@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.9ad8ae33

package/src/resources/extensions/gsd/tests/integration/gsd-integration-fixture.ts

@@ -0,0 +1,80 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type GsdIntegrationProject = {
+  root: string;
+};
+
+export type CreateGsdIntegrationProjectOptions = {
+  prefix?: string;
+  initialFiles?: Record<string, string>;
+};
+
+export function projectRoot(project: GsdIntegrationProject | string): string {
+  return typeof project === "string" ? project : project.root;
+}
+
+export function git(project: GsdIntegrationProject | string, ...args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: projectRoot(project),
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+export function createGsdIntegrationProject(
+  options: CreateGsdIntegrationProjectOptions | string = {},
+): GsdIntegrationProject {
+  const resolvedOptions = typeof options === "string" ? { prefix: options } : options;
+  const prefix = resolvedOptions.prefix ?? "gsd-integration-";
+  const root = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+
+  git(root, "init");
+  git(root, "config", "user.email", "test@test.com");
+  git(root, "config", "user.name", "Test");
+  git(root, "config", "core.autocrlf", "false");
+
+  writeProjectFile(root, "README.md", "# test\n");
+  for (const [relativePath, content] of Object.entries(resolvedOptions.initialFiles ?? {})) {
+    writeProjectFile(root, relativePath, content);
+  }
+  git(root, "add", ".");
+  git(root, "commit", "-m", "init");
+  git(root, "branch", "-M", "main");
+
+  return { root };
+}
+
+export function writeProjectFile(
+  project: GsdIntegrationProject | string,
+  relativePath: string,
+  content: string,
+): string {
+  const filePath = join(projectRoot(project), relativePath);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
+export function writeGsdMilestoneContext(
+  project: GsdIntegrationProject | string,
+  milestoneId: string,
+  content = `# ${milestoneId} Context\n`,
+): string {
+  return writeProjectFile(
+    project,
+    join(".gsd", "milestones", milestoneId, "CONTEXT.md"),
+    content,
+  );
+}
+
+export function commitAll(project: GsdIntegrationProject | string, message: string): void {
+  git(project, "add", ".");
+  git(project, "commit", "-m", message);
+}
+
+export function cleanupGsdIntegrationProject(project: GsdIntegrationProject | string): void {
+  rmSync(projectRoot(project), { recursive: true, force: true });
+}

package/src/resources/extensions/gsd/tests/integration/run-uat.test.ts

@@ -731,6 +731,75 @@ test('(u) run-uat prompt promotes artifact-driven browser specs to browser-execu
     }
 });
 
