gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/src/resources/extensions/gsd/tests/dispatch-complete-milestone-guard.test.ts

@@ -55,6 +55,11 @@ describe("completing-milestone dispatch guard (#4324)", () => {
 
     const classifyCall = source.indexOf("classifyMilestoneSummaryContent", summaryGuard);
     assert.ok(classifyCall > -1, "SUMMARY mismatch handling should classify summary content");
+    const dbGateBeforeClassify = source.indexOf("existingSummary && isDbAvailable()", summaryGuard);
+    assert.ok(
+      dbGateBeforeClassify === -1 || dbGateBeforeClassify > classifyCall,
+      "SUMMARY classification must not be gated on DB availability",
+    );
 
     const reconcileCall = source.indexOf('updateMilestoneStatus(mid, "complete"', summaryGuard);
     assert.ok(reconcileCall > -1, "successful SUMMARY should reconcile DB to complete");

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

@@ -255,6 +255,31 @@ test("dispatch guard skips completed milestone with SUMMARY even if it has unche
   );
 });
 
+test("dispatch guard does not skip failed milestone SUMMARY without blocker prose", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M001"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+
+  insertMilestone({ id: "M001", title: "Previous" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Core", status: "complete", depends: [], sequence: 1 });
+  insertSlice({ id: "S02", milestoneId: "M001", title: "Unfinished", status: "pending", depends: ["S01"], sequence: 2 });
+
+  insertMilestone({ id: "M002", title: "Current" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Start", status: "pending", depends: [], sequence: 1 });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), "# M001\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M001", "M001-SUMMARY.md"),
+    "---\nstatus: failed\n---\n# M001 Summary\nRecovery stopped.\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M002/S01"),
+    "Cannot dispatch plan-slice M002/S01: earlier slice M001/S02 is not complete.",
+  );
+});
+
 test("dispatch guard works without git repo", (t) => {
   const repo = setupRepo();
   t.after(() => teardownRepo(repo));

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

@@ -57,6 +57,17 @@ function scaffoldSlicePlan(basePath: string, mid: string, sid: string): void {
   ].join("\n"));
 }
 
+function scaffoldMilestoneContext(basePath: string, mid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-CONTEXT.md`), [
+    `# ${mid}: Test Milestone`,
+    "",
+    "Context for dispatch recovery tests.",
+    "",
+  ].join("\n"));
+}
+
 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 });
