dsh-ntr 0.3.4 → 0.3.5

package/src/bridge.ts

@@ -7,7 +7,7 @@
  * only object allowed to spawn a configured command.
  */
 
-import { spawn, type ChildProcess } from 'node:child_process'
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process'
 import { homedir } from 'node:os'
 import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -108,10 +108,47 @@ const FS_MAX_WRITE_BYTES = 2 * 1024 * 1024
  */
 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
+
 /** What the composer showed for an agent before a conversation picked it. */
 interface DisplayedChatDefaults {
   modelId?: string
   effort?: string
+  /** The agent's last-known mode (the composer's select without a pick). */
+  mode?: string
   extraConfigs?: Record<string, string | boolean>
 }
 
@@ -458,20 +495,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
@@ -511,6 +561,12 @@ export type SessionWorkspaceResolver = (dshSessionId: string) => { workspaceRoot
  */
 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
+
 /**
  * The plugin's normalized MCP server shape → the ACP wire shape.
  *
@@ -579,6 +635,7 @@ const DEFAULT_TUNING: Required<BridgeTuning> = {
   ambientQuietMs: 10_000,
   ambientMaxMs: 120_000,
   backgroundTaskMaxMs: 600_000,
+  backgroundTaskCeilingMs: 0,
   backgroundParkedGraceMs: 30_000,
   ambientStaleMs: 300_000,
 }
@@ -593,6 +650,24 @@ export class AgentBridge {
 
   private child?: ChildProcess
   private conn?: ClientConnection
+  /**
+   * 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 = 0
   private starting?: Promise<void>
   private readonly sessions = new Map<string, LiveSession>()
   private readonly acpIndex = new Map<string, LiveSession>()
@@ -1065,10 +1140,19 @@ export class AgentBridge {
     }
     if (this.state === 'ready' && this.conn !== undefined) 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()
@@ -1077,6 +1161,16 @@ export class AgentBridge {
         this.touch()
       })
       .catch((error: unknown) => {
+        // 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()
@@ -1084,16 +1178,30 @@ 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
   }
 
-  private async spawnAndConnect(): 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 async spawnAndConnect(epoch: number): Promise<void> {
     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 ?? [])
@@ -1109,6 +1217,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
@@ -1168,6 +1277,25 @@ export class AgentBridge {
       }),
       '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
@@ -1614,13 +1742,17 @@ 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
@@ -1686,9 +1818,42 @@ export class AgentBridge {
     }
   }
 
-  /** 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 {
     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).
+   */
+  private parkSessions(reason: string, cause: AcpReleaseCause): number {
+    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
@@ -1710,19 +1875,15 @@ 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. */
@@ -1864,6 +2025,13 @@ export class AgentBridge {
 
   /** Kill the child and drop every local session bound to this connection. */
   async stop(reason: 'closed' | 'agent-stopped' | 'agent-died' = 'agent-stopped'): Promise<void> {
+    // 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)
@@ -1890,6 +2058,8 @@ export class AgentBridge {
    * message. This is a stop, not a discard.
    */
   forceReset(reason: 'agent-stopped'): void {
+    this.teardownEpoch += 1
+    this.starting = undefined
     this.clearIdleTimer()
     for (const session of [...this.sessions.values()]) {
       session.closed = true
@@ -1909,6 +2079,13 @@ export class AgentBridge {
     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.
+   */
   private killChild(): void {
     const child = this.child
     this.child = undefined
@@ -1916,31 +2093,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) 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)
-      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()
+    if (child === undefined) return
+    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.
+   */
+  private async killChildAndWait(budgetMs: number): Promise<void> {
+    const child = this.child
+    this.child = undefined
+    this.spawnCwd = undefined
+    if (child === undefined) return
+    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: number = SHUTDOWN_BUDGET_MS): Promise<void> {
+    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()))
   }
 
   /**
@@ -2344,6 +2549,15 @@ interface CodebuddyMeta {
   isBackground?: boolean
   /** `codebuddy.ai/isSubagent` — the same re-send declares the worker a sub-agent. */
   isSubagent?: boolean
+  /**
+   * `codebuddy.ai/subagentType` / `codebuddy.ai/description` /
+   * `codebuddy.ai/memberName` — the worker's identity. CodeBuddy omits the
+   * dispatch call's `rawInput` on its first send (repl display), so these meta
+   * keys are the ONLY place the assigned role and task line can be read.
+   */
+  subagentType?: string
+  subagentDescription?: string
+  subagentName?: string
 }
 
 /** Read the CodeBuddy `_meta` keys off an update or a `{ _meta }` wrapper. */
@@ -2368,6 +2582,14 @@ function codebuddyMetaOf(source: unknown): CodebuddyMeta | undefined {
   // and guessing from it would make another agent's unrelated key look detached.
   if (meta['codebuddy.ai/isBackground'] === true) 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 as Record<string, unknown>
@@ -2541,6 +2763,71 @@ export function permissionAskReason(toolCall: unknown): string {
   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: Record<string, unknown>): Record<string, unknown> | undefined {
+  const raw = update.rawInput ?? update.arguments
+  if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) return raw as Record<string, unknown>
+  if (typeof raw === 'string' && raw.length <= 16_384) {
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as Record<string, unknown>
+    } 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: Record<string, unknown>): string {
+  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: Record<string, unknown>): boolean {
+  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: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
 function snapshot(session: LiveSession): SessionView {
   return {
     sessionId: session.sessionId,
@@ -3075,11 +3362,135 @@ export function windowsShimLaunch(
  * Best effort — `taskkill` is absent from no Windows this runs on, and a
  * failure here only means the OS reclaims the process later.
  */
-export function killProcessTree(pid: number): void {
+export function killProcessTree(pid: number): ChildProcess | undefined {
   try {
     const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true })
     killer.on('error', () => { /* nothing else to try; the OS reaps it eventually */ })
-  } catch { /* spawn itself refused */ }
+    // 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<number>()
+/** 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: ChildProcess): void {
+  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 = (): void => { 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(): void {
+  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 */ }
+  }
+  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: ChildProcess, budgetMs: number): Promise<void> {
+  // 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: ChildProcess, budgetMs: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
+  return new Promise<boolean>((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const settle = (gone: boolean): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      child.off('exit', onGone)
+      child.off('close', onGone)
+      resolve(gone)
+    }
+    const onGone = (): void => { 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)
+  })
 }
 
 /**
@@ -3519,6 +3930,12 @@ interface BackgroundDispatch {
   detached: boolean
   /** Whether any update came FROM the worker (`codebuddy.ai/parentToolCallId`). */
   sawWorkerUpdate: boolean
+  /** One-line label for the host's subagent catalog, refreshed until reported. */
+  catalogLabel: string
+  /** Whether `catalogLabel` carries the worker's identity, not just the tool name. */
+  catalogLabelIdentified: boolean
+  /** Whether the host catalog already accepted this dispatch (one fact per call). */
+  catalogReported: boolean
 }
 
 /**
@@ -3526,10 +3943,12 @@ interface BackgroundDispatch {
  *
  * Two phases, because their liveness signals differ:
  * - `worker`: at least one worker runs off-turn and may be silent for tens of
- *   seconds between model calls — NO quiet timer, only
- *   {@link BridgeTuning.backgroundTaskMaxMs}. It ends when EVERY known dispatch
- *   reported (completed / failed); a drain announcement is recorded meanwhile
- *   but arms no clock.
+ *   seconds between model calls — its clock is a SILENCE window
+ *   ({@link BridgeTuning.backgroundTaskMaxMs}) pushed out by every dispatch /
+ *   worker update, plus an optional whole-hold ceiling
+ *   ({@link BridgeTuning.backgroundTaskCeilingMs}). It ends when EVERY known
+ *   dispatch reported (completed / failed); a drain announcement is recorded
+ *   meanwhile but arms no clock.
  * - `drain`: every dispatch reported and the background turn that carries
  *   their report is (or is about to start) — the existing ambient windows
  *   apply (`ambientQuietMs` quiet, reset by every update; `ambientMaxMs`
@@ -3564,7 +3983,8 @@ interface BackgroundHold {
   floorSeq: number
   quietTimer?: ReturnType<typeof setTimeout>
   hardTimer?: ReturnType<typeof setTimeout>
-  /**
+  /** Absolute whole-hold ceiling; absent when the tuning disables it (0). */
+  ceilingTimer?: ReturnType<typeof setTimeout>  /**
    * The bounded wait for a driver step to speak into. Only while the hold is
    * PARKED (`pendingBackgroundHold`): the response landed between steps, and
    * the host is expected to open the continuation step for the Agent card.
@@ -3681,11 +4101,13 @@ class TurnStreamController {
   private pendingBackgroundHold?: BackgroundHold
   /**
    * 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: { taskMaxMs: number; graceMs: number }
+  private readonly backgroundTuning: { taskMaxMs: number; ceilingMs: number; graceMs: number }
   /**
    * When this controller was built. Only a drain announced AFTER this moment
    * may be adopted by the hold: an `ambient` record that predates the turn is
@@ -3935,11 +4357,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: string, requestId?: string): void {
     if (this.settled || this.disposed || this.closedTurn || this.stale) return
@@ -3967,6 +4391,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)
@@ -4058,10 +4483,31 @@ class TurnStreamController {
     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.
+   */
+  private noteBackgroundWorkerActivity(): void {
+    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). */
+  private armBackgroundCeiling(hold: BackgroundHold): void {
+    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`).
    */
   private noteBackgroundHoldActivity(): void {
     const hold = this.backgroundHold
@@ -4075,7 +4521,7 @@ class TurnStreamController {
     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. */
   private onBackgroundHard(hold: BackgroundHold): void {
     if (hold !== this.backgroundHold && hold !== this.pendingBackgroundHold) return
     this.closeBackgroundHold(hold, { hard: true })
@@ -4143,9 +4589,11 @@ class TurnStreamController {
   private clearBackgroundHoldTimers(hold: BackgroundHold): void {
     if (hold.quietTimer !== undefined) 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
   }
 
@@ -4282,8 +4730,13 @@ 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) known.detached = 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()
@@ -4299,8 +4752,13 @@ 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:
@@ -4312,22 +4770,64 @@ 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) this.startBackgroundDrain(held, meta.unsolicitedTurn.requestId)
+      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.
+   */
+  private reportSubagentDispatch(dispatch: BackgroundDispatch): void {
+    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.
+   */
+  private refreshSubagentDispatchLabel(dispatch: BackgroundDispatch, update: Record<string, unknown>): void {
+    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.
    */
   private noteDispatchProgress(): void {
     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)
   }
@@ -4810,7 +5310,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 as Record<string, unknown>
       // The dispatch / worker / announcement bookkeeping runs BEFORE the cursor
@@ -5376,14 +5877,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}.
-   */
-  get backgroundTuning(): { taskMaxMs: number; graceMs: number } {
+   * 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 } {
     return {
       taskMaxMs: this.tuning.backgroundTaskMaxMs,
+      ceilingMs: this.tuning.backgroundTaskCeilingMs,
       graceMs: this.tuning.backgroundParkedGraceMs,
     }
   }
@@ -5603,6 +6107,33 @@ export class BridgeManager {
     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?: SubagentCatalogReporter): void {
+    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: LiveSession, childId: string, label: string): boolean {
+    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
@@ -7800,14 +8331,31 @@ export class BridgeManager {
     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(): Promise<void> {
     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`. */
@@ -8044,6 +8592,7 @@ export class BridgeManager {
   }
   private sessionWorkspaceResolver?: SessionWorkspaceResolver
   private acpModeResolver?: AcpModeResolver
+  private subagentCatalogReporter?: SubagentCatalogReporter
   private attachmentResolver?: unknown
   /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
   private readonly acpModeCache = new Map<string, boolean>()
@@ -8052,8 +8601,8 @@ export class BridgeManager {
 
   /**
    * 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
@@ -8072,6 +8621,14 @@ export class BridgeManager {
     // `defaultEffort` only when the current value is one of the agent's levels.
     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: Record<string, string | boolean> = {}
     for (const option of catalog.extras ?? []) {
       const value = option.currentValue
@@ -8092,14 +8649,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.
    */
   private seedChatChoiceFromCatalog(
     dshSessionId: string,
@@ -8128,6 +8686,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)) {