sequant 2.9.0 → 2.11.0

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

@@ -10,13 +10,19 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
+import { withEscalatedEffort } from "./effort-escalation.js";
 import { classifyError, errorTypeToCategory, } from "./error-classifier.js";
-import { getGitDiffStats, getCommitHash } from "./git-diff-utils.js";
+import { getGitDiffStats, getCommitHash, resolveDiffBase, } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
-import { executePhaseWithRetry } from "./phase-executor.js";
+import { AUTO_WAIT_BUFFER_MS, createAutoWaitLedger, executePhaseWithRetry, hasExecChanges, isWindowExhaustedRateLimit, } from "./phase-executor.js";
+import { BillingError, RateLimitError, resetsAtToMs } from "../errors.js";
 import { parseBodyDependencyMarkers } from "./dependency-markers.js";
-import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, DOCS_LABELS, } from "./phase-mapper.js";
+import { determinePhasesForIssue, DOCS_LABELS } from "./phase-mapper.js";
+import { resolveSpecRecommendation } from "./spec-recommendation.js";
 import { activateRelay, deactivateRelay, } from "../relay/activation.js";
+import { getSettings } from "../settings.js";
+import { GitHubProvider } from "./platforms/github.js";
+import { runReadyGate, parseNonGoals, } from "./ready-gate.js";
 /**
  * Emit a structured progress line to stderr for MCP progress notifications.
  * Only emits when running under an orchestrator (e.g., MCP server).
@@ -28,29 +34,95 @@ import { activateRelay, deactivateRelay, } from "../relay/activation.js";
  * @param extra - Optional fields: durationSeconds (on complete), error (on failed)
  */
 /**
- * Wrap an `ExecutionConfig` with an `onActivity` hook that re-emits each
- * agent-output ping as a `"activity"` progress event for the dashboard (#543).
+ * Wrap an `ExecutionConfig` with the runtime liveness hooks:
+ * - `onActivity` — re-emits each agent-output ping as an `"activity"` progress
+ *   event for the dashboard (#543).
+ * - `onAutoWait` — re-emits each auto-wait tick as a `"waiting"` progress
+ *   event so the renderer and heartbeat can show the pause and its wake time
+ *   (#804 AC-7). Under `SEQUANT_ORCHESTRATOR` it additionally emits throttled
+ *   `SEQUANT_PROGRESS` waiting lines (#860): an MCP-driven wait was previously
+ *   invisible on the JSON channel — indistinguishable from a hang — AND was
+ *   killed by the MCP inactivity timeout, which resets on progress lines.
+ *   Optionally notifies `onWaitTransition` on wait start/end so the caller
+ *   can persist the wait to issue state (`sequant status` truthfulness).
  *
- * Returns the input config unchanged when no `onProgress` callback is set,
- * so non-TUI runs pay no overhead.
+ * Returns the input config unchanged when there is no consumer at all (no
+ * `onProgress`, no orchestrator channel, no transition callback), so plain
+ * non-TUI runs pay no overhead.
  *
  * @internal Exported for testing only
  */
