@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/tests/dispatch-history.test.ts

@@ -326,3 +326,105 @@ test("rehydrate degrades to an empty window without a scope or ledger", () => {
   assert.equal(noDb.rehydrate(), 0);
   assert.equal(noDb.getRecentWindow().length, 0);
 });
+
+// ─── Session-scoped rehydration (#852) ───────────────────────────────────────
+//
+// Without session scoping, two consecutive finalize-retry failures from a
+// PREVIOUS session persist in unit_dispatches and are loaded into the
+// DispatchHistory window on the NEXT session's start() → rehydrate() call.
+// The first advance's recordDispatch fills the window (matchingCount >=
+// STUCK_WINDOW_SIZE) and detectStuck Rule 1 fires immediately, killing
+// auto-mode before any new unit runs. The resolveTraceId option scopes
+// rehydrate() to the current session so only that session's dispatches
+// populate the window.
+
+test("#852: rehydrate with resolveTraceId ignores prior-session entries (empty window on fresh session)", (t) => {
+  const f = makeLedgerFixture(t);
+
+  // Prior session: six consecutive finalize-retry failures for the same unit.
+  // recordDispatchClaim uses the trace_id from the fixture's claim() helper
+  // (random per-iteration). We insert them directly so we control the trace_id.
+  for (let i = 0; i < STUCK_WINDOW_SIZE; i++) {
+    const claim = recordDispatchClaim({
+      traceId: "prior-session-trace-id",
+      workerId: f.worker,
+      milestoneLeaseToken: f.token,
+      milestoneId: "M001",
+      unitType: "discuss-milestone",
+      unitId: "M001",
+    });
+    assert.equal(claim.ok, true);
+    if (!claim.ok) return;
+    markFailed(claim.dispatchId, { errorSummary: "finalize-retry" });
+  }
+
+  // Unscoped rehydrate loads all prior entries — the window is full.
+  const unscopedHistory = createDispatchHistory({ resolveScopeId: () => f.base });
+  unscopedHistory.rehydrate();
+  assert.equal(
+    unscopedHistory.getRecentWindow().length,
+    STUCK_WINDOW_SIZE,
+    "unscoped rehydrate sees prior-session entries",
+  );
+
+  // New session: rehydrate scoped to a fresh trace_id that has never been
+  // written to unit_dispatches → 0 rows → the window stays empty.
+  const freshTraceId = "new-session-trace-id-never-in-db";
+  const freshHistory = createDispatchHistory({
+    resolveScopeId: () => f.base,
+    resolveTraceId: () => freshTraceId,
+  });
+  const count = freshHistory.rehydrate();
+  assert.equal(count, 0, "session-scoped rehydrate excludes prior-session entries");
+  assert.equal(freshHistory.getRecentWindow().length, 0);
+
+  // The first dispatch of the new session should not trigger stuck (window is
+  // empty, so Rule 1/2/3/4 cannot fire on a single-entry window).
+  freshHistory.recordDispatch("discuss-milestone", "M001");
+  assert.equal(
+    freshHistory.detectStuck(),
+    null,
+    "first dispatch in new session must not trigger stuck detection",
+  );
+});
+
+test("#852: rehydrate with resolveTraceId still includes current-session entries", (t) => {
+  const f = makeLedgerFixture(t);
+  const currentTraceId = "current-session-trace";
+
+  // Prior session entry (different trace_id).
+  const oldClaim = recordDispatchClaim({
+    traceId: "old-session-trace",
+    workerId: f.worker,
+    milestoneLeaseToken: f.token,
+    milestoneId: "M001",
+    unitType: "plan-milestone",
+    unitId: "M001",
+  });
+  assert.equal(oldClaim.ok, true);
+  if (oldClaim.ok) markFailed(oldClaim.dispatchId, { errorSummary: "finalize-retry" });
+
+  // Current session entries (matching trace_id).
+  for (let i = 0; i < 2; i++) {
+    const claim = recordDispatchClaim({
+      traceId: currentTraceId,
+      workerId: f.worker,
+      milestoneLeaseToken: f.token,
+      milestoneId: "M001",
+      unitType: "plan-milestone",
+      unitId: "M001",
+    });
+    assert.equal(claim.ok, true);
+    if (!claim.ok) return;
+    markFailed(claim.dispatchId, { errorSummary: "finalize-retry" });
+  }
+
+  // Scoped to current session: only the 2 current entries are loaded.
+  const history = createDispatchHistory({
+    resolveScopeId: () => f.base,
+    resolveTraceId: () => currentTraceId,
+  });
+  const count = history.rehydrate();
+  assert.equal(count, 2, "session-scoped rehydrate includes current-session entries");
+  assert.equal(history.getRecentWindow().length, 2);
+});

