@te-river/opencode-team-mode 1.5.15 → 1.6.1

package/dist/tm/dispatch.js

@@ -1,38 +1,61 @@
 /**
- * tm_dispatch / tm_join — ASYNC sub-agent dispatch (issue #7 of 2026-09-18).
+ * tm_join — the COLLECT side of sub-agent work (issue #7 of 2026-09-18; the
+ * dispatch side was removed in 1.5.16).
  *
- * Why this exists: the host's built-in `task` tool blocks the CALLING
- * session until the child agent returns, so "the team runs in parallel" was
- * only half true — the lead stood still for the sum of every dispatch, and
- * each child's full reply landed in the lead's context whether it needed it
- * there or not.  OpenCode hands plugins its own client (`input.client`), and
- * the official session API has `create` + `promptAsync` — "start if needed
- * and return IMMEDIATELY" — so a plugin-owned dispatcher gets real overlap
- * without touching a line of host code.  If a future host ever removes that
- * surface, both tools degrade with an explicit instruction to fall back to
- * `task`, rather than failing the round.
+ * What is gone and why: this module used to own a plugin-side dispatcher,
+ * `tm_dispatch`, which bought the lead real overlap by creating child sessions
+ * through `client.session.create` + `promptAsync`.  It was removed on the
+ * user's instruction, because a child a plugin creates is a session the user
+ * can neither open from the tool card nor stop from the interface — the host
+ * renders only its own built-in tools, and only its own `task` card links to a
+ * live child session.  "The lead can `cancel:true` it" is not the same thing as
+ * the user being able to.  Delegation therefore goes back to the host's `task`
+ * (and `task { background: true }`, which the installers switch on), and what
+ * stays here is the half that is still ours to do: observing and collecting
+ * children, which is also how the lead reads back a reply that
+ * `src/task-offload.ts` replaced with a pointer.
  *
  * Contract kept from T3 (no sub-agent spawns a sub-agent):
- *   - `tm_dispatch` executes ONLY for the team lead (ctx.agent check here,
- *     plus an explicit deny for the five specialists in agents.ts — the
- *     tm_* wildcard would otherwise hand it to everyone);
- *   - children are the five named specialists, never "team";
- *   - the child session is parented to the lead session (parentID), so the
- *     host's own session tree, cancellation and UI still make sense.
+ *   - `tm_join` executes ONLY for the team lead (ctx.agent check here, plus an
+ *     explicit deny for the five specialists in agents.ts — the tm_* wildcard
+ *     would otherwise hand it to everyone);
+ *   - the children it knows about are the five named specialists, never "team";
+ *   - everything it touches is parented to the calling session (parentID), and
+ *     parentage is READ BACK from the host before an id is claimed — this module
+ *     never assumes a session belongs to the caller.
  *
  * Context economy (design goal #4): tm_join renders each child's reply
- * through the SAME governance pipeline as every other tm_* tool, so five
- * long sub-agent reports become five handles + 80-token previews that the
- * lead can page through with tm_fetch — not 5×N kilotokens dumped inline.
+ * through the SAME governance pipeline as every other tm_* tool, so a long
+ * sub-agent report arrives as a handle + an 80-token preview the lead can page
+ * through with tm_fetch — not kilotokens dumped inline.
  */
 import { tmError, toToolResult } from "./result.js";
 import { unwrapClientResult } from "./client-unwrap.js";
-import { askUserForTarget } from "./perm-ask.js";
 import { detectContentType } from "./preview.js";
 import { shorten } from "./config.js";
+import { ledgerGoalLine, openItems } from "./ledger.js";
 /** The five dispatchable specialists — "team" is deliberately NOT in the
  *  list: a lead spawning a lead is the nesting T3 closed. */
 export const DISPATCH_TARGETS = ["architect", "implementer", "reviewer", "tester", "researcher"];
+/** A child seen being dispatched by the host's own tool, turned into a registry row.
+ *  Null when the ids are unusable: a child whose id equals the caller's would make
+ *  tm_join wait on the session it is running in, and an anonymous child cannot be
+ *  settled by an event we match on session id. */
+export function hostChildRecord(child, now = () => Date.now()) {
+    const sessionID = String(child?.sessionID ?? "").trim();
+    const parentSessionID = String(child?.parentSessionID ?? "").trim();
+    if (!sessionID || !parentSessionID || sessionID === parentSessionID)
+        return null;
+    return {
+        sessionID,
+        agent: String(child.agent ?? "").trim().toLowerCase() || "subagent",
+        label: String(child.label ?? "").trim().slice(0, 40) || "宿主子代理",
+        parentSessionID,
+        startedAt: now(),
+        state: "running",
+        via: "host-injection",
+    };
+}
 export function openHostTodos(todos) {
     if (!Array.isArray(todos))
         return [];
@@ -47,36 +70,98 @@ export function openHostTodos(todos) {
     }
     return open;
 }
-/** Resolve the host session API defensively — a missing namespace means the
- *  host does not speak this protocol, and the caller must degrade. */
+/** #80: the line tm_join adds when a SETTLED child still owns a browser window.
+ *  Takes only the leases already filtered to settled children, so the ownership
+ *  rule stays where the child registry is; this function's whole job is to say
+ *  it in the one shape that survives the lead's skimming — and to refuse to say
+ *  it for a window that was never ours. */
+export function leaseTripwire(held, callerSessionID) {
+    if (!held.length)
+        return null;
+    const isMine = (l) => !!callerSessionID && l.owner === callerSessionID;
+    const mine = held.filter(isMine);
+    const theirs = held.filter((l) => !isMine(l));
+    const at = (l) => `空闲 ${Math.round(l.idleMs / 1000)}s`;
+    const parts = [];
+    if (theirs.length) {
+        parts.push(`⚠ ${theirs.length} 个浏览器还开着（子代理已结算，但它没 close）：` +
+            theirs.map((l) => `${l.id}（${l.agent || "未知角色"} · ${at(l)}）`).join("、") +
+            `\n要么让它 close 并引用工具自己的三种裁决之一（已确认关闭 / 进程未核验 / 警告：关闭未完全成功），` +
+            `要么由你向用户写明为什么留着。不要替它写"已关闭"——那是把没人核实过的结论交付出去。`);
+    }
+    // The caller's own window is the one the user is looking at, and the live
+    // recheck proved this branch was the missing one: a lead that keeps a browser
+    // across rounds is legitimate, so this is a reminder, not an accusation —
+    // but silence is the defect.
+    for (const l of mine) {
+        parts.push(`（你自己还占着 ${l.id}，${at(l)}。收尾前 action:"close" 并引用工具的裁决句；` +
+            `如果确实要跨轮留着，就在回复里向用户说明为什么。）`);
+    }
+    return parts.join("\n");
+}
+/** Resolve the host session API defensively — `messages` is what tm_join
+ *  cannot work without (the collected reply); a host without it means the
+ *  caller must degrade, and `create`/`promptAsync` are deliberately NOT part
+ *  of this contract any more: nothing here spawns sessions. */
 export function sessionApiOf(client) {
     const session = client?.session;
     if (!session || typeof session !== "object")
         return null;
     const api = session;
-    if (typeof api.create !== "function" || typeof api.promptAsync !== "function")
+    if (typeof api.messages !== "function")
         return null;
     return api;
 }
