sequant 2.8.0 → 2.9.0

package/dist/src/lib/workflow/chain-resume.js

@@ -0,0 +1,166 @@
+/**
+ * Chain resume planning (#760).
+ *
+ * When a `--chain` run fails mid-way, earlier links may already be complete
+ * (`ready_for_merge`) with a checkpoint commit on their feature branch
+ * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
+ * should skip that completed prefix and resume at the first incomplete link,
+ * rebased onto the last completed link's committed tip — NOT `main` (which is
+ * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
+ *
+ * The existing pre-flight guard (`run-orchestrator.ts`) already drops
+ * `ready_for_merge`/`merged` issues from the run, but it is chain-unaware:
+ * dropping the completed prefix leaves the first incomplete link at index 0,
+ * where `executeSequential`'s successor-rebase never fires, so it silently
+ * builds on `main`. This module computes a *chain-correct* resume plan that
+ * preserves the completed prefix as the resume base.
+ *
+ * The planner is pure over an injected {@link CompletedLinkResolver} so the
+ * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
+ * real-git rebase is covered by the integration test.
+ */
+const COMPLETED_STATUSES = new Set(["ready_for_merge", "merged"]);
+/**
+ * Compute a chain-correct resume plan.
+ *
+ * Peels the *contiguous* completed prefix off the front of the chain (chain
+ * mode breaks on the first failure, so completed links always form a prefix).
+ * A completed link that appears *after* an incomplete one is left in `active`
+ * and re-executed — the conservative choice, since automatic skipping must not
+ * silently drop an issue the user intended to redo.
+ *
+ * @param orderedLinks Chain links in execution order, with persisted state.
+ * @param baseBranch The run's base branch (resume base when the prefix merged).
+ * @param resolver Git-ref resolver (injected for tests).
+ */
+export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
+    const skipped = [];
+    let firstIncomplete = 0;
+    for (const link of orderedLinks) {
+        if (link.status && COMPLETED_STATUSES.has(link.status)) {
+            skipped.push({
+                issueNumber: link.issueNumber,
+                status: link.status,
+                branch: link.branch,
+                worktree: link.worktree,
+            });
+            firstIncomplete++;
+        }
+        else {
+            break;
+        }
+    }
+    const allNumbers = orderedLinks.map((l) => l.issueNumber);
+    // No completed prefix → fresh run, nothing to resume.
+    if (skipped.length === 0) {
+        return { skipped: [], active: allNumbers, allComplete: false };
+    }
+    // Every link already complete → nothing to execute.
+    if (firstIncomplete >= orderedLinks.length) {
+        return { skipped, active: [], allComplete: true };
+    }
+    const active = allNumbers.slice(firstIncomplete);
+    const last = skipped[skipped.length - 1];
+    let resumeBase;
+    let resumeBaseCommit;
+    if (last.status === "merged") {
+        // The completed prefix's work is in the merged base (origin/main). Provision
+        // the first incomplete link from the base branch — the same base a fresh
+        // first link would use — rather than a local tip that squash-merge may have
+        // orphaned (never rebase a successor onto a stale post-merge local tip).
+        resumeBase = baseBranch;
+        resumeBaseCommit = resolver.resolveBaseTip();
+    }
+    else {
+        // ready_for_merge: the checkpoint tip lives only on the local feature
+        // branch. If that branch is gone (worktree/branch destroyed mid-way), the
+        // tip is unreconstructable — fail fast instead of wrong-basing the
+        // successor onto main (which would miss the completed link's work).
+        if (!last.branch) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ready_for_merge but no branch is recorded in state — ` +
+                    `cannot reconstruct the resume base. Re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        const tip = resolver.resolveBranchTip(last.branch);
+        if (!tip) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ready_for_merge but its branch "${last.branch}" no longer exists — ` +
+                    `the resume base is unreconstructable. Re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        // The branch exists, but a tip is only a valid resume base if it actually
+        // contains the link's work. `createCheckpointCommit` sweeps trailing
+        // uncommitted changes into a checkpoint commit; when it fails (commit hook,
+        // staging error, or unrelated dirty files) the status was *already* written
+        // as ready_for_merge, so this link still reads as a completed prefix while
+        // its tip is missing work. Rebasing the successor onto it would be exactly
+        // the silent wrong-base execution AC-3 forbids — fail fast instead.
+        if (last.worktree && resolver.isWorktreeDirty(last.worktree)) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ready_for_merge but its worktree has uncommitted changes — ` +
+                    `its checkpoint commit never landed, so branch "${last.branch}" is missing that work and ` +
+                    `resuming #${active[0]} here would build on an incomplete base. Commit them in ${last.worktree}, ` +
+                    `or re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        resumeBase = last.branch;
+        resumeBaseCommit = tip;
+    }
+    return {
+        skipped,
+        active,
+        resumeBase,
+        resumeBaseCommit,
+        resumeIssue: active[0],
+        allComplete: false,
+    };
+}
+/**
+ * Read each link's persisted state and compute the resume plan.
+ *
+ * Split out of `run-orchestrator.ts` so the state-reading half of resume — in
+ * particular "a state lookup failure must treat the link as *incomplete*", the
+ * conservative choice that re-executes rather than skipping on bad data — is
+ * testable without standing up an orchestrator.
+ *
+ * @param issueNumbers Chain issues in execution order.
+ * @param baseBranch The run's base branch.
+ * @param getIssueState Reads persisted state for one issue (may reject).
+ * @param resolver Git-ref resolver.
+ * @param onStateError Called when a lookup throws; the link is then treated as
+ *   incomplete (no status), so it stays in `active`.
+ */
+export async function planChainResumeFromState(issueNumbers, baseBranch, getIssueState, resolver, onStateError) {
+    const orderedLinks = [];
+    for (const issueNumber of issueNumbers) {
+        let status;
+        let branch;
+        let worktree;
+        try {
+            const issueState = await getIssueState(issueNumber);
+            status = issueState?.status;
+            branch = issueState?.branch;
+            worktree = issueState?.worktree;
+        }
+        catch (error) {
+            // Unknown state → treat as incomplete and re-execute. Skipping on a
+            // failed lookup could silently drop an issue the user meant to run.
+            onStateError?.(issueNumber, error);
+        }
+        orderedLinks.push({ issueNumber, status, branch, worktree });
+    }
+    return computeChainResumePlan(orderedLinks, baseBranch, resolver);
+}

package/dist/src/lib/workflow/dependency-markers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared parser for line-leading dependency markers in an issue body (#767).
+ *
+ * Two callers extract issue numbers from `depends on #N` / `blocked by #N`
+ * declarations:
+ *
+ *   - `chain-preflight.ts:parseDeclaredBlockers` — warn-only pre-flight, honors
+ *     BOTH `depends on` and `blocked by`.
+ *   - `batch-executor.ts:parseDependencies` — feeds `sortByDependencies`, which
+ *     *silently reorders the run*, so it honors ONLY `depends on`.
+ *
+ * The hardened mechanics (line anchoring, required `#`, code/comment stripping)
+ * were introduced for the pre-flight in #762/PR #764 and lived only in
+ * `chain-preflight.ts`. #767 promotes them here so the sorter can adopt the same
+ * hardening without the two regexes drifting — while keeping the **marker set
+ * per-caller** so sharing the parser does NOT make the sorter start reordering
+ * on `blocked by` (a new, unrequested silent-reorder class; #762 Open Q #3).
+ */
+/** A dependency-declaration marker a caller opts into honoring. */
+export type DepMarker = "depends on" | "blocked by";
+/**
+ * Parse the issue numbers a body declares itself dependent on / blocked by,
+ * honoring only the requested `markers`. Deduped, order-preserving.
+ *
+ * Only line-leading markers count as declarations — see `buildMarkerRegex` for
+ * why mid-sentence prose mentions are deliberately ignored. Code blocks, inline
+ * code spans, and HTML comments are stripped first.
+ */
+export declare function parseBodyDependencyMarkers(body: string, markers: DepMarker[]): number[];

package/dist/src/lib/workflow/dependency-markers.js

@@ -0,0 +1,79 @@
+/**
+ * Shared parser for line-leading dependency markers in an issue body (#767).
+ *
+ * Two callers extract issue numbers from `depends on #N` / `blocked by #N`
+ * declarations:
+ *
+ *   - `chain-preflight.ts:parseDeclaredBlockers` — warn-only pre-flight, honors
+ *     BOTH `depends on` and `blocked by`.
+ *   - `batch-executor.ts:parseDependencies` — feeds `sortByDependencies`, which
+ *     *silently reorders the run*, so it honors ONLY `depends on`.
+ *
+ * The hardened mechanics (line anchoring, required `#`, code/comment stripping)
+ * were introduced for the pre-flight in #762/PR #764 and lived only in
+ * `chain-preflight.ts`. #767 promotes them here so the sorter can adopt the same
+ * hardening without the two regexes drifting — while keeping the **marker set
+ * per-caller** so sharing the parser does NOT make the sorter start reordering
+ * on `blocked by` (a new, unrequested silent-reorder class; #762 Open Q #3).
+ */
+/**
+ * Build the anchored marker regex for the requested marker set.
+ *
+ * Matches a declared marker, optionally bold-wrapped, colon-separated, and/or
+ * written as a list item, e.g. `- **Depends on**: #123`.
+ *
+ * Anchored to line start because a *declaration* is a line about the issue's
+ * own dependencies, whereas prose that merely mentions the marker mid-sentence
+ * is not. #762's own body is the motivating case: it contains both `...when #39
+ * says blocked by #38` and `...real markers like "Blocked by #36"` as examples,
+ * and an unanchored match reported #762 as blocked by #38 and #36 — exactly the
+ * false inference #604 says is worse than none. That matters most under
+ * `--strict-preflight`, where a bogus warning hard-aborts a legitimate chain.
+ *
+ * The `#` is required (unlike the historic looser `#?` in `parseDependencies`)
+ * so a line such as `Blocked by 5 days of review` — or the prose
+ * `Issue 14 depends on 12+13` — cannot parse as an issue number.
+ */
+function buildMarkerRegex(markers) {
+    const alternation = markers.map((m) => m.split(/\s+/).join("\\s+")).join("|");
+    return new RegExp(`^\\s*(?:[-*]\\s*)?\\*?\\*?(?:${alternation})\\*?\\*?:?\\s*#(\\d+)`, "gim");
+}
+/**
+ * Strip fenced code blocks, inline code spans, and HTML comments so markers
+ * inside quoted shell snippets, documentation examples, or commented-out drafts
+ * don't count as real declarations. Inline spans are matched within a single
+ * line so an unbalanced backtick cannot swallow the rest of the body.
+ *
+ * Deliberately diverges from `assess-collision-detect.ts:stripCodeBlocksAndComments`,
+ * which keeps inline spans: its PATH_REGEX only matches backtick-wrapped paths,
+ * so stripping them there would find nothing. Same syntax, opposite meaning —
+ * a backticked marker here is an example, a backticked path there is the target.
+ * Keep the two separate (see PR #770).
+ */
+function stripCodeAndComments(body) {
+    return body
+        .replace(/```[\s\S]*?```/g, "")
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/`[^`\n]*`/g, "");
+}
+/**
+ * Parse the issue numbers a body declares itself dependent on / blocked by,
+ * honoring only the requested `markers`. Deduped, order-preserving.
+ *
+ * Only line-leading markers count as declarations — see `buildMarkerRegex` for
+ * why mid-sentence prose mentions are deliberately ignored. Code blocks, inline
+ * code spans, and HTML comments are stripped first.
+ */
+export function parseBodyDependencyMarkers(body, markers) {
+    if (markers.length === 0)
+        return [];
+    const cleaned = stripCodeAndComments(body);
+    const regex = buildMarkerRegex(markers);
+    const found = [];
+    for (const m of cleaned.matchAll(regex)) {
+        const n = parseInt(m[1], 10);
+        if (!isNaN(n) && !found.includes(n))
+            found.push(n);
+    }
+    return found;
+}

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

@@ -48,6 +48,13 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      * 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.
      */
     private errorFromAssistantError;
     private buildResumeHandle;

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

@@ -228,10 +228,22 @@ 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(),
                 };
@@ -239,8 +251,7 @@ export class ClaudeCodeDriver {
             // 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.
+            // proximate cause.
             const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             const stderrSuffix = capturedStderr
                 ? `\nStderr: ${capturedStderr.slice(0, 500)}`
@@ -287,15 +298,28 @@ export class ClaudeCodeDriver {
      * 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");
+                return new BillingError("Billing error", {
+                    assistantError: "billing_error",
+                });
             case "rate_limit":
-                return new RateLimitError("Rate limited");
+                return new RateLimitError("Rate limited", {
+                    assistantError: "rate_limit",
+                });
             case "overloaded":
-                return new RateLimitError("API overloaded");
+                return new RateLimitError("API overloaded", {
+                    assistantError: "overloaded",
+                });
             default:
                 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.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).