sequant 2.7.0 → 2.9.0

package/dist/src/lib/assess-collision-detect.d.ts

@@ -22,12 +22,28 @@
  * users to ignore the warning.
  */
 export declare const EXCLUDED_PATHS: ReadonlySet<string>;
+/**
+ * Markdown H1/H2 section headings whose bodies are background/citation prose,
+ * not statements of intent-to-modify. A path named *only* under one of these
+ * is a reference to existing code, not a file the issue will touch — so the
+ * whole section is stripped before path extraction.
+ *
+ * Match is case-insensitive and prefix-based, so `## Motivation — concrete
+ * recent miss` and `## Additional context (see #533)` both match. This is the
+ * cheap version of the #556 proximity-weighting mitigation (#769): exclude
+ * background sections wholesale rather than scoring per-path distance to AC
+ * bullets. "A path appears only in background" ⟺ "the path is absent from the
+ * foreground", so stripping these sections up front subsumes per-path tagging.
+ */
+export declare const BACKGROUND_SECTIONS: ReadonlySet<string>;
 /**
  * Extract the set of file paths an issue body identifies as
  * targets-of-modification.
  *
  * Strategy:
- *   1. Strip fenced code blocks and HTML comments (AC-5 guard).
+ *   1. Strip fenced code blocks and HTML comments (AC-5 guard), then strip
+ *      background/citation sections (#769) so a path named only under
+ *      `## References`, `## Context`, etc. isn't counted as a target.
  *   2. Pull every backtick-quoted path matching the source-tree regex,
  *      normalizing skill-mirror paths to their canonical bare form.
  *   3. If the body mentions "3-dir sync", also pull bare
@@ -71,7 +87,8 @@ export declare function detectFileCollisions(issuePaths: Map<number, Set<string>
  * - `chainSuggestion` — emitted only when ≥3 issues collide on the same
  *   file (AC-4); suggest-only, never auto-applied. Annotated with the
  *   historical chain-mode success rate at length≥3 (1/6 = 17%, per #604
- *   forensics) so users can weigh chain mode against the parallel default.
+ *   forensics — the entire sample predates the #748/#749 fixes) so users
+ *   can weigh chain mode against the parallel default.
  */
 export interface CollisionAnnotations {
     orderLines: string[];

package/dist/src/lib/assess-collision-detect.js

@@ -27,6 +27,26 @@ export const EXCLUDED_PATHS = new Set([
     "yarn.lock",
     "pnpm-lock.yaml",
 ]);
+/**
+ * Markdown H1/H2 section headings whose bodies are background/citation prose,
+ * not statements of intent-to-modify. A path named *only* under one of these
+ * is a reference to existing code, not a file the issue will touch — so the
+ * whole section is stripped before path extraction.
+ *
+ * Match is case-insensitive and prefix-based, so `## Motivation — concrete
+ * recent miss` and `## Additional context (see #533)` both match. This is the
+ * cheap version of the #556 proximity-weighting mitigation (#769): exclude
+ * background sections wholesale rather than scoring per-path distance to AC
+ * bullets. "A path appears only in background" ⟺ "the path is absent from the
+ * foreground", so stripping these sections up front subsumes per-path tagging.
+ */
+export const BACKGROUND_SECTIONS = new Set([
+    "references",
+    "context",
+    "motivation",
+    "additional context",
+    "see also",
+]);
 /**
  * Slash-command names recognized as references to a skill's SKILL.md.
  * Used by the slash-command-skill derivation rule when an issue body
@@ -83,10 +103,52 @@ const THREE_DIR_SYNC_PATTERN = /3[- ]dir(?:ectory)?\s+sync|across\s+all\s+three\
  * single-backtick wrapper, so this gives us the "paths quoted as code in
  * prose count, paths inside a code block don't" behavior the AC-5 guard
  * specifies.
+ *
+ * Do NOT unify this with `dependency-markers.ts:stripCodeAndComments`, which
+ * looks nearly identical but additionally strips inline spans. The two have
+ * opposite requirements for the same syntax: there a backticked marker is a
+ * documentation example to discard, here a backticked path is the entire
+ * signal. Adding its inline-span strip to this function would delete every
+ * path PATH_REGEX is looking for and silently return an empty set.
  */
 function stripCodeBlocksAndComments(body) {
     return body.replace(/```[\s\S]*?```/g, "").replace(/<!--[\s\S]*?-->/g, "");
 }
+/**
+ * Remove background/citation sections (see `BACKGROUND_SECTIONS`) so a path
+ * named only as a reference — under `## References`, `## Context`, etc. — is
+ * not counted as a modification target (#769).
+ *
+ * A section runs from its H1/H2 heading to the next H1/H2 heading (or EOF);
+ * `###`+ subsections belong to their parent section and are dropped with it.
+ * Only H1/H2 headings toggle sections — a `### Detail` inside a stripped
+ * `## Additional context` must not resurrect the rest of the section.
+ *
+ * Run this *after* `stripCodeBlocksAndComments` so a fenced block containing a
+ * `## `-prefixed line can't be misread as a real heading.
+ */
+function stripBackgroundSections(body) {
+    const kept = [];
+    let stripping = false;
+    for (const line of body.split("\n")) {
+        const heading = line.match(/^(#{1,6})\s+(.*)$/);
+        if (heading && heading[1].length <= 2) {
+            const text = heading[2].trim().toLowerCase();
+            stripping = false;
+            for (const section of BACKGROUND_SECTIONS) {
+                if (text.startsWith(section)) {
+                    stripping = true;
+                    break;
+                }
+            }
+            if (stripping)
+                continue; // drop the heading line itself
+        }
+        if (!stripping)
+            kept.push(line);
+    }
+    return kept.join("\n");
+}
 /**
  * Collapse a fully-qualified skill-mirror path to its canonical bare form.
  *
@@ -109,7 +171,9 @@ function normalizeSkillMirrorPath(path) {
  * targets-of-modification.
  *
  * Strategy:
- *   1. Strip fenced code blocks and HTML comments (AC-5 guard).
+ *   1. Strip fenced code blocks and HTML comments (AC-5 guard), then strip
+ *      background/citation sections (#769) so a path named only under
+ *      `## References`, `## Context`, etc. isn't counted as a target.
  *   2. Pull every backtick-quoted path matching the source-tree regex,
  *      normalizing skill-mirror paths to their canonical bare form.
  *   3. If the body mentions "3-dir sync", also pull bare
@@ -125,7 +189,7 @@ function normalizeSkillMirrorPath(path) {
  */
 export function extractPathsFromIssueBody(body) {
     const paths = new Set();
-    const cleaned = stripCodeBlocksAndComments(body);
+    const cleaned = stripBackgroundSections(stripCodeBlocksAndComments(body));
     for (const m of cleaned.matchAll(PATH_REGEX)) {
         paths.add(normalizeSkillMirrorPath(m[1]));
     }
@@ -208,9 +272,9 @@ export function formatCollisionAnnotations(results) {
         if (r.issues.length >= 3 && !chainSuggestion) {
             const ids = r.issues.join(" ");
             chainSuggestion =
-                `Chain: npx sequant run ${ids} --chain --qa-gate -Q   ` +
+                `Chain: npx sequant run ${ids} --chain -Q   ` +
                     `# alternative — ${r.issues.length} issues modify ${r.file} ` +
-                    `(chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)`;
+                    `(chain length≥3 historically 1/6 = 17%, predates the #748/#749 fixes; see docs/reference/chain-mode-analysis-2026-05.md)`;
         }
     }
     return { orderLines, warnings, chainSuggestion };

package/dist/src/lib/cli-ui/run-renderer.js

@@ -19,6 +19,7 @@ import chalk from "chalk";
 import logUpdate from "log-update";
 import stringWidth from "string-width";
 import { formatElapsedTime, formatTimestamp } from "./format.js";
+import { pipelineHasFailed } from "../workflow/status-derivation.js";
 const DEFAULT_LIVE_TICK_MS = 1000;
 const DEFAULT_NON_TTY_HEARTBEAT_MS = 60_000;
 const NARROW_TERMINAL_THRESHOLD = 80;
@@ -248,8 +249,13 @@ class BaseRenderer {
         else if (phase.startedAt !== undefined) {
             phase.durationMs = this.now() - phase.startedAt;
         }
-        state.status = "failed";
-        state.completedAt = this.now();
+        // #766: derive from the phase slots (loop excluded) instead of pinning
+        // `failed`, so a loop failure on an early quality-loop iteration doesn't
+        // stick after a later iteration recovers. Mirrors the orchestrator's card.
+        const nowFailed = pipelineHasFailed(state.phases);
+        state.status = nowFailed ? "failed" : "running";
+        if (nowFailed)
+            state.completedAt = this.now();
         state.currentPhase = undefined;
         if (event.error !== undefined)
             state.failureReason = event.error;
@@ -267,20 +273,22 @@ class BaseRenderer {
     }
     /** Mark an issue done after PR is recorded — derived from phase completion. */
     maybeMarkIssueDone(state) {
-        if (state.status === "failed")
-            return;
         const allTerminal = state.phases.every((p) => p.status === "done" || p.status === "failed");
         if (allTerminal && state.phases.length > 0) {
-            state.status = state.phases.some((p) => p.status === "failed")
-                ? "failed"
-                : "done";
+            // #766: derive the verdict (loop excluded) so a run that failed the loop
+            // on an early iteration and then recovered every planned phase resolves
+            // to `done`. No early `failed` guard: a stale loop failure must be able
+            // to de-escalate once the pipeline recovers.
+            state.status = pipelineHasFailed(state.phases) ? "failed" : "done";
             state.completedAt = this.now();
         }
     }
     // ------------ Hooks for subclasses ------------
     afterEvent(_event, state) {
-        if (state.status !== "failed")
-            this.maybeMarkIssueDone(state);
+        // #766: always re-derive — `maybeMarkIssueDone` guards internally and must
+        // run even when `state.status` is currently `failed` so a recovered loop
+        // failure can de-escalate to `done`.
+        this.maybeMarkIssueDone(state);
         this.afterStateChange();
     }
     afterStateChange() {

package/dist/src/lib/errors.d.ts

@@ -86,6 +86,97 @@ export declare class SubprocessError extends SequantError {
     readonly metadata: SubprocessErrorMetadata;
     constructor(message: string, metadata?: SubprocessErrorMetadata, cause?: Error);
 }
+/**
+ * Metadata carried by {@link RateLimitError} / {@link BillingError}.
+ *
+ * Fields mirror the structured signals the Claude Agent SDK emits via
+ * `rate_limit_event` (`SDKRateLimitInfo`). The `canUserPurchaseCredits` /
+ * `hasChargeableSavedPaymentMethod` fields arrived in SDK 0.3.181 and are
+ * optional so older streams (or absent fields) degrade gracefully.
+ */
+export interface RateLimitMetadata {
+    [key: string]: unknown;
+    /** Unix timestamp (seconds or ms) at which the limit resets. */
+    resetsAt?: number;
+    /** Which limit window was hit (five_hour, seven_day, overage, …). */
+    rateLimitType?: string;
+    /** Why overage/billing was disabled (e.g. `out_of_credits`). */
+    overageDisabledReason?: string;
+    /** SDK error code; `credits_required` indicates a billing failure. */
+    errorCode?: string;
+    /** Whether the user can self-serve purchase credits (≥0.3.181). */
+    canUserPurchaseCredits?: boolean;
+    /** Whether a chargeable payment method is on file (≥0.3.181). */
+    hasChargeableSavedPaymentMethod?: boolean;
+}
+/**
+ * Transient rate-limit error (HTTP 429-style throttle, overloaded API).
+ *
+ * Retryable: waiting and re-running can succeed once the limit window resets.
+ */
+export declare class RateLimitError extends SequantError {
+    readonly metadata: RateLimitMetadata;
+    constructor(message: string, metadata?: RateLimitMetadata, cause?: Error);
+}
+/**
+ * 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 declare class BillingError extends SequantError {
+    readonly metadata: RateLimitMetadata;
+    constructor(message: string, metadata?: RateLimitMetadata, cause?: Error);
+}
+/**
+ * Structural subset of the SDK's `SDKRateLimitInfo` consumed when building a
+ * rate-limit error. Declared here (not imported from the SDK) so `errors.ts`
+ * stays SDK-free — only the driver owns the `@anthropic-ai/claude-agent-sdk`
+ * import.
+ */
+export interface RateLimitInfoLike {
+    status?: string;
+    resetsAt?: number;
+    rateLimitType?: string;
+    overageDisabledReason?: string;
+    errorCode?: string;
+    canUserPurchaseCredits?: boolean;
+    hasChargeableSavedPaymentMethod?: boolean;
+}
+/**
+ * True when the rate-limit info represents a billing/credits failure (which a
+ * retry cannot fix), rather than a transient throttle.
+ */
+export declare function isBillingFailure(info: RateLimitInfoLike): boolean;
+/**
+ * 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 declare function isRateLimitFailureInfo(info: RateLimitInfoLike): boolean;
+/**
+ * Normalize a `resetsAt` timestamp to milliseconds. The SDK does not pin the
+ * unit, so use the same heuristic everywhere a `resetsAt` is compared or
+ * displayed: values below ~1e12 are seconds, otherwise milliseconds.
+ */
+export declare function resetsAtToMs(resetsAt: number): number;
+/**
+ * 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 declare function formatRateLimitMessage(info: RateLimitInfoLike): string;
+/**
+ * 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 declare function createRateLimitError(info: RateLimitInfoLike): RateLimitError | BillingError;
 /**
  * Map of error type names to their constructors.
  * Used for deserialization from logs.

package/dist/src/lib/errors.js

@@ -82,6 +82,122 @@ 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);
+}
+/**
+ * Normalize a `resetsAt` timestamp to milliseconds. The SDK does not pin the
+ * unit, so use the same heuristic everywhere a `resetsAt` is compared or
+ * displayed: values below ~1e12 are seconds, otherwise milliseconds.
+ */
+export function resetsAtToMs(resetsAt) {
+    return resetsAt < 1e12 ? resetsAt * 1000 : resetsAt;
+}
+/**
+ * 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) {
+    const ms = resetsAtToMs(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 +210,6 @@ export const ERROR_TYPE_MAP = {
     BuildError: BuildError,
     TimeoutError: TimeoutError,
     SubprocessError: SubprocessError,
+    RateLimitError: RateLimitError,
+    BillingError: BillingError,
 };

package/dist/src/lib/manifest.js

@@ -2,6 +2,7 @@
  * Manifest management for tracking installed version
  */
 import { readFile, writeFile, fileExists } from "./fs.js";
+import { compareVersions } from "./version-check.js";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 import { readFileSync } from "fs";
@@ -32,23 +33,6 @@ const PACKAGE_VERSION = pkg.version;
 export function getPackageVersion() {
     return PACKAGE_VERSION;
 }
-/**
- * Compare two semver versions.
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareVersions(a, b) {
-    const partsA = a.split(".").map(Number);
-    const partsB = b.split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-        const numA = partsA[i] || 0;
-        const numB = partsB[i] || 0;
-        if (numA > numB)
-            return 1;
-        if (numA < numB)
-            return -1;
-    }
-    return 0;
-}
 export async function getManifest() {
     if (!(await fileExists(MANIFEST_PATH))) {
         return null;

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

@@ -214,16 +214,13 @@ export function isCacheFresh(cache) {
  * Fetch the latest version from npm registry with timeout
  */
 export async function fetchLatestVersion() {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), VERSION_CHECK_TIMEOUT);
     try {
         const response = await fetch(NPM_REGISTRY_URL, {
-            signal: controller.signal,
+            signal: AbortSignal.timeout(VERSION_CHECK_TIMEOUT),
             headers: {
                 Accept: "application/json",
             },
         });
-        clearTimeout(timeoutId);
         if (!response.ok) {
             return null;
         }
@@ -231,7 +228,6 @@ export async function fetchLatestVersion() {
         return data.version || null;
     }
     catch {
-        clearTimeout(timeoutId);
         return null;
     }
 }
@@ -258,6 +254,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.d.ts

@@ -8,6 +8,7 @@
  * creation).
  */
 import { ExecutionConfig, PhaseResult, IssueResult, type RunOptions, type IssueExecutionContext, type BatchExecutionContext, type ProgressCallback } from "./types.js";
+import { type ErrorCategory } from "./error-classifier.js";
 export type { RunOptions, ProgressCallback, IssueExecutionContext, BatchExecutionContext, } from "./types.js";
 /**
  * Emit a structured progress line to stderr for MCP progress notifications.
@@ -73,4 +74,16 @@ export declare function parseBatches(batchArgs: string[]): number[][];
  */
 export declare function getEnvConfig(): Partial<RunOptions>;
 export declare function executeBatch(issueNumbers: number[], batchCtx: BatchExecutionContext): Promise<IssueResult[]>;
+/**
+ * Derive the bounded-enum failure category for a failed issue (#761 AC-7).
+ *
+ * Scans for the LAST non-loop failing phase — the same reverse scan
+ * `toIssueSummary` uses (#766), so the recorded category and the displayed
+ * failure reason describe the same attempt. Prefers the driver's structured
+ * cause over stderr-regex classification (#732). Returns only the enum value;
+ * message strings never leave this function (metrics privacy contract).
+ *
+ * @internal Exported for testing
+ */
+export declare function deriveFailureCategory(phaseResults: PhaseResult[]): ErrorCategory | undefined;
 export declare function runIssueWithLogging(ctx: IssueExecutionContext): Promise<IssueResult>;