wezard 2.2.2 → 2.3.0

package/dist/daemon/receipts.js

@@ -1,11 +1,62 @@
-import { waitForIdle } from "./graph.js";
-/** 对方最长允许干多久 (超过就放弃这一份回执, 不占着内存等到天亮)。 */
+// 回执: 一次 tell_peer 之后, 对方干完那一轮, 守护进程把它的结论**自动**送回发话方
+// 的输入框。
+//
+// 在这之前, 发话方只有两条路: 挂在 wait_peer 上阻塞等 (把一个能干活的 pane 锁死在
+// 轮询里, 而且一次只能等一批、等完才醒), 或者自己记得回头 peek —— 后者实际上没人做。
+// 异步回执把「问」和「收」拆开: 问完就接着干自己的事, 答案到了作为新的一轮进来。
+//
+// 这不是第二个编排器, 是一条投递通路。它只做四件事, 每一件都复用现成的判定:
+//   等对方停下 (mirror.untilIdle, 注册表判闲) → 取它答**这一句**的那段话
+//   (peers.replyToPeer, 按信封定位而不是按时刻) → 等发话方停下 → paste 进去。
+// 控制流仍在发话方自己的上下文里: 它没有被阻塞, 也没有被谁代理。
+//
+// 登记落盘 (`store`), boot 时把没收尾的重新守起来。不能纯内存: 这个仓库里被派活的
+// wizard 自己就常以 `build + reload` 收尾 —— reload 恰好落在它那一轮里, 内存里的
+// watcher 跟着进程一起没了, 发话方永远等不到回执。答案本来就在对方的 transcript 里
+// (按信封定位), 重启后接着守, 取到的还是同一段。
+import { randomBytes } from "node:crypto";
+import { parseClosing } from "./peers.js";
+import { isTerminal, turnState } from "../shared/turn-state.js";
+import { sleep, truncate } from "../shared/std.js";
+/** 对方最长允许干多久 (超过就投一份 timeout 回执, 不占着内存等到天亮)。默认值;
+ *  tell_peer 的 `deadline` 可在 [MIN, MAX] 里改 —— 上限留在 KEEP_MS 之内, 超时那份
+ *  回执还得数得进工单。 */
 const TARGET_WAIT_SEC = 3600;
-/** 发话方正忙时最长等它多久再投。 */
-const SENDER_WAIT_SEC = 1800;
-/** 对方停下来了却还没答我们这一句 (我们那一句排在别人后面) —— 再等下一次停下。
- *  连着这么多次都没答就认定它不会答了, 别守到天亮。 */
+const DEADLINE_MIN_SEC = 60;
+const DEADLINE_MAX_SEC = 12 * 3600;
+/** 交接把义务转进新会话时, 至少再给它这么久: 不然对方一交接, 这份就提前超时。 */
+const CARRY_GRACE_MS = 10 * 60_000;
+/** 一件活的编号: 注入之前生成, 写进信封, 回执按它定位答句。 */
+export const newTurn = () => `t${randomBytes(3).toString("hex")}`;
+/** `at` 发出、给了 `sec` 秒 (缺省 / 越界取默认或夹到边上) 的期限。 */
+export const deadlineOf = (at, sec) => at + 1000 * (sec === undefined || !Number.isFinite(sec) ? TARGET_WAIT_SEC : Math.min(Math.max(sec, DEADLINE_MIN_SEC), DEADLINE_MAX_SEC));
+/** 对方 pane 不在了, 隔这么久再看一眼才判 dead: 非交接的 pane 换新 (respawn) 也有
+ *  几秒是死的。 */
+const DEAD_GRACE_MS = 5000;
+/** 对方读进了我们这一句、停下了却没答 —— 再等下一次停下。连着这么多次都没答就认定
+ *  它不会答了, 别守到天亮。我们那一句还没被读进 (排在别的轮后面) 的那几次不算: 那是
+ *  在等前面的轮, 不是它不答; 只有整段 ramp 都闲着、问话仍不在 transcript 里, 才算一次
+ *  (那一句多半丢了)。 */
 const MAX_FRUITLESS = 3;
