gsd-pi 2.65.0-dev.d0517ff → 2.66.0

package/src/resources/extensions/gsd/auto-start.ts

@@ -47,6 +47,10 @@ import {
   nativeGetCurrentBranch,
   nativeDetectMainBranch,
   nativeCheckoutBranch,
+  nativeBranchList,
+  nativeBranchListMerged,
+  nativeBranchDelete,
+  nativeWorktreeRemove,
 } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import {
@@ -56,6 +60,7 @@ import {
 } from "./worktree.js";
 import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
+import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { initMetrics } from "./metrics.js";
 import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
@@ -76,6 +81,7 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
+  rmSync,
   statSync,
   unlinkSync,
 } from "node:fs";
@@ -117,6 +123,123 @@ export async function openProjectDbIfPresent(basePath: string): Promise<void> {
   }
 }
 
+/**
+ * Audit for orphaned milestone branches at bootstrap.
+ *
+ * After a milestone completes, the teardown step (merge branch → main,
+ * delete branch, remove worktree) runs as a post-completion engine step.
+ * If the session ends between completion and teardown, the branch and
+ * worktree are orphaned — the DB says "complete" so auto-mode won't
+ * re-enter the milestone, and the teardown is never retried.
+ *
+ * This audit runs on every fresh bootstrap to catch that gap:
+ * 1. Lists all local `milestone/*` branches.
+ * 2. For each, checks if the milestone's DB status is "complete".
+ * 3. If the branch is already merged into main → deletes the branch
+ *    and cleans up any orphaned worktree directory (safe, no data loss).
+ * 4. If the branch is NOT merged → preserves it and warns the user
+ *    so they can merge manually (data safety first).
+ *
+ * Returns a summary of actions taken for the caller to surface via notify.
+ */
+export function auditOrphanedMilestoneBranches(
+  basePath: string,
+  isolationMode: "worktree" | "branch" | "none",
+): { recovered: string[]; warnings: string[] } {
+  const recovered: string[] = [];
+  const warnings: string[] = [];
+
+  // Skip in none mode — no milestone branches are created
+  if (isolationMode === "none") return { recovered, warnings };
+
+  // Skip if DB not available — can't determine completion status
+  if (!isDbAvailable()) return { recovered, warnings };
+
+  let milestoneBranches: string[];
+  try {
+    milestoneBranches = nativeBranchList(basePath, "milestone/*");
+  } catch {
+    // git branch list failed — skip audit
+    return { recovered, warnings };
+  }
+
+  if (milestoneBranches.length === 0) return { recovered, warnings };
+
+  // Detect main branch for merge-check
+  let mainBranch: string;
+  try {
+    mainBranch = nativeDetectMainBranch(basePath);
+  } catch {
+    mainBranch = "main";
+  }
+
+  // Get branches already merged into main
+  let mergedBranches: Set<string>;
+  try {
+    mergedBranches = new Set(nativeBranchListMerged(basePath, mainBranch, "milestone/*"));
+  } catch {
+    mergedBranches = new Set();
+  }
+
+  for (const branch of milestoneBranches) {
+    const milestoneId = branch.replace(/^milestone\//, "");
+    const milestone = getMilestone(milestoneId);
+
+    // Only audit completed milestones
+    if (!milestone || milestone.status !== "complete") continue;
+
+    const isMerged = mergedBranches.has(branch);
+
+    if (isMerged) {
+      // Branch is merged — safe to delete branch and clean up worktree dir
+      try {
+        nativeBranchDelete(basePath, branch, true);
+        recovered.push(`Deleted merged branch ${branch} for completed milestone ${milestoneId}.`);
+      } catch (err) {
+        warnings.push(`Failed to delete merged branch ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Clean up orphaned worktree directory if it exists
+      const wtDir = getWorktreeDir(basePath, milestoneId);
+      if (existsSync(wtDir)) {
+        // Try git worktree remove first (handles registered worktrees)
+        try {
+          nativeWorktreeRemove(basePath, wtDir, true);
+        } catch (e) {
+          // Not a registered worktree — expected for orphaned dirs
+          logWarning("engine", `worktree remove failed (expected for orphaned dirs): ${e instanceof Error ? e.message : String(e)}`);
+        }
+
+        // If the directory still exists after git worktree remove (either it
+        // wasn't registered or the remove was a noop), fall back to direct
+        // filesystem removal — but only inside .gsd/worktrees/ for safety (#2365).
+        if (existsSync(wtDir)) {
+          if (isInsideWorktreesDir(basePath, wtDir)) {
+            try {
+              rmSync(wtDir, { recursive: true, force: true });
+              recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+            } catch (err2) {
+              warnings.push(`Failed to remove worktree directory for ${milestoneId}: ${err2 instanceof Error ? err2.message : String(err2)}`);
+            }
+          } else {
+            warnings.push(`Orphaned worktree directory for ${milestoneId} is outside .gsd/worktrees/ — skipping removal for safety.`);
+          }
+        } else {
+          recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`);
+        }
+      }
+    } else {
+      // Branch is NOT merged — preserve for safety, warn the user
+      warnings.push(
+        `Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
+        `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`,
+      );
+    }
+  }
+
+  return { recovered, warnings };
+}
+
 export async function bootstrapAutoSession(
   s: AutoSession,
   ctx: ExtensionCommandContext,
@@ -300,6 +423,26 @@ export async function bootstrapAutoSession(
     // derivation (queue-order, task status) works on a cold start (#2841).
     await openProjectDbIfPresent(base);
 
+    // ── Orphaned milestone branch audit ──
+    // Catches completed milestones whose teardown (merge + branch delete)
+    // was lost due to session ending between completion and teardown.
+    // Must run after DB open and before worktree entry.
+    try {
+      const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode());
+      for (const msg of auditResult.recovered) {
+        ctx.ui.notify(`Orphan audit: ${msg}`, "info");
+      }
+      for (const msg of auditResult.warnings) {
+        ctx.ui.notify(`Orphan audit: ${msg}`, "warning");
+      }
+      if (auditResult.recovered.length > 0) {
+        debugLog("orphan-audit", { recovered: auditResult.recovered, warnings: auditResult.warnings });
+      }
+    } catch (err) {
+      // Non-fatal — the audit is defensive, never block bootstrap
+      logWarning("bootstrap", `orphaned milestone branch audit failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
     let state = await deriveState(base);
 
     // Stale worktree state recovery (#654)

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -15,7 +15,7 @@ import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-dis
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
 import { deriveState } from "../state.js";
-import { formatOverridesSection, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
+import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
 import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
 
@@ -72,6 +72,8 @@ export async function buildBeforeAgentStartResult(
   const systemContent = loadPrompt("system", {
     bundledSkillsTable: buildBundledSkillsTable(),
     templatesDir: getTemplatesDir(),
+    shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
+    shortcutShell: formatShortcut("Ctrl+Alt+B"),
   });
   const loadedPreferences = loadEffectiveGSDPreferences();
   if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -8,6 +8,7 @@ import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
 import { projectRoot } from "../context.js";
+import { formatShortcut } from "../../files.js";
 
 export function showHelp(ctx: ExtensionCommandContext): void {
   const lines = [
@@ -24,12 +25,12 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
     "",
     "VISIBILITY",
-    "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",
+    `  /gsd status         Show progress dashboard  (${formatShortcut("Ctrl+Alt+G")})`,
     "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
-    "  /gsd notifications  View persistent notification history  [clear|tail|filter]  (Ctrl+Alt+N)",
+    `  /gsd notifications  View persistent notification history  [clear|tail|filter]  (${formatShortcut("Ctrl+Alt+N")})`,
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",

package/src/resources/extensions/gsd/files.ts

@@ -70,6 +70,25 @@ export function clearParseCache(): void {
   for (const cb of _cacheClearCallbacks) cb();
 }
 
+// ─── Platform shortcuts ───────────────────────────────────────────────────
+
+const IS_MAC = process.platform === "darwin";
+
+/**
+ * Format a keyboard shortcut for the current OS.
+ * Input: modifier key combo like "Ctrl+Alt+G"
+ * Output: "⌃⌥G" on macOS, "Ctrl+Alt+G" on Windows/Linux.
+ */
+export function formatShortcut(combo: string): string {
+  if (!IS_MAC) return combo;
+  return combo
+    .replace(/Ctrl\+Alt\+/i, "⌃⌥")
+    .replace(/Ctrl\+/i, "⌃")
+    .replace(/Alt\+/i, "⌥")
+    .replace(/Shift\+/i, "⇧")
+    .replace(/Cmd\+/i, "⌘");
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 /** Extract the text after a heading at a given level, up to the next heading of same or higher level. */

package/src/resources/extensions/gsd/notification-overlay.ts

@@ -1,6 +1,6 @@
 // GSD Extension — Notification History Overlay
 // Scrollable panel showing all persisted notifications with severity filtering.
-// Toggled with Ctrl+Alt+N or opened from /gsd notifications.
+// Toggled with Ctrl+Alt+N (⌃⌥N on macOS) or opened from /gsd notifications.
 
 import type { Theme } from "@gsd/pi-coding-agent";
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";

package/src/resources/extensions/gsd/notification-widget.ts

@@ -6,6 +6,7 @@
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { getUnreadCount, readNotifications } from "./notification-store.js";
+import { formatShortcut } from "./files.js";
 
 // ─── Pure rendering ──���────────────────────────���─────────────────────────
 
@@ -24,7 +25,7 @@ export function buildNotificationWidgetLines(): string[] {
     ? latest.message.slice(0, msgMax - 1) + "…"
     : latest.message;
 
-  return [`  ${icon} [${badge}]  ${truncated}  (Ctrl+Alt+N to view)`];
+  return [`  ${icon} [${badge}]  ${truncated}  (${formatShortcut("Ctrl+Alt+N")} to view)`];
 }
 
 // ─── Widget init ────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -2,7 +2,7 @@
  * GSD Parallel Monitor Overlay
  *
  * Full-screen TUI overlay showing real-time parallel worker progress.
- * Opened via `/gsd parallel watch` or Ctrl+Alt+P.
+ * Opened via `/gsd parallel watch` or Ctrl+Alt+P (⌃⌥P on macOS).
  * Reads the same data sources as `scripts/parallel-monitor.mjs` but
  * renders as a native pi-tui overlay with theme integration.
  */

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -238,8 +238,7 @@ export async function checkPackageExistence(
 export function normalizeFilePath(filePath: string): string {
   if (!filePath) return filePath;
 
-  // Strip backtick wrapping from LLM-generated paths (#3649)
-  let normalized = filePath.replace(/`/g, "");
+  let normalized = extractPathFromAnnotation(filePath);
 
   // Normalize path separators to forward slashes
   normalized = normalized.replace(/\\/g, "/");
@@ -260,6 +259,24 @@ export function normalizeFilePath(filePath: string): string {
   return normalized;
 }
 
+function extractPathFromAnnotation(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return trimmed;
+
+  const backtickMatch = trimmed.match(/^`([^`]+)`(?:\s+[—–-]\s+.*)?$/);
+  if (backtickMatch) {
+    return backtickMatch[1].trim();
+  }
+
+  const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
+  if (annotatedMatch) {
+    return annotatedMatch[1].trim();
+  }
+
+  // Fall back to the original behavior for already-plain paths.
+  return trimmed.replace(/`/g, "");
+}
+
 /**
  * Build a set of files that will be created by tasks up to (but not including) taskIndex.
  * All paths are normalized for consistent comparison.

package/src/resources/extensions/gsd/prompts/system.md

@@ -131,8 +131,8 @@ Templates showing the expected format for each artifact type are in:
 - `/gsd status` - progress dashboard overlay
 - `/gsd queue` - queue future milestones (safe while auto-mode is running)
 - `/gsd quick <task>` - quick task with GSD guarantees (atomic commits, state tracking) but no milestone ceremony
-- `Ctrl+Alt+G` - toggle dashboard overlay
-- `Ctrl+Alt+B` - show shell processes
+- `{{shortcutDashboard}}` - toggle dashboard overlay
+- `{{shortcutShell}}` - show shell processes
 
 ## Execution Heuristics
 

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

@@ -19,8 +19,10 @@
 import { createTestContext } from "./test-helpers.ts";
 import {
   withTimeout,
+  FINALIZE_PRE_TIMEOUT_MS,
   FINALIZE_POST_TIMEOUT_MS,
 } from "../auto/finalize-timeout.ts";
+import { MAX_FINALIZE_TIMEOUTS } from "../auto/types.ts";
 
 const { assertTrue, assertEq, report } = createTestContext();
 
@@ -78,6 +80,25 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertTrue(caught, "rejection should propagate");
 }
 
+// ═══ Test: FINALIZE_PRE_TIMEOUT_MS is defined and reasonable ═════════════════
+
+{
+  console.log("\n=== #3757: pre-verification timeout constant is defined and reasonable ===");
+
+  assertTrue(
+    typeof FINALIZE_PRE_TIMEOUT_MS === "number",
+    "FINALIZE_PRE_TIMEOUT_MS should be a number",
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS >= 30_000,
+    `pre timeout should be >= 30s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS <= 120_000,
+    `pre timeout should be <= 120s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+}
+
 // ═══ Test: FINALIZE_POST_TIMEOUT_MS is defined and reasonable ═════════════════
 
 {
@@ -113,4 +134,108 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertEq(result.timedOut, false, "should not time out");
 }
 
+// ═══ Test: runFinalize wraps BOTH pre and post verification with withTimeout ═
+
+{
+  console.log("\n=== #3757: runFinalize wraps preVerification with timeout guard ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  // Find the runFinalize function body
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
+
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // postUnitPreVerification must be wrapped in withTimeout
+  const preTimeoutIdx = fnBody.indexOf("withTimeout(");
+  assertTrue(preTimeoutIdx > 0, "withTimeout should appear in runFinalize");
+
+  const preVerIdx = fnBody.indexOf("postUnitPreVerification");
+  assertTrue(preVerIdx > 0, "postUnitPreVerification should appear in runFinalize");
+
+  // The first withTimeout should wrap postUnitPreVerification (not postUnitPostVerification)
+  const firstWithTimeout = fnBody.slice(preTimeoutIdx, preTimeoutIdx + 200);
+  assertTrue(
+    firstWithTimeout.includes("postUnitPreVerification"),
+    "first withTimeout in runFinalize should wrap postUnitPreVerification",
+  );
+
+  // postUnitPostVerification must also be wrapped
+  const postVerIdx = fnBody.indexOf("postUnitPostVerification");
+  assertTrue(postVerIdx > 0, "postUnitPostVerification should appear in runFinalize");
+
+  // Count withTimeout occurrences — should be at least 2 (pre + post)
+  const timeoutCount = (fnBody.match(/withTimeout\(/g) || []).length;
+  assertTrue(
+    timeoutCount >= 2,
+    `runFinalize should have at least 2 withTimeout guards (found ${timeoutCount})`,
+  );
+}
+
+// ═══ Test: MAX_FINALIZE_TIMEOUTS is defined and reasonable ═══════════════════
+
+{
+  console.log("\n=== #3757: MAX_FINALIZE_TIMEOUTS is defined and reasonable ===");
+
+  assertTrue(
+    typeof MAX_FINALIZE_TIMEOUTS === "number",
+    "MAX_FINALIZE_TIMEOUTS should be a number",
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS >= 2,
+    `threshold should be >= 2 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS <= 10,
+    `threshold should be <= 10 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+}
+
+// ═══ Test: timeout handlers escalate after consecutive timeouts ══════════════
+
+{
+  console.log("\n=== #3757: timeout handlers escalate and detach currentUnit ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // Both timeout handlers should increment consecutiveFinalizeTimeouts
+  const incrementCount = (fnBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
+  assertTrue(
+    incrementCount >= 2,
+    `should increment consecutiveFinalizeTimeouts in both pre and post handlers (found ${incrementCount})`,
+  );
+
+  // Both timeout handlers should check MAX_FINALIZE_TIMEOUTS for escalation
+  const escalationCount = (fnBody.match(/MAX_FINALIZE_TIMEOUTS/g) || []).length;
+  assertTrue(
+    escalationCount >= 2,
+    `should check MAX_FINALIZE_TIMEOUTS in both handlers (found ${escalationCount})`,
+  );
+
+  // Both timeout handlers should null out s.currentUnit to prevent late mutations
+  const detachCount = (fnBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
+  assertTrue(
+    detachCount >= 2,
+    `should detach s.currentUnit in both timeout handlers (found ${detachCount})`,
+  );
+
+  // Successful finalize should reset the counter
+  assertTrue(
+    fnBody.includes("consecutiveFinalizeTimeouts = 0"),
+    "should reset consecutiveFinalizeTimeouts on successful finalize",
+  );
+}
+
 report();

package/src/resources/extensions/gsd/tests/format-shortcut.test.ts

@@ -0,0 +1,69 @@
+// GSD Extension — formatShortcut tests
+// Verifies OS-specific keyboard shortcut rendering.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatShortcut } from '../files.ts';
+
+// ─── formatShortcut renders per-platform shortcuts ──────────────────────
+
+test('formatShortcut: converts Ctrl+Alt combo on macOS', () => {
+  // formatShortcut uses process.platform at module load time.
+  // We can only test the current platform's behavior.
+  const result = formatShortcut('Ctrl+Alt+G');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥G', 'macOS should use ⌃⌥ symbols');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+G', 'non-macOS should pass through unchanged');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+N', () => {
+  const result = formatShortcut('Ctrl+Alt+N');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥N');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+N');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+B', () => {
+  const result = formatShortcut('Ctrl+Alt+B');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥B');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+B');
+  }
+});
+
+test('formatShortcut: converts standalone Ctrl modifier', () => {
+  const result = formatShortcut('Ctrl+C');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃C');
+  } else {
+    assert.strictEqual(result, 'Ctrl+C');
+  }
+});
+
+test('formatShortcut: converts Shift modifier', () => {
+  const result = formatShortcut('Shift+Tab');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⇧Tab');
+  } else {
+    assert.strictEqual(result, 'Shift+Tab');
+  }
+});
+
+test('formatShortcut: converts Cmd modifier', () => {
+  const result = formatShortcut('Cmd+S');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌘S');
+  } else {
+    assert.strictEqual(result, 'Cmd+S');
+  }
+});
+
+test('formatShortcut: passes through plain key names', () => {
+  assert.strictEqual(formatShortcut('Escape'), 'Escape');
+  assert.strictEqual(formatShortcut('Enter'), 'Enter');
+});

package/src/resources/extensions/gsd/tests/journal-integration.test.ts

@@ -216,7 +216,7 @@ test("runDispatch emits dispatch-match with correct rule and flowId", async () =
     mid: "M001",
     midTitle: "Test Milestone",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runDispatch(ic, preData, loopState);
 
@@ -248,7 +248,7 @@ test("runDispatch emits dispatch-stop when dispatch returns stop action", async
     mid: "M001",
     midTitle: "Test",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runDispatch(ic, preData, loopState);
   assert.equal(result.action, "break");
@@ -303,6 +303,7 @@ test("runDispatch checks prior-slice completion against the project root in work
   const result = await runDispatch(ic, preData, {
     recentUnits: [],
     stuckRecoveryAttempts: 0,
+    consecutiveFinalizeTimeouts: 0,
   });
 
   assert.equal(result.action, "next");
@@ -343,7 +344,7 @@ test("runUnitPhase emits unit-start and unit-end with causedBy reference", async
     isRetry: false,
     previousTier: undefined,
   };
-  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   // Start runUnitPhase (it will block on runUnit internally)
   const unitPromise = runUnitPhase(ic, iterData, loopState);
@@ -400,7 +401,7 @@ test("all events from a mock iteration have monotonically increasing seq and sam
     mid: "M001",
     midTitle: "Test",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
   const dispatchResult = await runDispatch(ic, preData, loopState);
   assert.equal(dispatchResult.action, "next");
 
@@ -446,7 +447,7 @@ test("dispatch-match events include matchedRule field matching the rule name", a
     midTitle: "Test",
   };
 
-  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 });
+  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 });
 
   const matchEvents = capture.events.filter(e => e.eventType === "dispatch-match");
   assert.equal(matchEvents.length, 1);
@@ -475,7 +476,7 @@ test("pre-dispatch-hook event is emitted when hooks fire", async () => {
     midTitle: "Test",
   };
 
-  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 });
+  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 });
 
   const hookEvents = capture.events.filter(e => e.eventType === "pre-dispatch-hook");
   assert.equal(hookEvents.length, 1, "should emit one pre-dispatch-hook event");
@@ -497,7 +498,7 @@ test("terminal event is emitted on milestone-complete", async () => {
     }) as any,
   });
   const ic = makeIC(deps);
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runPreDispatch(ic, loopState);
   assert.equal(result.action, "break");
@@ -521,7 +522,7 @@ test("terminal event is emitted on blocked state", async () => {
     }) as any,
   });
   const ic = makeIC(deps);
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runPreDispatch(ic, loopState);
   assert.equal(result.action, "break");
@@ -550,7 +551,7 @@ test("milestone-transition event is emitted when milestone changes", async () =>
   const ic = makeIC(deps);
   // Session says current milestone is M001, but state will return M002
   ic.s.currentMilestoneId = "M001";
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   await runPreDispatch(ic, loopState);
 
@@ -580,7 +581,7 @@ test("unit-end event contains errorContext when unit is cancelled with structure
     isRetry: false,
     previousTier: undefined,
   };
-  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const unitPromise = runUnitPhase(ic, iterData, loopState);
   await new Promise(r => setTimeout(r, 50));