E04 修到零被拒线,harness 补七刀:跨进程租约与广播桥、原子写、引用墙、对话区按序号排

活动侧(E04 2.1.0 → 2.1.9,I01 1.2.2):
- 覆盖闭合成为机检:基座新增 distinct 读数,「计划盖住的客户数 = 候选行数」钉进
  S3 收步 / S4 哨兵 / 放行 L2;人加的候选客户不再被整单无视
- 「关键人待识别」占位句式全链退役:查无联系人先发数据录入卡收人;契约新增 refersTo,
  计划/回执的 contact_code 只许引用真实存在的联系人(安装期核引用目标)
- 台账更新确认摆全落库面:客户档案/联系人档案两张落库预览(touched: 数据源,
  正式现值 + 草稿叠加),可补改、可加行(自增主键由基座续号);姓名升必填
- 更新明细:update_key 位置键 + 「同一处只留一条」L2;依据写人话不带机器键;
  标题旁不摆单号;判据与文案不夹字段名;行标识去掉单标识那一段
- 回执骨架 = 计划行数钉进 S3 收步与 S4 哨兵;重做分支不许删计划凑数
- 阶段刻度对齐文档 7 步;起单样例预填满

基座侧:
- 两个后端连同一个库:task-claim 跨进程租约(迁移 0030)+ Postgres LISTEN/NOTIFY
  广播桥;对话区按任务内记忆序号排,不按墙上时钟;并卡「刚说过话」按记忆序列判紧邻
- 多行 write 整批先验后写(dryRun),被拒 = 一行都没落
- 决策卡意见与本单草稿字面比对,归属以观察进轨迹(note-anchors)
- 括号栈补「补闭括号」两形(少一个 } / 行对象没关直接跟下一行)
- 件上加行:空着的自增主键直进续号,不从别的行借号;未落下的行点名回给前端
- 人答复落库那一刻就把 runtime 翻 running(task.wake),两块同帧变脸
- 试跑单可落真库(land_master,迁移 0031,默认开);数据域按活动分组;
  JSON 列不再是 [object Object];按钮键感 + 在办进度条 + 防抖
- 报价链 A1–A7 从系统卸载(只卸不删源码),种子只装 E04/I01

契约变更(api-report 已刷新):FieldDeclaration.distinct / refersTo,
objectDeclaration.file,landMaster,unkeyed,assetFiles,ledgerByActivityRoute。
1700 测 / typecheck / lint / depcruise / api:check 绿。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EEJX8Z7CHejvwmDQyPQuBX

apps/api/src/app/workers/__tests__/task-claim.test.ts

@@ -0,0 +1,77 @@
+/**
+ * 跨进程租约 —— **两个后端连同一个库时,一张单只许一个在推**。
+ *
+ * 2026-08-24 柴浩那一单就死在这上头:本机与局域网另一台各跑一个后端,两边的推进器
+ * 同时推同一张单,两拍并发写一份 `loop_state`,后写的整份覆盖先写的 ——
+ * 「给 S2 发过卡」那个事实(worldTouched)被抹掉、S1 被收了两遍;
+ * 随后 finish 那道门说「从没发过卡」、重发那道门说「人已答过」,两堵墙对着撞,五拍熔断。
+ * 进程内那把 `taskMutex` 对这种局面无能为力(它自己的注释里就写着)。
+ *
+ * 这里测的是**发给库的那句话对不对**:判与占必须在同一条 SQL 里
+ * (分两句写就是经典竞态),且带过期时间(进程崩了不锁死)。
+ * SQL 的并发语义另以两条真连接对着真库跑过 20 轮 —— 每轮恰好一个赢。
+ */
+import { describe, expect, it } from 'vitest';
+import { claimTask, releaseTask, LEASE_MS } from '../task-claim.ts';
+
+/** 记下发出去的 SQL —— drizzle 的 sql`` 片段拼回可读字符串 */
+function fakeDb(rowCount: number) {
+  const sent: string[] = [];
+  return {
+    sent,
+    execute: async (q: unknown) => {
+      const chunks = (q as { queryChunks?: unknown[] }).queryChunks ?? [];
+      sent.push(
+        chunks
+          .map((c) => {
+            const one = c as { value?: unknown };
+            return Array.isArray(one.value) ? one.value.join('') : String(one.value ?? '?');
+          })
+          .join(''),
+      );
+      return { rows: Array.from({ length: rowCount }, () => ({ id: 't1' })) };
+    },
+  };
+}
+
+/** 传给被测函数那一下再转 —— 测试桩不必长得跟真 Db 一样 */
+const asDb = (stub: unknown): Parameters<typeof claimTask>[0] => stub as Parameters<typeof claimTask>[0];
+
+describe('claimTask —— 抢这一张单的推进权', () => {
+  it('抢到了(UPDATE 命中一行)返回 true', async () => {
+    expect(await claimTask(asDb(fakeDb(1)), 't1')).toBe(true);
+  });
+
+  it('**没抢到返回 false** —— 别的进程正推着,这一轮就跳过', async () => {
+    expect(await claimTask(asDb(fakeDb(0)), 't1')).toBe(false);
+  });
+
+  it('判与占在同一条 SQL 里:where 带「没人占 或 已过期」,并 returning', async () => {
+    const db = fakeDb(1);
+    await claimTask(asDb(db), 't1');
+    const sql = db.sent[0] ?? '';
+    expect(sql).toContain('update sys.task');
+    expect(sql).toContain('advancing_until is null or advancing_until < now()');
+    expect(sql).toContain('returning id');
+  });
+
+  it('**租约带过期时间** —— 进程崩了不把这张单锁死', async () => {
+    const db = fakeDb(1);
+    await claimTask(asDb(db), 't1');
+    expect(db.sent[0] ?? '').toContain('milliseconds');
+    // 默认租约比最慢的一轮宽得多,又不至于锁上半天
+    expect(LEASE_MS).toBeGreaterThanOrEqual(60_000);
+    expect(LEASE_MS).toBeLessThanOrEqual(15 * 60_000);
+  });
+
+  it('还锁就是清空那一列', async () => {
+    const db = fakeDb(1);
+    await releaseTask(asDb(db), 't1');
+    expect(db.sent[0] ?? '').toContain('advancing_until = null');
+  });
+
+  it('**还锁失败不抛** —— 这一拍的成果不该被还锁连累掉', async () => {
+    const broken = { execute: async () => Promise.reject(new Error('库连不上')) };
+    await expect(releaseTask(asDb(broken), 't1')).resolves.toBeUndefined();
+  });
+});

