dsh-ntr 0.3.1 → 0.3.2

package/src/bridge.ts

@@ -69,11 +69,11 @@ import type {
   RosterPresetRow,
 } from './impl.ts'
 import type {
-  AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPresetStatus, AcpReleaseCause, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike,
+  AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPresetStatus, AcpReleaseCause, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionForkInfo, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike,
   LlmModelInfo, LlmModelReasoningInfo, LlmProviderInfo, LlmReasoningEffortInfo, LlmResolvedModelInfo,
-  ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionOutcome, PermissionOptionView, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk,
+  AcpIdleRelease, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionOutcome, PermissionOptionView, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk,
 } from './protocol.ts'
-import { DEFAULT_TAG_HALO } from './protocol.ts'
+import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from './protocol.ts'
 import { UpdateService } from './update.ts'
 
 /**
@@ -138,6 +138,15 @@ interface LiveSession {
   closed: boolean
   /** The agent process died; the session awaits a `session/load` resume. */
   released: boolean
+  /**
+   * The agent-side session has history while the LOCAL buffer is empty: this
+   * record was restored from disk after a host restart (the replay has not
+   * landed yet), or a resume cleared the buffer ahead of the replay. The ACP
+   * view then says history replays on restore instead of "nothing yet". Set
+   * by `doResumeSession` (captured before the reset) and the restore path; the
+   * serializer ORs it with the live buffer length.
+   */
+  hasHistory?: boolean
   /**
    * When the agent last showed ANY sign of life on this session: an update, a
    * permission ask (arrival or answer), or a turn start. The stall watchdog
@@ -415,7 +424,7 @@ const DEFAULT_TUNING: Required<BridgeTuning> = {
   turnStallMs: 600_000,
   turnStallToolMs: 1_800_000,
   turnStallTickMs: 30_000,
-  idleTimeoutMs: 1_800_000,
+  idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
   probeIdleTimeoutMs: 300_000,
 }
 
@@ -453,7 +462,7 @@ export class AgentBridge {
   private readonly staleCancelRetryDelayMs: number
   private readonly staleCancelMaxRetries: number
   private readonly turnSettleMs: number
-  private readonly defaultIdleTimeoutMs: number
+  private defaultIdleTimeoutMs: number
   private readonly probeIdleTimeoutMs: number
   /** Armed while READY; fires the idle-release check. */
   private idleTimer?: ReturnType<typeof setTimeout>
@@ -474,6 +483,13 @@ export class AgentBridge {
    * that a caller is waiting on the child it is about to kill.
    */
   private pendingCreates = 0
+  /**
+   * `session/fork` requests in flight (the adopt path of a branched
+   * conversation). Same teardown hazard as {@link pendingCreates}: until the
+   * forked session is registered, nothing else would stop an idle release
+   * from killing the child out from under the caller.
+   */
+  private pendingForks = 0
   /**
    * Whether a REAL session has ever been registered on this bridge. Probes
    * bypass session bookkeeping, so a bridge that has never hosted anything was
@@ -516,6 +532,20 @@ export class AgentBridge {
      * this bridge was built.
      */
     private readonly sessionWorkspace?: () => SessionWorkspaceResolver | undefined,
+    /**
+     * Told whenever the SESSION RECORDS change shape (a release parks them, a
+     * resume revives them): the manager persists `chatSessions` through it, so
+     * a parked conversation stays resumable across a host restart (see
+     * `BridgeManager.loadPersistedChatSessions`).
+     */
+    private readonly onSessionsDirty?: () => void,
+    /**
+     * Told whenever a fresh `initialize` reports the agent's
+     * `sessionCapabilities.fork` bit — the LAST KNOWN fork capability the
+     * manager persists and serves to the browser (the bridge's own
+     * `initResult` dies with the process; the manager's copy survives it).
+     */
+    private readonly onForkCapability?: (agentId: string, supported: boolean) => void,
   ) {
     const merged = { ...DEFAULT_TUNING, ...tuning }
     this.startupTimeoutMs = merged.startupTimeoutMs
@@ -550,6 +580,24 @@ export class AgentBridge {
     this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, this.permissionTimeoutMs)
   }
 
