commandmate 0.49.0 → 0.49.1

package/dist/cli/commands/wait-notices.d.ts

@@ -0,0 +1,87 @@
+/**
+ * wait Command - stderr notices about Auto-Yes and pane obstructions
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+import type { CurrentOutputResponse } from '../types/api-responses';
+/**
+ * The cause sentence to append when the frame carries a pane obstruction, or ''
+ * (Issue #2095).
+ *
+ * Appended rather than substituted, and no exit code moves: the frame is
+ * genuinely unclassified and `wait` was already right to stop on it. What it
+ * could not say before is WHY, which left an operator with `capture --pane` and
+ * a screenful of box drawing to work it out from.
+ *
+ * Empty for a server too old to publish the field, which is the same output
+ * `wait` produced before this Issue.
+ */
+export declare function describePaneObstruction(data: CurrentOutputResponse): string;
+type LastSuppression = NonNullable<NonNullable<CurrentOutputResponse['autoYes']>['lastSuppression']>;
+/**
+ * The suppression currently blocking this session, or null.
+ *
+ * Issue #3863: with the Auto-Yes answer mode in effect (`autoYesAnswerMode`)
+ * when the server publishes one — what `question-left-to-human` and
+ * `recommended-option-unidentified` depend on.
+ */
+export declare function activeSuppression(data: CurrentOutputResponse, now: number): {
+    suppression: LastSuppression;
+    ageSeconds: number;
+    answerMode?: string;
+} | null;
+/**
+ * One stderr line naming what is holding this prompt (Issue #1699).
+ *
+ * `wait` used to print only "Waiting for human response...", which reads the
+ * same whether a human was always going to answer or whether Auto-Yes silently
+ * refused to. That ambiguity is what let a deny pattern matching a finished turn
+ * stall two workers unnoticed; the pattern and the reason code belong on screen.
+ *
+ * Issue #1843: the cause is chosen per reason rather than asserted. `reason=` is
+ * in the payload either way, so the prefix is the only part that can lie — and it
+ * did, for every non-contract suppression.
+ */
+export declare function formatSuppressionNotice(suppression: LastSuppression, ageSeconds: number, answerMode?: string): string;
+/**
+ * One stderr line saying Auto-Yes is off on this instance because the server
+ * restarted (Issue #3730), or null.
+ *
+ * Only words: the prompt was going to be reported either way — an instance
+ * whose grant the restart released is an instance with Auto-Yes off, and exit
+ * 10 for it is exactly the hand-back it always was. What this adds is the WHY,
+ * so a delegating agent re-enables Auto-Yes instead of guessing. A server
+ * older than the reason sends none, and nothing is printed.
+ *
+ * The command it suggests names the instance this wait is about: without
+ * `--instance`, `auto-yes --enable` arms the worktree's default primary, which
+ * for an alias (or a non-default tool) is another instance — the waited-on one
+ * would stay off while a grant went somewhere nobody asked for. The instance is
+ * the resolved `--instance` when one was given, else the CLI tool the server
+ * answered for (a primary's instance ID is its tool ID).
+ *
+ * @param instanceId - The resolved `--instance` of this wait, if any
+ */
+export declare function formatRestartReleaseNotice(worktreeId: string, data: CurrentOutputResponse, instanceId?: string): string | null;
+/**
+ * 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.
+ */
+export declare function formatEnterFallbackNotice(data: CurrentOutputResponse, now: number): string | null;
+/**
+ * Issue #3821: the server's own word that Auto-Yes left this prompt to a human
+ * (`autoYesDecision.state === 'withheld'`) — `server-poller-inactive` when no
+ * poller runs for the instance, or a stop the suppression record does not
+ * carry. Read only when the server publishes the field; an older one leaves
+ * `wait` holding as before.
+ */
+export declare function decisionWithheldReason(data: CurrentOutputResponse): string | null;
+export {};
+//# sourceMappingURL=wait-notices.d.ts.map

