dsh-ntr 0.3.3 → 0.3.5

package/lib/impl.js

@@ -834,6 +834,42 @@ export function childEnv(parent, extra) {
     return out;
 }
 // ---- Model catalog (pure parsing of ACP `configOptions`) ----
+/**
+ * ACP categories are free-form UX hints, not identity. Qoder CN tags
+ * `reasoning_effort` as `category: 'model'` (the spec means `thought_level`),
+ * and nothing stops an agent from reusing a category for several options.
+ * Slots are therefore assigned by `configId` first and category second, and a
+ * same-category option NEVER replaces another option's slot: whatever loses
+ * stays reachable through `extras` instead of silently becoming the model list.
+ */
+const EFFORT_OPTION_HINT = /effort|thinking|thought|reason/i;
+function isModelSelector(configId, name) {
+    return configId === 'model' || name.trim().toLowerCase() === 'model';
+}
+function catalogSlotFor(category, configId, name) {
+    const effortish = EFFORT_OPTION_HINT.test(configId) || EFFORT_OPTION_HINT.test(name);
+    if (category === 'model') {
+        // The option explicitly named `model` is the selector even when other
+        // model-scoped options are present.
+        if (isModelSelector(configId, name))
+            return { slot: 'model', rank: 3 };
+        // A model-scoped effort is mislabelled, not a model: route it to the
+        // thought chip when no real `thought_level` option is published.
+        if (effortish)
+            return { slot: 'thought', rank: 1 };
+        // An unknown model-scoped select: a last-resort selector only.
+        return { slot: 'model', rank: 1 };
+    }
+    if (category === 'thought_level')
+        return { slot: 'thought', rank: 3 };
+    if (category === 'mode')
+        return { slot: 'mode', rank: 2 };
+    // `model_config` is where the spec puts model-dependent knobs (effort,
+    // context size); only the effort-shaped ones have a dedicated control.
+    if (category === 'model_config' && effortish)
+        return { slot: 'thought', rank: 1 };
+    return undefined;
+}
 /**
  * Extract select options from a raw ACP `configOptions` payload.
  *
@@ -848,19 +884,13 @@ export function parseCatalogOptions(configOptions) {
     const out = {};
     if (!Array.isArray(configOptions))
         return out;
-    const extras = new Map();
+    const definitions = [];
+    const candidates = [];
     for (const raw of configOptions) {
         if (typeof raw !== 'object' || raw === null)
             continue;
         const row = raw;
         const category = typeof row.category === 'string' ? row.category : undefined;
-        const slot = category === 'model'
-            ? 'model'
-            : category === 'thought_level'
-                ? 'thought'
-                : category === 'mode'
-                    ? 'mode'
-                    : undefined;
         const configIdRaw = row.configId ?? row.id;
         if (typeof configIdRaw !== 'string' && typeof configIdRaw !== 'number')
             continue;
@@ -869,6 +899,7 @@ export function parseCatalogOptions(configOptions) {
             continue;
         const choices = [];
         collectCatalogChoices(row.options, choices);
+        const name = typeof row.name === 'string' && row.name !== '' ? row.name : configId;
         // A boolean toggle has no `options` at all; its current value is a JSON
         // boolean. It is encoded as 'true' / 'false' so the catalog stays
         // string-typed for every existing reader, and carries `kind` so the
@@ -877,7 +908,7 @@ export function parseCatalogOptions(configOptions) {
             || (typeof row.currentValue === 'boolean' && choices.length === 0);
         const option = {
             configId,
-            name: typeof row.name === 'string' && row.name !== '' ? row.name : configId,
+            name,
             ...(booleanKind ? { kind: 'boolean' } : {}),
             currentValue: booleanKind
                 ? row.currentValue === true || row.currentValue === 'true'
@@ -886,22 +917,81 @@ export function parseCatalogOptions(configOptions) {
                 : typeof row.currentValue === 'string' && row.currentValue !== '' ? row.currentValue : null,
             choices,
         };
+        definitions.push(option);
         // A toggle is never a model / thought / mode SELECT: those controls pick
         // among choices. It belongs to the advanced base, where it is a checkbox.
-        if (slot !== undefined && !booleanKind) {
-            out[slot] = option;
+        if (booleanKind)
             continue;
+        const slot = catalogSlotFor(category, configId, name);
+        if (slot !== undefined)
+            candidates.push({ ...slot, option });
+    }
+    const winnerIds = new Set();
+    for (const slot of ['model', 'thought', 'mode']) {
+        let winner;
+        for (const candidate of candidates) {
+            if (candidate.slot !== slot)
+                continue;
+            if (winner === undefined || candidate.rank > winner.rank) {
+                winner = candidate;
+            }
+            else if (candidate.rank === winner.rank && candidate.option.configId === winner.option.configId) {
+                // The same option redefined later in one answer: the last definition
+                // is the current one.
+                winner = candidate;
+            }
         }
-        // Choice-less options have nothing to pick; they would render an empty
-        // section in the advanced menu, so they stay out of the catalog entirely —
-        // except a boolean, whose whole point is that it has no choices.
-        if (choices.length > 0 || booleanKind)
-            extras.set(configId, option);
+        if (winner === undefined)
+            continue;
+        out[slot] = winner.option;
+        winnerIds.add(winner.option.configId);
+    }
+    // Choice-less options have nothing to pick; they would render an empty
+    // section in the advanced menu, so they stay out of the catalog entirely —
+    // except a boolean, whose whole point is that it has no choices. Anything
+    // that lost a slot race is still a real, settable option: keep it here.
+    const extras = new Map();
+    for (const option of definitions) {
+        if (winnerIds.has(option.configId))
+            continue;
+        if (option.choices.length > 0 || option.kind === 'boolean')
+            extras.set(option.configId, option);
     }
     if (extras.size > 0)
         out.extras = [...extras.values()];
     return out;
 }
+/**
+ * Whether a payload names ONE model selector without relying on category
+ * alone. When an agent publishes several `category: 'model'` options and none
+ * is explicitly the `model` id, the category is not trustworthy enough to
+ * reject the user's pick — callers must fail open instead of reporting
+ * `model_unavailable`.
+ */
+export function hasUnambiguousModelSelector(configOptions) {
+    if (!Array.isArray(configOptions))
+        return true;
+    let scoped = 0;
+    let explicit = false;
+    for (const raw of configOptions) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const row = raw;
+        if (row.category !== 'model')
+            continue;
+        const configIdRaw = row.configId ?? row.id;
+        if (typeof configIdRaw !== 'string' && typeof configIdRaw !== 'number')
+            continue;
+        const configId = String(configIdRaw);
+        if (configId === '')
+            continue;
+        scoped += 1;
+        const name = typeof row.name === 'string' ? row.name : '';
+        if (isModelSelector(configId, name))
+            explicit = true;
+    }
+    return explicit || scoped <= 1;
+}
 /**
  * Fold one per-session option answer's SHAPE into an agent-level catalog.
  *
@@ -2486,6 +2576,38 @@ export function isUnderPath(path, root) {
         return path.startsWith('/') && !isWin32Style(path);
     return trimmedPath === trimmedRoot || trimmedPath.startsWith(`${trimmedRoot}/`);
 }
+/**
+ * Record one ACP-side worker in the host's parent-owned subagent catalog as an
+ * EXTERNAL execution. Display-only: external entries have no child session, no
+ * activity/timing and no continuation, and `list_agents` omits them. The
+ * catalog is append-only, so a replayed/resumed dispatch must never add the
+ * same `childId` twice. Returns whether a new fact was appended.
+ */
+export function appendExternalSubagentCatalog(session, childId, label, now = Date.now()) {
+    if (childId === '' || session?.append === undefined)
+        return false;
+    const events = session.events;
+    if (Array.isArray(events)) {
+        for (let index = events.length - 1; index >= 0; index -= 1) {
+            const event = events[index];
+            if (event?.type === 'subagent/catalog' && event.data?.childId === childId)
+                return false;
+        }
+    }
+    try {
+        session.append('subagent/catalog', {
+            version: 2,
+            childId,
+            childCreatedAt: now,
+            mode: 'external',
+            label,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The agent preset a session actually runs.
  *

package/lib/index.js

@@ -5,7 +5,7 @@
  * hide the loader metadata — see harness postmortem 0001).
  */
 import { ACP_PRESET_ID, AcpLlmAdapter, BridgeManager, PLUGIN_VERSION } from "./bridge.js";
-import { EventHub, dispatchRpc, permissionReplayFrames, sessionAgentPreset, sessionAgentPresetFromLog, validateConfig } from "./impl.js";
+import { appendExternalSubagentCatalog, EventHub, dispatchRpc, permissionReplayFrames, sessionAgentPreset, sessionAgentPresetFromLog, validateConfig } from "./impl.js";
 import { UpdateService } from "./update.js";
 export const name = 'dsh-ntr';
 // Deliberately minimal: every other host service is probed structurally
@@ -200,6 +200,28 @@ export function apply(ctx, config) {
             return undefined;
         }
     };
+    /**
+     * Optional host integration: record detached ACP workers as EXTERNAL
+     * children in the parent chat session's subagent catalog. Display-only — the
+     * host renders them as read-only "external task" rows with no child
+     * session, activity or continuation — and is skipped silently on hosts
+     * without the catalog event.
+     */
+    const wireSubagentCatalog = () => {
+        const sessions = (typeof ctx.get === 'function' ? ctx.get('sessions') : undefined);
+        if (sessions === undefined)
+            return;
+        manager.setSubagentCatalogReporter((dshSessionId, childId, label) => {
+            let session;
+            try {
+                session = sessions.get(dshSessionId);
+            }
+            catch {
+                return;
+            }
+            appendExternalSubagentCatalog(session, childId, label);
+        });
+    };
     wireWorkspace();
     if (typeof ctx.inject === 'function') {
         // Late arrival for the workspace collaborators: a deployment missing one
@@ -211,9 +233,11 @@ export function apply(ctx, config) {
     // The ACP-preset verdict only needs the session store (live) and the
     // persistence store (cold); the sandbox knobs are NOT its dependencies.
     wireAcpMode();
+    wireSubagentCatalog();
     if (typeof ctx.inject === 'function') {
         ctx.inject(['sessions'], () => {
             wireAcpMode();
+            wireSubagentCatalog();
         });
     }
     const wireAttachments = (injectedCtx) => {

package/lib/types/bridge.d.ts

@@ -6,6 +6,7 @@
  * Connection RPC channel (authenticated) into `BridgeManager`, which is the
  * only object allowed to spawn a configured command.
  */
+import { type ChildProcess } from 'node:child_process';
 import { type ContentBlock, type InitializeResponse } from '@agentclientprotocol/sdk';
 import { EventHub, PermissionLedger, Transcript } from './impl.ts';
 import type { AcpToolCallSnapshot, PendingPermissionView, RosterPresetRow } from './impl.ts';
@@ -358,20 +359,33 @@ export interface BridgeTuning {
      */
     ambientMaxMs?: number;
     /**
-     * The hard ceiling on the WORKER phase of a detached-worker hold (see
-     * `TurnStreamController.holdForBackgroundDispatch`): the turn dispatched one
-     * or more background workers through `Agent` tool calls, the agent answered
-     * the prompt, and at least one worker has not reported back yet. The worker
-     * phase has NO quiet window on purpose — measured against CodeBuddy 2.179.0,
-     * a detached worker's own updates are 13–24s apart while it is perfectly
-     * alive — so only EVERY known dispatch reporting (completed / failed) or
-     * this ceiling can end it; a drain announcement is recorded but arms no
-     * clock before then. Once they have all reported, the drain's own
+     * How long the WORKER phase of a detached-worker hold may go WITHOUT any
+     * evidence from the worker (see `TurnStreamController.holdForBackgroundDispatch`):
+     * the turn dispatched one or more background workers through `Agent` tool
+     * calls, the agent answered the prompt, and at least one worker has not
+     * reported back yet. There is still no quiet clock in the ambient sense —
+     * measured against CodeBuddy 2.179.0, a detached worker's own updates are
+     * 13–24s apart while it is perfectly alive — so every update naming the
+     * dispatch or carrying its `parentToolCallId` PUSHES THIS WINDOW OUT. Only a
+     * genuinely silent worker, or every known dispatch reporting (completed /
+     * failed), ends the phase; a drain announcement is recorded but arms no
+     * quiet clock before then. Once they have all reported, the drain's own
      * `ambientQuietMs` / `ambientMaxMs` windows take over.
      *
-     * Default 600000 ms (10 minutes).
+     * Default 600000 ms (10 minutes of silence, not of total runtime).
      */
     backgroundTaskMaxMs?: number;
+    /**
+     * Optional ABSOLUTE ceiling on a detached-worker hold, both phases included.
+     * `backgroundTaskMaxMs` keeps an ACTIVE worker alive indefinitely; this is
+     * the emergency bound for a zombie that keeps emitting updates forever.
+     * `0` disables it — the turn can then stay open as long as the worker keeps
+     * proving it is alive, and the person can still steer/cancel the hold by
+     * sending a message.
+     *
+     * Default 0 (no ceiling).
+     */
+    backgroundTaskCeilingMs?: number;
     /**
      * How long a PARKED detached-worker hold may wait for the host to open the
      * driver step that carries the worker's report. The prompt response landed
@@ -410,6 +424,11 @@ export type SessionWorkspaceResolver = (dshSessionId: string) => {
  * browser's seat gate, which polls.
  */
 export type AcpModeResolver = (dshSessionId: string) => boolean | undefined | Promise<boolean | undefined>;
+/**
+ * Report one detached ACP worker to the host's parent-owned subagent catalog.
+ * Display-only: the host records an EXTERNAL execution with no child session.
+ */
+export type SubagentCatalogReporter = (dshSessionId: string, childId: string, label: string) => void;
 type BridgeState = 'stopped' | 'starting' | 'ready' | 'error';
 export declare class AgentBridge {
     readonly def: AcpAgentDef;
@@ -452,6 +471,24 @@ export declare class AgentBridge {
     stderrTail: string[];
     private child?;
     private 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.
+     */
+    private teardownEpoch;
     private starting?;
     private readonly sessions;
     private readonly acpIndex;
@@ -733,6 +770,11 @@ export declare class AgentBridge {
      *   it.
      */
     ensureReady(spawnCwd?: string): Promise<void>;
+    /**
+     * @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`).
+     */
     private spawnAndConnect;
     /**
      * Bound one agent-startup request (`initialize`, `session/new`,
@@ -864,8 +906,31 @@ export declare class AgentBridge {
      */
     resumeSession(session: LiveSession): Promise<LiveSession>;
     private doResumeSession;
-    /** 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: string, cause: AcpReleaseCause): void;
+    /**
+     * 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).
+     */
+    private parkSessions;
     /** Detach one released session record for a resume attempt. */
     takeReleased(sessionId: string): LiveSession | undefined;
     /** Drop a released session record for good (user closed it or the agent was stopped). */
@@ -901,7 +966,43 @@ export declare class AgentBridge {
      * message. This is a stop, not a discard.
      */
     forceReset(reason: 'agent-stopped'): void;
+    /**
+     * 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.
+     */
     private killChild;
+    /**
+     * 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.
+     */
+    private killChildAndWait;
+    /**
+     * 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.
+     */
+    shutdown(budgetMs?: number): Promise<void>;
     /**
      * Answer one ACP permission ask.
      *
@@ -982,6 +1083,17 @@ export declare function permissionToolName(toolCall: unknown): string;
  * capped so a pathological input cannot fill the card or the audit log.
  */
 export declare function permissionAskReason(toolCall: unknown): string;
+/**
+ * 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 declare function subagentDispatchLabel(update: Record<string, unknown>): string;
 /**
  * This plugin's OWN state directory, `~/.dsh/dsh-ntr`.
  *
@@ -1077,7 +1189,7 @@ export declare function windowsShimLaunch(command: string, args: readonly string
  * Best effort — `taskkill` is absent from no Windows this runs on, and a
  * failure here only means the OS reclaims the process later.
  */
-export declare function killProcessTree(pid: number): void;
+export declare function killProcessTree(pid: number): ChildProcess | undefined;
 /**
  * Globally install an agent's npm package. The package name reaches the
  * installer as a spawn argv item; on Windows the installer needs a shell,
@@ -1351,9 +1463,11 @@ declare class TurnStreamController {
     private 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}).
      */
     private readonly backgroundTuning;
     /**
@@ -1455,11 +1569,13 @@ declare 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: string, requestId?: string): void;
     /** Give a (possibly parked) hold a driver segment: cards off for the rest of it. */
@@ -1483,15 +1599,24 @@ declare class TurnStreamController {
     private enterBackgroundWorkerPhase;
     /** Push the drain phase's quiet clock out: every update is evidence of work. */
     private armBackgroundQuiet;
+    /**
+     * 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.
+     */
+    private noteBackgroundWorkerActivity;
+    /** Arm the hold's optional absolute ceiling (0 = unlimited). */
+    private armBackgroundCeiling;
     /**
      * 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`).
      */
     private noteBackgroundHoldActivity;
     /** The drained run went quiet: the turn ends with the stop reason the response gave. */
     private onBackgroundQuiet;
-    /** 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. */
     private onBackgroundHard;
     /**
      * No driver step opened inside the grace: the host is not coming back for
@@ -1566,6 +1691,22 @@ declare class TurnStreamController {
      * - an `unsolicitedTurn` announcement is the drain that carries the report.
      */
     private trackBackgroundDispatch;
+    /**
+     * 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.
+     */
+    private reportSubagentDispatch;
+    /**
+     * 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.
+     */
+    private refreshSubagentDispatchLabel;
     /**
      * 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.
@@ -1843,13 +1984,16 @@ export declare 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(): {
         taskMaxMs: number;
+        ceilingMs: number;
         graceMs: number;
     };
     /** Index a turn's controller, retiring whatever turn it supersedes. */
@@ -1910,6 +2054,19 @@ export declare class BridgeManager {
      * falls back to its own session-list rows.
      */
     setAcpModeResolver(resolver?: AcpModeResolver): void;
+    /**
+     * 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?: SubagentCatalogReporter): void;
+    /**
+     * 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: LiveSession, childId: string, label: string): boolean;
     /**
      * 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
@@ -2505,6 +2662,15 @@ export declare class BridgeManager {
     };
     sessions(): unknown[];
     stopAgent(agentId: string): Promise<void>;
+    /**
+     * 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.
+     */
     shutdownAll(): Promise<void>;
     /** Host-side reader of the harness preset roster (`ctx.agentPresets`), for `presetStatus`. */
     private presetRosterReader?;
@@ -2619,6 +2785,7 @@ export declare class BridgeManager {
     private forgetDshSession;
     private sessionWorkspaceResolver?;
     private acpModeResolver?;
+    private subagentCatalogReporter?;
     private attachmentResolver?;
     /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
     private readonly acpModeCache;
@@ -2626,8 +2793,8 @@ export declare class BridgeManager {
     private readonly acpModeInflight;
     /**
      * 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
@@ -2640,14 +2807,15 @@ export declare 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.
      */
     private seedChatChoiceFromCatalog;
     getOrCreateDshSession(dshSessionId: string | undefined, agentId: string, cwd?: string): Promise<LiveSession>;
@@ -2667,6 +2835,21 @@ export declare class BridgeManager {
      * user is told the context is gone.
      */
     private prepareStalledSession;
+    /**
+     * 聊天插话的槽位回收：宿主把插话作为同一会话在飞回合的下一步送达，
+     * 拒绝会让整条 host turn 失败。ACP 不能向运行中的 prompt 注入消息，
+     * 所以按插话语义中止当前回合，等 agent 真正结算后再让调用方重发。
+     *
+     * 只处理 `claimTurn` 的 `busy`（agent 仍持有本会话 prompt）；`unsettled`
+     * 说明我们这一侧已经释放过槽位（用户按过停止），保持原样拒绝。
+     *
+     * - 控制器已 settle（响应已到，延后收口还没释放闸门）：什么都不取消，只等闸门；
+     * - agent 真在跑：走用户取消同一条管线（session/cancel + 结算权限 + cancel fallback），
+     *   并立即关闭宿主这一侧的 segment，让闸门在 agent 应答/兜底后打开。
+     */
+    private reclaimChatPrompt;
+    /** 等 agent 侧 prompt slot 真正释放；步骤被取消时立即返回 aborted。 */
+    private waitForSettleGate;
     streamPrompt(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
 export declare class AcpLlmAdapter implements LlmAdapterLike {