@hegemonart/get-design-done 1.19.6 → 1.20.0

package/scripts/aggregate-agent-metrics.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * aggregate-agent-metrics.ts — Incremental per-agent aggregator.
+ *
+ * Reads: .design/telemetry/costs.jsonl (append-only ledger from
+ *        hooks/budget-enforcer.js)
+ *        agents/{agent}.md (frontmatter source for default-tier, parallel-safe,
+ *        reads-only, typical-duration-seconds)
+ * Writes: .design/agent-metrics.json (atomic overwrite via tmp-file + rename)
+ *         .design/telemetry/phase-totals.json (same, WR-02)
+ *
+ * Invoked:
+ *   1. Detached child of hooks/budget-enforcer.js after every telemetry write.
+ *   2. Directly by /gdd:optimize skill as an explicit refresh step.
+ *   3. Manually: `node --experimental-strip-types scripts/aggregate-agent-metrics.ts`
+ *   4. With `--help` to print usage (used by the Plan 20-00 smoke check).
+ *
+ * OPT-09 contract: fields must match Phase 11 reflector's expectations.
+ *
+ * Converted from scripts/aggregate-agent-metrics.js in Plan 20-00 (Tier-1).
+ * Behavior preserved verbatim.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+} from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+// Generated-type import (unused at runtime, erased by strip-types) to satisfy
+// Plan 20-00's requirement that every Tier-1 TS file participates in the
+// codegen graph. We pick AuthoritySnapshotSchema as a stable anchor and
+// re-export for downstream callers.
+import type { AuthoritySnapshotSchema } from '../reference/schemas/generated.js';
+export type { AuthoritySnapshotSchema };
+
+const CWD: string = process.cwd();
+const TELEMETRY_PATH: string = join(CWD, '.design', 'telemetry', 'costs.jsonl');
+const METRICS_PATH: string = join(CWD, '.design', 'agent-metrics.json');
+const PHASE_TOTALS_PATH: string = join(CWD, '.design', 'telemetry', 'phase-totals.json');
+const AGENTS_DIR: string = join(CWD, 'agents');
+
+/**
+ * Subset of the agent-markdown frontmatter we care about. `null` means the
+ * field is absent or unparseable (aggregator is tolerant — degraded mode
+ * preferred over hard-fail per OPT-09).
+ */
+interface AgentFrontmatter {
+  default_tier: string | null;
+  parallel_safe: boolean | null;
+  reads_only: boolean | null;
+  typical_duration_seconds: number | null;
+}
+
+/** ---- frontmatter reader (no YAML dep) ---- */
+function readAgentFrontmatter(agentName: string): Partial<AgentFrontmatter> {
+  const p: string = join(AGENTS_DIR, `${agentName}.md`);
+  if (!existsSync(p)) return {};
+  try {
+    const content: string = readFileSync(p, 'utf8');
+    const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!fm) return {};
+    const body: string = fm[1] ?? '';
+    const get = (key: string): string | null => {
+      const m = body.match(new RegExp(`^${key}:\\s*"?([^"\\n]+)"?`, 'm'));
+      return m && m[1] !== undefined ? m[1].trim() : null;
+    };
+    const defaultTier: string | null = get('default-tier');
+    const parallelSafe: string | null = get('parallel-safe');
+    const readsOnly: string | null = get('reads-only');
+    const typicalDuration: string | null = get('typical-duration-seconds');
+    return {
+      default_tier: defaultTier ?? null,
+      parallel_safe: parallelSafe === null ? null : /^(true|yes)$/i.test(parallelSafe),
+      reads_only: readsOnly === null ? null : /^(true|yes)$/i.test(readsOnly),
+      typical_duration_seconds:
+        typicalDuration === null ? null : Number(typicalDuration) || null,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Shape of a single row in .design/telemetry/costs.jsonl. Mirrors the OPT-09
+ * schema: nine mandatory fields + four optional diagnostic fields. Unknown
+ * keys are tolerated (Phase 11 reflector ignores them).
+ */
+export interface CostRow {
+  ts?: string;
+  agent?: string;
+  tier?: string;
+  tokens_in?: number | string;
+  tokens_out?: number | string;
+  cache_hit?: boolean;
+  est_cost_usd?: number | string;
+  cycle?: string;
+  phase?: string;
+  // Optional / diagnostic
+  tier_downgraded?: boolean;
+  enforcement_mode?: string;
+  lazy_skipped?: boolean;
+  block_reason?: string;
+}
+
+/** ---- telemetry reader ---- */
+function readTelemetryRows(): CostRow[] {
+  if (!existsSync(TELEMETRY_PATH)) return [];
+  const raw: string = readFileSync(TELEMETRY_PATH, 'utf8');
+  const out: CostRow[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as CostRow);
+    } catch {
+      // tolerant: skip malformed lines (partial write, truncation)
+    }
+  }
+  return out;
+}
+
+/** Per-agent roll-up accumulator. */
+interface AgentAccumulator {
+  total_spawns: number;
+  total_cost_usd: number;
+  total_tokens_in: number;
+  total_tokens_out: number;
+  cache_hits: number;
+  lazy_skips: number;
+}
+
+/** Final per-agent shape written to .design/agent-metrics.json. */
+export interface AgentMetrics {
+  typical_duration_seconds: number | null | undefined;
+  default_tier: string | null | undefined;
+  parallel_safe: boolean | null | undefined;
+  reads_only: boolean | null | undefined;
+  total_spawns: number;
+  total_cost_usd: number;
+  total_tokens_in: number;
+  total_tokens_out: number;
+  cache_hit_rate: number;
+  lazy_skip_rate: number;
+}
+
+/** ---- aggregator ---- */
+function aggregate(rows: readonly CostRow[]): Record<string, AgentMetrics> {
+  const byAgent = new Map<string, AgentAccumulator>();
+  for (const r of rows) {
+    // Blocked rows represent a spawn that was denied at the hook — the agent
+    // never actually ran, so it must not contribute to spawn counts, cost, or
+    // token totals. Skip them here (mirror of the filter in aggregateByPhase).
+    if (r.block_reason) continue;
+    const agent: string = r.agent ?? 'unknown';
+    let a = byAgent.get(agent);
+    if (!a) {
+      a = {
+        total_spawns: 0,
+        total_cost_usd: 0,
+        total_tokens_in: 0,
+        total_tokens_out: 0,
+        cache_hits: 0,
+        lazy_skips: 0,
+      };
+      byAgent.set(agent, a);
+    }
+    a.total_spawns += 1;
+    a.total_cost_usd += Number(r.est_cost_usd ?? 0);
+    a.total_tokens_in += Number(r.tokens_in ?? 0);
+    a.total_tokens_out += Number(r.tokens_out ?? 0);
+    if (r.cache_hit === true) a.cache_hits += 1;
+    if (r.lazy_skipped === true) a.lazy_skips += 1;
+  }
+
+  const out: Record<string, AgentMetrics> = {};
+  for (const [agent, a] of byAgent.entries()) {
+    const fm = readAgentFrontmatter(agent);
+    const spawns: number = a.total_spawns || 1; // guard div-by-zero
+    out[agent] = {
+      typical_duration_seconds: fm.typical_duration_seconds,
+      default_tier: fm.default_tier,
+      parallel_safe: fm.parallel_safe,
+      reads_only: fm.reads_only,
+      total_spawns: a.total_spawns,
+      total_cost_usd: Number(a.total_cost_usd.toFixed(6)),
+      total_tokens_in: a.total_tokens_in,
+      total_tokens_out: a.total_tokens_out,
+      cache_hit_rate: Number((a.cache_hits / spawns).toFixed(4)),
+      lazy_skip_rate: Number((a.lazy_skips / spawns).toFixed(4)),
+    };
+  }
+  return out;
+}
+
+/** ---- atomic write ---- */
+function writeAtomic(filePath: string, content: string): void {
+  const dir: string = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp: string = join(
+    dir,
+    `.${basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  writeFileSync(tmp, content, 'utf8');
+  renameSync(tmp, filePath);
+}
+
+/** ---- phase totals aggregator (WR-02: avoids full JSONL replay in budget enforcer) ---- */
+function aggregateByPhase(rows: readonly CostRow[]): Record<string, number> {
+  const byPhase: Record<string, number> = {};
+  for (const r of rows) {
+    // Blocked rows represent spawns that were denied by the hook — the agent
+    // never ran, so their est_cost_usd must not inflate cumulative phase spend.
+    // Counting them would make future hard-block and soft-threshold checks
+    // stricter than intended on every repeat cap hit.
+    if (r.block_reason) continue;
+    const phase: string = r.phase ?? 'unknown';
+    byPhase[phase] = (byPhase[phase] ?? 0) + Number(r.est_cost_usd ?? 0);
+  }
+  // Round to 6dp to match per-agent precision
+  for (const k of Object.keys(byPhase)) {
+    const v: number = byPhase[k] ?? 0;
+    byPhase[k] = Number(v.toFixed(6));
+  }
+  return byPhase;
+}
+
+/** ---- usage / --help ---- */
+function printHelp(): void {
+  console.log(
+    `aggregate-agent-metrics.ts — Aggregate per-agent telemetry from .design/telemetry/costs.jsonl.\n` +
+      `\n` +
+      `Usage:\n` +
+      `  node --experimental-strip-types scripts/aggregate-agent-metrics.ts\n` +
+      `  node --experimental-strip-types scripts/aggregate-agent-metrics.ts --help\n` +
+      `\n` +
+      `Reads:  .design/telemetry/costs.jsonl\n` +
+      `        agents/<agent>.md (frontmatter)\n` +
+      `Writes: .design/agent-metrics.json\n` +
+      `        .design/telemetry/phase-totals.json\n` +
+      `\n` +
+      `Invoked:\n` +
+      `  - Detached child of hooks/budget-enforcer.js after every telemetry row.\n` +
+      `  - Directly by /gdd:optimize as an explicit refresh step.\n` +
+      `  - Manually, on demand.\n`,
+  );
+}
+
+/** ---- main ---- */
+function main(): void {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const rows: CostRow[] = readTelemetryRows();
+  const agents = aggregate(rows);
+  const payload = {
+    generated_at: new Date().toISOString(),
+    agents,
+  };
+  writeAtomic(METRICS_PATH, JSON.stringify(payload, null, 2) + '\n');
+  // Write lightweight phase-totals.json so budget-enforcer can read phase
+  // spend in O(1) without replaying the full JSONL on every agent spawn
+  // (WR-02).
+  const phaseTotals = {
+    generated_at: new Date().toISOString(),
+    totals: aggregateByPhase(rows),
+  };
+  writeAtomic(PHASE_TOTALS_PATH, JSON.stringify(phaseTotals, null, 2) + '\n');
+}
+
+try {
+  main();
+} catch (err) {
+  // Fail open: aggregator must never block the hook or /gdd:optimize flow.
+  const msg: string = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`aggregate-agent-metrics: ${msg}\n`);
+  process.exit(0);
+}

package/scripts/codegen-schema-types.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * codegen-schema-types.ts — Generate TypeScript interface declarations from
+ * every Draft-07 JSON Schema under `reference/schemas/*.schema.json`.
+ *
+ * Output: `reference/schemas/generated.d.ts` — single file containing one
+ * `export interface XSchema` per schema, named from the filename stem.
+ *
+ * Invoked: `npm run codegen:schemas` (requires repo-root cwd, which npm sets
+ * automatically). If invoked directly, `--repo-root <path>` can override.
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — any read/parse/compile failure
+ */
+import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, dirname, basename } from 'node:path';
+import { compile } from 'json-schema-to-typescript';
+
+/**
+ * Resolve the repo root. Priority:
+ *   1. `--repo-root <path>` CLI arg.
+ *   2. `process.cwd()` — npm scripts run from the package root, so this is
+ *      the common case.
+ *
+ * We deliberately avoid `import.meta.url` / `__dirname` so this module stays
+ * valid under both CommonJS type-checking (Node16 + no package "type") and
+ * the Node 22+ `--experimental-strip-types` runtime, which auto-detects ESM.
+ */
+function resolveRepoRoot(): string {
+  const argv = process.argv.slice(2);
+  const idx = argv.indexOf('--repo-root');
+  if (idx !== -1 && idx + 1 < argv.length) {
+    const v = argv[idx + 1];
+    if (typeof v === 'string' && v.length > 0) return resolve(v);
+  }
+  return resolve(process.cwd());
+}
+
+const REPO_ROOT = resolveRepoRoot();
+const SCHEMA_DIR = join(REPO_ROOT, 'reference', 'schemas');
+const OUTPUT_PATH = join(SCHEMA_DIR, 'generated.d.ts');
+
+const HEADER =
+  '// AUTO-GENERATED from reference/schemas/*.schema.json — DO NOT EDIT.\n' +
+  '// Regenerate: npm run codegen:schemas\n' +
+  '/* eslint-disable */\n';
+
+/**
+ * Map a schema filename stem (e.g. "authority-snapshot" from
+ * "authority-snapshot.schema.json") to the canonical interface name per
+ * Plan 20-00: PascalCase + `Schema` suffix. Hyphens split word boundaries.
+ */
+function stemToInterfaceName(stem: string): string {
+  const pascal = stem
+    .split(/[-_.]/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join('');
+  return `${pascal}Schema`;
+}
+
+async function main(): Promise<void> {
+  const entries = readdirSync(SCHEMA_DIR)
+    .filter((f) => f.endsWith('.schema.json'))
+    .sort();
+
+  if (entries.length === 0) {
+    console.error(`codegen-schema-types: no *.schema.json files found in ${SCHEMA_DIR}`);
+    process.exit(1);
+  }
+
+  const chunks: string[] = [HEADER];
+
+  for (const file of entries) {
+    const stem = basename(file, '.schema.json');
+    const interfaceName = stemToInterfaceName(stem);
+    const schemaPath = join(SCHEMA_DIR, file);
+
+    let schema: unknown;
+    try {
+      schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`codegen-schema-types: failed to parse ${file}: ${msg}`);
+      process.exit(1);
+    }
+
+    try {
+      // compile() expects a JSONSchema; we pass our parsed object.
+      // bannerComment: '' — we add our own header once at the top.
+      const ts = await compile(schema as Parameters<typeof compile>[0], interfaceName, {
+        bannerComment: '',
+        additionalProperties: false,
+        style: { singleQuote: true, trailingComma: 'all' },
+        unreachableDefinitions: false,
+      });
+      chunks.push(`// ---- ${file} ----\n`);
+      // json-schema-to-typescript emits the top-level as the requested name,
+      // but when the schema's own `title` differs it may prefix. We rename
+      // the top-level export to our canonical name for stability.
+      const renamed = ensureExportInterface(ts, interfaceName);
+      chunks.push(renamed);
+      chunks.push('\n');
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`codegen-schema-types: failed to compile ${file}: ${msg}`);
+      process.exit(1);
+    }
+  }
+
+  mkdirSync(dirname(OUTPUT_PATH), { recursive: true });
+  writeFileSync(OUTPUT_PATH, chunks.join(''), 'utf8');
+  console.log(
+    `codegen-schema-types: wrote ${OUTPUT_PATH} (${entries.length} schema(s))`,
+  );
+}
+
+/**
+ * Ensure that the compiled TS output exports an interface/type alias with the
+ * exact canonical name. `json-schema-to-typescript` normally emits this
+ * already, but some schemas whose `title` field contains non-identifier
+ * characters (e.g. ".design/config.json") get their interface named from a
+ * cleaned title rather than our requested name. We add an `export` alias at
+ * the end so every generated chunk guarantees `export interface XSchema` (or
+ * `export type XSchema = ...`) is available.
+ */
+function ensureExportInterface(ts: string, canonical: string): string {
+  const hasCanonical = new RegExp(
+    `export\\s+(interface|type)\\s+${canonical}\\b`,
+  ).test(ts);
+  if (hasCanonical) return ts;
+
+  const firstExport = ts.match(
+    /export\s+(interface|type)\s+([A-Za-z_][A-Za-z0-9_]*)/,
+  );
+  if (!firstExport) {
+    return ts + `\nexport type ${canonical} = unknown;\n`;
+  }
+  const firstName = firstExport[2];
+  if (firstName === canonical) return ts;
+  return ts + `\nexport type ${canonical} = ${firstName};\n`;
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`codegen-schema-types: ${msg}`);
+  process.exit(1);
+});

