gsd-pi 2.71.0-dev.977c553 → 2.71.0-dev.e17e0ce

package/src/resources/extensions/gsd/session-model-override.ts

@@ -0,0 +1,36 @@
+export interface SessionModelOverride {
+  provider: string;
+  id: string;
+}
+
+const sessionOverrides = new Map<string, SessionModelOverride>();
+
+function normalizeSessionId(sessionId: string): string {
+  return typeof sessionId === "string" ? sessionId.trim() : "";
+}
+
+export function setSessionModelOverride(
+  sessionId: string,
+  override: SessionModelOverride,
+): void {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return;
+  sessionOverrides.set(key, {
+    provider: override.provider,
+    id: override.id,
+  });
+}
+
+export function getSessionModelOverride(
+  sessionId: string,
+): SessionModelOverride | undefined {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return undefined;
+  return sessionOverrides.get(key);
+}
+
+export function clearSessionModelOverride(sessionId: string): void {
+  const key = normalizeSessionId(sessionId);
+  if (!key) return;
+  sessionOverrides.delete(key);
+}

package/src/resources/extensions/gsd/shortcut-defs.ts

@@ -0,0 +1,49 @@
+// Canonical GSD shortcut definitions used by registration, help text, and overlays.
+
+import { formatShortcut } from "./files.js";
+
+export type GSDShortcutId = "dashboard" | "notifications" | "parallel";
+
+type GSDShortcutDef = {
+  key: "g" | "n" | "p";
+  action: string;
+  command: string;
+};
+
+export const GSD_SHORTCUTS: Record<GSDShortcutId, GSDShortcutDef> = {
+  dashboard: {
+    key: "g",
+    action: "Open GSD dashboard",
+    command: "/gsd status",
+  },
+  notifications: {
+    key: "n",
+    action: "Open notification history",
+    command: "/gsd notifications",
+  },
+  parallel: {
+    key: "p",
+    action: "Open parallel worker monitor",
+    command: "/gsd parallel watch",
+  },
+};
+
+function combo(prefix: "Ctrl+Alt+" | "Ctrl+Shift+", key: string): string {
+  return `${prefix}${key.toUpperCase()}`;
+}
+
+export function primaryShortcutCombo(id: GSDShortcutId): string {
+  return combo("Ctrl+Alt+", GSD_SHORTCUTS[id].key);
+}
+
+export function fallbackShortcutCombo(id: GSDShortcutId): string {
+  return combo("Ctrl+Shift+", GSD_SHORTCUTS[id].key);
+}
+
+export function shortcutPair(id: GSDShortcutId, formatter: (combo: string) => string = (combo) => combo): string {
+  return `${formatter(primaryShortcutCombo(id))} / ${formatter(fallbackShortcutCombo(id))}`;
+}
+
+export function formattedShortcutPair(id: GSDShortcutId): string {
+  return shortcutPair(id, formatShortcut);
+}

package/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts

