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

package/dist/tm/dispatch.js

@@ -1,29 +1,33 @@
 /**
- * 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";
@@ -32,35 +36,131 @@ import { shorten } from "./config.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"];
-/** Resolve the host session API defensively — a missing namespace means the
- *  host does not speak this protocol, and the caller must degrade. */
+export function openHostTodos(todos) {
+    if (!Array.isArray(todos))
+        return [];
+    const open = [];
+    for (const t of todos) {
+        const status = String(t?.status ?? "").toLowerCase();
+        if (!status || status === "completed" || status === "cancelled" || status === "done")
+            continue;
+        const content = String(t?.content ?? "").trim();
+        if (content)
+            open.push({ content: content.slice(0, 120), status });
+    }
+    return open;
+}
+/** #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.  `parseDispatchTitle`
- *  is the discriminator on the way back: a child the host lists but this
- *  process never created is OURS only if this shape (and a known agent)
- *  matches — otherwise it belongs to the built-in `task` tool and we must
- *  not claim its reply. */
-export function dispatchTitle(agent, label) {
-    return `tm:${agent}:${label}`;
+/** 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 was the host's OWN subagent convention — the built-in task tool
+ *  titles its children `${description} (@${agent} subagent)` (verified in the
+ *  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:"))
+    if (t.startsWith("tm:")) {
+        const rest = t.slice(3);
+        const colon = rest.indexOf(":");
+        const legacyAgent = (colon < 0 ? rest : rest.slice(0, colon)).trim().toLowerCase();
+        if (!legacyAgent || !targets.includes(legacyAgent))
+            return null;
+        return { agent: legacyAgent, label: (colon < 0 ? "" : rest.slice(colon + 1)).trim().slice(0, 40) };
+    }
+    // The marker is required here — without it a built-in task child would read
+    // as ours, which is the one thing the restart path must never do.
+    const m = /^(.*?) \(@([^\s()]+) subagent ·tm\)$/.exec(t);
+    if (!m)
         return null;
-    const rest = t.slice(3);
-    const colon = rest.indexOf(":");
-    const agent = (colon < 0 ? rest : rest.slice(0, colon)).trim().toLowerCase();
+    const agent = m[2].trim().toLowerCase();
     if (!agent || !targets.includes(agent))
         return null;
-    return { agent, label: (colon < 0 ? "" : rest.slice(colon + 1)).trim().slice(0, 40) };
+    return { agent, label: m[1].trim().slice(0, 40) };
 }
 /**
  * Pull the assistant reply text (and, when the host records it, the moment
@@ -83,12 +183,15 @@ export function lastAssistantMessage(messages) {
             continue;
         const completed = Number(info?.time?.completed);
         const completedAt = Number.isFinite(completed) && completed > 0 ? completed : undefined;
+        // an assistant turn that errored carries the reason on info.error — the
+        // lead must see it, or "no reply" reads as "the agent had nothing to say"
+        const error = info?.error ? describeHostError(info.error, 200) : undefined;
         const parts = entry?.parts;
         if (!Array.isArray(parts)) {
             // a bare message list (no {info,parts} envelope) — take any text part
             const one = entry ?? {};
             if (one.type === "text" && typeof one.text === "string")
-                return { text: one.text, completedAt };
+                return { text: one.text, ...(completedAt ? { completedAt } : {}), ...(error ? { error } : {}) };
             continue;
         }
         const texts = parts
@@ -97,8 +200,12 @@ export function lastAssistantMessage(messages) {
             return pp && pp.type === "text" && typeof pp.text === "string" && pp.text.trim() !== "";
         })
             .map((p) => String(p.text));
+        // keys are added only when present so a deep-equality assertion sees the
+        // shape the caller actually got (no `error: undefined` noise)
         if (texts.length)
-            return { text: texts.join("\n"), completedAt };
+            return { text: texts.join("\n"), ...(completedAt ? { completedAt } : {}), ...(error ? { error } : {}) };
+        if (error)
+            return { text: "", ...(completedAt ? { completedAt } : {}), error };
     }
     return { text: "" };
 }
@@ -106,6 +213,48 @@ export function lastAssistantMessage(messages) {
 export function lastAssistantText(messages) {
     return lastAssistantMessage(messages).text;
 }
+/**
+ * Turn whatever the host puts in an error slot into ONE readable line.
+ *
+ * The live host nests them (`{name, data:{message, ref}}`, `{error:{message}}`,
+ * a bare string — sometimes several at once), and `String(obj)` is
+ * "[object Object]".  That is what a lead reported to a user for three child
+ * sessions that died at launch: the one diagnostic the whole flow had was
+ * destroyed by our own rendering.  Never again: dig the known fields, then
+ * fall back to a compact key dump — never a bare object stringify.
+ */
+export function describeHostError(err, max = 220) {
+    if (typeof err === "string")
+        return shorten(err.trim() || "session.error", max);
+    if (err === null || err === undefined)
+        return "session.error";
+    if (typeof err !== "object")
+        return shorten(String(err), max);
+    const o = err;
+    const box = (v) => v && typeof v === "object" ? v : undefined;
+    const data = box(o.data);
+    const inner = box(o.error);
+    const pick = (...cands) => {
+        for (const c of cands)
+            if (typeof c === "string" && c.trim())
+                return c.trim();
+        return "";
+    };
+    const message = pick(o.message, data?.message, inner?.message, inner?.name, data?.ref ? `ref=${String(data.ref)}` : "");
+    const name = pick(o.name, inner?.name, data?.name);
+    const ref = pick(data?.ref, o.ref);
+    if (message || name) {
+        const head = name && message && !message.startsWith(name) ? `${name}: ${message}` : message || name;
+        return shorten(ref && !head.includes(ref) ? `${head}（ref=${ref}）` : head, max);
+    }
+    // nothing recognised — dump the SHAPE with short values, which is still
+    // infinitely more useful than "[object Object]"
+    const flat = Object.entries(o)
+        .slice(0, 6)
+        .map(([k, v]) => `${k}=${typeof v === "object" && v !== null ? Object.keys(v).slice(0, 4).join("+") : String(v).slice(0, 60)}`)
+        .join(" ");
+    return shorten(flat || "session.error", max);
+}
 /** One child's status line — the lead reads these, so keep them terse. */
 export function renderChildLine(c, elapsedMs) {
     const secs = Math.round(elapsedMs / 1000);
@@ -138,14 +287,47 @@ function sleep(ms) {
         t.unref?.();
     });
 }
