commandmate 0.44.1 → 0.44.3

package/dist/server/src/lib/realtime/terminal-broadcast.js

@@ -22,9 +22,10 @@ const current_output_builder_1 = require("../../lib/session/current-output-build
 const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
+const global_state_1 = require("../global-state");
+const terminal_session_ownership_1 = require("./terminal-session-ownership");
 const logger = (0, logger_1.createLogger)('terminal-broadcast');
-const versionCounters = globalThis.__terminalSnapshotVersions ??
-    (globalThis.__terminalSnapshotVersions = new Map());
+const versionCounters = (0, global_state_1.getOrInitGlobal)('__terminalSnapshotVersions', () => new Map());
 exports.INTERACTION_SNAPSHOT_RETRY_DELAYS_MS = [100, 250, 500, 750];
 function nextVersion(key) {
     const version = (versionCounters.get(key) ?? 0) + 1;
@@ -40,6 +41,8 @@ async function broadcastTerminalSnapshot(worktreeId, cliToolId, instanceId) {
     if (!(0, ws_server_1.hasRoomSubscribers)(worktreeId))
         return;
     try {
+        if (!(await isPushableSession(worktreeId, cliToolId, instanceId)))
+            return;
         const db = (0, db_instance_1.getDbInstance)();
         const payload = await (0, current_output_builder_1.buildCurrentOutput)(db, worktreeId, cliToolId, instanceId);
         emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId);
@@ -68,6 +71,9 @@ function snapshotFingerprint(payload) {
         // the push, the same reason `sessionStatus` and the two dismiss-panel
         // fields above are here.
         payload.promptAnswerable ?? null,
+        // Issue #3397: so "Auto-Yes sent Enter" (and its `no-effect` follow-up)
+        // reaches the push even when the frame did not change.
+        payload.autoYes?.lastEnterFallback ?? null,
         payload.isSelectionListActive ?? false,
         payload.isPagerActive ?? false,
         // Issue #2369: in the fingerprint for the same reason `sessionStatus` is —
@@ -80,7 +86,30 @@ function snapshotFingerprint(payload) {
         payload.startingSince ?? null,
     ]);
 }
+/**
+ * Whether the session under this (worktree, tool, instance)'s name may be read
+ * and pushed now (Issue #3334).
+ *
+ * `buildCurrentOutput` finds the session by name. The poller that drives this
+ * push was started by a send the route had checked, but it keeps ticking by
+ * name: if the session ends mid-poll and another CommandMate server starts one
+ * under the same name (#2865), the next tick would capture that server's pane
+ * and push it to this server's tabs. Asked before every capture, with the same
+ * check the WebSocket terminal uses; a refused session is not read and nothing
+ * is pushed — the HTTP poll (which answers 409) says what happened.
+ */
+async function isPushableSession(worktreeId, cliToolId, instanceId) {
+    const sessionName = manager_1.CLIToolManager.getInstance().getTool(cliToolId).getSessionName(worktreeId, instanceId);
+    const refusal = await (0, terminal_session_ownership_1.findTerminalSessionRefusal)(worktreeId, sessionName);
+    if (refusal === null)
+        return true;
+    logger.info('terminal-snapshot:refused', { worktreeId, cliToolId, instanceId, refusal });
+    return false;
+}
+/** `null` when the session may not be read now ({@link isPushableSession}). */
 async function captureFreshPayload(worktreeId, cliToolId, instanceId) {
+    if (!(await isPushableSession(worktreeId, cliToolId, instanceId)))
+        return null;
     const tool = manager_1.CLIToolManager.getInstance().getTool(cliToolId);
     (0, tmux_capture_cache_1.invalidateCache)(tool.getSessionName(worktreeId, instanceId));
     return (0, current_output_builder_1.buildCurrentOutput)((0, db_instance_1.getDbInstance)(), worktreeId, cliToolId, instanceId);
@@ -110,6 +139,9 @@ function emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId) {
         // `JSON.stringify` (in `broadcast`) already drops from the wire on its own.
         // Defaulting it would turn "not judged" into a judgement.
         promptAnswerable: payload.promptAnswerable,
+        // Issue #3397: straight through, like `promptAnswerable` — undefined (and so
+        // off the wire) when the payload carries no `autoYes`.
+        autoYesEnterFallback: payload.autoYes?.lastEnterFallback,
         isSelectionListActive: payload.isSelectionListActive ?? false,
         isPagerActive: payload.isPagerActive ?? false,
         isDismissablePanelActive: payload.isDismissablePanelActive ?? false,
@@ -129,11 +161,15 @@ async function broadcastTerminalSnapshotAfterInteraction(worktreeId, cliToolId,
         return;
     try {
         const initialPayload = await captureFreshPayload(worktreeId, cliToolId, instanceId);
+        if (initialPayload === null)
+            return;
         const initialFingerprint = snapshotFingerprint(initialPayload);
         emitTerminalSnapshot(worktreeId, cliToolId, initialPayload, instanceId);
         for (const delayMs of retryDelaysMs) {
             await new Promise(resolve => setTimeout(resolve, delayMs));
             const payload = await captureFreshPayload(worktreeId, cliToolId, instanceId);
+            if (payload === null)
+                return;
             if (snapshotFingerprint(payload) !== initialFingerprint) {
                 emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId);
                 return;

package/dist/server/src/lib/realtime/terminal-session-ownership.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * "May this server write to, or show, the session under this name right now?"
+ * (Issue #3334).
+ *
+ * Shared by the two realtime paths that address a session by a name they
+ * resolved earlier: the WebSocket terminal (`ws-server.ts` — every
+ * `terminal_input` / `terminal_resize` and the control-mode fallback capture)
+ * and the terminal snapshot push (`terminal-broadcast.ts`). Both outlive the
+ * moment they were set up — a socket, a poller chain — and a session that
+ * ended and was started again by another CommandMate server under the same
+ * name (#2865) would otherwise receive this server's keys, or have its screen
+ * pushed to this server's tabs. So both ask again before every write or read,
+ * the way the routes ask per request.
+ *
+ * Kept out of `ws-server.ts` so the push can import it without loading the
+ * socket server (and so the many suites that stub `@/lib/ws-server` keep
+ * stubbing only what they meant to).
+ *
+ * @module lib/realtime/terminal-session-ownership
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOREIGN_TERMINAL_SESSION_ERROR = void 0;
+exports.findTerminalSessionRefusal = findTerminalSessionRefusal;
+const db_instance_1 = require("../../lib/db/db-instance");
+const db_1 = require("../../lib/db");
+const session_ownership_1 = require("../../lib/cli-tools/session-ownership");
+/** The `terminal_error` text for a session another CommandMate server owns. */
+exports.FOREIGN_TERMINAL_SESSION_ERROR = 'Session belongs to another CommandMate server';
+/**
+ * Why the session may not be touched now, or null.
+ *
+ * The worktree row is re-read by id because a rename re-points a terminal
+ * subscription (`migrateWorktreeRooms`); a row that is gone cannot vouch for
+ * the session, which is refused for the same reason `sendUserMessage` refuses
+ * it. An absent session is not refused here — there is nothing of anyone's to
+ * show or type into, and each caller already handles a missing session.
+ */
+async function findTerminalSessionRefusal(worktreeId, sessionName) {
+    const worktree = (0, db_1.getWorktreeById)((0, db_instance_1.getDbInstance)(), worktreeId);
+    if (!worktree)
+        return 'Worktree not found';
+    const ownership = await (0, session_ownership_1.checkSessionOwnership)(sessionName, worktree.path);
+    return ownership.verdict === 'foreign' ? exports.FOREIGN_TERMINAL_SESSION_ERROR : null;
+}

package/dist/server/src/lib/relay/relay-delivery.js

@@ -58,6 +58,7 @@ const relay_readiness_1 = require("../../lib/relay/relay-readiness");
 const relay_session_ref_1 = require("../../lib/relay/relay-session-ref");
 const relay_system_line_1 = require("../../lib/relay/relay-system-line");
 const logger_1 = require("../../lib/logger");
+const global_state_1 = require("../global-state");
 const logger = (0, logger_1.createLogger)('relay-delivery');
 /**
  * How many assistant rows back the reply is looked for.
@@ -153,7 +154,7 @@ const TRANSCRIPT_READER_TOOLS = {
 const RELAY_TURN_ROW_GRACE_MS = 15_000;
 /** How often the grace above re-reads the ledger. */
 const RELAY_TURN_ROW_POLL_MS = 1_000;
-const inFlight = (globalThis.__relayDeliveryInFlight ??= new Set());
+const inFlight = (0, global_state_1.getOrInitGlobal)('__relayDeliveryInFlight', () => new Set());
 /** Forget every in-flight delivery. Test seam. */
 function resetRelayDeliveryState() {
     inFlight.clear();
@@ -222,6 +223,8 @@ function findWorkerReply(db, worker, since) {
 /** The options of B's open dialog, in the shape the notice lists them. */
 function promptOptionsOf(message) {
     const data = message.promptData;
+    // #3184: type narrowing only — the stored row's screen `options` are listed;
+    // a stored degraded record never carries a decision id, so it has none.
     if (!(0, models_1.isAnswerablePromptData)(data))
         return [];
     if (data.type === 'yes_no') {
@@ -383,6 +386,7 @@ function notifyRelayPromptWaiting(worker) {
             return;
         const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
         const options = promptOptionsOf(prompt);
+        // #3184: type narrowing only, to read `question` off the closed union.
         const question = (0, models_1.isAnswerablePromptData)(prompt.promptData)
             ? prompt.promptData.question
             : (prompt.promptData?.question ?? prompt.content);
@@ -467,7 +471,7 @@ async function deliverOne(db, relayId, kind, body) {
     if (!relay)
         return 'skipped';
     const requester = (0, relay_session_ref_1.resolveRelaySession)(db, relay.from);
-    const hold = await (0, relay_readiness_1.findRelayHoldReason)(requester.worktreeId, requester.cliToolId, requester.instanceId);
+    const hold = await (0, relay_readiness_1.findRelayHoldReason)(requester.worktreeId, requester.cliToolId, requester.instanceId, db);
     if (hold) {
         logger.debug('relay-delivery-held', { relayId, kind, reason: hold });
         return 'held';

package/dist/server/src/lib/relay/relay-readiness.js

@@ -13,12 +13,25 @@
  *    is running. The relay waits for `ready` instead — the ledger is durable, so
  *    waiting costs nothing but time.
  *
+ *    Since Issue #3337 "mid-turn" is also the hooks' answer when they speak for
+ *    a codex pane (`lib/session/hook-turn-hold`, the rule `capture --json`
+ *    reads): the frame alone read a live codex turn as `ready`.
+ *
  * The prompt-dialog question is deliberately NOT asked here: `sendUserMessage`
  * already refuses a send that would land in an open dialog (#1708/#1737), and
  * duplicating that judgement would give the relay path its own second opinion
  * about a state the send path is the authority on. A refusal there is a retry
  * here.
  *
+ * **Is it this server's session?** (Issue #3334) Asked first — before the
+ * pane is read, and before `isRunning()`, which reads the pane (claude) or
+ * resumes an event stream (opencode-v2) on its own.
+ * `sendUserMessage` refuses a session another CommandMate server created under
+ * the same name (#2865), but this check came first and read that pane to judge
+ * it — the same order `sendUserMessage` itself was fixed out of. Such a session
+ * holds the delivery (`foreign_session`): the ledger keeps the payload, and it
+ * goes out if this server's own session comes back before the deadline.
+ *
  * Fail-open on an unreadable pane, for the same reason `prompt-waiting-guard`
  * fails open: the cost of a wrong "ready" is a message the send path refuses
  * and the pump retries, while the cost of a wrong "not ready" is a relay that
@@ -29,22 +42,46 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findRelayHoldReason = findRelayHoldReason;
 const manager_1 = require("../../lib/cli-tools/manager");
+const session_name_1 = require("../../lib/cli-tools/session-name");
+const worktree_session_ownership_1 = require("../../lib/cli-tools/worktree-session-ownership");
 const cli_session_1 = require("../../lib/session/cli-session");
 const status_detector_1 = require("../../lib/detection/status-detector");
+const hook_turn_hold_1 = require("../../lib/session/hook-turn-hold");
 const status_capture_config_1 = require("../../config/status-capture-config");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('relay-readiness');
 /**
  * Whether a relay may be delivered into this session now.
  *
+ * @param db - The handle the worktree row is read from (Issue #3334); defaults
+ *   to the server's
  * @returns `null` when the session can take the message, else why it cannot
  */
-async function findRelayHoldReason(worktreeId, cliToolId, instanceId) {
+async function findRelayHoldReason(worktreeId, cliToolId, instanceId, db) {
     try {
+        // Issue #3334: the session name `sendUserMessage` will address, checked
+        // the way it checks it — before anything touches the session. That
+        // includes `isRunning()`: it is not a bare existence test for every tool.
+        // claude's reads the pane to judge its health, and opencode-v2's starts
+        // re-subscribing to the event stream of whatever server sits in the
+        // session's directory.
+        const sessionName = (0, session_name_1.resolveSessionName)(cliToolId, worktreeId, instanceId);
+        const ownership = await (0, worktree_session_ownership_1.checkWorktreeSessionOwnership)(worktreeId, sessionName, db);
+        if (ownership === null || ownership.verdict === 'foreign')
+            return 'foreign_session';
+        if (ownership.verdict === 'absent')
+            return 'session_stopped';
         const cliTool = manager_1.CLIToolManager.getInstance().getTool(cliToolId);
         if (!(await cliTool.isRunning(worktreeId, instanceId)))
             return 'session_stopped';
         const output = await (0, cli_session_1.captureSessionOutput)(worktreeId, cliToolId, status_capture_config_1.STATUS_CAPTURE_LINES, instanceId);
+        // Issue #3337: for a tool whose hook turns the screen may not end (codex),
+        // an open hook turn holds the pane at `running` whatever the frame reads —
+        // the rule `capture --json` publishes, read from the one place it is
+        // written. A frame of a live codex turn read `ready`, and a reply typed into
+        // it interrupted the turn.
+        if ((0, hook_turn_hold_1.hookTurnHoldsPane)(worktreeId, cliToolId, instanceId, output))
+            return 'generating';
         const status = (0, status_detector_1.detectSessionStatus)(output, cliToolId);
         // Only `running` holds. `waiting` is a dialog, which is the send path's
         // judgement to make (and its refusal is a retry); `idle` and `ready` both

package/dist/server/src/lib/relay/relay-triggers.js

@@ -75,6 +75,8 @@ exports.areRelayTriggersActive = areRelayTriggersActive;
 const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
 const relay_policy_1 = require("../../lib/relay/relay-policy");
 const logger_1 = require("../../lib/logger");
+const prompt_waiting_composition_1 = require("../../lib/session/prompt-waiting-composition");
+const registry_1 = require("../../lib/hooks/sources/registry");
 const logger = (0, logger_1.createLogger)('relay-triggers');
 /**
  * Tell the relays that this instance finished a turn.
@@ -151,6 +153,13 @@ function startRelayTriggers() {
         // another session as a question it might report to a human.
         if (!transition.waiting || transition.kind !== 'prompt')
             return;
+        // Issue #3184 (design §6-2): a wait answered over the agent's API is
+        // published as `prompt` for the dots and the push body, but the relay is
+        // not raised for it — its notice lists the stored row's screen options,
+        // and such a wait has none to list. Relaying it is a separate Issue.
+        if ((0, prompt_waiting_composition_1.isApiAnswerableWaitNow)(transition.worktreeId, transition.cliToolId, transition.instanceId, (0, registry_1.getAgentEventSource)(transition.cliToolId).capabilities.eventIdentity)) {
+            return;
+        }
         onRelayPromptWaiting(transition.worktreeId, transition.cliToolId, transition.instanceId);
     });
     const timer = setInterval(() => void runRelayMaintenance(), relay_policy_1.RELAY_PUMP_INTERVAL_MS);

package/dist/server/src/lib/resource-cleanup.js

@@ -22,6 +22,7 @@ exports.stopResourceCleanup = stopResourceCleanup;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const auto_yes_manager_1 = require("./polling/auto-yes-manager");
+const auto_yes_lifecycle_1 = require("./auto-yes-lifecycle");
 const path_validator_1 = require("./security/path-validator");
 const schedule_manager_1 = require("./schedule-manager");
 const timer_manager_1 = require("./timer-manager");
@@ -174,18 +175,19 @@ function cleanupOrphanedMapEntries() {
         // If DB query returned nothing, skip cleanup to avoid false positives
         return result;
     }
-    // Cleanup autoYesStates (Issue #525: composite keys)
+    // Cleanup autoYesStates (Issue #525: composite keys). Issue #3184: through the
+    // `orphan-swept` row of the Auto-Yes lifecycle table.
     const autoYesStateKeys = (0, auto_yes_manager_1.getAutoYesStateCompositeKeys)();
     for (const compositeKey of autoYesStateKeys) {
         const worktreeId = (0, auto_yes_manager_1.extractWorktreeId)(compositeKey);
         // [SEC4-MF-001] Validate extracted worktreeId
         if (!(0, path_validator_1.isValidWorktreeId)(worktreeId)) {
-            (0, auto_yes_manager_1.deleteAutoYesState)(compositeKey);
+            (0, auto_yes_lifecycle_1.applyAutoYesStateRule)('orphan-swept', { scope: 'key', compositeKey });
             result.deletedAutoYesStateIds.push(compositeKey);
             continue;
         }
         if (!validWorktreeIds.has(worktreeId)) {
-            (0, auto_yes_manager_1.deleteAutoYesState)(compositeKey);
+            (0, auto_yes_lifecycle_1.applyAutoYesStateRule)('orphan-swept', { scope: 'key', compositeKey });
             result.deletedAutoYesStateIds.push(compositeKey);
         }
     }
@@ -194,7 +196,7 @@ function cleanupOrphanedMapEntries() {
     for (const compositeKey of autoYesPollerKeys) {
         const worktreeId = (0, auto_yes_manager_1.extractWorktreeId)(compositeKey);
         if (!(0, path_validator_1.isValidWorktreeId)(worktreeId) || !validWorktreeIds.has(worktreeId)) {
-            (0, auto_yes_manager_1.stopAutoYesPolling)(compositeKey);
+            (0, auto_yes_lifecycle_1.stopAutoYesPollersFor)('orphan-swept', { scope: 'key', compositeKey });
             result.deletedAutoYesPollerIds.push(compositeKey);
         }
     }

package/dist/server/src/lib/response-cleaner.js

@@ -15,6 +15,7 @@ exports.cleanScrollbackResponse = cleanScrollbackResponse;
 exports.truncateMessage = truncateMessage;
 const cli_patterns_1 = require("./detection/cli-patterns");
 const tui_accumulator_1 = require("./tui-accumulator");
+const startup_screen_1 = require("./polling/startup-screen");
 const copilot_constants_1 = require("../config/copilot-constants");
 /**
  * Clean up Claude response by removing shell setup commands, environment exports, ANSI codes, and banner
@@ -473,11 +474,33 @@ function findScrollbackChromeStart(lines, cliToolId) {
  * classify rows by their SGR attributes, and stripping first would destroy the
  * evidence they read.
  *
+ * ## The startup screen (Issue #3293)
+ *
+ * Neither step removes a banner. codex's and vibe-local's startup screens are
+ * mostly rows no pattern names — the version, the cwd, a tagline, a logo — so
+ * the first flush of a session, whose cursor is 0, saved the screen as a reply.
+ * What says "this is not a reply" is the pane, not the rows: no message has
+ * been echoed on it yet ({@link isStartupScreenWithoutUserEcho}, the same
+ * reading the poller makes). So the flush hands the pane over with the rows.
+ *
+ * It is a separate argument because `response` cannot answer for it. The rows
+ * past the cursor ordinarily hold a reply and no echo — the echo of the turn
+ * they belong to sits above the cursor — so asking the question of `response`
+ * would empty real replies. A caller that has only a slice omits `paneLines`
+ * and gets the two steps above and nothing else.
+ *
  * @param response - Raw capture, ANSI intact
  * @param cliToolId - The tool the capture came from
+ * @param paneLines - The whole capture `response` was sliced from, ANSI intact.
+ *   Omitted when the caller does not hold it, or when the capture came back
+ *   clipped by its window (#1670 — the echo may have scrolled out of it)
  * @returns Cleaned response, or an empty string when the capture was all chrome
+ *   or the pane has not had a turn yet
  */
-function cleanScrollbackResponse(response, cliToolId) {
+function cleanScrollbackResponse(response, cliToolId, paneLines) {
+    if (paneLines && (0, startup_screen_1.isStartupScreenWithoutUserEcho)(cliToolId, paneLines)) {
+        return '';
+    }
     const allLines = response.split('\n');
     const chromeStart = findScrollbackChromeStart(allLines, cliToolId);
     const bodyLines = chromeStart >= 0 ? allLines.slice(0, chromeStart) : allLines;

package/dist/server/src/lib/response-extractor.js

@@ -222,6 +222,22 @@ function resolveExtractionStartIndex(lastCapturedLine, totalLines, bufferReset,
         return foundUserPrompt >= 0 ? foundUserPrompt + 1 : 0;
     }
     // Branch 2b: Codex uses lastCapturedLine directly (Codex-specific TUI behavior)
+    //
+    // Issue #3335: on codex 0.160.0 this is NOT a read cursor, and it is left
+    // that way on purpose. 0.160.0 draws in the alternate screen — the capture is
+    // the 1000-row pane, the composer pinned to row 996, the transcript growing
+    // from the top — so after the startup screen the cursor is the composer row
+    // (996, the poller) or the row count (999/1000, the pre-send flush and the
+    // advance after a transcript turn), and every reply is drawn above it.
+    // Extraction from it is empty, and the reply reaches History from codex's own
+    // transcript, read on the Stop hook (`hooks/stop-history-capture.ts` →
+    // `hooks/sources/codex/history.ts`), not from the pane. The cost is stated:
+    // a 0.160.0 session whose codex hooks are not installed or not trusted gets
+    // no reply row from the pane either. What the screen read must not do is
+    // save a wrong row from the parked cursor: the poller stops at the composer
+    // (`collectCompletedResponse`), a re-read from the top (cursor >= totalLines,
+    // branch 1 above) is dropped by `lineCount <= lastCapturedLine`, and the flush
+    // reads nothing at or below the composer (`isCodexCursorAtOrBelowComposer`).
     if (cliToolId === 'codex') {
         return Math.max(0, lastCapturedLine);
     }

package/dist/server/src/lib/schedule-manager.js

@@ -33,6 +33,7 @@ const claude_executor_1 = require("./session/claude-executor");
 const cron_parser_1 = require("./cron-parser");
 const job_executor_1 = require("./job-executor");
 const logger_1 = require("../lib/logger");
+const global_state_1 = require("./global-state");
 const logger = (0, logger_1.createLogger)('schedule-manager');
 // Re-export for backward compatibility (public API preservation)
 var cron_parser_2 = require("./cron-parser");
@@ -202,16 +203,13 @@ function replaceCronExpression(state, entry) {
  * Get or initialize the global manager state.
  */
 function getManagerState() {
-    if (!globalThis.__scheduleManagerStates) {
-        globalThis.__scheduleManagerStates = {
-            timerId: null,
-            schedules: new Map(),
-            initialized: false,
-            isSyncing: false,
-            cmateFileCache: new Map(),
-        };
-    }
-    return globalThis.__scheduleManagerStates;
+    return (0, global_state_1.getOrInitGlobal)('__scheduleManagerStates', () => ({
+        timerId: null,
+        schedules: new Map(),
+        initialized: false,
+        isSyncing: false,
+        cmateFileCache: new Map(),
+    }));
 }
 // =============================================================================
 // Lazy DB Accessor

package/dist/server/src/lib/session/agent-event-ask-user-question.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * The `AskUserQuestion` call an agent instance has in flight (Issue #1726).
+ *
+ * Split out of `agent-event-state` (Issue #3375), which re-exports the public
+ * names and applies the transition from `recordAgentEvent`.
+ *
+ * @module lib/session/agent-event-ask-user-question
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askUserQuestion = void 0;
+exports.applyAskUserQuestionTransition = applyAskUserQuestionTransition;
+exports.recordAskUserQuestion = recordAskUserQuestion;
+exports.getAskUserQuestion = getAskUserQuestion;
+exports.clearAskUserQuestion = clearAskUserQuestion;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+// Issue #2100: the shared list of tool names that mean "a human is being asked
+// to CHOOSE". Pure — its own only import is `permission-request-payload`, which
+// this module already reached for `ASK_USER_QUESTION_TOOL` — and importing it
+// here rather than repeating `'question'` is what keeps the release rule below
+// and `pendingDecisionKind`'s reader from drifting apart.
+const pending_decision_kind_1 = require("../../lib/hooks/pending-decision-kind");
+const agent_event_turn_1 = require("../../lib/session/agent-event-turn");
+const agent_event_structured_state_1 = require("../../lib/session/agent-event-structured-state");
+const global_state_1 = require("../global-state");
+/** compositeKey -> the `AskUserQuestion` call currently in flight (#1726). */
+exports.askUserQuestion = (0, global_state_1.getOrInitGlobal)('__agentEventAskUserQuestion', () => new Map());
+/**
+ * When the in-flight question is released (Issue #1726).
+ *
+ * | event                             | effect on the question |
+ * |-----------------------------------|------------------------|
+ * | `pre_tool_use(AskUserQuestion)`   | unchanged (this IS it) |
+ * | `pre_tool_use(any other tool)`    | release                |
+ * | `post_tool_use`                   | release                |
+ * | `notification(permission_prompt)` | **unchanged**          |
+ * | `notification(idle_prompt)`       | release                |
+ * | `notification(other)`             | unchanged              |
+ * | `stop`                            | release                |
+ * | `user_prompt_submit`              | release                |
+ * | `session_start` / `session_end`   | release                |
+ *
+ * `PostToolUse` is the precise release — "this tool call is over" — and `Stop`
+ * is the backstop for a delivery that never arrives. Issue #1726's text proposed
+ * `PostToolUse` and the #1721 spike recorded it as never observed, so this Issue
+ * measured it directly on a live v2.1.223 session (2026-08-06):
+ *
+ * ```
+ * 15:36:04.112  PreToolUse   AskUserQuestion
+ * 15:36:28.643  PostToolUse  AskUserQuestion   <- the human answered
+ * 15:36:29.992  Stop
+ * ```
+ *
+ * It fires, 1.3 s ahead of `Stop` here — and much further ahead whenever the
+ * agent keeps working after the answer, which is the case that matters: `Stop`
+ * alone would leave a finished question in place for the whole rest of the turn.
+ *
+ * A `PostToolUse` for any other tool releases as well: the agent could not have
+ * finished another tool call while this question was still on screen.
+ *
+ * **`Notification(permission_prompt)` keeping the question is a live
+ * measurement, not a guess.** The #1721 report says the picker emits no events
+ * while it is displayed (§5.6), and a first cut of this module read that as "any
+ * event means the picker is gone". Driving a real v2.1.223 session through the
+ * server on 2026-08-06 disproved it:
+ *
+ * ```
+ * 15:29:18.099  PreToolUse(AskUserQuestion)
+ * 15:29:18.109  PermissionRequest(AskUserQuestion) -> no decision
+ * 15:29:24.128  Notification(permission_prompt)      <- picker still on screen
+ * ```
+ *
+ * The notification lands ~6 s after the dialog is drawn (§5.5's timing exactly),
+ * which is *inside* the window §5.6 was counting rather than outside it. Under
+ * the first rule it deleted the question six seconds after it arrived, and the
+ * options went back to being the screen's — which is the whole feature, silently
+ * off, on every real session.
+ *
+ * `idle_prompt` still releases: the agent reporting it is sitting at the
+ * composer is the agent saying no picker is in front of it. An unrecognised
+ * notification type changes nothing, because nothing is known about it.
+ */
+function applyAskUserQuestionTransition(key, record) {
+    switch (record.event) {
+        case 'pre_tool_use':
+            // A `PreToolUse` for anything else means the agent has moved on to another
+            // tool, so whatever question was in flight has been answered. Only
+            // reachable when the operator's own settings.json registers a wider
+            // matcher than the injected `AskUserQuestion` one — the two files are
+            // concatenated, not substituted (#1722).
+            //
+            // Issue #2100: the exemption is the whole QUESTION vocabulary, not
+            // Claude's one spelling. opencode names its question tool `question`, and
+            // it publishes a tool part for the same call: measured on 1.18.23 in an
+            // isolated HOME, `question.asked` and
+            // `message.part.updated(tool=question, status=running)` arrive **in the
+            // same millisecond**, in that order (§27.3). Under the old test the
+            // second frame read as "the agent moved on to another tool" and deleted
+            // the episode 1 ms after the ingest recorded it, which is why
+            // `pendingDecisions[].questionOptions` and `promptData.askUserQuestion`
+            // were null for every opencode question. Claude is unaffected —
+            // `AskUserQuestion` is the first member of the same list — and the cost
+            // is that a hook tool literally named `question` no longer releases the
+            // episode, which is the same name `pendingDecisionKind` already reads as
+            // "this record is a question" for every tool.
+            if (!pending_decision_kind_1.QUESTION_DECISION_TOOL_NAMES.includes(record.detail ?? '')) {
+                exports.askUserQuestion.delete(key);
+            }
+            return;
+        case 'notification':
+            if (record.detail === 'idle_prompt')
+                exports.askUserQuestion.delete(key);
+            return;
+        case 'post_tool_use':
+        case 'stop':
+        case 'user_prompt_submit':
+        case 'session_start':
+        case 'session_end':
+            exports.askUserQuestion.delete(key);
+            return;
+        default:
+            // exhaustive check: a new AgentEventType must decide its transition here
+            record.event;
+            return;
+    }
+}
+/**
+ * Record the `AskUserQuestion` invocation reported for one instance.
+ *
+ * Idempotent by construction: the same call is reported twice on every session
+ * — once by `PreToolUse` and once by the `PermissionRequest` that
+ * `AskUserQuestion` also raises with a byte-identical `tool_input` — and the
+ * second delivery simply overwrites the first with the same content.
+ *
+ * @param at - Epoch ms; defaults to now
+ */
+function recordAskUserQuestion(worktreeId, cliToolId, instanceId, spec, at = Date.now()) {
+    exports.askUserQuestion.set((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId), { at, spec });
+}
+/**
+ * The `AskUserQuestion` call in flight for this instance, or null.
+ *
+ * Bounded exactly like {@link getStructuredSessionState}: a record from a
+ * previous generation belongs to a Claude process that no longer exists, and one
+ * older than {@link STRUCTURED_STATE_MAX_AGE_MS} has outlived the screen it
+ * describes. There is no provisional bound — unlike a `PermissionRequest`, a
+ * `PreToolUse(AskUserQuestion)` is not a prediction that a dialog *might*
+ * appear: allowing the permission request does not dismiss the picker (§5.6), so
+ * the picker is drawn unconditionally.
+ *
+ * @param now - Epoch ms; defaults to now
+ */
+function getAskUserQuestion(worktreeId, cliToolId, instanceId, now = Date.now()) {
+    const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
+    const episode = exports.askUserQuestion.get(key);
+    if (!episode)
+        return null;
+    const generation = agent_event_turn_1.generationStartedAt.get(key);
+    if (generation !== undefined && episode.at < generation)
+        return null;
+    if (now - episode.at >= agent_event_structured_state_1.STRUCTURED_STATE_MAX_AGE_MS)
+        return null;
+    return episode;
+}
+/** Drop the in-flight question for one instance. */
+function clearAskUserQuestion(worktreeId, cliToolId, instanceId) {
+    exports.askUserQuestion.delete((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId));
+}