commandmate 0.21.4 → 0.22.0

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

@@ -8,8 +8,12 @@
  * paths byte-for-byte consistent (DRY).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeStructuredStatus = mergeStructuredStatus;
 exports.buildCurrentOutput = buildCurrentOutput;
 const db_1 = require("../../lib/db");
+const unclassified_frame_tracker_1 = require("../../lib/detection/unclassified-frame-tracker");
+const models_1 = require("../../types/models");
+const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
 const cli_session_1 = require("../../lib/session/cli-session");
 const status_detector_1 = require("../../lib/detection/status-detector");
@@ -18,6 +22,244 @@ const auto_yes_suppression_state_1 = require("../../lib/polling/auto-yes-suppres
 const status_capture_config_1 = require("../../config/status-capture-config");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const prompt_waiting_composition_1 = require("../../lib/session/prompt-waiting-composition");
+const ask_user_question_prompt_1 = require("../../lib/session/ask-user-question-prompt");
+const structured_prompt_1 = require("../../lib/session/structured-prompt");
+const logger = (0, logger_1.createLogger)('current-output-builder');
+/**
+ * Write the "detection failed on this frame" row (Issue #1708).
+ *
+ * Stored as a `prompt` message so `capture --prompts` — the audit trail that
+ * exists precisely to answer "why did this stall?" — lists it alongside the
+ * prompts that WERE detected. It must never read as one of them, so the
+ * promptData carries `type: 'unclassified'` and `status: 'unclassified'`; the
+ * latter is also what keeps it out of `markPendingPromptsAsAnswered()`, whose
+ * SQL selects `status = 'pending'`. A frame nobody could read must not end up
+ * stamped "(answered via terminal)" the moment the flag clears.
+ *
+ * Not broadcast: this is a record for after the fact, and the prompt-answering
+ * UI has nothing to render for a frame with no parsed options.
+ *
+ * REACH, stated plainly because it is a real limit: this is driven by
+ * observation, not by the server's own loops. `buildCurrentOutput` has exactly
+ * two callers — the current-output route and `broadcastTerminalSnapshot`, which
+ * returns immediately when the room has no subscribers. So a row is written
+ * while `commandmate wait` is polling (every POLL_INTERVAL_MS), while a browser
+ * has the terminal open, or on a `capture --json`. A stall that nobody is
+ * watching at all writes nothing, and `capture --prompts` afterwards will not
+ * show it. That is tolerable because the stalls this exists to explain are the
+ * ones something WAS waiting on — but it means the Auto-Yes poller running
+ * alone is not enough. Feeding the tracker from that loop would need a second
+ * producer of `isUnclassifiedActive`, i.e. either duplicating its definition or
+ * adding a detectSessionStatus pass to a hot path; deliberately not done here.
+ *
+ * Best effort — a failed insert must never break the payload the caller is
+ * waiting on. The tracker has already marked the run as recorded, so a failure
+ * costs this one row, not a retry storm.
+ */
+function recordUnclassifiedFrame(db, params) {
+    const dwellSeconds = Math.round(params.dwellMs / 1000);
+    const statusReason = `${params.sessionStatus}/${params.sessionStatusReason}`;
+    const question = `Unclassified interactive frame (${statusReason}) held for ${dwellSeconds}s. ` +
+        `The detection layer could not parse it, so no prompt was published and ` +
+        `nothing could answer it. Inspect the raw pane with ` +
+        `\`commandmate capture ${params.worktreeId} --pane\`.`;
+    const record = {
+        type: models_1.UNCLASSIFIED_PROMPT_TYPE,
+        status: 'unclassified',
+        question,
+        options: [],
+        dwellSeconds,
+        sessionStatusReason: statusReason,
+    };
+    try {
+        (0, db_1.createMessage)(db, {
+            worktreeId: params.worktreeId,
+            role: 'assistant',
+            content: question,
+            messageType: 'prompt',
+            // Not a PromptData: nothing may answer this row, which is why the record
+            // type is kept out of that union (see UnclassifiedFrameRecord). The column
+            // is shared, so the cast is confined to this one write.
+            promptData: record,
+            timestamp: new Date(),
+            cliToolId: params.cliToolId,
+            instanceId: params.instanceId,
+        });
+        logger.info('unclassified-frame-recorded', {
+            worktreeId: params.worktreeId,
+            cliToolId: params.cliToolId,
+            dwellSeconds,
+            statusReason,
+        });
+    }
+    catch (error) {
+        logger.warn('unclassified-frame-record-failed', {
+            worktreeId: params.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Write the "the agent said a dialog is open and we could not read it" row
+ * (Issue #1725, continuing #1708's proposal 2).
+ *
+ * Written once per waiting episode, and ONLY while the scraper is publishing no
+ * prompt of its own. Both halves matter:
+ *
+ *  - once, because `buildCurrentOutput` runs on every poll and a row per poll
+ *    would turn one blocked dialog into a wall of identical history;
+ *  - only when the scraper is blind, because when it is not, the existing
+ *    prompt writers already record that prompt with its options and its answer.
+ *    A second row would double-count the audit trail `capture --prompts` prints
+ *    and put a "nobody could read this" line next to the parsed prompt that
+ *    proves somebody could.
+ *
+ * So a row here means exactly one thing, which is the thing #1708 asked to be
+ * recorded: a prompt existed and the detection layer did not see it.
+ *
+ * Best effort, for the same reason as {@link recordUnclassifiedFrame}: the
+ * caller is waiting on a payload, and a failed insert must cost this row and
+ * nothing else.
+ */
+function recordStructuredPrompt(db, params) {
+    const record = (0, structured_prompt_1.buildStructuredPromptHistoryRecord)(params.worktreeId, params.facts);
+    try {
+        (0, db_1.createMessage)(db, {
+            worktreeId: params.worktreeId,
+            role: 'assistant',
+            content: record.question,
+            summary: `structured prompt · source=${params.state.source}${params.state.toolName ? ` · tool=${params.state.toolName}` : ''}`,
+            messageType: 'prompt',
+            // Not a PromptData: it has no options and nothing may answer it by
+            // number. The column is shared, so the cast is confined to this write —
+            // the same arrangement UnclassifiedFrameRecord uses.
+            promptData: record,
+            timestamp: new Date(),
+            cliToolId: params.cliToolId,
+            instanceId: params.instanceId,
+        });
+        logger.info('structured-prompt-recorded', {
+            worktreeId: params.worktreeId,
+            cliToolId: params.cliToolId,
+            instanceId: params.instanceId,
+            source: params.state.source,
+            toolName: params.state.toolName,
+        });
+    }
+    catch (error) {
+        logger.warn('structured-prompt-record-failed', {
+            worktreeId: params.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * The `AskUserQuestion` call as the degraded prompt can describe it
+ * (Issue #1726).
+ *
+ * Only the first question, and no option numbers — see
+ * {@link StructuredAskUserQuestionSummary} for why a layer that cannot see the
+ * screen must not publish numbers for it.
+ */
+function summarizeAskUserQuestion(episode) {
+    const first = episode?.spec.questions[0];
+    if (!first)
+        return null;
+    return {
+        question: first.question,
+        labels: first.choices.map((choice) => choice.label),
+        questionCount: episode.spec.questions.length,
+    };
+}
+/**
+ * Prefer the agent's own account of what it is doing over the screen scrape
+ * (Issue #1723).
+ *
+ * Pure, and exported so the whole precedence table can be tested without a tmux
+ * session behind it.
+ *
+ * ## Why the scraper still wins in two cases
+ *
+ * **`waiting` on the scraper's side always wins.** A frame the detector reads
+ * as a prompt, a selection list or a pager is a frame a human has to act on,
+ * and this Issue deliberately does not touch `isPromptWaiting` / `promptData` /
+ * `isSelectionListActive` (they are #1725's). Letting a structured `running`
+ * overwrite `sessionStatus` while those three still said "answer me" would
+ * publish a self-contradicting payload. It is also the empirically necessary
+ * rule: the live capture found that Claude emits **no event at all** while an
+ * `AskUserQuestion` selection or "Ready to submit your answers?" screen is up
+ * (`agent-hooks-live-verification.md` §5.6), so the newest structured fact
+ * there is the `user_prompt_submit` that opened the turn — `running` — while
+ * the truth on screen is "waiting for a human". That is precisely the #1708
+ * stall, and the scraper is the only layer that can see it.
+ *
+ * **A structured `waiting` is applied only through the prompt-waiting state**
+ * (Issue #1725). #1723 recorded `Notification(permission_prompt)` and stopped
+ * there, for a reason that had to be answered before it could be promoted:
+ * nothing marks a permission prompt as *answered*, so a verdict read off the
+ * last event alone would stick until the next `Stop` and describe a session
+ * that went back to work minutes ago. `getStructuredPromptWaiting` is that
+ * answer — it is released by `Stop` / `user_prompt_submit` / a generation
+ * change, by the scraper reporting the frame it corroborated has cleared, and
+ * by expiry. So the `waiting` promoted here is the one that survives all of
+ * those, passed in explicitly; the raw `structured.status === 'waiting'` still
+ * decides nothing on its own.
+ *
+ * ## The one flag this touches beyond `sessionStatus`
+ *
+ * `isUnclassifiedActive` is cleared only for the `Stop`-arrived-but-the-pane-
+ * still-looks-busy case (structured `ready` over scraper `running`). That case
+ * is the entire point of the Issue for `commandmate wait`, whose completion
+ * check is `sessionStatus === 'ready' && isUnclassifiedActive !== true` — leave
+ * the flag up and the structured `ready` buys nothing.
+ *
+ * Everywhere else the flag is left exactly as the scraper set it, which is not
+ * timidity but two specific behaviours that must survive:
+ *
+ *  - a static overlay left on screen after a turn (`/help`, #1497) reads as
+ *    `ready`/`no_recent_output` while the structured layer also says `ready` —
+ *    the two agree, the structured layer adds nothing, and clearing the flag
+ *    would take away the navigation hatch the user needs to escape;
+ *  - a frame nobody can classify while the structured layer says `running` is
+ *    still a frame nobody can classify. `wait`'s unclassified dwell (exit 10)
+ *    is the last hatch for a screen that produces no events at all, and #1708
+ *    exists because it was missing. A structured `running` does not prove a
+ *    human is not needed — see the AskUserQuestion case above.
+ */
+function mergeStructuredStatus(scraper, structured, promptWaiting = null) {
+    if (scraper.status === 'waiting') {
+        return { ...scraper, structuredApplied: false };
+    }
+    // Issue #1725, the OR rule at the status level: the scraper reads this frame
+    // as running or ready, and the agent has told us a dialog is in front of it.
+    // Publishing `running` next to `isPromptWaiting: true` would be a payload
+    // that contradicts itself, and every consumer of `sessionStatus` — the
+    // sidebar dot, `deriveSessionStatus`, the worktrees API — would show a worker
+    // that needs a human as one that is busy.
+    if (promptWaiting !== null) {
+        return {
+            status: 'waiting',
+            reason: (0, prompt_waiting_composition_1.structuredWaitingReason)(promptWaiting),
+            thinking: false,
+            isUnclassifiedActive: scraper.isUnclassifiedActive,
+            structuredApplied: true,
+        };
+    }
+    if (structured === null || structured.status === 'waiting') {
+        return { ...scraper, structuredApplied: false };
+    }
+    const thinking = structured.status === 'running';
+    return {
+        status: structured.status,
+        reason: structured.reason,
+        thinking,
+        isUnclassifiedActive: structured.status === 'ready' && scraper.status === 'running'
+            ? false
+            : scraper.isUnclassifiedActive,
+        structuredApplied: true,
+    };
+}
 /**
  * Build the current-output payload for a worktree session.
  *
@@ -31,6 +273,14 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
     const manager = manager_1.CLIToolManager.getInstance();
     const cliTool = manager.getTool(cliToolId);
     const stopEventAt = (0, agent_event_state_1.getLastStopEventAt)(worktreeId, cliToolId, instanceId);
+    const lastEvent = (0, agent_event_state_1.getLastAgentEvent)(worktreeId, cliToolId, instanceId);
+    const structuredEvents = {
+        lastEventType: lastEvent?.event ?? null,
+        lastEventAt: lastEvent?.at ?? null,
+        lastEventDetail: lastEvent?.detail ?? null,
+        promptWaitingSince: null,
+        promptWaitingSource: null,
+    };
     const running = await cliTool.isRunning(worktreeId, instanceId);
     if (!running) {
         return {
@@ -41,6 +291,7 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
             sessionStatus: 'idle',
             sessionStatusReason: 'session_not_running',
             lastStopEventAt: stopEventAt,
+            structuredEvents,
         };
     }
     const sessionState = (0, db_1.getSessionState)(db, worktreeId, resolvedInstanceId);
@@ -67,7 +318,7 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
     const lastOutputTimestamp = lastServerResponseTimestamp ? new Date(lastServerResponseTimestamp) : undefined;
     const statusResult = (0, status_detector_1.detectSessionStatus)(output, cliToolId, lastOutputTimestamp);
     const thinking = statusResult.status === 'running' && statusResult.reason === status_detector_1.STATUS_REASON.THINKING_INDICATOR;
-    const isPromptWaiting = statusResult.hasActivePrompt;
+    const scraperPromptWaiting = statusResult.hasActivePrompt;
     const isSelectionListActive = statusResult.status === 'waiting' && status_detector_1.SELECTION_LIST_REASONS.has(statusResult.reason);
     const isPagerActive = statusResult.reason === status_detector_1.STATUS_REASON.CODEX_PAGER;
     // Issue #1497: the detection-independent nav hatch (#1017/#1494) is gated on
@@ -80,24 +331,139 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
     // as unclassified too and keep the hatch open instead of stranding the user.
     const isUnclassifiedActive = (statusResult.status === 'running' && statusResult.reason === status_detector_1.STATUS_REASON.DEFAULT) ||
         (statusResult.status === 'ready' && statusResult.reason === status_detector_1.STATUS_REASON.NO_RECENT_OUTPUT);
+    // Issue #1723: the two-layer merge. Everything above this line is the string
+    // analysis, unchanged and still the only source on a machine where no hook
+    // ever fires — `getStructuredSessionState` answers null there, and
+    // `mergeStructuredStatus` then returns the scraper's verdict untouched.
+    const structured = (0, agent_event_state_1.getStructuredSessionState)(worktreeId, cliToolId, instanceId);
+    // Issue #1725: the open-dialog half of the same merge, resolved before the
+    // status merge because it decides one of its inputs. The rule itself — the
+    // asymmetric release and the OR below — lives in `prompt-waiting-composition`
+    // since Issue #1737, because the `send` guard has to reach the same verdict
+    // and a second copy here is exactly how the two answers diverged.
+    const promptResolution = (0, prompt_waiting_composition_1.resolvePromptWaiting)({
+        worktreeId,
+        cliToolId,
+        instanceId,
+        scraper: {
+            status: statusResult.status,
+            reason: statusResult.reason,
+            hasActivePrompt: scraperPromptWaiting,
+        },
+    });
+    const promptWaiting = promptResolution.structured;
+    if (promptWaiting !== null) {
+        structuredEvents.promptWaitingSince = promptWaiting.at;
+        structuredEvents.promptWaitingSource = promptWaiting.source;
+    }
+    const merged = mergeStructuredStatus({ status: statusResult.status, reason: statusResult.reason, thinking, isUnclassifiedActive }, structured, promptWaiting);
+    // The OR rule, computed once for the whole server (Issue #1737): this is the
+    // same `resolvePromptWaiting` call the `send` guard makes, so the payload and
+    // 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 #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
+    // all while an AskUserQuestion picker is up (§5.6) and a record that asserted
+    // `waiting` from the invocation would go on asserting it long after a human
+    // answered in the terminal.
+    const askUserQuestion = (0, agent_event_state_1.getAskUserQuestion)(worktreeId, cliToolId, instanceId);
+    const scraperPromptData = statusResult.promptDetection.promptData;
+    const correctedPromptData = scraperPromptData && askUserQuestion
+        ? (0, ask_user_question_prompt_1.applyAskUserQuestion)(scraperPromptData, askUserQuestion.spec)
+        : null;
+    // The degraded form, for a dialog only the structured layer can see. Enriched
+    // with the question text when one is in flight — that turns "a dialog is open
+    // and nobody could read it" into "a dialog is open and here is what it asks".
+    const structuredFacts = promptWaiting === null
+        ? null
+        : { ...promptWaiting, askUserQuestion: summarizeAskUserQuestion(askUserQuestion) };
+    const promptData = scraperPromptWaiting
+        ? correctedPromptData ??
+            scraperPromptData ??
+            (structuredFacts ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts) : null)
+        : structuredFacts
+            ? (0, structured_prompt_1.buildStructuredPromptData)(worktreeId, structuredFacts)
+            : null;
+    // Issue #1723 §3: the field data this Epic is being built on. Every line is
+    // one poll where the screen and the agent disagreed about what the agent was
+    // doing, which is the only way to answer "how wrong was the scraper?" with a
+    // number instead of an anecdote. Emitted only on disagreement — a session
+    // where the two layers agree is silent — and including the disagreements this
+    // merge deliberately does NOT act on (`applied: false`), because those are
+    // exactly the cases the next Issues in the Epic have to decide about.
+    if (structured !== null && structured.status !== statusResult.status) {
+        logger.info('detection-divergence', {
+            worktreeId,
+            cliToolId,
+            instanceId: resolvedInstanceId,
+            scraperStatus: statusResult.status,
+            scraperReason: statusResult.reason,
+            structuredStatus: structured.status,
+            structuredReason: structured.reason,
+            structuredEvent: structured.event,
+            structuredEventAt: structured.at,
+            applied: merged.structuredApplied,
+        });
+    }
+    // Issue #1708: a frame nothing could classify left no trace anywhere. Both
+    // prompt-history writers (response-checker's pending row and
+    // recordAnsweredPrompt) are gated on `promptDetection.isPrompt === true`, so
+    // the only evidence a worker had stalled was the live pane — and `capture
+    // --prompts` answered "No prompt history." for a session that had been stuck
+    // for 900s. Record the failure itself, once, after it has persisted.
+    //
+    // Recorded here because this is the one place the flag is computed, and both
+    // the HTTP pull and the WebSocket push run through it, so the row appears at
+    // whatever cadence the session is actually being watched at.
+    //
+    // Fed the MERGED flag (#1723): a frame the structured layer classified is not
+    // an unclassified frame, and writing a "detection failed" row for a turn the
+    // agent itself told us had ended would put a false stall into the audit trail
+    // `capture --prompts` prints.
+    const unclassifiedVerdict = (0, unclassified_frame_tracker_1.observeUnclassifiedFrame)(compositeKey, merged.isUnclassifiedActive);
+    if (unclassifiedVerdict.shouldRecord) {
+        recordUnclassifiedFrame(db, {
+            worktreeId,
+            cliToolId,
+            instanceId: resolvedInstanceId,
+            dwellMs: unclassifiedVerdict.dwellMs,
+            sessionStatus: merged.status,
+            sessionStatusReason: merged.reason,
+        });
+    }
+    // Issue #1725: the structured layer saw a dialog the scraper did not. That
+    // gap is the fact worth keeping — see recordStructuredPrompt.
+    if (promptWaiting !== null && structuredFacts !== null && !scraperPromptWaiting && !promptWaiting.recorded) {
+        (0, agent_event_state_1.markStructuredPromptRecorded)(worktreeId, cliToolId, instanceId);
+        recordStructuredPrompt(db, {
+            worktreeId,
+            cliToolId,
+            instanceId: resolvedInstanceId,
+            state: promptWaiting,
+            facts: structuredFacts,
+        });
+    }
     const realtimeSnippet = lines.slice(-100).join('\n');
     const autoYesState = (0, auto_yes_manager_1.getAutoYesState)(worktreeId, cliToolId, instanceId);
     return {
         isRunning: true,
         cliToolId,
-        sessionStatus: statusResult.status,
-        sessionStatusReason: statusResult.reason,
+        sessionStatus: merged.status,
+        sessionStatusReason: merged.reason,
         content: newContent,
         fullOutput: output,
         realtimeSnippet,
         lineCount: totalLines,
         lastCapturedLine,
         isComplete: isPromptWaiting,
-        isGenerating: thinking,
-        thinking,
-        thinkingMessage: thinking ? 'Claude is thinking...' : null,
+        isGenerating: merged.thinking,
+        thinking: merged.thinking,
+        thinkingMessage: merged.thinking ? 'Claude is thinking...' : null,
         isPromptWaiting,
-        promptData: isPromptWaiting ? statusResult.promptDetection.promptData ?? null : null,
+        promptData,
         autoYes: {
             enabled: autoYesState?.enabled ?? false,
             expiresAt: autoYesState?.enabled ? autoYesState.expiresAt : null,
@@ -106,9 +472,10 @@ async function buildCurrentOutput(db, worktreeId, cliToolId, instanceId) {
         },
         isSelectionListActive,
         isPagerActive,
-        isUnclassifiedActive,
+        isUnclassifiedActive: merged.isUnclassifiedActive,
         lastServerResponseTimestamp,
         serverPollerActive: (0, auto_yes_manager_1.isPollerActive)(compositeKey),
         lastStopEventAt: stopEventAt,
+        structuredEvents,
     };
 }

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

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * The single answer to "is a prompt waiting on this session?" (Issue #1737).
+ *
+ * Two layers can see a dialog: the screen scraper (`detectSessionStatus`) and
+ * the agent's own structured events (`agent-event-state`). Issue #1725 composed
+ * them with OR inside `buildCurrentOutput` — and the `send` guard added by
+ * #1708 asked the scraper directly, so the same question had two answers and
+ * the guard let a structured-only dialog through. This module holds the
+ * composition once; `current-output-builder` and `prompt-waiting-guard` both
+ * read it and neither reimplements it.
+ *
+ * ## Two verdicts, deliberately, from one resolution
+ *
+ * `waiting` is what the payload publishes. `blocksSend` is what refuses a send.
+ * They are not the same question because they do not cost the same thing when
+ * they are wrong:
+ *
+ *  - a wrong `waiting` costs a user a prompt panel they can dismiss, and costs
+ *    `wait --on-prompt agent` an early exit 10 — bounded, visible, recoverable;
+ *  - a wrong `blocksSend` costs the session its writability. Nobody can talk to
+ *    the agent, including the operator trying to unstick it. That is the
+ *    failure #1725's author declined to risk ("a provisional record making a
+ *    session unwritable is a worse failure than the one it would prevent"), and
+ *    it is the reason this module exists rather than a one-line OR in the guard.
+ *
+ * So the structured layer's veto over sends — and only that veto — is bounded
+ * three ways: {@link STRUCTURED_SEND_BLOCK_MAX_AGE_MS}, a server-wide env
+ * switch, and a per-send opt-out. The scraper's half is bounded by nothing,
+ * because it re-reads the live frame every time and releases itself.
+ *
+ * @module lib/session/prompt-waiting-composition
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRUCTURED_SEND_GUARD_ENV = exports.STRUCTURED_SEND_BLOCK_MAX_AGE_MS = void 0;
+exports.structuredWaitingReason = structuredWaitingReason;
+exports.resolvePromptWaiting = resolvePromptWaiting;
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const status_mapping_1 = require("../../lib/session/status-mapping");
+/**
+ * How long a structured-only dialog may keep refusing sends (Issue #1737).
+ *
+ * The structured record is released by `Stop`, `user_prompt_submit`,
+ * `post_tool_use`, `Notification(idle_prompt)`, a generation change, and by the
+ * scraper watching the frame it corroborated clear. Every one of those is an
+ * event that may simply never arrive: hooks are fail-open by design, a `Stop`
+ * can be lost to a timeout, and the case this whole feature exists for is the
+ * scraper being blind to the dialog and therefore unable to report it gone. Put
+ * those together and a record can outlive its dialog with nothing left to
+ * release it — until {@link
+ * agent-event-state!STRUCTURED_STATE_MAX_AGE_MS} at 30 minutes, which is far too
+ * long to leave a session unwritable.
+ *
+ * Five minutes is chosen against what it costs in each direction. Losing the
+ * veto early costs the pre-#1737 behaviour for a dialog *the scraper cannot
+ * see* — a narrow slice of the #1708 hazard, since a dialog the scraper CAN see
+ * still blocks with no time bound at all. Holding it too long costs an operator
+ * every route to their own agent. The first is a missed guard; the second is an
+ * outage.
+ *
+ * Measured from the record's `at` — when the human was first reported blocked —
+ * for the same reason the other bounds are: that is the instant the fact was
+ * created, and refreshing it on corroboration would let a scraper that keeps
+ * misreading a frame extend the veto indefinitely.
+ */
+exports.STRUCTURED_SEND_BLOCK_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * Server-wide off switch for the structured half of the send guard.
+ *
+ * Set to `off` (or `0` / `false`) to make `send` consult only the scraper, i.e.
+ * exactly the #1708 guard. The escape hatch of last resort: it needs a server
+ * restart, which by itself already clears the in-memory record, so the per-send
+ * opt-out is the one an operator reaches for first. This exists for the fleet
+ * that decides it does not want the structured veto at all.
+ */
+exports.STRUCTURED_SEND_GUARD_ENV = 'CM_STRUCTURED_SEND_GUARD';
+/**
+ * The status reason a structured-only dialog publishes.
+ *
+ * Shared so `sessionStatusReason` in the payload and the reason logged by the
+ * send refusal cannot drift apart — an operator reading `hook_permission_prompt`
+ * in one surface should find the same word in the other.
+ */
+function structuredWaitingReason(state) {
+    return state.source === 'notification'
+        ? status_mapping_1.HOOK_STATUS_REASON.PERMISSION_PROMPT
+        : status_mapping_1.HOOK_STATUS_REASON.PERMISSION_REQUEST;
+}
+/** Whether {@link STRUCTURED_SEND_GUARD_ENV} turns the structured veto off. */
+function isStructuredSendGuardDisabled() {
+    const raw = process.env[exports.STRUCTURED_SEND_GUARD_ENV]?.trim().toLowerCase();
+    return raw === 'off' || raw === '0' || raw === 'false';
+}
+/**
+ * Resolve both layers into one verdict, applying the release rule on the way.
+ *
+ * Has side effects on the structured record, by design: this is the only place
+ * the scraper's observations reach it, so every caller that captured a frame
+ * must feed it here or the release rule simply stops running for that path.
+ *
+ * The release rule is asymmetric on purpose (Issue #1725). The scraper is
+ * allowed to say "that prompt is gone" only about a prompt it once saw, because
+ * the case this exists for is the scraper being BLIND to the dialog: if "the
+ * scraper reports no prompt" released the state on its own, the structured
+ * layer would be silenced in exactly the situation it was added for. So a frame
+ * the scraper reads as `waiting` arms the release (and confirms a provisional
+ * record), and only after that does a non-waiting frame clear it.
+ *
+ * This is also what the push/pull timing demands. The structured fact arrives
+ * over HTTP the moment the agent posts it, while the scraper reads a pane
+ * through a 5 s capture cache (`CACHE_TTL_MS`), so "the event is here and the
+ * scraper has not seen the dialog yet" is a state that always exists — and
+ * under a rule that let the scraper's silence win, that state would be a lost
+ * detection every single time.
+ */
+function resolvePromptWaiting({ worktreeId, cliToolId, instanceId, scraper, ignoreStructured = false, now = Date.now(), }) {
+    let structured = (0, agent_event_state_1.getStructuredPromptWaiting)(worktreeId, cliToolId, instanceId, now);
+    if (structured !== null) {
+        if (scraper.status === 'waiting') {
+            (0, agent_event_state_1.corroborateStructuredPromptWaiting)(worktreeId, cliToolId, instanceId, now);
+        }
+        else if (structured.scraperCorroborated) {
+            (0, agent_event_state_1.clearStructuredPromptWaiting)(worktreeId, cliToolId, instanceId);
+            structured = null;
+        }
+    }
+    const waiting = scraper.hasActivePrompt || structured !== null;
+    // The scraper is reading the frame in front of it right now, so its verdict
+    // needs no bound: the next capture releases it.
+    if (scraper.hasActivePrompt) {
+        return {
+            waiting,
+            scraperWaiting: true,
+            structured,
+            blocksSend: true,
+            blockedBy: 'scraper',
+            blockReason: scraper.reason,
+            structuredSendBlockSuppressed: null,
+        };
+    }
+    if (structured === null) {
+        return {
+            waiting,
+            scraperWaiting: false,
+            structured: null,
+            blocksSend: false,
+            blockedBy: null,
+            blockReason: null,
+            structuredSendBlockSuppressed: null,
+        };
+    }
+    const suppressed = structuredSendBlockSuppression(structured, ignoreStructured, now);
+    return {
+        waiting,
+        scraperWaiting: false,
+        structured,
+        blocksSend: suppressed === null,
+        blockedBy: suppressed === null ? 'structured' : null,
+        blockReason: suppressed === null ? structuredWaitingReason(structured) : null,
+        structuredSendBlockSuppressed: suppressed,
+    };
+}
+/**
+ * Why this structured record may not refuse a send, or null when it may.
+ *
+ * Ordered so the answer names the operator's own action first: someone who
+ * passed the opt-out should be told that is what happened, not that the record
+ * had also aged out.
+ */
+function structuredSendBlockSuppression(state, ignoreStructured, now) {
+    if (ignoreStructured)
+        return 'caller_opt_out';
+    if (isStructuredSendGuardDisabled())
+        return 'disabled';
+    if (now - state.at >= exports.STRUCTURED_SEND_BLOCK_MAX_AGE_MS)
+        return 'expired';
+    return null;
+}