+test('(w) run-uat prompt promotes browser-executable harness specs to runtime-executable (M006/S01)', async () => {
+    const base = createFixtureBase();
+    try {
+      const uatRel = '.gsd/milestones/M006/slices/S01/S01-UAT.md';
+      const uatContent = [
+        '# S01 UAT',
+        '',
+        '## UAT Type',
+        '- UAT mode: browser-executable',
+        '',
+        '## Preconditions',
+        '- Start the local app server with `npm run start`.',
+        '- Open the app at `http://127.0.0.1:4173`.',
+        '',
+        '## Evidence',
+        '- Fresh closeout verification command: `npm run test:uat`',
+      ].join('\n');
+      writeSliceFile(base, 'M006', 'S01', 'UAT', uatContent);
+
+      const prompt = await buildRunUatPrompt('M006', 'S01', uatRel, uatContent, base);
+
+      assert.match(prompt, /\*\*Detected UAT mode:\*\*\s*`runtime-executable`/);
+      assert.match(prompt, /uatType: "runtime-executable"/);
+      assert.match(prompt, /Runtime harness override/i);
+      assert.match(prompt, /Do \*\*not\*\* call `uat-service-start`/);
+      assert.doesNotMatch(prompt, /uatType: "browser-executable"/);
+    } finally {
+      cleanup(base);
+    }
+});
+
+test('(w2) run-uat prompt promotes harness from slice context when UAT only names test:server (M007/S01)', async () => {
+    const base = createFixtureBase();
+    try {
+      const uatRel = '.gsd/milestones/M007/slices/S01/S01-UAT.md';
+      const uatContent = [
+        '# S01 UAT',
+        '',
+        '## UAT Type',
+        '- UAT mode: browser-executable',
+        '',
+        '## Preconditions',
+        '- Start the dev/local verification server with `npm run test:server`.',
+        '- Open the app at the localhost URL printed by the server.',
+      ].join('\n');
+      writeSliceFile(base, 'M007', 'S01', 'UAT', uatContent);
+      writeSliceFile(
+        base,
+        'M007',
+        'S01',
+        'SUMMARY',
+        [
+          '# S01 Summary',
+          '',
+          'Verification: `npm run test:uat` passed with clean browser diagnostics.',
+        ].join('\n'),
+      );
+
+      const prompt = await buildRunUatPrompt('M007', 'S01', uatRel, uatContent, base);
+
+      assert.match(prompt, /\*\*Detected UAT mode:\*\*\s*`runtime-executable`/);
+      assert.match(prompt, /Runtime harness override/i);
+      assert.match(prompt, /npm run test:server/);
+      assert.match(prompt, /uatType: "runtime-executable"/);
+    } finally {
+      cleanup(base);
+    }
+});
+
 test('(v) run-uat prompt keeps deferred browser work artifact-driven', async () => {
     const base = createFixtureBase();
     try {
@@ -748,4 +817,134 @@ test('(v) run-uat prompt keeps deferred browser work artifact-driven', async ()
       cleanup(base);
     }
 });
+
+test('(x) checkNeedsRunUat returns runtime-executable when slice SUMMARY names a self-contained harness (M007/S01)', async () => {
+    // Regression: the dispatch gate must surface the same effective UAT mode
+    // that buildRunUatPrompt emits. When the UAT file alone declares
+    // `browser-executable` but the slice SUMMARY references `npm run test:uat`,
+    // the prompt promotes to `runtime-executable` — and so must the gate, or
+    // the auto-dispatch path requires browser tools / warms up the browser
+    // daemon (and may stop dispatch entirely) for a UAT that never touches
+    // the browser. See cursor[bot] review on PR #696.
+    const base = createFixtureBase();
+    try {
+      const roadmapDir = join(base, '.gsd', 'milestones', 'M007');
+      mkdirSync(roadmapDir, { recursive: true });
+      writeFileSync(
+        join(roadmapDir, 'M007-ROADMAP.md'),
+        [
+          '# M007: Test roadmap',
+          '',
+          '## Slices',
+          '',
+          '- [x] **S01: Only slice** `risk:low` `depends:[]`',
+          '',
+          '## Boundary Map',
+          '',
+        ].join('\n'),
+      );
+      writeSliceFile(
+        base,
+        'M007',
+        'S01',
+        'UAT',
+        [
+          '# S01 UAT',
+          '',
+          '## UAT Type',
+          '- UAT mode: browser-executable',
+          '',
+          '## Preconditions',
+          '- Start the dev/local verification server with `npm run test:server`.',
+        ].join('\n'),
+      );
+      writeSliceFile(
+        base,
+        'M007',
+        'S01',
+        'SUMMARY',
+        [
+          '# S01 Summary',
+          '',
+          'Verification: `npm run test:uat` passed with clean browser diagnostics.',
+        ].join('\n'),
+      );
+
+      const state = {
+        activeMilestone: { id: 'M007', title: 'Test roadmap' },
+        activeSlice: null,
+        activeTask: null,
+        phase: 'validating-milestone',
+        recentDecisions: [],
+        blockers: [],
+        nextAction: 'Validate M007',
+        registry: [],
+      } as const;
+
+      const result = await checkNeedsRunUat(base, 'M007', state as any, { uat_dispatch: true } as any);
+      assert.deepStrictEqual(
+        result,
+        { sliceId: 'S01', uatType: 'runtime-executable' },
+        'dispatch gate must mirror the prompt`s runtime-executable promotion so it does not require browser tools',
+      );
+    } finally {
+      cleanup(base);
+    }
+});
+
+test('(x2) checkNeedsRunUat leaves true browser-executable UAT unpromoted when no harness is referenced', async () => {
+    // Counter-test for (x): when the slice SUMMARY does NOT name a
+    // self-contained harness, the dispatch gate must still require browser
+    // tools for a genuinely browser-executable UAT.
+    const base = createFixtureBase();
+    try {
+      const roadmapDir = join(base, '.gsd', 'milestones', 'M008');
+      mkdirSync(roadmapDir, { recursive: true });
+      writeFileSync(
+        join(roadmapDir, 'M008-ROADMAP.md'),
+        [
+          '# M008: Test roadmap',
+          '',
+          '## Slices',
+          '',
+          '- [x] **S01: Only slice** `risk:low` `depends:[]`',
+          '',
+          '## Boundary Map',
+          '',
+        ].join('\n'),
+      );
+      writeSliceFile(base, 'M008', 'S01', 'UAT', makeBrowserObservableUatContent('browser-executable'));
+      writeSliceFile(
+        base,
+        'M008',
+        'S01',
+        'SUMMARY',
+        [
+          '# S01 Summary',
+          '',
+          'Verification: clicked through the UI and confirmed the search box filters todos.',
+        ].join('\n'),
+      );
+
+      const state = {
+        activeMilestone: { id: 'M008', title: 'Test roadmap' },
+        activeSlice: null,
+        activeTask: null,
+        phase: 'validating-milestone',
+        recentDecisions: [],
+        blockers: [],
+        nextAction: 'Validate M008',
+        registry: [],
+      } as const;
+
+      const result = await checkNeedsRunUat(base, 'M008', state as any, { uat_dispatch: true } as any);
+      assert.deepStrictEqual(
+        result,
+        { sliceId: 'S01', uatType: 'browser-executable' },
+        'a true browser-executable UAT without a harness reference must keep its browser-executable mode',
+      );
+    } finally {
+      cleanup(base);
+    }
+});
 });

