@cohortapp/agent-sdk 2.17.0 → 2.18.4

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

@@ -1,776 +0,0 @@
-/**
- * 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")
-    );
-    // ...and the shared billing contract it imports relative to itself.
-    mkdirSync(join(root, "lib/cost"), { recursive: true });
-    await fsp.copyFile(
-      new URL("../../lib/cost/ledger-row.mjs", import.meta.url),
-      join(root, "lib/cost/ledger-row.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);
-  }
-});