gsd-pi 2.82.0 → 3.0.0-dev.8b8d129d7

package/src/resources/extensions/gsd/tests/provider-switch-observer.test.ts

@@ -0,0 +1,252 @@
+// GSD-2 — ADR-005 Phase 3b: ProviderSwitchObserver Tests
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { setProviderSwitchObserver, type ProviderSwitchReport } from "@gsd/pi-ai";
+
+import { autoSession } from "../auto-runtime-state.ts";
+import {
+  initNotificationStore,
+  readNotifications,
+  _resetNotificationStore,
+} from "../notification-store.ts";
+import {
+  _resetProviderSwitchStats,
+  getProviderSwitchStats,
+  installProviderSwitchObserver,
+  uninstallProviderSwitchObserver,
+} from "../provider-switch-observer.ts";
+
+function makeReport(overrides: Partial<ProviderSwitchReport> = {}): ProviderSwitchReport {
+  return {
+    fromApi: "anthropic-messages",
+    toApi: "openai-responses",
+    thinkingBlocksDropped: 0,
+    thinkingBlocksDowngraded: 0,
+    toolCallIdsRemapped: 0,
+    syntheticToolResultsInserted: 0,
+    thoughtSignaturesDropped: 0,
+    ...overrides,
+  };
+}
+
+function withTempBasePath(): { basePath: string; cleanup: () => void } {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-provider-switch-"));
+  return {
+    basePath,
+    cleanup: () => rmSync(basePath, { recursive: true, force: true }),
+  };
+}
+
+test.beforeEach(() => {
+  _resetProviderSwitchStats();
+  _resetNotificationStore();
+  autoSession.currentTraceId = null;
+  autoSession.basePath = "";
+});
+
+test.afterEach(() => {
+  uninstallProviderSwitchObserver();
+  _resetNotificationStore();
+  autoSession.currentTraceId = null;
+  autoSession.basePath = "";
+});
+
+test("installProviderSwitchObserver wires the pi-ai observer hook", () => {
+  installProviderSwitchObserver();
+  // Indirect: a second install is a no-op. We verify by checking the counter
+  // increments exactly once when we fire a single report directly into pi-ai's
+  // observer slot.
+  installProviderSwitchObserver();
+
+  // Drive the pi-ai observer directly. The install above pointed it at our
+  // handler; firing here exercises the same code path as a real transform.
+  // We can't reach the installed handler reference from here, so we re-install
+  // a sentinel and confirm setProviderSwitchObserver accepts undefined.
+  setProviderSwitchObserver(undefined);
+  assert.ok(true); // install/uninstall did not throw
+});
+
+test("non-empty report increments the in-memory counter", () => {
+  installProviderSwitchObserver();
+
+  // Reach into the installed handler via setProviderSwitchObserver re-binding.
+  // We snapshot the handler by re-installing, capturing nothing — instead we
+  // use the public API: drive a report through the observer hook directly by
+  // calling setProviderSwitchObserver with a wrapper that proxies into the
+  // installed handler. This is awkward without a separate seam, so we test
+  // the recordReport path end-to-end by firing through pi-ai's transform helper
+  // pattern in a sibling test below. Here we exercise install idempotency only.
+
+  // Fire by setting our own observer that forwards to the module API isn't
+  // possible without exporting handleReport. Instead, verify install state
+  // doesn't crash; the real fire path is covered by the integration test
+  // below that exercises transformMessagesWithReport.
+  assert.deepEqual(getProviderSwitchStats().totalSwitches, 0);
+});
+
+test("end-to-end: transformMessagesWithReport fires the observer and updates stats + notifications", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+
+    // Construct a cross-API transform that will drop a redacted thinking block.
+    const targetModel = {
+      id: "gpt-5",
+      name: "GPT-5",
+      api: "openai-responses",
+      provider: "openai",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 128000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    const messages = [
+      {
+        role: "assistant" as const,
+        content: [
+          { type: "thinking" as const, thinking: "", redacted: true },
+          { type: "text" as const, text: "hi" },
+        ],
+        api: "anthropic-messages",
+        provider: "anthropic",
+        model: "claude-sonnet-4-6",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "stop" as const,
+        timestamp: Date.now(),
+      },
+    ];
+
+    transformMessagesWithReport(messages as Parameters<typeof transformMessagesWithReport>[0], targetModel, undefined, "anthropic-messages");
+
+    const stats = getProviderSwitchStats();
+    assert.equal(stats.totalSwitches, 1, "non-empty report should bump the counter");
+    assert.ok(stats.totals.thinkingBlocksDropped >= 1, "thinking block drop should be tallied");
+    assert.ok(stats.lastReport, "last report should be retained");
+    assert.equal(stats.lastReport?.fromApi, "anthropic-messages");
+    assert.equal(stats.lastReport?.toApi, "openai-responses");
+
+    // Notification persistence — the observer is interactive (no traceId), so
+    // the byTrace key falls back to "interactive".
+    assert.ok("interactive" in stats.byTrace, "interactive trace bucket should exist");
+    assert.equal(stats.byTrace.interactive?.switches, 1);
+
+    const notifications = readNotifications(basePath);
+    const switchNotifs = notifications.filter((n) => n.message.includes("Provider switch"));
+    assert.ok(switchNotifs.length >= 1, "a provider-switch notification should be persisted");
+    assert.equal(switchNotifs[0]?.severity, "warning");
+  } finally {
+    cleanup();
+  }
+});
+
+test("end-to-end: audit event is emitted when an auto trace is active", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+    autoSession.basePath = basePath;
+    autoSession.currentTraceId = "trace-provider-switch-1";
+
+    const targetModel = {
+      id: "gpt-5",
+      name: "GPT-5",
+      api: "openai-responses",
+      provider: "openai",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 128000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    const messages = [
+      {
+        role: "assistant" as const,
+        content: [
+          { type: "thinking" as const, thinking: "", redacted: true },
+          { type: "text" as const, text: "hi" },
+        ],
+        api: "anthropic-messages",
+        provider: "anthropic",
+        model: "claude-sonnet-4-6",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "stop" as const,
+        timestamp: Date.now(),
+      },
+    ];
+
+    transformMessagesWithReport(messages as Parameters<typeof transformMessagesWithReport>[0], targetModel, undefined, "anthropic-messages");
+
+    const auditLogPath = join(basePath, ".gsd", "audit", "events.jsonl");
+    assert.ok(existsSync(auditLogPath), "audit events file should be created");
+    const auditLines = readFileSync(auditLogPath, "utf-8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as { category: string; type: string; traceId: string; payload: Record<string, unknown> });
+    const switchEvent = auditLines.find((e) => e.category === "model-policy" && e.type === "provider-switch");
+    assert.ok(switchEvent, "a model-policy/provider-switch audit event should be present");
+    assert.equal(switchEvent?.traceId, "trace-provider-switch-1");
+    assert.equal(switchEvent?.payload.fromApi, "anthropic-messages");
+    assert.equal(switchEvent?.payload.toApi, "openai-responses");
+
+    const stats = getProviderSwitchStats();
+    assert.ok("trace-provider-switch-1" in stats.byTrace, "trace-keyed bucket should be populated");
+    assert.equal(stats.byTrace["trace-provider-switch-1"]?.switches, 1);
+  } finally {
+    cleanup();
+  }
+});
+
+test("empty report does not bump counter or emit a notification", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+
+    // Same-API transform → no transformations → empty report.
+    const sameApiModel = {
+      id: "claude-sonnet-4-6",
+      name: "Claude Sonnet 4.6",
+      api: "anthropic-messages",
+      provider: "anthropic",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    transformMessagesWithReport(
+      [
+        {
+          role: "user" as const,
+          content: "plain text — no transforms triggered",
+        },
+      ] as Parameters<typeof transformMessagesWithReport>[0],
+      sameApiModel,
+      undefined,
+      "anthropic-messages",
+    );
+
+    assert.equal(getProviderSwitchStats().totalSwitches, 0);
+    assert.equal(readNotifications(basePath).length, 0);
+  } finally {
+    cleanup();
+  }
+});

