sequant 2.7.0 → 2.9.0

package/dist/marketplace/external_plugins/sequant/skills/upstream/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: upstream
+description: "Monitor Claude Code releases, assess compatibility with sequant, and create issues for breaking changes and deprecations. Opportunities are noted in assessment reports for human triage."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash(gh *)
+  - Bash(git *)
+  - Bash(jq *)
+  - Bash(base64 *)
+  - Bash(npx tsx *)
+---
+
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/upstream/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/upstream` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
+# Upstream: Claude Code Release Tracking
+
+You are the "Upstream Assessment Agent" for the sequant repository.
+
+## Purpose
+
+When invoked as `/upstream`, your job is to:
+
+1. Fetch Claude Code release information from the public GitHub repo
+2. Analyze changes against sequant's current capabilities baseline
+3. Detect relevant changes using keyword matching and regex patterns
+4. Skip out-of-scope changes (configured in baseline.json `outOfScope`)
+5. Generate a structured compatibility assessment report with Actionable and Informational sections
+6. Auto-create GitHub issues for breaking changes, deprecations, new tools, and hook changes
+7. List opportunities in the assessment report for human triage (no individual issues created)
+
+## Invocation
+
+```bash
+# Analyze latest release
+/upstream
+
+# Analyze specific version
+/upstream v2.1.29
+
+# Analyze all releases since version
+/upstream --since v2.1.25
+
+# Dry-run mode (no issues created)
+/upstream --dry-run
+
+# Help
+/upstream --help
+```
+
+## Assessment Process
+
+### 1. Parse Arguments
+
+Parse the command arguments to determine:
+
+- **Target version**: Specific version (e.g., `v2.1.29`) or `latest`
+- **Since version**: If `--since` flag provided, assess all versions since that release
+- **Dry-run mode**: If `--dry-run` flag, generate report but skip issue creation
+- **Help**: If `--help` flag, show usage instructions
+
+### 2. Fetch Release Data
+
+Fetch release information from the public Claude Code repository:
+
+```bash
+# Get latest release
+gh release view --repo anthropics/claude-code --json tagName,name,body,publishedAt
+
+# Get specific version
+gh release view v2.1.29 --repo anthropics/claude-code --json tagName,name,body,publishedAt
+
+# List releases for --since support
+gh release list --repo anthropics/claude-code --limit 50 --json tagName,publishedAt
+```
+
+### 3. Load Baseline
+
+Load the sequant capabilities baseline from `.sequant/upstream/baseline.json`:
+
+```json
+{
+  "lastAssessedVersion": "v2.1.25",
+  "tools": {
+    "core": ["Task", "Bash", "Read", "Write", "Edit", "Glob", "Grep"],
+    "optional": ["WebFetch", "WebSearch", "NotebookEdit"]
+  },
+  "hooks": {
+    "used": ["PreToolUse"],
+    "files": ["src/hooks/pre-tool-hook.ts"]
+  },
+  "mcpServers": {
+    "required": [],
+    "optional": ["chrome-devtools", "context7", "sequential-thinking"]
+  },
+  "keywords": [
+    "Task", "Bash", "hook", "PreToolUse", "PostToolUse",
+    "MCP", "permission", "allow", "deny", "tool",
+    "background", "parallel", "agent", "subagent",
+    "settings", "config", "plugin"
+  ],
+  "dependencyMap": {
+    "permission": ["src/hooks/pre-tool-hook.ts", ".claude/settings.json"],
+    "hook": ["src/hooks/pre-tool-hook.ts"],
+    "Task": [".claude/skills/**/*.md", "src/lib/workflow/*.ts"],
+    "MCP": ["docs/mcp-integrations.md", ".claude/settings.json"]
+  },
+  "outOfScope": [
+    "PDF/document processing - users work with code and GitHub issues",
+    "Slack/OAuth integrations - workflow is GitHub-centric",
+    "Notebook editing - not a data science tool",
+    "IDE-specific features (VSCode, JetBrains) - sequant is CLI/terminal focused",
+    "Windows-specific fixes - sequant targets macOS/Linux"
+  ]
+}
+```
+
+### 4. Analyze Changes
+
+For each release, analyze the changelog/release body:
+
+**Step 1: Extract Changes**
+
+Parse the release body to extract individual change items. Common formats:
+- Bullet points: `- Added new feature X`
+- "What's changed" sections
+- BREAKING CHANGE markers
+
+**Step 2: Relevance Detection**
+
+For each change, check if it's relevant to sequant:
+
+```typescript
+// Keyword matching
+const isRelevant = baseline.keywords.some(kw =>
+  change.toLowerCase().includes(kw.toLowerCase())
+);
+
+// Pattern matching
+const patterns = {
+  newTool: /added.*tool|new.*tool|introducing/i,
+  deprecation: /deprecat|remov|no longer support/i,
+  breaking: /breaking|incompatible|must update/i,
+  hook: /hook|PreToolUse|PostToolUse/i,
+  permission: /permission|allow|deny|ask/i,
+};
+```
+
+**Step 3: Categorize**
+
+Categorize each relevant change:
+
+| Category | Detection Pattern | Issue Labels |
+|----------|------------------|--------------|
+| `breaking` | Breaking, incompatible, must update | `upstream`, `bug`, `priority:high` |
+| `deprecation` | Deprecated, removed, no longer supported | `upstream`, `bug` |
+| `new-tool` | Added tool, new tool, introducing | `upstream`, `enhancement` |
+| `hook-change` | Hook, PreToolUse, PostToolUse | `upstream`, `enhancement` |
+| `opportunity` | Keywords match but not above categories | (no issue — noted in assessment for human triage) |
+| `no-action` | Doesn't match patterns or keywords | (no issue) |
+
+**Step 4: Impact Mapping**
+
+For relevant changes, map to affected sequant files using `dependencyMap`:
+
+```typescript
+const impactFiles = baseline.dependencyMap[matchedKeyword] || [];
+```
+
+### 5. Check for Duplicates
+
+Before creating issues, check for existing upstream issues:
+
+```bash
+# Search for similar issues
+gh issue list --label upstream --search "<finding-title>" --json number,title
+```
+
+If a similar issue exists:
+- Add a comment linking to the new assessment
+- Skip creating a duplicate
+
+### 6. Generate Outputs
+
+**Output 1: Assessment Report (GitHub Issue)**
+
+Create a summary issue with the full assessment:
+
+```markdown
+## Upstream: Claude Code <version> Assessment
+
+**Release:** [<version>](https://github.com/anthropics/claude-code/releases/tag/<version>)
+**Released:** <date>
+**Assessed:** <today>
+
+### Summary
+
+| Category | Count | Action Required |
+|----------|-------|-----------------|
+| Breaking Changes | N | [status] |
+| New Tools | N | [status] |
+| Deprecations | N | [status] |
+| Opportunities | N | [status] |
+
+### Actionable
+
+*Breaking changes, deprecations, and other items that affect sequant.*
+
+[list of breaking, deprecation, new-tool, hook-change findings]
+
+### Informational
+
+*Opportunities noted for human triage. No individual issues auto-created.*
+
+[list of opportunity findings]
+
+### No Action Required
+
+[list of irrelevant changes]
+
+---
+
+*Generated by /upstream skill*
+```
+
+**Output 2: Individual Issues (Actionable Findings)**
+
+For each actionable finding (breaking, deprecation, new-tool, hook-change), create an issue.
+**Note:** Opportunities do NOT get individual issues — they are listed in the assessment report's Informational section for human triage.
+
+```markdown
+## feat: Leverage <feature> from Claude Code <version>
+
+**Upstream:** Claude Code <version>
+**Category:** <category>
+**Assessment:** #<assessment-issue>
+
+### Context
+
+<description from release notes>
+
+### Opportunity
+
+<how sequant could use this>
+
+### Proposed Implementation
+
+[To be determined during /spec phase]
+
+### Acceptance Criteria
+
+- [ ] AC-1: [To be defined]
+
+---
+
+*Auto-created by /upstream assessment #<N>*
+```
+
+Labels: `upstream`, `needs-triage`, `enhancement`
+
+**Output 3: Local Report**
+
+Save to `.sequant/upstream/<version>.md`:
+
+```markdown
+# Claude Code <version> Assessment
+
+Assessed: <date>
+Previous: <last-assessed-version>
+
+## Summary
+
+[same as GitHub issue]
+
+## Raw Findings
+
+[detailed analysis data]
+```
+
+**Output 4: Update Baseline**
+
+Update `.sequant/upstream/baseline.json`:
+- Set `lastAssessedVersion` to the assessed version
+
+### 7. Multi-Version Batching
+
+When `--since <version>` is used:
+
+1. List all releases after the specified version
+2. Assess each version individually
+3. Create a batched summary issue linking all individual assessments
+4. Update baseline to latest assessed version
+
+## Dry-Run Mode
+
+When `--dry-run` is specified:
+
+1. Perform full analysis
+2. Generate local report
+3. Output what issues WOULD be created (titles, labels)
+4. Skip actual GitHub issue creation
+5. Skip baseline update
+
+## Error Handling
+
+- **No releases found**: Exit with clear message
+- **Baseline missing**: Create default baseline, warn user
+- **GitHub API errors**: Retry with backoff, then fail gracefully
+- **Already assessed**: Skip with message (idempotent)
+
+## Output Verification
+
+**Before completing, verify:**
+
+- [ ] Release data successfully fetched
+- [ ] Baseline loaded (or created with defaults)
+- [ ] Each change categorized
+- [ ] Duplicates checked before issue creation
+- [ ] Assessment report created (or dry-run output shown)
+- [ ] Individual issues created for actionable findings (not opportunities)
+- [ ] Local report saved
+- [ ] Baseline updated with new version
+
+## Examples
+
+### Example 1: Assess Latest Release
+
+```
+/upstream
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+Loading baseline from .sequant/upstream/baseline.json...
+Last assessed: v2.1.27
+
+Analyzing 12 changes from release notes...
+- 3 relevant changes detected
+- 9 no-action changes
+
+Findings:
+1. [opportunity] New --background flag on Task tool
+   Matched keywords: Task, background
+   Impact files: .claude/skills/**/*.md
+
+2. [hook-change] Permissions now respect content-level ask
+   Matched keywords: permission
+   Impact files: src/hooks/pre-tool-hook.ts
+
+3. [deprecation] oldHookName deprecated
+   Matched pattern: deprecat
+   Impact files: src/hooks/pre-tool-hook.ts
+
+Creating assessment issue...
+Created: #250 - Upstream: Claude Code v2.1.29 Assessment
+
+Creating individual issues...
+Created: #251 - feat: Leverage new --background flag from Claude Code v2.1.29
+Created: #252 - chore: Update to new hook name (deprecation from v2.1.29)
+
+Saving local report to .sequant/upstream/v2.1.29.md...
+Updating baseline lastAssessedVersion to v2.1.29...
+
+Done! Assessment complete.
+```
+
+### Example 2: Dry Run
+
+```
+/upstream --dry-run
+
+[DRY RUN MODE - No issues will be created]
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+...analysis...
+
+Would create issues:
+1. Assessment: Upstream: Claude Code v2.1.29 Assessment
+2. Finding: feat: Leverage new --background flag from Claude Code v2.1.29
+3. Finding: chore: Update to new hook name (deprecation from v2.1.29)
+
+Local report saved: .sequant/upstream/v2.1.29.md
+Baseline NOT updated (dry-run mode)
+```
+
+### Example 3: Already Assessed
+
+```
+/upstream
+
+Fetching latest Claude Code release...
+Release: v2.1.29 (2025-01-31)
+
+Already assessed: .sequant/upstream/v2.1.29.md exists
+Use --force to re-assess.
+
+No action taken.
+```
+
+## Notes
+
+- This is an internal tool for sequant maintainers
+- All created issues get `needs-triage` label for human review
+- The skill is read-only for Claude Code repo (no PRs or edits)
+- Baseline file should be committed to version control
+- Local reports in `.sequant/upstream/` should be committed
+
+---
+
+*This skill monitors the upstream Claude Code project to help sequant stay current with new features and breaking changes.*

package/dist/src/commands/logs.js

@@ -81,6 +81,9 @@ function formatTime(isoString) {
 function displayLogSummary(log, filename, options) {
     const passed = log.summary.passed;
     const failed = log.summary.failed;
+    // #766: `partial` gets its own bucket so an all-partial run isn't rendered as
+    // `0 passed, 0 failed` (older logs predate the field → default to 0).
+    const partial = log.summary.partial ?? 0;
     const total = log.summary.totalIssues;
     const status = failed > 0
         ? chalk.red("FAILED")
@@ -91,7 +94,9 @@ function displayLogSummary(log, filename, options) {
     console.log(chalk.gray(`  File: ${filename}`));
     console.log(chalk.gray(`  Time: ${formatTime(log.startTime)}`));
     console.log(chalk.gray(`  Duration: ${formatDuration(log.summary.totalDurationSeconds)}`));
-    console.log(chalk.gray(`  Status: ${status} (${passed}/${total} passed, ${failed} failed)`));
+    console.log(chalk.gray(`  Status: ${status} (${passed}/${total} passed, ${failed} failed` +
+        (partial > 0 ? `, ${partial} partial` : "") +
+        `)`));
     console.log(chalk.gray(`  Phases: ${log.config.phases.join(" → ")}`));
     // Show issues
     for (const issue of log.issues) {

package/dist/src/commands/run-display.d.ts

@@ -9,6 +9,7 @@
  */
 import type { RunRenderer } from "../lib/cli-ui/run-renderer-types.js";
 import type { ResolvedRun, RunResult } from "../lib/workflow/run-orchestrator.js";
+import type { IssueResult } from "../lib/workflow/types.js";
 /**
  * Print pre-run config block.
  *
@@ -16,6 +17,25 @@ import type { ResolvedRun, RunResult } from "../lib/workflow/run-orchestrator.js
  * appear when non-default, matching the pre-#503 format.
  */
 export declare function displayConfig(r: ResolvedRun): void;
+/**
+ * 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 declare function buildRateLimitHaltNotice(results: IssueResult[], chainEnabled: boolean): {
+    issueNumber: number;
+    label: string;
+} | null;
 /**
  * Print post-run summary: per-issue grid, log path, reflection, tips.
  *

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,