@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

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

@@ -1,26 +1,203 @@
 // Project/App: gsd-pi
 // File Purpose: Auto Orchestration module contract and ADR-015 invariant sequence tests.
+//
+// Phase 2 of #442 collapsed the nine adapter seams into AutoOrchestrator. These
+// tests therefore drive the REAL collapsed orchestrator against real temp
+// SQLite + git fixtures (fixture builder modelled on
+// state-reconciliation-drift.test.ts) and inject dispatch decisions through the
+// real unified rule registry (setRegistry) rather than mock adapters. Decision
+// logic is asserted on observable advance() outcomes and journal events instead
+// of an internal calls[] array. Dispatch-decision parity (formerly the
+// createWiredDispatchAdapter tests) is asserted against the exported pure
+// decideOrchestratorDispatch helper.
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createAutoOrchestrator, STUCK_WINDOW_SIZE } from "../auto/orchestrator.js";
-import type { AutoOrchestratorDeps } from "../auto/contracts.js";
+import {
+  createAutoOrchestrator,
+  decideOrchestratorDispatch,
+  resolveLiveOrchestratorBasePath,
+  STUCK_WINDOW_SIZE,
+} from "../auto/orchestrator.js";
+import type { OrchestratorContext } from "../auto/orchestrator.js";
+import type { AutoOrchestrationModule, AutoSessionContext } from "../auto/contracts.js";
 import type { GSDState } from "../types.js";
-import { createWiredDispatchAdapter, resolveLiveOrchestratorBasePath } from "../auto.js";
 import { resolveDispatch, type DispatchContext } from "../auto-dispatch.js";
 import { RuleRegistry, setRegistry, resetRegistry } from "../rule-registry.js";
 import type { UnifiedRule } from "../rule-types.js";
 import { supportsStructuredQuestions } from "../workflow-mcp.js";
-import { closeDatabase, insertMilestone, insertSlice, insertTask, openDatabase } from "../gsd-db.js";
+import {
+  closeDatabase,
+  insertAssessment,
+  insertGateRow,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.js";
+import { AutoSession } from "../auto/session.js";
+import { acquireSessionLock, releaseSessionLock } from "../session-lock.js";
+import { queryJournal } from "../journal.js";
+import { invalidateAllCaches } from "../cache.js";
+import { invalidateStateCache } from "../state.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fixture builder
+//
+// Builds a real, isolated project: a git repo (so the pre-dispatch health gate
+// and merge-state reconciliation have something real to probe), a SQLite DB
+// seeded with one active milestone/slice/task, and the matching ROADMAP/PLAN
+// markdown projection. A real session lock is acquired so the orchestrator's
+// ensureLockOwnership passes. A fresh AutoSession is wired to the base path. A
+// dispatch rule is installed in the real unified registry so resolveDispatch
+// yields a deterministic decision — this is the only "injection", and it is the
+// same public seam (setRegistry) the dispatch engine already exposes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type DispatchRuleResult =
+  | { action: "dispatch"; unitType: string; unitId: string; prompt: string; pauseAfterDispatch?: boolean }
+  | { action: "stop"; reason: string; level: "info" | "warning" | "error" }
+  | { action: "skip"; matchedRule?: string };
+
+interface FixtureOptions {
+  /** When provided, the rule returns this result. Defaults to dispatching M001/S01/T01. */
+  dispatch?: () => DispatchRuleResult | Promise<DispatchRuleResult>;
+  /** Rule name (becomes the dispatch `reason`/`matchedRule`). */
+  ruleName?: string;
+  /** Skip seeding a ready task (used for the "no remaining units" / complete scenarios). */
+  noTask?: boolean;
+  /** Mark the seeded milestone complete (drives the completion → stopped path). */
+  complete?: boolean;
+}
 
-function assertBlockedResult(
-  result: Awaited<ReturnType<ReturnType<typeof createAutoOrchestrator>["advance"]>>,
-): asserts result is Extract<typeof result, { kind: "blocked" }> {
-  assert.equal(result.kind, "blocked");
+interface Fixture {
+  base: string;
+  session: AutoSession;
+  ctx: OrchestratorContext;
+  orchestrator: AutoOrchestrationModule;
+  /** Names emitted to the journal by the orchestrator (data.name), in order. */
+  journalNames(): string[];
+  cleanup(): void;
+}
+
+const DEFAULT_DISPATCH: DispatchRuleResult = {
+  action: "dispatch",
+  unitType: "execute-task",
+  unitId: "M001/S01/T01",
+  prompt: "fixture-prompt",
+};
+
+function gitInit(base: string): void {
+  execFileSync("git", ["init", "--initial-branch=main"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: base, stdio: "ignore" });
+  writeFileSync(join(base, ".gitkeep"), "");
+  execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", "initial"], { cwd: base, stdio: "ignore" });
+}
+
+function makeFixture(opts: FixtureOptions = {}): Fixture {
+  const base = mkdtempSync(join(tmpdir(), "gsd-orchestrator-"));
+  gitInit(base);
+
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const sliceDir = join(milestoneDir, "slices", "S01");
+  mkdirSync(join(sliceDir, "tasks"), { recursive: true });
+
+  invalidateAllCaches();
+  invalidateStateCache();
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone", status: opts.complete ? "complete" : "active" });
+  if (!opts.noTask && !opts.complete) {
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active", risk: "low", depends: [], demo: "", sequence: 1 });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task", status: "active" });
+  }
+
+  writeFileSync(
+    join(milestoneDir, "M001-ROADMAP.md"),
+    [
+      "# M001: Milestone",
+      "",
+      "**Vision:** Fixture milestone",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S01: Slice** `risk:low` `depends:[]`",
+      "",
+    ].join("\n"),
+  );
+  if (!opts.noTask && !opts.complete) {
+    writeFileSync(
+      join(sliceDir, "S01-PLAN.md"),
+      [
+        "# S01: Slice",
+        "",
+        "**Goal:** Fixture goal",
+        "**Demo:** Fixture demo",
+        "",
+        "## Must-Haves",
+        "",
+        "- Everything works",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: Task** `est:1h`",
+        "",
+      ].join("\n"),
+    );
+  }
+
+  acquireSessionLock(base);
+
+  const session = new AutoSession();
+  session.basePath = base;
+  session.originalBasePath = base;
+  session.currentMilestoneId = "M001";
+  session.resourceVersionOnStart = null;
+
+  const ctx: OrchestratorContext = {
+    ctx: { model: {}, modelRegistry: { getAll: () => [] }, ui: { notify() {} } } as never,
+    pi: { getActiveTools: () => [] } as never,
+    dispatchBasePath: base,
+    runtimeBasePath: base,
+    session,
+  };
+
+  const ruleName = opts.ruleName ?? "fixture-dispatch";
+  const decide = opts.dispatch ?? (() => DEFAULT_DISPATCH);
+  const rule: UnifiedRule = {
+    name: ruleName,
+    when: "dispatch",
+    evaluation: "first-match",
+    where: async () => decide(),
+    then: (r: unknown) => r,
+  };
+  setRegistry(new RuleRegistry([rule]));
+
+  const orchestrator = createAutoOrchestrator(ctx);
+
+  return {
+    base,
+    session,
+    ctx,
+    orchestrator,
+    journalNames() {
+      return queryJournal(base)
+        .map((e) => (e.data as Record<string, unknown> | undefined)?.name)
+        .filter((n): n is string => typeof n === "string");
+    },
+    cleanup() {
+      resetRegistry();
+      try { releaseSessionLock(base); } catch { /* */ }
+      try { closeDatabase(); } catch { /* */ }
+      try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+    },
+  };
 }
 
 function makeState(): GSDState {
@@ -38,637 +215,465 @@ function makeState(): GSDState {
   };
 }
 
