gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/src/resources/extensions/gsd/tests/crash-handler-secondary.test.ts

@@ -13,11 +13,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:f
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { installEpipeGuard } from "../bootstrap/register-extension.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-test-${randomUUID()}`);
@@ -25,13 +22,6 @@ function makeTmpBase(): string {
   return base;
 }
 
-// ─── register-extension source assertions ────────────────────────────────────
-
-const registerExtSrc = readFileSync(
-  join(__dirname, '..', 'bootstrap', 'register-extension.ts'),
-  'utf-8',
-);
-
 describe('register-extension crash handler secondary fixes (#3348)', () => {
   test('writeCrashLog is exported and writes a file to the crash directory', async () => {
     // Dynamic import so GSD_HOME can be pointed at a temp dir without polluting ~/.gsd
@@ -60,30 +50,44 @@ describe('register-extension crash handler secondary fixes (#3348)', () => {
   });
 
   test('_gsdRejectionGuard is registered for unhandledRejection', () => {
-    assert.match(
-      registerExtSrc,
-      /_gsdRejectionGuard/,
-      '_gsdRejectionGuard handler should be defined',
-    );
-    assert.match(
-      registerExtSrc,
-      /unhandledRejection/,
-      'installEpipeGuard should register an unhandledRejection handler',
+    installEpipeGuard();
+    const listener = process.listeners("unhandledRejection").find((candidate) =>
+      candidate.name === "_gsdRejectionGuard"
     );
+    assert.ok(listener, 'installEpipeGuard should register an unhandledRejection handler');
   });
 
-  test('_gsdEpipeGuard calls process.exit(1) for unrecoverable errors, not log-and-continue', () => {
-    // The original #3696 fix replaced "throw err" with a log-and-continue.
-    // The secondary fix replaces that with writeCrashLog + process.exit(1).
-    assert.ok(
-      !registerExtSrc.includes('process.stderr.write(`[gsd] uncaught extension error (non-fatal)'),
-      '_gsdEpipeGuard should NOT log errors as non-fatal and continue',
-    );
-    assert.match(
-      registerExtSrc,
-      /process\.exit\(1\)/,
-      '_gsdEpipeGuard should call process.exit(1) for unrecoverable errors',
+  test('_gsdEpipeGuard writes a crash log and exits for unrecoverable errors', () => {
+    installEpipeGuard();
+    const listener = process.listeners("uncaughtException").find((candidate) =>
+      candidate.name === "_gsdEpipeGuard"
     );
+    assert.ok(listener, '_gsdEpipeGuard should be registered');
+
+    const tmpHome = join(tmpdir(), `gsd-crash-exit-test-${randomUUID()}`);
+    const origHome = process.env.GSD_HOME;
+    const originalExit = process.exit;
+    let exitCode: number | string | null | undefined;
+    (process as any).exit = (code?: number | string | null | undefined): never => {
+      exitCode = code;
+      throw new Error("process.exit intercepted");
+    };
+    process.env.GSD_HOME = tmpHome;
+    try {
+      assert.throws(
+        () => listener(new Error("unrecoverable crash guard test"), "uncaughtException"),
+        /process\.exit intercepted/,
+      );
+      assert.equal(exitCode, 1);
+      const crashDir = join(tmpHome, "crash");
+      const logs = readdirSync(crashDir).filter((f) => f.endsWith(".log"));
+      assert.equal(logs.length, 1);
+      assert.match(readFileSync(join(crashDir, logs[0]), "utf-8"), /unrecoverable crash guard test/);
+    } finally {
+      (process as any).exit = originalExit;
+      process.env.GSD_HOME = origHome;
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
   });
 
   test('writeCrashLog never throws even when directory is unwritable', async () => {
@@ -232,4 +236,59 @@ describe('emitCrashRecoveredUnitEnd (#3348)', () => {
       rmSync(base, { recursive: true, force: true });
     }
   });
+
+  test('emitOpenUnitEndForUnit closes the latest open start with error context', async () => {
+    const base = makeTmpBase();
+    try {
+      const { emitJournalEvent, queryJournal } = await import('../journal.ts');
+      const { emitOpenUnitEndForUnit } = await import('../crash-recovery.ts');
+
+      const firstFlowId = randomUUID();
+      const secondFlowId = randomUUID();
+      emitJournalEvent(base, {
+        ts: new Date().toISOString(),
+        flowId: firstFlowId,
+        seq: 1,
+        eventType: 'unit-start',
+        data: { unitType: 'execute-task', unitId: 'M008/S04/T02' },
+      });
+      emitJournalEvent(base, {
+        ts: new Date().toISOString(),
+        flowId: firstFlowId,
+        seq: 2,
+        eventType: 'unit-end',
+        data: { unitType: 'execute-task', unitId: 'M008/S04/T02', status: 'completed' },
+        causedBy: { flowId: firstFlowId, seq: 1 },
+      });
+      emitJournalEvent(base, {
+        ts: new Date().toISOString(),
+        flowId: secondFlowId,
+        seq: 3,
+        eventType: 'unit-start',
+        data: { unitType: 'execute-task', unitId: 'M008/S04/T02' },
+      });
+
+      const emitted = emitOpenUnitEndForUnit(
+        base,
+        'execute-task',
+        'M008/S04/T02',
+        'cancelled',
+        { message: 'runUnitPhase exploded', category: 'unit-exception', isTransient: false },
+      );
+
+      assert.equal(emitted, true, 'open unit should be closed');
+      const ends = queryJournal(base).filter((e) => e.eventType === 'unit-end');
+      assert.equal(ends.length, 2, 'should preserve existing end and add one new end');
+      const newEnd = ends.find((e) => e.causedBy?.flowId === secondFlowId);
+      assert.ok(newEnd, 'new end should close the latest open start');
+      assert.equal(newEnd!.data?.status, 'cancelled');
+      assert.deepEqual(newEnd!.data?.errorContext, {
+        message: 'runUnitPhase exploded',
+        category: 'unit-exception',
+        isTransient: false,
+      });
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/crash-recovery-via-db.test.ts

@@ -30,6 +30,7 @@ import {
   isLockProcessAlive,
 } from "../crash-recovery.ts";
 import { normalizeRealPath } from "../paths.ts";
+import { writeUnitRuntimeRecord } from "../unit-runtime.ts";
 
 function makeBase(): string {
   const base = mkdtempSync(join(tmpdir(), "gsd-crash-recovery-"));
@@ -102,6 +103,27 @@ test("readCrashLock synthesizes LockData from a stale dead worker (no dispatches
   assert.ok(lock!.startedAt, "startedAt populated from workers.started_at");
 });
 
+test("readCrashLock falls back to latest in-flight runtime record when dispatch claim is missing", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  const projectRoot = normalizeRealPath(base);
+  const workerId = registerAutoWorker({ projectRootRealpath: projectRoot });
+  writeUnitRuntimeRecord(base, "execute-task", "M008/S04/T02", 1778069087937, {
+    phase: "dispatched",
+    lastProgressAt: 1778069087937,
+    lastProgressKind: "dispatch",
+  });
+  setWorkerPid(workerId, 99999);
+  expireWorker(workerId);
+
+  const lock = readCrashLock(base);
+  assert.ok(lock, "stale worker surfaced as a crash lock");
+  assert.equal(lock!.unitType, "execute-task");
+  assert.equal(lock!.unitId, "M008/S04/T02");
+  assert.equal(lock!.unitStartedAt, new Date(1778069087937).toISOString());
+});
+
 test("readCrashLock includes the most recent dispatch as unitType/unitId", (t) => {
   const base = makeBase();
   t.after(() => cleanup(base));

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -15,6 +15,7 @@ import { tmpdir } from "node:os";
 import { autoLoop } from "../auto/loop.js";
 import { resolveAgentEnd, _hasPendingResolveForTest, _resetPendingResolve } from "../auto/resolve.js";
 import type { LoopDeps } from "../auto/loop-deps.js";
+import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import type { SessionLockStatus } from "../session-lock.js";
 import { writeGraph, readGraph, type WorkflowGraph, type GraphStep } from "../graph.ts";
 import { writeFileSync } from "node:fs";
@@ -172,7 +173,6 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     rebuildState: async () => {},
     loadEffectiveGSDPreferences: () => undefined,
     preDispatchHealthGate: async () => ({ proceed: true, fixesApplied: [] }),
-    syncProjectRootToWorktree: () => {},
     checkResourcesStale: () => null,
     validateSessionLock: () => ({ valid: true } as SessionLockStatus),
     updateSessionLock: () => {},
@@ -182,7 +182,6 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     pruneQueueOrder: () => {},
     isInAutoWorktree: () => false,
     shouldUseWorktreeIsolation: () => false,
-    mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: false }),
     teardownAutoWorktree: () => {},
     createAutoWorktree: () => "/tmp/wt",
     captureIntegrationBranch: () => {},
@@ -192,7 +191,11 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
     preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
-    postflightPopStash: () => {},
+    postflightPopStash: () => ({
+      restored: true,
+      needsManualRecovery: false,
+      message: "restored",
+    }),
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,
@@ -224,15 +227,19 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     readFileSync: () => "",
     atomicWriteSync: () => {},
     GitServiceImpl: class {} as any,
-    resolver: {
-      get workPath() { return "/tmp/project"; },
-      get projectRoot() { return "/tmp/project"; },
-      get lockPath() { return "/tmp/project"; },
-      enterMilestone: () => {},
-      exitMilestone: () => {},
-      mergeAndExit: () => {},
-      mergeAndEnterNext: () => {},
+    lifecycle: {
+      enterMilestone: () => ({ ok: true, mode: "none", path: "/tmp/project" }),
+      exitMilestone: (_mid: string, opts: { merge: boolean }) => ({
+        ok: true,
+        merged: opts.merge,
+        codeFilesChanged: false,
+      }),
+      degradeToBranchMode: () => {},
+      restoreToProjectRoot: () => {},
+      isInMilestone: () => true,
+      getCurrentMilestoneIfAny: () => "M001",
     } as any,
+    worktreeProjection: new WorktreeStateProjection(),
     postUnitPreVerification: async () => "continue" as const,
     runPostUnitVerification: async () => "continue" as const,
     postUnitPostVerification: async () => "continue" as const,
@@ -372,6 +379,158 @@ describe("Custom engine loop integration", () => {
     assert.ok(stopEntry?.includes("Workflow complete"), "Should stop with 'Workflow complete'");
   });
 
+  it("finalizes custom-engine complete turns and clears current turn state", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([
+      makeStep({ id: "step-a", status: "complete" }),
+    ], "already-done");
+    writeGraph(runDir, graph);
+    writeDefinition(runDir, graph.steps, "already-done");
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const turnResults: Array<{ status: string; failureClass: string; error?: string }> = [];
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+      uokObserver: {
+        onTurnStart: () => {},
+        onTurnResult: (result) => {
+          deps.callLog.push(`turnResult:${result.status}`);
+          turnResults.push({
+            status: result.status,
+            failureClass: result.failureClass,
+            error: result.error,
+          });
+        },
+        onPhaseResult: () => {},
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.deepEqual(turnResults, [{ status: "completed", failureClass: "none", error: undefined }]);
+    assert.ok(
+      deps.callLog.includes("journal:iteration-end"),
+      `complete workflow should emit iteration-end; log=${deps.callLog.join(",")}`,
+    );
+    assert.ok(
+      deps.callLog.indexOf("turnResult:completed") < deps.callLog.indexOf("stopAuto:Workflow complete"),
+      `turn should finalize before stopAuto; log=${deps.callLog.join(",")}`,
+    );
+    assert.equal(s.currentTraceId, null);
+    assert.equal(s.currentTurnId, null);
+    assert.equal(pi.calls.length, 0, "complete workflow should not dispatch work");
+  });
+
+  it("stops blocked custom workflows and clears current turn state", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([
+      makeStep({ id: "step-a", dependsOn: ["step-b"] }),
+      makeStep({ id: "step-b", dependsOn: ["step-a"] }),
+    ], "blocked-workflow");
+    writeGraph(runDir, graph);
+    writeDefinition(runDir, graph.steps, "blocked-workflow");
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const turnResults: Array<{ status: string; failureClass: string; error?: string }> = [];
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+      uokObserver: {
+        onTurnStart: () => {},
+        onTurnResult: (result) => {
+          turnResults.push({
+            status: result.status,
+            failureClass: result.failureClass,
+            error: result.error,
+          });
+        },
+        onPhaseResult: () => {},
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.equal(turnResults.length, 1);
+    assert.equal(turnResults[0].status, "stopped");
+    assert.equal(turnResults[0].failureClass, "manual-attention");
+    assert.match(turnResults[0].error ?? "", /custom-engine-dispatch-stop/);
+    assert.ok(
+      deps.callLog.includes("journal:iteration-end"),
+      `blocked workflow should emit iteration-end; log=${deps.callLog.join(",")}`,
+    );
+    assert.equal(s.currentTraceId, null);
+    assert.equal(s.currentTurnId, null);
+    assert.equal(pi.calls.length, 0, "blocked workflow should not dispatch a custom step");
+    assert.match(
+      deps.callLog.find((e: string) => e.startsWith("stopAuto:")) ?? "",
+      /Workflow blocked: no pending steps are ready/,
+    );
+  });
+
+  it("finalizes the active turn when the session lock is lost", async () => {
+    _resetPendingResolve();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession();
+    const turnResults: Array<{ status: string; failureClass: string; error?: string }> = [];
+    const deps = makeMockDeps({
+      validateSessionLock: () => ({
+        valid: false,
+        failureReason: "pid-mismatch",
+        expectedPid: 111,
+        existingPid: 222,
+      } as SessionLockStatus),
+      handleLostSessionLock: () => {
+        deps.callLog.push("handleLostSessionLock");
+      },
+      uokObserver: {
+        onTurnStart: () => {},
+        onTurnResult: (result) => {
+          turnResults.push({
+            status: result.status,
+            failureClass: result.failureClass,
+            error: result.error,
+          });
+        },
+        onPhaseResult: () => {},
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.deepEqual(turnResults, [{
+      status: "stopped",
+      failureClass: "manual-attention",
+      error: "session-lock-lost",
+    }]);
+    assert.equal(s.currentTraceId, null);
+    assert.equal(s.currentTurnId, null);
+    assert.equal(pi.calls.length, 0, "lost session lock must not dispatch work");
+    assert.ok(deps.callLog.includes("handleLostSessionLock"));
+  });
+
   it("does not call runPreDispatch or runFinalize on the custom path", async () => {
     _resetPendingResolve();
 
@@ -512,11 +671,16 @@ describe("Custom engine loop integration", () => {
       activeRunDir: runDir,
       basePath: runDir,
     });
+    const journalEvents: Array<{ eventType: string; data?: any }> = [];
     const deps = makeMockDeps({
       stopAuto: async (_ctx, _pi, reason) => {
         deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
         s.active = false;
       },
+      emitJournalEvent: (entry: any) => {
+        journalEvents.push(entry);
+        deps.callLog.push(`journal:${entry.eventType}`);
+      },
     });
 
     const resolver = setInterval(() => {
@@ -548,6 +712,21 @@ describe("Custom engine loop integration", () => {
     assert.match(stopEntry ?? "", /requested retry 4 times without passing/);
     const finalGraph = readGraph(runDir);
     assert.equal(finalGraph.steps[0]?.status, "active", "failed verification must not reconcile the step complete");
+
+    const unitEndIndexes = journalEvents
+      .map((entry, index) => entry.eventType === "unit-end" ? index : -1)
+      .filter((index) => index >= 0);
+    const iterationEndIndexes = journalEvents
+      .map((entry, index) => entry.eventType === "iteration-end" ? index : -1)
+      .filter((index) => index >= 0);
+    assert.equal(unitEndIndexes.length, 4, "each custom verification retry/stop attempt must emit unit-end");
+    assert.equal(iterationEndIndexes.length, 4, "each custom verification retry/stop iteration must close after unit-end");
+    for (const [i, unitEndIndex] of unitEndIndexes.entries()) {
+      assert.ok(
+        iterationEndIndexes[i]! > unitEndIndex,
+        `custom verification attempt ${i + 1} should emit iteration-end after unit-end`,
+      );
+    }
   });
 
   it("persists custom verification retry budget across a session restart", async () => {

package/src/resources/extensions/gsd/tests/custom-verify-retry-store.test.ts

@@ -0,0 +1,139 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for custom workflow verification retry persistence.
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  customVerifyRetryStatePath,
+  hydrateCustomVerifyRetryCounts,
+  saveCustomVerifyRetryCounts,
+} from "../auto/custom-verify-retry-store.ts";
+
+function makeSession(activeRunDir: string): {
+  activeRunDir: string;
+  basePath: string;
+  verificationRetryCount: Map<string, number>;
+} {
+  return {
+    activeRunDir,
+    basePath: activeRunDir,
+    verificationRetryCount: new Map<string, number>(),
+  };
+}
+
+test("hydrateCustomVerifyRetryCounts loads positive finite counts from disk", () => {
+    const dir = mkdtempSync(join(tmpdir(), "gsd-verify-retries-"));
+  try {
+    const session = makeSession(dir);
+    mkdirSync(join(dir, "runtime"));
+    writeFileSync(customVerifyRetryStatePath(session), JSON.stringify({
+      counts: {
+        "execute-task/M001/S001/T001": 2.8,
+        "execute-task/M001/S001/T002": 1,
+        zero: 0,
+        negative: -1,
+        infinite: Number.POSITIVE_INFINITY,
+        string: "3",
+      },
+    }));
+
+    const logged: unknown[] = [];
+    const counts = hydrateCustomVerifyRetryCounts(session, {
+      logFailure: err => logged.push(err),
+    });
+
+    assert.equal(counts, session.verificationRetryCount);
+    assert.deepEqual([...counts.entries()], [
+      ["execute-task/M001/S001/T001", 2],
+      ["execute-task/M001/S001/T002", 1],
+    ]);
+    assert.deepEqual(logged, []);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("hydrateCustomVerifyRetryCounts keeps existing in-memory counts", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-verify-retries-"));
+  try {
+    const session = makeSession(dir);
+    session.verificationRetryCount.set("existing", 4);
+
+    const counts = hydrateCustomVerifyRetryCounts(session, {
+      logFailure: () => assert.fail("logFailure should not be called"),
+    });
+
+    assert.deepEqual([...counts.entries()], [["existing", 4]]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("hydrateCustomVerifyRetryCounts logs read failures and returns the existing map", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-verify-retries-"));
+  try {
+    const session = makeSession(dir);
+    const logged: unknown[] = [];
+
+    const counts = hydrateCustomVerifyRetryCounts(session, {
+      logFailure: err => logged.push(err),
+    });
+
+    assert.equal(counts, session.verificationRetryCount);
+    assert.equal(counts.size, 0);
+    assert.equal(logged.length, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("saveCustomVerifyRetryCounts writes counts with an updated timestamp", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-verify-retries-"));
+  try {
+    const session = makeSession(dir);
+    session.verificationRetryCount.set("execute-task/M001/S001/T001", 3);
+
+    saveCustomVerifyRetryCounts(session, {
+      logFailure: () => assert.fail("logFailure should not be called"),
+    });
+
+    const saved = JSON.parse(readFileSync(customVerifyRetryStatePath(session), "utf-8"));
+    assert.deepEqual(saved.counts, {
+      "execute-task/M001/S001/T001": 3,
+    });
+    assert.equal(typeof saved.updatedAt, "string");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("saveCustomVerifyRetryCounts deletes empty retry files and ignores missing files", () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-verify-retries-"));
+  try {
+    const session = makeSession(dir);
+    session.verificationRetryCount.set("execute-task/M001/S001/T001", 1);
+    saveCustomVerifyRetryCounts(session, {
+      logFailure: () => assert.fail("logFailure should not be called"),
+    });
+
+    session.verificationRetryCount.clear();
+    saveCustomVerifyRetryCounts(session, {
+      logFailure: () => assert.fail("logFailure should not be called"),
+    });
+    saveCustomVerifyRetryCounts(session, {
+      logFailure: () => assert.fail("logFailure should not be called"),
+    });
+
+    const logged: unknown[] = [];
+    hydrateCustomVerifyRetryCounts(session, {
+      logFailure: err => logged.push(err),
+    });
+    assert.equal(logged.length, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/custom-workflow-engine.test.ts

@@ -193,6 +193,56 @@ describe("CustomWorkflowEngine.resolveDispatch", () => {
     }
   });
 
+  it("returns stop with dependency details when pending steps are blocked", async () => {
+    const { engine } = setupEngine([
+      makeStep({ id: "a", dependsOn: ["b"] }),
+      makeStep({ id: "b", dependsOn: ["a"] }),
+    ]);
+
+    const state = await engine.deriveState("/unused");
+    const dispatch = await engine.resolveDispatch(state, { basePath: "/unused" });
+
+    assert.equal(dispatch.action, "stop");
+    if (dispatch.action === "stop") {
+      assert.equal(dispatch.level, "error");
+      assert.match(dispatch.reason, /Workflow blocked/);
+      assert.match(dispatch.reason, /a waiting on b \(pending\)/);
+      assert.match(dispatch.reason, /b waiting on a \(pending\)/);
+    }
+  });
+
+  it("reports missing dependencies when no pending step can run", async () => {
+    const { engine } = setupEngine([
+      makeStep({ id: "a", dependsOn: ["missing-step"] }),
+    ]);
+
+    const state = await engine.deriveState("/unused");
+    const dispatch = await engine.resolveDispatch(state, { basePath: "/unused" });
+
+    assert.equal(dispatch.action, "stop");
+    if (dispatch.action === "stop") {
+      assert.equal(dispatch.level, "error");
+      assert.match(dispatch.reason, /a waiting on missing-step \(missing\)/);
+    }
+  });
+
+  it("does not report expanded dependencies as blockers", async () => {
+    const { engine } = setupEngine([
+      makeStep({ id: "iter", status: "expanded" }),
+      makeStep({ id: "after", dependsOn: ["iter", "missing-step"] }),
+    ]);
+
+    const state = await engine.deriveState("/unused");
+    const dispatch = await engine.resolveDispatch(state, { basePath: "/unused" });
+
+    assert.equal(dispatch.action, "stop");
+    if (dispatch.action === "stop") {
+      assert.equal(dispatch.level, "error");
+      assert.match(dispatch.reason, /after waiting on missing-step \(missing\)/);
+      assert.doesNotMatch(dispatch.reason, /iter \(expanded\)/);
+    }
+  });
+
   it("respects dependency ordering", async () => {
     const { engine } = setupEngine([
       makeStep({ id: "a" }),