-export function withActivityHook(base, issueNumber, phase, onProgress) {
-    if (!onProgress)
+export function withActivityHook(base, issueNumber, phase, onProgress, onWaitTransition) {
+    const orchestrated = Boolean(process.env.SEQUANT_ORCHESTRATOR);
+    if (!onProgress && !orchestrated && !onWaitTransition)
         return base;
+    // Throttle the orchestrator waiting lines: the wait ticks every ~15s, and
+    // one JSON line per minute is enough to keep the MCP inactivity timeout
+    // alive (it resets on every SEQUANT_PROGRESS line) without bloating the
+    // captured stderr over a multi-hour pause.
+    let lastWaitLineAt = 0;
+    let waitAnnounced = false;
     return {
         ...base,
         onActivity: (text) => {
             try {
-                onProgress(issueNumber, phase, "activity", { text });
+                onProgress?.(issueNumber, phase, "activity", { text });
             }
             catch {
                 // Activity events must never disrupt the run.
             }
         },
+        onAutoWait: (notice) => {
+            try {
+                onProgress?.(issueNumber, phase, "waiting", {
+                    text: notice.message,
+                    // Omitted on the terminal notice — its absence is what tells the
+                    // consumers to clear the waiting state.
+                    wakeAtMs: notice.done ? undefined : notice.wakeAtMs,
+                });
+            }
+            catch {
+                // Liveness notices must never disrupt the run.
+            }
+            try {
+                if (notice.done) {
+                    if (waitAnnounced) {
+                        waitAnnounced = false;
+                        lastWaitLineAt = 0;
+                        emitProgressLine(issueNumber, phase, "waiting", {
+                            remainingMs: 0,
+                        });
+                        onWaitTransition?.(null);
+                    }
+                }
+                else {
+                    if (!waitAnnounced) {
+                        waitAnnounced = true;
+                        onWaitTransition?.(notice.wakeAtMs);
+                    }
+                    const now = Date.now();
+                    if (now - lastWaitLineAt >= AUTO_WAIT_PROGRESS_LINE_INTERVAL_MS) {
+                        lastWaitLineAt = now;
+                        emitProgressLine(issueNumber, phase, "waiting", {
+                            wakeAtMs: notice.wakeAtMs,
+                            remainingMs: notice.remainingMs,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Liveness notices must never disrupt the run.
+            }
+        },
     };
 }
+/**
+ * Cadence of orchestrator-channel waiting lines during an auto-wait (#860).
+ * See {@link withActivityHook}.
+ *
+ * @internal Exported for testing only
+ */
+export const AUTO_WAIT_PROGRESS_LINE_INTERVAL_MS = 60_000;
 /**
  * Build enriched prompt context for the /loop phase from a failed phase result (#488).
  * Passes QA verdict, failed ACs, and error directly so the /loop skill doesn't need
@@ -94,6 +166,17 @@ export function emitProgressLine(issue, phase, event = "start", extra) {
     if (extra?.iteration !== undefined) {
         payload.iteration = extra.iteration;
     }
+    // #860: auto-wait liveness. `wakeAtMs` is present while waiting and absent
+    // on the terminal notice (`remainingMs: 0`), mirroring the in-process
+    // ProgressCallback convention. Every line — waiting included — resets the
+    // MCP inactivity timeout (prefix-matched in spawnAsync), which is what
+    // keeps a legitimate multi-hour pause from being killed as "no progress".
+    if (extra?.wakeAtMs !== undefined) {
+        payload.wakeAtMs = extra.wakeAtMs;
+    }
+    if (extra?.remainingMs !== undefined) {
+        payload.remainingMs = extra.remainingMs;
+    }
     const line = `SEQUANT_PROGRESS:${JSON.stringify(payload)}\n`;
     process.stderr.write(line);
 }
@@ -254,8 +337,53 @@ export function getEnvConfig() {
     if (process.env.SEQUANT_SECURITY_REVIEW === "true") {
         config.securityReview = true;
     }
+    // #804: the env layer for --auto-wait. `resolveRunOptions` does NOT route
+    // through the `ConfigResolver` class (it uses `??` chains + this function),
+    // so numeric coercion is explicit here rather than free via `coerceEnvValue`.
+    // Non-numeric and negative values are ignored so a typo cannot silently
+    // enable an unbounded wait.
+    if (process.env.SEQUANT_AUTO_WAIT_MINUTES) {
+        const autoWait = parseInt(process.env.SEQUANT_AUTO_WAIT_MINUTES, 10);
+        if (!isNaN(autoWait) && autoWait >= 0) {
+            config.autoWaitMinutes = autoWait;
+        }
+    }
     return config;
 }
+/**
+ * Record an issue's completion in the run log in ONE place (#879): PR info, the
+ * PR-failure status flip, then finalize. Extracted so every batch loop shares a
+ * single completion sequence and cannot drift.
+ *
+ * The #879 defect was exactly such a drift: `markIssueFailed` was wired into
+ * `executeBatch`'s loop, but the live `sequant run` path is
+ * `RunOrchestrator.executeOneIssue`, which called `setPRInfo` + `completeIssue`
+ * without it — so a real run left the run-log status at `success` on a
+ * PR-creation failure. Both call sites now go through this helper.
+ *
+ * A PR-creation failure occurs after every phase has been logged, so
+ * `deriveIssueLogStatus` (last run at phase-log time) leaves the issue at
+ * `success`; the flip here is what counts it under `failed`. Safe post-hoc:
+ * no further phase is logged before `completeIssue`.
+ */
+export function recordIssueCompletion(logWriter, result, issueNumber) {
+    if (result.prNumber && result.prUrl) {
+        logWriter.setPRInfo(result.prNumber, result.prUrl, issueNumber);
+    }
+    if (result.prCreationError) {
+        logWriter.markIssueFailed(issueNumber);
+    }
+    logWriter.completeIssue(issueNumber);
+}
+/**
+ * @deprecated No live caller — `sequant run` executes issues via
+ * `RunOrchestrator.executeOneIssue`; this survives only as a
+ * `commands/run-compat` re-export. Do not build a new execution loop on it:
+ * any path that completes an issue MUST go through
+ * {@link recordIssueCompletion}, or the #879 status-drift returns (a
+ * completion path that skips the PR-failure flip logs a failed issue as
+ * `success`). Slated for removal with the run-compat surface.
+ */
 export async function executeBatch(issueNumbers, batchCtx) {
     const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = batchCtx;
     const results = [];
@@ -291,13 +419,10 @@ export async function executeBatch(issueNumbers, batchCtx) {
         };
         const result = await runIssueWithLogging(ctx);
         results.push(result);
-        // Record PR info in log before completing issue
-        if (logWriter && result.prNumber && result.prUrl) {
-            logWriter.setPRInfo(result.prNumber, result.prUrl);
-        }
-        // Complete issue logging
+        // Record PR info, flip status on PR failure (#879), and finalize — all via
+        // the shared helper so this loop and the orchestrator path cannot drift.
         if (logWriter) {
-            logWriter.completeIssue();
+            recordIssueCompletion(logWriter, result, issueNumber);
         }
     }
     return results;
@@ -323,6 +448,192 @@ export function deriveFailureCategory(phaseResults) {
         classifyError(failedPhase.stderrTail ?? [], failedPhase.exitCode);
     return errorTypeToCategory(typedError);
 }
+/**
+ * "Halt, don't loop" predicate for the outer `-Q` quality loop (#799).
+ *
+ * A billing / out-of-credits failure (`BillingError`) or a window-exhausted
+ * rate limit (reset hours away, per `isWindowExhaustedRateLimit`) cannot be
+ * recovered by re-running the phase — every retry re-spawns into the same
+ * closed window and, worse, mislabels the halt as a downstream
+ * `QA completed without a parseable verdict`. Mirrors the `haltedByCap` (#739)
+ * treatment: surface the real cause and halt so the user resumes once credits
+ * or the rate-limit window are restored.
+ *
+ * A transient / metadata-absent rate limit is NOT a halt: it returns false and
+ * keeps today's outer-loop behavior (the inner retry ladder in `phase-executor`
+ * handles its backoff, per #761 AC-4/AC-9).
+ *
+ * @internal Exported for testing
+ */
+export function isBillingOrWindowHalt(result) {
+    return isBillingHalt(result) || isWindowHalt(result);
+}
+/**
+ * The billing half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * Split out because the two causes stopped being interchangeable once
+ * `--auto-wait` existed: a closed window can now reopen on its own, while
+ * out-of-credits cannot — credits are purchased, not waited out. Callers that
+ * need to reason about recoverability must be able to tell them apart.
+ *
+ * @internal Exported for testing
+ */
+export function isBillingHalt(result) {
+    return result.structuredError instanceof BillingError;
+}
+/**
+ * The rate-limit-window half of {@link isBillingOrWindowHalt} (#804 AC-8).
+ *
+ * NOTE — this predicate needed no behavioral change for auto-wait, and that is
+ * a deliberate finding rather than an oversight. AC-8 anticipated that a phase
+ * which waits and then succeeds would still halt the `-Q` loop. It cannot:
+ * every call site (`:~700` spec, `:~1030` progress label, `:~1150` halt flag)
+ * sits inside the `else` of an `if (result.success)`, so a successful
+ * post-wait result never reaches this predicate at all. When auto-wait does
+ * NOT fire — the default, an exhausted budget, or a spent wait bound — the
+ * result is still a failure carrying a window-exhausted `RateLimitError`, and
+ * halting is then the correct outcome (#799 behavior, preserved exactly).
+ *
+ * @internal Exported for testing
+ */
+export function isWindowHalt(result) {
+    return isWindowExhaustedRateLimit(result.structuredError);
+}
+/**
+ * Human-readable halt reason for a billing / rate-limit-window failure (#799
+ * AC-3). Surfaces the driver's real cause verbatim — `result.error` is already
+ * the well-formatted message the driver built via `formatRateLimitMessage`
+ * (`Out of credits` for billing, `Rate limited — resets at <local time>` for a
+ * throttle with a known reset), so the phase-failed line and run summary name
+ * the actual cause instead of a downstream `QA completed without a parseable
+ * verdict`.
+ *
+ * Do NOT re-append `resetsAt` here: the rate-limit message already carries the
+ * reset time, and doing so produced a doubled, timezone-inconsistent string
+ * (`… resets at 07-24 14:32 — resets at 2026-…Z`). Credits failures carry no
+ * reset time by design (they need purchasing, not a window wait).
+ *
+ * @internal Exported for testing
+ */
+export function billingHaltReason(result) {
+    return result.error ?? "Out of credits";
+}
+/**
+ * Epoch ms after which a waitable-window halt can be re-entered (#892 AC-1):
+ * the window's `resetsAt` normalized to ms plus the same buffer auto-wait
+ * applies (`AUTO_WAIT_BUFFER_MS`), so in-process waits and durable halts wake
+ * on the same clock. Returns `null` when the result carries no future-reset
+ * rate-limit window — callers must then skip the `windowHalt` write rather
+ * than invent a resume time.
+ *
+ * @internal Exported for testing
+ */
+export function windowHaltResumeAtMs(result) {
+    if (!isWindowHalt(result))
+        return null;
+    const err = result.structuredError;
+    if (!(err instanceof RateLimitError))
+        return null;
+    const resetsAt = err.metadata.resetsAt;
+    if (typeof resetsAt !== "number")
+        return null;
+    return resetsAtToMs(resetsAt) + AUTO_WAIT_BUFFER_MS;
+}
+/**
+ * Persist or clear the durable `windowHalt` record for a phase result (#892).
+ *
+ * A waitable-window failure writes `resumeAt` (preserving any re-entry count);
+ * every other outcome — success, or a failure whose cause is not a waitable
+ * window — clears the record so `sequant resume` never re-enters on a stale
+ * or non-waitable halt. Never throws: state bookkeeping must not mask the
+ * phase result it describes.
+ */
+async function recordWindowHaltState(stateManager, issueNumber, phase, result) {
+    if (!stateManager)
+        return;
+    try {
+        const resumeAtMs = result.success ? null : windowHaltResumeAtMs(result);
+        if (resumeAtMs !== null) {
+            await stateManager.updateWindowHalt(issueNumber, phase, resumeAtMs);
+        }
+        else {
+            await stateManager.clearWindowHalt(issueNumber);
+        }
+    }
+    catch {
+        // State tracking errors shouldn't stop execution
+    }
+}
+/**
+ * Run the post-QA ready gate (#817) for a single issue at the run path's
+ * post-success / pre-PR seam.
+ *
+ * Mirrors `src/commands/ready.ts`'s driver: resolve the policy from
+ * `settings.ready.policy` (no per-run override — AC-4 forbids new surface),
+ * parse the issue's Non-Goals for report-only classification, wrap
+ * `executePhaseWithRetry` as the gate's phase runner, and delegate the whole
+ * qa→loop→qa loop to `runReadyGate`. The token budget stays disabled (parity
+ * with `sequant ready` invoked without `--budget`); the `maxIterations` cap
+ * already bounds cost.
+ *
+ * A gate failure is non-fatal: the standard-phase work is already committed to
+ * the worktree, so we log a warning and fall through to normal PR creation
+ * rather than aborting the run (the issue then keeps its `ready_for_merge`
+ * status — the run has degraded to a standard run, and nothing about the work
+ * is actually blocked).
+ *
+ * The failure is returned rather than swallowed. A dropped gate must not be
+ * invisible: the caller opted in with `--ready-gate`, so a run whose gate never
+ * executed has to look different in the summary from one that gated cleanly —
+ * otherwise a crashed gate is indistinguishable from an approved one, and the
+ * whole point of the flag (a second look actually happened) is silently lost.
+ */
+async function runReadyGateForIssue(args) {
+    const { issueNumber, worktreePath, config, shutdownManager, phasePauseHandle, onProgress, log, } = args;
+    const runGate = args.runGate ?? runReadyGate;
+    const getSettingsFn = args.getSettingsFn ?? getSettings;
+    const fetchBody = args.fetchBody ??
+        ((n) => new GitHubProvider().fetchIssueBodySync(String(n)));
+    try {
+        const settings = await getSettingsFn();
+        const policy = settings.ready.policy;
+        // Non-Goals feed the gate's report-only classification (ac mode never
+        // auto-fixes Non-Goal-touching findings). Best-effort — an unavailable
+        // body just yields no Non-Goals.
+        const body = fetchBody(issueNumber);
+        const nonGoals = body ? parseNonGoals(body) : [];
+        // The gate's phase runner: same executePhaseWithRetry wrapper ready.ts
+        // uses, bound to this issue's worktree, shutdown manager, and pause handle.
+        const runPhase = (phase, phaseConfig, wt) => executePhaseWithRetry(issueNumber, phase, phaseConfig, undefined, wt, shutdownManager, phasePauseHandle);
+        log(chalk.blue(`\n  Ready gate (#817) — policy: ${policy}, max iterations: ${config.maxIterations}`));
+        const result = await runGate({
+            issueNumber,
+            worktreePath,
+            policy,
+            maxIterations: config.maxIterations,
+            // AC-4: budget stays disabled on the run path (parity with `ready` sans
+            // `--budget`); maxIterations bounds cost.
+            tokenBudget: undefined,
+            nonGoals,
+            phaseTimeout: config.phaseTimeout,
+            mcp: config.mcp,
+            verbose: config.verbose,
+            runPhase,
+            onProgress,
+        });
+        log(result.ready
+            ? chalk.green(`  ✓ Ready gate: ${result.reason} — awaiting human merge (never merged)`)
+            : chalk.yellow(`  ⚠️  Ready gate halted: ${result.reason} — needs human review`));
+        return { result };
+    }
+    catch (err) {
+        // Non-fatal: keep the run going to PR with the standard status, but hand
+        // the reason back so the summary can say the gate did NOT run.
+        const error = err instanceof Error ? err.message : String(err);
+        log(chalk.yellow(`  ⚠️  Ready gate failed for #${issueNumber}: ${error} — continuing to PR without the gate.`));
+        return { error };
+    }
+}
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
     const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
@@ -335,6 +646,10 @@ export async function runIssueWithLogging(ctx) {
     let loopTriggered = false;
     // Cross-phase resume token, driver-tagged and cwd-bound (#674).
     let resumeHandle;
+    // #804 AC-6: ONE ledger for the whole issue. Created here rather than inside
+    // `executePhaseWithRetry` because the bound and the budget are per-issue —
+    // a per-phase ledger would silently grant every phase its own full budget.
+    const autoWaitLedger = createAutoWaitLedger(config.autoWaitMinutes);
     // In parallel mode, suppress per-issue terminal output to prevent interleaving.
     // The caller (run.ts) handles progress display via updateProgress().
     const log = config.parallel ? () => { } : console.log.bind(console);
@@ -368,6 +683,19 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // #860: persist auto-wait transitions to issue state so `sequant status`
+    // reports "waiting until <wake>" instead of an hours-stale in-progress
+    // phase. Fire-and-forget — state bookkeeping must never disturb the wait
+    // it describes.
+    const makeWaitTransition = (phase) => stateManager
+        ? (wakeAtMs) => {
+            void stateManager
+                .updateAutoWait(issueNumber, phase, wakeAtMs)
+                .catch(() => {
+                // Never let state bookkeeping disturb a live wait.
+            });
+        }
+        : undefined;
     // Activate relay (#383) if enabled. Tolerates errors — relay must never
     // block the underlying run.
     let relayActivation = null;
@@ -420,8 +748,10 @@ export async function runIssueWithLogging(ctx) {
         }
         const specStartTime = new Date();
         // Note: spec runs in main repo (not worktree) for planning
-        const specResult = await executePhaseWithRetry(issueNumber, "spec", withActivityHook(config, issueNumber, "spec", onProgress), resumeHandle, worktreePath, // Will be ignored for spec (non-isolated phase)
-        shutdownManager, phasePauseHandle);
+        const specResult = await executePhaseWithRetry(issueNumber, "spec", withActivityHook(config, issueNumber, "spec", onProgress, makeWaitTransition("spec")), resumeHandle, worktreePath, // Will be ignored for spec (non-isolated phase)
+        shutdownManager, phasePauseHandle, undefined, // executePhaseFn — use the default
+        undefined, // delayFn — use the default
+        autoWaitLedger);
         const specEndTime = new Date();
         if (specResult.resumeHandle) {
             resumeHandle = specResult.resumeHandle;
@@ -450,16 +780,19 @@ export async function runIssueWithLogging(ctx) {
             }
         }
         else {
-            // Mirror the main phase loop (#739): a turn-capped spec phase surfaces the
-            // distinct "partial output preserved" signal rather than a generic failure
-            // reason, so the cap is recognizable on the spec path too (it has its own
-            // failure handling, separate from the main loop). The partial output is
-            // preserved in `phaseResults` (pushed above) and the run still halts via
-            // the early return below.
+            // Mirror the main phase loop (#739/#799): a turn-capped spec phase surfaces
+            // the distinct "partial output preserved" signal, and a billing /
+            // rate-limit-window failure names the real cause — so both are recognizable
+            // on the spec path too (it has its own failure handling, separate from the
+            // main loop). The spec phase already halts on any failure via the early
+            // return below; routing billing through billingHaltReason only keeps the
+            // message/fallback symmetric with the main loop.
             const extra = {
                 error: specResult.capped
                     ? "turn cap reached — partial output preserved (resume to continue)"
-                    : (specResult.error ?? "unknown"),
+                    : isBillingOrWindowHalt(specResult)
+                        ? billingHaltReason(specResult)
+                        : (specResult.error ?? "unknown"),
             };
             emitProgressLine(issueNumber, "spec", "failed", extra);
             try {
@@ -517,6 +850,9 @@ export async function runIssueWithLogging(ctx) {
                 // State tracking errors shouldn't stop execution
             }
         }
+        // Durable halt-and-resume (#892 AC-1): a waitable-window spec halt writes
+        // `resumeAt` so `sequant resume` can re-enter after the window reopens.
+        await recordWindowHaltState(stateManager, issueNumber, "spec", specResult);
         if (!specResult.success) {
             const durationSeconds = (Date.now() - startTime) / 1000;
             // Archive relay state on early exit (spec failure).
@@ -542,22 +878,35 @@ export async function runIssueWithLogging(ctx) {
                 failureCategory: deriveFailureCategory(phaseResults),
             };
         }
-        // Parse recommended workflow from spec output
-        const parsedWorkflow = specResult.output
-            ? parseRecommendedWorkflow(specResult.output)
-            : null;
-        if (parsedWorkflow) {
-            // Remove spec from phases since we already ran it
-            phases = parsedWorkflow.phases.filter((p) => p !== "spec");
-            detectedQualityLoop = parsedWorkflow.qualityLoop;
-            log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        // Resolve the spec→run phase recommendation through the ordered chain
+        // comment-marker → comment-prose → chat-text → label-fallback (#921).
+        // Chat-text parsing alone is nondeterministic: the spec agent's plan
+        // comment is the durable artifact, but the old code only ever looked at
+        // ephemeral chat output, silently dropping recommended phases (e.g.
+        // testgen) whenever the agent posted the plan via a body file (#814).
+        const resolved = resolveSpecRecommendation({
+            chatOutput: specResult.output ?? "",
+            issueNumber,
+            labels,
+        });
+        // `resolveSpecRecommendation` already excludes "spec" regardless of
+        // which step in the chain produced the result.
+        phases = resolved.phases;
+        detectedQualityLoop = resolved.qualityLoop;
+        if (logWriter) {
+            logWriter.setSpecRecommendation({ source: resolved.source, phases, qualityLoop: detectedQualityLoop }, issueNumber);
+        }
+        if (resolved.source === "marker") {
+            log(chalk.gray(`    Spec recommends (marker): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        }
+        else if (resolved.source === "comment-prose") {
+            log(chalk.gray(`    Spec recommends (comment): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        }
+        else if (resolved.source === "chat") {
+            log(chalk.gray(`    Spec recommends (chat): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
         }
         else {
-            // Fall back to label-based detection
             log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
-            const detected = detectPhasesFromLabels(labels);
-            phases = detected.phases.filter((p) => p !== "spec");
-            detectedQualityLoop = detected.qualityLoop;
             log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
         }
     }
@@ -640,6 +989,11 @@ export async function runIssueWithLogging(ctx) {
     // retry too, not just the inner /loop spawn — re-running a capped phase
     // would only cap again, and "surface + halt" means the user resumes.
     let haltedByCap = false;
+    // Set when a phase fails with a billing / out-of-credits error or a
+    // window-exhausted rate limit (#799): like the turn cap, re-running the phase
+    // (or spawning /loop) cannot succeed while the window is closed, so halt the
+    // outer quality loop and let the user resume once credits/window are restored.
+    let haltedByBilling = false;
     while (iteration < maxIterations) {
         iteration++;
         if (useQualityLoop && iteration > 1) {
@@ -671,8 +1025,24 @@ export async function runIssueWithLogging(ctx) {
                     // State tracking errors shouldn't stop execution
                 }
             }
+            // #915: iteration > 1 is the outer quality-loop's retry signal — the
+            // same condition that triggers the "Quality loop iteration" log line
+            // above. This loop re-runs the WHOLE `phases` list on every iteration
+            // (it does not resume from the specific phase that failed), so the
+            // escalation is per RETRIED ITERATION, not per specific-phase-that-
+            // previously-failed: every phase dispatched while iteration > 1
+            // escalates, including one that already succeeded on iteration 1 (e.g.
+            // exec re-running alongside a retried qa). `withEscalatedEffort` is a
+            // no-op (returns the input config by reference) whenever escalation is
+            // off or this is the first attempt.
+            const { config: dispatchConfig, record: escalationRecord } = withEscalatedEffort(withActivityHook(issueConfig, issueNumber, phase, onProgress, makeWaitTransition(phase)), phase, iteration > 1);
+            if (escalationRecord && config.verbose) {
+                log(chalk.gray(`    effort: ${escalationRecord.base} → ${escalationRecord.escalated} (loop retry)`));
+            }
             const phaseStartTime = new Date();
-            const result = await executePhaseWithRetry(issueNumber, phase, withActivityHook(issueConfig, issueNumber, phase, onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
+            const result = await executePhaseWithRetry(issueNumber, phase, dispatchConfig, resumeHandle, worktreePath, shutdownManager, phasePauseHandle, undefined, // executePhaseFn — use the default
+            undefined, // delayFn — use the default
+            autoWaitLedger);
             const phaseEndTime = new Date();
             // Capture resume handle for subsequent phases (#674).
             if (result.resumeHandle) {
@@ -686,7 +1056,15 @@ export async function runIssueWithLogging(ctx) {
                     }
                 }
             }
-            phaseResults.push(result);
+            phaseResults.push(escalationRecord
+                ? {
+                    ...result,
+                    escalatedEffort: {
+                        base: escalationRecord.base,
+                        escalated: escalationRecord.escalated,
+                    },
+                }
+                : result);
             // Emit completion/failure progress event (AC-8)
             const phaseDurationSec = Math.round((phaseEndTime.getTime() - phaseStartTime.getTime()) / 1000);
             if (result.success) {
@@ -709,7 +1087,12 @@ export async function runIssueWithLogging(ctx) {
                 const extra = {
                     error: result.capped
                         ? "turn cap reached — partial output preserved (resume to continue)"
-                        : (result.error ?? "unknown"),
+                        : isBillingOrWindowHalt(result)
+                            ? // Billing / rate-limit-window halt (#799): name the real cause so
+                                // the run summary doesn't cascade into a downstream
+                                // `QA completed without a parseable verdict`.
+                                billingHaltReason(result)
+                            : (result.error ?? "unknown"),
                     iteration,
                 };
                 emitProgressLine(issueNumber, phase, "failed", extra);
@@ -722,13 +1105,21 @@ export async function runIssueWithLogging(ctx) {
             }
             // Log phase result with observability data (AC-1, AC-2, AC-3, AC-7)
             if (logWriter) {
+                // Resolve the diff base once (#878): worktrees branch from
+                // origin/<base>, so both the diff stats and the phase-commit check
+                // must compare against the resolved ref, not the local branch name.
+                const resolvedDiffBase = worktreePath
+                    ? resolveDiffBase(worktreePath, baseBranch ?? "main")
+                    : undefined;
                 // Capture git diff stats for worktree phases (AC-1, AC-3)
-                const diffStats = worktreePath
-                    ? getGitDiffStats(worktreePath, baseBranch)
+                const diffStats = worktreePath && resolvedDiffBase
+                    ? getGitDiffStats(worktreePath, resolvedDiffBase)
                     : undefined;
-                // Capture commit hash after phase (AC-2)
+                // Capture commit hash after phase (AC-2) — undefined when the branch
+                // never moved off its base, so a base tip is not logged as the
+                // phase's commit (#878).
                 const commitHash = worktreePath
-                    ? getCommitHash(worktreePath)
+                    ? getCommitHash(worktreePath, resolvedDiffBase)
                     : undefined;
                 // Read cache metrics for QA phase (AC-7)
                 const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
@@ -789,6 +1180,9 @@ export async function runIssueWithLogging(ctx) {
                     // State tracking errors shouldn't stop execution
                 }
             }
+            // Durable halt-and-resume (#892 AC-1): a waitable-window halt writes
+            // `resumeAt`; success or a non-window failure clears any stale record.
+            await recordWindowHaltState(stateManager, issueNumber, phase, result);
             if (result.success) {
                 // Phase succeeded — RunRenderer (#618) updates state via onProgress.
             }
@@ -797,12 +1191,24 @@ export async function runIssueWithLogging(ctx) {
                 if (result.capped) {
                     haltedByCap = true;
                 }
+                // Billing / rate-limit-window failure (#799): halt the outer quality
+                // loop for the same reason as the turn cap — re-running the phase or
+                // spawning /loop cannot succeed while credits/window are exhausted, and
+                // doing so mislabels the halt as a downstream unparseable-verdict error.
+                if (isBillingOrWindowHalt(result)) {
+                    haltedByBilling = true;
+                }
                 // If quality loop enabled, run loop phase to fix issues.
                 // A turn-capped phase (#739) is incomplete, not a genuine quality
                 // failure: skip the loop and halt cleanly ("surface + halt"). Spawning
                 // /loop on partial output would act on incomplete work — exactly the
                 // risk the capped path is meant to avoid. The user resumes instead.
-                if (useQualityLoop && iteration < maxIterations && !result.capped) {
+                // A billing / rate-limit-window halt (#799) is skipped for the same
+                // reason: /loop would re-spawn into the same closed window.
+                if (useQualityLoop &&
+                    iteration < maxIterations &&
+                    !result.capped &&
+                    !haltedByBilling) {
                     // #624 Item 3 (AC-3.3): the loop phase carries the current outer
                     // iteration so the live-zone status cell can show `loop N/M`.
                     const loopStartExtra = { iteration };
@@ -823,7 +1229,9 @@ export async function runIssueWithLogging(ctx) {
                         promptContext: buildLoopContext(result),
                     };
                     const loopStartTime = new Date();
-                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
+                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress, makeWaitTransition("loop")), resumeHandle, worktreePath, shutdownManager, phasePauseHandle, undefined, // executePhaseFn — use the default
+                    undefined, // delayFn — use the default
+                    autoWaitLedger);
                     const loopEndTime = new Date();
                     phaseResults.push(loopResult);
                     // #766: record the loop phase in the run log — spec (:655) and the
@@ -884,7 +1292,9 @@ export async function runIssueWithLogging(ctx) {
         }
         // A turn-capped phase (#739) halts the outer quality-loop retry as well —
         // re-running would only cap again; the partial work is already preserved.
-        if (haltedByCap) {
+        // A billing / rate-limit-window failure (#799) halts for the same reason:
+        // the retry re-spawns into the same closed window and cannot progress.
+        if (haltedByCap || haltedByBilling) {
             break;
         }
         // If we're not in quality loop mode, don't retry
@@ -896,10 +1306,42 @@ export async function runIssueWithLogging(ctx) {
     // Success is determined by whether all phases completed in any iteration,
     // not whether all accumulated phase results passed (which would fail after loop recovery)
     const success = completedSuccessfully;
-    // Update final issue status in state
+    // #817: opt-in post-QA ready gate. When the standard phases succeed AND
+    // `--ready-gate` was passed, drive the existing `sequant ready` engine
+    // (qa→loop→qa to the configured policy) against this worktree BEFORE
+    // checkpoint/rebase/PR — so the gate's auto-fix commits land in the PR. The
+    // engine NEVER merges; it terminates with the issue `waiting_for_human_merge`
+    // (ready) or `blocked` (guard halt). Without the flag this block is skipped
+    // entirely, keeping the run path byte-identical (AC-5).
+    const readyGateOutcome = config.readyGate && success && worktreePath
+        ? await runReadyGateForIssue({
+            issueNumber,
+            worktreePath,
+            config,
+            shutdownManager,
+            phasePauseHandle,
+            onProgress,
+            log,
+        })
+        : undefined;
+    const readyGateResult = readyGateOutcome?.result;
+    // Surfaced separately from `readyGateResult` so a gate that *crashed* renders
+    // differently in the summary from one that ran — a silently-skipped gate on a
+    // run the user explicitly opted into is the failure mode worth naming.
+    const readyGateError = readyGateOutcome?.error;
+    // Update final issue status in state. When the gate ran it owns the terminal
+    // status (never `ready_for_merge` — that would read as auto-merge-ready and
+    // defeat the human merge gate the gate deliberately stops at).
+    // Hoisted out of the `if (stateManager)` block below because the checkpoint
+    // warning also has to name this status, and naming the wrong one is exactly
+    // the #837 inaccuracy being fixed here.
+    const finalStatus = readyGateResult
+        ? readyGateResult.issueStatus
+        : success
+            ? "ready_for_merge"
+            : "in_progress";
     if (stateManager) {
         try {
-            const finalStatus = success ? "ready_for_merge" : "in_progress";
             await stateManager.updateIssueStatus(issueNumber, finalStatus);
         }
         catch {
@@ -910,11 +1352,17 @@ export async function runIssueWithLogging(ctx) {
     // #760: chain resume rebases the next link onto this checkpoint, so a failure
     // here is not silent — warn prominently and record it on the result (AC-4).
     //
-    // Note the status above is already `ready_for_merge`, so a re-run reads this
-    // link as a completed prefix and does NOT redo it. Its uncommitted work is
-    // therefore absent from the branch tip, which `computeChainResumePlan` detects
-    // (dirty worktree → fail fast) rather than wrong-basing the next link. The
-    // message states that outcome exactly: the work must be committed, or --force.
+    // Note a completed status was already written above — `ready_for_merge`, or
+    // `waiting_for_human_merge` when #817's `--ready-gate` owned the terminal
+    // status (#837) — so a re-run reads this link as a completed prefix and does
+    // NOT redo it. Its uncommitted work is therefore absent from the branch tip,
+    // which `computeChainResumePlan` detects (dirty worktree → fail fast) rather
+    // than wrong-basing the next link. The message states that outcome exactly:
+    // the work must be committed, or --force.
+    //
+    // A gate that halted (`blocked`) is NOT a completed prefix, so that link is
+    // re-executed on resume rather than skipped — see COMPLETED_STATUSES in
+    // chain-resume.ts.
     let checkpointFailed = false;
     if (success && chainMode && worktreePath) {
         const checkpointOk = createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
@@ -922,7 +1370,7 @@ export async function runIssueWithLogging(ctx) {
             checkpointFailed = true;
             log(chalk.yellow(`  ⚠️  Checkpoint commit for #${issueNumber} could not be created — its uncommitted ` +
                 `changes are NOT on branch ${branch ?? "the feature branch"}. #${issueNumber} stays ` +
-                `ready_for_merge, so a re-run will skip it and refuse to resume the chain here until the ` +
+                `${finalStatus}, so a re-run will skip it and refuse to resume the chain here until the ` +
                 `work is committed in ${worktreePath} (or re-run with --force to redo the whole chain).`));
         }
     }
@@ -941,7 +1389,27 @@ export async function runIssueWithLogging(ctx) {
     // Create PR after successful QA + rebase (unless --no-pr)
     let prNumber;
     let prUrl;
-    const shouldCreatePR = success && worktreePath && branch && !options.noPr;
+    // #879: a PR-creation failure after passing QA must fail the run, not print a
+    // warning and leave the issue at `success`. Recorded here and folded into the
+    // returned `success` below.
+    let prCreationError;
+    const wouldCreatePR = success && worktreePath && branch && !options.noPr;
+    // #920: a phase-restricted run (e.g. `--phases spec`) provisions a worktree
+    // and branch unconditionally of which phases ran, so a clean spec-only pass
+    // satisfies every conjunct above with zero commits — `gh pr create` then
+    // fails with "No commits between main and …" and the run reports failed
+    // for work that landed exactly where it was supposed to (the plan comment).
+    // Gate on the evidence (commits ahead of base) rather than the phase list:
+    // `hasExecChanges` fails open (`unknown` counts as "has changes") so a git
+    // error here falls through to today's attempt-PR behavior, and it resolves
+    // the base the same #537-aware way `classifyExecChanges` already does for
+    // the exec zero-diff guard.
+    let prSkippedReason;
+    if (wouldCreatePR && !hasExecChanges(worktreePath)) {
+        prSkippedReason = `no commits ahead of ${baseBranch ?? "main"} (no implementing phase ran)`;
+        log(chalk.gray(`    ℹ️  PR skipped — ${prSkippedReason}`));
+    }
+    const shouldCreatePR = wouldCreatePR && !prSkippedReason;
     if (shouldCreatePR) {
         // #605: under --stacked, target predecessor branch (only for non-first,
         // non-last issues). Last PR keeps `main` so partial progress can land.
@@ -954,7 +1422,10 @@ export async function runIssueWithLogging(ctx) {
         // #749: surface a non-A+ qa verdict (e.g. AC_MET_BUT_NOT_A_PLUS) in the PR
         // body so a reviewer sees why the run broke to PR rather than reaching A+.
         const qaVerdict = phaseResults.find((p) => p.phase === "qa")?.verdict;
-        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions, qaVerdict);
+        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions, qaVerdict, 
+        // #817 AC-6: surface the ready-gate outcome in the PR body the same way
+        // `sequant ready` reports it (threshold reached vs guard halt).
+        readyGateResult?.report);
         if (prResult.success && prResult.prNumber && prResult.prUrl) {
             prNumber = prResult.prNumber;
             prUrl = prResult.prUrl;
@@ -971,6 +1442,11 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
         }
+        else if (prResult.attempted && !prResult.success) {
+            // #879: PR creation was attempted (branch/QA passed) but failed. This is
+            // a run failure — the deliverable never reached GitHub.
+            prCreationError = prResult.error ?? "PR creation failed";
+        }
     }
     // Deactivate relay (#383) — archive inbox/outbox transcripts to
     // .sequant/logs/relay/ before worktree teardown (AC-D2). Never throws.
@@ -989,15 +1465,31 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // #879: fold a PR-creation failure into the issue's overall verdict. Phases
+    // all passed, but the run did not deliver — report it as failed.
+    const overallSuccess = success && !prCreationError;
     return {
         issueNumber,
-        success,
+        success: overallSuccess,
         phaseResults,
         durationSeconds,
         loopTriggered,
         prNumber,
         prUrl,
+        prCreationError,
+        prSkippedReason,
         checkpointFailed,
-        failureCategory: success ? undefined : deriveFailureCategory(phaseResults),
+        failureCategory: overallSuccess
+            ? undefined
+            : // #920: a PR-creation failure has no failed phase for
+                // `deriveFailureCategory` to classify — fall back to the dedicated
+                // category so the metrics residual from #879 (empty failureCategory
+                // on a PR-only failure) doesn't reopen for this failure path.
+                (deriveFailureCategory(phaseResults) ??
+                    (prCreationError ? "pr_creation" : undefined)),
+        // #817: present only when `--ready-gate` ran the gate; the summary renders
+        // its terminal reason (AC-6).
+        readyGate: readyGateResult,
+        readyGateError,
     };
 }