gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.9d08d820b

package/src/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
+- A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
+- You need current external information (library docs, API behavior) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

package/src/resources/extensions/gsd/tests/auto-session-encapsulation.test.ts

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AutoSession } from "../auto/session.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
@@ -32,6 +33,20 @@ function getRuntimeStateTsSource(): string {
   return readFileSync(RUNTIME_STATE_TS_PATH, "utf-8");
 }
 
+test("AutoSession.lockBasePath uses GSD_PROJECT_ROOT for symlink-resolved worktrees", () => {
+  const savedProjectRoot = process.env.GSD_PROJECT_ROOT;
+  process.env.GSD_PROJECT_ROOT = "/real/project";
+  try {
+    const session = new AutoSession();
+    session.basePath = "/Users/dev/.gsd/projects/abc123/worktrees/M001/slices/S01";
+
+    assert.equal(session.lockBasePath, "/real/project");
+  } finally {
+    if (savedProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+    else process.env.GSD_PROJECT_ROOT = savedProjectRoot;
+  }
+});
+
 // ── Invariant 1: No module-level mutable variables in auto.ts ────────────────
 
 test("auto.ts has no module-level let declarations", () => {

package/src/resources/extensions/gsd/tests/commands-extensions-version-compare.test.ts

@@ -0,0 +1,58 @@
+// GSD2 — Regression test for Issue #4946 isVersionGreater (commands-extensions.ts)
+//
+// Covers the inline npm-version comparator that replaced the `semver` import in
+// commands-extensions.ts. The original import broke `tsc -p tsconfig.json` whenever
+// `@types/semver` failed to install — the file is type-checked transitively despite
+// being under the `src/resources` exclude. The replacement keeps the same comparison
+// semantics for the realistic input space (npm extension version strings) without
+// pulling in the full semver type surface.
+
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { isVersionGreater } from "../commands-extensions.ts";
+
+describe("isVersionGreater — npm extension version comparison (#4946)", () => {
+	test("strictly greater patch beats lesser patch", () => {
+		assert.equal(isVersionGreater("1.2.4", "1.2.3"), true);
+		assert.equal(isVersionGreater("1.2.3", "1.2.4"), false);
+	});
+
+	test("equal versions are not strictly greater", () => {
+		assert.equal(isVersionGreater("1.2.3", "1.2.3"), false);
+	});
+
+	test("numeric (not lexicographic) component comparison", () => {
+		// Lexicographic compare would say "1.10.0" < "1.9.0".
+		assert.equal(isVersionGreater("1.10.0", "1.9.0"), true);
+		assert.equal(isVersionGreater("1.9.0", "1.10.0"), false);
+	});
+
+	test("major bump beats minor and patch differences", () => {
+		assert.equal(isVersionGreater("2.0.0", "1.99.99"), true);
+		assert.equal(isVersionGreater("1.99.99", "2.0.0"), false);
+	});
+
+	test("missing trailing components default to zero", () => {
+		assert.equal(isVersionGreater("1.2", "1.1.9"), true);
+		assert.equal(isVersionGreater("1", "0.9.9"), true);
+		assert.equal(isVersionGreater("1.2", "1.2.0"), false);
+	});
+
+	test("release version beats prerelease at the same release number", () => {
+		assert.equal(isVersionGreater("1.0.0", "1.0.0-beta.1"), true);
+		assert.equal(isVersionGreater("1.0.0-beta.1", "1.0.0"), false);
+	});
+
+	test("prerelease ordering: beta.2 > beta.1, rc.1 > beta.9", () => {
+		assert.equal(isVersionGreater("1.0.0-beta.2", "1.0.0-beta.1"), true);
+		assert.equal(isVersionGreater("1.0.0-rc.1", "1.0.0-beta.9"), true);
+	});
+
+	test("non-numeric junk in components doesn't crash — coerces to 0", () => {
+		// Defensive: we don't throw on garbage input; we treat unparseable
+		// components as 0. This matches the behaviour the extension installer
+		// can rely on without surfacing an error to the user.
+		assert.equal(isVersionGreater("1.x.0", "1.0.0"), false);
+		assert.equal(isVersionGreater("abc", "0.0.1"), false);
+	});
+});

package/src/resources/extensions/gsd/tests/home-dir.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Tests for getHomeDir() — cross-platform home directory resolution.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+
+describe("getHomeDir", () => {
+  let savedHome: string | undefined;
+  let savedUserProfile: string | undefined;
+  let getHomeDir: () => string;
+
+  beforeEach(async () => {
+    savedHome = process.env.HOME;
+    savedUserProfile = process.env.USERPROFILE;
+    const mod = await import("../home-dir.ts");
+    getHomeDir = mod.getHomeDir;
+  });
+
+  afterEach(() => {
+    if (savedHome !== undefined) {
+      process.env.HOME = savedHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (savedUserProfile !== undefined) {
+      process.env.USERPROFILE = savedUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+  });
+
+  it("returns HOME when set", () => {
+    process.env.HOME = "/test/home";
+    delete process.env.USERPROFILE;
+    assert.equal(getHomeDir(), "/test/home");
+  });
+
+  it("falls back to USERPROFILE when HOME is unset", () => {
+    delete process.env.HOME;
+    process.env.USERPROFILE = String.raw`C:\Users\test`;
+    assert.equal(getHomeDir(), String.raw`C:\Users\test`);
+  });
+
+  it("falls back to os.homedir() when both HOME and USERPROFILE are unset", () => {
+    delete process.env.HOME;
+    delete process.env.USERPROFILE;
+    assert.equal(getHomeDir(), homedir());
+  });
+});

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

@@ -7,7 +7,7 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -21,6 +21,7 @@ import {
   getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
   syncGsdStateToWorktree,
+  _resetAutoWorktreeOriginalBaseForTests,
 } from "../../auto-worktree.ts";
 
 // Note: execSync is used intentionally in tests for git operations with
@@ -142,6 +143,54 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("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-")));
+    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 {
+      const wtPath = createAutoWorktree(tempDir, "M001");
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+      assert.equal(existsSync(join(realWtPath, ".gsd", "worktrees", "M001")), false);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved 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");

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 { _resolveReportBasePath } from "../auto/phases.ts";
+import { _resolveDispatchGuardBasePath, _resolveReportBasePath } from "../auto/phases.ts";
 
 describe("_resolveReportBasePath", () => {
   test("uses originalBasePath when set (worktree scenario)", () => {
@@ -48,4 +48,21 @@ describe("_resolveReportBasePath", () => {
 
     assert.equal(_resolveReportBasePath(session), "/home/user/repo");
   });
+
+  test("uses GSD_PROJECT_ROOT for symlink-resolved worktree paths", () => {
+    const savedProjectRoot = process.env.GSD_PROJECT_ROOT;
+    process.env.GSD_PROJECT_ROOT = "/real/project";
+    try {
+      const session = {
+        originalBasePath: "",
+        basePath: "/Users/dev/.gsd/projects/abc123/worktrees/M001/slices/S01",
+      };
+
+      assert.equal(_resolveReportBasePath(session), "/real/project");
+      assert.equal(_resolveDispatchGuardBasePath(session), "/real/project");
+    } finally {
+      if (savedProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+      else process.env.GSD_PROJECT_ROOT = savedProjectRoot;
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/steer-worktree-path.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { appendOverride, loadActiveOverrides } from "../files.ts";
@@ -73,6 +73,22 @@ describe("steer worktree path resolution (#3476)", () => {
     assert.equal(result, null, "returns null for worktree without .git file");
   });
 
+  test("getAutoWorktreePath returns null when .git is a directory", () => {
+    mkdirSync(join(worktreePath, ".git"), { recursive: true });
+
+    const result = getAutoWorktreePath(projectRoot, "M001");
+
+    assert.equal(result, null, "returns null for standalone .git directories");
+  });
+
+  test("getAutoWorktreePath returns null when .git file is not a gitdir pointer", () => {
+    writeFileSync(join(worktreePath, ".git"), "not-a-gitdir\n", "utf-8");
+
+    const result = getAutoWorktreePath(projectRoot, "M001");
+
+    assert.equal(result, null, "returns null for invalid .git files");
+  });
+
   test("override routing: inactive worktree directory should not receive overrides", async () => {
     // Simulate the handleSteer path-resolution logic:
     // When no auto-mode is running, even if a worktree dir exists,

package/src/resources/extensions/gsd/tests/unit-context-manifest.test.ts

@@ -199,8 +199,8 @@ test("#4934: every manifest declares a tools policy", () => {
   }
 });
 
-test("#4934: tools.mode is one of the four declared policies", () => {
-  const validModes = new Set(["all", "read-only", "planning", "docs"]);
+test("#4934: tools.mode is one of the declared policies", () => {
+  const validModes = new Set(["all", "read-only", "planning", "planning-dispatch", "docs"]);
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const mode = (manifest as { tools: { mode: string } }).tools.mode;
     assert.ok(
@@ -219,7 +219,42 @@ test('#4934: only execute-task and reactive-execute may use tools.mode "all" (fu
         allowedAllUnits.has(unitType),
         `manifest "${unitType}" declares tools.mode = "all" but is not on the execute-track. ` +
         'Only execute-task and reactive-execute should have full source write access; ' +
-        'planning/discuss/research units must use "planning" (or "docs" for rewrite-docs).',
+        'planning/discuss/research units must use "planning" or "planning-dispatch" (or "docs" for rewrite-docs).',
+      );
+    }
+  }
+});
+
+test('planning-dispatch mode is reserved for slice-level decomposition and completion units', () => {
+  const allowedDispatchUnits = new Set([
+    "plan-slice",
+    "refine-slice",
+    "complete-slice",
+    "complete-milestone",
+  ]);
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const mode = (manifest as { tools: { mode: string } }).tools.mode;
+    if (mode === "planning-dispatch") {
+      assert.ok(
+        allowedDispatchUnits.has(unitType),
+        `manifest "${unitType}" declares tools.mode = "planning-dispatch" but is not on the dispatch-allowed allowlist. ` +
+        'planning-dispatch is intentionally narrow — extend the allowlist consciously when a new unit type genuinely benefits from subagent delegation.',
+      );
+    }
+  }
+});
+
+test('planning-dispatch manifests declare non-empty allowedSubagents lists', () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    if (manifest.tools.mode !== "planning-dispatch") continue;
+    assert.ok(
+      Array.isArray(manifest.tools.allowedSubagents) && manifest.tools.allowedSubagents.length > 0,
+      `manifest "${unitType}" has planning-dispatch policy but no allowedSubagents — explicit allowlist is required for runtime dispatch gating`,
+    );
+    for (const agent of manifest.tools.allowedSubagents) {
+      assert.ok(
+        typeof agent === "string" && agent.length > 0,
+        `manifest "${unitType}" has empty/invalid allowedSubagents entry: ${JSON.stringify(agent)}`,
       );
     }
   }

package/src/resources/extensions/gsd/tests/worktree-symlink-removal.test.ts

@@ -20,7 +20,7 @@ import {
   listWorktrees,
   worktreePath,
 } from "../worktree-manager.ts";
-import { describe, test } from 'node:test';
+import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
 
@@ -28,37 +28,41 @@ function run(command: string, cwd: string): string {
   return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
 }
 
-// Set up a test repo with .gsd/ as a symlink to an external directory,
-// mimicking the external state directory layout (~/.gsd/projects/<hash>/).
-// Resolve tmpdir to handle macOS /tmp -> /private/var/... symlink.
-const realTmp = realpathSync(tmpdir());
-const base = mkdtempSync(join(realTmp, "gsd-wt-symlink-test-"));
-const externalState = mkdtempSync(join(realTmp, "gsd-wt-symlink-ext-"));
-
-run("git init -b main", base);
-run('git config user.name "Test"', base);
-run('git config user.email "test@example.com"', base);
-
-// Create external state directory structure
-mkdirSync(join(externalState, "worktrees"), { recursive: true });
-
-// Create .gsd as a symlink to the external state directory
-symlinkSync(externalState, join(base, ".gsd"));
-
-// Verify the symlink is in place
-assert.ok(existsSync(join(base, ".gsd")), ".gsd symlink exists");
-assert.ok(
-  realpathSync(join(base, ".gsd")) === externalState,
-  ".gsd resolves to external state dir",
-);
+test('worktree-symlink-removal removes the git-registered symlink target safely', (t) => {
+  console.log("\n=== #1852: removeWorktree with symlinked .gsd/ ===");
 
-// Create initial commit so we have a valid repo
-writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
-run("git add .", base);
-run('git commit -m "init"', base);
+  // Set up a test repo with .gsd/ as a symlink to an external directory,
+  // mimicking the external state directory layout (~/.gsd/projects/<hash>/).
+  // Resolve tmpdir to handle macOS /tmp -> /private/var/... symlink.
+  const realTmp = realpathSync(tmpdir());
+  const base = mkdtempSync(join(realTmp, "gsd-wt-symlink-test-"));
+  const externalState = mkdtempSync(join(realTmp, "gsd-wt-symlink-ext-"));
+  t.after(() => {
+    rmSync(base, { recursive: true, force: true });
+    rmSync(externalState, { recursive: true, force: true });
+  });
+
+  run("git init -b main", base);
+  run('git config user.name "Test"', base);
+  run('git config user.email "test@example.com"', base);
+
+  // Create external state directory structure
+  mkdirSync(join(externalState, "worktrees"), { recursive: true });
+
+  // Create .gsd as a symlink to the external state directory
+  symlinkSync(externalState, join(base, ".gsd"));
+
+  // Verify the symlink is in place
+  assert.ok(existsSync(join(base, ".gsd")), ".gsd symlink exists");
+  assert.ok(
+    realpathSync(join(base, ".gsd")) === externalState,
+    ".gsd resolves to external state dir",
+  );
 
-describe('worktree-symlink-removal', async () => {
-  console.log("\n=== #1852: removeWorktree with symlinked .gsd/ ===");
+  // Create initial commit so we have a valid repo
+  writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+  run("git add .", base);
+  run('git commit -m "init"', base);
 
   // Create a worktree — git will resolve the symlink and register
   // the worktree at the external path
@@ -127,7 +131,4 @@ describe('worktree-symlink-removal', async () => {
   const listed = listWorktrees(base);
   assert.deepStrictEqual(listed.length, 0, "no worktrees listed after removal");
 
-  // Cleanup
-  rmSync(base, { recursive: true, force: true });
-  rmSync(externalState, { recursive: true, force: true });
 });

package/src/resources/extensions/gsd/tests/worktree.test.ts

@@ -255,6 +255,14 @@ describe('worktree', async () => {
     "returns unchanged for non-worktree path",
   );
 
+  const nestedRepoDir = join(base, "packages", "demo");
+  mkdirSync(nestedRepoDir, { recursive: true });
+  assert.deepStrictEqual(
+    normalizePath(resolveProjectRoot(nestedRepoDir)),
+    normalizePath(base),
+    "resolves normal repo subdirectories to the project root",
+  );
+
   // Without GSD_PROJECT_ROOT, direct layout with nested subdirs
   assert.deepStrictEqual(
     resolveProjectRoot("/data/.gsd/worktrees/M003/nested"),

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -9,12 +9,21 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join, sep } from 'node:path';
 
-import { shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
+import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
+import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
 import type { ToolsPolicy } from '../unit-context-manifest.ts';
 
 const BASE = join('/tmp', 'fake-project');
 const PLANNING: ToolsPolicy = { mode: 'planning' };
+const PLANNING_DISPATCH: ToolsPolicy = {
+  mode: 'planning-dispatch',
+  allowedSubagents: [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+};
+const PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
+  mode: 'planning-dispatch',
+  allowedSubagents: ['reviewer', 'security', 'tester'],
+};
 const READ_ONLY: ToolsPolicy = { mode: 'read-only' };
 const ALL: ToolsPolicy = { mode: 'all' };
 const DOCS: ToolsPolicy = {
@@ -143,6 +152,112 @@ test('planning-unit: blocks task tool (alt subagent name)', () => {
   assert.strictEqual(r.block, true);
 });
 
+test('planning-dispatch: allows subagent dispatch (delegated recon/planner during slice planning)', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['scout']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: allows task dispatch (delegated recon/planner during slice planning)', () => {
+  const r = shouldBlockPlanningUnit('task', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['planner']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: extracts subagent classes from single, parallel, and chain inputs', () => {
+  assert.deepEqual(extractSubagentAgentClasses({ agent: ' scout ' }), ['scout']);
+  assert.deepEqual(
+    extractSubagentAgentClasses({ tasks: [{ agent: 'planner' }, { agent: ' tester ' }] }),
+    ['planner', 'tester'],
+  );
+  assert.deepEqual(
+    extractSubagentAgentClasses({ chain: [{ agent: 'reviewer' }, { agent: 'security' }] }),
+    ['reviewer', 'security'],
+  );
+});
+
+test('planning-dispatch: blocks subagent dispatch when agentClasses is undefined (stale caller shim)', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, undefined);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /stale caller/);
+  assert.match(r.reason!, /tools-policy "planning-dispatch"/);
+});
+
+test('planning-dispatch: allows explicitly empty agent classes for downstream validation', () => {
+  const emptyClasses = extractSubagentAgentClasses({});
+  assert.deepEqual(emptyClasses, []);
+  const empty = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, emptyClasses);
+  assert.strictEqual(empty.block, false);
+});
+
+test('planning-dispatch: allows all globally allowed specialists when listed by policy', () => {
+  const policy: ToolsPolicy = {
+    mode: 'planning-dispatch',
+    allowedSubagents: [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+  };
+  const r = shouldBlockPlanningUnit(
+    'subagent',
+    '',
+    BASE,
+    'complete-milestone',
+    policy,
+    [...ALLOWED_PLANNING_DISPATCH_AGENTS],
+  );
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: blocks implementation-tier agent', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['worker']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"worker"/);
+  assert.match(r.reason!, /read-only specialists/);
+});
+
+test('planning-dispatch: blocks globally disallowed agent even if listed by policy', () => {
+  const policy: ToolsPolicy = {
+    mode: 'planning-dispatch',
+    allowedSubagents: ['refactorer'],
+  };
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'refine-slice', policy, ['refactorer']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"refactorer"/);
+  assert.match(r.reason!, /read-only specialists/);
+  assert.doesNotMatch(r.reason!, /ToolsPolicy\.allowedSubagents|permitted agents for this unit/);
+});
+
+test('planning-dispatch: blocks mixed batch containing a disallowed agent', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['scout', 'worker']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"worker"/);
+});
+
+test('planning-dispatch: allows review-tier agent under closeout policy', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'complete-slice', PLANNING_DISPATCH_REVIEW, ['reviewer']);
+  assert.strictEqual(r.block, false);
+});
+
+test('planning-dispatch: blocks recon agent under closeout policy', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'complete-slice', PLANNING_DISPATCH_REVIEW, ['scout']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"scout"/);
+  assert.match(r.reason!, /ToolsPolicy\.allowedSubagents|permitted agents for this unit/);
+  assert.doesNotMatch(r.reason!, /read-only specialists/);
+});
+
+test('planning-dispatch: still blocks writes to user source (write isolation preserved)', () => {
+  const r = shouldBlockPlanningUnit('write', join(BASE, 'src', 'main.ts'), BASE, 'plan-slice', PLANNING_DISPATCH);
+  assert.strictEqual(r.block, true);
+});
+
+test('planning-dispatch: still allows writes inside .gsd/', () => {
+  const r = shouldBlockPlanningUnit(
+    'write',
+    join(BASE, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'PLAN.md'),
+    BASE,
+    'plan-slice',
+    PLANNING_DISPATCH,
+  );
+  assert.strictEqual(r.block, false);
+});
+
 // ─── planning mode: pass-through tools ────────────────────────────────────
 
 test('planning-unit: allows read tool', () => {