+/** 等对方「动起来」的窗口: 注册表在它读进这一句之前仍报 idle, 不等这一下就会在它开工
+ *  之前读 transcript, 读到的还是上一件事。轮询放慢到 2s: idleNow 与 answered 都同步读
+ *  tail, 十几路 fan-out 同时 ramp 时 1s 一次会压住事件循环。 */
+const RAMP_MS = 20_000;
+const RAMP_POLL_MS = 2000;
+/** 每次最多等对方这么久就回来重读 deadline: 交接 transfer 会把 s.at 往后推, 一次定死的
+ *  超时会早于新的 deadline 放弃。 */
+const IDLE_STEP_MS = 5 * 60_000;
+/** codebuddy 没有注册表, 判闲靠 pane 采样 —— 它停在本地对话框上时 spinner 也会消失,
+ *  仍会被算作闲 (P1 在那边没修), 多采一次压低误判。发话方投递路径保持 2。 */
+const IDLE_CONFIRM = 3;
+/** 信封属性上的 k: `chat:<turn>:<base>` / `peer:<turn>:<key>` —— 只给机器读。chat 的
+ *  `turn` 是开那一轮的那句人话的时刻: 人先后问的两件事各派了活, 不能被当成兄弟。 */
+export const kAttr = (k) => `${k.kind}:${k.turn}:${k.kind === "chat" ? k.channel : k.from}`;
+export const kOfAttr = (a) => {
+    const m = a.match(/^(chat|peer):([^:]+):(.+)$/);
+    return !m ? undefined : m[1] === "chat" ? { kind: "chat", turn: m[2], channel: m[3] } : { kind: "peer", turn: m[2], from: m[3] };
+};
+const sameK = (a, b) => kAttr(a) === kAttr(b);
 /** 落盘的登记留多久。比对方最长允许干的时长宽, 好让续守的那一份仍数得进工单。 */
 const KEEP_MS = 24 * 3600_000;
 export const createReceipts = (deps) => {
@@ -20,6 +71,47 @@ export const createReceipts = (deps) => {
     const settle = (s) => { s.settled = true; save(s); };
     const stale = (s) => slots.get(keyOfPair(s.from, s.to))?.gen !== s.gen;
     const ofJob = (from, job) => [...slots.values()].filter((x) => x.from === from && x.job === job);
+    /** P 的答话方在答 P 的那一轮里又派出去、还没落定的活。 */
+    const children = (p) => [...slots.values()].filter((c) => c.from === p.to && c.k?.kind === "peer" && c.k.from === p.from && c.k.turn === p.turn && !c.settled);
+    /** 与 c 同一个发话方、同一个父 k、定论还没送进去的那几份 (不含 c)。送进去的只是一份
+     *  error 的那种还没落定: 续跑出来的真答案还要来。 */
+    const siblings = (c) => [...slots.values()].filter((x) => x !== c && x.from === c.from && !!x.k && sameK(x.k, c.k) && !x.settled && !(x.delivered && x.resolved));
+    /** 这份回执送进去之后, 发话方那一轮的终句去哪 (§3.3)。只在投递那一刻算: 兄弟们是
+     *  陆续回来的, 早算一步就会两份都以为自己不是最后一份。 */
+    const routeOf = (s, final) => {
+        const k = s.k;
+        if (!k || !final)
+            return { channel: s.channel, ...(k ? { k } : {}) };
+        const pending = siblings(s).length;
+        if (pending)
+            return { channel: "", k, pending };
+        if (k.kind === "chat")
+            return { channel: k.channel, k, replyTo: k };
+        const p = slots.get(keyOfPair(k.from, s.from));
+        return p && p.turn === k.turn && !p.resolved && !p.claimed ? { channel: "", k, replyTo: k, parent: p } : { channel: s.channel, k };
+    };
+    /** 续回: 上游那一份改锚到刚送进去的那份回执 (answerOf 按 reply-to 认它), 重新守。
+     *  正在守的那个 watcher 自己会发现锚变了; 挂起 (deferred) 的才要重新 arm。 */
+    const relay = (p, at) => {
+        p.at = at;
+        p.deadlineAt = Math.max(p.deadlineAt ?? 0, deadlineOf(at));
+        wake(p);
+    };
+    const wake = (p) => {
+        const was = p.deferred;
+        delete p.deferred;
+        save(p);
+        if (was)
+            arm(p, true);
+    };
+    /** 子活落定了却没有一份回执送进发话方 (发话方不在了 / 等不到它闲 / wait_peer 取走):
+     *  它若是挂起的上游等着的最后一份, 照样叫醒上游 —— 不然上游连一份 dead 都收不到。
+     *  锚不动: 上游按原来那一句重新守, 答话方不在了就落成 dead。 */
+    const release = (s) => {
+        const p = routeOf(s, true).parent;
+        if (p)
+            wake(p);
+    };
     // 同一个 pane 的回执串行投递。两份回执同时等到发话方 idle 时, 两次 paste 会挤进
     // 同一个输入框被当成一轮读掉 —— 正是异步化最容易带进来的那个故障。
     const chains = new Map();
@@ -28,20 +120,88 @@ export const createReceipts = (deps) => {
         chains.set(k, next.catch(() => undefined));
         return next;
     };
-    const arm = (s) => {
-        void watch(s).catch((e) => deps.log.warn({ err: e.message }, "receipt watch failed"));
+    // 一份 slot 同时只有一个 watcher: reload 续守与 relay 叫醒可能撞在一起, 两个 watcher
+    // 会把同一个答案投两遍。叫醒挂起的那份要 `force`: 挂起那一刻旧 watcher 已经同步返回,
+    // 只是 finally 还没跑; 用 token 免得旧的 finally 删掉新登记的那个。
+    const watching = new Map();
+    const arm = (s, force = false) => {
+        if (watching.has(s) && !force)
+            return;
+        const token = Symbol();
+        watching.set(s, token);
+        void watch(s)
+            .catch((e) => deps.log.warn({ err: e.message }, "receipt watch failed"))
+            .finally(() => { if (watching.get(s) === token)
+            watching.delete(s); });
     };
+    /** 对方这一轮结束了。判闲以注册表为准 (`untilIdle`): pane 的 spinner 在本地对话框上
+     *  (hook 回落成 ask / AskUserQuestion) 和长工具调用的间隙里都会消失, 按它判闲会把
+     *  一个停在对话框上的 wizard 当成「答完了却没答」, 扑空三次就把回执扔了。
+     *  先等它动起来 (`rampEnd` 之前): 还没读进这一句的会话注册表照样报 idle; 已经答出
+     *  来了 (`answered`, 太快的一轮可能在两次采样之间就跑完) 就不必等满。
+     *  `quiet` = 整段 ramp 它都闲着、什么也没答 —— 调用方据此判断那一句是不是丢了。 */
+    const settled = async (to, rampEnd, deadline, aborted, answered) => {
+        for (;;) {
+            if (aborted())
+                return { idle: false, reason: "stopped" };
+            if (Date.now() >= rampEnd)
+                return { idle: true, quiet: true };
+            if (!(await deps.idleNow(to)) || answered())
+                break;
+            await sleep(RAMP_POLL_MS);
+        }
+        for (;;) {
+            const left = deadline() - Date.now();
+            if (left <= 0)
+                return { idle: false, reason: "timeout" };
+            const r = await deps.untilIdle(to, Math.min(left, IDLE_STEP_MS), { aborted, confirm: IDLE_CONFIRM });
+            if (r.idle || aborted())
+                return r;
+        }
+    };
+    const canceled = (s) => s.outcome?.status === "canceled";
     /** 守到对方答出**我们这一句**为止。信封是比发话时刻更硬的锚 (见 peers.replyToPeer):
      *  对方正忙时我们那一句是排队的, 它先吐出来的是上一件事的结论 —— 按时刻取就会把
-     *  旧结论当成这一次的回执。所以"停下了但还没答我们"要接着等, 不能将就。 */
+     *  旧结论当成这一次的回执。所以"停下了但还没答我们"要接着等, 不能将就; 定位不到
+     *  问话 (undefined) 也只说明它还没读进, 绝不退回按时刻取。
+     *  那一轮以 CLI 报错收尾 → `error`; 报过一次之后只等续跑出来的真答案, 不再计扑空。
+     *  `undefined` = 被 wait_peer 取走或被新的一句顶掉, 调用方自己知道。 */
     const awaitReply = async (s) => {
         // 锚在发话时刻而不是此刻: reload 后续守的那一份不该重新领一整份时长。交接转过来
         // 的那份改锚到贴回简报的时刻, 所以每圈重算。
-        const deadline = () => s.at + TARGET_WAIT_SEC * 1000;
-        for (let fruitless = 0; fruitless < MAX_FRUITLESS && Date.now() < deadline();) {
-            const wr = await waitForIdle(s.to, deps.isBusy, deadline() - Date.now(), () => s.claimed || stale(s));
-            if (!wr.idle || s.claimed || stale(s))
-                return "";
+        const deadline = () => s.deadlineAt ?? s.at + TARGET_WAIT_SEC * 1000;
+        // cancel 落的终态也算: 守到一半被别人收掉, 不再等它的答案。
+        const aborted = () => s.claimed || stale(s) || canceled(s);
+        const reported = () => s.outcome?.status === "error";
+        // 反问过了: 同一段 NEED 不再投第二遍, 等发话方 tell_peer({re}) 答 (那会顶掉这份)。
+        const asked = () => s.outcome?.status === "need";
+        const reply = () => deps.replyFor(s.to, deps.nameOf(s.from), s.at, s.turn);
+        const news = (r) => !!r?.text.trim() && !(r.error && reported()) && !(asked() && r.text === s.outcome.body) && r.text !== s.bounced;
+        const failed = (status) => ({ status, body: failure(s, status) });
+        for (let fruitless = 0; fruitless < MAX_FRUITLESS;) {
+            if (Date.now() >= deadline())
+                return failed("timeout");
+            // 对方 pane 没了 (被收掉 / 崩了): 不会再答, 别空转三次 ramp。交接重开的那几秒
+            // pane 也是死的, 先等交接收尾再看; 别的换新 (respawn) 给一小段 grace。
+            await deps.handedOff?.(s.to);
+            if (s.answer !== undefined)
+                return { status: "done", body: s.answer };
+            if (!(await deps.paneLive(s.to))) {
+                await sleep(DEAD_GRACE_MS);
+                await deps.handedOff?.(s.to);
+                if (s.answer !== undefined)
+                    return { status: "done", body: s.answer };
+                if (!(await deps.paneLive(s.to)))
+                    return failed("dead");
+            }
+            const wr = await settled(s.to, Math.min(deadline(), Date.now() + RAMP_MS), deadline, aborted, () => news(reply()));
+            if (aborted())
+                return undefined;
+            if (!wr.idle) {
+                if (wr.reason === "timeout")
+                    return failed("timeout");
+                continue;
+            }
             // 它停下是因为在交接: 等交接收尾, 答案要么已钉在 s.answer, 要么义务转进了新会话
             // (那就接着守新会话)。这一段与下面的 replyFor 之间不能有 await —— 交接一旦
             // 开始就在旧会话还在时把 transfer 做完, 同步读到的必然还是旧 transcript。
@@ -49,113 +209,208 @@ export const createReceipts = (deps) => {
             if (handing)
                 await deps.handedOff?.(s.to);
             if (s.answer !== undefined)
-                return s.answer;
+                return { status: "done", body: s.answer };
             if (handing)
                 continue;
-            const got = deps.replyFor(s.to, deps.nameOf(s.from), s.at);
-            // undefined = 定位不到问话 (老 wizard 不挂信封): 没有更好的锚, 按时刻取。
-            if (got === undefined)
-                return deps.replyFor(s.to, deps.nameOf(s.from), 0) ?? "";
-            if (got.trim())
-                return got;
-            fruitless++;
+            const got = reply();
+            if (got && news(got))
+                return { status: got.error ? "error" : parseClosing(got.text).kind === "need" ? "need" : "done", body: got.text };
+            // 读进了没答 = 扑空一次; 还没读进 = 前面有别的轮, 接着等 —— 除非整段 ramp 都静着。
+            // 报过 error / NEED 之后它停着是在等人续跑或答复, 不算扑空, 守到期限。
+            if (!reported() && !asked() && (got !== undefined || wr.quiet))
+                fruitless++;
         }
-        return "";
+        // 打回过的那份: 它原样再交一遍 (按原文排除, 看不出是新的), 或打回那句因 reload 没注入
+        // 进去 —— 都扑空到这里。手上的原文就是它的交代, 照收, 别报 silent。
+        return s.bounced ? { status: "done", body: s.bounced } : failed("silent");
+    };
+    /** 失败回执的正文: 守护进程的一句说明 + 对方最后一句 (给发话方一点线索)。 */
+    const failure = (s, status) => {
+        const why = {
+            timeout: s.outcome?.status === "need"
+                ? `它的反问 (NEED) 等了 ${Math.round((Date.now() - s.at) / 60_000)} 分钟没人答`
+                : `等了 ${Math.round((Date.now() - s.at) / 60_000)} 分钟它还没答完`,
+            silent: `它停下了 ${MAX_FRUITLESS} 次, 都没答这一句`,
+            dead: "它的 pane 没了",
+        };
+        const last = deps.lastWords?.(s.to, s.at).trim();
+        return `（守护进程: ${deps.nameOf(s.to)} 没有给出结论 —— ${why[status] ?? status}。）${last ? `\n它最后说的: ${truncate(last, 600)}` : ""}`;
     };
     const watch = async (s) => {
         const lg = deps.log.child({ mod: "receipt", from: deps.nameOf(s.from), to: deps.nameOf(s.to), ...(s.job ? { job: s.job } : {}) });
-        const body = await awaitReply(s);
+        const anchor = s.at;
+        // 终态写一次不再改: reload 打断投递后续守的那一份直接重投同一个结果, 不再重等。
+        const got = s.outcome && isTerminal(s.outcome.status) ? s.outcome : await awaitReply(s);
+        // 等的过程中被 cancel 落了终态: 以它为准 (pane 随后被杀, awaitReply 可能报的是 dead)。
+        const out = canceled(s) ? s.outcome : got;
         if (stale(s))
             return;
-        if (s.claimed) {
+        if (s.claimed || !out) { // wait_peer 抢先取走了
             s.resolved = true;
             settle(s);
+            if (s.job)
+                deps.settleJob?.(s.job, s.to, "done", []);
             return;
-        } // wait_peer 抢先取走了
-        s.resolved = true;
-        if (!body.trim()) {
-            lg.info("receipt: 没有答这一句, 不回注");
-            settle(s);
+        }
+        // 下面到 save 之间不能有 await: relay 与这里的判定必须看到同一个状态。
+        // 锚被 relay 挪到了回执那一句: 刚取到的是旧锚的答案 (那句「已派」), 重来。
+        if (s.at !== anchor)
+            return watch(s);
+        // 它这一轮又派了活, 结论要等那些回来 —— 这一句不是定论: 不投、不计数 (§3.2)。
+        if (out.status === "done" && children(s).length) {
+            s.deferred = true;
+            save(s);
+            lg.info({ children: children(s).map((c) => deps.nameOf(c.to)) }, "receipt: 答话方又派了活, 等子回执回来再续");
+            return;
+        }
+        // 工单验收: 交了个空 RESULT (或缺约定的 ARTIFACT) —— 不投、不计数, 以发话方的名义同件号
+        // 打回一次; 再交上来的照收。新登记顶掉这一份 (它随即 stale), 守的是打回那一句的答案。
+        const why = out.status === "done" && s.job && !s.bounced ? deps.accept?.(s.job, out.body) : undefined;
+        if (why && deps.rebound) {
+            const at = Date.now();
+            const legs = (s.legs ?? 1) + 1;
+            register({ from: s.from, to: s.to, channel: s.channel, job: s.job, at, turn: s.turn, legs, deadlineAt: deadlineOf(at), ...(s.k ? { k: s.k } : {}), ...(s.asker ? { asker: s.asker } : {}), bounced: out.body });
+            const ok = await deps.rebound({ from: s.from, to: s.to, turn: s.turn, legs, channel: s.channel, ...(s.asker ? { asker: s.asker } : {}) }, why);
+            lg.info({ why, ok }, "receipt: 不合工单验收, 打回一次");
+            // 打回没注入进去: 原来那份照常交上去 (钉成新 slot 的答案, 它的 watcher 直接拿去投)。
+            if (!ok) {
+                const n = slots.get(keyOfPair(s.from, s.to));
+                if (n?.bounced && n.turn === s.turn) {
+                    n.answer = out.body;
+                    save(n);
+                }
+            }
             return;
         }
+        const final = isTerminal(out.status);
+        s.outcome = out;
+        s.resolved = final;
+        save(s);
+        if (final && s.job)
+            deps.settleJob?.(s.job, s.to, out.status, parseClosing(out.body).artifacts);
         // 发话方自己在交接: 重开的那几秒里 pane 是死的, 别把这当成"已经不在了"。
         await deps.handedOff?.(s.from);
         if (!(await deps.paneLive(s.from))) {
-            lg.info("receipt: 发话方已经不在了, 丢弃");
+            lg.info({ status: out.status }, "receipt: 发话方已经不在了, 丢弃");
             settle(s);
+            if (final)
+                release(s);
             return;
         }
-        s.claimed = true; // 占位先于投递: 这中间来的 wait_peer 不该把同一段再取一遍
+        if (final)
+            s.claimed = true; // 占位先于投递: 这中间来的 wait_peer 不该把同一段再取一遍
         const peers = s.job ? ofJob(s.from, s.job) : [s];
+        const tally = s.job ? deps.jobTally?.(s.job) : undefined;
         const meta = {
             from: s.to,
             channel: s.channel,
             job: s.job,
-            done: peers.filter((x) => x.resolved).length,
-            total: peers.length,
+            done: Math.max(peers.filter((x) => x.resolved).length, tally?.done ?? 0),
+            total: Math.max(peers.length, tally?.total ?? 0),
+            status: out.status,
+            turn: s.turn ?? "",
+            ...(s.asker ? { asker: s.asker } : {}),
         };
-        await serial(s.from, async () => {
-            if (stale(s))
-                return;
-            // 发话方正在生成 → 等它这一轮说完, 一结束就投。
+        const sent = await serial(s.from, async () => {
+            // 发话方正在生成 → 等它这一轮说完, 一结束就投。它的 pane 还活着就一直等 (上限是
+            // 登记的保留期): 回执到了却因为它在跑长活而扔掉, 它就只能永远等。
             // 等的过程中它开始交接 → 等交接完再来一圈: 投进旧会话会被交接一并带走 (简报
             // 已经写完了, 不含这一段), 投进还没贴回简报的新会话会抢在简报前面。
-            const until = Date.now() + SENDER_WAIT_SEC * 1000;
+            // 每圈都查 stale: 等发话方闲下来可能要很久, 同一对的新一句正是在这期间来的。
             for (;;) {
                 await deps.handedOff?.(s.from);
+                // settled 只可能是 wait_peer 在这期间取走了 (watcher 自己投完才 settle)。
+                // 排队期间被 cancel 落了终态: 手上这份 (need / error) 已经过时, 改投 canceled。
+                if (stale(s) || s.settled || (canceled(s) && out !== s.outcome))
+                    return false;
+                if (Date.now() >= s.at + KEEP_MS || !(await deps.paneLive(s.from))) {
+                    lg.warn({ status: out.status }, "receipt: 发话方一直没空或已不在, 放弃回注");
+                    return false;
+                }
                 if (!(await deps.idleNow(s.from))) {
-                    const w = await deps.untilIdle(s.from, until - Date.now());
-                    if (!w.idle) {
-                        lg.warn({ reason: w.reason }, "receipt: 发话方一直忙, 放弃回注");
-                        settle(s);
-                        return;
-                    }
+                    await deps.untilIdle(s.from, Math.min(IDLE_STEP_MS, s.at + KEEP_MS - Date.now()), { aborted: () => stale(s) });
+                    continue;
                 }
                 if (!deps.handingOff?.(s.from))
                     break;
             }
-            // 等的这段时间里同一对又说了一句 → 这一份作废, 后一句的回执才是要的那个。
-            // 进 serial 时查过一次不够: 等发话方闲下来可能要几分钟, 新的一句正是在这期间来的。
-            if (stale(s)) {
-                lg.info("receipt: 等发话方期间被新的一句顶掉, 不回注");
-                return;
+            // 上面最后一圈的 await 期间可能被 wait_peer 取走; 从这里到 deliver 之间不能有 await。
+            if (stale(s) || s.settled)
+                return false;
+            const { parent, ...route } = routeOf(s, final);
+            const at = Date.now();
+            // 先记成已投: 投递途中被 wait_peer 取走的, 要告诉它「这段已经在你会话里了」。
+            s.delivered = true;
+            const r = await deps.deliver(s.from, out.body, { ...meta, ...route });
+            if (!r.ok) {
+                s.delivered = false;
+                s.undelivered = true;
             }
-            const r = await deps.deliver(s.from, body, meta);
-            s.delivered = r.ok;
-            settle(s);
-            lg.info({ ok: r.ok, reason: r.reason, len: body.length, done: meta.done, total: meta.total }, "receipt: 回注");
+            if (r.ok && parent)
+                relay(parent, at);
+            lg.info({ ok: r.ok, reason: r.reason, status: out.status, len: out.body.length, done: meta.done, total: meta.total, ...(route.replyTo ? { replyTo: kAttr(route.replyTo) } : {}), ...(route.pending ? { pending: route.pending } : {}) }, "receipt: 回注");
+            return true;
         });
+        if (stale(s)) {
+            lg.info("receipt: 被同一对的新一句顶掉, 不回注");
+            return;
+        }
+        // error / need 只是中途报了一声: 接着守续跑 (或答复之后) 出来的答案。
+        if (!final && (sent || canceled(s)))
+            return watch(s);
+        settle(s);
+        if (!s.delivered)
+            release(s);
+    };
+    const register = (tell, watchIt = true) => {
+        const k = keyOfPair(tell.from, tell.to);
+        const at = tell.at ?? Date.now();
+        // 顶掉一份还没落定的工单活、自己又没带工单: 继承那张工单 —— 旧那份不会再投了,
+        // 这一句的答案就是那个成员的交代; 不继承它就永远不计 done, 工单齐不了。
+        const prev = slots.get(k);
+        const job = tell.job || (prev?.job && !prev.resolved ? prev.job : "");
+        const s = {
+            ...tell,
+            job,
+            at,
+            turn: tell.turn ?? newTurn(),
+            legs: tell.legs ?? 1,
+            deadlineAt: tell.deadlineAt ?? deadlineOf(at),
+            gen: (slots.get(k)?.gen ?? 0) + 1,
+            claimed: false,
+            delivered: false,
+            resolved: false,
+        };
+        slots.set(k, s);
+        if (watchIt)
+            arm(s);
+        else {
+            s.claimed = true;
+            s.resolved = true;
+            s.settled = true;
+        } // 不守 = 这一份没人会投
+        save(s);
+        return { at: s.at, turn: s.turn };
     };
     return {
-        register: (tell, watchIt = true) => {
-            const k = keyOfPair(tell.from, tell.to);
-            const s = {
-                ...tell,
-                job: tell.job ?? "",
-                at: tell.at ?? Date.now(),
-                gen: (slots.get(k)?.gen ?? 0) + 1,
-                claimed: false,
-                delivered: false,
-                resolved: false,
-            };
-            slots.set(k, s);
-            if (watchIt)
-                arm(s);
-            else {
-                s.claimed = true;
-                s.resolved = true;
-                s.settled = true;
-            } // 不守 = 这一份没人会投
-            save(s);
-            return { at: s.at };
+        register,
+        prepare: (from, to, re) => {
+            const want = re?.replace(/[`\s]/g, "");
+            const s = want ? slots.get(keyOfPair(from, to)) : undefined;
+            return s?.turn && s.turn === want
+                ? { turn: s.turn, legs: (s.legs ?? 1) + 1, job: s.job, channel: s.channel }
+                : { turn: newTurn(), legs: 1, ...(re ? { reUnknown: true } : {}) };
         },
         claim: (from, to) => {
             const s = slots.get(keyOfPair(from, to));
             if (!s)
                 return false;
+            const fresh = !s.settled;
             s.claimed = true;
             s.resolved = true;
             settle(s);
+            if (fresh)
+                release(s);
             return s.delivered;
         },
         sentAt: (from, to) => slots.get(keyOfPair(from, to))?.at ?? 0,
@@ -168,8 +423,10 @@ export const createReceipts = (deps) => {
                 const got = answered(s);
                 if (got.trim())
                     s.answer = got;
-                else
+                else {
                     s.at = carryAt;
+                    s.deadlineAt = Math.max(s.deadlineAt ?? 0, carryAt + CARRY_GRACE_MS);
+                }
                 save(s);
                 return !got.trim();
             });
@@ -177,8 +434,65 @@ export const createReceipts = (deps) => {
                 deps.log.info({ mod: "receipt", to: deps.nameOf(to), answered: owed.length - carried.length, carried: carried.map((s) => deps.nameOf(s.from)) }, "receipt: 交接时转交");
             return carried;
         },
+        pending: (from, to) => {
+            const s = slots.get(keyOfPair(from, to));
+            return s && !s.resolved && !s.claimed ? { job: s.job, turn: s.turn ?? "", need: s.outcome?.status === "need" } : undefined;
+        },
+        states: () => {
+            // 一个 target 欠好几份时只探一次 (探针要读它 transcript 的尾巴)。
+            const probed = new Map();
+            const parked = (t) => probed.get(t) ?? probed.set(t, deps.parkedNow?.(t) ?? false).get(t);
+            return [...slots.values()]
+                .filter((s) => !s.resolved && !s.claimed)
+                .map((s) => ({
+                from: s.from, to: s.to, turn: s.turn ?? "", job: s.job,
+                state: turnState(s, { parked: !s.outcome && parked(s.to) }),
+                ageMs: Date.now() - s.at,
+            }));
+        },
+        cancel: (target, by, only = () => true) => {
+            const hit = [...slots.values()].filter((s) => s.to === target && !s.resolved && !s.claimed && only({ from: s.from, turn: s.turn ?? "" }));
+            for (const s of hit) {
+                const last = deps.lastWords?.(s.to, s.at).trim();
+                s.outcome = {
+                    status: "canceled",
+                    body: `（守护进程: ${deps.nameOf(s.to)} 被 ${deps.nameOf(by)} 收掉 / 打断了, 这件活没有结论。）${last ? `\n它最后说的: ${truncate(last, 600)}` : ""}`,
+                };
+                if (s.job)
+                    deps.settleJob?.(s.job, s.to, "canceled", []);
+                // 发起 stop 的那方自己知道, 不投; 守着的 watcher 看到 claimed 就收尾。
+                if (s.from === by) {
+                    s.claimed = true;
+                    s.resolved = true;
+                    settle(s);
+                    continue;
+                }
+                save(s);
+                // 挂起等子活的没有 watcher 在守: 叫醒它去投这份 canceled。
+                if (s.deferred)
+                    wake(s);
+            }
+            return hit.length;
+        },
+        parentOf: (self, env, channel, opening) => {
+            if (env?.receipt)
+                return env.k ? kOfAttr(env.k) : undefined;
+            if (env?.kind === "peer" && env.private) {
+                const p = [...slots.values()].find((x) => x.to === self && !x.resolved && !x.claimed && (env.turn ? x.turn === env.turn : deps.nameOf(x.from) === env.from));
+                return p && { kind: "peer", from: p.from, turn: p.turn };
+            }
+            return { kind: "chat", channel, turn: opening };
+        },
+        askerOf: (self, env) => {
+            // 回执轮: 那件活是 self 派出去的; 派来的活: 那件活是派给 self 的。同一对后来又说了一句,
+            // 槽被顶掉 —— 件号对不上就认不出, 宁可不知道。
+            const mine = (x) => (env.receipt ? x.from === self : x.to === self);
+            const hit = [...slots.values()].find((x) => mine(x) && (env.turn ? x.turn === env.turn : deps.nameOf(env.receipt ? x.to : x.from) === env.from));
+            return hit?.asker;
+        },
         resume: () => {
-            const open = [...slots.values()].filter((s) => !s.settled);
+            // 挂起且子活还没落定的不守: 叫醒它是 relay / release 的事, 这里再 arm 一个就是两个 watcher。
+            const open = [...slots.values()].filter((s) => !s.settled && !(s.deferred && children(s).length));
             // 投到一半被 reload 打断的那份: claimed 是上一个进程的占位, 这里重新来过。
             open.forEach((s) => { s.claimed = false; arm(s); });
             if (open.length)