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

package/src/resources/extensions/gsd/tests/mcp-readiness-preflight.test.ts

@@ -0,0 +1,205 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the MCP readiness preflight gate in dispatchWorkflow.
+
+import { describe, test, mock } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { _awaitWorkflowMcpReadinessForTest as awaitWorkflowMcpReadiness } from "../guided-flow.ts";
+import { clearMcpConfigCache } from "../../mcp-client/manager.ts";
+import { clearWorkflowMcpProbeCache } from "../workflow-mcp-readiness-cache.ts";
+
+function makeCtx(opts: { authMode?: string; baseUrl?: string; systemPrompt?: string } = {}) {
+  const { authMode = "externalCli", baseUrl = "local://pipe", systemPrompt = "" } = opts;
+  return {
+    model: { provider: "anthropic", baseUrl },
+    modelRegistry: {
+      getProviderAuthMode: mock.fn(() => authMode),
+    },
+    getSystemPrompt: mock.fn(() => systemPrompt),
+    ui: {
+      setStatus: mock.fn(),
+      notify: mock.fn(),
+    },
+  } as any;
+}
+
+function makePi(tools: string[] | (() => string[])) {
+  const getTools = typeof tools === "function" ? tools : () => tools;
+  return {
+    getActiveTools: getTools,
+    getAllTools: () => getTools().map((name: string) => ({ name })),
+  } as any;
+}
+
+describe("awaitWorkflowMcpReadiness", () => {
+  test("returns null (ready) when not using MCP transport", async () => {
+    clearWorkflowMcpProbeCache();
+    const ctx = makeCtx({ authMode: "native", baseUrl: "https://api.anthropic.com" });
+    const pi = makePi([]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when provider has no auth mode", async () => {
+    const ctx = {
+      model: undefined,
+      modelRegistry: { getProviderAuthMode: mock.fn(() => undefined) },
+      ui: { setStatus: mock.fn(), notify: mock.fn() },
+    } as any;
+    const pi = makePi([]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when MCP tools are already registered", async () => {
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash", "mcp__gsd-workflow__ask_user_questions", "mcp__gsd-workflow__gsd_plan_slice"]);
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+  });
+
+  test("returns null (ready) when host system prompt advertises workflow MCP tools", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx({
+      systemPrompt: "Available tools: read, bash, mcp__gsd-workflow__ask_user_questions",
+    });
+    const pi = makePi(["read", "bash"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("treats a successful direct probe as readiness when session tools are absent", async () => {
+    const previousGsdHome = process.env.GSD_HOME;
+    const projectDir = mkdtempSync(join(tmpdir(), "gsd-guided-mcp-probe-project-"));
+    const gsdHomeDir = mkdtempSync(join(tmpdir(), "gsd-guided-mcp-probe-home-"));
+    try {
+      process.env.GSD_HOME = gsdHomeDir;
+      mkdirSync(join(projectDir, ".gsd"), { recursive: true });
+
+      const require = createRequire(import.meta.url);
+      const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+      const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+      const serverPath = join(projectDir, "fake-workflow-mcp-server.mjs");
+      writeFileSync(
+        serverPath,
+        [
+          `const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+          `const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+          'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+          'server.tool("gsd_status", "Probe-visible workflow tool", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+          'await server.connect(new StdioServerTransport());',
+        ].join("\n"),
+        "utf-8",
+      );
+      writeFileSync(
+        join(projectDir, ".mcp.json"),
+        JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+        "utf-8",
+      );
+
+      const ctx = makeCtx();
+      const pi = makePi(["read", "bash"]);
+
+      assert.equal(
+        await awaitWorkflowMcpReadiness(pi, ctx, projectDir, { timeoutMs: 15_000, pollMs: 100 }),
+        null,
+      );
+    } finally {
+      if (previousGsdHome === undefined) {
+        delete process.env.GSD_HOME;
+      } else {
+        process.env.GSD_HOME = previousGsdHome;
+      }
+      rmSync(projectDir, { recursive: true, force: true });
+      rmSync(gsdHomeDir, { recursive: true, force: true });
+      clearMcpConfigCache();
+    }
+  });
+
+  test("returns server and probe error when workflow MCP never becomes ready", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      const failure = await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path", {
+        timeoutMs: 5,
+        pollMs: 1,
+        probe: async () => ({
+          ok: false,
+          tools: [],
+          serverName: "gsd-workflow",
+          error: "connection refused",
+        }),
+      });
+      assert.deepEqual(failure, { server: "gsd-workflow", error: "connection refused" });
+      assert.ok(ctx.ui.setStatus.mock.calls.length >= 2);
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("returns null (ready) when MCP tools appear during polling", async () => {
+    const ctx = makeCtx();
+    let callCount = 0;
+    const pi = makePi(() => {
+      callCount++;
+      if (callCount >= 3) return ["mcp__gsd-workflow__gsd_plan_slice"];
+      return ["read", "bash"];
+    });
+    assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path"), null);
+    assert.ok(callCount >= 3, `expected at least 3 tool-check calls, got ${callCount}`);
+    assert.ok(ctx.ui.setStatus.mock.calls.length >= 2);
+  });
+
+  test("requires the active unit's workflow tools, not just any MCP workflow tool", async () => {
+    const originalCommand = process.env.GSD_WORKFLOW_MCP_COMMAND;
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash", "mcp__gsd-workflow__gsd_slice_complete"]);
+    try {
+      process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+      const failure = await awaitWorkflowMcpReadiness(pi, ctx, "/fake/path", {
+        unitType: "complete-slice",
+        timeoutMs: 5,
+        pollMs: 1,
+        probe: async () => ({
+          ok: true,
+          tools: ["gsd_slice_complete"],
+          serverName: "gsd-workflow",
+        }),
+      });
+
+      assert.deepEqual(failure, { server: "gsd-workflow" });
+    } finally {
+      if (originalCommand === undefined) {
+        delete process.env.GSD_WORKFLOW_MCP_COMMAND;
+      } else {
+        process.env.GSD_WORKFLOW_MCP_COMMAND = originalCommand;
+      }
+    }
+  });
+
+  test("returns null when no launch config is discoverable", async () => {
+    const ctx = makeCtx();
+    const pi = makePi(["read", "bash"]);
+    const launch = (await import("../workflow-mcp.js")).detectWorkflowMcpLaunchConfig(process.cwd());
+    if (!launch) {
+      assert.equal(await awaitWorkflowMcpReadiness(pi, ctx, process.cwd()), null);
+    }
+    // When launch config IS found, the function would timeout (15s) — skip that path in tests.
+  });
+});

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

@@ -58,13 +58,14 @@ describe("formatMcpStatusReport", () => {
     assert.match(result, /disabled/i);
   });
 
-  test("shows available state for servers that pass a status probe", () => {
+  test("labels probe-only availability separately from live connections", () => {
     const servers: McpServerStatus[] = [
       { name: "gsd-workflow", transport: "stdio", connected: false, available: true, toolCount: 62, error: undefined },
     ];
     const result = formatMcpStatusReport(servers);
     assert.match(result, /gsd-workflow/);
-    assert.match(result, /available — 62 tools/);
+    assert.match(result, /probe available — 62 tools/);
+    assert.doesNotMatch(result, /connected — 62 tools/);
     assert.doesNotMatch(result, /disconnected/);
   });
 
@@ -132,7 +133,7 @@ describe("formatMcpServerDetail", () => {
     assert.match(result, /disconnected/i);
   });
 
-  test("shows available status with tool names", () => {
+  test("shows probe-available status with tool names", () => {
     const result = formatMcpServerDetail({
       name: "gsd-workflow",
       transport: "stdio",
@@ -142,7 +143,7 @@ describe("formatMcpServerDetail", () => {
       tools: ["gsd_milestone_status"],
       error: undefined,
     });
-    assert.match(result, /available/i);
+    assert.match(result, /probe available/i);
     assert.match(result, /gsd_milestone_status/);
   });
 
@@ -206,7 +207,7 @@ describe("handleMcpStatus", () => {
       await handleMcpStatus("status", ctx as unknown as ExtensionCommandContext);
 
       assert.match(message, /gsd-workflow/);
-      assert.match(message, /available — 1 tools/);
+      assert.match(message, /probe available — 1 tools/);
       assert.doesNotMatch(message, /disconnected/);
     } finally {
       process.chdir(originalCwd);

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/milestone-merge-stash-restore.test.ts

@@ -4,7 +4,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { _runMilestoneMergeWithStashRestore } from "../auto/phases.js";
+import { _runMilestoneMergeWithStashRestore } from "../auto/closeout.js";
 import type { IterationContext } from "../auto/types.js";
 import { MergeConflictError } from "../git-service.js";
 import type {

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

@@ -10,7 +10,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { _resolveDispatchGuardBasePath, _resolveReportBasePath } from "../auto/phases.ts";
+import { _resolveDispatchGuardBasePath, _resolveReportBasePath } from "../auto/phase-helpers.ts";
 
 describe("_resolveReportBasePath", () => {
   test("uses originalBasePath when set (worktree scenario)", () => {

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

@@ -0,0 +1,92 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for milestone closeout settlement guidance.
+
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { evaluateAllCompleteSettlement } from "../milestone-settlement.ts";
+import { resolveExpectedArtifactPath } from "../auto-artifact-paths.ts";
+import {
+  closeDatabase,
+  insertAssessment,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
+
+let base = "";
+
+function runGit(cwd: string, args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function initRepo(root: string): void {
+  runGit(root, ["init", "-b", "main"]);
+  runGit(root, ["config", "user.email", "test@example.com"]);
+  runGit(root, ["config", "user.name", "Test User"]);
+  writeFileSync(join(root, "README.md"), "# fixture\n");
+  runGit(root, ["add", "."]);
+  runGit(root, ["commit", "-m", "chore: init"]);
+}
+
+function seedClosedMilestone(root: string, worktree: string): void {
+  mkdirSync(join(root, ".gsd"), { recursive: true });
+  openDatabase(join(root, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice One", status: "complete" });
+  insertTask({
+    id: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    title: "Task One",
+    status: "complete",
+    verificationResult: "passed",
+  });
+  insertAssessment({
+    path: ".gsd/milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass\n",
+  });
+
+  mkdirSync(join(worktree, ".gsd", "milestones", "M001"), { recursive: true });
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", "M001", worktree);
+  assert.ok(summaryPath, "complete-milestone summary path should resolve");
+  mkdirSync(dirname(summaryPath), { recursive: true });
+  writeFileSync(summaryPath, "# Milestone One\n\nComplete.\n");
+}
+
+afterEach(() => {
+  try { closeDatabase(); } catch { /* ignore */ }
+  if (base) rmSync(base, { recursive: true, force: true });
+  base = "";
+});
+
+test("merge-pending settlement routes back to complete-milestone dispatch without manual merge guidance", () => {
+  base = mkdtempSync(join(tmpdir(), "gsd-milestone-settlement-"));
+  initRepo(base);
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  mkdirSync(dirname(worktree), { recursive: true });
+  runGit(base, ["worktree", "add", "-b", "milestone/M001", worktree, "HEAD"]);
+  seedClosedMilestone(base, worktree);
+
+  const result = evaluateAllCompleteSettlement({
+    milestoneId: "M001",
+    statePhase: "complete",
+    basePath: worktree,
+    originalBasePath: base,
+    milestoneMerged: false,
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, "merge-pending");
+  assert.equal(result.nextAction, "Retry `/gsd dispatch complete-milestone M001`.");
+  assert.doesNotMatch(result.message, /merge manually/i);
+  assert.doesNotMatch(result.nextAction, /merge manually/i);
+});

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

@@ -14,7 +14,7 @@ import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { AutoSession } from "../auto/session.ts";
-import { runPreDispatch } from "../auto/phases.ts";
+import { runPreDispatch } from "../auto/pre-dispatch.ts";
 
 test("milestone transition archives completed units and rebuilds state", async () => {
   const tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-cu-reset-")));

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/notifications.test.ts

@@ -1,7 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { playQuestionBell } from "../../ask-user-questions.js";
+import { stopAuto } from "../auto.js";
+import { autoSession } from "../auto-runtime-state.js";
 import {
   buildDesktopNotificationCommand,
   shouldSendDesktopNotification,
@@ -58,18 +63,68 @@ test("playNotificationBell is silent when disabled", () => {
   assert.equal(output, "");
 });
 
-test("ask_user_questions plays local bell before waiting for an answer", () => {
-  const source = readFileSync(new URL("../../ask-user-questions.ts", import.meta.url), "utf-8");
+test("playQuestionBell writes a terminal bell when local bell is enabled", async () => {
+  let output = "";
+  const stream = { write: (chunk: string) => { output += chunk; } };
 
-  assert.match(source, /playNotificationBell\("question"\)/);
-  assert.match(source, /await playQuestionBell\(\)/);
+  await playQuestionBell({ enabled: true, local_bell: true }, stream);
+
+  assert.equal(output, "\u0007");
 });
 
-test("stopAuto plays local bell for auto-mode stop notifications", () => {
-  const source = readFileSync(new URL("../auto.ts", import.meta.url), "utf-8");
+test("playQuestionBell is silent when local bell is disabled", async () => {
+  let output = "";
+  const stream = { write: (chunk: string) => { output += chunk; } };
 
-  assert.match(source, /import \{[^}]*playNotificationBell[^}]*\} from "\.\/notifications\.js"/);
-  assert.match(source, /playNotificationBell\("stop", loadedPreferences\?\.notifications\)/);
+  await playQuestionBell({ enabled: true, local_bell: false }, stream);
+
+  assert.equal(output, "");
+});
+
+test("stopAuto plays local bell for auto-mode stop notifications", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-stop-bell-"));
+  const previousCwd = process.cwd();
+  const previousStderrWrite = process.stderr.write;
+  const previousStderrIsTTY = process.stderr.isTTY;
+  let bellOutput = "";
+
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.basePath = base;
+
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "PREFERENCES.md"),
+    "---\nnotifications:\n  enabled: true\n  local_bell: true\n---\n",
+    "utf-8",
+  );
+
+  process.stderr.isTTY = true;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    if (typeof chunk === "string") {
+      bellOutput += chunk;
+    }
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    await stopAuto(
+      { hasUI: false, ui: { notify: () => {}, setStatus: () => {}, setWidget: () => {}, setHeader: () => {} } } as any,
+      undefined,
+      "test stop",
+    );
+
+    assert.ok(
+      bellOutput.includes("\u0007"),
+      "stopAuto must write a terminal bell to stderr when the local bell preference is enabled",
+    );
+  } finally {
+    process.stderr.write = previousStderrWrite;
+    process.stderr.isTTY = previousStderrIsTTY;
+    autoSession.reset();
+    process.chdir(previousCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
 });
 
 test("buildDesktopNotificationCommand falls back to osascript on macOS when terminal-notifier is absent", () => {