@@ -7,9 +7,8 @@ const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
 const source = readFileSync(sourcePath, "utf-8");
 
 test("bootstrapAutoSession snapshots ctx.model before guided-flow entry (#2829)", () => {
-  // #3517 changed the snapshot to prefer GSD preferences, but the ordering
-  // guarantee still holds: the snapshot must be built before guided-flow.
-  const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel");
+  // The snapshot ordering guarantee still holds: build snapshot before guided-flow.
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
   assert.ok(snapshotIdx > -1, "auto-start.ts should snapshot model at bootstrap start");
 
   const firstDiscussIdx = source.indexOf('await showSmartEntry(ctx, pi, base, { step: requestedStepMode });');
@@ -29,8 +28,11 @@ test("bootstrapAutoSession restores autoModeStartModel from the early snapshot (
   assert.ok(snapshotRefIdx > -1, "autoModeStartModel should be restored from startModelSnapshot");
 });
 
-test("bootstrapAutoSession prefers GSD PREFERENCES.md over settings.json for start model (#3517)", () => {
-  // resolveDefaultSessionModel() should be called before the snapshot is built
+test("bootstrapAutoSession checks manual session override before preferences", () => {
+  const manualIdx = source.indexOf("const manualSessionOverride = getSessionModelOverride(");
+  assert.ok(manualIdx > -1, "auto-start.ts should read session model override first");
+
+  // resolveDefaultSessionModel() should still be called for fallback behavior
   const preferredIdx = source.indexOf("const preferredModel = resolveDefaultSessionModel(");
   assert.ok(preferredIdx > -1, "auto-start.ts should call resolveDefaultSessionModel()");
 
@@ -38,11 +40,11 @@ test("bootstrapAutoSession prefers GSD PREFERENCES.md over settings.json for sta
   const withProviderIdx = source.indexOf("resolveDefaultSessionModel(ctx.model?.provider)");
   assert.ok(withProviderIdx > -1, "auto-start.ts should pass ctx.model?.provider for bare ID resolution");
 
-  const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel");
-  assert.ok(snapshotIdx > -1, "startModelSnapshot should use preferredModel when available");
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
+  assert.ok(snapshotIdx > -1, "startModelSnapshot should prefer manual session override");
 
   assert.ok(
-    preferredIdx < snapshotIdx,
-    "resolveDefaultSessionModel() must be called before building startModelSnapshot",
+    manualIdx < snapshotIdx && preferredIdx < snapshotIdx,
+    "manual override and preference fallback must be resolved before building startModelSnapshot",
   );
 });

package/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, report } = createTestContext();
+
+const srcPath = join(import.meta.dirname, "..", "auto-start.ts");
+const src = readFileSync(srcPath, "utf-8");
+
+console.log("\n=== #3822: worktree bootstrap uses project DB path ===");
+
+const dbLifecycleIdx = src.indexOf("// ── DB lifecycle ──");
+assertTrue(dbLifecycleIdx > 0, "auto-start.ts has a DB lifecycle section");
+
+const dbLifecycleRegion = dbLifecycleIdx > 0 ? src.slice(dbLifecycleIdx, dbLifecycleIdx + 600) : "";
+
+assertTrue(
+  dbLifecycleRegion.includes("const gsdDbPath = resolveProjectRootDbPath(s.basePath);"),
+  "DB lifecycle resolves the project-root DB path after worktree entry (#3822)",
+);
+
+assertTrue(
+  !dbLifecycleRegion.includes('join(s.basePath, ".gsd", "gsd.db")'),
+  "DB lifecycle no longer derives gsd.db directly from the worktree path (#3822)",
+);
+
+report();

package/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts

@@ -0,0 +1,39 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const systemContextSrc = readFileSync(
+  join(import.meta.dirname, "..", "bootstrap", "system-context.ts"),
+  "utf-8",
+);
+const registerHooksSrc = readFileSync(
+  join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts"),
+  "utf-8",
+);
+
+describe("bootstrap deriveState DB guards (#3844)", () => {
+  test("system-context opens DB before deriveState in resume flows", () => {
+    const helperIdx = systemContextSrc.indexOf("const ensureStateDbOpen = async () => {");
+    const firstDeriveIdx = systemContextSrc.indexOf("const state = await deriveState(basePath);");
+    assert.ok(helperIdx > -1, "system-context should define a DB-open helper for deriveState callers");
+    assert.ok(firstDeriveIdx > -1, "system-context should still derive state for resume flows");
+    assert.ok(helperIdx < firstDeriveIdx, "system-context should prepare DB opening before deriveState resume calls");
+    assert.match(
+      systemContextSrc,
+      /await ensureStateDbOpen\(\);\s*\n\s*const state = await deriveState\(basePath\);/g,
+      "system-context resume flows should open DB before deriveState",
+    );
+  });
+
+  test("register-hooks opens DB before deriveState in session_before_compact", () => {
+    const compactIdx = registerHooksSrc.indexOf('pi.on("session_before_compact"');
+    assert.ok(compactIdx > -1, "register-hooks should define session_before_compact");
+    const compactSection = registerHooksSrc.slice(compactIdx, compactIdx + 1600);
+    const ensureIdx = compactSection.indexOf("ensureDbOpen()");
+    const deriveIdx = compactSection.indexOf("deriveState(basePath)");
+    assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen()");
+    assert.ok(deriveIdx > -1, "session_before_compact should derive state");
+    assert.ok(ensureIdx < deriveIdx, "session_before_compact should open DB before deriveState");
+  });
+});

package/src/resources/extensions/gsd/tests/complete-slice-prompt-task-summary-layout.test.ts

@@ -0,0 +1,18 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const promptPath = join(process.cwd(), "src/resources/extensions/gsd/prompts/complete-slice.md");
+const prompt = readFileSync(promptPath, "utf-8");
+
+test("complete-slice prompt explains the flat task summary layout", () => {
+  assert.match(prompt, /flat file layout/i);
+  assert.match(prompt, /T01-SUMMARY\.md/);
+  assert.match(prompt, /not inside per-task subdirectories like `tasks\/T01\/SUMMARY\.md`/i);
+});
+
+test("complete-slice prompt forbids the wrong task summary glob", () => {
+  assert.match(prompt, /find .*tasks -name "\*-SUMMARY\.md"/i);
+  assert.match(prompt, /Never use `tasks\/\*\/SUMMARY\.md`/);
+});

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

@@ -145,6 +145,33 @@ test("dispatch guard falls back to positional ordering when no dependencies decl
   );
 });
 
+test("dispatch guard ignores positionally-earlier reverse dependents for zero-dependency slices (#3720)", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M015"), { recursive: true });
+
+  insertMilestone({ id: "M015", title: "Reverse dependency fallback" });
+  insertSlice({ id: "S03", milestoneId: "M015", title: "Complete prerequisite", status: "complete", depends: [], sequence: 0 });
+  insertSlice({ id: "S04", milestoneId: "M015", title: "Depends on S04A", status: "pending", depends: ["S03", "S04A"], sequence: 0 });
+  insertSlice({ id: "S04A", milestoneId: "M015", title: "No explicit deps", status: "pending", depends: [], sequence: 0 });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M015", "M015-ROADMAP.md"), "# M015\n");
+
+  // S04A has no declared dependencies and should not be blocked by S04, because
+  // S04 itself depends on S04A. With sequence=0, DB ordering falls back to id.
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "execute-task", "M015/S04A/T02"),
+    null,
+  );
+
+  // The reverse direction is still blocked normally.
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "execute-task", "M015/S04/T01"),
+    "Cannot dispatch execute-task M015/S04/T01: dependency slice M015/S04A is not complete.",
+  );
+});
+
 test("dispatch guard allows slice with all declared dependencies complete", (t) => {
   const repo = setupRepo();
   t.after(() => teardownRepo(repo));

package/src/resources/extensions/gsd/tests/execute-task-prompt-existing-artifact-guard.test.ts

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const promptsDir = join(__dirname, "..", "prompts");
+
+test("execute-task prompt requires reading existing artifacts before write", () => {
+  const prompt = readFileSync(join(promptsDir, "execute-task.md"), "utf-8");
+
+  assert.match(
+    prompt,
+    /Before any `Write` that creates an artifact or output file, check whether that path already exists\./,
+    "execute-task prompt should require an existence check before creating artifacts",
+  );
+  assert.match(
+    prompt,
+    /If it does, read it first and decide whether the work is already done, should be extended, or truly needs replacement\./,
+    "execute-task prompt should require reading existing artifacts before replacement",
+  );
+});
+
+test("guided resume prompt checks for pre-existing artifacts", () => {
+  const prompt = readFileSync(join(promptsDir, "guided-resume-task.md"), "utf-8");
+
+  assert.match(
+    prompt,
+    /Before you create any expected artifact or output file, check whether it already exists and read it first/i,
+    "guided resume prompt should guard pre-existing artifacts",
+  );
+});

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,17 @@ 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");
+  }
+});

