@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/cadence-consumer.test.mjs

@@ -0,0 +1,770 @@
+/**
+ * cadence-consumer.test.mjs — node:test coverage for the cadence consumer.
+ *
+ * Uses startConsumer({ spawnSession }) to inject a stub sub-session spawner
+ * so no real Claude Code process is ever launched. Each test creates its own
+ * AGENT_ROOT under tmpdir() and tears it down afterwards.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, dirname } from "path";
+
+import { enqueueTick, listInbox, listClaimed, busDepth, getBusPaths } from "../../lib/cadence-bus.mjs";
+import { startConsumer as startConsumerRaw, parseUsageFromStdout, routeCadenceSpawn } from "./cadence-consumer.mjs";
+import { statSync } from "node:fs";
+
+// WS4 added a resource-governor + 429-breaker + budget gate to the consumer's
+// escalation path. These tests exercise the cadence routing / reliability layer
+// (inline vs guarded vs escalate, circuit breaker, stale recovery), which is
+// ORTHOGONAL to host-resource gating — so we neutralise WS4 with always-admit
+// stubs here. The governance gate itself is covered by
+// cadence-consumer-governance.test.mjs + resource-governor/rate-guard tests.
+const ADMIT_ALL = { admit: () => ({ decision: "ADMIT", reason: "test", snapshot: {} }), defaultDeps: () => ({}) };
+const RATE_OK = { checkRateLimit: () => ({ allowed: true, retryAt: null }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} };
+const BUDGET_OK = { dailyStatus: () => ({ essentialOnly: false }) };
+function startConsumer(opts = {}) {
+  return startConsumerRaw({ governor: ADMIT_ALL, rateGuard: RATE_OK, budgetGuard: BUDGET_OK, ...opts });
+}
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `cadence-consumer-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+/**
+ * Seed an agent root with a trigger prompt for a given cadence. Lets the
+ * consumer's "escalate" path find a real prompt file when our stub spawner
+ * is invoked.
+ */
+function plantPrompt(root, cadence, body = `# ${cadence} trigger prompt`) {
+  const path = join(root, "schedules/triggers", `${cadence}.md`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body);
+  return path;
+}
+
+/**
+ * Wait until `predicate()` returns truthy or the deadline expires. Polls
+ * every 25ms — fast enough for sub-200ms drain cycles, slow enough that
+ * tests don't burn CPU.
+ */
+async function waitFor(predicate, { timeoutMs = 5_000, intervalMs = 25 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await predicate()) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Inline handlers
+// ---------------------------------------------------------------------------
+
+test("consumer processes a registry-inline cadence without spawning", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    heartbeatMs: 1_000,
+    recoveryMs: 60_000,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    enqueueTick({ cadence: "cadence-bus-heartbeat", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().inline >= 1);
+    assert.ok(ok, "heartbeat cadence should drain inline");
+    assert.equal(spawnCalls.length, 0, "inline cadence must not spawn");
+    assert.equal(busDepth(root).inbox, 0);
+    assert.equal(busDepth(root).claimed, 0);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Guarded handlers
+// ---------------------------------------------------------------------------
+
+test("guarded cadence completes inline when there's no work", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    // No inbox files, no queues with items → guard returns "inline".
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().inline >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 0, "inbox empty → no spawn");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("guarded cadence escalates when guard says work is pending", async () => {
+  const root = await makeAgentRoot();
+  // Seed an inbox item so the inbox-processor guard returns "escalate".
+  // Also set INBOX_CADENCE_ESCALATE=1 because the default behaviour is
+  // now inline (reactive daemon owns inbox dispatch — see cadence-handlers.mjs).
+  mkdirSync(join(root, "state/inbox/slack"), { recursive: true });
+  writeFileSync(join(root, "state/inbox/slack/item.json"), JSON.stringify({ id: "msg1" }));
+  plantPrompt(root, "inbox-processor");
+  const prevEnv = process.env.INBOX_CADENCE_ESCALATE;
+  process.env.INBOX_CADENCE_ESCALATE = "1";
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0, duration_ms: 5 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok, "guard with pending work should escalate");
+    assert.equal(spawnCalls.length, 1);
+    assert.equal(spawnCalls[0].cadence, "inbox-processor");
+    assert.match(spawnCalls[0].promptPath, /schedules\/triggers\/inbox-processor\.md$/);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+    if (prevEnv === undefined) delete process.env.INBOX_CADENCE_ESCALATE;
+    else process.env.INBOX_CADENCE_ESCALATE = prevEnv;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Escalate path
+// ---------------------------------------------------------------------------
+
+test("escalate-mode cadence spawns with the configured prompt", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0, duration_ms: 10 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls[0].cadence, "weekly-strategic-memo");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("unknown cadence with a prompt file falls back to escalate", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "custom-cadence");
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "custom-cadence", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("unknown cadence with no prompt file DLQ's immediately", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "totally-unknown-thing", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().dlq >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 0);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Spawn failures
+// ---------------------------------------------------------------------------
+
+test("spawn failure retries within the budget, then DLQs", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  // Disable back-off + raise circuit threshold so the test exercises the
+  // retry-then-DLQ path without waiting for back-off windows. The
+  // real defaults (30s/2m back-off, 3-failure circuit) are exercised by
+  // dedicated tests below.
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 25,
+    backoffSchedule: [0, 0, 0],
+    circuitThreshold: 999,
+    maxAttempts: 2,
+    spawnSession: async () => ({ ok: false, exit_code: 1, error: "always-fail", duration_ms: 1 }),
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().dlq >= 1, { timeoutMs: 15_000 });
+    assert.ok(ok, `event should DLQ eventually; stats=${JSON.stringify(consumer.getStats())}`);
+    assert.ok(consumer.getStats().spawn_failures >= 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("circuit breaker opens after consecutive failures and blocks further spawns", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 20,
+    backoffSchedule: [0, 0, 0],
+    circuitThreshold: 2,
+    circuitDurationMs: 60_000, // 1 min — long enough for the assertion window
+    maxAttempts: 1, // each event DLQs on first failure so we don't conflate retry-counts
+    spawnSession: async () => { spawnCount++; return { ok: false, exit_code: 1, error: "fail", duration_ms: 1 }; },
+  });
+  try {
+    // Enqueue 5 events; circuit should open after 2 failures, blocking the rest.
+    for (let i = 0; i < 5; i++) {
+      enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    }
+    const opened = await waitFor(() => consumer.getStats().skipped_circuit_open >= 1, { timeoutMs: 10_000 });
+    assert.ok(opened, `circuit should open; stats=${JSON.stringify(consumer.getStats())}`);
+    // Spawn count must NOT keep climbing once the circuit is open.
+    const spawnsAtOpen = spawnCount;
+    await new Promise((r) => setTimeout(r, 500));
+    assert.equal(spawnCount, spawnsAtOpen, `spawns must stop once circuit opens (was ${spawnsAtOpen}, now ${spawnCount})`);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("back-off skips re-spawning until the cooldown elapses", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 20,
+    backoffSchedule: [0, 300, 300], // 300ms cooldown after each failure
+    circuitThreshold: 999,
+    maxAttempts: 1,
+    spawnSession: async () => { spawnCount++; return { ok: false, exit_code: 1, error: "fail", duration_ms: 1 }; },
+  });
+  try {
+    // Enqueue 2 events back-to-back. The 1st triggers a spawn (fails). The
+    // 2nd should be held back by the 300ms back-off window.
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await waitFor(() => spawnCount >= 1, { timeoutMs: 5_000 });
+    const spawnsBeforeWait = spawnCount;
+    // During the back-off window no new spawn should fire.
+    await new Promise((r) => setTimeout(r, 150));
+    assert.ok(spawnCount === spawnsBeforeWait, `spawns must wait for back-off (was ${spawnsBeforeWait}, now ${spawnCount})`);
+    assert.ok(consumer.getStats().skipped_backoff >= 1, "skipped_backoff should be recorded");
+    // After the window passes, the next event should be processed.
+    await waitFor(() => spawnCount > spawnsBeforeWait, { timeoutMs: 5_000 });
+    assert.ok(spawnCount > spawnsBeforeWait, "spawning resumes after back-off");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Emergency stop
+// ---------------------------------------------------------------------------
+
+test("consumer skips processing while .emergency-stop exists", async () => {
+  const root = await makeAgentRoot();
+  writeFileSync(join(root, ".emergency-stop"), "now");
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async () => { spawnCount++; return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    // Enqueue directly to the inbox: the bus's emergency-stop check is on
+    // enqueue, so we must bypass it. Drop a file straight in inbox/.
+    const paths = getBusPaths(root);
+    writeFileSync(join(paths.inbox, "evt-test.json"), JSON.stringify({
+      id: "evt-test", type: "cadence_tick", source: "manual", ts: new Date().toISOString(),
+      cadence: "weekly-strategic-memo", workflow: null, correlation_id: null,
+      priority: "normal", metadata: {}, attempts: 0,
+    }));
+    await new Promise((r) => setTimeout(r, 300));
+    const stats = consumer.getStats();
+    assert.equal(spawnCount, 0, "no spawn during emergency stop");
+    assert.ok(stats.skipped_emergency_stop >= 1);
+    assert.equal(listInbox(root).length, 1, "event remains in inbox until stop lifts");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("consumer resumes after .emergency-stop is removed", async () => {
+  const root = await makeAgentRoot();
+  writeFileSync(join(root, ".emergency-stop"), "now");
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 25,
+    spawnSession: async () => { spawnCount++; return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    const paths = getBusPaths(root);
+    writeFileSync(join(paths.inbox, "evt-test.json"), JSON.stringify({
+      id: "evt-test", type: "cadence_tick", source: "manual", ts: new Date().toISOString(),
+      cadence: "weekly-strategic-memo", workflow: null, correlation_id: null,
+      priority: "normal", metadata: {}, attempts: 0,
+    }));
+    await new Promise((r) => setTimeout(r, 200));
+    assert.equal(spawnCount, 0);
+    // Lift the stop.
+    await fsp.unlink(join(root, ".emergency-stop"));
+    const ok = await waitFor(() => spawnCount >= 1);
+    assert.ok(ok, "should process after stop lifts");
+    assert.ok(consumer.getStats().escalated >= 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Stale claim recovery on tick
+// ---------------------------------------------------------------------------
+
+test("consumer recovers stale claims on its periodic sweep", async () => {
+  const root = await makeAgentRoot();
+  // Plant a stale claim directly.
+  const paths = getBusPaths(root);
+  mkdirSync(paths.claimed, { recursive: true });
+  const stalePath = join(paths.claimed, "evt-stale.json");
+  writeFileSync(stalePath, JSON.stringify({
+    id: "evt-stale", cadence: "cadence-bus-heartbeat",
+    source: "manual", ts: "2026-01-01T00:00:00.000Z",
+    workflow: null, correlation_id: null, priority: "normal",
+    metadata: {}, attempts: 1, type: "cadence_tick",
+  }));
+  const oldMs = Date.now() - 60 * 60 * 1000; // 1h old
+  await fsp.utimes(stalePath, new Date(oldMs), new Date(oldMs));
+
+  const consumer = startConsumer({
+    agentRoot: root, pollMs: 50,
+    spawnSession: async () => ({ ok: true, exit_code: 0 }),
+  });
+  try {
+    // tickOnce manually so we don't depend on the periodic recovery timer.
+    await consumer.tickOnce();
+    const ok = await waitFor(() => consumer.getStats().inline >= 1, { timeoutMs: 5_000 });
+    assert.ok(ok, "stale claim should be recovered and processed");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Audit L6 — a known-active claim must NOT be swept by stale recovery, while a
+// genuinely stale (crashed-handler) claim IS recovered.
+// ---------------------------------------------------------------------------
+
+/** Plant a claimed/<id>.json with a given mtime (ms). */
+async function plantClaim(paths, id, ageMs) {
+  mkdirSync(paths.claimed, { recursive: true });
+  const p = join(paths.claimed, `${id}.json`);
+  writeFileSync(p, JSON.stringify({
+    id, cadence: "weekly-strategic-memo",
+    source: "manual", ts: "2026-01-01T00:00:00.000Z",
+    workflow: null, correlation_id: null, priority: "normal",
+    metadata: {}, attempts: 1, type: "cadence_tick",
+  }));
+  const when = new Date(Date.now() - ageMs);
+  await fsp.utimes(p, when, when);
+  return p;
+}
+
+test("L6: an in-flight claim is kept fresh and not recovered, but a stale crashed claim is", async () => {
+  const root = await makeAgentRoot();
+  const paths = getBusPaths(root);
+
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 60_000,        // don't let the poll loop drain/recover on its own
+    heartbeatMs: 60_000,
+    recoveryMs: 60_000,
+    spawnSession: async () => ({ ok: true, exit_code: 0 }),
+  });
+  try {
+    // Plant the claims AFTER startConsumer: startConsumer runs an initial
+    // recoverStaleClaimsGuarded() at construction time, and at that point no id
+    // is marked in-flight — so a pre-planted aged claim would be swept before
+    // the test could mark it. Plant + mark here, then drive recovery manually.
+    //
+    // ACTIVE: a claim the consumer knows is in-flight (long-running escalate).
+    // Its mtime is old enough to look stale to the mtime fallback alone.
+    const activePath = await plantClaim(paths, "evt-active", 60 * 60 * 1000); // 1h old
+    // STALE: a genuinely crashed handler — old mtime, NOT in the in-flight set.
+    await plantClaim(paths, "evt-stale", 60 * 60 * 1000); // 1h old
+
+    // Mark evt-active as in-flight, exactly as escalate() would.
+    consumer._markInFlight("evt-active");
+
+    const activeMtimeBefore = statSync(activePath).mtimeMs;
+
+    // Run the guarded recovery directly (deterministic; no real spawn).
+    const out = consumer._recoverStaleClaimsGuarded();
+
+    // The active claim must have had its mtime bumped to ~now (kept fresh) and
+    // must still be present in claimed/.
+    const activeMtimeAfter = statSync(activePath).mtimeMs;
+    assert.ok(
+      activeMtimeAfter > activeMtimeBefore,
+      `active claim mtime should be refreshed (before ${activeMtimeBefore}, after ${activeMtimeAfter})`,
+    );
+    const claimedNow = listClaimed(root);
+    assert.ok(claimedNow.includes("evt-active"), "in-flight claim must survive recovery");
+
+    // The genuinely stale claim must have been recovered (removed from claimed/).
+    assert.ok(!claimedNow.includes("evt-stale"), "crashed-handler claim must be recovered");
+    assert.ok(out.scanned >= 1, `recovery should have scanned claims; out=${JSON.stringify(out)}`);
+
+    // Once it's no longer in-flight, the previously-active claim becomes
+    // eligible again: backdate its mtime and recover.
+    consumer._clearInFlight("evt-active");
+    const old = new Date(Date.now() - 60 * 60 * 1000);
+    await fsp.utimes(activePath, old, old);
+    consumer._recoverStaleClaimsGuarded();
+    assert.ok(!listClaimed(root).includes("evt-active"), "claim recovers after it stops being in-flight");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Health
+// ---------------------------------------------------------------------------
+
+test("consumer writes a heartbeat to state/cadence-bus/health.json", async () => {
+  const root = await makeAgentRoot();
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 100,
+    heartbeatMs: 50, // force frequent heartbeats so the test doesn't drag
+    spawnSession: async () => ({ ok: true, exit_code: 0 }),
+  });
+  try {
+    const ok = await waitFor(async () => {
+      try {
+        const raw = await fsp.readFile(join(root, "state/cadence-bus/health.json"), "utf-8");
+        const h = JSON.parse(raw);
+        return typeof h.ts === "string" && h.version;
+      } catch { return false; }
+    });
+    assert.ok(ok, "health.json must be written");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Sub-session policy boundary
+// ---------------------------------------------------------------------------
+
+test("explicit reason is attached to event metadata before escalation", async () => {
+  // The consumer must surface WHY a sub-session was spawned. For guarded
+  // cadences this comes from the guard's reason/result. For unknown
+  // cadences with prompts, the registry policy log line is sufficient,
+  // but for audit visibility we attach guard data to event.metadata.
+  const root = await makeAgentRoot();
+  // Force a guard:escalate outcome via inbox-processor with pending items.
+  // Default behaviour is now inline (reactive daemon owns inbox), so
+  // override with INBOX_CADENCE_ESCALATE=1.
+  mkdirSync(join(root, "state/inbox/internal"), { recursive: true });
+  writeFileSync(join(root, "state/inbox/internal/x.json"), "{}");
+  plantPrompt(root, "inbox-processor");
+  const prevEnv = process.env.INBOX_CADENCE_ESCALATE;
+  process.env.INBOX_CADENCE_ESCALATE = "1";
+  const seen = [];
+  const consumer = startConsumer({
+    agentRoot: root, pollMs: 50,
+    spawnSession: async (opts) => { seen.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => seen.length > 0);
+    assert.ok(ok);
+    // The event archive should record guard_result so future audits can
+    // trace why the sub-session ran.
+    const procDir = join(root, "state/cadence-bus/processed");
+    // Drill down by date
+    const dates = (await fsp.readdir(procDir)).filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n));
+    assert.ok(dates.length >= 1);
+    const files = await fsp.readdir(join(procDir, dates[0]));
+    const archive = JSON.parse(await fsp.readFile(join(procDir, dates[0], files[0]), "utf-8"));
+    assert.equal(archive.result.decision, "escalated");
+    // The consumer attaches the guard's outcome to the event metadata so
+    // audits can trace exactly why a sub-session ran. We expect either a
+    // recorded reason string or the full guard object.
+    assert.ok(
+      archive.metadata && (archive.metadata.reason || archive.metadata.guard),
+      `expected metadata.reason or metadata.guard; got ${JSON.stringify(archive.metadata)}`,
+    );
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+    if (prevEnv === undefined) delete process.env.INBOX_CADENCE_ESCALATE;
+    else process.env.INBOX_CADENCE_ESCALATE = prevEnv;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 0.3 — cost telemetry: parse REAL token usage from a --output-format json run
+// so the ledger stops recording $0 forever (recovery C1). parseUsageFromStdout
+// reads the run's captured stdout file; on a parse failure it returns
+// { ok:false, reason } so the caller records a marker rather than fake zeros.
+// ---------------------------------------------------------------------------
+
+test("parseUsageFromStdout: reads real usage + total_cost_usd from a JSON result file", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const p = join(root, "out.json");
+    writeFileSync(p, JSON.stringify({
+      result: "tick done",
+      usage: { input_tokens: 3100, output_tokens: 740, cache_read_input_tokens: 500 },
+      total_cost_usd: 0.022,
+      model: "claude-sonnet-4-6",
+    }));
+    const u = parseUsageFromStdout(p);
+    assert.equal(u.ok, true);
+    assert.equal(u.inputTokens, 3100);
+    assert.equal(u.outputTokens, 740);
+    assert.equal(u.cacheReadTokens, 500);
+    assert.equal(u.totalCostUsd, 0.022);
+    assert.equal(u.model, "sonnet");
+  } finally { await rmRoot(root); }
+});
+
+test("parseUsageFromStdout: tolerates a banner before the JSON tail", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const p = join(root, "out.json");
+    writeFileSync(p, `Some launchd banner line\n${JSON.stringify({ usage: { input_tokens: 10, output_tokens: 5 } })}`);
+    const u = parseUsageFromStdout(p);
+    assert.equal(u.ok, true);
+    assert.equal(u.inputTokens, 10);
+    assert.equal(u.outputTokens, 5);
+  } finally { await rmRoot(root); }
+});
+
+test("parseUsageFromStdout: failure modes return ok:false with a reason (never fabricated zeros)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const empty = join(root, "empty.json");
+    writeFileSync(empty, "");
+    assert.equal(parseUsageFromStdout(empty).reason, "empty-stdout");
+
+    const plain = join(root, "plain.txt");
+    writeFileSync(plain, "this is a plain-text reply, not json");
+    assert.equal(parseUsageFromStdout(plain).ok, false);
+
+    const noUsage = join(root, "nousage.json");
+    writeFileSync(noUsage, JSON.stringify({ result: "x" }));
+    assert.equal(parseUsageFromStdout(noUsage).reason, "no-usage-field");
+
+    // A missing file does not throw — it reports a read failure.
+    assert.equal(parseUsageFromStdout(join(root, "does-not-exist.json")).ok, false);
+  } finally { await rmRoot(root); }
+});
+
+test("0.3: realSpawnSession argv requests --output-format json and records real usage end-to-end", async () => {
+  // Drive the REAL (non-injected) spawner against a fake `claude` shim that
+  // (a) echoes its argv to a side file so we can assert the spawn shape, and
+  // (b) prints a --output-format json result so the cost ledger gets REAL
+  // tokens. lib/claude-bin.mjs memoizes the resolved binary per process, so we
+  // run the whole thing in a FRESH child process via `node -e` with CLAUDE_BIN
+  // pointed at the shim (claude-bin's safety check requires an owner-only,
+  // non-writable executable, which our shim satisfies).
+  const { spawnSync } = await import("node:child_process");
+  const root = await makeAgentRoot();
+  try {
+    plantPrompt(root, "weekly-strategic-memo");
+    // A copy of the real tracker so the detached `record` call appends a row.
+    mkdirSync(join(root, "scripts/cost"), { recursive: true });
+    await fsp.copyFile(
+      new URL("../cost/track-claude-usage.mjs", import.meta.url),
+      join(root, "scripts/cost/track-claude-usage.mjs")
+    );
+
+    const argvFile = join(root, "shim-argv.txt");
+    const shim = join(root, "claude-shim");
+    // The shim writes its argv, then prints a JSON usage object on stdout.
+    writeFileSync(shim, [
+      "#!/usr/bin/env node",
+      `const fs=require("fs");`,
+      `fs.writeFileSync(${JSON.stringify(argvFile)}, JSON.stringify(process.argv.slice(2)));`,
+      `process.stdout.write(JSON.stringify({ result: "ok", usage: { input_tokens: 1234, output_tokens: 99 }, total_cost_usd: 0.005, model: "claude-sonnet-4-6" }));`,
+      "",
+    ].join("\n"));
+    await fsp.chmod(shim, 0o755);
+
+    const driver = `
+      import { startConsumer } from ${JSON.stringify(new URL("./cadence-consumer.mjs", import.meta.url).href)};
+      import { enqueueTick } from ${JSON.stringify(new URL("../../lib/cadence-bus.mjs", import.meta.url).href)};
+      const root = ${JSON.stringify(root)};
+      const c = startConsumer({ agentRoot: root, pollMs: 30,
+        governor: { admit: () => ({ decision: "ADMIT" }), defaultDeps: () => ({}) },
+        rateGuard: { checkRateLimit: () => ({ allowed: true }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} },
+        budgetGuard: { dailyStatus: () => ({ essentialOnly: false }) } });
+      enqueueTick({ cadence: "weekly-strategic-memo", source: "test", agentRoot: root });
+      const deadline = Date.now() + 8000;
+      while (Date.now() < deadline && c.getStats().escalated < 1) { await new Promise(r => setTimeout(r, 30)); }
+      await c.stop();
+      process.exit(0);
+    `;
+    const res = spawnSync(process.execPath, ["--input-type=module", "-e", driver], {
+      env: { ...process.env, CLAUDE_BIN: shim, AGENT_ROOT: root, MAESTRO_PREFER_SUBSCRIPTION_AUTH: "1" },
+      timeout: 20_000,
+      encoding: "utf-8",
+    });
+
+    // The spawn argv must request JSON output (so usage is capturable).
+    const argv = JSON.parse(await fsp.readFile(argvFile, "utf-8"));
+    assert.ok(argv.includes("--print"), `argv should include --print: ${res.stderr}`);
+    const ofIdx = argv.indexOf("--output-format");
+    assert.ok(ofIdx >= 0, "argv should request --output-format");
+    assert.equal(argv[ofIdx + 1], "json");
+
+    // And the ledger should carry the shim's REAL token counts (not 0).
+    const date = new Date().toISOString().slice(0, 10);
+    const ledger = join(root, "state/cost-tracking", `${date}.jsonl`);
+    let body = "";
+    for (let i = 0; i < 80 && !body.trim(); i++) {
+      try { body = await fsp.readFile(ledger, "utf-8"); } catch { /* */ }
+      if (!body.trim()) await new Promise((r) => setTimeout(r, 25));
+    }
+    assert.ok(body.trim(), `expected a cost row in the ledger; driver stderr: ${res.stderr}`);
+    const row = JSON.parse(body.trim().split("\n").pop());
+    assert.equal(row.source, "cadence-consumer");
+    assert.equal(row.input_tokens, 1234, "REAL input tokens (not 0)");
+    assert.equal(row.output_tokens, 99, "REAL output tokens (not 0)");
+    assert.ok(row.estimated_usd > 0, `estimated_usd should be nonzero, got ${row.estimated_usd}`);
+  } finally {
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3-4 COVERAGE — routeCadenceSpawn drives the cadence sub-session model
+// through resolveChain when the agent opts into a `schema_version: 2` config.
+// No config / a v1 config returns null (stock-CLI cadence spawn, unchanged).
+// ---------------------------------------------------------------------------
+
+/** Write a v2 routing config (JSON, no js-yaml needed) into an agent root. */
+function writeV2CadenceConfig(root) {
+  mkdirSync(join(root, "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(root, "config/model-routing.json"), JSON.stringify(cfg, null, 2));
+}
+
+test("COVERAGE: routeCadenceSpawn returns null with no routing config (stock-CLI cadence spawn)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    assert.equal(routeCadenceSpawn(root, "weekly-strategic-memo"), null);
+  } finally { await rmRoot(root); }
+});
+
+test("COVERAGE: routeCadenceSpawn resolves a v2 cadence to a catalog model + knobs + decision_id", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeV2CadenceConfig(root);
+    const t = routeCadenceSpawn(root, "weekly-strategic-memo");
+    assert.ok(t, "v2 config produces a routing target");
+    assert.equal(t.backend, "anthropic", "default rule resolves to the Anthropic session backend");
+    assert.equal(t.modelFlag, "claude-sonnet-4-6", "routed to the v2 default (Sonnet) catalog id");
+    assert.ok(typeof t.decisionId === "string" && t.decisionId.length > 0, "carries a decision_id");
+    assert.ok(Number.isFinite(Number(t.maxTurns)) && Number(t.maxTurns) > 0, "carries a maxTurns knob");
+    // An Anthropic session is not a third-party retarget → no BASE_URL injected.
+    assert.ok(!(t.envForSpawn && t.envForSpawn.ANTHROPIC_BASE_URL), "Anthropic session keeps stock keychain auth");
+  } finally { await rmRoot(root); }
+});
+
+test("COVERAGE: routeCadenceSpawn honours MAESTRO_ROUTER_FORCE_ANTHROPIC (kill switch)", async () => {
+  const prev = process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC;
+  process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC = "1";
+  const root = await makeAgentRoot();
+  try {
+    writeV2CadenceConfig(root);
+    const t = routeCadenceSpawn(root, "weekly-strategic-memo");
+    // Kill switch → an Anthropic-only decision; still a usable target, never a
+    // third-party retarget.
+    assert.ok(t, "kill switch still yields an Anthropic target");
+    assert.equal(t.backend, "anthropic");
+    assert.ok(!(t.envForSpawn && t.envForSpawn.ANTHROPIC_BASE_URL), "no third-party retarget under the kill switch");
+  } finally {
+    if (prev === undefined) delete process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC; else process.env.MAESTRO_ROUTER_FORCE_ANTHROPIC = prev;
+    await rmRoot(root);
+  }
+});