wezard 2.1.4 → 2.2.1

package/dist/daemon/index.js

@@ -12,7 +12,7 @@ import { loadMirrorStore } from "./mirror-store.js";
 import { startMirror, installMirrorEventListener } from "./mirror-bridge.js";
 import { setTmuxTimeoutReporter, spawnTmuxClaude } from "./spawn-tmux.js";
 import { installApprovalEventListener, makeApproveHandler } from "./approval.js";
-import { initDetailPersistence, makeDetailHandler, chatHandlers, configureRemoteForward, chatUrlFor, setWorldFactsProvider } from "./detail.js";
+import { initDetailPersistence, makeDetailHandler, chatHandlers, configureRemoteForward, chatUrlFor, setWorldFactsProvider, recordPost } from "./detail.js";
 import { EMPTY_FACTS } from "../shared/world.js";
 import { initAutoWindowPersistence } from "./session-cache.js";
 import { makeMessageHandler } from "./outbound.js";
@@ -30,10 +30,16 @@ import { baseOfKey, bindTagLinker, keyOf, linkTags, normalizeTag, tagFromCwd, ta
 import { clipForCharter, inboxPath, memoryPath, memoryRoot, proposeMemory, readMemory } from "./wizard-memory.js";
 import { ensureStewardTask } from "./memory-steward.js";
 import { applyChatNames, chatBaseOf, chatNameOf, clearChatName, listChatNames, normChatName, peerAddress, planChatNames, setChatName } from "./chat-name.js";
-import { bindWizardStore, loadWizardStore, wizardStore, settleName, settleAll, evictStaleName, childrenOf, ancestorsOf, renderCharter, renderRoster, } from "./wizard.js";
+import { bindWizardStore, loadWizardStore, wizardStore, settleName, settleAll, evictStaleName, childrenOf, ancestorsOf, renderCharter, renderRoster, CONTEXT_FULL_TOKENS, } from "./wizard.js";
 import { bindNoticeBox, createNoticeBox, chatAudience } from "./notices.js";
 import { loadJobStore, renderJobOpen, renderJobClose, JOB_MEMBER_MAX } from "./jobs.js";
-import { clipMiddle, extractResult, keepalivePingSigs, lastExchange, lastModel, renderPeerEnvelope, renderTaskEnvelope } from "./peers.js";
+import { clipMiddle, contextFiles, extractResult, lastContextTokens, lastExchange, lastModel, replyClosedBefore, talkTurns, renderPeerEnvelope, renderReceiptEnvelope, renderTaskEnvelope } from "./peers.js";
+import { keepalivePingSigs } from "../shared/keepalive.js";
+import { expandHome } from "../shared/paths.js";
+import { loadJsonMap } from "../shared/json-map-store.js";
+import { createReceipts } from "./receipts.js";
+import { createHandoffs, handedOff, handingOff } from "./handoff.js";
+import { rankCandidates, renderCandidates } from "./route.js";
 import { parseWhen, renderChatLog } from "./chat-log.js";
 import { startGraph, stopRun, getRun, listRuns, validateSpec, waitForIdle, waitForQuorum, } from "./graph.js";
 // pino's file transport is async; without flush, log.fatal before process.exit
@@ -105,7 +111,9 @@ const main = async () => {
         },
         nameOf: (t) => settleName(wizardStore(), chatNameOf(cfg, t), t),
     });
-    installInboundRouter(ws.client, cfg, log, bridge, sourcePath);
+    // 人话也过交接的闸 (见 handoff.ts): 交接期间说的话进新会话, 不被旧会话带走、也不在
+    // 重开的空档里 resume 回旧 sid。
+    installInboundRouter(ws.client, cfg, log, { ...bridge, dispatch: async (a) => (await handedOff(a.principal), bridge.dispatch(a)) }, sourcePath);
     // approval click → finalize 当前 liveStream, 后续 tool/text 落到 standalone。
     // 规则 2: 用户点击授权那一刻就是"上一段对话"的边界, 截断 stream 让授权后的
     // 工作单独成块, 比让 stream 一直长到下一个 inbound / hardTimer 更清晰。
