gsd-pi 2.17.0 → 2.19.0

package/src/resources/extensions/gsd/tests/knowledge.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Unit tests for KNOWLEDGE.md integration.
+ *
+ * Tests:
+ * - KNOWLEDGE is registered in GSD_ROOT_FILES
+ * - resolveGsdRootFile resolves KNOWLEDGE paths correctly
+ * - inlineGsdRootFile works with the KNOWLEDGE key
+ * - before_agent_start hook includes/omits knowledge block appropriately
+ */
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { GSD_ROOT_FILES, resolveGsdRootFile } from '../paths.ts';
+import { inlineGsdRootFile } from '../auto-prompts.ts';
+import { appendKnowledge } from '../files.ts';
+
+// ─── KNOWLEDGE is registered in GSD_ROOT_FILES ─────────────────────────────
+
+test('knowledge: KNOWLEDGE key exists in GSD_ROOT_FILES', () => {
+  assert.ok('KNOWLEDGE' in GSD_ROOT_FILES, 'GSD_ROOT_FILES should have KNOWLEDGE key');
+  assert.strictEqual(GSD_ROOT_FILES.KNOWLEDGE, 'KNOWLEDGE.md');
+});
+
+// ─── resolveGsdRootFile resolves KNOWLEDGE.md ───────────────────────────────
+
+test('knowledge: resolveGsdRootFile returns canonical path when KNOWLEDGE.md exists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'KNOWLEDGE.md'), '# Project Knowledge\n');
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  assert.strictEqual(resolved, join(gsdDir, 'KNOWLEDGE.md'));
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: resolveGsdRootFile resolves when legacy knowledge.md exists', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'knowledge.md'), '# Project Knowledge\n');
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  // On case-insensitive filesystems (macOS), canonical path matches;
+  // on case-sensitive (Linux), legacy path matches. Either is valid.
+  const canonical = join(gsdDir, 'KNOWLEDGE.md');
+  const legacy = join(gsdDir, 'knowledge.md');
+  assert.ok(
+    resolved === canonical || resolved === legacy,
+    `resolved path should be canonical or legacy, got: ${resolved}`,
+  );
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: resolveGsdRootFile returns canonical path when file does not exist', () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const resolved = resolveGsdRootFile(tmp, 'KNOWLEDGE');
+  assert.strictEqual(resolved, join(gsdDir, 'KNOWLEDGE.md'));
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── inlineGsdRootFile works with knowledge.md ─────────────────────────────
+
+test('knowledge: inlineGsdRootFile returns content when KNOWLEDGE.md exists', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+  writeFileSync(join(gsdDir, 'KNOWLEDGE.md'), '# Project Knowledge\n\n## Rules\n\nK001: Use real DB');
+
+  const result = await inlineGsdRootFile(tmp, 'knowledge.md', 'Project Knowledge');
+  assert.ok(result !== null, 'should return content');
+  assert.ok(result!.includes('Project Knowledge'), 'should include label');
+  assert.ok(result!.includes('K001'), 'should include knowledge content');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: inlineGsdRootFile returns null when KNOWLEDGE.md does not exist', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const result = await inlineGsdRootFile(tmp, 'knowledge.md', 'Project Knowledge');
+  assert.strictEqual(result, null, 'should return null when file does not exist');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── appendKnowledge creates file and appends entries ──────────────────────
+
+test('knowledge: appendKnowledge creates KNOWLEDGE.md with rule when file does not exist', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'rule', 'Use real DB for integration tests', 'M001/S01');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('# Project Knowledge'), 'should have header');
+  assert.ok(content.includes('K001'), 'should have K001 id');
+  assert.ok(content.includes('Use real DB for integration tests'), 'should have rule text');
+  assert.ok(content.includes('M001/S01'), 'should have scope');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge appends to existing KNOWLEDGE.md with auto-incrementing ID', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  // Create initial file with one rule
+  await appendKnowledge(tmp, 'rule', 'First rule', 'M001');
+  // Add second rule
+  await appendKnowledge(tmp, 'rule', 'Second rule', 'M001/S02');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('K001'), 'should have K001');
+  assert.ok(content.includes('K002'), 'should have K002');
+  assert.ok(content.includes('First rule'), 'should have first rule');
+  assert.ok(content.includes('Second rule'), 'should have second rule');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge handles pattern type', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'pattern', 'Middleware chain for auth', 'M001');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('P001'), 'should have P001 id');
+  assert.ok(content.includes('Middleware chain for auth'), 'should have pattern text');
+
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+test('knowledge: appendKnowledge handles lesson type', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'gsd-knowledge-'));
+  const gsdDir = join(tmp, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  await appendKnowledge(tmp, 'lesson', 'API timeout on large payloads', 'M002');
+
+  const content = readFileSync(join(gsdDir, 'KNOWLEDGE.md'), 'utf-8');
+  assert.ok(content.includes('L001'), 'should have L001 id');
+  assert.ok(content.includes('API timeout on large payloads'), 'should have lesson text');
+
+  rmSync(tmp, { recursive: true, force: true });
+});