-function makeDeps(overrides: Partial<AutoOrchestratorDeps> = {}): { deps: AutoOrchestratorDeps; calls: string[] } {
-  const calls: string[] = [];
-  const stateSnapshot = makeState();
-
-  const deps: AutoOrchestratorDeps = {
-    stateReconciliation: {
-      async reconcileBeforeDispatch() {
-        calls.push("state.reconcile");
-        return { ok: true, stateSnapshot };
-      },
-    },
-    dispatch: {
-      async decideNextUnit(input) {
-        calls.push("dispatch.decide");
-        assert.equal(input.stateSnapshot, stateSnapshot);
-        return { unitType: "execute-task", unitId: "T01", reason: "ready", preconditions: [] };
-      },
-    },
-    toolContract: {
-      async compileUnitToolContract() {
-        calls.push("tool.compile");
-        return { ok: true };
-      },
-    },
-    recovery: {
-      async classifyAndRecover() {
-        calls.push("recovery.classify");
-        return { action: "stop", reason: "fatal" };
-      },
-    },
-    worktree: {
-      async prepareForUnit() {
-        calls.push("worktree.prepare");
-        return { ok: true };
-      },
-      async syncAfterUnit() { calls.push("worktree.sync"); },
-      async cleanupOnStop() { calls.push("worktree.cleanup"); },
-    },
-    health: {
-      checkResourcesStale() {
-        calls.push("health.stale");
-        return null;
-      },
-      async preAdvanceGate() {
-        calls.push("health.pre");
-        return { kind: "pass" };
-      },
-      async postAdvanceRecord() { calls.push("health.post"); },
-    },
-    runtime: {
-      async ensureLockOwnership() { calls.push("runtime.lock"); },
-      async journalTransition(event) { calls.push(`journal:${event.name}`); },
-    },
-    notifications: {
-      async notifyLifecycle(event) { calls.push(`notify:${event.name}`); },
-    },
-    uokGate: {
-      async emit(input) { calls.push(`gate:${input.gateId}:${input.outcome}`); },
-    },
-  };
+const SESSION_CONTEXT: AutoSessionContext = { basePath: "/tmp/project", trigger: "manual" };
 
-  return { deps: { ...deps, ...overrides }, calls };
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// Lifecycle: start / resume / stop
+// ─────────────────────────────────────────────────────────────────────────────
 
-test("start() enters running phase without dispatching", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("start() enters running phase without dispatching", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.start({ basePath: "/tmp/project", trigger: "manual" });
+  const result = await f.orchestrator.start(SESSION_CONTEXT);
 
   assert.equal(result.kind, "started");
-  const status = orchestrator.getStatus();
+  const status = f.orchestrator.getStatus();
   assert.equal(status.phase, "running");
   assert.equal(status.activeUnit, undefined);
-  assert.ok(calls.includes("journal:start"));
-  assert.ok(!calls.includes("journal:advance"));
+  assert.ok(f.journalNames().includes("start"));
+  assert.ok(!f.journalNames().includes("advance"));
 });
 
-test("advance() returns blocked when health gate denies", async () => {
-  const { deps, calls } = makeDeps({
-    health: {
-      checkResourcesStale: () => null,
-      async preAdvanceGate() { return { kind: "fail", reason: "doctor-block" }; },
-      async postAdvanceRecord() {},
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("resume() enters running phase without dispatching", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.resume();
 
-  assertBlockedResult(result);
-  assert.equal(result.reason, "doctor-block");
-  assert.equal(result.action, "pause");
-  assert.ok(calls.includes("gate:pre-dispatch-health-gate:manual-attention"));
+  assert.equal(result.kind, "resumed");
+  assert.equal(f.orchestrator.getStatus().phase, "running");
+  assert.ok(!f.journalNames().includes("advance"));
 });
 
-test("advance() stops auto when health gate reports unrecoverable git probe", async () => {
-  const { deps } = makeDeps({
-    health: {
-      checkResourcesStale: () => null,
-      async preAdvanceGate() {
-        return { kind: "fail", reason: "Could not verify git conflict state", action: "stop" };
-      },
-      async postAdvanceRecord() {},
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("transitionCount increases across lifecycle transitions", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const before = f.orchestrator.getStatus().transitionCount;
+  await f.orchestrator.start(SESSION_CONTEXT);
+  const afterStart = f.orchestrator.getStatus().transitionCount;
+  await f.orchestrator.stop("done");
+  const afterStop = f.orchestrator.getStatus().transitionCount;
 
-  assertBlockedResult(result);
-  assert.equal(result.action, "stop");
+  assert.ok(afterStart > before);
+  assert.ok(afterStop > afterStart);
 });
 
-test("advance() returns blocked pause when resources are stale", async () => {
-  const { deps, calls } = makeDeps({
-    health: {
-      checkResourcesStale: () => "resources changed since session start",
-      async preAdvanceGate() { return { kind: "pass" }; },
-      async postAdvanceRecord() {},
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("stop() transitions to stopped and journals stop", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.stop("user-request");
 
-  assertBlockedResult(result);
-  assert.equal(result.reason, "resources changed since session start");
-  assert.equal(result.action, "pause");
-  assert.ok(calls.includes("gate:resource-version-guard:fail"));
-  assert.ok(!calls.includes("health.pre"));
-  assert.ok(!calls.includes("state.reconcile"));
+  assert.equal(result.kind, "stopped");
+  assert.equal(f.orchestrator.getStatus().phase, "stopped");
+  assert.ok(f.journalNames().includes("stop"));
 });
 
-test("advance() pre-dispatch parity: gate emissions and control-flow action match legacy branches", async () => {
-  type Scenario = {
-    name: string;
-    staleMsg: string | null;
-    gateResult: Awaited<ReturnType<AutoOrchestratorDeps["health"]["preAdvanceGate"]>>;
-    expectedKind: "advanced" | "blocked";
-    expectedAction?: "pause" | "stop";
-    expectedReason?: string;
-    expectedGates: string[];
-  };
-  const scenarios: Scenario[] = [
-    {
-      name: "pass",
-      staleMsg: null,
-      gateResult: { kind: "pass" },
-      expectedKind: "advanced",
-      expectedGates: [
-        "resource-version-guard:policy:pass:none:resource version guard passed:",
-        "pre-dispatch-health-gate:execution:pass:none:pre-dispatch health gate passed:",
-      ],
-    },
-    {
-      name: "resource-stale",
-      staleMsg: "resources changed since session start",
-      gateResult: { kind: "pass" },
-      expectedKind: "blocked",
-      expectedAction: "pause",
-      expectedReason: "resources changed since session start",
-      expectedGates: [
-        "resource-version-guard:policy:fail:policy:resource version guard blocked dispatch:resources changed since session start",
-      ],
-    },
-    {
-      name: "health-gate-fail",
-      staleMsg: null,
-      gateResult: { kind: "fail", reason: "doctor-block" },
-      expectedKind: "blocked",
-      expectedAction: "pause",
-      expectedReason: "doctor-block",
-      expectedGates: [
-        "resource-version-guard:policy:pass:none:resource version guard passed:",
-        "pre-dispatch-health-gate:execution:manual-attention:manual-attention:pre-dispatch health gate blocked dispatch:doctor-block",
-      ],
-    },
-  ];
-
-  for (const scenario of scenarios) {
-    const gateEvents: string[] = [];
-    const { deps } = makeDeps({
-      health: {
-        checkResourcesStale: () => scenario.staleMsg,
-        async preAdvanceGate() { return scenario.gateResult; },
-        async postAdvanceRecord() {},
-      },
-      uokGate: {
-        async emit(input) {
-          gateEvents.push(
-            `${input.gateId}:${input.gateType}:${input.outcome}:${input.failureClass}:${input.rationale}:${input.findings ?? ""}`,
-          );
-        },
-      },
-    });
-    const orchestrator = createAutoOrchestrator(deps);
-    const result = await orchestrator.advance();
-
-    assert.equal(result.kind, scenario.expectedKind, `${scenario.name} result kind`);
-    if (scenario.expectedKind === "blocked") {
-      assertBlockedResult(result);
-      assert.equal(result.action, scenario.expectedAction, `${scenario.name} blocked action`);
-      assert.equal(result.reason, scenario.expectedReason, `${scenario.name} blocked reason`);
-    }
-    assert.deepEqual(gateEvents, scenario.expectedGates, `${scenario.name} gate parity`);
-  }
-});
+// ─────────────────────────────────────────────────────────────────────────────
+// advance(): happy path + ADR-015 invariant sequence
+// ─────────────────────────────────────────────────────────────────────────────
 
-test("advance() continues past pre-dispatch health gate when it throws", async () => {
-  const { deps, calls } = makeDeps({
-    health: {
-      checkResourcesStale: () => null,
-      async preAdvanceGate() { return { kind: "threw", error: new Error("boom") }; },
-      async postAdvanceRecord() {},
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("advance() dispatches the resolved unit and journals advance", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
   assert.equal(result.kind, "advanced");
-  assert.ok(calls.includes("gate:pre-dispatch-health-gate:manual-attention"));
-  assert.ok(calls.includes("state.reconcile"));
-  assert.ok(calls.includes("dispatch.decide"));
+  if (result.kind !== "advanced") return;
+  assert.deepEqual(result.unit, { unitType: "execute-task", unitId: "M001/S01/T01" });
+  assert.equal(f.orchestrator.getStatus().phase, "running");
+  // Journal records the advance AFTER the invariant gates (lock, health,
+  // reconcile, dispatch, tool-contract, worktree) — i.e. no advance-blocked.
+  const names = f.journalNames();
+  assert.ok(names.includes("advance"));
+  assert.ok(!names.includes("advance-blocked"));
 });
 
-test("advance() forwards fixesApplied into pre-dispatch-health-gate pass findings", async () => {
-  let observed = "";
-  const { deps } = makeDeps({
-    health: {
-      checkResourcesStale: () => null,
-      async preAdvanceGate() { return { kind: "pass", fixesApplied: ["fix-a", "fix-b"] }; },
-      async postAdvanceRecord() {},
-    },
-    uokGate: {
-      async emit(input) {
-        if (input.gateId === "pre-dispatch-health-gate" && input.outcome === "pass") {
-          observed = input.findings ?? "";
-        }
-      },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("advance() sets active unit and is reflected in status", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  await orchestrator.advance();
+  await f.orchestrator.advance();
 
-  assert.equal(observed, "fix-a, fix-b");
+  assert.deepEqual(f.orchestrator.getStatus().activeUnit, {
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+  });
 });
 
-test("advance() follows the ADR-015 invariant sequence before journaling advance", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("advance() blocks source dispatch when an earlier slice is incomplete", async (t) => {
+  const f = makeFixture({
+    dispatch: () => ({
+      action: "dispatch",
+      unitType: "execute-task",
+      unitId: "M001/S02/T01",
+      prompt: "fixture-prompt",
+    }),
+  });
+  t.after(() => f.cleanup());
+
+  insertSlice({
+    id: "S02",
+    milestoneId: "M001",
+    title: "Second slice",
+    status: "active",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 2,
+  });
+  insertTask({
+    id: "T01",
+    sliceId: "S02",
+    milestoneId: "M001",
+    title: "Second task",
+    status: "active",
+  });
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
-  assert.equal(result.kind, "advanced");
-  assert.deepEqual(result.unit, { unitType: "execute-task", unitId: "T01" });
-  assert.deepEqual(calls, [
-    "runtime.lock",
-    "health.stale",
-    "gate:resource-version-guard:pass",
-    "health.pre",
-    "gate:pre-dispatch-health-gate:pass",
-    "state.reconcile",
-    "dispatch.decide",
-    "tool.compile",
-    "worktree.prepare",
-    "journal:advance",
-    "worktree.sync",
-    "health.post",
-  ]);
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "stop");
+  assert.match(result.reason, /earlier slice M001\/S01 is not complete/);
+  assert.equal(f.session.pendingOrchestrationDispatch, null);
+  assert.deepEqual(f.orchestrator.getStatus().activeUnit, undefined);
+  assert.ok(f.journalNames().includes("advance-blocked"));
 });
 
-test("advance() blocks before dispatch when State Reconciliation blocks", async () => {
-  const { deps, calls } = makeDeps({
-    stateReconciliation: {
-      async reconcileBeforeDispatch() {
-        calls.push("state.reconcile");
-        return { ok: false, reason: "state drift blocked", stateSnapshot: makeState() };
-      },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("getStatus() returns defensive copy of activeUnit", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  await f.orchestrator.advance();
+  const snap1 = f.orchestrator.getStatus();
+  if (snap1.activeUnit) snap1.activeUnit.unitId = "MUTATED";
+  const snap2 = f.orchestrator.getStatus();
 
-  assertBlockedResult(result);
-  assert.equal(result.reason, "state drift blocked");
-  assert.equal(result.action, "pause");
-  assert.ok(!calls.includes("dispatch.decide"));
-  assert.ok(calls.includes("journal:advance-blocked"));
+  assert.equal(snap2.activeUnit?.unitId, "M001/S01/T01");
 });
 
-test("advance() blocks before Runtime persistence when Tool Contract fails", async () => {
-  const { deps, calls } = makeDeps({
-    toolContract: {
-      async compileUnitToolContract() {
-        calls.push("tool.compile");
-        return { ok: false, reason: "unknown Unit" };
-      },
-    },
+// ─────────────────────────────────────────────────────────────────────────────
+// Dispatch passthrough decisions (skip / blocked / no-remaining-units)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("advance() keeps running when dispatch intentionally skips a phase", async (t) => {
+  const f = makeFixture({
+    dispatch: () => ({ action: "skip", matchedRule: "evaluating-gates skipped after marking gates omitted" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
-  assertBlockedResult(result);
-  assert.equal(result.reason, "unknown Unit");
-  assert.equal(result.action, "pause");
-  assert.ok(!calls.includes("worktree.prepare"));
-  assert.ok(!calls.includes("journal:advance"));
-  assert.ok(calls.includes("journal:advance-blocked"));
+  assert.equal(result.kind, "skipped");
+  if (result.kind !== "skipped") return;
+  assert.equal(result.reason, "evaluating-gates skipped after marking gates omitted");
+  assert.equal(f.orchestrator.getStatus().phase, "running");
+  const names = f.journalNames();
+  assert.ok(names.includes("advance-skipped"));
+  assert.ok(!names.includes("advance-stopped"));
 });
 
-test("advance() blocks before Runtime persistence when Worktree Safety fails", async () => {
-  const { deps, calls } = makeDeps({
-    worktree: {
-      async prepareForUnit() {
-        calls.push("worktree.prepare");
-        return { ok: false, reason: "worktree invalid" };
-      },
-      async syncAfterUnit() { calls.push("worktree.sync"); },
-      async cleanupOnStop() { calls.push("worktree.cleanup"); },
-    },
+test("advance() surfaces dispatch blocker reason instead of generic no remaining units", async (t) => {
+  const reason = "Milestone M001 validation verdict is needs-remediation but all slices are complete.";
+  const f = makeFixture({
+    dispatch: () => ({ action: "stop", reason, level: "warning" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
-  assertBlockedResult(result);
-  assert.equal(result.reason, "worktree invalid");
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.reason, reason);
   assert.equal(result.action, "pause");
-  assert.ok(!calls.includes("journal:advance"));
-  assert.ok(!calls.includes("worktree.sync"));
-  assert.ok(calls.includes("journal:advance-blocked"));
+  const names = f.journalNames();
+  assert.ok(names.includes("advance-blocked"));
+  assert.ok(!names.includes("advance-stopped"));
 });
 
-test("advance() allows non-worktree isolation prepare result", async () => {
-  const { deps, calls } = makeDeps({
-    worktree: {
-      async prepareForUnit() {
-        calls.push("worktree.prepare");
-        return { ok: true, reason: "isolation-not-worktree" };
-      },
-      async syncAfterUnit() { calls.push("worktree.sync"); },
-      async cleanupOnStop() { calls.push("worktree.cleanup"); },
-    },
+test("advance() stop level=error blocks with action stop", async (t) => {
+  const f = makeFixture({
+    dispatch: () => ({ action: "stop", reason: "hard blocker", level: "error" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
-  assert.equal(result.kind, "advanced");
-  assert.ok(calls.includes("journal:advance"));
-  assert.ok(calls.includes("worktree.sync"));
+  assert.equal(result.kind, "blocked");
+  if (result.kind !== "blocked") return;
+  assert.equal(result.action, "stop");
 });
 
-test("advance() stops when dispatch has no next unit", async () => {
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() { return null; },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+test("advance() reports completion when complete state has no next unit", async (t) => {
+  const f = makeFixture({ complete: true, noTask: true });
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
   assert.equal(result.kind, "stopped");
-  assert.equal(orchestrator.getStatus().phase, "stopped");
+  if (result.kind !== "stopped") return;
+  assert.equal(result.reason, "All milestones complete");
+  assert.equal(result.terminalOutcome?.code, "all-complete");
+  assert.equal(f.orchestrator.getStatus().phase, "stopped");
 });
 
-test("advance() reports completion when complete state has no next unit", async () => {
-  const completeState: GSDState = {
-    ...makeState(),
-    activeMilestone: null,
-    phase: "complete",
-    lastCompletedMilestone: { id: "M001", title: "Milestone" },
-    nextAction: "All milestones complete.",
-  };
-  const { deps } = makeDeps({
-    stateReconciliation: {
-      async reconcileBeforeDispatch() {
-        return { ok: true, stateSnapshot: completeState };
-      },
-    },
-    dispatch: {
-      async decideNextUnit() { return null; },
-    },
+test("advance() blocks all-complete stop when completed milestone is still unmerged in a worktree", async (t) => {
+  const f = makeFixture({ complete: true, noTask: true });
+  t.after(() => f.cleanup());
+
+  insertSlice({
+    id: "S01",
+    milestoneId: "M001",
+    title: "Slice",
+    status: "complete",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 1,
   });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const result = await orchestrator.advance();
-
-  assert.equal(result.kind, "stopped");
-  assert.equal(result.reason, "all milestones complete");
-});
-
-test("advance() keeps running when dispatch intentionally skips a phase", async () => {
-  const { deps, calls } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        return { kind: "skipped", reason: "evaluating-gates skipped after marking gates omitted" };
-      },
-    },
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
   });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const result = await orchestrator.advance();
-
-  assert.equal(result.kind, "skipped");
-  if (result.kind !== "skipped") return;
-  assert.equal(result.reason, "evaluating-gates skipped after marking gates omitted");
-  assert.equal(orchestrator.getStatus().phase, "running");
-  assert.ok(calls.includes("journal:advance-skipped"));
-  assert.ok(!calls.includes("journal:advance-stopped"));
-});
-
-test("advance() surfaces dispatch blocker reason instead of generic no remaining units", async () => {
-  const { deps, calls } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        return {
-          kind: "blocked",
-          reason: "Milestone M001 validation verdict is needs-remediation but all slices are complete.",
-          action: "pause",
-        };
-      },
-    },
+  insertGateRow({
+    milestoneId: "M001",
+    sliceId: "S01",
+    gateId: "Q3",
+    scope: "slice",
+    status: "pending",
   });
-  const orchestrator = createAutoOrchestrator(deps);
 
-  const result = await orchestrator.advance();
+  const worktreePath = join(f.base, ".gsd", "worktrees", "M001");
+  mkdirSync(join(f.base, ".gsd", "worktrees"), { recursive: true });
+  execFileSync("git", ["worktree", "add", "-b", "milestone/M001", worktreePath], { cwd: f.base, stdio: "ignore" });
+  mkdirSync(join(worktreePath, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(worktreePath, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\n");
+  f.session.basePath = worktreePath;
+  f.session.originalBasePath = f.base;
+  f.session.currentMilestoneId = "M001";
+  f.session.milestoneMergedInPhases = false;
+
+  const result = await f.orchestrator.advance();
 
   assert.equal(result.kind, "blocked");
   if (result.kind !== "blocked") return;
-  assert.equal(result.reason, "Milestone M001 validation verdict is needs-remediation but all slices are complete.");
   assert.equal(result.action, "pause");
-  assert.ok(calls.includes("journal:advance-blocked"));
-  assert.ok(!calls.includes("journal:advance-stopped"));
+  assert.equal(result.terminalOutcome?.code, "settlement-blocked");
+  assert.match(result.reason, /worktree branch has not been merged to main/);
+  assert.doesNotMatch(result.reason, /quality gate Q3 is still pending/);
+  assert.equal(f.orchestrator.getStatus().phase, "paused");
+  assert.equal(f.session.milestoneSettlement?.ok, false);
+  const names = f.journalNames();
+  assert.ok(names.includes("advance-blocked"));
+  assert.ok(!names.includes("advance-stopped"));
 });
 
-test("resume() enters running phase without dispatching", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("advance() stopped clears previous activeUnit and resets idempotent lock", async (t) => {
+  // First advance dispatches; then we make the milestone resolve to no unit by
+  // closing it on disk + DB and re-deriving. Simpler: drive a fixture that
+  // dispatches once, finalize externally, then the next decision is complete.
+  let dispatchOnce = true;
+  const f = makeFixture({
+    dispatch: () => {
+      if (dispatchOnce) {
+        dispatchOnce = false;
+        return DEFAULT_DISPATCH;
+      }
+      // After the first advance, signal completion via a benign skip → still
+      // exercises the running/active-unit transition. For the stopped path we
+      // rely on the complete-state test above.
+      return { action: "skip", matchedRule: "done" };
+    },
+  });
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.resume();
+  const first = await f.orchestrator.advance();
+  assert.equal(first.kind, "advanced");
 
-  assert.equal(result.kind, "resumed");
-  assert.equal(orchestrator.getStatus().phase, "running");
-  assert.ok(!calls.includes("journal:advance"));
-  assert.ok(!calls.includes("dispatch.decide"));
+  const second = await f.orchestrator.advance();
+  assert.equal(second.kind, "skipped");
+  // skip clears activeUnit
+  assert.equal(f.orchestrator.getStatus().activeUnit, undefined);
 });
 
-test("advance() uses recovery on error", async () => {
-  const { deps, calls } = makeDeps({
-    runtime: {
-      async ensureLockOwnership() { throw new Error("lock lost"); },
-      async journalTransition(event) { calls.push(`journal:${event.name}`); },
-    },
-    recovery: {
-      async classifyAndRecover() { return { action: "escalate", reason: "needs manual" }; },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
+// ─────────────────────────────────────────────────────────────────────────────
+// Idempotency + finalized guard + stuck-loop ring (issues #5786 / #5787 / #415)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("advance() is idempotent for the same active unit", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
+  const second = await f.orchestrator.advance();
 
-  assert.equal(result.kind, "error");
-  assert.equal(result.reason, "needs manual");
-  assert.equal(orchestrator.getStatus().phase, "error");
-  assert.ok(calls.includes("journal:advance-error"));
+  assert.equal(first.kind, "advanced");
+  if (first.kind === "advanced") {
+    assert.deepEqual(first.unit, { unitType: "execute-task", unitId: "M001/S01/T01" });
+  }
+  assert.equal(second.kind, "blocked");
+  if (second.kind !== "blocked") return;
+  assert.equal(second.reason, "idempotent advance: unit already active");
+  assert.equal(second.action, "pause");
 });
 
-test("advance() is idempotent for the same active unit", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("idempotency block fires with its own reason before saturation", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
-  const second = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
+  const second = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
-  assert.deepEqual(first.unit, { unitType: "execute-task", unitId: "T01" });
   assert.equal(second.kind, "blocked");
+  if (second.kind !== "blocked") return;
   assert.equal(second.reason, "idempotent advance: unit already active");
   assert.equal(second.action, "pause");
-
-  const prepareCalls = calls.filter((c) => c === "worktree.prepare").length;
-  assert.equal(prepareCalls, 1);
 });
 
-test("completeActiveUnit clears in-flight idempotency and stops stale same-unit advance", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("completeActiveUnit clears in-flight idempotency and stops stale same-unit advance", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
   assert.equal(first.kind, "advanced");
   if (first.kind !== "advanced") throw new Error("expected first advance");
 
-  await orchestrator.completeActiveUnit(first.unit);
-  const second = await orchestrator.advance();
+  await f.orchestrator.completeActiveUnit(first.unit);
+  const second = await f.orchestrator.advance();
 
-  assert.equal(orchestrator.getStatus().activeUnit, undefined);
+  assert.equal(f.orchestrator.getStatus().activeUnit, undefined);
   assert.equal(second.kind, "blocked");
   if (second.kind !== "blocked") throw new Error("expected stale same-unit block");
   assert.equal(second.action, "stop");
-  assert.equal(second.reason, "state did not advance after finalized execute-task T01");
-  assert.ok(calls.includes("journal:unit-finalized"));
-  const prepareCalls = calls.filter((c) => c === "worktree.prepare").length;
-  assert.equal(prepareCalls, 1, "stale same-unit advance must not prepare or redispatch");
+  assert.equal(second.reason, "state did not advance after finalized execute-task M001/S01/T01");
+  assert.ok(f.journalNames().includes("unit-finalized"));
 });
 
-test("completeActiveUnit allows a different next unit to advance", async () => {
-  let nextTaskId = "T01";
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        return { unitType: "execute-task", unitId: nextTaskId, reason: "ready", preconditions: [] };
-      },
-    },
+test("#442: finalized-repeat recovers (skipped) when the unit's artifact already exists on disk", async (t) => {
+  // plan-milestone's expected artifact is the ROADMAP, which the fixture
+  // already writes — so verifyExpectedArtifact returns true. This is the legacy
+  // stuck-recovery scenario (unit completed on disk, DB row stale): instead of
+  // the finalized-repeat HARD-STOP, #442 verify-and-recover should refresh +
+  // skip so the loop can progress. plan-milestone is deliberately NOT one of
+  // the DB-refreshing unit types, so the recovery stays side-effect-light.
+  const f = makeFixture({
+    dispatch: () => ({ action: "dispatch", unitType: "plan-milestone", unitId: "M001", prompt: "p" }),
+  });
+  t.after(() => f.cleanup());
+
+  const first = await f.orchestrator.advance();
+  if (first.kind !== "advanced") {
+    throw new Error(`expected advanced, got ${first.kind}: ${(first as { reason?: string }).reason ?? ""}`);
+  }
+  await f.orchestrator.completeActiveUnit(first.unit);
+
+  const second = await f.orchestrator.advance();
+  assert.equal(second.kind, "skipped", "should recover via artifact verification, not hard-stop");
+  if (second.kind !== "skipped") throw new Error("expected skipped recovery");
+  assert.match(second.reason, /stuck-recovery/);
+  assert.ok(f.journalNames().includes("advance-skipped"));
+});
+
+test("completeActiveUnit allows a different next unit to advance", async (t) => {
+  let nextTaskId = "M001/S01/T01";
+  const f = makeFixture({
+    dispatch: () => ({ action: "dispatch", unitType: "execute-task", unitId: nextTaskId, prompt: "p" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
   assert.equal(first.kind, "advanced");
   if (first.kind !== "advanced") throw new Error("expected first advance");
 
-  await orchestrator.completeActiveUnit(first.unit);
-  nextTaskId = "T02";
-  const second = await orchestrator.advance();
+  await f.orchestrator.completeActiveUnit(first.unit);
+  nextTaskId = "M001/S01/T02";
+  const second = await f.orchestrator.advance();
 
   assert.equal(second.kind, "advanced");
   if (second.kind !== "advanced") throw new Error("expected second advance");
-  assert.deepEqual(second.unit, { unitType: "execute-task", unitId: "T02" });
+  assert.deepEqual(second.unit, { unitType: "execute-task", unitId: "M001/S01/T02" });
 });
 
-test("completeActiveUnit guard survives an intervening advance and blocks X→Y→X re-dispatch", async () => {
-  // Regression test for issue #415: lastFinalizedUnitKey was wiped on every advance(),
-  // allowing completed units to be re-dispatched after any interleaving unit (X→Y→X).
-  let nextTaskId = "T01";
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        return { unitType: "execute-task", unitId: nextTaskId, reason: "ready", preconditions: [] };
-      },
-    },
+test("completeActiveUnit guard survives an intervening advance and blocks X→Y→X re-dispatch (#415)", async (t) => {
+  let nextTaskId = "M001/S01/T01";
+  const f = makeFixture({
+    dispatch: () => ({ action: "dispatch", unitType: "execute-task", unitId: nextTaskId, prompt: "p" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
-  // Step 1: advance X (T01)
-  const first = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
   assert.equal(first.kind, "advanced");
   if (first.kind !== "advanced") throw new Error("expected first advance");
 
-  // Step 2: complete X (T01) — sets lastFinalizedUnitKey = 'execute-task:T01'
-  await orchestrator.completeActiveUnit(first.unit);
+  await f.orchestrator.completeActiveUnit(first.unit);
 
-  // Step 3: advance Y (T02) — must NOT clear lastFinalizedUnitKey
-  nextTaskId = "T02";
-  const second = await orchestrator.advance();
+  nextTaskId = "M001/S01/T02";
+  const second = await f.orchestrator.advance();
   assert.equal(second.kind, "advanced");
   if (second.kind !== "advanced") throw new Error("expected second advance (T02)");
-  assert.deepEqual(second.unit, { unitType: "execute-task", unitId: "T02" });
+  assert.deepEqual(second.unit, { unitType: "execute-task", unitId: "M001/S01/T02" });
 
-  // Step 4: re-select X (T01) — must be blocked because T01 was finalized
-  nextTaskId = "T01";
-  const third = await orchestrator.advance();
+  nextTaskId = "M001/S01/T01";
+  const third = await f.orchestrator.advance();
   assert.equal(third.kind, "blocked");
   if (third.kind !== "blocked") throw new Error("expected X→Y→X re-dispatch to be blocked");
   assert.equal(third.action, "stop");
-  assert.equal(third.reason, "state did not advance after finalized execute-task T01");
+  assert.equal(third.reason, "state did not advance after finalized execute-task M001/S01/T01");
 });
 
-test("retryActiveUnit clears in-flight idempotency without marking the unit finalized", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("retryActiveUnit clears in-flight idempotency without marking the unit finalized", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
   assert.equal(first.kind, "advanced");
   if (first.kind !== "advanced") throw new Error("expected first advance");
 
-  await orchestrator.retryActiveUnit(first.unit);
-  const second = await orchestrator.advance();
+  await f.orchestrator.retryActiveUnit(first.unit);
+  const second = await f.orchestrator.advance();
 
   assert.equal(second.kind, "advanced");
   if (second.kind !== "advanced") throw new Error("expected retry advance");
   assert.deepEqual(second.unit, first.unit);
-  assert.ok(calls.includes("journal:unit-retry"));
-  const prepareCalls = calls.filter((c) => c === "worktree.prepare").length;
-  assert.equal(prepareCalls, 2, "retry should intentionally redispatch the same unit");
+  assert.ok(f.journalNames().includes("unit-retry"));
 });
 
-test("retryActiveUnit clears finalized same-unit guard for post-hook retries", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("retryActiveUnit clears finalized same-unit guard for post-hook retries", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
   assert.equal(first.kind, "advanced");
   if (first.kind !== "advanced") throw new Error("expected first advance");
 
-  await orchestrator.completeActiveUnit(first.unit);
-  await orchestrator.retryActiveUnit(first.unit);
-  const second = await orchestrator.advance();
+  await f.orchestrator.completeActiveUnit(first.unit);
+  await f.orchestrator.retryActiveUnit(first.unit);
+  const second = await f.orchestrator.advance();
 
   assert.equal(second.kind, "advanced");
   if (second.kind !== "advanced") throw new Error("expected retry advance");
   assert.deepEqual(second.unit, first.unit);
-  assert.ok(calls.includes("journal:unit-finalized"));
-  assert.ok(calls.includes("journal:unit-retry"));
-  const prepareCalls = calls.filter((c) => c === "worktree.prepare").length;
-  assert.equal(prepareCalls, 2, "post-hook retry should redispatch the finalized unit");
-});
-
-test("resume() re-enters running phase", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const result = await orchestrator.resume();
-
-  assert.equal(result.kind, "resumed");
-  assert.equal(orchestrator.getStatus().phase, "running");
+  const names = f.journalNames();
+  assert.ok(names.includes("unit-finalized"));
+  assert.ok(names.includes("unit-retry"));
 });
 
-test("resume() clears idempotent lock and allows re-advance", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("resume() clears idempotent lock and allows re-advance", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
-  const blocked = await orchestrator.advance();
-  const resumed = await orchestrator.resume();
-  const next = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
+  const blocked = await f.orchestrator.advance();
+  const resumed = await f.orchestrator.resume();
+  const next = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
   assert.equal(blocked.kind, "blocked");
@@ -676,263 +681,81 @@ test("resume() clears idempotent lock and allows re-advance", async () => {
   assert.equal(next.kind, "advanced");
 });
 
-test("transitionCount increases across lifecycle transitions", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const before = orchestrator.getStatus().transitionCount;
-  await orchestrator.start({ basePath: "/tmp/project", trigger: "manual" });
-  const afterStart = orchestrator.getStatus().transitionCount;
-  await orchestrator.stop("done");
-  const afterStop = orchestrator.getStatus().transitionCount;
-
-  assert.ok(afterStart > before);
-  assert.ok(afterStop > afterStart);
-});
-
-test("stop() clears idempotent unit lock so advance can run again", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("start() clears prior idempotent lock", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
-  const blocked = await orchestrator.advance();
-  const stopped = await orchestrator.stop("reset");
-  const second = await orchestrator.advance();
-
-  assert.equal(first.kind, "advanced");
-  assert.equal(blocked.kind, "blocked");
-  assert.equal(stopped.kind, "stopped");
-  assert.equal(second.kind, "advanced");
-});
-
-test("advance() stopped clears previous activeUnit", async () => {
-  let first = true;
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        if (first) {
-          first = false;
-          return { unitType: "execute-task", unitId: "T01", reason: "ready", preconditions: [] };
-        }
-        return null;
-      },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.advance();
-  const stopped = await orchestrator.advance();
-
-  assert.equal(stopped.kind, "stopped");
-  assert.equal(orchestrator.getStatus().activeUnit, undefined);
-});
-
-test("recovery stop clears activeUnit", async () => {
-  const { deps, calls } = makeDeps({
-    runtime: {
-      async ensureLockOwnership() { throw new Error("boom"); },
-      async journalTransition(event) { calls.push(`journal:${event.name}`); },
-    },
-    recovery: {
-      async classifyAndRecover() { return { action: "stop", reason: "fatal" }; },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const result = await orchestrator.advance();
-
-  assert.equal(result.kind, "stopped");
-  assert.equal(orchestrator.getStatus().activeUnit, undefined);
-  assert.ok(calls.includes("journal:advance-stopped"));
-  assert.ok(calls.includes("notify:stopped"));
-  assert.ok(!calls.includes("notify:error"));
-});
-
-test("recovery retry maps to paused result", async () => {
-  const { deps, calls } = makeDeps({
-    runtime: {
-      async ensureLockOwnership() { throw new Error("boom"); },
-      async journalTransition(event) { calls.push(`journal:${event.name}`); },
-    },
-    recovery: {
-      async classifyAndRecover() { return { action: "retry", reason: "transient" }; },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const result = await orchestrator.advance();
-
-  assert.equal(result.kind, "paused");
-  assert.equal(result.reason, "transient");
-  assert.equal(orchestrator.getStatus().phase, "paused");
-  assert.ok(calls.includes("journal:advance-paused"));
-  assert.ok(calls.includes("notify:pause"));
-});
-
-test("getStatus() returns defensive copy of activeUnit", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.advance();
-  const snap1 = orchestrator.getStatus();
-  if (snap1.activeUnit) snap1.activeUnit.unitId = "MUTATED";
-  const snap2 = orchestrator.getStatus();
-
-  assert.equal(snap2.activeUnit?.unitId, "T01");
-});
-
-test("start() clears prior idempotent lock", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.advance();
-  const blocked = await orchestrator.advance();
-  const restarted = await orchestrator.start({ basePath: "/tmp/project", trigger: "manual" });
-  const next = await orchestrator.advance();
+  await f.orchestrator.advance();
+  const blocked = await f.orchestrator.advance();
+  const restarted = await f.orchestrator.start(SESSION_CONTEXT);
+  const next = await f.orchestrator.advance();
 
   assert.equal(blocked.kind, "blocked");
   assert.equal(restarted.kind, "started");
   assert.equal(next.kind, "advanced");
 });
 
-test("error path emits error notification", async () => {
-  const { deps, calls } = makeDeps({
-    runtime: {
-      async ensureLockOwnership() { throw new Error("boom"); },
-      async journalTransition(event) { calls.push(`journal:${event.name}`); },
-    },
-    recovery: {
-      async classifyAndRecover() { return { action: "escalate", reason: "needs manual" }; },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.advance();
-
-  assert.ok(calls.includes("notify:error"));
-});
-
-test("blocked path journals advance-blocked", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stop() clears idempotent unit lock so advance can run again", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  await orchestrator.advance();
-  await orchestrator.advance();
-
-  assert.ok(calls.includes("journal:advance-blocked"));
-});
-
-test("health post hook runs on blocked result", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.advance();
-  await orchestrator.advance();
-
-  assert.ok(calls.includes("health.post"));
-});
-
-test("start() emits start notification", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.start({ basePath: "/tmp/project", trigger: "manual" });
-
-  assert.ok(calls.includes("notify:start"));
-});
-
-test("resume() emits resume notification", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
-
-  await orchestrator.resume();
-
-  assert.ok(calls.includes("notify:resume"));
-});
-
-test("stopped with no remaining units clears idempotent lock for next advance", async () => {
-  let callCount = 0;
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        callCount += 1;
-        if (callCount === 2) return null;
-        return { unitType: "execute-task", unitId: "T01", reason: "ready", preconditions: [] };
-      },
-    },
-  });
-  const orchestrator = createAutoOrchestrator(deps);
-
-  const first = await orchestrator.advance();
-  const stopped = await orchestrator.advance();
-  const after = await orchestrator.advance();
+  const first = await f.orchestrator.advance();
+  const blocked = await f.orchestrator.advance();
+  const stopped = await f.orchestrator.stop("reset");
+  const second = await f.orchestrator.advance();
 
   assert.equal(first.kind, "advanced");
+  assert.equal(blocked.kind, "blocked");
   assert.equal(stopped.kind, "stopped");
-  assert.equal(after.kind, "advanced");
+  assert.equal(second.kind, "advanced");
 });
 
-test("stop() cleans up worktree and transitions to stopped", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("blocked path journals advance-blocked and records a health snapshot", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.stop("user-request");
+  await f.orchestrator.advance();
+  await f.orchestrator.advance();
 
-  assert.equal(result.kind, "stopped");
-  assert.equal(orchestrator.getStatus().phase, "stopped");
-  assert.ok(calls.includes("worktree.cleanup"));
-  assert.ok(calls.includes("journal:stop"));
-  assert.ok(calls.includes("notify:stop"));
+  assert.ok(f.journalNames().includes("advance-blocked"));
 });
 
-// ────────────────────────────────────────────────────────────────────────
-// Stuck-loop ring buffer (issue #5787)
-// ────────────────────────────────────────────────────────────────────────
+// ─── Stuck-loop ring buffer (issue #5787) ──────────────────────────────────
 
 test("STUCK_WINDOW_SIZE matches the legacy auto/phases.ts constant", () => {
   assert.equal(STUCK_WINDOW_SIZE, 6);
 });
 
-test("stuck-loop: empty ring on a freshly constructed orchestrator advances normally", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: empty ring on a freshly constructed orchestrator advances normally", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const result = await orchestrator.advance();
+  const result = await f.orchestrator.advance();
 
   assert.equal(result.kind, "advanced");
 });
 
-test("stuck-loop: partial fill of mixed units does not block", async () => {
-  // Alternate A/B for STUCK_WINDOW_SIZE rounds. No single key saturates the
-  // window, so neither idempotency nor stuck-loop should fire.
+test("stuck-loop: partial fill of mixed units does not block", async (t) => {
   let i = 0;
-  const sequence = ["A", "B", "A", "B", "A", "B"];
-  const { deps } = makeDeps({
-    dispatch: {
-      async decideNextUnit() {
-        const id = sequence[i++ % sequence.length];
-        return { unitType: "execute-task", unitId: id, reason: "ready", preconditions: [] };
-      },
-    },
+  const sequence = ["M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B"];
+  const f = makeFixture({
+    dispatch: () => ({ action: "dispatch", unitType: "execute-task", unitId: sequence[i++ % sequence.length], prompt: "p" }),
   });
-  const orchestrator = createAutoOrchestrator(deps);
+  t.after(() => f.cleanup());
 
   for (let round = 0; round < STUCK_WINDOW_SIZE; round++) {
-    const result = await orchestrator.advance();
+    const result = await f.orchestrator.advance();
     assert.equal(result.kind, "advanced", `round ${round} should advance, got ${result.kind}`);
   }
 });
 
-test("stuck-loop: ring saturated with same unit blocks with action 'stop' and stuck-loop reason", async () => {
-  // Dispatch picks the same unit every time. The first advance succeeds.
-  // Calls 2..STUCK_WINDOW_SIZE-1 are idempotency-blocked while the ring fills.
-  // The STUCK_WINDOW_SIZE'th call sees a saturated ring and returns stuck-loop.
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: ring saturated with same unit blocks with action 'stop' and stuck-loop reason", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const results: Awaited<ReturnType<typeof orchestrator.advance>>[] = [];
+  const results: Awaited<ReturnType<typeof f.orchestrator.advance>>[] = [];
   for (let i = 0; i < STUCK_WINDOW_SIZE; i++) {
-    results.push(await orchestrator.advance());
+    results.push(await f.orchestrator.advance());
   }
 
   // First call advances.
@@ -952,88 +775,140 @@ test("stuck-loop: ring saturated with same unit blocks with action 'stop' and st
   assert.equal(last.kind, "blocked");
   if (last.kind !== "blocked") return;
   assert.equal(last.action, "stop");
-  assert.equal(last.reason, `stuck-loop: execute-task:T01 picked ${STUCK_WINDOW_SIZE} times`);
+  assert.equal(last.reason, `stuck-loop: execute-task:M001/S01/T01 picked ${STUCK_WINDOW_SIZE} times`);
 });
 
-test("stuck-loop: idempotency block continues to fire with its own reason before saturation", async () => {
-  // Two identical calls should produce idempotent (not stuck-loop). Ensures the
-  // existing idempotency block is not absorbed by the new check.
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: start() resets the ring so a fresh saturation cycle is required", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
-  const first = await orchestrator.advance();
-  const second = await orchestrator.advance();
+  for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
+    await f.orchestrator.advance();
+  }
 
-  assert.equal(first.kind, "advanced");
-  assert.equal(second.kind, "blocked");
-  assert.equal(second.reason, "idempotent advance: unit already active");
-  assert.equal(second.action, "pause");
+  const restarted = await f.orchestrator.start(SESSION_CONTEXT);
+  assert.equal(restarted.kind, "started");
+
+  const next = await f.orchestrator.advance();
+  assert.equal(next.kind, "advanced");
 });
 
-test("stuck-loop: start() resets the ring so a fresh saturation cycle is required", async () => {
-  // Fill the ring to one short of saturation, then start() — the ring should
-  // be cleared, and the next advance must succeed instead of going stuck.
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: resume() preserves ring so detection accumulates across pause/resume", async (t) => {
+  // Regression for #572: resume() must NOT reset dispatchKeyWindow. Before the
+  // fix, a pause/resume cycle cleared the window, letting a stuck loop silently
+  // re-accumulate STUCK_WINDOW_SIZE dispatches before being detected again.
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
   for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
-    await orchestrator.advance();
+    await f.orchestrator.advance();
   }
 
-  const restarted = await orchestrator.start({ basePath: "/tmp/project", trigger: "manual" });
-  assert.equal(restarted.kind, "started");
+  const resumed = await f.orchestrator.resume();
+  assert.equal(resumed.kind, "resumed");
 
-  // Immediately after start(), the next advance should succeed because start()
-  // no longer pre-dispatches and the ring was reset.
-  const next = await orchestrator.advance();
-  assert.equal(next.kind, "advanced");
+  // The ring is preserved, so the next advance pushes it to STUCK_WINDOW_SIZE
+  // and triggers stuck-loop detection — not a fresh dispatch.
+  const next = await f.orchestrator.advance();
+  assert.equal(next.kind, "blocked");
+  if (next.kind !== "blocked") return;
+  assert.equal(next.action, "stop");
+  assert.ok(next.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${next.reason}`);
 });
 
-test("stuck-loop: resume() resets the ring", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: stop('pause') preserves ring across the stop/resume cycle", async (t) => {
+  // Regression for #572: stop("pause") must behave the same as resume() —
+  // the window must survive so detection accumulates across pause/resume pairs.
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
   for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
-    await orchestrator.advance();
+    await f.orchestrator.advance();
   }
 
-  const resumed = await orchestrator.resume();
+  const stopped = await f.orchestrator.stop("pause");
+  assert.equal(stopped.kind, "stopped");
+
+  const resumed = await f.orchestrator.resume();
   assert.equal(resumed.kind, "resumed");
 
-  const next = await orchestrator.advance();
-  assert.equal(next.kind, "advanced");
+  const next = await f.orchestrator.advance();
+  assert.equal(next.kind, "blocked");
+  if (next.kind !== "blocked") return;
+  assert.equal(next.action, "stop");
+  assert.ok(next.reason.startsWith("stuck-loop:"), `expected stuck-loop reason, got: ${next.reason}`);
 });
 
-test("stuck-loop: stop() resets the ring", async () => {
-  const { deps } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: stop('user-request') resets the ring (hard stop)", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
   for (let i = 0; i < STUCK_WINDOW_SIZE - 1; i++) {
-    await orchestrator.advance();
+    await f.orchestrator.advance();
   }
 
-  const stopped = await orchestrator.stop("user-request");
+  const stopped = await f.orchestrator.stop("user-request");
   assert.equal(stopped.kind, "stopped");
 
-  // Ring is cleared by stop(). A subsequent advance is a fresh first-touch.
-  const next = await orchestrator.advance();
+  // Hard stop clears the ring, so the next advance dispatches fresh.
+  const next = await f.orchestrator.advance();
   assert.equal(next.kind, "advanced");
 });
 
-test("stuck-loop: journal records the stuck-loop reason on advance-blocked", async () => {
-  const { deps, calls } = makeDeps();
-  const orchestrator = createAutoOrchestrator(deps);
+test("stuck-loop: journal records the stuck-loop reason on advance-blocked", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
 
   for (let i = 0; i < STUCK_WINDOW_SIZE; i++) {
-    await orchestrator.advance();
+    await f.orchestrator.advance();
   }
 
-  assert.ok(calls.includes("journal:advance-blocked"));
+  const stuckEntry = queryJournal(f.base).find(
+    (e) => {
+      const reason = (e.data as Record<string, unknown> | undefined)?.reason;
+      return typeof reason === "string" && reason.startsWith("stuck-loop:");
+    },
+  );
+  assert.ok(stuckEntry, "journal must record an advance-blocked entry with the stuck-loop reason");
+  assert.ok(f.journalNames().includes("advance-blocked"));
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Recovery path: a lock held by another process throws inside advance() and is
+// routed through the REAL classifyFailure → result mapping + notifications.
+// We force the throw by acquiring the lock under a different PID (writing a
+// foreign-PID lockfile is not portable, so we drive the deterministic-stop
+// classification via a fixture whose runtimeBasePath has no valid lock).
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("advance() routes a lost-lock error through recovery and journals an outcome", async (t) => {
+  const f = makeFixture();
+  t.after(() => f.cleanup());
+
+  // Release the lock so ensureLockOwnership() sees missing-metadata and throws,
+  // exercising the catch → classifyAndRecover → result-mapping branch.
+  releaseSessionLock(f.base);
+  // Remove the lockfile artifact so getSessionLockStatus returns !valid.
+  try { rmSync(join(f.base, ".gsd", "auto.lock"), { force: true }); } catch { /* */ }
+  try { rmSync(join(f.base, ".gsd.lock"), { recursive: true, force: true }); } catch { /* */ }
+
+  const result = await f.orchestrator.advance();
+
+  // classifyFailure maps a generic Error to a recovery action; the orchestrator
+  // surfaces it as paused/stopped/error and journals the corresponding event.
+  assert.ok(["paused", "stopped", "error"].includes(result.kind), `unexpected kind ${result.kind}`);
+  const names = f.journalNames();
+  assert.ok(
+    names.includes("advance-paused") || names.includes("advance-stopped") || names.includes("advance-error"),
+    "recovery must journal an advance-paused/stopped/error event",
+  );
 });
 
-// ─── closeout regression: wired orchestrator must not dispatch from a removed worktree ───
+// ─────────────────────────────────────────────────────────────────────────────
+// closeout regression: live-base resolver after worktree cleanup
+// ─────────────────────────────────────────────────────────────────────────────
 
-test("wired orchestrator base resolver prefers live project root after worktree cleanup", (t) => {
+test("live orchestrator base resolver prefers live project root after worktree cleanup", (t) => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-orch-root-"));
   const staleWorktreeRoot = join(projectRoot, ".gsd", "worktrees", "M002");
   mkdirSync(join(staleWorktreeRoot, ".bg-shell"), { recursive: true });
@@ -1050,7 +925,7 @@ test("wired orchestrator base resolver prefers live project root after worktree
   );
 });
 
-test("wired orchestrator base resolver keeps a captured active git worktree", (t) => {
+test("live orchestrator base resolver keeps a captured active git worktree", (t) => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-orch-worktree-"));
   const worktreeRoot = join(projectRoot, ".gsd", "worktrees", "M003");
   mkdirSync(worktreeRoot, { recursive: true });
@@ -1066,14 +941,14 @@ test("wired orchestrator base resolver keeps a captured active git worktree", (t
   );
 });
 
-// ─── #5789 parity: wired dispatch adapter mirrors runDispatch's resolveDispatch call ───
+// ─────────────────────────────────────────────────────────────────────────────
+// Dispatch-decision parity (#5789) — formerly the createWiredDispatchAdapter
+// tests. These exercise the exported pure decideOrchestratorDispatch helper.
+// ─────────────────────────────────────────────────────────────────────────────
 
-test("wired DispatchAdapter forwards session-derived dispatch inputs identically to runDispatch", async () => {
+test("decideOrchestratorDispatch forwards session-derived dispatch inputs identically to runDispatch", async () => {
   const stateSnapshot = makeState();
 
-  // Install a capturing registry so we observe the DispatchContext both code paths
-  // build, and force a deterministic dispatch action so the parity assertion is
-  // about *inputs*, not rule evaluation.
   const captured: DispatchContext[] = [];
   const captureRule: UnifiedRule = {
     name: "test-capture",
@@ -1093,7 +968,6 @@ test("wired DispatchAdapter forwards session-derived dispatch inputs identically
   setRegistry(new RuleRegistry([captureRule]));
 
   try {
-    // Mock ExtensionContext + ExtensionAPI with the surface the wired adapter touches.
     const fakeModelRegistry = {
       getAll: () => [],
       getProviderAuthMode: (_provider: string) => "apiKey" as const,
@@ -1105,30 +979,28 @@ test("wired DispatchAdapter forwards session-derived dispatch inputs identically
         contextWindow: 200_000,
       },
       modelRegistry: fakeModelRegistry,
-    } as any;
+    } as never;
     const pi = {
       getActiveTools: () => ["read_file", "write_file"],
-    } as any;
+    } as never;
     const basePath = "/tmp/parity-fixture";
 
-    // Path A — wired adapter (what createWiredAutoOrchestrationModule uses).
-    const adapter = createWiredDispatchAdapter(ctx, pi, basePath);
-    const adapterResult = await adapter.decideNextUnit({ stateSnapshot });
+    // Path A — the orchestrator's pure dispatch decision.
+    const adapterResult = await decideOrchestratorDispatch(ctx, pi, basePath, undefined, { stateSnapshot });
 
     // Path B — direct resolveDispatch call mirroring phases.ts:runDispatch.
-    // Inline the same derivations runDispatch uses so any drift here is a parity break.
-    const prefs = undefined; // loadEffectiveGSDPreferences returns null for /tmp/parity-fixture.
-    const provider = ctx.model?.provider;
-    const authMode = provider && typeof ctx.modelRegistry?.getProviderAuthMode === "function"
-      ? ctx.modelRegistry.getProviderAuthMode(provider)
+    const prefs = undefined;
+    const provider = (ctx as { model?: { provider?: string } }).model?.provider;
+    const authMode = provider && typeof fakeModelRegistry.getProviderAuthMode === "function"
+      ? fakeModelRegistry.getProviderAuthMode(provider)
       : undefined;
-    const activeTools = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+    const activeTools = ["read_file", "write_file"];
     const structuredQuestionsAvailable: "true" | "false" =
       prefs !== undefined && (prefs as { planning_depth?: string }).planning_depth === "deep"
         ? "false"
         : supportsStructuredQuestions(activeTools, {
             authMode,
-            baseUrl: ctx.model?.baseUrl,
+            baseUrl: (ctx as { model?: { baseUrl?: string } }).model?.baseUrl,
           })
           ? "true"
           : "false";
@@ -1140,17 +1012,15 @@ test("wired DispatchAdapter forwards session-derived dispatch inputs identically
       state: stateSnapshot,
       prefs,
       structuredQuestionsAvailable,
-      sessionContextWindow: ctx.model?.contextWindow,
-      sessionProvider: ctx.model?.provider,
-      modelRegistry: ctx.modelRegistry,
+      sessionContextWindow: 200_000,
+      sessionProvider: "anthropic",
+      modelRegistry: fakeModelRegistry,
     };
     const directAction = await resolveDispatch(builtDirectCtx);
 
-    // Two contexts captured: one per resolveDispatch call.
     assert.equal(captured.length, 2, "expected two captured dispatch contexts");
     const [adapterCtx, directCtx] = captured;
 
-    // Parity assertion: session-derived fields are identical.
     assert.equal(adapterCtx.structuredQuestionsAvailable, directCtx.structuredQuestionsAvailable);
     assert.equal(adapterCtx.sessionContextWindow, directCtx.sessionContextWindow);
     assert.equal(adapterCtx.sessionProvider, directCtx.sessionProvider);
@@ -1159,7 +1029,6 @@ test("wired DispatchAdapter forwards session-derived dispatch inputs identically
     assert.equal(adapterCtx.mid, directCtx.mid);
     assert.equal(adapterCtx.midTitle, directCtx.midTitle);
 
-    // Dispatch action equality: both flows reach the same dispatch decision.
     if (!adapterResult || !("unitType" in adapterResult)) {
       assert.fail("expected adapter result to be a dispatch decision");
     }
@@ -1177,7 +1046,7 @@ test("wired DispatchAdapter forwards session-derived dispatch inputs identically
   }
 });
 
-test("wired DispatchAdapter prefers caller-supplied dispatch inputs over ctx-derived values", async () => {
+test("decideOrchestratorDispatch prefers caller-supplied dispatch inputs over ctx-derived values", async () => {
   const stateSnapshot = makeState();
   const captured: DispatchContext[] = [];
   const captureRule: UnifiedRule = {
@@ -1213,14 +1082,11 @@ test("wired DispatchAdapter prefers caller-supplied dispatch inputs over ctx-der
         contextWindow: 200_000,
       },
       modelRegistry: ctxModelRegistry,
-    } as any;
-    const pi = {
-      getActiveTools: () => [],
-    } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, "/tmp/parity-fixture");
-    const session = { basePath: "/tmp/session-fixture" } as any;
+    } as never;
+    const pi = { getActiveTools: () => [] } as never;
+    const session = { basePath: "/tmp/session-fixture" } as never;
 
-    const result = await adapter.decideNextUnit({
+    const result = await decideOrchestratorDispatch(ctx, pi, "/tmp/parity-fixture", undefined, {
       stateSnapshot,
       session,
       structuredQuestionsAvailable: "true",
@@ -1242,7 +1108,7 @@ test("wired DispatchAdapter prefers caller-supplied dispatch inputs over ctx-der
   }
 });
 
-test("wired DispatchAdapter forwards constructor session when advance input omits session", async () => {
+test("decideOrchestratorDispatch forwards constructor session when advance input omits session", async () => {
   const stateSnapshot = makeState();
   const captured: DispatchContext[] = [];
   const captureRule: UnifiedRule = {
@@ -1263,16 +1129,15 @@ test("wired DispatchAdapter forwards constructor session when advance input omit
   setRegistry(new RuleRegistry([captureRule]));
 
   try {
-    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-    const pi = { getActiveTools: () => [] } as any;
+    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+    const pi = { getActiveTools: () => [] } as never;
     const session = {
       basePath: "/tmp/worktree-fixture",
       originalBasePath: "/tmp/project-fixture",
       currentMilestoneId: "M001",
-    } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, "/tmp/project-fixture", session);
+    } as never;
 
-    const result = await adapter.decideNextUnit({ stateSnapshot });
+    const result = await decideOrchestratorDispatch(ctx, pi, "/tmp/project-fixture", session, { stateSnapshot });
 
     assert.ok(result);
     assert.equal(captured.length, 1, "expected one captured dispatch context");
@@ -1283,7 +1148,7 @@ test("wired DispatchAdapter forwards constructor session when advance input omit
   }
 });
 
-test("wired DispatchAdapter adopts next active milestone after the session milestone is closed", async (t) => {
+test("decideOrchestratorDispatch adopts next active milestone after the session milestone is closed", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-orchestrator-milestone-adopt-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));
 
@@ -1314,28 +1179,27 @@ test("wired DispatchAdapter adopts next active milestone after the session miles
   setRegistry(new RuleRegistry([captureRule]));
 
   try {
-    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-    const pi = { getActiveTools: () => [] } as any;
+    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+    const pi = { getActiveTools: () => [] } as never;
     const session = {
       basePath: base,
       originalBasePath: base,
       currentMilestoneId: "M001",
-    } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, base, session);
+    } as never;
 
-    const result = await adapter.decideNextUnit({ stateSnapshot });
+    const result = await decideOrchestratorDispatch(ctx, pi, base, session, { stateSnapshot });
 
     assert.ok(result);
-    if (!("unitType" in result)) assert.fail(`expected dispatch decision, got ${JSON.stringify(result)}`);
+    if (!result || !("unitType" in result)) assert.fail(`expected dispatch decision, got ${JSON.stringify(result)}`);
     assert.equal(result.unitId, "M002/S01/T01");
-    assert.equal(session.currentMilestoneId, "M002");
+    assert.equal((session as { currentMilestoneId: string }).currentMilestoneId, "M002");
     assert.equal(captured[0]?.session?.currentMilestoneId, "M002");
   } finally {
     resetRegistry();
   }
 });
 
-test("wired DispatchAdapter keeps blocking stale milestone worktree scope", async (t) => {
+test("decideOrchestratorDispatch keeps blocking stale milestone worktree scope", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-orchestrator-worktree-block-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));
 
@@ -1349,16 +1213,15 @@ test("wired DispatchAdapter keeps blocking stale milestone worktree scope", asyn
   };
   const worktreePath = join(base, ".gsd", "worktrees", "M001");
   mkdirSync(worktreePath, { recursive: true });
-  const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-  const pi = { getActiveTools: () => [] } as any;
+  const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+  const pi = { getActiveTools: () => [] } as never;
   const session = {
     basePath: worktreePath,
     originalBasePath: base,
     currentMilestoneId: "M001",
-  } as any;
-  const adapter = createWiredDispatchAdapter(ctx, pi, base, session);
+  } as never;
 
-  const result = await adapter.decideNextUnit({ stateSnapshot });
+  const result = await decideOrchestratorDispatch(ctx, pi, base, session, { stateSnapshot });
 
   assert.deepEqual(result, {
     kind: "blocked",
@@ -1366,13 +1229,13 @@ test("wired DispatchAdapter keeps blocking stale milestone worktree scope", asyn
       'Dispatch milestone mismatch: context mid "M002" does not match session.currentMilestoneId "M001". The active worktree/session and derived project state disagree; recover, park, or discard the stranded milestone before continuing.',
     action: "pause",
   });
-  assert.equal(session.currentMilestoneId, "M001");
+  assert.equal((session as { currentMilestoneId: string }).currentMilestoneId, "M001");
 });
 
-test("wired DispatchAdapter replays pending verification retry dispatch", async () => {
+test("decideOrchestratorDispatch replays pending verification retry dispatch", async () => {
   const stateSnapshot = makeState();
-  const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-  const pi = { getActiveTools: () => [] } as any;
+  const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+  const pi = { getActiveTools: () => [] } as never;
   const session = {
     basePath: "/tmp/worktree-fixture",
     pendingOrchestrationDispatch: null,
@@ -1385,22 +1248,25 @@ test("wired DispatchAdapter replays pending verification retry dispatch", async
       mid: "M004",
       midTitle: "Milestone 4",
     },
-  } as any;
-  const adapter = createWiredDispatchAdapter(ctx, pi, "/tmp/project-fixture", session);
+  } as never;
 
-  const result = await adapter.decideNextUnit({ stateSnapshot });
+  const result = await decideOrchestratorDispatch(ctx, pi, "/tmp/project-fixture", session, { stateSnapshot });
 
   assert.ok(result);
-  if (!("unitType" in result)) assert.fail("expected dispatch decision");
+  if (!result || !("unitType" in result)) assert.fail("expected dispatch decision");
   assert.equal(result.unitType, "complete-slice");
   assert.equal(result.unitId, "M004/S01");
   assert.equal(result.reason, "verification-retry");
-  assert.equal(session.pendingVerificationRetryDispatch, null);
-  assert.equal(session.pendingOrchestrationDispatch?.prompt, "repair slice closeout");
-  assert.equal(session.pendingOrchestrationDispatch?.state, stateSnapshot);
+  const sess = session as {
+    pendingVerificationRetryDispatch: unknown;
+    pendingOrchestrationDispatch: { prompt?: string; state?: unknown } | null;
+  };
+  assert.equal(sess.pendingVerificationRetryDispatch, null);
+  assert.equal(sess.pendingOrchestrationDispatch?.prompt, "repair slice closeout");
+  assert.equal(sess.pendingOrchestrationDispatch?.state, stateSnapshot);
 });
 
-test("wired DispatchAdapter clears verification retry state when skipping an already closed retry dispatch", async () => {
+test("decideOrchestratorDispatch clears verification retry state when skipping an already closed retry dispatch", async () => {
   const stateSnapshot = makeState();
   const base = mkdtempSync(join(tmpdir(), "gsd-orchestrator-closed-retry-"));
 
@@ -1425,8 +1291,8 @@ test("wired DispatchAdapter clears verification retry state when skipping an alr
     };
     setRegistry(new RuleRegistry([retryRule]));
 
-    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-    const pi = { getActiveTools: () => [] } as any;
+    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+    const pi = { getActiveTools: () => [] } as never;
     const session = {
       basePath: base,
       pendingOrchestrationDispatch: { stale: true },
@@ -1435,17 +1301,17 @@ test("wired DispatchAdapter clears verification retry state when skipping an alr
         failureContext: "artifact missing",
         attempt: 1,
       },
-    } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, base, session);
+    } as never;
 
-    const result = await adapter.decideNextUnit({ stateSnapshot });
+    const result = await decideOrchestratorDispatch(ctx, pi, base, session, { stateSnapshot });
 
     assert.deepEqual(result, {
       kind: "skipped",
       reason: "execute-task M001/S01/T01 is already complete",
     });
-    assert.equal(session.pendingVerificationRetry, null);
-    assert.equal(session.pendingOrchestrationDispatch, null);
+    const sess = session as { pendingVerificationRetry: unknown; pendingOrchestrationDispatch: unknown };
+    assert.equal(sess.pendingVerificationRetry, null);
+    assert.equal(sess.pendingOrchestrationDispatch, null);
   } finally {
     resetRegistry();
     closeDatabase();
@@ -1453,7 +1319,7 @@ test("wired DispatchAdapter clears verification retry state when skipping an alr
   }
 });
 
-test("wired DispatchAdapter preserves stop reason as a blocked decision", async () => {
+test("decideOrchestratorDispatch preserves stop reason as a blocked decision", async () => {
   const stateSnapshot = makeState();
   const stopRule: UnifiedRule = {
     name: "test-stop",
@@ -1469,11 +1335,10 @@ test("wired DispatchAdapter preserves stop reason as a blocked decision", async
   setRegistry(new RuleRegistry([stopRule]));
 
   try {
-    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-    const pi = { getActiveTools: () => [] } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, "/tmp/parity-fixture");
+    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+    const pi = { getActiveTools: () => [] } as never;
 
-    const result = await adapter.decideNextUnit({ stateSnapshot });
+    const result = await decideOrchestratorDispatch(ctx, pi, "/tmp/parity-fixture", undefined, { stateSnapshot });
 
     assert.deepEqual(result, {
       kind: "blocked",
@@ -1485,7 +1350,7 @@ test("wired DispatchAdapter preserves stop reason as a blocked decision", async
   }
 });
 
-test("wired DispatchAdapter preserves dispatch skip instead of collapsing it to no remaining units", async () => {
+test("decideOrchestratorDispatch preserves dispatch skip instead of collapsing it to no remaining units", async () => {
   const stateSnapshot = makeState();
   const skipRule: UnifiedRule = {
     name: "test-skip-gate",
@@ -1500,11 +1365,10 @@ test("wired DispatchAdapter preserves dispatch skip instead of collapsing it to
   setRegistry(new RuleRegistry([skipRule]));
 
   try {
-    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as any;
-    const pi = { getActiveTools: () => [] } as any;
-    const adapter = createWiredDispatchAdapter(ctx, pi, "/tmp/parity-fixture");
+    const ctx = { model: {}, modelRegistry: { getAll: () => [] } } as never;
+    const pi = { getActiveTools: () => [] } as never;
 
-    const result = await adapter.decideNextUnit({ stateSnapshot });
+    const result = await decideOrchestratorDispatch(ctx, pi, "/tmp/parity-fixture", undefined, { stateSnapshot });
 
     assert.deepEqual(result, {
       kind: "skipped",