package/src/resources/extensions/gsd/tests/quality-gates.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Validates planning and task template quality-gate content.
+
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -27,11 +30,14 @@ console.log("\n=== Level 1: Templates contain quality gate headings ===");
   const plan = loadTemplate("plan");
   assertTrue(plan.includes("## Threat Surface"), "plan.md contains ## Threat Surface");
   assertTrue(plan.includes("## Requirement Impact"), "plan.md contains ## Requirement Impact");
+  assertTrue(plan.includes("node --test"), "plan.md instructs using node --test for verification");
 
   const taskPlan = loadTemplate("task-plan");
   assertTrue(taskPlan.includes("## Failure Modes"), "task-plan.md contains ## Failure Modes");
   assertTrue(taskPlan.includes("## Load Profile"), "task-plan.md contains ## Load Profile");
   assertTrue(taskPlan.includes("## Negative Tests"), "task-plan.md contains ## Negative Tests");
+  assertTrue(taskPlan.includes("node --test"), "task-plan.md instructs using node --test for verification");
+  assertTrue(taskPlan.includes("node -e"), "task-plan.md mentions inline node -e as disallowed guidance");
 
   const sliceSummary = loadTemplate("slice-summary");
   assertTrue(sliceSummary.includes("## Operational Readiness"), "slice-summary.md contains ## Operational Readiness");

