gsd-pi 2.82.0-dev.ed17d078d → 3.0.0

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

@@ -7,13 +7,17 @@ import {
   ARTIFACT_KEYS,
   KNOWN_UNIT_TYPES,
   UNIT_MANIFESTS,
+  resolveSubagentPermissionContract,
   resolveManifest,
   type ArtifactKey,
   type ContextModePolicy,
   type SkillsPolicy,
   type UnitContextManifest,
 } from "../unit-context-manifest.ts";
-import { ALLOWED_PLANNING_DISPATCH_AGENTS } from "../bootstrap/write-gate.ts";
+import {
+  ALLOWED_PLANNING_DISPATCH_AGENTS,
+  shouldBlockPlanningUnit,
+} from "../bootstrap/write-gate.ts";
 import {
   getRequiredWorkflowToolsForAutoUnit,
   getRequiredWorkflowToolsForGuidedUnit,
@@ -216,7 +220,7 @@ test("#4934: every manifest declares a tools policy", () => {
 });
 
 test("#4934: tools.mode is one of the declared policies", () => {
-  const validModes = new Set(["all", "read-only", "planning", "planning-dispatch", "docs"]);
+  const validModes = new Set(["all", "read-only", "planning", "planning-dispatch", "docs", "verification"]);
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const mode = (manifest as { tools: { mode: string } }).tools.mode;
     assert.ok(
@@ -226,27 +230,101 @@ test("#4934: tools.mode is one of the declared policies", () => {
   }
 });
 
-test('#4934: only execute-task and reactive-execute may use tools.mode "all" (full source-tree write access)', () => {
-  const allowedAllUnits = new Set(["execute-task", "reactive-execute"]);
+test('#4934: only execution units and complete-milestone may use tools.mode "all"', () => {
+  const allowedAllUnits = new Set(["execute-task", "reactive-execute", "complete-milestone"]);
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const mode = (manifest as { tools: { mode: string } }).tools.mode;
     if (mode === "all") {
       assert.ok(
         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; ' +
+        `manifest "${unitType}" declares tools.mode = "all" but is not explicitly allowed. ` +
+        'Only execute-task, reactive-execute, and complete-milestone should have full source write access; ' +
         'planning/discuss/research units must use "planning" or "planning-dispatch" (or "docs" for rewrite-docs).',
       );
     }
   }
 });
 
+test("#5453: complete-milestone uses all tools so bash verification is not planning-dispatch blocked", () => {
+  const manifest = UNIT_MANIFESTS["complete-milestone"];
+
+  assert.strictEqual(manifest.tools.mode, "all");
+  assert.deepEqual(resolveSubagentPermissionContract("complete-milestone"), {
+    allowed: true,
+    allowedSubagents: ["*"],
+    toolsMode: "all",
+  });
+  // Runtime gate-level regression: these verification commands were blocked
+  // under planning-dispatch in #5453; complete-milestone must bypass that gate.
+  for (const cmd of ["git diff --name-only HEAD~1", "git log -n1 --oneline"]) {
+    const result = shouldBlockPlanningUnit(
+      "bash",
+      cmd,
+      process.cwd(),
+      "complete-milestone",
+      manifest.tools,
+    );
+    assert.strictEqual(
+      result.block,
+      false,
+      `shouldBlockPlanningUnit must not block ${cmd} for complete-milestone: ${result.reason}`,
+    );
+  }
+});
+
+test("#5843: run-uat uses verification tools policy so build/test commands can run", () => {
+  const manifest = UNIT_MANIFESTS["run-uat"];
+
+  assert.strictEqual(manifest.tools.mode, "verification");
+
+  const buildResult = shouldBlockPlanningUnit(
+    "bash",
+    "npm run build 2>&1",
+    process.cwd(),
+    "run-uat",
+    manifest.tools,
+  );
+  assert.strictEqual(
+    buildResult.block,
+    false,
+    `run-uat must allow build verification commands: ${buildResult.reason}`,
+  );
+
+  const sourceWriteResult = shouldBlockPlanningUnit(
+    "edit",
+    "src/main.ts",
+    process.cwd(),
+    "run-uat",
+    manifest.tools,
+  );
+  assert.strictEqual(sourceWriteResult.block, true);
+  assert.match(sourceWriteResult.reason!, /tools-policy "verification"/);
+});
+
+test("planning-dispatch hard block message omits internal tracker references", () => {
+  const manifest = UNIT_MANIFESTS["validate-milestone"];
+  assert.strictEqual(manifest.tools.mode, "planning-dispatch");
+
+  const result = shouldBlockPlanningUnit(
+    "task",
+    "scout",
+    process.cwd(),
+    "validate-milestone",
+    manifest.tools,
+  );
+
+  assert.strictEqual(result.block, true);
+  assert.ok(result.reason, "blocked dispatch should include a user-facing reason");
+  assert.doesNotMatch(result.reason!, /#[0-9]{3,}/);
+});
+
 test('planning-dispatch mode is reserved for slice-level decomposition and completion units', () => {
   const allowedDispatchUnits = new Set([
     "plan-slice",
+    "research-slice",
     "refine-slice",
     "complete-slice",
-    "complete-milestone",
+    "gate-evaluate",
     // Deep planning mode: research-project orchestrates 4 parallel research
     // subagents (stack/features/architecture/pitfalls). Subagent dispatch is
     // the unit's core mechanism — without it, the unit cannot do its job.
@@ -265,6 +343,24 @@ test('planning-dispatch mode is reserved for slice-level decomposition and compl
   }
 });
 
+test('Unit Tool Contract exposes subagent dispatch permissions', () => {
+  assert.deepEqual(resolveSubagentPermissionContract("plan-slice"), {
+    allowed: true,
+    allowedSubagents: ["scout", "planner"],
+    toolsMode: "planning-dispatch",
+  });
+  assert.deepEqual(resolveSubagentPermissionContract("gate-evaluate"), {
+    allowed: true,
+    allowedSubagents: ["reviewer", "security", "tester"],
+    toolsMode: "planning-dispatch",
+  });
+  assert.deepEqual(resolveSubagentPermissionContract("discuss-milestone"), {
+    allowed: false,
+    allowedSubagents: [],
+    toolsMode: "planning",
+  });
+});
+
 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;

package/src/resources/extensions/gsd/tests/validate-milestone-stuck-guard.test.ts

@@ -162,7 +162,7 @@ describe("validate-milestone stuck-loop guard (#4094)", () => {
     assert.equal(pauseAutoMock.mock.callCount(), 0);
   });
 
-  test("continues when no VALIDATION file exists yet", async () => {
+  test("retries when no VALIDATION file exists yet", async () => {
     insertMilestone({ id: "M001" });
     insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });
 
@@ -173,7 +173,34 @@ describe("validate-milestone stuck-loop guard (#4094)", () => {
 
     const result = await runPostUnitVerification({ s, ctx, pi } as VerificationContext, pauseAutoMock);
 
-    assert.equal(result, "continue");
+    assert.equal(result, "retry");
+    assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.ok(s.pendingVerificationRetry);
+    assert.equal(s.pendingVerificationRetry!.unitId, "M001");
+    assert.match(s.pendingVerificationRetry!.failureContext, /gsd_validate_milestone/);
+    assert.equal(s.pendingVerificationRetry!.attempt, 1);
+  });
+
+  test("retries when VALIDATION file exists but is empty", async () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });
+
+    const path = join(tempDir, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+    writeFileSync(path, "", "utf-8");
+    invalidateAllCaches();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, "validate-milestone", "M001");
+
+    const result = await runPostUnitVerification({ s, ctx, pi } as VerificationContext, pauseAutoMock);
+
+    assert.equal(result, "retry");
     assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.ok(s.pendingVerificationRetry);
+    assert.equal(s.pendingVerificationRetry!.unitId, "M001");
+    assert.match(s.pendingVerificationRetry!.failureContext, /exists but is empty/);
+    assert.equal(s.pendingVerificationRetry!.attempt, 1);
   });
 });

package/src/resources/extensions/gsd/tests/verification-gate.test.ts

@@ -22,7 +22,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { discoverCommands, runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, isLikelyCommand } from "../verification-gate.ts";
+import { discoverCommands, runVerificationGate, formatFailureContext, captureRuntimeErrors, runDependencyAudit, isLikelyCommand, validateVerificationCommand } from "../verification-gate.ts";
 import type { CaptureRuntimeErrorsOptions, DependencyAuditOptions } from "../verification-gate.ts";
 import { validatePreferences } from "../preferences.ts";
 
@@ -215,6 +215,102 @@ describe("verification-gate: discovery", () => {
     assert.equal(result.source, "task-plan");
     assert.deepStrictEqual(result.commands, ["npm run test"]);
   });
+
+  test("taskPlanVerify rejects piped pytest command", () => {
+    const result = discoverCommands({
+      taskPlanVerify: "python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5",
+      cwd: tmp,
+    });
+    assert.equal(result.source, "none");
+    assert.deepStrictEqual(result.commands, []);
+  });
+
+  test("Python project with tests discovers pytest when package.json is absent", () => {
+    mkdirSync(join(tmp, "tests"));
+    writeFileSync(join(tmp, "tests", "test_sample.py"), "def test_sample():\n    assert True\n");
+    writeFileSync(
+      join(tmp, "pyproject.toml"),
+      `[project]
+name = "sample"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+`,
+    );
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "python-project");
+    assert.deepStrictEqual(result.commands, ["python3 -m pytest"]);
+  });
+
+  test("Python project with nested Python test file discovers pytest", () => {
+    mkdirSync(join(tmp, "tests", "unit"), { recursive: true });
+    writeFileSync(join(tmp, "tests", "unit", "sample_test.py"), "def test_sample():\n    assert True\n");
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "python-project");
+    assert.deepStrictEqual(result.commands, ["python3 -m pytest"]);
+  });
+
+  test("Python project with pytest.ini discovers pytest", () => {
+    writeFileSync(join(tmp, "pytest.ini"), "[pytest]\npythonpath = .\n");
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "python-project");
+    assert.deepStrictEqual(result.commands, ["python3 -m pytest"]);
+  });
+
+  test("Python project with explicit pyproject pytest marker discovers pytest", () => {
+    writeFileSync(
+      join(tmp, "pyproject.toml"),
+      `[tool.pytest]
+pythonpath = ["."]
+`,
+    );
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "python-project");
+    assert.deepStrictEqual(result.commands, ["python3 -m pytest"]);
+  });
+
+  test("Python project markers without pytest evidence do not discover pytest", () => {
+    mkdirSync(join(tmp, "tests"));
+    writeFileSync(join(tmp, "tests", "README.md"), "# tests\n");
+    writeFileSync(
+      join(tmp, "pyproject.toml"),
+      `[project]
+name = "sample"
+dependencies = ["pytest-cov"]
+`,
+    );
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "none");
+    assert.deepStrictEqual(result.commands, []);
+  });
+
+  test("Python project with setup.cfg alone does not discover pytest", () => {
+    writeFileSync(join(tmp, "setup.cfg"), "[tool:pytest]\npythonpath = .\n");
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "none");
+    assert.deepStrictEqual(result.commands, []);
+  });
+
+  test("Python project with tox.ini alone does not discover pytest", () => {
+    writeFileSync(join(tmp, "tox.ini"), "[pytest]\npythonpath = .\n");
+
+    const result = discoverCommands({ cwd: tmp });
+
+    assert.equal(result.source, "none");
+    assert.deepStrictEqual(result.commands, []);
+  });
 });
 
 // ─── Execution Tests ─────────────────────────────────────────────────────────
