@te-river/opencode-team-mode 1.8.5 → 1.8.7

package/dist/tm/dispatch.js

@@ -112,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
@@ -314,6 +342,177 @@ export function hostEnvelopeBody(messages, sessionID) {
     }
     return null;
 }
+const HISTORY_ACK_RE = /The subagent is working in the background \(sessionID: (ses_[A-Za-z0-9]+)\)/gi;
+const SESSION_ID_RE = /^ses_[A-Za-z0-9]+$/;
+const SHELL_ID_RE = /^sh_[A-Za-z0-9]+$/;
+/**
+ * The text bodies a transcript carries, for the HISTORY scanners only.
+ *
+ * Deliberately wider than `transcriptTexts` above, which keeps the body-collection policy
+ * (`type:"text"`): a background dispatch's ACK reaches the parent as a TOOL RESULT part, and
+ * the v2 seam hands tool parts through untouched (`normaliseContextMessages` moves
+ * `content[]` to `parts[]` and keeps their kind).  Reading only `type:"text"` would make
+ * this whole recovery path structurally dead — the exact shape of the task-offload bug,
+ * where a matcher that never fired was mistaken for "nothing to match".  `textsOf` in
+ * `src/host/v2-subagent.ts` reads `{text}` off every part for the same reason.
+ */
+function historyTexts(messages) {
+    const list = Array.isArray(messages) ? messages : [];
+    const out = [];
+    for (const entry of list) {
+        const e = entry;
+        if (typeof e?.text === "string" && e.text.trim())
+            out.push(e.text);
+        if (!Array.isArray(e?.parts))
+            continue;
+        const joined = e.parts
+            .map((p) => {
+            const t = p?.text;
+            return typeof t === "string" ? t : "";
+        })
+            .filter((s) => s.trim())
+            .join("\n");
+        if (joined.trim())
+            out.push(joined);
+    }
+    return out;
+}
+/** End index of the tag that starts at `from`, honouring quotes: a shell `command` may
+ *  contain `>` (a redirect), and cutting the tag there would lose the `state` after it. */
+function historyTagEnd(text, from) {
+    let quote = "";
+    for (let i = from; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = "";
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === ">")
+            return i;
+    }
+    return -1;
+}
+function historyTagAttr(tag, name) {
+    const m = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(tag);
+    return (m?.[1] ?? m?.[2] ?? "").trim();
+}
+/** A label for a candidate whose evidence carried none: the nearest line above the ACK (the
+ *  dispatch description usually rides there), else the line below it, else `"host child"`. */
+function historyLabelNear(text, index) {
+    const before = text
+        .slice(0, index)
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const after = text
+        .slice(index)
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const cand = before[before.length - 1] ?? after[1] ?? "";
+    return cand.replace(/^[-*·\s]+/, "").slice(0, 40) || "host child";
+}
+function historyStateOf(raw) {
+    const s = raw.toLowerCase();
+    if (s === "running" || s === "started" || s === "busy")
+        return "running";
+    if (s === "completed" || s === "succeeded" || s === "done")
+        return "completed";
+    return "error";
+}
+/** Sub-agent candidates named by a parent transcript, in transcript order (a later
+ *  envelope overwrites the earlier ACK for the same id — that is what "last one wins"
+ *  means for a child that was woken and re-ran). */
+export function childrenFromParentHistory(messages) {
+    const found = new Map();
+    for (const text of historyTexts(messages)) {
+        for (const m of text.matchAll(HISTORY_ACK_RE)) {
+            const sid = m[1];
+            const prior = found.get(sid);
+            // An envelope already read for this id carries a stronger state; an ACK after it is a
+            // re-dispatch, so it wins — both cases reduce to "the later evidence wins".
+            found.set(sid, { sessionID: sid, state: "running", label: prior?.label ?? historyLabelNear(text, m.index ?? 0) });
+        }
+        let from = 0;
+        for (;;) {
+            const open = text.indexOf("<subagent", from);
+            if (open < 0)
+                break;
+            if (!/\s/.test(text[open + "<subagent".length] ?? "")) {
+                from = open + 9;
+                continue;
+            }
+            const gt = historyTagEnd(text, open);
+            if (gt < 0)
+                break;
+            const tag = text.slice(open, gt + 1);
+            const sid = historyTagAttr(tag, "sessionID");
+            const stateRaw = historyTagAttr(tag, "state");
+            const close = text.indexOf("</subagent>", gt + 1);
+            if (SESSION_ID_RE.test(sid) && stateRaw) {
+                const state = historyStateOf(stateRaw);
+                const body = close >= 0 && state === "completed" ? text.slice(gt + 1, close).trim() : "";
+                const described = historyTagAttr(tag, "description").slice(0, 40);
+                found.set(sid, {
+                    sessionID: sid,
+                    state,
+                    ...(body ? { body } : {}),
+                    label: described || found.get(sid)?.label || "host child",
+                });
+            }
+            from = close >= 0 ? close + "</subagent>".length : gt + 1;
+        }
+    }
+    return [...found.values()];
+}
+/** Background shells the host announced in a parent transcript, last state per id. */
+export function backgroundShellsFromParentHistory(messages) {
+    const found = new Map();
+    for (const text of historyTexts(messages)) {
+        let from = 0;
+        for (;;) {
+            const open = text.indexOf("<shell", from);
+            if (open < 0)
+                break;
+            if (!/\s/.test(text[open + "<shell".length] ?? "")) {
+                from = open + 6;
+                continue;
+            }
+            const gt = historyTagEnd(text, open);
+            if (gt < 0)
+                break;
+            const tag = text.slice(open, gt + 1);
+            const id = historyTagAttr(tag, "id");
+            if (SHELL_ID_RE.test(id)) {
+                const state = (historyTagAttr(tag, "state") || "running").toLowerCase();
+                const command = historyTagAttr(tag, "command");
+                found.set(id, { id, state, ...(command ? { command: command.slice(0, 80) } : {}) });
+            }
+            from = gt + 1;
+        }
+    }
+    return [...found.values()];
+}
+/** The `后台 shell` section tm_join appends.  A running shell is named as RUNNING and told
+ *  not to be re-dispatched: the user can see those processes, and a lead that cannot see
+ *  them dispatches the same work twice.  Nothing is killed here — the host owns the shell. */
+export function renderBackgroundShells(shells) {
+    if (!shells.length)
+        return null;
+    const verdict = (s) => s.state === "running" ? "运行中" : s.state === "completed" ? "已完成" : `失败(${s.state})`;
+    const parts = shells.map((s) => `${s.id} ${verdict(s)}${s.command ? ` · ${shorten(s.command, 60)}` : ""}`);
+    const running = shells.filter((s) => s.state === "running");
+    const lines = [`后台 shell：${shells.length} 个（${parts.join(" / ")}）`];
+    if (running.length) {
+        lines.push(`⏳ ${running.map((s) => s.id).join("、")} 还在跑 —— 别重复派同类活（宿主的 shell 自己收输出，这里只报告，不 kill）。`);
+    }
+    return lines.join("\n");
+}
 /**
  * Turn whatever the host puts in an error slot into ONE readable line.
  *
@@ -365,10 +564,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}` : "";
@@ -378,6 +594,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;
@@ -528,6 +776,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" ? "未插话" : "无插话缝";
 }
@@ -688,6 +981,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
@@ -820,7 +1122,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;
@@ -860,6 +1162,118 @@ export function buildDispatchTools(deps) {
         }
         return { adopted, looked: true, why: adopted ? "" : "会话树里没有被认领标题的子会话" };
     }
+    /** Read the CALLING session's own transcript.  On a host with no `session.children`
+     *  (2.1.4) this is the only recovery source left, and it is also where the host announces
+     *  its background shells.  Never throws: a failure is a reported `why`, because
+     *  "we could not look" and "there was nothing" must not print the same. */
+    async function readParentMessages(parent, directory) {
+        if (!parent)
+            return { ok: false, why: "调用方会话 id 缺失，读不到父会话历史" };
+        if (typeof api?.messages !== "function") {
+            return { ok: false, why: "这个宿主客户端没有给出读取会话正文的缝（v2 上是 ctx.session.context），父会话历史读不到" };
+        }
+        try {
+            const un = unwrapClientResult(await api.messages({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
+            if (!un.ok)
+                return { ok: false, why: `读取父会话历史失败：${shorten(un.message ?? "", 90)}` };
+            return { ok: true, data: un.data, why: "" };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                why: `读取父会话历史失败：${describeHostError(err?.message ?? err, 90)}`,
+            };
+        }
+    }
+    /**
+     * Adopt the children the PARENT TRANSCRIPT still names — the second recovery path, for a
+     * host whose `session.children` does not exist.  Measured live (2.1.4 + 1.8.6): a service
+     * restart empties this in-process registry, `session.children` is gone, so tm_join
+     * answered `没有待收集的派发` while the user could still see the sub-agents running — and
+     * the lead re-dispatched work that was already in flight.
+     *
+     * The transcript is not trusted as ownership: every candidate is verified through the
+     * host's own `session.get` (`parentID === the caller`) before a row is opened, because an
+     * envelope names a session, it does not prove the session is OURS.  A candidate the host
+     * will not confirm is counted as skipped and never shown as a child.
+     *
+     * The row's state comes from the evidence: `state="completed"` envelope → settled
+     * (`settleSource="injection"`, the host's own injection is the evidence);
+     * `state="error"` → failed; an ACK or `state="running"` → running, and the host's own
+     * `time.idle` is still asked for (it is the only source carrying the `outcome` word).
+     */
+    async function adoptFromParentHistory(parent, parentMessages, directory, only) {
+        const candidates = childrenFromParentHistory(parentMessages);
+        let adopted = 0;
+        let skipped = 0;
+        for (const cand of candidates) {
+            const sid = cand.sessionID;
+            if (!sid || sid === parent || children.has(sid) || (only && !only.has(sid))) {
+                skipped++;
+                continue;
+            }
+            const gate = await parentageOf(sid, parent, directory);
+            if (!gate.ok) {
+                skipped++;
+                log({ step_id: "join", event: "adopt_history_refused", child: sid, reason: "parentage" });
+                continue;
+            }
+            const hostAgent = gate.agent.trim().toLowerCase();
+            // T3: this registry never carries a lead, whatever a stale transcript says.
+            const agent = hostAgent && !sameAgent(hostAgent, leadAgent) ? hostAgent : "subagent";
+            const startedAt = now();
+            const rec = {
+                sessionID: sid,
+                agent,
+                label: cand.label || "host child",
+                parentSessionID: parent,
+                startedAt,
+                state: "running",
+                via: "host-injection",
+            };
+            if (cand.state === "completed") {
+                rec.state = "idle";
+                rec.finishedAt = startedAt;
+                rec.settleSource = "injection";
+            }
+            else if (cand.state === "error") {
+                rec.state = "error";
+                rec.finishedAt = startedAt;
+                rec.error = "宿主注入信封报告 state=error（正文随注入消息送达）";
+            }
+            else {
+                // Still running, as far as the transcript knows — but the host's own record is a
+                // better witness and it also carries `outcome`, which no envelope does.
+                const st = await readHostSessionState(api, sid);
+                if (st.idleAt) {
+                    rec.state = "idle";
+                    rec.finishedAt = st.idleAt;
+                    rec.hostIdleAt = st.idleAt;
+                    if (st.createdAt !== undefined)
+                        rec.hostCreatedAt = st.createdAt;
+                    rec.settleSource = "session-get";
+                    if (st.outcome)
+                        rec.outcome = st.outcome;
+                }
+                else if (st.createdAt !== undefined) {
+                    rec.hostCreatedAt = st.createdAt;
+                }
+            }
+            children.set(sid, rec);
+            deps.onChildSession?.(sid, agent);
+            adopted++;
+            log({ step_id: "join", event: "adopt", child: sid, agent, state: cand.state, source: "parent-history" });
+        }
+        // One summary row per call: the counters are what makes "I looked and there was
+        // nothing" distinguishable from "I never looked" in the trajectory.
+        log({ step_id: "join", event: "adopt_history", candidates: candidates.length, adopted, skipped, source: "parent-history" });
+        const why = !candidates.length
+            ? "父会话历史里没有子代理派发记录（既没有后台 ack，也没有 <subagent> 信封；历史若被压缩过，这条也不算数）"
+            : adopted
+                ? ""
+                : `父会话历史里 ${candidates.length} 个候选都没能认领（${skipped} 个已登记或宿主未确认归属）`;
+        return { adopted, looked: true, candidates: candidates.length, skipped, why };
+    }
     /** Claim ONE explicitly named child of the calling session — the host's own
      *  `task` child included, which `adoptFromHost` must never pick up on its
      *  own.  The lock is the host's parentage (`parentID === the caller`), read
@@ -953,8 +1367,9 @@ export function buildDispatchTools(deps) {
 - 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.  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.  已受理 is the whole claim: it is NOT proof the child read it, and the reply never says 已送达.  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.
+- 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 on a host with no \`session.children\` the children your own transcript still names — the background ACK \`(sessionID: ses_…)\` and the \`<subagent sessionID="…" state="…">\` envelope — are claimed after the host confirms their parentage.  One that answered while nobody was listening is reported 已完成, not lost.
+- Background SHELLS the host announced in this session are reported at the end of every reply (\`后台 shell：N 个\`), with the running ones named as still running.  Nothing is killed by this tool: re-run a shell only if a completed one failed, and never dispatch the same work again while one is still running.
 - 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)" },
@@ -999,7 +1414,20 @@ 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;
+                // Read the CALLER's own transcript ONCE per call: it is the floor recovery source
+                // when the host has no `session.children`, and the only place a background shell is
+                // ever announced.  In-process on v2 (`ctx.session.context`), one hop on v1.
+                const parentHistory = await readParentMessages(parent, directory);
+                // Shells are REPORTED, never claimed: they are the host's processes, and this tool
+                // only exists to keep the lead from re-dispatching what is already running.
+                const shellSection = parentHistory.ok
+                    ? renderBackgroundShells(backgroundShellsFromParentHistory(parentHistory.data))
+                    : null;
                 const idList = parseIdList(args.ids);
                 const idFilter = idList && idList.length ? new Set(idList) : null;
                 const owned = () => [...children.values()].filter((r) => (!parent || r.parentSessionID === parent) && (!idFilter || idFilter.has(r.sessionID)));
@@ -1018,6 +1446,24 @@ export function buildDispatchTools(deps) {
                     adoption = await adoptFromHost(parent, directory, idFilter);
                     if (adoption.adopted)
                         mine = owned();
+                    // Second recovery source, for the host that has no `session.children` at all
+                    // (measured 2.1.4): the parent transcript still names its children.  Only asked
+                    // when the tree walk did not settle the question — never instead of it.
+                    if (mine.length < (idFilter ? idFilter.size : 1)) {
+                        const hist = parentHistory.ok
+                            ? await adoptFromParentHistory(parent, parentHistory.data, directory, idFilter)
+                            : { adopted: 0, looked: false, candidates: 0, skipped: 0, why: parentHistory.why };
+                        if (hist.adopted)
+                            mine = owned();
+                        // The `why` has to keep the three states apart: a children API that looked, no
+                        // children API but the history claimed something, and neither source yielding a
+                        // child.  Fusing them is the overstatement this path was built to stop.
+                        adoption = {
+                            adopted: adoption.adopted + hist.adopted,
+                            looked: adoption.looked,
+                            why: [adoption.why, hist.why].filter(Boolean).join("；"),
+                        };
+                    }
                     // 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
                     // how the lead reads back a result we replaced with a pointer — the
@@ -1140,6 +1586,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",
@@ -1150,6 +1610,7 @@ export function buildDispatchTools(deps) {
                             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,
@@ -1160,7 +1621,10 @@ export function buildDispatchTools(deps) {
                         const wake = outcome === "steered" && wakeRequested && row && row.state !== "running"
                             ? `\n已按 wake:true 唤醒：它当时不是运行中（${row.state === "error" ? "失败" : "已结算"}），宿主把这条插话当成新的执行输入——它会和新派发的 worker 并发，留意这一点。`
                             : "";
-                        return toToolResult(`插话目标：${rowLine}\n插话结果：${steerVerdictLine(outcome, { inboxID, note, seam })}\n插话计数：${steerOutcomeParts(tally).join(" · ")}${wake}`);
+                        const deliveryLine = verified
+                            ? `\n投递核对：${steerDeliveryLine(verified.verdict, inboxID, verified.note)}`
+                            : "";
+                        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") {
@@ -1223,18 +1687,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
                             ? ""
@@ -1245,7 +1720,11 @@ export function buildDispatchTools(deps) {
                         // the transcript, and the honest reason is that a synchronous host
                         // task never enters this registry at all.
                         `如果你用的是同步 \`task\`：宿主自己就把结果收回来了，它从不登记在这里，这不是派发失败。` +
-                        `只有后台 \`task {background:true}\`（或显式带 ids）需要 tm_join 来取。`);
+                        `只有后台 \`task {background:true}\`（或显式带 ids）需要 tm_join 来取。` +
+                        // A round with no collectable CHILD is still not an empty round when the host
+                        // has shell commands in flight: the user can see them and the lead cannot, so
+                        // silence here is what produced a duplicate dispatch.
+                        (shellSection ? `\n\n${shellSection}` : ""));
                 }
                 await settleAdopted(mine, directory);
                 const waitMs = Math.max(0, Math.min(maxWaitMs, Number(args.waitMs) || 0));
@@ -1362,8 +1841,10 @@ export function buildDispatchTools(deps) {
                     });
                 }
                 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
@@ -1525,7 +2006,7 @@ export function buildDispatchTools(deps) {
                 // when bodies were actually read (`includeText:false` has no body to judge).
                 if (bodyStatus.length)
                     header.splice(childRowsEnd, 0, ...bodyStatus);
-                const body = [...header, ...(blocks.length ? ["", blocks.join("\n")] : [])].join("\n");
+                const body = [...header, ...(blocks.length ? ["", blocks.join("\n")] : []), ...(shellSection ? ["", shellSection] : [])].join("\n");
                 const stepId = deps.pipelines.nextStepId();
                 return toToolResult(await deps.pipelines.govern(stepId, tool, body, {
                     contentType: detectContentType(body),
@@ -1538,6 +2019,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."))
@@ -1560,21 +2101,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;