+/** `ids` arrives in three shapes on the live host: a real array, a
+ *  JSON-array STRING (`"[\"ses_x\"]"` — what a model actually sent on
+ *  2026-09-19), or a comma-separated list.  Array.isArray alone silently
+ *  ignored the string form and returned EVERY child when the lead asked for
+ *  one, which is the same class of bug as the old `Boolean("false")` headless
+ *  trap: the arg is trusted because it "looks" like the declared type. */
+export function parseIdList(raw) {
+    if (Array.isArray(raw))
+        return raw.map((x) => String(x ?? "").trim()).filter(Boolean);
+    const s = typeof raw === "string" ? raw.trim() : "";
+    if (!s)
+        return null;
+    if (s.startsWith("[") && s.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(s);
+            if (Array.isArray(parsed))
+                return parsed.map((x) => String(x ?? "").trim()).filter(Boolean);
+        }
+        catch {
+            /* fall through to the comma split */
+        }
+    }
+    return s.split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+}
 export function buildDispatchTools(deps) {
     const leadAgent = deps.leadAgent ?? "team";
     const targets = deps.targets ?? DISPATCH_TARGETS;
-    const maxWaitMs = deps.maxWaitMs ?? 300_000;
+    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
@@ -203,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)
@@ -247,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. */
@@ -261,90 +481,16 @@ export function buildDispatchTools(deps) {
             }
         }
     }
