@adaptic/maestro 1.7.2 → 1.8.0

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

@@ -0,0 +1,397 @@
+/**
+ * cadence-consumer.test.mjs — node:test coverage for the cadence consumer.
+ *
+ * Uses startConsumer({ spawnSession }) to inject a stub sub-session spawner
+ * so no real Claude Code process is ever launched. Each test creates its own
+ * AGENT_ROOT under tmpdir() and tears it down afterwards.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, dirname } from "path";
+
+import { enqueueTick, listInbox, listClaimed, busDepth, getBusPaths } from "../../lib/cadence-bus.mjs";
+import { startConsumer } from "./cadence-consumer.mjs";
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `cadence-consumer-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+/**
+ * Seed an agent root with a trigger prompt for a given cadence. Lets the
+ * consumer's "escalate" path find a real prompt file when our stub spawner
+ * is invoked.
+ */
+function plantPrompt(root, cadence, body = `# ${cadence} trigger prompt`) {
+  const path = join(root, "schedules/triggers", `${cadence}.md`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body);
+  return path;
+}
+
+/**
+ * Wait until `predicate()` returns truthy or the deadline expires. Polls
+ * every 25ms — fast enough for sub-200ms drain cycles, slow enough that
+ * tests don't burn CPU.
+ */
+async function waitFor(predicate, { timeoutMs = 5_000, intervalMs = 25 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await predicate()) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Inline handlers
+// ---------------------------------------------------------------------------
+
+test("consumer processes a registry-inline cadence without spawning", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    heartbeatMs: 1_000,
+    recoveryMs: 60_000,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    enqueueTick({ cadence: "cadence-bus-heartbeat", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().inline >= 1);
+    assert.ok(ok, "heartbeat cadence should drain inline");
+    assert.equal(spawnCalls.length, 0, "inline cadence must not spawn");
+    assert.equal(busDepth(root).inbox, 0);
+    assert.equal(busDepth(root).claimed, 0);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Guarded handlers
+// ---------------------------------------------------------------------------
+
+test("guarded cadence completes inline when there's no work", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    // No inbox files, no queues with items → guard returns "inline".
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().inline >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 0, "inbox empty → no spawn");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("guarded cadence escalates when guard says work is pending", async () => {
+  const root = await makeAgentRoot();
+  // Seed an inbox item so the inbox-processor guard returns "escalate".
+  mkdirSync(join(root, "state/inbox/slack"), { recursive: true });
+  writeFileSync(join(root, "state/inbox/slack/item.json"), JSON.stringify({ id: "msg1" }));
+  plantPrompt(root, "inbox-processor");
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0, duration_ms: 5 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok, "guard with pending work should escalate");
+    assert.equal(spawnCalls.length, 1);
+    assert.equal(spawnCalls[0].cadence, "inbox-processor");
+    assert.match(spawnCalls[0].promptPath, /schedules\/triggers\/inbox-processor\.md$/);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Escalate path
+// ---------------------------------------------------------------------------
+
+test("escalate-mode cadence spawns with the configured prompt", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0, duration_ms: 10 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls[0].cadence, "weekly-strategic-memo");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("unknown cadence with a prompt file falls back to escalate", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "custom-cadence");
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => {
+      spawnCalls.push(opts);
+      return { ok: true, exit_code: 0 };
+    },
+  });
+  try {
+    enqueueTick({ cadence: "custom-cadence", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().escalated >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("unknown cadence with no prompt file DLQ's immediately", async () => {
+  const root = await makeAgentRoot();
+  const spawnCalls = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async (opts) => { spawnCalls.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "totally-unknown-thing", source: "manual", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().dlq >= 1);
+    assert.ok(ok);
+    assert.equal(spawnCalls.length, 0);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Spawn failures
+// ---------------------------------------------------------------------------
+
+test("spawn failure retries within the budget, then DLQs", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "weekly-strategic-memo");
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 25,
+    spawnSession: async () => ({ ok: false, exit_code: 1, error: "always-fail", duration_ms: 1 }),
+  });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => consumer.getStats().dlq >= 1, { timeoutMs: 15_000 });
+    assert.ok(ok, `event should DLQ eventually; stats=${JSON.stringify(consumer.getStats())}`);
+    assert.ok(consumer.getStats().spawn_failures >= 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Emergency stop
+// ---------------------------------------------------------------------------
+
+test("consumer skips processing while .emergency-stop exists", async () => {
+  const root = await makeAgentRoot();
+  writeFileSync(join(root, ".emergency-stop"), "now");
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 50,
+    spawnSession: async () => { spawnCount++; return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    // Enqueue directly to the inbox: the bus's emergency-stop check is on
+    // enqueue, so we must bypass it. Drop a file straight in inbox/.
+    const paths = getBusPaths(root);
+    writeFileSync(join(paths.inbox, "evt-test.json"), JSON.stringify({
+      id: "evt-test", type: "cadence_tick", source: "manual", ts: new Date().toISOString(),
+      cadence: "weekly-strategic-memo", workflow: null, correlation_id: null,
+      priority: "normal", metadata: {}, attempts: 0,
+    }));
+    await new Promise((r) => setTimeout(r, 300));
+    const stats = consumer.getStats();
+    assert.equal(spawnCount, 0, "no spawn during emergency stop");
+    assert.ok(stats.skipped_emergency_stop >= 1);
+    assert.equal(listInbox(root).length, 1, "event remains in inbox until stop lifts");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+test("consumer resumes after .emergency-stop is removed", async () => {
+  const root = await makeAgentRoot();
+  writeFileSync(join(root, ".emergency-stop"), "now");
+  plantPrompt(root, "weekly-strategic-memo");
+  let spawnCount = 0;
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 25,
+    spawnSession: async () => { spawnCount++; return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    const paths = getBusPaths(root);
+    writeFileSync(join(paths.inbox, "evt-test.json"), JSON.stringify({
+      id: "evt-test", type: "cadence_tick", source: "manual", ts: new Date().toISOString(),
+      cadence: "weekly-strategic-memo", workflow: null, correlation_id: null,
+      priority: "normal", metadata: {}, attempts: 0,
+    }));
+    await new Promise((r) => setTimeout(r, 200));
+    assert.equal(spawnCount, 0);
+    // Lift the stop.
+    await fsp.unlink(join(root, ".emergency-stop"));
+    const ok = await waitFor(() => spawnCount >= 1);
+    assert.ok(ok, "should process after stop lifts");
+    assert.ok(consumer.getStats().escalated >= 1);
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Stale claim recovery on tick
+// ---------------------------------------------------------------------------
+
+test("consumer recovers stale claims on its periodic sweep", async () => {
+  const root = await makeAgentRoot();
+  // Plant a stale claim directly.
+  const paths = getBusPaths(root);
+  mkdirSync(paths.claimed, { recursive: true });
+  const stalePath = join(paths.claimed, "evt-stale.json");
+  writeFileSync(stalePath, JSON.stringify({
+    id: "evt-stale", cadence: "cadence-bus-heartbeat",
+    source: "manual", ts: "2026-01-01T00:00:00.000Z",
+    workflow: null, correlation_id: null, priority: "normal",
+    metadata: {}, attempts: 1, type: "cadence_tick",
+  }));
+  const oldMs = Date.now() - 60 * 60 * 1000; // 1h old
+  await fsp.utimes(stalePath, new Date(oldMs), new Date(oldMs));
+
+  const consumer = startConsumer({
+    agentRoot: root, pollMs: 50,
+    spawnSession: async () => ({ ok: true, exit_code: 0 }),
+  });
+  try {
+    // tickOnce manually so we don't depend on the periodic recovery timer.
+    await consumer.tickOnce();
+    const ok = await waitFor(() => consumer.getStats().inline >= 1, { timeoutMs: 5_000 });
+    assert.ok(ok, "stale claim should be recovered and processed");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Health
+// ---------------------------------------------------------------------------
+
+test("consumer writes a heartbeat to state/cadence-bus/health.json", async () => {
+  const root = await makeAgentRoot();
+  const consumer = startConsumer({
+    agentRoot: root,
+    pollMs: 100,
+    heartbeatMs: 50, // force frequent heartbeats so the test doesn't drag
+    spawnSession: async () => ({ ok: true, exit_code: 0 }),
+  });
+  try {
+    const ok = await waitFor(async () => {
+      try {
+        const raw = await fsp.readFile(join(root, "state/cadence-bus/health.json"), "utf-8");
+        const h = JSON.parse(raw);
+        return typeof h.ts === "string" && h.version;
+      } catch { return false; }
+    });
+    assert.ok(ok, "health.json must be written");
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Sub-session policy boundary
+// ---------------------------------------------------------------------------
+
+test("explicit reason is attached to event metadata before escalation", async () => {
+  // The consumer must surface WHY a sub-session was spawned. For guarded
+  // cadences this comes from the guard's reason/result. For unknown
+  // cadences with prompts, the registry policy log line is sufficient,
+  // but for audit visibility we attach guard data to event.metadata.
+  const root = await makeAgentRoot();
+  // Force a guard:escalate outcome via inbox-processor with pending items.
+  mkdirSync(join(root, "state/inbox/internal"), { recursive: true });
+  writeFileSync(join(root, "state/inbox/internal/x.json"), "{}");
+  plantPrompt(root, "inbox-processor");
+  const seen = [];
+  const consumer = startConsumer({
+    agentRoot: root, pollMs: 50,
+    spawnSession: async (opts) => { seen.push(opts); return { ok: true, exit_code: 0 }; },
+  });
+  try {
+    enqueueTick({ cadence: "inbox-processor", source: "launchd", agentRoot: root });
+    const ok = await waitFor(() => seen.length > 0);
+    assert.ok(ok);
+    // The event archive should record guard_result so future audits can
+    // trace why the sub-session ran.
+    const procDir = join(root, "state/cadence-bus/processed");
+    // Drill down by date
+    const dates = (await fsp.readdir(procDir)).filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n));
+    assert.ok(dates.length >= 1);
+    const files = await fsp.readdir(join(procDir, dates[0]));
+    const archive = JSON.parse(await fsp.readFile(join(procDir, dates[0], files[0]), "utf-8"));
+    assert.equal(archive.result.decision, "escalated");
+    // The consumer attaches the guard's outcome to the event metadata so
+    // audits can trace exactly why a sub-session ran. We expect either a
+    // recorded reason string or the full guard object.
+    assert.ok(
+      archive.metadata && (archive.metadata.reason || archive.metadata.guard),
+      `expected metadata.reason or metadata.guard; got ${JSON.stringify(archive.metadata)}`,
+    );
+  } finally {
+    await consumer.stop();
+    await rmRoot(root);
+  }
+});

package/scripts/daemon/cadence-handlers.mjs

@@ -0,0 +1,263 @@
+/**
+ * Maestro — Cadence Handler Registry
+ *
+ * Per-cadence policy for how the persistent main session services an event
+ * delivered onto the cadence bus.
+ *
+ * Three handler modes:
+ *
+ *   "inline"    — Handler runs entirely inside the persistent main Node
+ *                 process. No Claude Code spawned. Use for housekeeping
+ *                 (dashboard refresh, log rotation, queue sweeps that need
+ *                 no reasoning).
+ *
+ *   "guarded"   — Persistent process runs a lightweight pre-check (e.g.
+ *                 "is there anything in the inbox?") and only escalates to
+ *                 a sub-session if substantive work is required. If the
+ *                 pre-check says "no work", the tick completes inline.
+ *
+ *   "escalate"  — The cadence always needs Claude-grade reasoning or
+ *                 substantive drafting; the consumer spawns a sub-session
+ *                 with the trigger prompt under schedules/triggers/<name>.md.
+ *                 Reserved for substantive drafting, multi-step outreach,
+ *                 large audits, research, and explicit isolated audit
+ *                 boundaries.
+ *
+ * Handlers / guards receive ({ event, agentRoot, log }) and return a result
+ * object that becomes part of the processed event's archive record. They
+ * must not throw — return { ok:false, error } so the consumer can decide to
+ * retry or DLQ via its policy.
+ *
+ * Adding a new cadence: add an entry below. If you skip an entry the
+ * consumer falls back to escalate behaviour as long as a trigger prompt
+ * exists at schedules/triggers/<cadence>.md; otherwise it DLQ's the event
+ * with a clear error.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { recoverStaleClaims } from "../../lib/cadence-bus.mjs";
+
+// ---------------------------------------------------------------------------
+// Pre-check helpers (shared across guarded handlers)
+// ---------------------------------------------------------------------------
+
+/**
+ * Count files in a directory matching an optional regex. Returns 0 if the
+ * directory doesn't exist (idiomatic for fresh agent repos).
+ */
+function countFiles(dir, re) {
+  if (!existsSync(dir)) return 0;
+  try {
+    const all = readdirSync(dir);
+    return re ? all.filter((n) => re.test(n)).length : all.length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Return queue file names that contain at least one "- " entry. Avoids a
+ * YAML parser dep: cheap line-scan, plenty good enough for a guard.
+ */
+function queuesWithWork(agentRoot) {
+  const dir = join(agentRoot, "state", "queues");
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".yaml")) continue;
+    try {
+      const body = readFileSync(join(dir, name), "utf-8");
+      if (/^- /m.test(body)) out.push(name);
+    } catch { /* ignore */ }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Inline handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Heartbeat tick — purely internal. The consumer writes health.json on
+ * every cycle anyway; this handler exists so external schedulers (init,
+ * upgrade, doctor) can drop a heartbeat into the bus to verify end-to-end
+ * delivery.
+ */
+async function handleHeartbeat({ event }) {
+  return {
+    ok: true,
+    decision: "inline",
+    cadence: event.cadence,
+    note: "heartbeat acknowledged",
+  };
+}
+
+/**
+ * Stale-claim recovery — the consumer already does this on startup and
+ * periodically; an explicit cadence event lets ops force a sweep without
+ * restarting the daemon.
+ */
+async function handleStaleRecovery({ event, agentRoot }) {
+  const stats = recoverStaleClaims(agentRoot);
+  return { ok: true, decision: "inline", cadence: event.cadence, stats };
+}
+
+// ---------------------------------------------------------------------------
+// Guarded handlers — cheap pre-check, escalate only when there's work
+// ---------------------------------------------------------------------------
+
+/**
+ * inbox-processor guard:
+ *   - Count items under state/inbox/{slack,gmail,calendar,internal,sms,whatsapp}
+ *     that have NOT been moved to state/inbox/processed/.
+ *   - If 0, complete inline (saves a Claude Code spawn).
+ *   - If >0, escalate so a sub-session can classify and route them.
+ */
+async function guardInboxProcessor({ agentRoot }) {
+  const inboxRoot = join(agentRoot, "state", "inbox");
+  const sources = ["slack", "gmail", "calendar", "internal", "sms", "whatsapp"];
+  let pending = 0;
+  for (const src of sources) {
+    pending += countFiles(join(inboxRoot, src), /\.(json|ya?ml)$/i);
+  }
+  if (pending === 0) {
+    return { ok: true, decision: "inline", reason: "inbox empty", pending: 0 };
+  }
+  return { ok: true, decision: "escalate", pending };
+}
+
+/**
+ * backlog-executor guard:
+ *   - Look at state/queues/*.yaml; any queue with at least one item is work.
+ *   - If none, complete inline.
+ *   - If any, escalate.
+ */
+async function guardBacklogExecutor({ agentRoot }) {
+  const withWork = queuesWithWork(agentRoot);
+  if (withWork.length === 0) {
+    return { ok: true, decision: "inline", reason: "all queues empty" };
+  }
+  return { ok: true, decision: "escalate", queues_with_work: withWork };
+}
+
+/**
+ * meeting-prep guard: only escalate if today's calendar inbox has any
+ * unprocessed event files. The cheap signal is just checking
+ * state/inbox/calendar/ for unprocessed entries.
+ */
+async function guardMeetingPrep({ agentRoot }) {
+  const dir = join(agentRoot, "state", "inbox", "calendar");
+  const pending = countFiles(dir, /\.(json|ya?ml)$/i);
+  if (pending === 0) {
+    return { ok: true, decision: "inline", reason: "no pending calendar events" };
+  }
+  return { ok: true, decision: "escalate", pending };
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export const CADENCE_REGISTRY = {
+  // Internal housekeeping (always inline)
+  "cadence-bus-heartbeat": {
+    mode: "inline",
+    handler: handleHeartbeat,
+    description: "Probe tick used by doctor / upgrade to verify end-to-end delivery.",
+  },
+  "cadence-bus-recovery": {
+    mode: "inline",
+    handler: handleStaleRecovery,
+    description: "On-demand stale-claim recovery.",
+  },
+
+  // Operational cadences with cheap pre-checks
+  "inbox-processor": {
+    mode: "guarded",
+    guard: guardInboxProcessor,
+    prompt: "schedules/triggers/inbox-processor.md",
+    description: "Classify / route inbound items if any are waiting.",
+  },
+  "backlog-executor": {
+    mode: "guarded",
+    guard: guardBacklogExecutor,
+    prompt: "schedules/triggers/backlog-executor.md",
+    description: "Execute the next slice of the proactive backlog if queues are non-empty.",
+  },
+  "meeting-prep": {
+    mode: "guarded",
+    guard: guardMeetingPrep,
+    prompt: "schedules/triggers/meeting-prep.md",
+    description: "Prepare for upcoming meetings when there are unprocessed calendar items.",
+  },
+
+  // Always-escalate (substantive reasoning / drafting required)
+  "meeting-action-capture": {
+    mode: "escalate",
+    prompt: "schedules/triggers/meeting-action-capture.md",
+    description: "Capture meeting action items into queues.",
+  },
+  "daily-morning-brief": {
+    mode: "escalate",
+    prompt: "schedules/triggers/daily-morning-brief.md",
+    description: "Daily morning brief.",
+  },
+  "daily-midday-sweep": {
+    mode: "escalate",
+    prompt: "schedules/triggers/daily-midday-sweep.md",
+    description: "Midday comms triage and queue sweep.",
+  },
+  "daily-evening-wrap": {
+    mode: "escalate",
+    prompt: "schedules/triggers/daily-evening-wrap.md",
+    description: "Evening wrap, log review, follow-up close.",
+  },
+  "weekly-hiring": {
+    mode: "escalate",
+    prompt: "schedules/triggers/weekly-hiring.md",
+    description: "Weekly hiring review.",
+  },
+  "weekly-priorities": {
+    mode: "escalate",
+    prompt: "schedules/triggers/weekly-priorities.md",
+    description: "Weekly priorities review.",
+  },
+  "weekly-engineering-health": {
+    mode: "escalate",
+    prompt: "schedules/triggers/weekly-engineering-health.md",
+    description: "Weekly engineering health.",
+  },
+  "weekly-execution": {
+    mode: "escalate",
+    prompt: "schedules/triggers/weekly-execution.md",
+    description: "Weekly execution review.",
+  },
+  "weekly-strategic-memo": {
+    mode: "escalate",
+    prompt: "schedules/triggers/weekly-strategic-memo.md",
+    description: "Weekly strategic memo drafting.",
+  },
+  "quarterly-self-assessment": {
+    mode: "escalate",
+    prompt: "schedules/triggers/quarterly-self-assessment.md",
+    description: "Quarterly self-assessment.",
+  },
+};
+
+/**
+ * Look up a cadence definition. Returns null for unknown cadences so the
+ * consumer can decide between inferred-escalate and DLQ based on prompt
+ * file availability.
+ */
+export function getCadenceDef(name) {
+  return CADENCE_REGISTRY[name] || null;
+}
+
+/**
+ * Convenience: list all registered cadence names. Used by doctor to confirm
+ * the consumer can route every cadence that the plist generator emits.
+ */
+export function listCadenceNames() {
+  return Object.keys(CADENCE_REGISTRY);
+}

package/scripts/daemon/maestro-daemon.mjs

@@ -34,5 +34,25 @@ try {
   }
 } catch { /* maestro singleton not available */ }
 
+// Start the cadence consumer alongside the reactive event loop. This is the
+// single persistent owner of cadence housekeeping — launchd plists enqueue
+// cadence ticks onto state/cadence-bus/ and the consumer drains them here,
+// either handling them inline or escalating to a sub-session when warranted.
+// Failure to start the consumer must NOT take the reactive daemon down, so
+// we isolate startup errors.
+try {
+  const { startConsumer } = await import("./cadence-consumer.mjs");
+  const consumer = startConsumer({ agentRoot: AGENT_DIR });
+  const shutdown = async (sig) => {
+    try { await consumer.stop(); } catch { /* ignore */ }
+    console.log(`[DAEMON] cadence consumer stopped (${sig})`);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+} catch (err) {
+  console.error(`[DAEMON] cadence consumer failed to start: ${err.message}`);
+  // Reactive daemon continues. Doctor / healthcheck will surface this.
+}
+
 // Import and run the daemon (handles its own .env loading)
 await import("./sophie-daemon.mjs");