package/src/resources/extensions/gsd/tests/queue-reorder-ui.test.ts

@@ -0,0 +1,54 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { showQueueReorder } from "../queue-reorder-ui.ts";
+
+const fakeTheme = {
+  fg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+};
+
+describe("queue-reorder-ui", () => {
+  test("keeps cursor visible while scrolling long queue with arrow keys (#4656)", async () => {
+    const originalRowsDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "rows");
+    Object.defineProperty(process.stdout, "rows", { value: 20, configurable: true });
+
+    try {
+      const pending = Array.from({ length: 20 }, (_, idx) => ({
+        id: `M${String(idx + 1).padStart(3, "0")}`,
+        title: `Milestone ${idx + 1}`,
+      }));
+
+      let resolved: { order: string[]; depsToRemove: Array<{ milestone: string; dep: string }> } | null = null;
+      let lastRender: string[] = [];
+
+      const ctx = {
+        hasUI: true,
+        ui: {
+          custom: async (factory: any) => {
+            const component = factory({ requestRender() {} }, fakeTheme, null, (value: any) => {
+              resolved = value;
+            });
+
+            for (let i = 0; i < 15; i++) component.handleInput("\u001b[B");
+            lastRender = component.render(100);
+            component.handleInput("\r");
+            return resolved;
+          },
+        },
+      } as any;
+
+      await showQueueReorder(ctx, [], pending);
+
+      const joined = lastRender.join("\n");
+      assert.ok(joined.includes("M016"), "selected item should stay visible after scrolling");
+      assert.ok(lastRender.length <= 16, `overlay should fit terminal max-height, got ${lastRender.length}`);
+    } finally {
+      if (originalRowsDescriptor) {
+        Object.defineProperty(process.stdout, "rows", originalRowsDescriptor);
+      } else {
+        delete (process.stdout as { rows?: number }).rows;
+      }
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/remediation-completion-guard.test.ts

@@ -1,6 +1,6 @@
 /**
- * Regression test for #2675: completing-milestone dispatch rule must
- * block completion when VALIDATION verdict is "needs-remediation".
+ * Regression tests for non-passing VALIDATION verdicts: completing-milestone
+ * dispatch must block completion when VALIDATION needs remediation or attention.
  *
  * Without this guard, needs-remediation + allSlicesDone causes a loop:
  * complete-milestone dispatched → agent refuses (correct) → no SUMMARY
@@ -66,6 +66,93 @@ test("completing-milestone blocks when VALIDATION verdict is needs-remediation (
   }
 });
 
+test("completing-milestone blocks when VALIDATION verdict is needs-attention (#5747)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-attention-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"),
+      [
+        "---",
+        "verdict: needs-attention",
+        "remediation_round: 0",
+        "---",
+        "",
+        "# Validation Report",
+        "",
+        "Acceptance proof is incomplete and needs human attention.",
+      ].join("\n"),
+    );
+
+    const ctx = {
+      mid: "M001",
+      midTitle: "Test Milestone",
+      basePath: base,
+      state: { phase: "completing-milestone" } as any,
+      prefs: {} as any,
+      session: undefined,
+    };
+
+    const result = await completingRule!.match(ctx);
+
+    assert.ok(result !== null, "rule should match");
+    assert.equal(result!.action, "stop", "should return stop action");
+    if (result!.action === "stop") {
+      assert.equal(result!.level, "warning", "should be warning level (pausable)");
+      assert.ok(
+        result!.reason.includes("needs-attention"),
+        "reason should mention needs-attention",
+      );
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("completing-milestone blocks when VALIDATION verdict is fail (#5920)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-fail-verdict-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"),
+      [
+        "---",
+        "verdict: fail",
+        "---",
+        "",
+        "# Validation Report",
+        "",
+        "Blocking failures remain unresolved.",
+      ].join("\n"),
+    );
+
+    const ctx = {
+      mid: "M001",
+      midTitle: "Test Milestone",
+      basePath: base,
+      state: { phase: "completing-milestone" } as any,
+      prefs: {} as any,
+      session: undefined,
+    };
+
+    const result = await completingRule!.match(ctx);
+
+    assert.ok(result !== null, "rule should match");
+    assert.equal(result!.action, "stop", "should return stop action");
+    if (result!.action === "stop") {
+      assert.equal(result!.level, "warning", "should be warning level (pausable)");
+      assert.ok(
+        result!.reason.includes('verdict is "fail"'),
+        "reason should mention fail verdict",
+      );
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("completing-milestone proceeds normally when VALIDATION verdict is pass (#2675 guard)", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-remediation-"));
   mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });

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

@@ -0,0 +1,52 @@
+// GSD-2 + Repository registry seam tests.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRepositoryRegistryFromPreferences } from "../repository-registry.ts";
+
+test("repository registry includes implicit project root and declared child repos", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-repo-registry-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  mkdirSync(join(base, "frontend"), { recursive: true });
+  mkdirSync(join(base, "backend"), { recursive: true });
+
+  const registry = createRepositoryRegistryFromPreferences(base, {
+    workspace: {
+      mode: "parent",
+      repositories: {
+        frontend: { path: "frontend", role: "web UI", verification: ["npm test"] },
+        backend: { path: "./backend", role: "API", commit_policy: "skip" },
+      },
+    },
+  });
+
+  assert.equal(registry.mode, "parent");
+  assert.equal(registry.projectRoot, base);
+  assert.equal(registry.byId.get("project")?.root, base);
+  assert.equal(registry.byId.get("frontend")?.root, join(base, "frontend"));
+  assert.equal(registry.byId.get("backend")?.root, join(base, "backend"));
+  assert.deepEqual(registry.byId.get("frontend")?.verification, ["npm test"]);
+  assert.equal(registry.byId.get("backend")?.commitPolicy, "skip");
+});
+
+test("repository registry rejects repositories outside project root", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-repo-registry-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+
+  assert.throws(
+    () => createRepositoryRegistryFromPreferences(base, {
+      workspace: {
+        mode: "parent",
+        repositories: {
+          unsafe: { path: "../outside" },
+        },
+      },
+    }),
+    /outside project root/,
+  );
+});

package/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts

@@ -36,7 +36,7 @@ function makeUatProject(): string {
   return base;
 }
 
-test("run-uat dispatch stops after three attempts without a verdict", async () => {
+test("run-uat dispatch skips after three attempts without a verdict", async () => {
   const basePath = makeUatProject();
   const rule = DISPATCH_RULES.find((r) => r.name === "run-uat (post-completion)");
   assert.ok(rule, "run-uat dispatch rule is registered");
@@ -58,8 +58,7 @@ test("run-uat dispatch stops after three attempts without a verdict", async () =
     }
 
     const capped = await rule.match(ctx as any);
-    assert.equal(capped?.action, "stop");
-    assert.match(capped?.reason ?? "", /dispatched 3 times/);
+    assert.equal(capped?.action, "skip");
     assert.equal(getUatCount(basePath, "M001", "S01"), 4);
   } finally {
     rmSync(basePath, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -1,9 +1,11 @@
+// Project/App: GSD-2
+// File Purpose: Verifies GSD session hook widget and footer lifecycle behavior.
+
 /**
- * session-start-footer.test.ts
- *
  * Verifies that register-hooks.ts suppresses the gsd-health widget (not the
- * built-in footer) when isAutoActive() is true, and that setFooter is never
- * called by the extension in either session_start or session_switch.
+ * built-in footer) when isAutoActive() is true, clears stale completion widgets
+ * on inactive session switches, and that setFooter is never called by the
+ * extension in either session_start or session_switch.
  *
  * Testing strategy:
  *   1. Source-code regression guards: structural checks on register-hooks.ts.
@@ -139,6 +141,16 @@ test("session_switch toggles gsd-health from runtime auto state without touching
   widgetCalls.length = 0;
   autoSession.active = false;
   await sessionSwitch!({ reason: "resume" }, ctx);
+  assert.deepEqual(
+    widgetCalls
+      .filter((call) => call.key === "gsd-progress" || call.key === "gsd-outcome")
+      .map((call) => [call.key, call.value]),
+    [
+      ["gsd-progress", undefined],
+      ["gsd-outcome", undefined],
+    ],
+    "session_switch should clear stale GSD completion widgets when auto is inactive",
+  );
   const healthWidgetValues = widgetCalls
     .filter((call) => call.key === "gsd-health")
     .map((call) => call.value);

package/src/resources/extensions/gsd/tests/session-switch-abort-misclassification.test.ts

@@ -5,6 +5,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import {
+  _hasEmptyAgentEndContent,
   _handleSessionSwitchAgentEnd,
   isBareClaudeCodeStreamAbortPlaceholder,
   isClaudeCodeSessionSwitchAbortMessage,
@@ -188,6 +189,15 @@ test("empty-content aborted during session-switch is silently ignored", () => {
   assert.equal(cancelledWith, null);
 });
 
+test("missing agent_end content is classified as empty abort content", () => {
+  // Providers may omit content entirely for a late aborted agent_end. That is
+  // equivalent to empty content and must not pause/cancel the next unit.
+  assert.equal(_hasEmptyAgentEndContent(undefined), true);
+  assert.equal(_hasEmptyAgentEndContent(null), true);
+  assert.equal(_hasEmptyAgentEndContent([]), true);
+  assert.equal(_hasEmptyAgentEndContent([{ type: "text", text: "partial" }]), false);
+});
+
 test("completed assistant content with aborted stopReason during session-switch is ignored", () => {
   // newSession() can abort the just-finished provider stream while the last
   // assistant message still carries the completed unit summary. That is a

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

@@ -3,7 +3,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -12,8 +12,12 @@ import { validatePreferences } from "../preferences-validation.ts";
 import {
   _buildSliceWorkerEnvForTest,
   _resolveSliceParallelMaxWorkersForTest,
+  getSliceOrchestratorState,
   restoreSliceState,
+  resetSliceOrchestrator,
   SLICE_WORKER_AUTO_ARGS,
+  startSliceParallel,
+  stopSliceParallel,
 } from "../slice-parallel-orchestrator.ts";
 
 function readLinuxProcessStartFingerprint(pid: number): string | null {
@@ -50,6 +54,23 @@ function makeTempProject(): string {
   return basePath;
 }
 
+function runGit(basePath: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function initGitProject(basePath: string): void {
+  runGit(basePath, ["init", "--initial-branch=main"]);
+  runGit(basePath, ["config", "user.email", "test@example.com"]);
+  runGit(basePath, ["config", "user.name", "Test User"]);
+  writeFileSync(join(basePath, "README.md"), "initial\n", "utf-8");
+  runGit(basePath, ["add", "README.md"]);
+  runGit(basePath, ["commit", "-m", "initial"]);
+}
+
 function writeSliceOrchestratorState(
   basePath: string,
   worker: {
@@ -111,6 +132,56 @@ describe("slice worker launch contract", () => {
   });
 });
 
+describe("slice-parallel stale worktree handling", () => {
+  it("replaces a stale slice worktree before spawning the worker", async () => {
+    const basePath = makeTempProject();
+    const oldGsdBinPath = process.env.GSD_BIN_PATH;
+    try {
+      initGitProject(basePath);
+      const workerBin = join(basePath, "fake-worker.js");
+      writeFileSync(
+        workerBin,
+        [
+          "process.on('SIGTERM', () => process.exit(0));",
+          "setInterval(() => {}, 1000);",
+        ].join("\n"),
+        "utf-8",
+      );
+      process.env.GSD_BIN_PATH = workerBin;
+
+      const staleWorktree = join(basePath, ".gsd", "worktrees", "M900-S01");
+      mkdirSync(staleWorktree, { recursive: true });
+      writeFileSync(join(staleWorktree, ".git"), "gitdir: /tmp/not-this-repo\n", "utf-8");
+      writeFileSync(join(staleWorktree, "stale-marker"), "stale\n", "utf-8");
+
+      const result = await startSliceParallel(basePath, "M900", [{ id: "S01" }], { maxWorkers: 1 });
+
+      assert.deepEqual(result, { started: ["S01"], errors: [] });
+      assert.equal(existsSync(join(staleWorktree, "stale-marker")), false);
+      assert.equal(lstatSync(join(staleWorktree, ".git")).isFile(), true);
+      assert.match(readFileSync(join(staleWorktree, ".git"), "utf-8"), /^gitdir: /);
+      assert.equal(getSliceOrchestratorState()?.active, true);
+    } finally {
+      const child = getSliceOrchestratorState()?.workers.get("S01")?.process;
+      if (child && child.exitCode === null) {
+        await new Promise<void>((resolve) => {
+          const timeout = setTimeout(resolve, 500);
+          child.once("exit", () => {
+            clearTimeout(timeout);
+            resolve();
+          });
+          child.kill("SIGTERM");
+        });
+      }
+      stopSliceParallel();
+      resetSliceOrchestrator();
+      if (oldGsdBinPath === undefined) delete process.env.GSD_BIN_PATH;
+      else process.env.GSD_BIN_PATH = oldGsdBinPath;
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("slice-parallel-orchestrator recovery identity", () => {
   it("rejects a live PID when the process start fingerprint does not match", () => {
     const basePath = makeTempProject();