dsh-ntr 0.1.3 → 0.1.5

package/lib/bridge.js

@@ -12,17 +12,70 @@ import { delimiter, dirname, join } from 'node:path';
 import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
-import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, parseCatalogOptions, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, } from "./impl.js";
+import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, } from "./impl.js";
 import { DEFAULT_TAG_HALO } from "./protocol.js";
 const STDERR_TAIL_LINES = 40;
 /** Single fs/read_text_file answer cap — agents reading huge files must page via `line`/`limit`. */
 const FS_MAX_READ_BYTES = 2 * 1024 * 1024;
 /** Single fs/write_text_file payload cap. */
 const FS_MAX_WRITE_BYTES = 2 * 1024 * 1024;
+/**
+ * The plugin's normalized MCP server shape → the ACP wire shape.
+ *
+ * THE WIRE SHAPE IS ASYMMETRIC, and getting it wrong is SILENT:
+ *
+ *  - the stdio variant carries NO `type` field — an entry that carries
+ *    `type:'stdio'` is accepted by the agent and then never connected
+ *    (measured against codebuddy: the server never appeared, the agent just
+ *    reported the tool as missing);
+ *  - http/sse DO carry `type`;
+ *  - `env` / `headers` are `[{name,value}]` arrays on the wire, while the
+ *    plugin stores them as records (like `AcpAgentDef.env`).
+ *
+ * So the conversion lives here, once, and each branch is annotated with the
+ * SDK's OWN variant type — a wrong conversion does not compile. (The bare
+ * `McpServer` union is too loose to catch it: its excess-property check
+ * accepts any member's keys, so a stdio entry carrying `type:'stdio'` would
+ * type-check against the http variant and only fail at runtime, inside the
+ * agent, as a server that never connects.)
+ */
+function toAcpMcpServers(defs) {
+    if (defs === undefined)
+        return [];
+    return defs.map(def => {
+        if (def.transport === 'stdio') {
+            // NO `type` here — see the note above.
+            const server = {
+                name: def.name,
+                command: def.command,
+                args: def.args ?? [],
+                env: Object.entries(def.env ?? {}).map(([name, value]) => ({ name, value })),
+            };
+            return server;
+        }
+        if (def.transport === 'http') {
+            const server = {
+                type: 'http',
+                name: def.name,
+                url: def.url,
+                headers: Object.entries(def.headers ?? {}).map(([name, value]) => ({ name, value })),
+            };
+            return server;
+        }
+        const server = {
+            type: 'sse',
+            name: def.name,
+            url: def.url,
+            headers: Object.entries(def.headers ?? {}).map(([name, value]) => ({ name, value })),
+        };
+        return server;
+    });
+}
 const DEFAULT_TUNING = {
     startupTimeoutMs: 60_000,
     permissionTimeoutMs: 0,
     permissionFallbackTimeoutMs: 300_000,
+    nativeApprovalTimeoutMs: 300_000,
     cancelFallbackMs: 15_000,
     staleCancelRetryDelayMs: 600,
     staleCancelMaxRetries: 2,
@@ -64,7 +117,18 @@ export class AgentBridge {
     ledgerFallbacks = new Map;
     startupTimeoutMs;
     permissionTimeoutMs;
+    /**
+     * The two approval deadlines are NOT readonly, unlike their neighbors: the
+     * settings page rewrites them on a running bridge
+     * ({@link AgentBridge.applyApprovalDeadlines}), so a user editing the window
+     * does not have to kill every live session to see it take effect. Both are
+     * read per ask — `nativeApprovalTimeoutMs` when the native ask is armed,
+     * `permissionFallbackTimeoutMs` when the ledger ask's deadline is chosen — so
+     * a reassignment reaches every ask from that moment on. An ask already
+     * holding an armed timer keeps the window it was started with.
+     */
     permissionFallbackTimeoutMs;
+    nativeApprovalTimeoutMs;
     cancelFallbackMs;
     staleCancelRetryDelayMs;
     staleCancelMaxRetries;
@@ -101,7 +165,13 @@ export class AgentBridge {
     constructor(def, hub, transcriptMax, 
     /** Called when the connection dies so the manager can settle outstanding prompts. */
     onConnectionLost, 
-    /** Observes `configOptions` from any real session so the manager's model catalog stays warm. */
+    /**
+     * Observes `configOptions` from any real session so the manager's model
+     * catalog stays warm. `shapeOnly` marks a per-session answer (a
+     * `session/set_config_option` response): only the option SHAPE belongs in
+     * the agent-level catalog, never its `currentValue` — see
+     * {@link BridgeManager.absorbCatalogShape}.
+     */
     onCatalog, 
     /** Observes `availableCommands` from any real session so the agent's slash menu survives its sessions. */
     onCommands, tuning, 
@@ -127,6 +197,7 @@ export class AgentBridge {
         this.startupTimeoutMs = merged.startupTimeoutMs;
         this.permissionTimeoutMs = merged.permissionTimeoutMs;
         this.permissionFallbackTimeoutMs = merged.permissionFallbackTimeoutMs;
+        this.nativeApprovalTimeoutMs = merged.nativeApprovalTimeoutMs;
         this.cancelFallbackMs = merged.cancelFallbackMs;
         this.staleCancelRetryDelayMs = merged.staleCancelRetryDelayMs;
         this.staleCancelMaxRetries = merged.staleCancelMaxRetries;
@@ -134,6 +205,22 @@ export class AgentBridge {
         this.defaultIdleTimeoutMs = merged.idleTimeoutMs;
         this.probeIdleTimeoutMs = merged.probeIdleTimeoutMs;
     }
+    /**
+     * Adopt a rewritten approval deadline (the settings page's write). Only the
+     * two degraded-route windows live here; every other tuning value is fixed at
+     * construction, because a live bridge cannot meaningfully adopt a new startup
+     * or cancel window mid-flight.
+     *
+     * Deliberately does NOT re-arm anything: an ask that already holds a timer
+     * keeps the window it was started with, and the next ask reads the new value.
+     * Re-arming would move the goalposts under a human who is already deciding.
+     */
+    applyApprovalDeadlines(patch) {
+        if (patch.nativeApprovalTimeoutMs !== undefined)
+            this.nativeApprovalTimeoutMs = patch.nativeApprovalTimeoutMs;
+        if (patch.permissionFallbackTimeoutMs !== undefined)
+            this.permissionFallbackTimeoutMs = patch.permissionFallbackTimeoutMs;
+    }
     /**
      * 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
@@ -464,7 +551,14 @@ export class AgentBridge {
             protocolVersion: PROTOCOL_VERSION,
             // The fs handlers are implemented below behind the same workspace
             // sandbox that gates session cwds; terminal is not implemented.
-            clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: false },
+            // `session.configOptions.boolean` advertises the toggle form of
+            // `configOptions`; agents that gate `type: "boolean"` entries on it
+            // would otherwise never publish them.
+            clientCapabilities: {
+                fs: { readTextFile: true, writeTextFile: true },
+                terminal: false,
+                session: { configOptions: { boolean: {} } },
+            },
             clientInfo: { name: 'dsh-ntr', title: 'DSH NTR', version: '0.1.0' },
         }), 'initialize');
         this.initResult = init;
@@ -515,8 +609,9 @@ export class AgentBridge {
         if (conn === undefined)
             throw new AcpError('agent_unreachable', 'acp: connection is not open');
         const resolved = resolveSessionCwd(this.def, cwd, p => realpathSync(p), extraRoots);
-        const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: [] }), 'session/new');
-        if (this.onCatalog !== undefined && result.configOptions !== undefined && result.configOptions !== null) {
+        const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/new');
+        // An empty `configOptions` answer is a non-answer — see `usableConfigOptions`.
+        if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
             this.onCatalog(this.def.id, result.configOptions);
         }
         const session = {
@@ -541,7 +636,7 @@ export class AgentBridge {
                     },
                 }
                 : {}),
-            ...(result.configOptions !== undefined && result.configOptions !== null ? { configOptions: result.configOptions } : {}),
+            ...(usableConfigOptions(result.configOptions) ? { configOptions: result.configOptions } : {}),
         };
         this.sessions.set(session.sessionId, session);
         this.acpIndex.set(session.acpSessionId, session);
@@ -559,6 +654,15 @@ export class AgentBridge {
      * Spawn a throwaway ACP session purely to read its `configOptions` (the
      * model catalog probe). Deliberately bypasses the live-session bookkeeping
      * so probe sessions never surface in the browser session list.
+     *
+     * THE PROBE SENDS THE AGENT'S OWN MCP LIST, not an empty one. Measured
+     * against codebuddy: the servers handed to `session/new` land in the
+     * agent PROCESS's dynamic MCP scope, so a probe that sent an empty list
+     * would REPLACE that scope and drop the MCP servers of the live sessions
+     * on the same connection (the agent logged
+     * `serverManager.delete("injected")` and the live session's
+     * `mcp__injected__*` tools disappeared). One list per agent process is the
+     * only shape that keeps every session of that process consistent.
      */
     async probeConfigOptions() {
         // A probe is the reason an agent process can be resident with NOTHING else
@@ -571,7 +675,7 @@ export class AgentBridge {
             if (conn === undefined)
                 throw new AcpError('agent_unreachable', 'acp: connection is not open');
             const resolved = resolveSessionCwd(this.def, undefined, p => realpathSync(p));
-            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: [] }), 'session/new');
+            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/new');
             await conn.agent.request(methods.agent.session.close, { sessionId: result.sessionId }).catch(() => { });
             return Array.isArray(result.configOptions) ? result.configOptions : [];
         }
@@ -626,6 +730,13 @@ export class AgentBridge {
         // own turn apart from a later one.
         session.cancelRequestedAtTurn = session.turnSeq;
         await this.conn.agent.notify(methods.agent.session.cancel, { sessionId: session.acpSessionId }).catch(() => { });
+        // The ACP spec's counterpart to the notification we just sent: a client that
+        // cancels MUST answer every pending `session/request_permission` with
+        // `cancelled`. Leaving them open would hold the agent's tool call blocked on
+        // an answer that can no longer arrive — the turn is over, the human's
+        // decision is "stop". OmniTerm does the same from `AcpClient::cancel`
+        // (`PermissionManager::cancel_all`).
+        this.settlePermissions(session);
         this.armCancelFallback(session);
     }
     /**
@@ -719,8 +830,8 @@ export class AgentBridge {
             // is in flight, and let the browser drop its blocks/watermark first.
             this.acpIndex.set(session.acpSessionId, session);
             this.hub.broadcast({ type: 'session/reset', sessionId: session.sessionId, session: snapshot(session) });
-            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.load, { sessionId: session.acpSessionId, cwd: resolved, mcpServers: [] }), 'session/load');
-            if (this.onCatalog !== undefined && result.configOptions !== undefined && result.configOptions !== null) {
+            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.load, { sessionId: session.acpSessionId, cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/load');
+            if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
                 this.onCatalog(this.def.id, result.configOptions);
             }
             session.modes = result.modes !== undefined && result.modes !== null
@@ -733,7 +844,7 @@ export class AgentBridge {
                     })),
                 }
                 : session.modes;
-            if (Array.isArray(result.configOptions))
+            if (usableConfigOptions(result.configOptions))
                 session.configOptions = result.configOptions;
             this.sessions.set(session.sessionId, session);
             this.released.delete(session.sessionId);
@@ -825,15 +936,26 @@ export class AgentBridge {
         const conn = this.conn;
         if (conn === undefined)
             throw new AcpError('agent_unreachable', 'acp: connection is not open');
-        const result = await this.runCommand(() => conn.agent.request(methods.agent.session.setConfigOption, { sessionId: session.acpSessionId, configId, value }));
+        // A toggle must say so on the wire: the request union discriminates on
+        // `type`, and a bare boolean `value` is not a select value id.
+        const params = typeof value === 'boolean'
+            ? { sessionId: session.acpSessionId, configId, value, type: 'boolean' }
+            : { sessionId: session.acpSessionId, configId, value };
+        const result = await this.runCommand(() => conn.agent.request(methods.agent.session.setConfigOption, params));
         // The response carries the full authoritative option set; some agents
         // (pi-acp observed) never re-notify after a client-driven set. It feeds the
-        // SESSION snapshot only — never the agent-level catalog: `currentValue` in
-        // a per-session answer describes this session's pick, and promoting it to
-        // the catalog would turn the seat's own choice into `reasoning.defaultEffort`
-        // for every other conversation (and back onto itself next turn).
-        if (Array.isArray(result.configOptions))
+        // SESSION snapshot first — `currentValue` in a per-session answer describes
+        // this session's pick, and promoting it to the catalog would turn the
+        // seat's own choice into `reasoning.defaultEffort` for every other
+        // conversation (and back onto itself next turn). The option SHAPE still
+        // reaches the agent-level catalog (`shapeOnly`): this response is often the
+        // only place an agent publishes how its option set changes with the model
+        // (opencode offers `thought_level` just for models with variants), and the
+        // composer's thought chip is driven by the catalog.
+        if (usableConfigOptions(result.configOptions)) {
             session.configOptions = result.configOptions;
+            this.onCatalog?.(this.def.id, result.configOptions, true);
+        }
         this.publishMeta(session);
     }
     publishMeta(session) {
@@ -946,6 +1068,11 @@ export class AgentBridge {
                 resolve(outcome.outcome === 'selected'
                     ? { outcome: { outcome: 'selected', optionId: outcome.optionId } }
                     : { outcome: { outcome: 'cancelled' } });
+            }, {
+                // Kept for the reconnect replay: a client that connects after the ask
+                // was broadcast must be re-shown the very card it has to answer.
+                toolCall,
+                options: options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })),
             });
             // Deadline (`permissionTimeoutMs`): an approval left unanswered is
             // answered `cancelled` on the human's behalf instead of hanging the turn
@@ -953,14 +1080,22 @@ export class AgentBridge {
             // exception is a DEGRADED native route: the conversation just failed to
             // show the question, so waiting forever would hang the turn behind an
             // ask nobody can see there, and the fallback deadline applies instead
-            // (see `BridgeTuning.permissionFallbackTimeoutMs`).
+            // (see `BridgeTuning.permissionFallbackTimeoutMs`). `native-timeout` is
+            // the same degradation reached from the other side: the host took the
+            // ask and never answered it.
             const timeoutMs = this.permissionTimeoutMs > 0
                 ? this.permissionTimeoutMs
-                : native.reason === 'unavailable' ? this.permissionFallbackTimeoutMs : 0;
+                : native.reason === 'unavailable' || native.reason === 'native-timeout'
+                    ? this.permissionFallbackTimeoutMs
+                    : 0;
             // Recorded before the broadcast: the hub is synchronous, and the chat
             // line `streamPrompt` folds from this frame words itself by the path
             // this ask actually took.
-            this.ledgerFallbacks.set(requestId, { reason: native.reason, timeoutMs });
+            this.ledgerFallbacks.set(requestId, {
+                reason: native.reason,
+                timeoutMs,
+                ...(native.reason === 'native-timeout' ? { waitedMs: this.nativeApprovalTimeoutMs } : {}),
+            });
             if (timeoutMs > 0) {
                 timer = setTimeout(() => {
                     if (!this.permissions.has(requestId))
@@ -969,7 +1104,10 @@ export class AgentBridge {
                         type: 'agent/notice',
                         agentId: this.def.id,
                         level: 'info',
-                        text: `acp: permission request timed out after ${String(Math.round(timeoutMs / 1000))}s; answered "cancelled"`,
+                        // Name what was missed, the way a human needs it: which operation
+                        // sat unanswered, and for how long (OmniTerm's reaper writes the
+                        // same "you missed this" notice before it acts).
+                        text: `acp: permission request for "${permissionToolName(toolCall)}" timed out after ${String(Math.round(timeoutMs / 1000))}s; answered "cancelled"`,
                     });
                     this.permissions.respond(requestId, { outcome: 'cancelled' });
                 }, timeoutMs);
@@ -1000,8 +1138,19 @@ export class AgentBridge {
      * open turn, so a session started over `/acp` (no chat turn) cannot be
      * routed and must stay on the ledger path.
      *
-     * No `permissionTimeoutMs` timer is armed here on purpose: the human answers
-     * inside the conversation, and a host-side deadline would answer for them.
+     * The ask is raced against {@link BridgeTuning.nativeApprovalTimeoutMs}. A
+     * routed ask has exactly one answer entry — the composer takeover — and no
+     * broadcast at all, so a host that takes the question and never renders it
+     * would leave the turn hanging behind something invisible. Past the deadline
+     * the ask is WITHDRAWN (the signal handed to the host aborts, which settles
+     * its waterfall `cancelled` and drops the composer panel) and reported as
+     * `native-timeout`, sending the question to the ledger where the chat line
+     * and the settings card are both visible. Withdrawing is not answering: a
+     * human mid-decision finds the same question in the settings panel.
+     *
+     * No deadline is armed on the ledger paths (`no-requester`,
+     * `no-chat-session`): those never reach the host, and their answer entry is
+     * the settings panel the chat line already points at.
      *
      * @returns the agent-facing response, or the reason the ask must fall back
      * to the ledger (see {@link LedgerFallbackReason}).
@@ -1012,20 +1161,52 @@ export class AgentBridge {
             return { reason: 'no-requester' };
         if (session.dshSessionId === undefined)
             return { reason: 'no-chat-session' };
+        // One signal carries both withdrawals: the agent's own cancel (whatever
+        // aborted the ACP request) and the deadline. The host's waterfall races its
+        // answerers against this signal, so aborting is a clean withdrawal rather
+        // than a leak.
+        const withdraw = new AbortController();
+        const askSignal = signal === undefined ? withdraw.signal : AbortSignal.any([signal, withdraw.signal]);
+        let timer;
+        let timedOut = false;
+        const deadline = this.nativeApprovalTimeoutMs > 0
+            ? new Promise(resolve => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    withdraw.abort();
+                    resolve({ timedOut: true });
+                }, this.nativeApprovalTimeoutMs);
+                timer.unref?.();
+            })
+            : undefined;
         let outcome;
         try {
-            outcome = await requester({
+            const asked = requester({
                 dshSessionId: session.dshSessionId,
                 agentId: this.def.id,
                 toolName: permissionToolName(toolCall),
-                ...(signal === undefined ? {} : { signal }),
+                signal: askSignal,
             });
+            // A withdrawn ask settles on the host's own schedule; dropping it here
+            // must not surface as an unhandled rejection later.
+            asked.catch(() => { });
+            const settled = deadline === undefined
+                ? await asked.then(o => ({ outcome: o }))
+                : await Promise.race([asked.then(o => ({ outcome: o })), deadline]);
+            // The flag, not the race winner, decides: the host may settle `cancelled`
+            // from the very abort the deadline caused, and that is still a timeout.
+            if (timedOut || 'timedOut' in settled)
+                return { reason: 'native-timeout' };
+            outcome = settled.outcome;
         }
         catch {
             // Synchronous throw or rejection, either way: the ask falls back to the
             // ledger. An approval failure must never break the agent's turn.
             outcome = 'unavailable';
         }
+        finally {
+            clearTimeout(timer);
+        }
         if (outcome === 'unavailable')
             return { reason: 'unavailable' };
         const response = nativeOutcomeResponse(outcome, options);
@@ -1115,7 +1296,10 @@ export class AgentBridge {
                 session.modes = { ...session.modes, currentModeId: update.currentModeId };
                 break;
             case 'config_option_update':
-                session.configOptions = update.configOptions ?? [];
+                // Empty answers never overwrite the last known set — see `usableConfigOptions`.
+                if (!usableConfigOptions(update.configOptions))
+                    break;
+                session.configOptions = update.configOptions;
                 this.onCatalog?.(this.def.id, session.configOptions);
                 break;
             case 'available_commands_update':
@@ -1151,9 +1335,31 @@ export class AgentBridge {
     }
 }
 /** Human-facing identity of an ACP tool call (the approval headline). */
-function permissionToolName(toolCall) {
+/**
+ * Human-facing name of the tool an ask is about, for the chat line and the
+ * timeout notice.
+ *
+ * The ACP `toolCall.title` is the declared field, but it is OPTIONAL and real
+ * agents omit it: codebuddy puts the name in `_meta["codebuddy.ai/toolName"]`
+ * (observed live — without the fallback the notice reads `for "tool call"`,
+ * which tells the human nothing about what they missed). So read `title` first,
+ * then any `_meta` key whose last segment is `toolName`, then the standard
+ * `kind`, and only then give up with the generic phrase. Nothing is invented:
+ * every step reads a key the agent itself declared.
+ */
+export function permissionToolName(toolCall) {
     const row = (typeof toolCall === 'object' && toolCall !== null ? toolCall : {});
-    return typeof row.title === 'string' && row.title !== '' ? row.title : 'tool call';
+    if (typeof row.title === 'string' && row.title !== '')
+        return row.title;
+    const meta = (typeof row._meta === 'object' && row._meta !== null ? row._meta : {});
+    for (const [key, value] of Object.entries(meta)) {
+        const segment = key.split('/').at(-1) ?? key;
+        if (segment.toLowerCase() === 'toolname' && typeof value === 'string' && value !== '')
+            return value;
+    }
+    if (typeof row.kind === 'string' && row.kind !== '')
+        return row.kind;
+    return 'tool call';
 }
 /**
  * Translate a native approval outcome into the ACP option the agent must see.
@@ -2271,13 +2477,24 @@ class TurnStreamController {
         // The line must not point at a place with no answer entry, and the bridge
         // knows which path this ask took (`ledgerFallbackOf`, recorded before the
         // frame was broadcast). On the DESIGNED ledger paths the settings panel's
-        // card is the answer entry. A DEGRADED native route carries a deadline.
+        // card is the answer entry. A DEGRADED native route carries a deadline and
+        // has to say why the conversation is not showing the question — as an
+        // OBSERVED FACT, not a guessed cause: "no answer within Ns" is true whether
+        // the human was slow or the host never rendered the question.
         const fallback = this.bridge.ledgerFallbackOf(event.requestId);
-        return fallback?.reason === 'unavailable'
-            ? fallback.timeoutMs > 0
-                ? `\n> 🔐 [Permission Required: ${title}] - the approval service is unavailable; approve in Settings within ${String(Math.round(fallback.timeoutMs / 1000))}s or this request is cancelled\n`
-                : `\n> 🔐 [Permission Required: ${title}] - the approval service is unavailable; please approve in Settings\n`
-            : `\n> 🔐 [Permission Required: ${title}] - please approve in Settings\n`;
+        const why = fallback === undefined
+            ? undefined
+            : fallback.reason === 'unavailable'
+                ? 'the approval service is unavailable'
+                : fallback.reason === 'native-timeout'
+                    ? `no answer in the conversation within ${String(Math.round((fallback.waitedMs ?? 0) / 1000))}s`
+                    : undefined;
+        if (fallback === undefined || why === undefined) {
+            return `\n> 🔐 [Permission Required: ${title}] - please approve in Settings\n`;
+        }
+        return fallback.timeoutMs > 0
+            ? `\n> 🔐 [Permission Required: ${title}] - ${why}; approve in Settings within ${String(Math.round(fallback.timeoutMs / 1000))}s or this request is cancelled\n`
+            : `\n> 🔐 [Permission Required: ${title}] - ${why}; please approve in Settings\n`;
     }
 }
 /** Chunk text shared by the controller's fold (string / object / array forms). */
@@ -2315,13 +2532,47 @@ export class BridgeManager {
     configStoragePath;
     catalogStoragePath;
     probeModelsOnBoot;
-    tuning;
     bridges = new Map();
     defsMap = new Map();
     /** The plugin's own default ACP agent id (persisted; see `persistAgents`). */
     defaultAgentId;
     /** The agent tag's halo preference (persisted; see `persistAgents`). */
     tagHaloSetting = { ...DEFAULT_TAG_HALO };
+    /**
+     * What `cordis.patch.yml` asked for, by key — ONLY the keys it actually
+     * names. This is the deployment baseline, kept apart from
+     * {@link deadlineOverride} so the settings card can tell the user which of
+     * the two is winning. Empty when the file says nothing about either window,
+     * in which case {@link baselineDeadlines} (the built-in default) applies.
+     */
+    configuredDeadlines = {};
+    /**
+     * The value each deadline had before any override — the tuning this manager
+     * was constructed with, which already carries the validated config file (the
+     * host entry passes `validateConfig`'s output) or the built-in default.
+     *
+     * Held separately from {@link configuredDeadlines} because the two answer
+     * different questions: this one is what RUNS when nothing is overridden, that
+     * one is what the config file NAMED (which the card shows as the reset target
+     * and a bare default does not deserve). A manager built without tuning at all
+     * — a direct consumer, a test — gets `DEFAULT_TUNING` here and stays correct.
+     */
+    baselineDeadlines;
+    /**
+     * The settings page's own write, persisted with the agent registry. Merged
+     * OVER {@link baselineDeadlines}: once a user picks a window in the UI, that
+     * pick is what runs, and the config file becomes the value the reset button
+     * returns to. Without this split a hand-edited `cordis.patch.yml` and a UI
+     * write would fight with no way to tell which one is live.
+     */
+    deadlineOverride = {};
+    /**
+     * Tuning in force, defaults applied. The two approval deadlines are rewritten
+     * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
+     * rather than the constructor's parameter: every bridge built afterwards
+     * inherits the rewrite instead of the boot-time value.
+     */
+    tuning;
     /**
      * The in-flight (or just-settled) segmented turn of one DSH chat session.
      * Keyed by chat session id because the continuation steps of a segmented
@@ -2368,7 +2619,18 @@ export class BridgeManager {
         this.configStoragePath = configStoragePath;
         this.catalogStoragePath = catalogStoragePath;
         this.probeModelsOnBoot = probeModelsOnBoot;
-        this.tuning = tuning;
+        // Held as a live object rather than the raw parameter: the two approval
+        // deadlines are rewritten in place when the settings page writes them (see
+        // `applyDeadlineTuning`), and every bridge built afterwards must inherit
+        // the rewrite instead of the boot-time value.
+        this.tuning = { ...DEFAULT_TUNING, ...tuning };
+        // The pre-override deadline values, snapshotted before anything can rewrite
+        // them. Everything else in `tuning` is fixed for the manager's lifetime, so
+        // only this pair needs a snapshot.
+        this.baselineDeadlines = {
+            nativeApprovalTimeoutMs: this.tuning.nativeApprovalTimeoutMs,
+            permissionFallbackTimeoutMs: this.tuning.permissionFallbackTimeoutMs,
+        };
         for (const def of defs) {
             this.defsMap.set(def.id, def);
         }
@@ -2381,6 +2643,9 @@ export class BridgeManager {
         }
         this.loadPersistedAgents();
         this.loadPersistedCatalogs();
+        // A persisted deadline override must reach the tuning the bridges are built
+        // from, not just the settings card's readout.
+        this.applyDeadlineTuning();
         // 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();
@@ -2401,6 +2666,19 @@ export class BridgeManager {
     approvalRouting() {
         return this.approvalRequester !== undefined;
     }
+    /**
+     * Every outstanding ledger ask, across all agents, with the view the browser
+     * was shown it — the source of the reconnect replay (see
+     * `permissionReplayFrames`). Asks on the native route are deliberately
+     * absent: they broadcast nothing and their answer entry is the composer
+     * takeover the client already holds.
+     */
+    pendingPermissionViews() {
+        const views = [];
+        for (const bridge of this.bridges.values())
+            views.push(...bridge.permissions.pendingViews());
+        return views;
+    }
     /**
      * Let the host resolve a chat session's workspace root — the sidebar's
      * selected workspace, which the agent's session and its process both run in.
@@ -2864,8 +3142,19 @@ export class BridgeManager {
         if (option === undefined) {
             throw new AcpError('unknown_config', `acp: agent "${bound}" publishes no extra config option "${configId}"`);
         }
-        if (!option.choices.some(choice => choice.value === value)) {
-            throw new AcpError('bad_config', `acp: "${value}" is not a value of config option "${configId}"`);
+        if (option.kind === 'boolean') {
+            // The browser sends 'true' / 'false' from a checkbox row; the wire and
+            // the persisted pick both use the real boolean.
+            const toggle = typeof value === 'boolean'
+                ? value
+                : value === 'true' ? true : value === 'false' ? false : undefined;
+            if (toggle === undefined) {
+                throw new AcpError('bad_config', `acp: "${String(value)}" is not a boolean value of config option "${configId}"`);
+            }
+            value = toggle;
+        }
+        else if (typeof value !== 'string' || !option.choices.some(choice => choice.value === value)) {
+            throw new AcpError('bad_config', `acp: "${String(value)}" is not a value of config option "${configId}"`);
         }
         const current = this.chatAgentIntent.get(dshSessionId);
         const extraConfigs = current?.agentId === bound ? { ...current.extraConfigs } : {};
@@ -2962,12 +3251,17 @@ export class BridgeManager {
                     });
                     continue;
                 }
-                if (!option.choices.some(entry => entry.value === value)) {
+                // A toggle's truth is its boolean itself; a select's is membership in
+                // the choices the agent still offers.
+                const usable = option.kind === 'boolean'
+                    ? typeof value === 'boolean'
+                    : typeof value === 'string' && option.choices.some(entry => entry.value === value);
+                if (!usable) {
                     this.hub.broadcast({
                         type: 'agent/notice',
                         agentId: session.agentId,
                         level: 'error',
-                        text: `acp: agent "${session.agentId}" no longer offers "${value}" for config "${configId}"; keeping its own`,
+                        text: `acp: agent "${session.agentId}" no longer offers "${String(value)}" for config "${configId}"; keeping its own`,
                     });
                     continue;
                 }
@@ -3169,6 +3463,17 @@ export class BridgeManager {
                 catch {
                     this.tagHaloSetting = { ...DEFAULT_TAG_HALO };
                 }
+                // The settings page's approval-deadline override. Re-validated on every
+                // boot because the state file is user- and version-editable: an
+                // unreadable value must not poison the deadline, and a value the
+                // validator accepts must be the value that runs (a UI write that did
+                // not survive a restart would read as a broken setting).
+                try {
+                    this.deadlineOverride = validateApprovalDeadlines(parsed.approvalDeadlines ?? {});
+                }
+                catch {
+                    this.deadlineOverride = {};
+                }
                 this.loadPersistedChoices(parsed.conversations);
             }
         }
@@ -3194,7 +3499,7 @@ export class BridgeManager {
                 continue;
             const configs = extraConfigs !== null && typeof extraConfigs === 'object' && !Array.isArray(extraConfigs)
                 ? Object.fromEntries(Object.entries(extraConfigs)
-                    .filter(([, value]) => typeof value === 'string' && value !== ''))
+                    .filter(([, value]) => typeof value === 'boolean' || (typeof value === 'string' && value !== '')))
                 : {};
             this.chatAgentIntent.set(dshSessionId, {
                 agentId,
@@ -3223,6 +3528,11 @@ export class BridgeManager {
                 ...(this.defaultAgentId === undefined ? {} : { defaultAgentId: this.defaultAgentId }),
                 tagHalo: this.tagHaloSetting,
                 agents: [...this.defsMap.values()],
+                // The settings page's approval deadlines. Absent while none was ever
+                // written, so a fresh deployment's state file stays exactly as it was.
+                ...(Object.keys(this.deadlineOverride).length === 0
+                    ? {}
+                    : { approvalDeadlines: { ...this.deadlineOverride } }),
                 // The per-conversation picks: agent + model + thought level + mode +
                 // extra config values chosen in the composer, including for
                 // conversations with no live session yet.
@@ -3359,6 +3669,9 @@ export class BridgeManager {
      * current `parseCatalogOptions` has now seen this agent's real answer.
      */
     absorbCatalog(agentId, configOptions) {
+        // Empty / absurd answers never overwrite known state — see `usableConfigOptions`.
+        if (!usableConfigOptions(configOptions))
+            return this.catalogs.get(agentId) ?? { catalog: {}, updatedAt: 0 };
         const catalog = parseCatalogOptions(configOptions);
         this.catalogStale.delete(agentId);
         const existing = this.catalogs.get(agentId);
@@ -3386,6 +3699,30 @@ export class BridgeManager {
             this.broadcastExposure(agentId);
         return entry;
     }
+    /**
+     * Fold a per-session option answer's SHAPE into the agent's catalog.
+     *
+     * The counterpart of {@link absorbCatalog} for `session/set_config_option`
+     * responses: which options exist and which choices they offer is agent
+     * knowledge the seat must show (the composer's thought chip only renders
+     * when the catalog has `thought_level`, and some agents publish it only in
+     * the answer to a model change), while a per-session `currentValue` stays
+     * out of it. No auto-exposure and no staleness discharge either — this is
+     * one session's answer, not the agent-level observation those marks track.
+     */
+    absorbCatalogShape(agentId, configOptions) {
+        if (!usableConfigOptions(configOptions))
+            return;
+        const observed = parseCatalogOptions(configOptions);
+        const existing = this.catalogs.get(agentId);
+        const catalog = mergeCatalogShape(existing?.catalog, observed);
+        if (existing !== undefined && JSON.stringify(existing.catalog) === JSON.stringify(catalog))
+            return;
+        const entry = { catalog, updatedAt: Date.now() };
+        this.catalogs.set(agentId, entry);
+        this.persistCatalogs();
+        this.hub.broadcast({ type: 'catalog/updated', agentId, updatedAt: entry.updatedAt });
+    }
     /**
      * Remember the slash commands an agent declared in a real session.
      *
@@ -3418,11 +3755,12 @@ export class BridgeManager {
      * selection would resurrect a model the user deliberately unchecked every
      * time the agent repeats its catalog. The first observation has no baseline
      * (`before === undefined`), so it adds nothing; the user can still add the
-     * whole list with one click in the settings card.
+     * whole list with one click in the settings card. Discovery is ON unless the
+     * agent definition explicitly opts out with `autoDiscoverModels: false`.
      */
     autoExposeNewModels(agentId, next, before) {
         const def = this.defsMap.get(agentId);
-        if (def?.autoDiscoverModels !== true || before === undefined)
+        if (def === undefined || def.autoDiscoverModels === false || before === undefined)
             return false;
         const known = new Set((before.model?.choices ?? []).map(choice => choice.value));
         const exposed = new Set(def.exposedModels ?? []);
@@ -3444,7 +3782,7 @@ export class BridgeManager {
             type: 'agent/exposure',
             agentId,
             exposedModels: [...(def.exposedModels ?? [])],
-            autoDiscoverModels: def.autoDiscoverModels === true,
+            autoDiscoverModels: def.autoDiscoverModels !== false,
         });
     }
     catalogFor(agentId) {
@@ -3618,6 +3956,7 @@ export class BridgeManager {
                 extras: extraOptions.map(option => ({
                     configId: option.configId,
                     name: option.name,
+                    ...(option.kind === 'boolean' ? { kind: 'boolean' } : {}),
                     ...(option.currentValue === null ? {} : { currentValue: option.currentValue }),
                     choices: option.choices.map(choice => ({
                         id: choice.value,
@@ -3841,8 +4180,11 @@ export class BridgeManager {
         if (bridge === undefined) {
             bridge = this.makeBridge(def, (b, reason) => {
                 this.connectionLost(b, reason);
-            }, (observedAgentId, configOptions) => {
-                this.absorbCatalog(observedAgentId, configOptions);
+            }, (observedAgentId, configOptions, shapeOnly) => {
+                if (shapeOnly)
+                    this.absorbCatalogShape(observedAgentId, configOptions);
+                else
+                    this.absorbCatalog(observedAgentId, configOptions);
             }, (observedAgentId, commands) => {
                 this.absorbCommands(observedAgentId, commands);
             });
@@ -3970,16 +4312,17 @@ export class BridgeManager {
      * Toggle auto-discovery of newly published models. Lightweight like
      * `setExposedModels`: the def is mutated in place (live bridges share the
      * object) and persisted; no process is restarted, and the current selection
-     * is left exactly as it is.
+     * is left exactly as it is. On is the default, so only the opt-out
+     * (`false`) is written to the file.
      */
     async setAutoDiscoverModels(agentId, autoDiscoverModels) {
         const def = this.defsMap.get(agentId);
         if (def === undefined)
             throw new AcpError('unknown_agent', `acp: agent "${agentId}" is not configured`);
         if (autoDiscoverModels)
-            def.autoDiscoverModels = true;
-        else
             delete def.autoDiscoverModels;
+        else
+            def.autoDiscoverModels = false;
         this.persistAgents();
         this.broadcastExposure(agentId);
     }
@@ -4183,6 +4526,79 @@ export class BridgeManager {
         this.tagHaloSetting = validateTagHalo(halo);
         this.persistAgents();
     }
+    /**
+     * Declare the deployment baseline for the two approval deadlines — the values
+     * `cordis.patch.yml` names, passed RAW (only the keys it actually contains).
+     *
+     * Kept separate from the validated tuning because "the file says 600000" and
+     * "the file says nothing, so 300000 applies" are different facts: the settings
+     * card shows the first as the reset target and the second as a built-in
+     * default. Called once by the host entry, before any bridge exists — and it
+     * also moves the baseline, so a manager built without tuning (a direct
+     * consumer, a test) still runs what the deployment asked for.
+     */
+    setConfiguredApprovalDeadlines(values) {
+        this.configuredDeadlines = { ...values };
+        if (values.nativeApprovalTimeoutMs !== undefined)
+            this.baselineDeadlines.nativeApprovalTimeoutMs = values.nativeApprovalTimeoutMs;
+        if (values.permissionFallbackTimeoutMs !== undefined)
+            this.baselineDeadlines.permissionFallbackTimeoutMs = values.permissionFallbackTimeoutMs;
+        this.applyDeadlineTuning();
+    }
+    /**
+     * The approval deadlines in force, plus the two facts that explain a value the
+     * user did not pick: the config-file baseline an override is outranking, and a
+     * `permissionTimeoutMs` that overrides BOTH windows when non-zero. Both are
+     * reported only when they are actually in play, so the card can stay silent
+     * about a plain default.
+     */
+    approvalDeadlines() {
+        const deadlines = {
+            nativeApprovalTimeoutMs: this.tuning.nativeApprovalTimeoutMs,
+            permissionFallbackTimeoutMs: this.tuning.permissionFallbackTimeoutMs,
+        };
+        if (Object.keys(this.configuredDeadlines).length > 0)
+            deadlines.configured = { ...this.configuredDeadlines };
+        if (this.tuning.permissionTimeoutMs > 0)
+            deadlines.permissionTimeoutMs = this.tuning.permissionTimeoutMs;
+        return deadlines;
+    }
+    /**
+     * Write one or both approval deadlines (omitted keys keep their value), or
+     * drop the persisted override with `reset` so the config-file baseline — or
+     * the built-in default — 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 (the one thing an
+     * `agent/save`-style restart would cost them). Only asks armed AFTER the
+     * write see the new window; an ask already holding a timer keeps the one it
+     * started with.
+     */
+    async setApprovalDeadlines(patch, reset = false) {
+        // Merged BEFORE validating, so the whole resulting override passes the same
+        // gate the config file does (an override written by an older build is
+        // re-gated here rather than trusted). `validateApprovalDeadlines` also drops
+        // unknown keys, which is what keeps a stale payload from poisoning state.
+        const merged = reset ? {} : { ...this.deadlineOverride, ...patch };
+        this.deadlineOverride = validateApprovalDeadlines(merged);
+        this.applyDeadlineTuning();
+        this.persistAgents();
+    }
+    /**
+     * Recompute the two deadlines from override → deployment baseline, and push
+     * the result to every live bridge.
+     */
+    applyDeadlineTuning() {
+        const nativeApprovalTimeoutMs = this.deadlineOverride.nativeApprovalTimeoutMs
+            ?? this.baselineDeadlines.nativeApprovalTimeoutMs;
+        const permissionFallbackTimeoutMs = this.deadlineOverride.permissionFallbackTimeoutMs
+            ?? this.baselineDeadlines.permissionFallbackTimeoutMs;
+        this.tuning.nativeApprovalTimeoutMs = nativeApprovalTimeoutMs;
+        this.tuning.permissionFallbackTimeoutMs = permissionFallbackTimeoutMs;
+        const patch = { nativeApprovalTimeoutMs, permissionFallbackTimeoutMs };
+        for (const bridge of this.bridges.values())
+            bridge.applyApprovalDeadlines(patch);
+    }
     dshSessionMap = new Map();
     /**
      * What each DSH chat session has chosen for its ACP agent — the agent itself
@@ -4237,6 +4653,13 @@ export class BridgeManager {
         const extraConfigs = {};
         for (const option of catalog.extras ?? []) {
             const value = option.currentValue;
+            if (option.kind === 'boolean') {
+                // The catalog encodes a toggle as 'true' / 'false'; the pick stores the
+                // real boolean, exactly like an explicit checkbox click.
+                if (value === 'true' || value === 'false')
+                    extraConfigs[option.configId] = value === 'true';
+                continue;
+            }
             if (value !== null && value !== undefined && value !== '')
                 extraConfigs[option.configId] = value;
         }
@@ -4290,7 +4713,11 @@ export class BridgeManager {
                 const option = options.extras?.find(entry => entry.configId === configId);
                 if (option === undefined)
                     continue;
-                if (option.choices.length > 0 && !option.choices.some(choice => choice.value === value))
+                // The fresh session's own option set is the authority for BOTH forms:
+                // a toggle must still be a toggle, a select must still offer the value.
+                if (option.kind === 'boolean'
+                    ? typeof value !== 'boolean'
+                    : typeof value !== 'string' || (option.choices.length > 0 && !option.choices.some(choice => choice.value === value)))
                     continue;
                 extraConfigs[configId] = value;
                 changed = true;