sequant 2.7.0 → 2.8.0

package/dist/src/lib/version-check.js

@@ -258,6 +258,50 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Pure preflight check for the running Node version against the engines floor.
+ *
+ * Returns an actionable, multi-line message when `current` is below `floor`,
+ * or `null` when it satisfies the floor (or when `floor` is missing/unparseable,
+ * in which case the guard is skipped rather than crashing the CLI).
+ *
+ * `floor` is the raw `engines.node` value (e.g. ">=22.12.0"); the leading range
+ * operator is stripped before comparison. Reuses {@link compareVersions} — no
+ * `semver` dependency.
+ */
+export function getNodeVersionError(current, floor) {
+    // Strip any range operator (">=", "^", "~", etc.) from the floor.
+    const normalizedFloor = (floor ?? "").replace(/^[^\d]*/, "");
+    // No usable floor → skip the guard (metadata problem must not crash the CLI).
+    if (!/^\d/.test(normalizedFloor)) {
+        return null;
+    }
+    if (compareVersions(current, normalizedFloor) >= 0) {
+        return null;
+    }
+    const currentClean = current.replace(/^v/, "");
+    return [
+        `Sequant requires Node.js >=${normalizedFloor}, but you are running ${currentClean}.`,
+        "",
+        "Upgrade Node, then re-run:",
+        "  • fnm:          fnm install 22 && fnm use 22",
+        "  • nvm:          nvm install 22 && nvm use 22",
+        "  • or download:  https://nodejs.org/en/download",
+    ].join("\n");
+}
+/**
+ * Side-effecting wrapper around {@link getNodeVersionError}: prints the message
+ * and exits non-zero when the running Node is below the floor. Uses only
+ * built-in globals (`process.version`, `console`, `process.exit`) so it runs —
+ * rather than crashes — on the old Node it rejects.
+ */
+export function assertNodeVersion(floor) {
+    const error = getNodeVersionError(process.version, floor);
+    if (error) {
+        console.error(error);
+        process.exit(1);
+    }
+}
 /**
  * Check if the current version is outdated
  */

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

@@ -432,7 +432,17 @@ export async function runIssueWithLogging(ctx) {
             }
         }
         else {
-            const extra = { error: specResult.error ?? "unknown" };
+            // 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.
+            const extra = {
+                error: specResult.capped
+                    ? "turn cap reached — partial output preserved (resume to continue)"
+                    : (specResult.error ?? "unknown"),
+            };
             emitProgressLine(issueNumber, "spec", "failed", extra);
             try {
                 onProgress?.(issueNumber, "spec", "failed", extra);
@@ -462,7 +472,13 @@ export async function runIssueWithLogging(ctx) {
                 ? "success"
                 : specResult.error?.includes("Timeout")
                     ? "timeout"
-                    : "failure", { error: specResult.error, errorContext: specErrorContext });
+                    : "failure", {
+                error: specResult.error,
+                // Mark a turn-capped spec phase distinctly in the log (#739), matching
+                // the main phase loop: status stays "failure" but `capped` flags it.
+                capped: specResult.capped,
+                errorContext: specErrorContext,
+            });
             logWriter.logPhase(phaseLog);
         }
         // Track spec phase completion in state
