sequant 2.6.2 → 2.8.0

package/dist/src/lib/errors.js

@@ -82,6 +82,115 @@ export class SubprocessError extends SequantError {
         this.name = "SubprocessError";
     }
 }
+/**
+ * Transient rate-limit error (HTTP 429-style throttle, overloaded API).
+ *
+ * Retryable: waiting and re-running can succeed once the limit window resets.
+ */
+export class RateLimitError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: true, metadata, cause });
+        this.name = "RateLimitError";
+    }
+}
+/**
+ * Billing / out-of-credits error.
+ *
+ * NOT retryable: a no-MCP retry (or any retry) cannot refill credits, so the
+ * executor must surface the real cause instead of looping. Drives the #592
+ * fallback-noise skip in phase-executor.
+ */
+export class BillingError extends SequantError {
+    constructor(message, metadata = {}, cause) {
+        super(message, { isRetryable: false, metadata, cause });
+        this.name = "BillingError";
+    }
+}
+/**
+ * True when the rate-limit info represents a billing/credits failure (which a
+ * retry cannot fix), rather than a transient throttle.
+ */
+export function isBillingFailure(info) {
+    return (info.errorCode === "credits_required" ||
+        info.overageDisabledReason === "out_of_credits");
+}
+/**
+ * True when the rate-limit info represents an actual failure (rejection or
+ * billing), as opposed to an informational `allowed` / `allowed_warning`
+ * event. The driver uses this to avoid mis-attributing a stale warning event
+ * to an unrelated phase failure.
+ */
+export function isRateLimitFailureInfo(info) {
+    return info.status === "rejected" || isBillingFailure(info);
+}
+/**
+ * Format a Unix timestamp (seconds or ms) as a local time string.
+ *
+ * Bare `HH:MM` when the reset falls on the current local calendar day;
+ * date-qualified `MM-DD HH:MM` otherwise. Multi-day windows
+ * (`rateLimitType: seven_day*`) can reset days out — a bare `HH:MM` there reads
+ * as "later today" and misleads the user (#732 QA follow-up), so the date is
+ * included whenever the reset is not today.
+ */
+function formatResetTime(resetsAt) {
+    // Heuristic: values below ~1e12 are seconds, otherwise milliseconds.
+    const ms = resetsAt < 1e12 ? resetsAt * 1000 : resetsAt;
+    const d = new Date(ms);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const now = new Date();
+    const sameDay = d.getFullYear() === now.getFullYear() &&
+        d.getMonth() === now.getMonth() &&
+        d.getDate() === now.getDate();
+    if (sameDay) {
+        return `${hh}:${mm}`;
+    }
+    const mon = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${mon}-${day} ${hh}:${mm}`;
+}
+/**
+ * Build a user-facing message from rate-limit info, naming the real cause:
+ * - billing/credits → "Out of credits" (enriched with purchasable vs hard
+ *   limit when the ≥0.3.181 `canUserPurchaseCredits` field is present)
+ * - transient throttle → "Rate limited — resets at HH:MM" (date-qualified as
+ *   "MM-DD HH:MM" when the reset is not today; reset time omitted entirely when
+ *   `resetsAt` is absent)
+ */
+export function formatRateLimitMessage(info) {
+    if (isBillingFailure(info)) {
+        if (info.canUserPurchaseCredits === true) {
+            return "Out of credits — purchasable";
+        }
+        if (info.canUserPurchaseCredits === false) {
+            return "Out of credits — hard limit";
+        }
+        return "Out of credits";
+    }
+    if (info.resetsAt !== undefined) {
+        return `Rate limited — resets at ${formatResetTime(info.resetsAt)}`;
+    }
+    return "Rate limited";
+}
+/**
+ * Construct the appropriate typed error from structured rate-limit info.
+ * Billing/credits failures become a non-retryable {@link BillingError};
+ * transient throttles become a retryable {@link RateLimitError}.
+ */
+export function createRateLimitError(info) {
+    const message = formatRateLimitMessage(info);
+    const metadata = {
+        resetsAt: info.resetsAt,
+        rateLimitType: info.rateLimitType,
+        overageDisabledReason: info.overageDisabledReason,
+        errorCode: info.errorCode,
+        canUserPurchaseCredits: info.canUserPurchaseCredits,
+        hasChargeableSavedPaymentMethod: info.hasChargeableSavedPaymentMethod,
+    };
+    return isBillingFailure(info)
+        ? new BillingError(message, metadata)
+        : new RateLimitError(message, metadata);
+}
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.
@@ -94,4 +203,6 @@ export const ERROR_TYPE_MAP = {
     BuildError: BuildError,
     TimeoutError: TimeoutError,
     SubprocessError: SubprocessError,
+    RateLimitError: RateLimitError,
+    BillingError: BillingError,
 };

package/dist/src/lib/version-check.d.ts

@@ -114,6 +114,25 @@ export declare function fetchLatestVersion(): Promise<string | null>;
  * Returns: -1 if a < b, 0 if a == b, 1 if a > b
  */
 export declare function compareVersions(a: string, b: string): number;
+/**
+ * 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 declare function getNodeVersionError(current: string, floor: string | null | undefined): string | null;
+/**
+ * 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 declare function assertNodeVersion(floor: string | null | undefined): void;
 /**
  * Check if the current version is outdated
  */

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.