dsh-ntr 0.3.3 → 0.3.5

package/lib/bridge.js

@@ -6,13 +6,13 @@
  * Connection RPC channel (authenticated) into `BridgeManager`, which is the
  * only object allowed to spawn a configured command.
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { delimiter, dirname, join } from 'node:path';
 import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
-import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, isAbsolutePath, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
+import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, hasUnambiguousModelSelector, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, isAbsolutePath, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
 import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from "./protocol.js";
 import { OUTPUT_CHARS_PER_TOKEN, TurnTpsTracker } from "./tps.js";
 /**
@@ -42,6 +42,37 @@ const FS_MAX_WRITE_BYTES = 2 * 1024 * 1024;
  * stop — and with it the stall reclaim that calls it — forever.
  */
 const SESSION_CLOSE_TIMEOUT_MS = 5_000;
+/**
+ * The second — and last — slice after the escalation kill (`SIGKILL` on POSIX,
+ * a second `taskkill /T /F` on Windows). Deliberately short: past this point
+ * the child is the OS's problem (plus the exit reaper, see `reapLiveChildren`).
+ *
+ * `disposeChild` RESERVES this inside the budget it is handed, so every caller's
+ * number means the WHOLE disposal — graceful wait plus escalation wait — and
+ * never just the first one.
+ */
+const KILL_ESCALATION_GRACE_MS = 500;
+/**
+ * Fire-and-forget kill: the whole disposal budget for the non-teardown paths
+ * (see `KILL_ESCALATION_GRACE_MS` for how it splits). Same 3s the old inline
+ * SIGKILL timer used before escalating.
+ */
+const KILL_ESCALATION_DELAY_MS = 3_000;
+/**
+ * Budget for disposing a child whose start was invalidated by a teardown (see
+ * `AgentBridge.spawnAndConnect`). Short: that child was spawned moments ago and
+ * never served anything, so there is nothing to drain.
+ */
+const STALE_START_KILL_BUDGET_MS = 2_000;
+/**
+ * The WHOLE host-shutdown budget for killing children, shared by every bridge
+ * (bridges run concurrently, so this is the worst case for all of them, not
+ * per bridge). One number, one deadline: `AgentBridge.shutdown` hands what is
+ * LEFT of it to `killChildAndWait`, and `disposeChild` reserves the escalation
+ * grace inside that — so the graceful wait gets at most 4s − 500ms and the
+ * whole disposal, escalation included, never exceeds 4s.
+ */
+const SHUTDOWN_BUDGET_MS = 4_000;
 /**
  * The plugin's normalized MCP server shape → the ACP wire shape.
  *
@@ -110,6 +141,7 @@ const DEFAULT_TUNING = {
     ambientQuietMs: 10_000,
     ambientMaxMs: 120_000,
     backgroundTaskMaxMs: 600_000,
+    backgroundTaskCeilingMs: 0,
     backgroundParkedGraceMs: 30_000,
     ambientStaleMs: 300_000,
 };
@@ -129,6 +161,24 @@ export class AgentBridge {
     stderrTail = [];
     child;
     conn;
+    /**
+     * Teardown generation, bumped ONLY by a deliberate teardown (`stop` /
+     * `shutdown` / `forceReset`), so a start that was already in flight can tell
+     * that nobody owns its outcome any more: `spawnAndConnect` re-checks this
+     * after each await and disposes the child it would otherwise have published
+     * as `ready`. Without it, a teardown landing during `ensureAgentExecutable`
+     * (a global npm install can take minutes) left a freshly spawned agent
+     * running with no owner.
+     *
+     * `releaseAll` and `killChild` deliberately do NOT bump it: both are also the
+     * failure path of a start's own handshake — a child dying during startup goes
+     * `exit` → `connectionLost` → `releaseAll('died')` — and that start must
+     * still publish `error` with its stderr tail rather than be mistaken for a
+     * teardown (see `ensureReady`). It cannot leak a process either way: a crash
+     * release only happens once the child exists, and `spawnAndConnect` has no
+     * spawn point left after that.
+     */
+    teardownEpoch = 0;
     starting;
     sessions = new Map();
     acpIndex = new Map();
