@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/scripts/daemon/dispatcher-governance.test.mjs

@@ -1,1013 +0,0 @@
-/**
- * dispatcher-governance.test.mjs — WS4 coverage for the dispatcher's
- * resource-governor / rate-breaker admission gating and the in-flight session
- * resume reconcile.
- *
- * The dispatcher is a stateful module that reads AGENT_DIR at import time and
- * spawns real `claude` children on the ADMIT path. To stay hermetic we:
- *   • import a FRESH module per test (isolated tmpdir AGENT_DIR), and
- *   • inject fake governor + rateGuard via setGovernanceForTests so we only
- *     ever exercise the NON-spawning branches (DEFER/QUEUE) and the reconcile
- *     path (which takes an injected spawnResume) — no child process is launched.
- *
- * The two invariants under test:
- *   (1) DEFER never drops work and never burns retry budget — a deferred
- *       backlog item is NOT claimed and NO session/queue entry is created, so
- *       the on-disk queue item is retried by the next sweep untouched.
- *   (2) Resume reconcile re-dispatches mid-flight work, and only after 3
- *       strikes marks the item blocked (never bricks, never loops forever).
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { promises as fsp } from "node:fs";
-import { writeFileSync, mkdirSync, existsSync, readFileSync, readdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-async function freshDispatcher() {
-  const dir = join(tmpdir(), `dispatcher-gov-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-  mkdirSync(join(dir, "state/sessions"), { recursive: true });
-  mkdirSync(join(dir, "state/queues"), { recursive: true });
-  mkdirSync(join(dir, "logs/daemon"), { recursive: true });
-  process.env.AGENT_DIR = dir;
-  const url = new URL("./dispatcher.mjs", import.meta.url);
-  const mod = await import(`${url.href}?gov=${Math.random()}`);
-  return { mod, dir };
-}
-async function cleanup(dir) { try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* */ } }
-
-/**
- * Read every diagnostic-event row the dispatcher appended to its tmp
- * logs/diagnostics/<UTC-date>.jsonl stream. Returns [] if nothing was written.
- */
-function readDiagnostics(dir) {
-  const date = new Date().toISOString().slice(0, 10);
-  const path = join(dir, "logs", "diagnostics", `${date}.jsonl`);
-  let raw = "";
-  try { raw = readFileSync(path, "utf-8"); } catch { return []; }
-  return raw.split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-}
-
-const fakeGovernor = (decision) => ({
-  admit: () => ({ decision, reason: `forced-${decision}`, snapshot: {} }),
-  defaultDeps: () => ({}),
-});
-const allowRate = { checkRateLimit: () => ({ allowed: true, retryAt: null }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} };
-const openRate = { checkRateLimit: () => ({ allowed: false, retryAt: Date.now() + 60_000 }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} };
-const noBudget = { dailyStatus: () => ({ essentialOnly: false }) };
-
-function itemClaimDir(dir) { return join(dir, "state/locks/item-claims"); }
-function claimFiles(dir) {
-  try { return readdirSync(itemClaimDir(dir)).filter((f) => f.endsWith(".claim")); } catch { return []; }
-}
-
-// ---------------------------------------------------------------------------
-// Invariant 1 — DEFER never drops work, never claims, never burns budget
-// ---------------------------------------------------------------------------
-
-test("backlog DEFER: item is NOT claimed and NO session is created (sweep retries it)", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("DEFER"), rateGuard: allowRate, budgetGuard: noBudget });
-    mod.dispatch("prompt", { id: "BL-1", title: "deep work", source_file: "backlog.yaml" }, { summary: "deep work", priority: "normal", model: "sonnet" }, "backlog");
-    const status = mod.getStatus();
-    assert.equal(status.active_sessions, 0, "no session spawned on DEFER");
-    assert.equal(status.priority_queue_length, 0);
-    assert.equal(status.normal_queue_length, 0);
-    // The crucial bit: no item claim was written, so the on-disk item is left
-    // fully intact for the next backlog sweep.
-    assert.deepEqual(claimFiles(dir), [], "DEFER must not claim the item");
-  } finally { await cleanup(dir); }
-});
-
-test("backlog QUEUE (capacity): item left on disk, not claimed, not spawned", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("QUEUE"), rateGuard: allowRate, budgetGuard: noBudget });
-    mod.dispatch("prompt", { id: "BL-2", title: "task", source_file: "backlog.yaml" }, { summary: "task", priority: "normal", model: "sonnet" }, "backlog");
-    const status = mod.getStatus();
-    assert.equal(status.active_sessions, 0);
-    assert.deepEqual(claimFiles(dir), [], "QUEUE must not claim the backlog item");
-  } finally { await cleanup(dir); }
-});
-
-test("inbox DEFER is QUEUED, never dropped (user message preserved in memory)", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("DEFER"), rateGuard: allowRate, budgetGuard: noBudget });
-    mod.dispatch("prompt", { id: "IN-1", channel: "D123" }, { summary: "hi", priority: "normal", model: "sonnet" }, "inbox");
-    const status = mod.getStatus();
-    assert.equal(status.active_sessions, 0, "DEFER does not spawn");
-    assert.equal(status.normal_queue_length, 1, "inbox DEFER is queued, not dropped");
-  } finally { await cleanup(dir); }
-});
-
-test("rate breaker open: backlog deferred (no claim), inbox queued", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // Governor would ADMIT, but the shared 429 breaker is open → gate spawns.
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: openRate, budgetGuard: noBudget });
-
-    mod.dispatch("p", { id: "BL-3", title: "t", source_file: "q.yaml" }, { summary: "t", priority: "normal", model: "sonnet" }, "backlog");
-    assert.deepEqual(claimFiles(dir), [], "rate-limited backlog must not claim");
-    assert.equal(mod.getStatus().active_sessions, 0);
-
-    mod.dispatch("p", { id: "IN-2", channel: "D9" }, { summary: "u", priority: "high", model: "sonnet" }, "inbox");
-    const status = mod.getStatus();
-    assert.equal(status.active_sessions, 0, "rate-limited inbox does not spawn");
-    assert.equal(status.priority_queue_length, 1, "high-priority inbox queued under the breaker");
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// Invariant 2 — resume reconcile: re-dispatch mid-flight, block after 3 strikes
-// ---------------------------------------------------------------------------
-
-function plantMarker(dir, sessionId, marker) {
-  const d = join(dir, "state/sessions/resume-pending");
-  mkdirSync(d, { recursive: true });
-  writeFileSync(join(d, `${sessionId}.json`), JSON.stringify({
-    sessionId, claudeSessionId: `cs-${sessionId}`, source: "backlog",
-    itemId: marker.itemId || null, sourceFile: marker.sourceFile || null,
-    // H1: a real marker persists the original prompt + the exact model flag so
-    // the resume re-spawns `--session-id <id> <prompt>` (not `--resume`).
-    prompt: marker.prompt ?? `continue work on ${marker.itemId || sessionId}`,
-    modelFlag: marker.modelFlag ?? "claude-sonnet-4-6",
-    model: marker.model ?? "sonnet",
-    startedAt: marker.startedAt ?? Date.now(), recoveryAttempts: marker.recoveryAttempts ?? 0,
-    ...marker,
-  }, null, 2));
-}
-
-test("reconcile re-dispatches a fresh in-flight marker via injected spawnResume", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    plantMarker(dir, "s-fresh", { itemId: "BL-9", sourceFile: "q.yaml", startedAt: Date.now() });
-    const resumed = [];
-    const stats = mod.reconcileResumePending({ spawnResume: ({ marker }) => resumed.push(marker.sessionId) });
-    assert.equal(stats.resumed, 1);
-    assert.deepEqual(resumed, ["s-fresh"]);
-    // The marker's attempt count was bumped (so a crash mid-resume still
-    // advances toward the strike cap), and the marker survives for the
-    // resumed session's own close handler to clear.
-    const m = JSON.parse(readFileSync(join(dir, "state/sessions/resume-pending/s-fresh.json"), "utf-8"));
-    assert.equal(m.recoveryAttempts, 1);
-  } finally { await cleanup(dir); }
-});
-
-test("reconcile blocks the item after 3 strikes instead of resuming forever", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // A real queue file with the item open, so markItemBlocked can flip it.
-    writeFileSync(join(dir, "state/queues/q.yaml"),
-      `- id: BL-STUCK\n  title: stuck task\n  status: open\n  priority: normal\n`);
-    plantMarker(dir, "s-stuck", { itemId: "BL-STUCK", sourceFile: "q.yaml", startedAt: Date.now(), recoveryAttempts: 3 });
-    const resumed = [];
-    const stats = mod.reconcileResumePending({ spawnResume: ({ marker }) => resumed.push(marker.sessionId) });
-    assert.equal(stats.blocked, 1);
-    assert.equal(stats.resumed, 0, "must NOT resume past the strike cap");
-    assert.deepEqual(resumed, []);
-    // Marker is gone, and the queue item is now status: blocked.
-    assert.equal(existsSync(join(dir, "state/sessions/resume-pending/s-stuck.json")), false);
-    const q = readFileSync(join(dir, "state/queues/q.yaml"), "utf-8");
-    assert.match(q, /status:\s*blocked/);
-    assert.match(q, /WS4 recovery/);
-  } finally { await cleanup(dir); }
-});
-
-test("reconcile blocks a marker that is older than the freshness window", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    writeFileSync(join(dir, "state/queues/q.yaml"),
-      `- id: BL-OLD\n  title: old\n  status: open\n  priority: low\n`);
-    // 7h old > default 6h freshness window.
-    plantMarker(dir, "s-old", { itemId: "BL-OLD", sourceFile: "q.yaml", startedAt: Date.now() - 7 * 60 * 60 * 1000, recoveryAttempts: 0 });
-    const resumed = [];
-    const stats = mod.reconcileResumePending({ spawnResume: ({ marker }) => resumed.push(marker.sessionId) });
-    assert.equal(stats.expired, 1);
-    assert.equal(stats.resumed, 0);
-    assert.equal(existsSync(join(dir, "state/sessions/resume-pending/s-old.json")), false);
-  } finally { await cleanup(dir); }
-});
-
-test("resume reconcile DEFERS (never re-storms) when the backlog budget is 0 (reactive-only seat)", async () => {
-  // DAEMON_MAX_CONCURRENT=3 → backlogCap = 3 - RESERVED_INBOX_SLOTS(3) = 0, so a
-  // reactive-only seat must resume NOTHING on boot — the fresh-seat storm root.
-  process.env.DAEMON_MAX_CONCURRENT = "3";
-  const { mod, dir } = await freshDispatcher();
-  try {
-    plantMarker(dir, "s-a", { itemId: "BL-A", sourceFile: "q.yaml", startedAt: Date.now() });
-    plantMarker(dir, "s-b", { itemId: "BL-B", sourceFile: "q.yaml", startedAt: Date.now() });
-    let spawned = 0;
-    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
-    assert.equal(spawned, 0, "no resume spawns on a budget-0 seat");
-    assert.equal(stats.resumed, 0);
-    assert.equal(stats.deferred, 2, "both live markers deferred, not blocked/expired");
-    // markers are LEFT on disk (deferred, not retired) for a later reconcile
-    const left = readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json"));
-    assert.equal(left.length, 2, "deferred markers persist");
-  } finally { delete process.env.DAEMON_MAX_CONCURRENT; await cleanup(dir); }
-});
-
-test("resume reconcile is GATED (resumes nothing) while the shared breaker is open", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ rateGuard: { checkRateLimit: () => ({ allowed: false, retryAt: Date.now() + 60_000 }) } });
-    plantMarker(dir, "s-x", { itemId: "BL-X", sourceFile: "q.yaml", startedAt: Date.now() });
-    let spawned = 0;
-    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
-    assert.equal(spawned, 0, "an open breaker (e.g. a usage-limit hold) blocks all resume");
-    assert.equal(stats.resumed, 0);
-    assert.equal(stats.scanned, 0, "returns before scanning when the breaker is open");
-    // the marker is untouched, ready for the next reconcile after the breaker clears
-    assert.equal(readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json")).length, 1);
-  } finally { await cleanup(dir); }
-});
-
-test("reconcile on an empty resume-pending dir is a no-op", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    const stats = mod.reconcileResumePending({ spawnResume: () => { throw new Error("should not spawn"); } });
-    assert.deepEqual(stats, { scanned: 0, resumed: 0, blocked: 0, expired: 0, deferred: 0 });
-  } finally { await cleanup(dir); }
-});
-
-test("resetActiveSessions({reconcile:true}) drives the reconcile; plain call does not", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    plantMarker(dir, "s-r", { itemId: "BL-R", sourceFile: "q.yaml", startedAt: Date.now() });
-    let spawns = 0;
-    // Plain reset (shutdown path): clears active.json, does NOT reconcile.
-    mod.resetActiveSessions();
-    assert.equal(existsSync(join(dir, "state/sessions/resume-pending/s-r.json")), true, "plain reset leaves markers untouched");
-    // Reconcile reset (startup path): re-dispatches.
-    mod.resetActiveSessions({ reconcile: true, spawnResume: () => { spawns++; } });
-    assert.equal(spawns, 1, "startup reconcile re-dispatched the marker");
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// H1 — the REAL resume spawner re-issues --session-id + a fresh prompt and
-// does NOT use --resume (the existing reconcile tests inject a fake spawnResume
-// so the real argv was previously untested). This is the regression guard for
-// the silent-work-loss / mass-blocking bug.
-// ---------------------------------------------------------------------------
-
-/** A child-process stub that captures argv and never launches anything. */
-function fakeProc() {
-  const handlers = {};
-  return {
-    stdout: { on: () => {} },
-    stderr: { on: () => {} },
-    on: (ev, cb) => { handlers[ev] = cb; },
-    kill: () => {},
-    killed: false,
-    _handlers: handlers,
-  };
-}
-
-test("H1: defaultSpawnResume re-spawns `--session-id <id> <prompt>` and NEVER `--resume`", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // A fresh, resumable marker carrying the original prompt + model flag.
-    plantMarker(dir, "s-real", {
-      itemId: "BL-REAL", sourceFile: "q.yaml", startedAt: Date.now(),
-      claudeSessionId: "CS-FIXED-UUID", prompt: "finish drafting the board memo", modelFlag: "claude-opus-4-6",
-    });
-
-    const calls = [];
-    const restore = mod.setSpawnForTests((bin, args) => { calls.push({ bin, args }); return fakeProc(); });
-    try {
-      // NO injected spawnResume → exercises the real defaultSpawnResume path.
-      const stats = mod.reconcileResumePending();
-      assert.equal(stats.resumed, 1, "the fresh marker should resume");
-    } finally { restore(); }
-
-    assert.equal(calls.length, 1, "exactly one resume spawn");
-    const { args } = calls[0];
-
-    // The blessed shape (mirrors responder.mjs):
-    assert.ok(!args.includes("--resume"), "must NOT use --resume (the bug)");
-    const sidIdx = args.indexOf("--session-id");
-    assert.ok(sidIdx >= 0, "must pass --session-id");
-    assert.equal(args[sidIdx + 1], "CS-FIXED-UUID", "resumes against the pre-minted session id");
-    // The original prompt is the LAST positional arg (the work to continue).
-    assert.equal(args[args.length - 1], "finish drafting the board memo", "carries the original prompt");
-    // Re-spawns against the SAME backend/model the original used.
-    const modelIdx = args.indexOf("--model");
-    assert.ok(modelIdx >= 0, "must pass --model");
-    assert.equal(args[modelIdx + 1], "claude-opus-4-6", "same model flag the original spawn used");
-    // It is a print-mode spawn (json/print contract), like every daemon spawn.
-    assert.ok(args.includes("--print"), "still a --print spawn");
-  } finally { await cleanup(dir); }
-});
-
-test("H1: a marker missing the original prompt is retired, never spawned as a no-op", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // Legacy / corrupt marker: has a session id but NO prompt.
-    const d = join(dir, "state/sessions/resume-pending");
-    mkdirSync(d, { recursive: true });
-    writeFileSync(join(d, "s-legacy.json"), JSON.stringify({
-      sessionId: "s-legacy", claudeSessionId: "CS-LEGACY", source: "backlog",
-      itemId: "BL-LEGACY", sourceFile: "q.yaml", startedAt: Date.now(), recoveryAttempts: 0,
-      // prompt intentionally absent
-    }, null, 2));
-
-    let spawned = 0;
-    const restore = mod.setSpawnForTests(() => { spawned++; return fakeProc(); });
-    try {
-      const stats = mod.reconcileResumePending();
-      assert.equal(stats.resumed, 0, "no prompt → cannot truly resume");
-      assert.equal(stats.expired, 1, "retired instead");
-    } finally { restore(); }
-    assert.equal(spawned, 0, "must NOT spawn a promptless no-op the close handler would treat as done");
-    assert.equal(existsSync(join(d, "s-legacy.json")), false, "the un-resumable marker is dropped");
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// M2 — an INTENTIONAL eviction clears the backlog item's resume marker, so a
-// later reboot reconcile can't re-dispatch it (no claim) while sweepBacklog
-// independently claims+dispatches the same item → double run.
-// ---------------------------------------------------------------------------
-
-test("M2: evicting a backlog session for a priority inbox item clears its resume marker", async () => {
-  // Eviction only fires when ALL slots are full (activeSessions.size >=
-  // MAX_CONCURRENT). With MAX_CONCURRENT=4 the backlog cap is 4 - RESERVED(3) =
-  // 1, so we run exactly 1 (evictable) backlog session plus 3 inbox sessions to
-  // saturate the daemon; the 5th (high-priority inbox) item must then preempt
-  // the backlog session. MAX_CONCURRENT is read at module top, so set it BEFORE
-  // the fresh import.
-  process.env.DAEMON_MAX_CONCURRENT = "4";
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // ADMIT everything; never spawn a real child (fake spawn).
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const restore = mod.setSpawnForTests(() => fakeProc());
-    try {
-      // 1) One running backlog session — this writes a resume-pending marker.
-      mod.dispatch("do the backlog work", { id: "BL-EVICT", title: "deep work", source_file: "q.yaml" },
-        { summary: "deep work", priority: "low", model: "sonnet" }, "backlog");
-      // 2) Saturate the remaining 3 slots with normal inbox sessions.
-      for (let i = 0; i < 3; i++) {
-        mod.dispatch("filler", { id: `IN-FILL-${i}`, channel: `D${i}` },
-          { summary: `filler ${i}`, priority: "normal", model: "sonnet" }, "inbox");
-      }
-      assert.equal(mod.getStatus().active_sessions, 4, "all 4 slots are full (1 backlog + 3 inbox)");
-      const markerDir = join(dir, "state/sessions/resume-pending");
-      const before = readdirSync(markerDir).filter((f) => f.endsWith(".json"));
-      assert.ok(before.length >= 1, "a resume marker exists for the running backlog session");
-
-      // 3) A high-priority inbox item with no free slot → must evict the backlog
-      //    session, and on eviction the marker must be cleared (deliberate
-      //    preemption, not a crash). Only the backlog session is evictable.
-      mod.dispatch("urgent ceo ask", { id: "IN-PRIO", channel: "DZ" },
-        { summary: "ceo ask", priority: "high", model: "sonnet" }, "inbox");
-
-      // The backlog session's marker (the only backlog source) is now gone.
-      // (The fake process never emits "close", so the in-memory session map and
-      // the 3 inbox markers persist — eviction's marker-clear is synchronous and
-      // independent of the close handler, which is exactly the point: a reboot
-      // happening right after the SIGTERM must NOT find a resumable marker.)
-      const after = readdirSync(markerDir).filter((f) => f.endsWith(".json"));
-      const remainingBacklog = after.filter((f) => {
-        try { return JSON.parse(readFileSync(join(markerDir, f), "utf-8")).itemId === "BL-EVICT"; }
-        catch { return false; }
-      });
-      assert.deepEqual(remainingBacklog, [], "the evicted backlog session's resume marker is cleared");
-      // Sanity: the 3 inbox sessions' markers are untouched (eviction is targeted).
-      assert.equal(after.length, 3, "only the backlog marker was cleared; inbox markers remain");
-    } finally { restore(); }
-  } finally {
-    delete process.env.DAEMON_MAX_CONCURRENT;
-    await cleanup(dir);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// yieldBacklogForReactive — a reply about to hit the subscription evicts
-// already-running BACKLOG down to REACTIVE_INFLIGHT_BACKLOG_MAX, and NEVER
-// touches an inbox/reactive session.
-// ---------------------------------------------------------------------------
-
-/** A child stub that records whether it was killed (never launches anything). */
-function killTrackingProc() {
-  const handlers = {};
-  const p = {
-    stdout: { on: () => {} },
-    stderr: { on: () => {} },
-    on: (ev, cb) => { handlers[ev] = cb; },
-    kill: () => { p.killed = true; },
-    killed: false,
-    _handlers: handlers,
-  };
-  return p;
-}
-
-test("yieldBacklogForReactive: evicts backlog down to the cap and spares every inbox session", async () => {
-  process.env.DAEMON_MAX_CONCURRENT = "8";
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const procs = [];
-    const restore = mod.setSpawnForTests(() => { const p = killTrackingProc(); procs.push(p); return p; });
-    try {
-      // 3 backlog sessions (dispatch order = age order) …
-      for (let i = 0; i < 3; i++) {
-        mod.dispatch("backlog work", { id: `BL-${i}`, title: `bl ${i}`, source_file: "q.yaml" },
-          { summary: `bl ${i}`, priority: "low", model: "sonnet" }, "backlog");
-      }
-      // … and 2 inbox sessions, all running concurrently.
-      for (let i = 0; i < 2; i++) {
-        mod.dispatch("inbox work", { id: `IN-${i}`, channel: `D${i}` },
-          { summary: `in ${i}`, priority: "normal", model: "sonnet" }, "inbox");
-      }
-      assert.equal(mod.getStatus().active_sessions, 5, "3 backlog + 2 inbox live");
-
-      // A reply is about to generate → yield the subscription. Cap is 1, so 2 of
-      // the 3 backlog sessions are evicted; the inbox sessions are never touched.
-      const evicted = mod.yieldBacklogForReactive();
-      assert.equal(evicted, 2, "evicts backlog down to REACTIVE_INFLIGHT_BACKLOG_MAX (1)");
-
-      const backlogProcs = procs.slice(0, 3);
-      const inboxProcs = procs.slice(3, 5);
-      assert.equal(backlogProcs.filter((p) => p.killed).length, 2, "exactly two backlog procs killed");
-      assert.equal(inboxProcs.filter((p) => p.killed).length, 0, "no inbox/reactive proc is ever killed");
-
-      // Idempotent: already at the cap → a second call is a no-op.
-      assert.equal(mod.yieldBacklogForReactive(), 0, "no further eviction once at the cap");
-    } finally { restore(); }
-  } finally {
-    delete process.env.DAEMON_MAX_CONCURRENT;
-    await cleanup(dir);
-  }
-});
-
-test("yieldBacklogForReactive: no-op when backlog is already at/under the cap", async () => {
-  process.env.DAEMON_MAX_CONCURRENT = "8";
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const restore = mod.setSpawnForTests(() => killTrackingProc());
-    try {
-      // Only inbox sessions running — nothing self-directed to yield.
-      for (let i = 0; i < 3; i++) {
-        mod.dispatch("inbox work", { id: `IN-${i}`, channel: `D${i}` },
-          { summary: `in ${i}`, priority: "normal", model: "sonnet" }, "inbox");
-      }
-      assert.equal(mod.yieldBacklogForReactive(), 0, "nothing to evict");
-      // One backlog session — at the cap of 1 → still a no-op.
-      mod.dispatch("bl", { id: "BL-ONE", title: "one", source_file: "q.yaml" },
-        { summary: "one", priority: "low", model: "sonnet" }, "backlog");
-      assert.equal(mod.yieldBacklogForReactive(), 0, "a single backlog session is within the cap");
-    } finally { restore(); }
-  } finally {
-    delete process.env.DAEMON_MAX_CONCURRENT;
-    await cleanup(dir);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// M1 — a governor/budget/rate DEFER that force-queues an inbox item while NO
-// session is running must arm a single (debounced) re-drain timer, so the item
-// isn't stranded until the next external dispatch.
-// ---------------------------------------------------------------------------
-
-test("M1: force-queued inbox item with zero active sessions arms a single re-drain timer", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // Governor DEFERs → inbox item is queued, not spawned, with 0 sessions.
-    mod.setGovernanceForTests({ governor: fakeGovernor("DEFER"), rateGuard: allowRate, budgetGuard: noBudget });
-    assert.equal(mod._hasReDrainArmed(), false, "no timer before any dispatch");
-
-    mod.dispatch("hello", { id: "IN-M1", channel: "D1" }, { summary: "hi", priority: "normal", model: "sonnet" }, "inbox");
-    assert.equal(mod.getStatus().normal_queue_length, 1, "DEFER queued the inbox item");
-    assert.equal(mod.getStatus().active_sessions, 0, "nothing running to drive a close-drain");
-    assert.equal(mod._hasReDrainArmed(), true, "a re-drain timer is armed to self-heal the stall");
-
-    // Debounce: a second force-queue must NOT stack a second timer.
-    mod.dispatch("hello again", { id: "IN-M1b", channel: "D2" }, { summary: "hi2", priority: "normal", model: "sonnet" }, "inbox");
-    assert.equal(mod.getStatus().normal_queue_length, 2);
-    assert.equal(mod._hasReDrainArmed(), true, "still exactly one armed timer (debounced)");
-  } finally { await cleanup(dir); }
-});
-
-test("M1: a fully-admitted inbox dispatch (which spawns) does not arm a re-drain timer", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const restore = mod.setSpawnForTests(() => fakeProc());
-    try {
-      mod.dispatch("hello", { id: "IN-OK", channel: "D1" }, { summary: "hi", priority: "normal", model: "sonnet" }, "inbox");
-      assert.equal(mod.getStatus().active_sessions, 1, "ADMIT spawned a session");
-      assert.equal(mod._hasReDrainArmed(), false, "a running session will drive the next drain — no timer needed");
-    } finally { restore(); }
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// 0.6 — permission posture: the user-facing inbox spawn routes through
-// sessionPermissionArgs() instead of a hardcoded --dangerously-skip-permissions.
-// Default behaviour is byte-for-byte unchanged; opting in actually scopes tools.
-// ---------------------------------------------------------------------------
-
-/** A controllable child stub that can emit stdout then close on demand. */
-function controllableProc() {
-  const handlers = {};
-  return {
-    stdout: { on: (ev, cb) => { if (ev === "data") handlers.stdout = cb; } },
-    stderr: { on: (ev, cb) => { if (ev === "data") handlers.stderr = cb; } },
-    on: (ev, cb) => { handlers[ev] = cb; },
-    kill: () => {},
-    killed: false,
-    emitStdout(chunk) { if (handlers.stdout) handlers.stdout(Buffer.from(chunk)); },
-    emitClose(code) { if (handlers.close) handlers.close(code); },
-  };
-}
-
-test("0.6: inbox spawn argv uses sessionPermissionArgs default (--dangerously-skip-permissions), never a hardcoded literal", async () => {
-  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
-  delete process.env.MAESTRO_SCOPED_PERMISSIONS; // default / back-compat mode
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const calls = [];
-    const restore = mod.setSpawnForTests((bin, args) => { calls.push(args); return fakeProc(); });
-    try {
-      mod.dispatch("do the thing", { id: "IN-PERM", channel: "D1" }, { summary: "x", priority: "normal", model: "sonnet" }, "inbox");
-      assert.equal(calls.length, 1, "exactly one spawn");
-      const args = calls[0];
-      // Default mode preserves the prior literal (no behaviour change for non-opted-in operators).
-      assert.ok(args.includes("--dangerously-skip-permissions"), "default permission flag preserved");
-      assert.ok(!args.includes("--allowedTools"), "no scoping in default mode");
-      // Cost telemetry: the run is asked for JSON output so we can read real usage.
-      assert.ok(args.includes("--output-format"), "spawn requests JSON output for cost capture");
-      assert.equal(args[args.indexOf("--output-format") + 1], "json");
-    } finally { restore(); }
-  } finally {
-    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
-    await cleanup(dir);
-  }
-});
-
-test("0.6: with MAESTRO_SCOPED_PERMISSIONS=1 the inbox spawn is scoped (--allowedTools), not skip-permissions", async () => {
-  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
-  process.env.MAESTRO_SCOPED_PERMISSIONS = "1"; // operator opts into scoping
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const calls = [];
-    const restore = mod.setSpawnForTests((bin, args) => { calls.push(args); return fakeProc(); });
-    try {
-      mod.dispatch("do the thing", { id: "IN-PERM2", channel: "D1" }, { summary: "x", priority: "normal", model: "sonnet" }, "inbox");
-      const args = calls[0];
-      assert.ok(!args.includes("--dangerously-skip-permissions"), "scoped mode must NOT skip permissions");
-      const idx = args.indexOf("--allowedTools");
-      assert.ok(idx >= 0, "scoped mode passes --allowedTools");
-      assert.ok(typeof args[idx + 1] === "string" && args[idx + 1].length > 0, "with a non-empty tool list");
-    } finally { restore(); }
-  } finally {
-    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
-    await cleanup(dir);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// 0.3 — cost telemetry: the dispatcher parser recovers REAL token usage from a
-// `--output-format json` run, and the close handler writes a truthful ledger
-// row (no more --input-tokens 0 fabrication).
-// ---------------------------------------------------------------------------
-
-test("0.3: parseUsageFromText recovers real token usage + total_cost_usd from a JSON result", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    const json = JSON.stringify({
-      result: "done",
-      usage: { input_tokens: 4200, output_tokens: 530, cache_read_input_tokens: 1000 },
-      total_cost_usd: 0.071,
-      model: "claude-opus-4-6",
-    });
-    const u = mod.parseUsageFromText(json);
-    assert.equal(u.ok, true);
-    assert.equal(u.inputTokens, 4200);
-    assert.equal(u.outputTokens, 530);
-    assert.equal(u.cacheReadTokens, 1000);
-    assert.equal(u.totalCostUsd, 0.071);
-    assert.equal(u.model, "opus", "resolved model id maps to the tracker's coarse class");
-
-    // A banner-prefixed JSON tail still parses (tolerant path).
-    const u2 = mod.parseUsageFromText(`[some-warning]\n${json}`);
-    assert.equal(u2.ok, true);
-    assert.equal(u2.inputTokens, 4200);
-
-    // Non-JSON / no usage → ok:false with a reason, NEVER fabricated zeros.
-    assert.equal(mod.parseUsageFromText("plain text reply").ok, false);
-    assert.equal(mod.parseUsageFromText("").reason, "empty-stdout");
-    assert.equal(mod.parseUsageFromText(JSON.stringify({ result: "x" })).reason, "no-usage-field");
-  } finally { await cleanup(dir); }
-});
-
-test("0.3: a finished inbox session writes a nonzero cost-ledger row from its real usage", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    // Ledger dir + a real tracker so the close handler's detached `record` call
-    // actually appends a row. (The dispatcher invokes the on-disk tracker.)
-    await fsp.mkdir(join(dir, "state/cost-tracking"), { recursive: true });
-    await fsp.mkdir(join(dir, "scripts/cost"), { recursive: true });
-    await fsp.copyFile(
-      new URL("../cost/track-claude-usage.mjs", import.meta.url),
-      join(dir, "scripts/cost/track-claude-usage.mjs")
-    );
-    // The tracker imports the shared billing contract (lib/cost/ledger-row.mjs)
-    // relative to itself, so a synthetic agent root needs it too — otherwise the
-    // detached `record` spawn dies on import and writes nothing. (In the wild
-    // that failure is silent, which is why doctor's tripwire now goes RED when
-    // the daemon logs sessions that never reach the ledger.)
-    await fsp.mkdir(join(dir, "lib/cost"), { recursive: true });
-    await fsp.copyFile(
-      new URL("../../lib/cost/ledger-row.mjs", import.meta.url),
-      join(dir, "lib/cost/ledger-row.mjs")
-    );
-
-    const proc = controllableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    try {
-      mod.dispatch("work", { id: "IN-COST", channel: "D1" }, { summary: "x", priority: "normal", model: "sonnet" }, "inbox");
-      // Feed the run's JSON result then close cleanly.
-      proc.emitStdout(JSON.stringify({
-        result: "ok",
-        usage: { input_tokens: 2000, output_tokens: 400 },
-        total_cost_usd: 0.012,
-        model: "claude-sonnet-4-6",
-      }));
-      proc.emitClose(0);
-    } finally { restore(); }
-
-    // The tracker is spawned detached; poll briefly for the ledger row.
-    const date = new Date().toISOString().slice(0, 10);
-    const ledger = join(dir, "state/cost-tracking", `${date}.jsonl`);
-    let body = "";
-    for (let i = 0; i < 80 && !body.trim(); i++) {
-      try { body = readFileSync(ledger, "utf-8"); } catch { /* not yet */ }
-      if (!body.trim()) await new Promise((r) => setTimeout(r, 25));
-    }
-    assert.ok(body.trim(), "a cost row was appended for the dispatcher session");
-    const row = JSON.parse(body.trim().split("\n").pop());
-    assert.equal(row.source, "dispatcher", "row attributed to the dispatcher spawn source");
-    assert.equal(row.input_tokens, 2000, "REAL input tokens recorded (not 0)");
-    assert.equal(row.output_tokens, 400, "REAL output tokens recorded (not 0)");
-    assert.ok(row.estimated_usd > 0, `estimated_usd must be nonzero, got ${row.estimated_usd}`);
-    assert.equal(row.total_cost_usd, 0.012, "CLI authoritative cost stored for reconciliation");
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// Phase 3-4 COVERAGE — the dispatcher routes session spawns through the v2
-// resolveChain path when the agent opts into a `schema_version: 2` config. The
-// RouteDecision drives the --model flag + spawn knobs (--max-turns / --agents),
-// and its decision_id is carried onto the resume marker (and the ledger row).
-// A v2 config that resolves to an Anthropic session keeps stock keychain auth
-// (no retarget env), so this stays byte-compatible with the Max-subscription
-// default for the model id Anthropic resolves.
-// ---------------------------------------------------------------------------
-
-/**
- * Write a minimal `schema_version: 2` routing config (JSON form, so the loader
- * needs no js-yaml) into the agent dir. The default rule resolves a session to
- * the Anthropic Sonnet row in the bundled catalog (grade A — the only reachable
- * session backend without third-party keys).
- */
-function writeV2Config(dir) {
-  mkdirSync(join(dir, "config"), { recursive: true });
-  const cfg = {
-    schema_version: 2,
-    aliases: {
-      frontier: "anthropic/claude-opus-4-8",
-      default: "anthropic/claude-sonnet-4-6",
-      fast: "anthropic/claude-haiku-4-5",
-    },
-    defaults: { needs_tool_use_for_sessions: true, data_class: "sensitive", cache_ttl: "1h" },
-    backends: { anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] } },
-    routing_policy: [{ default: true, chain: ["default", "fast"] }],
-    fallback_to_anthropic: true,
-  };
-  writeFileSync(join(dir, "config/model-routing.json"), JSON.stringify(cfg, null, 2));
-}
-
-test("COVERAGE: a v2 config routes the inbox spawn through resolveChain (--model + --max-turns + --agents)", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    writeV2Config(dir);
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const calls = [];
-    const restore = mod.setSpawnForTests((bin, args) => { calls.push(args); return fakeProc(); });
-    try {
-      mod.dispatch("respond to the user", { id: "IN-V2", channel: "D1" }, { summary: "v2", priority: "normal", model: "sonnet" }, "inbox");
-      assert.equal(calls.length, 1, "exactly one spawn");
-      const args = calls[0];
-      // Cost telemetry + JSON contract preserved.
-      assert.ok(args.includes("--print"));
-      assert.equal(args[args.indexOf("--output-format") + 1], "json");
-      // The decision's chosen model flows onto --model (concrete catalog id).
-      const mIdx = args.indexOf("--model");
-      assert.ok(mIdx >= 0, "must pass --model");
-      assert.equal(args[mIdx + 1], "claude-sonnet-4-6", "routed to the v2 default (Sonnet) catalog id");
-      // Session.responder spawn knobs (SPEC §6.5): --max-turns + Haiku-Explore --agents.
-      const mtIdx = args.indexOf("--max-turns");
-      assert.ok(mtIdx >= 0, "v2 spawn carries --max-turns");
-      assert.equal(args[mtIdx + 1], "40", "session.responder maxTurns default");
-      const agIdx = args.indexOf("--agents");
-      assert.ok(agIdx >= 0, "v2 spawn carries the --agents cheap-subagent map");
-      assert.ok(/Haiku-Explore/.test(args[agIdx + 1]), "the agents map is the Haiku-Explore fan-out");
-      // Permission posture unchanged (default skip-permissions).
-      assert.ok(args.includes("--dangerously-skip-permissions"), "permission posture preserved");
-      // The prompt is still the last positional arg.
-      assert.equal(args[args.length - 1], "respond to the user", "prompt remains the trailing positional");
-    } finally { restore(); }
-  } finally { await cleanup(dir); }
-});
-
-test("COVERAGE: the v2 resume marker carries the RouteDecision decision_id", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    writeV2Config(dir);
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const restore = mod.setSpawnForTests(() => fakeProc());
-    try {
-      mod.dispatch("work", { id: "IN-DID", channel: "D1" }, { summary: "did", priority: "normal", model: "sonnet" }, "inbox");
-      const markerDir = join(dir, "state/sessions/resume-pending");
-      const files = readdirSync(markerDir).filter((f) => f.endsWith(".json"));
-      assert.equal(files.length, 1, "one resume marker written");
-      const marker = JSON.parse(readFileSync(join(markerDir, files[0]), "utf-8"));
-      assert.ok(typeof marker.decision_id === "string" && marker.decision_id.length > 0, "marker carries a v2 decision_id");
-      assert.equal(marker.modelFlag, "claude-sonnet-4-6", "marker pins the routed model flag");
-    } finally { restore(); }
-  } finally { await cleanup(dir); }
-});
-
-test("COVERAGE: MAESTRO_ROUTER_FORCE_ANTHROPIC still short-circuits under a v2 config", async () => {
-  const prev = process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC;
-  process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC = "1";
-  const { mod, dir } = await freshDispatcher();
-  try {
-    writeV2Config(dir);
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const calls = [];
-    const restore = mod.setSpawnForTests((bin, args) => { calls.push(args); return fakeProc(); });
-    try {
-      mod.dispatch("hi", { id: "IN-KILL", channel: "D1" }, { summary: "kill", priority: "normal", model: "sonnet" }, "inbox");
-      const args = calls[0];
-      // Kill switch → Anthropic-only chain; spawn still happens, env is NOT a
-      // third-party retarget (no ANTHROPIC_BASE_URL injected for an Anthropic row).
-      assert.ok(args.includes("--print"));
-      assert.ok(args.includes("--model"), "kill switch still spawns with a concrete --model");
-    } finally { restore(); }
-  } finally {
-    if (prev === undefined) delete process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC; else process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC = prev;
-    await cleanup(dir);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// F1/H2 — dispatch onClose: the spawn-close notification that lets the daemon
-// defer markProcessed to success and re-deliver on crash. The callback must
-// fire EXACTLY ONCE per session, with ok=true only on a clean (exit 0) close
-// and ok=false on a non-zero close OR a spawn error.
-// ---------------------------------------------------------------------------
-
-/** A controllable stub that can emit stdout, close, or error on demand. */
-function closableProc() {
-  const handlers = {};
-  return {
-    stdout: { on: (ev, cb) => { if (ev === "data") handlers.stdout = cb; } },
-    stderr: { on: (ev, cb) => { if (ev === "data") handlers.stderr = cb; } },
-    on: (ev, cb) => { handlers[ev] = cb; },
-    kill: () => {},
-    killed: false,
-    emitStdout(chunk) { if (handlers.stdout) handlers.stdout(Buffer.from(chunk)); },
-    emitClose(code) { if (handlers.close) handlers.close(code); },
-    emitError(err) { if (handlers.error) handlers.error(err); },
-  };
-}
-
-test("F1/H2: a clean (exit 0) close fires onClose once with ok:true", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const calls = [];
-    try {
-      mod.dispatch("work", { id: "IN-OK", raw_ref: "slack:C1:111", channel: "D1" },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox",
-        { onClose: (r) => calls.push(r) });
-      assert.equal(mod.getStatus().active_sessions, 1, "session spawned");
-      assert.equal(calls.length, 0, "onClose has NOT fired before close (markProcessed must be deferred)");
-      proc.emitClose(0);
-    } finally { restore(); }
-    assert.equal(calls.length, 1, "onClose fired exactly once on close");
-    assert.equal(calls[0].ok, true, "exit 0 → ok:true (finalize)");
-    assert.equal(calls[0].code, 0);
-    assert.equal(calls[0].item.id, "IN-OK", "the original item is handed back to the caller");
-  } finally { await cleanup(dir); }
-});
-
-test("F1/H2: a non-zero close fires onClose once with ok:false (item left re-deliverable)", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const calls = [];
-    try {
-      mod.dispatch("work", { id: "IN-FAIL", raw_ref: "slack:C2:222", channel: "D2" },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox",
-        { onClose: (r) => calls.push(r) });
-      proc.emitClose(1);
-    } finally { restore(); }
-    assert.equal(calls.length, 1, "onClose fired exactly once");
-    assert.equal(calls[0].ok, false, "non-zero exit → ok:false (do NOT finalize)");
-  } finally { await cleanup(dir); }
-});
-
-test("F1/H2: a spawn error fires onClose once with ok:false and is not double-fired by the trailing close", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const calls = [];
-    try {
-      mod.dispatch("work", { id: "IN-ERR", raw_ref: "slack:C3:333", channel: "D3" },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox",
-        { onClose: (r) => calls.push(r) });
-      // ENOENT-style failure emits "error" then a trailing "close" (the
-      // dispatcher's spawnErrorHandled guard). onClose must fire only once.
-      const err = new Error("spawn ENOENT"); err.code = "ENOENT";
-      proc.emitError(err);
-      proc.emitClose(null);
-    } finally { restore(); }
-    assert.equal(calls.length, 1, "onClose fired exactly once despite error+close");
-    assert.equal(calls[0].ok, false, "spawn failure → ok:false");
-  } finally { await cleanup(dir); }
-});
-
-test("F1/H2: onClose survives queueing — a DEFER'd inbox item still fires onClose once drained+spawned", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    // The queued entry must carry its onClose through to a later drain. Flip the
-    // governor decision between dispatches: the FIRST inbox item is DEFER'd
-    // (queued, no spawn), then we flip to ADMIT so a SECOND item spawns; closing
-    // that second session drives drainQueue, which spawns the queued first item
-    // — its onClose must still fire.
-    let decision = "DEFER";
-    const swingGovernor = { admit: () => ({ decision, reason: `forced-${decision}`, snapshot: {} }), defaultDeps: () => ({}) };
-    mod.setGovernanceForTests({ governor: swingGovernor, rateGuard: allowRate, budgetGuard: noBudget });
-    const byPrompt = new Map();
-    const restore = mod.setSpawnForTests((bin, args) => {
-      const p = closableProc();
-      byPrompt.set(args[args.length - 1], p); // key by trailing prompt positional
-      return p;
-    });
-    const queuedCalls = [];
-    try {
-      // 1) DEFER → queued, no spawn yet, onClose pending.
-      mod.dispatch("queued-work", { id: "IN-Q", raw_ref: "slack:C4:444", channel: "D4" },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox",
-        { onClose: (r) => queuedCalls.push(r) });
-      assert.equal(mod.getStatus().normal_queue_length, 1, "DEFER queued the first item");
-      assert.equal(byPrompt.size, 0, "nothing spawned under DEFER");
-
-      // 2) Flip to ADMIT and dispatch a driver item that actually spawns.
-      decision = "ADMIT";
-      mod.dispatch("driver-work", { id: "IN-DRV", raw_ref: "slack:C4:445", channel: "D4b" },
-        { summary: "y", priority: "normal", model: "sonnet" }, "inbox", { onClose: () => {} });
-      assert.ok(byPrompt.has("driver-work"), "driver session spawned under ADMIT");
-      assert.equal(queuedCalls.length, 0, "queued item's onClose has NOT fired yet");
-
-      // 3) Close the driver → drainQueue spawns the queued IN-Q (carrying onClose).
-      byPrompt.get("driver-work").emitClose(0);
-      assert.ok(byPrompt.has("queued-work"), "the queued item spawned on drain");
-      assert.equal(queuedCalls.length, 0, "still not fired until the queued session itself closes");
-
-      // 4) Close the queued session → its onClose finally fires (ok:true).
-      byPrompt.get("queued-work").emitClose(0);
-    } finally { restore(); }
-    assert.equal(queuedCalls.length, 1, "the queued item's onClose fired exactly once after spawn+close");
-    assert.equal(queuedCalls[0].ok, true, "clean close → ok:true");
-    assert.equal(queuedCalls[0].item.id, "IN-Q", "onClose carries the originally-queued item");
-  } finally { await cleanup(dir); }
-});
-
-// ---------------------------------------------------------------------------
-// DIAG — the observability spine: the dispatcher emits dispatched →
-// session_opened → session_closed onto logs/diagnostics, all carrying the
-// interaction's trace_id (handed off explicitly on item.trace_id, since the
-// proc-close handler fires outside any withTrace scope) so the audit can join
-// every hop of one interaction by a single id. STRICT additive: emitEvent is
-// fail-open and never alters dispatch/spawn/close semantics.
-// ---------------------------------------------------------------------------
-
-test("DIAG: a spawned+closed inbox session emits dispatched→session_opened→session_closed carrying ONE stable trace_id", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const TRACE = "01HZZZTRACEDISPATCHERTEST0"; // 26-char ULID-shaped id the daemon would have minted
-    try {
-      // The daemon sets item.trace_id at item_received; the dispatcher reads it.
-      mod.dispatch("work", { id: "IN-TRACE", raw_ref: "slack:C1:1", channel: "D1", trace_id: TRACE },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox", { onClose: () => {} });
-      proc.emitClose(0);
-    } finally { restore(); }
-
-    const rows = readDiagnostics(dir);
-    const byType = (t) => rows.filter((r) => r.type === t);
-    const dispatched = byType("dispatched");
-    const opened = byType("session_opened");
-    const closed = byType("session_closed");
-    assert.equal(dispatched.length, 1, "exactly one dispatched event");
-    assert.equal(opened.length, 1, "exactly one session_opened event");
-    assert.equal(closed.length, 1, "exactly one session_closed event");
-    // The crucial invariant: a single stable trace_id across every hop.
-    for (const r of [dispatched[0], opened[0], closed[0]]) {
-      assert.equal(r.trace_id, TRACE, `${r.type} carries the interaction trace_id`);
-    }
-    assert.equal(closed[0].attrs.exit_code, 0, "session_closed records the clean exit code");
-    // Same session_id ties the three rows to one spawn.
-    assert.equal(dispatched[0].attrs.session_id, opened[0].attrs.session_id);
-    assert.equal(opened[0].attrs.session_id, closed[0].attrs.session_id);
-  } finally { await cleanup(dir); }
-});
-
-test("DIAG: a spawn ERROR still emits session_closed once (exit_code null, error carried), carrying the trace_id", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const TRACE = "01HZZZTRACEDISPATCHERERR00";
-    try {
-      mod.dispatch("work", { id: "IN-ERR", raw_ref: "slack:C2:2", channel: "D2", trace_id: TRACE },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox", { onClose: () => {} });
-      const err = new Error("spawn ENOENT"); err.code = "ENOENT";
-      proc.emitError(err);
-      proc.emitClose(null); // trailing close (spawnErrorHandled guard) must NOT re-emit
-    } finally { restore(); }
-
-    const closed = readDiagnostics(dir).filter((r) => r.type === "session_closed");
-    assert.equal(closed.length, 1, "exactly one session_closed even with error+trailing-close");
-    assert.equal(closed[0].trace_id, TRACE, "error-path session_closed carries the trace_id");
-    assert.equal(closed[0].attrs.exit_code, null, "spawn-error close has no exit code");
-    assert.equal(closed[0].attrs.error, "ENOENT", "the spawn error code is recorded");
-  } finally { await cleanup(dir); }
-});
-
-test("DIAG: a v2-routed spawn carries the RouteDecision decision_id onto every diagnostic hop", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    writeV2Config(dir);
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const TRACE = "01HZZZTRACEDISPATCHERV2000";
-    try {
-      mod.dispatch("work", { id: "IN-V2D", channel: "D1", trace_id: TRACE },
-        { summary: "v2", priority: "normal", model: "sonnet" }, "inbox", { onClose: () => {} });
-      proc.emitClose(0);
-    } finally { restore(); }
-
-    const rows = readDiagnostics(dir).filter((r) => ["dispatched", "session_opened", "session_closed"].includes(r.type));
-    assert.equal(rows.length, 3, "all three hops emitted");
-    for (const r of rows) {
-      assert.ok(typeof r.attrs.decision_id === "string" && r.attrs.decision_id.length > 0,
-        `${r.type} carries a v2 decision_id`);
-    }
-  } finally { await cleanup(dir); }
-});
-
-test("DIAG: emitEvent is fail-open — a session with no trace_id still closes cleanly (trace_id null, no throw)", async () => {
-  const { mod, dir } = await freshDispatcher();
-  try {
-    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
-    const proc = closableProc();
-    const restore = mod.setSpawnForTests(() => proc);
-    const calls = [];
-    try {
-      // No trace_id on the item (an un-instrumented call path). The dispatch +
-      // close must work exactly as before; diagnostics degrade to trace_id null.
-      mod.dispatch("work", { id: "IN-NOTRACE", raw_ref: "slack:C9:9", channel: "D9" },
-        { summary: "x", priority: "normal", model: "sonnet" }, "inbox", { onClose: (r) => calls.push(r) });
-      proc.emitClose(0);
-    } finally { restore(); }
-    assert.equal(calls.length, 1, "onClose still fired (semantics preserved)");
-    assert.equal(calls[0].ok, true, "clean close → ok:true unchanged");
-    const closed = readDiagnostics(dir).filter((r) => r.type === "session_closed");
-    assert.equal(closed.length, 1);
-    assert.equal(closed[0].trace_id, null, "no interaction trace → trace_id null (degrades, never throws)");
-  } finally { await cleanup(dir); }
-});