@te-river/opencode-team-mode 1.8.4 → 1.8.6

package/dist/tm/dispatch.js

@@ -40,6 +40,22 @@
  * already calls.  What the host does NOT give is tool-level cancellation — the
  * only thing stoppable is the whole active execution (`interrupt`) — so nothing
  * here pretends that granularity exists.
+ *
+ * Waking (2026-10-23, measured in another project): steering a session that has
+ * already settled is not an interjection, it is a RESURRECTION — the host's own
+ * sentence is "Steering wakes session execution", so the line starts a second run
+ * that overlaps whatever the lead dispatched meanwhile (two processes on one
+ * device, in the incident that produced this).  A steer therefore refuses unless
+ * the registry says `running`, and the explicit `wake:true` opt-in is the only way
+ * to deliver into a settled/unknown child.  The same incident showed the mirror
+ * bug on the stop path: a settled row made `cancel:true` answer "没有运行中的
+ * 子代理可停" WITHOUT asking the host, while the woken child was in fact running.
+ * An explicitly named id is always asked of the host now.
+ *
+ * The body fallback has one more source: a settled host sub-agent's report also
+ * lives in the PARENT transcript as `<subagent sessionID="…">…</subagent>`; when
+ * the child session's context yields no assistant text, that envelope is read
+ * (exact id match, last one wins) instead of reporting `child_body_missing`.
  */
 import { sameAgent } from "../identity.js";
 import { tmError, toToolResult } from "./result.js";
@@ -96,6 +112,34 @@ export function sessionApiOf(client) {
         return null;
     return api;
 }