@@ -445,6 +541,10 @@ test("isLikelyCommand: prose descriptions are rejected", () => {
   assert.equal(isLikelyCommand("Build succeeds without errors or warnings"), false);
 });
 
+test("isLikelyCommand: non-ASCII prose descriptions are rejected", () => {
+  assert.equal(isLikelyCommand("所有 命令 输出 一行 JSONL go test ./... 通过"), false);
+});
+
 test("isLikelyCommand: empty or whitespace-only strings are rejected", () => {
   assert.equal(isLikelyCommand(""), false);
   assert.equal(isLikelyCommand("   "), false);
@@ -455,6 +555,15 @@ test("isLikelyCommand: short lowercase tokens without flags are accepted (could
   assert.equal(isLikelyCommand("mycheck"), true);
 });
 
+test("validateVerificationCommand rejects shell control syntax", () => {
+  assert.deepEqual(validateVerificationCommand("python3 -m pytest tests/ -q --tb=short").ok, true);
+  const result = validateVerificationCommand("python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5");
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.match(result.reason, /shell control syntax/);
+  }
+});
+
 // ─── Additional Preference Validation Tests (T02) ──────────────────────────
 
 test("verification-gate: verification_commands produces no unknown-key warnings", () => {

package/src/resources/extensions/gsd/tests/verification-verdict.test.ts

@@ -0,0 +1,78 @@
+// Project/App: GSD-2
+// File Purpose: Tests for host-owned auto-mode verification verdict policy.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { decideVerificationVerdict } from "../verification-verdict.ts";
+import type { VerificationResult } from "../types.ts";
+
+function makeResult(overrides: Partial<VerificationResult> = {}): VerificationResult {
+  return {
+    passed: true,
+    checks: [],
+    discoverySource: "none",
+    timestamp: 1,
+    ...overrides,
+  };
+}
+
+test("execute-task fails closed when no host-owned checks are discovered", () => {
+  const verdict = decideVerificationVerdict("execute-task", makeResult());
+
+  assert.equal(verdict.passed, false);
+  assert.equal(verdict.reason, "no-host-checks");
+  assert.equal(verdict.retryable, false);
+  assert.match(verdict.failureContext, /No runnable host-owned verification command/);
+});
+
+test("non execute-task units preserve no-check pass semantics", () => {
+  const verdict = decideVerificationVerdict("plan-slice", makeResult());
+
+  assert.equal(verdict.passed, true);
+  assert.equal(verdict.reason, "passed");
+});
+
+test("execute-task command failure remains retryable verification failure", () => {
+  const verdict = decideVerificationVerdict(
+    "execute-task",
+    makeResult({
+      passed: false,
+      discoverySource: "package-json",
+      checks: [
+        {
+          command: "npm test",
+          exitCode: 1,
+          stdout: "",
+          stderr: "failed",
+          durationMs: 10,
+        },
+      ],
+    }),
+  );
+
+  assert.equal(verdict.passed, false);
+  assert.equal(verdict.reason, "checks-failed");
+  assert.equal(verdict.retryable, true);
+});
+
+test("execute-task passes when a discovered host check succeeds", () => {
+  const verdict = decideVerificationVerdict(
+    "execute-task",
+    makeResult({
+      discoverySource: "preference",
+      checks: [
+        {
+          command: "npm test",
+          exitCode: 0,
+          stdout: "ok",
+          stderr: "",
+          durationMs: 10,
+        },
+      ],
+    }),
+  );
+
+  assert.equal(verdict.passed, true);
+  assert.equal(verdict.reason, "passed");
+});

package/src/resources/extensions/gsd/tests/workflow-kernel.test.ts

@@ -165,6 +165,13 @@ test("decideFinalizeResult maps break results to stop decisions", () => {
   );
 });
 
+test("decideFinalizeResult maps step-wizard breaks to completed step exits", () => {
+  assert.deepEqual(
+    decideFinalizeResult({ action: "break", reason: "step-wizard" }),
+    { action: "complete-and-break" },
+  );
+});
+
 test("decideFinalizeResult maps continue and next results", () => {
   assert.deepEqual(
     decideFinalizeResult({ action: "continue" }),

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

@@ -375,7 +375,7 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
               estimate: "10m",
               files: ["src/resources/extensions/gsd/workflow-mcp.ts"],
               verify: "node --test",
-              inputs: ["M001-ROADMAP.md"],
+              inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
               expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
             },
           ],
@@ -746,3 +746,21 @@ test("transport compatibility still blocks units whose MCP tools are not exposed
   assert.match(error ?? "", /requires secure_env_collect/);
   assert.match(error ?? "", /currently exposes only/);
 });
+
+test("transport compatibility accepts MCP-namespaced runtime tools", () => {
+  const error = getWorkflowTransportSupportError(
+    "claude-code",
+    ["gsd_summary_save"],
+    {
+      projectRoot: "/tmp/project",
+      env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+      surface: "auto-mode",
+      unitType: "research-slice",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      activeTools: ["mcp__gsd-workflow__gsd_summary_save"],
+    },
+  );
+
+  assert.equal(error, null);
+});

package/src/resources/extensions/gsd/tests/workflow-memory-pressure.test.ts

@@ -4,7 +4,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { measureMemoryPressure } from "../auto/workflow-memory-pressure.ts";
+import {
+  measureMemoryPressure,
+  shouldCheckMemoryPressure,
+} from "../auto/workflow-memory-pressure.ts";
 
 const mb = 1024 * 1024;
 
@@ -69,3 +72,20 @@ test("measureMemoryPressure falls back when heap limit cannot be read", () => {
     pct: 0.25,
   });
 });
