@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tests/integration/auto-worktree.test.ts

@@ -11,6 +11,11 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
+import {
+  commitAll,
+  createGsdIntegrationProject,
+  writeGsdMilestoneContext,
+} from "./gsd-integration-fixture.ts";
 
 import {
   createAutoWorktree,
@@ -32,17 +37,12 @@ function run(command: string, cwd: string): string {
 }
 
 function createTempRepo(): string {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-test-")));
-  run("git init", dir);
-  run("git config user.email test@test.com", dir);
-  run("git config user.name Test", dir);
-  // Create initial commit on main
-  writeFileSync(join(dir, "README.md"), "# test\n");
-  run("git add .", dir);
-  run("git commit -m init", dir);
-  // Ensure branch is called main
-  run("git branch -M main", dir);
-  return dir;
+  return createGsdIntegrationProject("auto-wt-test-").root;
+}
+
+function commitMilestoneContext(repo: string, milestoneId: string): void {
+  writeGsdMilestoneContext(repo, milestoneId);
+  commitAll(repo, "add milestone");
 }
 
 describe("auto-worktree lifecycle", () => {
@@ -59,13 +59,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("create → detect → teardown", () => {
     tempDir = createTempRepo();
-
-    // Create .gsd/milestones/M003 with a dummy file (simulates planning artifacts)
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // ─── createAutoWorktree ──────────────────────────────────────────
     const wtPath = createAutoWorktree(tempDir, "M003");
@@ -112,11 +106,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("re-entry: create again, exit without teardown, re-enter", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     const wtPath2 = createAutoWorktree(tempDir, "M003");
     assert.ok(existsSync(wtPath2), "worktree re-created");
@@ -144,6 +134,21 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("isInAutoWorktree returns false when ambient cwd was deleted", (t) => {
+    const cwd = t.mock.method(process, "cwd", () => {
+      const err = new Error("process.cwd failed") as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      err.syscall = "uv_cwd";
+      throw err;
+    });
+
+    try {
+      assert.equal(isInAutoWorktree("/repo"), false);
+    } finally {
+      cwd.mock.restore();
+    }
+  });
+
   test("symlink-resolved auto worktree is detected after module state reset", () => {
     tempDir = createTempRepo();
     const savedGsdHome = process.env.GSD_HOME;
@@ -157,7 +162,7 @@ describe("auto-worktree lifecycle", () => {
     try {
       const wtPath = createAutoWorktree(tempDir, "M001");
       const realWtPath = realpathSync(wtPath);
-      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+      assert.equal(realWtPath, join(tempDir, ".gsd-worktrees", "M001"), "worktree uses canonical path under project root, not through the .gsd symlink");
 
       _resetAutoWorktreeOriginalBaseForTests();
       process.chdir(realWtPath);
@@ -192,13 +197,62 @@ describe("auto-worktree lifecycle", () => {
     }
   });
 
+  test("legacy symlink-resolved auto worktree is detected after module state reset", () => {
+    tempDir = createTempRepo();
+    const savedGsdHome = process.env.GSD_HOME;
+    const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-home-legacy-")));
+    const storage = join(fakeHome, ".gsd", "projects", "abc123def456");
+    mkdirSync(join(storage, "milestones", "M001"), { recursive: true });
+    writeFileSync(join(storage, "milestones", "M001", "CONTEXT.md"), "# M001\n");
+    symlinkSync(storage, join(tempDir, ".gsd"));
+    process.env.GSD_HOME = join(fakeHome, ".gsd");
+
+    try {
+      // Worktrees created by older versions live at .gsd/worktrees/<MID>;
+      // git resolves the symlink and registers them under external state.
+      // Detection must keep working for them — canonical .gsd-worktrees/
+      // creation never crosses the symlink, so create the legacy worktree
+      // explicitly.
+      const wtPath = join(tempDir, ".gsd", "worktrees", "M001");
+      run(`git worktree add -b milestone/M001 "${wtPath}"`, tempDir);
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(realWtPath);
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing legacy worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(realWtPath);
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved legacy worktree cwd",
+      );
+    } finally {
+      process.chdir(tempDir);
+      try {
+        teardownAutoWorktree(tempDir, "M001");
+      } catch {
+        // Best-effort cleanup for partially-created temp worktrees.
+      }
+      if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = savedGsdHome;
+      rmSync(fakeHome, { recursive: true, force: true });
+    }
+  });
+
   test("coexistence with manual worktree", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Import createWorktree directly for manual worktree
     const { createWorktree } = await import("../../worktree-manager.ts");
@@ -221,11 +275,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("split-brain prevention: originalBase cleared after teardown", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     createAutoWorktree(tempDir, "M003");
     teardownAutoWorktree(tempDir, "M003");
@@ -235,11 +285,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#1526: getMainBranch returns milestone/<MID> in auto-worktree", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M005");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M005 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M005");
 
     const { GitServiceImpl } = await import("../../git-service.ts");
 
@@ -259,11 +305,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#1713: stale worktree directory without .git file", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M010");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M010 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M010");
 
     // Simulate a crash leaving a stale directory with no .git file.
     const { worktreePath } = await import("../../worktree-manager.ts");
@@ -284,11 +326,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#778: re-attach does not reconcile plan checkboxes into a worktree-local .gsd projection", async () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     const planRelPath = join(".gsd", "milestones", "M004", "slices", "S01", "S01-PLAN.md");
     const planDir = join(tempDir, ".gsd", "milestones", "M004", "slices", "S01");
@@ -348,11 +386,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#2791: mcp.json is not copied into worktree on creation after copyPlanningArtifacts removal", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Create mcp.json in .gsd/ AFTER the commit (untracked, like real usage).
     // Phase C removed copyPlanningArtifacts, so creation should not seed a
@@ -377,11 +411,7 @@ describe("auto-worktree lifecycle", () => {
 
   test("#2791: mcp.json synced via syncGsdStateToWorktree (ROOT_STATE_FILES)", () => {
     tempDir = createTempRepo();
-    const msDir = join(tempDir, ".gsd", "milestones", "M003");
-    mkdirSync(msDir, { recursive: true });
-    writeFileSync(join(msDir, "CONTEXT.md"), "# M003 Context\n");
-    run("git add .", tempDir);
-    run("git commit -m \"add milestone\"", tempDir);
+    commitMilestoneContext(tempDir, "M003");
 
     // Create worktree first (no mcp.json yet)
     const wtPath = createAutoWorktree(tempDir, "M003");

package/src/resources/extensions/gsd/tests/integration/doctor-environment-async.test.ts

@@ -0,0 +1,104 @@
+// Project/App: gsd-pi
+// File Purpose: Verify the non-blocking runEnvironmentChecksAsync is behaviourally
+// identical to the synchronous runEnvironmentChecks (the health-widget render
+// path was moved onto the async variant for performance), and that the single-
+// scan checkPortConflicts still detects a real in-use port.
+
+import test, { type TestContext } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { createServer } from "node:net";
+
+import {
+  runEnvironmentChecks,
+  runEnvironmentChecksAsync,
+  type EnvironmentCheckResult,
+} from "../../doctor-environment.ts";
+
+function makeProject(t: TestContext, files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-env-async-"));
+  t.after(() => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+  for (const [name, content] of Object.entries(files)) {
+    const filePath = join(dir, name);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+  }
+  return dir;
+}
+
+// Stable, order-independent signature of a check-result set for comparison.
+function normalize(results: EnvironmentCheckResult[]): string[] {
+  return results.map((r) => `${r.name}|${r.status}|${r.message}|${r.detail ?? ""}`).sort();
+}
+
+test("runEnvironmentChecksAsync returns the same results as runEnvironmentChecks", async (t) => {
+  const dir = makeProject(t, {
+    "package.json": JSON.stringify({
+      name: "fixture",
+      engines: { node: ">=18" },
+      scripts: { dev: "vite --port 4321", build: "tsc" },
+      devDependencies: { typescript: "^5.0.0" },
+    }),
+    ".env.example": "API_KEY=\n",
+    Dockerfile: "FROM node:20\n",
+  });
+  mkdirSync(join(dir, "node_modules"), { recursive: true });
+
+  const sync = runEnvironmentChecks(dir);
+  const asyncResults = await runEnvironmentChecksAsync(dir);
+
+  assert.deepEqual(
+    normalize(asyncResults),
+    normalize(sync),
+    "async checks must produce the identical result set as the sync checks",
+  );
+  // Sanity: the fixture is rich enough that the suite actually produced checks.
+  assert.ok(sync.length > 0, "expected the fixture to yield environment checks");
+});
+
+test("runEnvironmentChecksAsync matches sync on a bare directory (no package.json)", async (t) => {
+  const dir = makeProject(t, {});
+  const sync = runEnvironmentChecks(dir);
+  const asyncResults = await runEnvironmentChecksAsync(dir);
+  assert.deepEqual(normalize(asyncResults), normalize(sync));
+});
+
+test(
+  "single-scan port check detects a real in-use port, identically sync and async",
+  { skip: process.platform === "win32" ? "lsof-based port check is macOS/Linux only" : false },
+  async (t) => {
+    // Bind a real listener, then reference its port from package.json scripts so
+    // collectPortsToCheck picks it up. The server stays up across both check runs.
+    const server = createServer();
+    const port = await new Promise<number>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address();
+        resolve(typeof addr === "object" && addr ? addr.port : 0);
+      });
+    });
+    t.after(() => new Promise<void>((resolve) => server.close(() => resolve())));
+    assert.ok(port >= 1024 && port <= 65535, "ephemeral port should be in the checked range");
+
+    const dir = makeProject(t, {
+      "package.json": JSON.stringify({ name: "fixture", scripts: { dev: `serve --port ${port}` } }),
+    });
+
+    const syncConflicts = runEnvironmentChecks(dir).filter((r) => r.name === "port_conflict");
+    const asyncConflicts = (await runEnvironmentChecksAsync(dir)).filter((r) => r.name === "port_conflict");
+
+    // Equivalence holds regardless of whether lsof is present on the runner.
+    assert.deepEqual(normalize(asyncConflicts), normalize(syncConflicts), "sync and async must agree on port conflicts");
+    // On macOS/Linux lsof is standard, so the listener must be reported and named.
+    assert.equal(syncConflicts.length, 1, "expected exactly one port conflict for the in-use port");
+    assert.match(syncConflicts[0]!.message, new RegExp(`\\b${port}\\b`), "conflict message must name the in-use port");
+  },
+);

package/src/resources/extensions/gsd/tests/integration/git-service.test.ts

@@ -293,11 +293,12 @@ describe('git-service', async () => {
 
   assert.deepStrictEqual(
     RUNTIME_EXCLUSION_PATHS.length,
-    16,
-    "exactly 16 runtime exclusion paths"
+    17,
+    "exactly 17 runtime exclusion paths"
   );
 
   const expectedPaths = [
+    ".gsd-worktrees/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",

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

@@ -317,6 +317,24 @@ test('(k2) run-uat prompt references gsd_uat_result_save, not direct write', ()
   );
 });
 
+test('(k3) run-uat prompt warns that .gsd glob misses can be symlink traversal artifacts', async () => {
+  const base = createFixtureBase();
+  try {
+    const uatRel = '.gsd/milestones/M001/slices/S01/S01-UAT.md';
+    const uatContent = makeUatContent('runtime-executable');
+    writeSliceFile(base, 'M001', 'S01', 'UAT', uatContent);
+
+    const prompt = await buildRunUatPrompt('M001', 'S01', uatRel, uatContent, base);
+
+    assert.match(prompt, /\.gsd\/\*\*/);
+    assert.match(prompt, /symlink-backed/i);
+    assert.match(prompt, /do not infer that the GSD harness is missing/i);
+    assert.match(prompt, /use the preloaded UAT context/i);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('(l) dispatch preconditions via resolveSliceFile', () => {
     const base = createFixtureBase();
     const uatContent = makeUatContent('artifact-driven');
@@ -731,6 +749,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 +835,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);
+    }
+});
 });