gsd-pi 2.75.0 → 2.76.0

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

@@ -316,6 +316,50 @@ describe('doctor-proactive', async () => {
       }
     });
 
+    test('health gate: git.snapshots:false suppresses stale-commit snapshot (#4420)', async () => {
+      // Build a repo whose HEAD commit is far enough in the past that the
+      // default stale-commit threshold (30 min) is exceeded, then dirty the
+      // tracked file so the snapshot path has material to commit.
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), "doc-proactive-4420-")));
+      cleanups.push(dir);
+      const oldDate = "2020-01-01T00:00:00Z";
+      const env = { ...process.env, GIT_AUTHOR_DATE: oldDate, GIT_COMMITTER_DATE: oldDate };
+      execSync("git init", { cwd: dir, stdio: "ignore", env });
+      execSync("git config user.email test@test.com", { cwd: dir, stdio: "ignore", env });
+      execSync("git config user.name Test", { cwd: dir, stdio: "ignore", env });
+      writeFileSync(join(dir, "README.md"), "# test\n");
+      execSync("git add .", { cwd: dir, stdio: "ignore", env });
+      execSync('git commit -m init', { cwd: dir, stdio: "ignore", env });
+      execSync("git branch -M main", { cwd: dir, stdio: "ignore", env });
+      mkdirSync(join(dir, ".gsd"), { recursive: true });
+
+      writeFileSync(join(dir, "README.md"), "# test\n\ndirty\n");
+      assert.ok(run("git status --porcelain", dir).length > 0, "working tree is dirty");
+
+      writeFileSync(
+        join(dir, ".gsd", "PREFERENCES.md"),
+        `---\ngit:\n  snapshots: false\n---\n`,
+      );
+
+      const commitCountBefore = run("git rev-list --count HEAD", dir);
+
+      const previousCwd = process.cwd();
+      process.chdir(dir);
+      try {
+        const result = await preDispatchHealthGate(dir);
+        assert.ok(result.proceed, "gate proceeds when snapshots are disabled");
+        assert.ok(
+          !result.fixesApplied.some(f => f.includes("gsd snapshot")),
+          `no snapshot fix reported when git.snapshots:false (got: ${JSON.stringify(result.fixesApplied)})`,
+        );
+      } finally {
+        process.chdir(previousCwd);
+      }
+
+      const commitCountAfter = run("git rev-list --count HEAD", dir);
+      assert.strictEqual(commitCountAfter, commitCountBefore, "no snapshot commit was created");
+    });
+
   } finally {
     resetProactiveHealing();
     for (const dir of cleanups) {

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

@@ -9,7 +9,7 @@ import assert from 'node:assert/strict';
  *   state_file_stale, gitignore_missing_patterns
  */
 
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, realpathSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -252,6 +252,37 @@ node_modules/
     } else {
     }
 
+    // ─── Test 8b: Symlinked .gsd without .gitignore entry (#4423) ─────
+    if (process.platform !== "win32") {
+    test('symlinked_gsd_unignored', async () => {
+      const dir = createGitProject();
+      cleanups.push(dir);
+
+      // Create .gsd as a symlink to an external directory (standard external
+      // state layout), and write a .gitignore that does NOT list .gsd.
+      const externalGsd = mkdtempSync(join(tmpdir(), "gsd-external-doctor-"));
+      cleanups.push(externalGsd);
+      writeFileSync(join(externalGsd, "STATE.md"), "# State\n");
+      symlinkSync(externalGsd, join(dir, ".gsd"));
+
+      writeFileSync(join(dir, ".gitignore"), "node_modules/\n");
+
+      const detect = await runGSDDoctor(dir);
+      const symlinkIssues = detect.issues.filter(i => i.code === "symlinked_gsd_unignored");
+      assert.ok(symlinkIssues.length > 0, "detects symlinked .gsd without gitignore entry");
+
+      const fixed = await runGSDDoctor(dir, { fix: true });
+      assert.ok(
+        fixed.fixesApplied.some(f => f.includes(".gitignore")),
+        "fix updates .gitignore",
+      );
+
+      const content = readFileSync(join(dir, ".gitignore"), "utf-8");
+      assert.ok(/^\.gsd\/?$/m.test(content), "gitignore now has .gsd entry");
+    });
+    } else {
+    }
+
     // ─── Test 9: Orphaned completed-units detection & fix ─────────────
     test('orphaned_completed_units', async () => {
       const dir = createMinimalProject();
@@ -277,6 +308,42 @@ node_modules/
       assert.deepStrictEqual(content.length, 0, "all orphaned keys removed");
     });
 
+    // ─── Test: hook/ compound keys are NOT flagged as orphaned (#2826) ─
+    test('orphaned_completed_units — hook/ compound keys not flagged', async () => {
+      const dir = createMinimalProject();
+      cleanups.push(dir);
+
+      // Hook unit types are stored as "hook/<hookName>/<unitId...>".
+      // These are valid completions with no artifact to verify — they must
+      // not be reported as orphaned_completed_units.
+      const completedKeys = [
+        "hook/telegram-progress/M001/S01",
+        "hook/telegram-progress/M001/S01/T01",
+        "hook/my-custom-hook/M001",
+        // Mix in a genuinely missing plain key to confirm detection still works
+        "execute-task/M001/S01/T99",
+      ];
+      writeFileSync(join(dir, ".gsd", "completed-units.json"), JSON.stringify(completedKeys));
+
+      const detect = await runGSDDoctor(dir);
+      const orphanIssues = detect.issues.filter(i => i.code === "orphaned_completed_units");
+
+      // Only the plain "execute-task/M001/S01/T99" should be flagged, not the hooks.
+      // If the compound-type parsing is broken, all 4 keys (including the 3 hook/
+      // keys) would be flagged. With the fix, at most 1 key is flagged.
+      if (orphanIssues.length > 0) {
+        const msg = orphanIssues[0]!.message;
+        assert.ok(
+          !msg.includes("hook/telegram-progress") && !msg.includes("hook/my-custom-hook"),
+          `hook/ keys must not appear in orphaned_completed_units message — got: ${msg}`,
+        );
+        assert.ok(
+          !msg.includes("4 completed-unit key") && !msg.includes("3 completed-unit key"),
+          `hook/ keys must not inflate the orphaned count — got: ${msg}`,
+        );
+      }
+    });
+
     // ─── Test: Stranded lock directory detection & fix ────────────────
     // Skip on Windows: proper-lockfile uses advisory file locking on Windows,
     // not the directory-based mechanism. The .gsd.lock/ directory pattern is

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

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, symlinkSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, symlinkSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -1247,8 +1247,8 @@ describe('git-service', async () => {
 
   test('nativeAddAllWithExclusions: symlinked .gsd fallback', () => {
     // When .gsd is a symlink, git rejects `:!.gsd/...` pathspecs with
-    // "fatal: pathspec '...' is beyond a symbolic link". The fix falls
-    // back to `git add -u` (tracked files only), NOT `git add -A`.
+    // "fatal: pathspec '...' is beyond a symbolic link". When `.gsd` is
+    // already gitignored, the fallback should still stage untracked real files.
     const repo = initTempRepo();
 
     // Create the real .gsd directory outside the repo, then symlink it
@@ -1269,9 +1269,9 @@ describe('git-service', async () => {
     run('git commit -m "add app"', repo);
     writeFileSync(join(repo, "src/app.ts"), "export const x = 2;");
 
-    // Create an untracked file simulating large data (NOT in .gitignore)
-    // This is the key scenario: large untracked dirs that git add -A would traverse
-    createFile(repo, "data/large-model.bin", "pretend this is 10GB");
+    // Create an untracked file that should still be staged by the fallback
+    // because `.gsd` itself is already protected by .gitignore.
+    createFile(repo, "src/new-feature.ts", "export const fresh = true;");
 
     // nativeAddAllWithExclusions should NOT throw despite .gsd being a symlink
     let threw = false;
@@ -1287,17 +1287,115 @@ describe('git-service', async () => {
     const staged = run("git diff --cached --name-only", repo);
     assert.ok(staged.includes("src/app.ts"), "modified tracked file staged despite symlinked .gsd");
 
-    // CRITICAL: untracked files must NOT be staged — the symlink fallback
-    // should use `git add -u` (tracked only), not `git add -A` (all files).
-    // Using `git add -A` on a repo with large untracked data dirs hangs. (#1977)
-    assert.ok(!staged.includes("data/large-model.bin"),
-      "symlink fallback must not stage untracked files (would hang on large repos)");
+    assert.ok(staged.includes("src/new-feature.ts"),
+      "symlink fallback should still stage new real files when .gsd is gitignored");
     assert.ok(!staged.includes(".gsd"), ".gsd content not staged");
 
     rmSync(repo, { recursive: true, force: true });
     rmSync(externalGsd, { recursive: true, force: true });
   });
 
+  test('nativeAddAllWithExclusions: self-heals symlinked .gsd when .gitignore lacks it (#4423)', () => {
+    // When `.gsd` is a symlink AND not listed in `.gitignore`, the staging
+    // fallback must self-heal by appending `.gsd` to `.gitignore` and retrying
+    // `git add -A`. Without this, new user files are silently dropped.
+    const repo = initTempRepo();
+
+    const externalGsd = mkdtempSync(join(tmpdir(), "gsd-external-unignored-"));
+    mkdirSync(join(externalGsd, "activity"), { recursive: true });
+    writeFileSync(join(externalGsd, "activity", "log.jsonl"), "log data");
+    writeFileSync(join(externalGsd, "STATE.md"), "# State");
+
+    symlinkSync(externalGsd, join(repo, ".gsd"));
+
+    createFile(repo, "src/app.ts", "export const x = 1;");
+    run("git add -A", repo);
+    run('git commit -m "add app"', repo);
+    writeFileSync(join(repo, "src/app.ts"), "export const x = 2;");
+    createFile(repo, "src/new-feature.ts", "export const fresh = true;");
+
+    let threw = false;
+    try {
+      nativeAddAllWithExclusions(repo, RUNTIME_EXCLUSION_PATHS);
+    } catch (e) {
+      threw = true;
+      console.error("  unexpected error:", e);
+    }
+    assert.ok(!threw, "nativeAddAllWithExclusions does not throw with symlinked .gsd when .gsd is not gitignored");
+
+    const staged = run("git diff --cached --name-only", repo);
+    assert.ok(staged.includes("src/app.ts"), "tracked modifications stage");
+    assert.ok(
+      staged.includes("src/new-feature.ts"),
+      "self-heal adds .gsd to .gitignore so new user files are staged",
+    );
+    assert.ok(!staged.includes(".gsd"), ".gsd contents stay unstaged after self-heal");
+
+    // Verify the self-heal actually wrote to .gitignore
+    const gitignore = readFileSync(join(repo, ".gitignore"), "utf-8");
+    assert.ok(/^\.gsd\/?$/m.test(gitignore), ".gitignore contains .gsd entry after self-heal");
+
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(externalGsd, { recursive: true, force: true });
+  });
+
+  test('nativeAddAllWithExclusions: explicit staging protects work when manage_gitignore:false (#4423)', () => {
+    // When `git.manage_gitignore: false` is set in PREFERENCES.md, the
+    // self-heal path is disabled. The fallback must still protect user work
+    // by explicitly staging untracked real files while skipping `.gsd`.
+    const repo = initTempRepo();
+
+    const externalGsd = mkdtempSync(join(tmpdir(), "gsd-external-optout-"));
+    mkdirSync(join(externalGsd, "activity"), { recursive: true });
+    writeFileSync(join(externalGsd, "activity", "log.jsonl"), "log data");
+    writeFileSync(join(externalGsd, "STATE.md"), "# State");
+
+    symlinkSync(externalGsd, join(repo, ".gsd"));
+
+    // Create PREFERENCES.md inside the symlink target (the linked .gsd dir)
+    // with the opt-out flag. The regex matches a top-level occurrence.
+    writeFileSync(
+      join(repo, ".gsd", "PREFERENCES.md"),
+      "---\nversion: 1\ngit:\n  manage_gitignore: false\n---\n",
+    );
+
+    createFile(repo, "src/app.ts", "export const x = 1;");
+    run("git add -A", repo);
+    run('git commit -m "add app"', repo);
+    writeFileSync(join(repo, "src/app.ts"), "export const x = 2;");
+    createFile(repo, "src/new-feature.ts", "export const fresh = true;");
+
+    let threw = false;
+    try {
+      nativeAddAllWithExclusions(repo, RUNTIME_EXCLUSION_PATHS);
+    } catch (e) {
+      threw = true;
+      console.error("  unexpected error:", e);
+    }
+    assert.ok(!threw, "nativeAddAllWithExclusions does not throw under manage_gitignore:false");
+
+    const staged = run("git diff --cached --name-only", repo);
+    assert.ok(staged.includes("src/app.ts"), "tracked modifications stage");
+    assert.ok(
+      staged.includes("src/new-feature.ts"),
+      "explicit staging protects new files even when self-heal is disabled",
+    );
+    assert.ok(!staged.includes(".gsd"), ".gsd contents stay unstaged");
+
+    // Self-heal must NOT have written to .gitignore
+    const gitignoreExists = existsSync(join(repo, ".gitignore"));
+    if (gitignoreExists) {
+      const gitignore = readFileSync(join(repo, ".gitignore"), "utf-8");
+      assert.ok(
+        !/^\.gsd\/?$/m.test(gitignore),
+        "manage_gitignore:false must prevent writes to .gitignore",
+      );
+    }
+
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(externalGsd, { recursive: true, force: true });
+  });
+
   // ─── nativeAddAllWithExclusions: non-symlinked .gsd still works ───────
 
   test('nativeAddAllWithExclusions: non-symlinked .gsd still works', () => {

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

@@ -358,6 +358,57 @@ test('writeBlockerPlaceholder: does NOT update DB for non-execute-task types', a
   }
 });
 
+test('writeBlockerPlaceholder: updates execute-task plan checkbox after DB recovery (#4126)', async () => {
+  const base = createFixtureBase();
+  try {
+    const {
+      openDatabase,
+      closeDatabase,
+      insertMilestone,
+      insertSlice,
+      insertTask,
+      getTask,
+      isDbAvailable,
+    } = await import("../../gsd-db.ts");
+
+    const dbPath = join(base, ".gsd", "gsd.db");
+    const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Recoverable task** `est:5m`",
+    ].join("\n"));
+
+    openDatabase(dbPath);
+    try {
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active" });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Recoverable task", status: "pending" });
+
+      writeBlockerPlaceholder("execute-task", "M001/S01/T01", base, "context exhaustion recovery");
+
+      const task = getTask("M001", "S01", "T01");
+      assert.equal(task?.status, "complete", "execute-task recovery should still mark the DB task complete");
+
+      const planContent = readFileSync(join(sliceDir, "S01-PLAN.md"), "utf-8");
+      assert.match(
+        planContent,
+        /\- \[x\] \*\*T01: Recoverable task\*\*/,
+        "execute-task recovery should re-render the slice plan checkbox after marking the DB row complete",
+      );
+    } finally {
+      if (isDbAvailable()) closeDatabase();
+    }
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('writeBlockerPlaceholder: updates DB slice status for complete-slice (#2653)', async () => {
   const base = createFixtureBase();
   try {

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

@@ -356,10 +356,10 @@ test("full lifecycle: migration through completion through doctor", async (t) =>
       assert.match(sliceSummary, /Core feature proven/, "Slice summary should contain one-liner");
     }
 
-    // Verify roadmap checkbox toggled
+    // Verify roadmap checkbox toggled — authoritative renderer emits a checkbox list.
     const roadmapPath = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
     const roadmapAfter = readFileSync(roadmapPath, "utf-8");
-    assert.ok(roadmapAfter.includes("\u2705"), "S01 should be checked in roadmap (✅ emoji in table format)");
+    assert.match(roadmapAfter, /- \[x\] \*\*S01:/, "S01 should be checked ([x]) in roadmap");
 
     // Verify slice status in DB
     const sliceRow = getSlice("M001", "S01");

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

@@ -0,0 +1,53 @@
+/**
+ * Test isolation utilities for integration tests.
+ *
+ * Integration tests often call `mergeMilestoneToMain` and other functions that
+ * load preferences. If the user's global ~/.gsd/preferences.md has
+ * `git.main_branch: master`, tests fail because test repos use `main`.
+ *
+ * These utilities isolate tests from the user's global environment.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { _resetServiceCache } from "../../worktree.ts";
+import { _clearGsdRootCache } from "../../paths.ts";
+
+let originalHome: string | undefined;
+let fakeHome: string | null = null;
+
+/**
+ * Isolate the test environment from user's global preferences.
+ * Creates a fake HOME directory so loadEffectiveGSDPreferences() returns
+ * empty global preferences instead of the user's ~/.gsd/preferences.md.
+ *
+ * Call this in a test.before() hook.
+ */
+export function isolateFromGlobalPreferences(): void {
+  originalHome = process.env.HOME;
+  fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-test-home-")));
+  process.env.HOME = fakeHome;
+  _clearGsdRootCache();
+  _resetServiceCache();
+}
+
+/**
+ * Restore the original HOME and clean up the fake home directory.
+ *
+ * Call this in a test.after() hook.
+ */
+export function restoreGlobalPreferences(): void {
+  if (originalHome !== undefined) {
+    process.env.HOME = originalHome;
+  } else {
+    delete process.env.HOME;
+  }
+  _clearGsdRootCache();
+  _resetServiceCache();
+  if (fakeHome) {
+    rmSync(fakeHome, { recursive: true, force: true });
+    fakeHome = null;
+  }
+}

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

@@ -10,13 +10,17 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import type { JournalEntry } from "../journal.js";
 import type { LoopDeps } from "../auto/loop-deps.js";
 import type { IterationContext, LoopState, PreDispatchData, IterationData } from "../auto/types.js";
 import type { SessionLockStatus } from "../session-lock.js";
-import { runDispatch, runUnitPhase, runPreDispatch } from "../auto/phases.js";
+import { runDispatch, runUnitPhase, runPreDispatch, runFinalize } from "../auto/phases.js";
+import { readUnitRuntimeRecord } from "../unit-runtime.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -317,6 +321,75 @@ test("runDispatch checks prior-slice completion against the project root in work
   ]);
 });
 
+test("runDispatch pauses when complete-milestone summary exists on disk but the unit is still stuck (#4289)", async (t) => {
+  const capture = createEventCapture();
+  let pauseCalls = 0;
+  let stopCalls = 0;
+  const base = join(tmpdir(), `gsd-stuck-complete-${randomUUID()}`);
+  t.after(() => {
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  mkdirSync(join(base, "src"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Summary\nDone.\n");
+  writeFileSync(join(base, "src", "app.ts"), "export const ok = true;\n");
+
+  execFileSync("git", ["init", "-b", "main"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.name", "Codex"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "codex@example.com"], { cwd: base, stdio: "ignore" });
+  writeFileSync(join(base, "README.md"), "# test\n");
+  execFileSync("git", ["add", "README.md"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "chore: seed"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["checkout", "-b", "fix/test"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["add", ".gsd/milestones/M001/M001-SUMMARY.md", "src/app.ts"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "feat: summary exists but db is stale"], { cwd: base, stdio: "ignore" });
+
+  const deps = makeMockDeps(capture, {
+    pauseAuto: async () => { pauseCalls++; },
+    stopAuto: async () => { stopCalls++; },
+    resolveDispatch: async () => ({
+      action: "dispatch" as const,
+      unitType: "complete-milestone",
+      unitId: "M001",
+      prompt: "complete the milestone",
+      matchedRule: "completing-milestone-rule",
+    }),
+  });
+
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath: base,
+      currentMilestoneId: "M001",
+    } as any,
+  });
+  const preData: PreDispatchData = {
+    state: {
+      phase: "completing-milestone",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      registry: [{ id: "M001", status: "active" }],
+      blockers: [],
+    } as any,
+    mid: "M001",
+    midTitle: "Test Milestone",
+  };
+
+  const result = await runDispatch(ic, preData, {
+    recentUnits: [
+      { key: "complete-milestone/M001" },
+      { key: "complete-milestone/M001" },
+    ],
+    stuckRecoveryAttempts: 0,
+    consecutiveFinalizeTimeouts: 0,
+  });
+
+  assert.equal(result.action, "break");
+  assert.equal((result as any).reason, "complete-milestone-artifact-db-mismatch");
+  assert.equal(pauseCalls, 1, "complete-milestone disk/db mismatch should pause auto-mode");
+  assert.equal(stopCalls, 0, "mismatch pause should not hard-stop the loop");
+});
+
 test("runUnitPhase emits unit-start and unit-end with causedBy reference", async () => {
   const capture = createEventCapture();
 
@@ -380,6 +453,41 @@ test("runUnitPhase emits unit-start and unit-end with causedBy reference", async
   assert.equal(endEvents[0].causedBy!.seq, startEvents[0].seq, "unit-end causedBy.seq must match unit-start.seq");
 });
 
+test("runUnitPhase increments unitDispatchCount for repeated artifact-missing retries", async () => {
+  const capture = createEventCapture();
+  const { resolveAgentEnd, _resetPendingResolve } = await import("../auto-loop.js");
+  _resetPendingResolve();
+
+  const deps = makeMockDeps(capture);
+  const ic = makeIC(deps);
+  const iterData: IterationData = {
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do stuff",
+    finalPrompt: "do stuff",
+    pauseAfterUatDispatch: false,
+    state: { phase: "executing", activeMilestone: { id: "M001" }, activeSlice: { id: "S01" }, registry: [], blockers: [] } as any,
+    mid: "M001",
+    midTitle: "Test",
+    isRetry: false,
+    previousTier: undefined,
+  };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
+
+  const firstRun = runUnitPhase(ic, iterData, loopState);
+  await new Promise(r => setTimeout(r, 50));
+  resolveAgentEnd({ messages: [{ role: "assistant" }] });
+  await firstRun;
+  assert.equal(ic.s.unitDispatchCount.get("execute-task/M001/S01/T01"), 1);
+
+  _resetPendingResolve();
+  const secondRun = runUnitPhase(ic, iterData, loopState);
+  await new Promise(r => setTimeout(r, 50));
+  resolveAgentEnd({ messages: [{ role: "assistant" }] });
+  await secondRun;
+  assert.equal(ic.s.unitDispatchCount.get("execute-task/M001/S01/T01"), 2);
+});
+
 test("all events from a mock iteration have monotonically increasing seq and same flowId", async () => {
   const capture = createEventCapture();
   const { resolveAgentEnd, _resetPendingResolve } = await import("../auto-loop.js");
@@ -667,3 +775,65 @@ test("session-failed cancellations close out and emit unit-end before hard stop"
   assert.equal((endEvents[0].data as any).artifactVerified, false);
   assert.equal((endEvents[0].data as any).errorContext.category, "session-failed");
 });
+
+test("runFinalize pauses and emits unit-end when pre-verification times out", async () => {
+  const capture = createEventCapture();
+  let pauseCalls = 0;
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-finalize-timeout-"));
+
+  const deps = makeMockDeps(capture, {
+    pauseAuto: async () => { pauseCalls++; },
+    postUnitPreVerification: async () => {
+      await new Promise(() => {});
+      return "continue" as const;
+    },
+  });
+
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath,
+      currentUnit: { type: "execute-task", id: "M001/S01/T01", startedAt: 1234 },
+    } as any,
+  });
+  const iterData: IterationData = {
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do stuff",
+    finalPrompt: "do stuff",
+    pauseAfterUatDispatch: false,
+    state: { phase: "executing", activeMilestone: { id: "M001" }, activeSlice: { id: "S01" }, registry: [], blockers: [] } as any,
+    mid: "M001",
+    midTitle: "Test",
+    isRetry: false,
+    previousTier: undefined,
+  };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
+
+  const originalSetTimeout = globalThis.setTimeout;
+  try {
+    globalThis.setTimeout = ((handler: (...args: any[]) => void, _timeout?: number, ...args: any[]) =>
+      originalSetTimeout(handler, 0, ...args)) as typeof setTimeout;
+
+    const result = await runFinalize(ic, iterData, loopState);
+    assert.equal(result.action, "break");
+    assert.equal((result as any).reason, "finalize-pre-timeout");
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+  }
+
+  assert.equal(pauseCalls, 1, "pre-verification timeout should pause auto-mode");
+  assert.equal(loopState.consecutiveFinalizeTimeouts, 1, "timeout should increment finalize timeout counter");
+  assert.equal(ic.s.currentUnit, null, "timed-out finalize should detach currentUnit");
+
+  const runtime = readUnitRuntimeRecord(basePath, "execute-task", "M001/S01/T01");
+  assert.ok(runtime, "timed-out finalize should persist a runtime record");
+  assert.equal(runtime?.phase, "finalize-timeout");
+  assert.equal(runtime?.lastProgressKind, "finalize-pre-timeout");
+
+  const endEvents = capture.events.filter((e) => e.eventType === "unit-end");
+  assert.equal(endEvents.length, 1, "timed-out finalize should emit terminal unit-end");
+  assert.equal((endEvents[0].data as any).status, "timed-out-finalize");
+  assert.equal((endEvents[0].data as any).artifactVerified, false);
+  assert.equal((endEvents[0].data as any).finalizeStage, "pre");
+});

package/src/resources/extensions/gsd/tests/md-importer.test.ts

@@ -363,7 +363,7 @@ test('md-importer: schema v1→v2 migration', () => {
   openDatabase(':memory:');
   const adapter = _getAdapter();
   const version = adapter?.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assert.deepStrictEqual(version?.v, 15, 'new DB should be at schema version 15');
+  assert.deepStrictEqual(version?.v, 20, 'new DB should be at schema version 20');
 
   // Artifacts table should exist
   const tableCheck = adapter?.prepare("SELECT count(*) as c FROM sqlite_master WHERE type='table' AND name='artifacts'").get();