+  /**
+   * Adopt a rewritten host-default idle window (the settings page's write).
+   *
+   * Only the DEFAULT moves: an agent that names its own `idleTimeoutMs` keeps
+   * it (that promise is about the agent, not about the deployment), and a
+   * probe-only child keeps the short probe window.
+   *
+   * The timer is re-armed so the new window governs from NOW: an already
+   * armed timer still holds the old window, so a shortened window would not
+   * take effect until the old one elapsed.
+   */
+  applyIdleRelease(defaultIdleTimeoutMs: number): void {
+    if (this.defaultIdleTimeoutMs === defaultIdleTimeoutMs) return
+    this.defaultIdleTimeoutMs = defaultIdleTimeoutMs
+    this.clearIdleTimer()
+    this.touch()
+  }
+
   /**
    * The idle-release window this agent honors for its CHAT process: its own
    * field, else the host default. This is the number the panel prefills and
@@ -744,6 +792,7 @@ export class AgentBridge {
   private hasActiveWork(): boolean {
     if (this.pendingProbes > 0
       || this.pendingCreates > 0
+      || this.pendingForks > 0
       || this.pendingCommands.size > 0
       || this.resuming.size > 0
       || this.permissions.sessionIds().length > 0
@@ -768,6 +817,7 @@ export class AgentBridge {
   hasOtherActiveWork(session: LiveSession): boolean {
     if (this.pendingProbes > 0
       || this.pendingCreates > 0
+      || this.pendingForks > 0
       || this.resuming.size > 0
       || this.starting !== undefined) return true
     for (const sessionId of this.pendingCommands.keys()) {
@@ -944,6 +994,10 @@ export class AgentBridge {
       'initialize',
     )
     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
+    // browser's branch button after a release (`initResult` itself dies here).
+    this.onForkCapability?.(this.def.id, this.initResult?.agentCapabilities?.sessionCapabilities?.fork != null)
   }
 
   /**
@@ -1094,6 +1148,103 @@ export class AgentBridge {
     }
   }
 
+  /**
+   * Fork one live session through the agent's own `session/fork` (the
+   * UNSTABLE fourth session-creation point): the agent copies its internal
+   * state into a NEW ACP session that remembers the parent's context — the
+   * second half of a branched conversation, after the host's `sessions.fork`
+   * has already built the DSH session tree. The child is addressed by the
+   * CHILD DSH conversation id, so its first message reaches an agent that
+   * actually remembers the parent.
+   *
+   * The parent must be live on this connection — a released parent has no
+   * process to fork from (the browser blocks that click; this is the hard
+   * stop behind it). The ACP request carries the SAME `mcpServers` list as
+   * `session/new` / `session/load` (one list per process; an empty list would
+   * evict the live sessions' MCP scope) and is bounded by the startup timeout
+   * like every session-creation step. Counted in {@link pendingForks} while
+   * in flight so an idle release cannot kill the child out from under the
+   * caller.
+   */
+  async forkSession(parent: LiveSession, dshSessionId: string): Promise<LiveSession> {
+    if (this.initResult?.agentCapabilities?.sessionCapabilities?.fork == null) {
+      throw new AcpError('fork_unsupported', `acp: agent "${this.def.id}" does not advertise the session/fork capability`)
+    }
+    const conn = this.conn
+    if (conn === undefined) throw new AcpError('agent_unreachable', 'acp: connection is not open')
+    // The child runs where the parent runs: its cwd is the parent's already
+    // validated workspace, re-trusted as its own extra root (the same minimal
+    // trust `resolveSessionCwd` applied when the parent was created — never
+    // the agent's configured sandbox cwd, which is not where the conversation
+    // lives).
+    const resolved = resolveSessionCwd(this.def, parent.cwd, p => realpathSync(p), [parent.cwd])
+    this.pendingForks += 1
+    try {
+      const result = await this.withStartupTimeout(
+        conn.agent.request(methods.agent.session.fork, {
+          sessionId: parent.acpSessionId,
+          cwd: resolved,
+          mcpServers: toAcpMcpServers(this.def.mcpServers),
+        }),
+        'session/fork',
+      )
+      // A fork answer that names the parent (or any session already routed on
+      // this connection) would interleave the parent's updates, asks and
+      // permission cards into the child — refuse it rather than register it.
+      if (typeof result.sessionId !== 'string' || result.sessionId === '') {
+        throw new AcpError('fork_failed', 'acp: session/fork returned no session id')
+      }
+      if (result.sessionId === parent.acpSessionId || this.acpIndex.has(result.sessionId)) {
+        throw new AcpError('fork_id_conflict', 'acp: session/fork returned an id that already exists on this connection')
+      }
+      const session: LiveSession = {
+        sessionId: randomUUID(),
+        agentId: this.def.id,
+        acpSessionId: result.sessionId,
+        cwd: resolved,
+        running: false,
+        turnSeq: 0,
+        closed: false,
+        released: false,
+        lastAgentActivityAt: Date.now(),
+        activeToolCalls: new Set(),
+        transcript: new Transcript(this.transcriptMax),
+        dshSessionId,
+        ...(result.modes !== undefined && result.modes !== null
+          ? {
+            modes: {
+              currentModeId: result.modes.currentModeId,
+              availableModes: result.modes.availableModes.map(m => ({
+                id: m.id,
+                name: m.name,
+                ...(m.description !== null ? { description: m.description } : {}),
+              })),
+            },
+          }
+          : {}),
+        ...(usableConfigOptions(result.configOptions) ? { configOptions: result.configOptions } : {}),
+      }
+      // The fork answer's config options are the AGENT-LEVEL surface too (the
+      // same feed `session/new` provides): absorb them so the composer chips
+      // of the fresh conversation render without a probe.
+      if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
+        this.onCatalog(this.def.id, result.configOptions)
+      }
+      this.sessions.set(session.sessionId, session)
+      this.acpIndex.set(session.acpSessionId, session)
+      // Same flip as `createSession`: a registered session makes this a chat
+      // process; re-arm the idle clock on the agent's own window.
+      this.clearIdleTimer()
+      this.everHostedSession = true
+      this.hub.broadcast({ type: 'session/created', sessionId: session.sessionId, session: snapshot(session) })
+      this.touch()
+      return session
+    } finally {
+      this.pendingForks -= 1
+      this.touch()
+    }
+  }
+
   /**
    * Fire one prompt turn. Returns after the agent settles the turn; the caller
    * (manager) keeps the UI informed through broadcast events, so the RPC that
@@ -1241,7 +1392,11 @@ export class AgentBridge {
       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".
+      // seq keeps meaning "position in the current epoch". What the buffer held
+      // is now the agent's to replay — remember that there IS history before
+      // dropping it, or a failed resume parks an empty buffer back and the
+      // view claims the conversation never happened.
+      session.hasHistory = session.hasHistory === true || session.transcript.since(0).length > 0
       session.transcript = new Transcript(this.transcriptMax)
       session.cwd = resolved
       session.running = false
@@ -1285,6 +1440,7 @@ export class AgentBridge {
       this.touch()
       // Republish so configOptions/modes observed on load reach the browser.
       this.hub.broadcast({ type: 'session/meta', sessionId: session.sessionId, session: snapshot(session) })
+      this.onSessionsDirty?.()
       return session
     } catch (error) {
       this.acpIndex.delete(session.acpSessionId)
@@ -1292,6 +1448,7 @@ export class AgentBridge {
       session.released = true
       this.released.set(session.sessionId, session)
       this.hub.broadcast({ type: 'session/released', sessionId: session.sessionId, session: snapshot(session), reason: 'resume failed', cause: 'resume-failed' })
+      this.onSessionsDirty?.()
       throw error
     }
   }
@@ -1327,6 +1484,10 @@ export class AgentBridge {
     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?.()
   }
 
   /** Detach one released session record for a resume attempt. */
