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

package/src/resources/extensions/gsd/tests/observability-validator-boundary.test.ts

@@ -0,0 +1,194 @@
+// Regression tests for issue #912:
+// validatePlanBoundary and validateCompleteBoundary must load all task
+// artifact files and collect issues from every file, not just the first.
+//
+// The bug was sequential await-inside-loop loading; the fix batches reads
+// with Promise.all. These tests assert the observable outcome: issues are
+// returned for every task file present, not only one.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { validatePlanBoundary, validateCompleteBoundary } from "../observability-validator.ts";
+import { clearPathCache, _clearGsdRootCache } from "../paths.ts";
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+//
+// Each file is intentionally minimal so it triggers at least one deterministic
+// validation issue (missing ## Steps → empty_steps_section, missing frontmatter
+// observability_surfaces → missing_observability_frontmatter). The exact issue
+// count is not asserted; we only verify that at least one issue refers to each
+// task file path, proving all files were loaded and validated.
+
+const BARE_TASK_PLAN = (id: string) => `# ${id}: Bare Task\n\n## Description\n\nDoes something.\n`;
+
+const BARE_TASK_SUMMARY = (id: string) => `# ${id}-SUMMARY\n\n## Summary\n\nCompleted.\n`;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an isolated temp project root and return its path plus a cleanup
+ * function that clears path caches and removes the directory.
+ */
+function makeProject(): { root: string; cleanup: () => void } {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-obs-boundary-")));
+  return {
+    root,
+    cleanup() {
+      _clearGsdRootCache();
+      clearPathCache();
+      try { rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
+    },
+  };
+}
+
+/**
+ * Create the legacy tasks directory structure inside a temp project root:
+ *   {root}/.gsd/milestones/{mid}/slices/{sid}/tasks/
+ *
+ * Legacy layout is used because flat-phase projects embed tasks as inline
+ * checkboxes in the slice plan file (no tasks/ subdir). The legacy layout
+ * has an explicit tasks/ directory that resolveTasksDir returns.
+ */
+function makeLegacyTasksDir(root: string, mid: string, sid: string): string {
+  const dir = join(root, ".gsd", "milestones", mid, "slices", sid, "tasks");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+// ── validatePlanBoundary ────────────────────────────────────────────────────
+
+test("#912 validatePlanBoundary: issues collected from every task plan file", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const tasksDir = makeLegacyTasksDir(root, "M001", "S01");
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), BARE_TASK_PLAN("T01"), "utf-8");
+  writeFileSync(join(tasksDir, "T02-PLAN.md"), BARE_TASK_PLAN("T02"), "utf-8");
+  writeFileSync(join(tasksDir, "T03-PLAN.md"), BARE_TASK_PLAN("T03"), "utf-8");
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const issues = await validatePlanBoundary(root, "M001", "S01");
+
+  // Every task file must appear in at least one issue — proving all three
+  // were loaded. Before the fix only the last file in the loop would be
+  // validated because the loop re-used a stale `content` binding.
+  const paths = new Set(issues.map(i => i.file));
+  assert.ok(
+    paths.size >= 3,
+    `expected issues from at least 3 task plan files, got paths: ${JSON.stringify([...paths])}`,
+  );
+
+  const t01Issues = issues.filter(i => i.file.includes("T01"));
+  const t02Issues = issues.filter(i => i.file.includes("T02"));
+  const t03Issues = issues.filter(i => i.file.includes("T03"));
+  assert.ok(t01Issues.length > 0, "T01-PLAN.md should produce at least one validation issue");
+  assert.ok(t02Issues.length > 0, "T02-PLAN.md should produce at least one validation issue");
+  assert.ok(t03Issues.length > 0, "T03-PLAN.md should produce at least one validation issue");
+});
+
+test("#912 validatePlanBoundary: no issues when tasks directory is empty", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  // Create the tasks dir but leave it empty — no PLAN files.
+  makeLegacyTasksDir(root, "M001", "S01");
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const issues = await validatePlanBoundary(root, "M001", "S01");
+
+  // No slice plan and no task plans → no issues.
+  assert.strictEqual(issues.length, 0, "empty tasks dir should produce no issues");
+});
+
+test("#912 validatePlanBoundary: returns empty array when basePath has no .gsd dir", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  // Don't create any .gsd structure — resolveTasksDir returns null.
+  const issues = await validatePlanBoundary(root, "M001", "S01");
+
+  assert.strictEqual(issues.length, 0, "missing .gsd layout should produce no issues");
+});
+
+// ── validateCompleteBoundary ─────────────────────────────────────────────────
+
+test("#912 validateCompleteBoundary: issues collected from every task summary file", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const tasksDir = makeLegacyTasksDir(root, "M001", "S01");
+  writeFileSync(join(tasksDir, "T01-SUMMARY.md"), BARE_TASK_SUMMARY("T01"), "utf-8");
+  writeFileSync(join(tasksDir, "T02-SUMMARY.md"), BARE_TASK_SUMMARY("T02"), "utf-8");
+  writeFileSync(join(tasksDir, "T03-SUMMARY.md"), BARE_TASK_SUMMARY("T03"), "utf-8");
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const issues = await validateCompleteBoundary(root, "M001", "S01");
+
+  // Every task file must appear in at least one issue — proving all three
+  // summary files were loaded in parallel and validated.
+  const paths = new Set(issues.map(i => i.file));
+  assert.ok(
+    paths.size >= 3,
+    `expected issues from at least 3 task summary files, got paths: ${JSON.stringify([...paths])}`,
+  );
+
+  const t01Issues = issues.filter(i => i.file.includes("T01"));
+  const t02Issues = issues.filter(i => i.file.includes("T02"));
+  const t03Issues = issues.filter(i => i.file.includes("T03"));
+  assert.ok(t01Issues.length > 0, "T01-SUMMARY.md should produce at least one validation issue");
+  assert.ok(t02Issues.length > 0, "T02-SUMMARY.md should produce at least one validation issue");
+  assert.ok(t03Issues.length > 0, "T03-SUMMARY.md should produce at least one validation issue");
+});
+
+test("#912 validateCompleteBoundary: no issues when tasks directory is empty", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  makeLegacyTasksDir(root, "M001", "S01");
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const issues = await validateCompleteBoundary(root, "M001", "S01");
+
+  assert.strictEqual(issues.length, 0, "empty tasks dir should produce no issues");
+});
+
+test("#912 validateCompleteBoundary: returns empty array when basePath has no .gsd dir", async (t) => {
+  const { root, cleanup } = makeProject();
+  t.after(cleanup);
+
+  _clearGsdRootCache();
+  clearPathCache();
+
+  const issues = await validateCompleteBoundary(root, "M001", "S01");
+
+  assert.strictEqual(issues.length, 0, "missing .gsd layout should produce no issues");
+});

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

