@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/cadence-handlers.mjs

@@ -0,0 +1,1121 @@
+/**
+ * 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.
+ *
+ * Optional per-entry field `allowedTools` (audit H1): a string[] of the tool
+ * names the cadence's sub-session is permitted to use. This is consumed ONLY
+ * when the operator opts into scoped permissions
+ * (MAESTRO_SCOPED_PERMISSIONS=1) via lib/session-permissions.mjs; it is
+ * ignored otherwise (default behaviour stays --dangerously-skip-permissions).
+ * Cadences without the field fall back to a conservative read-only allowlist
+ * in scoped mode. Keep these lists as tight as the cadence genuinely needs.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { recoverStaleClaims } from "../../lib/cadence-bus.mjs";
+import { isQuarterStartMonth } from "../../lib/cadences.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// 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:
+ *   The reactive daemon (agent-daemon.mjs) continuously polls inbound
+ *   services + drains state/inbox/ + dispatches sessions via classifier
+ *   and dispatcher. Running the cadence-bus inbox-processor cadence on
+ *   top causes DOUBLE responses to the same message — observed in
+ *   ravi-ai when a CEO DM got TWO substantive replies (one from each
+ *   path) on 2026-05-12.
+ *
+ *   So this guard now always returns inline. The reactive daemon owns
+ *   inbox dispatch. Operators who want the cadence-only mode (no reactive
+ *   daemon) can set INBOX_CADENCE_ESCALATE=1 in .env to flip behaviour.
+ *
+ *   Pre-check is still done (count pending items) so the inline result
+ *   carries useful telemetry, but escalation is suppressed.
+ */
+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 (process.env.INBOX_CADENCE_ESCALATE === "1") {
+    if (pending === 0) {
+      return { ok: true, decision: "inline", reason: "inbox empty", pending: 0 };
+    }
+    return { ok: true, decision: "escalate", pending };
+  }
+  return {
+    ok: true,
+    decision: "inline",
+    reason: "reactive-daemon-owns-inbox",
+    pending,
+    note: "Set INBOX_CADENCE_ESCALATE=1 to override.",
+  };
+}
+
+/**
+ * backlog-executor guard:
+ *   The reactive daemon (agent-daemon.mjs) already runs an internal
+ *   backlog sweep every BACKLOG_INTERVAL (default 10min) which dispatches
+ *   one session per top-priority queue item with proper post-completion
+ *   cooldowns. Running the cadence-bus backlog-executor on top of that
+ *   spawns DUPLICATE sessions for the same items — observed as 159
+ *   redundant spawns / day in ravi-ai's logs.
+ *
+ *   So this guard now always returns inline. The reactive daemon owns
+ *   the backlog. Operators who prefer the cadence-only mode (no reactive
+ *   daemon) can set BACKLOG_CADENCE_ESCALATE=1 in .env to flip behaviour.
+ */
+async function guardBacklogExecutor({ agentRoot }) {
+  if (process.env.BACKLOG_CADENCE_ESCALATE === "1") {
+    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 };
+  }
+  return {
+    ok: true,
+    decision: "inline",
+    reason: "reactive-daemon-owns-backlog",
+    note: "Set BACKLOG_CADENCE_ESCALATE=1 to override.",
+  };
+}
+
+// --- skill-curator consolidation due-check (phase 2) -----------------------
+
+const CONSOLIDATION_STATE_REL = join("state", "learning", "consolidation.json");
+const CONSOLIDATE_WORKER_REL = join(__dirname, "..", "learning", "consolidate-skills.mjs");
+
+/** Read the last consolidation timestamp (ms). Fail-open → 0 (never run). */
+function readLastConsolidationAt(agentRoot) {
+  try {
+    const p = join(agentRoot, CONSOLIDATION_STATE_REL);
+    if (!existsSync(p)) return 0;
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    const t = Date.parse(obj && obj.lastConsolidationAt);
+    return Number.isFinite(t) ? t : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Persist the last consolidation timestamp atomically. Fail-open. */
+function writeLastConsolidationAt(agentRoot, nowMs) {
+  try {
+    const p = join(agentRoot, CONSOLIDATION_STATE_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ lastConsolidationAt: new Date(nowMs).toISOString() }, null, 2) + "\n");
+    renameSync(tmp, p);
+  } catch { /* fail-open */ }
+}
+
+/** Spawn the consolidation worker DETACHED + unref'd (mirrors hook-runner). Fail-open. */
+function spawnConsolidationWorker(agentRoot) {
+  try {
+    const child = spawn(process.execPath, [CONSOLIDATE_WORKER_REL], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, MAESTRO_CONSOLIDATE_ROOT: agentRoot },
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether an LLM umbrella-consolidation pass is DUE and, if so, spawn it
+ * DETACHED (never inline, never a nested sub-session). Gated on: config enabled,
+ * candidate count ≥ minSkills, and intervalDays since the last run. Returns a
+ * small descriptor for the guard's result. Injectable seams (tests):
+ *   o.now              — clock (ms)
+ *   o.spawnFn          — replace the detached spawner
+ *   o.candidateCountFn — replace the candidate counter (avoids touching disk)
+ * Fail-open: any throw → { spawned:false, reason:"error" }.
+ */
+async function maybeSpawnConsolidation(agentRoot, o = {}) {
+  try {
+    const nowMs = Number.isFinite(o.now) ? o.now : Date.now();
+    let minSkills = 5, intervalDays = 14, enabled = true;
+    try {
+      const cfgMod = await import("../../lib/learning/config.mjs");
+      const collMod = await import("../../lib/collective/config.mjs");
+      const coll = await collMod.loadConfig(agentRoot);
+      const cfg = await cfgMod.loadLearningConfig(agentRoot, coll);
+      const c = cfg && cfg.consolidation ? cfg.consolidation : {};
+      enabled = c.enabled !== false && cfg.enabled !== false;
+      if (Number.isFinite(c.minSkills)) minSkills = c.minSkills;
+      if (Number.isFinite(c.intervalDays)) intervalDays = c.intervalDays;
+    } catch { /* defaults */ }
+
+    if (!enabled) return { spawned: false, reason: "disabled" };
+
+    // (b) enough agent-authored active skills to be worth a clustering pass.
+    let candidateCount;
+    if (typeof o.candidateCountFn === "function") {
+      candidateCount = o.candidateCountFn(agentRoot);
+    } else {
+      const curator = await import("../../lib/learning/curator.mjs");
+      candidateCount = curator.selectConsolidationCandidates(agentRoot).length;
+    }
+    if (candidateCount < minSkills) return { spawned: false, reason: "below-threshold", candidateCount };
+
+    // (c) at least intervalDays since the last consolidation.
+    const last = readLastConsolidationAt(agentRoot);
+    const dueAt = last + intervalDays * 86400_000;
+    if (last && nowMs < dueAt) return { spawned: false, reason: "not-due", candidateCount };
+
+    const spawnFn = o.spawnFn || spawnConsolidationWorker;
+    const ok = spawnFn(agentRoot);
+    if (ok) writeLastConsolidationAt(agentRoot, nowMs); // mark even if the worker later no-ops (don't re-spawn each tick)
+    return { spawned: !!ok, reason: ok ? "spawned" : "spawn-failed", candidateCount };
+  } catch (err) {
+    return { spawned: false, reason: "error", error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * skill-curator guard (WS3): deterministic lifecycle housekeeping for the
+ * agent's self-authored skills, PLUS a periodic LLM umbrella-consolidation pass.
+ *
+ * Phase 1 (inline, no Claude): the cheap pre-check asks the sidecar whether ANY
+ * non-pinned skill has crossed a stale (30d) or archive (90d) boundary; if so we
+ * run the pure curator transitions INLINE (moving a .md into _archive/ and
+ * dropping it from plugin.json needs no reasoning).
+ *
+ * Phase 2 (detached worker, NOT a sub-session): when consolidation is DUE
+ * (enabled + ≥ minSkills agent-authored active skills + ≥ intervalDays since the
+ * last pass, tracked in state/learning/consolidation.json) we spawn
+ * scripts/learning/consolidate-skills.mjs as a DETACHED, unref'd child — the same
+ * fire-and-forget pattern as the collective capture worker. We do NOT block the
+ * consumer and do NOT escalate to a managed sub-session; the guard still returns
+ * `inline`. The LLM call lives entirely inside that detached worker.
+ */
+async function guardSkillCurator({ agentRoot, log }, opts = {}) {
+  try {
+    const curator = await import("../../lib/learning/curator.mjs");
+    let staleDays, archiveDays;
+    try {
+      const cfgMod = await import("../../lib/learning/config.mjs");
+      const collMod = await import("../../lib/collective/config.mjs");
+      const coll = await collMod.loadConfig(agentRoot);
+      const cfg = await cfgMod.loadLearningConfig(agentRoot, coll);
+      staleDays = cfg.staleDays; archiveDays = cfg.archiveDays;
+    } catch { /* fall back to curator defaults */ }
+
+    // Daily catch-up for the verbatim transcript store (the Stop-hook ingests
+    // per-session; this sweeps anything that machine missed). Best-effort.
+    try {
+      const sidx = await import("../../lib/learning/session-index.mjs");
+      await sidx.ingestAll({ agentRoot });
+    } catch { /* on-demand store; a missed sweep is harmless */ }
+
+    // Phase 1 — deterministic lifecycle transitions (inline).
+    let transitioned = [], archived = [];
+    if (curator.hasPendingTransitions(agentRoot, { staleDays, archiveDays })) {
+      const res = curator.runCurator({ agentRoot, staleDays, archiveDays });
+      transitioned = res.transitioned; archived = res.archived;
+      if (typeof log === "function" && (transitioned.length || archived.length)) {
+        log("info", `[skill-curator] transitioned ${transitioned.length}, archived ${archived.length}`);
+      }
+    }
+
+    // Phase 2 — LLM umbrella consolidation, spawned DETACHED if due. Never blocks
+    // the consumer, never escalates to a sub-session.
+    const consolidation = await maybeSpawnConsolidation(agentRoot, opts.consolidation || {});
+    if (consolidation.spawned && typeof log === "function") {
+      log("info", `[skill-curator] umbrella consolidation spawned (detached); ${consolidation.candidateCount} candidate(s)`);
+    }
+
+    return {
+      ok: true,
+      decision: "inline",
+      transitioned,
+      archived,
+      consolidation: consolidation.spawned ? "spawned" : consolidation.reason,
+    };
+  } catch (err) {
+    // Fail-open: housekeeping must never DLQ.
+    return { ok: true, decision: "inline", reason: "curator-error", error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * 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 };
+}
+
+/**
+ * quarterly-self-assessment guard (Phase 0 item 0.14): the plist fires on the
+ * 1st of EVERY month, but the report is QUARTERLY. Escalate to the Claude
+ * sub-session only in a quarter-start month (Jan/Apr/Jul/Oct); otherwise the
+ * tick completes inline with no spawn — preventing the 12×/year (3× cost)
+ * misfire confirmed by the audit. Pure delegation to isQuarterStartMonth so the
+ * month logic stays unit-tested in lib/cadences.mjs.
+ */
+async function guardQuarterlySelfAssessment({ now } = {}) {
+  const when = now instanceof Date ? now : new Date();
+  if (!isQuarterStartMonth(when)) {
+    return { ok: true, decision: "inline", reason: "not a quarter-start month" };
+  }
+  return { ok: true, decision: "escalate", reason: "quarter start" };
+}
+
+// ---------------------------------------------------------------------------
+// Economics / scheduling cadences (WS-economics)
+//
+// These wire already-built deterministic economics + scheduling functions onto
+// the cadence bus. They run INLINE in the persistent daemon (no LLM spawn) —
+// except dynamic-jobs, which is a GUARDED escalate-when-due primitive. Every one
+// is fail-open: a throw never DLQs the tick, it returns { ok:false, error }.
+// ---------------------------------------------------------------------------
+
+/** Read config/agent.json fail-open (for the org legs). Returns null on any error. */
+function loadAgentCfg(agentRoot) {
+  try {
+    const p = join(agentRoot, "config", "agent.json");
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * nightly-cost-reconcile (inline): three-way spend reconcile of today's local
+ * router ledger against the Anthropic Admin Cost API. We pass NO fetchImpl, so
+ * the provider leg is skipped and reconcile fails open (driftPct null, never an
+ * error). A real deployment injects the Admin API fetch in prod. Drift > 10%
+ * (`flagged`) logs a warning. The result (drift %) goes in the inline result.
+ * The lib fn is injectable via `opts.reconcileImpl` for tests.
+ */
+async function handleNightlyCostReconcile({ event, agentRoot, log }, opts = {}) {
+  try {
+    const reconcile =
+      opts.reconcileImpl ||
+      (await import("../../lib/model-router/reconcile.mjs")).reconcileDaily;
+    // fetchImpl intentionally undefined → reconcile fails open (provider null).
+    const res = await reconcile({ agentRoot, fetchImpl: opts.fetchImpl });
+    if (res && res.flagged && typeof log === "function") {
+      log("warn", `[nightly-cost-reconcile] drift ${res.driftPct}% exceeds ${res.thresholdPct}% (local $${res.localUSD} vs provider $${res.providerUSD})`);
+    }
+    return {
+      ok: true,
+      decision: "inline",
+      cadence: event.cadence,
+      day: res?.day ?? null,
+      driftPct: res?.driftPct ?? null,
+      flagged: !!(res && res.flagged),
+      localUSD: res?.localUSD ?? null,
+      providerUSD: res?.providerUSD ?? null,
+    };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * fleet-cost-digest (inline): build the daily fleet LLM-spend digest from the
+ * local router ledger (org rollup leg fails open when Cohort is disabled). The
+ * digest summary (total / sessions / cache-read KPI / source) goes in the inline
+ * result. Injectable via `opts.digestImpl` for tests.
+ */
+async function handleFleetCostDigest({ event, agentRoot, log }, opts = {}) {
+  try {
+    const digestFn =
+      opts.digestImpl ||
+      (await import("../../scripts/cost/fleet-digest.mjs")).fleetDigest;
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    const d = await digestFn({ agentRoot, cfg });
+    if (d && d.cacheReadKpiOk === false && typeof log === "function") {
+      log("warn", `[fleet-cost-digest] cache-read ratio ${(d.cacheReadRatio * 100).toFixed(1)}% below 60% target`);
+    }
+    return {
+      ok: true,
+      decision: "inline",
+      cadence: event.cadence,
+      day: d?.day ?? null,
+      totalUSD: d?.totalUSD ?? null,
+      sessions: d?.sessions ?? null,
+      cacheReadRatio: d?.cacheReadRatio ?? null,
+      cacheReadKpiOk: d?.cacheReadKpiOk ?? null,
+      source: d?.source ?? null,
+      summary: d ? `Fleet LLM spend ${d.day} (${d.source}): $${d.totalUSD} over ${d.sessions} session(s), cache-read ${(d.cacheReadRatio * 100).toFixed(1)}%` : null,
+    };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * org-cost-sync (inline): push today's router ledger rows to the Cohort org
+ * rollup via cost.report, batched + idempotent. No-op / fail-open when org
+ * (Cohort) is disabled (enabled:false in the result). Injectable via
+ * `opts.reportImpl` for tests.
+ */
+async function handleOrgCostSync({ event, agentRoot }, opts = {}) {
+  try {
+    const reportFn =
+      opts.reportImpl ||
+      (await import("../../lib/org/cost-sync.mjs")).reportLedger;
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    const res = await reportFn({ agentRoot, cfg, fetchImpl: opts.fetchImpl });
+    return {
+      ok: true,
+      decision: "inline",
+      cadence: event.cadence,
+      enabled: !!(res && res.enabled),
+      rowsRead: res?.rowsRead ?? 0,
+      reported: res?.reported ?? 0,
+      failed: res?.failed ?? 0,
+      localUSD: res?.localUSD ?? 0,
+    };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * monitoring-alerts (inline): gather the diagnostics counters, today's cost
+ * ledger, peer presence, daemon health + backup freshness, evaluate the
+ * behavioral alert rules, and emit any firing alerts to the configured webhook
+ * (config/alerts.yaml `alerts.webhook`) — else log them. Deterministic, no LLM.
+ * Fail-open + fully injectable for tests. This is what makes lib/diagnostics/
+ * alerts.mjs actually fire on a schedule.
+ */
+async function handleMonitoringAlerts({ event, agentRoot, log }, opts = {}) {
+  try {
+    const A = opts.alertsImpl || (await import("../../lib/diagnostics/alerts.mjs"));
+    const snapshot = opts.snapshot !== undefined
+      ? opts.snapshot
+      : (await import("../../lib/diagnostics/counters.mjs")).snapshot({ agentRoot });
+    const ledger = opts.ledger !== undefined
+      ? opts.ledger
+      : (await import("../../lib/model-router/ledger.mjs")).sumLedgerToday({ agentRoot });
+    const presence = opts.presence !== undefined
+      ? opts.presence
+      : (await import("../../lib/collective/presence.mjs")).list(agentRoot);
+    const health = opts.health !== undefined ? opts.health : recoverStaleClaims && readDaemonHealth(agentRoot);
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    const now = opts.now || Date.now();
+
+    const alerts = A.evaluateAlerts({ snapshot, ledger, presence, health, thresholds: opts.thresholds, now }) || [];
+
+    const sinkUrl = cfg && cfg.alerts && cfg.alerts.webhook;
+    const sink = opts.sink || (async (alert) => {
+      if (sinkUrl) {
+        const { fetchWithTimeout } = await import("../../lib/util/fetch-timeout.mjs");
+        await fetchWithTimeout(sinkUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(alert) }, 8000);
+      } else if (typeof log === "function") {
+        log("warn", `[alert:${alert.severity}] ${alert.id} — ${alert.detail}`);
+      }
+    });
+    const res = alerts.length ? await A.emitAlerts(alerts, { sink }) : { attempted: 0, delivered: 0, failed: 0 };
+    return { ok: true, decision: "inline", cadence: event.cadence, alerts: alerts.length, delivered: res.delivered ?? 0, severities: alerts.map((a) => a.severity) };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/** Best-effort daemon-health freshness for the alert rules (never throws). */
+function readDaemonHealth(agentRoot) {
+  try {
+    const p = join(agentRoot, "state", "cadence-bus", "health.json");
+    if (!existsSync(p)) return { daemonDown: true };
+    const h = JSON.parse(readFileSync(p, "utf-8"));
+    return { ts: h.ts || h.updatedAt || null, daemonDown: false };
+  } catch { return { daemonDown: true }; }
+}
+
+/**
+ * dynamic-jobs guard (guarded): ask dueJobs() which agent-created jobs are due
+ * right now. None due → inline (cheap, write-free). Some due → escalate, with
+ * the due jobs carried in the result so the spawned session can action each
+ * reminder/job payload. dueJobs ADVANCES the store (coalesces recurring, expires
+ * stale one-offs) as a side effect — that is the intended consume. Injectable via
+ * `opts.dueJobsImpl` + `opts.now` for tests. Fail-open: a throw stays inline.
+ */
+async function guardDynamicJobs({ event, agentRoot }, opts = {}) {
+  try {
+    const due =
+      opts.dueJobsImpl ||
+      (await import("../../lib/scheduling/dynamic-jobs.mjs")).dueJobs;
+    const jobs = due(agentRoot, { now: opts.now }) || [];
+    if (jobs.length === 0) {
+      return { ok: true, decision: "inline", cadence: event.cadence, reason: "no jobs due", due: 0 };
+    }
+    return { ok: true, decision: "escalate", cadence: event.cadence, reason: `${jobs.length} job(s) due`, due: jobs.length, jobs };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Org messaging inbound (SP10) — pull Cohort messages/@mentions/call-invites
+// ---------------------------------------------------------------------------
+
+const MESSAGING_CURSOR_REL = join("state", "messaging", "inbound-cursor.json");
+
+/** Read the org-messaging inbound cursor (seq). Fail-open → 0 (from genesis). */
+function readMessagingCursor(agentRoot) {
+  try {
+    const p = join(agentRoot, MESSAGING_CURSOR_REL);
+    if (!existsSync(p)) return 0;
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    const c = Number(obj && obj.cursor);
+    return Number.isFinite(c) ? c : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Persist the org-messaging inbound cursor atomically (temp → rename). Fail-open. */
+function writeMessagingCursor(agentRoot, cursor) {
+  try {
+    const p = join(agentRoot, MESSAGING_CURSOR_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ cursor, updatedAt: new Date().toISOString() }, null, 2) + "\n");
+    renameSync(tmp, p);
+  } catch { /* fail-open */ }
+}
+
+/**
+ * messaging-inbound guard (guarded): poll the Cohort messaging/calling event
+ * stream for new messages / @mentions / call-invites DIRECTED AT this
+ * agent (lib/org/messaging.pullInbound), and ROUTE each one into the existing
+ * daemon inbox pipeline by writing a legacy inbox item under
+ * state/inbox/cohort/ — so the agent reacts to a Cohort @mention exactly like
+ * a Slack/Telegram one (classifier → directed-gate → responder → dispatcher).
+ *
+ * The reactive daemon OWNS inbox dispatch, so the default decision is `inline`
+ * (we route the items but don't escalate — escalating would double-respond, the
+ * same hazard guardInboxProcessor documents). Operators running cadence-only mode
+ * (no reactive daemon) can set MESSAGING_INBOUND_ESCALATE=1 to escalate to the
+ * trigger when new directed items arrive.
+ *
+ * Cursor is advanced + persisted atomically AFTER the items are written, so a
+ * crash re-pulls (at-least-once into the dedup-guarded writeInboxItem) rather
+ * than dropping. Fail-open: a disabled/unreachable org or any throw stays inline
+ * with 0 routed (org messaging is fail-open at runtime).
+ *
+ * Injectable seams (tests): o.pullImpl, o.writeImpl, o.toInboxImpl, o.cfg,
+ * o.fetchImpl, o.now — so tests never touch the network or real config.
+ */
+async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
+  try {
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    // No org config at all → nothing to pull. Stay inline (fail-open, no spawn).
+    if (!cfg || !cfg.org || !cfg.org.cohort) {
+      return { ok: true, decision: "inline", cadence: event.cadence, reason: "org messaging not configured", routed: 0 };
+    }
+
+    const pull = opts.pullImpl || (await import("../../lib/org/messaging.mjs")).pullInbound;
+    const eventToInboxItem =
+      opts.toInboxImpl || (await import("../../lib/channels/inbox-item.mjs")).eventToInboxItem;
+    const writeInboxItem = opts.writeImpl || (await import("../poller/utils.mjs")).writeInboxItem;
+
+    const cursor = readMessagingCursor(agentRoot);
+    const res = await pull({ cfg, cursor, fetchImpl: opts.fetchImpl });
+    const events = (res && Array.isArray(res.events)) ? res.events : [];
+
+    let routed = 0;
+    for (const ev of events) {
+      try {
+        const item = eventToInboxItem(ev);
+        writeInboxItem("cohort", item, agentRoot);
+        routed += 1;
+      } catch { /* one bad event must not drop the rest */ }
+    }
+
+    // Advance the cursor AFTER writing (at-least-once; writeInboxItem dedupes).
+    const next = res && res.nextCursor != null ? res.nextCursor : cursor;
+    if (next !== cursor) writeMessagingCursor(agentRoot, next);
+
+    if (routed && typeof log === "function") {
+      log("info", `[messaging-inbound] routed ${routed} Cohort item(s) into the inbox pipeline`);
+    }
+
+    if (process.env.MESSAGING_INBOUND_ESCALATE === "1" && routed > 0) {
+      return { ok: true, decision: "escalate", cadence: event.cadence, reason: `${routed} directed item(s)`, routed };
+    }
+    return {
+      ok: true,
+      decision: "inline",
+      cadence: event.cadence,
+      reason: routed ? "routed to inbox (reactive-daemon-owns-dispatch)" : "no new directed items",
+      routed,
+      note: routed ? "Set MESSAGING_INBOUND_ESCALATE=1 to escalate instead of routing to the inbox." : undefined,
+    };
+  } catch (err) {
+    return { ok: true, decision: "inline", cadence: event.cadence, reason: "messaging-inbound-error", routed: 0, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Directory hygiene + brand steward (2026-07 Directory & Design)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve { base, token } for an org call from an agent cfg, or null when the
+ * integration is off/unconfigured. Mirrors lib/org/messaging.resolveOrg — the
+ * SAME isEnabled + configFromAgent chain, so a disabled agent is inert here for
+ * exactly the reason it is inert everywhere else. Never throws.
+ */
+async function resolveOrgCall(cfg) {
+  try {
+    const { isEnabled, configFromAgent } = await import("../../lib/org/client.mjs");
+    if (!isEnabled(cfg)) return null;
+    const c = configFromAgent(cfg);
+    return c.base ? { base: c.base, token: c.token, orgId: c.orgId } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * directory-hygiene guard (guarded): a CHEAP pre-check over the Directory's two
+ * human review queues — pending captures and pending duplicate candidates. If
+ * both are empty the tick completes inline with no Claude spawn; if either has
+ * work, escalate to schedules/triggers/directory-hygiene.md, where the session
+ * proposes captures from signatures/rosters/bank feeds, enriches channels,
+ * re-verifies anything unseen for >90d, and flags duplicates.
+ *
+ * The guard itself only ever READS. Everything the escalated session does is a
+ * PROPOSAL: merges, awareness changes, capture resolution and archives are
+ * human-gated server-side (DECISIONS D-7), so this cadence cannot mutate a
+ * record even if the model tried.
+ *
+ * Awareness note: the queue counts below are awareness-scoped like every other
+ * Directory read. A zero count means "nothing this seat can see", never "nothing
+ * exists" — which is why a zero-count tick stays inline rather than reporting
+ * a clean queue.
+ *
+ * Injectable seams (tests): o.cfg, o.callImpl, o.fetchImpl — so tests never
+ * touch the network or real config. Fail-open: an unreachable/disabled org, a
+ * transport error, or ANY throw stays inline with 0 pending.
+ */
+async function guardDirectoryHygiene({ event, agentRoot, log }, opts = {}) {
+  const cadence = event && event.cadence ? event.cadence : "directory-hygiene";
+  try {
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    const org = await resolveOrgCall(cfg);
+    if (!org) {
+      return { ok: true, decision: "inline", cadence, reason: "org directory not configured", captures: 0, duplicates: 0 };
+    }
+
+    const call = opts.callImpl || (await import("../../lib/org/client.mjs")).call;
+    const o = { base: org.base, token: org.token, orgId: org.orgId, fetchImpl: opts.fetchImpl };
+    const [capFrame, dupFrame] = await Promise.all([
+      call("directory.listCaptures", { status: "PENDING", limit: 50 }, o),
+      call("directory.listMerges", { status: "PENDING", limit: 50 }, o),
+    ]);
+
+    const rows = (frame, ...keys) => {
+      if (!frame || !frame.ok || !frame.result) return [];
+      const r = frame.result;
+      if (Array.isArray(r)) return r;
+      for (const k of keys) if (Array.isArray(r[k])) return r[k];
+      return [];
+    };
+    const captures = rows(capFrame, "captures", "items").length;
+    const duplicates = rows(dupFrame, "candidates", "merges", "items").length;
+    const pending = captures + duplicates;
+
+    if (pending === 0) {
+      return { ok: true, decision: "inline", cadence, reason: "review queues clear", captures: 0, duplicates: 0 };
+    }
+    if (typeof log === "function") {
+      log("info", `[directory-hygiene] ${captures} capture(s) + ${duplicates} duplicate(s) pending`);
+    }
+    return {
+      ok: true,
+      decision: "escalate",
+      cadence,
+      reason: `${captures} capture(s), ${duplicates} duplicate(s) pending`,
+      captures,
+      duplicates,
+      pending,
+    };
+  } catch (err) {
+    return {
+      ok: true,
+      decision: "inline",
+      cadence,
+      reason: "directory-hygiene-error",
+      captures: 0,
+      duplicates: 0,
+      error: err && err.message ? err.message : String(err),
+    };
+  }
+}
+
+const BRAND_CURSOR_REL = join("state", "org", "brand-steward-cursor.json");
+
+/** Read the brand-steward event cursor (seq). Fail-open → 0 (from genesis). */
+function readBrandCursor(agentRoot) {
+  try {
+    const p = join(agentRoot, BRAND_CURSOR_REL);
+    if (!existsSync(p)) return 0;
+    const c = Number(JSON.parse(readFileSync(p, "utf8")).cursor);
+    return Number.isFinite(c) ? c : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Persist the brand-steward cursor atomically (temp → rename). Fail-open. */
+function writeBrandCursor(agentRoot, cursor) {
+  try {
+    const p = join(agentRoot, BRAND_CURSOR_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ cursor, updatedAt: new Date().toISOString() }, null, 2) + "\n");
+    renameSync(tmp, p);
+  } catch { /* fail-open */ }
+}
+
+/** Brand events that mean "the foundation moved; downstream assets are stale". */
+const BRAND_SAVE_KINDS = new Set(["version.saved", "foundation.updated", "version.head_moved"]);
+
+/**
+ * brand-steward guard (guarded): tail the org event chain for a brand
+ * foundation change (`branding/version.saved` and its siblings). A foundation
+ * save is what makes rendered imagery and templates STALE, so this is
+ * event-driven rather than time-driven — it escalates ONLY on a real save, and
+ * otherwise costs one cheap GET.
+ *
+ * On escalation the session runs schedules/triggers/brand-steward.md: quote the
+ * stale slots (`design_generate_image` with `budgetCents: 0`), re-render what is
+ * worth re-rendering inside the budget, and post a working-now status line
+ * carrying the actual spend.
+ *
+ * The cursor advances AFTER the decision, so a crash re-reads the same window
+ * (at-least-once) rather than silently skipping a brand save. `hq` ignores a
+ * `family=` query param on the events read, so the family/kind filter is applied
+ * client-side here — the same posture as lib/org/messaging.pullInbound.
+ *
+ * Injectable seams (tests): o.cfg, o.readImpl, o.fetchImpl. Fail-open in every
+ * direction; never throws.
+ */
+async function guardBrandSteward({ event, agentRoot, log }, opts = {}) {
+  const cadence = event && event.cadence ? event.cadence : "brand-steward";
+  try {
+    const cfg = opts.cfg !== undefined ? opts.cfg : loadAgentCfg(agentRoot);
+    const org = await resolveOrgCall(cfg);
+    if (!org) {
+      return { ok: true, decision: "inline", cadence, reason: "org design not configured", saves: 0 };
+    }
+
+    const read = opts.readImpl || (await import("../../lib/org/client.mjs")).read;
+    const cursor = readBrandCursor(agentRoot);
+    const r = await read(
+      `events?cursor=${encodeURIComponent(cursor)}&limit=200&family=branding`,
+      { base: org.base, token: org.token, orgId: org.orgId, fetchImpl: opts.fetchImpl },
+    );
+    if (!r || !r.ok || !r.payload) {
+      return { ok: true, decision: "inline", cadence, reason: "events unreadable", saves: 0 };
+    }
+
+    const raw = Array.isArray(r.payload)
+      ? r.payload
+      : Array.isArray(r.payload.events)
+        ? r.payload.events
+        : [];
+    let maxSeq = cursor;
+    const saves = [];
+    for (const ev of raw) {
+      const seq = Number(ev && ev.seq);
+      if (Number.isFinite(seq)) maxSeq = Math.max(Number(maxSeq) || 0, seq);
+      // hq ignores family= on the events read, so filter here.
+      if (!ev || ev.family !== "branding") continue;
+      if (!BRAND_SAVE_KINDS.has(String(ev.kind || ""))) continue;
+      saves.push({ seq, kind: ev.kind, at: ev.at ?? null });
+    }
+
+    if (raw.length && maxSeq !== cursor) writeBrandCursor(agentRoot, maxSeq);
+
+    if (saves.length === 0) {
+      return { ok: true, decision: "inline", cadence, reason: "no brand save since last tick", saves: 0, cursor: maxSeq };
+    }
+    if (typeof log === "function") {
+      log("info", `[brand-steward] ${saves.length} brand foundation change(s) — imagery/templates may be stale`);
+    }
+    return {
+      ok: true,
+      decision: "escalate",
+      cadence,
+      reason: `${saves.length} brand foundation change(s) since seq ${cursor}`,
+      saves: saves.length,
+      latestKind: saves[saves.length - 1].kind,
+      cursor: maxSeq,
+    };
+  } catch (err) {
+    return {
+      ok: true,
+      decision: "inline",
+      cadence,
+      reason: "brand-steward-error",
+      saves: 0,
+      error: err && err.message ? err.message : String(err),
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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.",
+  },
+  "skill-curator": {
+    mode: "guarded",
+    guard: guardSkillCurator,
+    // No prompt file and never escalates to a sub-session. Phase 1 (lifecycle
+    // transitions) runs inline; phase 2 (LLM umbrella consolidation) runs as a
+    // DETACHED worker (scripts/learning/consolidate-skills.mjs) spawned from the
+    // guard when due — the guard still returns `inline`, so the consumer is
+    // never blocked and no managed sub-session is created.
+    description: "Lifecycle housekeeping (active→stale→archived) inline + periodic LLM umbrella consolidation via a detached worker. Never escalates.",
+  },
+  "meeting-prep": {
+    mode: "guarded",
+    guard: guardMeetingPrep,
+    prompt: "schedules/triggers/meeting-prep.md",
+    description: "Prepare for upcoming meetings when there are unprocessed calendar items.",
+    // Scoped-permissions allowlist (audit H1). Meeting prep reads the calendar
+    // + recent context and drafts a brief; it does not need shell/write/send
+    // primitives. Only consulted when MAESTRO_SCOPED_PERMISSIONS=1.
+    allowedTools: ["Read", "Grep", "Glob", "LS", "search_calendar", "search_meetings"],
+  },
+
+  // 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: "guarded",
+    guard: guardQuarterlySelfAssessment,
+    prompt: "schedules/triggers/quarterly-self-assessment.md",
+    description: "Quarterly self-assessment (guard escalates only in a quarter-start month).",
+  },
+
+  // Economics / scheduling cadences (WS-economics). Deterministic → inline,
+  // except dynamic-jobs (guarded escalate-when-due).
+  "nightly-cost-reconcile": {
+    mode: "inline",
+    handler: handleNightlyCostReconcile,
+    description: "Nightly three-way spend reconcile vs the Admin Cost API; flags drift > 10%. Inline (no LLM); fails open with no fetchImpl.",
+  },
+  "fleet-cost-digest": {
+    mode: "inline",
+    handler: handleFleetCostDigest,
+    description: "Daily fleet LLM-spend digest from the local router ledger (org rollup leg fails open). Inline.",
+  },
+  "org-cost-sync": {
+    mode: "inline",
+    handler: handleOrgCostSync,
+    description: "Push today's router ledger rows to Cohort cost.report (no-op/fail-open when org disabled). Inline.",
+  },
+  "monitoring-alerts": {
+    mode: "inline",
+    handler: handleMonitoringAlerts,
+    description: "Evaluate behavioral alert rules (guard-fail/refusal spikes, cost p99, absent-agent, daemon-down) over the diagnostics counters + ledger + presence; emit to config/alerts.yaml webhook else log. Inline (no LLM); fail-open.",
+  },
+  "dynamic-jobs": {
+    mode: "guarded",
+    guard: guardDynamicJobs,
+    prompt: "schedules/triggers/dynamic-jobs.md",
+    description: "Action agent-created reminders/jobs. Guard escalates only when dueJobs() returns due work; otherwise inline.",
+  },
+
+  // Org messaging inbound (SP10). Guarded — the guard pulls new Cohort
+  // messages/@mentions/call-invites directed at this agent and routes them into
+  // the inbox pipeline (the reactive daemon owns dispatch, so it stays inline);
+  // MESSAGING_INBOUND_ESCALATE=1 flips it to escalate when items arrive.
+  "messaging-inbound": {
+    mode: "guarded",
+    guard: guardMessagingInbound,
+    prompt: "schedules/triggers/messaging-inbound.md",
+    description: "Pull Cohort org messages/@mentions/call-invites directed at this agent into the inbox pipeline. Guarded — inline routing by default; escalate-when-items with MESSAGING_INBOUND_ESCALATE=1. Fail-open when org disabled.",
+    // Scoped-permissions allowlist (audit H1): when it escalates, the sub-session
+    // reads the org context and drafts a reply — no shell/write primitives.
+    allowedTools: ["Read", "Grep", "Glob", "LS", "messaging_history", "messaging_send"],
+  },
+
+  // Directory & Design stewards (2026-07). Both guarded, both cheap when idle.
+  "directory-hygiene": {
+    mode: "guarded",
+    guard: guardDirectoryHygiene,
+    prompt: "schedules/triggers/directory-hygiene.md",
+    description:
+      "Keep the Directory clean: propose captures from signatures/rosters/bank feeds, enrich channels, re-verify anything unseen for >90d, flag duplicates. Guarded — escalates only when the capture/duplicate queues have work. PROPOSE-ONLY: merges, awareness changes and archives are human-gated server-side. Fail-open when org disabled.",
+    // Scoped-permissions allowlist (audit H1). Every Directory verb here is a
+    // read or a PROPOSAL; the human-gated verbs are deliberately absent, so even
+    // in scoped mode the cadence physically cannot reach for them.
+    allowedTools: [
+      "Read", "Grep", "Glob", "LS",
+      "directory_search", "directory_list_people", "directory_list_orgs",
+      "directory_get_person", "directory_get_org",
+      "directory_list_captures", "directory_list_merges",
+      "directory_propose_capture", "directory_propose_merge",
+      "directory_add_channel", "directory_update_person",
+    ],
+  },
+  "brand-steward": {
+    mode: "guarded",
+    guard: guardBrandSteward,
+    prompt: "schedules/triggers/brand-steward.md",
+    description:
+      "React to a brand foundation save: quote the stale image slots and templates, re-render what is worth re-rendering inside the budget, and post a working-now status carrying the real spend. Guarded — escalates only on a branding version.saved/foundation.updated event. Fail-open when org disabled.",
+    // Reads + the costed producers. branding.saveFoundation/restoreFoundation are
+    // admin-scope server-side and have no tool here — the cadence proposes.
+    allowedTools: [
+      "Read", "Grep", "Glob", "LS",
+      "design_foundation", "design_voice", "design_list_templates",
+      "design_render_template", "design_export_kit", "design_generate_image",
+      "design_propose_change", "messaging_send",
+    ],
+  },
+};
+
+// Optional config-driven cadence registry (config/.cadence-registry.json),
+// written by scripts/setup/generate-cadences.mjs from the agent's function ×
+// altitude. Lets archetype-specific cadences route without editing this file.
+// Cached after first read.
+let _configRegistry = null;
+function loadConfigRegistry() {
+  if (_configRegistry !== null) return _configRegistry;
+  _configRegistry = {};
+  try {
+    const root = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+    const p = join(root, "config", ".cadence-registry.json");
+    if (existsSync(p)) _configRegistry = JSON.parse(readFileSync(p, "utf-8")) || {};
+  } catch { _configRegistry = {}; }
+  return _configRegistry;
+}
+
+/**
+ * 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. The hardcoded CADENCE_REGISTRY wins; the config-driven archetype
+ * cadences (config/.cadence-registry.json) fill in the rest.
+ */
+export function getCadenceDef(name) {
+  if (CADENCE_REGISTRY[name]) return CADENCE_REGISTRY[name];
+  const cfg = loadConfigRegistry()[name];
+  if (cfg && cfg.prompt) {
+    return { mode: cfg.mode || "escalate", prompt: cfg.prompt, description: "archetype cadence (config-driven)" };
+  }
+  return 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);
+}
+
+// Exported for tests (and for the consumer, which already reaches the guard via
+// CADENCE_REGISTRY). The optional second arg carries injectable seams for the
+// phase-2 consolidation due-check (clock + fake spawner) without touching the
+// production path.
+export { guardSkillCurator, maybeSpawnConsolidation };
+
+// Economics / scheduling handlers — exported for tests (the consumer reaches
+// them via CADENCE_REGISTRY). Each takes an optional second arg of injectable
+// seams (lib fn / clock / cfg) so tests never touch the network or real config.
+export {
+  handleNightlyCostReconcile,
+  handleFleetCostDigest,
+  handleOrgCostSync,
+  guardDynamicJobs,
+  guardMessagingInbound,
+  guardDirectoryHygiene,
+  guardBrandSteward,
+};