gsd-pi 2.71.0-dev.06b86c6 → 2.71.0-dev.246c32d

package/src/resources/extensions/gsd/tests/complete-slice-gate-closure.test.ts

@@ -0,0 +1,167 @@
+/**
+ * complete-slice gate closure integration test.
+ *
+ * Pins the fix for the Q8-stall bug: complete-slice must close every gate
+ * owned by the complete-slice turn based on the content of the matching
+ * CompleteSliceParams field. Without this, Q8 stays pending forever and
+ * blocks state derivation on subsequent loops.
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  insertGateRow,
+  getGateResults,
+} from "../gsd-db.ts";
+import { handleCompleteSlice } from "../tools/complete-slice.ts";
+import type { CompleteSliceParams } from "../types.ts";
+
+function makeValidSliceParams(overrides: Partial<CompleteSliceParams> = {}): CompleteSliceParams {
+  return {
+    sliceId: "S01",
+    milestoneId: "M001",
+    sliceTitle: "Test Slice",
+    oneLiner: "Implemented test slice",
+    narrative: "Built and tested.",
+    verification: "All tests pass.",
+    deviations: "None.",
+    knownLimitations: "None.",
+    followUps: "None.",
+    keyFiles: ["src/foo.ts"],
+    keyDecisions: [],
+    patternsEstablished: [],
+    observabilitySurfaces: [],
+    provides: [],
+    requirementsSurfaced: [],
+    drillDownPaths: [],
+    affects: [],
+    requirementsAdvanced: [],
+    requirementsValidated: [],
+    requirementsInvalidated: [],
+    filesModified: [],
+    requires: [],
+    uatContent: "## Smoke Test\n\nVerify happy path.",
+    ...overrides,
+  };
+}
+
+describe("complete-slice closes complete-slice-owned gates", () => {
+  let dbPath: string;
+  let basePath: string;
+
+  beforeEach(() => {
+    dbPath = path.join(
+      fs.mkdtempSync(path.join(os.tmpdir(), "gsd-slice-gate-")),
+      "test.db",
+    );
+    openDatabase(dbPath);
+
+    basePath = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-slice-gate-handler-"));
+    const sliceDir = path.join(
+      basePath, ".gsd", "milestones", "M001", "slices", "S01", "tasks",
+    );
+    fs.mkdirSync(sliceDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(basePath, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Test Milestone",
+        "",
+        "## Slices",
+        "",
+        '- [ ] **S01: Test Slice** `risk:medium` `depends:[]`',
+        "  - After this: basic functionality works",
+      ].join("\n"),
+    );
+
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+    insertTask({
+      id: "T01", sliceId: "S01", milestoneId: "M001",
+      status: "complete", title: "Task 1",
+    });
+
+    // Seed Q8 as pending — this is what plan-slice does today.
+    insertGateRow({
+      milestoneId: "M001", sliceId: "S01",
+      gateId: "Q8", scope: "slice",
+    });
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    fs.rmSync(path.dirname(dbPath), { recursive: true, force: true });
+    fs.rmSync(basePath, { recursive: true, force: true });
+  });
+
+  test("Q8 closes as 'pass' when operationalReadiness is populated", async () => {
+    const params = makeValidSliceParams({
+      operationalReadiness: [
+        "- Health signal: /health endpoint returns 200",
+        "- Failure signal: error rate alert in observability dashboard",
+        "- Recovery: systemd auto-restart",
+      ].join("\n"),
+    });
+
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8, "Q8 row must exist after complete-slice");
+    assert.equal(q8.status, "complete");
+    assert.equal(q8.verdict, "pass");
+    assert.ok(
+      q8.findings.includes("Health signal"),
+      "Q8 findings must capture the operationalReadiness content",
+    );
+  });
+
+  test("Q8 closes as 'omitted' when operationalReadiness is empty", async () => {
+    const params = makeValidSliceParams({ operationalReadiness: "" });
+
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8, "Q8 row must exist after complete-slice");
+    assert.equal(q8.status, "complete");
+    assert.equal(q8.verdict, "omitted");
+  });
+
+  test("Q8 also closes when operationalReadiness is omitted entirely", async () => {
+    // A model that doesn't pass operationalReadiness at all must still
+    // move Q8 out of 'pending' — leaving it pending produces the stall.
+    const params = makeValidSliceParams();
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result), `handler failed: ${(result as any).error}`);
+
+    const gates = getGateResults("M001", "S01", "slice");
+    const q8 = gates.find((g) => g.gate_id === "Q8");
+    assert.ok(q8);
+    assert.notEqual(q8.status, "pending", "Q8 must never remain pending after complete-slice");
+    assert.equal(q8.verdict, "omitted");
+  });
+
+  test("summary markdown contains Operational Readiness section", async () => {
+    const params = makeValidSliceParams({
+      operationalReadiness: "- Health signal: /health\n- Failure signal: alert",
+    });
+    const result = await handleCompleteSlice(params, basePath);
+    assert.ok(!("error" in result));
+    if (!("error" in result)) {
+      const summary = fs.readFileSync(result.summaryPath, "utf-8");
+      assert.match(summary, /^## Operational Readiness/m);
+      assert.match(summary, /Health signal: \/health/);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -574,6 +574,42 @@ test("runProviderChecks reports ok for OpenAI via openai-codex auth.json (#2922)
   rmSync(tmpHome, { recursive: true, force: true });
 });
 
+test("runProviderChecks reports ok for claude-code without any API key", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cc-repo-")));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(repo, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "models:",
+      "  execution:",
+      "    model: claude-sonnet-4-6",
+      "    provider: claude-code",
+      "---",
+      "",
+    ].join("\n"),
+  );
+
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cc-home-")));
+
+  withEnv({
+    HOME: tmpHome,
+    ANTHROPIC_API_KEY: undefined,
+    ANTHROPIC_OAUTH_TOKEN: undefined,
+  }, () => {
+    withCwd(repo, () => {
+      const results = runProviderChecks();
+      const cc = results.find(r => r.name === "claude-code");
+      assert.ok(cc, "claude-code result should exist");
+      assert.equal(cc!.status, "ok", "claude-code uses CLI auth — must be ok without API keys");
+      assert.ok(cc!.message.includes("CLI auth"), "should indicate CLI auth");
+    });
+  });
+
+  rmSync(repo, { recursive: true, force: true });
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
 test("PROVIDER_ROUTES includes google-gemini-cli as route for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");

package/src/resources/extensions/gsd/tests/forensics-stuck-loops.test.ts

@@ -101,3 +101,65 @@ test("#1943 detectStuckLoops ignores watchdog duplicates but flags real re-dispa
   assert.equal(anomalies.length, 1, `expected 1 anomaly (for the 3x dispatched task), got ${anomalies.length}`);
   assert.ok(anomalies[0].summary.includes("3 times"));
 });
+
+test("#3760 detectStuckLoops ignores cross-session recovery re-dispatches", () => {
+  const anomalies: ForensicAnomaly[] = [];
+
+  const units: UnitMetrics[] = [
+    makeUnit({
+      type: "plan-slice",
+      id: "M001/S02",
+      startedAt: 1000,
+      finishedAt: 2000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "plan-slice",
+      id: "M001/S02",
+      startedAt: 5000,
+      finishedAt: 6000,
+      autoSessionKey: "session-b",
+    }),
+  ];
+
+  detectStuckLoops(units, anomalies);
+
+  assert.equal(anomalies.length, 0, "cross-session recovery should not be flagged as a stuck loop");
+});
+
+test("#3760 detectStuckLoops still flags repeated dispatches within one auto session", () => {
+  const anomalies: ForensicAnomaly[] = [];
+
+  const units: UnitMetrics[] = [
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 1000,
+      finishedAt: 2000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 5000,
+      finishedAt: 6000,
+      autoSessionKey: "session-a",
+    }),
+    makeUnit({
+      type: "complete-slice",
+      id: "M011/S02",
+      startedAt: 9000,
+      finishedAt: 10000,
+      autoSessionKey: "session-b",
+    }),
+  ];
+
+  detectStuckLoops(units, anomalies);
+
+  assert.equal(anomalies.length, 1, "within-session retries should still be flagged");
+  assert.ok(anomalies[0].summary.includes("2 times"), `summary should reflect the worst same-session loop: ${anomalies[0].summary}`);
+  assert.ok(
+    anomalies[0].details.includes("Cross-session recovery runs are ignored"),
+    `details should explain the session-aware rule: ${anomalies[0].details}`,
+  );
+});

package/src/resources/extensions/gsd/tests/format-shortcut.test.ts

@@ -4,6 +4,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { formatShortcut } from '../files.ts';
+import { formattedShortcutPair, primaryShortcutCombo, fallbackShortcutCombo } from '../shortcut-defs.ts';
 
 // ─── formatShortcut renders per-platform shortcuts ──────────────────────
 
@@ -67,3 +68,33 @@ test('formatShortcut: passes through plain key names', () => {
   assert.strictEqual(formatShortcut('Escape'), 'Escape');
   assert.strictEqual(formatShortcut('Enter'), 'Enter');
 });
+
+test("shortcut-defs: exposes canonical dashboard combos", () => {
+  assert.equal(primaryShortcutCombo("dashboard"), "Ctrl+Alt+G");
+  assert.equal(fallbackShortcutCombo("dashboard"), "Ctrl+Shift+G");
+});
+
+test("shortcut-defs: formats shortcut pair using platform symbols", () => {
+  const pair = formattedShortcutPair("notifications");
+  if (process.platform === "darwin") {
+    assert.equal(pair, "⌃⌥N / ⌃⇧N");
+  } else {
+    assert.equal(pair, "Ctrl+Alt+N / Ctrl+Shift+N");
+  }
+});
+
+test("shortcut-defs: parallel shortcut omits fallback (hasFallback: false)", () => {
+  const pair = formattedShortcutPair("parallel");
+  if (process.platform === "darwin") {
+    assert.equal(pair, "⌃⌥P", "parallel should only show primary combo");
+  } else {
+    assert.equal(pair, "Ctrl+Alt+P", "parallel should only show primary combo");
+  }
+  // Verify it does NOT contain the fallback separator
+  assert.ok(!pair.includes("/"), "parallel pair should not contain fallback separator");
+});
+
+test("shortcut-defs: dashboard shortcut includes fallback (hasFallback: true)", () => {
+  const pair = formattedShortcutPair("dashboard");
+  assert.ok(pair.includes("/"), "dashboard pair should contain fallback separator");
+});

package/src/resources/extensions/gsd/tests/gate-dispatch.test.ts

@@ -186,4 +186,31 @@ describe("evaluating-gates phase", () => {
     insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q5", scope: "task", taskId: "T01" });
     assert.equal(getPendingSliceGateCount("M001", "S01"), 1);
   });
+
+  test("Q8 (owned by complete-slice) does not block evaluating-gates phase", async () => {
+    // Regression: Q8 is stored with scope:"slice" but owned by the
+    // complete-slice turn. Before the gate registry landed, deriveState
+    // counted Q8 as a blocker for evaluating-gates while the gate-evaluate
+    // prompt silently dropped Q8 — an unrecoverable stall. After the
+    // registry change, deriveState filters by owner turn, so Q8 never
+    // blocks evaluating-gates.
+    planSlice(tmpDir);
+    await renderPlanFromDb(tmpDir, "M001", "S01");
+
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q4", scope: "slice" });
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q8", scope: "slice" });
+
+    saveGateResult({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", verdict: "pass", rationale: "OK", findings: "" });
+    saveGateResult({ milestoneId: "M001", sliceId: "S01", gateId: "Q4", verdict: "omitted", rationale: "N/A", findings: "" });
+    // Q8 deliberately left pending — it's complete-slice's problem.
+
+    invalidateStateCache();
+    const state = await deriveState(tmpDir);
+    assert.equal(
+      state.phase,
+      "executing",
+      `pending Q8 must not stall evaluating-gates — got phase=${state.phase}`,
+    );
+  });
 });

package/src/resources/extensions/gsd/tests/gate-registry.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Gate registry tests — enforce that every declared GateId has a registry
+ * entry, that every owner-turn bucket is non-empty, and that coverage
+ * assertions fail loudly instead of silently skipping unknown gates.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  GATE_REGISTRY,
+  assertGateCoverage,
+  getGateDefinition,
+  getGateIdsForTurn,
+  getGatesForTurn,
+  getOwnerTurn,
+  type OwnerTurn,
+} from "../gate-registry.ts";
+import type { GateId } from "../types.ts";
+
+/** Authoritative list of GateIds as declared in types.ts. */
+const ALL_GATE_IDS: readonly GateId[] = [
+  "Q3", "Q4", "Q5", "Q6", "Q7", "Q8",
+  "MV01", "MV02", "MV03", "MV04",
+];
+
+const ALL_OWNER_TURNS: readonly OwnerTurn[] = [
+  "gate-evaluate",
+  "execute-task",
+  "complete-slice",
+  "validate-milestone",
+];
+
+describe("gate-registry", () => {
+  test("every declared GateId has a registry entry", () => {
+    for (const id of ALL_GATE_IDS) {
+      const def = GATE_REGISTRY[id];
+      assert.ok(def, `missing registry entry for gate ${id}`);
+      assert.equal(def.id, id);
+      assert.ok(def.question.length > 0, `${id} missing question`);
+      assert.ok(def.guidance.length > 0, `${id} missing guidance`);
+      assert.ok(def.promptSection.length > 0, `${id} missing promptSection`);
+    }
+  });
+
+  test("registry contains no extra gate entries", () => {
+    const registryIds = new Set(Object.keys(GATE_REGISTRY));
+    const declaredIds = new Set<string>(ALL_GATE_IDS);
+    for (const id of registryIds) {
+      assert.ok(declaredIds.has(id), `registry has unknown gate ${id}`);
+    }
+  });
+
+  test("every owner turn owns at least one gate", () => {
+    for (const turn of ALL_OWNER_TURNS) {
+      const gates = getGatesForTurn(turn);
+      assert.ok(
+        gates.length > 0,
+        `owner turn "${turn}" has no gates — likely a registry mistake`,
+      );
+    }
+  });
+
+  test("owner turn buckets are disjoint", () => {
+    const seen = new Set<string>();
+    for (const turn of ALL_OWNER_TURNS) {
+      for (const def of getGatesForTurn(turn)) {
+        assert.ok(!seen.has(def.id), `gate ${def.id} claimed by two turns`);
+        seen.add(def.id);
+      }
+    }
+    // Every gate should appear in exactly one bucket.
+    assert.equal(seen.size, ALL_GATE_IDS.length);
+  });
+
+  test("getOwnerTurn round-trips against GATE_REGISTRY", () => {
+    for (const id of ALL_GATE_IDS) {
+      const turn = getOwnerTurn(id);
+      const idsForTurn = getGateIdsForTurn(turn);
+      assert.ok(idsForTurn.has(id), `${id} not in ${turn} bucket`);
+    }
+  });
+
+  test("getGateDefinition returns undefined for unknown ids", () => {
+    assert.equal(getGateDefinition("Q99"), undefined);
+    assert.equal(getGateDefinition("not-a-gate"), undefined);
+  });
+});
+
+describe("assertGateCoverage", () => {
+  test("throws when a row is owned by a different turn", () => {
+    // Q8 is owned by complete-slice, not gate-evaluate — this used to be
+    // silently dropped by the old `if (!meta) continue;` filter, causing
+    // the evaluating-gates phase to stall.
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q8" }], "gate-evaluate"),
+      (err: Error) =>
+        err.message.includes("Q8") && err.message.includes("gate-evaluate"),
+    );
+  });
+
+  test("throws when a row has an unknown gate id", () => {
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q999" as GateId }], "gate-evaluate", { requireAll: false }),
+      (err: Error) => err.message.includes("Q999"),
+    );
+  });
+
+  test("throws when requireAll is true and an owned gate is missing", () => {
+    // gate-evaluate owns Q3 and Q4. Passing only Q3 should fail.
+    assert.throws(
+      () => assertGateCoverage([{ gate_id: "Q3" }], "gate-evaluate", { requireAll: true }),
+      (err: Error) => err.message.includes("Q4"),
+    );
+  });
+
+  test("passes when requireAll is false and only a subset is pending", () => {
+    // execute-task owns Q5/Q6/Q7, but a task with no external dependencies
+    // may only have Q7 seeded. That's still valid coverage.
+    assert.doesNotThrow(() =>
+      assertGateCoverage([{ gate_id: "Q7" }], "execute-task", { requireAll: false }),
+    );
+  });
+
+  test("passes when requireAll is true and every owned gate is pending", () => {
+    assert.doesNotThrow(() =>
+      assertGateCoverage(
+        [{ gate_id: "Q3" }, { gate_id: "Q4" }],
+        "gate-evaluate",
+        { requireAll: true },
+      ),
+    );
+  });
+
+  test("empty pending list passes when requireAll is false", () => {
+    assert.doesNotThrow(() =>
+      assertGateCoverage([], "complete-slice", { requireAll: false }),
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/infra-errors-cooldown.test.ts

@@ -0,0 +1,180 @@
+// gsd / infra-errors cooldown detection tests
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  isTransientCooldownError,
+  getCooldownRetryAfterMs,
+  MAX_COOLDOWN_RETRIES,
+  COOLDOWN_FALLBACK_WAIT_MS,
+} from "../auto/infra-errors.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+describe("infra-errors cooldown constants", () => {
+  test("COOLDOWN_FALLBACK_WAIT_MS is a positive number greater than the 30s rate-limit backoff", () => {
+    assert.ok(typeof COOLDOWN_FALLBACK_WAIT_MS === "number");
+    assert.ok(COOLDOWN_FALLBACK_WAIT_MS > 30_000, "should exceed the 30s rate-limit window");
+  });
+
+  test("MAX_COOLDOWN_RETRIES is a positive integer", () => {
+    assert.ok(typeof MAX_COOLDOWN_RETRIES === "number");
+    assert.ok(Number.isInteger(MAX_COOLDOWN_RETRIES));
+    assert.ok(MAX_COOLDOWN_RETRIES > 0);
+  });
+
+  test("COOLDOWN_FALLBACK_WAIT_MS is 35_000", () => {
+    assert.equal(COOLDOWN_FALLBACK_WAIT_MS, 35_000);
+  });
+
+  test("MAX_COOLDOWN_RETRIES is 5", () => {
+    assert.equal(MAX_COOLDOWN_RETRIES, 5);
+  });
+});
+
+// ─── isTransientCooldownError: structured detection ──────────────────────────
+
+describe("isTransientCooldownError — structured code detection", () => {
+  test("returns true for an object with code === AUTH_COOLDOWN", () => {
+    const err = { code: "AUTH_COOLDOWN", message: "credentials in cooldown" };
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true for a real CredentialCooldownError-shaped error", () => {
+    // Simulate CredentialCooldownError without importing sdk.ts (leaf-module rule)
+    const err = Object.assign(new Error('All credentials for "anthropic" are in a cooldown window.'), {
+      code: "AUTH_COOLDOWN",
+      retryAfterMs: 30_000,
+      name: "CredentialCooldownError",
+    });
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns false for an object with a different code", () => {
+    const err = { code: "ENOSPC", message: "disk full" };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+
+  test("returns false for an object with no code property", () => {
+    const err = { message: "some random error" };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── isTransientCooldownError: message fallback ───────────────────────────────
+
+describe("isTransientCooldownError — message fallback (cross-process)", () => {
+  test("returns true when message contains 'in a cooldown window'", () => {
+    const err = new Error('All credentials for "openai" are in a cooldown window. Please wait.');
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true when message matches case-insensitively", () => {
+    const err = new Error("credentials IN A COOLDOWN WINDOW");
+    assert.equal(isTransientCooldownError(err), true);
+  });
+
+  test("returns true for a plain string containing cooldown window phrase", () => {
+    assert.equal(isTransientCooldownError("all keys in a cooldown window"), true);
+  });
+
+  test("returns false for a generic error message", () => {
+    const err = new Error("rate limit exceeded");
+    assert.equal(isTransientCooldownError(err), false);
+  });
+
+  test("returns false for an error message about auth failure without cooldown phrase", () => {
+    const err = new Error("Authentication failed: invalid API key");
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── isTransientCooldownError: edge cases ────────────────────────────────────
+
+describe("isTransientCooldownError — edge cases", () => {
+  test("returns false for null", () => {
+    assert.equal(isTransientCooldownError(null), false);
+  });
+
+  test("returns false for undefined", () => {
+    assert.equal(isTransientCooldownError(undefined), false);
+  });
+
+  test("returns false for a number", () => {
+    assert.equal(isTransientCooldownError(42), false);
+  });
+
+  test("returns false for an empty object", () => {
+    assert.equal(isTransientCooldownError({}), false);
+  });
+
+  test("returns false for an object with code === AUTH_COOLDOWN as a non-string", () => {
+    // code must be a string matching "AUTH_COOLDOWN" exactly
+    const err = { code: 42 };
+    assert.equal(isTransientCooldownError(err), false);
+  });
+});
+
+// ─── getCooldownRetryAfterMs: structured extraction ──────────────────────────
+
+describe("getCooldownRetryAfterMs — structured extraction", () => {
+  test("returns retryAfterMs when code is AUTH_COOLDOWN and retryAfterMs is set", () => {
+    const err = { code: "AUTH_COOLDOWN", retryAfterMs: 30_000 };
+    assert.equal(getCooldownRetryAfterMs(err), 30_000);
+  });
+
+  test("returns undefined when code is AUTH_COOLDOWN but retryAfterMs is absent", () => {
+    const err = { code: "AUTH_COOLDOWN" };
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns 0 when retryAfterMs is explicitly 0", () => {
+    const err = { code: "AUTH_COOLDOWN", retryAfterMs: 0 };
+    assert.equal(getCooldownRetryAfterMs(err), 0);
+  });
+
+  test("returns undefined for an error with a different code even if retryAfterMs is set", () => {
+    const err = { code: "ENOSPC", retryAfterMs: 5_000 };
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns undefined for a plain Error with no code property", () => {
+    const err = new Error("something went wrong");
+    assert.equal(getCooldownRetryAfterMs(err), undefined);
+  });
+
+  test("returns retryAfterMs from a full CredentialCooldownError-shaped object", () => {
+    const err = Object.assign(new Error('All credentials for "anthropic" are in a cooldown window.'), {
+      code: "AUTH_COOLDOWN",
+      retryAfterMs: 15_000,
+      name: "CredentialCooldownError",
+    });
+    assert.equal(getCooldownRetryAfterMs(err), 15_000);
+  });
+});
+
+// ─── getCooldownRetryAfterMs: edge cases ─────────────────────────────────────
+
+describe("getCooldownRetryAfterMs — edge cases", () => {
+  test("returns undefined for null", () => {
+    assert.equal(getCooldownRetryAfterMs(null), undefined);
+  });
+
+  test("returns undefined for undefined", () => {
+    assert.equal(getCooldownRetryAfterMs(undefined), undefined);
+  });
+
+  test("returns undefined for a plain string", () => {
+    assert.equal(getCooldownRetryAfterMs("AUTH_COOLDOWN"), undefined);
+  });
+
+  test("returns undefined for an empty object", () => {
+    assert.equal(getCooldownRetryAfterMs({}), undefined);
+  });
+
+  test("returns undefined for a number", () => {
+    assert.equal(getCooldownRetryAfterMs(42), undefined);
+  });
+});