@adaptic/maestro 1.7.3 → 1.8.0

package/scripts/cadence/enqueue-cadence-tick.test.mjs

@@ -0,0 +1,154 @@
+/**
+ * enqueue-cadence-tick.test.mjs — node:test coverage for the CLI enqueue
+ * script (the entry point used by launchd plists).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ENQUEUE_SCRIPT = resolve(__dirname, "enqueue-cadence-tick.mjs");
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `enqueue-cli-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 { /* */ }
+}
+
+function run(cwd, args, env = {}) {
+  return spawnSync(process.execPath, [ENQUEUE_SCRIPT, ...args], {
+    cwd,
+    env: { ...process.env, AGENT_ROOT: cwd, ...env },
+    encoding: "utf-8",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Happy path
+// ---------------------------------------------------------------------------
+
+test("CLI enqueues a tick and writes inbox JSON", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["inbox-processor", "--source=launchd"]);
+    assert.equal(r.status, 0, r.stderr);
+    const out = JSON.parse(r.stdout.trim());
+    assert.equal(out.ok, true);
+    assert.equal(out.cadence, "inbox-processor");
+    assert.equal(out.fallback_only, false);
+    assert.ok(out.path);
+    assert.ok(existsSync(out.path));
+    const event = JSON.parse(readFileSync(out.path, "utf-8"));
+    assert.equal(event.source, "launchd");
+    assert.equal(event.cadence, "inbox-processor");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI accepts metadata pairs (repeated and comma-separated)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, [
+      "weekly-strategic-memo",
+      "--source=manual",
+      "--metadata=note=launch",
+      "--metadata=k1=v1,k2=v2",
+    ]);
+    assert.equal(r.status, 0);
+    const out = JSON.parse(r.stdout.trim());
+    const event = JSON.parse(readFileSync(out.path, "utf-8"));
+    assert.equal(event.metadata.note, "launch");
+    assert.equal(event.metadata.k1, "v1");
+    assert.equal(event.metadata.k2, "v2");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --quiet suppresses stdout JSON", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["inbox-processor", "--source=launchd", "--quiet"]);
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout.trim(), "");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --version prints bus schema version", async () => {
+  const r = spawnSync(process.execPath, [ENQUEUE_SCRIPT, "--version"], { encoding: "utf-8" });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /^\d+$/m);
+});
+
+test("CLI --help prints usage and exits 0", async () => {
+  const r = spawnSync(process.execPath, [ENQUEUE_SCRIPT, "--help"], { encoding: "utf-8" });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /enqueue-cadence-tick/);
+});
+
+// ---------------------------------------------------------------------------
+// Error paths
+// ---------------------------------------------------------------------------
+
+test("CLI exits 2 with no cadence", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, []);
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /required/);
+  } finally { await rmRoot(root); }
+});
+
+test("CLI exits 2 on unknown flag", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["x", "--what-is-this"]);
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /unknown flag/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Emergency stop
+// ---------------------------------------------------------------------------
+
+test("CLI returns 0 with skipped=emergency-stop when stop flag exists", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeFileSync(join(root, ".emergency-stop"), "now");
+    const r = run(root, ["weekly-strategic-memo", "--source=launchd"]);
+    assert.equal(r.status, 0);
+    const out = JSON.parse(r.stdout.trim());
+    assert.equal(out.skipped, "emergency-stop");
+    assert.equal(out.fallback_only, true);
+    assert.equal(out.path, null);
+    // No file landed in inbox/.
+    assert.ok(!existsSync(join(root, "state/cadence-bus/inbox", `${out.id}.json`)));
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Bus-handoff sanity — the CLI must finish in well under a second so launchd
+// never piles up; we don't pin a number, just a generous ceiling.
+// ---------------------------------------------------------------------------
+
+test("CLI completes in well under 2 seconds", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const t0 = Date.now();
+    const r = run(root, ["inbox-processor", "--source=launchd", "--quiet"]);
+    const dt = Date.now() - t0;
+    assert.equal(r.status, 0);
+    assert.ok(dt < 2000, `enqueue took ${dt}ms`);
+  } finally { await rmRoot(root); }
+});

