sequant 2.8.0 → 2.9.0

package/dist/src/commands/run-display.js

@@ -10,7 +10,9 @@
 import chalk from "chalk";
 import { ui, colors } from "../lib/cli-ui.js";
 import { renderRunSummary } from "../lib/cli-ui/run-renderer.js";
+import { BillingError, RateLimitError, formatRateLimitMessage, isBillingFailure, } from "../lib/errors.js";
 import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
+import { LOOP_PHASE } from "../lib/workflow/status-derivation.js";
 /**
  * Print pre-run config block.
  *
@@ -67,7 +69,19 @@ export function displayConfig(r) {
  * Convert workflow `IssueResult` to renderer `IssueSummary`.
  */
 function toIssueSummary(r) {
-    const failedPhase = r.phaseResults.find((p) => !p.success);
+    // #766: the reason to show is the LAST failing attempt, not the first.
+    // `phaseResults` accumulates every attempt across every quality-loop
+    // iteration, so `.find()` (first-wins) rendered a stale first-iteration
+    // reason: #762's cell read `Timeout after 1800s` when its real last failure
+    // was an API drop. `verdict`/`unmetCount` below hang off the same entry, so
+    // they were stale for the same reason. `loop` is excluded on the same grounds
+    // the card and log exclude it (see `status-derivation.ts`) — it is auxiliary
+    // recovery, and a trailing loop failure would mask the phase that actually
+    // failed. Reverse scan rather than `findLast`: tsconfig pins `lib: ES2022`
+    // and `findLast` is ES2023.
+    const failedPhase = [...r.phaseResults]
+        .reverse()
+        .find((p) => !p.success && p.phase !== LOOP_PHASE);
     const summary = {
         issueNumber: r.issueNumber,
         success: r.success,
@@ -91,6 +105,48 @@ function toIssueSummary(r) {
     }
     return summary;
 }
+/**
+ * Detect a chain halted by a rate-limit/billing failure and build the summary
+ * notice for it (#761 AC-5). Returns null when the run wasn't a chain, no
+ * issue failed, or the halting failure wasn't rate-limit-classified.
+ *
+ * Extracted from `displaySummary` so the halt-and-print decision is testable
+ * standalone — the same treatment #760 gave `planChainResumeFromState` when it
+ * hit the executeSequential testability wall.
+ *
+ * The failing phase is found with the same reverse non-loop scan as
+ * `toIssueSummary` (#766): the classification must describe the LAST attempt,
+ * not a stale first-iteration failure.
+ *
+ * @internal Exported for testing
+ */
+export function buildRateLimitHaltNotice(results, chainEnabled) {
+    if (!chainEnabled)
+        return null;
+    // Chain mode halts at the first failed link, so at most one failed issue
+    // exists; scan defensively anyway.
+    for (const r of results) {
+        if (r.success)
+            continue;
+        const failedPhase = [...r.phaseResults]
+            .reverse()
+            .find((p) => !p.success && p.phase !== LOOP_PHASE);
+        const err = failedPhase?.structuredError;
+        if (err instanceof RateLimitError || err instanceof BillingError) {
+            // Event-derived errors get their message from formatRateLimitMessage, so
+            // re-deriving from metadata is exact and includes resetsAt. But errors
+            // from the assistant-error channel carry no billing/reset metadata —
+            // re-deriving there would mislabel a BillingError as "Rate limited"
+            // (isBillingFailure({}) is false) — so fall back to the typed message
+            // when the metadata carries no signal.
+            const label = err.metadata.resetsAt !== undefined || isBillingFailure(err.metadata)
+                ? formatRateLimitMessage(err.metadata)
+                : err.message;
+            return { issueNumber: r.issueNumber, label };
+        }
+    }
+    return null;
+}
 /**
  * Print post-run summary: per-issue grid, log path, reflection, tips.
  *
@@ -120,6 +176,29 @@ export function displaySummary(result, renderer) {
             dryRun: config.dryRun,
         });
     }
+    // #760: a chain link whose checkpoint commit failed keeps its own work but
+    // loses the recovery point resume depends on, and the per-issue warning has
+    // long scrolled past by now on a multi-hour chain. Restate it at the summary,
+    // where the user is actually looking, so the next run's fail-fast is expected.
+    const checkpointFailures = results.filter((r) => r.checkpointFailed);
+    if (checkpointFailures.length > 0) {
+        console.log(colors.warning(`  ⚠️  Checkpoint commit failed for ${checkpointFailures
+            .map((r) => `#${r.issueNumber}`)
+            .join(", ")} — uncommitted work is missing from the feature branch.`));
+        console.log(colors.muted("     Resuming this chain will stop at that link until the work is committed (or use --force)."));
+        console.log("");
+    }
+    // #761: a chain halted by a rate limit already stopped at the right link,
+    // but the labeled cause has long scrolled past by now (same rationale as the
+    // #760 restatement above), and #760 added no resume flag — resume IS
+    // re-running the identical command. Say both explicitly, or the halt reads
+    // as a bug and the resume path stays undiscovered.
+    const rateLimitHalt = buildRateLimitHaltNotice(results, mergedOptions.chain === true);
+    if (rateLimitHalt) {
+        console.log(colors.warning(`  ⚠️  ${rateLimitHalt.label} — chain halted at #${rateLimitHalt.issueNumber}.`));
+        console.log(colors.muted(`     Re-run the same command to resume from #${rateLimitHalt.issueNumber} (no flag needed; completed links are skipped).`));
+        console.log("");
+    }
     if (mergedOptions.reflect && results.length > 0) {
         const reflection = analyzeRun({
             results,

package/dist/src/commands/stats.js

@@ -263,6 +263,35 @@ function loadMetrics() {
         return null;
     }
 }
+/**
+ * Compute the failure-category breakdown over runs that recorded a failure —
+ * outcome "failed" (every issue failed) or "partial" (at least one issue
+ * failed) (#783).
+ *
+ * NOTE — deviation from AC-1's literal "over failed runs" wording: partial runs
+ * also carry a failureCategory (recorded whenever >=1 issue fails) and are
+ * genuine signal for "what's killing my runs", so they are counted here by
+ * explicit user decision. Success runs never carry the field and are excluded.
+ *
+ * Runs without the field (pre-#761 records, or a partial whose failure was
+ * never categorized) are bucketed as "unclassified" — never dropped and never
+ * conflated with the "unknown" enum value.
+ *
+ * Pure function of the passed runs array, so any upstream cohort filtering is
+ * automatically respected (computed after filtering, not before).
+ */
+function calculateFailureCategoryBreakdown(runs) {
+    const counts = new Map();
+    for (const run of runs) {
+        if (run.outcome === "success")
+            continue;
+        const category = run.failureCategory ?? "unclassified";
+        counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([category, count]) => ({ category, count }))
+        .sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
+}
 /**
  * Calculate analytics from metrics
  */
@@ -274,6 +303,7 @@ function calculateMetricsAnalytics(metrics) {
             successCount: 0,
             partialCount: 0,
             failedCount: 0,
+            failureCategories: [],
             successRate: 0,
             avgTokensPerRun: 0,
             avgFilesChanged: 0,
@@ -294,6 +324,7 @@ function calculateMetricsAnalytics(metrics) {
     const successCount = runs.filter((r) => r.outcome === "success").length;
     const partialCount = runs.filter((r) => r.outcome === "partial").length;
     const failedCount = runs.filter((r) => r.outcome === "failed").length;
+    const failureCategories = calculateFailureCategoryBreakdown(runs);
     const successRate = (successCount / runs.length) * 100;
     const avgTokensPerRun = runs.reduce((sum, r) => sum + r.metrics.tokensUsed, 0) / runs.length;
     const avgFilesChanged = runs.reduce((sum, r) => sum + r.metrics.filesChanged, 0) / runs.length;
@@ -323,6 +354,7 @@ function calculateMetricsAnalytics(metrics) {
         successCount,
         partialCount,
         failedCount,
+        failureCategories,
         successRate,
         avgTokensPerRun,
         avgFilesChanged,
@@ -415,6 +447,19 @@ function displayMetricsAnalytics(analytics) {
         const failedRate = (analytics.failedCount / total) * 100;
         console.log(`  ${colors.error("\u2717 Failed")}    ${analytics.failedCount} (${failedRate.toFixed(0)}%)    ${failedBar}`);
     }
+    // Failure-category breakdown (#783) \u2014 adjacent to the outcome bars above.
+    // Counts runs that recorded a failure (outcome "failed" or "partial"); hidden
+    // entirely when there are none (AC-3).
+    if (analytics.failureCategories.length > 0) {
+        const failureRunCount = analytics.failureCategories.reduce((sum, b) => sum + b.count, 0);
+        const runNoun = failureRunCount === 1 ? "run with a failure" : "runs with a failure";
+        console.log(ui.sectionHeader(`Failure Categories (${failureRunCount} ${runNoun})`));
+        const pad = Math.max(...analytics.failureCategories.map((b) => b.category.length));
+        for (const bucket of analytics.failureCategories) {
+            const pct = ((bucket.count / failureRunCount) * 100).toFixed(0);
+            console.log(`  ${bucket.category.padEnd(pad)}  ${bucket.count} (${pct}%)`);
+        }
+    }
     // Averages table
     console.log(ui.sectionHeader("Averages"));
     const avgData = {};
@@ -653,6 +698,8 @@ export async function statsCommand(options) {
                 partialCount: analytics.partialCount,
                 failedCount: analytics.failedCount,
                 successRate: analytics.successRate,
+                // Failure-category breakdown over failed runs (#783 AC-5)
+                failureCategories: analytics.failureCategories,
                 avgTokensPerRun: analytics.avgTokensPerRun,
                 avgFilesChanged: analytics.avgFilesChanged,
                 avgLinesAdded: analytics.avgLinesAdded,

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

@@ -156,6 +156,12 @@ export declare function isBillingFailure(info: RateLimitInfoLike): boolean;
  * 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

package/dist/src/lib/errors.js

@@ -123,6 +123,14 @@ export function isBillingFailure(info) {
 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.
  *
@@ -133,8 +141,7 @@ export function isRateLimitFailureInfo(info) {
  * 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 ms = resetsAtToMs(resetsAt);
     const d = new Date(ms);
     const hh = String(d.getHours()).padStart(2, "0");
     const mm = String(d.getMinutes()).padStart(2, "0");

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.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;
     }
 }

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>;