package/src/resources/extensions/gsd/tests/mcp-project-config.test.ts

@@ -60,7 +60,9 @@ test("ensureProjectWorkflowMcpConfig creates .mcp.json with workflow and browser
     assert.equal(typeof browserArgs[mcpArgIndex + 6], "string");
     assert.ok((browserArgs[mcpArgIndex + 6] ?? "").length > 0, "identity-key must be non-empty");
     assert.equal(browserArgs[mcpArgIndex + 7], "--identity-project");
-    assert.equal(browserArgs[mcpArgIndex + 8], projectRoot);
+    assert.equal(typeof browserArgs[mcpArgIndex + 8], "string");
+    assert.ok((browserArgs[mcpArgIndex + 8] ?? "").length > 0, "identity-project must be non-empty");
+    assert.doesNotMatch(browserArgs[mcpArgIndex + 8] ?? "", /[\\/]/, "identity-project must not be a filesystem path");
     assert.equal((browserServer as { cwd?: string })?.cwd, projectRoot);
 
     const settings = JSON.parse(readFileSync(join(projectRoot, ".claude", "settings.local.json"), "utf-8")) as {

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

@@ -3,22 +3,24 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { openDatabase, insertAssessment, insertMilestone, insertSlice, closeDatabase } from "../gsd-db.js";
 import {
   isMilestoneCloseoutSettled,
   evaluateCompleteMilestoneDispatch,
+  isCompletedMilestoneTerminal,
+  repairMissingMilestoneSummaryProjection,
 } from "../milestone-closeout.js";
 import type { DispatchContext } from "../auto-dispatch.js";
 
 /** Build a minimal DispatchContext for the dispatch-policy branches under test. */
-function makeDispatchCtx(base: string, phase: string): DispatchContext {
+function makeDispatchCtx(base: string, phase: string, mid = "M001"): DispatchContext {
   return {
     basePath: base,
-    mid: "M001",
-    midTitle: "M001: Test",
+    mid,
+    midTitle: `${mid}: Test`,
     state: { phase } as DispatchContext["state"],
     prefs: undefined,
   } as DispatchContext;
@@ -119,3 +121,92 @@ test("evaluateCompleteMilestoneDispatch skips when milestone is already closed",
   assert.ok(action, "an already-closed milestone in completing-milestone should yield an action");
   assert.equal(action!.action, "skip", "already-closed milestone should resolve to skip (idempotent)");
 });
+
+test("isCompletedMilestoneTerminal accepts DB complete without SUMMARY artifact", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-terminal-db-complete-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+
+  assert.equal(await isCompletedMilestoneTerminal(base, "M008"), true);
+});
+
+test("isCompletedMilestoneTerminal accepts validation-pass with all slices closed", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-terminal-validation-pass-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Active", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M008/M008-VALIDATION.md",
+    milestoneId: "M008",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+
+  assert.equal(await isCompletedMilestoneTerminal(base, "M008"), true);
+});
+
+test("evaluateCompleteMilestoneDispatch repairs missing SUMMARY when DB is closed", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-dispatch-repair-summary-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd", "milestones", "M008"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Live Text Search", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M008/M008-VALIDATION.md",
+    milestoneId: "M008",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+
+  const action = await evaluateCompleteMilestoneDispatch(
+    makeDispatchCtx(base, "completing-milestone", "M008"),
+  );
+  assert.equal(action?.action, "skip");
+  assert.ok(
+    existsSync(join(base, ".gsd", "milestones", "M008", "M008-SUMMARY.md")),
+    "repair should write the missing milestone SUMMARY projection",
+  );
+});
+
+test("repairMissingMilestoneSummaryProjection succeeds when milestone dir does not exist yet", async () => {
+  // Regression: resolveExpectedArtifactPath returns null before the milestone
+  // directory exists. The post-write success check must use the handler's
+  // returned summaryPath (the absolute path it just created), not the
+  // pre-write resolver result, otherwise repair always reports failure and
+  // dispatch falls back to re-dispatching complete-milestone.
+  const base = mkdtempSync(join(tmpdir(), "gsd-repair-summary-new-dir-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M042", title: "Done", status: "complete" });
+
+  const repair = await repairMissingMilestoneSummaryProjection(base, "M042");
+  assert.equal(repair.ok, true, "repair should report success when handler creates the SUMMARY");
+  assert.ok(
+    existsSync(join(base, ".gsd", "milestones", "M042", "M042-SUMMARY.md")),
+    "repair should write the SUMMARY artifact to the canonical projection path",
+  );
+});
+
+test("repairMissingMilestoneSummaryProjection is idempotent when SUMMARY exists", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-repair-summary-idempotent-"));
+  tmpDirs.push(base);
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  const summaryPath = join(milestoneDir, "M001-SUMMARY.md");
+  writeFileSync(summaryPath, "# Existing summary\n");
+
+  const repair = await repairMissingMilestoneSummaryProjection(base, "M001");
+  assert.equal(repair.ok, true);
+  assert.equal(readFileSync(summaryPath, "utf-8"), "# Existing summary\n");
+});

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