package/dist/cli/commands/wait-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-notices.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-notices.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAA4B,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAe9F;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAS3E;AAmCD,KAAK,eAAe,GAAG,WAAW,CAChC,WAAW,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CACjE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,MAAM,GACV;IAAE,WAAW,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoBlF;AA+GD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAerH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,qBAAqB,EAC3B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAajG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAIjF"}

package/dist/cli/commands/wait-notices.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * wait Command - stderr notices about Auto-Yes and pane obstructions
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describePaneObstruction = describePaneObstruction;
+exports.activeSuppression = activeSuppression;
+exports.formatSuppressionNotice = formatSuppressionNotice;
+exports.formatRestartReleaseNotice = formatRestartReleaseNotice;
+exports.formatEnterFallbackNotice = formatEnterFallbackNotice;
+exports.decisionWithheldReason = decisionWithheldReason;
+/**
+ * The keystroke that closes opencode's sidebar, in opencode's own notation
+ * (Issue #2095).
+ *
+ * A local copy of `OPENCODE_SIDEBAR_RECOVERY_CHORD` from
+ * `src/lib/detection/opencode-pane-obstruction.ts` and not an import: the CLI
+ * builds with `"paths": {}` (tsconfig.cli.json) and cannot reach `@/lib` at all,
+ * which is why `api-responses.ts` mirrors payload shapes rather than importing
+ * them. Taken from opencode's own keybind table, which its `ctrl+p` palette
+ * prints as `Show sidebar   ctrl+x b`.
+ */
+const OPENCODE_SIDEBAR_RECOVERY_CHORD = 'ctrl+x b';
+/**
+ * The cause sentence to append when the frame carries a pane obstruction, or ''
+ * (Issue #2095).
+ *
+ * Appended rather than substituted, and no exit code moves: the frame is
+ * genuinely unclassified and `wait` was already right to stop on it. What it
+ * could not say before is WHY, which left an operator with `capture --pane` and
+ * a screenful of box drawing to work it out from.
+ *
+ * Empty for a server too old to publish the field, which is the same output
+ * `wait` produced before this Issue.
+ */
+function describePaneObstruction(data) {
+    const obstruction = data.paneObstruction;
+    if (!obstruction)
+        return '';
+    return (` Cause: paneObstruction=${obstruction.id} — a second column is sharing rows with the ` +
+        `transcript (it reads ${JSON.stringify(obstruction.matchedText)}), which covers the marker ` +
+        `that ends a turn. Press \`${OPENCODE_SIDEBAR_RECOVERY_CHORD}\` in the pane to close ` +
+        `opencode's sidebar.`);
+}
+/**
+ * How recent `autoYes.lastSuppression` must be to be reported as the reason this
+ * wait is blocked (Issue #1699).
+ *
+ * The record is refreshed on every poll for as long as the suppressed prompt is
+ * on screen, so a fresh timestamp means "this is happening now" while an old one
+ * is a historical suppression of some earlier prompt. The window is generous
+ * against the server's own poll interval — being a few seconds late with a true
+ * report beats staying silent, which is the failure this exists to fix.
+ *
+ * Issue #2463 reads the same window as "the policy withheld THIS prompt", which
+ * is what ends the Auto-Yes hold at once. `current-output` publishes no start
+ * time for a scraped prompt, so the push gate's `suppression.at >= waitingSince`
+ * (`src/lib/push/prompt-push-gate.ts`) cannot be computed here; a record that is
+ * still being re-stamped is the CLI's reading of it. Using one window for both
+ * keeps the hold and the payload in agreement: an exit 10 carries
+ * `autoYesSuppression` exactly when the hold judged the answer withheld. The
+ * error runs towards reporting — a withheld answer to an earlier prompt, under a
+ * minute old, still ends the hold, which is the pre-#2463 exit rather than a
+ * new failure.
+ *
+ * Issue #3798: a server that names the waiting episodes does what the push gate
+ * does — the record's `episodeId` against the payload's
+ * `autoYes.waitingEpisodeId`, which decide when both are present: another id
+ * (or no wait open) is a record of an earlier wait, however recent; the same
+ * id is this wait's. Either one missing (an older server, a record written
+ * before any wait was open), this window decides as before. Whichever
+ * decides, a record the server marks `lastSuppressionAnswered` — Auto-Yes
+ * answered the open wait after it was written — is history, not this wait's
+ * reason, as the push gate reads it: the hold goes on.
+ */
+const SUPPRESSION_FRESH_MS = 60_000;
+/**
+ * The suppression currently blocking this session, or null.
+ *
+ * Issue #3863: with the Auto-Yes answer mode in effect (`autoYesAnswerMode`)
+ * when the server publishes one — what `question-left-to-human` and
+ * `recommended-option-unidentified` depend on.
+ */
+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;
+    const ageMs = now - suppression.at;
+    const waitId = data.autoYes?.waitingEpisodeId;
+    if (suppression.episodeId !== undefined && waitId !== undefined) {
+        if (suppression.episodeId !== waitId)
+            return null;
+    }
+    else if (ageMs > SUPPRESSION_FRESH_MS) {
+        // A negative age is clock skew between the CLI and the server, not staleness.
+        return null;
+    }
+    if (data.autoYes?.lastSuppressionAnswered === true)
+        return null;
+    const answerMode = data.autoYesAnswerMode;
+    return {
+        suppression,
+        ageSeconds: Math.max(0, Math.round(ageMs / 1000)),
+        ...(answerMode !== undefined ? { answerMode } : {}),
+    };
+}
+/** The wording for the four reasons a contract's `autoYes` block really authors. */
+const CONTRACT_POLICY_CAUSE = 'by contract policy';
+/**
+ * What withheld the answer, in the words `wait` puts on stderr (Issue #1843).
+ *
+ * A Record over the whole reason union rather than one fixed phrase: adding a
+ * reason to {@link AutoYesSuppressionReason} without deciding what `wait` should
+ * say about it is a compile error here, which is the point. Until #1843 the
+ * notice hard-coded "by contract policy" for every reason, so #1829's
+ * `agent-launch-dialog` — a product-side decision the poller makes with no
+ * contract in sight (`suppressIfNotOursToAnswer` in
+ * `src/lib/polling/auto-yes-prompt-suppression.ts`: codex's lifecycle dialogs,
+ * gemini's folder trust since #3776 and copilot's since #3790) — sent operators
+ * of contract-less worktrees hunting for a `denyPatterns` entry that did not
+ * exist.
+ *
+ * The three sites that record a suppression are covered: the poller's launch-dialog
+ * branch (`agent-launch-dialog`), the poller's policy branch and
+ * `lib/hooks/permission-decision-service.ts` (both the four `evaluatePolicyAgainstTexts`
+ * verdicts, which is why those four keep the pre-#1843 wording exactly), and
+ * the poller's stopped-answer branch (`partial-answer`, Issue #3706 / #3713),
+ * and the poller's agy trust-screen branch (`startup-trust-unhandled`, Issue #3757),
+ * and the poller's question confirm-page branch (`question-confirm-page`, Issue #3748),
+ * and the poller's question branch (`question-left-to-human`, Issue #3822),
+ * and the resolver's permission-row reading (`allow-once-unidentified`, Issue #3822),
+ * and the resolver's choice of a question's recommended option
+ * (`recommended-option-unidentified`, Issue #3863),
+ * and the poller's agy receipt-gate branch (`no-hook-receipt`, Issue #3767),
+ * and a contract lookup that failed on either of the policy paths
+ * (`policy-lookup-failed`, Issue #3822).
+ */
+const SUPPRESSION_CAUSE = {
+    'mode-off': CONTRACT_POLICY_CAUSE,
+    'deny-pattern': CONTRACT_POLICY_CAUSE,
+    'deny-pattern-unusable': CONTRACT_POLICY_CAUSE,
+    'type-not-allowed': CONTRACT_POLICY_CAUSE,
+    // Issue #3822. Not "by contract policy": the contract could not be read at
+    // all, so nothing it says was applied. Withheld rather than answered, since
+    // the contract may state `off`; it clears once the server reads it again.
+    'policy-lookup-failed': 'because the server could not read the execution contract (the database lookup failed), so Auto-Yes does not answer until it can; check the server log for policy-lookup-failed',
+    // Issue #3790: after the launch window the poller still leaves copilot's and
+    // gemini's trust dialogs alone when the cursor is not on the safe row, and
+    // nobody else answers them then.
+    'agent-launch-dialog': "while the agent's launch dialog was on screen; if it stays after the launch (copilot's cursor on 2. or 3., gemini's not on 1. Trust folder), answer it at the pane",
+    // Issue #1924. Deliberately not "by contract policy": no contract was
+    // consulted. The frame looked like a numbered list to the generic estimator
+    // and like prose to the tool's own detector, and an operator who reads this
+    // should go and look at the pane rather than at `denyPatterns`.
+    'unclassified-frame': 'because no tool-specific dialog detector recognised the frame',
+    // Issue #3713 (#3706's reason). Not "by contract policy" either: an earlier
+    // Auto-Yes answer was stopped with some of its keys already in the input, and
+    // typing it again would append to them, so the prompt waits for a human.
+    // Issue #3880: or a send of it (Auto-Yes's, or a person's that failed) ended
+    // without tmux confirming it, and no key may be known to be there. The #3713
+    // sentence is kept as it was and the other case follows it.
+    'partial-answer': "because an earlier answer left partial input; Auto-Yes is waiting for a human (or that answer's send could not be confirmed, so the input may hold it: check the pane, then answer; an answer that goes through releases the hold)",
+    // Issue #3757. agy's startup folder-trust screen: the launch's to confirm, not
+    // Auto-Yes's, and agy drew it after the launch window had ended.
+    'startup-trust-unhandled': "because agy's startup folder-trust confirmation is the launch's to answer, not Auto-Yes's; the next send confirms it once, or answer it at the pane",
+    // Issue #3748. The AskUserQuestion confirm page (`Submit` / `Cancel`): the
+    // tool's own reader recognised it, and `Submit` commits whatever stands as the
+    // answers, so it waits for a human. Was recorded as `unclassified-frame`,
+    // whose wording above says the opposite (nothing recognised the frame).
+    'question-confirm-page': "because the question's Submit/Cancel confirmation commits the answers as they stand, so Auto-Yes leaves it to a human",
+    // Issue #3822. A question the agent asks the operator (an AskUserQuestion
+    // picker, OpenCode V2's question form): Auto-Yes answers permissions only,
+    // and no contract setting delegates the question. Issue #3863: since the
+    // answer modes, that is the `careful` mode's rule (and OpenCode V2's form
+    // under either mode); `answerMode=` on the line says which mode was on.
+    'question-left-to-human': 'because the agent is asking a question, and Auto-Yes answers permissions only (the careful answer mode, or a question form no mode answers); answer it at the pane (prompt --json, respond), or turn Auto-Yes on with --answer-mode recommended to have it pick the recommended option',
+    // Issue #3822. A permission dialog none of whose rows allows this call only
+    // (each saves a rule, changes the mode or denies), or two of which read so.
+    // Auto-Yes never picks a row that outlives this call, so it waits for a human.
+    'allow-once-unidentified': 'because no single option of the permission dialog allows this call only (the others save a rule, change the permission mode, or deny); Auto-Yes does not pick those, so answer it at the pane (prompt --json, respond)',
+    // Issue #3863. The recommended answer mode answers a question with its one
+    // recommended option (else its default), and could not tell which that is.
+    'recommended-option-unidentified': "because the question's recommended option could not be told (two or more marked recommended, a title it could not tell from its description, a typed-text or multi-select answer); answer it at the pane (prompt --json, respond)",
+    // Issue #3767. agy's approval dialog has no matching hook question (none, too
+    // late, already on screen, or the hook stopped arriving). Not a contract verdict.
+    // Issue #3789: nor one left unused — the last was spent on keys Auto-Yes sent,
+    // and a dialog is still up past the grace — so "no unused question" covers both.
+    'no-hook-receipt': "because there is no unused agy hook permission question for this dialog (none arrived in time, or the last one was spent on keys that did not clear it); answer it yourself (auto-yes --disable, prompt --json, respond --expect-screen) or check hooks.json",
+};
+/**
+ * {@link SUPPRESSION_CAUSE} for a reason that arrived over the wire.
+ *
+ * `reason` is a server-supplied string, so a server newer than this CLI can name
+ * a reason the union does not have. Naming it verbatim is the only honest answer:
+ * quietly folding an unknown reason into "by contract policy" is the same
+ * misattribution #1843 exists to remove, just for a future reason instead of
+ * `agent-launch-dialog`.
+ */
+function suppressionCause(reason) {
+    return Object.prototype.hasOwnProperty.call(SUPPRESSION_CAUSE, reason)
+        ? SUPPRESSION_CAUSE[reason]
+        : `for a reason this CLI does not recognise (${reason})`;
+}
+/**
+ * One stderr line naming what is holding this prompt (Issue #1699).
+ *
+ * `wait` used to print only "Waiting for human response...", which reads the
+ * same whether a human was always going to answer or whether Auto-Yes silently
+ * refused to. That ambiguity is what let a deny pattern matching a finished turn
+ * stall two workers unnoticed; the pattern and the reason code belong on screen.
+ *
+ * Issue #1843: the cause is chosen per reason rather than asserted. `reason=` is
+ * in the payload either way, so the prefix is the only part that can lie — and it
+ * did, for every non-contract suppression.
+ */
+function formatSuppressionNotice(suppression, ageSeconds, answerMode) {
+    const parts = [
+        `reason=${suppression.reason}`,
+        `mode=${suppression.mode ?? 'none'}`,
+        `promptType=${suppression.promptType}`,
+    ];
+    if (suppression.pattern !== undefined) {
+        parts.push(`pattern=${JSON.stringify(suppression.pattern)}`);
+    }
+    // Issue #3863: the Auto-Yes answer mode in effect, when the server says.
+    if (answerMode !== undefined) {
+        parts.push(`answerMode=${answerMode}`);
+    }
+    const cause = suppressionCause(suppression.reason);
+    return `  auto-yes suppressed this prompt ${cause}: ${parts.join(' ')} (${ageSeconds}s ago)`;
+}
+/**
+ * One stderr line saying Auto-Yes is off on this instance because the server
+ * restarted (Issue #3730), or null.
+ *
+ * Only words: the prompt was going to be reported either way — an instance
+ * whose grant the restart released is an instance with Auto-Yes off, and exit
+ * 10 for it is exactly the hand-back it always was. What this adds is the WHY,
+ * so a delegating agent re-enables Auto-Yes instead of guessing. A server
+ * older than the reason sends none, and nothing is printed.
+ *
+ * The command it suggests names the instance this wait is about: without
+ * `--instance`, `auto-yes --enable` arms the worktree's default primary, which
+ * for an alias (or a non-default tool) is another instance — the waited-on one
+ * would stay off while a grant went somewhere nobody asked for. The instance is
+ * the resolved `--instance` when one was given, else the CLI tool the server
+ * answered for (a primary's instance ID is its tool ID).
+ *
+ * @param instanceId - The resolved `--instance` of this wait, if any
+ */
+function formatRestartReleaseNotice(worktreeId, data, instanceId) {
+    if (data.autoYes?.enabled !== false || data.autoYes.stopReason !== 'server-restart')
+        return null;
+    const target = instanceId ?? data.cliToolId;
+    const command = `commandmate auto-yes ${worktreeId} --enable${target ? ` --instance ${target}` : ''}`;
+    return `  auto-yes was released by a server restart on ${worktreeId} (it is not turned back on ` +
+        `automatically); re-enable it with \`${command}\` if this session should keep answering.`;
+}
+/**
+ * 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}`;
+}
+/**
+ * Issue #3821: the server's own word that Auto-Yes left this prompt to a human
+ * (`autoYesDecision.state === 'withheld'`) — `server-poller-inactive` when no
+ * poller runs for the instance, or a stop the suppression record does not
+ * carry. Read only when the server publishes the field; an older one leaves
+ * `wait` holding as before.
+ */
+function decisionWithheldReason(data) {
+    const decision = data.autoYesDecision;
+    if (decision?.state !== 'withheld')
+        return null;
+    return decision.reason ?? 'unknown';
+}