package/src/resources/extensions/gsd/tests/memory-leak-guards.test.ts

@@ -0,0 +1,87 @@
+/**
+ * memory-leak-guards.test.ts — Tests for #611 memory leak fixes.
+ *
+ * Verifies that module-level state accumulators are properly bounded
+ * and cleared to prevent OOM during long-running auto-mode sessions.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { saveActivityLog, clearActivityLogState } from "../activity-log.ts";
+import { clearPathCache } from "../paths.ts";
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+
+function createCtx(entries: unknown[]) {
+  return { sessionManager: { getEntries: () => entries } } as unknown as ExtensionContext;
+}
+
+// ─── activity-log: clearActivityLogState ─────────────────────────────────────
+
+test("clearActivityLogState resets dedup state so identical saves write again", () => {
+  clearActivityLogState();
+  const baseDir = mkdtempSync(join(tmpdir(), "gsd-memleak-test-"));
+  try {
+    const entries = [{ role: "assistant", content: "test entry" }];
+    const ctx = createCtx(entries);
+
+    // First save
+    saveActivityLog(ctx, baseDir, "execute-task", "M001/S01/T01");
+
+    const actDir = join(baseDir, ".gsd", "activity");
+    assert.equal(readdirSync(actDir).length, 1, "first save creates one file");
+
+    // Same content, same unit — deduped
+    saveActivityLog(ctx, baseDir, "execute-task", "M001/S01/T01");
+    assert.equal(readdirSync(actDir).length, 1, "dedup prevents duplicate write");
+
+    // Clear state
+    clearActivityLogState();
+
+    // Same content again — after clear, writes again (fresh state)
+    saveActivityLog(ctx, baseDir, "execute-task", "M001/S01/T01");
+    assert.equal(readdirSync(actDir).length, 2, "after clear, dedup state is reset");
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+// ─── activity-log: streaming JSONL write ────────────────────────────────────
+
+test("saveActivityLog writes valid JSONL via streaming", () => {
+  clearActivityLogState();
+  const baseDir = mkdtempSync(join(tmpdir(), "gsd-memleak-jsonl-"));
+  try {
+    const entries = [
+      { type: "message", message: { role: "user", content: "hello" } },
+      { type: "message", message: { role: "assistant", content: "world" } },
+      { type: "message", message: { role: "user", content: "test" } },
+    ];
+    const ctx = createCtx(entries);
+
+    saveActivityLog(ctx, baseDir, "execute-task", "M002/S01/T01");
+
+    const actDir = join(baseDir, ".gsd", "activity");
+    const files = readdirSync(actDir);
+    assert.equal(files.length, 1, "one file written");
+
+    const content = readFileSync(join(actDir, files[0]), "utf-8");
+    const lines = content.trim().split("\n");
+    assert.equal(lines.length, 3, "three JSONL lines");
+
+    for (const line of lines) {
+      assert.doesNotThrow(() => JSON.parse(line), `line is valid JSON`);
+    }
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+// ─── paths.ts: directory cache bounds ───────────────────────────────────────
+
+test("clearPathCache does not throw", () => {
+  assert.doesNotThrow(() => clearPathCache(), "clearPathCache should not throw");
+});

package/src/resources/extensions/gsd/tests/milestone-transition-worktree.test.ts

@@ -0,0 +1,144 @@
+/**
+ * milestone-transition-worktree.test.ts — Tests for #616 fix.
+ *
+ * Verifies that when auto-mode transitions between milestones, the
+ * worktree lifecycle is handled: old worktree merged, new worktree created.
+ *
+ * Uses source-level checks since the full auto-mode dispatch loop
+ * requires the @gsd/pi-coding-agent runtime.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, realpathSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createAutoWorktree,
+  teardownAutoWorktree,
+  isInAutoWorktree,
+  getAutoWorktreeOriginalBase,
+  mergeMilestoneToMain,
+} from "../auto-worktree.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function run(command: string, cwd: string): string {
+  return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-mt-wt-test-")));
+  run("git init", dir);
+  run("git config user.email test@test.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+function createMilestoneArtifacts(dir: string, mid: string): void {
+  const msDir = join(dir, ".gsd", "milestones", mid);
+  mkdirSync(msDir, { recursive: true });
+  writeFileSync(join(msDir, "CONTEXT.md"), `# ${mid} Context\n`);
+  const roadmap = [
+    `# ${mid}: Test Milestone`,
+    "**Vision**: testing",
+    "## Success Criteria",
+    "- It works",
+    "## Slices",
+    "- [x] S01 — First slice",
+  ].join("\n");
+  writeFileSync(join(msDir, `${mid}-ROADMAP.md`), roadmap);
+}
+
+// ─── Milestone transition: worktree swap ─────────────────────────────────────
+
+test("worktree swap on milestone transition: merge old, create new", () => {
+  const savedCwd = process.cwd();
+  let tempDir = "";
+
+  try {
+    tempDir = createTempRepo();
+
+    // Set up M001 and M002 milestone artifacts
+    createMilestoneArtifacts(tempDir, "M001");
+    createMilestoneArtifacts(tempDir, "M002");
+    run("git add .", tempDir);
+    run("git commit -m \"add milestones\"", tempDir);
+
+    // Phase 1: Create worktree for M001 (simulates auto-mode start)
+    const wt1 = createAutoWorktree(tempDir, "M001");
+    assert.equal(process.cwd(), wt1, "cwd should be in M001 worktree");
+    assert.ok(isInAutoWorktree(tempDir), "should be in auto-worktree");
+    assert.equal(getAutoWorktreeOriginalBase(), tempDir, "original base preserved");
+
+    // Add a commit in M001 worktree to simulate work
+    writeFileSync(join(wt1, "feature-m001.txt"), "M001 work\n");
+    run("git add .", wt1);
+    run("git commit -m \"feat(M001): add feature\"", wt1);
+
+    // Phase 2: Simulate milestone transition — merge M001, exit worktree
+    const roadmapPath = join(tempDir, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
+    const roadmapContent = readFileSync(roadmapPath, "utf-8");
+    mergeMilestoneToMain(tempDir, "M001", roadmapContent);
+
+    // After merge: cwd should be back at project root
+    assert.equal(process.cwd(), tempDir, "cwd restored to project root after merge");
+    assert.ok(!isInAutoWorktree(tempDir), "no longer in auto-worktree after merge");
+
+    // Verify M001 work was merged to main
+    const mainLog = run("git log --oneline -3", tempDir);
+    assert.ok(mainLog.includes("M001"), "M001 squash commit should be on main");
+
+    // Phase 3: Create new worktree for M002 (simulates new milestone)
+    const wt2 = createAutoWorktree(tempDir, "M002");
+    assert.equal(process.cwd(), wt2, "cwd should be in M002 worktree");
+    assert.ok(isInAutoWorktree(tempDir), "should be in M002 auto-worktree");
+
+    // The new worktree should have the M001 feature file (merged to main)
+    assert.ok(existsSync(join(wt2, "feature-m001.txt")), "M002 worktree inherits M001 merged work");
+
+    // Verify branch is correct
+    const branch = run("git branch --show-current", wt2);
+    assert.equal(branch, "milestone/M002", "M002 worktree on correct branch");
+
+    // Cleanup
+    teardownAutoWorktree(tempDir, "M002");
+  } finally {
+    process.chdir(savedCwd);
+    if (tempDir && existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+});
+
+// ─── Verify the transition code path exists in auto.ts ──────────────────────
+
+test("auto.ts milestone transition block contains worktree lifecycle", () => {
+  const autoSrc = readFileSync(
+    join(__dirname, "..", "auto.ts"),
+    "utf-8",
+  );
+
+  // The fix adds worktree merge + create inside the milestone transition block
+  assert.ok(
+    autoSrc.includes("Worktree lifecycle on milestone transition"),
+    "auto.ts should contain the worktree lifecycle comment marker",
+  );
+  assert.ok(
+    autoSrc.includes("mergeMilestoneToMain") && autoSrc.includes("mid !== currentMilestoneId"),
+    "auto.ts should call mergeMilestoneToMain during milestone transition",
+  );
+  assert.ok(
+    autoSrc.includes("createAutoWorktree") && autoSrc.includes("Created auto-worktree for"),
+    "auto.ts should create new worktree for incoming milestone",
+  );
+});

package/src/resources/extensions/gsd/tests/model-cost-table.test.ts

@@ -0,0 +1,69 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { lookupModelCost, compareModelCost, BUNDLED_COST_TABLE } from "../model-cost-table.js";
+
+// ─── lookupModelCost ─────────────────────────────────────────────────────────
+
+test("lookupModelCost finds exact match", () => {
+  const entry = lookupModelCost("claude-opus-4-6");
+  assert.ok(entry);
+  assert.equal(entry.id, "claude-opus-4-6");
+  assert.ok(entry.inputPer1k > 0);
+  assert.ok(entry.outputPer1k > 0);
+});
+
+test("lookupModelCost strips provider prefix", () => {
+  const entry = lookupModelCost("anthropic/claude-opus-4-6");
+  assert.ok(entry);
+  assert.equal(entry.id, "claude-opus-4-6");
+});
+
+test("lookupModelCost returns undefined for unknown model", () => {
+  const entry = lookupModelCost("totally-unknown-model");
+  assert.equal(entry, undefined);
+});
+
+test("lookupModelCost finds haiku", () => {
+  const entry = lookupModelCost("claude-haiku-4-5");
+  assert.ok(entry);
+  assert.ok(entry.inputPer1k < 0.001, "haiku should be cheap");
+});
+
+// ─── compareModelCost ────────────────────────────────────────────────────────
+
+test("haiku is cheaper than opus", () => {
+  assert.ok(compareModelCost("claude-haiku-4-5", "claude-opus-4-6") < 0);
+});
+
+test("opus is more expensive than sonnet", () => {
+  assert.ok(compareModelCost("claude-opus-4-6", "claude-sonnet-4-6") > 0);
+});
+
+test("same model has equal cost", () => {
+  assert.equal(compareModelCost("claude-opus-4-6", "claude-opus-4-6"), 0);
+});
+
+// ─── BUNDLED_COST_TABLE ──────────────────────────────────────────────────────
+
+test("cost table has entries for all major providers", () => {
+  const ids = BUNDLED_COST_TABLE.map(e => e.id);
+  // Anthropic
+  assert.ok(ids.includes("claude-opus-4-6"));
+  assert.ok(ids.includes("claude-sonnet-4-6"));
+  assert.ok(ids.includes("claude-haiku-4-5"));
+  // OpenAI
+  assert.ok(ids.includes("gpt-4o"));
+  assert.ok(ids.includes("gpt-4o-mini"));
+  // Google
+  assert.ok(ids.includes("gemini-2.0-flash"));
+});
+
+test("all cost table entries have valid data", () => {
+  for (const entry of BUNDLED_COST_TABLE) {
+    assert.ok(entry.id, `entry missing id`);
+    assert.ok(entry.inputPer1k >= 0, `${entry.id} inputPer1k should be >= 0`);
+    assert.ok(entry.outputPer1k >= 0, `${entry.id} outputPer1k should be >= 0`);
+    assert.ok(entry.updatedAt, `${entry.id} missing updatedAt`);
+  }
+});

package/src/resources/extensions/gsd/tests/model-router.test.ts

@@ -0,0 +1,167 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  resolveModelForComplexity,
+  escalateTier,
+  defaultRoutingConfig,
+} from "../model-router.js";
+import type { DynamicRoutingConfig, RoutingDecision } from "../model-router.js";
+import type { ClassificationResult } from "../complexity-classifier.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeClassification(tier: "light" | "standard" | "heavy", reason = "test"): ClassificationResult {
+  return { tier, reason, downgraded: false };
+}
+
+const AVAILABLE_MODELS = [
+  "claude-opus-4-6",
+  "claude-sonnet-4-6",
+  "claude-haiku-4-5",
+  "gpt-4o-mini",
+];
+
+// ─── Passthrough when disabled ───────────────────────────────────────────────
+
+test("returns configured model when routing is disabled", () => {
+  const config = { ...defaultRoutingConfig(), enabled: false };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "claude-opus-4-6");
+  assert.equal(result.wasDowngraded, false);
+});
+
+test("returns configured model when no phase config", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    undefined,
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "");
+  assert.equal(result.wasDowngraded, false);
+});
+
+// ─── Downgrade-only semantics ────────────────────────────────────────────────
+
+test("does not downgrade when tier matches configured model tier", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  const result = resolveModelForComplexity(
+    makeClassification("heavy"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "claude-opus-4-6");
+  assert.equal(result.wasDowngraded, false);
+});
+
+test("does not upgrade beyond configured model", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  // Configured model is sonnet (standard), classification says heavy
+  const result = resolveModelForComplexity(
+    makeClassification("heavy"),
+    { primary: "claude-sonnet-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "claude-sonnet-4-6");
+  assert.equal(result.wasDowngraded, false);
+});
+
+test("downgrades from opus to haiku for light tier", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  // Should pick haiku or gpt-4o-mini (cheapest light tier)
+  assert.ok(
+    result.modelId === "claude-haiku-4-5" || result.modelId === "gpt-4o-mini",
+    `Expected light-tier model, got ${result.modelId}`,
+  );
+  assert.equal(result.wasDowngraded, true);
+});
+
+test("downgrades from opus to sonnet for standard tier", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  const result = resolveModelForComplexity(
+    makeClassification("standard"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "claude-sonnet-4-6");
+  assert.equal(result.wasDowngraded, true);
+});
+
+// ─── Explicit tier_models ────────────────────────────────────────────────────
+
+test("uses explicit tier_models when configured", () => {
+  const config: DynamicRoutingConfig = {
+    ...defaultRoutingConfig(),
+    enabled: true,
+    tier_models: { light: "gpt-4o-mini", standard: "claude-sonnet-4-6" },
+  };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.equal(result.modelId, "gpt-4o-mini");
+  assert.equal(result.wasDowngraded, true);
+});
+
+// ─── Fallback chain construction ─────────────────────────────────────────────
+
+test("fallback chain includes configured primary as last resort", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: ["claude-sonnet-4-6"] },
+    config,
+    AVAILABLE_MODELS,
+  );
+  assert.ok(result.wasDowngraded);
+  // Fallbacks should include the configured fallbacks and primary
+  assert.ok(result.fallbacks.includes("claude-opus-4-6"), "primary should be in fallbacks");
+  assert.ok(result.fallbacks.includes("claude-sonnet-4-6"), "configured fallback should be in fallbacks");
+});
+
+// ─── Escalation ──────────────────────────────────────────────────────────────
+
+test("escalateTier moves light → standard", () => {
+  assert.equal(escalateTier("light"), "standard");
+});
+
+test("escalateTier moves standard → heavy", () => {
+  assert.equal(escalateTier("standard"), "heavy");
+});
+
+test("escalateTier returns null for heavy (max)", () => {
+  assert.equal(escalateTier("heavy"), null);
+});
+
+// ─── No suitable model available ─────────────────────────────────────────────
+
+test("falls back to configured model when no light-tier model available", () => {
+  const config = { ...defaultRoutingConfig(), enabled: true };
+  // Only heavy-tier models available
+  const result = resolveModelForComplexity(
+    makeClassification("light"),
+    { primary: "claude-opus-4-6", fallbacks: [] },
+    config,
+    ["claude-opus-4-6"],
+  );
+  assert.equal(result.modelId, "claude-opus-4-6");
+  assert.equal(result.wasDowngraded, false);
+});