dsh-ntr 0.3.1 → 0.3.2

package/lib/bridge.js

@@ -13,7 +13,7 @@ import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
 import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
-import { DEFAULT_TAG_HALO } from "./protocol.js";
+import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from "./protocol.js";
 /**
  * Version of this installed package, read from the shipped `package.json` —
  * one level above both `src/` at test time and `lib/` at runtime. The settings
@@ -104,7 +104,7 @@ const DEFAULT_TUNING = {
     turnStallMs: 600_000,
     turnStallToolMs: 1_800_000,
     turnStallTickMs: 30_000,
-    idleTimeoutMs: 1_800_000,
+    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
     probeIdleTimeoutMs: 300_000,
 };
 export class AgentBridge {
@@ -115,6 +115,8 @@ export class AgentBridge {
     onCatalog;
     onCommands;
     sessionWorkspace;
+    onSessionsDirty;
+    onForkCapability;
     state = 'stopped';
     initResult;
     lastError;
@@ -166,6 +168,13 @@ export class AgentBridge {
      * that a caller is waiting on the child it is about to kill.
      */
     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.
+     */
+    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
@@ -202,7 +211,21 @@ export class AgentBridge {
      * Resolved per turn: the host entry may wire the workspace reader after
      * this bridge was built.
      */
-    sessionWorkspace) {
+    sessionWorkspace, 
+    /**
+     * 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`).
+     */
+    onSessionsDirty, 
+    /**
+     * 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).
+     */
+    onForkCapability) {
         this.def = def;
         this.hub = hub;
         this.transcriptMax = transcriptMax;
@@ -210,6 +233,8 @@ export class AgentBridge {
         this.onCatalog = onCatalog;
         this.onCommands = onCommands;
         this.sessionWorkspace = sessionWorkspace;
+        this.onSessionsDirty = onSessionsDirty;
+        this.onForkCapability = onForkCapability;
         const merged = { ...DEFAULT_TUNING, ...tuning };
         this.startupTimeoutMs = merged.startupTimeoutMs;
         this.permissionTimeoutMode = merged.permissionTimeoutMode;
@@ -243,6 +268,24 @@ export class AgentBridge {
         // on arrival.
         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) {
+        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
@@ -437,6 +480,7 @@ export class AgentBridge {
     hasActiveWork() {
         if (this.pendingProbes > 0
             || this.pendingCreates > 0
+            || this.pendingForks > 0
             || this.pendingCommands.size > 0
             || this.resuming.size > 0
             || this.permissions.sessionIds().length > 0
@@ -462,6 +506,7 @@ export class AgentBridge {
     hasOtherActiveWork(session) {
         if (this.pendingProbes > 0
             || this.pendingCreates > 0
+            || this.pendingForks > 0
             || this.resuming.size > 0
             || this.starting !== undefined)
             return true;
@@ -640,6 +685,10 @@ export class AgentBridge {
             clientInfo: { name: 'dsh-ntr', title: 'DSH NTR', version: PLUGIN_VERSION },
         }), '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);
     }
     /**
      * Bound one agent-startup request (`initialize`, `session/new`,
@@ -783,6 +832,101 @@ export class AgentBridge {
             this.touch();
         }
     }
+    /**
+     * 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, dshSessionId) {
+        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 = {
+                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
@@ -930,7 +1074,11 @@ export class AgentBridge {
                 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;
@@ -972,6 +1120,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) {
@@ -980,6 +1129,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;
         }
     }
@@ -1015,6 +1165,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. */
     takeReleased(sessionId) {
@@ -1028,6 +1182,14 @@ export class AgentBridge {
     dropReleased(sessionId) {
         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) {
+        this.released.set(session.sessionId, session);
+    }
     get releasedList() {
         return [...this.released.values()];
     }
@@ -1594,9 +1756,56 @@ function snapshot(session) {
         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, capability) {
+    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 } };
+}
+function persistedChatSession(session) {
+    return {
+        sessionId: session.sessionId,
+        acpSessionId: session.acpSessionId,
+        agentId: session.agentId,
+        dshSessionId: session.dshSessionId,
+        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) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const modes = value;
+    return typeof modes.currentModeId === 'string' && Array.isArray(modes.availableModes);
+}
+/** Tolerant shape check for a `usage` value read back from disk. */
+function isPersistedUsage(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const usage = value;
+    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
@@ -2841,6 +3050,29 @@ export class BridgeManager {
      * write would fight with no way to tell which one is live.
      */
     deadlineOverride = {};
+    /**
+     * 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.
+     */
+    idleReleaseOverride;
+    /**
+     * 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".
+     */
+    configuredIdleTimeoutMs;
+    /**
+     * The idle-release window before any override — the tuning this manager was
+     * constructed with (the deployment baseline, or the built-in 30 minutes).
+     */
+    baselineIdleTimeoutMs;
     /**
      * Tuning in force, defaults applied. The approval deadline is rewritten
      * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
@@ -3002,6 +3234,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);
@@ -3018,12 +3251,16 @@ 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();
     }
-    makeBridge(def, onConnectionLost, onCatalog, onCommands) {
-        return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver);
+    makeBridge(def, onConnectionLost, onCatalog, onCommands, onSessionsDirty, onForkCapability) {
+        return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver, onSessionsDirty, onForkCapability);
     }
     /**
      * Every outstanding ask, across all agents, with the view the browser was
@@ -3166,11 +3403,84 @@ 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, parentDshSessionId) {
+        // 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.
      *
@@ -3428,12 +3738,13 @@ export class BridgeManager {
         for (const session of this.dshSessionMap.values()) {
             if (session.dshSessionId !== dshSessionId || session.agentId !== agentId)
                 continue;
+            session.choice = choice;
+            session.modelId = modelId;
             if (session.released)
                 continue;
             await this.alignSessionConfig(session, choice, session.reasoningEffort);
-            session.choice = choice;
-            session.modelId = modelId;
         }
+        this.persistAgents();
     }
     /**
      * Switch the reasoning effort for one chat session.
@@ -3458,14 +3769,18 @@ 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)
+            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();
     }
     /**
      * Set one of the agent's EXTRA config options for one chat session (the
@@ -3658,9 +3973,15 @@ export class BridgeManager {
         return views;
     }
     /**
-     * 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, modeId, agentId) {
         if (agentId !== undefined) {
@@ -3690,15 +4011,62 @@ 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
         // bottom bar remembers its last choice, not just the thought level).
         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) {
+        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`.
      *
@@ -3889,7 +4257,22 @@ 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.idleRelease;
+                    const value = raw?.idleTimeoutMs;
+                    this.idleReleaseOverride = typeof value === 'number' && IDLE_RELEASE_MS.includes(value)
+                        ? value
+                        : undefined;
+                }
+                catch {
+                    this.idleReleaseOverride = undefined;
+                }
                 this.loadPersistedChoices(parsed.conversations);
+                this.loadPersistedChatSessions(parsed.chatSessions);
             }
         }
         catch {
@@ -3938,6 +4321,13 @@ export class BridgeManager {
         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 }),
@@ -3948,12 +4338,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');
         }
@@ -3961,8 +4357,77 @@ export class BridgeManager {
             // Storage persist failure is non-fatal
         }
     }
+    /**
+     * 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.
+     */
+    loadPersistedChatSessions(raw) {
+        if (!Array.isArray(raw))
+            return;
+        for (const row of raw) {
+            if (row === null || typeof row !== 'object')
+                continue;
+            const record = row;
+            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;
+            const session = {
+                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(),
+                transcript: new Transcript(this.transcriptMax),
+            };
+            this.dshSessionMap.set(`${dshSessionId}:${agentId}`, session);
+            this.bridge(agentId).parkReleased(session);
+        }
+    }
     // ---- Model catalog ----
     catalogs = new Map();
+    /**
+     * 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).
+     */
+    forkCaps = new Map();
     /**
      * The slash commands each agent declared in its most recent session, cached
      * per agent and persisted alongside the model catalog.
@@ -4035,6 +4500,10 @@ export class BridgeManager {
                 if (typeof raw !== 'object' || raw === null)
                     continue;
                 const row = raw;
+                // 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)) {
@@ -4068,6 +4537,12 @@ export class BridgeManager {
             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 {
@@ -4162,6 +4637,32 @@ export class BridgeManager {
         // first `/`, when there is still no live session to ask.
         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).
+     */
+    noteForkCapability(agentId, supported) {
+        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.
+     */
+    canForkNow(agentId) {
+        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.
      *
@@ -4602,6 +5103,10 @@ export class BridgeManager {
                     this.absorbCatalog(observedAgentId, configOptions);
             }, (observedAgentId, commands) => {
                 this.absorbCommands(observedAgentId, commands);
+            }, () => {
+                this.persistAgents();
+            }, (observedAgentId, supported) => {
+                this.noteForkCapability(observedAgentId, supported);
             });
             this.bridges.set(agentId, bridge);
         }
@@ -4760,11 +5265,15 @@ export class BridgeManager {
         }
         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)
+        const droppedFork = this.forkCaps.delete(agentId);
+        if (droppedCatalog || droppedCommands || droppedFork)
             this.persistCatalogs();
         this.persistAgents();
         this.hub.broadcast({
@@ -5004,6 +5513,23 @@ export class BridgeManager {
         this.tagHaloSetting = validateTagHalo(halo);
         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) {
+        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).
@@ -5051,6 +5577,56 @@ export class BridgeManager {
             deadlines.configuredMode = this.configuredMode;
         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() {
+        const release = {
+            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, reset = false) {
+        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.
+     */
+    applyIdleReleaseTuning() {
+        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.
+     */
+    idleTimeoutMs() {
+        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 —
@@ -5108,10 +5684,17 @@ export class BridgeManager {
     chatAgentIntent = new Map();
     /** Drop every chat-keyed record pointing at one host session (close/stop paths). */
     forgetDshSession(sessionId) {
+        let dropped = false;
         for (const [key, session] of this.dshSessionMap) {
-            if (session.sessionId === sessionId)
+            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();
     }
     sessionWorkspaceResolver;
     acpModeResolver;
@@ -5265,6 +5848,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
@@ -5314,6 +5900,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;
     }
     /**