package/scripts/cadence/launchd-cadence-wrapper.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# launchd-cadence-wrapper.sh — Bootstraps env and execs the Node cadence
+# enqueue script under launchd.
+#
+# Usage in a plist:
+#   <key>ProgramArguments</key>
+#   <array>
+#     <string>/path/to/scripts/cadence/launchd-cadence-wrapper.sh</string>
+#     <string>/path/to/scripts/cadence/enqueue-cadence-tick.mjs</string>
+#     <string>cadence-name</string>
+#     <string>--source=launchd</string>
+#   </array>
+#
+# What it does:
+#   1. Sets HOME, PATH, USER, AGENT_ROOT (launchd's bare env doesn't include them).
+#   2. Picks a node binary (nvm, homebrew, system fallback).
+#   3. Redirects stdout/stderr to logs/cadence-bus/launchd-YYYY-MM-DD.log.
+#   4. Exec's `node <enqueue-script> "$@"`.
+#
+# This is a *pure enqueue* wrapper — it must NOT spawn Claude Code. The
+# heavyweight cadence work happens inside the persistent daemon's cadence
+# consumer, not here.
+
+set -e
+
+if [ $# -lt 1 ]; then
+  echo "[cadence-wrapper] FATAL: enqueue script path required" >&2
+  exit 64
+fi
+
+ENQUEUE_SCRIPT="$1"
+shift
+
+# Walk up from the enqueue script to find the agent root. AGENT_ROOT is the
+# nearest ancestor with both package.json and config/.
+TARGET_DIR="$(cd "$(dirname "$ENQUEUE_SCRIPT")" && pwd -P)"
+CANDIDATE="$TARGET_DIR"
+AGENT_ROOT=""
+while [ "$CANDIDATE" != "/" ]; do
+  if [ -f "$CANDIDATE/package.json" ] && [ -d "$CANDIDATE/config" ]; then
+    AGENT_ROOT="$CANDIDATE"
+    break
+  fi
+  CANDIDATE="$(dirname "$CANDIDATE")"
+done
+AGENT_ROOT="${AGENT_ROOT:-$TARGET_DIR}"
+
+export AGENT_ROOT
+export AGENT_DIR="$AGENT_ROOT"
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$HOME/.nvm/versions/node/v24/bin/node" \
+  "$HOME/.nvm/versions/node/v22/bin/node" \
+  "$HOME/.nvm/versions/node/v20/bin/node" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  /usr/bin/node; do
+  if [ -x "$candidate" ]; then
+    NODE_BIN="$candidate"
+    break
+  fi
+done
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[cadence-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+LOG_DATE="$(date +%Y-%m-%d)"
+LOG_DIR="$AGENT_ROOT/logs/cadence-bus"
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+LOG_FILE="$LOG_DIR/launchd-${LOG_DATE}.log"
+
+# Exec the enqueue script. stdin is closed; stdout/stderr go to the log.
+exec "$NODE_BIN" "$ENQUEUE_SCRIPT" "$@" >> "$LOG_FILE" 2>&1

package/scripts/daemon/cadence-consumer.mjs

@@ -0,0 +1,439 @@
+/**
+ * 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 --dangerously-skip-permissions <prompt>`
+ *                  child_process.spawn.
+ *   maxSpawnMs     hard timeout per sub-session (default 30 * 60_000).
+ *   logger         optional fn({ ts, level, …rest }) → void for tests.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+import {
+  ensureBusDirs,
+  claimNextTick,
+  completeTick,
+  failTick,
+  recoverStaleClaims,
+  writeHealth,
+  getBusPaths,
+  logBusEvent,
+  busDepth,
+} from "../../lib/cadence-bus.mjs";
+import { getCadenceDef } from "./cadence-handlers.mjs";
+
+// ---------------------------------------------------------------------------
+// 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;
+
+// ---------------------------------------------------------------------------
+// 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 */ }
+  }
+}
+
+/**
+ * Spawn a sub-session running the cadence's trigger prompt and resolve
+ * with { exit_code, durationMs }. Reads the prompt at call time so the
+ * latest version (possibly upgraded between ticks) is always used.
+ */
+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;
+    }
+
+    const bin = process.env.CLAUDE_BIN || "claude";
+    const args = ["--print", "--dangerously-skip-permissions", body];
+    const env = { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot };
+    const started = Date.now();
+
+    log({ level: "info", stage: "subsession_spawn", cadence, bin });
+
+    let child;
+    try {
+      child = spawn(bin, args, { cwd: agentRoot, env, stdio: "ignore" });
+    } catch (err) {
+      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);
+      const durationMs = Date.now() - started;
+      const exit_code = typeof code === "number" ? code : (signal ? -1 : -5);
+      resolveOut({
+        ok: exit_code === 0,
+        exit_code,
+        signal: signal || null,
+        duration_ms: durationMs,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      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;
+
+  const stats = {
+    started_at: new Date().toISOString(),
+    received: 0,
+    inline: 0,
+    escalated: 0,
+    skipped_emergency_stop: 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;
+
+  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) {
+    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,
+      });
+      failTick(agentRoot, event.id, "deferred:concurrent-spawn", { maxAttempts: 10 });
+      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;
+    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;
+    }
+
+    if (result.ok) {
+      completeTick(agentRoot, event.id, {
+        decision: "escalated",
+        cadence: event.cadence,
+        prompt: promptPath,
+        exit_code: result.exit_code,
+        duration_ms: result.duration_ms,
+      });
+      stats.escalated += 1;
+      stats.last_decision = "escalated";
+      return { ok: true, decision: "escalated", exit_code: result.exit_code };
+    }
+    log({ level: "error", stage: "subsession_failed", id: event.id, cadence: event.cadence, exit_code: result.exit_code, error: result.error || null });
+    stats.spawn_failures += 1;
+    const outcome = failTick(agentRoot, event.id, result.error || `exit ${result.exit_code}`);
+    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/.
+    recoverStaleClaims(agentRoot);
+
+    let processed = 0;
+    // Drain as much as the consumer can in one tick, but yield to the
+    // event loop between events so heartbeats and stop signals fire.
+    while (!stopping) {
+      const claim = claimNextTick(agentRoot);
+      if (!claim) break;
+      const event = claim.event;
+      activeTick = event.id;
+      try {
+        await processEvent(event);
+      } finally {
+        activeTick = null;
+      }
+      processed += 1;
+      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 = recoverStaleClaims(agentRoot);
+      if (out.scanned > 0) {
+        log({ level: "info", stage: "periodic_recovery", ...out });
+      }
+    } catch (err) {
+      log({ level: "error", stage: "periodic_recovery_failed", error: err.message });
+    }
+  }, recoveryMs);
+  recoveryTimer.unref?.();
+  timers.push(recoveryTimer);
+
+  // Initial sweep + heartbeat
+  recoverStaleClaims(agentRoot);
+  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) };
+}
+
+// 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);
+}