-    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>", label: "<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 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.`,
-        args: {
-            agent: { descriptor: `agent: ${targets.join("|")} (required)` },
-            task: { descriptor: "task: string (required — the full self-contained brief the child works from)" },
-            label: { descriptor: "label: string (optional short slug for this dispatch, ≤40 chars)" },
-        },
-        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 工具（会阻塞你，但功能等价）。`));
-                }
-                const label = (typeof args.label === "string" && args.label.trim() ? args.label.trim() : task.split(/\s+/).slice(0, 4).join(" ")).slice(0, 40);
-                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 promptBody = {
-                    agent,
-                    noReply: false,
-                    parts: [{ type: "text", text: task }],
-                };
-                const directory = typeof c.directory === "string" && c.directory ? c.directory : undefined;
-                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 });
-                return toToolResult([
-                    `已派发（非阻塞）：${agent} · "${label}" · 子会话 ${sid}`,
-                    `你现在可以继续：编排下一步、做廉价检查、或继续派发其它独立任务。`,
-                    `收集结果：tm_join（立即看状态）或 tm_join { waitMs: 60000 }。所有派发完成前不要提交结论。`,
-                ].join("\n"));
-            }
-            catch (err) {
-                const e = err;
-                return toToolResult(tmError(tool, "execute", `tm_dispatch 失败：${shorten(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)" },
         },
@@ -358,10 +504,13 @@ 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 idFilter = Array.isArray(args.ids)
-                    ? new Set(args.ids.map((x) => String(x ?? "").trim()).filter(Boolean))
-                    : null;
+                const idList = parseIdList(args.ids);
+                const idFilter = idList && idList.length ? new Set(idList) : null;
                 const owned = () => [...children.values()].filter((r) => (!parent || r.parentSessionID === parent) && (!idFilter || idFilter.has(r.sessionID)));
                 let mine = owned();
                 // This process has never seen some (or all) of what the lead is asking
@@ -369,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);
@@ -387,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") {
@@ -403,9 +615,48 @@ 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按目标指令：要么继续做掉，要么向用户写明哪一条被什么卡住；不要把这轮当成收尾。` +
+                                `（若这些项其实已经做完——例如你刚把派发结果收齐——先用 todowrite 更新状态，再收尾。）`);
+                            log({ step_id: "join", event: "goal_open", count: open.length });
+                        }
+                    }
+                    catch {
+                        /* 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 = [];
@@ -413,7 +664,9 @@ 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() || "（该子会话没有可读的助手回复——用内置 read/tm_read 检查其会话，或重新派发）"}`);
+                        blocks.push(`--- ${r.agent} "${r.label}" (${r.sessionID}) ---\n${text.trim() ||
+                            `（该子会话没有可读的助手回复${r.error ? `；宿主错误：${r.error}` : reply.error ? `；宿主错误：${reply.error}` : ""}）` +
+                                `——子会话不是文件，tm_read 读不到它：在宿主的会话面板里看这条子会话，或改用内置 task 工具重做这一步。`}`);
                     }
                 }
                 const body = [...header, ...(blocks.length ? ["", blocks.join("\n")] : [])].join("\n");
@@ -425,7 +678,7 @@ export function buildDispatchTools(deps) {
             }
             catch (err) {
                 const e = err;
-                return toToolResult(tmError(tool, "execute", `tm_join 失败：${shorten(e?.message ?? err, 160)}`));
+                return toToolResult(tmError(tool, "execute", `tm_join 失败：${describeHostError(e?.message ?? err, 160)}`));
             }
         },
     };
@@ -451,7 +704,9 @@ export function buildDispatchTools(deps) {
         if (type === "session.error") {
             rec.state = "error";
             rec.finishedAt = now();
-            rec.error = shorten(props?.error?.message ?? props?.error ?? "session.error", 120);
+            // describeHostError, NOT String(err): the host nests its errors and the
+            // bare stringify produced "[object Object]" for a real launch failure
+            rec.error = describeHostError(props?.error ?? "session.error", 200);
             log({ step_id: "events", event: "error", child: sid, agent: rec.agent, reason: rec.error });
             return;
         }
@@ -467,7 +722,6 @@ export function buildDispatchTools(deps) {
         }
     };
     return {
-        tm_dispatch: dispatch,
         tm_join: join,
         observeEvent,
         children: () => [...children.values()],