@intentius/chant 0.13.1 → 0.15.1

package/src/cli/main.test.ts

@@ -188,6 +188,51 @@ describe("parseArgs", () => {
     expect(result.extraPositional).toBe(".");
     expect(result.extraPositional2).toBe(undefined);
   });
+
+  // ── components release/status flags (#568) ──────────────────────────────
+
+  test("parses --component, --digest, --git-sha, --run-id, --actor for components release", () => {
+    const result = parseArgs([
+      "components", "release", "prod",
+      "--component", "search-service",
+      "--digest", "sha256:abc123",
+      "--git-sha", "deadbeef",
+      "--run-id", "run-1",
+      "--actor", "alice",
+    ]);
+    expect(result.command).toBe("components");
+    expect(result.path).toBe("release");
+    expect(result.extraPositional).toBe("prod");
+    expect(result.component).toBe("search-service");
+    expect(result.digest).toBe("sha256:abc123");
+    expect(result.gitSha).toBe("deadbeef");
+    expect(result.runId).toBe("run-1");
+    expect(result.actor).toBe("alice");
+  });
+
+  test("parses --compare-to and --live for components status", () => {
+    const result = parseArgs(["components", "status", "prod", "--compare-to", "staging", "--live", "--json"]);
+    expect(result.command).toBe("components");
+    expect(result.path).toBe("status");
+    expect(result.extraPositional).toBe("prod");
+    expect(result.compareTo).toBe("staging");
+    expect(result.live).toBe(true);
+    expect(result.json).toBe(true);
+  });
+
+  // ── --no-release-record (#597) ───────────────────────────────────────────
+
+  test("parses --no-release-record for run --components", () => {
+    const result = parseArgs(["run", "--components", "search-service", "--env", "staging", "--no-release-record"]);
+    expect(result.components).toBe(true);
+    expect(result.env).toBe("staging");
+    expect(result.noReleaseRecord).toBe(true);
+  });
+
+  test("--no-release-record is undefined (not false) when omitted", () => {
+    const result = parseArgs(["run", "--components", "search-service"]);
+    expect(result.noReleaseRecord).toBeUndefined();
+  });
 });
 
 // ── resolveCommand tests ──────────────────────────────────────────