package/scripts/lib/error-classifier.cjs

@@ -0,0 +1,232 @@
+// scripts/lib/error-classifier.cjs
+//
+// Plan 20-14 — classify raw errors into a recovery-action vocabulary.
+//
+// Plan 20-04 shipped the GDDError taxonomy (ValidationError /
+// StateConflictError / OperationFailedError). This module is one layer
+// lower: it maps LOW-LEVEL errors (fetch rejections, Anthropic API
+// responses, Node errno rejections) onto a small enum that recovery
+// code can switch on without needing to know which SDK produced the
+// error.
+//
+// Consumers (e.g. budget-enforcer retry, figma probe retry, MCP
+// transport) check `classify(err).reason` and decide whether to retry,
+// compress, surface, or fail.
+//
+// Classification rules — evaluated in order; first match wins:
+//   1. HTTP 429  OR  message ~ /rate.?limit/       → RATE_LIMITED      (retryable)
+//   2. HTTP 413  OR  /context.?(length|window|overflow)/
+//                OR  /context_length_exceeded/     → CONTEXT_OVERFLOW  (retryable with compression)
+//   3. HTTP 401/403                                → AUTH_ERROR        (NOT retryable)
+//   4. /tool not found|unknown tool/               → TOOL_NOT_FOUND    (NOT retryable)
+//   5. HTTP 5xx  OR  errno ECONNRESET/ETIMEDOUT/EAI_AGAIN/ECONNREFUSED
+//                OR  /network|timeout|socket/       → NETWORK_TRANSIENT (retryable)
+//   6. HTTP 4xx (non-auth, non-rate, non-overflow) → VALIDATION        (NOT retryable)
+//   7. HTTP >= 400 with no other match             → NETWORK_PERMANENT (NOT retryable)
+//   8. Anything else (null, undefined, plain Error) → UNKNOWN          (NOT retryable)
+//
+// Rule order matters: the tool-not-found string can land inside
+// otherwise-validation-shaped errors, so it's checked early. Anthropic
+// "context_length_exceeded" returns HTTP 400 in some surfaces and HTTP
+// 413 in others — rule 2 catches it either way.
+//
+// Reference: `reference/error-recovery.md` describes the protocol layer
+// that sits on top of this module.
+
+'use strict';
+
+/**
+ * @readonly
+ * @enum {string}
+ */
+const FailoverReason = Object.freeze({
+  RATE_LIMITED: 'rate_limited',
+  CONTEXT_OVERFLOW: 'context_overflow',
+  AUTH_ERROR: 'auth_error',
+  NETWORK_TRANSIENT: 'network_transient',
+  NETWORK_PERMANENT: 'network_permanent',
+  TOOL_NOT_FOUND: 'tool_not_found',
+  VALIDATION: 'validation',
+  UNKNOWN: 'unknown',
+});
+
+/** Suggested actions per reason — keyed by FailoverReason. */
+const SUGGESTED_ACTIONS = Object.freeze({
+  [FailoverReason.RATE_LIMITED]:
+    'consult scripts/lib/rate-guard.cjs → blockUntilReady(provider); then retry with scripts/lib/jittered-backoff.cjs',
+  [FailoverReason.CONTEXT_OVERFLOW]:
+    'compress context (drop oldest non-system turns; target 50% reduction) and retry once',
+  [FailoverReason.AUTH_ERROR]:
+    'surface to user — do not retry; credentials or OAuth session need refresh',
+  [FailoverReason.NETWORK_TRANSIENT]:
+    'retry with scripts/lib/jittered-backoff.cjs; max 3 attempts',
+  [FailoverReason.NETWORK_PERMANENT]:
+    'surface to user; do not retry — endpoint is wrong or resource is gone',
+  [FailoverReason.TOOL_NOT_FOUND]:
+    'do not retry; verify tool name and MCP registration',
+  [FailoverReason.VALIDATION]:
+    'do not retry same input; surface validation detail to caller',
+  [FailoverReason.UNKNOWN]:
+    'surface to user — cannot determine safe recovery action',
+});
+
+/** Which reasons are safe to retry by policy. */
+const RETRYABLE = Object.freeze({
+  [FailoverReason.RATE_LIMITED]: true,
+  [FailoverReason.CONTEXT_OVERFLOW]: true,
+  [FailoverReason.NETWORK_TRANSIENT]: true,
+  [FailoverReason.AUTH_ERROR]: false,
+  [FailoverReason.NETWORK_PERMANENT]: false,
+  [FailoverReason.TOOL_NOT_FOUND]: false,
+  [FailoverReason.VALIDATION]: false,
+  [FailoverReason.UNKNOWN]: false,
+});
+
+/** Extract a numeric HTTP status from an error shape. Returns null on miss. */
+function statusOf(err) {
+  if (err === null || err === undefined) return null;
+  if (typeof err !== 'object') return null;
+  // Direct status / statusCode field.
+  if (Number.isFinite(err.status)) return Number(err.status);
+  if (Number.isFinite(err.statusCode)) return Number(err.statusCode);
+  // Fetch / node-fetch responses wrap status under .response.
+  if (err.response && typeof err.response === 'object') {
+    if (Number.isFinite(err.response.status)) return Number(err.response.status);
+    if (Number.isFinite(err.response.statusCode)) return Number(err.response.statusCode);
+  }
+  return null;
+}
+
+/** Extract a string message; tolerant of anything. */
+function messageOf(err) {
+  if (err === null || err === undefined) return '';
+  if (typeof err === 'string') return err;
+  if (typeof err === 'object') {
+    // Gather every string-ish field in priority order; join with ' | ' so
+    // classification regexes can match against any of them without the
+    // caller needing to know which SDK shaped the error. OpenAI-style
+    // wraps the interesting discriminator in `error.code` while keeping
+    // a generic top-level message; the join lets both contribute.
+    const parts = [];
+    if (typeof err.message === 'string' && err.message.length > 0) parts.push(err.message);
+    if (err.error && typeof err.error === 'object') {
+      if (typeof err.error.code === 'string') parts.push(err.error.code);
+      if (typeof err.error.type === 'string') parts.push(err.error.type);
+      if (typeof err.error.message === 'string') parts.push(err.error.message);
+    }
+    // Only use top-level `code` when it is NOT an errno (errnoOf handles
+    // those). Errnos always match /^E[A-Z0-9_]+$/, so filter them out.
+    if (typeof err.code === 'string' && !/^E[A-Z0-9_]+$/.test(err.code)) {
+      parts.push(err.code);
+    }
+    if (parts.length > 0) return parts.join(' | ');
+  }
+  return '';
+}
+
+/** Extract a low-level errno code (ECONNRESET, ETIMEDOUT, ...). */
+function errnoOf(err) {
+  if (err === null || err === undefined || typeof err !== 'object') return '';
+  if (typeof err.code === 'string' && /^E[A-Z0-9_]+$/.test(err.code)) return err.code;
+  // fetch native in newer Node wraps the cause
+  if (err.cause && typeof err.cause === 'object') {
+    const code = err.cause.code;
+    if (typeof code === 'string' && /^E[A-Z0-9_]+$/.test(code)) return code;
+  }
+  return '';
+}
+
+/**
+ * Classify a raw error into a {@link FailoverReason}.
+ *
+ * @param {unknown} err
+ * @returns {{reason: string, retryable: boolean, suggestedAction: string, raw: unknown}}
+ */
+function classify(err) {
+  const status = statusOf(err);
+  const message = messageOf(err).toLowerCase();
+  const errno = errnoOf(err);
+
+  // 1. Rate limit.
+  if (status === 429 || /rate.?limit/.test(message) || /too many requests/.test(message)) {
+    return build(FailoverReason.RATE_LIMITED, err);
+  }
+
+  // 2. Context overflow. Anthropic returns 400 with type=invalid_request and
+  //    message containing "prompt is too long"; OpenAI returns 400 with
+  //    code=context_length_exceeded; some edge surfaces use 413.
+  if (
+    status === 413 ||
+    /context_length_exceeded/.test(message) ||
+    /context.{0,10}(length|window|overflow|too.?long)/.test(message) ||
+    /prompt is too long/.test(message) ||
+    /maximum context length/.test(message)
+  ) {
+    return build(FailoverReason.CONTEXT_OVERFLOW, err);
+  }
+
+  // 3. Auth.
+  if (status === 401 || status === 403) {
+    return build(FailoverReason.AUTH_ERROR, err);
+  }
+  if (
+    /not authenticated/.test(message) ||
+    /invalid[_ ]api[_ ]key/.test(message) ||
+    /unauthorized/.test(message) ||
+    /authentication/.test(message)
+  ) {
+    return build(FailoverReason.AUTH_ERROR, err);
+  }
+
+  // 4. Tool not found.
+  if (/tool not found/.test(message) || /unknown tool/.test(message) || /no such tool/.test(message)) {
+    return build(FailoverReason.TOOL_NOT_FOUND, err);
+  }
+
+  // 5. Network transient: 5xx or low-level errno.
+  if (typeof status === 'number' && status >= 500 && status < 600) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+  if (
+    errno === 'ECONNRESET' ||
+    errno === 'ETIMEDOUT' ||
+    errno === 'EAI_AGAIN' ||
+    errno === 'ECONNREFUSED' ||
+    errno === 'ENETUNREACH' ||
+    errno === 'EPIPE'
+  ) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+  if (/\bsocket\b/.test(message) || /network/.test(message) || /\btimeout\b/.test(message)) {
+    return build(FailoverReason.NETWORK_TRANSIENT, err);
+  }
+
+  // 6. Other 4xx → validation.
+  if (typeof status === 'number' && status >= 400 && status < 500) {
+    return build(FailoverReason.VALIDATION, err);
+  }
+
+  // 7. Other >= 400 (e.g. 6xx exotic gateway codes).
+  if (typeof status === 'number' && status >= 400) {
+    return build(FailoverReason.NETWORK_PERMANENT, err);
+  }
+
+  // 8. Fallthrough.
+  return build(FailoverReason.UNKNOWN, err);
+}
+
+function build(reason, raw) {
+  return {
+    reason,
+    retryable: RETRYABLE[reason] === true,
+    suggestedAction: SUGGESTED_ACTIONS[reason],
+    raw,
+  };
+}
+
+module.exports = {
+  FailoverReason,
+  classify,
+  SUGGESTED_ACTIONS,
+  RETRYABLE,
+};