sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/phase-executor.js

@@ -8,11 +8,13 @@
  * is agent-agnostic.
  */
 import chalk from "chalk";
-import { execSync, execFileSync } from "child_process";
+import { execFileSync } from "child_process";
+import { resolveDiffBase } from "./git-diff-utils.js";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
-import { ApiError, BillingError, RateLimitError, resetsAtToMs, } from "../errors.js";
+import { ApiError, BillingError, RateLimitError, formatRateLimitMessage, formatResetTime, resetsAtToMs, } from "../errors.js";
+import { formatElapsedTime } from "../cli-ui/format.js";
 import { phaseRegistry } from "./phase-registry.js";
 import { bracketedConsoleLog } from "./notice.js";
 /**
@@ -136,6 +138,241 @@ export function isWindowExhaustedRateLimit(error, now = Date.now()) {
         return false;
     return resetsAtToMs(resetsAt) - now > RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS;
 }
+/**
+ * Buffer added to a rate-limit reset before waking (#804 AC-5). `resetsAt` is a
+ * floor, not an exact moment: clock skew between this host and the API, plus
+ * server-side rounding, otherwise produce an immediate second rejection on
+ * wake. One minute is negligible against the five-hour/seven-day windows this
+ * exists for.
+ *
+ * @internal Exported for testing only
+ */
+export const AUTO_WAIT_BUFFER_MS = 60 * 1000;
+/**
+ * Hard cap on auto-waits per issue (#804 AC-6), independent of the minutes
+ * budget. A window that is still closed on wake must not produce an unbounded
+ * pause loop, so the count bounds the *number* of pauses while
+ * `autoWaitMinutes` bounds their *total duration*. Either bound being spent
+ * halts with today's labeled message.
+ *
+ * @internal Exported for testing only
+ */
+export const AUTO_WAIT_MAX_WAITS = 2;
+/**
+ * Granularity of the auto-wait sleep (#804 AC-7). The wait is performed as a
+ * series of ticks rather than one multi-hour `delayFn` call so that (a) the
+ * renderer/heartbeat can be refreshed with the remaining time, and (b) a
+ * Ctrl-C is observed promptly instead of at the wake time.
+ *
+ * @internal Exported for testing only
+ */
+export const AUTO_WAIT_TICK_MS = 15 * 1000;
+/**
+ * Build a fresh ledger from a minutes budget. A missing, negative or
+ * non-finite budget yields a disabled ledger (`budgetMs: 0`) — the default,
+ * which preserves pre-#804 behavior exactly.
+ */
+export function createAutoWaitLedger(budgetMinutes) {
+    const minutes = typeof budgetMinutes === "number" && Number.isFinite(budgetMinutes)
+        ? Math.max(0, budgetMinutes)
+        : 0;
+    return { budgetMs: minutes * 60 * 1000, waits: 0, spentMs: 0 };
+}
+/**
+ * Decide whether to wait out an exhausted rate-limit window (#804 AC-3).
+ *
+ * Deliberately separate from {@link isWindowExhaustedRateLimit} and
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS}, which answer *"is this transient
+ * or exhausted?"*. This answers a different question — *"am I willing to wait
+ * that long?"* — and fires ONLY once the former is already true. Keeping them
+ * apart is what leaves `autoWaitMinutes` the single user-facing dial for the
+ * wait-vs-halt outcome.
+ *
+ * Returns `null` (no wait — halt as before) when:
+ * - auto-wait is off, or the per-issue wait count is spent;
+ * - the failure is not a window-exhausted `RateLimitError`. A `BillingError`
+ *   lands here: it is a sibling class, not a subclass, so the `instanceof`
+ *   check inside `isWindowExhaustedRateLimit` excludes it. That is load-bearing
+ *   — a `BillingError` may still carry `resetsAt` (an explicit
+ *   `credits_required`, or a window that has already passed — see the #860
+ *   narrowing in `isBillingFailure`), so gating on the timestamp's presence
+ *   instead of the error type would wait out a credits failure that no amount
+ *   of waiting can heal (AC-4). Since #860, a *live* recognized window
+ *   (`five_hour`/`seven_day*` + future reset) classifies as `RateLimitError`
+ *   upstream even when `out_of_credits` is present, which is what lets the
+ *   real captured subscription payloads reach this decision at all;
+ * - the reset has already passed (nothing to wait for);
+ * - the required wait exceeds the budget REMAINING, not the total (AC-6).
+ *
+ * @internal Exported for testing only
+ */
+export function shouldAutoWaitForReset(error, ledger, now = Date.now()) {
+    if (ledger.budgetMs <= 0)
+        return null;
+    if (ledger.waits >= AUTO_WAIT_MAX_WAITS)
+        return null;
+    // These two guards duplicate checks inside `isWindowExhaustedRateLimit`, and
+    // that duplication is deliberate: TypeScript cannot narrow through a boolean
+    // helper, so without them the lines below need `as RateLimitError` /
+    // `as number` casts. Real narrowing beats a cast in the one function that
+    // decides whether to pause a run for hours. The classifier below still owns
+    // the "transient or exhausted?" question (AC-3) — these only prove types.
+    if (!(error instanceof RateLimitError))
+        return null;
+    const resetsAt = error.metadata.resetsAt;
+    if (typeof resetsAt !== "number")
+        return null;
+    if (!isWindowExhaustedRateLimit(error, now))
+        return null;
+    // All arithmetic stays in epoch ms (AC-5) — resetsAtToMs first, buffer
+    // after, formatting only ever for display.
+    const wakeAtMs = resetsAtToMs(resetsAt) + AUTO_WAIT_BUFFER_MS;
+    const waitMs = wakeAtMs - now;
+    if (waitMs <= 0)
+        return null;
+    const remainingMs = ledger.budgetMs - ledger.spentMs;
+    if (waitMs > remainingMs)
+        return null;
+    // Carry the narrowed error forward so callers don't have to re-cast it.
+    return { waitMs, wakeAtMs, error };
+}
+/**
+ * Sleep until an auto-wait's wake time, in ticks (#804 AC-7).
+ *
+ * Chunking the sleep is what makes a multi-hour pause survivable:
+ * - `onTick` refreshes the live display so the wait is visible rather than a
+ *   silent stall (the #574 complaint at 60x scale);
+ * - each tick races the injected `delayFn` against the abort signal, so Ctrl-C
+ *   returns immediately instead of blocking until the wake.
+ *
+ * Reuses the caller's `delayFn` so the wait stays fully test-injectable.
+ *
+ * Returns the ms actually slept and whether the wait was aborted.
+ *
+ * @internal Exported for testing only
+ */
+export async function waitForWindowReset(waitMs, options) {
+    const { delayFn, signal, onTick } = options;
+    const now = options.now ?? Date.now;
+    const tickMs = options.tickMs ?? AUTO_WAIT_TICK_MS;
+    const startedAt = now();
+    const deadline = startedAt + waitMs;
+    // Two independent notions of "how much is left", and the loop honors
+    // whichever expires first:
+    //   - `budgetLeft` counts down by the slices actually requested. This is what
+    //     terminates the loop, and it does so after a fixed number of iterations
+    //     regardless of what the clock does — without it, an injected delayFn
+    //     that resolves instantly (every test) would spin against the wall clock
+    //     until the real reset time arrived.
+    //   - the `deadline` check ends the wait early when real time has outrun the
+    //     slices, e.g. a laptop resumed from sleep mid-wait.
+    let budgetLeft = waitMs;
+    let sleptMs = 0;
+    // ONE abort listener for the whole wait, not one per tick. A 5-hour wait is
+    // ~1200 ticks; registering inside the loop would pile up that many listeners
+    // (and as many pending promises) on a single signal, tripping Node's
+    // max-listeners warning and leaking until the wait ended.
+    const abortPromise = signal
+        ? new Promise((resolve) => {
+            signal.addEventListener("abort", () => resolve(true), { once: true });
+        })
+        : null;
+    for (;;) {
+        if (signal?.aborted) {
+            return { sleptMs: Math.max(sleptMs, now() - startedAt), aborted: true };
+        }
+        const clockLeft = deadline - now();
+        const remainingMs = Math.min(budgetLeft, clockLeft);
+        if (remainingMs <= 0)
+            break;
+        onTick?.(remainingMs);
+        const sliceMs = Math.min(tickMs, remainingMs);
+        budgetLeft -= sliceMs;
+        sleptMs += sliceMs;
+        // The injected delayFn exposes no timer handle, so an in-flight slice
+        // cannot be cleared on abort. Racing bounds the *observed* Ctrl-C latency
+        // to ~0 regardless; only the orphaned timer runs on, and it is one tick
+        // long, not one window long.
+        if (abortPromise) {
+            const aborted = await Promise.race([
+                delayFn(sliceMs).then(() => false),
+                abortPromise,
+            ]);
+            if (aborted) {
+                // This slice never completed — don't bill the ledger for it.
+                sleptMs -= sliceMs;
+                return { sleptMs: Math.max(sleptMs, now() - startedAt), aborted: true };
+            }
+        }
+        else {
+            await delayFn(sliceMs);
+        }
+    }
+    return {
+        sleptMs: Math.max(sleptMs, now() - startedAt),
+        aborted: signal?.aborted === true,
+    };
+}
+/**
+ * Run one granted auto-wait end to end (#804): emit the live notices, sleep,
+ * update the ledger, and report whether Ctrl-C interrupted it.
+ *
+ * Shared by both arms of the retry ladder (the cold-start loop and the
+ * `skipColdStartRetry` single-attempt path) so the two cannot drift on
+ * bookkeeping or messaging.
+ *
+ * @internal Exported for testing only
+ */
+export async function performAutoWait(issueNumber, phase, config, decision, ledger, delayFn, shutdownManager, spinner) {
+    // Count the wait BEFORE sleeping. If the process dies mid-wait the ledger is
+    // gone anyway, but an exception on the sleep path must not hand back a free
+    // retry — the bound exists to stop unbounded pause loops.
+    ledger.waits += 1;
+    // AC-5: reuse the driver's own formatter for the cause rather than
+    // re-deriving a timestamp, and render the wake time (a distinct value —
+    // reset plus buffer) through the same `formatResetTime` convention.
+    const cause = formatRateLimitMessage(decision.error.metadata);
+    const wakeLabel = formatResetTime(decision.wakeAtMs);
+    const header = `${cause} · auto-wait ${ledger.waits}/${AUTO_WAIT_MAX_WAITS} — resuming at ${wakeLabel}`;
+    bracketedConsoleLog(spinner, chalk.yellow(`\n    ⏸ ${header} (${formatElapsedTime(decision.waitMs / 1000)})`));
+    const emit = (remainingMs, done) => {
+        try {
+            config.onAutoWait?.({
+                issueNumber,
+                phase,
+                wakeAtMs: decision.wakeAtMs,
+                remainingMs,
+                message: done
+                    ? `${cause} · auto-wait complete`
+                    : `${header} · ${formatElapsedTime(remainingMs / 1000)} left`,
+                done,
+            });
+        }
+        catch {
+            // Liveness notices must never disrupt the run.
+        }
+    };
+    // AC-7: a registered controller is aborted by ShutdownManager on SIGINT, so
+    // Ctrl-C ends the wait instead of blocking until the wake.
+    const controller = new AbortController();
+    shutdownManager?.addAbortController(controller);
+    try {
+        const { sleptMs, aborted } = await waitForWindowReset(decision.waitMs, {
+            delayFn,
+            signal: controller.signal,
+            onTick: (remainingMs) => emit(remainingMs, false),
+        });
+        ledger.spentMs += sleptMs;
+        emit(0, true);
+        if (aborted) {
+            bracketedConsoleLog(spinner, chalk.yellow(`    ✕ Auto-wait interrupted — halting`));
+        }
+        return { aborted };
+    }
+    finally {
+        shutdownManager?.removeAbortController(controller);
+    }
+}
 export function parseQaVerdict(output) {
     if (!output)
         return null;
@@ -160,6 +397,59 @@ export function parseQaVerdict(output) {
     const verdict = verdictMatch[1].toUpperCase().replace(/-/g, "_");
     return verdict;
 }
+/**
+ * Deferral/continuation markers that signal a QA agent ended its turn intending
+ * to continue *later* — as if a subsequent turn or a background poll were
+ * available to it. Seeded from the #853 live repro, whose QA turn deferred to a
+ * background CI poll and "the completion notification" instead of emitting a
+ * verdict. Matched as lowercased literal substrings (ReDoS-safe) against the
+ * output tail only.
+ *
+ * The second group covers deferral-to-*user* phrasing, observed by running the
+ * detector against every `qa` phase output in 99 real `.sequant/logs` runs: a
+ * turn that ended "this needs a decision from you … Tell me which one and I'll
+ * execute it" (run-2026-06-06) is the same one-shot violation with the wait
+ * pointed at a human instead of a poll. Structural alternatives were tried
+ * against the same corpus and rejected: 19/45 outputs with a *parseable*
+ * verdict have no `Verdict`-labelled line at all, so label-presence cannot
+ * discriminate — a literal marker list is the shape that works here.
+ */
+const QA_DEFERRAL_MARKERS = [
+    "i'll pick this up",
+    "pick this up on the completion",
+    "completion notification",
+    "background poll",
+    "when the background",
+    "when ci ",
+    "later turn",
+    "i'll invoke",
+    // Deferral-to-user (corpus-observed, run-2026-06-06T03-33-20):
+    "needs a decision from you",
+    "tell me which",
+    "let me know which",
+    "tell me and i'll",
+];
+/**
+ * Distinguish a QA turn that produced *no verdict at all* from one whose output
+ * was present but unparseable (#853). Returns true when the output is empty /
+ * whitespace, or when its tail contains deferral language — the agent treating
+ * its one-shot phase as if a later turn were available.
+ *
+ * Both cases are hard failures either way; this only refines which message is
+ * emitted, so a false positive is harmless (it swaps one failing message for
+ * another). Kept deliberately conservative and literal to stay ReDoS-safe.
+ *
+ * @internal Exported for testing only.
+ */
+export function endedWithoutVerdict(output) {
+    if (!output || output.trim().length === 0)
+        return true;
+    // Scan the tail only: deferral language lives at the end of the turn, where
+    // the agent signs off planning to continue. A larger window would also catch
+    // a mid-review aside that says "later" without deferring the whole turn.
+    const tail = output.slice(-2000).toLowerCase();
+    return QA_DEFERRAL_MARKERS.some((marker) => tail.includes(marker));
+}
 /**
  * Parse condensed QA summary from QA phase output (#434).
  *
@@ -313,26 +603,41 @@ export function resolveBaseRef(cwd) {
     return recorded.startsWith("origin/") ? recorded : `origin/${recorded}`;
 }
 /**
- * Check whether the exec phase produced any changes in the worktree.
- * Returns true if HEAD has commits unique to it relative to the resolved
- * base ref (see {@link resolveBaseRef}) OR uncommitted work is present.
+ * Parse the file paths out of `git status --porcelain` (v1) output. Each line
+ * is `XY <path>` (two status chars + a space); renames are `R  <old> -> <new>`,
+ * for which we name the new path.
+ */
+function parsePorcelainPaths(porcelain) {
+    return porcelain
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const rest = line.slice(3);
+        const arrow = rest.indexOf(" -> ");
+        return arrow >= 0 ? rest.slice(arrow + 4) : rest;
+    });
+}
+/**
+ * Classify what the exec phase produced in the worktree (#879).
  *
- * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD
- * but not the base) instead of `git diff <base>..HEAD`, because the
- * two-dot diff also fires in reverse when the base has advanced past HEAD
- * — on stale branches that would falsely report "has commits" even when the
- * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD but not
+ * the base) instead of `git diff <base>..HEAD`, because the two-dot diff also
+ * fires in reverse when the base has advanced past HEAD — on stale branches
+ * that would falsely report "has commits" even when exec produced nothing,
+ * reintroducing the bug #534 is fixing.
  *
  * The base ref defaults to `origin/main` but is overridden to the worktree's
- * recorded base (see #537) so zero-diff execs are still detected on
- * custom-base worktrees (e.g. those created with `--base feature/epic`).
+ * recorded base (see #537) so zero-diff execs are still detected on custom-base
+ * worktrees (e.g. those created with `--base feature/epic`).
  *
- * Fails open (returns true) on git errors — a missing origin ref is better
- * diagnosed as a real zero-diff run than as a false phase failure.
+ * Read-only: runs only `git rev-list` and `git status --porcelain`, so it never
+ * mutates the worktree — an exec phase that fails on an `uncommitted` result
+ * leaves the dirty files exactly where the agent left them (#879 AC-3).
  *
  * @internal Exported for testing only.
  */