@@ -43,7 +43,7 @@ function makeState(): GSDState {
 
 const fakeCtx = {
   model: { provider: "anthropic", baseUrl: "https://api.anthropic.com", contextWindow: 200_000 },
-  modelRegistry: { getAll: () => [], getProviderAuthMode: (_p: string) => "apiKey" as const },
+  modelRegistry: { getAll: () => [], getAvailable: () => [], getProviderAuthMode: (_p: string) => "apiKey" as const },
 } as never;
 const fakePi = { getActiveTools: () => ["read_file", "write_file"] } as never;
 const BASE = "/tmp/orchestrator-legacy-parity";

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

@@ -0,0 +1,339 @@
+// gsd-pi — Orchestrator advance() log coverage.
+//
+// The orchestrator's private methods (findPriorSliceCompletionBlocker,
+// emitUokGate, mergePendingCompleteMilestone) each emit `engine` warnings on
+// their failure paths (orchestrator.ts:660 / :538 / :637). They are only
+// reachable by driving advance() through a real AutoOrchestrator constructed
+// via createAutoOrchestrator. This file builds a minimal fixture (git repo +
+// seeded DB + session lock + registry dispatch rule, modelled on
+// auto-orchestrator.test.ts's makeFixture) and drives advance() into each
+// branch, asserting the log output.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  createAutoOrchestrator,
+  _setProjectionRebuildFnForTests,
+  type OrchestratorContext,
+} from "../auto/orchestrator.ts";
+import type { AutoSessionContext } from "../auto/contracts.ts";
+import { RuleRegistry, setRegistry, resetRegistry } from "../rule-registry.ts";
+import type { UnifiedRule } from "../rule-types.ts";
+import {
+  closeDatabase,
+  insertAssessment,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+  _getAdapter,
+} from "../gsd-db.ts";
+import { resolveExpectedArtifactPath } from "../auto-artifact-paths.ts";
+import { AutoSession } from "../auto/session.ts";
+import { acquireSessionLock, releaseSessionLock } from "../session-lock.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import { invalidateStateCache } from "../state.ts";
+import {
+  drainLogs,
+  setStderrLoggingEnabled,
+  _resetLogs,
+  type LogEntry,
+} from "../workflow-logger.ts";
+
+const SESSION_CONTEXT: AutoSessionContext = { basePath: "/tmp/project", trigger: "manual" };
+
+function gitInit(base: string): void {
+  execFileSync("git", ["init", "--initial-branch=main"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: base, stdio: "ignore" });
+  writeFileSync(join(base, ".gitkeep"), "");
+  execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "initial"], { cwd: base, stdio: "ignore" });
+}
+
+interface FixtureOptions {
+  /** Override the session's originalBasePath (used by findPriorSliceCompletionBlocker's guard). */
+  originalBasePath?: string;
+  /** The dispatch decision the registry rule returns. */
+  dispatch?: UnifiedRule["where"];
+  /** Drop the gate_runs table after seeding so emitUokGate's insertGateRun throws (:538 path). */
+  dropGateRuns?: boolean;
+}
+
+interface Fixture {
+  base: string;
+  session: AutoSession;
+  orchestrator: ReturnType<typeof createAutoOrchestrator>;
+  cleanup(): void;
+}
+
+function makeFixture(opts: FixtureOptions = {}): Fixture {
+  const base = mkdtempSync(join(tmpdir(), "gsd-orch-logs-"));
+  gitInit(base);
+
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const sliceDir = join(milestoneDir, "slices", "S01");
+  mkdirSync(join(sliceDir, "tasks"), { recursive: true });
+
+  invalidateAllCaches();
+  invalidateStateCache();
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active", risk: "low", depends: [], demo: "", sequence: 1 });
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task", status: "active" });
+  if (opts.dropGateRuns) {
+    // Break the gate_runs sink so UokGateRunner.run → insertGateRun throws,
+    // exercising emitUokGate's catch (orchestrator.ts:538).
+    _getAdapter()!.exec("DROP TABLE gate_runs");
+  }
+
+  writeFileSync(
+    join(milestoneDir, "M001-ROADMAP.md"),
+    ["# M001: Milestone", "", "**Vision:** Fixture", "", "## Slices", "", "- [ ] **S01: Slice** `risk:low` `depends:[]`", ""].join("\n"),
+  );
+  writeFileSync(
+    join(sliceDir, "S01-PLAN.md"),
+    ["# S01: Slice", "", "**Goal:** g", "**Demo:** d", "", "## Tasks", "", "- [ ] **T01: Task** `est:1h`", ""].join("\n"),
+  );
+
+  acquireSessionLock(base);
+
+  const session = new AutoSession();
+  session.basePath = base;
+  // originalBasePath feeds resolveWorktreeProjectRoot inside
+  // findPriorSliceCompletionBlocker → getMainBranch(guardBasePath). Pointing it
+  // at a non-git directory makes branch discovery throw → :660 warning.
+  session.originalBasePath = opts.originalBasePath ?? base;
+  session.currentMilestoneId = "M001";
+  session.resourceVersionOnStart = null;
+
+  const ctx: OrchestratorContext = {
+    ctx: { model: {}, modelRegistry: { getAll: () => [], getAvailable: () => [] }, ui: { notify() {} } } as never,
+    pi: { getActiveTools: () => [] } as never,
+    dispatchBasePath: base,
+    runtimeBasePath: base,
+    session,
+  };
+
+  const rule: UnifiedRule = {
+    name: "fixture-dispatch",
+    when: "dispatch",
+    evaluation: "first-match",
+    where: opts.dispatch ?? (async () => ({
+      action: "dispatch",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      prompt: "fixture-prompt",
+    })),
+    then: (r) => r,
+  };
+  setRegistry(new RuleRegistry([rule]));
+
+  const orchestrator = createAutoOrchestrator(ctx);
+
+  return {
+    base,
+    session,
+    orchestrator,
+    cleanup() {
+      resetRegistry();
+      try { releaseSessionLock(base); } catch { /* */ }
+      try { closeDatabase(); } catch { /* */ }
+      try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+    },
+  };
+}
+
+/** Capture log entries emitted during fn, with stderr suppressed. */
+async function captureLogs<T>(fn: () => Promise<T>): Promise<{ result: T; logs: LogEntry[] }> {
+  const previous = setStderrLoggingEnabled(false);
+  _resetLogs();
+  try {
+    const result = await fn();
+    return { result, logs: drainLogs() };
+  } finally {
+    _resetLogs();
+    setStderrLoggingEnabled(previous);
+  }
+}
+
+// orchestrator.ts:660 — findPriorSliceCompletionBlocker catches a getMainBranch
+// failure and logs `branch discovery failed, falling back to main`. Triggered
+// by pointing session.originalBasePath at a non-git directory.
+test("advance() logs an engine warning when branch discovery fails (orchestrator.ts:660)", async (t) => {
+  // A second temp dir that is deliberately NOT a git repo.
+  const nonGit = mkdtempSync(join(tmpdir(), "gsd-orch-logs-nongit-"));
+  const f = makeFixture({ originalBasePath: nonGit });
+  t.after(() => {
+    f.cleanup();
+    rmSync(nonGit, { recursive: true, force: true });
+  });
+
+  const { logs } = await captureLogs(() => f.orchestrator.advance());
+
+  const branchWarn = logs.find(
+    (e) => e.component === "engine" && e.severity === "warn" && /branch discovery failed/u.test(e.message),
+  );
+  assert.ok(
+    branchWarn,
+    "an engine warning must be logged when getMainBranch fails (got: " +
+      logs.filter((e) => e.component === "engine").map((e) => e.message).join(" | ") + ")",
+  );
+  assert.match(branchWarn!.message, /branch discovery failed, falling back to main/u);
+});
+
+// orchestrator.ts:538 — emitUokGate catches a UokGateRunner.run failure and logs
+// `uok gate emit failed`. Gates are enabled by default (uok.gates.enabled ?? true),
+// and runner.run persists via insertGateRun; dropping the gate_runs table makes
+// that persistence throw, surfacing through the catch.
+test("advance() logs an engine warning when the uok gate emit fails (orchestrator.ts:538)", async (t) => {
+  const f = makeFixture({ dropGateRuns: true });
+  t.after(() => f.cleanup());
+
+  const { logs } = await captureLogs(() => f.orchestrator.advance());
+
+  const uokFail = logs.find(
+    (e) => e.component === "engine" && e.severity === "warn" && /uok gate emit failed/u.test(e.message),
+  );
+  assert.ok(
+    uokFail,
+    "an engine warning must be logged when UokGateRunner.run fails (got: " +
+      logs.filter((e) => e.component === "engine").map((e) => e.message).join(" | ") + ")",
+  );
+  assert.match(uokFail!.message, /uok gate emit failed/u);
+  assert.equal(uokFail!.context?.file, "orchestrator.ts");
+  assert.ok(uokFail!.context?.gateId, "the failing gate id must be captured in context");
+});
+
+// orchestrator.ts:637 — mergePendingCompleteMilestone catches a
+// rebuildMarkdownProjectionsFromDb failure after the system-owned milestone
+// merge and logs `markdown projection rebuild after settlement merge failed`.
+// Reached only when advance() hits a merge-pending settlement (auto-worktree,
+// complete milestone, proven closeout, no remaining units). We build that state
+// (real git worktree + closed milestone + SUMMARY artifact, modelled on
+// milestone-settlement.test.ts), inject a throwing rebuild via the test seam,
+// and assert the engine warning.
+test("advance() logs an engine warning when the post-settlement projection rebuild fails (orchestrator.ts:637)", async (t) => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-orch-logs-settle-"));
+  // Real git repo at the project root.
+  execFileSync("git", ["init", "-b", "main"], { cwd: projectRoot, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: projectRoot, stdio: "ignore" });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: projectRoot, stdio: "ignore" });
+  writeFileSync(join(projectRoot, "README.md"), "# fixture\n");
+  execFileSync("git", ["add", "."], { cwd: projectRoot, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "chore: init"], { cwd: projectRoot, stdio: "ignore" });
+
+  // Auto-worktree for M001 — required so evaluateAllCompleteSettlement returns
+  // merge-pending (isActiveUnmergedWorktree must be true).
+  const worktree = join(projectRoot, ".gsd", "worktrees", "M001");
+  mkdirSync(dirname(worktree), { recursive: true });
+  execFileSync("git", ["worktree", "add", "-b", "milestone/M001", worktree, "HEAD"], { cwd: projectRoot, stdio: "ignore" });
+
+  // Seed a closed milestone + proven closeout SUMMARY so proveMilestoneCloseout
+  // passes and the settlement resolves to merge-pending.
+  mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+  invalidateAllCaches();
+  invalidateStateCache();
+  openDatabase(join(projectRoot, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice One", status: "complete" });
+  insertTask({
+    id: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    title: "Task One",
+    status: "complete",
+    verificationResult: "passed",
+  });
+  insertAssessment({
+    path: ".gsd/milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass\n",
+  });
+  // Create the milestone projection dir in the worktree BEFORE resolving the
+  // summary artifact path (resolveExpectedArtifactPath needs the dir to exist).
+  const milestoneProjDir = join(worktree, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneProjDir, { recursive: true });
+  // A content-bearing legacy milestone dir requires at least one non-META file
+  // (dirIsContentBearingLegacyMilestone) so the layout sniffer treats it as a
+  // real legacy milestone rather than a metadata-only placeholder.
+  writeFileSync(join(milestoneProjDir, "M001-CONTEXT.md"), "# M001\n");
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", "M001", worktree);
+  assert.ok(summaryPath, "complete-milestone summary path must resolve");
+  mkdirSync(dirname(summaryPath), { recursive: true });
+  writeFileSync(summaryPath, "# Milestone One\n\nComplete.\n");
+
+  acquireSessionLock(projectRoot);
+
+  const session = new AutoSession();
+  session.basePath = worktree;
+  session.originalBasePath = projectRoot;
+  session.currentMilestoneId = "M001";
+  session.resourceVersionOnStart = null;
+
+  const ctx: OrchestratorContext = {
+    ctx: { model: {}, modelRegistry: { getAll: () => [], getAvailable: () => [] }, ui: { notify() {} } } as never,
+    pi: { getActiveTools: () => [] } as never,
+    dispatchBasePath: worktree,
+    runtimeBasePath: worktree,
+    session,
+  };
+
+  // Registry rule returns skip (no remaining units) so advance() reaches the
+  // no-remaining-units settlement branch and calls mergePendingCompleteMilestone.
+  const rule: UnifiedRule = {
+    name: "settle-no-units",
+    when: "dispatch",
+    evaluation: "first-match",
+    where: async () => ({ action: "skip", matchedRule: "settle-no-units" }),
+    then: (r) => r,
+  };
+  setRegistry(new RuleRegistry([rule]));
+
+  const orchestrator = createAutoOrchestrator(ctx);
+
+  // Inject a throwing projection rebuild so :637 fires after exitMilestone
+  // completes the system-owned merge. restoreDefault() in finally keeps the
+  // seam production-neutral for every other test in the process.
+  const restoreDefault = _setProjectionRebuildFnForTests(async () => {
+    throw new Error("forced projection rebuild failure");
+  });
+
+  t.after(() => {
+    restoreDefault();
+    resetRegistry();
+    try { releaseSessionLock(projectRoot); } catch { /* */ }
+    try { closeDatabase(); } catch { /* */ }
+    try { execFileSync("git", ["worktree", "remove", "--force", worktree], { cwd: projectRoot, stdio: "ignore" }); } catch { /* */ }
+    try { rmSync(projectRoot, { recursive: true, force: true }); } catch { /* */ }
+  });
+
+  const previous = setStderrLoggingEnabled(false);
+  _resetLogs();
+  let logs: LogEntry[] = [];
+  try {
+    await orchestrator.advance();
+    logs = drainLogs();
+  } finally {
+    _resetLogs();
+    setStderrLoggingEnabled(previous);
+  }
+
+  const rebuildWarn = logs.find(
+    (e) => e.component === "engine" && e.severity === "warn" &&
+      /markdown projection rebuild after settlement merge failed/u.test(e.message),
+  );
+  assert.ok(
+    rebuildWarn,
+    "an engine warning must be logged when the post-settlement projection rebuild fails (got: " +
+      logs.filter((e) => e.component === "engine").map((e) => e.message).join(" | ") + ")",
+  );
+  assert.match(rebuildWarn!.message, /forced projection rebuild failure/u);
+});

