sequant 2.7.0 → 2.9.0

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(),
             };
@@ -174,14 +228,31 @@ export class ClaudeCodeDriver {
             clearTimeout(timeoutId);
             const error = err instanceof Error ? err.message : String(err);
             if (error.includes("abort") || error.includes("AbortError")) {
+                // A rate limit can manifest as a hang rather than a stream event
+                // reaching the result: the SDK stalls, the phase timeout fires, and
+                // the abort lands here. Only failure-grade signals are ever captured
+                // (see the stream loop), so attaching them cannot mask a genuine
+                // timeout — with no signal, `abortStructuredError` is undefined and
+                // the bare timeout message survives unchanged (#761 AC-1). Without
+                // this, the captured `rateLimitInfo` was discarded and downstream
+                // classification saw only `Timeout after Ns`, sending a closed
+                // rate-limit window into the full retry + MCP-fallback ladder.
+                const abortStructuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
                 return {
                     success: false,
                     output: capturedOutput,
-                    error: `Timeout after ${config.phaseTimeout}s`,
+                    error: abortStructuredError?.message ??
+                        `Timeout after ${config.phaseTimeout}s`,
+                    structuredError: abortStructuredError,
                     stderrTail: stderrBuffer.getLines(),
                     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.
+            const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             const stderrSuffix = capturedStderr
                 ? `\nStderr: ${capturedStderr.slice(0, 500)}`
                 : "";
@@ -190,12 +261,69 @@ 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.
+     *
+     * The assistant-error channel carries no `resetsAt`/`rateLimitType` (the
+     * enum is the whole signal — `SDKAssistantMessageError` is a bare string),
+     * so the originating variant is recorded in metadata to keep `rate_limit`
+     * and `overloaded` distinguishable downstream (#761 AC-9). With no
+     * `resetsAt`, these errors are treated as transient by the executor's
+     * window-exhaustion check — the mandatory metadata-absent fallback.
+     */
+    errorFromAssistantError(error) {
+        switch (error) {
+            case "billing_error":
+                return new BillingError("Billing error", {
+                    assistantError: "billing_error",
+                });
+            case "rate_limit":
+                return new RateLimitError("Rate limited", {
+                    assistantError: "rate_limit",
+                });
+            case "overloaded":
+                return new RateLimitError("API overloaded", {
+                    assistantError: "overloaded",
+                });
+            default:
+                return undefined;
+        }
+    }
     buildResumeHandle(token, originCwd) {
         if (!token)
             return undefined;

package/dist/src/lib/workflow/error-classifier.d.ts

@@ -5,8 +5,15 @@
  * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
 import { SequantError } from "../errors.js";
-/** All recognized error categories (kept for backwards compatibility). */
-export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "unknown"];
+/**
+ * All recognized error categories (kept for backwards compatibility).
+ *
+ * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
+ * errors — `classifyError` never produces them, since stderr text cannot
+ * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * Keep in sync with the inline category enum in `run-log-schema.ts`.
+ */
+export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "unknown"];
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
 /**
  * Map from error type name to legacy category string.

package/dist/src/lib/workflow/error-classifier.js

@@ -5,13 +5,22 @@
  * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
 import { ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutError, SubprocessError, } from "../errors.js";
-/** All recognized error categories (kept for backwards compatibility). */
+/**
+ * All recognized error categories (kept for backwards compatibility).
+ *
+ * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
+ * errors — `classifyError` never produces them, since stderr text cannot
+ * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * Keep in sync with the inline category enum in `run-log-schema.ts`.
+ */
 export const ERROR_CATEGORIES = [
     "context_overflow",
     "api_error",
     "hook_failure",
     "build_error",
     "timeout",
+    "rate_limit",
+    "billing",
     "unknown",
 ];
 /**
@@ -30,6 +39,10 @@ export function errorTypeToCategory(error) {
             return "build_error";
         case "TimeoutError":
             return "timeout";
+        case "RateLimitError":
+            return "rate_limit";
+        case "BillingError":
+            return "billing";
         default:
             return "unknown";
     }

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/log-writer.js

@@ -16,7 +16,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { createEmptyRunLog, finalizeRunLog, generateLogFilename, LOG_PATHS, } from "./run-log-schema.js";
+import { createEmptyRunLog, finalizeRunLog, deriveIssueLogStatus, generateLogFilename, LOG_PATHS, } from "./run-log-schema.js";
 import { rotateIfNeeded, DEFAULT_ROTATION_SETTINGS, } from "./log-rotation.js";
 /**
  * Manages writing structured run logs to disk
@@ -94,13 +94,11 @@ export class LogWriter {
             throw new Error(`No active issue #${phaseLog.issueNumber}. Call startIssue() first.`);
         }
         issue.phases = [...(issue.phases ?? []), phaseLog];
-        // Update issue status based on phase result
-        if (phaseLog.status === "failure") {
-            issue.status = "failure";
-        }
-        else if (phaseLog.status === "timeout" && issue.status !== "failure") {
-            issue.status = "partial";
-        }
+        // #766: derive from the latest attempt of each phase (loop excluded) rather
+        // than pinning failure/partial forever. A timeout or failure that a later
+        // quality-loop iteration recovers from no longer sticks, so the JSON log
+        // agrees with the live card and summary table (AC-3/AC-5).
+        issue.status = deriveIssueLogStatus(issue.phases);
         if (this.verbose) {
             console.log(`Log phase: ${phaseLog.phase} (${phaseLog.status}) - ${phaseLog.durationSeconds.toFixed(1)}s`);
         }

package/dist/src/lib/workflow/metrics-schema.d.ts

@@ -25,6 +25,24 @@ export declare const RunOutcomeSchema: z.ZodEnum<{
     failed: "failed";
 }>;
 export type RunOutcome = z.infer<typeof RunOutcomeSchema>;
+/**
+ * Bounded-enum classification of the failure that ended a run (#761 AC-7).
+ *
+ * Sourced from `ERROR_CATEGORIES` so the metric can never carry free text —
+ * error *messages* stay excluded per the privacy contract above MetricRunSchema
+ * (they could contain sensitive info); a closed enum cannot.
+ */
+export declare const FailureCategorySchema: z.ZodEnum<{
+    unknown: "unknown";
+    timeout: "timeout";
+    context_overflow: "context_overflow";
+    api_error: "api_error";
+    hook_failure: "hook_failure";
+    build_error: "build_error";
+    rate_limit: "rate_limit";
+    billing: "billing";
+}>;
+export type FailureCategory = z.infer<typeof FailureCategorySchema>;
 /**
  * Available phases (aligned with run-log-schema.ts)
  */
@@ -83,6 +101,16 @@ export declare const MetricRunSchema: z.ZodObject<{
     duration: z.ZodNumber;
     model: z.ZodString;
     flags: z.ZodArray<z.ZodString>;
+    failureCategory: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        timeout: "timeout";
+        context_overflow: "context_overflow";
+        api_error: "api_error";
+        hook_failure: "hook_failure";
+        build_error: "build_error";
+        rate_limit: "rate_limit";
+        billing: "billing";
+    }>>;
     metrics: z.ZodObject<{
         tokensUsed: z.ZodNumber;
         filesChanged: z.ZodNumber;
@@ -123,6 +151,16 @@ export declare const MetricsSchema: z.ZodObject<{
         duration: z.ZodNumber;
         model: z.ZodString;
         flags: z.ZodArray<z.ZodString>;
+        failureCategory: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            timeout: "timeout";
+            context_overflow: "context_overflow";
+            api_error: "api_error";
+            hook_failure: "hook_failure";
+            build_error: "build_error";
+            rate_limit: "rate_limit";
+            billing: "billing";
+        }>>;
         metrics: z.ZodObject<{
             tokensUsed: z.ZodNumber;
             filesChanged: z.ZodNumber;
@@ -154,6 +192,7 @@ export declare function createMetricRun(options: {
     duration: number;
     model?: string;
     flags?: string[];
+    failureCategory?: FailureCategory;
     metrics?: Partial<RunMetrics>;
 }): MetricRun;
 /**

package/dist/src/lib/workflow/metrics-schema.js

@@ -17,10 +17,19 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { ERROR_CATEGORIES } from "./error-classifier.js";
 /**
  * Outcome of a workflow run
  */
 export const RunOutcomeSchema = z.enum(["success", "partial", "failed"]);
+/**
+ * Bounded-enum classification of the failure that ended a run (#761 AC-7).
+ *
+ * Sourced from `ERROR_CATEGORIES` so the metric can never carry free text —
+ * error *messages* stay excluded per the privacy contract above MetricRunSchema
+ * (they could contain sensitive info); a closed enum cannot.
+ */
+export const FailureCategorySchema = z.enum(ERROR_CATEGORIES);
 /**
  * Available phases (aligned with run-log-schema.ts)
  */
@@ -81,6 +90,12 @@ export const MetricRunSchema = z.object({
     model: z.string(),
     /** CLI flags used (e.g., ["--chain", "--sequential"]) */
     flags: z.array(z.string()),
+    /**
+     * Category of the failure that ended the run (#761 AC-7). Optional and
+     * enum-only; absent on success and on records written before this field
+     * existed (additive — no `version` bump required).
+     */
+    failureCategory: FailureCategorySchema.optional(),
     /** Aggregate metrics */
     metrics: RunMetricsSchema,
 });
@@ -121,6 +136,7 @@ export function createMetricRun(options) {
         duration: options.duration,
         model: options.model ?? "unknown",
         flags: options.flags ?? [],
+        failureCategory: options.failureCategory,
         metrics: {
             tokensUsed: options.metrics?.tokensUsed ?? 0,
             filesChanged: options.metrics?.filesChanged ?? 0,

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

@@ -20,7 +20,7 @@
  * });
  * ```
  */
-import { type Metrics, type MetricRun, type MetricPhase, type RunOutcome, type RunMetrics } from "./metrics-schema.js";
+import { type Metrics, type MetricRun, type MetricPhase, type RunOutcome, type RunMetrics, type FailureCategory } from "./metrics-schema.js";
 export interface MetricsWriterOptions {
     /** Path to metrics file (default: .sequant/metrics.json) */
     metricsPath?: string;
@@ -69,6 +69,7 @@ export declare class MetricsWriter {
         duration: number;
         model?: string;
         flags?: string[];
+        failureCategory?: FailureCategory;
         metrics?: Partial<RunMetrics>;
     }): Promise<MetricRun>;
     /**

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

@@ -11,6 +11,7 @@ import { ShutdownManager } from "../shutdown.js";
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict, PhasePauseHandle } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
 import type { AgentPhaseResult, ResumeHandle } from "./drivers/index.js";
+import { SequantError } from "../errors.js";
 /**
  * Leading + trailing throttle. Fires the wrapped callback immediately on the
  * first call, drops subsequent calls that arrive inside `intervalMs` but
@@ -35,6 +36,37 @@ export declare function createThrottledReporter(fn: (text: string) => void, inte
 export declare const SPEC_RETRY_BACKOFF_MS: number;
 /** @internal Exported for testing only */
 export declare const SPEC_EXTRA_RETRIES: number;
+/**
+ * A rate limit whose window resets further out than this is treated as
+ * exhausted rather than transient (#761 AC-2): no retry can succeed inside a
+ * closed window, so consuming cold-start retries (each burning up to a full
+ * `phaseTimeout`) only delays the labeled halt. Five minutes comfortably
+ * exceeds any backoff this executor performs while staying far below the
+ * five-hour/seven-day windows the check exists to catch.
+ *
+ * @internal Exported for testing only
+ */
+export declare const RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS: number;
+/**
+ * Base backoff for transient rate-limit retries (#761 AC-4), doubled per
+ * attempt (5s, 10s). Same scale as `SPEC_RETRY_BACKOFF_MS` — long enough to
+ * outlive a momentary throttle, short enough to be negligible next to a
+ * phase's runtime.
+ *
+ * @internal Exported for testing only
+ */
+export declare const RATE_LIMIT_RETRY_BACKOFF_MS = 5000;
+/**
+ * True when a failure is a rate limit whose reset lies beyond
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS} — i.e. window exhaustion, not a
+ * transient throttle. Metadata-absent rate limits (the assistant-error channel
+ * carries no `resetsAt`, see #761 AC-9) return false and fall through to the
+ * transient path: with no timing signal, retry-with-backoff is the safe
+ * default, skipping all retries is not.
+ *
+ * @internal Exported for testing only
+ */
+export declare function isWindowExhaustedRateLimit(error: SequantError | undefined, now?: number): boolean;
 export declare function parseQaVerdict(output: string): QaVerdict | null;
 /**
  * Parse condensed QA summary from QA phase output (#434).
@@ -111,6 +143,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.