package/src/resources/extensions/gsd/tests/dispatch-logs.test.ts

@@ -0,0 +1,103 @@
+// gsd-pi — Dispatch-path log coverage.
+//
+// `resolveDispatch` delegates to the rule registry when one is initialized
+// (auto-dispatch.ts:1818-1835). If `getRegistry()` throws — e.g. the registry
+// was never initialized or was reset — the catch logs a `dispatch` warning
+// ("registry dispatch failed, falling back to inline rules") and falls through
+// to the inline DISPATCH_RULES loop. That warning is the operator's only signal
+// that dispatch silently degraded from registry-driven to inline; no test
+// asserted it. This file pins it.
+//
+// Strategy: resetRegistry() so getRegistry() throws, then call resolveDispatch
+// with a minimal no-DB context. We assert the warning lands and that the
+// function still returns a DispatchAction rather than throwing (resilience).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { resolveDispatch, DISPATCH_RULES, type DispatchContext } from "../auto-dispatch.ts";
+import {
+  convertDispatchRules,
+  getRegistry,
+  initRegistry,
+  resetRegistry,
+} from "../rule-registry.ts";
+import {
+  drainLogs,
+  setStderrLoggingEnabled,
+  _resetLogs,
+  type LogEntry,
+} from "../workflow-logger.ts";
+
+/**
+ * Build a minimal DispatchContext that passes resolveDispatch's early guards
+ * without a database:
+ *  - isDbAvailable() is false → the closed-milestone guard is skipped.
+ *  - activeMilestone is null → the activeMid/scope mismatch guards are skipped.
+ * So execution reaches the registry delegation block.
+ */
+function makeMinimalCtx(basePath: string): DispatchContext {
+  return {
+    basePath,
+    mid: "M001",
+    midTitle: "Test Milestone",
+    prefs: undefined,
+    state: {
+      activeMilestone: null,
+      activeSlice: null,
+      activeTask: null,
+      phase: "unhandled",
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "",
+      registry: [],
+    } as unknown as DispatchContext["state"],
+  };
+}
+
+test("resolveDispatch logs a dispatch warning and falls back to inline rules when the registry is uninitialized", async () => {
+  // Snapshot and clear the singleton so getRegistry() throws inside resolveDispatch.
+  let previousExists = false;
+  try {
+    getRegistry();
+    previousExists = true;
+  } catch {
+    previousExists = false;
+  }
+  resetRegistry();
+
+  const base = mkdtempSync(join(tmpdir(), "gsd-dispatch-logs-"));
+  const previousStderr = setStderrLoggingEnabled(false);
+  _resetLogs();
+  let logs: LogEntry[] = [];
+  try {
+    // resolveDispatch must NOT throw — it catches the registry failure, logs,
+    // and falls through to inline DISPATCH_RULES.
+    const action = await resolveDispatch(makeMinimalCtx(base));
+    assert.ok(action, "resolveDispatch must still return a DispatchAction after registry failure");
+    logs = drainLogs();
+  } finally {
+    _resetLogs();
+    setStderrLoggingEnabled(previousStderr);
+    rmSync(base, { recursive: true, force: true });
+    // Restore a usable registry for any subsequent test in the process.
+    initRegistry(convertDispatchRules(DISPATCH_RULES));
+    if (!previousExists) resetRegistry();
+  }
+
+  const warn = logs.find((e) => e.component === "dispatch" && e.severity === "warn");
+  assert.ok(warn, "a dispatch warning must be logged when the registry is unavailable");
+  assert.match(
+    warn!.message,
+    /registry dispatch failed, falling back to inline rules/u,
+    "warning must identify the registry fallback reason",
+  );
+  assert.match(
+    warn!.message,
+    /not initialized/u,
+    "warning must carry the underlying getRegistry() error detail",
+  );
+});