package/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts

@@ -160,7 +160,10 @@ describe("auditOrphanedMilestoneBranches", () => {
       `warning should mention stranded milestone/M001 and in-progress state; got: ${JSON.stringify(result.warnings)}`,
     );
     assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
-    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+    // #812 — worktree-configured isolation must recover as "worktree" even when
+    // the worktree directory is absent on disk, so recovery re-materializes the
+    // worktree from the branch instead of checking it out in the project root.
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "worktree");
     assert.equal(result.blockingStrandedWork?.commitsAhead, 1);
 
     // Branch must still exist
@@ -168,6 +171,54 @@ describe("auditOrphanedMilestoneBranches", () => {
     assert.ok(branches.includes("milestone/M001"), "in-progress branch must be preserved");
   });
 
+  test("#812 — in-progress orphan under branch isolation recovers as branch", () => {
+    // Same stranded scenario but the project is configured for branch-mode
+    // isolation, where there is never a worktree to re-materialize. Recovery
+    // must stay "branch".
+    run("git checkout -b milestone/M001", dir);
+    writeFileSync(join(dir, "feature.txt"), "in-progress work\n");
+    run("git add feature.txt", dir);
+    run("git commit -m \"in-progress work on M001\"", dir);
+    run("git checkout main", dir);
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "branch");
+
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+  });
+
+  test("#812-followup — worktree-mode project degrades to branch recovery when branch is already checked out at root", () => {
+    // Simulates the leftover state from the pre-fix #812 recovery path: the
+    // old code checked out milestone/<id> in the project root instead of
+    // creating a worktree. On the next bootstrap:
+    //   - isolationMode === "worktree"
+    //   - HEAD at project root === "milestone/M001"
+    //   - no linked worktree directory on disk
+    //
+    // Requesting worktree recovery in this state calls `git worktree add` for
+    // a branch git already considers "in use by another worktree" (the main
+    // worktree counts), causing bootstrap to abort with GSD_LOCK_HELD.
+    // The fix detects the root checkout and degrades to "branch" so the
+    // session resumes on the already-checked-out branch without failing.
+    run("git checkout -b milestone/M001", dir);
+    writeFileSync(join(dir, "feature.txt"), "in-progress work\n");
+    run("git add feature.txt", dir);
+    run("git commit -m \"in-progress work on M001\"", dir);
+    // NOTE: stay on milestone/M001 — do NOT check out main.
+    // This simulates the project root being on the milestone branch.
+
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.equal(result.blockingStrandedWork?.milestoneId, "M001");
+    // Must degrade to "branch" — worktree creation would fail because the
+    // branch is already checked out at the project root.
+    assert.equal(result.blockingStrandedWork?.recoveryMode, "branch");
+  });
+
   test("#4762 — also surfaces worktree directory for in-progress orphan when present", () => {
     // In-progress + unmerged + physical worktree directory — the full primary scenario.
     run("git checkout -b milestone/M001", dir);