@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/cadence-consumer.mjs

@@ -0,0 +1,1080 @@
+/**
+ * Maestro — Cadence Consumer
+ *
+ * The persistent main session's drain loop for the cadence bus.
+ *
+ * Lifecycle: launched once per agent process (inside maestro-daemon.mjs).
+ * On every tick it:
+ *
+ *   1. Recovers any stale claims (events whose handler crashed mid-flight).
+ *   2. Drains inbox/, atomically claiming each event.
+ *   3. Routes the event through cadence-handlers.mjs:
+ *        - inline   → run handler in-process, complete.
+ *        - guarded  → run cheap pre-check; if "no work", complete inline,
+ *                     else escalate to a sub-session.
+ *        - escalate → spawn a sub-session running the cadence's trigger
+ *                     prompt under schedules/triggers/<name>.md.
+ *      Unknown cadences with a prompt on disk default to escalate; without
+ *      a prompt they go straight to dlq with a clear error.
+ *   4. Respects .emergency-stop: while present, the loop logs a heartbeat
+ *      but never spawns a sub-session and never processes events. Existing
+ *      claims remain on disk so they can be resumed once the stop is lifted.
+ *   5. Writes a heartbeat to state/cadence-bus/health.json on every cycle
+ *      so doctor / healthcheck can confirm liveness.
+ *
+ * The consumer never spawns more than ONE sub-session at a time on its own.
+ * That bound exists because the parent process is the single owner of
+ * cadence housekeeping; if your workflow needs higher parallelism, lean on
+ * the existing daemon dispatcher (which is purpose-built for inbox items),
+ * not on multiplying cadence consumers.
+ *
+ * Public API:
+ *   startConsumer(opts) → { stop(), getStats(), tickOnce() }
+ *
+ * Options:
+ *   agentRoot      override AGENT_ROOT (tests).
+ *   pollMs         drain interval (default 2_000).
+ *   heartbeatMs    health.json refresh interval (default 15_000).
+ *   recoveryMs     stale-claim sweep interval (default 5 * 60_000).
+ *   spawnSession   injected spawner for tests; defaults to a real
+ *                  `claude --print <permission-args> <prompt>` child_process
+ *                  .spawn. <permission-args> comes from
+ *                  lib/session-permissions.mjs#sessionPermissionArgs and is
+ *                  `--dangerously-skip-permissions` by default, or a scoped
+ *                  per-cadence `--allowedTools <list>` when the operator sets
+ *                  MAESTRO_SCOPED_PERMISSIONS=1 (audit H1).
+ *   maxSpawnMs     hard timeout per sub-session (default 30 * 60_000).
+ *   logger         optional fn({ ts, level, …rest }) → void for tests.
+ *   now            injectable clock fn() → ms (tests); used when re-stamping
+ *                  in-flight claim mtimes so the stale-claim sweep can't sweep
+ *                  a live escalate (audit L6).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, openSync, closeSync, statSync, unlinkSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+
+import {
+  ensureBusDirs,
+  claimNextTick,
+  completeTick,
+  failTick,
+  requeueTick,
+  recoverStaleClaims,
+  sweepRetention,
+  writeHealth,
+  getBusPaths,
+  logBusEvent,
+  busDepth,
+} from "../../lib/cadence-bus.mjs";
+import { resolveClaudeBin as sharedResolveClaude, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+import { getCadenceDef } from "./cadence-handlers.mjs";
+import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
+import { renderTemplate, buildContext } from "../../lib/render.mjs";
+// Model router (opt-in). A `schema_version: 2` config routes each cadence
+// sub-session's model through resolveChain (SPEC §6.2): the RouteDecision
+// supplies the --model flag, the session-retarget env (third-party backends),
+// the spawn knobs (--max-turns / --effort / --agents Haiku-Explore map), and a
+// decision_id for the ledger/audit join. Deferrable cadences route on the BATCH
+// lane (-50%) before the budget ladder degrades the chain. No config / v1 config
+// / any router error → the historical stock-CLI cadence spawn, unchanged.
+import {
+  loadRoutingConfig,
+  resolveChain,
+} from "../../lib/model-router.mjs";
+import { buildChildEnv } from "../../lib/model-router/spawn.mjs";
+import { budgetLadder, batchLaneFor, spawnKnobsFor } from "../../lib/model-router/economics.mjs";
+import * as budgetGuardForBand from "../../lib/budget-guard.mjs";
+// WS4 — the consumer is one of the spawn sources, so it honours the SAME
+// resource governor + shared 429 breaker + daily-budget essential-only mode as
+// the dispatcher. A non-ADMIT decision REQUEUES the tick (decision:"deferred")
+// WITHOUT calling failTick — a governor/rate deferral is an upstream gate, not
+// a per-event failure, so it must never burn the event's retry budget.
+import * as resourceGovernor from "../../lib/resource-governor.mjs";
+import * as rateGuardModule from "../../lib/rate-guard.mjs";
+import * as budgetGuardModule from "../../lib/budget-guard.mjs";
+
+const RATE_PROVIDER = process.env.MAESTRO_RATE_PROVIDER || "anthropic";
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_POLL_MS = 2_000;
+const DEFAULT_HEARTBEAT_MS = 15_000;
+const DEFAULT_RECOVERY_MS = 5 * 60_000;
+const DEFAULT_SPAWN_TIMEOUT_MS = 30 * 60_000;
+
+// Concurrency: at most one sub-session at a time per cadence consumer.
+// Cadence events are not realtime — queueing one tick behind another is
+// preferable to thrashing Claude / hitting usage limits.
+const MAX_CONCURRENT_SUB_SESSIONS = 1;
+
+// Retry policy. Most cadence failures are systemic (broken prompt, bad
+// auth, transient API errors) — 5 retries doesn't help, it just amplifies
+// the burn. 2 retries with exponential back-off is the right balance.
+const DEFAULT_MAX_ATTEMPTS = 2;
+const BACKOFF_SCHEDULE_MS = [0, 30_000, 120_000]; // 1st retry +30s, 2nd retry +2m
+
+// Circuit breaker — when 3 same-cadence failures land in a row, stop
+// spawning that cadence for 30 minutes. Prevents launchd-rate runaway.
+const CIRCUIT_OPEN_THRESHOLD = 3;
+const CIRCUIT_OPEN_DURATION_MS = 30 * 60_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isEmergencyStop(paths) {
+  return existsSync(paths.emergencyStop);
+}
+
+function defaultLogger(entry) {
+  // The default logger ALSO writes to logs/cadence-bus/<date>.jsonl via
+  // logBusEvent, but mirrors important events to stderr so launchd's
+  // StandardErrorPath captures them.
+  if (entry.level === "error" || entry.level === "warn") {
+    try { process.stderr.write(`[cadence-consumer] ${JSON.stringify(entry)}\n`); }
+    catch { /* ignore */ }
+  }
+}
+
+// Claude binary resolution moved to lib/claude-bin.mjs (shared by
+// dispatcher, responder, and this consumer). See that file for the
+// candidate search order.
+const resolveClaudeBin = sharedResolveClaude;
+
+/**
+ * Parse the `claude --print --output-format json` result object from a captured
+ * stdout file to recover the run's REAL token usage + authoritative cost
+ * (recovery C1). The CLI emits a single JSON object:
+ *   { result, usage: { input_tokens, output_tokens, cache_read_input_tokens, ... },
+ *     total_cost_usd, ... }
+ * Some CLI versions wrap it differently or prepend a banner, so we read the file
+ * and JSON.parse the LAST balanced top-level object (the JSON tail is the
+ * result). Returns { ok, inputTokens, outputTokens, cacheReadTokens?,
+ * totalCostUsd?, model? } on success, or { ok:false, reason } so the caller can
+ * record a parse-failure marker instead of fabricating zeros.
+ *
+ * @param {string} stdoutPath
+ * @returns {{ok:true,inputTokens:number,outputTokens:number,cacheReadTokens?:number,totalCostUsd?:number,model?:string}|{ok:false,reason:string}}
+ */
+export function parseUsageFromStdout(stdoutPath) {
+  let raw;
+  try { raw = readFileSync(stdoutPath, "utf-8"); }
+  catch (err) { return { ok: false, reason: `read-failed: ${err.message}` }; }
+  const trimmed = (raw || "").trim();
+  if (!trimmed) return { ok: false, reason: "empty-stdout" };
+
+  let obj = null;
+  // Fast path: the whole file is the JSON object.
+  try { obj = JSON.parse(trimmed); }
+  catch {
+    // Tolerant path: a leading banner / log line can precede the JSON tail. The
+    // CLI's result object is the FIRST balanced top-level object, so slice from
+    // the first "{" to the last "}". (lastIndexOf("{") would grab a nested
+    // object's opening brace and break the parse.)
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start !== -1 && end !== -1 && end > start) {
+      try { obj = JSON.parse(trimmed.slice(start, end + 1)); }
+      catch { obj = null; }
+    }
+  }
+  if (!obj || typeof obj !== "object") return { ok: false, reason: "no-json-object" };
+
+  const usage = obj.usage && typeof obj.usage === "object" ? obj.usage : null;
+  if (!usage) return { ok: false, reason: "no-usage-field" };
+
+  const inputTokens = Number(usage.input_tokens);
+  const outputTokens = Number(usage.output_tokens);
+  if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens)) {
+    return { ok: false, reason: "non-numeric-tokens" };
+  }
+
+  const out = { ok: true, inputTokens, outputTokens };
+  const cacheRead = Number(usage.cache_read_input_tokens);
+  if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
+  const totalCost = Number(obj.total_cost_usd);
+  if (Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
+  // The CLI may report the resolved model (e.g. "claude-sonnet-4-6"); map it to
+  // the tracker's coarse class so pricing lookup stays correct.
+  if (typeof obj.model === "string" && obj.model) {
+    out.model = /opus/i.test(obj.model) ? "opus" : /haiku/i.test(obj.model) ? "haiku" : "sonnet";
+  }
+  return out;
+}
+
+// Lazy + cached routing config per agentRoot (invalidated only on process
+// restart, matching the dispatcher). A misconfigured YAML doesn't break cadence
+// spawns — we fall back to the stock-CLI path.
+const _cadenceRoutingCache = new Map(); // agentRoot -> config | null
+function getCadenceRoutingConfig(agentRoot) {
+  if (_cadenceRoutingCache.has(agentRoot)) return _cadenceRoutingCache.get(agentRoot);
+  let cfg = null;
+  try {
+    cfg = loadRoutingConfig(agentRoot) || null;
+  } catch (err) {
+    process.stderr.write(`[cadence-consumer] model-router config invalid, using stock CLI: ${err.message}\n`);
+    cfg = null;
+  }
+  _cadenceRoutingCache.set(agentRoot, cfg);
+  return cfg;
+}
+
+/**
+ * Route a cadence sub-session's model through the v2 router. Returns a normalised
+ * target { modelFlag, envForSpawn, decisionId, backend, model, transport,
+ * maxTurns, effort, agentsJson, explain } or null when there's nothing to route
+ * (no config, v1 config, kill switch, or any router error) — the caller then
+ * keeps the historical stock-CLI cadence spawn (no --model, keychain OAuth).
+ *
+ * NEVER throws. Deferrable cadences (digests, learning, rollups) route on the
+ * BATCH lane; the budget band (from budget-guard) degrades the chain per §6.4.
+ *
+ * Exported as a test seam (and for doctor/introspection); the spawn path is the
+ * only production caller.
+ */
+export function routeCadenceSpawn(agentRoot, cadence) {
+  const cfg = getCadenceRoutingConfig(agentRoot);
+  if (!cfg || cfg.schema_version !== 2) return null;
+  try {
+    const taskClass = `cadence.${cadence}`;
+    let band = 0;
+    try {
+      const st = budgetGuardForBand.dailyStatus({ agentRoot });
+      band = budgetLadder(st.spentUSD, st.capUSD).band;
+    } catch { /* band 0 on read failure */ }
+    const req = {
+      agent_role: "cadence",
+      source: "cadence",
+      priority: "normal",
+      task_class: taskClass,
+      // Cadence work runs over internal queues / repo state, not live inbound
+      // user DMs — internal data class (SPEC §7.6). Deferrable → batch lane.
+      data_class: "internal",
+      lane: batchLaneFor({ task_class: taskClass, priority: "normal" }) ? "batch" : "realtime",
+      budget_band: band,
+      harness_hint: "session",
+    };
+    const decision = resolveChain(req, { config: cfg, agentRoot });
+    if (!decision || !decision.chosen) return null;
+    const knobs = spawnKnobsFor(taskClass);
+    const sa = decision.spawnArgs || {};
+    return {
+      modelFlag: sa.modelFlag || decision.chosen.model || null,
+      envForSpawn: decision.envForSpawn || {},
+      decisionId: decision.decision_id || null,
+      backend: decision.chosen.provider || null,
+      model: decision.chosen.model || null,
+      transport: decision.chosen.transport || null,
+      maxTurns: sa.maxTurns != null ? sa.maxTurns : knobs.maxTurns,
+      effort: sa.effort != null ? sa.effort : knobs.effort,
+      agentsJson: sa.agentsJson != null ? sa.agentsJson : knobs.agentsJson,
+      explain: decision.explain || null,
+      lane: decision.lane || req.lane,
+    };
+  } catch (err) {
+    process.stderr.write(`[cadence-consumer] resolveChain failed for ${cadence}, using stock CLI: ${err.message}\n`);
+    return null;
+  }
+}
+
+/**
+ * Spawn a sub-session running the cadence's trigger prompt and resolve
+ * with { exit_code, durationMs, stderr_tail }. Reads the prompt at call
+ * time so the latest version (possibly upgraded between ticks) is always
+ * used.
+ *
+ * Robustness: stdout + stderr are tee'd to logs/cadence-bus/subsessions/
+ * so non-zero exits remain diagnosable after the fact. The last ~4 KB of
+ * stderr is also captured in-memory and surfaced on the failure event.
+ */
+function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
+  return new Promise((resolveOut) => {
+    const fullPrompt = join(agentRoot, promptPath);
+    if (!existsSync(fullPrompt)) {
+      resolveOut({ ok: false, exit_code: -2, error: `prompt not found: ${promptPath}` });
+      return;
+    }
+    let body;
+    try { body = readFileSync(fullPrompt, "utf-8"); }
+    catch (err) {
+      resolveOut({ ok: false, exit_code: -3, error: `prompt read failed: ${err.message}` });
+      return;
+    }
+
+    // Render {{agent.*}} / {{company.*}} identity tokens at spawn time so framework
+    // triggers stay generic in the package and resolve to THIS agent + company
+    // (see lib/render.mjs). Synchronous, from config/agent.json + config/company.json.
+    // No-op on token-free text, so this is behaviour-preserving for any not-yet-
+    // tokenised trigger.
+    try {
+      const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
+      let companyCfg = {};
+      try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
+      body = renderTemplate(body, buildContext(agentCfg, null, companyCfg));
+    } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+
+    const bin = resolveClaudeBin();
+    // Permission scoping (audit H1). sessionPermissionArgs() defaults to the
+    // historical "--dangerously-skip-permissions" unless the operator opts in
+    // with MAESTRO_SCOPED_PERMISSIONS=1, in which case it returns a per-cadence
+    // "--allowedTools <list>" form. daemonClaudeArgs() (--strict-mcp-config /
+    // --bare) is still appended separately so it applies in both modes.
+    const permissionArgs = sessionPermissionArgs({ cadence, mode: getCadenceDef(cadence)?.mode });
+
+    // Route the cadence sub-session's model through the v2 router (opt-in). When
+    // a backend is chosen we pass its --model flag + spawn knobs; otherwise the
+    // argv stays exactly as before (no --model → stock CLI default model).
+    const target = routeCadenceSpawn(agentRoot, cadence);
+    const routedArgs = [];
+    if (target) {
+      if (target.maxTurns != null && Number.isFinite(Number(target.maxTurns))) {
+        routedArgs.push("--max-turns", String(target.maxTurns));
+      }
+      if (target.effort) routedArgs.push("--effort", String(target.effort));
+      if (target.agentsJson) {
+        routedArgs.push("--agents", typeof target.agentsJson === "string" ? target.agentsJson : JSON.stringify(target.agentsJson));
+      }
+      if (target.modelFlag) routedArgs.push("--model", String(target.modelFlag));
+      log({ level: "info", stage: "cadence_routed", cadence, decision_id: target.decisionId, backend: target.backend, model: target.model, transport: target.transport, lane: target.lane, explain: target.explain });
+    }
+
+    // --output-format json makes stdout a single JSON object carrying the real
+    // token usage (and total_cost_usd) for this run. The cadence sub-session's
+    // stdout is redirected to stdoutPath (below) and nothing parses it for
+    // CONTENT — only this function reads it back, to record a TRUTHFUL cost row
+    // (recovery C1). Without this the ledger logged input/output tokens 0 → the
+    // fleet's only spend control summed $0 forever.
+    // The cadence PROMPT (body) stays the LAST positional arg; routed model +
+    // knob flags slot before it (after the daemon args), mirroring the dispatcher.
+    const args = ["--print", "--output-format", "json", ...permissionArgs, ...daemonClaudeArgs(), ...routedArgs, body];
+    // PATH augmented via lib/claude-bin.mjs so subsession can find jq/node.
+    let env = {
+      ...process.env,
+      AGENT_ROOT: agentRoot,
+      AGENT_DIR: agentRoot,
+      PATH: augmentedPath(),
+    };
+    // v2 third-party retarget: build the child env through the execution layer's
+    // §7.3 allowlist scrub so no foreign credential leaks into the third-party
+    // session (buildChildEnv injects ANTHROPIC_API_KEY="" for a retarget). We
+    // preserve the cadence-specific env (AGENT_ROOT/AGENT_DIR/PATH) on top.
+    const retargeting = !!(target && target.envForSpawn && target.envForSpawn.ANTHROPIC_BASE_URL);
+    if (retargeting) {
+      env = {
+        ...buildChildEnv(env, target.envForSpawn),
+        AGENT_ROOT: agentRoot,
+        AGENT_DIR: agentRoot,
+        PATH: augmentedPath(),
+      };
+    } else {
+      // Auth handling. Claude Code authenticates via macOS Keychain
+      // (OAuth from the user's Pro/Max subscription) when no API key is
+      // set, OR via the ANTHROPIC_API_KEY env var when one is present.
+      // If the env key is present BUT looks like a placeholder / empty
+      // string, we strip it so claude can fall back to Keychain OAuth.
+      // Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to always strip
+      // the API key (force subscription auth) — useful when the agent
+      // owns a Claude Code Pro/Max subscription and shouldn't burn API
+      // credits for routine ticks.
+      const preferSubscription = process.env.MAESTRO_PREFER_SUBSCRIPTION_AUTH === "1";
+      const apiKey = env.ANTHROPIC_API_KEY || "";
+      if (preferSubscription || !apiKey.trim() || /^(your-api-key|placeholder|xxx+|sk-ant-xxx)/i.test(apiKey)) {
+        delete env.ANTHROPIC_API_KEY;
+      }
+    }
+    const started = Date.now();
+
+    // Per-run log file. Pattern is short enough to be tail-friendly.
+    const logsDir = join(agentRoot, "logs", "cadence-bus", "subsessions");
+    mkdirSync(logsDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const stdoutPath = join(logsDir, `${date}-${cadence}-${stamp}.stdout.log`);
+    const stderrPath = join(logsDir, `${date}-${cadence}-${stamp}.stderr.log`);
+    const stdoutFd = openSync(stdoutPath, "a");
+    const stderrFd = openSync(stderrPath, "a");
+
+    log({ level: "info", stage: "subsession_spawn", cadence, bin, stdout: stdoutPath, stderr: stderrPath });
+
+    let child;
+    try {
+      // stdio:
+      //   0 ignore  (claude --print reads prompt from argv, not stdin)
+      //   1 → file  (capture stdout for later inspection)
+      //   2 → file  (capture stderr — critical for diagnosing exit-1)
+      child = spawn(bin, args, { cwd: agentRoot, env, stdio: ["ignore", stdoutFd, stderrFd] });
+    } catch (err) {
+      try { closeSync(stdoutFd); closeSync(stderrFd); } catch { /* */ }
+      resolveOut({ ok: false, exit_code: -4, error: `spawn failed: ${err.message}` });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      log({ level: "warn", stage: "subsession_timeout", cadence, timeout_ms: timeoutMs });
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      // Give it a beat to die before SIGKILL.
+      setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* ignore */ } }, 5_000);
+    }, timeoutMs);
+
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      try { closeSync(stdoutFd); closeSync(stderrFd); } catch { /* */ }
+      const durationMs = Date.now() - started;
+      const exit_code = typeof code === "number" ? code : (signal ? -1 : -5);
+
+      // Pull tail of stderr (and stdout if stderr empty) for the failure
+      // surface. Best-effort; we never block on file size.
+      let stderrTail = "";
+      try {
+        const body = readFileSync(stderrPath, "utf-8");
+        stderrTail = body.slice(-4096);
+        if (!stderrTail.trim()) {
+          const so = readFileSync(stdoutPath, "utf-8");
+          stderrTail = so.slice(-4096);
+        }
+      } catch { /* file may not exist if spawn ENOENT before fd-redirect */ }
+
+      // Record a TRUTHFUL cost-ledger row (recovery C1). We parse the run's
+      // `--output-format json` object from stdoutPath to read the REAL token
+      // usage (and the CLI's authoritative total_cost_usd) and pass those to the
+      // tracker, which derives estimated_usd. If parsing fails we pass NO token
+      // flags (tracker records 0 then) and log a parse-failure marker — we never
+      // fabricate counts.
+      const usage = parseUsageFromStdout(stdoutPath);
+      try {
+        const trackerPath = join(agentRoot, "scripts/cost/track-claude-usage.mjs");
+        if (existsSync(trackerPath)) {
+          const trackerArgs = [
+            trackerPath, "record",
+            "--cadence", cadence,
+            "--source", "cadence-consumer",
+            // Prefer the CLI-reported resolved model class; else the routed
+            // model flag (v2); else the historical sonnet default.
+            "--model", usage.model || (target && target.model) || "sonnet",
+            "--duration-ms", String(durationMs),
+            "--exit", String(exit_code),
+          ];
+          // Carry the v2 RouteDecision id onto the ledger row (SPEC §4.7) so a
+          // cadence spend row joins its routing decision. Absent on stock-CLI.
+          if (target && target.decisionId) trackerArgs.push("--decision-id", String(target.decisionId));
+          if (usage.ok) {
+            trackerArgs.push("--input-tokens", String(usage.inputTokens));
+            trackerArgs.push("--output-tokens", String(usage.outputTokens));
+            if (usage.cacheReadTokens != null) trackerArgs.push("--cache-read-tokens", String(usage.cacheReadTokens));
+            if (usage.totalCostUsd != null) trackerArgs.push("--total-cost-usd", String(usage.totalCostUsd));
+          } else {
+            // Parse failure: do NOT pass fabricated zeros — omit token flags
+            // (tracker defaults them to 0) and surface the gap in the bus log so
+            // a systematic parse regression is visible rather than silently $0.
+            log({ level: "warn", stage: "cost_usage_parse_failed", cadence, reason: usage.reason, stdout: stdoutPath });
+          }
+          spawn(process.execPath, trackerArgs, { stdio: "ignore", env: { ...env, AGENT_ROOT: agentRoot } }).unref();
+        }
+      } catch { /* cost tracking is best-effort */ }
+
+      // Clean up empty log files so the directory doesn't accumulate
+      // hundreds of zero-byte successes.
+      try {
+
+        if (statSync(stdoutPath).size === 0) unlinkSync(stdoutPath);
+        if (statSync(stderrPath).size === 0) unlinkSync(stderrPath);
+      } catch { /* */ }
+
+      resolveOut({
+        ok: exit_code === 0,
+        exit_code,
+        signal: signal || null,
+        duration_ms: durationMs,
+        stderr_tail: stderrTail || null,
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      try { closeSync(stdoutFd); closeSync(stderrFd); } catch { /* */ }
+      const durationMs = Date.now() - started;
+      resolveOut({ ok: false, exit_code: -6, error: err.message, duration_ms: durationMs });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Start the consumer. Returns control handles (stop, getStats, tickOnce).
+ * Caller must `await stop()` to flush state on shutdown.
+ */
+export function startConsumer(opts = {}) {
+  const agentRoot = opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+  const paths = ensureBusDirs(agentRoot);
+
+  const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const recoveryMs = opts.recoveryMs ?? DEFAULT_RECOVERY_MS;
+  const maxSpawnMs = opts.maxSpawnMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
+  const spawnSession = opts.spawnSession || realSpawnSession;
+  const userLogger = opts.logger;
+  // Test / tuning hooks for the reliability layer.
+  const backoffSchedule = opts.backoffSchedule || BACKOFF_SCHEDULE_MS;
+  const circuitThreshold = opts.circuitThreshold ?? CIRCUIT_OPEN_THRESHOLD;
+  const circuitDurationMs = opts.circuitDurationMs ?? CIRCUIT_OPEN_DURATION_MS;
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  // WS4 governance modules (injectable for hermetic tests).
+  const governor = opts.governor || resourceGovernor;
+  const rateGuard = opts.rateGuard || rateGuardModule;
+  const budgetGuard = opts.budgetGuard || budgetGuardModule;
+
+  /**
+   * Admission gate for an escalation. Folds the shared 429 breaker + the
+   * resource governor (+ budget essential-only) into one decision. Fail-open:
+   * any throw → admit (Invariant: a governance bug must not wedge cadences).
+   * Returns { admit:boolean, reason }.
+   */
+  function governanceGate() {
+    try {
+      const rb = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot });
+      if (!rb.allowed) return { admit: false, reason: "rate-limited" };
+      let mode = null;
+      try { if (budgetGuard.dailyStatus({ agentRoot }).essentialOnly) mode = "essential-only"; }
+      catch { /* budget read best-effort */ }
+      const adm = governor.admit({ source: "cadence", mode }, governor.defaultDeps({ agentRoot }));
+      if (adm.decision !== "ADMIT") return { admit: false, reason: adm.reason || adm.decision };
+      return { admit: true };
+    } catch {
+      return { admit: true, reason: "governor-error-fail-open" };
+    }
+  }
+
+  const stats = {
+    started_at: new Date().toISOString(),
+    received: 0,
+    inline: 0,
+    escalated: 0,
+    skipped_emergency_stop: 0,
+    skipped_circuit_open: 0,
+    skipped_backoff: 0,
+    dlq: 0,
+    retries: 0,
+    spawn_failures: 0,
+    last_event_id: null,
+    last_decision: null,
+  };
+
+  let stopping = false;
+  let activeTick = null;
+  let timers = [];
+  let activeSubSessions = 0;
+
+  // Audit L6: stale-claim recovery in lib/cadence-bus.mjs is mtime-based and
+  // cannot distinguish a crashed handler from a slow-but-live one. A
+  // long-running escalate keeps its claim in claimed/ for the whole sub-session
+  // run (default cap 30m). recoverStaleClaims' default threshold is also 30m,
+  // so a sub-session that runs near the cap could have its claim swept while
+  // still executing — producing a SECOND sub-session for the same cadence tick.
+  //
+  // The consumer is the single owner of cadence escalation, so it knows
+  // exactly which claim ids are in-flight. We track them here and, immediately
+  // before every recovery sweep, re-stamp those files' mtimes to "now". That
+  // keeps a known-active claim out of the stale window without touching the
+  // mtime fallback that still recovers genuinely crashed handlers (whose ids
+  // are NOT in this set). We deliberately filter consumer-side rather than
+  // change recoverStaleClaims' signature (it lives in lib/cadence-bus.mjs,
+  // owned by another change-set).
+  const inFlightClaimIds = new Set();
+
+  // Injectable clock so tests can drive the stale window deterministically.
+  const nowMs = typeof opts.now === "function" ? opts.now : Date.now;
+
+  /**
+   * Re-stamp the mtime of every in-flight claim file to the current time so
+   * the next mtime-based stale sweep treats it as fresh. Best-effort: a missing
+   * file (already completed/recovered) or a permission error is ignored — the
+   * mtime fallback still protects genuinely crashed handlers.
+   */
+  function keepActiveClaimsFresh() {
+    if (inFlightClaimIds.size === 0) return;
+    const when = new Date(nowMs());
+    for (const id of inFlightClaimIds) {
+      try {
+        const claimedPath = join(paths.claimed, `${id}.json`);
+        if (existsSync(claimedPath)) utimesSync(claimedPath, when, when);
+      } catch { /* best-effort; mtime fallback still applies if we miss one */ }
+    }
+  }
+
+  /**
+   * Recover stale claims, first protecting the consumer's known-active claims
+   * (audit L6). All call sites route through here so the active-id guard is
+   * applied uniformly.
+   */
+  function recoverStaleClaimsGuarded() {
+    keepActiveClaimsFresh();
+    return recoverStaleClaims(agentRoot);
+  }
+
+  // Per-cadence reliability state. Tracks consecutive failure count and
+  // the earliest moment we'll allow another spawn for that cadence.
+  // Persists nothing — circuit state is in-memory only. On daemon restart
+  // we get a fresh slate; that's intentional (operators expect a restart
+  // to mean "try again now").
+  const cadenceState = new Map(); // cadence → { failures, openUntil, nextAllowedAt }
+
+  function getCadenceState(cadence) {
+    let s = cadenceState.get(cadence);
+    if (!s) { s = { failures: 0, openUntil: 0, nextAllowedAt: 0 }; cadenceState.set(cadence, s); }
+    return s;
+  }
+
+  function recordSubsessionSuccess(cadence) {
+    const s = getCadenceState(cadence);
+    s.failures = 0;
+    s.openUntil = 0;
+    s.nextAllowedAt = 0;
+  }
+
+  function recordSubsessionFailure(cadence) {
+    const s = getCadenceState(cadence);
+    s.failures += 1;
+    // Exponential back-off honouring the (test-overridable) schedule.
+    const idx = Math.min(s.failures, backoffSchedule.length - 1);
+    s.nextAllowedAt = Date.now() + backoffSchedule[idx];
+    if (s.failures >= circuitThreshold) {
+      s.openUntil = Date.now() + circuitDurationMs;
+      log({ level: "error", stage: "circuit_opened", cadence, failures: s.failures, open_until: new Date(s.openUntil).toISOString() });
+      writeCircuitFile();
+    }
+  }
+
+  function writeCircuitFile() {
+    // Persist the open-circuit snapshot so doctor + the operator can see
+    // which cadences are currently held back without scraping logs.
+    const open = {};
+    for (const [cad, s] of cadenceState.entries()) {
+      if (s.openUntil > Date.now()) {
+        open[cad] = { failures: s.failures, open_until: new Date(s.openUntil).toISOString() };
+      }
+    }
+    const path = join(agentRoot, "state/cadence-bus/circuit-open.json");
+    try {
+      if (Object.keys(open).length === 0) {
+        // Remove the file when nothing is open.
+
+        try { unlinkSync(path); } catch { /* */ }
+      } else {
+        writeFileSync(path, JSON.stringify({ generated: new Date().toISOString(), open }, null, 2) + "\n");
+      }
+    } catch { /* best-effort */ }
+  }
+
+  function isCadenceAllowed(cadence) {
+    const s = getCadenceState(cadence);
+    const now = Date.now();
+    if (s.openUntil > now) return { allowed: false, reason: "circuit-open", retry_at: s.openUntil };
+    if (s.nextAllowedAt > now) return { allowed: false, reason: "backoff", retry_at: s.nextAllowedAt };
+    // Circuit closes automatically when openUntil passes.
+    if (s.openUntil && s.openUntil <= now) {
+      s.openUntil = 0;
+      s.failures = 0;
+      log({ level: "info", stage: "circuit_closed", cadence });
+      writeCircuitFile();
+    }
+    return { allowed: true };
+  }
+
+  function log(entry) {
+    const enriched = { ts: new Date().toISOString(), ...entry };
+    logBusEvent(agentRoot, enriched);
+    if (userLogger) {
+      try { userLogger(enriched); } catch { /* never crash on logging */ }
+    } else {
+      defaultLogger(enriched);
+    }
+  }
+
+  function heartbeat() {
+    writeHealth(agentRoot, {
+      stats: { ...stats, depth: busDepth(agentRoot) },
+      active_subsessions: activeSubSessions,
+      stopping,
+    });
+  }
+
+  async function escalate(event) {
+    // Circuit-breaker / back-off gate. If this cadence is currently held
+    // back, requeue without spawning. The event keeps its attempt count
+    // because the failure was upstream (not a per-event problem).
+    const gate = isCadenceAllowed(event.cadence);
+    if (!gate.allowed) {
+      log({
+        level: "warn",
+        stage: gate.reason === "circuit-open" ? "skipped_circuit_open" : "skipped_backoff",
+        id: event.id,
+        cadence: event.cadence,
+        retry_at: new Date(gate.retry_at).toISOString(),
+      });
+      if (gate.reason === "circuit-open") stats.skipped_circuit_open += 1;
+      else stats.skipped_backoff += 1;
+      // Put the event back in inbox unchanged. Attempt accounting is
+      // single-sourced in failTick (audit M5), so we no longer decrement here
+      // — a held-back-by-circuit re-queue is not a failed attempt and must
+      // not drift the count. Use the atomic requeueTick (audit M6) instead of
+      // a bare writeFileSync so a crash can't leave a half-written inbox file.
+      requeueTick(agentRoot, event);
+      return { ok: false, decision: gate.reason };
+    }
+
+    // WS4 governance gate — beside the concurrency cap. If the host is under
+    // memory/load pressure, the 429 breaker is open, or the daily budget is
+    // exhausted (essential-only), DEFER this cadence tick: requeue it unchanged
+    // and DO NOT call failTick (a governor/rate deferral is an upstream gate,
+    // not a per-event failure — burning retry budget here would eventually DLQ
+    // a perfectly good cadence just because the box was busy).
+    {
+      const gov = governanceGate();
+      if (!gov.admit) {
+        log({
+          level: "info",
+          stage: "escalate_deferred",
+          reason: gov.reason,
+          id: event.id,
+          cadence: event.cadence,
+        });
+        requeueTick(agentRoot, event);
+        stats.retries += 1;
+        stats.last_decision = "deferred";
+        return { ok: false, decision: "deferred" };
+      }
+    }
+
+    if (activeSubSessions >= MAX_CONCURRENT_SUB_SESSIONS) {
+      // Re-queue and try again next tick. Single-owner cadence consumer
+      // means this can only happen when a prior tick is still running —
+      // queue depth is the right back-pressure signal.
+      log({
+        level: "info",
+        stage: "escalate_deferred",
+        id: event.id,
+        cadence: event.cadence,
+        active_subsessions: activeSubSessions,
+      });
+      // Re-queue unchanged — concurrent-spawn isn't a per-event failure, so
+      // it must not touch the attempt count (single-sourced in failTick,
+      // audit M5). Atomic requeueTick (audit M6) replaces the bare
+      // writeFileSync that could leave a half-written inbox file.
+      requeueTick(agentRoot, event);
+      stats.retries += 1;
+      return { ok: false, decision: "deferred" };
+    }
+
+    const def = getCadenceDef(event.cadence);
+    let promptPath = def?.prompt;
+    if (!promptPath) {
+      // Unknown cadence — try the conventional location.
+      const conventional = `schedules/triggers/${event.cadence}.md`;
+      if (existsSync(join(agentRoot, conventional))) {
+        promptPath = conventional;
+        log({ level: "warn", stage: "escalate_unknown_cadence", id: event.id, cadence: event.cadence, prompt: conventional });
+      } else {
+        log({ level: "error", stage: "escalate_no_prompt", id: event.id, cadence: event.cadence });
+        failTick(agentRoot, event.id, `no handler and no prompt at ${conventional}`, { terminal: true });
+        stats.dlq += 1;
+        return { ok: false, decision: "dlq-no-prompt" };
+      }
+    }
+
+    activeSubSessions += 1;
+    // Audit L6: mark this claim in-flight so the periodic stale-claim sweep
+    // (which can run concurrently with a long-running sub-session) does not
+    // treat its claimed/<id>.json as crashed and re-queue it under us.
+    inFlightClaimIds.add(event.id);
+    let result;
+    try {
+      log({ level: "info", stage: "escalating", id: event.id, cadence: event.cadence, prompt: promptPath, reason: event.metadata?.reason || "registry policy" });
+      result = await spawnSession({
+        agentRoot,
+        cadence: event.cadence,
+        promptPath,
+        timeoutMs: maxSpawnMs,
+        log,
+      });
+    } finally {
+      activeSubSessions -= 1;
+      inFlightClaimIds.delete(event.id);
+    }
+
+    if (result.ok) {
+      completeTick(agentRoot, event.id, {
+        decision: "escalated",
+        cadence: event.cadence,
+        prompt: promptPath,
+        exit_code: result.exit_code,
+        duration_ms: result.duration_ms,
+        stdout_path: result.stdout_path || null,
+        stderr_path: result.stderr_path || null,
+      });
+      recordSubsessionSuccess(event.cadence);
+      // WS4: a clean sub-session closes the shared 429 breaker.
+      try { rateGuard.recordSuccess(RATE_PROVIDER, { agentRoot }); } catch { /* */ }
+      stats.escalated += 1;
+      stats.last_decision = "escalated";
+      return { ok: true, decision: "escalated", exit_code: result.exit_code };
+    }
+
+    // WS4: if the sub-session failed with a rate-limit / overload signal, open
+    // the shared breaker and REQUEUE the tick unchanged (decision:"deferred")
+    // instead of failTick — a 429 is an upstream gate, not a per-event failure,
+    // so it must not burn this cadence's retry budget toward the DLQ.
+    if (rateGuard.classifyStderr(result.stderr_tail || result.error || "")) {
+      try {
+        const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot });
+        log({ level: "warn", stage: "subsession_rate_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil });
+      } catch { /* */ }
+      // L2: a 429 is a SHARED, provider-side rate-limit signal — the shared
+      // breaker (recordRateLimit above) already throttles every cadence. It is
+      // NOT evidence that THIS cadence is broken, so we must NOT call
+      // recordSubsessionFailure here: doing so would advance the per-cadence
+      // circuit toward open and leave a perfectly-healthy cadence circuit-open
+      // even after the shared breaker clears. Requeue unchanged (no failTick,
+      // no circuit trip); the shared breaker gates re-escalation.
+      requeueTick(agentRoot, event);
+      stats.retries += 1;
+      stats.last_decision = "deferred";
+      return { ok: false, decision: "deferred" };
+    }
+
+    // Failure path: log + cap retries low. The exact stderr tail comes
+    // from the spawn helper so we never DLQ "blind" again.
+    const stderrTail = (result.stderr_tail || "").trim().split("\n").slice(-3).join(" | ");
+    log({
+      level: "error",
+      stage: "subsession_failed",
+      id: event.id,
+      cadence: event.cadence,
+      exit_code: result.exit_code,
+      duration_ms: result.duration_ms,
+      error: result.error || stderrTail || `exit ${result.exit_code}`,
+      stderr_path: result.stderr_path || null,
+    });
+    stats.spawn_failures += 1;
+    recordSubsessionFailure(event.cadence);
+    const reason = result.error || (stderrTail ? `exit ${result.exit_code}: ${stderrTail}` : `exit ${result.exit_code}`);
+    const outcome = failTick(agentRoot, event.id, reason, { maxAttempts });
+    if (outcome?.destination === "dlq") stats.dlq += 1;
+    else stats.retries += 1;
+    return { ok: false, decision: outcome?.destination || "failed" };
+  }
+
+  // NOTE: do not name this `process` — function declarations are hoisted
+  // and would shadow the global `process` object inside startConsumer.
+  async function processEvent(event) {
+    stats.received += 1;
+    stats.last_event_id = event.id;
+
+    const def = getCadenceDef(event.cadence);
+    if (def?.mode === "inline" && typeof def.handler === "function") {
+      try {
+        const out = await def.handler({ event, agentRoot, log });
+        completeTick(agentRoot, event.id, {
+          decision: "inline",
+          cadence: event.cadence,
+          handler_result: out,
+        });
+        stats.inline += 1;
+        stats.last_decision = "inline";
+        return { decision: "inline", result: out };
+      } catch (err) {
+        log({ level: "error", stage: "inline_handler_threw", id: event.id, cadence: event.cadence, error: err.message });
+        const outcome = failTick(agentRoot, event.id, `inline-handler-threw: ${err.message}`);
+        if (outcome?.destination === "dlq") stats.dlq += 1;
+        return { decision: "failed", error: err.message };
+      }
+    }
+
+    if (def?.mode === "guarded" && typeof def.guard === "function") {
+      let guardOut;
+      try {
+        guardOut = await def.guard({ event, agentRoot, log });
+      } catch (err) {
+        log({ level: "error", stage: "guard_threw", id: event.id, cadence: event.cadence, error: err.message });
+        failTick(agentRoot, event.id, `guard-threw: ${err.message}`);
+        stats.retries += 1;
+        return { decision: "failed", error: err.message };
+      }
+      if (guardOut?.decision === "inline") {
+        completeTick(agentRoot, event.id, {
+          decision: "inline_via_guard",
+          cadence: event.cadence,
+          guard_result: guardOut,
+        });
+        stats.inline += 1;
+        stats.last_decision = "inline_via_guard";
+        return { decision: "inline_via_guard", result: guardOut };
+      }
+      // Guard says escalate — record WHY so the archived event shows the
+      // substantive pre-check that justified spawning a sub-session. Persist
+      // the annotated metadata to claimed/<id>.json so completeTick picks it
+      // up when it archives to processed/.
+      event.metadata = {
+        ...(event.metadata || {}),
+        reason: guardOut?.reason || "guard:escalate",
+        guard: guardOut,
+      };
+      try {
+        const claimedPath = join(paths.claimed, `${event.id}.json`);
+        writeFileSync(claimedPath, JSON.stringify(event, null, 2) + "\n");
+      } catch (err) {
+        log({ level: "warn", stage: "persist_metadata_failed", id: event.id, error: err.message });
+      }
+      return escalate(event);
+    }
+
+    // No registry entry, or registry says escalate.
+    return escalate(event);
+  }
+
+  async function tickOnce() {
+    if (stopping) return { processed: 0 };
+    if (isEmergencyStop(paths)) {
+      stats.skipped_emergency_stop += 1;
+      heartbeat();
+      log({ level: "warn", stage: "emergency_stop_active" });
+      return { processed: 0, emergency_stop: true };
+    }
+    // Recover stale claims occasionally — done by the periodic timer too,
+    // but every tick is cheap because it short-circuits on empty claimed/.
+    // Routed through the guarded wrapper so an in-flight claim is never swept
+    // (audit L6).
+    recoverStaleClaimsGuarded();
+
+    let processed = 0;
+    let escalatedThisTick = 0;
+    // Drain inline events as much as the consumer can in one tick; cap
+    // sub-session escalations at 1 per tick so a fast-failing cadence
+    // can't burn a whole minute's worth of retries inside a single poll.
+    // The next poll (DEFAULT_POLL_MS later) will pick up where we left off.
+    while (!stopping) {
+      const claim = claimNextTick(agentRoot);
+      if (!claim) break;
+      const event = claim.event;
+      activeTick = event.id;
+      let didEscalate = false;
+      try {
+        const def = getCadenceDef(event.cadence);
+        const willEscalate = !def || (def.mode !== "inline" && (def.mode !== "guarded" || true));
+        // Roughly: if it's not a registry-inline cadence, we MAY escalate.
+        // We don't yet know if the guard will say inline; processEvent
+        // will tell us via stats. Use the escalated stats delta as the
+        // signal that an actual sub-session ran this iteration.
+        const before = stats.escalated + stats.spawn_failures + stats.skipped_circuit_open + stats.skipped_backoff;
+        await processEvent(event);
+        const after = stats.escalated + stats.spawn_failures + stats.skipped_circuit_open + stats.skipped_backoff;
+        if (after > before) didEscalate = true;
+        // Silence unused var warning.
+        void willEscalate;
+      } finally {
+        activeTick = null;
+      }
+      processed += 1;
+      if (didEscalate) escalatedThisTick += 1;
+      // Hard cap: at most ONE sub-session spawn per tick. Inline ticks
+      // keep draining freely (they're cheap).
+      if (escalatedThisTick >= 1) break;
+      if (processed >= 16) break; // soft batch cap
+    }
+    return { processed };
+  }
+
+  // Background loops
+  const pollTimer = setInterval(() => {
+    tickOnce().catch((err) => {
+      log({ level: "error", stage: "tick_threw", error: err?.message || String(err) });
+    });
+  }, pollMs);
+  pollTimer.unref?.();
+  timers.push(pollTimer);
+
+  const hbTimer = setInterval(() => heartbeat(), heartbeatMs);
+  hbTimer.unref?.();
+  timers.push(hbTimer);
+
+  const recoveryTimer = setInterval(() => {
+    try {
+      const out = recoverStaleClaimsGuarded();
+      if (out.scanned > 0) {
+        log({ level: "info", stage: "periodic_recovery", ...out });
+      }
+    } catch (err) {
+      log({ level: "error", stage: "periodic_recovery_failed", error: err.message });
+    }
+    // Retention sweep (audit M8) shares the recovery cadence. Isolated in its
+    // own try/catch so a sweep failure can never take down stale-claim
+    // recovery — the more critical of the two.
+    try {
+      const swept = sweepRetention(agentRoot);
+      if (
+        swept.processedDirsDeleted || swept.dlqDeleted || swept.failedDeleted ||
+        swept.queueRotated || swept.logsDeleted
+      ) {
+        log({ level: "info", stage: "periodic_retention", ...swept });
+      }
+    } catch (err) {
+      log({ level: "error", stage: "periodic_retention_failed", error: err.message });
+    }
+  }, recoveryMs);
+  recoveryTimer.unref?.();
+  timers.push(recoveryTimer);
+
+  // Initial sweep + heartbeat
+  recoverStaleClaimsGuarded();
+  heartbeat();
+  log({ level: "info", stage: "consumer_started", pollMs, heartbeatMs, recoveryMs });
+
+  async function stop() {
+    if (stopping) return;
+    stopping = true;
+    for (const t of timers) clearInterval(t);
+    timers = [];
+    log({ level: "info", stage: "consumer_stopping", active_tick: activeTick });
+    heartbeat();
+  }
+
+  function getStats() {
+    return { ...stats, depth: busDepth(agentRoot), agent_root: agentRoot };
+  }
+
+  return {
+    stop,
+    getStats,
+    tickOnce,
+    _paths: getBusPaths(agentRoot),
+    // Test hooks (audit L6). Let tests drive the active-id guard and the
+    // guarded recovery deterministically without spawning a real sub-session.
+    _recoverStaleClaimsGuarded: recoverStaleClaimsGuarded,
+    _markInFlight: (id) => inFlightClaimIds.add(id),
+    _clearInFlight: (id) => inFlightClaimIds.delete(id),
+  };
+}
+
+// Allow `node scripts/daemon/cadence-consumer.mjs` to run the consumer
+// standalone (useful for development and for migrations that need to
+// drain the bus without starting the full daemon).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const consumer = startConsumer({});
+  const shutdown = async (sig) => {
+    process.stderr.write(`[cadence-consumer] caught ${sig}, stopping…\n`);
+    await consumer.stop();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  // Keep the process alive — unref'd timers won't otherwise.
+  setInterval(() => {}, 60_000);
+}