sequant 2.8.0 → 2.10.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 } 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";
 /**
@@ -98,6 +100,279 @@ const SPEC_RETRY_STRATEGY = phaseRegistry.get("spec").retryStrategy;
 export const SPEC_RETRY_BACKOFF_MS = SPEC_RETRY_STRATEGY?.backoffMs ?? 5000;
 /** @internal Exported for testing only */
 export const SPEC_EXTRA_RETRIES = SPEC_RETRY_STRATEGY?.extraRetries ?? 1;
+/**
+ * A rate limit whose window resets further out than this is treated as
+ * exhausted rather than transient (#761 AC-2): no retry can succeed inside a
+ * closed window, so consuming cold-start retries (each burning up to a full
+ * `phaseTimeout`) only delays the labeled halt. Five minutes comfortably
+ * exceeds any backoff this executor performs while staying far below the
+ * five-hour/seven-day windows the check exists to catch.
+ *
+ * @internal Exported for testing only
+ */
+export const RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS = 5 * 60 * 1000;
+/**
+ * Base backoff for transient rate-limit retries (#761 AC-4), doubled per
+ * attempt (5s, 10s). Same scale as `SPEC_RETRY_BACKOFF_MS` — long enough to
+ * outlive a momentary throttle, short enough to be negligible next to a
+ * phase's runtime.
+ *
+ * @internal Exported for testing only
+ */
+export const RATE_LIMIT_RETRY_BACKOFF_MS = 5000;
+/**
+ * True when a failure is a rate limit whose reset lies beyond
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS} — i.e. window exhaustion, not a
+ * transient throttle. Metadata-absent rate limits (the assistant-error channel
+ * carries no `resetsAt`, see #761 AC-9) return false and fall through to the
+ * transient path: with no timing signal, retry-with-backoff is the safe
+ * default, skipping all retries is not.
+ *
+ * @internal Exported for testing only
+ */
+export function isWindowExhaustedRateLimit(error, now = Date.now()) {
+    if (!(error instanceof RateLimitError))
+        return false;
+    const resetsAt = error.metadata.resetsAt;
+    if (typeof resetsAt !== "number")
+        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;
@@ -122,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).
  *
@@ -275,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 {
@@ -304,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
@@ -348,9 +721,12 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         const summary = agentResult.output
             ? (parseQaSummary(agentResult.output) ?? undefined)
             : undefined;
-        if (verdict &&
-            verdict !== "READY_FOR_MERGE" &&
-            verdict !== "NEEDS_VERIFICATION") {
+        if (verdict === "AC_NOT_MET") {
+            // #749: only AC_NOT_MET (and the null branch below, #534) hard-fails.
+            // AC_MET_BUT_NOT_A_PLUS is a stopping/ready state — it must break to PR,
+            // not feed the quality loop (mirrors ready-gate.ts's `ac` policy). The
+            // verdict is retained on the success result so the PR/log surfaces the
+            // "not A+" note.
             return {
                 phase,
                 success: false,
@@ -364,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,
@@ -387,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,
@@ -507,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"],
@@ -699,7 +1105,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);
@@ -715,18 +1130,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 {
@@ -746,6 +1175,49 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             if (lastResult.capped) {
                 return lastResult;
             }
+            // Window-exhausted rate limit (#761 AC-2): the reset is hours away, so
+            // every retry re-spawns into the same closed window — worst case
+            // ~4 × phaseTimeout (≈2h) of doomed attempts before the run halts.
+            // Modelled on the `capped` early return above: skip all remaining
+            // cold-start retries and (via the return) the MCP fallback. Checked
+            // 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`));
+                }
+                return lastResult;
+            }
+            // Transient rate limit (#761 AC-4): retry, but with real backoff — the
+            // bare `continue` this replaces re-spawned immediately into the same
+            // throttle. Reuses the injected `delayFn`; delay doubles per attempt.
+            // Metadata-absent rate limits land here by design (AC-9 fallback rule).
+            if (lastResult.structuredError instanceof RateLimitError &&
+                attempt < COLD_START_MAX_RETRIES) {
+                const backoffMs = RATE_LIMIT_RETRY_BACKOFF_MS * 2 ** attempt;
+                if (config.verbose) {
+                    bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ ${lastResult.error ?? "Rate limited"} — backing off ${backoffMs}ms before retry... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                }
+                await delayFn(backoffMs);
+                continue;
+            }
             // Genuine failure (took long enough to be real work) → skip cold-start retries.
             // Use error classification (AC-9): if the error is retryable (e.g., API
             // rate limit, transient 503), allow one more attempt even for genuine failures.
@@ -793,11 +1265,16 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // intent is documented and future code paths can't accidentally re-spawn a
     // capped phase without MCP.
     const failureIsCapped = lastResult.capped === true;
+    // A throttle must not trigger "retrying without MCP" (#761 AC-3): MCP was
+    // never the cause, and the re-spawn burns up to another full phaseTimeout
+    // against the same limit while mislabeling the failure as MCP-related.
+    const failureIsRateLimited = lastResult.structuredError instanceof RateLimitError;
     if (config.mcp &&
         !lastResult.success &&
         !skipColdStartRetry &&
         !failureIsBilling &&
-        !failureIsCapped) {
+        !failureIsCapped &&
+        !failureIsRateLimited) {
         bracketedConsoleLog(spinner, chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
         // Create config copy with MCP disabled
         const configWithoutMcp = {