gsd-pi 2.67.0-dev.1cd1e0f → 2.67.0-dev.2142d3e

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,3 +1,6 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
 const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
@@ -65,6 +68,69 @@ const GATE_SAFE_TOOLS = new Set([
   "search_and_read",
 ]);
 
+export interface WriteGateSnapshot {
+  verifiedDepthMilestones: string[];
+  activeQueuePhase: boolean;
+  pendingGateId: string | null;
+}
+
+function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+}
+
+function writeGateSnapshotPath(basePath: string = process.cwd()): string {
+  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+}
+
+function currentWriteGateSnapshot(): WriteGateSnapshot {
+  return {
+    verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+    activeQueuePhase,
+    pendingGateId,
+  };
+}
+
+function persistWriteGateSnapshot(basePath: string = process.cwd()): void {
+  if (!shouldPersistWriteGateSnapshot()) return;
+  const path = writeGateSnapshotPath(basePath);
+  mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
+  const tempPath = `${path}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
+  renameSync(tempPath, path);
+}
+
+function clearPersistedWriteGateSnapshot(basePath: string = process.cwd()): void {
+  if (!shouldPersistWriteGateSnapshot()) return;
+  const path = writeGateSnapshotPath(basePath);
+  try {
+    unlinkSync(path);
+  } catch {
+    // swallow
+  }
+}
+
+function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
+  const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const verified = Array.isArray(record.verifiedDepthMilestones)
+    ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
+    : [];
+  return {
+    verifiedDepthMilestones: [...new Set(verified)].sort(),
+    activeQueuePhase: record.activeQueuePhase === true,
+    pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
+  };
+}
+
+export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+  const path = writeGateSnapshotPath(basePath);
+  if (!existsSync(path)) return currentWriteGateSnapshot();
+  try {
+    return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return currentWriteGateSnapshot();
+  }
+}
+
 export function isDepthVerified(): boolean {
   return verifiedDepthMilestones.size > 0;
 }
@@ -77,28 +143,40 @@ export function isMilestoneDepthVerified(milestoneId: string | null | undefined)
   return verifiedDepthMilestones.has(milestoneId);
 }
 
+export function isMilestoneDepthVerifiedInSnapshot(
+  snapshot: WriteGateSnapshot,
+  milestoneId: string | null | undefined,
+): boolean {
+  if (!milestoneId) return false;
+  return snapshot.verifiedDepthMilestones.includes(milestoneId);
+}
+
 export function isQueuePhaseActive(): boolean {
   return activeQueuePhase;
 }
 
 export function setQueuePhaseActive(active: boolean): void {
   activeQueuePhase = active;
+  persistWriteGateSnapshot();
 }
 
 export function resetWriteGateState(): void {
   verifiedDepthMilestones.clear();
   pendingGateId = null;
+  persistWriteGateSnapshot();
 }
 
 export function clearDiscussionFlowState(): void {
   verifiedDepthMilestones.clear();
   activeQueuePhase = false;
   pendingGateId = null;
+  clearPersistedWriteGateSnapshot();
 }
 
-export function markDepthVerified(milestoneId?: string | null): void {
+export function markDepthVerified(milestoneId?: string | null, basePath: string = process.cwd()): void {
   if (!milestoneId) return;
   verifiedDepthMilestones.add(milestoneId);
+  persistWriteGateSnapshot(basePath);
 }
 
 /**
@@ -130,6 +208,7 @@ function extractContextMilestoneId(inputPath: string): string | null {
  */
 export function setPendingGate(gateId: string): void {
   pendingGateId = gateId;
+  persistWriteGateSnapshot();
 }
 
 /**
@@ -137,6 +216,7 @@ export function setPendingGate(gateId: string): void {
  */
 export function clearPendingGate(): void {
   pendingGateId = null;
+  persistWriteGateSnapshot();
 }
 
 /**
@@ -154,11 +234,20 @@ export function getPendingGate(): string | null {
  * Read-only tools and ask_user_questions itself are always allowed.
  */
 export function shouldBlockPendingGate(
+  toolName: string,
+  milestoneId: string | null,
+  queuePhaseActive?: boolean,
+): { block: boolean; reason?: string } {
+  return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+}
+
+export function shouldBlockPendingGateInSnapshot(
+  snapshot: WriteGateSnapshot,
   toolName: string,
   _milestoneId: string | null,
   _queuePhaseActive?: boolean,
 ): { block: boolean; reason?: string } {
-  if (!pendingGateId) return { block: false };
+  if (!snapshot.pendingGateId) return { block: false };
 
   if (GATE_SAFE_TOOLS.has(toolName)) return { block: false };
 
@@ -168,7 +257,7 @@ export function shouldBlockPendingGate(
   return {
     block: true,
     reason: [
-      `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+      `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
       `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -182,11 +271,20 @@ export function shouldBlockPendingGate(
  * Read-only bash commands are allowed; mutating commands are blocked.
  */
 export function shouldBlockPendingGateBash(
+  command: string,
+  milestoneId: string | null,
+  queuePhaseActive?: boolean,
+): { block: boolean; reason?: string } {
+  return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+}
+
+export function shouldBlockPendingGateBashInSnapshot(
+  snapshot: WriteGateSnapshot,
   command: string,
   _milestoneId: string | null,
   _queuePhaseActive?: boolean,
 ): { block: boolean; reason?: string } {
-  if (!pendingGateId) return { block: false };
+  if (!snapshot.pendingGateId) return { block: false };
 
   // Allow read-only bash commands
   if (BASH_READ_ONLY_RE.test(command)) return { block: false };
@@ -194,7 +292,7 @@ export function shouldBlockPendingGateBash(
   return {
     block: true,
     reason: [
-      `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+      `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
       `You MUST re-call ask_user_questions with the gate question before running mutating commands.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -275,6 +373,15 @@ export function shouldBlockContextArtifactSave(
   artifactType: string,
   milestoneId: string | null,
   sliceId?: string | null,
+): { block: boolean; reason?: string } {
+  return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+}
+
+export function shouldBlockContextArtifactSaveInSnapshot(
+  snapshot: WriteGateSnapshot,
+  artifactType: string,
+  milestoneId: string | null,
+  sliceId?: string | null,
 ): { block: boolean; reason?: string } {
   if (artifactType !== "CONTEXT") return { block: false };
   if (sliceId) return { block: false };
@@ -287,7 +394,7 @@ export function shouldBlockContextArtifactSave(
       ].join(" "),
     };
   }
-  if (isMilestoneDepthVerified(milestoneId)) return { block: false };
+  if (isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return { block: false };
 
   return {
     block: true,
@@ -317,6 +424,15 @@ export function shouldBlockQueueExecution(
   toolName: string,
   input: string,
   queuePhaseActive: boolean,
+): { block: boolean; reason?: string } {
+  return shouldBlockQueueExecutionInSnapshot(currentWriteGateSnapshot(), toolName, input, queuePhaseActive);
+}
+
+export function shouldBlockQueueExecutionInSnapshot(
+  snapshot: WriteGateSnapshot,
+  toolName: string,
+  input: string,
+  queuePhaseActive: boolean = snapshot.activeQueuePhase,
 ): { block: boolean; reason?: string } {
   if (!queuePhaseActive) return { block: false };
 

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -194,6 +194,56 @@ function sortModelsForSelection(models: Model<any>[], currentModel: Model<any> |
   });
 }
 
+function buildProviderModelGroups(
+  models: Model<any>[],
+  currentModel: Model<any> | undefined,
+): Map<string, Model<any>[]> {
+  const byProvider = new Map<string, Model<any>[]>();
+
+  for (const model of sortModelsForSelection(models, currentModel)) {
+    let group = byProvider.get(model.provider);
+    if (!group) {
+      group = [];
+      byProvider.set(model.provider, group);
+    }
+    group.push(model);
+  }
+  return byProvider;
+}
+
+async function selectModelByProvider(
+  title: string,
+  models: Model<any>[],
+  ctx: ExtensionCommandContext,
+  currentModel: Model<any> | undefined,
+): Promise<Model<any> | undefined> {
+  const byProvider = buildProviderModelGroups(models, currentModel);
+  const providerOptions = Array.from(byProvider.entries()).map(([provider, group]) =>
+    `${provider} (${group.length} model${group.length === 1 ? "" : "s"})`,
+  );
+  providerOptions.push("(cancel)");
+
+  const providerChoice = await ctx.ui.select(`${title} — choose provider:`, providerOptions);
+  if (!providerChoice || typeof providerChoice !== "string" || providerChoice === "(cancel)") return undefined;
+
+  const providerName = providerChoice.replace(/ \(\d+ models?\)$/, "");
+  const providerModels = byProvider.get(providerName);
+  if (!providerModels || providerModels.length === 0) return undefined;
+
+  const optionToModel = new Map<string, Model<any>>();
+  const modelOptions = providerModels.map((model) => {
+    const isCurrent = currentModel && model.provider === currentModel.provider && model.id === currentModel.id;
+    const label = `${isCurrent ? "* " : ""}${model.id}`;
+    optionToModel.set(label, model);
+    return label;
+  });
+  modelOptions.push("(cancel)");
+
+  const modelChoice = await ctx.ui.select(`${title} — ${providerName}:`, modelOptions);
+  if (!modelChoice || typeof modelChoice !== "string" || modelChoice === "(cancel)") return undefined;
+  return optionToModel.get(modelChoice);
+}
+
 async function resolveRequestedModel(
   query: string,
   ctx: ExtensionCommandContext,
@@ -211,19 +261,7 @@ async function resolveRequestedModel(
 
   if (partialMatches.length === 1) return partialMatches[0];
   if (partialMatches.length === 0 || !ctx.hasUI) return undefined;
-
-  const sorted = sortModelsForSelection(partialMatches, ctx.model);
-  const optionToModel = new Map<string, Model<any>>();
-  const options = sorted.map((model) => {
-    const label = `${model.provider}/${model.id}`;
-    optionToModel.set(label, model);
-    return label;
-  });
-  options.push("(cancel)");
-
-  const choice = await ctx.ui.select(`Multiple models match "${query}" — choose one:`, options);
-  if (!choice || typeof choice !== "string" || choice === "(cancel)") return undefined;
-  return optionToModel.get(choice);
+  return selectModelByProvider(`Multiple models match "${query}"`, partialMatches, ctx, ctx.model);
 }
 
 async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi: ExtensionAPI | undefined): Promise<void> {
@@ -247,18 +285,7 @@ async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi
       return;
     }
 
-    const optionToModel = new Map<string, Model<any>>();
-    const options = sortModelsForSelection(availableModels, ctx.model).map((model) => {
-      const isCurrent = ctx.model && model.provider === ctx.model.provider && model.id === ctx.model.id;
-      const label = `${isCurrent ? "* " : ""}${model.provider}/${model.id}`;
-      optionToModel.set(label, model);
-      return label;
-    });
-    options.push("(cancel)");
-
-    const choice = await ctx.ui.select("Select session model:", options);
-    if (!choice || typeof choice !== "string" || choice === "(cancel)") return;
-    targetModel = optionToModel.get(choice);
+    targetModel = await selectModelByProvider("Select session model:", availableModels, ctx, ctx.model);
   } else {
     targetModel = await resolveRequestedModel(trimmed, ctx);
   }

package/src/resources/extensions/gsd/commands/index.ts

@@ -8,7 +8,13 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
     getArgumentCompletions: getGsdArgumentCompletions,
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const { handleGSDCommand } = await import("./dispatcher.js");
-      await handleGSDCommand(args, ctx, pi);
+      const { setStderrLoggingEnabled } = await import("../workflow-logger.js");
+      const previousStderrSetting = setStderrLoggingEnabled(false);
+      try {
+        await handleGSDCommand(args, ctx, pi);
+      } finally {
+        setStderrLoggingEnabled(previousStderrSetting);
+      }
     },
   });
 }

package/src/resources/extensions/gsd/guided-flow.ts

@@ -40,6 +40,10 @@ import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMiles
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
+import {
+  getWorkflowTransportSupportError,
+  getRequiredWorkflowToolsForGuidedUnit,
+} from "./workflow-mcp.js";
 import {
   runPreparation,
   formatCodebaseBrief,
@@ -318,6 +322,26 @@ async function dispatchWorkflow(
         routing: result.routing,
       });
     }
+
+    const compatibilityError = getWorkflowTransportSupportError(
+      result.appliedModel?.provider ?? ctx.model?.provider,
+      getRequiredWorkflowToolsForGuidedUnit(unitType),
+      {
+        projectRoot: process.cwd(),
+        surface: "guided flow",
+        unitType,
+        authMode: result.appliedModel?.provider
+          ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+          : ctx.model?.provider
+            ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+            : undefined,
+        baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+      },
+    );
+    if (compatibilityError) {
+      ctx.ui.notify(compatibilityError, "error");
+      return;
+    }
   }
 
   // Scope tools for discuss flows (#2949).

package/src/resources/extensions/gsd/init-wizard.ts

@@ -235,6 +235,20 @@ export async function showProjectInit(
   // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
   bootstrapGsdDirectory(basePath, prefs, signals);
 
+  // Initialize SQLite database so GSD starts in full-capability mode (#3880).
+  // Without this, isDbAvailable() returns false and GSD enters degraded
+  // markdown-only mode until a tool handler happens to call ensureDbOpen().
+  let dbReady = false;
+  try {
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    dbReady = await ensureDbOpen(basePath);
+  } catch {
+    // Swallowed — warning surfaced below
+  }
+  if (!dbReady) {
+    ctx.ui.notify("Warning: database initialization failed — GSD will run in degraded mode until the next /gsd invocation.", "warning");
+  }
+
   // Ensure .gitignore
   ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
@@ -250,6 +264,25 @@ export async function showProjectInit(
     // Non-fatal — codebase map generation failure should never block project init
   }
 
+  // Write initial STATE.md so it exists before the first /gsd invocation.
+  // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
+  // which would otherwise generate STATE.md at guided-flow.ts:1358.
+  let stateReady = false;
+  try {
+    const { deriveState } = await import("./state.js");
+    const { buildStateMarkdown } = await import("./doctor.js");
+    const { saveFile } = await import("./files.js");
+    const { resolveGsdRootFile } = await import("./paths.js");
+    const state = await deriveState(basePath);
+    await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
+    stateReady = true;
+  } catch {
+    // Swallowed — warning surfaced below
+  }
+  if (!stateReady) {
+    ctx.ui.notify("Warning: initial STATE.md generation failed — it will be created on the next /gsd invocation.", "warning");
+  }
+
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
 
   return { completed: true, bootstrapped: true };
@@ -433,6 +466,7 @@ function bootstrapGsdDirectory(
 
   const gsd = gsdRoot(basePath);
   mkdirSync(join(gsd, "milestones"), { recursive: true });
+  mkdirSync(join(gsd, "runtime"), { recursive: true });
 
   // Write PREFERENCES.md from wizard answers
   const preferencesContent = buildPreferencesFile(prefs);

package/src/resources/extensions/gsd/tests/core-overlay-fallback.test.ts

@@ -74,3 +74,104 @@ test("model command resolves and persists exact provider-qualified selection", a
   assert.deepEqual(applied, selectedModel);
   assert.match(notices[0]!.message, /openai\/gpt-5\.4/);
 });
+
+test("interactive model picker chooses provider first, then model", async () => {
+  const selectedModel = { provider: "openai", id: "gpt-5.4" };
+  let applied: typeof selectedModel | null = null;
+  const selects: Array<{ title: string; options: string[] }> = [];
+  const notices: Array<{ message: string; type?: string }> = [];
+
+  const ctx = {
+    hasUI: true,
+    model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+    modelRegistry: {
+      getAvailable: () => [
+        { provider: "openai", id: "gpt-5.4" },
+        { provider: "anthropic", id: "claude-opus-4-6" },
+        { provider: "openai", id: "gpt-5.3-mini" },
+        { provider: "anthropic", id: "claude-sonnet-4-6" },
+      ],
+    },
+    ui: {
+      select: async (title: string, options: string[]) => {
+        selects.push({ title, options });
+        return selects.length === 1 ? "openai (2 models)" : "gpt-5.4";
+      },
+      notify: (message: string, type?: string) => {
+        notices.push({ message, type });
+      },
+    },
+  } as any;
+
+  const pi = {
+    setModel: async (model: typeof selectedModel) => {
+      applied = model;
+      return true;
+    },
+  } as any;
+
+  const handled = await handleCoreCommand("model", ctx, pi);
+  assert.equal(handled, true);
+  assert.deepEqual(selects, [
+    {
+      title: "Select session model: — choose provider:",
+      options: ["anthropic (2 models)", "openai (2 models)", "(cancel)"],
+    },
+    {
+      title: "Select session model: — openai:",
+      options: ["gpt-5.3-mini", "gpt-5.4", "(cancel)"],
+    },
+  ]);
+  assert.deepEqual(applied, selectedModel);
+  assert.match(notices[0]!.message, /openai\/gpt-5\.4/);
+});
+
+test("ambiguous typed model selection chooses provider first, then model", async () => {
+  const selectedModel = { provider: "github-copilot", id: "gpt-5" };
+  let applied: typeof selectedModel | null = null;
+  const selects: Array<{ title: string; options: string[] }> = [];
+  const notices: Array<{ message: string; type?: string }> = [];
+
+  const ctx = {
+    hasUI: true,
+    model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+    modelRegistry: {
+      getAvailable: () => [
+        { provider: "openai", id: "gpt-5" },
+        { provider: "github-copilot", id: "gpt-5" },
+        { provider: "openai", id: "gpt-5-mini" },
+      ],
+    },
+    ui: {
+      select: async (title: string, options: string[]) => {
+        selects.push({ title, options });
+        return selects.length === 1 ? "github-copilot (1 model)" : "gpt-5";
+      },
+      notify: (message: string, type?: string) => {
+        notices.push({ message, type });
+      },
+    },
+  } as any;
+
+  const pi = {
+    setModel: async (model: typeof selectedModel) => {
+      applied = model;
+      return true;
+    },
+  } as any;
+
+  const handled = await handleCoreCommand("model gpt", ctx, pi);
+  assert.equal(handled, true);
+  assert.deepEqual(selects, [
+    {
+      title: "Multiple models match \"gpt\" — choose provider:",
+      options: ["github-copilot (1 model)", "openai (2 models)", "(cancel)"],
+    },
+    {
+      title: "Multiple models match \"gpt\" — github-copilot:",
+      options: ["gpt-5", "(cancel)"],
+    },
+  ]);
+  assert.deepEqual(applied, selectedModel);
+  assert.match(notices[0]!.message, /github-copilot\/gpt-5/);
+});

package/src/resources/extensions/gsd/tests/ensure-db-open.test.ts

@@ -77,6 +77,36 @@ describe('ensure-db-open', () => {
     }
   });
 
+  test('ensureDbOpen: explicit basePath opens target project without cwd override', async () => {
+    const tmpDir = makeTmpDir();
+    const gsdDir = path.join(tmpDir, '.gsd');
+    fs.mkdirSync(gsdDir, { recursive: true });
+    fs.writeFileSync(path.join(gsdDir, 'DECISIONS.md'), `# Decisions
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable |
+|---|------|-------|----------|--------|-----------|-----------|
+| D777 | M001 | architecture | Use explicit basePath | BasePath | Avoid cwd coupling | Yes |
+`);
+
+    try {
+      closeDatabase();
+    } catch { /* ok */ }
+
+    const originalCwd = process.cwd();
+    try {
+      const { ensureDbOpen } = await import('../bootstrap/dynamic-tools.ts');
+      const result = await ensureDbOpen(tmpDir);
+
+      assert.ok(result === true, 'ensureDbOpen should honor explicit basePath');
+      assert.equal(process.cwd(), originalCwd, 'ensureDbOpen should not mutate process.cwd');
+      assert.ok(isDbAvailable(), 'DB should be available after explicit open');
+      assert.ok(getDecisionById('D777') !== null, 'explicit basePath DB should be opened');
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // ensureDbOpen returns false when no .gsd/ exists
   // ═══════════════════════════════════════════════════════════════════════════
@@ -159,6 +189,42 @@ describe('ensure-db-open', () => {
     }
   });
 
+  test('ensureDbOpen: switches open database when basePath changes', async () => {
+    const firstDir = makeTmpDir();
+    const secondDir = makeTmpDir();
+    fs.mkdirSync(path.join(firstDir, '.gsd'), { recursive: true });
+    fs.mkdirSync(path.join(secondDir, '.gsd'), { recursive: true });
+    fs.writeFileSync(path.join(firstDir, '.gsd', 'DECISIONS.md'), `# Decisions
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable |
+|---|------|-------|----------|--------|-----------|-----------|
+| D101 | M001 | architecture | First DB | First | First rationale | Yes |
+`);
+    fs.writeFileSync(path.join(secondDir, '.gsd', 'DECISIONS.md'), `# Decisions
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable |
+|---|------|-------|----------|--------|-----------|-----------|
+| D202 | M001 | architecture | Second DB | Second | Second rationale | Yes |
+`);
+
+    try {
+      closeDatabase();
+    } catch { /* ok */ }
+
+    try {
+      const { ensureDbOpen } = await import('../bootstrap/dynamic-tools.ts');
+      assert.equal(await ensureDbOpen(firstDir), true);
+      assert.ok(getDecisionById('D101') !== null, 'first DB should be active');
+      assert.equal(await ensureDbOpen(secondDir), true);
+      assert.ok(getDecisionById('D202') !== null, 'second DB should be active after switch');
+      assert.equal(getDecisionById('D101'), null, 'first DB should no longer be active after switch');
+    } finally {
+      closeDatabase();
+      cleanupDir(firstDir);
+      cleanupDir(secondDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
 
 });