package/src/resources/extensions/gsd/tests/dispatch-missing-task-plans.test.ts

@@ -69,9 +69,12 @@ function makeContextFor(
 // ─── Scaffold helpers ──────────────────────────────────────────────────────
 
 function scaffoldSlicePlan(basePath: string, mid: string, sid: string): void {
-  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid);
+  // Flat-phase: phases/NN-slug/NN-MM-PLAN.md
+  const phaseNum = parseInt(mid.match(/^M0*(\d+)/i)?.[1] || '1', 10);
+  const planNum = parseInt(sid.match(/^S0*(\d+)/i)?.[1] || '1', 10);
+  const dir = join(basePath, ".gsd", "phases", `${String(phaseNum).padStart(2, '0')}-test`);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${sid}-PLAN.md`), [
+  writeFileSync(join(dir, `${String(phaseNum).padStart(2, '0')}-${String(planNum).padStart(2, '0')}-PLAN.md`), [
     `# ${sid}: Third Slice`,
     "",
     "## Tasks",
@@ -82,9 +85,10 @@ function scaffoldSlicePlan(basePath: string, mid: string, sid: string): void {
 }
 
 function scaffoldMilestoneContext(basePath: string, mid: string): void {
-  const dir = join(basePath, ".gsd", "milestones", mid);
+  const phaseNum = parseInt(mid.match(/^M0*(\d+)/i)?.[1] || '1', 10);
+  const dir = join(basePath, ".gsd", "phases", `${String(phaseNum).padStart(2, '0')}-test`);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${mid}-CONTEXT.md`), [
+  writeFileSync(join(dir, `${String(phaseNum).padStart(2, '0')}-CONTEXT.md`), [
     `# ${mid}: Test Milestone`,
     "",
     "Context for dispatch recovery tests.",
@@ -93,15 +97,9 @@ function scaffoldMilestoneContext(basePath: string, mid: string): void {
 }
 
 function scaffoldTaskPlan(basePath: string, mid: string, sid: string, tid: string): void {
-  const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks");
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${tid}-PLAN.md`), [
-    `# ${tid}: Do something`,
-    "",
-    "## Steps",
-    "- [ ] Step 1",
-    "",
-  ].join("\n"));
+  // Flat-phase: no per-task plan files. This is a no-op — tasks live as
+  // checkboxes inside the slice plan. Kept for backward-compat with tests
+  // that call it; does nothing in flat-phase.
 }
 
 // ─── Tests ─────────────────────────────────────────────────────────────────
