@te-river/opencode-team-mode 1.6.0 → 1.6.2

package/dist/tm/dispatch.js

@@ -33,9 +33,29 @@ import { tmError, toToolResult } from "./result.js";
 import { unwrapClientResult } from "./client-unwrap.js";
 import { detectContentType } from "./preview.js";
 import { shorten } from "./config.js";
+import { ledgerGoalLine, openItems } from "./ledger.js";
 /** The five dispatchable specialists — "team" is deliberately NOT in the
  *  list: a lead spawning a lead is the nesting T3 closed. */
 export const DISPATCH_TARGETS = ["architect", "implementer", "reviewer", "tester", "researcher"];
+/** A child seen being dispatched by the host's own tool, turned into a registry row.
+ *  Null when the ids are unusable: a child whose id equals the caller's would make
+ *  tm_join wait on the session it is running in, and an anonymous child cannot be
+ *  settled by an event we match on session id. */
+export function hostChildRecord(child, now = () => Date.now()) {
+    const sessionID = String(child?.sessionID ?? "").trim();
+    const parentSessionID = String(child?.parentSessionID ?? "").trim();
+    if (!sessionID || !parentSessionID || sessionID === parentSessionID)
+        return null;
+    return {
+        sessionID,
+        agent: String(child.agent ?? "").trim().toLowerCase() || "subagent",
+        label: String(child.label ?? "").trim().slice(0, 40) || "宿主子代理",
+        parentSessionID,
+        startedAt: now(),
+        state: "running",
+        via: "host-injection",
+    };
+}
 export function openHostTodos(todos) {
     if (!Array.isArray(todos))
         return [];
@@ -169,9 +189,17 @@ export function parseDispatchTitle(title, targets) {
  * bare Part[] — the LAST assistant message is the answer, everything earlier
  * is that agent's own working transcript.
  *
+ * This function deliberately does NOT learn about the host's message shapes:
+ * `ctx.session.context` answers with `{id, role, metadata, content:[…]}` on
+ * 2.0.20 and with flat `{id, time, text, type}` on 2.0.18, and BOTH are
+ * normalised at that seam (`normaliseContextMessages`, src/host/v2-session-client.ts)
+ * before they reach here. Recognising `content` here as well would mean two
+ * places guess at a shape nobody measured, which is exactly how A1 shipped: the
+ * seam answered, the body was dropped, and the sentence blamed the host.
+ *
  * `completedAt` is what lets a rebuilt registry tell "still running" from
  * "finished while we were not listening": AssistantMessage.time.completed is
- * only set once the message is done.
+ * only set once the message is done, and it is copied, never invented.
  */
 export function lastAssistantMessage(messages) {
     const list = Array.isArray(messages) ? messages : [];
@@ -259,7 +287,14 @@ export function describeHostError(err, max = 220) {
 export function renderChildLine(c, elapsedMs) {
     const secs = Math.round(elapsedMs / 1000);
     const tag = c.state === "running" ? `运行中 ${secs}s` : c.state === "error" ? `失败：${shorten(c.error ?? "", 80)}` : `已完成 ${secs}s`;
-    return `${c.sessionID} · ${c.agent} · "${c.label}" · ${tag}${c.adopted ? " ·（本进程重启后由宿主会话树接管）" : ""}`;
+    // #33: a row the host reported IDLE for a stop attempt is not a delivery — the lead
+    // needs to see that the child was never running, not a bare 已完成.
+    const stop = c.state === "idle" && c.cancelNote ? ` ·${c.cancelNote}` : "";
+    return `${c.sessionID} · ${c.agent} · "${c.label}" · ${tag}${stop}${c.adopted ? " ·（本进程重启后由宿主会话树接管）" : ""}${c.via === "host-injection" && c.settleSource === "parent-idle"
+        ? " ·（宿主子代理：随父会话空闲推定已结算，宿主没给过这个子会话的 idle 事件）"
+        : c.via === "host-injection"
+            ? " ·（宿主 subagent 派发）"
+            : ""}`;
 }
 /** Verdicts tm_join can actually observe (issue #7's "leader keeps control"). */
 export function summarizeStates(children) {
@@ -311,6 +346,61 @@ export function parseIdList(raw) {
     }
     return s.split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
 }
+/** Read the stop verdict out of the v2 adapter's `{data:{outcome,message}}`. Anything
+ *  unrecognisable is `unknown`, never `stopped` — a shape we cannot read is not evidence
+ *  a child died. */
+export function cancelOutcomeOf(res) {
+    const un = unwrapClientResult(res);
+    if (!un.ok)
+        return { outcome: "threw", note: un.message };
+    const data = un.data;
+    const o = String(data?.outcome ?? "");
+    const known = ["stopped", "idle", "unknown", "no-seam", "threw"];
+    if (known.includes(o))
+        return { outcome: o, note: typeof data?.message === "string" ? data.message : undefined };
+    return { outcome: "unknown", note: o ? `宿主返回了没认出的结果（${shorten(o, 24)}）` : "宿主没有返回 interrupted 字段" };
+}
+/** The line the lead reads, per outcome. Terse and falsifiable: each names what was
+ *  OBSERVED, and the escape hatch for the cases where nothing was observed. */
+export function cancelVerdictLine(outcome, note) {
+    const why = note ? `：${shorten(note, 80)}` : "";
+    switch (outcome) {
+        case "stopped":
+            return "已由宿主中断（interrupted=true）";
+        case "idle":
+            return "宿主回 idle no-op——它当时没有活动执行，所以我没有停掉任何东西";
+        case "unknown":
+            return `中断调用成功，但宿主没给出 interrupted 布尔${why}——是否真的停了，我不知道`;
+        case "no-seam":
+            return "这个宿主没给中断子会话的缝（session.interrupt / abort 都没有），未取消";
+        case "threw":
+            return `中断被宿主拒绝${why}`;
+    }
+}
+/** Short name for one outcome, used in the count line. */
+export function cancelOutcomeLabel(o) {
+    return o === "stopped"
+        ? "已由宿主中断"
+        : o === "idle"
+            ? "空闲未中断"
+            : o === "unknown"
+                ? "未确认"
+                : o === "no-seam"
+                    ? "无中断缝"
+                    : "被宿主拒绝";
+}
+/** The summary counts, spelled the way the lead has to quote them. Fixed order so a
+ *  rerun prints the same line, and an absent outcome prints nothing rather than "0". */
+export function cancelOutcomeParts(tally) {
+    const order = ["stopped", "idle", "unknown", "threw", "no-seam"];
+    const out = [];
+    for (const o of order) {
+        const n = tally[o];
+        if (n)
+            out.push(`${n} ${cancelOutcomeLabel(o)}`);
+    }
+    return out;
+}
 export function buildDispatchTools(deps) {
     const leadAgent = deps.leadAgent ?? "team";
     const targets = deps.targets ?? DISPATCH_TARGETS;
@@ -366,14 +456,29 @@ export function buildDispatchTools(deps) {
     }
     function fetchReply(sid, directory) {
         return (async () => {
-            if (typeof api?.messages !== "function")
-                return { text: "" };
+            if (typeof api?.messages !== "function") {
+                return { text: "", error: "这个宿主客户端没有给出读取子会话正文的缝（v2 上它是 ctx.session.context 的兼容层）" };
+            }
             try {
-                const un = unwrapClientResult(await api.messages({ path: { id: sid }, ...(directory ? { query: { directory } } : {}) }));
-                return un.ok ? lastAssistantMessage(un.data) : { text: "" };
+                const raw = await api.messages({ path: { id: sid }, ...(directory ? { query: { directory } } : {}) });
+                const un = unwrapClientResult(raw);
+                const got = un.ok ? lastAssistantMessage(un.data) : { text: "", error: un.message };
+                // The seam that ANSWERED, named by the seam itself. On v1 that is the host's
+                // `session.messages`; on v2 the same call is served by `ctx.session.context`, and
+                // printing "session.messages" there would credit an endpoint this host does not
+                // have — the class of claim this product exists to refuse.
+                const via = String(raw?.via ?? "session.messages");
+                // And the SHAPE the seam saw, reported by the seam (names and counts only). This is
+                // what makes a `child_body_missing` row falsifiable instead of a shrug: "answered,
+                // and the last item carried no text part" is a different fact from "no seam".
+                const reported = raw?.shape;
+                const shape = typeof reported === "string" && reported ? reported : undefined;
+                return got.text
+                    ? { ...got, via, ...(shape ? { shape } : {}) }
+                    : { text: "", error: got.error, via, ...(shape ? { shape } : {}) };
             }
-            catch {
-                return { text: "" };
+            catch (err) {
+                return { text: "", error: describeHostError(err?.message ?? err, 140) };
             }
         })();
     }
@@ -392,17 +497,28 @@ export function buildDispatchTools(deps) {
      * path that may take a host child, and the parentage check it must pass.
      */
     async function adoptFromHost(parent, directory, only) {
-        if (typeof api?.children !== "function" || !parent)
-            return 0;
+        // Three outcomes used to collapse into `0`: the host surface is absent (v2's
+        // client shim has no `session` domain), the call failed, and "we asked and
+        // there was nothing".  The empty-round answer reads "宿主会话树里也没有可认领的
+        // 子会话", which is a claim about case three — asserted in cases one and two,
+        // where nobody looked.  A lead that believes it will stop waiting for a report
+        // that exists, which is the silent loss this function exists to prevent.
+        // The reason names the MISSING SEAM, not a host generation: the same absence
+        // occurs on a v1-shaped client that lacks `session.messages`, and a sentence
+        // blaming "v2" there would be false in the opposite direction.
+        if (typeof api?.children !== "function")
+            return { adopted: 0, looked: false, why: "这个宿主客户端没有给出 session.children（可辨认的 session API 缺失），我没有看过会话树" };
+        if (!parent)
+            return { adopted: 0, looked: false, why: "调用方会话 id 缺失，无从查询子会话" };
         let un;
         try {
             un = unwrapClientResult(await api.children({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
         }
-        catch {
-            return 0;
+        catch (err) {
+            return { adopted: 0, looked: false, why: `查询会话树失败：${describeHostError(err)}` };
         }
         if (!un.ok || !Array.isArray(un.data))
-            return 0;
+            return { adopted: 0, looked: false, why: "宿主返回了无法解析的会话树结果" };
         let adopted = 0;
         for (const raw of un.data) {
             const sid = String(raw?.id ?? "").trim();
@@ -429,7 +545,7 @@ export function buildDispatchTools(deps) {
             adopted++;
             log({ step_id: "join", event: "adopt", child: sid, agent: parsed.agent, label: rec.label });
         }
-        return adopted;
+        return { adopted, looked: true, why: adopted ? "" : "会话树里没有被认领标题的子会话" };
     }
     /** Claim ONE explicitly named child of the calling session — the host's own
      *  `task` child included, which `adoptFromHost` must never pick up on its
@@ -482,11 +598,11 @@ export function buildDispatchTools(deps) {
         }
     }
     const join = {
-        description: `Collect the sub-agent work attached to THIS session — the read-back side of delegation. You reach for it in two situations: the host's background \`task\` finished and TeamMode replaced its injected reply with a preview (pull the whole thing back with \`{ ids: ["<child session>"] }\`), or a dispatched child from before this build is still open and needs collecting or cancelling.
-- No args: status snapshot of every open child of THIS session — running / idle(done) / error, with elapsed seconds.  Cheap and non-blocking: use it to decide whether to keep working or start merging.
-- { waitMs: 30000 }: bounded wait (capped at ${waitLabel(maxWaitMs)}) until every child settles.  A wait BLOCKS YOU — your turn is parked in this tool call, so it is the synchronous \`task\` experience with none of its visibility.  Wait once, briefly, and only when the very next step needs the answer; a second consecutive wait after nothing settled is cut to 10s and answered with what to do instead.  Never wait for a child whose result you do not need — abort it instead ({ cancel: true }).
-- { ids: [...] }: restrict to those child sessions — a host \`task\` child is collectable when you NAME it (its parentage is verified against the host's own session tree, never assumed); { cancel: true }: abort still-running ones.
-- A plugin/host restart does NOT orphan a child: those the host still lists under your session are re-adopted automatically (their rows are marked 接管), and one that answered while nobody was listening is reported 已完成, not lost.
+        description: `Collect the sub-agent work attached to THIS session — the read-back side of delegation. You reach for it in two situations: the host's background \`task\` finished and TeamMode replaced its injected reply with a preview (pull the whole thing back with \`{ ids: ["<child session>"] }\`), or a dispatched child from before this build is still open and needs collecting or cancelling.
+- No args: status snapshot of every open child of THIS session — running / idle(done) / error, with elapsed seconds.  Cheap and non-blocking: use it to decide whether to keep working or start merging.
+- { waitMs: 30000 }: bounded wait (capped at ${waitLabel(maxWaitMs)}) until every child settles.  A wait BLOCKS YOU — your turn is parked in this tool call, so it is the synchronous \`task\` experience with none of its visibility.  Wait once, briefly, and only when the very next step needs the answer; a second consecutive wait after nothing settled is cut to 10s and answered with what to do instead.  Never wait for a child whose result you do not need — abort it instead ({ cancel: true }).
+- { ids: [...] }: restrict to those child sessions — a host \`task\` child is collectable when you NAME it (its parentage is verified against the host's own session tree, never assumed); { cancel: true }: abort still-running ones.
+- A plugin/host restart does NOT orphan a child: those the host still lists under your session are re-adopted automatically (their rows are marked 接管), and one that answered while nobody was listening is reported 已完成, not lost.
 - Replies come back through the offload pipeline: a long sub-agent report arrives as a handle + ≤80-token preview (page it with tm_fetch), so a batch of parallel work does not multiply your context.  STATUS: blocked/failed children are surfaced first, always.`,
         args: {
             ids: { descriptor: "ids: string[] (optional — only these child sessions)" },
@@ -513,10 +629,19 @@ export function buildDispatchTools(deps) {
                 const idFilter = idList && idList.length ? new Set(idList) : null;
                 const owned = () => [...children.values()].filter((r) => (!parent || r.parentSessionID === parent) && (!idFilter || idFilter.has(r.sessionID)));
                 let mine = owned();
+                // Whether we got to LOOK at the host's tree, and what it said — the empty
+                // answer must not claim "there is nothing to adopt" on a host we cannot
+                // query, so the fact travels with the attempt rather than being inferred.
+                let adoption = {
+                    adopted: 0,
+                    looked: false,
+                    why: "本进程已经认全了要收的子代理，没有去查会话树",
+                };
                 // This process has never seen some (or all) of what the lead is asking
                 // for — the host's session tree, not our memory, is the authority.
                 if (mine.length < (idFilter ? idFilter.size : 1)) {
-                    if (await adoptFromHost(parent, directory, idFilter))
+                    adoption = await adoptFromHost(parent, directory, idFilter);
+                    if (adoption.adopted)
                         mine = owned();
                     // Plan B: a NAMED id may be the host's own `task` child (no ·tm
                     // marker, so the tree walk above never claims it).  Collecting it is
@@ -563,7 +688,28 @@ export function buildDispatchTools(deps) {
                 };
                 if (!mine.length) {
                     const lease = leaseLine();
-                    return toToolResult(`没有待收集的派发${idFilter ? "（ids 未匹配到本会话的子代理，宿主会话树里也没有可认领的子会话）" : ""}。` +
+                    // The parenthetical is now chosen by whether we actually looked, so a
+                    // host we cannot query no longer reports as "confirmed: nothing there".
+                    const saw = adoption.looked;
+                    const inner = idFilter
+                        ? (() => {
+                            // Naming the shapes the v2 session bridge tried is the whole point:
+                            // without it, a claim that failed because `ctx.session.get` answered
+                            // in a shape we do not know prints the same sentence as a tree we
+                            // did query, and the lead goes back to waiting for a report that
+                            // exists.
+                            const sr = deps.sessionReaderReport?.();
+                            const bridge = sr && sr.attempted > 0
+                                ? `；我试过的 ctx.session 形状：${(sr.failedShapes.length ? sr.failedShapes.join("→") : sr.usedShape ?? "?")}${sr.lastError ? `（宿主最后一次的错误：${shorten(sr.lastError, 90)}）` : "（宿主没有报错，只是没给出 parentID）"}`
+                                : "";
+                            return saw
+                                ? `（ids 未匹配到本会话的子代理，宿主会话树里也没有可认领的子会话）${bridge}`
+                                : `（ids 未匹配到；而且我没能查看宿主会话树：${adoption.why}）${bridge}`;
+                        })()
+                        : saw
+                            ? ""
+                            : `（注意：${adoption.why}，所以"确实没有子代理"这个结论我给不出）`;
+                    return toToolResult(`没有待收集的派发${inner}。` +
                         // The old line asserted the dispatch had failed.  Measured live: it
                         // had not — a completed host `task` with a full reply was sitting in
                         // the transcript, and the honest reason is that a synchronous host
@@ -599,25 +745,62 @@ export function buildDispatchTools(deps) {
                     still_running: stillRunning.length,
                     repeat: repeatWait,
                 });
+                // #33 — the STOP path. Runs BEFORE the header is built, because the per-child
+                // verdict belongs in the child's own row, and the summary line below must be able
+                // to say which of the outcomes it is counting.
+                let cancelTally = null;
                 if (args.cancel === true || args.cancel === "true") {
+                    cancelTally = {};
                     for (const r of stillRunning) {
+                        let outcome;
+                        let note;
                         if (typeof api?.abort === "function") {
+                            // v1's path, byte-exact and FIRST: the personality is frozen and a shipped
+                            // test pins "aborted on request".
                             const un = unwrapClientResult(await api.abort({ path: { id: r.sessionID } }));
+                            outcome = un.ok ? "stopped" : "threw";
                             r.error = un.ok ? "aborted on request" : `abort failed: ${shorten(un.message ?? "", 60)}`;
+                            r.state = "error";
+                        }
+                        else if (typeof api?.interrupt === "function") {
+                            const got = cancelOutcomeOf(await api.interrupt({ path: { id: r.sessionID } }));
+                            outcome = got.outcome;
+                            note = got.note;
+                            // `idle` is the host saying there was no active execution: the registry row
+                            // was stale, not a failed stop. Anything else closes as undelivered.
+                            r.state = outcome === "idle" ? "idle" : "error";
+                            r.cancelNote = cancelVerdictLine(outcome, note);
+                            if (r.state === "error")
+                                r.error = r.cancelNote;
                         }
                         else {
+                            outcome = "no-seam";
                             r.error = "宿主无 abort 接口，未取消";
+                            r.state = "error";
                         }
-                        r.state = "error";
                         r.finishedAt = now();
-                        log({ step_id: "join", event: "cancel", child: r.sessionID, agent: r.agent, ok: r.error.startsWith("aborted") });
+                        cancelTally[outcome] = (cancelTally[outcome] ?? 0) + 1;
+                        log({ step_id: "join", event: "cancel", child: r.sessionID, agent: r.agent, outcome, ok: outcome === "stopped" });
                     }
+                    log({
+                        step_id: "join",
+                        event: "cancel_summary",
+                        count: stillRunning.length,
+                        outcomes: cancelOutcomeParts(cancelTally).join(" / "),
+                    });
                 }
                 const sums = summarizeStates(mine);
                 const header = [
                     `派发汇总：${sums.idle} 完成 / ${sums.running} 运行中 / ${sums.error} 失败${settled ? "（全部已结算）" : `（未等到全部结算 · 本次已等 ${Math.round((now() - waitStart) / 1000)}s）`}`,
                     ...mine.map((r) => renderChildLine(r, (r.finishedAt ?? now()) - r.startedAt)),
                 ];
+                if (cancelTally) {
+                    const parts = cancelOutcomeParts(cancelTally);
+                    header.push(`取消尝试：${parts.join(" · ") || "没有运行中的子代理可停"} —— ` +
+                        `只有「已由宿主中断」是宿主确认过的停止；「空闲未中断」说明它当时没在活动执行里` +
+                        `（登记行过时了，不是失败）；「未确认」说明中断调用成功但宿主没回 interrupted 布尔。` +
+                        `这三种结论不要混成一句"已取消"转述给用户。`);
+                }
                 if (stillRunning.length && !settled) {
                     header.push(`⏱ 还有 ${stillRunning.length} 个子代理在跑 —— 先告诉用户你在等谁、在等什么、这一轮不是交付，再决定是等还是去干活。` +
                         `你的工具调用在界面上只是一行打不开的卡片，你不说，用户没法把"回合结束"和"任务完成"分开。`);
@@ -633,20 +816,75 @@ export function buildDispatchTools(deps) {
                 // child settled says nothing about the USER'S goal, and the host's own
                 // todo list does.  Read-only (GET /session/{id}/todo has no write
                 // body), so this can remind but never rewrite.
-                if (settled && typeof api?.todo === "function" && parent) {
-                    try {
-                        const un = unwrapClientResult(await api.todo({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
-                        const open = un.ok ? openHostTodos(un.data) : [];
-                        if (open.length) {
-                            header.push(`⚠ 目标未达成：宿主 todolist 还有 ${open.length} 项未完成 —— ${open.slice(0, 6).map((t) => `「${t.content}」(${t.status})`).join("、")}` +
-                                (open.length > 6 ? ` …+${open.length - 6}` : "") +
-                                `\n按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。` +
-                                `（若这些项其实已经做完——例如你刚把派发结果收齐——先用 todowrite 更新状态，再收尾。）`);
-                            log({ step_id: "join", event: "goal_open", count: open.length });
+                //
+                // The check has THREE outcomes and all three must be sayable.  Silence when
+                // the seam is missing (v2's client shim has no `todo`) read as "the goal
+                // check ran and passed", which is the same overstatement this tool was
+                // already fixed for on the adoption path — a settled round is exactly when
+                // an unchecked box matters most.
+                if (settled) {
+                    const canCheck = typeof api?.todo === "function" && Boolean(parent);
+                    let checked = false;
+                    let ledgerEmpty = false;
+                    if (canCheck) {
+                        try {
+                            const un = unwrapClientResult(await api.todo({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
+                            checked = un.ok;
+                            const open = un.ok ? openHostTodos(un.data) : [];
+                            if (open.length) {
+                                header.push(`⚠ 目标未达成：宿主 todolist 还有 ${open.length} 项未完成 —— ${open.slice(0, 6).map((t) => `「${t.content}」(${t.status})`).join("、")}` +
+                                    (open.length > 6 ? ` …+${open.length - 6}` : "") +
+                                    `\n按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。` +
+                                    // v1 has the built-in `todowrite`; a host without it must not be
+                                    // told to call a tool it cannot call (the tm_ptc_run / `task`
+                                    // lesson a third time).  Without the write seam the only honest
+                                    // move is to say which items are done in the reply.
+                                    (typeof api?.todo === "function"
+                                        ? `（若这些项其实已经做完——例如你刚把派发结果收齐——先用 todowrite 更新状态，再收尾。）`
+                                        : `（这个宿主没给写清单的入口：若这些项其实已完成，就在回复里逐条写明哪条做完了、依据是什么。）`));
+                                log({ step_id: "join", event: "goal_open", count: open.length });
+                            }
+                        }
+                        catch {
+                            checked = false;
+                            /* the todo endpoint is an extra, never a reason to fail a join */
                         }
                     }
-                    catch {
-                        /* the todo endpoint is an extra, never a reason to fail a join */
+                    if (!checked && deps.ledgerStore?.available?.() && parent) {
+                        // v2 has no `session.todo` to read, so the list that CAN be checked is
+                        // the one this plugin keeps (`tm_ledger`, in ctx.storage).  A non-empty
+                        // open set is a fact worth refusing a wrap-up over; an EMPTY one is not
+                        // evidence the goal was met — it usually means nothing was ever
+                        // recorded, which is its own honest "cannot check".
+                        try {
+                            const led = await deps.ledgerStore.load(parent);
+                            const rest = led ? openItems(led) : [];
+                            if (rest.length) {
+                                const line = ledgerGoalLine(led);
+                                if (line)
+                                    header.push(line);
+                                log({ step_id: "join", event: "goal_open", count: rest.length, source: "ledger" });
+                                checked = true;
+                            }
+                            else if (led) {
+                                ledgerEmpty = true;
+                            }
+                        }
+                        catch {
+                            /* the ledger is an extra too — a store that will not read never fails a join */
+                        }
+                    }
+                    if (!checked) {
+                        header.push(canCheck
+                            ? "（目标核对没做成：宿主 todo 端点返回异常，这一轮我没有看到你的清单状态。）"
+                            : ledgerEmpty
+                                ? "（目标核对没做成：这个宿主没给 session.todo 端点，而 tm_ledger 里一条都没有——没有可核对的目标状态。`所有子代理已结算` 不等于 `目标已达成`：要么先 tm_ledger { action:\"add\" } 把要求记下来，要么在回复里自己逐条核对再收尾。）"
+                                : "（目标核对没做成：这个宿主没给 session.todo 端点，我也读不到本插件的 tm_ledger——无法读取清单状态。`所有子代理已结算` 不等于 `目标已达成`，这一轮请自己核对再收尾。）");
+                        log({
+                            step_id: "join",
+                            event: "goal_unchecked",
+                            reason: canCheck ? "endpoint_failed" : ledgerEmpty ? "ledger_empty" : "no_seam",
+                        });
                     }
                 }
                 // #80/#86/#87: THE LEASE TRIPWIRE — one computation (leaseLine above),
@@ -664,9 +902,28 @@ export function buildDispatchTools(deps) {
                     for (const r of collectible) {
                         const reply = await fetchReply(r.sessionID, directory);
                         const text = reply.text;
-                        blocks.push(`--- ${r.agent} "${r.label}" (${r.sessionID}) ---\n${text.trim() ||
-                            `（该子会话没有可读的助手回复${r.error ? `；宿主错误：${r.error}` : reply.error ? `；宿主错误：${reply.error}` : ""}）` +
-                                `——子会话不是文件，tm_read 读不到它：在宿主的会话面板里看这条子会话，或改用内置 task 工具重做这一步。`}`);
+                        const src = text && reply.via ? ` ·正文来源=${reply.via}` : "";
+                        // Which seam answered, per child — an id, a seam name and the SHAPE it saw, never
+                        // a body (R6 binds a diagnostic too). This is the line that makes "正文来源=…"
+                        // checkable later, and the only place the three outcomes stay distinguishable:
+                        // a real body, a seam that answered with nothing readable (`shape=items=2 …
+                        // content=1 kinds=[tool] text=0`), and a seam that never answered (`no-context-method`).
+                        log({
+                            step_id: "join",
+                            event: text ? "child_body" : "child_body_missing",
+                            child: r.sessionID,
+                            via: reply.via ?? "none",
+                            // Only when the SEAM reported one: v1's SDK client gives no shape, and the v1
+                            // personality is frozen — its rows stay byte-exact rather than gaining a field
+                            // nobody asked for. The v2 bridge reports a shape on every path.
+                            ...(text || !reply.shape ? {} : { shape: reply.shape }),
+                        });
+                        blocks.push(`--- ${r.agent} "${r.label}" (${r.sessionID})${src} ---\n${text.trim() ||
+                            (r.via === "host-injection"
+                                ? `（这个子会话由宿主的 subagent 工具派发，而这一次我没有读到它的正文${reply.error ? `：${reply.error}` : "：这个宿主没给可读正文的缝"}。完成时宿主仍会把 \`<subagent sessionID=\"${r.sessionID}\" …>\` 注入本会话，我已经把它登记在案、状态如上。` +
+                                    `要全文就在那条注入到达后读它，或让子代理把交付写进黑板；不要为了拿正文反复 join。）`
+                                : `（该子会话没有可读的助手回复${r.error ? `；宿主错误：${r.error}` : reply.error ? `；宿主错误：${reply.error}` : ""}）` +
+                                    `——子会话不是文件，tm_read 读不到它：在宿主的会话面板里看这条子会话，或改用内置 task 工具重做这一步。`)}`);
                     }
                 }
                 const body = [...header, ...(blocks.length ? ["", blocks.join("\n")] : [])].join("\n");
@@ -691,12 +948,31 @@ export function buildDispatchTools(deps) {
         if (!sid)
             return;
         const rec = children.get(sid);
-        if (!rec)
+        if (!rec) {
+            // The parent's own idle is the only completion signal v2 gives us for a host
+            // child: the background reply is injected into the parent before the parent's turn
+            // ends (measured: child injected …824730, parent idle …829038), and the plugin has
+            // no endpoint to read a child session's state.  So settle the still-running host
+            // children of THIS session — and say plainly that it is a presumption.
+            if (type === "session.idle") {
+                for (const child of children.values()) {
+                    if (child.via !== "host-injection" || child.state !== "running")
+                        continue;
+                    if (child.parentSessionID !== sid)
+                        continue;
+                    child.state = "idle";
+                    child.finishedAt = now();
+                    child.settleSource = "parent-idle";
+                    log({ step_id: "events", event: "idle_presumed", child: child.sessionID, agent: child.agent, ms: child.finishedAt - child.startedAt });
+                }
+            }
             return;
+        }
         if (type === "session.idle") {
             if (rec.state === "running") {
                 rec.state = "idle";
                 rec.finishedAt = now();
+                rec.settleSource = "event";
                 log({ step_id: "events", event: "idle", child: sid, agent: rec.agent, ms: (rec.finishedAt ?? 0) - rec.startedAt });
             }
             return;
@@ -721,9 +997,54 @@ export function buildDispatchTools(deps) {
             }
         }
     };
+    /** Open a row for a child the HOST dispatched (v2's `subagent` tool) that this
+     *  registry never created.  Returns false when the ids are unusable or the child is
+     *  already known — a plugin reload replays hooks, and a second row for one session
+     *  would make tm_join count the same work twice. */
+    function register(child) {
+        const rec = hostChildRecord(child, now);
+        if (!rec || children.has(rec.sessionID))
+            return false;
+        children.set(rec.sessionID, rec);
+        deps.onChildSession?.(rec.sessionID, rec.agent);
+        // The label is model-authored free text: it belongs in the lead's table, never in
+        // the audit trail (R6 binds a diagnostic as much as a guard).
+        log({ step_id: "join", event: "host_subagent", child: rec.sessionID, agent: rec.agent, parent: rec.parentSessionID });
+        return true;
+    }
+    /** Settle a child from the host's OWN completion envelope (see
+     *  `applyV2CompletionWatch`).  Returns false when this process does not know the id, so
+     *  an unrelated session's injection never touches our registry.  This is the third
+     *  settle source and the only one that works mid-turn on v2: the child's own
+     *  `session.idle` is not forwarded to a plugin subscriber (measured 2026-09-26), and a
+     *  parent-idle presumption cannot fire while the parent is still working — which left a
+     *  child whose report had already been injected showing 运行中. */
+    function settle(sessionID, state) {
+        const rec = children.get(String(sessionID ?? "").trim());
+        if (!rec || rec.state !== "running")
+            return false;
+        rec.finishedAt = now();
+        if (state === "error" || state === "failed" || state === "aborted") {
+            rec.state = "error";
+            rec.error = `宿主报告子会话 ${state}（其正文随注入消息送达）`;
+        }
+        else {
+            rec.state = "idle";
+        }
+        rec.settleSource = "injection";
+        log({ step_id: "events", event: "idle_injection", child: rec.sessionID, agent: rec.agent, ms: rec.finishedAt - rec.startedAt });
+        return true;
+    }
     return {
         tm_join: join,
         observeEvent,
+        register,
+        settle,
+        /** Anything still running? The completion scan is O(messages) per request, so it
+         *  asks this first and skips the read when the answer is no. */
+        hasOpen: () => { for (const c of children.values())
+            if (c.state === "running")
+                return true; return false; },
         children: () => [...children.values()],
     };
 }