@@ -1342,6 +1503,15 @@ export class AgentBridge {
     return this.released.delete(sessionId)
   }
 
+  /**
+   * Register a session record restored from disk as already parked: a host
+   * restart killed every process, so it comes back exactly as `releaseAll`
+   * would have left it — resumable via `session/load`, never live.
+   */
+  parkReleased(session: LiveSession): void {
+    this.released.set(session.sessionId, session)
+  }
+
   get releasedList(): LiveSession[] {
     return [...this.released.values()]
   }
@@ -1918,10 +2088,78 @@ function snapshot(session: LiveSession): SessionView {
     running: session.running,
     closed: session.closed,
     ...(session.released ? { released: true } : {}),
+    ...(session.hasHistory === true ? { hasHistory: true } : {}),
     seq: session.transcript.head,
   }
 }
 
+/**
+ * The `fork` half of one `session/chat-list` row: the host's verdict on
+ * forking this session's ACP agent. The capability half is the agent's LAST
+ * KNOWN bit (see `canForkNow`); the state half is the session's own, released
+ * checked before running (a parked record is never running). The browser
+ * renders its branch button from this verdict and never reads a capability
+ * bit itself.
+ */
+function forkRowInfo(session: LiveSession, capability: boolean): { fork: ChatSessionForkInfo } {
+  if (!capability) return { fork: { supported: false, reason: 'unsupported' } }
+  if (session.released) return { fork: { supported: false, reason: 'released' } }
+  if (session.running || session.settled !== undefined) return { fork: { supported: false, reason: 'busy' } }
+  return { fork: { supported: true } }
+}
+
+/**
+ * One chat-bound session record, as persisted across host restarts (the
+ * `chatSessions` key of the agent registry). Deliberately identity + display
+ * mirrors ONLY — the transcript is the agent's to replay on `session/load`,
+ * and `configOptions` come back from the same load. `hasHistory` is what lets
+ * an empty restored view say "history replays on restore" instead of
+ * "nothing yet".
+ */
+interface PersistedChatSession {
+  sessionId: string
+  acpSessionId: string
+  agentId: string
+  dshSessionId: string
+  cwd: string
+  title?: string
+  modelId?: string
+  reasoningEffort?: string
+  modes?: SessionView['modes']
+  usage?: SessionView['usage']
+  hasHistory?: boolean
+}
+
+function persistedChatSession(session: LiveSession): PersistedChatSession {
+  return {
+    sessionId: session.sessionId,
+    acpSessionId: session.acpSessionId,
+    agentId: session.agentId,
+    dshSessionId: session.dshSessionId as string,
+    cwd: session.cwd,
+    ...(session.title === undefined ? {} : { title: session.title }),
+    ...(session.modelId === undefined ? {} : { modelId: session.modelId }),
+    ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }),
+    ...(session.modes === undefined ? {} : { modes: session.modes }),
+    ...(session.usage === undefined ? {} : { usage: session.usage }),
+    ...(session.hasHistory === true || session.transcript.since(0).length > 0 ? { hasHistory: true } : {}),
+  }
+}
+
+/** Tolerant shape check for a `modes` value read back from disk. */
+function isPersistedModes(value: unknown): value is SessionView['modes'] {
+  if (value === null || typeof value !== 'object') return false
+  const modes = value as { currentModeId?: unknown; availableModes?: unknown }
+  return typeof modes.currentModeId === 'string' && Array.isArray(modes.availableModes)
+}
+
+/** Tolerant shape check for a `usage` value read back from disk. */
+function isPersistedUsage(value: unknown): value is SessionView['usage'] {
+  if (value === null || typeof value !== 'object') return false
+  const usage = value as { used?: unknown; size?: unknown }
+  return typeof usage.used === 'number' && typeof usage.size === 'number'
+}
+
 /**
  * The DSH chat session's OWN workspace, when one is resolvable: the directory
  * the user selected in the DSH sidebar, which the host reports back as the
@@ -3240,6 +3478,29 @@ export class BridgeManager {
    * write would fight with no way to tell which one is live.
    */
   private deadlineOverride: ApprovalDeadlinePatch = {}