@@ -471,6 +487,9 @@ export async function runIssueWithLogging(ctx) {
                 const phaseStatus = specResult.success ? "completed" : "failed";
                 await stateManager.updatePhaseStatus(issueNumber, "spec", phaseStatus, {
                     error: specResult.error,
+                    // Mark a turn-capped spec halt distinctly in state (#739), matching
+                    // the run-log marker — status stays "failed", `capped` flags it.
+                    capped: specResult.capped,
                 });
             }
             catch {
@@ -595,6 +614,10 @@ export async function runIssueWithLogging(ctx) {
     const useQualityLoop = config.qualityLoop || detectedQualityLoop;
     const maxIterations = useQualityLoop ? config.maxIterations : 1;
     let completedSuccessfully = false;
+    // Set when a phase hits its turn cap (#739): halt the outer quality-loop
+    // 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;
     while (iteration < maxIterations) {
         iteration++;
         if (useQualityLoop && iteration > 1) {
@@ -655,7 +678,18 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             else {
-                const extra = { error: result.error ?? "unknown", iteration };
+                // A turn-capped phase is incomplete-but-not-hard-failed (#739): surface a
+                // distinct "partial output preserved" signal instead of a generic failure
+                // reason, so the user knows the run halted on a recoverable cap (and can
+                // resume) rather than on a genuine error. The partial `result.output` is
+                // already preserved in `phaseResults` (pushed above) and the phase log
+                // (`capped` flag below); the run still halts cleanly at the `break` below.
+                const extra = {
+                    error: result.capped
+                        ? "turn cap reached — partial output preserved (resume to continue)"
+                        : (result.error ?? "unknown"),
+                    iteration,
+                };
                 emitProgressLine(issueNumber, phase, "failed", extra);
                 try {
                     onProgress?.(issueNumber, phase, "failed", extra);
@@ -696,6 +730,9 @@ export async function runIssueWithLogging(ctx) {
                         ? "timeout"
                         : "failure", {
                     error: result.error,
+                    // Mark a turn-capped phase distinctly in the log (#739): status stays
+                    // "failure" (no new enum value) but `capped` flags it as recoverable.
+                    capped: result.capped,
                     verdict: result.verdict,
                     summary: result.summary,
                     // Observability fields (AC-1, AC-2, AC-3, AC-7)
@@ -715,7 +752,13 @@ export async function runIssueWithLogging(ctx) {
                         : result.error?.includes("Timeout")
                             ? "failed"
                             : "failed";
-                    await stateManager.updatePhaseStatus(issueNumber, phase, phaseStatus, { error: result.error });
+                    await stateManager.updatePhaseStatus(issueNumber, phase, phaseStatus, {
+                        error: result.error,
+                        // Mark a turn-capped phase halt distinctly in state (#739),
+                        // matching the run-log marker — status stays "failed",
+                        // `capped` flags it as recoverable for the resume path.
+                        capped: result.capped,
+                    });
                 }
                 catch {
                     // State tracking errors shouldn't stop execution
@@ -726,8 +769,15 @@ export async function runIssueWithLogging(ctx) {
             }
             else {
                 phasesFailed = true;
-                // If quality loop enabled, run loop phase to fix issues
-                if (useQualityLoop && iteration < maxIterations) {
+                if (result.capped) {
+                    haltedByCap = 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) {
                     // #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 };
@@ -790,6 +840,11 @@ export async function runIssueWithLogging(ctx) {
             completedSuccessfully = true;
             break;
         }
+        // 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) {
+            break;
+        }
         // If we're not in quality loop mode, don't retry
         if (!config.qualityLoop) {
             break;

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -5,6 +5,7 @@
  * Continue.dev, Copilot SDK, Cursor API) can be added by implementing this
  * interface without touching orchestration logic.
  */
+import type { SequantError } from "../../errors.js";
 /**
  * Resume handle for a previous agent session.
  *
@@ -64,6 +65,22 @@ export interface AgentPhaseResult {
     /** Driver-tagged resume handle for cwd-safe cross-phase resume (#674). */
     resumeHandle?: ResumeHandle;
     error?: string;
+    /**
+     * Set when the agent hit its `maxTurns` ceiling (`error_max_turns`). The
+     * `output` is partial-but-usable rather than a hard failure, so consumers
+     * can treat it as inconclusive/incomplete instead of discarding the work.
+     * See #733.
+     */
+    capped?: boolean;
+    /**
+     * Typed error carrying structured cause data (#732). Set by drivers that can
+     * observe structured failure signals (e.g. ClaudeCodeDriver reading the SDK's
+     * `rate_limit_event` / assistant `error`). The executor prefers this over
+     * stderr-regex classification and uses its type to gate retry behavior (e.g.
+     * skipping the MCP fallback for non-retryable billing failures). Left
+     * undefined by drivers without structured signals (aider, subprocess paths).
+     */
+    structuredError?: SequantError;
     /** Last N lines of stderr captured via RingBuffer (#447) */
     stderrTail?: string[];
     /** Last N lines of stdout captured via RingBuffer (#447) */

package/dist/src/lib/workflow/drivers/claude-code.d.ts

@@ -28,6 +28,28 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      */
     canResume(handle: ResumeHandle, targetCwd: string): boolean;
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
+    /**
+     * Derive a typed {@link SequantError} from structured SDK failure signals
+     * (#732). Precedence: a captured `rate_limit_event` (richest signal) wins;
+     * otherwise the assistant-level `error`; otherwise the last `api_retry`
+     * error. Returns undefined when no rate-limit/billing signal was seen, so
+     * the executor falls back to stderr-regex classification.
+     *
+     * Exception: a non-retryable billing failure must never be downgraded to a
+     * retryable {@link RateLimitError}. If the `rate_limit_event` was only a
+     * transient throttle but the assistant separately reported `billing_error`,
+     * the billing cause wins — a retry cannot refill credits, and a
+     * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
+     * the `rate_limit_event` is itself a billing failure its richer metadata
+     * (`canUserPurchaseCredits`, etc.) is preserved.
+     */
+    private buildStructuredError;
+    /**
+     * Map the SDK's assistant/api-retry error enum to a typed error. Only
+     * rate-limit / billing variants are mapped; other variants (auth, etc.)
+     * return undefined and defer to the existing classification path.
+     */
+    private errorFromAssistantError;
     private buildResumeHandle;
     isAvailable(): Promise<boolean>;
 }

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -6,6 +6,7 @@
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getMcpServersConfig } from "../../system.js";
+import { RateLimitError, BillingError, createRateLimitError, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
     name = "claude-code";
@@ -47,6 +48,16 @@ export class ClaudeCodeDriver {
         let resultMessage;
         let capturedOutput = "";
         let capturedStderr = "";
+        // Structured rate-limit / billing signals captured from the SDK stream
+        // (#732). The SDK emits these but sequant previously dropped them on the
+        // floor, falling back to regex-on-stderr classification. We keep only the
+        // latest *failure-grade* rate-limit info (rejection or billing) so an
+        // informational `allowed_warning` event isn't mis-attributed to an
+        // unrelated phase failure.
+        let rateLimitInfo;
+        let assistantError;
+        // Last api_retry signal, captured opportunistically for diagnostics.
+        let apiRetryError;
         const stderrBuffer = new RingBuffer(50);
         const stdoutBuffer = new RingBuffer(50);
         // Resolve resume token with cwd-safety check.
@@ -99,7 +110,26 @@ export class ClaudeCodeDriver {
                 if (message.type === "system" && message.subtype === "init") {
                     resultSessionId = message.session_id;
                 }
+                // Capture structured rate-limit info (#732). Only retain
+                // failure-grade events (rejection / billing) so a benign warning
+                // doesn't poison the failure path.
+                if (message.type === "rate_limit_event" &&
+                    isRateLimitFailureInfo(message.rate_limit_info)) {
+                    rateLimitInfo = message.rate_limit_info;
+                }
+                // Capture api_retry diagnostics (#732, optional). These are transient
+                // retries the SDK performs internally; recorded for the structured
+                // error fallback when no rate_limit_event/assistant error is present.
+                if (message.type === "system" && message.subtype === "api_retry") {
+                    apiRetryError = message.error;
+                }
                 if (message.type === "assistant") {
+                    // Capture the assistant-level error field (#732) — `rate_limit`,
+                    // `billing_error`, `overloaded`, etc. Previously discarded by the
+                    // text-only content filter below.
+                    if (message.error) {
+                        assistantError = message.error;
+                    }
                     const content = message.message.content;
                     const textContent = content
                         .filter((c) => c.type === "text" && c.text)
@@ -124,6 +154,10 @@ export class ClaudeCodeDriver {
             // `config.cwd`. `sessionId` is mirrored for one release (#674) so
             // upgraded callers can still drive resume off the deprecated field.
             const resumeHandle = this.buildResumeHandle(resultSessionId, config.cwd);
+            // Build a typed error from structured SDK signals (#732). Present only
+            // when the stream surfaced a rate-limit/billing failure; otherwise
+            // undefined and the executor falls back to stderr-regex classification.
+            const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             if (resultMessage) {
                 if (resultMessage.subtype === "success") {
                     return {
@@ -135,13 +169,29 @@ export class ClaudeCodeDriver {
                         stdoutTail: stdoutBuffer.getLines(),
                     };
                 }
+                // Turn-cap is a soft, recoverable outcome, not a hard failure: the
+                // agent produced partial work before hitting its `maxTurns` ceiling
+                // (turn caps are live on every agent since #484). Warn (not error)
+                // and return the partial output flagged `capped` so consumers — the
+                // /qa and /exec skills — can treat it as inconclusive/incomplete
+                // rather than discarding the work. See #733. Branched out of the
+                // error switch below so it never carries a hard `error` string.
+                if (resultMessage.subtype === "error_max_turns") {
+                    config.onStderr?.("⚠️ Agent hit its turn cap (error_max_turns). Returning partial results.\n");
+                    return {
+                        success: false,
+                        capped: true,
+                        output: capturedOutput,
+                        sessionId: resultSessionId,
+                        resumeHandle,
+                        stderrTail: stderrBuffer.getLines(),
+                        stdoutTail: stdoutBuffer.getLines(),
+                    };
+                }
                 // Handle error subtypes
                 let error;
                 const errorSubtype = resultMessage.subtype;
-                if (errorSubtype === "error_max_turns") {
-                    error = "Max turns reached";
-                }
-                else if (errorSubtype === "error_during_execution") {
+                if (errorSubtype === "error_during_execution") {
                     error = resultMessage.errors?.join(", ") || "Error during execution";
                 }
                 else if (errorSubtype === "error_max_budget_usd") {
@@ -155,7 +205,10 @@ export class ClaudeCodeDriver {
                     output: capturedOutput,
                     sessionId: resultSessionId,
                     resumeHandle,
-                    error,
+                    // Prefer the structured cause (e.g. "Out of credits") over the
+                    // generic subtype text when available (#732).
+                    error: structuredError?.message ?? error,
+                    structuredError,
                     stderrTail: stderrBuffer.getLines(),
                     stdoutTail: stdoutBuffer.getLines(),
                 };
@@ -165,7 +218,8 @@ export class ClaudeCodeDriver {
                 output: capturedOutput,
                 sessionId: resultSessionId,
                 resumeHandle,
-                error: "No result received from Claude",
+                error: structuredError?.message ?? "No result received from Claude",
+                structuredError,
                 stderrTail: stderrBuffer.getLines(),
                 stdoutTail: stdoutBuffer.getLines(),
             };
@@ -182,6 +236,12 @@ export class ClaudeCodeDriver {
                     stdoutTail: stdoutBuffer.getLines(),
                 };
             }
+            // If the stream surfaced a failure-grade rate-limit/billing signal before
+            // throwing, prefer that typed cause (#732) over the raw thrown message — a
+            // mid-stream throw after a *rejected* rate_limit_event is very likely the
+            // proximate cause. Abort/timeout is handled above first, so a genuine
+            // timeout is never masked by a stale rate-limit signal.
+            const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             const stderrSuffix = capturedStderr
                 ? `\nStderr: ${capturedStderr.slice(0, 500)}`
                 : "";
@@ -190,12 +250,56 @@ export class ClaudeCodeDriver {
                 output: capturedOutput,
                 sessionId: resultSessionId,
                 resumeHandle: this.buildResumeHandle(resultSessionId, config.cwd),
-                error: error + stderrSuffix,
+                error: structuredError?.message ?? error + stderrSuffix,
+                structuredError,
                 stderrTail: stderrBuffer.getLines(),
                 stdoutTail: stdoutBuffer.getLines(),
             };
         }
     }
+    /**
+     * Derive a typed {@link SequantError} from structured SDK failure signals
+     * (#732). Precedence: a captured `rate_limit_event` (richest signal) wins;
+     * otherwise the assistant-level `error`; otherwise the last `api_retry`
+     * error. Returns undefined when no rate-limit/billing signal was seen, so
+     * the executor falls back to stderr-regex classification.
+     *
+     * Exception: a non-retryable billing failure must never be downgraded to a
+     * retryable {@link RateLimitError}. If the `rate_limit_event` was only a
+     * transient throttle but the assistant separately reported `billing_error`,
+     * the billing cause wins — a retry cannot refill credits, and a
+     * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
+     * the `rate_limit_event` is itself a billing failure its richer metadata
+     * (`canUserPurchaseCredits`, etc.) is preserved.
+     */
+    buildStructuredError(rateLimitInfo, assistantError, apiRetryError) {
+        if (rateLimitInfo) {
+            const err = createRateLimitError(rateLimitInfo);
+            if (err instanceof RateLimitError && assistantError === "billing_error") {
+                return new BillingError("Billing error");
+            }
+            return err;
+        }
+        return (this.errorFromAssistantError(assistantError) ??
+            this.errorFromAssistantError(apiRetryError));
+    }
+    /**
+     * Map the SDK's assistant/api-retry error enum to a typed error. Only
+     * rate-limit / billing variants are mapped; other variants (auth, etc.)
+     * return undefined and defer to the existing classification path.
+     */
+    errorFromAssistantError(error) {
+        switch (error) {
+            case "billing_error":
+                return new BillingError("Billing error");
+            case "rate_limit":
+                return new RateLimitError("Rate limited");
+            case "overloaded":
+                return new RateLimitError("API overloaded");
+            default:
+                return undefined;
+        }
+    }
     buildResumeHandle(token, originCwd) {
         if (!token)
             return undefined;

package/dist/src/lib/workflow/log-writer.d.ts

@@ -99,4 +99,4 @@ export declare class LogWriter {
  *
  * Utility function for creating phase logs when you have start/end times.
  */
-export declare function createPhaseLogFromTiming(phase: Phase, issueNumber: number, startTime: Date, endTime: Date, status: PhaseLog["status"], options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "summary" | "commitHash" | "fileDiffStats" | "cacheMetrics" | "errorContext">>): PhaseLog;
+export declare function createPhaseLogFromTiming(phase: Phase, issueNumber: number, startTime: Date, endTime: Date, status: PhaseLog["status"], options?: Partial<Pick<PhaseLog, "error" | "capped" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "summary" | "commitHash" | "fileDiffStats" | "cacheMetrics" | "errorContext">>): PhaseLog;

package/dist/src/lib/workflow/phase-executor.d.ts

@@ -111,6 +111,24 @@ export declare function mapAgentSuccessToPhaseResult(phase: Phase, agentResult:
     sessionId?: string;
     resumeHandle?: ResumeHandle;
 };
+/**
+ * Map a failed driver result to a `PhaseResult`.
+ *
+ * Symmetric to {@link mapAgentSuccessToPhaseResult}; extracted so the
+ * failure-path mapping (notably the #739 capped/output gating) is unit-testable
+ * without spawning a driver.
+ *
+ * `output` is propagated **only** for a capped phase (#739): a capped result is
+ * incomplete-but-not-hard-failed, so its partial work must survive downstream.
+ * A genuine (non-capped) failure keeps the historical behaviour of dropping
+ * `output`, leaving the `/loop` fix-context (`formatFailureContext`) unchanged.
+ *
+ * @internal Exported for testing only
+ */
+export declare function mapAgentFailureToPhaseResult(phase: Phase, agentResult: AgentPhaseResult, durationSeconds: number): PhaseResult & {
+    sessionId?: string;
+    resumeHandle?: ResumeHandle;
+};
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.

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

@@ -12,7 +12,7 @@ import { execSync, execFileSync } from "child_process";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
-import { ApiError } from "../errors.js";
+import { ApiError, BillingError } from "../errors.js";
 import { phaseRegistry } from "./phase-registry.js";
 import { bracketedConsoleLog } from "./notice.js";
 /**
@@ -408,6 +408,43 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         ...tails,
     };
 }
+/**
+ * Map a failed driver result to a `PhaseResult`.
+ *
+ * Symmetric to {@link mapAgentSuccessToPhaseResult}; extracted so the
+ * failure-path mapping (notably the #739 capped/output gating) is unit-testable
+ * without spawning a driver.
+ *
+ * `output` is propagated **only** for a capped phase (#739): a capped result is
+ * incomplete-but-not-hard-failed, so its partial work must survive downstream.
+ * A genuine (non-capped) failure keeps the historical behaviour of dropping
+ * `output`, leaving the `/loop` fix-context (`formatFailureContext`) unchanged.
+ *
+ * @internal Exported for testing only
+ */
+export function mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds) {
+    return {
+        phase,
+        success: false,
+        durationSeconds,
+        error: agentResult.error,
+        // Propagate the driver's typed cause (#732) so the retry logic can prefer
+        // it over stderr-regex classification and gate the MCP fallback.
+        structuredError: agentResult.structuredError,
+        // Propagate the turn-cap flag and the partial output (#739). On the failure
+        // path `output` was previously dropped entirely — for a capped phase the
+        // partial work is usable and must be preserved, mirroring the driver/skill
+        // slice from #733. Gating `output` on `capped` keeps non-capped failures
+        // byte-for-byte identical to pre-#739 behaviour.
+        capped: agentResult.capped,
+        output: agentResult.capped ? agentResult.output : undefined,
+        sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
+        stderrTail: agentResult.stderrTail,
+        stdoutTail: agentResult.stdoutTail,
+        exitCode: agentResult.exitCode,
+    };
+}
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -642,17 +679,7 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
     if (agentResult.success) {
         return mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
     }
-    return {
-        phase,
-        success: false,
-        durationSeconds,
-        error: agentResult.error,
-        sessionId: agentResult.sessionId,
-        resumeHandle: agentResult.resumeHandle,
-        stderrTail: agentResult.stderrTail,
-        stdoutTail: agentResult.stdoutTail,
-        exitCode: agentResult.exitCode,
-    };
+    return mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
 }
 /**
  * Execute a phase with automatic retry for cold-start failures and MCP fallback.
@@ -693,6 +720,14 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
         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;
+        }
     }
     else {
         // Phase 1: Cold-start retry attempts (with MCP enabled if configured)
@@ -703,11 +738,23 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             if (lastResult.success) {
                 return lastResult;
             }
+            // Turn-capped phase (#739): short-circuit before cold-start retries, the
+            // MCP fallback, and the spec-extra retry — a retry cannot un-cap a turn
+            // limit. The early return here (rather than a guard at the MCP gate alone)
+            // is what skips the cold-start re-spawns, unlike the billing case which
+            // still cold-start-retries in the <60s window.
+            if (lastResult.capped) {
+                return lastResult;
+            }
             // 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.
             if (duration >= COLD_START_THRESHOLD_SECONDS) {
-                const typedError = classifyError(lastResult.stderrTail ?? [], lastResult.exitCode);
+                // Prefer the driver's structured cause (#732) — it reflects the real
+                // SDK rate-limit/billing signal — over stderr-regex classification,
+                // which only sees text and never the structured data.
+                const typedError = lastResult.structuredError ??
+                    classifyError(lastResult.stderrTail ?? [], lastResult.exitCode);
                 if (typedError.isRetryable && attempt < COLD_START_MAX_RETRIES) {
                     if (config.verbose) {
                         const label = typedError instanceof ApiError
@@ -735,7 +782,22 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // Phase 2: MCP fallback - if MCP is enabled and we're still failing, try without MCP
     // This handles npx-based MCP servers that fail on first run due to cold-cache issues.
     // Skip for `loop` phase — MCP is never the cause of loop failures (#488).
-    if (config.mcp && !lastResult.success && !skipColdStartRetry) {
+    //
+    // Also skip when the failure is a billing/credits error (#732): a no-MCP
+    // retry cannot refill credits, so the misleading "retrying without MCP"
+    // noise (#592) would only mask the real cause. The accurate structured
+    // message (e.g. "Out of credits") is surfaced instead.
+    const failureIsBilling = lastResult.structuredError instanceof BillingError;
+    // Belt-and-suspenders (#739): the capped early-returns above already exit
+    // before reaching here, but gate the MCP fallback on `!failureIsCapped` too so
+    // intent is documented and future code paths can't accidentally re-spawn a
+    // capped phase without MCP.
+    const failureIsCapped = lastResult.capped === true;
+    if (config.mcp &&
+        !lastResult.success &&
+        !skipColdStartRetry &&
+        !failureIsBilling &&
+        !failureIsCapped) {
         bracketedConsoleLog(spinner, chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
         // Create config copy with MCP disabled
         const configWithoutMcp = {

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -125,6 +125,7 @@ export declare const PhaseLogSchema: z.ZodObject<{
         timeout: "timeout";
     }>;
     error: z.ZodOptional<z.ZodString>;
+    capped: z.ZodOptional<z.ZodBoolean>;
     iterations: z.ZodOptional<z.ZodNumber>;
     filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
     testsRun: z.ZodOptional<z.ZodNumber>;
@@ -201,6 +202,7 @@ export declare const IssueLogSchema: z.ZodObject<{
             timeout: "timeout";
         }>;
         error: z.ZodOptional<z.ZodString>;
+        capped: z.ZodOptional<z.ZodBoolean>;
         iterations: z.ZodOptional<z.ZodNumber>;
         filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
         testsRun: z.ZodOptional<z.ZodNumber>;
@@ -318,6 +320,7 @@ export declare const RunLogSchema: z.ZodObject<{
                 timeout: "timeout";
             }>;
             error: z.ZodOptional<z.ZodString>;
+            capped: z.ZodOptional<z.ZodBoolean>;
             iterations: z.ZodOptional<z.ZodNumber>;
             filesModified: z.ZodOptional<z.ZodArray<z.ZodString>>;
             testsRun: z.ZodOptional<z.ZodNumber>;

package/dist/src/lib/workflow/run-log-schema.js

@@ -130,6 +130,13 @@ export const PhaseLogSchema = z.object({
     status: PhaseStatusSchema,
     /** Error message if failed */
     error: z.string().optional(),
+    /**
+     * Set when the phase hit its turn cap (`error_max_turns`) (#739). Distinguishes
+     * an incomplete-but-not-hard-failed phase (partial output preserved) from a
+     * genuine failure. Reuses the `"failure"` status — additive boolean rather than
+     * a new `PhaseStatus` enum value, to keep the persisted-log schema stable.
+     */
+    capped: z.boolean().optional(),
     /** Number of iterations (for loop phase) */
     iterations: z.number().int().nonnegative().optional(),
     /** Files modified during this phase */

package/dist/src/lib/workflow/state-manager.d.ts

@@ -116,6 +116,7 @@ export declare class StateManager {
     updatePhaseStatus(issueNumber: number, phase: Phase, status: PhaseStatus, options?: {
         error?: string;
         iteration?: number;
+        capped?: boolean;
     }): Promise<void>;
     /**
      * Update the overall issue status

package/dist/src/lib/workflow/state-manager.js

@@ -300,6 +300,12 @@ export class StateManager {
             if (options?.iteration !== undefined) {
                 phaseState.iteration = options.iteration;
             }
+            // Persist the turn-cap marker (#739) so a halted-on-cap phase is
+            // distinguishable from a genuine failure in state, not just the run-log —
+            // this is what makes the "reversible later" resume path first-class.
+            if (options?.capped !== undefined) {
+                phaseState.capped = options.capped;
+            }
             // Preserve startedAt if already set
             const existingPhase = issueState.phases[phase];
             if (existingPhase?.startedAt && status !== "pending") {