+
+test("shouldCheckMemoryPressure covers the first auto-mode iteration", () => {
+  assert.equal(shouldCheckMemoryPressure(1, 5), true);
+  assert.equal(shouldCheckMemoryPressure(2, 5), false);
+  assert.equal(shouldCheckMemoryPressure(5, 5), true);
+});
+
+test("shouldCheckMemoryPressure rejects invalid intervals", () => {
+  assert.throws(
+    () => shouldCheckMemoryPressure(1, 0),
+    /positive integer/,
+  );
+  assert.throws(
+    () => shouldCheckMemoryPressure(1, 1.5),
+    /positive integer/,
+  );
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -246,7 +246,7 @@ test("executePlanSlice writes task planning state and rendered plan artifacts",
           estimate: "15m",
           files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"],
           verify: "node --test",
-          inputs: ["ROADMAP.md"],
+          inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
           expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
         },
       ],

package/src/resources/extensions/gsd/tests/worktree-git-pathspec.test.ts

@@ -0,0 +1,39 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { _gitPathspecForWorktreePath } from "../auto-worktree.ts";
+
+function run(cmd: string, args: string[], cwd: string): string {
+  return execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+describe("worktree git pathspec", () => {
+  test("skips external GSD bookkeeping directories outside the git work-tree", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-pathspec-")));
+    const repo = join(root, "project");
+    const externalGsd = join(root, ".gsd", "projects", "abc123");
+
+    try {
+      mkdirSync(repo, { recursive: true });
+      mkdirSync(join(externalGsd, "milestones", "M002-wa00fm"), { recursive: true });
+      mkdirSync(join(externalGsd, "runtime", "units"), { recursive: true });
+      run("git", ["init"], repo);
+      writeFileSync(join(repo, "README.md"), "# test\n");
+
+      assert.equal(
+        _gitPathspecForWorktreePath(repo, join(externalGsd, "milestones", "M002-wa00fm")),
+        null,
+      );
+      assert.equal(
+        _gitPathspecForWorktreePath(repo, join(externalGsd, "runtime", "units")),
+        null,
+      );
+    } finally {
+      if (existsSync(root)) rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -30,11 +30,13 @@ function initGitRepoIn(base: string, isolation: "worktree" | "branch" | "none"):
 }
 import {
   WorktreeLifecycle,
+  resetRecentWorktreeMergeFailuresForTest,
   type WorktreeLifecycleDeps,
   type NotifyCtx,
 } from "../worktree-lifecycle.js";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import { type TaskCommitContext } from "../worktree.js";
+import { MergeConflictError } from "../git-service.js";
 
 // ADR-016 phase 2 / C-track retired all worktree-manager + cache + prefs
 // fields from `WorktreeLifecycleDeps`. Tests still pass them as overrides
@@ -141,6 +143,20 @@ function readJournalEntries(basePath: string): JournalEntry[] {
   }
 }
 
+function setupMergeWorktree(basePath: string, milestoneId: string): string {
+  initGitRepoIn(basePath, "worktree");
+  execFileSync("git", ["checkout", "-b", `milestone/${milestoneId}`], { cwd: basePath, stdio: "pipe" });
+  execFileSync("git", ["checkout", "main"], { cwd: basePath, stdio: "pipe" });
+  const wt = join(basePath, ".gsd", "worktrees", milestoneId);
+  execFileSync("git", ["worktree", "add", wt, `milestone/${milestoneId}`], { cwd: basePath, stdio: "pipe" });
+  mkdirSync(join(basePath, ".gsd", "milestones", milestoneId), { recursive: true });
+  writeFileSync(
+    join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+    `# ${milestoneId}\n- [x] S01: Slice one\n`,
+  );
+  return wt;
+}
+
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 describe("worktree journal events", () => {
@@ -148,6 +164,7 @@ describe("worktree journal events", () => {
   const originalCwd = process.cwd();
 
   beforeEach(() => {
+    resetRecentWorktreeMergeFailuresForTest();
     // realpathSync to match what `auto-worktree.ts` returns from
     // `resolveWorktreeProjectRoot` (macOS resolves `/var` → `/private/var`).
     tmp = realpathSync(mkdtempSync(join(tmpdir(), "wt-journal-")));
@@ -284,17 +301,7 @@ describe("worktree journal events", () => {
   });
 
   test("mergeAndExit emits worktree-merge-failed on error", () => {
-    initGitRepoIn(tmp, "worktree");
-    execFileSync("git", ["checkout", "-b", "milestone/M001"], { cwd: tmp, stdio: "pipe" });
-    execFileSync("git", ["checkout", "main"], { cwd: tmp, stdio: "pipe" });
-    const wt = join(tmp, ".gsd", "worktrees", "M001");
-    execFileSync("git", ["worktree", "add", wt, "milestone/M001"], { cwd: tmp, stdio: "pipe" });
-    mkdirSync(join(tmp, ".gsd", "milestones", "M001"), { recursive: true });
-    writeFileSync(
-      join(tmp, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
-      "# M001\n- [x] S01: Slice one\n",
-    );
-
+    const wt = setupMergeWorktree(tmp, "M001");
     const s = makeSession({ basePath: wt, originalBasePath: tmp });
     const deps = makeDeps({
       mergeMilestoneToMain: () => { throw new Error("conflict in main"); },
@@ -318,11 +325,56 @@ describe("worktree journal events", () => {
       );
     }
 
+    new WorktreeLifecycle(s, deps).exitMilestone(
+      "M001",
+      { merge: true },
+      makeNotifyCtx(),
+    );
+
     const entries = readJournalEntries(tmp);
-    const failed = entries.find(e => e.eventType === "worktree-merge-failed");
+    const failures = entries.filter(e => e.eventType === "worktree-merge-failed");
+    const failed = failures[0];
     assert.ok(failed, "worktree-merge-failed event should be emitted");
     assert.equal(failed!.data?.milestoneId, "M001");
     assert.equal(failed!.data?.error, "conflict in main");
+    assert.equal(failures.length, 1, "duplicate merge failures are journaled once");
+  });
+
+  test("merge failure dedupe uses stable conflict category and expires", (t) => {
+    let now = 1_000_000;
+    t.mock.method(Date, "now", () => now);
+    const wt = setupMergeWorktree(tmp, "M001");
+    const s = makeSession({ basePath: wt, originalBasePath: tmp });
+    let attempt = 0;
+    const deps = makeDeps({
+      mergeMilestoneToMain: () => {
+        attempt += 1;
+        throw new MergeConflictError(
+          attempt === 1 ? ["src/a.ts"] : ["src/b.ts", "src/c.ts"],
+          "squash",
+          "milestone/M001",
+          "main",
+        );
+      },
+    });
+    const lifecycle = new WorktreeLifecycle(s, deps);
+
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+
+    let failures = readJournalEntries(tmp).filter(e => e.eventType === "worktree-merge-failed");
+    assert.equal(failures.length, 1, "variable conflict filenames should not bypass dedupe");
+    assert.match(
+      String(failures[0]!.data?.error),
+      /src\/a\.ts/,
+      "journal payload keeps the original error message",
+    );
+
+    now += 60_001;
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+
+    failures = readJournalEntries(tmp).filter(e => e.eventType === "worktree-merge-failed");
+    assert.equal(failures.length, 2, "same merge failure is journaled again after dedupe expiry");
   });
 
   test("journal entries have valid flowId, seq, and ts fields", () => {