@@ -357,7 +365,8 @@ const main = async () => {
             // 没点名就按配置的 keepalive.spawnDefault 来 —— 调用方明说的永远优先。
             const keepalive = typeof body.keepalive === "boolean" ? body.keepalive : cfg.wrc.mirror.keepalive.spawnDefault;
             log.child({ mod: "mirror", sub: "sessions-new", target }).info({ self, cwd, foreign, cli: body.cli, model, keepalive }, "spawning peer session");
-            const r = await m.newSession(target, name, body.cli, { cwd, model, keepalive });
+            // silent: 新 wizard 就位不进群 (生命周期事件), 同群的 wizard 从名册增量里得知。
+            const r = await m.newSession(target, name, body.cli, { cwd, model, keepalive, silent: true });
             if (!r.ok && !existed)
                 wizards.drop(target);
             // r.model 是 spawnTmuxClaude 通过 /model 实测确认落地的那个 —— 可能跟调用方
@@ -581,11 +590,62 @@ const main = async () => {
         const channelOf = (self) => m.currentChannel(self) || baseOfKey(self);
         /** 同伴注入的信封: 公开轮写上那个群的名字, 私聊不写 (见 peers.renderPeerEnvelope)。 */
         const envelopeFor = (from, channel) => renderPeerEnvelope(displayName(from), channel ? chatNameOf(cfg, channel) : undefined);
-        // 发话时刻 —— wait_peer 拿它把「回复」和「这一次发话」对上 (peers.lastReply)。
-        // 纯内存: reload 之后退化成不带关联的旧行为, 不值得为它落盘。
-        const sentAt = new Map();
-        const pairOf = (from, to) => `${from}\u0000${to}`;
-        const stampSend = (from, to) => void sentAt.set(pairOf(from, to), Date.now());
+        // 回执 (见 receipts.ts): 一次 tell_peer 之后对方干完那一轮, 它的结论自动 paste
+        // 回发话方的输入框, 发话方全程不阻塞。这里只提供四样能力给那个模块 —— 忙闲、
+        // 死活、「它答我那一句的是哪段话」、以及怎么把一段话送进去 —— 投递逻辑在那边。
+        const receipts = createReceipts({
+            isBusy: m.isBusy,
+            idleNow: m.idleNow,
+            untilIdle: m.untilIdle,
+            paneLive: m.paneLive,
+            nameOf: displayName,
+            log,
+            store: loadJsonMap(cfg.wrc.mirror.receiptsFile),
+            handingOff,
+            handedOff,
+            // 信封锚取不到 (对方是个还不挂信封的老 wizard) 时退回按时刻取, 由 receipts
+            // 区分这两种"没有"。
+            replyFor: (to, fromName, since) => m.replyToPeer(to, fromName, since),
+            deliver: (to, bodyText, meta) => m.injectText(to, clipMiddle(bodyText), undefined, {
+                // receipt:true 是「这一轮不该再生回执」的记录 —— 回环在结构上就不成立:
+                // 只有 tell_peer 那条路登记 watcher, 这里是直接注入。
+                from: { kind: "peer", from: meta.from, receipt: true, ...(meta.job ? { job: meta.job } : {}) },
+                channel: meta.channel,
+                envelope: renderReceiptEnvelope(displayName(meta.from), meta.channel ? chatNameOf(cfg, meta.channel) : undefined, meta.job ? { job: meta.job, done: meta.done, total: meta.total } : undefined),
+            }),
+        });
+        // reload 前在飞的回执: 等 mirror 把绑定都恢复了再续守 —— 早一步读 target 会拿不到
+        // transcript, 退回按时刻取就可能把上一件事的结论当回执。
+        // 交接 (见 handoff.ts): 换会话不换身份。这里给它重开、贴话、读旧 transcript 的能力,
+        // 闸、回执清点与断点续做在那边。
+        const pingSigs = keepalivePingSigs(cfg.wrc.mirror.keepalive.ping);
+        const handoffs = createHandoffs({
+            isBusy: m.isBusy,
+            sessionId: (t) => m.sessionInfo(t)?.sessionId ?? "",
+            restart: (t) => restartFresh(t),
+            // 欠着回执的发话方挂上它们的信封: 新会话那一轮就是在答它们, 回执照常按信封定位,
+            // 频道也接回原来那一句所在的地方 (私聊不进群)。
+            inject: (t, text, owe) => owe.length
+                ? m.injectText(t, text, undefined, {
+                    from: { kind: "peer", from: owe[0].from },
+                    channel: owe[0].channel,
+                    envelope: owe.map((o) => envelopeFor(o.from, o.channel)).join(""),
+                })
+                : m.injectText(t, text),
+            lastText: m.lastText,
+            answeredBefore: (to, from, since, until) => {
+                const p = m.sessionInfo(to)?.jsonlPath;
+                return p ? replyClosedBefore(expandHome(p), displayName(from), since, until, pingSigs) : undefined;
+            },
+            receipts,
+            // 交接是生命周期事件, 不进群; 失败只捎给它自己 (它调完 handoff_self 拿到的是
+            // scheduled:true, 不说的话它不知道上下文其实没换)。
+            notify: (t, text) => notices.post([t], text),
+            log,
+            store: loadJsonMap(cfg.wrc.mirror.handoffsFile),
+        });
+        // 交接先续做: 它的闸要在回执续守之前立起来, 否则续守的 watcher 会读到换了一半的会话。
+        void m.restored.then(() => { handoffs.resume(); receipts.resume(); });
         /** 入参里的地址: 新字段 `name`, 老 MCP 进程 (正在跑的 wizard) 仍在传 `tag`。 */
         const addrOf = (b) => String(b.name ?? b.tag ?? "");
         /** 撞上的名字属于一个静默超过一天的 wizard → 顶掉它 (见 evictStaleName), 同群的
@@ -672,8 +732,10 @@ const main = async () => {
                 return;
             }
             const dests = [...new Set(refs.length ? refs.map((r) => chatBaseOf(cfg, r)) : [channelOf(self)])];
-            for (const dest of dests)
+            for (const dest of dests) {
                 notifyChat(dest, `${relayLabel(self)}\n\n${content}`);
+                recordPost({ target: self, channel: dest, body: content });
+            }
             json(res, 200, { ok: true, sent: dests.map((d) => chatNameOf(cfg, d) || d) });
         });
         http.register("POST /peers/peek", async (req, res) => {
@@ -789,7 +851,11 @@ const main = async () => {
                 ].join("\n"),
             });
         });
-        http.register("POST /peers/send", async (req, res) => {
+        // 跟另一个 wizard 说一句话。`tell_peer` 是它现在的名字 —— 「说」而不是「发送并
+        // 等待」: 调用方注入完就返回, 对方干完那一轮的结论由守护进程自动送回来 (receipts)。
+        // `/peers/send` 保留为同一个处理函数: 正在跑的 wizard 的 MCP 进程是旧代码, 换名字
+        // 不能把它们的通路掐断。
+        const tellPeer = async (req, res) => {
             const { self, body } = await readPeerBody(req);
             if (!self) {
                 json(res, 400, { ok: false, reason: "cannot resolve caller session" });
@@ -816,7 +882,9 @@ const main = async () => {
             const { target, foreign } = r;
             // 公开与否由发话方 (LLM) 判断: 公开 = 在它这一轮的公开频道里说, 气泡进群、对方
             // 那一轮的回复也发进这个群; 私聊 (默认) = 只落双方的 rolepage, 回复靠 wait_peer 取。
-            const isPublic = body.public === true;
+            // 只有两端都是登记在册的 wizard 才能当着人说: 裸 target 冒充的发话方、forget
+            // 掉的分身不是谁, 它们的往来进群只会留下一段人找不到主的对话 —— 降为私聊。
+            const isPublic = body.public === true && !!wizards.get(self) && !!wizards.get(target);
             const channel = isPublic ? channelOf(self) : "";
             // Injecting into your own pane would type into the box you're generating
             // from — Claude Code queues it and the caller deadlocks waiting for itself.
@@ -824,31 +892,40 @@ const main = async () => {
                 json(res, 400, { ok: false, reason: "refusing to inject into the calling session itself" });
                 return;
             }
+            // 它正在交接: 这句话等它换完会话再进 —— 投进旧会话会被交接一并带走, 投进重开中的
+            // 空 pane 会 resume 回旧 sid (见 handoff.ts)。发话时刻取在这之后。
+            await handedOff(target);
             // 投递时机。默认照旧立刻投 —— 「回答它的提问」「打断它」本来就是冲着一个
             // 正在忙的会话去的。`when:"idle"` 是**派新活**该用的那一种: 两个 wizard 同时
             // 找第三个时, 两段文本会挤进同一个输入框、被当成一轮读掉, 这在协同网络里
             // 不是边角情况而是常态。等它闲下来再投, 一句话就是一轮。
             const when = (body.when ?? "now") === "idle" ? "idle" : "now";
             const waitSec = Math.min(Math.max(Number(body.waitSec ?? 600) || 600, 10), 3600);
-            const wasBusy = await m.isBusy(target);
+            // 「忙」= 这一轮还没结束, 或停在审批上等人 —— 都不是能接新活的时候。
+            const wasBusy = !(await m.idleNow(target));
             let waitedMs = 0;
             if (when === "idle" && wasBusy) {
                 const t0 = Date.now();
-                // rampMs=0: ramp 是给「刚注入、这一轮还没起来」准备的; 这里相反, 一旦它
-                // 真闲下来就该立刻投。
-                const wr = await waitForIdle(target, m.isBusy, waitSec * 1000, () => false, { rampMs: 0, confirm: 2 });
+                // 它那一轮一结束就投: 注册表 status 翻 idle 是事件, 不抽样也不等稳定期。
+                const wr = await m.untilIdle(target, waitSec * 1000);
                 waitedMs = Date.now() - t0;
                 if (!wr.idle) {
                     json(res, 409, { ok: false, target, foreign, wasBusy, waitedMs, reason: `它一直在忙, ${waitSec}s 内没闲下来 —— peek_peer 看看它卡在哪, 或者用 when:"now" 插队` });
                     return;
                 }
             }
-            stampSend(self, target);
+            // 时刻取在注入**之前**: 晚于那一句落盘的话, 回执定位的下界就偏了。
+            const at = Date.now();
             const inj = await m.injectText(target, text, undefined, {
                 from: { kind: "peer", from: self, ...(jobId ? { job: jobId } : {}), ...(isPublic ? { public: true } : {}) },
                 channel,
                 envelope: envelopeFor(self, channel),
             });
+            // 回执: 对方干完那一轮, 守护进程把它的结论自动送回来 (默认开)。`receipt:false`
+            // 是"放出去就不管了"的那种派活。注入失败就不守 —— 没有问话, 也不会有回答。
+            const wantReceipt = body.receipt !== false;
+            if (inj.ok)
+                receipts.register({ from: self, to: target, channel, job: jobId, at }, wantReceipt);
             // 工单成员照旧记账 (收工那一条会列出各自那段活); 公开的那一句在群里成气泡。
             if (inj.ok && jobId)
                 jobs.attach(jobId, { target, task: text, spawned: false });
@@ -856,8 +933,21 @@ const main = async () => {
                 relayPeer(self, target, text, channel);
             // `wasBusy` 是给调用方的判断依据: 立刻投给一个正在生成的会话, 这句话会排在
             // 它这一轮后面, 而不是马上被读到。
-            json(res, inj.ok ? 200 : 502, { ...inj, name: peerAddress(cfg, self, target), public: isPublic, wasBusy, ...(waitedMs ? { waitedMs } : {}), ...(jobId ? { job: jobId } : {}) });
-        });
+            json(res, inj.ok ? 200 : 502, {
+                ...inj,
+                name: peerAddress(cfg, self, target),
+                public: isPublic,
+                wasBusy,
+                ...(waitedMs ? { waitedMs } : {}),
+                ...(jobId ? { job: jobId } : {}),
+                // 回执怎么回来 —— 写在回包里, 调用方 (模型) 不必从工具描述里回忆。
+                ...(inj.ok && wantReceipt
+                    ? { receipt: "它干完那一轮, 结论会作为新的一轮自动进到你这里 —— 不要挂在 wait_peer 上等, 接着干你自己的事" }
+                    : {}),
+            });
+        };
+        http.register("POST /peers/tell", tellPeer);
+        http.register("POST /peers/send", tellPeer); // 老 MCP 进程还在调这个名字
         // 等一个 wizard, 或者等一**组**。fan-out 之后 join 必须是并行的: 串行地等五个
         // 分身, 墙钟是五个之和, 而它们本来就在同时干活。`need` 把 all / any / 过半收进
         // 一个数字 (默认全等), 满了就撤掉剩下的等待。
@@ -901,11 +991,15 @@ const main = async () => {
             //   - 内部 key (`target`) 与 `foreign` 不回: 模型用不上, 还会被诱导去拼 key。
             const results = uniq.map((h, i) => {
                 const wr = wrs[i];
-                const full = wr.idle ? m.lastReply(h.target, sentAt.get(pairOf(self, h.target)) ?? 0) : "";
+                // 取走就占位: 同一段话不会再作为回执 paste 进来一遍 (见 receipts.claim)。
+                const full = wr.idle ? m.lastReply(h.target, receipts.sentAt(self, h.target)) : "";
+                const already = full ? receipts.claim(self, h.target) : false;
                 const result = extractResult(full);
                 return {
                     name: h.address,
                     idle: wr.idle,
+                    // 回执早一步到了: 这段话已经作为新的一轮进过你的会话, 别再处理第二遍。
+                    ...(already ? { delivered: true } : {}),
                     ...(wr.reason ? { reason: wr.reason } : {}),
                     ...(result
                         ? { result, ...(full.length > result.length + 200 ? { omitted: full.length - result.length } : {}) }
@@ -922,11 +1016,17 @@ const main = async () => {
                 ? { ok: true, ...results[0] }
                 : { ok: true, need, done, satisfied: done >= need, results });
         });
-        // POST /handoff — 交接一个 pane 的会话给一个全新会话,原地完成。先让目标
-        // 会话把当前工作压成一份"零上下文也能接手"的交接简报,等它写完并抓取,
-        // 再向同一 pane 注入 `/clear`(原地重开 session、重置上下文窗口、cwd 不变),
-        // settle 后把简报作为新会话的首条消息贴进去。全程只操控 tmux。拒绝对调用方
-        // 自身 pane 操作(会 deadlock,同 /peers/send)。
+        // 交接的「重开」一步: 走 /new (杀旧 pane、起新进程) 而不是往原 pane 注入 /clear。
+        // /clear 只换会话不换进程 —— MCP 子进程、charter 都还是旧的, 新工具拿不到; 镜像
+        // 还得靠 sid 轮换探测才跟得上。模型 / CLI / cwd / keepalive 照旧沿用。
+        const restartFresh = (target) => {
+            const info = m.sessionInfo(target);
+            return m.newSession(target, displayName(target) || tagOfKey(target) || target, info?.cli, { model: info?.model || undefined, silent: true, warm: true });
+        };
+        // POST /handoff — 交接一个 pane 的会话给一个全新会话。先让目标会话把当前工作
+        // 压成一份"零上下文也能接手"的交接简报,等它写完并抓取,再 restartFresh 换一个
+        // 全新的进程(同名、同 cwd),把简报作为新会话的首条消息贴进去。拒绝对调用方
+        // 自身操作(会 deadlock,同 /peers/send)。
         http.register("POST /handoff", async (req, res) => {
             const { self, body } = await readPeerBody(req);
             if (!self) {
@@ -958,44 +1058,8 @@ const main = async () => {
             }
             const focus = (body.focus ?? "").toString().trim();
             const timeoutMs = Math.min(Math.max(Number(body.timeoutSec ?? 600) || 600, 30), 7200) * 1000;
-            const briefPrompt = [
-                "把你当前会话的全部工作压缩成一份**交接简报**,目标是让一个零上下文的全新会话仅凭这份简报就能无缝接手。必须自洽、具体、可执行,涵盖:",
-                "1. 总目标 / 用户到底想要什么",
-                "2. 已完成的事、关键决策与其理由",
-                "3. 当前状态:改到哪了、什么能跑、什么还没跑通",
-                "4. 下一步该做什么(有序)",
-                "5. 涉及的关键文件/路径/符号,以及非显而易见的坑",
-                focus ? `特别强调:${focus}` : "",
-                "只输出这份简报本身,不要寒暄、不要反问。",
-            ].filter(Boolean).join("\n");
-            const inj1 = await m.injectText(target, briefPrompt);
-            if (!inj1.ok) {
-                json(res, 502, { ok: false, target, reason: `summary inject failed: ${inj1.reason}` });
-                return;
-            }
-            const idle = await waitForIdle(target, m.isBusy, timeoutMs, () => false);
-            const brief = m.lastText(target);
-            // 没等到 idle 就不能 /clear —— 那会丢掉这次还在生成的交接总结。
-            if (!idle.idle) {
-                json(res, 504, { ok: false, target, brief, reason: `target still working: ${idle.reason}; not clearing to avoid losing the turn` });
-                return;
-            }
-            if (!brief.trim()) {
-                json(res, 502, { ok: false, target, reason: "target produced no summary text" });
-                return;
-            }
-            const clr = await m.injectText(target, "/clear");
-            if (!clr.ok) {
-                json(res, 502, { ok: false, target, brief, reason: `/clear inject failed: ${clr.reason}` });
-                return;
-            }
-            // /clear 后 TUI 重绘出全新空会话 + 首条注入需要 warmup,给足 settle。
-            await new Promise((r) => setTimeout(r, 3000));
-            const carry = `以下是上一个会话交接过来的工作简报,请据此无缝接手并继续:\n\n${brief}`;
-            const inj2 = await m.injectText(target, carry);
-            json(res, inj2.ok ? 200 : 502, inj2.ok
-                ? { ok: true, target, brief }
-                : { ok: false, target, brief, reason: `handoff carry inject failed: ${inj2.reason}` });
+            const r = await handoffs.other(target, focus, timeoutMs);
+            json(res, r.ok ? 200 : r.status, r.ok ? { ok: true, target, brief: r.brief } : { ok: false, target, reason: r.reason, ...(r.brief ? { brief: r.brief } : {}) });
         });
         // ── Wizard: 会话的身份层 ────────────────────────────────────────────
         // 一个会话 (`chat:xxx#k`) 从此是一个 wizard: 一个全局唯一的名字 (默认会话出生时
@@ -1132,6 +1196,7 @@ const main = async () => {
                 })),
                 schedules: tasks.list().filter((x) => x.enabled).map((x) => {
                     const st = tasks.stateOf(x.id);
+                    const loadError = tasks.errors()[x.id];
                     return {
                         id: x.id,
                         target: x.target || (cfg.defaultChat ?? ""),
@@ -1142,21 +1207,31 @@ const main = async () => {
                         note: x.note,
                         createdBy: x.createdBy,
                         owner: x.owner || (cfg.defaultChat ?? ""),
+                        fresh: x.fresh,
+                        hasGate: x.hasGate,
+                        lastGate: st.lastGate,
+                        lastGateAt: st.lastGateAt,
+                        lastError: st.lastError,
+                        ...(loadError ? { loadError } : {}),
+                        file: x.file,
                     };
                 }),
                 chatNames: Object.fromEntries(listChatNames(cfg).map((c) => [c.base, c.name])),
             };
         };
+        // 一次采集失败 (某个 pane 的 tmux 抖了一下) 不等于注册表没了: 退回上一份好的,
+        // 否则这份空占位会被推给 svr, 把整张名册抹成「缺席」直到下一次推送。
+        let lastGood = EMPTY_FACTS;
         setWorldFactsProvider(() => {
             const now = Date.now();
             if (!worldCache || now - worldCache.at > WORLD_TTL_MS) {
-                worldCache = { at: now, facts: collectWorldFacts().catch(() => EMPTY_FACTS) };
+                worldCache = {
+                    at: now,
+                    facts: collectWorldFacts().then((f) => (lastGood = f), () => lastGood),
+                };
             }
             return worldCache.facts;
         });
-        /** 上下文超过这个数就该自己交接了。Claude 家族最小的窗口是 200k, 留三成余量
-         *  给交接那一轮本身 —— 提示而已, 决定权在 wizard 自己。 */
-        const HANDOFF_HINT_TOKENS = 140_000;
         const briefOf = (self, target) => ({
             name: settleName(wizards, chatNameOf(cfg, target), target),
             address: peerAddress(cfg, self, target),
@@ -1236,7 +1311,7 @@ const main = async () => {
                 cli: info?.cli,
                 model: info?.model ?? "",
                 contextTokens: info?.contextTokens ?? 0,
-                handoffSuggested: (info?.contextTokens ?? 0) > HANDOFF_HINT_TOKENS,
+                handoffSuggested: (info?.contextTokens ?? 0) > CONTEXT_FULL_TOKENS,
             };
         };
         /** 全体名册: 活着的 (peers + 跨聊天可寻址的) 在前, 注册表里有记录但此刻不在
@@ -1358,6 +1433,7 @@ const main = async () => {
                 ...r,
                 model: r.model || (r.jsonlPath ? lastModel(r.jsonlPath) : ""),
                 summary: r.jsonlPath ? lastExchange(r.jsonlPath, 80, warm) : "",
+                contextTokens: r.jsonlPath ? lastContextTokens(r.jsonlPath) : 0,
             }));
             json(res, 200, {
                 ok: true,
@@ -1365,7 +1441,7 @@ const main = async () => {
                 matched: hit.length,
                 shown: shown.length,
                 text: [
-                    `名册 · 列出 ${shown.length}/${hit.length} 个 (全机 ${all.length} 个) · 忙 = 正在生成, 闲 = 活着没在跑, 冷 = 没有 pane (发消息会唤醒)`,
+                    `名册 · 列出 ${shown.length}/${hit.length} 个 (全机 ${all.length} 个) · 忙 = 正在生成, 闲 = 活着没在跑, 冷 = 没有 pane (发消息会唤醒) · ctx = 当前上下文用量`,
                     renderRoster(shown, Date.now(), homedir()),
                     ...(hit.length > shown.length
                         ? [`还有 ${hit.length - shown.length} 个没列出来 —— 用 query (名字/职责) / cwd (工作区) / chat 收窄, 或者调大 limit`]
@@ -1373,6 +1449,38 @@ const main = async () => {
                 ].join("\n"),
             });
         });
+        // 管家分派前的候选表: 事实在这里算 (交集、读过的文件、ctx), 权衡留给管家。
+        // 只为活着的读 transcript —— 冷的没有 jsonl 可读, 靠职责命中进表。
+        http.register("POST /wizard/route", async (req, res) => {
+            const { self, body } = await readPeerBody(req);
+            if (!self) {
+                json(res, 400, { ok: false, reason: "cannot resolve caller session" });
+                return;
+            }
+            const b = body;
+            const task = (b.task ?? "").trim();
+            if (!task) {
+                json(res, 400, { ok: false, reason: "task is required" });
+                return;
+            }
+            ensureChatNames(self);
+            const warm = keepalivePingSigs(cfg.wrc.mirror.keepalive.ping);
+            const rows = (await rosterOf(self))
+                .filter((r) => !r.self)
+                .map((r) => {
+                const live = r.jsonlPath ? r.jsonlPath : "";
+                return {
+                    ...r,
+                    contextTokens: live ? lastContextTokens(live) : 0,
+                    files: live ? contextFiles(live) : [],
+                    asks: live ? talkTurns(live, 12, warm).filter((t) => t.role === "user").map((t) => t.text) : [],
+                    summary: live ? lastExchange(live, 80, warm) : "",
+                };
+            });
+            const limit = Math.min(Math.max(Number(b.limit ?? 5) || 5, 1), 20);
+            const cands = rankCandidates(task, (b.cwd ?? "").trim() || m.getCwd(self).runningCwd, rows).slice(0, limit);
+            json(res, 200, { ok: true, text: renderCandidates(cands, Date.now(), homedir()) });
+        });
         // 记忆三种作用域: self 跟着自己 (wizards.json), 直写; chat / workspace 是共享的 md,
         // 每个在那个群 / 那个目录出生的 wizard 都会读到 —— 它们只收提议, 由整理者合并
         // (见 wizard-memory.ts / memory-steward.ts)。
@@ -1513,8 +1621,7 @@ const main = async () => {
             const keepalive = typeof b.keepalive === "boolean" ? b.keepalive : cfg.wrc.mirror.keepalive.spawnDefault;
             // 先盖章再生: 分叉出来的 transcript 里躺着被克隆者的旧回复, 时刻早于这一枚章,
             // wait_peer 才不会把它们当成分身对这件活的答复。
-            if (task)
-                stampSend(self, target);
+            const taskAt = Date.now();
             const r = await m.cloneSession({
                 parent: source,
                 target,
@@ -1554,11 +1661,15 @@ const main = async () => {
             }
             if (jobId)
                 jobs.attach(jobId, { target, task, spawned: true });
+            // 分身的第一件活也守回执: fan-out 最常见的形状就是 clone_wizard({task}) × N,
+            // 让它们干完自己把结论送回来, 发起方不必挂在 wait_peer 上。
+            if (dispatched)
+                receipts.register({ from: self, to: target, channel: "", job: jobId, at: taskAt });
             json(res, 200, { ok: true, target, name, address: name, inherited: r.inherited, sessionId: r.sessionId, cwd: r.cwd, dispatched, keepalive, ...(r.model ? { model: r.model } : {}), ...(r.modelWarning ? { modelWarning: r.modelWarning } : {}), ...(jobId ? { job: jobId } : {}) });
         });
         // 收掉一个 wizard。interrupt = 打断它这一轮 (Esc); end = 结束它并回收 pane。
         // 自己终结自己是合法的 (分身干完活自我了结), 代价是这次工具调用不会返回 ——
-        // 群里的气泡就是回执, 与 set_workspace 同款。
+        // 回执只在 rolepage (生命周期事件不进群); 同群的 wizard 从名册增量里得知。
         http.register("POST /wizard/stop", async (req, res) => {
             const { self, body } = await readPeerBody(req);
             if (!self) {
@@ -1585,7 +1696,6 @@ const main = async () => {
             }
             if (end && b.forget)
                 wizards.drop(target);
-            notifyChat(target, withTagHeader(target, `${end ? "已结束" : "已打断"} · 由 ${displayName(self)} 发起`));
             // 打断只是停了它这一轮, 它还在; 只有结束才是名册变了。
             if (end)
                 postRoster(baseOfKey(target), [target, self], `**${victim.name || target}** 已收工 · 由 ${displayName(self)} 结束${b.forget ? " (记录一并抹掉)" : ""}`);
@@ -1620,7 +1730,7 @@ const main = async () => {
             const done = await m.setModel(r.target, model, scope);
             json(res, done.ok ? 200 : 502, { ...done, target: r.target, name: briefOf(self, r.target).name, ...(done.ok ? { model: done.applied } : {}) });
         });
-        // 自我交接: 上下文撑不住了, 自己把工作压成简报, 原地 /clear 重开, 再把简报贴
+        // 自我交接: 上下文撑不住了, 自己把工作压成简报, /new 换一个全新进程, 再把简报贴
         // 回去。和 /handoff 的区别是**简报由调用方自己写在入参里** —— 它没法在自己
         // 生成的当口再被问一次 (那正是 /handoff 拒绝对自身操作的原因)。所以这里先应答,
         // 等它这一轮说完、pane 空下来再动手。
@@ -1636,29 +1746,9 @@ const main = async () => {
                 return;
             }
             const info = m.sessionInfo(self);
-            json(res, 200, { ok: true, target: self, contextTokens: info?.contextTokens ?? 0, scheduled: true });
-            // 应答之后再干活: 调用方此刻还在生成, 必须等它把话说完。
-            void (async () => {
-                const lg = log.child({ mod: "wizard", sub: "handoff-self", target: self });
-                const idle = await waitForIdle(self, m.isBusy, 10 * 60_000, () => false);
-                if (!idle.idle) {
-                    lg.warn({ reason: idle.reason }, "self-handoff: 目标一直忙, 放弃");
-                    // 之前这里只写日志: 调用方早就拿到 `scheduled:true` 挂了, 交接静悄悄
-                    // 放弃, 群里没有任何气泡告诉人。补一条 notify, 对齐它成功时的那条。
-                    notifyChat(self, withTagHeader(self, `上下文交接放弃: 一直没能闲下来 (${idle.reason}), 上下文和之前一样没动, 有空再试一次`));
-                    return;
-                }
-                const clr = await m.injectText(self, "/clear");
-                if (!clr.ok) {
-                    lg.warn({ reason: clr.reason }, "self-handoff: /clear 注入失败");
-                    return;
-                }
-                await new Promise((r2) => setTimeout(r2, 3000));
-                const carry = `以下是你自己上一段会话压缩出来的交接简报, 据此无缝接着干:\n\n${brief}`;
-                const inj = await m.injectText(self, carry);
-                lg.info({ ok: inj.ok, reason: inj.reason }, "self-handoff: 完成");
-                notifyChat(self, withTagHeader(self, `上下文已交接重开 (${info?.contextTokens ?? 0} tok → 0), 工作照旧`));
-            })();
+            // 应答之后再干活: 调用方此刻还在生成, 交接要等它把话说完 (见 handoff.ts)。
+            const r = handoffs.self(self, brief);
+            json(res, r.ok ? 200 : 409, r.ok ? { ok: true, target: self, contextTokens: info?.contextTokens ?? 0, scheduled: true } : { ok: false, reason: r.reason });
         });
         // ── Job: 一次 fan-out 的工单 ─────────────────────────────────────────
         // 账本, 不是编排器: 控制流留在发起的那个 wizard 手里 (它自己 spawn / wait /
@@ -1879,7 +1969,7 @@ const main = async () => {
                     const r = await m.newSession(target, node.tag, node.cli, { model: node.model, cwd: node.cwd, silent: true });
                     return { ok: r.ok, reason: r.reason };
                 },
-                send: (target, text, origin) => m.injectText(target, text, origin),
+                send: async (target, text, origin) => (await handedOff(target), m.injectText(target, text, origin)),
                 isBusy: m.isBusy,
                 lastText: async (target) => m.lastText(target),
                 notify: notifyChat,
@@ -1938,6 +2028,8 @@ const main = async () => {
         // 跑完自动收掉。只有排班时点名了某个 wizard (fresh=false) 且它此刻闲着,
         // 才把这句话直接投进它那一轮 —— 「在已有会话里继续」是要求出来的, 不是默认。
         scheduledTaskInject = async (target, text, { taskId, fresh }) => {
+            if (!fresh)
+                await handedOff(target); // 交接中途 pane 是空的, 别当成闲着投进去
             const busy = fresh ? false : await m.isBusy(target);
             if (!fresh && !busy)
                 return m.injectText(target, text, undefined, { fromChat: true, from: { kind: "task", taskId }, envelope: renderTaskEnvelope(taskId) });