@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

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

@@ -1,8 +1,13 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { parseMilestoneTarget, parseModelFlag } from "../commands/handlers/auto.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
 describe("parseMilestoneTarget", () => {
   it("extracts a simple milestone ID", () => {
     const result = parseMilestoneTarget("auto M016");
@@ -60,6 +65,24 @@ describe("parseMilestoneTarget", () => {
   });
 });
 
+describe("auto preference diagnostics", () => {
+  it("notifies preference diagnostics before launching auto-mode", () => {
+    const source = readFileSync(join(__dirname, "..", "commands", "handlers", "auto.ts"), "utf-8");
+    const autoBlockIndex = source.indexOf('if (trimmed === "auto" || trimmed.startsWith("auto "))');
+    assert.ok(autoBlockIndex >= 0, "auto command block should exist");
+    const nextBlockIndex = source.indexOf('if (trimmed === "stop")', autoBlockIndex);
+    const autoBlock = source.slice(autoBlockIndex, nextBlockIndex);
+    const notifyIndex = autoBlock.indexOf("notifyPreferenceDiagnostics");
+    assert.ok(notifyIndex >= 0, "auto command should notify preference diagnostics");
+    for (const match of autoBlock.matchAll(/startAutoDetached/g)) {
+      assert.ok(
+        notifyIndex < match.index!,
+        "preference diagnostics should be notified before each auto-mode launch",
+      );
+    }
+  });
+});
+
 describe("parseModelFlag", () => {
   it("extracts provider/model from --model", () => {
     const result = parseModelFlag("auto --model openrouter/openai/gpt-5.4");

package/src/resources/extensions/gsd/tests/auto-model-selection-tool-poisoning.test.ts

@@ -33,6 +33,7 @@ import {
   selectAndApplyModel,
   ModelPolicyDispatchBlockedError,
   clearToolBaseline,
+  getRegisteredToolSnapshot,
   getToolBaselineSnapshot,
 } from "../auto-model-selection.js";
 import { applyModelPolicyFilter } from "../uok/model-policy.js";
@@ -773,3 +774,20 @@ test("baseline union (#477): getToolBaselineSnapshot includes live tools not pre
     env.cleanup();
   }
 });
+
+test("registered tool snapshot includes tools hidden from the active surface", () => {
+  const pi = {
+    getActiveTools: () => ["read"],
+    getAllTools: () => [
+      { name: "read" },
+      { name: "browser_navigate" },
+      { name: "mcp__gsd-browser__*" },
+    ],
+  };
+
+  assert.deepEqual(getRegisteredToolSnapshot(pi as any), [
+    "read",
+    "browser_navigate",
+    "mcp__gsd-browser__*",
+  ]);
+});

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

@@ -33,6 +33,8 @@ import type { UnifiedRule } from "../rule-types.js";
 import { supportsStructuredQuestions } from "../workflow-mcp.js";
 import {
   closeDatabase,
+  insertAssessment,
+  insertGateRow,
   insertMilestone,
   insertSlice,
   insertTask,
@@ -302,6 +304,46 @@ test("advance() sets active unit and is reflected in status", async (t) => {
   });
 });
 
+test("advance() blocks source dispatch when an earlier slice is incomplete", async (t) => {
+  const f = makeFixture({
+    dispatch: () => ({
+      action: "dispatch",
+      unitType: "execute-task",
+      unitId: "M001/S02/T01",
+      prompt: "fixture-prompt",
+    }),
+  });
+  t.after(() => f.cleanup());
+
+  insertSlice({
+    id: "S02",
+    milestoneId: "M001",
+    title: "Second slice",
+    status: "active",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 2,
+  });
+  insertTask({
+    id: "T01",
+    sliceId: "S02",
+    milestoneId: "M001",
+    title: "Second task",
+    status: "active",
+  });
+
+  const result = await f.orchestrator.advance();
+
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "stop");
+  assert.match(result.reason, /earlier slice M001\/S01 is not complete/);
+  assert.equal(f.session.pendingOrchestrationDispatch, null);
+  assert.deepEqual(f.orchestrator.getStatus().activeUnit, undefined);
+  assert.ok(f.journalNames().includes("advance-blocked"));
+});
+
 test("getStatus() returns defensive copy of activeUnit", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());
@@ -374,10 +416,65 @@ test("advance() reports completion when complete state has no next unit", async
 
   assert.equal(result.kind, "stopped");
   if (result.kind !== "stopped") return;
-  assert.equal(result.reason, "all milestones complete");
+  assert.equal(result.reason, "All milestones complete");
+  assert.equal(result.terminalOutcome?.code, "all-complete");
   assert.equal(f.orchestrator.getStatus().phase, "stopped");
 });
 
+test("advance() blocks all-complete stop when completed milestone is still unmerged in a worktree", async (t) => {
+  const f = makeFixture({ complete: true, noTask: true });
+  t.after(() => f.cleanup());
+
+  insertSlice({
+    id: "S01",
+    milestoneId: "M001",
+    title: "Slice",
+    status: "complete",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 1,
+  });
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+  insertGateRow({
+    milestoneId: "M001",
+    sliceId: "S01",
+    gateId: "Q3",
+    scope: "slice",
+    status: "pending",
+  });
+
+  const worktreePath = join(f.base, ".gsd", "worktrees", "M001");
+  mkdirSync(join(f.base, ".gsd", "worktrees"), { recursive: true });
+  execFileSync("git", ["worktree", "add", "-b", "milestone/M001", worktreePath], { cwd: f.base, stdio: "ignore" });
+  mkdirSync(join(worktreePath, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(worktreePath, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\n");
+  f.session.basePath = worktreePath;
+  f.session.originalBasePath = f.base;
+  f.session.currentMilestoneId = "M001";
+  f.session.milestoneMergedInPhases = false;
+
+  const result = await f.orchestrator.advance();
+
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "pause");
+  assert.equal(result.terminalOutcome?.code, "settlement-blocked");
+  assert.match(result.reason, /worktree branch has not been merged to main/);
+  assert.doesNotMatch(result.reason, /quality gate Q3 is still pending/);
+  assert.equal(f.orchestrator.getStatus().phase, "paused");
+  assert.equal(f.session.milestoneSettlement?.ok, false);
+  const names = f.journalNames();
+  assert.ok(names.includes("advance-blocked"));
+  assert.ok(!names.includes("advance-stopped"));
+});
+
 test("advance() stopped clears previous activeUnit and resets idempotent lock", async (t) => {
   // First advance dispatches; then we make the milestone resolve to no unit by
   // closing it on disk + DB and re-deriving. Simpler: drive a fixture that
@@ -696,7 +793,10 @@ test("stuck-loop: start() resets the ring so a fresh saturation cycle is require
   assert.equal(next.kind, "advanced");
 });
 
-test("stuck-loop: resume() resets the ring", async (t) => {
+test("stuck-loop: resume() preserves ring so detection accumulates across pause/resume", async (t) => {
+  // Regression for #572: resume() must NOT reset dispatchKeyWindow. Before the
+  // fix, a pause/resume cycle cleared the window, letting a stuck loop silently
+  // re-accumulate STUCK_WINDOW_SIZE dispatches before being detected again.
   const f = makeFixture();
   t.after(() => f.cleanup());
 
@@ -707,11 +807,39 @@ test("stuck-loop: resume() resets the ring", async (t) => {
   const resumed = await f.orchestrator.resume();
   assert.equal(resumed.kind, "resumed");
 
+  // The ring is preserved, so the next advance pushes it to STUCK_WINDOW_SIZE
+  // and triggers stuck-loop detection — not a fresh dispatch.
   const next = await f.orchestrator.advance();
-  assert.equal(next.kind, "advanced");
+  assert.equal(next.kind, "blocked");
+  if (next.kind !== "blocked") return;
+  assert.equal(next.action, "stop");
+  assert.ok(next.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${next.reason}`);
+});
+
+test("stuck-loop: stop('pause') preserves ring across the stop/resume cycle", async (t) => {
+  // Regression for #572: stop("pause") must behave the same as resume() —
+  // the window must survive so detection accumulates across pause/resume pairs.
+  const f = makeFixture();
+  t.after(() => f.cleanup());
+
+  for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
+    await f.orchestrator.advance();
+  }
+
+  const stopped = await f.orchestrator.stop("pause");
+  assert.equal(stopped.kind, "stopped");
+
+  const resumed = await f.orchestrator.resume();
+  assert.equal(resumed.kind, "resumed");
+
+  const next = await f.orchestrator.advance();
+  assert.equal(next.kind, "blocked");
+  if (next.kind !== "blocked") return;
+  assert.equal(next.action, "stop");
+  assert.ok(next.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${next.reason}`);
 });
 
-test("stuck-loop: stop() resets the ring", async (t) => {
+test("stuck-loop: stop('user-request') resets the ring (hard stop)", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());
 
@@ -722,6 +850,7 @@ test("stuck-loop: stop() resets the ring", async (t) => {
   const stopped = await f.orchestrator.stop("user-request");
   assert.equal(stopped.kind, "stopped");
 
+  // Hard stop clears the ring, so the next advance dispatches fresh.
   const next = await f.orchestrator.advance();
   assert.equal(next.kind, "advanced");
 });

package/src/resources/extensions/gsd/tests/auto-paused-ui-cleanup.test.ts

@@ -306,7 +306,9 @@ test("pauseAuto records the expected worktree path when paused from project root
 
     const meta = readPausedSessionMetadata(base);
     assert.ok(meta);
-    assert.equal(meta.worktreePath, join(base, ".gsd", "worktrees", "M001"));
+    // No worktree exists yet, so the recorded path is the canonical
+    // .gsd-worktrees/ creation location (worktree-placement seam).
+    assert.equal(meta.worktreePath, join(base, ".gsd-worktrees", "M001"));
   } finally {
     autoSession.reset();
     try {

package/src/resources/extensions/gsd/tests/auto-post-unit-evidence-crossref-4909.test.ts

@@ -88,3 +88,49 @@ test("detects session execution tools supported by the evidence collector", () =
 
   assert.equal(_hasExecutionToolCallsInSessionForTest(entries), true);
 });
+
+test("detects execution tool calls in bare agent-end messages (no session-entry wrapper)", () => {
+  // The auto loop passes opts.agentEndMessages as bare {role, content}
+  // messages — not {type: "message", message} session-manager entries.
+  const entries = [
+    {
+      role: "assistant",
+      content: [
+        {
+          type: "toolCall",
+          name: "Bash",
+          arguments: { command: "test -s index.html && grep -q localStorage index.html" },
+        },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), true);
+});
+
+test("does not suppress for bare agent-end messages without execution tools", () => {
+  const entries = [
+    {
+      role: "assistant",
+      content: [
+        { type: "text", text: "Task complete." },
+        { type: "toolCall", name: "Write", arguments: { file_path: "index.html" } },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), false);
+});
+
+test("ignores bare user messages with toolCall-shaped content", () => {
+  const entries = [
+    {
+      role: "user",
+      content: [
+        { type: "toolCall", name: "bash", arguments: { command: "echo hi" } },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), false);
+});

package/src/resources/extensions/gsd/tests/auto-runtime-state.test.ts

@@ -6,12 +6,15 @@ import assert from "node:assert/strict";
 
 import {
   autoSession,
+  clearAutoToolSurfaceSnapshot,
   clearToolInvocationError,
   getAutoRuntimeSnapshot,
+  recordAutoToolSurfaceSnapshot,
 } from "../auto-runtime-state.ts";
 
 test("getAutoRuntimeSnapshot includes orchestration phase when available", () => {
   autoSession.reset();
+  clearAutoToolSurfaceSnapshot();
   autoSession.active = true;
   autoSession.basePath = "/tmp/project";
   autoSession.orchestration = {
@@ -33,10 +36,40 @@ test("getAutoRuntimeSnapshot includes orchestration phase when available", () =>
   assert.equal(snap.orchestrationPhase, "running");
   assert.equal(snap.orchestrationTransitionCount, 3);
   assert.equal(snap.orchestrationLastTransitionAt, 123);
+  assert.equal(snap.toolSurface, null);
 
   autoSession.reset();
 });
 
+test("getAutoRuntimeSnapshot includes the active typed tool-surface snapshot", () => {
+  autoSession.reset();
+  clearAutoToolSurfaceSnapshot();
+  autoSession.active = true;
+
+  recordAutoToolSurfaceSnapshot({
+    source: "dispatch-scope",
+    unitType: "run-uat",
+    modelFacingToolNames: ["read", "read", "gsd_uat_exec"],
+    registeredToolNames: ["read", "browser_navigate"],
+    scopedToolNames: ["read", "browser_navigate"],
+    presentedToolNames: ["gsd_uat_exec"],
+    capturedAt: 123,
+  });
+
+  const snap = getAutoRuntimeSnapshot();
+
+  assert.equal(snap.toolSurface?.source, "dispatch-scope");
+  assert.equal(snap.toolSurface?.unitType, "run-uat");
+  assert.deepEqual(snap.toolSurface?.modelFacingToolNames, ["read", "gsd_uat_exec"]);
+  assert.deepEqual(snap.toolSurface?.registeredToolNames, ["read", "browser_navigate"]);
+  assert.deepEqual(snap.toolSurface?.scopedToolNames, ["read", "browser_navigate"]);
+  assert.deepEqual(snap.toolSurface?.presentedToolNames, ["gsd_uat_exec"]);
+  assert.equal(snap.toolSurface?.capturedAt, 123);
+
+  autoSession.reset();
+  clearAutoToolSurfaceSnapshot();
+});
+
 test("clearToolInvocationError clears stale tool error state for active auto sessions", () => {
   autoSession.reset();
   autoSession.active = true;
@@ -56,4 +89,5 @@ test("getAutoRuntimeSnapshot omits orchestration phase when seam not wired", ()
   assert.equal(snap.orchestrationPhase, undefined);
   assert.equal(snap.orchestrationTransitionCount, undefined);
   assert.equal(snap.orchestrationLastTransitionAt, undefined);
+  assert.equal(snap.toolSurface, null);
 });

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

@@ -184,7 +184,7 @@ describe("auto-worktree workspace registry", () => {
     git(["commit", "-m", "add milestone"], tempDir);
 
     createAutoWorktree(tempDir, "M003");
-    const wtDir = join(tempDir, ".gsd", "worktrees", "M003");
+    const wtDir = join(tempDir, ".gsd-worktrees", "M003");
     writeFileSync(join(wtDir, "feature.txt"), "implemented\n");
     git(["add", "feature.txt"], wtDir);
     git(["commit", "-m", "feat: implement M003"], wtDir);
@@ -216,7 +216,7 @@ describe("auto-worktree workspace registry", () => {
     git(["commit", "-m", "add milestone"], tempDir);
 
     createAutoWorktree(tempDir, "M004");
-    const wtDir = join(tempDir, ".gsd", "worktrees", "M004");
+    const wtDir = join(tempDir, ".gsd-worktrees", "M004");
     writeFileSync(join(wtDir, "feature.txt"), "implemented\n");
     git(["add", "feature.txt"], wtDir);
     git(["commit", "-m", "feat: implement M004"], wtDir);

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

@@ -35,7 +35,8 @@ test("repair target accepts a missing expected milestone worktree", () => {
 
     assert.equal(result.ok, true);
     if (result.ok) {
-      assert.equal(result.expectedPath, join(base, ".gsd", "worktrees", "M001"));
+      // No worktree exists yet, so the expected path is the canonical container.
+      assert.equal(result.expectedPath, join(base, ".gsd-worktrees", "M001"));
     }
   } finally {
     cleanup(base);
@@ -192,7 +193,8 @@ test("paused metadata path resolves to the expected worktree while paused at pro
       baseIsAutoWorktree: false,
     });
 
-    assert.equal(result, join(base, ".gsd", "worktrees", "M001"));
+    // No worktree exists yet, so resolution lands at the canonical container.
+    assert.equal(result, join(base, ".gsd-worktrees", "M001"));
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/browser-automation-contract-fixture.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+
+import {
+	getUatBrowserToolSupportError,
+	hasUatBrowserToolSurface,
+	type UatType,
+} from "../uat-policy.ts";
+
+export const BROWSER_AUTOMATION_CONTRACT_TOOLS = {
+	piProvider: ["read", "browser_navigate"],
+	externalMcpClient: ["read", "mcp__gsd-browser__browser_navigate"],
+	externalMcpWildcard: ["read", "mcp__gsd-browser__*"],
+	otherBrowserMcp: ["read", "mcp__browser-uat__*"],
+	workflowOnly: ["read", "mcp__gsd-workflow__*"],
+	withoutBrowser: ["read", "gsd_uat_exec"],
+} as const;
+
+export function assertBrowserAutomationContractAvailable(tools: readonly string[]): void {
+	assert.equal(hasUatBrowserToolSurface(tools), true, `${tools.join(", ")} should satisfy the Browser Automation Contract`);
+}
+
+export function assertBrowserAutomationContractMissing(tools: readonly string[] | undefined): void {
+	assert.equal(hasUatBrowserToolSurface(tools), false, `${tools?.join(", ") ?? "undefined"} should not satisfy the Browser Automation Contract`);
+}
+
+export function assertBrowserBackedUatCanDispatch(options: {
+	uatType: UatType;
+	activeTools: readonly string[] | undefined;
+	registeredTools?: readonly string[];
+}): void {
+	assert.equal(
+		getUatBrowserToolSupportError({
+			...options,
+			milestoneId: "M001",
+			sliceId: "S01",
+		}),
+		null,
+	);
+}

package/src/resources/extensions/gsd/tests/browser-contract.test.ts

@@ -0,0 +1,44 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  BROWSER_CONTRACT_TOOL_NAMES,
+  BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES,
+  hasBrowserContractPrefix,
+  isBrowserContractToolName,
+} from "../../shared/browser-contract.ts";
+import { isUatBrowserToolName } from "../uat-policy.ts";
+import { BROWSER_REQUIREMENT_RE, BROWSER_RUNTIME_RE } from "../browser-evidence.ts";
+
+// Note: RUN_UAT_BROWSER_TOOL_NAMES and MANAGED_GSD_BROWSER_TOOL_NAMES are
+// reference-equal aliases of BROWSER_CONTRACT_TOOL_NAMES, and the managed
+// adapter's spec table is Record-keyed by BrowserContractToolName — both
+// derivations are pinned by the type system, not by runtime assertions here.
+describe("Browser Automation Contract parity", () => {
+  it("every contract name satisfies the UAT browser-tool predicate, bare and MCP-prefixed", () => {
+    for (const name of BROWSER_CONTRACT_TOOL_NAMES) {
+      assert.equal(isUatBrowserToolName(name), true, name);
+      assert.equal(isUatBrowserToolName(`mcp__gsd-browser__${name}`), true, `mcp__gsd-browser__${name}`);
+    }
+  });
+
+  it("contract names are canonical browser_* names with no duplicates", () => {
+    assert.equal(new Set(BROWSER_CONTRACT_TOOL_NAMES).size, BROWSER_CONTRACT_TOOL_NAMES.length);
+    for (const name of BROWSER_CONTRACT_TOOL_NAMES) {
+      assert.equal(hasBrowserContractPrefix(name), true, name);
+      assert.equal(isBrowserContractToolName(name), true, name);
+    }
+    assert.equal(isBrowserContractToolName("browser_not_a_real_tool"), false);
+    assert.equal(hasBrowserContractPrefix("gsd_uat_exec"), false);
+  });
+
+  it("evidence-signal names stay a subset of the contract and drive the detection regexes", () => {
+    for (const name of BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES) {
+      assert.equal(isBrowserContractToolName(name), true, name);
+      // Identifier-shaped names keep the regex splice in browser-evidence.ts escape-free.
+      assert.match(name, /^browser_[a-z_]+$/);
+      assert.match(`Verified via ${name} call`, BROWSER_REQUIREMENT_RE);
+      assert.match(`Verified via ${name} call`, BROWSER_RUNTIME_RE);
+    }
+  });
+});

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

@@ -17,6 +17,7 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.ts";
+import { resolveCloseoutArtifactProjection } from "../artifact-projection.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-canon-test-${randomUUID()}`);
@@ -106,3 +107,22 @@ test("only returns the worktree for the requested milestone, not siblings", () =
     cleanup(base);
   }
 });
+
+test("resolveCloseoutArtifactProjection names project and canonical artifact roots", () => {
+  const base = makeTmpBase();
+  try {
+    const wtPath = makeLiveWorktree(base, "M001");
+    const projection = resolveCloseoutArtifactProjection({
+      milestoneId: "M001",
+      basePath: wtPath,
+      originalBasePath: base,
+    });
+
+    assert.equal(projection.projectRoot, base);
+    assert.equal(projection.canonicalMilestoneRoot, wtPath);
+    assert.equal(projection.summaryArtifactBasePath, wtPath);
+    assert.equal(projection.gateEvidenceBasePath, wtPath);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/checkout-branch-stash-guard.test.ts

@@ -5,7 +5,7 @@ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSy
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { checkoutBranchWithStashGuard } from "../auto-worktree.ts";
+import { checkoutBranchWithStashGuard } from "../worktree-git-recovery.ts";
 
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
@@ -159,4 +159,69 @@ describe("checkoutBranchWithStashGuard", () => {
     const stashList = git(["stash", "list"], repo).trim();
     assert.equal(stashList, "");
   });
+
+  test("auto-resolves combined non-.gsd untracked collision and .gsd index conflict", (t) => {
+    // Regression for: gate checked nonGsdUnmerged.length === 0 but ignored
+    // .gsd/ index conflicts, so a failed pop with both an untracked non-.gsd/
+    // collision AND a .gsd/ tracked conflict would drop the stash while leaving
+    // .gsd/ index unmerged entries unresolved.
+    const repo = createRepo(t);
+    // Add .gsd/DECISIONS.md to base so both branches diverge from it
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "base\n");
+    git(["add", ".gsd/DECISIONS.md"], repo);
+    git(["commit", "-m", "add decisions"], repo);
+
+    git(["checkout", "-b", "milestone/M003"], repo);
+    // Branch has its own version of DECISIONS.md (non-JSONL .gsd/ file)
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "target-version\n");
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"dark\"}\n");
+    git(["add", ".gsd/DECISIONS.md", ".harness/settings.json"], repo);
+    git(["commit", "-m", "branch state"], repo);
+    git(["checkout", "main"], repo);
+
+    // On main: tracked .gsd/ change (creates unmerged index entry on pop) +
+    // untracked harness file (triggers "already exists, no checkout").
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "local-version\n");
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"light\"}\n");
+
+    checkoutBranchWithStashGuard(repo, "milestone/M003", "test-combined-gsd-conflict");
+
+    const branch = git(["branch", "--show-current"], repo).trim();
+    assert.equal(branch, "milestone/M003");
+    const decisions = readFileSync(join(repo, ".gsd", "DECISIONS.md"), "utf8");
+    assert.equal(decisions, "target-version\n");
+    assert.doesNotMatch(decisions, /<<<<<<<|=======|>>>>>>>/);
+    const status = git(["status", "--porcelain"], repo).trim();
+    assert.equal(status, "");
+    const stashList = git(["stash", "list"], repo).trim();
+    assert.equal(stashList, "");
+  });
+
+  test("auto-resolves non-.gsd untracked restore collisions (e.g. harness config outside .gsd/)", (t) => {
+    const repo = createRepo(t);
+    // Target branch has a harness config file committed; source (main) has it untracked.
+    // Use a path not affected by global gitignore rules (unlike .claude/settings.local.json).
+    git(["checkout", "-b", "milestone/M001"], repo);
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"dark\"}\n");
+    git(["add", ".harness/settings.json"], repo);
+    git(["commit", "-m", "add harness settings"], repo);
+    git(["checkout", "main"], repo);
+
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"light\"}\n");
+
+    checkoutBranchWithStashGuard(repo, "milestone/M001", "test-non-gsd-untracked-collision");
+
+    const branch = git(["branch", "--show-current"], repo).trim();
+    assert.equal(branch, "milestone/M001");
+    const wtContent = readFileSync(join(repo, ".harness", "settings.json"), "utf8");
+    assert.equal(wtContent, "{\"theme\":\"dark\"}\n");
+    const status = git(["status", "--porcelain"], repo).trim();
+    assert.equal(status, "");
+    const stashList = git(["stash", "list"], repo).trim();
+    assert.equal(stashList, "");
+  });
 });

package/src/resources/extensions/gsd/tests/clear-stale-autostart.test.ts

@@ -73,4 +73,48 @@ describe("clear stale pending auto-start (#3667)", () => {
       "pending auto-start gate must clear stale map entries for completed discussions",
     );
   });
+
+  test("guided-flow recovers a finished-but-unconsumed discussion instead of dead-ending", () => {
+    // CONTEXT exists + no live turn means the discussion completed but the
+    // agent_end handoff never consumed the entry (e.g. an external-engine
+    // post-hoc gate re-arm wiped the depth verification after the save).
+    // Without recovery, every /gsd prints "Discussion already in progress"
+    // forever: the stale heuristic requires CONTEXT to be absent and
+    // discussPlanComplete requires a ROADMAP that planning never produced.
+    const source = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
+    assert.ok(
+      source.includes("milestoneHasContext && !isAgentTurnInFlight(ctx)"),
+      "pending-entry guard must have a recovery branch for CONTEXT-present, no-turn-in-flight entries",
+    );
+    assert.ok(
+      source.includes("extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId"),
+      "recovery must only clear a pending gate belonging to the entry's own milestone",
+    );
+    assert.ok(
+      source.includes("if (checkAutoStartAfterDiscuss(basePath)) return;"),
+      "recovery must re-run the discuss→auto handoff after clearing the stale gate",
+    );
+  });
+
+  test("guided-flow does not treat a live discuss turn as a stale pending entry", () => {
+    const source = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
+    assert.ok(
+      source.includes("!isAgentTurnInFlight(ctx)"),
+      "stale-entry deletion must be gated on no agent turn being in flight — a dispatched " +
+      "discuss turn can think for over 30s before writing its first artifact, and deleting " +
+      "its entry re-dispatches the workflow (duplicate interview + duplicate completion message)",
+    );
+    assert.ok(
+      source.includes('const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");'),
+      "stale-entry check must treat an existing CONTEXT-DRAFT as proof of an in-progress interview",
+    );
+    assert.ok(
+      source.includes("!milestoneHasDraft"),
+      "stale-entry deletion must require the CONTEXT-DRAFT to be absent",
+    );
+    assert.ok(
+      source.includes("ctx.hasPendingMessages"),
+      "in-flight detection must also cover dispatched-but-not-yet-started queued messages",
+    );
+  });
 });