+  /**
+   * The idle-release window the settings page picked, in ms, persisted
+   * with the agent registry. `undefined` means the deployment baseline runs.
+   *
+   * Merged OVER {@link baselineIdleTimeoutMs} exactly like
+   * {@link deadlineOverride} over {@link baselineDeadline}: a UI pick is what
+   * runs, and `cordis.patch.yml` becomes the value the reset button returns
+   * to. Without this split the two sources would fight with no way to tell
+   * which one is live.
+   */
+  private idleReleaseOverride?: number
+  /**
+   * The window `cordis.patch.yml` names, when it names one. Kept apart
+   * from the override for the same reason the deadline keeps its baseline
+   * apart: the settings card has to be able to say "the file asks for
+   * 10 minutes, the value set here wins".
+   */
+  private configuredIdleTimeoutMs?: number
+  /**
+   * The idle-release window before any override — the tuning this manager was
+   * constructed with (the deployment baseline, or the built-in 30 minutes).
+   */
+  private baselineIdleTimeoutMs: number
   /**
    * Tuning in force, defaults applied. The approval deadline is rewritten
    * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
@@ -3401,6 +3662,7 @@ export class BridgeManager {
     // it. Everything else in `tuning` is fixed for the manager's lifetime, so
     // only this needs a snapshot.
     this.baselineDeadline = this.tuning.permissionTimeoutMs
+    this.baselineIdleTimeoutMs = this.tuning.idleTimeoutMs
     this.baselineMode = this.tuning.permissionTimeoutMode
     for (const def of defs) {
       this.defsMap.set(def.id, def)
@@ -3417,6 +3679,10 @@ export class BridgeManager {
     // A persisted deadline override must reach the tuning the bridges are built
     // from, not just the settings card's readout.
     this.applyDeadlineTuning()
+    // The same for the idle-release window: a persisted override must
+    // reach the tuning the bridges are built from, not just the
+    // settings card's readout.
+    this.applyIdleReleaseTuning()
     // The request-path rewrite falls back to this default for a conversation
     // the user never bound explicitly — the same agent the composer chip shows.
     routeBindingRegistry().defaultModel = this.defaultAgent()
@@ -3427,8 +3693,10 @@ export class BridgeManager {
     onConnectionLost: (bridge: AgentBridge, reason: string) => void,
     onCatalog?: (agentId: string, configOptions: unknown, shapeOnly?: boolean) => void,
     onCommands?: (agentId: string, commands: NonNullable<SessionView['availableCommands']>) => void,
+    onSessionsDirty?: () => void,
+    onForkCapability?: (agentId: string, supported: boolean) => void,
   ): AgentBridge {
-    return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver)
+    return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver, onSessionsDirty, onForkCapability)
   }
 
   /**
@@ -3567,12 +3835,87 @@ export class BridgeManager {
         ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }),
         ...(session.modes === undefined ? {} : { modes: session.modes }),
         ...(session.availableCommands === undefined ? {} : { availableCommands: session.availableCommands }),
+        ...(session.usage === undefined ? {} : { usage: session.usage }),
         ...(session.released ? { released: true } : {}),
+        ...(session.running ? { running: true } : {}),
+        ...forkRowInfo(session, this.canForkNow(session.agentId)),
       })
     }
     return out
   }
 
+  /**
+   * Adopt the ACP side of a branched conversation: the browser has already
+   * asked the HOST to fork the DSH session tree (`sessions.fork`), and this
+   * runs the agent's own `session/fork` of the parent conversation's live ACP
+   * session so the child actually remembers the parent context — then binds
+   * the child to it (the fourth session-creation point, with every discipline
+   * the other three carry).
+   *
+   * Failure is deliberately all-or-nothing: nothing is written for the child
+   * until the agent has answered, so a failed adopt leaves the child an
+   * ordinary copied-history conversation whose first message starts a fresh
+   * `session/new` (today's behavior) — never a half-bound record.
+   *
+   * @param childDshSessionId - the DSH session the host fork created.
+   * @param parentDshSessionId - the conversation being branched; its ACP
+   *   session must be LIVE on this connection (a released parent has no
+   *   process to fork from — the browser blocks the click, this is the hard
+   *   stop behind it).
+   */
+  async adoptForkedSession(childDshSessionId: string, parentDshSessionId: string): Promise<{ sessionId: string; acpSessionId: string }> {
+    // One conversation, one agent (the lock). The parent's LIVE session is
+    // the fork source; released or in-flight-settling parents are refused —
+    // forking a parked record would silently resume it, and forking mid-turn
+    // would fork an agent state the parent turn is still changing.
+    const parent = [...this.dshSessionMap.values()].find(session =>
+      session.dshSessionId === parentDshSessionId && !session.closed && !session.released)
+    if (parent === undefined) {
+      throw new AcpError('parent_not_live', 'acp: the conversation to branch has no live ACP session; send a message to resume it first')
+    }
+    if (parent.running || parent.settled !== undefined) {
+      throw new AcpError('turn_in_flight', 'acp: the conversation to branch is running a turn; wait for it to finish')
+    }
+    const agentId = parent.agentId
+    const childKey = `${childDshSessionId}:${agentId}`
+    if (this.dshSessionMap.has(childKey)) {
+      throw new AcpError('id_conflict', 'acp: the forked conversation is already bound to an ACP session')
+    }
+    // Capability gate BEFORE any request: an agent that never advertised
+    // `session/fork` must not be asked (it would answer an unknown-method
+    // error at best). Live init wins, last-known falls back — the same
+    // verdict the browser's row already showed.
+    if (!this.canForkNow(agentId)) {
+      throw new AcpError('fork_unsupported', `acp: agent "${agentId}" does not advertise the session/fork capability`)
+    }
+    const session = await this.bridge(agentId).forkSession(parent, childDshSessionId)
+    // The fork answered — the child is real on the agent side. From here the
+    // binding is written through the SAME paths as any chat session: one
+    // choice record (a copy of the parent's, locked — a branched conversation
+    // belongs to its agent from birth), the route pin, and persistence.
+    this.dshSessionMap.set(childKey, session)
+    const parentChoice = this.chatAgentIntent.get(parentDshSessionId)
+    this.patchChatChoice(childDshSessionId, {
+      agentId,
+      locked: true,
+      ...(parentChoice?.modelId === undefined ? {} : { modelId: parentChoice.modelId }),
+      ...(parentChoice?.effort === undefined ? {} : { effort: parentChoice.effort }),
+      ...(parentChoice?.mode === undefined ? {} : { mode: parentChoice.mode }),
+      ...(parentChoice?.extraConfigs === undefined ? {} : { extraConfigs: { ...parentChoice.extraConfigs } }),
+    })
+    // The fourth creation point follows the same discipline as `createSession`
+    // and `doResumeSession`: apply the recorded pick to the fresh session, so
+    // mode and extra configs (which only this path applies) cannot drift from
+    // what the composer shows — a forked session starts on the agent-side
+    // state the fork copied, and the record must match what runs.
+    await this.applyChatChoice(session)
+    // Re-publish so the browser's list and the composer's occupancy ring see
+    // the child immediately (with its just-bound choice mirrors).
+    this.hub.broadcast({ type: 'session/meta', sessionId: session.sessionId, session: snapshot(session) })
+    this.persistAgents()
+    return { sessionId: session.sessionId, acpSessionId: session.acpSessionId }
+  }
+
   /**
    * Bind one DSH chat session to an ACP agent.
    *
@@ -3827,11 +4170,12 @@ export class BridgeManager {
     this.patchChatChoice(dshSessionId, { agentId, modelId: choice === undefined ? undefined : modelId })
     for (const session of this.dshSessionMap.values()) {
       if (session.dshSessionId !== dshSessionId || session.agentId !== agentId) continue
-      if (session.released) continue
-      await this.alignSessionConfig(session, choice, session.reasoningEffort)
       session.choice = choice
       session.modelId = modelId
+      if (session.released) continue
+      await this.alignSessionConfig(session, choice, session.reasoningEffort)
     }
+    this.persistAgents()
   }
 
   /**
@@ -3857,12 +4201,15 @@ export class BridgeManager {
     // session is skipped here and re-aligned by `applyChatChoice` on resume.
     this.patchChatChoice(dshSessionId, { ...(agentId === undefined ? {} : { agentId }), effort })
     for (const session of this.dshSessionMap.values()) {
-      if (session.dshSessionId !== dshSessionId || session.released) continue
+      if (session.dshSessionId !== dshSessionId) continue
       if (agentId !== undefined && session.agentId !== agentId) continue
+      session.reasoningEffort = effort
+      if (session.released) continue
       const aligned = await this.alignSessionConfig(session, session.choice, effort)
       // Same rule as the model axis: a dropped level is no longer "in force".
       session.reasoningEffort = aligned.effortStale ? undefined : effort
     }
+    this.persistAgents()
   }
 
   /**
@@ -4051,9 +4398,15 @@ export class BridgeManager {
   }
 
   /**
-   * Switch one chat-bound session's ACP mode. A released session is resumed
-   * first (`session/load`), matching the "send to recover" promise — the mode
-   * switch is itself a reason to bring the agent back.
+   * Switch one chat-bound session's ACP mode.
+   *
+   * A released session is deliberately NOT resumed for it (user decision,
+   * 2026-10-30 — the composer's axes are "what the next turn should use", and
+   * the process comes back only when the user sends a message or hits the
+   * released banner's resume button). The pick is recorded and
+   * `applyChatChoice` applies it on resume, exactly like `setChatSessionModel`
+   * / `setChatSessionEffort` / `setChatSessionConfig`; only a LIVE session is
+   * told immediately (`session/set_mode`).
    */
   async setChatSessionMode(dshSessionId: string, modeId: string, agentId?: string): Promise<void> {
     if (agentId !== undefined) {
@@ -4083,9 +4436,20 @@ export class BridgeManager {
     if (target.closed) {
       throw new AcpError('unknown_session', `acp: the ACP session bound to chat session ${dshSessionId} is closed`)
     }
+    // A PARKED session gets the same record-only treatment (its agent is its
+    // own `agentId`, whatever the caller passed — the selection above already
+    // matched it). Resuming here was the one composer axis that broke ranks
+    // with the others, and it woke a process the user had explicitly parked.
+    if (target.released) {
+      this.patchChatChoice(dshSessionId, { agentId: target.agentId, mode: modeId })
+      if (target.modes !== undefined) {
+        target.modes = { ...target.modes, currentModeId: modeId }
+      }
+      this.persistAgents()
+      return
+    }
     const bridge = this.bridge(target.agentId)
-    const session = target.released ? await bridge.resumeSession(target) : target
-    await bridge.setMode(session, modeId)
+    await bridge.setMode(target, modeId)
     // Persisted only AFTER the agent accepted it: a mode the agent rejected must
     // not come back on the next restore. This is the same contract the model and
     // thought level follow (user decision, 2026-10-18 — every control in the
@@ -4093,6 +4457,42 @@ export class BridgeManager {
     this.patchChatChoice(dshSessionId, { agentId: target.agentId, mode: modeId })
   }
 
+  /**
+   * Bring one chat conversation's released session back on a fresh process on
+   * the USER's explicit gesture (the "恢复进程" banner) — the same work the
+   * next prompt performs lazily (`getOrCreateDshSession`'s released branch),
+   * minus the create path: a banner button must never materialize a session
+   * the conversation has not had yet. A live target passes through untouched,
+   * so a double click (or a click racing the next message) spawns nothing.
+   */
+  async resumeChatSession(dshSessionId: string): Promise<void> {
+    const candidates = [...this.dshSessionMap.values()].filter(
+      session => session.dshSessionId === dshSessionId && !session.closed,
+    )
+    // The session the NEXT message would use — the bound agent's — is the one
+    // to bring back; the first candidate is the fallback for a conversation
+    // whose binding has drifted (same selection `setChatSessionMode` makes
+    // without an explicit agentId).
+    const target = candidates.find(session => session.agentId === this.chatAgentFor(dshSessionId)) ?? candidates[0]
+    if (target === undefined) {
+      throw new AcpError('unknown_session', `acp: no ACP session is bound to chat session ${dshSessionId}`)
+    }
+    if (!target.released) return
+    const bridge = this.bridge(target.agentId)
+    const resumed = await bridge.resumeSession(target)
+    // Chat-side rebind + pick re-application, verbatim the lazy path's: the
+    // freshly loaded session comes back at the agent's defaults, so the
+    // conversation's model / thought level must be re-applied or the composer
+    // would show one thing and the process run another (see
+    // `getOrCreateDshSession`).
+    resumed.dshSessionId = dshSessionId
+    this.lockChatAgent(dshSessionId, target.agentId)
+    if (this.chatAgentIntent.has(dshSessionId)) this.syncConversationRoute(dshSessionId)
+    else routeBindingRegistry().conversations.set(dshSessionId, resumed.modelId ?? target.agentId)
+    await this.applyChatChoice(resumed)
+    resumed.provisionalLock = false
+  }
+
   /**
    * Wire the harness's preset roster (`ctx.agentPresets`) into `presetStatus`.
    *
@@ -4276,7 +4676,21 @@ export class BridgeManager {
         } catch {
           this.deadlineOverride = {}
         }
+        // The settings page's idle-release pick. Re-validated on every boot
+        // because the state file is user- and version-editable: an
+        // unreadable value must not poison the window, and a value the
+        // validator accepts must be the value that runs.
+        try {
+          const raw = (parsed as { idleRelease?: unknown }).idleRelease
+          const value = (raw as { idleTimeoutMs?: unknown } | undefined)?.idleTimeoutMs
+          this.idleReleaseOverride = typeof value === 'number' && IDLE_RELEASE_MS.includes(value)
+            ? value
+            : undefined
+        } catch {
+          this.idleReleaseOverride = undefined
+        }
         this.loadPersistedChoices((parsed as { conversations?: unknown }).conversations)
+        this.loadPersistedChatSessions((parsed as { chatSessions?: unknown }).chatSessions)
       }
     } catch {
       // Storage load failure is non-fatal
@@ -4323,6 +4737,13 @@ export class BridgeManager {
     const filePath = this.getStoragePath()
     if (!filePath) return
     try {
+      // The chat-bound session records themselves: a host restart kills the
+      // processes but not the agent-side sessions, so restoring these as
+      // PARKED keeps a conversation resumable (`session/load`) instead of
+      // its next message silently starting a context-less new one.
+      const chatSessions = [...this.dshSessionMap.values()]
+        .filter(session => session.dshSessionId !== undefined && !session.closed)
+        .map(persistedChatSession)
       const payload = {
         version: 2,
         ...(this.defaultAgentId === undefined ? {} : { defaultAgentId: this.defaultAgentId }),
@@ -4333,12 +4754,18 @@ export class BridgeManager {
         ...(Object.keys(this.deadlineOverride).length === 0
           ? {}
           : { approvalDeadlines: { ...this.deadlineOverride } }),
+        // The settings page's idle-release pick. Absent while none was
+        // ever written, so a fresh deployment's state file stays as it was.
+        ...(this.idleReleaseOverride === undefined
+          ? {}
+          : { idleRelease: { idleTimeoutMs: this.idleReleaseOverride } }),
         // The per-conversation picks: agent + model + thought level + mode +
         // extra config values chosen in the composer, including for
         // conversations with no live session yet.
         ...(this.chatAgentIntent.size === 0
           ? {}
           : { conversations: Object.fromEntries(this.chatAgentIntent) }),
+        ...(chatSessions.length === 0 ? {} : { chatSessions }),
       }
       writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf-8')
     } catch {
@@ -4346,9 +4773,73 @@ export class BridgeManager {
     }
   }
 
+  /**
+   * Restore chat session records from disk as PARKED sessions.
+   *
+   * Every process died with the host, so nothing comes back live — but the
+   * agent-side sessions did not. Restoring each record as `released` is what
+   * makes the released banner, its resume button and the "next message
+   * resumes it" promise survive a restart (the alternative is the next
+   * message quietly starting a NEW, context-less session — constraint 10's
+   * "released ≠ destroyed" lost at the process boundary). Tolerant, one row
+   * at a time: a single corrupt entry must not cost every other conversation
+   * its context. Records whose agent is no longer configured are dropped —
+   * there is nothing to resume ON, and the next write omits them.
+   */
+  private loadPersistedChatSessions(raw: unknown): void {
+    if (!Array.isArray(raw)) return
+    for (const row of raw) {
+      if (row === null || typeof row !== 'object') continue
+      const record = row as Record<string, unknown>
+      const { sessionId, acpSessionId, agentId, dshSessionId, cwd } = record
+      if (typeof sessionId !== 'string' || sessionId === '') continue
+      if (typeof acpSessionId !== 'string' || acpSessionId === '') continue
+      if (typeof agentId !== 'string' || agentId === '') continue
+      if (typeof dshSessionId !== 'string' || dshSessionId === '') continue
+      if (typeof cwd !== 'string') continue
+      if (!this.defsMap.has(agentId)) continue
+      const { title, modelId, reasoningEffort, modes, usage, hasHistory } = record as {
+        title?: unknown; modelId?: unknown; reasoningEffort?: unknown; modes?: unknown; usage?: unknown; hasHistory?: unknown
+      }
+      const session: LiveSession = {
+        sessionId,
+        acpSessionId,
+        agentId,
+        dshSessionId,
+        cwd,
+        ...(typeof title === 'string' && title !== '' ? { title } : {}),
+        ...(typeof modelId === 'string' && modelId !== ''
+          ? { modelId, ...(splitAdapterModelId(modelId).choice === undefined ? {} : { choice: splitAdapterModelId(modelId).choice }) }
+          : {}),
+        ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
+        ...(isPersistedModes(modes) ? { modes } : {}),
+        ...(isPersistedUsage(usage) ? { usage } : {}),
+        ...(hasHistory === true ? { hasHistory: true } : {}),
+        running: false,
+        turnSeq: 0,
+        closed: false,
+        released: true,
+        lastAgentActivityAt: Date.now(),
+        activeToolCalls: new Set<string>(),
+        transcript: new Transcript(this.transcriptMax),
+      }
+      this.dshSessionMap.set(`${dshSessionId}:${agentId}`, session)
+      this.bridge(agentId).parkReleased(session)
+    }
+  }
+
   // ---- Model catalog ----
 
   private readonly catalogs = new Map<string, { catalog: AcpAgentCatalog; updatedAt: number }>()
+  /**
+   * Each agent's LAST KNOWN `sessionCapabilities.fork` bit, persisted with the
+   * model catalog. A live `initialize` result outranks it whenever one exists
+   * (see {@link canForkNow}) — this copy answers when the process is gone
+   * (a released session's branch button must not flash into "supported" just
+   * because `initResult` died with it, nor read `view().agentCapabilities`,
+   * which a release clears).
+   */
+  private readonly forkCaps = new Map<string, boolean>()
   /**
    * The slash commands each agent declared in its most recent session, cached
    * per agent and persisted alongside the model catalog.
@@ -4415,7 +4906,10 @@ export class BridgeManager {
       const stale = parsed.version !== BridgeManager.CATALOG_SCHEMA
       for (const [agentId, raw] of Object.entries(agents)) {
         if (typeof raw !== 'object' || raw === null) continue
-        const row = raw as { catalog?: unknown; updatedAt?: unknown; commands?: unknown; commandsUpdatedAt?: unknown }
+        const row = raw as { catalog?: unknown; updatedAt?: unknown; commands?: unknown; commandsUpdatedAt?: unknown; fork?: unknown }
+        // The persisted fork capability: a LAST KNOWN bit, loaded before any
+        // bridge can report a fresh one (a fresh `initialize` overwrites it).
+        if (typeof row.fork === 'boolean') this.forkCaps.set(agentId, row.fork)
         // Commands and the model catalog are learned independently (a session
         // may declare one before the other), so either half alone is a valid row.
         if (Array.isArray(row.commands)) {
@@ -4445,11 +4939,18 @@ export class BridgeManager {
         updatedAt?: number
         commands?: NonNullable<SessionView['availableCommands']>
         commandsUpdatedAt?: number
+        fork?: boolean
       }> = {}
       for (const [agentId, entry] of this.catalogs) agents[agentId] = { catalog: entry.catalog, updatedAt: entry.updatedAt }
       for (const [agentId, entry] of this.commandCache) {
         agents[agentId] = { ...(agents[agentId] ?? {}), commands: entry.commands, commandsUpdatedAt: entry.updatedAt }
       }
+      // The LAST KNOWN fork capability rides the same file: it outlives the
+      // agent process, which is exactly when the browser needs it (see
+      // `canForkNow`).
+      for (const [agentId, supported] of this.forkCaps) {
+        agents[agentId] = { ...(agents[agentId] ?? {}), fork: supported }
+      }
       writeFileSync(filePath, JSON.stringify({ version: BridgeManager.CATALOG_SCHEMA, agents }, null, 2), 'utf-8')
     } catch {
       // Storage persist failure is non-fatal
@@ -4541,6 +5042,33 @@ export class BridgeManager {
     this.hub.broadcast({ type: 'catalog/updated', agentId, updatedAt: entry.updatedAt })
   }
 
+  /**
+   * Record a fresh `initialize`'s `sessionCapabilities.fork` verdict (the
+   * bridge reports it right after the handshake). Persisted with the model
+   * catalog; no broadcast — the browser learns it through `session/chat-list`
+   * rows, and its branch button deliberately runs on a last-known basis (the
+   * agent's own next `initialize` is the refresh).
+   */
+  private noteForkCapability(agentId: string, supported: boolean): void {
+    if (this.forkCaps.get(agentId) === supported) return
+    this.forkCaps.set(agentId, supported)
+    this.persistCatalogs()
+  }
+
+  /**
+   * Whether an agent's fork can be attempted RIGHT NOW: a live `initialize`
+   * answer wins (the process is up, its handshake is current); only when the
+   * process is gone does the LAST KNOWN persisted bit answer. `false` covers
+   * "never seen" — an unknown agent simply never gets a fork attempt.
+   */
+  private canForkNow(agentId: string): boolean {
+    const bridge = this.bridges.get(agentId)
+    if (bridge?.initResult !== undefined) {
+      return bridge.initResult.agentCapabilities?.sessionCapabilities?.fork != null
+    }
+    return this.forkCaps.get(agentId) === true
+  }
+
   /**
    * Append models this observation newly introduced to the agent's selection.
    *
@@ -4966,6 +5494,10 @@ export class BridgeManager {
         else this.absorbCatalog(observedAgentId, configOptions)
       }, (observedAgentId, commands) => {
         this.absorbCommands(observedAgentId, commands)
+      }, () => {
+        this.persistAgents()
+      }, (observedAgentId, supported) => {
+        this.noteForkCapability(observedAgentId, supported)
       })
       this.bridges.set(agentId, bridge)
     }
@@ -5125,11 +5657,15 @@ export class BridgeManager {
       if (splitAdapterModelId(model).agentId === agentId) routeBindingRegistry().conversations.delete(dshSessionId)
     }
     if (routeBindingRegistry().defaultModel === agentId) routeBindingRegistry().defaultModel = undefined
-    // Both maps are independent (either may be missing), so delete both before
-    // deciding whether the file needs rewriting.
+    // All three maps are independent (any may be missing), so delete all
+    // before deciding whether the file needs rewriting. The fork capability
+    // goes with the agent: a same-id rebuild must not inherit the OLD agent's
+    // "supported" and click into a `fork_unsupported` wall before its own
+    // first `initialize` answers.
     const droppedCatalog = this.catalogs.delete(agentId)
     const droppedCommands = this.commandCache.delete(agentId)
-    if (droppedCatalog || droppedCommands) this.persistCatalogs()
+    const droppedFork = this.forkCaps.delete(agentId)
+    if (droppedCatalog || droppedCommands || droppedFork) this.persistCatalogs()
     this.persistAgents()
     this.hub.broadcast({
       type: 'agent/status',
@@ -5378,6 +5914,23 @@ export class BridgeManager {
     this.persistAgents()
   }
 
+  /**
+   * Declare the deployment baseline for the idle-release window — the value
+   * `cordis.patch.yml` names, passed RAW (only when it names one).
+   *
+   * Kept separate from the validated tuning for the same reason the
+   * deadline keeps its baseline apart: "the file says 10 minutes" and
+   * "the file says nothing, so 30 minutes applies" are different facts.
+   * The first is the reset target and shows as the fact being overridden;
+   * the second is a built-in default. Called once by the host entry,
+   * before any bridge exists.
+   */
+  setConfiguredIdleRelease(idleTimeoutMs: number | undefined): void {
+    this.configuredIdleTimeoutMs = idleTimeoutMs
+    if (idleTimeoutMs !== undefined) this.baselineIdleTimeoutMs = idleTimeoutMs
+    this.applyIdleReleaseTuning()
+  }
+
   /**
    * Declare the deployment baseline for the approval deadline — the values
    * `cordis.patch.yml` names, passed RAW (only the keys it actually contains).
@@ -5424,6 +5977,58 @@ export class BridgeManager {
     return deadlines
   }
 
+  /**
+   * The idle-release window in force, plus the facts that explain a value the
+   * user did not pick: the deployment baseline an override is outranking.
+   *
+   * `defaultIdleTimeoutMs` is the window a RESET returns to — the deployment
+   * baseline when the config file names one, else the built-in default. It is
+   * NOT a hardcoded constant: a deployment that names 10 minutes must reset
+   * to 10 minutes, not to the built-in 30.
+   *
+   * The config file's own number is reported only when the file names one, so
+   * the settings card can stay silent about a plain default.
+   */
+  idleRelease(): AcpIdleRelease {
+    const release: AcpIdleRelease = {
+      idleTimeoutMs: this.idleTimeoutMs(),
+      defaultIdleTimeoutMs: this.baselineIdleTimeoutMs,
+    }
+    if (this.configuredIdleTimeoutMs !== undefined) release.configuredIdleTimeoutMs = this.configuredIdleTimeoutMs
+    return release
+  }
+
+  /**
+   * Write the idle-release window, or drop the persisted override with
+   * `reset` so the deployment baseline applies again.
+   *
+   * HOT: the rewrite reaches every live bridge, so a user changing the window
+   * never has to kill a running session to see it take effect.
+   */
+  async setIdleRelease(idleTimeoutMs: number | undefined, reset = false): Promise<void> {
+    this.idleReleaseOverride = reset ? undefined : idleTimeoutMs
+    this.applyIdleReleaseTuning()
+    this.persistAgents()
+  }
+
+  /**
+   * Recompute the idle-release window from override → deployment baseline, and
+   * push the result to every live bridge.
+   */
+  private applyIdleReleaseTuning(): void {
+    const window = this.idleTimeoutMs()
+    this.tuning.idleTimeoutMs = window
+    for (const bridge of this.bridges.values()) bridge.applyIdleRelease(window)
+  }
+
+  /**
+   * The idle-release window that runs, in ms: the settings page's pick, else
+   * the deployment baseline.
+   */
+  private idleTimeoutMs(): number {
+    return this.idleReleaseOverride ?? this.baselineIdleTimeoutMs
+  }
+
   /**
    * Write the approval deadline, or the mode (omitted keys keep their value),
    * or drop the persisted override with `reset` so the config-file baseline —
@@ -5486,9 +6091,16 @@ export class BridgeManager {
 
   /** Drop every chat-keyed record pointing at one host session (close/stop paths). */
   private forgetDshSession(sessionId: string): void {
+    let dropped = false
     for (const [key, session] of this.dshSessionMap) {
-      if (session.sessionId === sessionId) this.dshSessionMap.delete(key)
+      if (session.sessionId === sessionId) {
+        this.dshSessionMap.delete(key)
+        dropped = true
+      }
     }
+    // The disk record goes with it: a closed session is destroyed, not parked,
+    // and must not come back on the next boot (constraint 10).
+    if (dropped) this.persistAgents()
   }
   private sessionWorkspaceResolver?: SessionWorkspaceResolver
   private acpModeResolver?: AcpModeResolver
@@ -5638,6 +6250,9 @@ export class BridgeManager {
       // A RESUMED session had context before this call; a lock written here is
       // not provisional even if the conversation record was missing it.
       resumed.provisionalLock = false
+      // The load refreshed the record's mirrors (modes / usage / hasHistory);
+      // persist so a later restart restores what this resume saw.
+      this.persistAgents()
       return resumed
     }
     // A chat session runs where its DSH session lives, not in the plugin's
@@ -5687,6 +6302,9 @@ export class BridgeManager {
       // conversation back (a failed first attempt must not trap it).
       session.provisionalLock = this.lockChatAgent(dshSessionId, agentId)
     }
+    // The record is on disk from here: a host restart restores it as parked
+    // instead of the next message starting a context-less new session.
+    this.persistAgents()
     return session
   }