@@ -609,10 +659,20 @@ export class AgentBridge {
             return Promise.resolve();
         if (this.starting !== undefined)
             return this.starting;
+        const epoch = this.teardownEpoch;
         this.state = 'starting';
         this.publishStatus();
-        this.starting = this.spawnAndConnect()
+        const started = this.spawnAndConnect(epoch)
             .then(() => {
+            // A teardown landed while the handshake was in flight: it owns the
+            // bridge now, and `spawnAndConnect` has already disposed whatever it
+            // spawned. Publishing `ready` here would paint a live status back over
+            // the stopped bridge. `state` catches the one teardown that does NOT
+            // bump the epoch — a crash release (`releaseAll`): without it, a
+            // handshake that resolved just as the child died would paint `ready`
+            // over the `stopped` that the crash left behind.
+            if (this.teardownEpoch !== epoch || this.state !== 'starting')
+                return;
             this.state = 'ready';
             this.lastError = undefined;
             this.publishStatus();
@@ -621,6 +681,16 @@ export class AgentBridge {
             this.touch();
         })
             .catch((error) => {
+            // Same guard: a start nobody owns any more must not publish its
+            // outcome. A start's OWN failure — `withStartupTimeout`, or the child
+            // dying mid-handshake (which runs through `releaseAll`) — still reaches
+            // the lines below and publishes `error` with its stderr tail; neither
+            // of those paths bumps the epoch.
+            if (this.teardownEpoch !== epoch) {
+                // Publish nothing, but keep the caller's error contract: every
+                // interrupted start has always surfaced as `agent_unreachable`.
+                throw new AcpError('agent_unreachable', `acp: agent "${this.def.id}" failed to start: ${error instanceof Error ? error.message : String(error)}`);
+            }
             this.state = 'error';
             this.lastError = error instanceof Error ? error.message : String(error);
             this.clearIdleTimer();
@@ -628,15 +698,31 @@ export class AgentBridge {
             this.publishStatus();
             throw new AcpError('agent_unreachable', `acp: agent "${this.def.id}" failed to start: ${this.lastError}`);
         })
-            .finally(() => { this.starting = undefined; });
-        return this.starting;
+            .finally(() => {
+            // Only clear a slot that is still OURS: a teardown may have cleared it
+            // (and a fresh `ensureReady` may already hold it).
+            if (this.starting === started)
+                this.starting = undefined;
+        });
+        this.starting = started;
+        return started;
     }
-    async spawnAndConnect() {
+    /**
+     * @param epoch - `teardownEpoch` captured when this start claimed the bridge.
+     *   Every await below is a window in which a teardown can land; a stale start
+     *   owns nothing and must leave no process behind (see `teardownEpoch`).
+     */
+    async spawnAndConnect(epoch) {
         this.stderrTail = [];
         // Resolve (and, with npmPackage, auto-install) the executable before the
         // spawn; the resolved absolute path also pins the lookup to the host PATH
         // plus the well-known extra dirs, not the child env the agent may override.
         const { command } = await ensureAgentExecutable(this.def, undefined, line => this.noteStderr(line));
+        // A teardown landed while the executable was being resolved — a global
+        // install can hold this await for minutes. Nothing has been spawned yet, so
+        // there is nothing to reap; just refuse to create the process.
+        if (this.teardownEpoch !== epoch)
+            return;
         const cwd = safeSpawnCwd(this.def, this.wantedSpawnCwd);
         this.spawnCwd = cwd;
         const launch = windowsShimLaunch(command, this.def.args ?? []);
@@ -652,6 +738,7 @@ export class AgentBridge {
             ...(launch.verbatim ? { windowsVerbatimArguments: true } : {}),
         });
         this.child = child;
+        trackAgentChild(child);
         child.on('error', (error) => {
             // Identity guard: a stale event from a PREVIOUS child must not tear down
             // a connection that replaced it (an `exit` can land after the respawn
@@ -709,6 +796,25 @@ export class AgentBridge {
             },
             clientInfo: { name: 'dsh-ntr', title: 'DSH NTR', version: PLUGIN_VERSION },
         }), 'initialize');
+        // The second — and widest — window: `initialize` waits up to the startup
+        // budget, and a shutdown / stop during it already dropped the connection and
+        // killed the child we spawned. That child is OURS even though the bridge no
+        // longer points at it, so dispose it with the awaitable kill instead of
+        // leaving a process nobody can reach.
+        if (this.teardownEpoch !== epoch) {
+            // Only when it is still the CURRENT connection: a newer one belongs to a
+            // fresh start and must not be closed from here.
+            if (this.conn === conn) {
+                this.conn = undefined;
+                conn.close();
+            }
+            if (this.child === child) {
+                this.child = undefined;
+                this.spawnCwd = undefined;
+            }
+            await disposeChild(child, STALE_START_KILL_BUDGET_MS);
+            return;
+        }
         this.initResult = init;
         // The fork capability is agent knowledge that must outlive the process:
         // report it so the manager can persist a LAST KNOWN copy and serve the
@@ -1144,14 +1250,18 @@ export class AgentBridge {
             // workspace from its own cwd would come back in the plugin's sandbox.
             const workspaceRoot = chatWorkspaceRoot(this.sessionWorkspace?.(), session.dshSessionId);
             await this.ensureReady(workspaceRoot);
+            // The CONNECTION first: a teardown that landed during the start leaves no
+            // `initResult` either, and reporting that as `resume_unsupported` would
+            // blame the agent for a capability it may well have. "The bridge is not
+            // up" is the honest answer.
+            const conn = this.conn;
+            if (conn === undefined)
+                throw new AcpError('agent_unreachable', 'acp: connection is not open');
             // The capability comes from the FRESH initialize: after a crash the
             // bridge restarts the process, so check the (new) initResult here.
             if (this.initResult?.agentCapabilities?.loadSession !== true) {
                 throw new AcpError('resume_unsupported', `acp: agent "${this.def.id}" does not advertise the loadSession capability; start a new session`);
             }
-            const conn = this.conn;
-            if (conn === undefined)
-                throw new AcpError('agent_unreachable', 'acp: connection is not open');
             const resolved = resolveSessionCwd(this.def, session.cwd, p => realpathSync(p), workspaceRoot === undefined ? [] : [workspaceRoot]);
             // Replay arrives as brand-new updates, so the transcript restarts too;
             // seq keeps meaning "position in the current epoch". What the buffer held
@@ -1215,9 +1325,41 @@ export class AgentBridge {
             throw error;
         }
     }
-    /** Release all live sessions (process died or went idle): keep them resumable, settle permissions, drop the connection. */
+    /**
+     * Release all live sessions (process died or went idle): keep them resumable,
+     * settle permissions, drop the connection.
+     *
+     * Deliberately does NOT bump `teardownEpoch`: a child's death during startup
+     * runs through `connectionLost` into this method, and that start must still
+     * publish `error` with its stderr tail — the settings card expands on exactly
+     * that pair (see `view` / `teardownEpoch`).
+     */
     releaseAll(reason, cause) {
         this.clearIdleTimer();
+        this.parkSessions(reason, cause);
+        this.conn?.close();
+        this.conn = undefined;
+        this.killChild();
+        this.state = 'stopped';
+        this.initResult = undefined;
+        this.publishStatus();
+    }
+    /**
+     * Park every live session as RELEASED — resumable through `session/load`,
+     * never destroyed — and persist the records.
+     *
+     * This is the local half shared by `releaseAll` (crash / idle / workspace) and
+     * `shutdown` (host exit): those paths differ only in what happens to the child
+     * afterwards. A `closed` session is skipped — its record belongs to
+     * `closeSession`, and flipping it to released would let a resume resurrect a
+     * conversation that is being destroyed (constraint 10).
+     *
+     * Returns how many sessions were parked, so a shutdown with nothing to park
+     * does not rewrite the state file (a second `shutdownAll` must not erase the
+     * records the first one persisted).
+     */
+    parkSessions(reason, cause) {
+        let parked = 0;
         for (const session of [...this.sessions.values()]) {
             // A session already being closed is `closeSession`'s to delete. Marking
             // it released would park it as resumable, and `doResumeSession` flips
@@ -1240,19 +1382,16 @@ export class AgentBridge {
             this.settlePermissions(session);
             this.released.set(session.sessionId, session);
             this.hub.broadcast({ type: 'session/released', sessionId: session.sessionId, session: snapshot(session), reason, cause });
+            parked += 1;
         }
         this.sessions.clear();
         this.acpIndex.clear();
-        this.conn?.close();
-        this.conn = undefined;
-        this.killChild();
-        this.state = 'stopped';
-        this.initResult = undefined;
-        this.publishStatus();
         // The parked records are what keeps them resumable after a host restart —
         // persist now, while their transcripts (the `hasHistory` evidence) are
         // still the ones they were parked with.
-        this.onSessionsDirty?.();
+        if (parked > 0)
+            this.onSessionsDirty?.();
+        return parked;
     }
     /** Detach one released session record for a resume attempt. */
     takeReleased(sessionId) {
@@ -1390,6 +1529,13 @@ export class AgentBridge {
     }
     /** Kill the child and drop every local session bound to this connection. */
     async stop(reason = 'agent-stopped') {
+        // Deliberate teardown: an in-flight start owns nothing any more, and must
+        // not be able to publish `ready` over the stopped state that follows.
+        this.teardownEpoch += 1;
+        // Drop the memoized start: a later `ensureReady` must not adopt a promise
+        // whose result was already discarded. That promise's own `finally`
+        // re-checks identity, so it cannot clear a NEWER start's slot.
+        this.starting = undefined;
         this.clearIdleTimer();
         for (const session of [...this.sessions.values()]) {
             await this.closeSession(session, reason);
@@ -1415,6 +1561,8 @@ export class AgentBridge {
      * message. This is a stop, not a discard.
      */
     forceReset(reason) {
+        this.teardownEpoch += 1;
+        this.starting = undefined;
         this.clearIdleTimer();
         for (const session of [...this.sessions.values()]) {
             session.closed = true;
@@ -1433,6 +1581,13 @@ export class AgentBridge {
         this.initResult = undefined;
         this.publishStatus();
     }
+    /**
+     * Fire-and-forget kill for the NON-teardown paths: idle release, workspace
+     * move, crash handling, `forceReset`, and a start's own failure. None of them
+     * may block on a dying process, and CRASH ≠ DESTROY (constraint 10): the
+     * sessions were already parked by the caller, this only takes the process
+     * away. The awaitable variant is `killChildAndWait`, used by host shutdown.
+     */
     killChild() {
         const child = this.child;
         this.child = undefined;
@@ -1440,36 +1595,59 @@ export class AgentBridge {
         // `spawnAndConnect`). Leaving it behind would make `ensureReady` believe a
         // process is still running in that directory.
         this.spawnCwd = undefined;
-        if (child === undefined || child.pid === undefined)
+        if (child === undefined)
             return;
-        try {
-            child.stdin?.end();
-        }
-        catch { /* already gone */ }
-        const pid = child.pid;
-        if (process.platform === 'win32') {
-            // Parity with the POSIX branch below, which kills the whole process
-            // GROUP: on Windows "the group" is the process tree, and it has to be
-            // killed while the tree is intact — killing the direct child first (a
-            // `cmd.exe` shim wrapper, see `windowsShimLaunch`) re-parents the agent
-            // out of `taskkill /T`'s reach. `stdin.end()` above is the graceful half.
-            killProcessTree(pid);
+        void disposeChild(child, KILL_ESCALATION_DELAY_MS);
+    }
+    /**
+     * Take the current child away and WAIT until it is gone (bounded). Only the
+     * host shutdown path uses this — every other teardown must stay
+     * fire-and-forget.
+     *
+     * Always resolves: a teardown that could hang on an agent ignoring SIGTERM
+     * would be worse than a leaked process, and the process-exit reaper
+     * (`reapLiveChildren`) still holds the pid if even the escalation loses.
+     */
+    async killChildAndWait(budgetMs) {
+        const child = this.child;
+        this.child = undefined;
+        this.spawnCwd = undefined;
+        if (child === undefined)
             return;
-        }
-        try {
-            process.kill(-pid, 'SIGTERM');
-        }
-        catch {
-            child.kill('SIGTERM');
-        }
-        setTimeout(() => {
-            if (child.exitCode !== null || child.signalCode !== null)
-                return;
-            try {
-                process.kill(-pid, 'SIGKILL');
-            }
-            catch { /* already gone */ }
-        }, 3000).unref();
+        await disposeChild(child, budgetMs);
+    }
+    /**
+     * Host shutdown: park every live session as RELEASED (resumable, exactly as a
+     * crash would leave it), then WAIT for the child to die.
+     *
+     * Deliberately not `stop`: `stop` asks every session's agent to
+     * `session/close` and then clears the released records — i.e. it DESTROYS the
+     * conversations. A host shutdown is not the user's "stop this agent" gesture:
+     * the host is coming back, and the conversations must come back with it
+     * (constraint 10, plus the `chatSessions` records that outlive the restart).
+     * Skipping the per-session RPC is also what keeps teardown bounded: N sessions
+     * would otherwise spend up to N × SESSION_CLOSE_TIMEOUT_MS before the child
+     * was even signalled, and the process is about to die anyway — "the agent
+     * forgot this session" costs nothing a `session/load` cannot rebuild.
+     *
+     * Always resolves: `budgetMs` bounds the WHOLE kill — parking is synchronous,
+     * the graceful wait and the escalation both come out of the same deadline,
+     * and whatever still lives after it is the exit reaper's.
+     */
+    async shutdown(budgetMs = SHUTDOWN_BUDGET_MS) {
+        const deadline = Date.now() + Math.max(0, budgetMs);
+        // A deliberate teardown: an in-flight start must not publish `ready` (or
+        // leave its process running) over the stopped state this leaves behind.
+        this.teardownEpoch += 1;
+        this.starting = undefined;
+        this.clearIdleTimer();
+        this.parkSessions('the host is shutting down', 'shutdown');
+        this.conn?.close();
+        this.conn = undefined;
+        this.state = 'stopped';
+        this.initResult = undefined;
+        this.publishStatus();
+        await this.killChildAndWait(Math.max(0, deadline - Date.now()));
     }
     /**
      * Answer one ACP permission ask.
@@ -1837,6 +2015,16 @@ function codebuddyMetaOf(source) {
         out.isBackground = true;
     if (meta['codebuddy.ai/isSubagent'] === true)
         out.isSubagent = true;
+    const subagentType = meta['codebuddy.ai/subagentType'];
+    if (typeof subagentType === 'string' && subagentType !== '')
+        out.subagentType = subagentType;
+    const subagentDescription = meta['codebuddy.ai/description'];
+    if (typeof subagentDescription === 'string' && subagentDescription !== '') {
+        out.subagentDescription = subagentDescription;
+    }
+    const subagentName = meta['codebuddy.ai/memberName'];
+    if (typeof subagentName === 'string' && subagentName !== '')
+        out.subagentName = subagentName;
     const unsolicited = meta['codebuddy.ai/unsolicitedTurn'];
     if (typeof unsolicited === 'object' && unsolicited !== null) {
         const run = unsolicited;
@@ -2010,6 +2198,71 @@ export function permissionAskReason(toolCall) {
     const line = detail === undefined || detail === title ? title : `${title} · ${detail}`;
     return line.length > APPROVAL_REASON_MAX ? `${line.slice(0, APPROVAL_REASON_MAX - 1)}…` : line;
 }
+/** Longest label the host's subagent catalog row carries for an ACP worker. */
+const SUBAGENT_CATALOG_LABEL_MAX = 160;
+/** The structured input object an ACP tool call declared, if any. */
+function rawInputObjectOf(update) {
+    const raw = update.rawInput ?? update.arguments;
+    if (raw !== null && typeof raw === 'object' && !Array.isArray(raw))
+        return raw;
+    if (typeof raw === 'string' && raw.length <= 16_384) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * One line naming a detached ACP worker in the host's subagent catalog.
+ *
+ * The identity is read from what CodeBuddy actually sends, in order: the
+ * `_meta` keys on the dispatch call's result frames (`subagentType` /
+ * `description` / `memberName` — the FIRST `tool_call` omits `rawInput`, so
+ * these are often the only source), then the structured `rawInput`, then the
+ * tool title. The prompt body is only used when nothing shorter exists. Capped
+ * so a pathological input cannot fill the catalog row.
+ */
+export function subagentDispatchLabel(update) {
+    const meta = codebuddyMetaOf(update);
+    const input = rawInputObjectOf(update) ?? {};
+    const type = meta?.subagentType
+        ?? nonEmptyStringOf(input.subagent_type)
+        ?? nonEmptyStringOf(input.subagentType)
+        ?? permissionToolName(update);
+    const detail = meta?.subagentName
+        ?? nonEmptyStringOf(input.name)
+        ?? meta?.subagentDescription
+        ?? nonEmptyStringOf(input.description)
+        ?? nonEmptyStringOf(input.prompt);
+    const line = detail === undefined || detail === type ? type : `${type} · ${detail}`;
+    return line.length > SUBAGENT_CATALOG_LABEL_MAX ? `${line.slice(0, SUBAGENT_CATALOG_LABEL_MAX - 1)}…` : line;
+}
+/**
+ * Whether the update declared the worker's IDENTITY (role / task / name)
+ * rather than just restating the `Agent` tool. A bare dispatch names the tool
+ * as "Agent"; reporting that as the catalog label says nothing, so the report
+ * waits for one of these facts (or for the dispatch to complete).
+ */
+function subagentDispatchDeclaresIdentity(update) {
+    const meta = codebuddyMetaOf(update);
+    if (meta?.subagentType !== undefined
+        || meta?.subagentDescription !== undefined
+        || meta?.subagentName !== undefined)
+        return true;
+    const input = rawInputObjectOf(update);
+    if (input === undefined)
+        return false;
+    return ['subagent_type', 'subagentType', 'name', 'description', 'prompt']
+        .some(key => nonEmptyStringOf(input[key]) !== undefined);
+}
+function nonEmptyStringOf(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
 function snapshot(session) {
     return {
         sessionId: session.sessionId,
@@ -2490,8 +2743,141 @@ export function killProcessTree(pid) {
     try {
         const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
         killer.on('error', () => { });
+        // Handed back so a caller that wants to wait can; the existing
+        // fire-and-forget callers simply ignore it.
+        return killer;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every agent child this host started and has not seen exit yet, by pid. */
+const liveChildPids = new Set();
+/** Whether the process-exit reaper is already installed (installed once). */
+let exitReaperArmed = false;
+/** Remember a freshly spawned agent child for the last-resort reaper. */
+function trackAgentChild(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    liveChildPids.add(pid);
+    // Both events: `exit` is the process fact, `close` is it plus its stdio being
+    // closed. Whichever comes first forgets the pid.
+    const forget = () => { liveChildPids.delete(pid); };
+    child.once('exit', forget);
+    child.once('close', forget);
+    if (exitReaperArmed)
+        return;
+    exitReaperArmed = true;
+    process.once('exit', reapLiveChildren);
+}
+/**
+ * Last resort for a host that leaves without a graceful teardown: an unhandled
+ * crash that still runs `exit`, an explicit `process.exit()`, or a disposer the
+ * host never awaited. Only SYNC calls are legal here — the `exit` event cannot
+ * wait for a promise — hence `spawnSync` and a bare `process.kill`.
+ *
+ * Deliberately NOT a `SIGINT` / `SIGTERM` handler: registering one flips the
+ * host's own default disposition (killing the default "exit on Ctrl-C", or
+ * double-handling the host's shutdown and hanging it). A host that handles the
+ * signal itself still reaches `exit`; one that is SIGKILLed can run nothing at
+ * all (see AGENTS/protocol.md §7 for that limit).
+ */
+function reapLiveChildren() {
+    for (const pid of liveChildPids) {
+        try {
+            if (process.platform === 'win32') {
+                spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
+            }
+            else {
+                // The child was spawned `detached`, so it leads its own process group:
+                // -pid reaches everything it started (same reasoning as the graceful
+                // POSIX kill).
+                process.kill(-pid, 'SIGKILL');
+            }
+        }
+        catch { /* already gone, or no permission left to try */ }
     }
-    catch { /* spawn itself refused */ }
+    liveChildPids.clear();
+}
+/**
+ * End the child's stdin, dispatch the platform kill, and wait until the process
+ * is gone — bounded, and never rejecting.
+ *
+ * The escalation is deliberately platform-shaped: POSIX gets a process-GROUP
+ * `SIGKILL` (an agent that ignores SIGTERM is exactly what a second signal is
+ * for), Windows a second `taskkill /T /F` (the first may never have run at all:
+ * a failed spawn of `taskkill` is swallowed by `killProcessTree`).
+ */
+async function disposeChild(child, budgetMs) {
+    // ONE deadline for the whole disposal: the escalation wait comes out of the
+    // same budget, so `budgetMs` can never turn into "grace period + grace
+    // period" (see `KILL_ESCALATION_GRACE_MS`).
+    const deadline = Date.now() + Math.max(0, budgetMs);
+    try {
+        child.stdin?.end();
+    }
+    catch { /* already gone */ }
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    // A child that already exited may have had its pid reused: signalling it
+    // would reach an unrelated process (group). Nothing left to kill.
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const windows = process.platform === 'win32';
+    if (windows) {
+        // Parity with the POSIX branch, which kills the whole process GROUP: on
+        // Windows "the group" is the process tree, and it has to be killed while
+        // the tree is intact — killing the direct child first (a `cmd.exe` shim
+        // wrapper, see `windowsShimLaunch`) re-parents the agent out of
+        // `taskkill /T`'s reach. `stdin.end()` above is the graceful half.
+        killProcessTree(pid);
+    }
+    else {
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            child.kill('SIGTERM');
+        }
+    }
+    // Everything except the escalation slice: the second wait is only there to
+    // confirm a SIGKILL / taskkill landed, and it must fit inside the same budget.
+    if (await waitForChildExit(child, Math.max(0, budgetMs - KILL_ESCALATION_GRACE_MS)))
+        return;
+    if (windows) {
+        killProcessTree(pid);
+    }
+    else {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+    }
+    // Whatever is left of the deadline, never a fresh grace period.
+    await waitForChildExit(child, Math.max(0, deadline - Date.now()));
+}
+/** Resolve true once the child is gone, false when the budget runs out first. */
+function waitForChildExit(child, budgetMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        let timer;
+        const settle = (gone) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            child.off('exit', onGone);
+            child.off('close', onGone);
+            resolve(gone);
+        };
+        const onGone = () => { settle(true); };
+        timer = setTimeout(() => { settle(false); }, budgetMs);
+        // The host may exit while this waits; an armed timer must not hold it open.
+        timer.unref?.();
+        child.once('exit', onGone);
+        child.once('close', onGone);
+    });
 }
 /**
  * Globally install an agent's npm package. The package name reaches the
@@ -2910,9 +3296,11 @@ class TurnStreamController {
     pendingBackgroundHold;
     /**
      * The hold's own windows, read once at construction like the ambient pair:
-     * `taskMaxMs` is the worker phase's ceiling, `graceMs` the parked hold's
-     * bounded wait for a driver step (see {@link BridgeTuning.backgroundTaskMaxMs}
-     * and {@link BridgeTuning.backgroundParkedGraceMs}).
+     * `taskMaxMs` is the worker phase's silence window, `ceilingMs` the optional
+     * whole-hold absolute bound (0 = none), `graceMs` the parked hold's bounded
+     * wait for a driver step (see {@link BridgeTuning.backgroundTaskMaxMs} /
+     * {@link BridgeTuning.backgroundTaskCeilingMs} /
+     * {@link BridgeTuning.backgroundParkedGraceMs}).
      */
     backgroundTuning;
     /**
@@ -3157,11 +3545,13 @@ class TurnStreamController {
      * - marks the segment background, so EVERY tool call for the rest of the
      *   hold — the workers', the drain's TaskOutput — stays transcript-only and
      *   the final message carries text with no card in front of it;
-     * - waits in two phases: the worker phase only has the
-     *   {@link BridgeTuning.backgroundTaskMaxMs} ceiling (a detached worker goes
-     *   silent for tens of seconds while it works) and ends only when ALL known
-     *   dispatches reported, after which the drain phase uses the ambient
-     *   windows.
+     * - waits in two phases: the worker phase's clock is a SILENCE window
+     *   ({@link BridgeTuning.backgroundTaskMaxMs}) that every dispatch / worker
+     *   update pushes out, so a long task that keeps reporting is never cut at a
+     *   fixed total runtime. It ends when ALL known dispatches reported, after
+     *   which the drain phase uses the ambient windows. An optional absolute
+     *   ceiling ({@link BridgeTuning.backgroundTaskCeilingMs}, default none)
+     *   bounds a zombie that keeps talking forever.
      */
     holdForBackgroundDispatch(stopReason, requestId) {
         if (this.settled || this.disposed || this.closedTurn || this.stale)
@@ -3193,6 +3583,7 @@ class TurnStreamController {
         this.endTurn();
         hold.hardTimer = setTimeout(() => { this.onBackgroundHard(hold); }, this.backgroundTuning.taskMaxMs);
         hold.hardTimer.unref?.();
+        this.armBackgroundCeiling(hold);
         const seg = this.segment;
         if (seg !== undefined && !seg.finished) {
             this.adoptBackgroundHold(seg, hold);
@@ -3291,10 +3682,32 @@ class TurnStreamController {
         hold.quietTimer = setTimeout(() => { this.onBackgroundQuiet(hold); }, this.ambientTuning.quietMs);
         hold.quietTimer.unref?.();
     }
+    /**
+     * Evidence from a live dispatch / worker: the worker phase is SILENCE-based,
+     * so each update pushes its deadline out. A long task that keeps reporting is
+     * never cut at a fixed total runtime; only a genuinely quiet worker is.
+     */
+    noteBackgroundWorkerActivity() {
+        const hold = this.activeBackgroundHold();
+        if (hold === undefined || hold.phase !== 'worker' || hold.retired)
+            return;
+        if (hold.hardTimer !== undefined)
+            clearTimeout(hold.hardTimer);
+        hold.hardTimer = setTimeout(() => { this.onBackgroundHard(hold); }, this.backgroundTuning.taskMaxMs);
+        hold.hardTimer.unref?.();
+    }
+    /** Arm the hold's optional absolute ceiling (0 = unlimited). */
+    armBackgroundCeiling(hold) {
+        if (this.backgroundTuning.ceilingMs <= 0)
+            return;
+        hold.ceilingTimer = setTimeout(() => { this.onBackgroundHard(hold); }, this.backgroundTuning.ceilingMs);
+        hold.ceilingTimer.unref?.();
+    }
     /**
      * Any session update restarts the drain phase's quiet clock. Only an
-     * ADOPTED hold has one: a parked hold's wait belongs to its grace timer, and
-     * the worker phase never has a clock at all.
+     * ADOPTED hold has a quiet clock: a parked hold's wait belongs to its grace
+     * timer, and the worker phase is pushed forward only by dispatch / worker
+     * evidence (see `noteBackgroundWorkerActivity`).
      */
     noteBackgroundHoldActivity() {
         const hold = this.backgroundHold;
@@ -3308,7 +3721,7 @@ class TurnStreamController {
             return;
         this.closeBackgroundHold(hold, { hard: false });
     }
-    /** The hold outlived its ceiling (worker or drain): the run is still going. */
+    /** The hold went silent past its window, or outlived the absolute ceiling. */
     onBackgroundHard(hold) {
         if (hold !== this.backgroundHold && hold !== this.pendingBackgroundHold)
             return;
@@ -3378,10 +3791,13 @@ class TurnStreamController {
             clearTimeout(hold.quietTimer);
         if (hold.hardTimer !== undefined)
             clearTimeout(hold.hardTimer);
+        if (hold.ceilingTimer !== undefined)
+            clearTimeout(hold.ceilingTimer);
         if (hold.graceTimer !== undefined)
             clearTimeout(hold.graceTimer);
         hold.quietTimer = undefined;
         hold.hardTimer = undefined;
+        hold.ceilingTimer = undefined;
         hold.graceTimer = undefined;
     }
     /**
@@ -3525,10 +3941,15 @@ class TurnStreamController {
             const known = this.dispatches.get(toolCallId);
             if (known !== undefined) {
                 // A known dispatch: the id is the whole evidence (see the doc above).
+                this.noteBackgroundWorkerActivity();
                 if (status !== '')
                     known.status = status;
-                if (meta?.isBackground === true)
+                if (!known.catalogReported)
+                    this.refreshSubagentDispatchLabel(known, update);
+                if (meta?.isBackground === true) {
                     known.detached = true;
+                    this.reportSubagentDispatch(known);
+                }
                 if (completedStatus && !known.completed) {
                     known.completed = true;
                     this.noteDispatchProgress();
@@ -3545,8 +3966,14 @@ class TurnStreamController {
                     completed: completedStatus,
                     detached: meta.isBackground === true,
                     sawWorkerUpdate: false,
+                    catalogLabel: subagentDispatchLabel(update),
+                    catalogLabelIdentified: subagentDispatchDeclaresIdentity(update),
+                    catalogReported: false,
                 };
                 this.dispatches.set(toolCallId, dispatch);
+                this.noteBackgroundWorkerActivity();
+                if (dispatch.detached)
+                    this.reportSubagentDispatch(dispatch);
                 if (!dispatch.completed) {
                     const held = this.activeBackgroundHold();
                     // A dispatch registered after the drain phase began means new work:
@@ -3559,16 +3986,56 @@ class TurnStreamController {
         if (meta?.parentToolCallId !== undefined) {
             const parent = this.dispatches.get(meta.parentToolCallId);
             if (parent !== undefined) {
+                this.noteBackgroundWorkerActivity();
                 parent.detached = true;
                 parent.sawWorkerUpdate = true;
+                this.reportSubagentDispatch(parent);
             }
         }
         if (meta?.unsolicitedTurn !== undefined) {
             const held = this.activeBackgroundHold();
-            if (held !== undefined)
+            if (held !== undefined) {
+                this.noteBackgroundWorkerActivity();
                 this.startBackgroundDrain(held, meta.unsolicitedTurn.requestId);
+            }
+        }
+    }
+    /**
+     * Hand one DETACHED dispatch to the host's subagent catalog. One fact per
+     * tool call, and only once the wire's structure proves the work runs
+     * off-turn — a synchronous `Agent` / `Task` call is a tool call, not a
+     * catalog child.
+     */
+    reportSubagentDispatch(dispatch) {
+        if (dispatch.catalogReported)
+            return;
+        // A bare "Agent" row says nothing; wait for the identity frame. A
+        // completed dispatch reports with whatever it has — a row must not be
+        // lost because the agent never declared more than the tool name.
+        if (!dispatch.catalogLabelIdentified && !dispatch.completed)
+            return;
+        if (this.manager.reportSubagentCatalog(this.session, `acp:${dispatch.toolCallId}`, dispatch.catalogLabel)) {
+            dispatch.catalogReported = true;
         }
     }
+    /**
+     * Take a better label from a later frame of the SAME dispatch call.
+     *
+     * CodeBuddy omits `rawInput` (and often the title) on the dispatch call's
+     * first send, then restates the whole task identity in `_meta` on the result
+     * frame. A frame with no identity and no title is a bare status update and
+     * must not downgrade what is already known.
+     */
+    refreshSubagentDispatchLabel(dispatch, update) {
+        const identified = subagentDispatchDeclaresIdentity(update);
+        if (!identified && dispatch.catalogLabelIdentified)
+            return;
+        const title = update.title;
+        if (!identified && !(typeof title === 'string' && title !== ''))
+            return;
+        dispatch.catalogLabel = subagentDispatchLabel(update);
+        dispatch.catalogLabelIdentified = identified;
+    }
     /**
      * A dispatch just reported: once the LAST one has, the drain phase starts.
      * Until then the turn stays in its worker phase, with no quiet clock.
@@ -3576,6 +4043,10 @@ class TurnStreamController {
     noteDispatchProgress() {
         if (!this.allDispatchesCompleted())
             return;
+        // Last chance for a row still waiting on identity: completion is a fact
+        // even when the agent never said more than the tool name.
+        for (const dispatch of this.dispatches.values())
+            this.reportSubagentDispatch(dispatch);
         const held = this.activeBackgroundHold();
         if (held !== undefined)
             this.startBackgroundDrain(held);
@@ -4074,7 +4545,8 @@ class TurnStreamController {
             // background drain is still working, so the ambient quiet clock restarts.
             this.noteAmbientActivity();
             // A detached-worker hold's drain phase has the same rule; its worker
-            // phase never does (see `BridgeTuning.backgroundTaskMaxMs`).
+            // phase is pushed out only by dispatch / worker evidence (see
+            // `BridgeTuning.backgroundTaskMaxMs`).
             this.noteBackgroundHoldActivity();
             const update = typed.update;
             // The dispatch / worker / announcement bookkeeping runs BEFORE the cursor
@@ -4669,14 +5141,17 @@ export class BridgeManager {
     /**
      * The detached-worker hold's windows, read once at controller construction
      * for the same reason as {@link ambientTuning}: `taskMaxMs` is the worker
-     * phase's only clock (see {@link BridgeTuning.backgroundTaskMaxMs}) and
-     * `graceMs` the bounded wait a PARKED hold gives the host to open its
-     * continuation step (see {@link BridgeTuning.backgroundParkedGraceMs}). The
-     * drain phase reuses {@link ambientTuning}.
+     * phase's SILENCE window, pushed out by every dispatch / worker update (see
+     * {@link BridgeTuning.backgroundTaskMaxMs}), `ceilingMs` its optional
+     * absolute bound (0 = none) and `graceMs` the bounded wait a PARKED hold
+     * gives the host to open its continuation step (see
+     * {@link BridgeTuning.backgroundParkedGraceMs}). The drain phase reuses
+     * {@link ambientTuning}.
      */
     get backgroundTuning() {
         return {
             taskMaxMs: this.tuning.backgroundTaskMaxMs,
+            ceilingMs: this.tuning.backgroundTaskCeilingMs,
             graceMs: this.tuning.backgroundParkedGraceMs,
         };
     }
@@ -4885,6 +5360,33 @@ export class BridgeManager {
     setAcpModeResolver(resolver) {
         this.acpModeResolver = resolver;
     }
+    /**
+     * Optional host integration: report a detached ACP worker as an EXTERNAL
+     * child in the parent chat session's subagent catalog. Display-only — the
+     * host renders it as a read-only "external task" row with no child session,
+     * activity or continuation. An absent reporter is a no-op.
+     */
+    setSubagentCatalogReporter(reporter) {
+        this.subagentCatalogReporter = reporter;
+    }
+    /**
+     * Hand one detached worker to the host catalog. Returns whether a reporter
+     * handled it; a missing chat id or reporter leaves the dispatch unclaimed so
+     * a later wire update can retry.
+     */
+    reportSubagentCatalog(session, childId, label) {
+        const dshSessionId = session.dshSessionId;
+        const reporter = this.subagentCatalogReporter;
+        if (dshSessionId === undefined || reporter === undefined)
+            return false;
+        try {
+            reporter(dshSessionId, childId, label);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Whether ONE DSH chat session runs the ACP agent preset, asked by chat
      * session id. The browser's composer surfaces consume this: on hosts whose
@@ -6287,6 +6789,11 @@ export class BridgeManager {
         const def = this.defsMap.get(agentId);
         if (def === undefined || def.autoDiscoverModels === false || before === undefined)
             return false;
+        // A different model-slot identity is a corrected reading, not newly added
+        // models. Diffing across it would expose an entire real catalog the first
+        // time a parser fix replaces a mislabelled slot (Qoder CN).
+        if (before.model !== undefined && next.model !== undefined && before.model.configId !== next.model.configId)
+            return false;
         const known = new Set((before.model?.choices ?? []).map(choice => choice.value));
         const exposed = new Set(def.exposedModels ?? []);
         const added = (next.model?.choices ?? [])
@@ -6686,6 +7193,12 @@ export class BridgeManager {
         const wanted = modelChoice !== undefined && modelChoice !== '' ? modelChoice : undefined;
         if (wanted === undefined)
             return undefined;
+        // `category` is a UX hint, not identity: an agent may publish several
+        // `category: 'model'` options (Qoder CN ships `reasoning_effort` that way)
+        // and no explicit `model` id. In that case the selector is a guess, so a
+        // "not offered" verdict would refuse a perfectly valid pick — fail open.
+        if (!hasUnambiguousModelSelector(session.configOptions))
+            return undefined;
         const model = parseCatalogOptions(session.configOptions).model;
         if (model === undefined)
             return undefined;
@@ -7113,14 +7626,31 @@ export class BridgeManager {
         this.disposeTurnStreamsOf(controller => controller.session.agentId === agentId);
         await this.bridges.get(agentId)?.stop('agent-stopped');
     }
+    /**
+     * Host shutdown: park every conversation, then make sure no agent child
+     * outlives the host. Bridges run CONCURRENTLY against one bounded budget, so a
+     * single wedged agent cannot spend every other bridge's slice too.
+     *
+     * `/acp`'s "stop this agent" gesture is `stopAgent` → `stop`, which is a
+     * different promise: it closes the sessions on purpose. See
+     * `AgentBridge.shutdown` for why host exit must not.
+     */
     async shutdownAll() {
         if (this.stallTimer !== undefined) {
             clearInterval(this.stallTimer);
             this.stallTimer = undefined;
         }
-        this.dshSessionMap.clear();
         this.disposeTurnStreamsOf(() => true);
-        await Promise.all([...this.bridges.values()].map(b => b.stop('agent-stopped')));
+        // NOT cleared before the shutdown: `persistAgents` (called from
+        // `parkSessions`) writes the parked records out of `dshSessionMap`, and
+        // that write is what keeps the conversations resumable across the restart.
+        //
+        // `allSettled`, not `all`: one bridge's failure must neither skip the
+        // others nor reject a disposer that never asked for an answer. And NOT
+        // cleared afterwards either: a late `persistAgents` would then write
+        // `chatSessions: []` and erase exactly what the shutdown just saved. These
+        // records are terminal — nothing reads them again after disposal.
+        await Promise.allSettled([...this.bridges.values()].map(b => b.shutdown(SHUTDOWN_BUDGET_MS)));
     }
     /** Host-side reader of the harness preset roster (`ctx.agentPresets`), for `presetStatus`. */
     presetRosterReader;
@@ -7345,6 +7875,7 @@ export class BridgeManager {
     }
     sessionWorkspaceResolver;
     acpModeResolver;
+    subagentCatalogReporter;
     attachmentResolver;
     /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
     acpModeCache = new Map();
@@ -7352,8 +7883,8 @@ export class BridgeManager {
     acpModeInflight = new Map();
     /**
      * The agent values the composer is showing for a conversation that has not
-     * picked them — the catalog's current model, thought level and extra config
-     * values.
+     * picked them — the catalog's current model, thought level, mode and extra
+     * config values.
      *
      * Captured BEFORE `session/new`: materializing the session absorbs its own
      * defaults into the catalog (`absorbCatalog`), which would overwrite exactly
@@ -7374,6 +7905,15 @@ export class BridgeManager {
         const effort = this.reasoningMeta(agentId)?.defaultEffort;
         if (effort !== undefined)
             out.effort = effort;
+        // The mode select's pre-first-message value is the catalog's last-known
+        // mode (the agent's own answer from another session), and `session/new`
+        // starts on whatever the agent itself defaults to. Without capturing it,
+        // a conversation whose select reads "Bypass Permissions" would run its
+        // first turn on "Always Ask" — the same display/run split the model and
+        // thought level are seeded for.
+        const mode = catalog.mode?.currentValue;
+        if (mode !== null && mode !== undefined && mode !== '')
+            out.mode = mode;
         const extraConfigs = {};
         for (const option of catalog.extras ?? []) {
             const value = option.currentValue;
@@ -7396,14 +7936,15 @@ export class BridgeManager {
      * first prompt runs.
      *
      * A conversation with no explicit pick displays the agent catalog's current
-     * model / thought level / extras, while the ACP session `session/new` just
-     * created starts on whatever the agent itself defaults to. Without this the
-     * user is shown one model and the agent runs another — the defect reported
-     * as "the displayed model was not used". Values the fresh session does not
-     * offer are skipped (its `configOptions` are the authority, and the catalog
-     * update that rode `session/new` will correct the display), never turned
-     * into a failed first turn. Explicit picks always win: only missing fields
-     * are filled.
+     * model / thought level / mode / extras, while the ACP session `session/new`
+     * just created starts on whatever the agent itself defaults to. Without this
+     * the user is shown one model and the agent runs another — the defect
+     * reported as "the displayed model was not used", and the reported first
+     * turn that ignored the mode select's value. Values the fresh session does
+     * not offer are skipped (its `configOptions` are the authority, and the
+     * catalog update that rode `session/new` will correct the display), never
+     * turned into a failed first turn. Explicit picks always win: only missing
+     * fields are filled.
      */
     seedChatChoiceFromCatalog(dshSessionId, agentId, session, displayed) {
         if (displayed === undefined)
@@ -7429,6 +7970,18 @@ export class BridgeManager {
                 changed = true;
             }
         }
+        // The mode is the third axis of the same contract. The select's value
+        // before the first message is the catalog's last-known mode; `session/new`
+        // answers with the agent's own default. Seed the displayed one when the
+        // fresh session still offers it — an agent that publishes no `modes`
+        // field is applied best-effort, exactly like `applyChatChoice`.
+        const displayedMode = displayed.mode;
+        const offeredModes = session.modes?.availableModes ?? [];
+        if (current?.mode === undefined && displayedMode !== undefined
+            && (offeredModes.length === 0 || offeredModes.some(entry => entry.id === displayedMode))) {
+            patch.mode = displayedMode;
+            changed = true;
+        }
         if (displayed.extraConfigs !== undefined) {
             const extraConfigs = { ...(current?.agentId === agentId ? current.extraConfigs : undefined) };
             for (const [configId, value] of Object.entries(displayed.extraConfigs)) {
@@ -7630,6 +8183,44 @@ export class BridgeManager {
         });
         return { ok: true, reset: true };
     }
+    /**
+     * 聊天插话的槽位回收：宿主把插话作为同一会话在飞回合的下一步送达，
+     * 拒绝会让整条 host turn 失败。ACP 不能向运行中的 prompt 注入消息，
+     * 所以按插话语义中止当前回合，等 agent 真正结算后再让调用方重发。
+     *
+     * 只处理 `claimTurn` 的 `busy`（agent 仍持有本会话 prompt）；`unsettled`
+     * 说明我们这一侧已经释放过槽位（用户按过停止），保持原样拒绝。
+     *
+     * - 控制器已 settle（响应已到，延后收口还没释放闸门）：什么都不取消，只等闸门；
+     * - agent 真在跑：走用户取消同一条管线（session/cancel + 结算权限 + cancel fallback），
+     *   并立即关闭宿主这一侧的 segment，让闸门在 agent 应答/兜底后打开。
+     */
+    async reclaimChatPrompt(session, controller, signal) {
+        if (session.closed || session.released)
+            return 'ok';
+        if (!controller.hasSettled && session.promptInFlight === true) {
+            await this.bridge(session.agentId).cancel(session);
+            controller.abortActiveSegment();
+        }
+        return this.waitForSettleGate(session, signal);
+    }
+    /** 等 agent 侧 prompt slot 真正释放；步骤被取消时立即返回 aborted。 */
+    waitForSettleGate(session, signal) {
+        const pending = session.settled;
+        if (pending === undefined)
+            return Promise.resolve('ok');
+        if (signal?.aborted)
+            return Promise.resolve('aborted');
+        return new Promise(resolve => {
+            const done = (value) => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve(value);
+            };
+            const onAbort = () => { done('aborted'); };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            void pending.then(() => { done('ok'); });
+        });
+    }
     async *streamPrompt(options) {
         // The plugin's own conversation↔agent mapping decides who serves the turn
         // (see `bindChatAgent`): the driver may arrive here with the previous
@@ -7837,26 +8428,82 @@ export class BridgeManager {
         }
         // One prompt slot per session, and a turn the user aborted still occupies
         // the AGENT's slot until it acknowledges the cancel (see `claimTurn`).
-        const claim = await bridge.claimTurn(session);
+        let claim = await bridge.claimTurn(session);
         if (!claim.ok) {
-            // Never roll the provisional lock back here: a failed claim means ANOTHER
-            // prompt holds the slot (or the agent has not settled it), and that turn
-            // owns the conversation's lock. Closing the session would kill a turn
-            // that is actively streaming — the refusal already tells the user to
-            // retry.
-            yield {
-                type: 'finish',
-                reason: {
-                    kind: 'error',
-                    failure: {
-                        message: claim.reason === 'busy'
-                            ? 'acp: this session already has a prompt in flight'
-                            : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
-                        code: 'turn_in_flight',
+            // A STEER ("插话"): the host delivers the user's mid-turn message as the
+            // NEXT step of the SAME host turn, so the conversation's own ACP prompt
+            // is still on air. Refusing would fail the whole host turn. ACP forbids
+            // injecting into a running prompt, so the steer's real semantic — abort
+            // the current turn, then send this one — is spelled cancel + wait +
+            // re-claim here.
+            //
+            // Only `busy` can be a steer: it means the AGENT still holds OUR prompt
+            // (`promptInFlight`). `unsettled` means our side already released the
+            // slot (the person pressed stop, or an earlier steer cancelled): the
+            // agent has not acknowledged yet, and quietly queueing the next message
+            // behind a turn the user stopped is not this path's business — that
+            // stays the honest `turn_in_flight` refusal below.
+            //
+            // Only the conversation's OWN in-flight turn qualifies (its live stream
+            // controller, on this very session). A `/acp` RPC turn has no chat
+            // controller, and another conversation never reaches this session, so
+            // both keep the plain refusal: nothing may be cancelled behind a
+            // caller's back.
+            const chatController = claim.reason === 'busy' && options.sessionId !== undefined
+                ? this.turnStreamFor(options.sessionId)
+                : undefined;
+            if (options.sessionId !== undefined
+                && chatController !== undefined
+                && !chatController.stale
+                && chatController.session === session) {
+                const reclaimed = await this.reclaimChatPrompt(session, chatController, options.signal);
+                if (reclaimed === 'aborted') {
+                    // The person pressed stop while the previous turn was winding down:
+                    // the steer is theirs to re-send, nothing goes to the agent.
+                    yield {
+                        type: 'finish',
+                        reason: { kind: 'aborted', failure: { message: 'aborted', code: 'ABORTED' } },
+                    };
+                    return;
+                }
+                // A first turn that produced nothing rolled its provisional lock back
+                // and CLOSED (and forgot) this session: the steer needs a fresh one.
+                if (session.closed || session.released) {
+                    try {
+                        session = await this.getOrCreateDshSession(options.sessionId, agentId);
+                    }
+                    catch (err) {
+                        yield {
+                            type: 'finish',
+                            reason: { kind: 'error', failure: { message: describeError(err), code: 'session_init_failed' } },
+                        };
+                        return;
+                    }
+                }
+                // Same bridge: the session may have been re-created, but the
+                // conversation is still served by this agent's process.
+                claim = await bridge.claimTurn(session);
+            }
+            if (!claim.ok) {
+                // Never roll the provisional lock back here: a failed claim means
+                // ANOTHER prompt holds the slot (or the agent has not settled it), and
+                // that turn owns the conversation's lock. Closing the session would
+                // kill a turn that is actively streaming — the refusal already tells
+                // the user to retry.
+                yield {
+                    type: 'finish',
+                    reason: {
+                        kind: 'error',
+                        failure: {
+                            message: claim.reason === 'busy'
+                                ? 'acp: this session already has a prompt in flight'
+                                : 'acp: the agent is still finishing the previous (cancelled) turn; send again in a moment',
+                            code: 'turn_in_flight',
+                        },
                     },
-                },
-            };
-            return;
+                };
+                return;
+            }
         }
         // Same-agent model/effort switches ride the SAME ACP session (context
         // stays continuous); switching to another agent lands in a separate one