@@ -110,7 +108,9 @@ test("dispatch: missing task plan triggers plan-slice (not stop) — issue #909"
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
-  // Slice plan exists with tasks, but tasks/ directory is empty
+  // Slice plan exists with tasks. In flat-phase, tasks are checkboxes inside
+  // the slice plan (no per-task files), so this is the NORMAL state — dispatch
+  // should proceed to execute-task, not recover with plan-slice.
   scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
 
@@ -118,10 +118,9 @@ test("dispatch: missing task plan triggers plan-slice (not stop) — issue #909"
   const result = await resolveDispatch(ctx);
 
   assert.equal(result.action, "dispatch", "should dispatch, not stop");
-  assert.ok(result.action === "dispatch" && result.unitType === "plan-slice",
-    `unitType should be plan-slice, got: ${result.action === "dispatch" ? result.unitType : "(stop)"}`);
-  assert.ok(result.action === "dispatch" && result.unitId === "M002/S03",
-    `unitId should be M002/S03, got: ${result.action === "dispatch" ? result.unitId : "(stop)"}`);
+  // Flat-phase: tasks embedded in slice plan → execute-task (not plan-slice recovery)
+  assert.ok(result.action === "dispatch" && result.unitType === "execute-task",
+    `unitType should be execute-task (tasks in slice plan), got: ${result.action === "dispatch" ? result.unitType : "(stop)"}`);
 });
 
 test("dispatch: closed milestone is not implicitly recovered or reopened", async (t) => {
@@ -153,7 +152,10 @@ test("dispatch: present task plan proceeds to execute-task normally", async (t)
 
   scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
-  scaffoldTaskPlan(tmp, "M002", "S03", "T01");
+  // Flat-phase: tasks are checkboxes inside the slice plan (no per-task PLAN files).
+  // scaffoldTaskPlan is intentionally NOT called here — creating a milestones/ dir
+  // as a side effect would confuse milestonesDir() into treating this as a legacy
+  // layout, breaking slice plan resolution and causing discuss-milestone dispatch.
 
   const ctx = makeContext(tmp);
   const result = await resolveDispatch(ctx);
@@ -280,8 +282,9 @@ test("dispatch: artifact checks trust active session basePath even when original
 });
 
 test("dispatch: plan-slice recovery loop — second call after plan-slice still recovers cleanly", async (t) => {
-  // Simulate: plan-slice ran but T01-PLAN.md is still missing (e.g. agent crashed mid-write).
-  // Dispatch should still re-dispatch plan-slice, not hard-stop.
+  // Flat-phase: tasks are checkboxes inside the slice plan, so there are no
+  // per-task plan files to be "missing". Dispatch should go to execute-task
+  // (the normal flow), not plan-slice recovery.
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-loop-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
@@ -291,19 +294,22 @@ test("dispatch: plan-slice recovery loop — second call after plan-slice still
   const ctx = makeContext(tmp);
   const r1 = await resolveDispatch(ctx);
   assert.equal(r1.action, "dispatch");
-  assert.ok(r1.action === "dispatch" && r1.unitType === "plan-slice");
+  assert.ok(r1.action === "dispatch" && r1.unitType === "execute-task",
+    "flat-phase: should dispatch execute-task (tasks in slice plan)");
 
-  // Still no task plan written — dispatch again
+  // Second dispatch should also go to execute-task (idempotent)
   const r2 = await resolveDispatch(ctx);
   assert.equal(r2.action, "dispatch");
-  assert.ok(r2.action === "dispatch" && r2.unitType === "plan-slice",
-    "should keep dispatching plan-slice until task plans appear");
+  assert.ok(r2.action === "dispatch" && r2.unitType === "execute-task",
+    "should keep dispatching execute-task");
 });
 
 test("dispatch: missing task plan recovery logs root/worktree diagnostic when debug enabled — issue #6194", async (t) => {
-  // The diagnostic exists to surface root/worktree artifact-path mismatches
-  // when the recovery rule fires. It must report the paths that were checked
-  // so a stuck session can be traced — not just that recovery happened.
+  // Flat-phase: tasks are embedded in the slice plan, so the recovery rule
+  // (which fires when per-task plan files are missing) doesn't apply.
+  // The diagnostic log entry is only produced in the legacy layout.
+  // This test verifies the normal flat-phase dispatch path doesn't crash
+  // with debug enabled.
   const tmp = mkdtempSync(join(tmpdir(), "gsd-6194-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
@@ -315,25 +321,8 @@ test("dispatch: missing task plan recovery logs root/worktree diagnostic when de
 
   const ctx = makeContext(tmp);
   const result = await resolveDispatch(ctx);
-  assert.ok(result.action === "dispatch" && result.unitType === "plan-slice",
-    "recovery rule must fire for the diagnostic to be exercised");
-
-  const logPath = getDebugLogPath();
-  assert.ok(logPath, "debug log path should be set while debug is enabled");
-
-  const entry = readFileSync(logPath!, "utf8")
-    .trim()
-    .split("\n")
-    .filter(Boolean)
-    .map((line) => JSON.parse(line) as Record<string, unknown>)
-    .find((e) => e.event === "dispatch-missing-task-plan-recovery");
-
-  assert.ok(entry, "diagnostic event should be logged when recovery fires in debug mode");
-  assert.equal(entry!.basePathUsedForArtifactChecks, tmp);
-  assert.equal(entry!.artifactExists, false, "task plan is genuinely absent");
-  assert.equal(entry!.expectedTaskPlanExists, false, "expected task plan is genuinely absent");
-  assert.equal(entry!.projectionArtifactExists, false, "projection task plan is genuinely absent");
-  assert.equal(entry!.hasRootWorktreeMismatch, false, "root/worktree mismatch should be false in single-root scenario");
-  assert.equal(typeof entry!.expectedTaskPlanPath, "string");
-  assert.equal(typeof entry!.projectionTaskPlanPath, "string");
+  // Flat-phase: dispatch goes to execute-task (tasks in slice plan)
+  assert.ok(result.action === "dispatch",
+    "should dispatch without crashing in debug mode");
+  // Flat-phase: no recovery diagnostic entry expected (tasks in slice plan)
 });

package/src/resources/extensions/gsd/tests/dispatch-reactive-logs.test.ts

@@ -0,0 +1,98 @@
+// gsd-pi — Dispatch reactive graph derivation log coverage.
+//
+// The "executing → reactive-execute" rule wraps its graph derivation in a
+// best-effort catch (auto-dispatch.ts:1492-1496) that logs a `dispatch` ERROR
+// "reactive graph derivation failed" and falls through to sequential execution.
+// The catch is otherwise unreachable because every operation it wraps
+// (loadSliceTaskIO, deriveTaskGraph, saveReactiveState) is internally
+// defensive — so we inject a throwing derive function via the sanctioned
+// setReactiveGraphDeriveFnForTest seam (mirroring the :1809 / :637 pattern) to
+// deterministically exercise the failure path.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  resolveDispatch,
+  DISPATCH_RULES,
+  setReactiveGraphDeriveFnForTest,
+  type DispatchContext,
+} from "../auto-dispatch.ts";
+import type { GSDState } from "../types.ts";
+import {
+  drainLogs,
+  setStderrLoggingEnabled,
+  _resetLogs,
+  type LogEntry,
+} from "../workflow-logger.ts";
+import { convertDispatchRules, initRegistry, getRegistry, resetRegistry } from "../rule-registry.ts";
+
+function makeExecutingCtx(base: string): DispatchContext {
+  return {
+    basePath: base,
+    mid: "M001",
+    midTitle: "Milestone",
+    state: {
+      phase: "executing",
+      activeMilestone: { id: "M001", title: "Milestone", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      activeTask: { id: "T01", title: "Task" },
+      registry: [],
+      blockers: [],
+    } as unknown as GSDState,
+    // Explicit opt-in keeps the legacy min-ready threshold (2) and ensures the
+    // rule proceeds past the enabled/maxParallel guards into the derivation try.
+    prefs: { reactive_execution: { enabled: true, max_parallel: 2 } } as DispatchContext["prefs"],
+  };
+}
+
+test("reactive rule logs a dispatch error when graph derivation throws (auto-dispatch.ts:1494)", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-reactive-logs-"));
+  // Minimal slice projection so the rule's earlier filesystem guards resolve.
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01\n\n## Tasks\n\n- [ ] **T01: A**\n", "utf-8");
+
+  // Snapshot + initialize the registry so resolveDispatch uses the inline rules.
+  let previousExists = false;
+  try { getRegistry(); previousExists = true; } catch { previousExists = false; }
+  initRegistry(convertDispatchRules(DISPATCH_RULES));
+
+  // Inject a throwing derive fn so the rule's try block (auto-dispatch.ts:1414+)
+  // throws before any defensive operation, hitting the :1494 catch.
+  const restoreDerive = setReactiveGraphDeriveFnForTest(async () => {
+    throw new Error("forced graph derivation failure");
+  });
+
+  const previousStderr = setStderrLoggingEnabled(false);
+  _resetLogs();
+  let logs: LogEntry[] = [];
+  try {
+    // resolveDispatch must NOT throw — the rule catches the derivation failure
+    // and falls through to sequential execution.
+    await resolveDispatch(makeExecutingCtx(base));
+    logs = drainLogs();
+  } finally {
+    _resetLogs();
+    setStderrLoggingEnabled(previousStderr);
+    restoreDerive();
+    initRegistry(convertDispatchRules(DISPATCH_RULES));
+    if (!previousExists) resetRegistry();
+    rmSync(base, { recursive: true, force: true });
+    void t;
+  }
+
+  const err = logs.find(
+    (e) => e.component === "dispatch" && e.severity === "error" && /reactive graph derivation failed/u.test(e.message),
+  );
+  assert.ok(
+    err,
+    "a dispatch ERROR must be logged when reactive graph derivation fails (got: " +
+      logs.filter((e) => e.component === "dispatch").map((e) => e.message).join(" | ") + ")",
+  );
+  assert.equal(err!.message, "reactive graph derivation failed");
+  assert.match(err!.context?.error ?? "", /forced graph derivation failure/u);
+});

package/src/resources/extensions/gsd/tests/dist-redirect.mjs

@@ -44,6 +44,11 @@ export function resolve(specifier, context, nextResolve) {
   } else if (specifier.startsWith("@earendil-works/pi-agent-core/") || specifier.startsWith("@gsd/pi-agent-core/")) {
     const subpath = specifier.replace(/^@[^/]+\/pi-agent-core\//, "").replace(/\.js$/, ".ts");
     specifier = new URL(`packages/pi-agent-core/src/${subpath}`, ROOT).href;
+  } else if (specifier === "@gsd/agent-core") {
+    specifier = new URL("packages/gsd-agent-core/src/index.ts", ROOT).href;
+  } else if (specifier.startsWith("@gsd/agent-core/")) {
+    const subpath = specifier.replace(/^@gsd\/agent-core\//, "").replace(/\.js$/, ".ts");
+    specifier = new URL(`packages/gsd-agent-core/src/${subpath}`, ROOT).href;
   } else if (specifier === "@gsd/native") {
     specifier = new URL("packages/native/src/index.ts", ROOT).href;
   } else if (specifier.startsWith("@gsd/native/")) {
@@ -115,6 +120,8 @@ export function load(url, context, nextLoad) {
     url = url.replace('/dist/index.js', '/src/index.ts');
   } else if (url.includes('/packages/pi-agent-core/dist/index.js')) {
     url = url.replace('/dist/index.js', '/src/index.ts');
+  } else if (url.includes('/packages/gsd-agent-core/dist/')) {
+    url = url.replace('/dist/', '/src/').replace(/\.js$/, '.ts');
   } else if (url.includes('/packages/pi-tui/dist/index.js')) {
     url = url.replace('/dist/index.js', '/src/index.ts');
   }

package/src/resources/extensions/gsd/tests/doctor-git-checks-autoresolve.test.ts

@@ -0,0 +1,149 @@
+// Project/App: gsd-pi
+// File Purpose: Doctor attempts safe conflict auto-resolution before hard-blocking auto-mode (#849).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runGSDDoctor } from "../doctor.ts";
+import { closeDatabase } from "../gsd-db.js";
+
+function runGit(args: string[], cwd: string): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+}
+
+function tryGit(args: string[], cwd: string): void {
+  try {
+    runGit(args, cwd);
+  } catch {
+    // Expected to fail for conflicting merges — the conflict state is what we want.
+  }
+}
+
+function makeRepoWithConflict(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-autoresolve-"));
+  runGit(["init", "-b", "main"], base);
+  runGit(["config", "user.name", "Test User"], base);
+  runGit(["config", "user.email", "test@example.com"], base);
+
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  mkdirSync(join(base, "src"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "STATE.md"), "base state\n", "utf-8");
+  writeFileSync(join(base, "src", "app.js"), "base app\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "chore: init"], base);
+
+  runGit(["checkout", "-b", "feature"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "feature state\n", "utf-8");
+  writeFileSync(join(base, "src", "app.js"), "feature app\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: feature edits"], base);
+
+  runGit(["checkout", "main"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "main state\n", "utf-8");
+  writeFileSync(join(base, "src", "app.js"), "main app\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: main edits"], base);
+
+  // Conflicting merge — leaves unmerged paths + MERGE_HEAD.
+  tryGit(["merge", "feature"], base);
+  return base;
+}
+
+test.after(() => {
+  closeDatabase();
+});
+
+test("doctor auto-resolves safe .gsd/ conflicts and only blocks on manual paths", async (t) => {
+  const base = makeRepoWithConflict();
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const report = await runGSDDoctor(base, { isolationMode: "none" });
+
+  const conflictIssue = report.issues.find((issue) => issue.code === "unresolved_git_conflicts");
+  assert.ok(conflictIssue, "manual conflict should still be reported");
+  assert.match(conflictIssue!.message, /src\/app\.js/, "manual path should be listed");
+  assert.doesNotMatch(
+    conflictIssue!.message,
+    /\.gsd\/STATE\.md/,
+    "safe .gsd/ path should have been auto-resolved out of the conflict list",
+  );
+});
+
+test("doctor clears conflicts entirely when all unmerged paths are safe", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-autoresolve-safe-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  runGit(["init", "-b", "main"], base);
+  runGit(["config", "user.name", "Test User"], base);
+  runGit(["config", "user.email", "test@example.com"], base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "STATE.md"), "base\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "chore: init"], base);
+
+  runGit(["checkout", "-b", "feature"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "feature\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: edit"], base);
+
+  runGit(["checkout", "main"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "main\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: edit"], base);
+
+  tryGit(["merge", "feature"], base);
+
+  const report = await runGSDDoctor(base, { isolationMode: "none" });
+
+  assert.ok(
+    !report.issues.some((issue) => issue.code === "unresolved_git_conflicts"),
+    "no manual conflicts should remain after safe auto-resolve",
+  );
+  assert.ok(
+    !existsSync(join(base, ".git", "MERGE_HEAD")),
+    "merge-state markers should be cleared in the same pass",
+  );
+});
+
+test("doctor --dry-run does not mutate git state when safe conflicts are present", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-autoresolve-dryrun-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  runGit(["init", "-b", "main"], base);
+  runGit(["config", "user.name", "Test User"], base);
+  runGit(["config", "user.email", "test@example.com"], base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "STATE.md"), "base\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "chore: init"], base);
+
+  runGit(["checkout", "-b", "feature"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "feature\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: edit"], base);
+
+  runGit(["checkout", "main"], base);
+  writeFileSync(join(base, ".gsd", "STATE.md"), "main\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "feat: edit"], base);
+
+  tryGit(["merge", "feature"], base);
+
+  // dry-run must not mutate git state even when all conflicts are safe
+  const report = await runGSDDoctor(base, { dryRun: true, isolationMode: "none" });
+
+  // MERGE_HEAD must still exist — dry-run is read-only
+  assert.ok(
+    existsSync(join(base, ".git", "MERGE_HEAD")),
+    "dry-run must not clear merge-state markers",
+  );
+  // The conflict should still be reported (unresolved paths are reported as-is)
+  assert.ok(
+    report.issues.some((issue) => issue.code === "unresolved_git_conflicts"),
+    "dry-run should still report the conflict without resolving it",
+  );
+});