apps/api/src/app/workers/dispatcher.ts

@@ -13,6 +13,7 @@ import type { Delivery } from '@modules/event';
 import { claimPendingDeliveries } from '@modules/event';
 import type { Container } from '../container.ts';
 import { taskMutex } from './task-lock.ts';
+import { claimTask, releaseTask } from './task-claim.ts';
 
 /** 消费者:按目标类型分派 */
 export type Consumer = (delivery: Delivery, container: Container) => Promise<void>;
@@ -31,6 +32,14 @@ export async function dispatchOnce(deps: DispatcherDeps): Promise<number> {
   for (const delivery of batch) {
     // 同任务按序:取到锁才处理,取不到说明同目标的另一条正在处理,留待下一轮
     await taskMutex.tryRun(`${delivery.target.kind}:${String(delivery.target.id)}`, async () => {
+      /*
+       * **投递也会推一拍**(consumer 里 `task.deliver` 末尾就是 `tick`)——
+       * 所以它同样要抢库里那份租约:上面那把锁只在本进程内算数,而两个后端连同一个库时
+       * (2026-08-24 实测)投递与另一台的推进器会并发写同一份 `loop_state`。
+       * 抢不到就先不处理,这一条留给下一轮 —— 它还在 pending,不会丢。
+       */
+      const taskId = delivery.target.kind === 'task' ? String(delivery.target.id) : undefined;
+      if (taskId !== undefined && !(await claimTask(container.db, taskId))) return;
       try {
         const consumer = deps.consumers.get(delivery.target.kind);
         if (consumer !== undefined) {
@@ -53,6 +62,9 @@ export async function dispatchOnce(deps: DispatcherDeps): Promise<number> {
         handled += 1;
       } catch (error) {
         await container.event.reportFailure(delivery.id, error instanceof Error ? error.message : String(error));
+      } finally {
+        // 推完就还租约 —— 不还也不会锁死(会过期),还了下一条投递立刻接得上
+        if (taskId !== undefined) await releaseTask(container.db, taskId);
       }
     });
   }

apps/api/src/app/workers/task-advancer.ts

@@ -9,6 +9,7 @@ import { and, eq, sql } from 'drizzle-orm';
 import { taskTable } from '@modules/task';
 import type { Container } from '../container.ts';
 import { taskMutex } from './task-lock.ts';
+import { claimTask, releaseTask } from './task-claim.ts';
 
 export type AdvancerOptions = {
   readonly container: Container;
@@ -51,6 +52,22 @@ export async function advanceOnce(options: AdvancerOptions): Promise<number> {
      * 抢不到就跳过 —— 那边正推着,这边再推就是两条线同时改一份运行时状态。
      */
     const ran = await taskMutex.tryRun(`task:${row.id}`, async () => {
+      /*
+       * **再抢一次库里的租约** —— 上面那把锁只在本进程内算数。
+       *
+       * 两个后端连同一个库时(本机 + 局域网另一台,2026-08-24 实测),两边的推进器
+       * 各扫各的、同时推同一张单:两拍并发写一份 `loop_state`,后写的整份覆盖先写的,
+       * 「发过卡」这个事实就此消失,门与门对着撞,五拍熔断。
+       * 抢不到说明别的进程正推着 —— 跳过,它推完自然轮得到。
+       */
+      if (!(await claimTask(container.db, row.id))) return;
+      try {
+        return await advanceOne();
+      } finally {
+        await releaseTask(container.db, row.id);
+      }
+
+      async function advanceOne(): Promise<void> {
       /** 这一轮之前它是什么样 —— 变了才广播,不然每两秒给在线浏览器发一次噪声 */
       const before = await container.task.get(row.id as never).catch(() => undefined);
       for (let tick = 0; tick < (options.maxTicks ?? 3); tick += 1) {
@@ -95,7 +112,7 @@ export async function advanceOnce(options: AdvancerOptions): Promise<number> {
           break;
         }
       }
-      return true;
+      }
     });
     void ran;
   }

apps/api/src/app/workers/task-claim.ts

@@ -0,0 +1,59 @@
+/**
+ * 任务推进的**跨进程租约** —— 一张单同一时刻只许一个后端在推。
+ *
+ * `task-lock.ts` 那把是**进程内**的互斥,它开头就写着:「MVP 单进程,进程内互斥就够;
+ * 多进程部署时再叠一层」。2026-08-24 那一天就撞上了:本机与局域网另一台机器上各跑着
+ * 一个后端,连的是同一个库,两边的推进器各自 2 秒扫一次「running 的单」,
+ * **同时推同一张**。两拍并发跑在同一份 `loop_state` 上,后写的整份覆盖先写的 ——
+ * 「给 S2 发过卡」这个事实被抹掉、S1 被收了两遍,随后 finish 与重发两道门对着撞,
+ * 连拒五拍熔断(柴浩那一单)。
+ *
+ * 为什么不用 `pg_try_advisory_lock`:它是**会话级**的,而我们经连接池取连接 ——
+ * 加锁与解锁多半落在不同连接上。`pg_try_advisory_xact_lock` 是事务级的,而推一拍
+ * 要调模型、要写好几张表,不该整个包在一个事务里。
+ *
+ * 所以用**库里的一列**当租约:抢到才推,推完就还;**带过期时间** —— 进程崩了不锁死,
+ * 租约一过别的进程照样接得上。这是任务队列的老办法,跨进程、跨机器都算数。
+ */
+import { sql } from 'drizzle-orm';
+import type { Db } from '@shared/db.ts';
+
+/**
+ * 租约多久过期。推一拍最慢是一次模型调用(实测 1.5-5 秒,关思考之前有过 56 秒),
+ * 而推进器一轮最多连推 3 拍 —— 给到 5 分钟:比最慢的一轮宽得多,又不至于
+ * 让崩掉的进程把一张单锁上半天。
+ */
+export const LEASE_MS = 5 * 60 * 1000;
+
+function rowsOf(result: unknown): unknown[] {
+  if (Array.isArray(result)) return result;
+  const rows = (result as { rows?: unknown }).rows;
+  return Array.isArray(rows) ? rows : [];
+}
+
+/**
+ * 抢这一张单的推进权。**抢到返回 true**,没抢到(别的进程正推着)返回 false。
+ *
+ * 一条 SQL 里判 + 占:`where advancing_until is null or advancing_until < now()` ——
+ * 两个进程同时来,PG 的行锁保证只有一个的 UPDATE 命中,另一个 RETURNING 空。
+ * 判和占分两句写是经典的竞态,这里不给它机会。
+ */
+export async function claimTask(db: Db, taskId: string, leaseMs: number = LEASE_MS): Promise<boolean> {
+  const result = await db.execute(sql`
+    update sys.task
+       set advancing_until = now() + (${leaseMs} || ' milliseconds')::interval
+     where id = ${taskId}
+       and (advancing_until is null or advancing_until < now())
+    returning id`);
+  return rowsOf(result).length > 0;
+}
+
+/**
+ * 推完就还 —— 不还也不会锁死(租约会过期),但还了下一轮就能接着推,
+ * 不必干等到过期。**失败不抛**:还锁失败不该把这一拍的成果连累掉。
+ */
+export async function releaseTask(db: Db, taskId: string): Promise<void> {
+  await db
+    .execute(sql`update sys.task set advancing_until = null where id = ${taskId}`)
+    .catch(() => undefined);
+}