package/dist/cli/commands/wait-poll-bookkeeping.d.ts

@@ -0,0 +1,15 @@
+/**
+ * wait Command - what pollWorktree records off each frame before its stages judge it
+ * Issue #3966: split out of pollWorktree to bring its complexity under 25.
+ */
+import type { CurrentOutputResponse } from '../types/api-responses';
+import type { PollState, PollWorktreeOptions } from './wait-poll-state';
+/** Stall detection and `everRunning` off one frame. */
+export declare function trackPollActivity(state: PollState, data: CurrentOutputResponse): void;
+/** Adopt the turn this frame names and tell the caller's turn callbacks. */
+export declare function adoptAndPublishTurn(state: PollState, data: CurrentOutputResponse, startTime: number, options: PollWorktreeOptions): void;
+/** Drop a self-resume hold whose `stop` is no longer the newest word. */
+export declare function releaseMovedSelfResumeHold(worktreeId: string, state: PollState, selfResumeStopAt: number | null): void;
+/** Say that the prompt an Auto-Yes hold was waiting on has cleared, and end the hold. */
+export declare function noteAutoYesPromptCleared(worktreeId: string, state: PollState): void;
+//# sourceMappingURL=wait-poll-bookkeeping.d.ts.map

package/dist/cli/commands/wait-poll-bookkeeping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-poll-bookkeeping.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-poll-bookkeeping.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxE,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAUrF;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,qBAAqB,EAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,GAC3B,IAAI,CAeN;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,EAChB,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAC9B,IAAI,CAUN;AAED,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAQnF"}

