@cohortapp/agent-sdk 2.3.0

package/lib/cadence-bus.mjs

@@ -0,0 +1,1120 @@
+/**
+ * Maestro — Cadence Bus
+ *
+ * Local, file-backed event queue that decouples scheduled cadence ticks
+ * (launchd, manual, daemon, init-maestro, upgrade) from the persistent main
+ * Maestro session that actually services them.
+ *
+ * Why this exists
+ * ---------------
+ * Before the bus, every scheduled cadence tick (inbox-processor every 5m,
+ * backlog-executor every 10m, the daily/weekly/quarterly ones, …) was wired
+ * to launch a fresh `claude --print` session via run-trigger.sh. That meant
+ * dozens of full Claude Code spawns per day, each paying full auth/context/
+ * token overhead even when the tick had nothing to do. It also made
+ * emergency-stop, deduplication, rate-limiting, and quota gating ad-hoc.
+ *
+ * After the bus, launchd just enqueues a tiny JSON event onto a directory.
+ * The persistent daemon (maestro-daemon.mjs) consumes events in-process,
+ * handles lightweight scan/classify/route work inline, and only spawns a
+ * sub-session when the work genuinely warrants it.
+ *
+ * Storage layout (all paths relative to AGENT_ROOT)
+ * --------------------------------------------------
+ *   state/cadence-bus/
+ *     inbox/                  — newly enqueued events (one JSON per event)
+ *     claimed/                — events currently being processed
+ *     processed/<YYYY-MM-DD>/ — successful completions, archived by date
+ *     failed/                 — last-known-bad event payloads (transient errors)
+ *     dlq/                    — events that exceeded retry budget (terminal)
+ *     queue.jsonl             — append-only fallback log (every enqueue lands
+ *                               here too, so no event is lost even if inbox/
+ *                               is unavailable on a given enqueue)
+ *     health.json             — heartbeat written by the consumer
+ *
+ * Concurrency model
+ * -----------------
+ * Atomic enqueue:   write to a temp file in the same directory, then
+ *                   rename(tmp, final). rename(2) is atomic on macOS APFS
+ *                   when source and destination live on the same volume.
+ *
+ * Atomic claim:     rename(inbox/<id>.json → claimed/<id>.json). If two
+ *                   consumers race for the same file, exactly one rename
+ *                   succeeds; the loser gets ENOENT and skips the event.
+ *                   No locks, no stale-lock pathology.
+ *
+ * Stale recovery:   on consumer startup (and periodically while running),
+ *                   any file in claimed/ older than STALE_CLAIM_MS is
+ *                   either returned to inbox/ (under the retry budget) or
+ *                   moved to dlq/. This handles crashes mid-processing.
+ *
+ * Event payload schema
+ * --------------------
+ *   {
+ *     "id":            "evt-2026-05-12T15:30:00.123Z-<random>",
+ *     "type":          "cadence_tick" | "manual_tick" | "internal",
+ *     "source":        "launchd" | "manual" | "daemon" | "init-maestro" | "upgrade",
+ *     "ts":            "2026-05-12T15:30:00.123Z",
+ *     "cadence":       "inbox-processor" | "backlog-executor" | "weekly-strategic-memo" | …,
+ *     "workflow":      "continuous/inbox-processor" (optional),
+ *     "correlation_id": "<external id, optional>",
+ *     "priority":      "high" | "normal" | "low" (default "normal"),
+ *     "metadata":      { … free-form, kept for auditing },
+ *     "attempts":      0 (auto-managed by consumer)
+ *   }
+ *
+ * The bus does not interpret `cadence` itself — it only routes by it.
+ * Handler selection and execution live in scripts/daemon/cadence-handlers.mjs
+ * and scripts/daemon/cadence-consumer.mjs.
+ */
+
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  truncateSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Constants (override-friendly via env for tests)
+// ---------------------------------------------------------------------------
+
+export const BUS_RELATIVE = "state/cadence-bus";
+export const LOGS_RELATIVE = "logs/cadence-bus";
+
+// Bus schema version. If we change the on-disk layout in a backwards-
+// incompatible way, bump this and write a migration. Doctor reads this.
+export const BUS_VERSION = "1";
+
+// Stale claim threshold — claims older than this are recovered to inbox or
+// the dlq. Defaults assume the longest live cadence handler runs well under
+// 30 minutes; tune via env for long-running migrations.
+const DEFAULT_STALE_CLAIM_MS = 30 * 60 * 1000;
+
+// Maximum attempts before an event goes to dlq. Cadence ticks are mostly
+// non-essential; we don't want a single stuck tick to clog the bus.
+const DEFAULT_MAX_ATTEMPTS = 5;
+
+// Retention defaults (audit M8). On a 24/7 mini nothing prunes processed/,
+// dlq/, failed/, queue.jsonl or the log dir, so they grow without bound.
+// sweepRetention enforces these caps; all overridable via opts / env.
+const DEFAULT_PROCESSED_RETENTION_DAYS = 14;
+const DEFAULT_TERMINAL_KEEP = 500;               // newest N files kept in dlq/ & failed/
+const DEFAULT_QUEUE_MAX_BYTES = 5 * 1024 * 1024; // queue.jsonl rotate threshold (~5MB)
+const DEFAULT_LOG_RETENTION_DAYS = 14;           // logs/cadence-bus/<date>.jsonl
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the agent root. Prefers explicit arg, then AGENT_ROOT env, then
+ * AGENT_DIR env, then process.cwd(). Returns an absolute path.
+ */
+export function resolveAgentRoot(agentRoot) {
+  return resolve(
+    agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
+/**
+ * Return all bus paths derived from an agent root.
+ */
+export function getBusPaths(agentRoot) {
+  const root = resolveAgentRoot(agentRoot);
+  const base = join(root, BUS_RELATIVE);
+  return {
+    agentRoot: root,
+    base,
+    inbox: join(base, "inbox"),
+    claimed: join(base, "claimed"),
+    processed: join(base, "processed"),
+    failed: join(base, "failed"),
+    dlq: join(base, "dlq"),
+    queueJsonl: join(base, "queue.jsonl"),
+    health: join(base, "health.json"),
+    version: join(base, "VERSION"),
+    // WS4 at-most-once cron state: per-cadence {lastRunAt,nextRunAt,intervalMs}.
+    schedule: join(base, "schedule.json"),
+    scheduleLock: join(base, "schedule.json.lock"),
+    logsDir: join(root, LOGS_RELATIVE),
+    emergencyStop: join(root, ".emergency-stop"),
+  };
+}
+
+/**
+ * Idempotently create the cadence-bus directory tree. Safe to call on every
+ * enqueue/consume; no-op once present.
+ */
+export function ensureBusDirs(agentRoot) {
+  const paths = getBusPaths(agentRoot);
+  for (const dir of [paths.inbox, paths.claimed, paths.processed, paths.failed, paths.dlq, paths.logsDir]) {
+    mkdirSync(dir, { recursive: true });
+  }
+  // Touch a version marker so doctor / upgrade can detect a freshly-created
+  // bus and reason about schema migrations later.
+  if (!existsSync(paths.version)) {
+    writeFileSync(paths.version, `${BUS_VERSION}\n`);
+  }
+  return paths;
+}
+
+// ---------------------------------------------------------------------------
+// Event id
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a unique, sortable event id of the form:
+ *   evt-2026-05-12T15:30:00.123Z-<8 hex>
+ * The ISO prefix makes inbox/ directory listings naturally sorted by time.
+ * The random suffix avoids collisions for events enqueued in the same ms.
+ */
+export function nextEventId(now = new Date()) {
+  const iso = now.toISOString();
+  const rand = randomBytes(4).toString("hex");
+  return `evt-${iso}-${rand}`;
+}
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
+function todayUtc(now = new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+
+/**
+ * Append a structured log line to logs/cadence-bus/<date>.jsonl. Best-effort;
+ * caller never blocks on log failures. Returns true on success, false on a
+ * caught I/O error.
+ */
+export function logBusEvent(agentRoot, entry) {
+  try {
+    const paths = getBusPaths(agentRoot);
+    mkdirSync(paths.logsDir, { recursive: true });
+    const file = join(paths.logsDir, `${todayUtc()}.jsonl`);
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+    appendFileSync(file, line);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically write JSON to `targetPath`. Writes a sibling `.tmp` file, fsyncs
+ * the file's contents to disk, then renames it over the target. The fsync
+ * happens BEFORE the rename so the durable bytes are in place once the atomic
+ * rename publishes the name — a crash after the rename returns can't surface a
+ * zero-length or half-written file. (On macOS APFS rename(2) is atomic for
+ * same-volume source/dest; fsync flushes the data the rename then exposes.)
+ *
+ * Exported (audit M6) so the consumer's re-queue paths use the same
+ * write-temp-then-rename primitive instead of a bare writeFileSync that can
+ * leave a half-written inbox file if the process dies mid-write.
+ */
+export function writeJsonAtomic(targetPath, obj) {
+  mkdirSync(dirname(targetPath), { recursive: true });
+  const tmp = `${targetPath}.tmp.${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}`;
+  const data = JSON.stringify(obj, null, 2) + "\n";
+  // Write + fsync via an explicit fd so the contents are durable before the
+  // rename publishes the name. closeSync runs whether or not fsync succeeds.
+  const fd = openSync(tmp, "w");
+  try {
+    writeSync(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    renameSync(tmp, targetPath);
+  } catch (err) {
+    // Clean up the orphan tmp file if rename failed.
+    try { unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Enqueue
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a one-line JSON record to the fallback queue.jsonl. Used both as a
+ * tamper-evident audit log of every enqueue and as a last-resort fallback
+ * when writing to inbox/ fails (e.g. disk full, permissions).
+ */
+function appendFallbackQueue(paths, event) {
+  try {
+    mkdirSync(dirname(paths.queueJsonl), { recursive: true });
+    appendFileSync(paths.queueJsonl, JSON.stringify(event) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// At-most-once cron gate (WS4)
+// ---------------------------------------------------------------------------
+//
+// The plist's StartInterval/StartCalendarInterval is the wall-clock trigger,
+// but launchd can double-fire (catch-up after sleep, overlapping loads) and,
+// after a reboot/outage, it would otherwise replay every missed tick at once.
+// When the caller passes `intervalMs` (derived by generate-plists.sh from the
+// cadence's interval), enqueueTick consults a per-cadence schedule under an
+// O_EXCL lock and admits AT MOST ONE tick per interval:
+//
+//   • grace          — a fire within graceMs of the boundary is the real tick:
+//                       advance nextRunAt and admit. An early/duplicate fire is
+//                       suppressed.  graceMs = clamp(interval/2, 120s, 2h).
+//   • stale fast-fwd  — if we're more than one whole interval past nextRunAt
+//                       (we were asleep / powered off), jump nextRunAt to the
+//                       NEXT future boundary and admit exactly ONE catch-up
+//                       tick — never the burst of missed ones.
+//
+// When `intervalMs` is absent the gate is a no-op and enqueueTick behaves
+// exactly as before (full back-compat — every existing caller/test).
+
+const SCHEDULE_GRACE_MIN_MS = 120_000;          // 2 min
+const SCHEDULE_GRACE_MAX_MS = 2 * 60 * 60_000;  // 2 h
+const SCHEDULE_LOCK_STALE_MS = 30_000;          // a held lock older than this is stale
+
+function clampGrace(intervalMs) {
+  return Math.min(SCHEDULE_GRACE_MAX_MS, Math.max(SCHEDULE_GRACE_MIN_MS, Math.floor(intervalMs / 2)));
+}
+
+/**
+ * Acquire the schedule lock via O_EXCL (same atomic primitive as
+ * session-lock.mjs:89). Returns true on success. A stale lock (older than
+ * SCHEDULE_LOCK_STALE_MS) is reclaimed so a crash mid-update can't wedge the
+ * gate forever.
+ */
+function acquireScheduleLock(paths, now) {
+  try {
+    writeFileSync(paths.scheduleLock, JSON.stringify({ pid: process.pid, at: now }), { flag: "wx" });
+    return true;
+  } catch (err) {
+    if (err.code !== "EEXIST") return false;
+    // Reclaim if stale.
+    try {
+      const st = statSync(paths.scheduleLock);
+      if (now - st.mtimeMs >= SCHEDULE_LOCK_STALE_MS) {
+        writeFileSync(paths.scheduleLock, JSON.stringify({ pid: process.pid, at: now }));
+        return true;
+      }
+    } catch { /* vanished — try once more */ }
+    try {
+      writeFileSync(paths.scheduleLock, JSON.stringify({ pid: process.pid, at: now }), { flag: "wx" });
+      return true;
+    } catch { return false; }
+  }
+}
+
+function releaseScheduleLock(paths) {
+  try { unlinkSync(paths.scheduleLock); } catch { /* */ }
+}
+
+function readSchedule(paths) {
+  try { return JSON.parse(readFileSync(paths.schedule, "utf-8")) || {}; }
+  catch { return {}; }
+}
+
+/**
+ * Decide whether to admit this cadence tick, mutating the on-disk schedule.
+ * Pure-ish: the only side effect is the schedule.json write (under the lock).
+ * Returns { admit: boolean, reason, kind }.
+ *
+ * If the lock can't be taken (rare contention) we FAIL OPEN — admit the tick
+ * (Invariant: never drop work; a duplicate is cheaper than a missed cadence).
+ *
+ * @param {object} paths
+ * @param {string} cadence
+ * @param {number} intervalMs
+ * @param {number} now
+ */
+function scheduleGate(paths, cadence, intervalMs, now) {
+  if (!(Number.isFinite(intervalMs) && intervalMs > 0)) {
+    return { admit: true, reason: "no-interval", kind: "passthrough" };
+  }
+  mkdirSync(paths.base, { recursive: true });
+  if (!acquireScheduleLock(paths, now)) {
+    return { admit: true, reason: "lock-contended-fail-open", kind: "admit" };
+  }
+  try {
+    const sched = readSchedule(paths);
+    const entry = sched[cadence];
+    const grace = clampGrace(intervalMs);
+
+    let result;
+    if (!entry || !Number.isFinite(Number(entry.nextRunAt))) {
+      // First time we've seen this cadence: admit now, schedule the next one.
+      sched[cadence] = { lastRunAt: now, nextRunAt: now + intervalMs, intervalMs };
+      result = { admit: true, reason: "first-tick", kind: "admit" };
+    } else {
+      const nextRunAt = Number(entry.nextRunAt);
+      if (now > nextRunAt + intervalMs) {
+        // STALE: we were asleep/off for more than a whole interval. Jump
+        // nextRunAt to the next FUTURE boundary and admit exactly one catch-up.
+        let boundary = nextRunAt;
+        // Advance in whole intervals until strictly in the future.
+        const periodsMissed = Math.floor((now - nextRunAt) / intervalMs) + 1;
+        boundary = nextRunAt + periodsMissed * intervalMs;
+        if (boundary <= now) boundary += intervalMs; // safety: ensure future
+        sched[cadence] = { lastRunAt: now, nextRunAt: boundary, intervalMs };
+        result = { admit: true, reason: "stale-fast-forward", kind: "catch-up", periodsMissed };
+      } else if (now >= nextRunAt - grace) {
+        // On-time (within grace of the boundary): the real tick. Advance.
+        sched[cadence] = { lastRunAt: now, nextRunAt: nextRunAt + intervalMs, intervalMs };
+        result = { admit: true, reason: "on-boundary", kind: "admit" };
+      } else {
+        // Too early / duplicate launchd fire — suppress.
+        result = { admit: false, reason: "before-grace-window", kind: "duplicate", nextRunAt };
+      }
+    }
+
+    if (result.admit) {
+      try { writeJsonAtomic(paths.schedule, sched); }
+      catch { /* best-effort; on write failure we still admit (no work lost) */ }
+    }
+    return result;
+  } finally {
+    releaseScheduleLock(paths);
+  }
+}
+
+/**
+ * Enqueue a cadence event onto the bus.
+ *
+ * @param {object} input
+ * @param {string} input.cadence  Cadence name (e.g. "inbox-processor"). Required.
+ * @param {string} [input.type]   Event type, default "cadence_tick".
+ * @param {string} [input.source] Originator label, default "manual".
+ * @param {string} [input.workflow]
+ * @param {string} [input.correlation_id]
+ * @param {"high"|"normal"|"low"} [input.priority]
+ * @param {object} [input.metadata]
+ * @param {number} [input.intervalMs]  Cadence interval (ms). When present,
+ *                                      enables the at-most-once cron gate
+ *                                      (grace + stale fast-forward). Absent →
+ *                                      legacy behaviour, every call enqueues.
+ * @param {number} [input.now]         Injectable clock (ms) for tests.
+ * @param {string} [input.agentRoot]  Override AGENT_ROOT for tests.
+ * @returns {{ id: string, path: string, fallbackOnly: boolean, skipped?: string }}
+ */
+export function enqueueTick(input = {}) {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("enqueueTick: input must be an object");
+  }
+  const cadence = String(input.cadence || "").trim();
+  if (!cadence) {
+    throw new Error("enqueueTick: cadence is required");
+  }
+
+  const paths = ensureBusDirs(input.agentRoot);
+
+  // Emergency-stop short-circuit. The bus still logs the event so we can
+  // see what would have run, but no file lands in inbox/.
+  if (existsSync(paths.emergencyStop)) {
+    const event = buildEvent(input, cadence);
+    appendFallbackQueue(paths, { ...event, _suppressed: "emergency-stop" });
+    logBusEvent(paths.agentRoot, {
+      level: "info",
+      stage: "enqueue_suppressed",
+      cadence,
+      reason: "emergency-stop",
+      id: event.id,
+    });
+    return { id: event.id, path: null, fallbackOnly: true, skipped: "emergency-stop" };
+  }
+
+  const event = buildEvent(input, cadence);
+  const target = join(paths.inbox, `${event.id}.json`);
+
+  // Dedup against replay (audit H12). When a caller supplies an explicit
+  // `input.id` (e.g. a poller re-delivering after a reconnect), writing
+  // straight to inbox/ would clobber an in-flight event — overwriting its
+  // bumped attempt count — or silently re-run a cadence already processed.
+  // Auto-generated ids are collision-resistant, so this only guards the
+  // explicit-id case.
+  if (input.id) {
+    const dup =
+      existsSync(join(paths.inbox, `${event.id}.json`)) ? "inbox" :
+      existsSync(join(paths.claimed, `${event.id}.json`)) ? "claimed" :
+      existsSync(join(paths.dlq, `${event.id}.json`)) ? "dlq" :
+      isProcessedId(paths.agentRoot, event.id) ? "processed" :
+      null;
+    if (dup) {
+      logBusEvent(paths.agentRoot, {
+        level: "info",
+        stage: "enqueue_deduped",
+        cadence,
+        id: event.id,
+        existing: dup,
+      });
+      return { id: event.id, path: null, fallbackOnly: false, deduped: dup };
+    }
+  }
+
+  // At-most-once cron gate (WS4). Only engages when intervalMs is supplied by
+  // the caller (plist). Suppressed ticks are still audited so we can see what
+  // launchd fired, but nothing lands in inbox/.
+  if (Number.isFinite(input.intervalMs) && input.intervalMs > 0) {
+    const nowMs = typeof input.now === "number" ? input.now : Date.now();
+    const gate = scheduleGate(paths, cadence, input.intervalMs, nowMs);
+    if (!gate.admit) {
+      appendFallbackQueue(paths, { ...event, _suppressed: gate.reason });
+      logBusEvent(paths.agentRoot, {
+        level: "info",
+        stage: "enqueue_suppressed",
+        cadence,
+        reason: gate.reason,
+        kind: gate.kind,
+        id: event.id,
+      });
+      return { id: event.id, path: null, fallbackOnly: true, skipped: gate.reason };
+    }
+    // Annotate the admitted event so the catch-up case is visible downstream.
+    if (gate.kind === "catch-up") {
+      event.metadata = { ...(event.metadata || {}), schedule_kind: "catch-up", periods_missed: gate.periodsMissed };
+    }
+  }
+
+  // Always write the audit row first. If inbox write fails the event is
+  // still recoverable from queue.jsonl.
+  appendFallbackQueue(paths, event);
+
+  let fallbackOnly = false;
+  try {
+    writeJsonAtomic(target, event);
+  } catch (err) {
+    fallbackOnly = true;
+    logBusEvent(paths.agentRoot, {
+      level: "error",
+      stage: "enqueue_inbox_failed",
+      cadence,
+      id: event.id,
+      error: err.message,
+    });
+  }
+
+  logBusEvent(paths.agentRoot, {
+    level: "info",
+    stage: fallbackOnly ? "enqueued_fallback" : "enqueued",
+    cadence,
+    source: event.source,
+    priority: event.priority,
+    id: event.id,
+  });
+
+  return { id: event.id, path: fallbackOnly ? null : target, fallbackOnly };
+}
+
+function buildEvent(input, cadence) {
+  return {
+    id: input.id || nextEventId(),
+    type: input.type || "cadence_tick",
+    source: input.source || "manual",
+    ts: input.ts || new Date().toISOString(),
+    cadence,
+    workflow: input.workflow || null,
+    correlation_id: input.correlation_id || null,
+    priority: ["high", "normal", "low"].includes(input.priority) ? input.priority : "normal",
+    metadata: input.metadata && typeof input.metadata === "object" ? input.metadata : {},
+    attempts: typeof input.attempts === "number" ? input.attempts : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Consume
+// ---------------------------------------------------------------------------
+
+/**
+ * List inbox event ids in chronological order. Returns ids without `.json`.
+ */
+export function listInbox(agentRoot) {
+  const paths = getBusPaths(agentRoot);
+  if (!existsSync(paths.inbox)) return [];
+  return readdirSync(paths.inbox)
+    .filter((n) => n.endsWith(".json") && !n.endsWith(".tmp"))
+    .sort()
+    .map((n) => n.slice(0, -5));
+}
+
+/**
+ * List currently-claimed event ids. Used by stale-claim recovery.
+ */
+export function listClaimed(agentRoot) {
+  const paths = getBusPaths(agentRoot);
+  if (!existsSync(paths.claimed)) return [];
+  return readdirSync(paths.claimed)
+    .filter((n) => n.endsWith(".json") && !n.endsWith(".tmp"))
+    .sort()
+    .map((n) => n.slice(0, -5));
+}
+
+/**
+ * Atomically claim the oldest inbox event for processing. Returns the parsed
+ * event payload (with absolute paths attached), or null if the inbox was
+ * empty / all candidates lost the race.
+ *
+ * Other consumers racing for the same event will see ENOENT on rename and
+ * naturally move on.
+ */
+export function claimNextTick(agentRoot) {
+  const paths = ensureBusDirs(agentRoot);
+  const ids = listInbox(paths.agentRoot);
+  for (const id of ids) {
+    const src = join(paths.inbox, `${id}.json`);
+    const dst = join(paths.claimed, `${id}.json`);
+    try {
+      renameSync(src, dst);
+    } catch (err) {
+      if (err.code === "ENOENT") continue; // someone else claimed it
+      throw err;
+    }
+    // Load the event from its claimed path. If it's malformed, fail it and
+    // try the next one.
+    let event;
+    try {
+      event = JSON.parse(readFileSync(dst, "utf-8"));
+    } catch (err) {
+      logBusEvent(paths.agentRoot, {
+        level: "error",
+        stage: "claim_parse_failed",
+        id,
+        error: err.message,
+      });
+      failTick(paths.agentRoot, id, `parse-failed: ${err.message}`);
+      continue;
+    }
+    // Attempt accounting is single-sourced in failTick (audit M5). Claiming
+    // an event is NOT a failed attempt, so claim must not mutate `attempts`
+    // — otherwise a successful first run would have already burned one unit
+    // of retry budget, and a crash-then-recover would double-count it.
+    // Normalise the field so downstream readers always see a number.
+    if (typeof event.attempts !== "number") {
+      event.attempts = 0;
+    }
+    logBusEvent(paths.agentRoot, {
+      level: "info",
+      stage: "claimed",
+      id,
+      cadence: event.cadence,
+      attempts: event.attempts,
+    });
+    return { event, claimedPath: dst };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle transitions
+// ---------------------------------------------------------------------------
+
+function moveClaimed(paths, id, destDir, suffix = ".json") {
+  const src = join(paths.claimed, `${id}.json`);
+  mkdirSync(destDir, { recursive: true });
+  const dst = join(destDir, `${id}${suffix}`);
+  if (!existsSync(src)) return null;
+  renameSync(src, dst);
+  return dst;
+}
+
+/**
+ * Has an event id already been archived under processed/<date>/? Used by
+ * enqueueTick to suppress re-running a cadence that already completed when a
+ * producer replays an explicit id after a reconnect (H12). Scans the dated
+ * processed/ subdirectories for <id>.json.
+ *
+ * @param {string} agentRoot
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isProcessedId(agentRoot, id) {
+  const paths = getBusPaths(agentRoot);
+  if (!existsSync(paths.processed)) return false;
+  let dateDirs;
+  try {
+    dateDirs = readdirSync(paths.processed, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const d of dateDirs) {
+    if (!d.isDirectory()) continue;
+    if (existsSync(join(paths.processed, d.name, `${id}.json`))) return true;
+  }
+  return false;
+}
+
+/**
+ * Mark a claimed event as successfully processed. Moves it to
+ * processed/<YYYY-MM-DD>/<id>.json and stores the handler result alongside.
+ */
+export function completeTick(agentRoot, id, result = {}) {
+  const paths = ensureBusDirs(agentRoot);
+  const date = todayUtc();
+  const dst = moveClaimed(paths, id, join(paths.processed, date));
+  if (!dst) {
+    logBusEvent(paths.agentRoot, { level: "warn", stage: "complete_missing", id });
+    return null;
+  }
+  // Annotate the archived event with the result. Best-effort, but observable:
+  // this write carries the handler result + completed_at audit fields, so a
+  // silent failure would leave the processed/ record unannotated — log it.
+  try {
+    const event = JSON.parse(readFileSync(dst, "utf-8"));
+    event.result = result;
+    event.completed_at = new Date().toISOString();
+    writeJsonAtomic(dst, event);
+  } catch (err) {
+    logBusEvent(paths.agentRoot, {
+      level: "warn",
+      stage: "best_effort_write_failed",
+      op: "complete_annotate",
+      id,
+      error: err.message,
+    });
+  }
+  logBusEvent(paths.agentRoot, {
+    level: "info",
+    stage: "processed",
+    id,
+    cadence: result.cadence || null,
+    decision: result.decision || null,
+    duration_ms: result.duration_ms ?? null,
+  });
+  return dst;
+}
+
+/**
+ * Mark a claimed event as failed. If under the retry budget, returns it to
+ * inbox/ for another attempt; otherwise routes to dlq/.
+ */
+export function failTick(agentRoot, id, errorOrReason, opts = {}) {
+  const paths = ensureBusDirs(agentRoot);
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const srcClaimed = join(paths.claimed, `${id}.json`);
+  let event = null;
+  if (existsSync(srcClaimed)) {
+    try { event = JSON.parse(readFileSync(srcClaimed, "utf-8")); } catch { /* */ }
+  }
+  if (!event) {
+    // Caller already moved or never had a claim; nothing to do.
+    logBusEvent(paths.agentRoot, { level: "warn", stage: "fail_missing", id });
+    return null;
+  }
+  event.last_error = typeof errorOrReason === "string"
+    ? errorOrReason
+    : (errorOrReason?.message || String(errorOrReason));
+  event.failed_at = new Date().toISOString();
+
+  // Single source of truth for attempt accounting (audit M5). A failed
+  // attempt is the ONLY thing that increments `attempts`; claim/consumer
+  // never touch it. Increment first, then compare against the budget so the
+  // count reflects the attempt that just failed.
+  const attempts = (typeof event.attempts === "number" ? event.attempts : 0) + 1;
+  event.attempts = attempts;
+
+  if (attempts >= maxAttempts || opts.terminal === true) {
+    // Move to dlq/. Persist the bumped count + last_error onto the claimed
+    // file first so the archived dlq payload reflects the final attempt.
+    // Best-effort, but observable: this write carries the attempt count that
+    // justified the DLQ decision, so a silent failure would archive a stale
+    // payload — log it instead of swallowing.
+    try {
+      writeJsonAtomic(srcClaimed, event);
+    } catch (err) {
+      logBusEvent(paths.agentRoot, {
+        level: "warn",
+        stage: "best_effort_write_failed",
+        op: "dlq_persist_attempts",
+        id,
+        cadence: event.cadence,
+        attempts,
+        error: err.message,
+      });
+    }
+    moveClaimed(paths, id, paths.dlq);
+    logBusEvent(paths.agentRoot, {
+      level: "error",
+      stage: "dlq",
+      id,
+      cadence: event.cadence,
+      attempts,
+      reason: event.last_error,
+    });
+    return { destination: "dlq" };
+  }
+
+  // Re-enqueue: write fresh in inbox/, drop the claim. Guarded (audit M7):
+  // if the inbox write fails (ENOSPC / EACCES), leave the claim in place so
+  // the next stale-claim recovery sweep retries it, rather than throwing out
+  // of failTick and losing the event entirely.
+  const newTarget = join(paths.inbox, `${id}.json`);
+  try {
+    writeJsonAtomic(newTarget, event);
+  } catch (err) {
+    logBusEvent(paths.agentRoot, {
+      level: "error",
+      stage: "retry_requeue_failed",
+      id,
+      cadence: event.cadence,
+      attempts,
+      error: err.message,
+    });
+    return { destination: "claimed", error: err.message };
+  }
+  try { unlinkSync(srcClaimed); } catch { /* */ }
+  logBusEvent(paths.agentRoot, {
+    level: "warn",
+    stage: "retry_requeued",
+    id,
+    cadence: event.cadence,
+    attempts,
+    reason: event.last_error,
+  });
+  return { destination: "inbox" };
+}
+
+/**
+ * Atomically re-enqueue an already-loaded event object back onto inbox/ and
+ * drop its claim (audit M6). Used by the consumer's circuit-open / deferred
+ * re-queue paths so they go through the same write-temp-then-rename primitive
+ * as every other bus write instead of a bare writeFileSync.
+ *
+ * Does NOT touch `event.attempts` — re-queueing because of an upstream gate
+ * (circuit open, concurrency cap) is not a failed attempt, and attempt
+ * accounting is single-sourced in failTick (M5). The caller passes the event
+ * exactly as it wants it re-queued.
+ *
+ * Best-effort: on a write failure the claim is left in place so stale-claim
+ * recovery can retry it. Returns true if the event landed in inbox/.
+ *
+ * @param {string} agentRoot
+ * @param {object} event  Must include `id`.
+ * @returns {boolean}
+ */
+export function requeueTick(agentRoot, event) {
+  if (!event || typeof event !== "object" || !event.id) {
+    throw new TypeError("requeueTick: event with an id is required");
+  }
+  const paths = ensureBusDirs(agentRoot);
+  const target = join(paths.inbox, `${event.id}.json`);
+  try {
+    writeJsonAtomic(target, event);
+  } catch (err) {
+    logBusEvent(paths.agentRoot, {
+      level: "error",
+      stage: "requeue_failed",
+      id: event.id,
+      cadence: event.cadence,
+      error: err.message,
+    });
+    return false;
+  }
+  try { unlinkSync(join(paths.claimed, `${event.id}.json`)); } catch { /* */ }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Stale claim recovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Sweep claimed/ for entries older than `maxAgeMs`. Each stale claim is
+ * either returned to inbox/ (under the retry budget) or moved to dlq/.
+ * Safe to run on consumer startup *and* periodically while running, because
+ * the consumer is the only writer to claimed/.
+ *
+ * Returns the count of events recovered + count moved to dlq.
+ */
+export function recoverStaleClaims(agentRoot, maxAgeMs = DEFAULT_STALE_CLAIM_MS, now = Date.now()) {
+  const paths = ensureBusDirs(agentRoot);
+  const stats = { recovered: 0, dlq: 0, scanned: 0 };
+  if (!existsSync(paths.claimed)) return stats;
+  for (const name of readdirSync(paths.claimed)) {
+    if (!name.endsWith(".json")) continue;
+    stats.scanned++;
+    const claimedPath = join(paths.claimed, name);
+    let st;
+    try { st = statSync(claimedPath); } catch { continue; }
+    if (now - st.mtimeMs < maxAgeMs) continue;
+
+    const id = name.slice(0, -5);
+    const outcome = failTick(paths.agentRoot, id, "stale-claim-recovery", {
+      maxAttempts: DEFAULT_MAX_ATTEMPTS,
+    });
+    if (outcome?.destination === "dlq") stats.dlq++;
+    else if (outcome?.destination === "inbox") stats.recovered++;
+  }
+  if (stats.scanned > 0) {
+    logBusEvent(paths.agentRoot, {
+      level: "info",
+      stage: "stale_recovery_complete",
+      ...stats,
+    });
+  }
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Retention sweep (audit M8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Best-effort: list directory entries, or [] on any error.
+ */
+function safeReaddir(dir, opts) {
+  try { return readdirSync(dir, opts); } catch { return []; }
+}
+
+/**
+ * Prune unbounded bus growth. Designed to run on the same periodic timer as
+ * recoverStaleClaims. EVERY step is wrapped so a single failure (permissions,
+ * a file vanishing mid-sweep, ENOSPC on a temp write) can never throw out of
+ * the sweep and kill the recovery loop.
+ *
+ * Steps:
+ *   1. Delete processed/<YYYY-MM-DD>/ dirs older than `processedDays`
+ *      (default 14, env MAESTRO_RETENTION_DAYS, opts.processedDays).
+ *   2. Cap dlq/ and failed/ to the newest `terminalKeep` files (default 500,
+ *      opts.terminalKeep). Oldest are unlinked first.
+ *   3. Rotate/truncate queue.jsonl if it exceeds `queueMaxBytes` (~5MB),
+ *      keeping the tail so recent audit rows survive.
+ *   4. Delete logs/cadence-bus/<YYYY-MM-DD>.jsonl older than `logDays`.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts]
+ * @param {number} [opts.processedDays]
+ * @param {number} [opts.terminalKeep]
+ * @param {number} [opts.queueMaxBytes]
+ * @param {number} [opts.logDays]
+ * @param {number} [opts.now]  injectable clock (ms) for tests
+ * @returns {{processedDirsDeleted:number, dlqDeleted:number, failedDeleted:number, queueRotated:boolean, logsDeleted:number, errors:number}}
+ */
+export function sweepRetention(agentRoot, opts = {}) {
+  const stats = {
+    processedDirsDeleted: 0,
+    dlqDeleted: 0,
+    failedDeleted: 0,
+    queueRotated: false,
+    logsDeleted: 0,
+    errors: 0,
+  };
+
+  let paths;
+  try {
+    paths = getBusPaths(agentRoot);
+  } catch {
+    stats.errors++;
+    return stats;
+  }
+
+  const now = typeof opts.now === "number" ? opts.now : Date.now();
+  const envDays = Number(process.env.MAESTRO_RETENTION_DAYS);
+  const processedDays =
+    Number.isFinite(opts.processedDays) ? opts.processedDays
+    : Number.isFinite(envDays) ? envDays
+    : DEFAULT_PROCESSED_RETENTION_DAYS;
+  const terminalKeep = Number.isFinite(opts.terminalKeep) ? opts.terminalKeep : DEFAULT_TERMINAL_KEEP;
+  const queueMaxBytes = Number.isFinite(opts.queueMaxBytes) ? opts.queueMaxBytes : DEFAULT_QUEUE_MAX_BYTES;
+  const logDays = Number.isFinite(opts.logDays) ? opts.logDays : DEFAULT_LOG_RETENTION_DAYS;
+
+  // --- 1. processed/<date>/ dirs older than processedDays --------------------
+  try {
+    const cutoff = now - processedDays * 24 * 60 * 60 * 1000;
+    for (const ent of safeReaddir(paths.processed, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      // Date dirs are named YYYY-MM-DD. Parse to a UTC midnight timestamp;
+      // fall back to mtime for anything that doesn't match the pattern.
+      let dirMs;
+      const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(ent.name);
+      if (m) {
+        dirMs = Date.parse(`${ent.name}T00:00:00.000Z`);
+      }
+      const full = join(paths.processed, ent.name);
+      if (!Number.isFinite(dirMs)) {
+        try { dirMs = statSync(full).mtimeMs; } catch { continue; }
+      }
+      if (dirMs < cutoff) {
+        try {
+          rmSync(full, { recursive: true, force: true });
+          stats.processedDirsDeleted++;
+        } catch { stats.errors++; }
+      }
+    }
+  } catch { stats.errors++; }
+
+  // --- 2. cap dlq/ and failed/ to newest terminalKeep ------------------------
+  for (const [dir, key] of [[paths.dlq, "dlqDeleted"], [paths.failed, "failedDeleted"]]) {
+    try {
+      const files = safeReaddir(dir).filter((n) => n.endsWith(".json"));
+      if (files.length <= terminalKeep) continue;
+      // Sort by mtime ascending (oldest first); delete the overflow.
+      const withTimes = [];
+      for (const n of files) {
+        const full = join(dir, n);
+        let mtime = 0;
+        try { mtime = statSync(full).mtimeMs; } catch { continue; }
+        withTimes.push({ full, mtime });
+      }
+      withTimes.sort((a, b) => a.mtime - b.mtime);
+      const toDelete = withTimes.length - terminalKeep;
+      for (let i = 0; i < toDelete; i++) {
+        try {
+          unlinkSync(withTimes[i].full);
+          stats[key]++;
+        } catch { stats.errors++; }
+      }
+    } catch { stats.errors++; }
+  }
+
+  // --- 3. rotate/truncate queue.jsonl if oversized ---------------------------
+  try {
+    if (existsSync(paths.queueJsonl)) {
+      let size = 0;
+      try { size = statSync(paths.queueJsonl).size; } catch { size = 0; }
+      if (size > queueMaxBytes) {
+        // Keep the tail (most recent rows). Read the last ~half of the cap so
+        // the file shrinks well below the threshold and recent audit context
+        // survives. Best-effort; on read failure fall back to truncating.
+        let tail = "";
+        try {
+          const buf = readFileSync(paths.queueJsonl, "utf-8");
+          const keepBytes = Math.floor(queueMaxBytes / 2);
+          tail = buf.slice(-keepBytes);
+          // Drop a partial leading line so the file stays valid JSONL.
+          const nl = tail.indexOf("\n");
+          if (nl >= 0) tail = tail.slice(nl + 1);
+        } catch { tail = ""; }
+        try {
+          if (tail) {
+            writeFileSync(paths.queueJsonl, tail);
+          } else {
+            truncateSync(paths.queueJsonl, 0);
+          }
+          stats.queueRotated = true;
+        } catch { stats.errors++; }
+      }
+    }
+  } catch { stats.errors++; }
+
+  // --- 4. logs/cadence-bus/<date>.jsonl older than logDays -------------------
+  try {
+    const cutoff = now - logDays * 24 * 60 * 60 * 1000;
+    for (const n of safeReaddir(paths.logsDir)) {
+      const m = /^(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(n);
+      if (!m) continue;
+      const fileMs = Date.parse(`${m[1]}T00:00:00.000Z`);
+      if (!Number.isFinite(fileMs)) continue;
+      if (fileMs < cutoff) {
+        try {
+          unlinkSync(join(paths.logsDir, n));
+          stats.logsDeleted++;
+        } catch { stats.errors++; }
+      }
+    }
+  } catch { stats.errors++; }
+
+  // Audit row — best-effort, never throws (logBusEvent swallows its own I/O).
+  if (
+    stats.processedDirsDeleted || stats.dlqDeleted || stats.failedDeleted ||
+    stats.queueRotated || stats.logsDeleted || stats.errors
+  ) {
+    logBusEvent(paths.agentRoot, { level: "info", stage: "retention_sweep", ...stats });
+  }
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Heartbeat
+// ---------------------------------------------------------------------------
+
+/**
+ * Write the consumer's heartbeat state. Doctor / healthcheck reads this to
+ * confirm the persistent main session is alive.
+ */
+export function writeHealth(agentRoot, state = {}) {
+  const paths = ensureBusDirs(agentRoot);
+  const payload = {
+    version: BUS_VERSION,
+    ts: new Date().toISOString(),
+    pid: process.pid,
+    ...state,
+  };
+  try {
+    writeJsonAtomic(paths.health, payload);
+  } catch {
+    /* best-effort */
+  }
+  return payload;
+}
+
+/**
+ * Read the consumer's heartbeat state. Returns null if missing or unreadable.
+ */
+export function readHealth(agentRoot) {
+  const paths = getBusPaths(agentRoot);
+  if (!existsSync(paths.health)) return null;
+  try {
+    return JSON.parse(readFileSync(paths.health, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inspect bus depth — counts of events at each stage. Used by doctor and
+ * tests; cheap enough to call frequently.
+ */
+export function busDepth(agentRoot) {
+  const paths = getBusPaths(agentRoot);
+  const dirCount = (d) => existsSync(d) ? readdirSync(d).filter((n) => n.endsWith(".json")).length : 0;
+  return {
+    inbox: dirCount(paths.inbox),
+    claimed: dirCount(paths.claimed),
+    dlq: dirCount(paths.dlq),
+    failed: dirCount(paths.failed),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI usability
+// ---------------------------------------------------------------------------
+
+/**
+ * Touch each bus directory so a fresh checkout/install has the expected
+ * shape on disk. Equivalent to calling ensureBusDirs + readHealth probe
+ * + writing a `.gitkeep` per dir so empty-bus repos still track structure.
+ */
+export function bootstrapBus(agentRoot) {
+  const paths = ensureBusDirs(agentRoot);
+  for (const dir of [paths.inbox, paths.claimed, paths.processed, paths.failed, paths.dlq, paths.logsDir]) {
+    const keep = join(dir, ".gitkeep");
+    if (!existsSync(keep)) {
+      try { closeSync(openSync(keep, "a")); } catch { /* ignore */ }
+    }
+  }
+  return paths;
+}