-/** The title `tm_dispatch` gives every child session.
+/** 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
+ *  card structurally cannot do.  Gated behind a runtime flag (verified in the
+ *  desktop binary): `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`, falling back
+ *  to the umbrella `OPENCODE_EXPERIMENTAL`.  We read the SAME env the host
+ *  reads — our plugin runs inside that process — so this is a fact, not a
+ *  guess. */
+export function hostBackgroundSubagentsEnabled(env = process.env) {
+    const truthy = (v) => {
+        const s = typeof v === "string" ? v.trim().toLowerCase() : "";
+        if (!s)
+            return null;
+        return s === "1" || s === "true" || s === "yes" || s === "on";
+    };
+    return truthy(env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS) ?? truthy(env.OPENCODE_EXPERIMENTAL) ?? false;
+}
+/** A wait budget spelled the way a human reads it (never "0s" for 300 ms). */
+function waitLabel(ms) {
+    return ms >= 1000 ? `${Math.round(ms / 1000)}s` : `${ms}ms`;
+}
+/** What a tm_join wait may actually cost.  The FIRST bounded wait gets the
+ *  requested budget (clamped to TM_JOIN_MAX_WAIT_MS); a wait that follows a
+ *  wait which settled nothing gets cut to REPEAT_WAIT_MS, because the second
+ *  one is the shape of a lead parking instead of working — measured live at
+ *  2 × 300 s of nothing while six children ran. */
+export const REPEAT_WAIT_MS = 10_000;
+export function joinBudget(waitMs, maxWaitMs, prev) {
+    const clamped = Math.max(0, Math.min(maxWaitMs, waitMs));
+    const repeat = !!prev && prev.stillRunning > 0 && clamped > 0;
+    const streak = clamped === 0 ? (prev?.streak ?? 0) : repeat ? (prev?.streak ?? 1) + 1 : 1;
+    return { budget: repeat ? Math.min(clamped, REPEAT_WAIT_MS) : clamped, repeat, streak };
+}
+/** Recognise the title a `tm_dispatch` child used to carry — the tool is no
+ *  longer registered (a plugin-spawned child is a session the user can neither
+ *  open from a card nor stop from the UI), but children created before the
+ *  change are still live in the host's session tree and tm_join must still
+ *  collect them.
  *
- *  The shape is the host's OWN subagent convention — the built-in task tool
+ *  The shape was the host's OWN subagent convention — the built-in task tool
  *  titles its children `${description} (@${agent} subagent)` (verified in the
- *  desktop binary), because that is what the renderer's `taskSession()`
- *  heuristic reads to colour a child row and to resolve it from a tool card.
- *  A plugin cannot register a tool renderer (the desktop's ToolRegistry holds
- *  exactly the built-in names), so matching the convention is the only way our
- *  children look like sub-agent sessions in the sidebar instead of a mystery
- *  row.  ` ·tm` is our own marker and it is LOAD-BEARING: it is what keeps a
- *  `task`-spawned child out of `parseDispatchTitle`, so tm_join never claims a
- *  reply that belongs to the host's dispatcher. */
-export function dispatchTitle(agent, label) {
-    return `${label} (@${agent} subagent${DISPATCH_TITLE_MARKER})`;
-}
-/** Suffix tm_dispatch appends inside the host's `(@<agent> subagent)` shape. */
-export const DISPATCH_TITLE_MARKER = " ·tm";
-/** The pre-1.5.15 title (`tm:<agent>:<label>`).  Still accepted on the way in
- *  so a child created before the upgrade is not orphaned by restart recovery. */
+ *  desktop binary), which is what the renderer's `taskSession()` heuristic
+ *  reads to colour a child row.  Ours added a ` ·tm` marker inside that shape,
+ *  and the marker is LOAD-BEARING in both directions: it is what tells a
+ *  leftover dispatch apart from a host `task` child, so an automatic tree walk
+ *  never claims a reply that belongs to the host's dispatcher.  The pre-1.5.15
+ *  shape (`tm:<agent>:<label>`) still parses for the same reason — a session
+ *  that exists must stay collectable.  A child named explicitly by id takes a
+ *  different path (`claimNamedChild`), where the lock is the host's own
+ *  parentage rather than the title. */
 export function parseDispatchTitle(title, targets) {
     const t = typeof title === "string" ? title.trim() : "";
     if (t.startsWith("tm:")) {
@@ -194,7 +279,11 @@ export function describeHostError(err, max = 220) {
 export function renderChildLine(c, elapsedMs) {
     const secs = Math.round(elapsedMs / 1000);
     const tag = c.state === "running" ? `运行中 ${secs}s` : c.state === "error" ? `失败：${shorten(c.error ?? "", 80)}` : `已完成 ${secs}s`;
-    return `${c.sessionID} · ${c.agent} · "${c.label}" · ${tag}${c.adopted ? " ·（本进程重启后由宿主会话树接管）" : ""}`;
+    return `${c.sessionID} · ${c.agent} · "${c.label}" · ${tag}${c.adopted ? " ·（本进程重启后由宿主会话树接管）" : ""}${c.via === "host-injection" && c.settleSource === "parent-idle"
+        ? " ·（宿主子代理：随父会话空闲推定已结算，宿主没给过这个子会话的 idle 事件）"
+        : c.via === "host-injection"
+            ? " ·（宿主 subagent 派发）"
+            : ""}`;
 }
 /** Verdicts tm_join can actually observe (issue #7's "leader keeps control"). */
 export function summarizeStates(children) {
@@ -249,14 +338,20 @@ export function parseIdList(raw) {
 export function buildDispatchTools(deps) {
     const leadAgent = deps.leadAgent ?? "team";
     const targets = deps.targets ?? DISPATCH_TARGETS;
-    const maxWaitMs = deps.maxWaitMs ?? 300_000;
-    const askBeforeSpawn = deps.askBeforeSpawn !== false;
-    const maxDepth = Math.max(0, Number.isFinite(deps.maxDepth) ? deps.maxDepth : 1);
-    const parallel = deps.parallelDispatch !== "off";
+    const maxWaitMs = deps.maxWaitMs ?? 60_000;
     const now = deps.now ?? (() => Date.now());
     const store = deps.pipelines.store;
+    // The trajectory label stays `tm_dispatch` after the tool's death on purpose:
+    // tm_stats reads it, and adopt/cancel/wait events from a 1.5.15 run must stay
+    // comparable with this one.  Renaming would split the history in two.
     const log = (e) => store.appendTrajectory({ tool: "tm_dispatch", ...e });
     const children = new Map();
+    /** 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
+     *  which settled nothing is the pattern a live session burned ten minutes
+     *  on.  It gets cut short and answered with what to do instead. */
+    const lastJoin = new Map();
     const api = sessionApiOf(deps.client);
     /** Refresh a child's state from the host's own status map (the event bus
      *  is the fast path; this is the belt when an event was missed — a child
@@ -295,48 +390,25 @@ export function buildDispatchTools(deps) {
     }
     function fetchReply(sid, directory) {
         return (async () => {
-            if (typeof api?.messages !== "function")
-                return { text: "" };
+            if (typeof api?.messages !== "function") {
+                return { text: "", error: "这个宿主客户端没有给出读取子会话正文的缝（v2 上它是 ctx.session.context 的兼容层）" };
+            }
             try {
-                const un = unwrapClientResult(await api.messages({ path: { id: sid }, ...(directory ? { query: { directory } } : {}) }));
-                return un.ok ? lastAssistantMessage(un.data) : { text: "" };
+                const raw = await api.messages({ path: { id: sid }, ...(directory ? { query: { directory } } : {}) });
+                const un = unwrapClientResult(raw);
+                const got = un.ok ? lastAssistantMessage(un.data) : { text: "", error: un.message };
+                // The seam that ANSWERED, named by the seam itself. On v1 that is the host's
+                // `session.messages`; on v2 the same call is served by `ctx.session.context`, and
+                // printing "session.messages" there would credit an endpoint this host does not
+                // have — the class of claim this product exists to refuse.
+                const via = String(raw?.via ?? "session.messages");
+                return got.text ? { ...got, via } : { text: "", error: got.error, via };
             }
-            catch {
-                return { text: "" };
+            catch (err) {
+                return { text: "", error: describeHostError(err?.message ?? err, 140) };
             }
         })();
     }
-    /**
-     * The model the CHILD should run.  A child session carries no model of its
-     * own, and `prompt_async` accepts `model:{providerID,modelID}` — the
-     * built-in `task` tool supplies one, we did not, and three dispatched
-     * children died at launch with no readable reply (2026-09-19).  Inherit the
-     * lead's own last-used model from the parent transcript; when nothing can
-     * be resolved, dispatch anyway and say so in the reply, so a failure is
-     * never mysterious.
-     */
-    async function parentModel(parent, directory) {
-        if (typeof api?.messages !== "function" || !parent)
-            return undefined;
-        try {
-            const un = unwrapClientResult(await api.messages({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
-            if (!un.ok || !Array.isArray(un.data))
-                return undefined;
-            for (let i = un.data.length - 1; i >= 0; i--) {
-                const info = un.data[i]?.info;
-                if (!info || String(info.role ?? "").toLowerCase() !== "assistant")
-                    continue;
-                const providerID = typeof info.providerID === "string" ? info.providerID.trim() : "";
-                const modelID = typeof info.modelID === "string" ? info.modelID.trim() : "";
-                if (providerID && modelID)
-                    return { providerID, modelID };
-            }
-        }
-        catch {
-            /* no transcript readable — dispatch without a model and report it */
-        }
-        return undefined;
-    }
     /**
      * Adopt the children the HOST lists under this parent but this process never
      * dispatched: the plugin instance restarted (or the lead resumed a session
@@ -345,22 +417,35 @@ export function buildDispatchTools(deps) {
      * tm_join's honest answer would be "没有待收集的派发" while a finished report
      * sits in the host, which is exactly the silent loss issue #7 was about.
      *
-     * The discriminator is the title tm_dispatch itself writes (`dispatchTitle`
-     * + a known agent), so a child spawned by the built-in `task` tool is never
-     * claimed as ours.
+     * The discriminator is the title shape our removed `tm_dispatch` used to
+     * write (a recognised agent + the ` ·tm` marker) or the pre-1.5.15
+     * `tm:<agent>:<label>`, so a child spawned by the built-in `task` tool is
+     * never claimed as ours on speculation — see `claimNamedChild` for the one
+     * path that may take a host child, and the parentage check it must pass.
      */
     async function adoptFromHost(parent, directory, only) {
-        if (typeof api?.children !== "function" || !parent)
-            return 0;
+        // Three outcomes used to collapse into `0`: the host surface is absent (v2's
+        // client shim has no `session` domain), the call failed, and "we asked and
+        // there was nothing".  The empty-round answer reads "宿主会话树里也没有可认领的
+        // 子会话", which is a claim about case three — asserted in cases one and two,
+        // where nobody looked.  A lead that believes it will stop waiting for a report
+        // that exists, which is the silent loss this function exists to prevent.
+        // The reason names the MISSING SEAM, not a host generation: the same absence
+        // occurs on a v1-shaped client that lacks `session.messages`, and a sentence
+        // blaming "v2" there would be false in the opposite direction.
+        if (typeof api?.children !== "function")
+            return { adopted: 0, looked: false, why: "这个宿主客户端没有给出 session.children（可辨认的 session API 缺失），我没有看过会话树" };
+        if (!parent)
+            return { adopted: 0, looked: false, why: "调用方会话 id 缺失，无从查询子会话" };
         let un;
         try {
             un = unwrapClientResult(await api.children({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
         }
-        catch {
-            return 0;
+        catch (err) {
+            return { adopted: 0, looked: false, why: `查询会话树失败：${describeHostError(err)}` };
         }
         if (!un.ok || !Array.isArray(un.data))
-            return 0;
+            return { adopted: 0, looked: false, why: "宿主返回了无法解析的会话树结果" };
         let adopted = 0;
         for (const raw of un.data) {
             const sid = String(raw?.id ?? "").trim();
@@ -387,7 +472,43 @@ export function buildDispatchTools(deps) {
             adopted++;
             log({ step_id: "join", event: "adopt", child: sid, agent: parsed.agent, label: rec.label });
         }
-        return adopted;
+        return { adopted, looked: true, why: adopted ? "" : "会话树里没有被认领标题的子会话" };
+    }
+    /** Claim ONE explicitly named child of the calling session — the host's own
+     *  `task` child included, which `adoptFromHost` must never pick up on its
+     *  own.  The lock is the host's parentage (`parentID === the caller`), read
+     *  back rather than assumed: an id belonging to someone else stays a miss. */
+    async function claimNamedChild(sid, parent, directory) {
+        if (typeof api?.get !== "function" || !sid || !parent || children.has(sid))
+            return false;
+        let un;
+        try {
+            un = unwrapClientResult(await api.get({ path: { id: sid }, ...(directory ? { query: { directory } } : {}) }));
+        }
+        catch {
+            return false;
+        }
+        if (!un.ok)
+            return false;
+        const info = un.data;
+        if (String(info?.parentID ?? "").trim() !== parent)
+            return false;
+        const rawAgent = String(info?.agent ?? "").trim().toLowerCase();
+        const agent = targets.includes(rawAgent) ? rawAgent : "task";
+        const title = String(info?.title ?? "").trim();
+        const created = Number(info?.time?.created);
+        children.set(sid, {
+            sessionID: sid,
+            agent,
+            label: (title || "host task").slice(0, 40),
+            parentSessionID: parent,
+            startedAt: Number.isFinite(created) && created > 0 ? created : now(),
+            state: "running",
+            adopted: true,
+        });
+        deps.onChildSession?.(sid, agent);
+        log({ step_id: "join", event: "claim_host_task", child: sid, agent });
+        return true;
     }
     /** Settle verdict for adopted rows: `AssistantMessage.time.completed` is
      *  only set once the reply is done, so it answers "finished while nobody
@@ -403,177 +524,16 @@ export function buildDispatchTools(deps) {
             }
         }
     }
-    /**
-     * How deep the caller's session sits: the host's task tool counts the
-     * parentID chain and refuses at `subagent_depth` (default 1 = no nested
-     * subagents). That check lives in the TOOL, not in the session API, so a
-     * plugin-side dispatcher that skipped it would quietly let a user's nesting
-     * limit be escaped. Walk it the same way; an unreachable session (no `get`
-     * endpoint, deleted) stops the walk at what we know rather than allowing.
-     */
-    async function sessionDepth(sessionID, directory) {
-        if (typeof api?.get !== "function" || !sessionID)
-            return 0;
-        let depth = 0;
-        let current = sessionID;
-        for (let hop = 0; hop < 16; hop++) {
-            try {
-                const un = unwrapClientResult(await api.get({ path: { id: current }, ...(directory ? { query: { directory } } : {}) }));
-                const parentID = un.ok ? String(un.data?.parentID ?? "").trim() : "";
-                if (!parentID)
-                    break;
-                depth++;
-                current = parentID;
-            }
-            catch {
-                break;
-            }
-        }
-        return depth;
-    }
-    const dispatch = {
-        description: `Fire-and-continue sub-agent dispatch — the lead's parallelism lever (the built-in task tool BLOCKS you until the child finishes; this one does not).
-- { agent: ${targets.join("|")} , task: "<self-contained brief>", description: "<short slug>" } → starts the specialist in its OWN child session (parented to yours) and returns the child session id IMMEDIATELY.  You keep working the same round: plan the next step, do a cheap read of your own, or fire more dispatches — independent work runs concurrently instead of serially.
-- The child is a real session: it appears under yours in the host's session tree (titled "<description> (@<agent> subagent ·tm)"), so the user can open it and watch it work.  Its tool card is NOT expandable — the host only renders bodies for its own built-in tools — so say out loud which child is running and what it is for.
-- The brief must stand alone: the child has not seen this conversation, does not know what you tried, and cannot ask you mid-run.  Say what to do, WHY it matters, which files/paths are its territory, what "done" looks like, and how much thoroughness you expect — the child still answers the mandatory STATUS/CHANGES/FINDINGS/EVIDENCE/HANDOFF skeleton.
-- Collect with tm_join (no wait = status snapshot, waitMs = bounded wait).  Collected replies ride the offload pipeline: a long report arrives as a handle + preview, not a context flood.
-- Division of labour: bulk reading / searching / aggregation burns the CHILD's context and comes back as a skeleton; your own context is the scarce resource — keep it for routing, decisions and the final merge.
-- Only the team lead may call this; a child never dispatches (no nested teams).  If the host exposes no async session API the call fails with an explicit "use the built-in task tool" directive.${parallel
-            ? ""
-            : `
-- TM_PARALLEL_DISPATCH=off is set: at most ONE child may run at a time, so a second dispatch while one is live is refused.  Dispatch, tm_join it, then dispatch the next — and tell the user why the team is serial.`}`,
-        args: {
-            agent: { descriptor: `agent: ${targets.join("|")} (required)` },
-            task: { descriptor: "task: string (required — the full self-contained brief the child works from)" },
-            description: {
-                descriptor: "description: string (optional ≤40-char slug — the child session's title and the line the UI shows for this call; defaults to the task's first words)",
-            },
-        },
-        execute: async (rawArgs, ctx) => {
-            const tool = "tm_dispatch";
-            try {
-                const args = (rawArgs ?? {});
-                const c = (ctx ?? {});
-                const caller = String(c.agent ?? "").trim();
-                if (caller && caller !== leadAgent) {
-                    return toToolResult(tmError(tool, "governance", `只有 ${leadAgent} 可以派发子代理（当前 agent="${shorten(caller, 24)}"）。T3 规则：子代理不再派子代理——把需要并行的工作交给 lead 编排。`));
-                }
-                const agent = String(args.agent ?? "").trim().toLowerCase();
-                if (!targets.includes(agent)) {
-                    return toToolResult(tmError(tool, "args", `未知派发目标 "${shorten(agent, 30)}"——可用: ${targets.join(", ")}`));
-                }
-                const task = typeof args.task === "string" ? args.task.trim() : "";
-                if (task.length < 20) {
-                    return toToolResult(tmError(tool, "args", "task 太短：子代理看不到本会话，派发说明必须自包含（目标、涉及文件、完成判据、期望深度）。"));
-                }
-                const parent = String(c.sessionID ?? "").trim();
-                if (!parent) {
-                    return toToolResult(tmError(tool, "client", "缺少 sessionID（宿主未把会话上下文传给插件），无法建立父子会话。"));
-                }
-                if (!api) {
-                    return toToolResult(tmError(tool, "client", `此宿主未暴露异步会话 API（client.session.create/promptAsync），tm_dispatch 不可用——改用内置 task 工具（会阻塞你，但功能等价）。`));
-                }
-                // `description` is the host's own name for this field (the task tool
-                // takes prompt + description), and the desktop reads exactly that key
-                // as a tool card's subtitle — so the dispatch shows as
-                // "Called tm_dispatch · 修登录页" instead of a raw-JSON chip.
-                const label = (typeof args.description === "string" && args.description.trim()
-                    ? args.description.trim()
-                    : task.split(/\s+/).slice(0, 4).join(" ")).slice(0, 40);
-                const directory = typeof c.directory === "string" && c.directory ? c.directory : undefined;
-                // --- governance the built-in task tool applies and we must not lose -
-                // (1) nesting ceiling, same 口径 as the host's subagent_depth
-                const depth = await sessionDepth(parent, directory);
-                if (depth >= maxDepth) {
-                    return toToolResult(tmError(tool, "governance", `已达子代理嵌套上限（当前深度 ${depth}，TM_SUBAGENT_DEPTH=${maxDepth}，与宿主 subagent_depth 同口径）。` +
-                        `这与 T3「子代理不再派子代理」同源：把这项工作留在你自己这一层，或让宿主配置放宽。`));
-                }
-                // (1b) TM_PARALLEL_DISPATCH=off — one child at a time.  Refused BEFORE
-                // the dialog (same ordering as tm_pty's concurrency cap): never ask the
-                // user to approve a spawn the policy has already declined.
-                if (!parallel) {
-                    const live = [...children.values()].filter((r) => r.state === "running" && r.parentSessionID === parent);
-                    if (live.length) {
-                        const who = live.map((r) => `${r.agent}「${r.label}」`).slice(0, 4).join("、");
-                        log({ step_id: "dispatch", event: "serial_refused", agent, label, live: live.length });
-                        return toToolResult(tmError(tool, "governance", `TM_PARALLEL_DISPATCH=off：一次只跑一个子代理，而你这轮已有 ${live.length} 个在跑（${who}）。` +
-                            `先 tm_join 收掉再派 ${agent}。注意：并行才是 Team 的意义——串行是你选的模式，` +
-                            `要恢复默认值就删掉 TM_PARALLEL_DISPATCH 或设为 on。`));
-                    }
-                }
-                // (2) the user decides which sub-agent gets spawned — the task tool
-                // asks ctx.ask({permission:"task", patterns:[subagent_type]}) and we
-                // bypass that tool, so we ask on our own permission name. No bridge ⇒
-                // refuse (never a silent pass), same rule as tm_pty / evaluate_script.
-                if (askBeforeSpawn) {
-                    const outcome = await askUserForTarget(ctx, {
-                        permission: tool,
-                        patterns: [agent],
-                        metadata: { tool, subagent_type: agent, description: label },
-                    });
-                    log({ step_id: "dispatch", event: "consent", agent, label, verdict: outcome });
-                    if (outcome !== "approved") {
-                        return toToolResult(tmError(tool, "permission", outcome === "unavailable"
-                            ? `tm_dispatch 需要官方确认窗批准派工，本宿主没有 ask 桥——已拒绝。改用内置 task 工具（会阻塞你，但由宿主治理），或 TM_DISPATCH_ASK=off。`
-                            : `派工未获批准（${agent}），已拒绝创建子会话。请改用内置 task 工具，或向用户确认后再派。`));
-                    }
-                }
-                if (typeof api?.create !== "function" || typeof api?.promptAsync !== "function") {
-                    return toToolResult(tmError(tool, "client", "此宿主的 client.session 缺少 create/promptAsync——改用内置 task 工具。"));
-                }
-                // PROPERTY-ACCESS CALLS (api.create / api.promptAsync), never a
-                // captured function reference — see refreshFromStatus above.
-                const created = unwrapClientResult(await api.create({ body: { parentID: parent, title: dispatchTitle(agent, label) } }));
-                if (!created.ok)
-                    return toToolResult(tmError(tool, "client", `创建子会话失败：${shorten(created.message ?? "", 120)}`));
-                const sid = String(created.data?.id ?? "").trim();
-                if (!sid)
-                    return toToolResult(tmError(tool, "client", "子会话创建后未返回 id"));
-                const model = await parentModel(parent, directory);
-                const promptBody = {
-                    agent,
-                    noReply: false,
-                    ...(model ? { model } : {}),
-                    parts: [{ type: "text", text: task }],
-                };
-                const sent = unwrapClientResult(await api.promptAsync({ path: { id: sid }, ...(directory ? { query: { directory } } : {}), body: promptBody }));
-                if (!sent.ok) {
-                    return toToolResult(tmError(tool, "client", `子会话 ${sid} 已创建但提示未能启动：${shorten(sent.message ?? "", 120)}——可对该 id 直接用内置 task，或本次改用 task 工具。`));
-                }
-                const rec = { sessionID: sid, agent, label, parentSessionID: parent, startedAt: now(), state: "running" };
-                children.set(sid, rec);
-                deps.onChildSession?.(sid, agent);
-                log({ step_id: "dispatch", event: "start", child: sid, parent: parent, agent, label, model: model ? `${model.providerID}/${model.modelID}` : "host-default" });
-                // The child's tool card is a one-liner the user cannot open (a plugin
-                // cannot register a renderer), so the toast is the only thing that
-                // points at the live session — without it a dispatch just looks like a
-                // stalled tool call.
-                deps.notify?.(`子代理已启动：${agent}「${label}」— 在左侧会话树里展开本会话即可实时查看（子会话 ${sid}）`);
-                return toToolResult([
-                    `已派发（非阻塞）：${agent} · "${label}" · 子会话 ${sid}`,
-                    model
-                        ? `模型沿用你当前的：${model.providerID}/${model.modelID}（子会话不自带模型）。`
-                        : `⚠ 未能从本会话记录里解析出模型，子会话将由宿主决定——若它启动即失败，改用内置 task 工具。`,
-                    `你现在可以继续：编排下一步、做廉价检查、或继续派发其它独立任务。`,
-                    `收集结果：tm_join（立即看状态）或 tm_join { waitMs: 60000 }。所有派发完成前不要提交结论。`,
-                ].join("\n"));
-            }
-            catch (err) {
-                const e = err;
-                return toToolResult(tmError(tool, "execute", `tm_dispatch 失败：${describeHostError(e?.message ?? err, 160)}`));
-            }
-        },
-    };
     const join = {
-        description: `Collect what the async dispatches (tm_dispatch) have produced.
+        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 ${Math.round(maxWaitMs / 1000)}s) until every child settles, then returns each one's reply skeleton.  Never wait for a child whose result you do not need — abort it instead ({ cancel: true }).
-- { ids: [...] }: restrict to those child sessions; { cancel: true }: abort still-running ones (a runaway child is yours to stop, not the user's problem).
-- A plugin/host restart does NOT orphan a dispatch: children 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 five parallel dispatches do not multiply your context.  STATUS: blocked/failed children are surfaced first, always.`,
+- { waitMs: 30000 }: bounded wait (capped at ${waitLabel(maxWaitMs)}) until every child settles.  A wait BLOCKS YOU — your turn is parked in this tool call, so it is the synchronous \`task\` experience with none of its visibility.  Wait once, briefly, and only when the very next step needs the answer; a second consecutive wait after nothing settled is cut to 10s and answered with what to do instead.  Never wait for a child whose result you do not need — abort it instead ({ cancel: true }).
+- { ids: [...] }: restrict to those child sessions — a host \`task\` child is collectable when you NAME it (its parentage is verified against the host's own session tree, never assumed); { cancel: true }: abort still-running ones.
+- A plugin/host restart does NOT orphan a child: those the host still lists under your session are re-adopted automatically (their rows are marked 接管), and one that answered while nobody was listening is reported 已完成, not lost.
+- Replies come back through the offload pipeline: a long sub-agent report arrives as a handle + ≤80-token preview (page it with tm_fetch), so a batch of parallel work does not multiply your context.  STATUS: blocked/failed children are surfaced first, always.`,
         args: {
             ids: { descriptor: "ids: string[] (optional — only these child sessions)" },
-            waitMs: { descriptor: "waitMs: number (optional 0..300000 — bounded wait before collecting)" },
+            waitMs: { descriptor: `waitMs: number (optional 0..${maxWaitMs} — bounded wait; a SECOND consecutive wait is cut to 10s, because waiting is not parallel work)` },
             cancel: { descriptor: "cancel: true (abort the still-running children in this set)" },
             includeText: { descriptor: "includeText: false to get only the status table (default true)" },
         },
@@ -587,23 +547,110 @@ export function buildDispatchTools(deps) {
                     return toToolResult(tmError(tool, "governance", `只有 ${leadAgent} 能收集派发结果。`));
                 }
                 const parent = String(c.sessionID ?? "").trim();
+                // tm_stats counts calls from `event:"call"`, and tm_join only ever
+                // 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" });
                 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;
                 const owned = () => [...children.values()].filter((r) => (!parent || r.parentSessionID === parent) && (!idFilter || idFilter.has(r.sessionID)));
                 let mine = owned();
+                // Whether we got to LOOK at the host's tree, and what it said — the empty
+                // answer must not claim "there is nothing to adopt" on a host we cannot
+                // query, so the fact travels with the attempt rather than being inferred.
+                let adoption = {
+                    adopted: 0,
+                    looked: false,
+                    why: "本进程已经认全了要收的子代理，没有去查会话树",
+                };
                 // This process has never seen some (or all) of what the lead is asking
                 // for — the host's session tree, not our memory, is the authority.
                 if (mine.length < (idFilter ? idFilter.size : 1)) {
-                    if (await adoptFromHost(parent, directory, idFilter))
+                    adoption = await adoptFromHost(parent, directory, idFilter);
+                    if (adoption.adopted)
                         mine = owned();
+                    // Plan B: a NAMED id may be the host's own `task` child (no ·tm
+                    // marker, so the tree walk above never claims it).  Collecting it is
+                    // how the lead reads back a result we replaced with a pointer — the
+                    // host's parentage check below replaces the title discriminator, and
+                    // only an explicit request reaches this path.
+                    if (idFilter) {
+                        for (const sid of idFilter) {
+                            if (children.has(sid))
+                                continue;
+                            if (await claimNamedChild(sid, parent, directory))
+                                mine = owned();
+                        }
+                    }
                 }
+                // #87: computed BEFORE any early return.  The live regression of #86 was
+                // a lead holding a browser while tm_join answered "nothing to collect" —
+                // a SYNCHRONOUS host task never registers in this table (the host
+                // collects it inline), so the header assembly below never ran, and the
+                // window the user was looking at went unreported again.  A forgotten
+                // browser has to surface on EVERY answer this tool gives.
+                const leaseLine = () => {
+                    if (typeof deps.browserLeases !== "function")
+                        return "";
+                    let held = [];
+                    try {
+                        const done = new Set(mine.filter((r) => r.state !== "running").map((r) => r.sessionID));
+                        held = deps.browserLeases().filter((l) => done.has(l.owner) || l.owner === parent);
+                    }
+                    catch {
+                        /* the lease table is an extra, never a reason to fail a join */
+                        return "";
+                    }
+                    const line = leaseTripwire(held, parent) ?? "";
+                    if (line) {
+                        log({
+                            step_id: "join",
+                            event: "lease_held",
+                            count: held.length,
+                            ids: held.map((l) => l.id).join(","),
+                        });
+                    }
+                    return line;
+                };
                 if (!mine.length) {
-                    return toToolResult(`没有待收集的派发${idFilter ? "（ids 未匹配到本会话的子代理，宿主会话树里也没有 tm: 标题的子会话）" : ""}。刚派发过却看不到？说明那次派发没成功——回到 tm_dispatch 的返回值检查。`);
+                    const lease = leaseLine();
+                    // The parenthetical is now chosen by whether we actually looked, so a
+                    // host we cannot query no longer reports as "confirmed: nothing there".
+                    const saw = adoption.looked;
+                    const inner = idFilter
+                        ? (() => {
+                            // Naming the shapes the v2 session bridge tried is the whole point:
+                            // without it, a claim that failed because `ctx.session.get` answered
+                            // in a shape we do not know prints the same sentence as a tree we
+                            // did query, and the lead goes back to waiting for a report that
+                            // exists.
+                            const sr = deps.sessionReaderReport?.();
+                            const bridge = sr && sr.attempted > 0
+                                ? `；我试过的 ctx.session 形状：${(sr.failedShapes.length ? sr.failedShapes.join("→") : sr.usedShape ?? "?")}${sr.lastError ? `（宿主最后一次的错误：${shorten(sr.lastError, 90)}）` : "（宿主没有报错，只是没给出 parentID）"}`
+                                : "";
+                            return saw
+                                ? `（ids 未匹配到本会话的子代理，宿主会话树里也没有可认领的子会话）${bridge}`
+                                : `（ids 未匹配到；而且我没能查看宿主会话树：${adoption.why}）${bridge}`;
+                        })()
+                        : saw
+                            ? ""
+                            : `（注意：${adoption.why}，所以"确实没有子代理"这个结论我给不出）`;
+                    return toToolResult(`没有待收集的派发${inner}。` +
+                        // The old line asserted the dispatch had failed.  Measured live: it
+                        // had not — a completed host `task` with a full reply was sitting in
+                        // the transcript, and the honest reason is that a synchronous host
+                        // task never enters this registry at all.
+                        `如果你用的是同步 \`task\`：宿主自己就把结果收回来了，它从不登记在这里，这不是派发失败。` +
+                        `只有后台 \`task {background:true}\`（或显式带 ids）需要 tm_join 来取。` +
+                        (lease ? `\n${lease}` : ""));
                 }
                 await settleAdopted(mine, directory);
                 const waitMs = Math.max(0, Math.min(maxWaitMs, Number(args.waitMs) || 0));
-                const deadline = now() + waitMs;
+                const prev = lastJoin.get(parent);
+                const { budget, repeat: repeatWait, streak } = joinBudget(waitMs, maxWaitMs, prev);
+                const waitStart = now();
+                const deadline = waitStart + budget;
                 let settled = false;
                 for (;;) {
                     await refreshFromStatus(directory);
@@ -615,6 +662,16 @@ export function buildDispatchTools(deps) {
                     await sleep(Math.min(1000, Math.max(100, deadline - now())));
                 }
                 const stillRunning = mine.filter((r) => r.state === "running");
+                lastJoin.set(parent, { at: now(), stillRunning: stillRunning.length, streak });
+                log({
+                    step_id: "join",
+                    event: "wait",
+                    asked_ms: waitMs,
+                    budget_ms: budget,
+                    waited_ms: Math.max(0, now() - waitStart),
+                    still_running: stillRunning.length,
+                    repeat: repeatWait,
+                });
                 if (args.cancel === true || args.cancel === "true") {
                     for (const r of stillRunning) {
                         if (typeof api?.abort === "function") {
@@ -631,28 +688,103 @@ export function buildDispatchTools(deps) {
                 }
                 const sums = summarizeStates(mine);
                 const header = [
-                    `派发汇总：${sums.idle} 完成 / ${sums.running} 运行中 / ${sums.error} 失败${settled ? "（全部已结算）" : "（未等到全部结算，可再次 tm_join）"}`,
+                    `派发汇总：${sums.idle} 完成 / ${sums.running} 运行中 / ${sums.error} 失败${settled ? "（全部已结算）" : `（未等到全部结算 · 本次已等 ${Math.round((now() - waitStart) / 1000)}s）`}`,
                     ...mine.map((r) => renderChildLine(r, (r.finishedAt ?? now()) - r.startedAt)),
                 ];
+                if (stillRunning.length && !settled) {
+                    header.push(`⏱ 还有 ${stillRunning.length} 个子代理在跑 —— 先告诉用户你在等谁、在等什么、这一轮不是交付，再决定是等还是去干活。` +
+                        `你的工具调用在界面上只是一行打不开的卡片，你不说，用户没法把"回合结束"和"任务完成"分开。`);
+                }
+                if (repeatWait && stillRunning.length) {
+                    header.push(`⏳ 连续第 ${streak} 次等待，而且上一次也没等到结算 —— 这段等待里你什么都没做，它不是并行，是同步 task 的等价物。` +
+                        `别再等：① 先做 lead 工作（合并骨架、路由下一个独立任务、你自己的验收项），做完再 tm_join；` +
+                        `② 或就此收尾，把未收的派发逐条列成 open handoff 交给用户；` +
+                        `③ 或 { cancel: true } 收掉已经不需要的那些。` +
+                        `（宿主若开了 OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true，内置 task {background:true} 的卡片可以直接点开看实时进度。）`);
+                }
                 // Goal tripwire, at the exact moment a lead tends to wrap up: every
                 // child settled says nothing about the USER'S goal, and the host's own
                 // todo list does.  Read-only (GET /session/{id}/todo has no write
                 // body), so this can remind but never rewrite.
-                if (settled && typeof api?.todo === "function" && parent) {
-                    try {
-                        const un = unwrapClientResult(await api.todo({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
-                        const open = un.ok ? openHostTodos(un.data) : [];
-                        if (open.length) {
-                            header.push(`⚠ 目标未达成：宿主 todolist 还有 ${open.length} 项未完成 —— ${open.slice(0, 6).map((t) => `「${t.content}」(${t.status})`).join("、")}` +
-                                (open.length > 6 ? ` …+${open.length - 6}` : "") +
-                                `\n按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。`);
-                            log({ step_id: "join", event: "goal_open", count: open.length });
+                //
+                // The check has THREE outcomes and all three must be sayable.  Silence when
+                // the seam is missing (v2's client shim has no `todo`) read as "the goal
+                // check ran and passed", which is the same overstatement this tool was
+                // already fixed for on the adoption path — a settled round is exactly when
+                // an unchecked box matters most.
+                if (settled) {
+                    const canCheck = typeof api?.todo === "function" && Boolean(parent);
+                    let checked = false;
+                    let ledgerEmpty = false;
+                    if (canCheck) {
+                        try {
+                            const un = unwrapClientResult(await api.todo({ path: { id: parent }, ...(directory ? { query: { directory } } : {}) }));
+                            checked = un.ok;
+                            const open = un.ok ? openHostTodos(un.data) : [];
+                            if (open.length) {
+                                header.push(`⚠ 目标未达成：宿主 todolist 还有 ${open.length} 项未完成 —— ${open.slice(0, 6).map((t) => `「${t.content}」(${t.status})`).join("、")}` +
+                                    (open.length > 6 ? ` …+${open.length - 6}` : "") +
+                                    `\n按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。` +
+                                    // v1 has the built-in `todowrite`; a host without it must not be
+                                    // told to call a tool it cannot call (the tm_ptc_run / `task`
+                                    // lesson a third time).  Without the write seam the only honest
+                                    // move is to say which items are done in the reply.
+                                    (typeof api?.todo === "function"
+                                        ? `（若这些项其实已经做完——例如你刚把派发结果收齐——先用 todowrite 更新状态，再收尾。）`
+                                        : `（这个宿主没给写清单的入口：若这些项其实已完成，就在回复里逐条写明哪条做完了、依据是什么。）`));
+                                log({ step_id: "join", event: "goal_open", count: open.length });
+                            }
+                        }
+                        catch {
+                            checked = false;
+                            /* the todo endpoint is an extra, never a reason to fail a join */
                         }
                     }
-                    catch {
-                        /* the todo endpoint is an extra, never a reason to fail a join */
+                    if (!checked && deps.ledgerStore?.available?.() && parent) {
+                        // v2 has no `session.todo` to read, so the list that CAN be checked is
+                        // the one this plugin keeps (`tm_ledger`, in ctx.storage).  A non-empty
+                        // open set is a fact worth refusing a wrap-up over; an EMPTY one is not
+                        // evidence the goal was met — it usually means nothing was ever
+                        // recorded, which is its own honest "cannot check".
+                        try {
+                            const led = await deps.ledgerStore.load(parent);
+                            const rest = led ? openItems(led) : [];
+                            if (rest.length) {
+                                const line = ledgerGoalLine(led);
+                                if (line)
+                                    header.push(line);
+                                log({ step_id: "join", event: "goal_open", count: rest.length, source: "ledger" });
+                                checked = true;
+                            }
+                            else if (led) {
+                                ledgerEmpty = true;
+                            }
+                        }
+                        catch {
+                            /* the ledger is an extra too — a store that will not read never fails a join */
+                        }
+                    }
+                    if (!checked) {
+                        header.push(canCheck
+                            ? "（目标核对没做成：宿主 todo 端点返回异常，这一轮我没有看到你的清单状态。）"
+                            : ledgerEmpty
+                                ? "（目标核对没做成：这个宿主没给 session.todo 端点，而 tm_ledger 里一条都没有——没有可核对的目标状态。`所有子代理已结算` 不等于 `目标已达成`：要么先 tm_ledger { action:\"add\" } 把要求记下来，要么在回复里自己逐条核对再收尾。）"
+                                : "（目标核对没做成：这个宿主没给 session.todo 端点，我也读不到本插件的 tm_ledger——无法读取清单状态。`所有子代理已结算` 不等于 `目标已达成`，这一轮请自己核对再收尾。）");
+                        log({
+                            step_id: "join",
+                            event: "goal_unchecked",
+                            reason: canCheck ? "endpoint_failed" : ledgerEmpty ? "ledger_empty" : "no_seam",
+                        });
                     }
                 }
+                // #80/#86/#87: THE LEASE TRIPWIRE — one computation (leaseLine above),
+                // attached to every answer this tool gives, so a settled round and an
+                // empty one cannot disagree about whether a window is still open.
+                if (settled) {
+                    const lease = leaseLine();
+                    if (lease)
+                        header.push(lease);
+                }
                 const wantText = !(args.includeText === false || args.includeText === "false");
                 const collectible = mine.filter((r) => r.state !== "running");
                 const blocks = [];
@@ -660,9 +792,16 @@ export function buildDispatchTools(deps) {
                     for (const r of collectible) {
                         const reply = await fetchReply(r.sessionID, directory);
                         const text = reply.text;
-                        blocks.push(`--- ${r.agent} "${r.label}" (${r.sessionID}) ---\n${text.trim() ||
-                            `（该子会话没有可读的助手回复${r.error ? `；宿主错误：${r.error}` : reply.error ? `；宿主错误：${reply.error}` : ""}）` +
-                                `——子会话不是文件，tm_read 读不到它：在宿主的会话面板里看这条子会话，或改用内置 task 工具重做这一步。`}`);
+                        const src = text && reply.via ? ` ·正文来源=${reply.via}` : "";
+                        // Which seam answered, per child — an id and a seam name, never a body (R6 binds
+                        // a diagnostic too). This is the line that makes "正文来源=…" checkable later.
+                        log({ step_id: "join", event: text ? "child_body" : "child_body_missing", child: r.sessionID, via: reply.via ?? "none" });
+                        blocks.push(`--- ${r.agent} "${r.label}" (${r.sessionID})${src} ---\n${text.trim() ||
+                            (r.via === "host-injection"
+                                ? `（这个子会话由宿主的 subagent 工具派发，而这一次我没有读到它的正文${reply.error ? `：${reply.error}` : "：这个宿主没给可读正文的缝"}。完成时宿主仍会把 \`<subagent sessionID=\"${r.sessionID}\" …>\` 注入本会话，我已经把它登记在案、状态如上。` +
+                                    `要全文就在那条注入到达后读它，或让子代理把交付写进黑板；不要为了拿正文反复 join。）`
+                                : `（该子会话没有可读的助手回复${r.error ? `；宿主错误：${r.error}` : reply.error ? `；宿主错误：${reply.error}` : ""}）` +
+                                    `——子会话不是文件，tm_read 读不到它：在宿主的会话面板里看这条子会话，或改用内置 task 工具重做这一步。`)}`);
                     }
                 }
                 const body = [...header, ...(blocks.length ? ["", blocks.join("\n")] : [])].join("\n");
@@ -687,12 +826,31 @@ export function buildDispatchTools(deps) {
         if (!sid)
             return;
         const rec = children.get(sid);
-        if (!rec)
+        if (!rec) {
+            // The parent's own idle is the only completion signal v2 gives us for a host
+            // child: the background reply is injected into the parent before the parent's turn
+            // ends (measured: child injected …824730, parent idle …829038), and the plugin has
+            // no endpoint to read a child session's state.  So settle the still-running host
+            // children of THIS session — and say plainly that it is a presumption.
+            if (type === "session.idle") {
+                for (const child of children.values()) {
+                    if (child.via !== "host-injection" || child.state !== "running")
+                        continue;
+                    if (child.parentSessionID !== sid)
+                        continue;
+                    child.state = "idle";
+                    child.finishedAt = now();
+                    child.settleSource = "parent-idle";
+                    log({ step_id: "events", event: "idle_presumed", child: child.sessionID, agent: child.agent, ms: child.finishedAt - child.startedAt });
+                }
+            }
             return;
+        }
         if (type === "session.idle") {
             if (rec.state === "running") {
                 rec.state = "idle";
                 rec.finishedAt = now();
+                rec.settleSource = "event";
                 log({ step_id: "events", event: "idle", child: sid, agent: rec.agent, ms: (rec.finishedAt ?? 0) - rec.startedAt });
             }
             return;
@@ -717,10 +875,54 @@ export function buildDispatchTools(deps) {
             }
         }
     };
+    /** Open a row for a child the HOST dispatched (v2's `subagent` tool) that this
+     *  registry never created.  Returns false when the ids are unusable or the child is
+     *  already known — a plugin reload replays hooks, and a second row for one session
+     *  would make tm_join count the same work twice. */
+    function register(child) {
+        const rec = hostChildRecord(child, now);
+        if (!rec || children.has(rec.sessionID))
+            return false;
+        children.set(rec.sessionID, rec);
+        deps.onChildSession?.(rec.sessionID, rec.agent);
+        // The label is model-authored free text: it belongs in the lead's table, never in
+        // the audit trail (R6 binds a diagnostic as much as a guard).
+        log({ step_id: "join", event: "host_subagent", child: rec.sessionID, agent: rec.agent, parent: rec.parentSessionID });
+        return true;
+    }
+    /** Settle a child from the host's OWN completion envelope (see
+     *  `applyV2CompletionWatch`).  Returns false when this process does not know the id, so
+     *  an unrelated session's injection never touches our registry.  This is the third
+     *  settle source and the only one that works mid-turn on v2: the child's own
+     *  `session.idle` is not forwarded to a plugin subscriber (measured 2026-09-26), and a
+     *  parent-idle presumption cannot fire while the parent is still working — which left a
+     *  child whose report had already been injected showing 运行中. */
+    function settle(sessionID, state) {
+        const rec = children.get(String(sessionID ?? "").trim());
+        if (!rec || rec.state !== "running")
+            return false;
+        rec.finishedAt = now();
+        if (state === "error" || state === "failed" || state === "aborted") {
+            rec.state = "error";
+            rec.error = `宿主报告子会话 ${state}（其正文随注入消息送达）`;
+        }
+        else {
+            rec.state = "idle";
+        }
+        rec.settleSource = "injection";
+        log({ step_id: "events", event: "idle_injection", child: rec.sessionID, agent: rec.agent, ms: rec.finishedAt - rec.startedAt });
+        return true;
+    }
     return {
-        tm_dispatch: dispatch,
         tm_join: join,
         observeEvent,
+        register,
+        settle,
+        /** Anything still running? The completion scan is O(messages) per request, so it
+         *  asks this first and skips the read when the answer is no. */
+        hasOpen: () => { for (const c of children.values())
+            if (c.state === "running")
+                return true; return false; },
         children: () => [...children.values()],
     };
 }