@@ -14,7 +14,7 @@ import { tmpdir } from "node:os";
 import { resolveExpectedArtifactPath } from "../auto-artifact-paths.ts";
 import { unitPhaseLabel, unitVerb } from "../auto-dashboard.ts";
 import { classifyUnitPhase } from "../metrics.ts";
-import { resolveModelWithFallbacksForUnit } from "../preferences-models.ts";
+import { resolveDefaultSessionModel, resolveModelWithFallbacksForUnit } from "../preferences-models.ts";
 import { KNOWN_UNIT_LABELS } from "../preferences-types.ts";
 
 function withModelPreferences<T>(fn: () => T): T {
@@ -92,6 +92,37 @@ test("run-uat falls back to completion when uat bucket is not configured", () =>
   }
 });
 
+test("default session model resolves from the explicit project base path", () => {
+  const oldHome = process.env.GSD_HOME;
+  const originalCwd = process.cwd();
+  const home = mkdtempSync(join(tmpdir(), "gsd-model-map-home-"));
+  const base = mkdtempSync(join(tmpdir(), "gsd-model-map-project-"));
+
+  try {
+    process.env.GSD_HOME = home;
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "PREFERENCES.md"), [
+      "---",
+      "models:",
+      "  execution: gpt-5.5",
+      "---",
+      "",
+    ].join("\n"));
+    process.chdir(home);
+
+    assert.deepEqual(resolveDefaultSessionModel("openai-codex", base), {
+      provider: "openai-codex",
+      id: "gpt-5.5",
+    });
+  } finally {
+    process.chdir(originalCwd);
+    if (oldHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = oldHome;
+    rmSync(home, { recursive: true, force: true });
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("every known unit label with a dispatch phase resolves when all model buckets are configured", () => {
   withModelPreferences(() => {
     const missing = KNOWN_UNIT_LABELS.filter((unitType) => !resolveModelWithFallbacksForUnit(unitType));

package/src/resources/extensions/gsd/tests/notification-store.test.ts

@@ -306,6 +306,38 @@ describe("notification-store", () => {
     rmSync(lockPath, { force: true });
   });
 
+  test("structured meta persists kind and scope on the entry", () => {
+    initNotificationStore(tmp);
+    appendNotification("Auto-mode blocked — validation gate", "warning", "notify", { kind: "auto-stop", scope: "M005" });
+
+    const entries = readNotifications();
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].kind, "auto-stop");
+    assert.equal(entries[0].scope, "M005");
+  });
+
+  test("dedup keys on kind+scope when present, not on prose", () => {
+    initNotificationStore(tmp);
+    appendNotification("Auto-mode blocked — validation gate", "warning", "notify", { kind: "auto-stop", scope: "M005" });
+    // Rephrased message, same structured identity → deduped within the window
+    appendNotification("Auto-mode blocked — gate rejected", "warning", "notify", { kind: "auto-stop", scope: "M005" });
+    // Same kind, different scope → distinct
+    appendNotification("Auto-mode blocked — validation gate", "warning", "notify", { kind: "auto-stop", scope: "M006" });
+
+    assert.equal(readNotifications().length, 2);
+  });
+
+  test("readNotifications filters by kind and scope", () => {
+    initNotificationStore(tmp);
+    appendNotification("a", "info", "notify", { kind: "auto-stop", scope: "M005" });
+    appendNotification("b", "info", "notify", { kind: "provider-error-pause", scope: "M005" });
+    appendNotification("c", "info");
+
+    assert.equal(readNotifications(tmp, { kind: "auto-stop" }).length, 1);
+    assert.equal(readNotifications(tmp, { scope: "M005" }).length, 2);
+    assert.equal(readNotifications(tmp, { kind: "provider-error-pause", scope: "M005" })[0].message, "b");
+  });
+
   test("listeners are notified on append, markAllRead, and clear", () => {
     initNotificationStore(tmp);
     let calls = 0;

package/src/resources/extensions/gsd/tests/oauth-api-model-routing.test.ts

@@ -0,0 +1,167 @@
+/**
+ * OAuth/subscription vs pay-per-token API routing for bare model IDs.
+ *
+ * When the same model ID (e.g. gpt-5.5) exists on multiple providers, resolveModelId
+ * must prefer subscription/OAuth routes over platform API keys.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { MODELS } from "../../../../../packages/pi-ai/dist/models.generated.js";
+import {
+  BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE,
+  resolveModelId,
+} from "../auto-model-selection.js";
+
+type ModelRef = { id: string; provider: string };
+
+function modelsForProviders(modelId: string, providers: string[]): ModelRef[] {
+  return providers.map((provider) => ({ id: modelId, provider }));
+}
+
+/** Table-driven precedence cases — one row per conflict shape, not per model ID. */
+const PRECEDENCE_CASES: Array<{
+  label: string;
+  modelId: string;
+  providers: string[];
+  expected: string;
+  currentProvider?: string;
+}> = [
+  {
+    label: "ChatGPT OAuth beats OpenAI API (gpt-5.5)",
+    modelId: "gpt-5.5",
+    providers: ["openai", "openai-codex"],
+    expected: "openai-codex",
+  },
+  {
+    label: "Codex beats Copilot beats OpenAI API (gpt-5.5 triple)",
+    modelId: "gpt-5.5",
+    providers: ["openai", "github-copilot", "openai-codex"],
+    expected: "openai-codex",
+  },
+  {
+    label: "Copilot OAuth beats OpenAI API when no Codex (gpt-5.5)",
+    modelId: "gpt-5.5",
+    providers: ["openai", "github-copilot"],
+    expected: "github-copilot",
+  },
+  {
+    label: "Copilot OAuth beats OpenAI API (gpt-5-mini)",
+    modelId: "gpt-5-mini",
+    providers: ["openai", "github-copilot"],
+    expected: "github-copilot",
+  },
+  {
+    label: "Anthropic beats Copilot for Claude (claude-sonnet-4-6)",
+    modelId: "claude-sonnet-4-6",
+    providers: ["anthropic", "github-copilot"],
+    expected: "anthropic",
+  },
+  {
+    label: "Copilot beats Google API for Gemini (gemini-2.5-pro)",
+    modelId: "gemini-2.5-pro",
+    providers: ["google", "github-copilot"],
+    expected: "github-copilot",
+  },
+  {
+    label: "Gemini CLI beats Google API (gemini-2.5-pro)",
+    modelId: "gemini-2.5-pro",
+    providers: ["google", "google-gemini-cli"],
+    expected: "google-gemini-cli",
+  },
+  {
+    label: "Gemini CLI beats Copilot beats Google API",
+    modelId: "gemini-2.5-pro",
+    providers: ["google", "github-copilot", "google-gemini-cli"],
+    expected: "google-gemini-cli",
+  },
+  {
+    label: "Session provider still wins (openai-codex explicit)",
+    modelId: "gpt-5.5",
+    providers: ["openai", "openai-codex", "github-copilot"],
+    expected: "github-copilot",
+    currentProvider: "github-copilot",
+  },
+  {
+    label: "claude-code session beats anthropic (#3772)",
+    modelId: "claude-sonnet-4-6",
+    providers: ["anthropic", "claude-code"],
+    expected: "claude-code",
+    currentProvider: "claude-code",
+  },
+];
+
+for (const row of PRECEDENCE_CASES) {
+  test(`resolveModelId precedence: ${row.label}`, () => {
+    const available = modelsForProviders(row.modelId, row.providers);
+    const result = resolveModelId(row.modelId, available, row.currentProvider);
+    assert.ok(result, `expected a match for ${row.modelId}`);
+    assert.equal(result.provider, row.expected);
+  });
+}
+
+test("BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE covers known OAuth/subscription providers", () => {
+  const expected = [
+    "openai-codex",
+    "google-gemini-cli",
+    "anthropic",
+    "github-copilot",
+    "google-antigravity",
+  ];
+  assert.deepEqual([...BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE], expected);
+});
+
+test("every catalog overlap with OAuth/subscription + API resolves to subscription route", () => {
+  const oauthProviders = new Set(["anthropic", "github-copilot", "openai-codex"]);
+  const subscriptionCli = new Set(["google-gemini-cli", "google-antigravity", "claude-code"]);
+  const apiPayPerToken = new Set(["openai", "google", "azure-openai-responses"]);
+
+  const byId = new Map<string, Set<string>>();
+  for (const [provider, models] of Object.entries(MODELS)) {
+    for (const id of Object.keys(models)) {
+      if (!byId.has(id)) byId.set(id, new Set());
+      byId.get(id)!.add(provider);
+    }
+  }
+
+  const failures: string[] = [];
+
+  for (const [modelId, providers] of byId) {
+    if (providers.size < 2) continue;
+
+    const hasApi = [...providers].some((p) => apiPayPerToken.has(p));
+    const subscriptionCandidates = [...providers].filter(
+      (p) => oauthProviders.has(p) || subscriptionCli.has(p),
+    );
+    if (!hasApi || subscriptionCandidates.length === 0) continue;
+
+    const testProviders = new Set<string>(subscriptionCandidates);
+    for (const p of providers) {
+      if (apiPayPerToken.has(p)) testProviders.add(p);
+    }
+
+    const available = modelsForProviders(modelId, [...testProviders]);
+    const result = resolveModelId(modelId, available, undefined);
+    if (!result) {
+      failures.push(`${modelId}: no resolution among ${[...testProviders].join(", ")}`);
+      continue;
+    }
+
+    const winnerIsSubscription =
+      oauthProviders.has(result.provider) ||
+      subscriptionCli.has(result.provider) ||
+      result.provider === "anthropic";
+
+    if (!winnerIsSubscription) {
+      failures.push(
+        `${modelId}: got ${result.provider}, expected subscription route among ${[...testProviders].join(", ")}`,
+      );
+    }
+  }
+
+  assert.equal(
+    failures.length,
+    0,
+    `catalog overlap routing failures:\n${failures.join("\n")}`,
+  );
+});