commandmate 0.44.1 → 0.44.3

package/dist/cli/commands/wait.js

@@ -31,6 +31,7 @@ const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const verify_runner_1 = require("../utils/verify-runner");
 const agent_target_options_1 = require("../config/agent-target-options");
+const prompt_view_1 = require("../../lib/session/prompt-view");
 const instances_1 = require("./instances");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
@@ -53,7 +54,24 @@ const SELECTION_LIST_PROMPT_TYPE = 'selection_list';
  * among them) keeps working and simply meets a kind it does not recognise,
  * whereas a new exit code reads as an infrastructure error to all of them.
  */
-const UNCLASSIFIED_PROMPT_TYPE = 'unclassified';
+//
+// Issue #3184: the value comes from `lib/session/prompt-view` rather than a copy
+// here — that module has no imports, so the CLI build compiles it.
+const UNCLASSIFIED_PROMPT_TYPE = prompt_view_1.UNCLASSIFIED_PROMPT_VIEW_TYPE;
+/**
+ * How the prompt reported on exit 10 is answered (Issue #3184): `screen` = the
+ * option number or y/n typed at the pane (`respond`), `api` = a decision
+ * delivered over the agent's own API (`respond <id> <number>`, no keys sent),
+ * `terminal` = nothing to offer, a human answers at the pane. Read off the
+ * shared view so `wait` and the browser cannot reach different conclusions.
+ */
+function waitAnswerVia(view) {
+    if (view?.kind === 'screen-choices')
+        return 'screen';
+    if (view?.kind === 'api-choices')
+        return 'api';
+    return 'terminal';
+}
 /**
  * Why `wait` decided the agent was done, printed on the completion line
  * (Issue #1839).
@@ -200,6 +218,8 @@ function describePaneObstruction(data) {
 const SUPPRESSION_FRESH_MS = 60_000;
 /** The suppression currently blocking this session, or null. */
 function activeSuppression(data, now) {
+    // No `autoYes` at all (a session that is not running, Issue #3300) reads as
+    // "nothing was withheld", the same as a null record.
     const suppression = data.autoYes?.lastSuppression;
     if (!suppression)
         return null;
@@ -278,6 +298,33 @@ function formatSuppressionNotice(suppression, ageSeconds) {
     const cause = suppressionCause(suppression.reason);
     return `  auto-yes suppressed this prompt ${cause}: ${parts.join(' ')} (${ageSeconds}s ago)`;
 }
+/**
+ * One stderr line saying Auto-Yes pressed Enter on THIS prompt (Issue #3397), or
+ * null when the record is absent or about another screen.
+ *
+ * The prompt is one CommandMate could not read (the window offers direct input
+ * for it). `sent` — Auto-Yes confirmed whatever was selected; `no-effect` — the
+ * same screen outlived the Enter, no second one was sent, and it is a human's
+ * again. An outcome this CLI does not know is named verbatim (#1843's rule).
+ * `currentPrompt` is the server's judgement that the record is about the
+ * `promptData` of the same response, so an Enter sent to an earlier screen is
+ * never reported against this one.
+ */
+function formatEnterFallbackNotice(data, now) {
+    const record = data.autoYes?.lastEnterFallback;
+    if (!record || record.currentPrompt !== true)
+        return null;
+    const detail = `refusal=${record.refusalReason} promptType=${record.promptType}`;
+    const ago = `(${Math.max(0, Math.round((now - record.at) / 1000))}s ago)`;
+    if (record.outcome === 'sent') {
+        return `  auto-yes sent Enter to this prompt (CommandMate could not read it): ${detail} ${ago}`;
+    }
+    if (record.outcome === 'no-effect') {
+        return `  auto-yes sent Enter to this prompt, but the same screen is still up (no-effect); ` +
+            `answer it in the terminal: ${detail} ${ago}`;
+    }
+    return `  auto-yes Enter record for this prompt: outcome=${record.outcome} ${detail} ${ago}`;
+}
 /**
  * Whether this server publishes a real turn record (Issue #1930).
  *
@@ -660,6 +707,508 @@ function nextPollWithinDeadlines(options, startTime, lastActivityTime, now) {
     }
     return true;
 }
+/**
+ * The exit-10 payload for a prompt the detection layer parsed. `suppressed` is
+ * {@link activeSuppression}'s reading of the same poll.
+ */
+function buildPromptOutput(worktreeId, data, promptData, suppressed) {
+    // Issue #1898: the degraded `unclassified` payload carries no `options`
+    // — by construction, because nothing parsed the screen — but for a
+    // source whose approvals are answered by decision id it does carry
+    // `decisionOptions`, which ARE answerable (`respond <id> 1`). Reporting
+    // an empty list there told the caller a dialog was open and gave it
+    // nothing to do about it, which is the whole of #1898-3 seen from the
+    // pipeline's side.
+    //
+    // Issue #3184: and a QUESTION answered by decision id (OpenCode V2,
+    // #2100) carries neither — its choices are `askUserQuestion.labels`,
+    // numbered by position. The panel offered them as buttons while this
+    // reported `[]`. Which of these applies is the shared view's call
+    // (`readPromptView`), not a third reading of the raw fields here.
+    const promptView = (0, prompt_view_1.readPromptView)(data);
+    const promptOptions = promptData.options?.length
+        ? promptData.options
+        : promptData.decisionOptions?.length
+            ? promptData.decisionOptions
+            : promptView?.apiTarget === 'question'
+                ? promptView.choices.map((choice) => ({
+                    number: Number(choice.answer),
+                    label: choice.label,
+                }))
+                : [];
+    const promptOutput = {
+        worktreeId,
+        cliToolId: data.cliToolId || 'claude',
+        type: promptData.type || 'unknown',
+        question: promptData.question || '',
+        options: promptOptions,
+        status: promptData.status || 'pending',
+        answerVia: waitAnswerVia(promptView),
+        ...(promptData.approvalTarget !== undefined && {
+            approvalTarget: promptData.approvalTarget,
+        }),
+        ...(suppressed && {
+            autoYesSuppression: {
+                reason: suppressed.suppression.reason,
+                mode: suppressed.suppression.mode,
+                promptType: suppressed.suppression.promptType,
+                ...(suppressed.suppression.pattern !== undefined && {
+                    pattern: suppressed.suppression.pattern,
+                }),
+                ageSeconds: suppressed.ageSeconds,
+            },
+        }),
+    };
+    return promptOutput;
+}
+/** The exit-10 payload for an arrow-key selection list (Issue #1628). */
+function buildSelectionListOutput(worktreeId, data) {
+    return {
+        worktreeId,
+        cliToolId: data.cliToolId || 'claude',
+        type: SELECTION_LIST_PROMPT_TYPE,
+        question: data.sessionStatusReason ?? SELECTION_LIST_PROMPT_TYPE,
+        options: [],
+        status: 'pending',
+    };
+}
+/**
+ * What `wait` says about a frame that stayed unclassified for the whole dwell
+ * (Issue #1708): the stderr line, and the `question` of its exit-10 payload.
+ */
+function describeUnclassifiedFrame(worktreeId, data, dwellMs) {
+    const dwellSeconds = Math.round(dwellMs / 1000);
+    return (`Unclassified interactive frame on ${worktreeId} for ${dwellSeconds}s ` +
+        `(status=${data.sessionStatus ?? 'unknown'}/${data.sessionStatusReason ?? 'unknown'}). ` +
+        `The detection layer could not parse it; inspect the raw pane with ` +
+        `\`commandmate capture ${worktreeId} --pane\`.` +
+        // Issue #2095: the sidebar is exactly this frame's reason, and the
+        // one recovery is a keystroke in the pane. Riding the message keeps
+        // the exit-code table (10, `type: unclassified`) unchanged for every
+        // caller that already branches on it.
+        describePaneObstruction(data));
+}
+/** The exit-10 payload for a persistently unclassified frame (Issue #1708). */
+function buildUnclassifiedOutput(worktreeId, data, question) {
+    return {
+        worktreeId,
+        cliToolId: data.cliToolId || 'claude',
+        type: UNCLASSIFIED_PROMPT_TYPE,
+        question,
+        options: [],
+        status: 'pending',
+        answerVia: 'terminal',
+    };
+}
+/** The stderr line for a session this wait never saw running (Issue #1628). */
+function describeNotStarted(worktreeId, data, options) {
+    return (`Not started: ${worktreeId} has no running ${data.cliToolId ?? 'agent'} session` +
+        `${options.instance ? ` for instance ${options.instance}` : ''}` +
+        // Issue #1884: name the stage that chose the agent above. `wait` has
+        // no --agent to correct a mis-resolution with, so "no running claude
+        // session for instance opencode" was the entire evidence an operator
+        // got for a live agent reported as absent. `worktree-default` here
+        // means the instance is neither in the roster nor named after a
+        // tool; `client-fallback`, that the server is too old to resolve.
+        `${data.resolvedBy ? ` (resolvedBy=${data.resolvedBy})` : ''}.`);
+}
+/** The outcome that ends the wait with `result`. */
+function exitWith(result) {
+    return { kind: 'exit', result };
+}
+/**
+ * Stage: `--timeout` and `--stall-timeout`, asked at the top of every poll,
+ * before its request. Exit 124.
+ */
+function deadlineStage(poll, state) {
+    const { worktreeId, options, startTime } = poll;
+    // Check timeout
+    if (options.timeout) {
+        const elapsed = (Date.now() - startTime) / 1000;
+        if (elapsed >= options.timeout) {
+            console.error(`Timeout: ${worktreeId} exceeded ${options.timeout}s`);
+            return exitWith({ exitCode: types_1.WaitExitCode.TIMEOUT });
+        }
+    }
+    // Check stall-timeout
+    if (options.stallTimeout) {
+        const stallElapsed = (Date.now() - state.lastActivityTime) / 1000;
+        if (stallElapsed >= options.stallTimeout) {
+            console.error(`Stall timeout: ${worktreeId} no output for ${options.stallTimeout}s`);
+            return exitWith({ exitCode: types_1.WaitExitCode.TIMEOUT });
+        }
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage: a prompt the detection layer parsed. Exit 10, unless it is held for a
+ * human (`--on-prompt human`) or for the target's Auto-Yes (Issue #2463).
+ */
+function promptStage(poll, state, data) {
+    const { worktreeId, options, startTime, autoYesGraceSeconds, autoYesGraceMs } = poll;
+    // Prompt detected
+    if (data.isPromptWaiting && data.promptData) {
+        // Issue #1699: report a policy suppression on both exits — the human one
+        // keeps polling and would otherwise say nothing about why nobody
+        // answered, and the agent one is read by pipelines that never see stderr.
+        const suppressed = activeSuppression(data, Date.now());
+        // [DR1-03] Prompt detection exit code
+        if (options.onPrompt === 'human') {
+            // Block and continue polling - user handles prompt manually
+            console.error(`Prompt detected on ${worktreeId}. Waiting for human response...`);
+            if (suppressed) {
+                console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
+            }
+            // Issue #3397: and whether Auto-Yes already pressed Enter on it.
+            const enterNotice = formatEnterFallbackNotice(data, Date.now());
+            if (enterNotice)
+                console.error(enterNotice);
+            return { kind: 'wait' };
+        }
+        // Issue #2463: the one case `decidePromptPush()` stays quiet about —
+        // Auto-Yes is on and has not withheld this answer — is a prompt Auto-Yes
+        // is about to answer, and exit 10 there hands a delegation back to a
+        // human for a dialog nobody had to see. Hold it for the grace window; a
+        // poll that shows no prompt ends the hold below and completion is judged
+        // as usual. A withheld answer (`suppressed`) and Auto-Yes being off are
+        // the gate's other two branches and still exit 10 at once.
+        if (!suppressed && data.autoYes?.enabled === true && autoYesGraceMs > 0) {
+            const now = Date.now();
+            if (state.autoYesAnsweringSince === null) {
+                state.autoYesAnsweringSince = now;
+                // stderr only: stdout is the exit-10 payload and nothing else.
+                console.error("Prompt detected; the target's Auto-Yes is answering, waiting up to " +
+                    `${autoYesGraceSeconds}s… (${worktreeId})`);
+            }
+            const heldMs = now - state.autoYesAnsweringSince;
+            if (heldMs < autoYesGraceMs &&
+                nextPollWithinDeadlines(options, startTime, state.lastActivityTime, now)) {
+                return { kind: 'wait' };
+            }
+            console.error(heldMs < autoYesGraceMs
+                ? `Note: the prompt on ${worktreeId} is still open after ${Math.round(heldMs / 1000)}s ` +
+                    'under Auto-Yes, and the next poll would pass --timeout/--stall-timeout; reporting it now.'
+                : `Note: the target's Auto-Yes did not answer the prompt on ${worktreeId} within ` +
+                    `${autoYesGraceSeconds}s; reporting it.`);
+        }
+        else if (state.autoYesAnsweringSince !== null && !suppressed) {
+            console.error(`Note: Auto-Yes is no longer enabled on ${worktreeId}; reporting the prompt.`);
+        }
+        // Default (agent mode): output prompt info and exit 10
+        const promptOutput = buildPromptOutput(worktreeId, data, data.promptData, suppressed);
+        if (suppressed) {
+            console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
+        }
+        // Issue #3397: stderr only, like the notice above; the exit-10 payload is unchanged.
+        const enterNotice = formatEnterFallbackNotice(data, Date.now());
+        if (enterNotice)
+            console.error(enterNotice);
+        return exitWith({ exitCode: types_1.WaitExitCode.PROMPT_DETECTED, output: promptOutput });
+    }
+    return { kind: 'next' };
+}
+/** Stage: an arrow-key selection list (Issue #1628). Exit 10, or held under `--on-prompt human`. */
+function selectionListStage(poll, data) {
+    const { worktreeId, options } = poll;
+    // Issue #1628: an arrow-key menu is the agent blocked on a human just as much
+    // as a numbered prompt is, but it is published with isPromptWaiting=false so
+    // the UI can render NavigationButtons instead of PromptPanel. Treat it as a
+    // prompt here — otherwise `wait` polls a stopped agent until --timeout.
+    if (data.isSelectionListActive) {
+        if (options.onPrompt === 'human') {
+            console.error(`Selection list active on ${worktreeId} (${data.sessionStatusReason ?? 'selection_list'}). ` +
+                'Waiting for human response...');
+            // Issue #1699: the poller parses frames status-detector publishes as
+            // selection lists, so a policy can be the reason this one is stuck too.
+            const suppressed = activeSuppression(data, Date.now());
+            if (suppressed) {
+                console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
+            }
+            return { kind: 'wait' };
+        }
+        return exitWith({
+            exitCode: types_1.WaitExitCode.PROMPT_DETECTED,
+            output: buildSelectionListOutput(worktreeId, data),
+        });
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage: an interactive frame nothing could parse, once it has stayed up for the
+ * whole dwell (Issue #1708). Exit 10, or held under `--on-prompt human`.
+ */
+function unclassifiedStage(poll, state, data) {
+    const { worktreeId, options } = poll;
+    // Issue #1708: the frame is interactive but nothing could parse it. The
+    // detection layer is the single entry point every downstream safeguard
+    // hangs off, so a frame that slips past it disables Auto-Yes, the exit-10
+    // handoff and the contract's autoYes policy all at once — and `wait` used
+    // to burn its whole --timeout without ever mentioning it. Treat a
+    // PERSISTENT unclassified frame as a stop reason of its own.
+    //
+    // The dwell deliberately spans ALL THREE states that raise this flag, and
+    // the completion check below is suppressed while it is up. That is the
+    // whole point, and it is worth spelling out because the obvious reading is
+    // the wrong one. The server's definition (`isUnclassifiedFrame` in
+    // `src/lib/session/status-evidence.ts`, restated there by Issue #2011):
+    //
+    //   isUnclassifiedActive =
+    //     running && (default | unknown_frame | no_recent_output)
+    //
+    // `no_recent_output` is there because a static unrecognised overlay
+    // DEGRADES into it — once the Auto-Yes poller stamps
+    // lastServerResponseTimestamp, a frame that stopped changing flips from
+    // `running`/`default` after STALE_OUTPUT_THRESHOLD_MS (5s). `unknown_frame`
+    // is the same floor for a tool that opts out of the generic composer check
+    // (copilot, opencode), and says "this tool's own rules looked and read
+    // nothing". Both arrive about twelve times faster than this dwell. Letting
+    // the completion check claim one turned a stalled worker into `Completed`,
+    // which is worse than the timeout Issue #1708 complained about: exit 124
+    // stops a pipeline, exit 0 lets it merge. Measured before this guard: two
+    // unclassified polls followed by the degraded state returned SUCCESS.
+    //
+    // What is deliberately NOT in the set is `ready`/`input_prompt` with
+    // `statusEvidence: 'none'` — the agent back at its composer on a frame no
+    // tool-specific idle rule could vouch for. That frame WAS classified; what
+    // is missing is positive proof, which is a different question and §4 D1's
+    // to answer. Issue #1927 folded the two together and every idle Claude pane
+    // stopped completing (#2011). Whether `wait` should hold for evidence as
+    // well as classification is open, and any answer belongs in the same place
+    // as the rollout that produces the evidence — not here.
+    if (data.isUnclassifiedActive === true) {
+        if (state.unclassifiedSince === null)
+            state.unclassifiedSince = Date.now();
+        const dwellMs = Date.now() - state.unclassifiedSince;
+        if (dwellMs >= UNCLASSIFIED_DWELL_MS) {
+            const question = describeUnclassifiedFrame(worktreeId, data, dwellMs);
+            if (options.onPrompt === 'human') {
+                console.error(question);
+                console.error('Waiting for human response...');
+                return { kind: 'wait' };
+            }
+            console.error(question);
+            return exitWith({
+                exitCode: types_1.WaitExitCode.PROMPT_DETECTED,
+                output: buildUnclassifiedOutput(worktreeId, data, question),
+            });
+        }
+    }
+    else {
+        state.unclassifiedSince = null;
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage: the session is not running (Path A). Exit 21 when this wait never saw
+ * it alive (Issue #1628), exit 0 when it went away after it had been seen.
+ */
+function notRunningStage(poll, state, data, selfResumeSuffix) {
+    const { worktreeId, options } = poll;
+    // Completion check [DR1-04]:
+    // Path A: the tmux session went away after we had seen it alive — the agent
+    //         finished and its session was stopped.
+    // Path B: agent completed task (sessionStatus === 'ready', input prompt detected)
+    // Both indicate "no more work in progress" from wait command's perspective.
+    // (This stage handles Path A only; Path B is checked in `readyStage`.)
+    //
+    // Issue #1628 narrowed Path A: a session that was NEVER seen running is
+    // "nothing to wait for" (NOT_STARTED), not a completion. See `everRunning`.
+    if (!data.isRunning && !state.everRunning) {
+        console.error(describeNotStarted(worktreeId, data, options));
+        return exitWith({ exitCode: types_1.VerifyExitCode.NOT_STARTED });
+    }
+    if (!data.isRunning) {
+        console.error(`Completed: ${worktreeId} (basis=${COMPLETION_BASIS.SESSION_GONE}${selfResumeSuffix()})`);
+        return exitWith({ exitCode: types_1.WaitExitCode.SUCCESS });
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage of a `ready` frame: an upstream fault on the frame, under
+ * `--fail-on-upstream-fault` (Issue #1839). Exit 11.
+ */
+function upstreamFaultStage(poll, data) {
+    const { worktreeId, options } = poll;
+    // Issue #1839: the agent is back at its composer with an upstream
+    // failure on the frame. Checked BEFORE the turn-boundary gate below,
+    // because it is the answer to the question that gate can only ask: the
+    // turn did not end, and this is why. Without it the same session runs
+    // to --timeout and reports 124, which says nothing about the cause.
+    const fault = data.upstreamFault ?? null;
+    if (options.failOnUpstreamFault && fault) {
+        console.error(`Upstream fault on ${worktreeId}: id=${fault.id} — the agent is back at its ` +
+            'composer with an upstream API failure on screen, so this turn did not run. ' +
+            `Matched: ${JSON.stringify(fault.matchedText)}`);
+        if (fault.id === 'context-limit') {
+            // A retry into the same session hits the same wall (Issue #3011).
+            console.error('The session\'s conversation is over the model\'s context limit. Start a fresh ' +
+                `session and send again: commandmate instances ${worktreeId} kill ` +
+                `${options.instance ?? '<instance>'}`);
+        }
+        return exitWith({
+            exitCode: types_1.WaitExitCode.UPSTREAM_FAULT,
+            upstreamFault: { id: fault.id, matchedText: fault.matchedText },
+        });
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage of a `ready` frame: the agent has not reported the end of the turn this
+ * wait adopted (Issue #1839). Held.
+ */
+function unsettledTurnStage(poll, state, data) {
+    const { worktreeId } = poll;
+    // Issue #1839: `ready` off the terminal frame is the agent's composer,
+    // not the agent's verdict. Measured 2026-08-20 against a stub upstream
+    // answering 529: Claude returns to the composer ~3 s after the send
+    // having executed nothing, and never sends `Stop`. When this instance's
+    // hooks ARE reporting — the only case in which `turnStartedAt` is
+    // non-null — that missing `Stop` is the difference between "finished"
+    // and "never ran", and it is the only signal that carries it.
+    if (!turnSettled(data, state.turnStartedAt)) {
+        console.error(`Waiting: ${worktreeId} is back at its composer, but its agent has not reported ` +
+            `the end of this turn (turnStartedAt=${state.turnStartedAt}, ` +
+            `lastStopEventAt=${data.lastStopEventAt ?? 'none'}, ${describeTurnClose(data)}). ` +
+            'Not reporting completion; inspect with ' +
+            `\`commandmate capture ${worktreeId} --json\`.`);
+        return { kind: 'wait' };
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage of a `ready` frame: the turn ended on a `stop` that said the agent will
+ * resume by itself (Issue #2614). Held, up to {@link SELF_RESUME_HOLD_MS}.
+ */
+function selfResumeHoldStage(poll, state, data, selfResumeStopAt) {
+    const { worktreeId } = poll;
+    // Issue #2614: the turn did end — the agent said so — but it also said
+    // that work of its own is still running in the background (a `schedule`
+    // timer, a backgrounded command), and that work wakes it with nobody
+    // typing anything. Measured 2026-09-17 on antigravity 1.2.4: four such
+    // stops ~58 s before each self-wake, and the first one was reported as
+    // `Completed (basis=hook_stop)` and verified five minutes before the
+    // work was done. So this `stop` is held until it is no longer the newest
+    // word (see `selfResumeStopAt` above), or until the bound.
+    //
+    // The bound is measured from whichever is further along: the `stop`
+    // itself (server clock — a negative age is skew, and the max discards
+    // it) or this wait's first sight of it. A session that said so hours ago
+    // and never woke is not held again.
+    if (selfResumeStopAt !== null) {
+        const now = Date.now();
+        if (state.selfResumeHold === null)
+            state.selfResumeHold = { stopAt: selfResumeStopAt, since: now };
+        const heldMs = now - state.selfResumeHold.since;
+        const elapsedMs = Math.max(heldMs, now - selfResumeStopAt);
+        if (elapsedMs < exports.SELF_RESUME_HOLD_MS) {
+            state.selfResumeHeld = true;
+            console.error(`Waiting: ${worktreeId} ended its turn with background work still running ` +
+                `(stoppedAt=${new Date(selfResumeStopAt).toISOString()}, ` +
+                `lastEventDetail=${exports.SELF_RESUME_PENDING_DETAIL}, ${describeTurnClose(data)}); ` +
+                'it resumes by itself when that work finishes. Not reporting completion ' +
+                `(held ${Math.round(heldMs / 1000)}s, at most ${exports.SELF_RESUME_HOLD_MS / 1000}s ` +
+                'after the stop).');
+            return { kind: 'wait' };
+        }
+        console.error(`Note: ${worktreeId} said at its stop ${Math.round(elapsedMs / 1000)}s ` +
+            'ago that background work was still running, and has not resumed since; ' +
+            'completing on that stop.');
+    }
+    return { kind: 'next' };
+}
+/**
+ * Stage of a `ready` frame: the chat ledger shows a prompt the agent has not
+ * reported the end of (Issue #1975). Held, up to {@link PENDING_PROMPT_HOLD_MS}.
+ * `next` carries whether the newest prompt was answered, which
+ * {@link completionStage} needs for its basis.
+ */
+async function promptLedgerStage(poll, state, data) {
+    const { client, worktreeId, options, startTime } = poll;
+    // Issue #1975: the same frame, one question further back. #1839's gate
+    // above can only fire once a turn has been ADOPTED, and `send` leaves a
+    // window ~1s wide in which nothing has been: the newest structured event
+    // is still the previous turn's `stop`, so `adoptTurnStart` takes nothing,
+    // `turnSettled` reads null as "settled", and the composer the agent has
+    // not touched yet is read as the composer it came back to. Measured
+    // 2026-08-22 against copilot 1.0.80 on an isolated server: 3 of 5
+    // send-then-wait runs came back in ~0.3s with `basis=scraper_ready` and
+    // no artefact on disk.
+    //
+    // So ask the ledger instead of the clock: has this instance been handed
+    // a prompt that the agent has not reported the end of? See
+    // {@link outstandingPrompt} for why that comparison is the one that
+    // separates "not started" from "finished", and
+    // {@link reportsTurnBoundaries} for why a tool that posts no hooks never
+    // reaches it.
+    let answeredNewestPrompt = false;
+    if (state.turnStartedAt === null && state.promptLedgerReadable && reportsTurnBoundaries(data)) {
+        const ledger = await readNewestPromptAt(client, worktreeId, options, data);
+        // One notice, then stop asking: a ledger that failed once will fail
+        // every poll, and the point of degrading is to stop paying for it.
+        state.promptLedgerReadable = ledger.readable;
+        if (ledger.readable && ledger.submittedAt !== null) {
+            if (outstandingPrompt(data, ledger.submittedAt)) {
+                const heldMs = Date.now() - startTime;
+                if (heldMs < PENDING_PROMPT_HOLD_MS) {
+                    console.error(`Waiting: ${worktreeId} is at its composer, but the newest prompt sent to it ` +
+                        `has no reported end (sentAt=${new Date(ledger.submittedAt).toISOString()}, ` +
+                        `lastStopEventAt=${data.lastStopEventAt ?? 'none'}, ${describeTurnClose(data)}). ` +
+                        'Not reporting completion: the agent has not started this turn yet.');
+                    return { kind: 'wait' };
+                }
+                console.error(`Note: ${worktreeId} has been at its composer for ` +
+                    `${Math.round(heldMs / 1000)}s with the newest prompt still unreported by its ` +
+                    'agent. Its hooks are not answering; completing on the frame alone.');
+            }
+            else {
+                answeredNewestPrompt = true;
+            }
+        }
+    }
+    return { kind: 'next', answeredNewestPrompt };
+}
+/** Last stage of a `ready` frame: the completion line with its basis. Exit 0. */
+function completionStage(poll, state, answeredNewestPrompt, selfResumeSuffix) {
+    const { worktreeId } = poll;
+    // `hook_stop` on both branches that have one, and they are the same
+    // statement made from two records: the agent reported the end of the
+    // turn this wait is about. `scraper_ready` keeps its documented meaning
+    // — "the screen said so and nothing corroborated it" — which is now
+    // exactly the set of cases that reach it.
+    const basis = state.turnStartedAt !== null || answeredNewestPrompt
+        ? COMPLETION_BASIS.HOOK_STOP
+        : COMPLETION_BASIS.SCRAPER_READY;
+    console.error(`Completed: ${worktreeId} (basis=${basis}${selfResumeSuffix()})`);
+    return exitWith({ exitCode: types_1.WaitExitCode.SUCCESS });
+}
+/**
+ * Stage: the agent is back at its composer on a frame that was understood. Asks
+ * the stages of a `ready` frame in order; the first that applies decides.
+ */
+async function readyStage(poll, state, data, selfResumeStopAt, selfResumeSuffix) {
+    // Issue #1708 narrowed Path B: `ready` is only a completion when the frame
+    // was actually understood. A structured `hook_stop` over an unreadable
+    // pane is the degraded form of an overlay nobody could parse (see the note
+    // above), and reporting it as `Completed` is how a stalled worker gets
+    // merged. Path A is untouched — a session that went away really is
+    // finished, and carries no flag anyway.
+    if (data.sessionStatus === 'ready' && data.isUnclassifiedActive !== true) {
+        const faultOutcome = upstreamFaultStage(poll, data);
+        if (faultOutcome.kind !== 'next')
+            return faultOutcome;
+        const turnOutcome = unsettledTurnStage(poll, state, data);
+        if (turnOutcome.kind !== 'next')
+            return turnOutcome;
+        const holdOutcome = selfResumeHoldStage(poll, state, data, selfResumeStopAt);
+        if (holdOutcome.kind !== 'next')
+            return holdOutcome;
+        const ledgerOutcome = await promptLedgerStage(poll, state, data);
+        if (ledgerOutcome.kind !== 'next')
+            return ledgerOutcome;
+        return completionStage(poll, state, ledgerOutcome.answeredNewestPrompt, selfResumeSuffix);
+    }
+    return { kind: 'next' };
+}
 /**
  * Poll a single worktree until completion, prompt, or timeout.
  *
@@ -676,81 +1225,36 @@ function nextPollWithinDeadlines(options, startTime, lastActivityTime, now) {
  */
 async function pollWorktree(client, worktreeId, options) {
     const startTime = Date.now();
-    let lastActivityTime = Date.now();
-    let lastContent = '';
-    /**
-     * Issue #1628: whether this wait ever saw the session alive. `!isRunning` on the
-     * FIRST poll is "there is nothing here to wait for", not "the agent finished" —
-     * reporting SUCCESS for it is how a wait on a worktree whose agent never started
-     * (wrong tool, wrong instance, session never created) came back `Completed` in
-     * milliseconds and handed a `passed` verdict to whatever ran next.
-     */
-    let everRunning = false;
-    /**
-     * Epoch ms of the first poll in the current unbroken run of
-     * `isUnclassifiedActive === true`, or null when the last poll cleared it
-     * (Issue #1708).
-     */
-    let unclassifiedSince = null;
-    /**
-     * Epoch ms of the `user_prompt_submit` / `pre_tool_use` / `post_tool_use` this
-     * wait adopted as "the turn I am waiting on", or null when the agent has
-     * reported none (Issue #1839). See {@link adoptTurnStart}.
-     */
-    let turnStartedAt = null;
-    /**
-     * Whether the chat ledger is still worth asking (Issue #1975). Cleared by the
-     * first read that fails, after which this wait judges completion from the
-     * frame alone — the pre-#1975 behaviour — rather than re-reporting the same
-     * unreachable endpoint on every poll.
-     */
-    let promptLedgerReadable = true;
-    /**
-     * Epoch ms of the first poll in the current unbroken run of an agent-mode
-     * prompt the target's Auto-Yes is expected to answer, or null (Issue #2463).
-     * Cleared by the first poll that shows no prompt, so every prompt Auto-Yes
-     * answers gets a window of its own.
-     */
-    let autoYesAnsweringSince = null;
+    const state = {
+        lastActivityTime: Date.now(),
+        lastContent: '',
+        everRunning: false,
+        unclassifiedSince: null,
+        turnStartedAt: null,
+        promptLedgerReadable: true,
+        autoYesAnsweringSince: null,
+        selfResumeHold: null,
+        selfResumeHeldMs: 0,
+        selfResumeHeld: false,
+    };
     const autoYesGraceSeconds = options.autoYesGrace ?? AUTO_YES_GRACE_DEFAULT_SECONDS;
     const autoYesGraceMs = autoYesGraceSeconds * 1000;
-    /**
-     * The self-resume hold in progress: the `stop` it is about, and when this wait
-     * first held on it (CLI clock). Null when none is (Issue #2614).
-     */
-    let selfResumeHold = null;
-    /** Milliseconds spent in self-resume holds that have already ended (Issue #2614). */
-    let selfResumeHeldMs = 0;
-    /** Whether any poll of this wait was held for a self-resume (Issue #2614). */
-    let selfResumeHeld = false;
+    const poll = { client, worktreeId, options, startTime, autoYesGraceSeconds, autoYesGraceMs };
     /**
      * What the completion line adds when this wait held for a self-resume, or ''
      * (Issue #2614). `basis=` keeps its word: the verdict is still the agent's own
      * `Stop`, the hold only decided which one.
      */
     const selfResumeSuffix = () => {
-        if (!selfResumeHeld)
+        if (!state.selfResumeHeld)
             return '';
-        const total = selfResumeHeldMs + (selfResumeHold ? Date.now() - selfResumeHold.since : 0);
+        const total = state.selfResumeHeldMs + (state.selfResumeHold ? Date.now() - state.selfResumeHold.since : 0);
         return `, heldForSelfResume=${Math.round(total / 1000)}s`;
     };
     while (true) {
-        // Check timeout
-        if (options.timeout) {
-            const elapsed = (Date.now() - startTime) / 1000;
-            if (elapsed >= options.timeout) {
-                console.error(`Timeout: ${worktreeId} exceeded ${options.timeout}s`);
-                return { exitCode: types_1.WaitExitCode.TIMEOUT };
-            }
-        }
-        // Check stall-timeout
-        if (options.stallTimeout) {
-            const stallElapsed = (Date.now() - lastActivityTime) / 1000;
-            if (stallElapsed >= options.stallTimeout) {
-                console.error(`Stall timeout: ${worktreeId} no output for ${options.stallTimeout}s`);
-                return { exitCode: types_1.WaitExitCode.TIMEOUT };
-            }
-        }
+        const deadlineOutcome = deadlineStage(poll, state);
+        if (deadlineOutcome.kind === 'exit')
+            return deadlineOutcome.result;
         try {
             // Issue #868: scope polling to a specific agent instance when provided.
             const path = options.instance
@@ -758,12 +1262,12 @@ async function pollWorktree(client, worktreeId, options) {
                 : `/api/worktrees/${worktreeId}/current-output`;
             const data = await client.get(path);
             // Track content changes for stall detection
-            if (data.content !== lastContent) {
-                lastContent = data.content;
-                lastActivityTime = Date.now();
+            if (data.content !== state.lastContent) {
+                state.lastContent = data.content;
+                state.lastActivityTime = Date.now();
             }
             if (data.isRunning) {
-                everRunning = true;
+                state.everRunning = true;
             }
             // Issue #3179: the agent is still launching. Work in progress, so keep
             // polling: no prompt or selection list is read off the launch's frame,
@@ -772,377 +1276,65 @@ async function pollWorktree(client, worktreeId, options) {
             // launch that then fails leaves no session, which is NOT_STARTED, not a
             // completion. The server bounds the launch, so this cannot hold forever.
             if (typeof data.startingSince === 'number') {
-                unclassifiedSince = null;
+                state.unclassifiedSince = null;
                 await sleep(POLL_INTERVAL_MS);
                 continue;
             }
             // Issue #1839: done before any exit path so the turn is adopted even on a
             // poll that ends in a prompt — the same turn is still open when the human
             // answers and `--on-prompt human` resumes polling.
-            turnStartedAt = adoptTurnStart(data, startTime, turnStartedAt);
+            state.turnStartedAt = adoptTurnStart(data, startTime, state.turnStartedAt);
             // Issue #2614: a self-resume hold is about one `stop`, and ends the first
             // time that `stop` is no longer the newest word — the agent woke (a
             // turn-opening event) or stopped again. Checked on every poll, ahead of
             // every exit, because the wake usually lands on a `running` frame that
             // never reaches the hold itself.
             const selfResumeStopAt = pendingSelfResumeStop(data);
-            if (selfResumeHold !== null && selfResumeHold.stopAt !== selfResumeStopAt) {
-                const heldMs = Date.now() - selfResumeHold.since;
-                selfResumeHeldMs += heldMs;
-                selfResumeHold = null;
+            if (state.selfResumeHold !== null && state.selfResumeHold.stopAt !== selfResumeStopAt) {
+                const heldMs = Date.now() - state.selfResumeHold.since;
+                state.selfResumeHeldMs += heldMs;
+                state.selfResumeHold = null;
                 console.error(`Note: ${worktreeId} has moved past the stop it said it would resume from ` +
                     `(held ${Math.round(heldMs / 1000)}s); judging its current state.`);
             }
-            // Prompt detected
-            if (data.isPromptWaiting && data.promptData) {
-                // Issue #1699: report a policy suppression on both exits — the human one
-                // keeps polling and would otherwise say nothing about why nobody
-                // answered, and the agent one is read by pipelines that never see stderr.
-                const suppressed = activeSuppression(data, Date.now());
-                // [DR1-03] Prompt detection exit code
-                if (options.onPrompt === 'human') {
-                    // Block and continue polling - user handles prompt manually
-                    console.error(`Prompt detected on ${worktreeId}. Waiting for human response...`);
-                    if (suppressed) {
-                        console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
-                    }
-                    await sleep(POLL_INTERVAL_MS);
-                    continue;
-                }
-                // Issue #2463: the one case `decidePromptPush()` stays quiet about —
-                // Auto-Yes is on and has not withheld this answer — is a prompt Auto-Yes
-                // is about to answer, and exit 10 there hands a delegation back to a
-                // human for a dialog nobody had to see. Hold it for the grace window; a
-                // poll that shows no prompt ends the hold below and completion is judged
-                // as usual. A withheld answer (`suppressed`) and Auto-Yes being off are
-                // the gate's other two branches and still exit 10 at once.
-                if (!suppressed && data.autoYes?.enabled === true && autoYesGraceMs > 0) {
-                    const now = Date.now();
-                    if (autoYesAnsweringSince === null) {
-                        autoYesAnsweringSince = now;
-                        // stderr only: stdout is the exit-10 payload and nothing else.
-                        console.error("Prompt detected; the target's Auto-Yes is answering, waiting up to " +
-                            `${autoYesGraceSeconds}s… (${worktreeId})`);
-                    }
-                    const heldMs = now - autoYesAnsweringSince;
-                    if (heldMs < autoYesGraceMs &&
-                        nextPollWithinDeadlines(options, startTime, lastActivityTime, now)) {
-                        await sleep(POLL_INTERVAL_MS);
-                        continue;
-                    }
-                    console.error(heldMs < autoYesGraceMs
-                        ? `Note: the prompt on ${worktreeId} is still open after ${Math.round(heldMs / 1000)}s ` +
-                            'under Auto-Yes, and the next poll would pass --timeout/--stall-timeout; reporting it now.'
-                        : `Note: the target's Auto-Yes did not answer the prompt on ${worktreeId} within ` +
-                            `${autoYesGraceSeconds}s; reporting it.`);
-                }
-                else if (autoYesAnsweringSince !== null && !suppressed) {
-                    console.error(`Note: Auto-Yes is no longer enabled on ${worktreeId}; reporting the prompt.`);
-                }
-                // Default (agent mode): output prompt info and exit 10
-                //
-                // Issue #1898: the degraded `unclassified` payload carries no `options`
-                // — by construction, because nothing parsed the screen — but for a
-                // source whose approvals are answered by decision id it does carry
-                // `decisionOptions`, which ARE answerable (`respond <id> 1`). Reporting
-                // an empty list there told the caller a dialog was open and gave it
-                // nothing to do about it, which is the whole of #1898-3 seen from the
-                // pipeline's side.
-                const promptOptions = data.promptData.options?.length
-                    ? data.promptData.options
-                    : (data.promptData.decisionOptions ?? []);
-                const promptOutput = {
-                    worktreeId,
-                    cliToolId: data.cliToolId || 'claude',
-                    type: data.promptData.type || 'unknown',
-                    question: data.promptData.question || '',
-                    options: promptOptions,
-                    status: data.promptData.status || 'pending',
-                    ...(data.promptData.approvalTarget !== undefined && {
-                        approvalTarget: data.promptData.approvalTarget,
-                    }),
-                    ...(suppressed && {
-                        autoYesSuppression: {
-                            reason: suppressed.suppression.reason,
-                            mode: suppressed.suppression.mode,
-                            promptType: suppressed.suppression.promptType,
-                            ...(suppressed.suppression.pattern !== undefined && {
-                                pattern: suppressed.suppression.pattern,
-                            }),
-                            ageSeconds: suppressed.ageSeconds,
-                        },
-                    }),
-                };
-                if (suppressed) {
-                    console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
-                }
-                return { exitCode: types_1.WaitExitCode.PROMPT_DETECTED, output: promptOutput };
+            const promptOutcome = promptStage(poll, state, data);
+            if (promptOutcome.kind === 'exit')
+                return promptOutcome.result;
+            if (promptOutcome.kind === 'wait') {
+                await sleep(POLL_INTERVAL_MS);
+                continue;
             }
             // Issue #2463: the prompt the hold was waiting on has gone. Who answered it
             // is not on the wire — Auto-Yes, or a human at the pane — so the line says
             // only that it cleared; what the agent does next is for the checks below.
-            if (autoYesAnsweringSince !== null) {
+            if (state.autoYesAnsweringSince !== null) {
                 console.error(`Prompt on ${worktreeId} cleared after ` +
-                    `${Math.round((Date.now() - autoYesAnsweringSince) / 1000)}s; judging completion as usual.`);
-                autoYesAnsweringSince = null;
-            }
-            // Issue #1628: an arrow-key menu is the agent blocked on a human just as much
-            // as a numbered prompt is, but it is published with isPromptWaiting=false so
-            // the UI can render NavigationButtons instead of PromptPanel. Treat it as a
-            // prompt here — otherwise `wait` polls a stopped agent until --timeout.
-            if (data.isSelectionListActive) {
-                if (options.onPrompt === 'human') {
-                    console.error(`Selection list active on ${worktreeId} (${data.sessionStatusReason ?? 'selection_list'}). ` +
-                        'Waiting for human response...');
-                    // Issue #1699: the poller parses frames status-detector publishes as
-                    // selection lists, so a policy can be the reason this one is stuck too.
-                    const suppressed = activeSuppression(data, Date.now());
-                    if (suppressed) {
-                        console.error(formatSuppressionNotice(suppressed.suppression, suppressed.ageSeconds));
-                    }
-                    await sleep(POLL_INTERVAL_MS);
-                    continue;
-                }
-                return {
-                    exitCode: types_1.WaitExitCode.PROMPT_DETECTED,
-                    output: {
-                        worktreeId,
-                        cliToolId: data.cliToolId || 'claude',
-                        type: SELECTION_LIST_PROMPT_TYPE,
-                        question: data.sessionStatusReason ?? SELECTION_LIST_PROMPT_TYPE,
-                        options: [],
-                        status: 'pending',
-                    },
-                };
-            }
-            // Issue #1708: the frame is interactive but nothing could parse it. The
-            // detection layer is the single entry point every downstream safeguard
-            // hangs off, so a frame that slips past it disables Auto-Yes, the exit-10
-            // handoff and the contract's autoYes policy all at once — and `wait` used
-            // to burn its whole --timeout without ever mentioning it. Treat a
-            // PERSISTENT unclassified frame as a stop reason of its own.
-            //
-            // The dwell deliberately spans ALL THREE states that raise this flag, and
-            // the completion check below is suppressed while it is up. That is the
-            // whole point, and it is worth spelling out because the obvious reading is
-            // the wrong one. The server's definition (`isUnclassifiedFrame` in
-            // `src/lib/session/status-evidence.ts`, restated there by Issue #2011):
-            //
-            //   isUnclassifiedActive =
-            //     running && (default | unknown_frame | no_recent_output)
-            //
-            // `no_recent_output` is there because a static unrecognised overlay
-            // DEGRADES into it — once the Auto-Yes poller stamps
-            // lastServerResponseTimestamp, a frame that stopped changing flips from
-            // `running`/`default` after STALE_OUTPUT_THRESHOLD_MS (5s). `unknown_frame`
-            // is the same floor for a tool that opts out of the generic composer check
-            // (copilot, opencode), and says "this tool's own rules looked and read
-            // nothing". Both arrive about twelve times faster than this dwell. Letting
-            // the completion check claim one turned a stalled worker into `Completed`,
-            // which is worse than the timeout Issue #1708 complained about: exit 124
-            // stops a pipeline, exit 0 lets it merge. Measured before this guard: two
-            // unclassified polls followed by the degraded state returned SUCCESS.
-            //
-            // What is deliberately NOT in the set is `ready`/`input_prompt` with
-            // `statusEvidence: 'none'` — the agent back at its composer on a frame no
-            // tool-specific idle rule could vouch for. That frame WAS classified; what
-            // is missing is positive proof, which is a different question and §4 D1's
-            // to answer. Issue #1927 folded the two together and every idle Claude pane
-            // stopped completing (#2011). Whether `wait` should hold for evidence as
-            // well as classification is open, and any answer belongs in the same place
-            // as the rollout that produces the evidence — not here.
-            if (data.isUnclassifiedActive === true) {
-                if (unclassifiedSince === null)
-                    unclassifiedSince = Date.now();
-                const dwellMs = Date.now() - unclassifiedSince;
-                if (dwellMs >= UNCLASSIFIED_DWELL_MS) {
-                    const dwellSeconds = Math.round(dwellMs / 1000);
-                    const question = `Unclassified interactive frame on ${worktreeId} for ${dwellSeconds}s ` +
-                        `(status=${data.sessionStatus ?? 'unknown'}/${data.sessionStatusReason ?? 'unknown'}). ` +
-                        `The detection layer could not parse it; inspect the raw pane with ` +
-                        `\`commandmate capture ${worktreeId} --pane\`.` +
-                        // Issue #2095: the sidebar is exactly this frame's reason, and the
-                        // one recovery is a keystroke in the pane. Riding the message keeps
-                        // the exit-code table (10, `type: unclassified`) unchanged for every
-                        // caller that already branches on it.
-                        describePaneObstruction(data);
-                    if (options.onPrompt === 'human') {
-                        console.error(question);
-                        console.error('Waiting for human response...');
-                        await sleep(POLL_INTERVAL_MS);
-                        continue;
-                    }
-                    console.error(question);
-                    return {
-                        exitCode: types_1.WaitExitCode.PROMPT_DETECTED,
-                        output: {
-                            worktreeId,
-                            cliToolId: data.cliToolId || 'claude',
-                            type: UNCLASSIFIED_PROMPT_TYPE,
-                            question,
-                            options: [],
-                            status: 'pending',
-                        },
-                    };
-                }
-            }
-            else {
-                unclassifiedSince = null;
+                    `${Math.round((Date.now() - state.autoYesAnsweringSince) / 1000)}s; judging completion as usual.`);
+                state.autoYesAnsweringSince = null;
             }
-            // Completion check [DR1-04]:
-            // Path A: the tmux session went away after we had seen it alive — the agent
-            //         finished and its session was stopped.
-            // Path B: agent completed task (sessionStatus === 'ready', input prompt detected)
-            // Both indicate "no more work in progress" from wait command's perspective.
-            //
-            // Issue #1628 narrowed Path A: a session that was NEVER seen running is
-            // "nothing to wait for" (NOT_STARTED), not a completion. See `everRunning`.
-            if (!data.isRunning && !everRunning) {
-                console.error(`Not started: ${worktreeId} has no running ${data.cliToolId ?? 'agent'} session` +
-                    `${options.instance ? ` for instance ${options.instance}` : ''}` +
-                    // Issue #1884: name the stage that chose the agent above. `wait` has
-                    // no --agent to correct a mis-resolution with, so "no running claude
-                    // session for instance opencode" was the entire evidence an operator
-                    // got for a live agent reported as absent. `worktree-default` here
-                    // means the instance is neither in the roster nor named after a
-                    // tool; `client-fallback`, that the server is too old to resolve.
-                    `${data.resolvedBy ? ` (resolvedBy=${data.resolvedBy})` : ''}.`);
-                return { exitCode: types_1.VerifyExitCode.NOT_STARTED };
+            const selectionListOutcome = selectionListStage(poll, data);
+            if (selectionListOutcome.kind === 'exit')
+                return selectionListOutcome.result;
+            if (selectionListOutcome.kind === 'wait') {
+                await sleep(POLL_INTERVAL_MS);
+                continue;
             }
-            // Issue #1708 narrowed Path B: `ready` is only a completion when the frame
-            // was actually understood. A structured `hook_stop` over an unreadable
-            // pane is the degraded form of an overlay nobody could parse (see the note
-            // above), and reporting it as `Completed` is how a stalled worker gets
-            // merged. Path A is untouched — a session that went away really is
-            // finished, and carries no flag anyway.
-            if (!data.isRunning) {
-                console.error(`Completed: ${worktreeId} (basis=${COMPLETION_BASIS.SESSION_GONE}${selfResumeSuffix()})`);
-                return { exitCode: types_1.WaitExitCode.SUCCESS };
+            const unclassifiedOutcome = unclassifiedStage(poll, state, data);
+            if (unclassifiedOutcome.kind === 'exit')
+                return unclassifiedOutcome.result;
+            if (unclassifiedOutcome.kind === 'wait') {
+                await sleep(POLL_INTERVAL_MS);
+                continue;
             }
-            if (data.sessionStatus === 'ready' && data.isUnclassifiedActive !== true) {
-                // Issue #1839: the agent is back at its composer with an upstream
-                // failure on the frame. Checked BEFORE the turn-boundary gate below,
-                // because it is the answer to the question that gate can only ask: the
-                // turn did not end, and this is why. Without it the same session runs
-                // to --timeout and reports 124, which says nothing about the cause.
-                const fault = data.upstreamFault ?? null;
-                if (options.failOnUpstreamFault && fault) {
-                    console.error(`Upstream fault on ${worktreeId}: id=${fault.id} — the agent is back at its ` +
-                        'composer with an upstream API failure on screen, so this turn did not run. ' +
-                        `Matched: ${JSON.stringify(fault.matchedText)}`);
-                    if (fault.id === 'context-limit') {
-                        // A retry into the same session hits the same wall (Issue #3011).
-                        console.error('The session\'s conversation is over the model\'s context limit. Start a fresh ' +
-                            `session and send again: commandmate instances ${worktreeId} kill ` +
-                            `${options.instance ?? '<instance>'}`);
-                    }
-                    return {
-                        exitCode: types_1.WaitExitCode.UPSTREAM_FAULT,
-                        upstreamFault: { id: fault.id, matchedText: fault.matchedText },
-                    };
-                }
-                // Issue #1839: `ready` off the terminal frame is the agent's composer,
-                // not the agent's verdict. Measured 2026-08-20 against a stub upstream
-                // answering 529: Claude returns to the composer ~3 s after the send
-                // having executed nothing, and never sends `Stop`. When this instance's
-                // hooks ARE reporting — the only case in which `turnStartedAt` is
-                // non-null — that missing `Stop` is the difference between "finished"
-                // and "never ran", and it is the only signal that carries it.
-                if (!turnSettled(data, turnStartedAt)) {
-                    console.error(`Waiting: ${worktreeId} is back at its composer, but its agent has not reported ` +
-                        `the end of this turn (turnStartedAt=${turnStartedAt}, ` +
-                        `lastStopEventAt=${data.lastStopEventAt ?? 'none'}, ${describeTurnClose(data)}). ` +
-                        'Not reporting completion; inspect with ' +
-                        `\`commandmate capture ${worktreeId} --json\`.`);
-                    await sleep(POLL_INTERVAL_MS);
-                    continue;
-                }
-                // Issue #2614: the turn did end — the agent said so — but it also said
-                // that work of its own is still running in the background (a `schedule`
-                // timer, a backgrounded command), and that work wakes it with nobody
-                // typing anything. Measured 2026-09-17 on antigravity 1.2.4: four such
-                // stops ~58 s before each self-wake, and the first one was reported as
-                // `Completed (basis=hook_stop)` and verified five minutes before the
-                // work was done. So this `stop` is held until it is no longer the newest
-                // word (see `selfResumeStopAt` above), or until the bound.
-                //
-                // The bound is measured from whichever is further along: the `stop`
-                // itself (server clock — a negative age is skew, and the max discards
-                // it) or this wait's first sight of it. A session that said so hours ago
-                // and never woke is not held again.
-                if (selfResumeStopAt !== null) {
-                    const now = Date.now();
-                    if (selfResumeHold === null)
-                        selfResumeHold = { stopAt: selfResumeStopAt, since: now };
-                    const heldMs = now - selfResumeHold.since;
-                    const elapsedMs = Math.max(heldMs, now - selfResumeStopAt);
-                    if (elapsedMs < exports.SELF_RESUME_HOLD_MS) {
-                        selfResumeHeld = true;
-                        console.error(`Waiting: ${worktreeId} ended its turn with background work still running ` +
-                            `(stoppedAt=${new Date(selfResumeStopAt).toISOString()}, ` +
-                            `lastEventDetail=${exports.SELF_RESUME_PENDING_DETAIL}, ${describeTurnClose(data)}); ` +
-                            'it resumes by itself when that work finishes. Not reporting completion ' +
-                            `(held ${Math.round(heldMs / 1000)}s, at most ${exports.SELF_RESUME_HOLD_MS / 1000}s ` +
-                            'after the stop).');
-                        await sleep(POLL_INTERVAL_MS);
-                        continue;
-                    }
-                    console.error(`Note: ${worktreeId} said at its stop ${Math.round(elapsedMs / 1000)}s ` +
-                        'ago that background work was still running, and has not resumed since; ' +
-                        'completing on that stop.');
-                }
-                // Issue #1975: the same frame, one question further back. #1839's gate
-                // above can only fire once a turn has been ADOPTED, and `send` leaves a
-                // window ~1s wide in which nothing has been: the newest structured event
-                // is still the previous turn's `stop`, so `adoptTurnStart` takes nothing,
-                // `turnSettled` reads null as "settled", and the composer the agent has
-                // not touched yet is read as the composer it came back to. Measured
-                // 2026-08-22 against copilot 1.0.80 on an isolated server: 3 of 5
-                // send-then-wait runs came back in ~0.3s with `basis=scraper_ready` and
-                // no artefact on disk.
-                //
-                // So ask the ledger instead of the clock: has this instance been handed
-                // a prompt that the agent has not reported the end of? See
-                // {@link outstandingPrompt} for why that comparison is the one that
-                // separates "not started" from "finished", and
-                // {@link reportsTurnBoundaries} for why a tool that posts no hooks never
-                // reaches it.
-                let answeredNewestPrompt = false;
-                if (turnStartedAt === null && promptLedgerReadable && reportsTurnBoundaries(data)) {
-                    const ledger = await readNewestPromptAt(client, worktreeId, options, data);
-                    // One notice, then stop asking: a ledger that failed once will fail
-                    // every poll, and the point of degrading is to stop paying for it.
-                    promptLedgerReadable = ledger.readable;
-                    if (ledger.readable && ledger.submittedAt !== null) {
-                        if (outstandingPrompt(data, ledger.submittedAt)) {
-                            const heldMs = Date.now() - startTime;
-                            if (heldMs < PENDING_PROMPT_HOLD_MS) {
-                                console.error(`Waiting: ${worktreeId} is at its composer, but the newest prompt sent to it ` +
-                                    `has no reported end (sentAt=${new Date(ledger.submittedAt).toISOString()}, ` +
-                                    `lastStopEventAt=${data.lastStopEventAt ?? 'none'}, ${describeTurnClose(data)}). ` +
-                                    'Not reporting completion: the agent has not started this turn yet.');
-                                await sleep(POLL_INTERVAL_MS);
-                                continue;
-                            }
-                            console.error(`Note: ${worktreeId} has been at its composer for ` +
-                                `${Math.round(heldMs / 1000)}s with the newest prompt still unreported by its ` +
-                                'agent. Its hooks are not answering; completing on the frame alone.');
-                        }
-                        else {
-                            answeredNewestPrompt = true;
-                        }
-                    }
-                }
-                // `hook_stop` on both branches that have one, and they are the same
-                // statement made from two records: the agent reported the end of the
-                // turn this wait is about. `scraper_ready` keeps its documented meaning
-                // — "the screen said so and nothing corroborated it" — which is now
-                // exactly the set of cases that reach it.
-                const basis = turnStartedAt !== null || answeredNewestPrompt
-                    ? COMPLETION_BASIS.HOOK_STOP
-                    : COMPLETION_BASIS.SCRAPER_READY;
-                console.error(`Completed: ${worktreeId} (basis=${basis}${selfResumeSuffix()})`);
-                return { exitCode: types_1.WaitExitCode.SUCCESS };
+            const notRunningOutcome = notRunningStage(poll, state, data, selfResumeSuffix);
+            if (notRunningOutcome.kind === 'exit')
+                return notRunningOutcome.result;
+            const readyOutcome = await readyStage(poll, state, data, selfResumeStopAt, selfResumeSuffix);
+            if (readyOutcome.kind === 'exit')
+                return readyOutcome.result;
+            if (readyOutcome.kind === 'wait') {
+                await sleep(POLL_INTERVAL_MS);
+                continue;
             }
             // Progress indicator on stderr [DR1-05]
             console.error(`Waiting: ${worktreeId} (status=${data.sessionStatus}, running=${data.isRunning}, prompt=${data.isPromptWaiting})`);