commandmate 0.44.0 → 0.44.2

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/session/agent-session-lifecycle.js

@@ -43,6 +43,7 @@ exports.buildAgentLaunchCommandLine = buildAgentLaunchCommandLine;
 const sources_1 = require("../../lib/hooks/sources");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
 const session_generation_archive_1 = require("../../lib/session/session-generation-archive");
+const session_starting_state_1 = require("../../lib/session/session-starting-state");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/session/agent-session-lifecycle');
 /**
@@ -66,6 +67,16 @@ const logger = (0, logger_1.createLogger)('lib/session/agent-session-lifecycle')
  * @param at - Epoch ms; defaults to now
  */
 function beginAgentSession(target, at = Date.now()) {
+    // Issue #3179: the launch is in progress from here until
+    // `BaseCLITool.startSession` returns or throws (it clears the record in a
+    // `finally`). First, so the screen stops reading the about-to-be-created pane
+    // as a running agent before anything else here can fail.
+    // Issue #3195: the record is written under the token `startSession` is
+    // running the launch with (an `AsyncLocalStorage`, read inside
+    // `markSessionStarting`), which is how that `finally` knows the record is
+    // its own. A second call from the same launch (codex's
+    // `relaunchIntoSamePane`) rewrites the same launch's record.
+    (0, session_starting_state_1.markSessionStarting)(target.worktreeId, target.cliToolId, target.instanceId, at);
     const before = (0, agent_event_state_1.getAgentEventDropCounts)(target.worktreeId, target.cliToolId, target.instanceId).decisionEvicted;
     (0, agent_event_state_1.beginAgentEventGeneration)(target.worktreeId, target.cliToolId, target.instanceId, at);
     const after = (0, agent_event_state_1.getAgentEventDropCounts)(target.worktreeId, target.cliToolId, target.instanceId).decisionEvicted;

package/dist/server/src/lib/session/claude-session.js

@@ -36,6 +36,7 @@ const cmate_cli_tool_parser_1 = require("../../lib/cmate-cli-tool-parser");
 const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
 const session_start_error_1 = require("../../lib/session/session-start-error");
+const launch_screen_1 = require("../../lib/session/launch-screen");
 const logger = (0, logger_1.createLogger)('claude-session');
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 // ----- Helper Functions -----
@@ -429,6 +430,11 @@ function findSessionErrorPattern(cleanOutput) {
  * reading as a zsh prompt. What changed is that six other tools can now be
  * asked the same question; see `lib/cli-tools/liveness-spec`.
  *
+ * Issue #3191: a `user@host …` prompt of 40 characters or more is now read as
+ * the shell too (claude's spec takes `SHELL_PROMPT_LINE_PATTERNS`), so a claude
+ * that was `/exit`ed into a long zsh / bash prompt is reported unhealthy and
+ * relaunched instead of timing out the next send.
+ *
  * @param sessionName - tmux session name
  * @returns HealthCheckResult with healthy status and optional reason
  */
@@ -674,7 +680,7 @@ async function startClaudeSession(options) {
         // and the operator's `~/.claude/settings.json` (measured on 2.1.278).
         const launchCommand = model === undefined ? baseLaunchCommand : `${baseLaunchCommand} --model ${(0, hook_settings_generator_1.shellQuote)(model)}`;
         // Start Claude CLI in interactive mode using dynamically resolved path
-        await (0, tmux_1.sendKeys)(sessionName, launchCommand, true);
+        await (0, tmux_1.sendKeys)(sessionName, (0, launch_screen_1.withLaunchScreenCleared)(launchCommand), true);
         // Wait for Claude to initialize with dynamic detection (OCP-001)
         // Use constants instead of hardcoded values
         const maxWaitTime = exports.CLAUDE_INIT_TIMEOUT;

package/dist/server/src/lib/session/current-output-builder.js

@@ -55,6 +55,7 @@ const db_1 = require("../../lib/db");
 // when this instance was last handed a prompt.
 const chat_db_1 = require("../../lib/db/chat-db");
 const unclassified_frame_tracker_1 = require("../../lib/detection/unclassified-frame-tracker");
+const session_starting_state_1 = require("../../lib/session/session-starting-state");
 const composer_text_1 = require("../../lib/detection/composer-text");
 const upstream_faults_1 = require("../../lib/detection/upstream-faults");
 const opencode_pane_obstruction_1 = require("../../lib/detection/opencode-pane-obstruction");
@@ -85,6 +86,7 @@ const prompt_waiting_composition_1 = require("../../lib/session/prompt-waiting-c
 const provisional_turn_1 = require("../../lib/session/provisional-turn");
 const status_evidence_1 = require("../../lib/session/status-evidence");
 const ask_user_question_prompt_1 = require("../../lib/session/ask-user-question-prompt");
+const prompt_view_1 = require("../../lib/session/prompt-view");
 const auto_yes_dialog_gate_1 = require("../../lib/polling/auto-yes-dialog-gate");
 const layer_disagreement_1 = require("../../lib/session/layer-disagreement");
 const structured_prompt_1 = require("../../lib/session/structured-prompt");
@@ -608,7 +610,8 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId, resolut
     // surface is actually being watched at, which is exactly the property the
     // terminal snapshot already has. Gated on the merged verdict (`'running'`, not
     // the tmux-session-exists `isRunning`) so an idle pane reads no transcript.
-    if (payload.isRunning && payload.sessionStatus === 'running') {
+    // Issue #3179: not during a launch — there is no turn to publish yet.
+    if (payload.isRunning && payload.sessionStatus === 'running' && payload.startingSince == null) {
         // Issue #2248 made this an `await`, and it buys less than it looks like: the
         // expensive half — the transcript read and the broadcast — is detached
         // inside, so what is waited for is a worktree row and a Map lookup. What it
@@ -750,6 +753,10 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
         (0, status_evidence_1.forgetLastKnownStatus)((0, auto_yes_manager_1.buildCompositeKey)(worktreeId, cliToolId, instanceId));
         return {
             isRunning: false,
+            // Issue #3179: `beginAgentSession` runs before the pane is created, so a
+            // launch can be in progress with no tmux session yet. Read-only here —
+            // there is no frame to judge a dialog on.
+            startingSince: (0, session_starting_state_1.getSessionStartingSince)(worktreeId, cliToolId, instanceId),
             sessionName,
             content: '',
             lineCount: 0,
@@ -828,7 +835,17 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     const compositeKey = (0, auto_yes_manager_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
     const lastServerResponseTimestamp = (0, auto_yes_manager_1.getLastServerResponseTimestamp)(compositeKey);
     const lastOutputTimestamp = lastServerResponseTimestamp ? new Date(lastServerResponseTimestamp) : undefined;
-    const statusResult = (0, status_detector_1.detectSessionStatus)(output, cliToolId, lastOutputTimestamp);
+    const rawStatusResult = (0, status_detector_1.detectSessionStatus)(output, cliToolId, lastOutputTimestamp);
+    // Issue #3179: a launch in progress. The frame is a shell prompt and the
+    // launch line, or a dialog the launch is about to answer, and none of the
+    // flags below may be read off it: the floor verdict raised the Navigate pad,
+    // the trust dialog raised the selection list / prompt sheet. A dialog that
+    // outstays the launch's own answer releases the record (a login, an unknown
+    // dialog), and from then on this is the ordinary verdict again.
+    const startingSince = (0, session_starting_state_1.observeSessionStartingFrame)(worktreeId, cliToolId, instanceId, rawStatusResult.status === 'waiting' || rawStatusResult.hasActivePrompt);
+    const statusResult = startingSince === null
+        ? rawStatusResult
+        : (0, session_starting_state_1.startingStatusResult)(rawStatusResult);
     // Issue #1912: every `running` reason that means "the agent is producing
     // output", not just `thinking_indicator`. opencode answers
     // `opencode_processing_indicator` for its `esc interrupt` footer, which is
@@ -946,7 +963,9 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // the guard cannot disagree about whether a prompt is open. What they are
     // still allowed to differ on is what to DO about it — see `blocksSend`, which
     // bounds the structured layer's veto over sends and leaves this flag alone.
-    const isPromptWaiting = promptResolution.waiting;
+    // Issue #3179: not while a launch is in progress. The scraper half is already
+    // neutralised above; this also drops a structured wait the launch inherited.
+    const isPromptWaiting = startingSince === null && promptResolution.waiting;
     // Issue #1726: the agent's own account of what it asked. It contributes only
     // where some other layer has already established that a dialog is on screen —
     // this record decides no status of its own, because Claude emits nothing at
@@ -1033,13 +1052,15 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
             // instead of by coincidence.)
             patterns: decisionOptions !== null ? promptWaiting.patterns : null,
         };
-    const promptData = scraperPromptWaiting
-        ? correctedPromptData ??
-            scraperPromptData ??
-            (structuredFacts ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts) : null)
-        : structuredFacts
-            ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts)
-            : null;
+    const promptData = startingSince !== null
+        ? null
+        : scraperPromptWaiting
+            ? correctedPromptData ??
+                scraperPromptData ??
+                (structuredFacts ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts) : null)
+            : structuredFacts
+                ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts)
+                : null;
     // Issue #2870: whether `/prompt-response` would answer the prompt published
     // above, read by the SAME function it re-verifies with. In #2868 `promptData`
     // came off the generic parser alone, the route refused it, and the UI's Send
@@ -1111,7 +1132,9 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // and the 60 seconds — start afresh if the frame is still unreadable once the
     // decision is gone (answered, expired, or the source dropped).
     const answerableOverAgentApi = (0, structured_prompt_1.hasApiAnswerableDecision)(eventSource.capabilities.eventIdentity, structuredEvents.pendingDecisions ?? []);
-    const unclassifiedVerdict = (0, unclassified_frame_tracker_1.observeUnclassifiedFrame)(compositeKey, merged.isUnclassifiedActive && !answerableOverAgentApi);
+    // Issue #3179: a launch in progress is not a detection failure — its frame is
+    // the shell and the launch line — so no row, and the run starts afresh after.
+    const unclassifiedVerdict = (0, unclassified_frame_tracker_1.observeUnclassifiedFrame)(compositeKey, merged.isUnclassifiedActive && !answerableOverAgentApi && startingSince === null);
     if (unclassifiedVerdict.shouldRecord) {
         recordUnclassifiedFrame(db, {
             worktreeId,
@@ -1197,32 +1220,40 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
     // `sessionStatus` it sat next to one poll earlier. Observed before it is read
     // so a positive poll reports itself, which is what keeps the field from
     // looking stale on a healthy session.
+    // Issue #3179: the structured layer cannot override a launch in progress
+    // either — a `waiting` it inherited would put the answer sheet back.
+    const published = startingSince === null
+        ? merged
+        : { ...merged, status: 'running', reason: status_detector_1.STATUS_REASON.STARTING, thinking: false };
     (0, status_evidence_1.observeStatusEvidence)(compositeKey, {
-        status: merged.status,
-        reason: merged.reason,
-        evidence: merged.evidence,
+        status: published.status,
+        reason: published.reason,
+        evidence: published.evidence,
     });
     const lastKnown = (0, status_evidence_1.getLastKnownStatus)(compositeKey);
     return {
         isRunning: true,
         sessionName,
         cliToolId,
-        sessionStatus: merged.status,
-        sessionStatusReason: merged.reason,
+        sessionStatus: published.status,
+        sessionStatusReason: published.reason,
         content: newContent,
         fullOutput: output,
         realtimeSnippet,
         lineCount: totalLines,
         lastCapturedLine,
         isComplete: isPromptWaiting,
-        isGenerating: merged.thinking,
-        thinking: merged.thinking,
+        isGenerating: published.thinking,
+        thinking: published.thinking,
         // Issue #2607: named after the tool actually running. A fixed "Claude" was
         // published for every agent, and `capture --json` readers took it at its word.
-        thinkingMessage: merged.thinking ? `${(0, types_2.getCliToolDisplayName)(cliToolId)} is thinking...` : null,
+        thinkingMessage: published.thinking ? `${(0, types_2.getCliToolDisplayName)(cliToolId)} is thinking...` : null,
         isPromptWaiting,
         promptData,
         ...(promptAnswerable !== undefined ? { promptAnswerable } : {}),
+        // Issue #3184: appended next to the value it is derived from, not at the end
+        // — it is a reading of `promptData`, and only of it.
+        promptView: (0, prompt_view_1.derivePromptView)(promptData),
         autoYes: {
             enabled: autoYesState?.enabled ?? false,
             expiresAt: autoYesState?.enabled ? autoYesState.expiresAt : null,
@@ -1235,11 +1266,12 @@ async function buildPayload(db, worktreeId, cliToolId, instanceId) {
         isSelectionListActive,
         isPagerActive,
         isDismissablePanelActive,
-        isUnclassifiedActive: merged.isUnclassifiedActive,
+        isUnclassifiedActive: startingSince === null && merged.isUnclassifiedActive,
+        startingSince,
         // Issue #1926: the same fact `isUnclassifiedActive` carries, named the way
         // §4 D1 names it. Published from the merged verdict so the two cannot
         // disagree on the wire.
-        statusEvidence: merged.evidence,
+        statusEvidence: published.evidence,
         lastKnownStatus: lastKnown?.status ?? null,
         lastKnownStatusAt: lastKnown?.at ?? null,
         lastServerResponseTimestamp,

package/dist/server/src/lib/session/launch-screen.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Keep the launch line off the pane (Issue #3180).
+ *
+ * Every `startSession` types its launch line into the pane's login shell —
+ * `CM_HOOK_URL='…' CM_PERMISSION_HOOK_URL='…' CM_PORT='3000' 'agy'` — and the
+ * shell echoes it. A tool that repaints the whole screen hides the echo once it
+ * draws; agy and codex draw inline, so the line, with its internal URL, port
+ * and worktree ID, stayed in the scrollback for the life of the session.
+ *
+ * `clear` runs in the same shell, before the agent, so the echo is wiped before
+ * the agent paints. The shell stays the agent's parent exactly as before, which
+ * is what keeps exit detection (`judgeToolLiveness`, `relaunchIfToolExited`)
+ * unchanged: when the agent quits, the pane falls back to the same shell prompt.
+ *
+ * `clear` alone only empties the visible screen. tmux 3.4+ defaults to
+ * `scroll-on-clear on`, which moves what `clear` wiped INTO the scrollback, and
+ * CommandMate's capture reads the scrollback: in the 2026-10-04 UAT (tmux 3.5a)
+ * codex, antigravity, Command Code and gemini still had the launch line twice in
+ * `tmux capture-pane -p -J -S -` (two `CM_HOOK_URL` hits), and it surfaced in the
+ * UI terminal and in codex's trust-dialog sheet. So `printf '\033[3J'` follows
+ * `clear`: ESC [3J (Erase Saved Lines) drops the scrollback, the echo included.
+ * `tmux clear-history` would also work but depends on the pane having a tmux
+ * binary and `TMUX` set, so it is not used. `printf` is a builtin in zsh, bash,
+ * dash and fish, and each reads `\033` in the format as octal ESC; the single
+ * quotes keep the backslash for printf in all of them.
+ *
+ * Joined with `;`, not `&&`, and with `clear`'s stderr dropped: a pane whose
+ * `clear` is missing or fails (unknown `TERM`, no ncurses), or whose `printf`
+ * fails, must still start the agent — a launch line left on screen is a
+ * cosmetic leak, a session that never starts is not — and must not print the
+ * failure in the line's place.
+ *
+ * Applied at the `sendKeys` call site, AFTER any flags a tool appends
+ * (`--model`, `-s <id>`, Command Code's launch flags): `buildAgentLaunchCommandLine`
+ * stays `NAME='value' … command`, and an appended flag lands on the agent, not
+ * on `clear`.
+ *
+ * Deliberately not in a module the session suites mock wholesale
+ * (`agent-session-lifecycle`, `tmux`), so those suites see the real prefix.
+ *
+ * @module lib/session/launch-screen
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAUNCH_SCREEN_CLEAR_PREFIX = void 0;
+exports.withLaunchScreenCleared = withLaunchScreenCleared;
+/** The prefix every launch line is typed with. */
+exports.LAUNCH_SCREEN_CLEAR_PREFIX = "clear 2>/dev/null; printf '\\033[3J'; ";
+/**
+ * The line to type into the pane: clear the screen and the scrollback, then launch.
+ *
+ * @param launchCommand - The rendered launch line, flags included
+ * @returns `clear 2>/dev/null; printf '\033[3J'; <launchCommand>`
+ */
+function withLaunchScreenCleared(launchCommand) {
+    return `${exports.LAUNCH_SCREEN_CLEAR_PREFIX}${launchCommand}`;
+}

package/dist/server/src/lib/session/prompt-view.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * How a waiting prompt is shown and answered, decided once (Issue #3184).
+ *
+ * Before this module every reader of a prompt payload re-derived the same three
+ * facts for itself — "can it be answered?", "where are the choices?", "is the
+ * answer a keystroke or an API call?" — from `type`, `options`,
+ * `decisionOptions`, `decisionId` and `askUserQuestion`. The panel, the phone
+ * sheet, the chat surface, Auto-Yes and `wait` each combined them a little
+ * differently, and a fix to one surface kept missing the others (#2775 →
+ * #2810 → #2822, #3181). {@link derivePromptView} is the one combination; a
+ * reader takes its {@link PromptView} and does not look at the raw fields to
+ * decide what to show.
+ *
+ * ## No imports, on purpose
+ *
+ * The CLI (`tsconfig.cli.json`) compiles with `"paths": {}`, so it can reach a
+ * module under `src/lib` by a relative path only when nothing in that module's
+ * graph uses the `@/` alias. `types/models` and `session/structured-prompt` both
+ * do. The input is therefore a structural type ({@link PromptViewSource}) that
+ * every existing prompt shape — `LivePromptData`, `StoredPromptData`, the CLI's
+ * own `PromptData` mirror — satisfies without a cast, and this file stays
+ * importable from a client component, the server and the CLI alike.
+ *
+ * ## What it does not replace
+ *
+ * `isAnswerablePromptData()` (`types/models`) stays: it narrows to the closed
+ * `PromptData` union (#1725) for the code that builds an answer body. The two
+ * agree by construction — `derivePromptView(x)?.kind === 'screen-choices'`
+ * exactly when `isAnswerablePromptData(x)` — and
+ * `tests/unit/session/prompt-view-3184.test.ts` holds that over every fixture.
+ *
+ * @module lib/session/prompt-view
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPED_TEXT_FIELD_LABEL_PATTERNS = exports.UNCLASSIFIED_PROMPT_VIEW_TYPE = void 0;
+exports.promptHeadingMessage = promptHeadingMessage;
+exports.optionTakesTypedText = optionTakesTypedText;
+exports.readDecisionId = readDecisionId;
+exports.readQuestionChoices = readQuestionChoices;
+exports.readDecisionHeading = readDecisionHeading;
+exports.derivePromptView = derivePromptView;
+exports.readPromptView = readPromptView;
+/**
+ * `promptData.type` for a frame nothing could classify. Same value as
+ * `UNCLASSIFIED_PROMPT_TYPE` in `types/models`, restated because this module may
+ * not import it (see the module note); the test asserts the two are equal.
+ */
+exports.UNCLASSIFIED_PROMPT_VIEW_TYPE = 'unclassified';
+function promptHeadingMessage(heading) {
+    switch (heading.kind) {
+        case 'question':
+            return { text: heading.text };
+        case 'approval':
+            return heading.toolName
+                ? { key: 'structuredApprovalTitle', values: { toolName: heading.toolName } }
+                : { key: 'structuredApprovalTitleNoTool' };
+        case 'agent-question':
+            return { key: 'structuredQuestionTitle' };
+        case 'unreadable':
+            return { key: 'unclassifiedTitle' };
+    }
+}
+// =============================================================================
+// Field readers (moved from components/worktree/prompt-decision-id, #1932/#2039/#3181)
+// =============================================================================
+/**
+ * The option labels measured to be a text field on screen (Issue #2573).
+ * Restated from `TYPED_TEXT_FIELD_LABEL_PATTERNS` in
+ * `lib/detection/prompt-detect-multiple-choice`, whose graph reaches `fs`.
+ */
+exports.TYPED_TEXT_FIELD_LABEL_PATTERNS = [
+    /^[^\S\n]*type\s+something\b/i,
+];
+/**
+ * Whether an option is a text field on screen, so its answer is the typed TEXT
+ * rather than its number (Issue #2573). `requiresTextInput` alone is also true
+ * for a menu row such as `No, tell Command Code what to do differently`.
+ */
+function optionTakesTypedText(option) {
+    return option.requiresTextInput === true
+        && exports.TYPED_TEXT_FIELD_LABEL_PATTERNS.some((pattern) => pattern.test(option.label));
+}
+/**
+ * The decision id a payload names, or null (Issue #1932). A validating read:
+ * absent, empty or not a string is "no addressable decision".
+ */
+function readDecisionId(source) {
+    if (!source)
+        return null;
+    const candidate = source.decisionId;
+    return typeof candidate === 'string' && candidate !== '' ? candidate : null;
+}
+function hasDecisionOptions(source) {
+    return Array.isArray(source.decisionOptions) && source.decisionOptions.length > 0;
+}
+/**
+ * The choices a question offers when it may be answered over the API, or null
+ * (Issue #2039). All three must hold: a decision id, exactly one question with
+ * a complete label list, and NO approval verdicts on the same payload.
+ */
+function readQuestionChoices(source) {
+    if (!source || readDecisionId(source) === null)
+        return null;
+    if (hasDecisionOptions(source))
+        return null;
+    const asked = source.askUserQuestion;
+    if (!asked || typeof asked.question !== 'string' || asked.question === '')
+        return null;
+    if (!Array.isArray(asked.labels) || asked.labels.length === 0)
+        return null;
+    const labels = asked.labels.filter((label) => typeof label === 'string' && label !== '');
+    // Partial is worse than none: the numbers are positions in this list.
+    if (labels.length !== asked.labels.length)
+        return null;
+    const questionCount = typeof asked.questionCount === 'number' ? asked.questionCount : 1;
+    if (questionCount !== 1)
+        return null;
+    return {
+        question: asked.question,
+        labels,
+        questionCount,
+        ...(asked.custom === true ? { custom: true } : {}),
+    };
+}
+/** The heading for addressable choices, or null when there is nothing to click (#3181). */
+function readDecisionHeading(source) {
+    if (!source || readDecisionId(source) === null)
+        return null;
+    if (hasDecisionOptions(source)) {
+        return {
+            kind: 'approval',
+            toolName: typeof source.toolName === 'string' && source.toolName ? source.toolName : null,
+        };
+    }
+    return readQuestionChoices(source) ? { kind: 'question' } : null;
+}
+// =============================================================================
+// The view
+// =============================================================================
+function screenChoices(source) {
+    const options = Array.isArray(source.options) ? source.options : [];
+    const choices = [];
+    for (const option of options) {
+        if (typeof option === 'string') {
+            // yes_no: `['yes', 'no']`, answered by the word itself.
+            choices.push({
+                answer: option,
+                label: option,
+                isDefault: source.defaultOption === option,
+                takesText: false,
+            });
+            continue;
+        }
+        if (!option || typeof option !== 'object')
+            continue;
+        const o = option;
+        if (typeof o.number !== 'number' || typeof o.label !== 'string')
+            continue;
+        choices.push({
+            answer: String(o.number),
+            label: o.label,
+            isDefault: o.isDefault === true,
+            takesText: optionTakesTypedText({ label: o.label, requiresTextInput: o.requiresTextInput === true }),
+            ...(typeof o.description === 'string' ? { description: o.description } : {}),
+        });
+    }
+    return choices;
+}
+function decisionChoices(decisionOptions) {
+    if (!Array.isArray(decisionOptions))
+        return [];
+    const choices = [];
+    for (const option of decisionOptions) {
+        const o = option;
+        if (!o || typeof o.number !== 'number' || typeof o.label !== 'string')
+            continue;
+        choices.push({ answer: String(o.number), label: o.label, isDefault: false, takesText: false });
+    }
+    return choices;
+}
+const UNREADABLE_VIEW = {
+    kind: 'unreadable',
+    heading: { kind: 'unreadable' },
+    choices: [],
+    multiSelect: false,
+    freeText: null,
+    decisionId: null,
+    apiTarget: null,
+};
+/**
+ * Decide how a prompt payload is shown and answered (Issue #3184).
+ *
+ * Evaluated in this order (design §2.3):
+ *  1. any `type` but the unclassified sentinel → `screen-choices`;
+ *  2. unclassified + decision id + approval verdicts → `api-choices` (approval);
+ *  3. unclassified + decision id + one complete question → `api-choices` (question);
+ *  4. every other unclassified payload — no id, #1932's options-without-id half
+ *     state, and both stored history records — → `unreadable`.
+ *
+ * @param source - A live or stored prompt payload, or null
+ * @returns The view, or null when there is no prompt
+ */
+function derivePromptView(source) {
+    if (source == null)
+        return null;
+    if (source.type !== exports.UNCLASSIFIED_PROMPT_VIEW_TYPE) {
+        const choices = screenChoices(source);
+        return {
+            kind: 'screen-choices',
+            heading: { kind: 'question', text: typeof source.question === 'string' ? source.question : '' },
+            choices,
+            multiSelect: source.multiSelect === true,
+            freeText: choices.some((choice) => choice.takesText) ? { via: 'screen' } : null,
+            decisionId: null,
+            apiTarget: null,
+        };
+    }
+    const decisionId = readDecisionId(source);
+    if (decisionId !== null && hasDecisionOptions(source)) {
+        const choices = decisionChoices(source.decisionOptions);
+        if (choices.length > 0) {
+            return {
+                kind: 'api-choices',
+                heading: {
+                    kind: 'approval',
+                    toolName: typeof source.toolName === 'string' && source.toolName ? source.toolName : null,
+                },
+                choices,
+                multiSelect: false,
+                freeText: null,
+                decisionId,
+                apiTarget: 'approval',
+            };
+        }
+    }
+    const question = readQuestionChoices(source);
+    if (decisionId !== null && question !== null) {
+        return {
+            kind: 'api-choices',
+            heading: { kind: 'agent-question', text: question.question },
+            choices: question.labels.map((label, index) => ({
+                answer: String(index + 1),
+                label,
+                isDefault: false,
+                takesText: false,
+            })),
+            multiSelect: false,
+            freeText: question.custom === true ? { via: 'api' } : null,
+            decisionId,
+            apiTarget: 'question',
+        };
+    }
+    return UNREADABLE_VIEW;
+}
+/**
+ * The view a `current-output` payload carries, falling back to deriving it.
+ *
+ * `??`, not `||`: a server from before #3184 sends no `promptView`, and its
+ * absence means "this daemon does not publish the field" — the same function
+ * then decides from `promptData`, so old and new servers reach the same answer.
+ */
+function readPromptView(payload) {
+    if (!payload)
+        return null;
+    return payload.promptView ?? derivePromptView(payload.promptData);
+}

package/dist/server/src/lib/session/prompt-waiting-composition.js

@@ -33,11 +33,45 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRUCTURED_SEND_GUARD_ENV = exports.STRUCTURED_SEND_BLOCK_MAX_AGE_MS = void 0;
+exports.isApiAnswerableStructuredWait = isApiAnswerableStructuredWait;
+exports.isApiAnswerableWaitNow = isApiAnswerableWaitNow;
 exports.structuredWaitingReason = structuredWaitingReason;
 exports.resolvePromptWaiting = resolvePromptWaiting;
 exports.peekPromptWaiting = peekPromptWaiting;
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
 const status_mapping_1 = require("../../lib/session/status-mapping");
+const structured_prompt_1 = require("../../lib/session/structured-prompt");
+/**
+ * Whether a structured wait is one the app answers over the agent's own API
+ * (Issue #3184, design §6-2).
+ *
+ * The same three conjuncts `current-output-builder` requires before it
+ * publishes a `decisionId` on the live payload (its `addressableDecisionId`):
+ * the record came from `Notification(permission_prompt)` rather than being a
+ * `permission-request` forecast, the tool's event source names each decision
+ * by id (`eventIdentity: 'permission-id'`), and the record carries such an id.
+ * That is exactly when `derivePromptView` reads the payload as `api-choices` —
+ * an approval or a question the panel draws buttons for — so the waiting kind
+ * published beside it says `prompt` too, instead of the scraper's `menu` /
+ * `unclassified` and the push body's "check the terminal".
+ *
+ * @param structured - The structured record, or null
+ * @param eventIdentity - `capabilities.eventIdentity` of the tool's event source
+ */
+function isApiAnswerableStructuredWait(structured, eventIdentity) {
+    return (structured !== null &&
+        structured.source === 'notification' &&
+        eventIdentity === 'permission-id' &&
+        (0, structured_prompt_1.isAddressableDecision)(structured.decisionId));
+}
+/**
+ * {@link isApiAnswerableStructuredWait} for the record as it stands now — a
+ * read, like {@link peekPromptWaiting}: nothing is released or corroborated.
+ * Kept here so the structured record is still read in this one module (#1737).
+ */
+function isApiAnswerableWaitNow(worktreeId, cliToolId, instanceId, eventIdentity) {
+    return isApiAnswerableStructuredWait((0, agent_event_state_1.getStructuredPromptWaiting)(worktreeId, cliToolId, instanceId), eventIdentity);
+}
 /**
  * How long a structured-only dialog may keep refusing sends (Issue #1737).
  *