@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/tests/prefs-wizard-coverage.test.ts

@@ -182,6 +182,70 @@ test("prefs wizard save path preserves every known preference key", async () =>
   }
 });
 
+test("verification wizard prompts for per-unit cost cap and persists it (regression #1121)", async () => {
+  // Regression for #1121: the `/gsd prefs` Verification category never prompted for
+  // `per_unit_cost_cap_usd`, so the per-unit cost cap could only be set by hand-editing
+  // PREFERENCES.md. Drive the wizard into Verification, answer the cap prompt, and assert
+  // the prompt exists and the entered value is serialized + round-trips back as a number.
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+
+  const inputLabels: string[] = [];
+  let topMenuVisits = 0;
+
+  const ctx = {
+    ui: {
+      notify() {},
+      select: async (label: string, options: string[]) => {
+        if (label === "GSD Preferences") {
+          topMenuVisits += 1;
+          if (topMenuVisits === 1) {
+            const verification = options.find((o) => o.startsWith("Verification"));
+            assert.ok(verification, "wizard menu must offer a Verification category");
+            return verification;
+          }
+          return "── Save & Exit ──";
+        }
+        // verification_commands string-list sub-menu — leave it untouched
+        if (options.includes("Done")) return "Done";
+        // boolean/enum prompts within the category — keep the current value
+        if (options.includes("(keep current)")) return "(keep current)";
+        return options[options.length - 1];
+      },
+      input: async (label: string) => {
+        inputLabels.push(label);
+        if (label.includes("Per-unit cost cap")) return "12.5";
+        return null; // escape every other numeric/string prompt (no change)
+      },
+    },
+    waitForIdle: async () => {},
+    reload: async () => {},
+  } as any;
+
+  try {
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    // The Verification wizard must actually ask for the per-unit cost cap.
+    assert.ok(
+      inputLabels.some((l) => l.includes("Per-unit cost cap")),
+      `Verification wizard must prompt for the per-unit cost cap; prompts seen:\n${inputLabels.join("\n")}`,
+    );
+
+    // The entered value must be serialized to PREFERENCES.md...
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.match(saved, /per_unit_cost_cap_usd:\s*12\.5(\s|$)/m);
+
+    // ...and round-trip back through the parser/validator as a number.
+    const parsed = parsePreferencesMarkdown(saved);
+    assert.notEqual(parsed, null);
+    const { errors, preferences } = validatePreferences(parsed!);
+    assert.deepEqual(errors, []);
+    assert.equal(preferences.per_unit_cost_cap_usd, 12.5);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("category summaries expose the wizard menu surface for configured prefs", () => {
   const summaries = buildCategorySummaries(PREF_SAMPLE_VALUES);
   assert.deepEqual(
@@ -203,11 +267,14 @@ test("category summaries expose the wizard menu surface for configured prefs", (
       "timeouts",
       "uok",
       "verification",
+      "workspace",
     ],
   );
   assert.match(summaries.models, /phase/);
   assert.match(summaries.integrations, /remote: C123/);
   assert.match(summaries.verification, /1 cmd/);
+  assert.match(summaries.workspace, /mode: parent/);
+  assert.match(summaries.workspace, /1 repo/);
 });
 
 test("models wizard offers discovered models for enabled providers", async () => {
@@ -276,3 +343,78 @@ test("models wizard offers discovered models for enabled providers", async () =>
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test("workspace wizard category configures parent mode with a declared repository", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-workspace-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+  try {
+    // Drive: Workspace → parent mode → Add repository (id=frontend, path=frontend,
+    // role=ui, verification=npm test, commit policy auto) → Done → Save & Exit.
+    const selects = [
+      "Workspace       (single-repo)",       // pick the Workspace category
+      "parent",                               // promptEnum: workspace mode
+      "Add repository",                       // sub-menu
+      "(keep current)",                       // promptEnum: commit policy -> keep auto default
+      "Done",                                 // exit repo sub-menu
+      "── Save & Exit ──",                    // exit wizard
+    ];
+    const inputs = [
+      "frontend",                             // repository id
+      "frontend",                             // repository path
+      "ui",                                   // role
+      "npm test",                             // verification commands
+    ];
+    const ctx = {
+      ui: {
+        notify() {},
+        select: async () => selects.shift(),
+        input: async () => inputs.shift(),
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    } as any;
+
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.match(saved, /mode: parent/);
+    assert.match(saved, /frontend:/);
+    assert.match(saved, /path: frontend/);
+    assert.match(saved, /role: ui/);
+    assert.match(saved, /npm test/);
+    assert.equal(selects.length, 0, "all queued selects should be consumed");
+    assert.equal(inputs.length, 0, "all queued inputs should be consumed");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("workspace wizard does not save parent mode when no repository is declared", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-workspace-empty-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+  try {
+    // parent mode with no repos added → should warn and not persist workspace.
+    const selects = [
+      "Workspace       (single-repo)",
+      "parent",
+      "Done",                                 // add nothing
+      "── Save & Exit ──",
+    ];
+    const ctx = {
+      ui: {
+        notify() {},
+        select: async () => selects.shift(),
+        input: async () => "",
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    } as any;
+
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.doesNotMatch(saved, /mode: parent/, "parent mode must not persist without a declared repo");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/progressive-planning.test.ts

@@ -17,7 +17,8 @@ import {
   getSlice,
 } from "../gsd-db.ts";
 import { autoHealSketchFlags } from "../state-reconciliation/drift/sketch-flag.ts";
-import { deriveState, deriveStateFromDb } from "../state.ts";
+import { deriveState, deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import { reconcileBeforeDispatch } from "../state-reconciliation.ts";
 import { resolveDispatch } from "../auto-dispatch.ts";
 import type { DispatchContext } from "../auto-dispatch.ts";
 
@@ -174,7 +175,7 @@ test("ADR-011: refining + flag flipped OFF mid-milestone → falls through to pl
   }
 });
 
-test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (progressive_planning ON)", async (t) => {
+test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispatch, then dispatch routes past refining (progressive_planning ON)", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -188,11 +189,22 @@ test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (prog
   );
   process.chdir(base);
 
-  // deriveStateFromDb auto-heals the stale sketch flag when PLAN.md exists,
-  // regardless of the progressive_planning preference.
+  // Derivation is pure (ADR-017): a stale sketch flag (PLAN on disk but
+  // is_sketch=1) yields 'refining' and must NOT mutate the DB. Healing is
+  // owned by reconcileBeforeDispatch, which runs before every dispatch.
+  invalidateStateCache();
+  const beforeReconcile = await deriveStateFromDb(base);
+  assert.equal(beforeReconcile.activeSlice?.id, "S02");
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal the stale sketch flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile clears the stale sketch flag once PLAN exists");
+
+  invalidateStateCache();
   const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive: flag cleared when PLAN exists");
-  assert.equal(state.phase, "planning", "derive: phase advances past refining once flag is healed");
+  assert.equal(state.phase, "planning", "re-derive advances past refining once the flag is healed");
 
   const ctx: DispatchContext = {
     basePath: base,
@@ -229,7 +241,7 @@ test("ADR-011: autoHealSketchFlags flips is_sketch=0 when PLAN file exists", asy
   assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "post-heal: flag cleared");
 });
 
-test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists", async (t) => {
+test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN exists", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -244,12 +256,23 @@ test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists",
   );
   process.chdir(base);
 
-  const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive should clear stale is_sketch");
-  assert.equal(state.phase, "planning", "state should advance past refining once stale flag is healed");
+  // Pure derivation reports the stale flag as 'refining' without repairing it.
+  invalidateStateCache();
+  const stale = await deriveStateFromDb(base);
+  assert.equal(stale.phase, "refining", "derive alone must not heal the stale flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "is_sketch unchanged before reconcile");
+
+  // Reconciliation owns the repair (ADR-017 stale-sketch-flag drift handler).
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile should clear stale is_sketch");
+
+  invalidateStateCache();
+  const healed = await deriveStateFromDb(base);
+  assert.equal(healed.phase, "planning", "state advances past refining once the stale flag is healed");
 });
 
-test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing", async (t) => {
+test("ADR-011: deriveState stays pure across worktree/canonical-root; healing belongs to reconcile at the canonical artifact root", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -265,9 +288,22 @@ test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing"
   mkdirSync(worktreePath, { recursive: true });
   process.chdir(worktreePath);
 
-  const state = await deriveState(worktreePath, { projectRootForReads: base });
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "deriveState should heal from canonical artifact root");
-  assert.equal(state.phase, "planning", "state should advance past refining when PLAN exists at canonical root");
+  // Deriving from the worktree with reads routed to the canonical artifact
+  // root resolves DB state but never mutates it (ADR-017: derive is pure).
+  // The legacy projectRootForReads-driven heal is gone; healing now happens
+  // in reconcileBeforeDispatch, which auto runs against canonicalProjectRoot.
+  invalidateStateCache();
+  const beforeReconcile = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal, even via projectRootForReads");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile at the canonical root heals the stale flag");
+
+  invalidateStateCache();
+  const healed = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(healed.phase, "planning", "re-derive advances past refining once healed at the canonical root");
 });
 
 test("ADR-011: schema v16 is idempotent — re-opening DB preserves is_sketch and sketch_scope columns", async (t) => {

package/src/resources/extensions/gsd/tests/prompt-budget-enforcement.test.ts

@@ -72,6 +72,25 @@ function setupDependencyFixture(
   mkdirSync(targetSliceDir, { recursive: true });
 }
 
+function setupFlatPhaseSlicePlan(base: string): void {
+  const phaseDir = join(base, ".gsd", "phases", "01-flat-phase");
+  mkdirSync(phaseDir, { recursive: true });
+  writeFileSync(
+    join(phaseDir, "01-01-PLAN.md"),
+    [
+      "# S01: Flat phase slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Flat task** `est:15m`",
+      "",
+      "## Verification",
+      "",
+      "- Rendered prompt points at this slice plan.",
+    ].join("\n"),
+  );
+}
+
 // ─── inlineDependencySummaries truncation ─────────────────────────────────────
 
 describe("prompt-budget: inlineDependencySummaries truncation", () => {
@@ -412,6 +431,26 @@ describe("prompt-budget: execute-task template", () => {
     }
   });
 
+  it("flat-phase execute-task fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildExecuteTaskPrompt("M001", "S01", "Slice", "T01", "Task", base, {
+        level: "minimal",
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("verificationBudget format varies with context window size", () => {
     const budget128K = computeBudgets(128_000);
     const budget1M = computeBudgets(1_000_000);
@@ -566,6 +605,25 @@ describe("prompt-budget: execute-task builder truncation pattern", () => {
 });
 
 describe("prompt-budget: reactive-execute builder", () => {
+  it("flat-phase subagent fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildReactiveExecutePrompt("M001", "Milestone", "S01", "Slice", ["T01"], base, undefined, {
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("caps dependency carry-forward per ready subagent", async () => {
     const base = createFixtureBase();
     try {

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -533,6 +533,7 @@ test("plan-milestone prompt references DB-backed planning tool and explicitly fo
   assert.match(prompt, /Do \*\*not\*\* write `?\{\{outputPath\}\}`?, `?ROADMAP\.md`?, or other planning artifacts manually/i);
   assert.match(prompt, /NEVER call `gsd_plan_milestone` with only `milestoneId` and `sliceId`/);
   assert.match(prompt, /gsd_plan_slice/);
+  assert.match(prompt, /gsd_plan_task/);
 });
 
 test("discuss prompts forbid gsd_plan_milestone slice-only tool args", () => {
@@ -548,12 +549,12 @@ test("plan-slice prompt no longer frames direct PLAN writes as the source of tru
   assert.match(prompt, /Do \*\*not\*\* rely on direct `PLAN\.md` writes as the source of truth/i);
 });
 
-test("plan-slice prompt explicitly names gsd_plan_slice as DB-backed planning tool", () => {
+test("plan-slice prompt explicitly names incremental DB-backed planning tools", () => {
   const prompt = readPrompt("plan-slice");
   assert.match(prompt, /gsd_plan_slice/);
   assert.match(prompt, /gsd_plan_task/);
-  // The prompt should describe the DB-backed tool as the canonical write path
-  assert.match(prompt, /DB-backed tool is the canonical write path/i);
+  assert.match(prompt, /Persist incrementally through DB-backed tools/i);
+  assert.match(prompt, /DB-backed tools are the canonical write path/i);
 });
 
 test("plan-slice prompt does not instruct direct file writes as a primary step", () => {
@@ -562,11 +563,12 @@ test("plan-slice prompt does not instruct direct file writes as a primary step",
   assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{outputPath\}\}`?\s*$/m);
 });
 
-test("plan-slice prompt clarifies gsd_plan_slice handles task persistence", () => {
+test("plan-slice prompt requires per-task incremental persistence", () => {
   const prompt = readPrompt("plan-slice");
-  // gsd_plan_slice persists tasks in its transaction — no separate gsd_plan_task calls needed
   assert.match(prompt, /gsd_plan_task/);
-  assert.match(prompt, /gsd_plan_slice` handles task persistence/i);
+  assert.match(prompt, /omit `tasks` for this metadata call/i);
+  assert.match(prompt, /call `gsd_plan_task` once per task/i);
+  assert.doesNotMatch(prompt, /do not call `gsd_plan_task`/i);
 });
 
 test("plan-slice prompt references web app UAT guidance when planning browser work", () => {

package/src/resources/extensions/gsd/tests/recovery-verify-logs.test.ts

@@ -227,7 +227,7 @@ test("plan-slice verify-fail logs a recovery warning when the tasks dir is missi
   }
 });
 
-test("plan-slice verify-fail logs a recovery warning when an individual task plan file is missing", () => {
+test("plan-slice verify-fail logs a recovery warning when an individual task artifact is missing", () => {
   const base = createFixtureBase("gsd-recovery-logs-taskplan-");
   try {
     const dir = sliceDir(base, "M001", "S01");
@@ -236,17 +236,17 @@ test("plan-slice verify-fail logs a recovery warning when an individual task pla
       "# S01: Has task\n\n## Tasks\n\n- [ ] **T01: A** `est:15m`\n",
       "utf-8",
     );
-    // Create the tasks dir but NOT the T01-PLAN.md file inside it.
+    // Create the tasks dir but NOT any T01 task artifact inside it.
     mkdirSync(join(dir, "tasks"), { recursive: true });
 
     const { result, logs } = verifyAndCaptureLogs("plan-slice", "M001/S01", base);
 
-    assert.equal(result, false, "a missing task plan file must fail verification");
+    assert.equal(result, false, "a missing task artifact must fail verification");
     const recovery = findRecovery(logs);
     assert.ok(recovery, "a recovery warning must be logged");
     assert.match(
       recovery!.message,
-      /verify-fail plan-slice M001\/S01: task plan missing .*T01-PLAN\.md/u,
+      /verify-fail plan-slice M001\/S01: task artifact missing for T01/u,
     );
   } finally {
     rmSync(base, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/redact-secrets.test.ts

@@ -0,0 +1,56 @@
+// redact-secrets.test.ts
+// Verifies secret-shaped substrings are replaced while benign text and JSON
+// structure are preserved.
+//
+// Fake secrets are assembled from fragments at runtime so external secret
+// scanners (GitGuardian) and the repo secret-scan never see a literal
+// secret-shaped string in this source file — the runtime value still matches
+// the redaction patterns, which is what the test exercises.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { redactSecrets } from "../redact-secrets.js";
+
+const PLACEHOLDER = "«redacted»";
+
+// Fragment-built fakes (never a full secret literal in source).
+const FAKE = {
+  github: "gh" + "p_" + "A".repeat(36), // GitHub PAT shape: ghp_ + 36 chars
+  aws: "AKIA" + "IOSFODNN7EXAMPL0", // AWS access key id shape: AKIA + 16 chars
+  anthropic: "sk-" + "ant-" + "x".repeat(28), // Anthropic key shape
+  bearer: "sk-" + "b".repeat(24), // generic sk- token
+};
+
+test("redacts a Bearer authorization token", () => {
+  const out = redactSecrets(`Authorization: Bearer ${FAKE.bearer}`);
+  assert.ok(out.includes("Authorization:"), "keeps the label context");
+  assert.ok(out.includes(PLACEHOLDER), "redacts the token");
+  assert.ok(!out.includes(FAKE.bearer), "raw token is gone");
+});
+
+test("redacts key=value style secrets", () => {
+  const anth = redactSecrets(`ANTHROPIC_API_KEY="${FAKE.anthropic}"`);
+  assert.ok(anth.includes(PLACEHOLDER) && !anth.includes(FAKE.anthropic));
+  const gh = redactSecrets(`"token": "${FAKE.github}"`);
+  assert.ok(gh.includes(PLACEHOLDER) && !gh.includes(FAKE.github));
+});
+
+test("redacts an AWS access key id", () => {
+  const out = redactSecrets(`aws key ${FAKE.aws} in output`);
+  assert.ok(out.includes(PLACEHOLDER) && !out.includes(FAKE.aws));
+});
+
+test("leaves benign text mentioning 'token' untouched", () => {
+  const line = "The token is passed to the next unit for processing.";
+  assert.equal(redactSecrets(line), line);
+});
+
+test("redacting a JSON string keeps it valid JSON", () => {
+  const original = JSON.stringify({ msg: "using key=SECRETVALUE here", auth: FAKE.github });
+  const redacted = redactSecrets(original);
+  // Must still parse.
+  const parsed = JSON.parse(redacted) as { msg: string; auth: string };
+  // The bare GitHub token is redacted; the non-keyword "key=..." stays (no false structure break).
+  assert.ok(!redacted.includes(FAKE.github));
+  assert.equal(parsed.auth, PLACEHOLDER);
+});

package/src/resources/extensions/gsd/tests/register-hooks-flat-phase-migration.test.ts

@@ -0,0 +1,73 @@
+// Project/App: gsd-pi
+// File Purpose: Verifies session bootstrap fails closed when flat-phase migration cannot complete.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
+
+type HookHandler = (event: unknown, ctx: any) => Promise<void> | void;
+
+function createSessionStartHandler(): HookHandler {
+  const handlers = new Map<string, HookHandler>();
+  const pi = {
+    on(event: string, handler: HookHandler) {
+      handlers.set(event, handler);
+    },
+  };
+
+  registerHooks(pi as any, []);
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler should be registered");
+  return sessionStart;
+}
+
+function makeContext(basePath: string) {
+  return {
+    cwd: basePath,
+    hasUI: false,
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setWidget: () => {},
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+    },
+    model: null,
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+    },
+    sessionManager: {
+      getSessionId: () => null,
+    },
+    setCompactionThresholdOverride: () => {},
+  };
+}
+
+test("session_start rejects when required flat-phase migration fails", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-bootstrap-flat-migration-"));
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# M001: Foundation\n", "utf-8");
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  closeDatabase();
+
+  writeFileSync(join(base, ".gsd-backups"), "not a directory\n", "utf-8");
+
+  const sessionStart = createSessionStartHandler();
+
+  await assert.rejects(
+    () => Promise.resolve(sessionStart({}, makeContext(base))),
+    /flat-phase migration/,
+  );
+  assert.ok(existsSync(join(base, ".gsd", "milestones", "M001")), "legacy layout should remain for recovery");
+});