@@ -76,6 +87,7 @@ test("dispatch: missing task plan triggers plan-slice (not stop) — issue #909"
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
   // Slice plan exists with tasks, but tasks/ directory is empty
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
 
   const ctx = makeContext(tmp);
@@ -92,6 +104,7 @@ test("dispatch: present task plan proceeds to execute-task normally", async (t)
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-ok-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
   scaffoldTaskPlan(tmp, "M002", "S03", "T01");
 
@@ -111,6 +124,7 @@ test("dispatch: plan-slice recovery loop — second call after plan-slice still
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-loop-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
 
   const ctx = makeContext(tmp);

package/src/resources/extensions/gsd/tests/double-merge-guard.test.ts

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AutoSession } from "../auto/session.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -20,7 +21,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const completeIdx = phasesSrc.indexOf('state.phase === "complete"');
     assert.ok(completeIdx > 0, "phases.ts should have a 'complete' phase check");
 
-    const afterComplete = phasesSrc.slice(completeIdx, completeIdx + 600);
+    const afterComplete = extractSourceRegion(phasesSrc, 'state.phase === "complete"');
     const mergeIdx = afterComplete.indexOf("deps.resolver.mergeAndExit");
     const flagIdx = afterComplete.indexOf("s.milestoneMergedInPhases = true");
 
@@ -42,7 +43,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const allCompleteIdx = phasesSrc.indexOf("incomplete.length === 0");
     assert.ok(allCompleteIdx > 0, "phases.ts should have an all-milestones-complete check");
 
-    const afterAllComplete = phasesSrc.slice(allCompleteIdx, allCompleteIdx + 800);
+    const afterAllComplete = extractSourceRegion(phasesSrc, "incomplete.length === 0");
     const mergeIdx = afterAllComplete.indexOf("deps.resolver.mergeAndExit");
     const flagIdx = afterAllComplete.indexOf("s.milestoneMergedInPhases = true");
 
@@ -64,7 +65,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
     assert.ok(step4Idx > 0, "auto.ts should have Step 4 worktree exit");
 
-    const step4Block = autoSrc.slice(step4Idx, step4Idx + 600);
+    const step4Block = extractSourceRegion(autoSrc, "Step 4: Auto-worktree exit");
     assert.ok(
       step4Block.includes("milestoneMergedInPhases"),
       "stopAuto Step 4 must check milestoneMergedInPhases before merging",

package/src/resources/extensions/gsd/tests/empty-content-abort-loop.test.ts

@@ -13,6 +13,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const RECOVERY_PATH = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts");
@@ -30,7 +31,7 @@ test("agent-end-recovery.ts does not pause on aborted messages with empty conten
   assert.ok(abortIdx > -1, "abort handler must exist in agent-end-recovery.ts");
 
   // Extract the region around the abort handler (enough to see the guard logic)
-  const abortRegion = source.slice(Math.max(0, abortIdx - 200), abortIdx + 600);
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"', { fromIdx: abortIdx });
 
   // Must check for empty content before pausing
   assert.ok(
@@ -48,7 +49,7 @@ test("agent-end-recovery.ts routes empty-content aborted messages to resolveAgen
   assert.ok(abortIdx > -1, "abort handler must exist");
 
   // Get the full abort handling block (from the if to the next stopReason check or success path)
-  const afterAbort = source.slice(abortIdx, abortIdx + 800);
+  const afterAbort = extractSourceRegion(source, 'stopReason === "aborted"');
 
   // The abort block must have a code path that calls resolveAgentEnd (for empty-content case)
   assert.ok(
@@ -63,7 +64,7 @@ test("agent-end-recovery.ts checks for errorMessage presence in abort handler (#
   const abortIdx = source.indexOf('stopReason === "aborted"');
   assert.ok(abortIdx > -1, "abort handler must exist");
 
-  const abortRegion = source.slice(abortIdx, abortIdx + 600);
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"');
 
   // Fatal aborts should have error context (errorMessage field).
   // The handler should check for this to distinguish fatal from non-fatal aborts.

package/src/resources/extensions/gsd/tests/execution-entry-missing-context-4671.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Regression tests for #4671 — execution-entry phase + missing CONTEXT.md.
+ *
+ * When a milestone advances to an execution-entry phase (executing /
+ * summarizing / validating-milestone / completing-milestone) without
+ * `CONTEXT.md` on disk, the `pre-planning (no context) → discuss-milestone`
+ * rule no longer fires and the plan-v2 gate only blocks. This rule provides
+ * the recovery by redispatching to discuss-milestone.
+ *
+ * Exercises the dispatch rule from DISPATCH_RULES directly with a
+ * DispatchContext built against a real temp directory.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DISPATCH_RULES, type DispatchContext } from "../auto-dispatch.ts";
+import type { GSDState, Phase } from "../types.ts";
+
+const RULE_NAME_TOKEN = "execution-entry phase (no context)";
+
+function findRule() {
+  const matches = DISPATCH_RULES.filter((r) => r.name.includes(RULE_NAME_TOKEN));
+  if (matches.length !== 1) {
+    throw new Error(
+      `expected exactly one dispatch rule containing "${RULE_NAME_TOKEN}", found ${matches.length}`,
+    );
+  }
+  return matches[0];
+}
+
+function buildState(phase: Phase): GSDState {
+  return {
+    activeMilestone: { id: "M001", title: "Test milestone" },
+    activeSlice: null,
+    activeTask: null,
+    phase,
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "",
+    registry: [],
+  };
+}
+
+function makeBasePath(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), `gsd-4671-${prefix}-`));
+  mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true });
+  return dir;
+}
+
+function buildCtx(basePath: string, state: GSDState): DispatchContext {
+  return {
+    basePath,
+    mid: "M001",
+    midTitle: "Test milestone",
+    state,
+    prefs: undefined,
+  };
+}
+
+describe("#4671 execution-entry phase missing-context recovery", () => {
+  const executionEntryPhases: Phase[] = [
+    "executing",
+    "summarizing",
+    "validating-milestone",
+    "completing-milestone",
+  ];
+
+  for (const phase of executionEntryPhases) {
+    test(`phase=${phase} with missing CONTEXT.md → dispatches discuss-milestone`, async () => {
+      const basePath = makeBasePath(`missing-${phase}`);
+      try {
+        const action = await findRule().match(buildCtx(basePath, buildState(phase)));
+        assert.ok(action, "rule must return an action when CONTEXT.md is missing");
+        assert.strictEqual(action!.action, "dispatch");
+        if (action!.action === "dispatch") {
+          assert.strictEqual(action!.unitType, "discuss-milestone");
+          assert.strictEqual(action!.unitId, "M001");
+          assert.ok(typeof action!.prompt === "string" && action!.prompt.length > 0);
+        }
+      } finally {
+        rmSync(basePath, { recursive: true, force: true });
+      }
+    });
+  }
+
+  test("phase=executing with CONTEXT.md present → falls through", async () => {
+    const basePath = makeBasePath("has-context");
+    try {
+      writeFileSync(
+        join(basePath, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "# M001 Context\n\nSome real context.\n",
+      );
+      const action = await findRule().match(buildCtx(basePath, buildState("executing")));
+      assert.strictEqual(action, null, "rule must fall through when CONTEXT.md exists");
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("phase=executing accepts finalized CONTEXT.md from GSD_PROJECT_ROOT fallback", async () => {
+    const projectRoot = makeBasePath("project-root-context");
+    const worktreeBase = makeBasePath("worktree-context");
+    const prevProjectRoot = process.env.GSD_PROJECT_ROOT;
+    try {
+      writeFileSync(
+        join(projectRoot, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "# M001 Context\n\nFinalized context at project root.\n",
+      );
+      process.env.GSD_PROJECT_ROOT = projectRoot;
+
+      const action = await findRule().match(buildCtx(worktreeBase, buildState("executing")));
+      assert.strictEqual(
+        action,
+        null,
+        "rule must align with plan-v2 project-root fallback before redispatching",
+      );
+    } finally {
+      if (prevProjectRoot === undefined) {
+        delete process.env.GSD_PROJECT_ROOT;
+      } else {
+        process.env.GSD_PROJECT_ROOT = prevProjectRoot;
+      }
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(worktreeBase, { recursive: true, force: true });
+    }
+  });
+
+  test("phase=pre-planning does not trigger this rule (handled by upstream rule)", async () => {
+    const basePath = makeBasePath("pre-planning");
+    try {
+      const action = await findRule().match(buildCtx(basePath, buildState("pre-planning")));
+      assert.strictEqual(
+        action,
+        null,
+        "rule must only target execution-entry phases; pre-planning is handled elsewhere",
+      );
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("empty CONTEXT.md (whitespace only) → rule still fires", async () => {
+    const basePath = makeBasePath("empty-context");
+    try {
+      writeFileSync(
+        join(basePath, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "   \n\t\n",
+      );
+      const action = await findRule().match(buildCtx(basePath, buildState("summarizing")));
+      assert.ok(action, "rule must fire when CONTEXT.md is empty/whitespace-only");
+      if (action?.action === "dispatch") {
+        assert.strictEqual(action.unitType, "discuss-milestone");
+      }
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("rule ordering: fires BEFORE execution-entry phase handlers", () => {
+    const recoveryIdx = DISPATCH_RULES.findIndex((r) => r.name.includes(RULE_NAME_TOKEN));
+    const summarizingIdx = DISPATCH_RULES.findIndex((r) =>
+      r.name.startsWith("summarizing → complete-slice"),
+    );
+    assert.ok(recoveryIdx > -1, "recovery rule must exist");
+    assert.ok(summarizingIdx > -1, "summarizing rule must exist");
+    assert.ok(
+      recoveryIdx < summarizingIdx,
+      `recovery rule (idx ${recoveryIdx}) must come before summarizing rule (idx ${summarizingIdx}) so it can redispatch before the plan-v2 gate blocks`,
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/file-lock.test.ts

@@ -52,7 +52,7 @@ test("withFileLock: executes callback when file does not exist", async () => {
   }
 });
 
-test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
+test("withFileLockSync: throws ELOCKED by default (no silent fallback)", () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -65,19 +65,56 @@ test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
   const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = withFileLockSync(filePath, () => {
-      called++;
-      return "fallback-ok";
-    });
+    assert.throws(
+      () => {
+        withFileLockSync(
+          filePath,
+          () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLockSync: onLocked=\"skip\" runs callback unlocked on ELOCKED", () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = withFileLockSync(
+      filePath,
+      () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     release();
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
+test("withFileLock: throws ELOCKED by default (no silent fallback)", async () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -90,12 +127,49 @@ test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
   const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = await withFileLock(filePath, async () => {
-      called++;
-      return "fallback-ok";
-    });
+    await assert.rejects(
+      async () => {
+        await withFileLock(
+          filePath,
+          async () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    await release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLock: onLocked=\"skip\" runs callback unlocked on ELOCKED", async () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = await withFileLock(
+      filePath,
+      async () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     await release();
     rmSync(dir, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -16,7 +16,7 @@
  * isolated unit testing.
  */
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 import {
   withTimeout,
   FINALIZE_PRE_TIMEOUT_MS,
@@ -163,7 +163,7 @@ function getRunFinalizeBody(phasesSource: string): string {
   assertTrue(preVerIdx > 0, "postUnitPreVerification should appear in runFinalize");
 
   // The first withTimeout should wrap postUnitPreVerification (not postUnitPostVerification)
-  const firstWithTimeout = fnBody.slice(preTimeoutIdx, preTimeoutIdx + 200);
+  const firstWithTimeout = extractSourceRegion(fnBody, "withTimeout(");
   assertTrue(
     firstWithTimeout.includes("postUnitPreVerification"),
     "first withTimeout in runFinalize should wrap postUnitPreVerification",

package/src/resources/extensions/gsd/tests/forensics-hook-key-parse.test.ts

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const gsdDir = join(__dirname, "..");
@@ -43,7 +44,7 @@ describe("forensics hook compound key parsing (#2826)", () => {
   it("detectMissingArtifacts delegates to splitCompletedKey", () => {
     const fnStart = forensicsSrc.indexOf("function detectMissingArtifacts(");
     assert.ok(fnStart !== -1, "detectMissingArtifacts must exist in forensics.ts");
-    const fnBody = forensicsSrc.slice(fnStart, fnStart + 1000);
+    const fnBody = extractSourceRegion(forensicsSrc, "function detectMissingArtifacts(");
     assert.ok(
       fnBody.includes("splitCompletedKey("),
       "detectMissingArtifacts must call splitCompletedKey() rather than inline the split logic",

package/src/resources/extensions/gsd/tests/forensics-worktree-telemetry.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Tests for the #4764 forensics integration — verifies that
+ * buildForensicReport picks up worktree telemetry aggregates and emits
+ * anomalies for orphans and auto-exits with unmerged work.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, mkdirSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import {
+  emitWorktreeOrphaned,
+  emitAutoExit,
+  emitWorktreeCreated,
+  emitWorktreeMerged,
+} from "../worktree-telemetry.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const gsdDir = join(__dirname, "..");
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-for-tel-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+describe("#4764 forensics + worktree telemetry integration", () => {
+  const forensicsSrc = readFileSync(join(gsdDir, "forensics.ts"), "utf-8");
+
+  it("forensics.ts imports the telemetry summarizer", () => {
+    assert.ok(
+      forensicsSrc.includes("summarizeWorktreeTelemetry"),
+      "forensics must consume the telemetry aggregator",
+    );
+  });
+
+  it("forensics.ts does NOT call queryJournal directly (memory guard)", () => {
+    // The same invariant guarded by forensics-journal.test.ts — re-asserted
+    // here so this feature change doesn't regress it.
+    assert.ok(
+      !forensicsSrc.includes("queryJournal("),
+      "forensics.ts must route journal reads through aggregators, not queryJournal",
+    );
+  });
+
+  it("ForensicReport includes worktreeTelemetry field", () => {
+    assert.ok(
+      forensicsSrc.includes("worktreeTelemetry"),
+      "report shape must include the telemetry summary",
+    );
+  });
+
+  it("formatReportForPrompt gates Worktree Telemetry section on signal", () => {
+    assert.ok(
+      forensicsSrc.includes("Worktree Telemetry"),
+      "prompt formatter must include a Worktree Telemetry section",
+    );
+  });
+
+  it("new anomaly types worktree-orphan and worktree-unmerged-exit exist on the union", () => {
+    assert.ok(forensicsSrc.includes('"worktree-orphan"'));
+    assert.ok(forensicsSrc.includes('"worktree-unmerged-exit"'));
+  });
+
+  it("buildForensicReport surfaces worktree-orphan anomaly when the journal shows an in-progress orphan", async () => {
+    const base = makeTmpBase();
+    try {
+      // Seed the journal with one in-progress orphan event
+      emitWorktreeOrphaned(base, "M001", {
+        reason: "in-progress-unmerged",
+        commitsAhead: 3,
+        worktreeDirExists: true,
+      });
+
+      const { buildForensicReport } = await import("../forensics.ts");
+      const report = await buildForensicReport(base);
+
+      const orphanAnomalies = report.anomalies.filter(a => a.type === "worktree-orphan");
+      assert.ok(orphanAnomalies.length >= 1, `expected a worktree-orphan anomaly; got ${JSON.stringify(report.anomalies.map(a => a.type))}`);
+      assert.equal(orphanAnomalies[0].severity, "warning", "in-progress orphan should be a warning");
+
+      // Aggregate fields surface in the telemetry summary
+      assert.ok(report.worktreeTelemetry, "report should carry the telemetry summary");
+      assert.equal(report.worktreeTelemetry!.orphansDetected, 1);
+      assert.equal(report.worktreeTelemetry!.orphansByReason["in-progress-unmerged"], 1);
+    } finally { cleanup(base); }
+  });
+
+  it("buildForensicReport surfaces worktree-unmerged-exit anomaly when auto-exit left work unmerged", async () => {
+    const base = makeTmpBase();
+    try {
+      emitAutoExit(base, { reason: "pause", milestoneId: "M002", milestoneMerged: false });
+      emitAutoExit(base, { reason: "stop", milestoneId: "M002", milestoneMerged: false });
+      emitAutoExit(base, { reason: "all-complete", milestoneId: "M001", milestoneMerged: true });
+
+      const { buildForensicReport } = await import("../forensics.ts");
+      const report = await buildForensicReport(base);
+
+      const unmergedExitAnomalies = report.anomalies.filter(a => a.type === "worktree-unmerged-exit");
+      assert.equal(unmergedExitAnomalies.length, 1, "exactly one aggregate unmerged-exit anomaly");
+      assert.equal(unmergedExitAnomalies[0].severity, "warning");
+      assert.ok(
+        unmergedExitAnomalies[0].summary.includes("2"),
+        "summary should mention the count (2 unmerged exits out of 3 total)",
+      );
+
+      assert.equal(report.worktreeTelemetry!.exitsWithUnmergedWork, 2);
+    } finally { cleanup(base); }
+  });
+
+  it("buildForensicReport emits no telemetry anomalies when there are no signals", async () => {
+    const base = makeTmpBase();
+    try {
+      // Healthy path — worktree created and merged without incident
+      emitWorktreeCreated(base, "M001");
+      emitWorktreeMerged(base, "M001", {
+        reason: "milestone-complete",
+        durationMs: 250,
+        conflict: false,
+      });
+      emitAutoExit(base, { reason: "all-complete", milestoneId: "M001", milestoneMerged: true });
+
+      const { buildForensicReport } = await import("../forensics.ts");
+      const report = await buildForensicReport(base);
+
+      const telemetryAnomalies = report.anomalies.filter(a =>
+        a.type === "worktree-orphan" || a.type === "worktree-unmerged-exit"
+      );
+      assert.deepStrictEqual(telemetryAnomalies, [], "no orphans, no unmerged exits → no telemetry anomalies");
+
+      assert.equal(report.worktreeTelemetry!.worktreesCreated, 1);
+      assert.equal(report.worktreeTelemetry!.worktreesMerged, 1);
+      assert.equal(report.worktreeTelemetry!.orphansDetected, 0);
+      assert.equal(report.worktreeTelemetry!.exitsWithUnmergedWork, 0);
+    } finally { cleanup(base); }
+  });
+});