-export function hasExecChanges(cwd) {
+export function classifyExecChanges(cwd) {
     const baseRef = resolveBaseRef(cwd);
     let commitsAhead;
     try {
@@ -342,23 +647,53 @@ export function hasExecChanges(cwd) {
         commitsAhead = Number.parseInt(count, 10) > 0;
     }
     catch {
-        return true;
+        return { kind: "unknown" };
     }
     if (commitsAhead)
-        return true;
+        return { kind: "commits" };
     try {
-        const porcelain = execFileSync("git", ["status", "--porcelain"], {
-            cwd,
-            stdio: "pipe",
-        })
-            .toString()
-            .trim();
-        return porcelain.length > 0;
+        // `--untracked-files=all` lists each new file individually rather than
+        // collapsing a wholly-untracked directory to its top-level path — so the
+        // #879 failure message names the actual files the agent left behind (AC-2).
+        const porcelain = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd, stdio: "pipe" }).toString();
+        const paths = parsePorcelainPaths(porcelain);
+        return paths.length > 0 ? { kind: "uncommitted", paths } : { kind: "none" };
     }
     catch {
-        return true;
+        return { kind: "unknown" };
     }
 }
+/**
+ * Check whether the exec phase produced deliverable work in the worktree.
+ *
+ * Thin boolean wrapper over {@link classifyExecChanges}: only `commits` (real
+ * work) and `unknown` (git error — fail open) count as "has changes". Note the
+ * #879 behaviour change: an `uncommitted`-only tree now returns **false**, since
+ * uncommitted work is not a deliverable. Both callers (the exec guard in
+ * {@link mapAgentSuccessToPhaseResult} and the ready gate) want this stricter
+ * semantics.
+ *
+ * @internal Exported for testing only.
+ */
+export function hasExecChanges(cwd) {
+    const { kind } = classifyExecChanges(cwd);
+    return kind === "commits" || kind === "unknown";
+}
+/** Cap on how many dirty paths the #879 exec-failure message lists inline. */
+const MAX_UNCOMMITTED_PATHS_LISTED = 20;
+/**
+ * Build the exec-failure message for an `uncommitted`-only worktree (#879 AC-2).
+ * Names the dirty paths so the work is discoverable from the run log alone,
+ * capped at {@link MAX_UNCOMMITTED_PATHS_LISTED} to keep the log bounded.
+ */
+function formatUncommittedExecError(paths, cwd) {
+    const listed = paths.slice(0, MAX_UNCOMMITTED_PATHS_LISTED);
+    const remainder = paths.length - listed.length;
+    const suffix = remainder > 0 ? `, … and ${remainder} more` : "";
+    return (`exec left ${paths.length} file(s) uncommitted and made no commits — ` +
+        `uncommitted work cannot rebase, push, or become a PR. The work is ` +
+        `preserved in ${cwd}: ${listed.join(", ")}${suffix}`);
+}
 /**
  * Map a successful AgentPhaseResult to a PhaseResult, applying phase-specific
  * guards that catch agent sessions which returned success without producing
@@ -405,12 +740,20 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             };
         }
         if (!verdict) {
-            // #534: a null verdict (empty or unparseable output) is not success.
+            // #534: a null verdict is not success. #853 splits this into two classes
+            // so the message is not misleading. A turn that deferred to a later turn
+            // (or produced no output) never emitted a verdict — reporting that as
+            // "unparseable" sends a debugger to inspect a verdict regex that was
+            // never the problem. Both remain hard failures (`success:false`); only
+            // the message differs.
+            const error = endedWithoutVerdict(agentResult.output)
+                ? "QA ended without producing a verdict — the phase is one-shot; the agent deferred to a later turn or emitted no output"
+                : "QA completed without a parseable verdict";
             return {
                 phase,
                 success: false,
                 durationSeconds,
-                error: "QA completed without a parseable verdict",
+                error,
                 ...resume,
                 output: agentResult.output,
                 summary,
@@ -428,17 +771,38 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             ...tails,
         };
     }
-    if (phase === "exec" && !hasExecChanges(cwd)) {
-        // #534: an exec phase that produced nothing is not success.
-        return {
-            phase,
-            success: false,
-            durationSeconds,
-            error: "exec produced no changes (no commits, no uncommitted work)",
-            ...resume,
-            output: agentResult.output,
-            ...tails,
-        };
+    if (phase === "exec") {
+        // #534/#879: an exec phase that produced no deliverable commits is not
+        // success. Two distinct non-deliverable states, each with its own message:
+        //   - `none`: literally nothing (#534's empty-branch class).
+        //   - `uncommitted`: a dirty tree with no commits — used to be counted as
+        //     success (#879), but it cannot rebase, push, or become a PR. Failing
+        //     here (rather than auto-committing) preserves the work in place; the
+        //     message names the paths so it is discoverable from the run log alone.
+        // `commits`/`unknown` fall through to success (unknown fails open).
+        const changes = classifyExecChanges(cwd);
+        if (changes.kind === "none") {
+            return {
+                phase,
+                success: false,
+                durationSeconds,
+                error: "exec produced no changes (no commits, no uncommitted work)",
+                ...resume,
+                output: agentResult.output,
+                ...tails,
+            };
+        }
+        if (changes.kind === "uncommitted") {
+            return {
+                phase,
+                success: false,
+                durationSeconds,
+                error: formatUncommittedExecError(changes.paths, cwd),
+                ...resume,
+                output: agentResult.output,
+                ...tails,
+            };
+        }
     }
     return {
         phase,
@@ -548,7 +912,8 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
     let files;
     if (config.agent && config.agent !== "claude-code") {
         try {
-            const output = execSync("git diff --name-only main...HEAD", {
+            const diffBase = resolveDiffBase(cwd, "main");
+            const output = execFileSync("git", ["diff", "--name-only", `${diffBase}...HEAD`], {
                 cwd,
                 encoding: "utf-8",
                 stdio: ["pipe", "pipe", "pipe"],
@@ -667,6 +1032,12 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
     const eligibleHandle = resumeHandle && driver.canResume(resumeHandle, cwd)
         ? resumeHandle
         : undefined;
+    // #914: resolved per-phase model/effort, if this phase has one. Both
+    // ExecutionConfig producers (buildExecutionConfig, ready-gate.ts's
+    // buildPhaseConfig) populate `phasePolicies` the same way, so this is the
+    // single site that turns it into driver-facing fields — see the doc
+    // comment on ExecutionConfig.phasePolicies.
+    const phasePolicy = config.phasePolicies?.[phase];
     // Build AgentExecutionConfig for the driver
     const agentConfig = {
         cwd,
@@ -678,6 +1049,10 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         resumeHandle: eligibleHandle,
         sessionId: eligibleHandle?.token,
         files,
+        ...(phasePolicy?.model ? { model: phasePolicy.model } : {}),
+        ...(phasePolicy?.effort
+            ? { effort: phasePolicy.effort }
+            : {}),
         onOutput: config.verbose || reportActivity
             ? (text) => {
                 if (config.verbose) {
@@ -740,7 +1115,16 @@ export async function executePhaseWithRetry(issueNumber, phase, config, resumeHa
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn = executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
-delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), 
+/**
+ * Per-issue auto-wait accounting (#804). Deliberately the LAST parameter:
+ * the #761/#799 regression tests call this function positionally with
+ * `executePhaseFn` at 8 and `delayFn` at 9, and AC-2 requires those tests to
+ * pass unmodified. Defaults to a fresh disabled-or-config-derived ledger, so
+ * a caller that does not thread one still gets correct (bounded) behavior —
+ * just scoped to this phase rather than the issue.
+ */
+autoWaitLedger = createAutoWaitLedger(config.autoWaitMinutes)) {
     // Skip retry logic if explicitly disabled
     if (config.retry === false) {
         return executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
@@ -756,18 +1140,32 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
         phaseRegistry.get(phase).retryStrategy?.maxRetries === 0;
     let lastResult;
     if (skipColdStartRetry) {
-        // Single attempt — no cold-start retry loop
-        lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
-        if (lastResult.success) {
-            return lastResult;
-        }
-        // Turn-capped phase (#739): incomplete-but-not-hard-failed. A retry cannot
-        // un-cap a turn limit, so short-circuit before any fallback — same rationale
-        // as the billing skip (#732), but capped must skip *all* retries (incl.
-        // cold-start), so an explicit early return is required, not just a guard
-        // flag at the MCP gate.
-        if (lastResult.capped) {
-            return lastResult;
+        // Single attempt — no cold-start retry loop. The only thing that re-enters
+        // this loop is a granted auto-wait (#804): `maxRetries: 0` means "a retry
+        // cannot help", but a reopened rate-limit window is precisely the case
+        // where it can. Bounded by AUTO_WAIT_MAX_WAITS.
+        for (;;) {
+            lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
+            if (lastResult.success) {
+                return lastResult;
+            }
+            // Turn-capped phase (#739): incomplete-but-not-hard-failed. A retry cannot
+            // un-cap a turn limit, so short-circuit before any fallback — same rationale
+            // as the billing skip (#732), but capped must skip *all* retries (incl.
+            // cold-start), so an explicit early return is required, not just a guard
+            // flag at the MCP gate.
+            if (lastResult.capped) {
+                return lastResult;
+            }
+            // #804: without this, `--auto-wait` would silently not cover the `loop`
+            // phase — the one phase registered with `maxRetries: 0` — and a window
+            // limit hitting /loop would still hard-halt with the flag set.
+            const decision = shouldAutoWaitForReset(lastResult.structuredError, autoWaitLedger);
+            if (!decision)
+                break;
+            const { aborted } = await performAutoWait(issueNumber, phase, config, decision, autoWaitLedger, delayFn, shutdownManager, spinner);
+            if (aborted)
+                return lastResult;
         }
     }
     else {
@@ -795,6 +1193,23 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             // before the duration branch because a rate-limit rejection typically
             // fails fast and would otherwise be mistaken for a cold-start failure.
             if (isWindowExhaustedRateLimit(lastResult.structuredError)) {
+                // #804: opt-in auto-wait. Sits between phase attempts (never inside a
+                // spawn), so `phaseTimeout` is not implicated. Returns null — and this
+                // falls through to today's halt — whenever auto-wait is off, the
+                // budget/bound is spent, or the failure is billing rather than a rate
+                // limit.
+                const decision = shouldAutoWaitForReset(lastResult.structuredError, autoWaitLedger);
+                if (decision) {
+                    const { aborted } = await performAutoWait(issueNumber, phase, config, decision, autoWaitLedger, delayFn, shutdownManager, spinner);
+                    if (!aborted) {
+                        // A wait is not a cold-start retry, so it must not consume one:
+                        // the loop's `attempt++` cancels this out. Bounded by
+                        // AUTO_WAIT_MAX_WAITS, which is what makes this safe from looping.
+                        attempt--;
+                        continue;
+                    }
+                    return lastResult;
+                }
                 if (config.verbose) {
                     bracketedConsoleLog(spinner, chalk.yellow(`\n    ✕ ${lastResult.error ?? "Rate limited"} — window exhausted, skipping retries`));
                 }

package/dist/src/lib/workflow/phase-registry.js

@@ -190,13 +190,14 @@ Run relevant commands and capture their output for review.`,
 phaseRegistry.register({
     name: "qa",
     skill: "qa",
-    promptTemplate: "Review the implementation for GitHub issue #{issue} against acceptance criteria. Run the /qa {issue} workflow.",
+    promptTemplate: "Review the implementation for GitHub issue #{issue} against acceptance criteria. Run the /qa {issue} workflow. Your turn is one-shot: you must emit a `### Verdict:` line before the turn ends — deferring to a later turn or a background CI poll is not available.",
     requiresWorktree: true,
     driverOverrides: {
         aider: {
             promptTemplate: `Review the changes for GitHub issue #{issue}.
 Run 'npm test' and 'npm run build' to verify everything works.
 Check each acceptance criterion from the issue comments.
+Your turn is one-shot: emit a verdict now — do not defer to a later turn or a background CI poll. If the tree is unreviewable, emit AC_NOT_MET (code-caused red CI) or NEEDS_VERIFICATION (pending/infra-blocked CI); never end without a verdict.
 Output a verdict: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, or AC_NOT_MET
 with format "### Verdict: <VERDICT>" followed by an explanation.`,
         },