package/src/resources/extensions/gsd/tests/gsd-no-project-error.test.ts

@@ -0,0 +1,73 @@
+/**
+ * GSDNoProjectError — tests for friendly home-directory error handling.
+ *
+ * Verifies that GSDNoProjectError is thrown for blocked directories and
+ * that the dispatcher catches it with a user-friendly message.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const contextSrc = readFileSync(join(__dirname, "..", "commands", "context.ts"), "utf-8");
+const dispatcherSrc = readFileSync(join(__dirname, "..", "commands", "dispatcher.ts"), "utf-8");
+
+// ─── GSDNoProjectError class ──────────────────────────────────────────────
+
+test("GSDNoProjectError class is exported from context.ts", () => {
+  assert.ok(
+    contextSrc.includes("export class GSDNoProjectError extends Error"),
+    "GSDNoProjectError should be an exported Error subclass",
+  );
+});
+
+test("GSDNoProjectError sets name property", () => {
+  assert.ok(
+    contextSrc.includes('this.name = "GSDNoProjectError"'),
+    "GSDNoProjectError should set its name for instanceof checks",
+  );
+});
+
+// ─── projectRoot blocked directory handling ───────────────────────────────
+
+test("projectRoot uses validateDirectory and checks for blocked severity", () => {
+  assert.ok(
+    contextSrc.includes("validateDirectory(pathToCheck)"),
+    "projectRoot should call validateDirectory",
+  );
+  assert.ok(
+    contextSrc.includes('result.severity === "blocked"'),
+    "projectRoot should check for blocked severity",
+  );
+});
+
+test("projectRoot throws GSDNoProjectError on blocked directory", () => {
+  assert.ok(
+    contextSrc.includes("throw new GSDNoProjectError"),
+    "projectRoot should throw GSDNoProjectError when directory is blocked",
+  );
+});
+
+// ─── Dispatcher catch ─────────────────────────────────────────────────────
+
+test("dispatcher catches GSDNoProjectError with user-friendly message", () => {
+  assert.ok(
+    dispatcherSrc.includes("err instanceof GSDNoProjectError"),
+    "dispatcher should catch GSDNoProjectError specifically",
+  );
+  assert.ok(
+    dispatcherSrc.includes("cd"),
+    "error message should suggest cd-ing into a project directory",
+  );
+});
+
+test("dispatcher re-throws non-GSDNoProjectError exceptions", () => {
+  assert.ok(
+    dispatcherSrc.includes("throw err"),
+    "dispatcher should re-throw unexpected errors",
+  );
+});

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);
+  });
+});