@@ -205,6 +250,9 @@ describe("resolveCommand", () => {
     { name: "dev", handler: noop },
     { name: "lifecycle plan", handler: noop },
     { name: "lifecycle", handler: noop },
+    { name: "components status", handler: noop },
+    { name: "components release", handler: noop },
+    { name: "components", handler: noop },
   ];
 
   function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
@@ -286,6 +334,24 @@ describe("resolveCommand", () => {
     expect(result!.compound).toBe(false);
   });
 
+  test("resolves components status as compound command", () => {
+    const result = resolveCommand(makeArgs({ command: "components", path: "status" }), testRegistry);
+    expect(result!.def.name).toBe("components status");
+    expect(result!.compound).toBe(true);
+  });
+
+  test("resolves components release as compound command", () => {
+    const result = resolveCommand(makeArgs({ command: "components", path: "release" }), testRegistry);
+    expect(result!.def.name).toBe("components release");
+    expect(result!.compound).toBe(true);
+  });
+
+  test("falls back to unknown components subcommand handler", () => {
+    const result = resolveCommand(makeArgs({ command: "components", path: "bogus" }), testRegistry);
+    expect(result!.def.name).toBe("components");
+    expect(result!.compound).toBe(false);
+  });
+
   test("resolves run status as compound command", () => {
     const registry: CommandDef[] = [
       { name: "run list", handler: noop },

package/src/cli/main.ts

@@ -9,13 +9,14 @@ import { ENV_VAR, unknownEnvError } from "../env";
 import { initRuntime } from "../runtime-adapter";
 import { runBuild } from "./handlers/build";
 import { runLint } from "./handlers/lint";
-import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevUnknown } from "./handlers/dev";
+import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevSurfaceDiff, runDevPinnedUpgrade, runDevRollingUpgrade, runDevUnknown } from "./handlers/dev";
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runDescribe, runImport, runAudit, runUpdate, runDoctor } from "./handlers/misc";
 import { runVendor } from "./handlers/vendor";
 import { runMigrate } from "./handlers/migrate";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 
@@ -127,6 +128,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.theme = args[++i];
     } else if (arg === "--stacks") {
       result.stacks = true;
+    } else if (arg === "--components") {
+      result.components = true;
+    } else if (arg === "--generate") {
+      result.generate = args[++i];
+    } else if (arg === "--dump-outputs") {
+      result.dumpOutputs = args[++i];
+    } else if (arg === "--seed-outputs") {
+      (result.seedOutputs ??= []).push(args[++i]);
     } else if (arg === "--detail") {
       result.detail = Number(args[++i]);
     } else if (arg === "--lens") {
@@ -151,6 +160,30 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.temporal = true;
     } else if (arg === "--json") {
       result.json = true;
+    } else if (arg === "--update-snapshot") {
+      result.updateSnapshot = true;
+    } else if (arg === "--run-examples") {
+      result.runExamples = true;
+    } else if (arg === "--pinned-digest") {
+      result.pinnedDigest = args[++i];
+    } else if (arg === "--check") {
+      result.check = true;
+    } else if (arg === "--bump") {
+      result.bump = true;
+    } else if (arg === "--component") {
+      result.component = args[++i];
+    } else if (arg === "--digest") {
+      result.digest = args[++i];
+    } else if (arg === "--git-sha") {
+      result.gitSha = args[++i];
+    } else if (arg === "--run-id") {
+      result.runId = args[++i];
+    } else if (arg === "--actor") {
+      result.actor = args[++i];
+    } else if (arg === "--compare-to") {
+      result.compareTo = args[++i];
+    } else if (arg === "--no-release-record") {
+      result.noReleaseRecord = true;
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -183,6 +216,10 @@ Commands:
   init                  Initialize a new chant project
   init lexicon <name>   Scaffold a new lexicon plugin project
   build                 Build infrastructure from specification files
+                        (--components --generate gitlab: generate mode (#563) —
+                         synthesize a thin .gitlab-ci.yml that triggers each
+                         discovered component's own deploy in wave order,
+                         instead of a normal lexicon build)
   lint                  Check specifications for issues
   list                  List discovered entities
   describe              Show the effective config for one component
@@ -198,10 +235,21 @@ Commands:
 Ops:
   run <name>            Start an Op workflow (spawns worker + submits to Temporal)
   run list              List all Ops with current run status
+                        --components: list discovered Components instead (--temporal
+                        also annotates each with its latest run status; #599)
   run status <name>     Show current workflow run state
+                        --components: show a Component's durable run state instead (#599)
   run signal <name> <signal>  Send a named signal to unblock a gate
+                        --components: signal a Component's workflow instead (#589)
   run cancel <name>     Cancel the active workflow run (requires --force)
+                        --components: cancel a Component's workflow instead (#589)
   run log <name>        Show run history for an Op
+                        --components: show a Component's run history instead (#599)
+  run --components <name|all>  Run discovered Component(s) through the interpret
+                        driver on the local executor (--env <env>; #585).
+                        On success, auto-emits a release-ledger record per
+                        component that published a digest (default: on;
+                        --no-release-record to opt out; #597)
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
@@ -222,11 +270,33 @@ Lifecycle (alias: lc):
                             --json: emit the ChangeSet as JSON
   lifecycle log [env]       History of lifecycle snapshots
 
+Component release ledger + status:
+  components status [env]  What's built vs what's deployed where, joined by
+                            digest (--live: reconcile against live+ownership;
+                            --json: stable machine-readable contract;
+                            --compare-to <env>: cross-check the same
+                            component's recorded digest against another env)
+  components release <env> Append one immutable release record
+                            (--component <name> --digest <sha256:...>
+                             [--git-sha <sha>] [--run-id <id>] [--actor <name>])
+
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
   dev publish           Package lexicon for distribution
   dev onboard <name>    Patch CI, Dockerfiles, and workflows for a new lexicon
   dev check-lexicon <dir>  Check lexicon completeness (tier 1/2/3)
+  dev surface-diff <dir>   Regen lexicon, validate, diff API surface vs committed baseline
+                           (--force: bypass spec cache; --update-snapshot: write new baseline;
+                            --bump: with --update-snapshot, bump package version by drift severity;
+                            --check: fail if the committed baseline drifted (never writes);
+                            --run-examples: also run example build harness;
+                            --pinned-digest <file>: verify spec digest before regen)
+  dev pinned-upgrade <dir> Report if a pinned lexicon (k8s|gcp|docker|gitlab) has a newer
+                           upstream release; dry-run bump + regen + surface-diff, then revert
+                           (reports only; --force bypasses the spec cache, -f json for JSON)
+  dev rolling-upgrade <dir>  Report rolling-spec drift (aws, azure, github): regen from
+                           latest, diff surface vs committed baseline, print delta + PR
+                           label (dry run; --force bypasses the spec cache, --format json)
 
 Servers:
   serve lsp             Start the LSP server (stdio)
@@ -268,12 +338,25 @@ Options:
   --strict              Escalate needs-review/validation to errors (migrate)
   --validate            Run external validator (glci/glab) after migrate
   --use-composites      Rewrite to composite calls when patterns match (migrate)
+  --components          Target discovered Component declarations instead of
+                        lexicon resources (list, describe, graph, build, run)
+  --generate <lexicon>  Generate mode (build --components only): synthesize CI
+                        YAML for <lexicon> instead of running a normal build.
+                        Only "gitlab" is implemented for v1.
+  --no-release-record   Skip auto-emitting a release-ledger record after a
+                        successful \`run --components\` deploy (default: on;
+                        also settable via chant.config.ts's
+                        release.autoRecord: false; #597)
 
 Examples:
   chant build ./infra/
   chant build ./infra/ --output stack.json
   chant build ./infra/ --format yaml
   chant build ./infra/ --watch
+  chant build ./infra/ --components --generate gitlab
+  chant build ./infra/ --components --generate gitlab --output .gitlab-ci.yml
+  chant run --components search-service --env staging
+  chant run --components all --env production
   chant import template.json --output ./infra/
   chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
@@ -332,6 +415,9 @@ const registry: CommandDef[] = [
   { name: "dev publish", requiresPlugins: true, handler: runDevPublish },
   { name: "dev onboard", handler: runDevOnboard },
   { name: "dev check-lexicon", handler: runDevCheckLexicon },
+  { name: "dev surface-diff", handler: runDevSurfaceDiff },
+  { name: "dev pinned-upgrade", handler: runDevPinnedUpgrade },
+  { name: "dev rolling-upgrade", handler: runDevRollingUpgrade },
 
   // Op / run subcommands
   { name: "run list", handler: runOpList },
@@ -352,6 +438,10 @@ const registry: CommandDef[] = [
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
   { name: "lifecycle log", handler: runLifecycleLog },
 
+  // Component release ledger + status surface (#568, epic #551)
+  { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
+  { name: "components release", handler: runComponentsReleaseRecord },
+
   // Serve subcommands
   { name: "serve lsp", requiresPlugins: true, handler: runServeLsp },
   { name: "serve mcp", requiresPlugins: true, handler: runServeMcp },
@@ -360,6 +450,7 @@ const registry: CommandDef[] = [
   { name: "lifecycle", handler: runLifecycleUnknown },
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
+  { name: "components", handler: runComponentsUnknown },
 ];
 
 /**
@@ -414,8 +505,20 @@ async function main(): Promise<void> {
   // which then fell through to import-detection on an empty file set and failed
   // with "No lexicon detected" even though chant.config.ts lists the lexicons.
   const projectPath = match.compound ? "." : args.path;
+  // `chant build --components --generate <lexicon>` (#563, generate mode)
+  // discovers `Component` declarations, not lexicon resources — a project
+  // made entirely of components has no reason to declare a chant lexicon
+  // plugin at all. Load plugins best-effort here instead of exiting, so
+  // generate mode works whether or not `chant.config.ts` names a lexicon.
+  // `components status` (#568) is the same shape: a components-only project
+  // may have no lexicon plugin, and `--live` reconciliation is opt-in, so
+  // missing plugins there is "no live evidence" (a warning), not a hard exit.
+  const isGenerateComponents = match.def.name === "build" && args.components && !!args.generate;
+  const isComponentsStatus = match.def.name === "components status";
   const plugins = match.def.requiresPlugins
-    ? await loadPluginsOrExit(projectPath)
+    ? isGenerateComponents || isComponentsStatus
+      ? await loadPlugins(await resolveProjectLexicons(resolve(projectPath)).catch(() => [])).catch(() => [])
+      : await loadPluginsOrExit(projectPath)
     : [];
   const serializers = plugins.map((p) => p.serializer);
   const ctx = { args, plugins, serializers };

package/src/cli/registry.ts

@@ -58,6 +58,13 @@ export interface ParsedArgs {
   env?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
+  /** `chant list --components` / `chant graph --components` — surface discovered
+   * `Component` declarations (#560) instead of/alongside lexicon resources. */
+  components?: boolean;
+  /** `chant build --components --generate <lexicon>` — generate mode (#563):
+   * synthesize CI YAML from discovered components instead of running a normal
+   * lexicon build. Only "gitlab" is implemented for v1. */
+  generate?: string;
   /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
   detail?: number;
   /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
@@ -83,6 +90,34 @@ export interface ParsedArgs {
   failOn?: string;
   /** `chant audit --theme <file>` — JSON theme knobs for the HTML report */
   theme?: string;
+  /** `chant dev surface-diff --update-snapshot` — write the fresh snapshot as the new baseline */
+  updateSnapshot?: boolean;
+  /** `chant dev surface-diff --run-examples` — also run the example build harness */
+  runExamples?: boolean;
+  /** `chant dev surface-diff --pinned-digest <file>` — path to SHA-256 digest file for supply-chain verification */
+  pinnedDigest?: string;
+  /** `chant dev surface-diff --check` — verify the committed baseline matches a fresh regen; exit non-zero if it drifted. Never writes the snapshot. */
+  check?: boolean;
+  /** `chant dev surface-diff --update-snapshot --bump` — bump the lexicon's package.json version by the drift severity so the accepted surface is publishable (#616). */
+  bump?: boolean;
+  /** `chant components release record --component <name>` (#568) — component name for the release record being appended. */
+  component?: string;
+  /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. */
+  digest?: string;
+  /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
+  gitSha?: string;
+  /** `chant components release record --run-id <id>` (#568) — orchestrator/CI run identifier. */
+  runId?: string;
+  /** `chant components release record --actor <name>` (#568) — who/what triggered the deploy. */
+  actor?: string;
+  /** `chant components status <env> --compare-to <env>` (#568) — a second environment to cross-check the same component's recorded digest against. */
+  compareTo?: string;
+  /** `chant run --components <name> --env <env> --no-release-record` (#597) — opt out of auto-emitting a release-ledger record after a successful component deploy. Default (flag omitted): recording is ON. Also settable project-wide via `chant.config.ts`'s `release.autoRecord: false`. */
+  noReleaseRecord?: boolean;
+  /** `chant run --components <name> --dump-outputs <file>` — after the run, write the accumulated cross-component/cross-stack outputs (JSON, keyed by component name) to `<file>`, for a downstream job to `--seed-outputs`. */
+  dumpOutputs?: string;
+  /** `chant run --components <name> --seed-outputs <file>` (repeatable) — before the run, load each JSON outputs file (as written by `--dump-outputs`) and seed cross-component/cross-stack resolution with it, so a `stackOutput()`/`@<dep>.publish.*` reference to a component that ran in an earlier job resolves. */
+  seedOutputs?: string[];
 }
 
 /**

package/src/codegen/fetch.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, afterEach } from "vitest";
-import { extractFromTar, fetchWithRetry } from "./fetch";
+import { extractFromTar, fetchWithRetry, TransientFetchError } from "./fetch";
 
 /**
  * Build a minimal valid tar buffer with a single file entry.
@@ -168,11 +168,16 @@ describe("fetchWithRetry", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
-  test("throws after exhausting retries on a transient status", async () => {
+  test("throws TransientFetchError after exhausting retries on a transient status", async () => {
     const fetchMock = vi.fn().mockResolvedValue(status(504));
     vi.stubGlobal("fetch", fetchMock);
 
-    await expect(fetchWithRetry("https://example.test/x", 2, 1)).rejects.toThrow("returned 504");
+    const err = await fetchWithRetry("https://example.test/x", 2, 1).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TransientFetchError);
+    expect((err as TransientFetchError).url).toBe("https://example.test/x");
+    expect((err as TransientFetchError).lastStatus).toBe(504);
+    expect((err as TransientFetchError).message).toContain("Transient fetch failure");
+    expect((err as TransientFetchError).message).toContain("HTTP 504");
     // initial attempt + 2 retries
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
@@ -217,4 +222,80 @@ describe("fetchWithRetry", () => {
     await expect(fetchWithRetry("https://example.test/x", 4, 1, init)).rejects.toThrow("returned 403");
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
+
+  test("429 then 200 succeeds after retry", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(status(429))
+      .mockResolvedValueOnce(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const resp = await fetchWithRetry("https://example.test/x", 4, 1);
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("honors Retry-After header (seconds) on 429", async () => {
+    const sleepCalls: number[] = [];
+    // Intercept sleep without really waiting
+    vi.useFakeTimers();
+
+    const r429 = new Response("", {
+      status: 429,
+      headers: { "Retry-After": "2" },
+    });
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(r429)
+      .mockResolvedValueOnce(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    // Run with fake timers — advance all pending timers automatically
+    const resultPromise = fetchWithRetry("https://example.test/x", 4, 1);
+    await vi.runAllTimersAsync();
+    const resp = await resultPromise;
+
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    vi.useRealTimers();
+    void sleepCalls;
+  });
+
+  test("throws TransientFetchError with clear message on persistent 429", async () => {
+    const r429 = new Response("", { status: 429 });
+    const fetchMock = vi.fn().mockResolvedValue(r429);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const err = await fetchWithRetry("https://example.test/rate-limited", 2, 1).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TransientFetchError);
+    const tfe = err as TransientFetchError;
+    expect(tfe.url).toBe("https://example.test/rate-limited");
+    expect(tfe.lastStatus).toBe(429);
+    expect(tfe.message).toContain("Transient fetch failure");
+    expect(tfe.message).toContain("HTTP 429");
+    expect(tfe.message).toContain("rate-limit or upstream outage");
+    expect(tfe.name).toBe("TransientFetchError");
+  });
+
+  test("throws TransientFetchError with clear message on persistent 5xx", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(status(503));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const err = await fetchWithRetry("https://example.test/unavailable", 1, 1).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TransientFetchError);
+    const tfe = err as TransientFetchError;
+    expect(tfe.lastStatus).toBe(503);
+    expect(tfe.message).toContain("HTTP 503");
+  });
+
+  test("TransientFetchError message includes attempt count", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(status(500));
+    vi.stubGlobal("fetch", fetchMock);
+
+    // 0 retries → exactly 1 attempt
+    const err = await fetchWithRetry("https://example.test/x", 0, 1).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TransientFetchError);
+    expect((err as TransientFetchError).message).toContain("1 attempt");
+  });
 });

package/src/codegen/fetch.ts

@@ -30,11 +30,38 @@ const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
 
 const DEFAULT_RETRIES = 4;
 const DEFAULT_BACKOFF_MS = 1000;
+/** Hard cap on Retry-After delays so a rogue header cannot stall CI indefinitely. */
+const MAX_RETRY_AFTER_MS = 60_000;
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * Parse the `Retry-After` response header and return a delay in milliseconds.
+ *
+ * The header value may be an integer number of seconds or an HTTP-date.
+ * Returns `null` when the header is absent or unparseable.
+ * The returned value is capped at {@link MAX_RETRY_AFTER_MS}.
+ */
+function parseRetryAfter(response: Response): number | null {
+  const raw = response.headers.get("retry-after");
+  if (!raw) return null;
+
+  const seconds = Number(raw.trim());
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return Math.min(Math.ceil(seconds * 1000), MAX_RETRY_AFTER_MS);
+  }
+
+  // HTTP-date format: "Wed, 01 Jul 2026 12:00:00 GMT"
+  const date = new Date(raw);
+  if (!Number.isNaN(date.getTime())) {
+    return Math.min(Math.max(0, date.getTime() - Date.now()), MAX_RETRY_AFTER_MS);
+  }
+
+  return null;
+}
+
 /**
  * Fetch a URL, retrying on transient failures (network errors and
  * retryable HTTP statuses) with exponential backoff.
@@ -42,9 +69,16 @@ function sleep(ms: number): Promise<void> {
  * Permanent failures (e.g. 404, 403) are not retried — they throw on the
  * first response. The returned response is guaranteed `ok`.
  *
+ * When a `Retry-After` header is present on a 429 or 503 response the delay
+ * from that header is used instead of the exponential back-off for that
+ * specific retry, capped at {@link MAX_RETRY_AFTER_MS}.
+ *
  * `init` is passed through to `fetch` on every attempt, so callers that
  * need request headers (e.g. the GitHub API `Accept` header) or an abort
  * signal get retries without duplicating the loop.
+ *
+ * On exhaustion a descriptive {@link TransientFetchError} is thrown rather
+ * than the raw last error so the caller can surface a human-readable message.
  */
 export async function fetchWithRetry(
   url: string,
@@ -52,12 +86,17 @@ export async function fetchWithRetry(
   backoffMs = DEFAULT_BACKOFF_MS,
   init?: RequestInit,
 ): Promise<Response> {
+  let lastStatus: number | undefined;
   let lastError: Error | undefined;
+  // When a response carries a Retry-After header, the indicated delay replaces
+  // the exponential back-off for that specific next retry.
+  let retryAfterOverride: number | null = null;
 
   for (let attempt = 0; attempt <= retries; attempt++) {
     if (attempt > 0) {
-      const delay = backoffMs * 2 ** (attempt - 1);
+      const delay = retryAfterOverride ?? backoffMs * 2 ** (attempt - 1);
       debug(`retrying ${url} (attempt ${attempt}/${retries}) after ${delay}ms: ${lastError?.message}`);
+      retryAfterOverride = null;
       await sleep(delay);
     }
 
@@ -67,6 +106,7 @@ export async function fetchWithRetry(
     } catch (e) {
       // Network-level failure (DNS, connection reset, timeout). Transient.
       lastError = e instanceof Error ? e : new Error(String(e));
+      lastStatus = undefined;
       continue;
     }
 
@@ -74,10 +114,44 @@ export async function fetchWithRetry(
 
     const err = new Error(`Download from ${url} returned ${response.status}`);
     if (!RETRYABLE_STATUSES.has(response.status)) throw err;
+
     lastError = err;
+    lastStatus = response.status;
+
+    // Capture Retry-After so the next loop iteration uses it instead of backoff
+    const retryAfterMs = parseRetryAfter(response);
+    if (retryAfterMs !== null) {
+      debug(`Retry-After for ${url}: ${retryAfterMs}ms`);
+      retryAfterOverride = retryAfterMs;
+    }
   }
 
-  throw lastError ?? new Error(`Download from ${url} failed after ${retries} retries`);
+  throw new TransientFetchError(url, retries, lastStatus, lastError);
+}
+
+/**
+ * Thrown when {@link fetchWithRetry} exhausts all retry attempts on a
+ * transient failure (429 / 5xx / network error).
+ *
+ * The message is human-readable and actionable: it names the URL, the number
+ * of attempts made, and the last HTTP status (if any) so that an upstream Op
+ * can route it to a report/issue without exposing a raw stack trace.
+ */
+export class TransientFetchError extends Error {
+  constructor(
+    public readonly url: string,
+    public readonly retries: number,
+    public readonly lastStatus: number | undefined,
+    public readonly cause?: Error,
+  ) {
+    const attempts = retries + 1;
+    const statusPart = lastStatus !== undefined ? ` (HTTP ${lastStatus})` : "";
+    super(
+      `Transient fetch failure for ${url}${statusPart} — failed after ${attempts} attempt${attempts === 1 ? "" : "s"}. ` +
+        `This is typically a rate-limit or upstream outage. Retry later or check upstream status.`,
+    );
+    this.name = "TransientFetchError";
+  }
 }
 
 // ── Fetch with cache ───────────────────────────────────────────────