+export async function readHostSessionState(api, sessionID) {
+    const id = String(sessionID ?? "").trim();
+    if (!api || typeof api.get !== "function" || !id)
+        return { answered: false };
+    try {
+        // The flat `{sessionID}` spelling is the measured one; the v2 bridge also retries the
+        // older `{path:{id}}` shape, so either call convention still lands.
+        const un = unwrapClientResult(await api.get({ sessionID: id }));
+        if (!un.ok)
+            return { answered: false };
+        const d = un.data;
+        if (!d || typeof d !== "object")
+            return { answered: false };
+        const createdAt = typeof d.time?.created === "number" && d.time.created > 0 ? d.time.created : undefined;
+        const idleAt = typeof d.time?.idle === "number" && d.time.idle > 0 ? d.time.idle : undefined;
+        const outcome = typeof d.outcome === "string" && d.outcome.trim() ? d.outcome.trim() : undefined;
+        return {
+            answered: true,
+            ...(createdAt ? { createdAt } : {}),
+            ...(idleAt ? { idleAt } : {}),
+            ...(outcome ? { outcome } : {}),
+        };
+    }
+    catch {
+        // A throwing seam is "we could not ask" — never "it settled".
+        return { answered: false };
+    }
+}
 /** The host's OWN visible-and-non-blocking sub-agent path: its built-in `task`
  *  takes `background: true`, and because that card is rendered by the host's
  *  own `task` renderer it links to the live child session — which a plugin tool
@@ -225,6 +269,79 @@ export function lastAssistantMessage(messages) {
 export function lastAssistantText(messages) {
     return lastAssistantMessage(messages).text;
 }
+/** Every non-empty text body a transcript carries, in message order.
+ *  Deliberately NOT filtered by role: the host's completion envelope arrives as an
+ *  ordinary (user-role) message, and dropping it here would make the fallback below
+ *  structurally dead. */
+function transcriptTexts(messages) {
+    const list = Array.isArray(messages) ? messages : [];
+    const out = [];
+    for (const entry of list) {
+        const e = entry;
+        if (Array.isArray(e?.parts)) {
+            const t = e.parts
+                .filter((p) => {
+                const pp = p;
+                return pp && pp.type === "text" && typeof pp.text === "string";
+            })
+                .map((p) => String(p.text))
+                .join("\n");
+            if (t.trim())
+                out.push(t);
+            continue;
+        }
+        if (e?.type === "text" && typeof e.text === "string" && e.text.trim())
+            out.push(e.text);
+    }
+    return out;
+}
+/** The body of the LAST `<subagent sessionID="<sid>" …>…</subagent>` envelope in one
+ *  text, or null.  The id must match EXACTLY — an envelope naming another child is
+ *  never adopted, because the lead naming a session must not receive someone else's
+ *  report (the same rule `parentageOf` applies to steering). */
+function lastEnvelopeFor(text, sessionID) {
+    let from = 0;
+    let found = null;
+    for (;;) {
+        const open = text.indexOf("<subagent", from);
+        if (open < 0)
+            break;
+        const gt = text.indexOf(">", open);
+        if (gt < 0)
+            break;
+        const tag = text.slice(open, gt + 1);
+        const close = text.indexOf("</subagent>", gt + 1);
+        if (close < 0)
+            break;
+        const id = /\bsessionID\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(tag);
+        if (id && (id[1] ?? id[2] ?? "").trim() === sessionID) {
+            const body = text.slice(gt + 1, close).trim();
+            if (body)
+                found = body;
+        }
+        from = close + "</subagent>".length;
+    }
+    return found;
+}
+/** The body the host injected into the PARENT transcript for this child, if any.
+ *  The v2 plugin can read a child's own context, but a host sub-agent's report also
+ *  arrives in the parent as a completion envelope — and on a host whose child context
+ *  answers with no assistant text (the measured `child_body_missing`), that envelope
+ *  is the only readable copy.  Null when nothing matches, so the caller keeps its
+ *  exact `child_body_missing` wording rather than inventing a third outcome. */
+export function hostEnvelopeBody(messages, sessionID) {
+    const sid = String(sessionID ?? "").trim();
+    if (!sid)
+        return null;
+    const texts = transcriptTexts(messages);
+    // newest-first: a child re-run after a wake may have been injected more than once
+    for (let i = texts.length - 1; i >= 0; i--) {
+        const hit = lastEnvelopeFor(texts[i], sid);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
 /**
  * Turn whatever the host puts in an error slot into ONE readable line.
  *
@@ -276,10 +393,27 @@ export function describeHostError(err, max = 220) {
  * that had already landed — the fix is to say it, not to withhold the text.
  */
 export const INCOMPLETE_PRESUMED_BODY_WARNING = "⚠ 推定结算且正文未带完成时间：这可能是最后一次工具调用前的半截话，不要据此判定交付；稍后再次 tm_join 可复核（或让子代理续跑）。";
-/** One child's status line — the lead reads these, so keep them terse. */
+/** One child's status line — the lead reads these, so keep them terse.  The tag is chosen by
+ *  the settle SOURCE, because the same word would otherwise cover a host-confirmed finish, an
+ *  unreachable seam and a guess: only `session-get` may print the host's outcome, and nothing
+ *  but a real settlement may print 完成. */
 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`;
+    const hostRunSecs = c.hostIdleAt !== undefined && c.hostCreatedAt !== undefined && c.hostIdleAt > c.hostCreatedAt
+        ? Math.round((c.hostIdleAt - c.hostCreatedAt) / 1000)
+        : secs;
+    const tag = c.state === "running"
+        ? `运行中 ${secs}s`
+        : c.state === "error"
+            ? `失败：${shorten(c.error ?? "", 80)}`
+            : c.settleSource === "session-get"
+                ? // The host's own record answered with a finished run: the only form allowed to
+                    // print its outcome word, and it never says 推定.
+                    `已结算（${c.outcome ?? "宿主未给 outcome"}）· 运行 ${hostRunSecs}s`
+                : c.settleSource === "parent-idle"
+                    ? // An inference.  完成 is exactly the word this may not borrow.
+                        `推定已结算（未确认完成）· 派发后 ${secs}s`
+                    : `已完成 ${secs}s`;
     // #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}` : "";
@@ -289,6 +423,38 @@ export function renderChildLine(c, elapsedMs) {
             ? " ·（宿主 subagent 派发）"
             : ""}`;
 }
+/**
+ * One line saying HOW the round's rows reached their state: `宿主确认` (the host's own record,
+ * event or envelope), `推定` (our inference) and `未结算` (still running).  A lead skimming two
+ * rows that both read 已结算 otherwise cannot tell which one the host actually confirmed — and
+ * that difference is the whole point of asking `session.get` first.
+ */
+export function settleTallyLine(children) {
+    if (!children.length)
+        return "";
+    let confirmed = 0;
+    let presumed = 0;
+    let open = 0;
+    const outcomes = new Map();
+    for (const c of children) {
+        if (c.state === "running") {
+            open++;
+            continue;
+        }
+        if (c.settleSource === "parent-idle") {
+            presumed++;
+            continue;
+        }
+        confirmed++;
+        if (c.outcome)
+            outcomes.set(c.outcome, (outcomes.get(c.outcome) ?? 0) + 1);
+    }
+    const named = [...outcomes.entries()].map(([o, n]) => `${o} ${n}`);
+    const withoutOutcome = confirmed - [...outcomes.values()].reduce((a, b) => a + b, 0);
+    if (withoutOutcome > 0)
+        named.push(`宿主未给 outcome ${withoutOutcome}`);
+    return `结算：宿主确认 ${confirmed}${named.length ? `（${named.join(" · ")}）` : ""} / 推定 ${presumed} / 未结算 ${open}`;
+}
 /** Verdicts tm_join can actually observe (issue #7's "leader keeps control"). */
 export function summarizeStates(children) {
     let running = 0;
@@ -439,6 +605,51 @@ export function steerVerdictLine(outcome, opts) {
             return `未插话${seam}：${shorten(opts?.note ?? "宿主没有回 inbox id", 120)}`;
     }
 }
+/** What the lead reads after the delivery check.  Every branch says out loud that delivery is
+ *  not obedience — the composition must never promise what the child will do. */
+export function steerDeliveryLine(v, inboxID, note) {
+    const inbox = inboxID ? `（inbox=${inboxID}）` : "";
+    switch (v) {
+        case "delivered":
+            return `已送达${inbox}：该 inbox 项已经不在待投递清单里，宿主把它交给了子会话。投递不等于子代理照做 —— 它是否按这条改，仍要看下一次结算与正文。`;
+        case "queued":
+            return `已受理（未送达，宿主在步边界投递）${inbox}：该项仍在待投递清单里。投递≠执行，别把这一句当成子代理会照做。`;
+        case "unverified":
+            return `已受理${inbox}（未验证送达${note ? `：${shorten(note, 80)}` : "：宿主没有给出可核对的待投递清单"}）。投递≠执行。`;
+    }
+}
+/** Re-read the child's inbox once after a successful steer and answer the only question that
+ *  can be answered: is the item still pending?  `unverified` covers every shape we cannot
+ *  read — no seam, a throwing call, a payload with items we could not identify — because
+ *  "absent" must not be inferred from "unreadable". */
+export async function verifySteerDelivery(api, sessionID, inboxID) {
+    if (!api || api.v2SteerSeam !== true || typeof api.inboxList !== "function") {
+        return { verdict: "unverified", note: "这个宿主没有 session.inbox.list 的缝" };
+    }
+    try {
+        const un = unwrapClientResult(await api.inboxList({ sessionID }));
+        if (!un.ok)
+            return { verdict: "unverified", note: un.message };
+        const data = un.data;
+        const seamOut = String(data?.outcome ?? "");
+        if (seamOut === "threw" || seamOut === "no-seam") {
+            return {
+                verdict: "unverified",
+                note: seamOut === "no-seam" ? "宿主没给 session.inbox.list" : String(data?.message ?? "查询被宿主拒绝"),
+            };
+        }
+        const listed = inboxItemLines(data?.items);
+        // An item we could not parse is not an item that is gone: `skipped` covers unknown id
+        // shapes AND the overflow past the list cap, and both make "absent" unprovable.
+        if (listed.skipped > 0)
+            return { verdict: "unverified", note: `清单里有 ${listed.skipped} 项没被列出（id 形状或条数上限）` };
+        const stillQueued = listed.lines.some((l) => l.split(" · ")[0] === `id=${inboxID}`);
+        return stillQueued ? { verdict: "queued" } : { verdict: "delivered" };
+    }
+    catch (err) {
+        return { verdict: "unverified", note: describeHostError(err, 120) };
+    }
+}
 export function steerOutcomeLabel(o) {
     return o === "steered" ? "已受理" : o === "not-steered" ? "未插话" : "无插话缝";
 }
@@ -599,6 +810,15 @@ export function buildDispatchTools(deps) {
     // comparable with this one.  Renaming would split the history in two.
     const log = (e) => store.appendTrajectory({ tool: "tm_dispatch", ...e });
     const children = new Map();
+    /** Settle checks still in flight.  `observeEvent` is a synchronous hook — the host does not
+     *  await it — while asking `session.get` is async, so the read is tracked here and DRAINED by
+     *  tm_join before it reports.  Without that, a join issued right after a parent-idle event
+     *  could answer from a row we were in the middle of updating. */
+    const settling = new Set();
+    const trackSettle = (p) => {
+        settling.add(p);
+        void p.finally(() => settling.delete(p));
+    };
     /** Per-parent memory of the LAST join's outcome.  A wait is not parallelism
      *  — while tm_join is in flight the lead's turn is blocked exactly like a
      *  synchronous `task` call — so a SECOND wait that inherited a first wait
@@ -641,7 +861,26 @@ export function buildDispatchTools(deps) {
             }
         }
     }
-    function fetchReply(sid, directory) {
+    /** Read the completion envelope the host injected into the PARENT transcript for
+     *  this child.  Absent seam / failed call / no matching envelope all return null —
+     *  the fallback may not turn "I could not look" into a body. */
+    async function envelopeFromParent(parent, sid, directory) {
+        if (!parent || !sid || parent === sid)
+            return null;
+        if (typeof api?.messages !== "function")
+            return null;
+        try {
+            const raw = await api.messages({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) });
+            const un = unwrapClientResult(raw);
+            if (!un.ok)
+                return null;
+            return hostEnvelopeBody(un.data, sid);
+        }
+        catch {
+            return null;
+        }
+    }
+    function fetchReply(sid, directory, parentSessionID) {
         return (async () => {
             if (typeof api?.messages !== "function") {
                 return { text: "", error: "这个宿主客户端没有给出读取子会话正文的缝（v2 上它是 ctx.session.context 的兼容层）", bodyComplete: false };
@@ -668,9 +907,19 @@ export function buildDispatchTools(deps) {
                     bodyComplete: typeof got.completedAt === "number",
                     ...(typeof got.completedAt === "number" ? { bodyCompletedAt: got.completedAt } : {}),
                 };
-                return got.text
+                return got.text.trim()
                     ? { ...got, via, ...(shape ? { shape } : {}), ...completeness }
-                    : { text: "", error: got.error, via, ...(shape ? { shape } : {}), ...completeness };
+                    : await (async () => {
+                        // C: the child's own context answered with no assistant text.  Before
+                        // reporting `child_body_missing`, look for the host's completion envelope
+                        // in the parent — for a host sub-agent that IS the delivered report, and a
+                        // lead that cannot read it has to re-dispatch work that already landed.
+                        const envelope = await envelopeFromParent(parentSessionID ?? "", sid, directory);
+                        if (envelope) {
+                            return { text: envelope, via: "host-envelope", shape: "parent-envelope", bodyComplete: true };
+                        }
+                        return { text: "", error: got.error, via, ...(shape ? { shape } : {}), ...completeness };
+                    })();
             }
             catch (err) {
                 return { text: "", error: describeHostError(err?.message ?? err, 140), bodyComplete: false };
@@ -702,7 +951,7 @@ export function buildDispatchTools(deps) {
         // 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 缺失），我没有看过会话树" };
+            return { adopted: 0, looked: false, why: "这个宿主客户端没有给出 session.children（缺的只是「列举会话树」这一条缝，不是我整个 session API 不可用），我没有看过会话树" };
         if (!parent)
             return { adopted: 0, looked: false, why: "调用方会话 id 缺失，无从查询子会话" };
         let un;
@@ -834,10 +1083,10 @@ export function buildDispatchTools(deps) {
         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.
-- Steer a child while it runs — the same call, no separate tool: { steer: "先停手，验收改成 X", ids: ["<child>"] } admits the line into that child's inbox with delivery "steer" (or "queue") and the host wakes execution at the step boundary.  已受理 is the whole claim: it is NOT proof the child read it, and the reply never says 已送达.  { unread: true, ids: ["<child>"] } lists that child's undelivered inbox items (ids + shape only, never the body); { unsend: {"sessionID":"ses_…","inboxID":"msg_…"} } withdraws one that has not been delivered — an already-delivered item is the documented no-op and is reported as one.  All three ask the host for parentage FIRST and refuse a session that is not yours; a host without the seam answers no-seam instead of pretending.
+- { 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.  With explicit ids the host is ALWAYS asked, even for a row this process believes settled — a settled-looking row can have been woken and be running for real.
+- Steer a child while it runs — the same call, no separate tool: { steer: "先停手，验收改成 X", ids: ["<child>"] } admits the line into that child's inbox with delivery "steer" (or "queue") and the host wakes execution at the step boundary.  已受理 means the host took the line into that inbox — NOT that the child read or obeyed it.  After a successful steer the tool re-reads that inbox ONCE: an item gone from the pending list is reported 已送达, still pending is 已受理（未送达，宿主在步边界投递）, and an inbox it cannot read is 已受理（未验证送达）— delivery is never inferred from the write alone, and none of the three means the child followed it.  Steer REFUSES a child whose registered state is not running (idle / error / unknown), because the host's doc sentence "Steering wakes session execution" means the line starts a second run that overlaps new dispatches — pass { wake: true } to do that deliberately.  { unread: true, ids: ["<child>"] } lists that child's undelivered inbox items (ids + shape only, never the body); { unsend: {"sessionID":"ses_…","inboxID":"msg_…"} } withdraws one that has not been delivered — an already-delivered item is the documented no-op and is reported as one.  All three ask the host for parentage FIRST and refuse a session that is not yours; a host without the seam answers no-seam instead of pretending.
 - 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.`,
+- 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.  When a child's own session yields no assistant text, the host's injected \`<subagent sessionID="…">…</subagent>\` envelope in THIS session is read as the body and labelled 正文来源=宿主注入信封 (an id must match exactly).`,
         args: {
             ids: { descriptor: "ids: string[] (optional — only these child sessions)" },
             waitMs: { descriptor: `waitMs: number (optional 0..${maxWaitMs} — bounded wait; a SECOND consecutive wait is cut to 10s, because waiting is not parallel work)` },
@@ -857,6 +1106,9 @@ export function buildDispatchTools(deps) {
             delivery: {
                 descriptor: "delivery: steer|queue (optional, default steer — applies to steer only. Any other value is refused rather than silently defaulted.)",
             },
+            wake: {
+                descriptor: "wake: boolean (optional, default false — steer only. A steer into a settled/idle child is REFUSED unless this is true, because the host wakes execution and the child then overlaps new dispatches. Accepts true/false or the strings \"true\"/\"false\".)",
+            },
             unread: {
                 descriptor: "unread: true (optional — list the undelivered inbox items of the child named by ids: ids and shape only, never the body)",
             },
@@ -878,6 +1130,10 @@ export function buildDispatchTools(deps) {
                 // wrote its governed result — so the token table read "0 调用 / 2 结果",
                 // which looks like a broken counter rather than a tool that ran.
                 store.appendTrajectory({ tool, step_id: "join", event: "call" });
+                // A settle check may still be talking to the host (see `settling`).  Drain it before
+                // reading the registry so this reply never mixes a fresh table with a half-updated row.
+                if (settling.size)
+                    await Promise.allSettled([...settling]);
                 const directory = typeof c.directory === "string" && c.directory ? c.directory : undefined;
                 const idList = parseIdList(args.ids);
                 const idFilter = idList && idList.length ? new Set(idList) : null;
@@ -963,6 +1219,45 @@ export function buildDispatchTools(deps) {
                         ? renderChildLine(row, (row.finishedAt ?? now()) - row.startedAt)
                         : `${target} · ${gate.agent} ·（本进程没有它的登记行，归属由宿主确认）`;
                     if (steerText) {
+                        // A steer into a session that is not running is a WAKE, not an interjection:
+                        // the host's own doc says "Steering wakes session execution", so it starts a
+                        // second run that overlaps whatever the lead dispatched meanwhile.  Measured
+                        // cost: a settled child was woken this way and ran concurrently with a fresh
+                        // worker, two processes on one device.  Default = refuse; `wake:true` is the
+                        // explicit opt-in, and the value is coerced the way the rest of this tool's
+                        // boolean args are (`cancel`/`unread` above): boolean or "true"/"false".
+                        const wakeRaw = args.wake;
+                        let wakeRequested = false;
+                        if (wakeRaw !== undefined && wakeRaw !== null) {
+                            if (wakeRaw === true || wakeRaw === false)
+                                wakeRequested = wakeRaw;
+                            else if (typeof wakeRaw === "string" && /^(true|false)$/i.test(wakeRaw.trim())) {
+                                wakeRequested = /^true$/i.test(wakeRaw.trim());
+                            }
+                            else {
+                                return toToolResult(tmError(tool, "args", `wake 只接受 true/false（布尔或 "true"/"false" 字符串），收到 ${shorten(String(wakeRaw), 24)}，未发送。`));
+                            }
+                        }
+                        // The registry can be stale in the dangerous direction too (an event we
+                        // missed would leave a settled child looking running); ask the host before
+                        // trusting "running" when it offers a status map.
+                        if (row && row.state === "running" && typeof api?.status === "function") {
+                            await refreshFromStatus(directory);
+                        }
+                        const rowState = row?.state;
+                        if (rowState !== "running" && !wakeRequested) {
+                            log({
+                                step_id: "join",
+                                event: "steer_refused",
+                                child: target,
+                                agent: gate.agent,
+                                reason: "not-running",
+                                state: rowState ?? "unregistered",
+                                // the LENGTH, never the text — R6 binds the audit trail as much as the reply
+                                chars: steerText.length,
+                            });
+                            return toToolResult(`没有发送：该子代理已结算（或状态未知）；插话会唤醒它并与新派发并发——要停止用 cancel:true，要复活请显式 wake:true。\n目标：${rowLine}`);
+                        }
                         let outcome = "no-seam";
                         let inboxID;
                         let note;
@@ -980,6 +1275,20 @@ export function buildDispatchTools(deps) {
                             // and a verdict read off whatever came back.
                             note = "这个客户端不是 v2 的 ctx.session 桥（v1 的 session.prompt 走 {path,body}，没有 delivery 字段），未调用";
                         }
+                        // C — the write only proves ADMISSION.  Ask the same inbox once more for the one
+                        // checkable fact: is the item still pending?  Nothing is claimed when the seam
+                        // cannot answer (see steerDeliveryLine's unverified branch).
+                        const verified = outcome === "steered" && inboxID ? await verifySteerDelivery(api, target, inboxID) : null;
+                        if (verified) {
+                            log({
+                                step_id: "join",
+                                event: "steer_delivery",
+                                child: target,
+                                inboxID,
+                                verdict: verified.verdict,
+                                ...(verified.note ? { reason: shorten(verified.note, 120) } : {}),
+                            });
+                        }
                         log({
                             step_id: "join",
                             event: "steer",
@@ -988,7 +1297,9 @@ export function buildDispatchTools(deps) {
                             delivery,
                             outcome,
                             ok: outcome === "steered",
+                            wake: wakeRequested,
                             ...(inboxID ? { inboxID } : {}),
+                            ...(verified ? { delivered: verified.verdict } : {}),
                             ...(seam ? { seam } : {}),
                             // the LENGTH, never the text — R6 binds the audit trail as much as the reply
                             chars: steerText.length,
@@ -996,10 +1307,13 @@ export function buildDispatchTools(deps) {
                         const tally = {};
                         tally[outcome] = 1;
                         log({ step_id: "join", event: "steer_summary", count: 1, outcomes: steerOutcomeParts(tally).join(" / ") });
-                        const wake = row && row.state !== "running"
-                            ? `\n它现在不是运行中（${row.state === "error" ? "失败" : "已结算"}）；按文档 steer 会唤醒它的执行，但唤醒之后它做什么，要等它结算才看得到。`
+                        const wake = outcome === "steered" && wakeRequested && row && row.state !== "running"
+                            ? `\n已按 wake:true 唤醒：它当时不是运行中（${row.state === "error" ? "失败" : "已结算"}），宿主把这条插话当成新的执行输入——它会和新派发的 worker 并发，留意这一点。`
+                            : "";
+                        const deliveryLine = verified
+                            ? `\n投递核对：${steerDeliveryLine(verified.verdict, inboxID, verified.note)}`
                             : "";
-                        return toToolResult(`插话目标：${rowLine}\n插话结果：${steerVerdictLine(outcome, { inboxID, note, seam })}\n插话计数：${steerOutcomeParts(tally).join(" · ")}${wake}`);
+                        return toToolResult(`插话目标：${rowLine}\n插话结果：${steerVerdictLine(outcome, { inboxID, note, seam })}\n插话计数：${steerOutcomeParts(tally).join(" · ")}${deliveryLine}${wake}`);
                     }
                     if (wantsUnread) {
                         if (!api || api.v2SteerSeam !== true || typeof api.inboxList !== "function") {
@@ -1062,18 +1376,29 @@ export function buildDispatchTools(deps) {
                     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.
+                            // TWO independent facts live here, and they used to be fused into one
+                            // sentence: what the session READER can do, and whether the CHILDREN
+                            // endpoint exists.  On 2.1.4 `ctx.session.get({sessionID})` answers while
+                            // `session.children` does not, so the old text ("可辨认的 session API 缺失"
+                            // plus the last error of a shape already abandoned) told the lead the host
+                            // had no session API at all — and it went back to assuming its id was
+                            // fine and the host broken.  State them separately, and name the shapes
+                            // only when EVERY shape failed: a shape that worked makes the abandoned
+                            // ones irrelevant, not evidence.
                             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）"}`
+                                ? sr.usedShape
+                                    ? `；ctx.session.get 可用（形状 ${sr.usedShape}）：宿主没有 session.children，按 id 读单条会话可以，列举会话树不行`
+                                    : `；按 id 读子会话也失败：试过的 ctx.session 形状 ${sr.failedShapes.length ? sr.failedShapes.join("→") : "?"}${sr.lastError ? `（宿主最后一次的错误：${shorten(sr.lastError, 90)}）` : "（宿主没有报错，只是没给出 parentID）"}`
                                 : "";
+                            // A named id that neither our registry nor the host's by-id read could
+                            // resolve is a miss about THAT id — saying it means the host has no
+                            // session API is the claim this branch exists to stop making.
+                            const named = [...idFilter].slice(0, 3).map((s) => shorten(s, 40)).join("、");
+                            const miss = `ids 未匹配到本会话的子代理：${named} 在本机不存在或无权限`;
                             return saw
-                                ? `（ids 未匹配到本会话的子代理，宿主会话树里也没有可认领的子会话）${bridge}`
-                                : `（ids 未匹配到；而且我没能查看宿主会话树：${adoption.why}）${bridge}`;
+                                ? `（${miss}；宿主会话树里也没有可认领的子会话${bridge}）`
+                                : `（${miss}；而且我没能查看宿主会话树：${adoption.why}${bridge}）`;
                         })()
                         : saw
                             ? ""
@@ -1119,47 +1444,92 @@ export function buildDispatchTools(deps) {
                 let cancelTally = null;
                 if (args.cancel === true || args.cancel === "true") {
                     cancelTally = {};
-                    for (const r of stillRunning) {
+                    // B: an EXPLICITLY named id is always asked of the host.  The registry is this
+                    // process's memory, not the host's truth — the live failure was a row settled
+                    // HERE while the host had just been made to run it by a steer, and the old loop
+                    // over `stillRunning` answered "没有运行中的子代理可停" without ever calling the
+                    // host.  With no ids the shipped behaviour stays ("only those we still believe
+                    // are running"), because "cancel everything" must not interrogate every settled
+                    // child of the session.
+                    const cancelTargets = idFilter ? mine.filter((r) => idFilter.has(r.sessionID)) : stillRunning;
+                    for (const r of cancelTargets) {
+                        const wasRunning = r.state === "running";
                         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".
+                            // v1's path, byte-exact and FIRST for a RUNNING row: 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";
+                            if (wasRunning) {
+                                outcome = un.ok ? "stopped" : "threw";
+                                r.error = un.ok ? "aborted on request" : `abort failed: ${shorten(un.message ?? "", 60)}`;
+                                r.state = "error";
+                            }
+                            else {
+                                // v1's abort returns no `interrupted` boolean, so an already-settled row
+                                // cannot honestly be called stopped OR failed from this answer.
+                                outcome = un.ok ? "unknown" : "threw";
+                                note = un.ok ? "v1 的 abort 不返回 interrupted 布尔" : un.message;
+                                r.cancelNote = cancelVerdictLine(outcome, note);
+                            }
                         }
                         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")
+                            if (wasRunning) {
+                                // `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";
+                                if (r.state === "error")
+                                    r.error = r.cancelNote;
+                            }
+                            else if (outcome === "stopped") {
+                                // A row we believed settled was in fact executing (a woken session is the
+                                // measured case): the host just stopped it, and the row must say so.
+                                r.state = "error";
                                 r.error = r.cancelNote;
+                            }
+                            // idle / unknown / no-seam / threw on an already-settled row leave its settle
+                            // verdict alone — the stop attempt is extra evidence, not a re-settlement.
                         }
                         else {
                             outcome = "no-seam";
-                            r.error = "宿主无 abort 接口，未取消";
-                            r.state = "error";
+                            if (wasRunning) {
+                                r.error = "宿主无 abort 接口，未取消";
+                                r.state = "error";
+                            }
+                            else {
+                                r.cancelNote = cancelVerdictLine("no-seam");
+                            }
                         }
-                        r.finishedAt = now();
+                        if (wasRunning || r.finishedAt === undefined)
+                            r.finishedAt = now();
                         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",
+                            child: r.sessionID,
+                            agent: r.agent,
+                            outcome,
+                            explicit: Boolean(idFilter),
+                            was_running: wasRunning,
+                            ok: outcome === "stopped",
+                        });
                     }
                     log({
                         step_id: "join",
                         event: "cancel_summary",
-                        count: stillRunning.length,
+                        count: cancelTargets.length,
                         outcomes: cancelOutcomeParts(cancelTally).join(" / "),
                     });
                 }
                 const sums = summarizeStates(mine);
+                const settleLine = settleTallyLine(mine);
                 const header = [
                     `派发汇总：${sums.idle} 完成 / ${sums.running} 运行中 / ${sums.error} 失败${settled ? "（全部已结算）" : `（未等到全部结算 · 本次已等 ${Math.round((now() - waitStart) / 1000)}s）`}`,
+                    ...(settleLine ? [settleLine] : []),
                     ...mine.map((r) => renderChildLine(r, (r.finishedAt ?? now()) - r.startedAt)),
                 ];
                 // The `正文：` line belongs directly under the child rows it describes, but the
@@ -1168,7 +1538,11 @@ export function buildDispatchTools(deps) {
                 const childRowsEnd = header.length;
                 if (cancelTally) {
                     const parts = cancelOutcomeParts(cancelTally);
-                    header.push(`取消尝试：${parts.join(" · ") || "没有运行中的子代理可停"} —— ` +
+                    header.push(`取消尝试：${parts.join(" · ") ||
+                        // Never leave "没有运行中的子代理可停" as the ONLY answer: with no ids the
+                        // default restricted the attempt to rows we believed running, and the lead
+                        // must know that a settled-looking row was therefore not asked about.
+                        "没有运行中的子代理可停（未显式给 ids 时只对登记为运行中的子代理发起取消；若你怀疑某个已结算的子会话其实在跑，用 ids 点名——我会先去问宿主）"} —— ` +
                         `只有「已由宿主中断」是宿主确认过的停止；「空闲未中断」说明它当时没在活动执行里` +
                         `（登记行过时了，不是失败）；「未确认」说明中断调用成功但宿主没回 interrupted 布尔。` +
                         `这三种结论不要混成一句"已取消"转述给用户。`);
@@ -1267,7 +1641,7 @@ export function buildDispatchTools(deps) {
                 const bodyStatus = [];
                 if (wantText) {
                     for (const r of collectible) {
-                        const reply = await fetchReply(r.sessionID, directory);
+                        const reply = await fetchReply(r.sessionID, directory, parent);
                         const text = reply.text;
                         r.bodyComplete = reply.bodyComplete === true;
                         r.bodyCompletedAt = reply.bodyCompletedAt;
@@ -1279,7 +1653,10 @@ export function buildDispatchTools(deps) {
                         // fragment, which would be the same overstatement facing the other way.
                         const half = hasBody && r.bodyComplete === false && r.settleSource === "parent-idle";
                         bodyStatus.push(`正文：${!hasBody ? "缺失" : r.bodyComplete ? "完整" : half ? "半截（推定）" : "未带完成时间"} · ${r.agent} "${r.label}"`);
-                        const src = text && reply.via ? ` ·正文来源=${reply.via}` : "";
+                        // C labels the fallback in the lead's words: the body above came from the
+                        // host's own completion injection, not from the child's session context.
+                        const viaLabel = reply.via === "host-envelope" ? "宿主注入信封" : reply.via;
+                        const src = text && viaLabel ? ` ·正文来源=${viaLabel}` : "";
                         // 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:
@@ -1327,6 +1704,66 @@ export function buildDispatchTools(deps) {
             }
         },
     };
+    /** Settle the still-running HOST children of a session that just went idle — by ASKING the
+     *  host, not by assuming.  One `session.get` per child, three outcomes kept apart:
+     *   - `time.idle` present → settled, `settleSource="session-get"`, host `outcome` kept;
+     *   - answered WITHOUT idle → the child is still running: the row is left alone and the
+     *     attempt is counted (`settle_unchecked`), because a live child reported as settled is
+     *     the exact overstatement this tool was already fixed for;
+     *   - no seam / a throwing call → the old `parent-idle` presumption, printed as one.
+     *  `idle_settled` and `idle_presumed` are separate trajectory rows on purpose: tm_stats can
+     *  then show how often the host actually confirmed a finish. */
+    async function reconcileHostChildren(rows) {
+        for (const child of rows) {
+            if (child.state !== "running")
+                continue;
+            const st = await readHostSessionState(api, child.sessionID);
+            if (st.idleAt) {
+                child.state = "idle";
+                child.finishedAt = st.idleAt;
+                child.hostIdleAt = st.idleAt;
+                if (st.createdAt !== undefined)
+                    child.hostCreatedAt = st.createdAt;
+                child.settleSource = "session-get";
+                if (st.outcome)
+                    child.outcome = st.outcome;
+                log({
+                    step_id: "events",
+                    event: "idle_settled",
+                    source: "session-get",
+                    child: child.sessionID,
+                    agent: child.agent,
+                    ...(st.outcome ? { outcome: st.outcome } : {}),
+                    ms: st.idleAt - child.startedAt,
+                });
+                continue;
+            }
+            if (st.answered) {
+                log({
+                    step_id: "events",
+                    event: "settle_unchecked",
+                    source: "session-get",
+                    reason: "still-running",
+                    child: child.sessionID,
+                    agent: child.agent,
+                });
+                continue;
+            }
+            presumeParentIdle([child]);
+        }
+    }
+    /** The FALLBACK: a still-running host child of a session that just went idle, on a host we
+     *  could not ask.  Recorded as `parent-idle` and printed as a presumption — never 完成. */
+    function presumeParentIdle(rows) {
+        for (const child of rows) {
+            if (child.state !== "running")
+                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 });
+        }
+    }
     const observeEvent = (event) => {
         const rawType = String(event?.type ?? "");
         if (!rawType.startsWith("session."))
@@ -1349,21 +1786,22 @@ export function buildDispatchTools(deps) {
             return;
         const rec = children.get(sid);
         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.
+            // The parent's own idle is the only completion signal the host gives us for a HOST
+            // child — and it is not the strongest one available: `session.get({sessionID})` answers
+            // the child's own `time.idle` (verified on 2.1.4), so we ASK first and only fall back to
+            // the inference when the host cannot be asked.  A row that stayed 运行中 forever would be
+            // an overstatement in reverse; a row presumed settled when the host says it is still
+            // executing is the overstatement this tool exists to refuse.
             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 });
+                const pending = [...children.values()].filter((child) => child.via === "host-injection" && child.state === "running" && child.parentSessionID === sid);
+                if (pending.length) {
+                    // No seam at all → the fallback needs no round-trip, so it lands HERE and the
+                    // synchronous hook stays synchronously readable.  A seam that EXISTS is asked, and
+                    // that read is tracked so tm_join drains it before reporting.
+                    if (!api || typeof api.get !== "function")
+                        presumeParentIdle(pending);
+                    else
+                        trackSettle(reconcileHostChildren(pending));
                 }
             }
             return;