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

package/dist/tm/dispatch.js

@@ -1,33 +1,36 @@
 /**
- * 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";
 /** The five dispatchable specialists — "team" is deliberately NOT in the
@@ -47,36 +50,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:")) {
@@ -249,14 +314,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
@@ -306,37 +377,6 @@ export function buildDispatchTools(deps) {
             }
         })();
     }
-    /**
-     * 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,9 +385,11 @@ 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)
@@ -389,6 +431,42 @@ export function buildDispatchTools(deps) {
         }
         return 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
      *  was listening?" without waiting for an event that already fired. */
@@ -403,177 +481,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,6 +504,10 @@ 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;
@@ -597,13 +518,66 @@ export function buildDispatchTools(deps) {
                 if (mine.length < (idFilter ? idFilter.size : 1)) {
                     if (await adoptFromHost(parent, directory, idFilter))
                         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();
+                    return toToolResult(`没有待收集的派发${idFilter ? "（ids 未匹配到本会话的子代理，宿主会话树里也没有可认领的子会话）" : ""}。` +
+                        // 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 +589,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,9 +615,20 @@ 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
@@ -645,7 +640,8 @@ export function buildDispatchTools(deps) {
                         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按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。`);
+                                `\n按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。` +
+                                `（若这些项其实已经做完——例如你刚把派发结果收齐——先用 todowrite 更新状态，再收尾。）`);
                             log({ step_id: "join", event: "goal_open", count: open.length });
                         }
                     }
@@ -653,6 +649,14 @@ export function buildDispatchTools(deps) {
                         /* the todo endpoint is an extra, never a reason to fail a join */
                     }
                 }
+                // #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 = [];
@@ -718,7 +722,6 @@ export function buildDispatchTools(deps) {
         }
     };
     return {
-        tm_dispatch: dispatch,
         tm_join: join,
         observeEvent,
         children: () => [...children.values()],