package/dist/cli/commands/wait-poll-bookkeeping.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * wait Command - what pollWorktree records off each frame before its stages judge it
+ * Issue #3966: split out of pollWorktree to bring its complexity under 25.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackPollActivity = trackPollActivity;
+exports.adoptAndPublishTurn = adoptAndPublishTurn;
+exports.releaseMovedSelfResumeHold = releaseMovedSelfResumeHold;
+exports.noteAutoYesPromptCleared = noteAutoYesPromptCleared;
+const wait_turn_boundary_1 = require("./wait-turn-boundary");
+/** Stall detection and `everRunning` off one frame. */
+function trackPollActivity(state, data) {
+    // Track content changes for stall detection
+    if (data.content !== state.lastContent) {
+        state.lastContent = data.content;
+        state.lastActivityTime = Date.now();
+    }
+    if (data.isRunning) {
+        state.everRunning = true;
+    }
+}
+/** Adopt the turn this frame names and tell the caller's turn callbacks. */
+function adoptAndPublishTurn(state, data, startTime, options) {
+    // 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.
+    state.turnStartedAt = (0, wait_turn_boundary_1.adoptTurnStart)(data, startTime, state.turnStartedAt);
+    if (options.onTurnStart) {
+        const published = data.structuredEvents;
+        const closedAt = published?.openedAt != null && published.openedAt === state.turnStartedAt
+            ? published.closedAt ?? null
+            : null;
+        options.onTurnStart(state.turnStartedAt, closedAt);
+    }
+    if (options.onTurnRecord) {
+        options.onTurnRecord(data.structuredEvents?.openedAt ?? null, data.structuredEvents?.closedAt ?? null);
+    }
+}
+/** Drop a self-resume hold whose `stop` is no longer the newest word. */
+function releaseMovedSelfResumeHold(worktreeId, state, selfResumeStopAt) {
+    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.`);
+    }
+}
+/** Say that the prompt an Auto-Yes hold was waiting on has cleared, and end the hold. */
+function noteAutoYesPromptCleared(worktreeId, state) {
+    if (state.autoYesAnsweringSince !== null) {
+        console.error(`Prompt on ${worktreeId} cleared after ` +
+            `${Math.round((Date.now() - state.autoYesAnsweringSince) / 1000)}s; judging completion as usual.`);
+        state.autoYesAnsweringSince = null;
+    }
+}

package/dist/cli/commands/wait-poll-state.d.ts

@@ -0,0 +1,118 @@
+/**
+ * wait Command - what pollWorktree carries between polls and hands its stages
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+import type { WaitOptions } from '../types';
+import type { ApiClient } from '../utils/api-client';
+/**
+ * {@link pollWorktree}'s options: {@link WaitOptions} plus the Auto-Yes grace
+ * (Issue #2463).
+ */
+export interface PollWorktreeOptions extends WaitOptions {
+    /**
+     * `--auto-yes-grace`, in seconds; 0 turns the hold off. Absent means
+     * {@link AUTO_YES_GRACE_DEFAULT_SECONDS}, which is what `ask` gets: it calls
+     * {@link pollWorktree} without the flag.
+     */
+    autoYesGrace?: number;
+    /**
+     * Told the turn this poll has adopted, every poll (Issue #3955).
+     *
+     * `ask` reads it after a completion to tell whether the turn whose end it
+     * waited on had already opened before its own message was sent — the shape
+     * of a second `ask` folded into a turn another sender started. Absent for
+     * `wait`, which has no send to compare against.
+     *
+     * `closedAt` is the server's close time for that turn when this poll's
+     * published turn is the adopted one, else null: a turn that had already
+     * closed before the send is not one the message could have joined.
+     */
+    onTurnStart?: (turnStartedAt: number | null, closedAt: number | null) => void;
+    /**
+     * Told the turn record the server published, every poll, whether or not
+     * this poll adopts it (Issue #3955).
+     *
+     * {@link onTurnStart} only ever names an adopted turn, and adoption drops a
+     * closed turn that opened more than {@link TURN_ADOPTION_GRACE_MS} before the
+     * poll started. A second `ask` that joined such a turn, which then closed
+     * before that ask's first poll, would never hear of it. This is the raw
+     * record, read only: nothing `wait` decides depends on it.
+     */
+    onTurnRecord?: (openedAt: number | null, closedAt: number | null) => void;
+}
+/**
+ * What {@link pollWorktree} carries from one poll to the next: every variable its
+ * loop writes. What the loop only reads stays a `const` there.
+ */
+export interface PollState {
+    lastActivityTime: number;
+    lastContent: string;
+    /**
+     * 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.
+     */
+    everRunning: boolean;
+    /**
+     * Epoch ms of the first poll in the current unbroken run of
+     * `isUnclassifiedActive === true`, or null when the last poll cleared it
+     * (Issue #1708).
+     */
+    unclassifiedSince: number | 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}.
+     */
+    turnStartedAt: number | 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.
+     */
+    promptLedgerReadable: boolean;
+    /**
+     * 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.
+     */
+    autoYesAnsweringSince: number | null;
+    /**
+     * 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).
+     */
+    selfResumeHold: {
+        stopAt: number;
+        since: number;
+    } | null;
+    /** Milliseconds spent in self-resume holds that have already ended (Issue #2614). */
+    selfResumeHeldMs: number;
+    /** Whether any poll of this wait was held for a self-resume (Issue #2614). */
+    selfResumeHeld: boolean;
+    /**
+     * The orphan turn being held: its `openedAt`, and when this wait first saw it
+     * as one (CLI clock). Null when none is (Issue #3429). See
+     * {@link releaseOrphanTurn}.
+     */
+    orphanTurnHold: {
+        openedAt: number;
+        since: number;
+    } | null;
+}
+/**
+ * What {@link pollWorktree} hands every stage of a poll and never writes: its
+ * `const`s, as {@link PollState} is its variables.
+ */
+export interface PollContext {
+    client: ApiClient;
+    worktreeId: string;
+    options: PollWorktreeOptions;
+    startTime: number;
+    autoYesGraceSeconds: number;
+    autoYesGraceMs: number;
+}
+//# sourceMappingURL=wait-poll-state.d.ts.map

package/dist/cli/commands/wait-poll-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-poll-state.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-poll-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9E;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,cAAc,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/cli/commands/wait-poll-state.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * wait Command - what pollWorktree carries between polls and hands its stages
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli/commands/wait-timing.d.ts

@@ -0,0 +1,46 @@
+/**
+ * wait Command - poll interval and the deadline arithmetic of a poll
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+import type { WaitOptions } from '../types';
+/** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
+export declare const POLL_INTERVAL_MS = 5000;
+/**
+ * Whether one more poll interval still lands inside `--timeout` and
+ * `--stall-timeout` (Issue #2463).
+ *
+ * The Auto-Yes hold asks before it sleeps. Otherwise a caller whose deadline
+ * lapses during the hold would hear 124 about a prompt it used to hear 10 about:
+ * the hold is there to give Auto-Yes a chance to answer, not to turn an open
+ * prompt into a timeout. The same two checks the top of {@link pollWorktree}'s
+ * loop makes, one interval ahead.
+ */
+export declare function nextPollWithinDeadlines(options: WaitOptions, startTime: number, lastActivityTime: number, now: number): boolean;
+/**
+ * Milliseconds left before `--timeout` or `--stall-timeout` would end the wait,
+ * whichever is sooner; `Infinity` when neither is set (Issue #3956).
+ */
+export declare function msBeforeDeadlines(options: WaitOptions, startTime: number, lastActivityTime: number, now: number): number;
+/**
+ * Thrown by {@link readWithinDeadlines} when `--timeout` or `--stall-timeout`
+ * ends a read (Issue #3974). Not an `ApiError` and not a failed poll: the poll
+ * loop goes back to its deadline check, which ends the wait with exit 124.
+ */
+export declare class DeadlineReached extends Error {
+    constructor();
+}
+/**
+ * Runs one read of a poll bounded by `--timeout` / `--stall-timeout`
+ * (Issue #3974): the read gets an `AbortSignal` that fires when the sooner of
+ * the two runs out ({@link msBeforeDeadlines}). With neither set, `read` gets no
+ * signal and runs as before (also when the time left is more than a timer can
+ * hold). With no time left, no read is started.
+ *
+ * A read that was aborted — whether it threw (`ApiClient.get`) or swallowed the
+ * failure (`readNewestPromptAt`) — throws {@link DeadlineReached}, so a ledger
+ * that did not answer is a timeout, not "unreadable". Any other failure is
+ * rethrown as it came.
+ */
+export declare function readWithinDeadlines<T>(options: WaitOptions, startTime: number, lastActivityTime: number, read: (signal?: AbortSignal) => Promise<T>): Promise<T>;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=wait-timing.d.ts.map

package/dist/cli/commands/wait-timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-timing.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,GAAG,EAAE,MAAM,GACV,OAAO,CAOT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,GAAG,EAAE,MAAM,GACV,MAAM,CAOR;AAKD;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;;CAKzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,CAAC,CAkBZ;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}