gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -10,6 +10,7 @@ import {
   autoLoop,
   detectStuck,
   _resetPendingResolve,
+  _hasPendingResolveForTest,
   _setActiveSession,
   isSessionSwitchInFlight,
   type UnitResult,
@@ -35,12 +36,15 @@ function makeMockSession(opts?: {
   newSessionDelayMs?: number;
   onNewSessionStart?: (session: any) => void;
   onNewSessionSettle?: (session: any) => void;
+  /** Called after the delay with the aborted state of any passed abortSignal.
+   *  Used to verify that runUnit passes an aborted signal on late resolution (#3731). */
+  onSignalCheck?: (aborted: boolean) => void;
 }) {
   const session = {
     active: true,
     verbose: false,
     cmdCtx: {
-      newSession: () => {
+      newSession: (options?: { abortSignal?: AbortSignal }) => {
         opts?.onNewSessionStart?.(session);
         if (opts?.newSessionThrows) {
           return Promise.reject(new Error(opts.newSessionThrows));
@@ -50,11 +54,17 @@ function makeMockSession(opts?: {
         if (delay > 0) {
           return new Promise<{ cancelled: boolean }>((res) =>
             setTimeout(() => {
+              // Simulate AgentSession.newSession() checking abortSignal after
+              // its internal async work (abort()) completes — this is where the
+              // real code captures process.cwd() and rebuilds the tool runtime.
+              // If the signal is aborted, the real code discards the session.
+              opts?.onSignalCheck?.(options?.abortSignal?.aborted ?? false);
               opts?.onNewSessionSettle?.(session);
               res(result);
             }, delay),
           );
         }
+        opts?.onSignalCheck?.(options?.abortSignal?.aborted ?? false);
         opts?.onNewSessionSettle?.(session);
         return Promise.resolve(result);
       },
@@ -349,6 +359,182 @@ test("runUnit cancels before dispatch when model restore fails after newSession"
   ]);
 });
 
+test("runUnit cancels before dispatch when provider is not request-ready (#4555)", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-6" };
+  ctx.modelRegistry = {
+    isProviderRequestReady: (_provider: string) => false,
+  };
+
+  const pi = makeMockPi();
+  const s = makeMockSession();
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "provider");
+  assert.match(
+    result.errorContext?.message ?? "",
+    /Provider anthropic is not request-ready/,
+  );
+  assert.equal(pi.calls.length, 0, "sendMessage must not be called when provider is not ready");
+  assert.equal(_hasPendingResolveForTest(), false, "provider cancellation must clear the pending resolver");
+});
+
+test("runUnit cancels before dispatch using currentUnitModel provider when set (#4555)", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  // ctx.model uses "openai" which IS ready — if the code ignores currentUnitModel
+  // and falls back to ctx.model.provider, the unit would NOT be cancelled. The
+  // test therefore differentiates: only a bug (wrong provider lookup) would pass.
+  ctx.model = { provider: "openai", id: "gpt-4o" };
+  // modelRegistry says anthropic is not ready but openai is
+  ctx.modelRegistry = {
+    isProviderRequestReady: (provider: string) => provider === "openai",
+  };
+
+  const pi = makeMockPi();
+  const s = makeMockSession();
+  // currentUnitModel overrides the provider used in the readiness check
+  s.currentUnitModel = { provider: "anthropic", id: "claude-opus-4-6" };
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "provider");
+  assert.match(
+    result.errorContext?.message ?? "",
+    /Provider anthropic is not request-ready/,
+  );
+  assert.equal(pi.calls.length, 0, "sendMessage must not be called — anthropic (currentUnitModel) is not ready");
+});
+
+test("runUnit does not cancel before dispatch when provider is request-ready (#4555)", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-6" };
+  ctx.modelRegistry = {
+    isProviderRequestReady: (_provider: string) => true,
+  };
+
+  const pi = makeMockPi();
+  const s = makeMockSession();
+
+  const resultPromise = runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  await new Promise((r) => setTimeout(r, 10));
+  resolveAgentEnd(makeEvent());
+
+  const result = await resultPromise;
+  assert.equal(result.status, "completed");
+  assert.equal(pi.calls.length, 1, "sendMessage must be called when provider is ready");
+});
+
+test("runUnit proceeds when modelRegistry is absent (no readiness check available) (#4555)", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-6" };
+  // No modelRegistry on ctx — pre-check should be skipped
+
+  const pi = makeMockPi();
+  const s = makeMockSession();
+
+  const resultPromise = runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  await new Promise((r) => setTimeout(r, 10));
+  resolveAgentEnd(makeEvent());
+
+  const result = await resultPromise;
+  assert.equal(result.status, "completed");
+  assert.equal(pi.calls.length, 1);
+});
+
+test("runUnit proceeds when isProviderRequestReady throws (defensive) (#4555)", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-6" };
+  ctx.modelRegistry = {
+    isProviderRequestReady: (_provider: string) => {
+      throw new Error("registry error");
+    },
+  };
+
+  const pi = makeMockPi();
+  const s = makeMockSession();
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  // When the readyCheck throws, ready=false → unit cancelled
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "provider");
+  assert.equal(pi.calls.length, 0);
+});
+
+test("late-resolving newSession() after timeout receives aborted signal so tool runtime is not configured with root cwd (#3731)", async () => {
+  // When newSession() times out in runUnit(), auto-mode restores cwd to project
+  // root. If newSession() later resolves, it must NOT use process.cwd() to
+  // configure the tool runtime (which would give it root cwd, not worktree cwd).
+  //
+  // The fix: runUnit creates an AbortController, aborts it on timeout, and passes
+  // the signal to newSession(). AgentSession.newSession() checks the signal after
+  // its internal await this.abort() completes and returns early (discards) if aborted.
+  //
+  // This test uses mock.timers to control timing precisely.
+  _resetPendingResolve();
+  mock.timers.enable();
+
+  try {
+    let abortedWhenLateSessionSettled: boolean | null = null;
+
+    // newSession mock simulates AgentSession.newSession() behavior:
+    // after an internal delay (representing await this.abort()), it checks the
+    // abortSignal — that's where the real code would capture process.cwd() and
+    // call _buildRuntime. If aborted, the real code must discard the session.
+    const s = makeMockSession({
+      newSessionDelayMs: 200_000, // longer than NEW_SESSION_TIMEOUT_MS (120s)
+      onSignalCheck: (aborted) => {
+        abortedWhenLateSessionSettled = aborted;
+      },
+    });
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+
+    const resultPromise = runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+    // Tick past the 120s NEW_SESSION_TIMEOUT_MS — runUnit returns cancelled
+    mock.timers.tick(121_000);
+    await Promise.resolve();
+
+    const result = await resultPromise;
+    assert.equal(result.status, "cancelled", "runUnit must return cancelled on session timeout");
+
+    // Tick past the delayed newSession (200s total) — the late newSession resolves
+    mock.timers.tick(80_000);
+    // Drain microtask queue so the .finally() and setTimeout callbacks run
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // The key assertion: when the late newSession() resolves, runUnit must have
+    // passed an aborted AbortSignal. Without the fix, no signal is passed and
+    // abortedWhenLateSessionSettled would be false (or null, if signal not passed at all).
+    assert.equal(
+      abortedWhenLateSessionSettled,
+      true,
+      "runUnit must pass an aborted AbortSignal to newSession() when it resolves after the session-creation timeout (#3731). " +
+      "Without this, AgentSession.newSession() captures root process.cwd() and rebuilds the tool runtime with wrong cwd.",
+    );
+  } finally {
+    mock.timers.reset();
+  }
+});
+
 // ─── Structural assertions ───────────────────────────────────────────────────
 
 test("auto-loop.ts exports autoLoop, runUnit, resolveAgentEnd", async () => {
@@ -409,7 +595,7 @@ test("auto/phases.ts: selectAndApplyModel called exactly once and before updateP
   // Extract the runUnitPhase function body
   const fnStart = src.indexOf("export async function runUnitPhase");
   assert.ok(fnStart > 0, "runUnitPhase should exist in phases.ts");
-  const fnBody = src.slice(fnStart, fnStart + 12000);
+  const fnBody = src.slice(fnStart, fnStart + 16000);
 
   // selectAndApplyModel must appear exactly once
   const allOccurrences = [...fnBody.matchAll(/selectAndApplyModel\(/g)];
@@ -497,6 +683,8 @@ function makeMockDeps(
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
+    preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
+    postflightPopStash: () => {},
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,
@@ -663,6 +851,45 @@ test("autoLoop exits on terminal complete state", async (t) => {
   );
 });
 
+test("autoLoop pauses when provider readiness cancels before dispatch", async () => {
+  _resetPendingResolve();
+
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  ctx.ui.notify = (message: string, level?: string) => {
+    notifications.push({ message, level });
+  };
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-6" };
+  ctx.modelRegistry = {
+    getProviderAuthMode: () => "api-key",
+    isProviderRequestReady: () => false,
+  };
+
+  const pi = makeMockPi();
+  const s = makeLoopSession();
+  const deps = makeMockDeps({
+    selectAndApplyModel: async () => ({
+      routing: null,
+      appliedModel: { provider: "anthropic", id: "claude-opus-4-6" },
+    }),
+  });
+
+  await autoLoop(ctx, pi, s, deps);
+
+  assert.equal(pi.calls.length, 0, "provider readiness cancellation must not dispatch a message");
+  assert.ok(deps.callLog.includes("pauseAuto"), "provider readiness cancellation should pause auto-mode");
+  assert.ok(!deps.callLog.includes("stopAuto"), "provider readiness cancellation should not hard-stop auto-mode");
+  assert.ok(
+    !deps.callLog.includes("postUnitPreVerification"),
+    "post-unit verification must not run after pre-dispatch provider cancellation",
+  );
+  assert.ok(
+    notifications.some(n => /Provider anthropic is not request-ready/.test(n.message)),
+    "provider pause should notify with the readiness failure",
+  );
+});
+
 test("autoLoop passes structured session-lock failure details to the handler", async () => {
   _resetPendingResolve();
 
@@ -1423,9 +1650,16 @@ test("auto-timeout-recovery.ts calls resolveAgentEnd instead of dispatchNextUnit
     !src.includes("await dispatchNextUnit"),
     "auto-timeout-recovery.ts must not call dispatchNextUnit",
   );
+  // After PR #4716, advance branches go through bumpAndResolveSynthetic()
+  // (which bumps the turn epoch and calls resolveAgentEnd atomically).
+  // Either direct resolveAgentEnd() or the helper satisfies the invariant:
+  // the loop must be re-iterated on timeout recovery.
+  const reIteratesLoop =
+    src.includes("resolveAgentEnd(") ||
+    src.includes("bumpAndResolveSynthetic(");
   assert.ok(
-    src.includes("resolveAgentEnd("),
-    "auto-timeout-recovery.ts must call resolveAgentEnd to re-iterate the loop on timeout recovery",
+    reIteratesLoop,
+    "auto-timeout-recovery.ts must call resolveAgentEnd (directly or via bumpAndResolveSynthetic) to re-iterate the loop on timeout recovery",
   );
 });
 

package/src/resources/extensions/gsd/tests/auto-mode-guards.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression tests for auto-mode guards (#4704 Tier 2 / #4712).
+ *
+ * Validates the defense-in-depth writer asserts in milestone-actions.ts —
+ * parkMilestone, unparkMilestone, and discardMilestone must refuse to run
+ * while auto-mode is active, regardless of the calling dispatch path.
+ */
+import { describe, test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { parkMilestone, unparkMilestone, discardMilestone } from '../milestone-actions.ts';
+import { _setAutoActiveForTest } from '../auto.ts';
+
+function createFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-guard-test-'));
+  const mDir = join(base, '.gsd', 'milestones', 'M001');
+  mkdirSync(mDir, { recursive: true });
+  writeFileSync(join(mDir, 'M001-ROADMAP.md'), '# M001\n', 'utf-8');
+  return base;
+}
+
+describe('auto-mode guards (milestone-actions)', () => {
+  afterEach(() => {
+    _setAutoActiveForTest(false);
+  });
+
+  test('parkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => parkMilestone(base, 'M001', 'test'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('unparkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => unparkMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('discardMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => discardMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('parkMilestone proceeds normally when auto-mode is inactive', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(false);
+      const result = parkMilestone(base, 'M001', 'baseline');
+      assert.ok(result, 'park succeeds when auto is inactive');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/auto-model-selection.test.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-import { resolvePreferredModelConfig, resolveModelId } from "../auto-model-selection.js";
+import { resolvePreferredModelConfig, resolveModelId, selectAndApplyModel } from "../auto-model-selection.js";
 
 function makeTempDir(prefix: string): string {
   return mkdtempSync(join(tmpdir(), prefix));
@@ -46,6 +46,7 @@ test("resolvePreferredModelConfig synthesizes heavy routing ceiling when models
     assert.deepEqual(config, {
       primary: "claude-opus-4-6",
       fallbacks: [],
+      source: "synthesized",
     });
   } finally {
     process.chdir(originalCwd);
@@ -88,6 +89,7 @@ test("resolvePreferredModelConfig falls back to auto start model when heavy tier
     assert.deepEqual(config, {
       primary: "openai/gpt-5.4",
       fallbacks: [],
+      source: "synthesized",
     });
   } finally {
     process.chdir(originalCwd);
@@ -131,6 +133,7 @@ test("resolvePreferredModelConfig keeps explicit phase models as the ceiling", (
     assert.deepEqual(config, {
       primary: "claude-sonnet-4-6",
       fallbacks: [],
+      source: "explicit",
     });
   } finally {
     process.chdir(originalCwd);
@@ -141,6 +144,85 @@ test("resolvePreferredModelConfig keeps explicit phase models as the ceiling", (
   }
 });
 
+test("selectAndApplyModel honors explicit phase models without downgrading (#3617)", async () => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = makeTempDir("gsd-routing-project-");
+  const tempGsdHome = makeTempDir("gsd-routing-home-");
+  const setModelCalls: string[] = [];
+  let beforeModelSelectCalled = false;
+
+  try {
+    mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(tempProject, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "models:",
+        "  planning: claude-opus-4-6",
+        "dynamic_routing:",
+        "  enabled: true",
+        "  tier_models:",
+        "    light: gpt-4o-mini",
+        "    standard: claude-sonnet-4-6",
+        "    heavy: claude-opus-4-6",
+        "---",
+      ].join("\n"),
+      "utf-8",
+    );
+    process.env.GSD_HOME = tempGsdHome;
+    process.chdir(tempProject);
+
+    const availableModels = [
+      { id: "claude-opus-4-6", provider: "anthropic", api: "anthropic-messages" },
+      { id: "claude-sonnet-4-6", provider: "anthropic", api: "anthropic-messages" },
+      { id: "gpt-4o-mini", provider: "openai", api: "responses" },
+    ];
+
+    const result = await selectAndApplyModel(
+      {
+        modelRegistry: { getAvailable: () => availableModels },
+        sessionManager: { getSessionId: () => "test-session" },
+        ui: { notify: () => {} },
+        model: { provider: "anthropic", id: "claude-opus-4-6", api: "anthropic-messages" },
+      } as any,
+      {
+        setModel: async (model: { provider: string; id: string }) => {
+          setModelCalls.push(`${model.provider}/${model.id}`);
+          return true;
+        },
+        emitBeforeModelSelect: async () => {
+          beforeModelSelectCalled = true;
+          return undefined;
+        },
+        getActiveTools: () => [],
+        emitAdjustToolSet: async () => undefined,
+        setActiveTools: () => {},
+      } as any,
+      "plan-slice",
+      "slice-1",
+      tempProject,
+      undefined,
+      false,
+      { provider: "anthropic", id: "claude-opus-4-6" },
+      undefined,
+      true,
+    );
+
+    assert.equal(beforeModelSelectCalled, false, "explicit phase models should skip dynamic routing hooks");
+    assert.deepEqual(setModelCalls, ["anthropic/claude-opus-4-6"]);
+    assert.equal(result.routing, null, "explicit phase models should not record a routing downgrade");
+    assert.equal(result.appliedModel?.provider, "anthropic");
+    assert.equal(result.appliedModel?.id, "claude-opus-4-6");
+  } finally {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  }
+});
+
 // ─── resolveModelId tests ─────────────────────────────────────────────────
 
 test("resolveModelId: bare ID resolves to claude-code when session is claude-code (#3772)", () => {
@@ -259,6 +341,18 @@ test("dynamic routing passes provider-qualified model keys to the router", () =>
   );
 });
 
+test("selectAndApplyModel re-applies captured thinking level after setModel success", () => {
+  const src = readFileSync(join(__dirname, "..", "auto-model-selection.ts"), "utf-8");
+  assert.ok(
+    src.includes("autoModeStartThinkingLevel?: ReturnType<ExtensionAPI[\"getThinkingLevel\"]> | null"),
+    "selectAndApplyModel should accept an autoModeStartThinkingLevel parameter",
+  );
+  assert.ok(
+    src.includes("reapplyThinkingLevel(pi, autoModeStartThinkingLevel)"),
+    "selectAndApplyModel should re-apply captured thinking level after model changes",
+  );
+});
+
 test("resolveModelId: anthropic wins over claude-code when session provider is not claude-code", () => {
   const availableModels = [
     { id: "claude-sonnet-4-6", provider: "claude-code" },

package/src/resources/extensions/gsd/tests/auto-paused-session-validation.test.ts

@@ -39,6 +39,18 @@ test("auto.ts validates milestone before restoring paused session (#1664)", () =
     source.includes('resolveMilestoneFile(base, meta.milestoneId, "SUMMARY")'),
     "auto.ts must check for SUMMARY file to detect completed milestones",
   );
+
+  // Resume path must sanitize paused session file metadata before unlink/recovery.
+  assert.ok(
+    source.includes("normalizeSessionFilePath(meta.sessionFile ?? null)"),
+    "auto.ts must sanitize paused-session metadata sessionFile before using it",
+  );
+
+  // Pause path must sanitize live session file path before persisting metadata.
+  assert.ok(
+    source.includes("normalizeSessionFilePath(ctx?.sessionManager?.getSessionFile() ?? null)"),
+    "auto.ts must sanitize sessionManager getSessionFile output before persisting",
+  );
 });
 
 // ─── Filesystem validation unit tests ───────────────────────────────────────

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

@@ -706,6 +706,79 @@ test("verifyExpectedArtifact complete-milestone passes with impl files (#1703)",
   }
 });
 
+test("verifyExpectedArtifact complete-milestone fails when DB milestone is not complete (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-active"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nverification FAILED — not complete.");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation with failed summary"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, false, "complete-milestone must fail when DB status is not complete");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact complete-milestone passes when DB milestone is complete (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-complete"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nDone.");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation complete"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, true, "complete-milestone should pass when DB status is complete");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact complete-milestone tolerates transient DB lag when SUMMARY is canonical success (#4658)", () => {
+  const base = makeGitBase();
+  try {
+    execFileSync("git", ["checkout", "-b", "feat/ms-db-lag-success"], { cwd: base, stdio: "ignore" });
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"),
+      [
+        "---",
+        "id: M001",
+        "status: complete",
+        "---",
+        "",
+        "# M001: Success",
+      ].join("\n"),
+    );
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "app.ts"), "console.log('hello');");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: implementation with stale db"], { cwd: base, stdio: "ignore" });
+
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+
+    const result = verifyExpectedArtifact("complete-milestone", "M001", base);
+    assert.equal(result, true, "canonical success SUMMARY should pass verification during transient DB lag");
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("verifyExpectedArtifact checks pending gate-evaluate artifacts without ESM require failures", () => {
   const base = makeTmpProject();
 
@@ -775,6 +848,55 @@ test("#4414: parallel-research sentinel path does not collide with RESEARCH suff
   }
 });
 
+test("#4068: verifyExpectedArtifact parallel-research treats PARALLEL-BLOCKER as terminal completion", () => {
+  // Regression: when a parallel-research unit times out and the timeout-recovery
+  // machinery writes a PARALLEL-BLOCKER placeholder, verifyExpectedArtifact must
+  // return true so the dispatch loop can advance.  Previously it only returned
+  // true when every slice had a RESEARCH file — meaning a timeout always left
+  // verifyExpectedArtifact returning false, the unit was never cleared from
+  // unitDispatchCount, and the dispatch rule re-fired on the next iteration
+  // (infinite loop, issue #4068 / #4355).
+  const base = makeTmpBase();
+  try {
+    // Write a minimal roadmap
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      [
+        "# M001: Timeout Test",
+        "",
+        "## Slices",
+        "",
+        "- [ ] **S01: Alpha** `risk:low` `depends:[]`",
+        "- [ ] **S02: Beta** `risk:low` `depends:[]`",
+        "",
+      ].join("\n"),
+      "utf-8",
+    );
+
+    // No RESEARCH files written — subagents timed out
+    clearParseCache();
+    invalidateAllCaches();
+
+    // Simulate timeout-recovery writing the PARALLEL-BLOCKER placeholder
+    const blockerPath = resolveExpectedArtifactPath("research-slice", "M001/parallel-research", base);
+    assert.ok(blockerPath, "PARALLEL-BLOCKER path must resolve for parallel-research unit");
+    writeFileSync(blockerPath!, "# BLOCKER — timeout recovery\n\n**Reason**: hard timeout.\n", "utf-8");
+
+    clearParseCache();
+    invalidateAllCaches();
+
+    // After blocker is written, verifyExpectedArtifact must return true
+    // so the dispatch loop treats this unit as complete and moves on.
+    assert.equal(
+      verifyExpectedArtifact("research-slice", "M001/parallel-research", base),
+      true,
+      "#4068: PARALLEL-BLOCKER on disk must satisfy verifyExpectedArtifact so the loop does not re-dispatch",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("#4414: verifyExpectedArtifact parallel-research succeeds when all research-ready slices have RESEARCH", () => {
   const base = makeTmpBase();
   try {