@adaptic/maestro 1.7.3 → 1.8.1

package/.claude/commands/init-maestro.md

@@ -435,7 +435,9 @@ The generated tools should be COMPREHENSIVE — every responsibility listed in P
 
 ## Phase 3: Machine Configuration
 
-After identity rewriting completes, generate and install the launchd plists (these need the agent name from Phase 1):
+After identity rewriting completes, generate and install the launchd plists (these need the agent name from Phase 1).
+
+The plists generated here use the **cadence bus architecture** (maestro 1.8+): scheduled cadence ticks no longer spawn a fresh Claude Code session per tick. Instead, launchd invokes `scripts/cadence/enqueue-cadence-tick.mjs` (≈10 ms, no Claude) which drops a JSON event onto `state/cadence-bus/inbox/`. The persistent daemon (started by the `*-daemon` plist) drains the bus and decides — per cadence — whether to handle the tick inline or escalate to a managed sub-session.
 
 ### Step 1: Generate launchd plists
 
@@ -443,7 +445,7 @@ After identity rewriting completes, generate and install the launchd plists (the
 bash scripts/local-triggers/generate-plists.sh
 ```
 
-This reads `config/agent.ts` to get the agent's first name and generates all 13 launchd plist files with correct labels and paths.
+This reads `config/agent.ts` to get the agent's first name and generates all 13 launchd plist files with correct labels and paths. Every plist carries the `maestro-plist-arch: cadence-bus v1` marker.
 
 ### Step 2: Install launchd agents
 
@@ -462,6 +464,17 @@ done
 
 Report how many triggers were installed.
 
+### Step 2b: Cadence bus smoke test (verifies end-to-end delivery)
+
+```bash
+# Enqueue a heartbeat tick and confirm the daemon drained it.
+node scripts/cadence/enqueue-cadence-tick.mjs cadence-bus-heartbeat --source=init-maestro
+sleep 4
+node scripts/cadence/cadence-status.mjs
+```
+
+The heartbeat must show `depth.inbox: 0` and a fresh `health.ts` within the last minute. If not, check `logs/cadence-bus/<date>.jsonl` and `logs/daemon/launchd-stderr.log`.
+
 ### Step 3: macOS headless configuration (optional)
 
 Offer to configure the Mac mini for headless 24/7 operation:

package/.gitignore

@@ -18,6 +18,13 @@ memory/
 outputs/
 knowledge/
 
+# Generated launchd plists — produced per-agent by generate-plists.sh from
+# the agent's own config/agent.ts. Never committed to the framework; each
+# agent regenerates them at init-agent.sh time. Keep the directory via
+# scripts/local-triggers/plists/.gitkeep.
+scripts/local-triggers/plists/*.plist
+scripts/poller-launchd/*.plist
+
 # Editor
 *.swp
 *.swo

package/README.md

@@ -103,7 +103,8 @@ After `create`, run `claude "/init-maestro"` to configure the agent's identity a
 
 Updates framework files in an existing agent repo. This command copies the latest versions of:
 
-- `scripts/` -- poller, daemon, hooks, PDF generation, setup scripts
+- `scripts/` -- poller, daemon, hooks, PDF generation, setup scripts, **cadence bus enqueue + consumer + wrapper**
+- `lib/` -- shared framework primitives (singleton lock, **cadence bus**, action executor, tool definitions)
 - `policies/` -- action classification, information barriers, prompt injection defence
 - `docs/` -- architecture, governance, runbooks
 - `public/assets/` -- brand assets
@@ -112,20 +113,34 @@ Updates framework files in an existing agent repo. This command copies the lates
 - `plugins/maestro-skills/` -- operational skills
 - `agents/` -- new agents are added, existing ones preserved (no deletions)
 
-It also creates any missing directories from the expanded directory set.
+It also creates any missing directories from the expanded directory set, including `state/cadence-bus/{inbox,claimed,processed,failed,dlq}` and `logs/cadence-bus/`.
 
-Agent-specific files (`config/`, `CLAUDE.md`, `knowledge/`, `memory/`, `state/`, `logs/`) are never touched.
+**Cadence-bus migration (1.8+):** `upgrade` automatically migrates legacy spawn-per-tick launchd plists:
+
+1. Detects generated plists at `scripts/local-triggers/plists/` that still call `run-trigger.sh` directly.
+2. Backs them up to `.maestro/backup/plists/<utc-timestamp>/`.
+3. Regenerates them via `scripts/local-triggers/generate-plists.sh` so they invoke the lightweight cadence enqueue script instead.
+4. Surfaces any installed plists at `~/Library/LaunchAgents/ai.adaptic.*` that still match the legacy pattern, with exact `launchctl unload && launchctl load` commands the operator can run to roll the live job.
+
+The migration is idempotent — a second `upgrade` run on a fully-migrated repo is a clean no-op.
+
+Agent-specific files (`config/`, `CLAUDE.md`, `knowledge/`, `memory/`, `state/`, `logs/`, `outputs/`, `.env`) are never touched.
 
 ### `npx @adaptic/maestro doctor`
 
-Verifies the agent installation. Checks for 16 essential files:
+Verifies the agent installation end-to-end. Checks include:
+
+- **Framework files:** `config/agent.ts`, `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/init-maestro.md`, `package.json`, `scripts/setup/init-agent.sh`, `scripts/healthcheck.sh`, `scripts/daemon/maestro-daemon.mjs`, `scripts/local-triggers/generate-plists.sh`.
+- **Cadence bus (1.8+):** `lib/cadence-bus.mjs`, `scripts/cadence/enqueue-cadence-tick.mjs`, `scripts/cadence/launchd-cadence-wrapper.sh`, `scripts/daemon/cadence-consumer.mjs`, `scripts/daemon/cadence-handlers.mjs`, plus the `state/cadence-bus/{inbox,claimed,processed,failed,dlq}` directory tree.
+- **Plist architecture:** every generated plist at `scripts/local-triggers/plists/` carries the `maestro-plist-arch: cadence-bus` marker, and NO plist still calls `run-trigger.sh` directly. Installed plists under `~/Library/LaunchAgents/ai.adaptic.*` are spot-checked too; doctor prints the exact `launchctl unload && launchctl load` commands to migrate any stragglers.
+- **Daemon heartbeat:** `state/cadence-bus/health.json` is fresh (under 60s) when the daemon is running.
+- **Smoke test:** doctor enqueues a `cadence-bus-heartbeat` tick to confirm the producer side works end-to-end.
+- **Config:** `config/environment.yaml`, `config/contacts.yaml`, `config/priorities.yaml`, `config/sla-defaults.yaml`.
+- **State:** `state/dashboards/executive-summary.yaml`, `state/queues/action-stack.yaml`, `knowledge/decisions/decision-schema.yaml`.
+- **Environment:** `.env` file with `ANTHROPIC_API_KEY` (required), `SLACK_USER_TOKEN`, `GMAIL_APP_PASSWORD` (optional).
+- **Dependencies:** `node_modules` installed, Claude CLI available, jq available, emergency-stop script present.
 
-- Core: `config/agent.ts`, `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/init-maestro.md`, `package.json`
-- Setup: `scripts/setup/init-agent.sh`, `scripts/healthcheck.sh`, `scripts/daemon/maestro-daemon.mjs`, `scripts/local-triggers/generate-plists.sh`
-- Config: `config/environment.yaml`, `config/contacts.yaml`, `config/priorities.yaml`, `config/sla-defaults.yaml`
-- State: `state/dashboards/executive-summary.yaml`, `state/queues/action-stack.yaml`, `knowledge/decisions/decision-schema.yaml`
-- Environment: `.env` file with `ANTHROPIC_API_KEY` (required), `SLACK_USER_TOKEN`, `GMAIL_APP_PASSWORD` (optional)
-- Dependencies: `node_modules` installed, Claude CLI available
+Doctor exits non-zero when issues are found and prints actionable remediation (most commonly: `npx @adaptic/maestro upgrade`).
 
 ---
 
@@ -253,10 +268,46 @@ All Maestro agents operate in three concurrent modes:
 
 **Mode 1: Reactive** -- The nervous system. A lightweight poller checks Slack, Gmail, and Calendar every 60 seconds. An inbox processor classifies and routes incoming items every 5 minutes. Priority events trigger immediate processing.
 
-**Mode 2: Scheduled** -- The heartbeat. Daily morning brief, midday sweep, evening wrap. Weekly strategic memo, pipeline review, execution review. Monthly board readiness, risk refresh. Quarterly self-assessment and board pack. All triggered via macOS launchd.
+**Mode 2: Scheduled** -- The heartbeat. Daily morning brief, midday sweep, evening wrap. Weekly strategic memo, pipeline review, execution review. Monthly board readiness, risk refresh. Quarterly self-assessment and board pack. All scheduled via macOS launchd; cadence ticks flow through the cadence bus (see below) and are serviced by the persistent daemon, NOT by spawning a fresh Claude Code session per tick.
 
 **Mode 3: Proactive** -- The engine. The backlog executor runs every 10 minutes, reads all queues, selects the top actionable items by priority, and spawns parallel agents to execute them. Items move continuously from `open` to `in_progress` to `resolved` to `closed`.
 
+### Cadence Bus
+
+Scheduled cadence ticks (every 5 / 10 / 15 / 30 minutes, daily, weekly, monthly, quarterly) are decoupled from Claude Code via a local file-backed event bus at `state/cadence-bus/`:
+
+```
+launchd ──► scripts/cadence/enqueue-cadence-tick.mjs (≈10 ms, no Claude)
+                       │
+                       ▼
+            state/cadence-bus/inbox/<event>.json
+                       │
+                       ▼
+       maestro-daemon.mjs ──► cadence-consumer.mjs (single persistent owner)
+                       │
+                ┌──────┴──────┐
+                ▼             ▼
+            inline       sub-session
+        (housekeeping)  (substantive work)
+```
+
+**Why this matters.** The previous architecture spawned a fresh `claude --print` session per cadence tick — dozens of full Claude Code spawns per day, each paying full auth/context/token overhead even when the tick had nothing to do. The cadence bus:
+
+- Routes every tick through ONE persistent main session (the daemon).
+- Handles lightweight ticks **inline** (no Claude spawned) — heartbeats, housekeeping, queue sweeps with cheap pre-checks.
+- Only spawns a sub-session when the cadence genuinely warrants isolated work: substantive drafting, multi-step outreach, large audits, research, work requiring separate context/audit boundaries.
+- Honours `.emergency-stop` at both producer and consumer.
+- Is safe if the daemon is briefly down — events accumulate in `inbox/` and drain on next startup.
+- Records the full lifecycle (received → claimed → processed | escalated | failed | dlq) under `logs/cadence-bus/<date>.jsonl`.
+
+Per-cadence policy lives in `scripts/daemon/cadence-handlers.mjs`:
+
+- **inline** — handler runs entirely in-process (e.g. heartbeat, stale-claim sweep).
+- **guarded** — cheap pre-check (queues empty? inbox empty?); only escalates if there's substantive work.
+- **escalate** — spawns a sub-session running the cadence's trigger prompt under `schedules/triggers/<name>.md`.
+
+See `docs/runbooks/perpetual-operations.md` for ops procedures.
+
 ---
 
 ## Auto-Publishing

package/bin/maestro.mjs

@@ -8,7 +8,7 @@
  *   npx @adaptic/maestro doctor             # Verify installation and configuration
  */
 
-import { resolve, join, dirname, relative, sep } from "node:path";
+import { resolve, join, dirname, relative, sep, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   mkdirSync,
@@ -21,13 +21,20 @@ import {
   statSync,
   lstatSync,
 } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const MAESTRO_ROOT = resolve(__dirname, "..");
 const SCAFFOLD_DIR = join(MAESTRO_ROOT, "scaffold");
 
+// Plist architecture marker — must match the value emitted by
+// scripts/local-triggers/generate-plists.sh. Used by doctor + upgrade
+// migration to distinguish cadence-bus plists from the legacy
+// spawn-per-tick pattern (which invoked run-trigger.sh directly).
+const PLIST_ARCH_MARKER = "maestro-plist-arch: cadence-bus";
+const LEGACY_PLIST_INDICATOR = "run-trigger.sh";
+
 // ---------------------------------------------------------------------------
 // Colours
 // ---------------------------------------------------------------------------
@@ -87,6 +94,11 @@ function create(targetName) {
     "ingest",
     "mcp",
     "services",
+    // lib/ holds shared framework primitives — singleton lock, cadence bus,
+    // action executor, tool definitions — that scripts/ imports via relative
+    // paths. Must travel with each agent repo so the relative imports work
+    // without depending on a checkout of @adaptic/maestro on the same host.
+    "lib",
   ];
 
   for (const dir of frameworkDirs) {
@@ -153,6 +165,12 @@ function create(targetName) {
     "state/slack-responded",
     "state/slack-thread-tracker",
     "state/tmp",
+    "state/cadence-bus",
+    "state/cadence-bus/inbox",
+    "state/cadence-bus/claimed",
+    "state/cadence-bus/processed",
+    "state/cadence-bus/failed",
+    "state/cadence-bus/dlq",
     "outputs/briefs",
     "outputs/drafts",
     "outputs/memos",
@@ -167,6 +185,7 @@ function create(targetName) {
     "logs/evolution",
     "logs/huddle",
     "logs/daemon",
+    "logs/cadence-bus",
     "logs/infra",
     "logs/monitor",
     "logs/phone",
@@ -583,6 +602,9 @@ rubrics: []
       "configure-macos": "sudo ./scripts/setup/configure-macos.sh",
       "configure-macos:check": "./scripts/setup/configure-macos.sh --check",
       daemon: "node scripts/daemon/maestro-daemon.mjs",
+      "cadence:enqueue": "node scripts/cadence/enqueue-cadence-tick.mjs",
+      "cadence:consume": "node scripts/daemon/cadence-consumer.mjs",
+      "cadence:status": "node scripts/cadence/cadence-status.mjs",
       healthcheck: "./scripts/healthcheck.sh",
       "emergency-stop": "./scripts/emergency-stop.sh",
       resume: "./scripts/resume-operations.sh",
@@ -710,6 +732,10 @@ const UPGRADE_PATHS = [
   { path: "plugins/maestro-skills", mode: "smart" },
   { path: "teams", mode: "smart" },
   { path: "agents", mode: "merge" },
+  // Framework primitives — colocated with scripts/ so relative imports
+  // (e.g. ../../lib/cadence-bus.mjs from scripts/cadence/*) resolve in
+  // every agent repo without needing @adaptic/maestro in node_modules.
+  { path: "lib", mode: "smart" },
 ];
 
 function sha256File(p) {
@@ -832,6 +858,186 @@ function dirtyPathSet(cwd) {
   return set;
 }
 
+// ---------------------------------------------------------------------------
+// Cadence-bus migration (called from upgrade)
+// ---------------------------------------------------------------------------
+//
+// As of maestro 1.8 scheduled cadence ticks no longer spawn a fresh Claude
+// Code session per tick. launchd plists now invoke a lightweight Node
+// enqueue script that drops a JSON event onto state/cadence-bus/; the
+// persistent maestro-daemon.mjs consumes the bus.
+//
+// This migration runs idempotently on every upgrade:
+//   1. Detect generated plists at scripts/local-triggers/plists/ that still
+//      reference run-trigger.sh (the legacy per-tick spawn path).
+//   2. Back them up to .maestro/backup/plists/<utc-timestamp>/.
+//   3. Regenerate plists via scripts/local-triggers/generate-plists.sh so
+//      the on-disk files match the cadence-bus architecture.
+//   4. Surface installed plists at ~/Library/LaunchAgents/ that still match
+//      the legacy pattern, with exact launchctl unload/load commands the
+//      operator can run.
+//
+// Returns a summary object the caller uses to print user-visible output.
+
+function plistRefersToLegacy(path) {
+  try {
+    const body = readFileSync(path, "utf-8");
+    return body.includes(LEGACY_PLIST_INDICATOR);
+  } catch {
+    return false;
+  }
+}
+
+function plistMatchesArch(path) {
+  try {
+    const body = readFileSync(path, "utf-8");
+    return body.includes(PLIST_ARCH_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function listPlists(dir) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((n) => n.endsWith(".plist")).map((n) => join(dir, n));
+  } catch {
+    return [];
+  }
+}
+
+function migrateCadenceBus(cwd, flags) {
+  const summary = {
+    generated_legacy: [],
+    generated_modern: [],
+    installed_legacy: [],
+    backed_up: [],
+    regenerated: false,
+    skipped_regen_reason: null,
+    bus_dir: null,
+    notes: [],
+  };
+
+  // Bootstrap the cadence-bus directory tree even when nothing else is
+  // moving — needed for fresh installs that upgrade through this path.
+  const busBase = join(cwd, "state", "cadence-bus");
+  summary.bus_dir = busBase;
+  for (const d of ["inbox", "claimed", "processed", "failed", "dlq"]) {
+    const full = join(busBase, d);
+    if (!existsSync(full) && !flags.dryRun) {
+      mkdirSync(full, { recursive: true });
+    }
+  }
+  const versionFile = join(busBase, "VERSION");
+  if (!existsSync(versionFile) && !flags.dryRun) {
+    writeFileSync(versionFile, "1\n");
+  }
+
+  // Inspect generated plists.
+  const generatedDir = join(cwd, "scripts/local-triggers/plists");
+  const generated = listPlists(generatedDir);
+  for (const p of generated) {
+    const rel = relative(cwd, p);
+    if (plistRefersToLegacy(p)) summary.generated_legacy.push(rel);
+    else if (plistMatchesArch(p)) summary.generated_modern.push(rel);
+  }
+
+  // Inspect installed plists.
+  const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+  for (const p of listPlists(installedDir)) {
+    const name = basename(p);
+    // Only consider plists owned by Maestro — labels start with ai.adaptic.
+    if (!name.startsWith("ai.adaptic.")) continue;
+    if (plistRefersToLegacy(p)) summary.installed_legacy.push(p);
+  }
+
+  // Back up any legacy generated plists.
+  if (summary.generated_legacy.length > 0) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupDir = join(cwd, ".maestro/backup/plists", ts);
+    if (!flags.dryRun) {
+      mkdirSync(backupDir, { recursive: true });
+      for (const rel of summary.generated_legacy) {
+        const src = join(cwd, rel);
+        const dst = join(backupDir, basename(src));
+        try {
+          copyFileSync(src, dst);
+          summary.backed_up.push(relative(cwd, dst));
+        } catch (err) {
+          summary.notes.push(`backup failed for ${rel}: ${err.message}`);
+        }
+      }
+    } else {
+      // Dry-run: still report what would be backed up.
+      summary.notes.push(`would back up ${summary.generated_legacy.length} legacy plist(s) to .maestro/backup/plists/${ts}/`);
+    }
+
+    // Regenerate via the bundled script. Soft failure — operator can rerun.
+    const generator = join(cwd, "scripts/local-triggers/generate-plists.sh");
+    if (existsSync(generator)) {
+      if (!flags.dryRun) {
+        try {
+          execFileSync("/bin/bash", [generator], { cwd, stdio: "pipe" });
+          summary.regenerated = true;
+        } catch (err) {
+          summary.skipped_regen_reason = `generate-plists.sh failed: ${err.message.split("\n")[0]}`;
+        }
+      } else {
+        summary.notes.push("dry-run: would regenerate plists via scripts/local-triggers/generate-plists.sh");
+      }
+    } else {
+      summary.skipped_regen_reason = "scripts/local-triggers/generate-plists.sh missing";
+    }
+  }
+
+  return summary;
+}
+
+function printCadenceBusSummary(summary, flags) {
+  console.log();
+  console.log(`${C.bold}Cadence bus migration${C.reset}${flags.dryRun ? " (dry run)" : ""}`);
+  if (summary.generated_legacy.length === 0 && summary.installed_legacy.length === 0) {
+    ok("Already on cadence-bus architecture (no legacy plists found).");
+    if (summary.generated_modern.length > 0) {
+      ok(`${summary.generated_modern.length} generated plist(s) carry the cadence-bus marker.`);
+    }
+    return;
+  }
+  if (summary.generated_legacy.length > 0) {
+    warn(`${summary.generated_legacy.length} generated plist(s) still call run-trigger.sh directly:`);
+    for (const p of summary.generated_legacy.slice(0, 8)) console.log(`    ${p}`);
+    if (summary.generated_legacy.length > 8) {
+      console.log(`    … and ${summary.generated_legacy.length - 8} more`);
+    }
+  }
+  if (summary.backed_up.length > 0) {
+    ok(`Backed up ${summary.backed_up.length} legacy plist(s) under ${dirname(summary.backed_up[0])}`);
+  }
+  if (summary.regenerated) {
+    ok("Regenerated plists with the cadence-bus architecture.");
+  } else if (summary.skipped_regen_reason) {
+    warn(`Skipped plist regeneration: ${summary.skipped_regen_reason}`);
+    warn("Run manually: ./scripts/local-triggers/generate-plists.sh");
+  }
+
+  if (summary.installed_legacy.length > 0) {
+    console.log();
+    warn(`${summary.installed_legacy.length} installed launchd plist(s) at ~/Library/LaunchAgents/ still use the legacy spawn-per-tick pattern.`);
+    warn("Reload them so launchctl picks up the cadence-bus versions:");
+    for (const p of summary.installed_legacy.slice(0, 8)) {
+      const label = basename(p, ".plist");
+      console.log(`    launchctl unload "${p}" && launchctl load "${p}"`);
+      // Cosmetic alias for label clarity.
+      void label;
+    }
+    if (summary.installed_legacy.length > 8) {
+      console.log(`    … and ${summary.installed_legacy.length - 8} more`);
+    }
+  }
+
+  for (const note of summary.notes) console.log(`    note: ${note}`);
+}
+
 function parseUpgradeFlags(args) {
   const flags = {
     dryRun: false,
@@ -1005,6 +1211,10 @@ Per-file behaviour:
     "knowledge/decisions/archive", "self-optimization/scenarios", "tests",
     "logs/infra", "logs/monitor", "logs/phone", "logs/sms",
     "logs/whatsapp", "logs/email",
+    // Cadence bus (architecture introduced in maestro 1.8). Idempotent.
+    "state/cadence-bus", "state/cadence-bus/inbox", "state/cadence-bus/claimed",
+    "state/cadence-bus/processed", "state/cadence-bus/failed", "state/cadence-bus/dlq",
+    "logs/cadence-bus",
   ];
   let newDirs = 0;
   for (const dir of ensureDirs) {
@@ -1015,6 +1225,10 @@ Per-file behaviour:
     }
   }
 
+  // Cadence-bus migration: detect legacy spawn-per-tick plists and rewrite
+  // them so launchd enqueues cadence events instead of spawning Claude.
+  const cadenceMigration = migrateCadenceBus(cwd, flags);
+
   // Regenerate config/agent.env from config/agent.json so newly-installed
   // (or already-installed) shell scripts find the agent identity vars.
   // Soft failure — older agents that haven't migrated to the SOT layout
@@ -1052,6 +1266,10 @@ Per-file behaviour:
     if (preservedFiles.length > 5) console.log(`    … and ${preservedFiles.length - 5} more`);
   }
 
+  // Surface the cadence-bus migration summary AFTER the file-by-file
+  // upgrade summary so the operator sees both layers of change.
+  printCadenceBusSummary(cadenceMigration, flags);
+
   console.log();
   log("Agent-specific paths (config/, CLAUDE.md, knowledge/, memory/, state/, outputs/, logs/, .env) were NOT touched.");
 }
@@ -1068,6 +1286,7 @@ function doctor() {
 
   let issues = 0;
 
+  // ── Framework files ─────────────────────────────────────────────────────
   const essentialFiles = [
     "config/agent.ts", "CLAUDE.md", ".claude/settings.json",
     ".claude/commands/init-maestro.md", "package.json",
@@ -1079,6 +1298,13 @@ function doctor() {
     "state/dashboards/executive-summary.yaml",
     "state/queues/action-stack.yaml",
     "knowledge/decisions/decision-schema.yaml",
+    // Cadence-bus architecture (maestro 1.8+)
+    "lib/cadence-bus.mjs",
+    "scripts/cadence/enqueue-cadence-tick.mjs",
+    "scripts/cadence/launchd-cadence-wrapper.sh",
+    "scripts/cadence/cadence-status.mjs",
+    "scripts/daemon/cadence-consumer.mjs",
+    "scripts/daemon/cadence-handlers.mjs",
   ];
 
   for (const file of essentialFiles) {
@@ -1086,6 +1312,102 @@ function doctor() {
     else { fail(`Missing: ${file}`); issues++; }
   }
 
+  // ── Cadence bus state directories ───────────────────────────────────────
+  const busDirs = [
+    "state/cadence-bus",
+    "state/cadence-bus/inbox",
+    "state/cadence-bus/claimed",
+    "state/cadence-bus/processed",
+    "state/cadence-bus/failed",
+    "state/cadence-bus/dlq",
+    "logs/cadence-bus",
+  ];
+  for (const d of busDirs) {
+    if (existsSync(join(cwd, d))) ok(d);
+    else { warn(`Missing: ${d} — run: npx @adaptic/maestro upgrade`); issues++; }
+  }
+
+  // ── Launchd plist architecture ──────────────────────────────────────────
+  const plistDir = join(cwd, "scripts/local-triggers/plists");
+  if (existsSync(plistDir)) {
+    const plists = readdirSync(plistDir).filter((n) => n.endsWith(".plist"));
+    let legacy = 0;
+    let modern = 0;
+    for (const name of plists) {
+      const body = readFileSync(join(plistDir, name), "utf-8");
+      if (body.includes(LEGACY_PLIST_INDICATOR)) legacy++;
+      else if (body.includes(PLIST_ARCH_MARKER)) modern++;
+    }
+    if (plists.length === 0) {
+      warn("scripts/local-triggers/plists/ is empty — run: scripts/local-triggers/generate-plists.sh");
+      issues++;
+    } else if (legacy > 0) {
+      // Legacy plists are a migration warning rather than a fatal — the
+      // operator can fix them with `maestro upgrade`. Use warn() so the
+      // message lands on stdout where scripted callers will see it.
+      warn(`${legacy} plist(s) still call run-trigger.sh directly (legacy spawn-per-tick).`);
+      warn(`  Fix:  npx @adaptic/maestro upgrade   (will back up + regenerate)`);
+      issues++;
+    } else {
+      ok(`${modern}/${plists.length} plist(s) use the cadence-bus architecture`);
+    }
+
+    // Spot-check installed plists at ~/Library/LaunchAgents/.
+    const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+    if (existsSync(installedDir)) {
+      let installedLegacy = 0;
+      for (const name of readdirSync(installedDir)) {
+        if (!name.startsWith("ai.adaptic.")) continue;
+        if (!name.endsWith(".plist")) continue;
+        const body = readFileSync(join(installedDir, name), "utf-8");
+        if (body.includes(LEGACY_PLIST_INDICATOR)) installedLegacy++;
+      }
+      if (installedLegacy > 0) {
+        warn(`${installedLegacy} installed launchd plist(s) still use the legacy pattern.`);
+        warn("  Fix:  npx @adaptic/maestro upgrade   then follow the printed launchctl commands.");
+        issues++;
+      } else {
+        ok("Installed launchd plists (ai.adaptic.*) are on cadence-bus or absent");
+      }
+    }
+  } else {
+    warn("scripts/local-triggers/plists/ does not exist yet — run scripts/setup/init-agent.sh");
+  }
+
+  // ── Cadence consumer heartbeat ──────────────────────────────────────────
+  try {
+    // Read via the bundled lib so we don't reinvent path resolution.
+    const mod = readFileSync(join(cwd, "state/cadence-bus/health.json"), "utf-8");
+    const health = JSON.parse(mod);
+    const ageMs = Date.now() - new Date(health.ts).getTime();
+    if (ageMs < 60_000) ok(`Cadence consumer heartbeat fresh (${Math.round(ageMs / 1000)}s)`);
+    else if (ageMs < 5 * 60_000) warn(`Cadence consumer heartbeat stale (${Math.round(ageMs / 1000)}s) — daemon may be slow.`);
+    else {
+      warn(`Cadence consumer heartbeat very stale (${Math.round(ageMs / 1000)}s) — start the daemon: npm run daemon`);
+      issues++;
+    }
+  } catch {
+    warn("No cadence consumer heartbeat yet — start the daemon: npm run daemon");
+  }
+
+  // ── Manual tick smoke test ──────────────────────────────────────────────
+  // Enqueue a heartbeat tick if cadence files are in place. The bus
+  // accepts the event even when the consumer isn't running; the file lands
+  // on disk and is recoverable. This proves the producer side end-to-end.
+  const enqueueScript = join(cwd, "scripts/cadence/enqueue-cadence-tick.mjs");
+  if (existsSync(enqueueScript)) {
+    const result = spawnSync(process.execPath, [
+      enqueueScript, "cadence-bus-heartbeat",
+      "--source=daemon", "--metadata=note=doctor-smoke", "--quiet",
+    ], { cwd, encoding: "utf-8", env: { ...process.env, AGENT_ROOT: cwd } });
+    if (result.status === 0) ok("Cadence enqueue smoke test passed");
+    else {
+      fail(`Cadence enqueue smoke test failed (exit ${result.status}): ${(result.stderr || "").trim()}`);
+      issues++;
+    }
+  }
+
+  // ── .env ────────────────────────────────────────────────────────────────
   if (existsSync(join(cwd, ".env"))) {
     const env = readFileSync(join(cwd, ".env"), "utf-8");
     const check = (key, required) => {
@@ -1102,6 +1424,7 @@ function doctor() {
     issues++;
   }
 
+  // ── Dependencies ────────────────────────────────────────────────────────
   if (existsSync(join(cwd, "node_modules"))) ok("node_modules installed");
   else { fail("node_modules not found — run: npm install"); issues++; }
 
@@ -1113,9 +1436,22 @@ function doctor() {
     issues++;
   }
 
+  try {
+    execFileSync("which", ["jq"], { stdio: "pipe" });
+    ok("jq installed");
+  } catch {
+    warn("jq not found — install: brew install jq (used by various shell helpers)");
+  }
+
+  // ── Emergency-stop wiring ───────────────────────────────────────────────
+  const stopScript = join(cwd, "scripts/emergency-stop.sh");
+  if (existsSync(stopScript)) ok("scripts/emergency-stop.sh present");
+  else { warn("scripts/emergency-stop.sh missing — kill-switch unavailable"); issues++; }
+
   console.log();
   if (issues === 0) ok("All checks passed.");
   else warn(`${issues} issue(s) found.`);
+  process.exitCode = issues === 0 ? 0 : 1;
 }
 
 // ---------------------------------------------------------------------------