@adaptic/maestro 1.7.3 → 1.8.0

package/bin/maestro.test.mjs

@@ -0,0 +1,299 @@
+/**
+ * maestro.test.mjs — CLI tests for the bin/maestro.mjs commands.
+ *
+ * Covers:
+ *   • `create` scaffolds the cadence-bus directory tree, the enqueue
+ *     script, the consumer, and the cadence handlers under the new agent.
+ *   • `upgrade` migrates a legacy-style agent repo: backs up old plists,
+ *     bootstraps state/cadence-bus/, regenerates plists.
+ *   • `upgrade` preserves agent-specific files (CLAUDE.md, config/,
+ *     knowledge/, memory/, state/, logs/, outputs/, .env) untouched.
+ *   • `upgrade` is idempotent when run twice on the same repo.
+ *   • `doctor` flags legacy plists with actionable remediation.
+ *
+ * Note: `create` runs `npm install` at the end, which is heavyweight. To
+ * keep test runtime reasonable we skip the npm install step by passing
+ * an alternate npm shim on PATH that is a no-op. Same trick for git.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "node:url";
+import { spawnSync, execFileSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(__dirname, "..");
+const MAESTRO_CLI = resolve(__dirname, "maestro.mjs");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function tmpRoot(prefix = "maestro-cli-test") {
+  const path = join(
+    tmpdir(),
+    `${prefix}-${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 { /* */ }
+}
+
+/**
+ * Build a PATH that shadows `npm` (and optionally `git`) with no-op shims
+ * so `create` doesn't actually try to install dependencies. Returns the new
+ * env block plus the shim dir (for cleanup).
+ */
+async function withShim() {
+  const dir = await tmpRoot("maestro-shim");
+  const npm = join(dir, "npm");
+  writeFileSync(npm, "#!/bin/bash\necho '[shim npm]' \"$@\" >&2\nexit 0\n");
+  await fsp.chmod(npm, 0o755);
+  // Keep real git (we want git init to actually init).
+  const env = { ...process.env, PATH: `${dir}:${process.env.PATH || ""}` };
+  return { env, dir };
+}
+
+function runCli(args, cwd, env) {
+  return spawnSync(process.execPath, [MAESTRO_CLI, ...args], {
+    cwd: cwd || process.cwd(),
+    env: env || process.env,
+    encoding: "utf-8",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+
+test("create scaffolds cadence-bus dirs and enqueue/consumer/handlers", async () => {
+  const parent = await tmpRoot("maestro-create");
+  const { env, dir: shim } = await withShim();
+  try {
+    const r = runCli(["create", "test-agent"], parent, env);
+    assert.equal(r.status, 0, r.stderr || r.stdout);
+    const agent = join(parent, "test-agent");
+
+    // Cadence bus directory tree
+    for (const d of [
+      "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",
+    ]) {
+      assert.ok(existsSync(join(agent, d)), `missing ${d}`);
+    }
+
+    // New framework files copied into the agent repo.
+    for (const f of [
+      "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",
+    ]) {
+      assert.ok(existsSync(join(agent, f)), `missing ${f}`);
+    }
+
+    // Agent package.json has the cadence:* scripts.
+    const pkg = JSON.parse(readFileSync(join(agent, "package.json"), "utf-8"));
+    assert.ok(pkg.scripts["cadence:enqueue"]);
+    assert.ok(pkg.scripts["cadence:consume"]);
+    assert.ok(pkg.scripts["cadence:status"]);
+  } finally {
+    await rmRoot(parent);
+    await rmRoot(shim);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// upgrade — migration
+// ---------------------------------------------------------------------------
+
+async function makeLegacyAgent() {
+  const root = await tmpRoot("maestro-legacy");
+  // Minimal identity so `upgrade` recognises this as a Maestro repo.
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "CLAUDE.md"), "# legacy agent\n");
+  writeFileSync(join(root, "config/agent.ts"), "export const AGENT = { firstName: 'legacy' };\n");
+  writeFileSync(join(root, "package.json"), '{"name":"legacy-agent","version":"1.0.0"}\n');
+  // Personal/local agent state that must NOT be touched.
+  mkdirSync(join(root, "knowledge/decisions"), { recursive: true });
+  mkdirSync(join(root, "memory/interactions"), { recursive: true });
+  mkdirSync(join(root, "state/queues"), { recursive: true });
+  mkdirSync(join(root, "outputs"), { recursive: true });
+  mkdirSync(join(root, "logs"), { recursive: true });
+  writeFileSync(join(root, "knowledge/decisions/local-decision.md"), "# do not touch");
+  writeFileSync(join(root, "memory/interactions/local-memory.yaml"), "# do not touch");
+  writeFileSync(join(root, "state/queues/action-stack.yaml"), "items:\n  - id: P1\n    title: local item\n");
+  writeFileSync(join(root, "outputs/local-output.md"), "# my draft");
+  writeFileSync(join(root, "logs/local.log"), "audit data");
+  writeFileSync(join(root, ".env"), "ANTHROPIC_API_KEY=sk-x\n");
+
+  // Legacy plist that calls run-trigger.sh directly.
+  mkdirSync(join(root, "scripts/local-triggers/plists"), { recursive: true });
+  writeFileSync(
+    join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"),
+    `<?xml version="1.0"?><plist><dict>
+<key>ProgramArguments</key><array>
+  <string>/foo/scripts/local-triggers/run-trigger.sh</string>
+  <string>inbox-processor</string>
+</array></dict></plist>`
+  );
+
+  // Init git so smart-merge sees the working tree as clean.
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["add", "-A"], { cwd: root });
+  execFileSync(
+    "git",
+    ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "init"],
+    { cwd: root },
+  );
+  return root;
+}
+
+test("upgrade backs up legacy plists and regenerates with cadence-bus marker", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    // Backup directory exists.
+    const backupRoot = join(root, ".maestro/backup/plists");
+    assert.ok(existsSync(backupRoot), "backup root must exist");
+    const stamps = readdirSync(backupRoot);
+    assert.ok(stamps.length >= 1);
+    const backedUp = readdirSync(join(backupRoot, stamps[0]));
+    assert.ok(backedUp.some((n) => /legacy-inbox-processor\.plist$/.test(n)));
+
+    // After regeneration, plists carry the cadence-bus marker and none
+    // reference run-trigger.sh.
+    const plistDir = join(root, "scripts/local-triggers/plists");
+    const plists = readdirSync(plistDir).filter((n) => n.endsWith(".plist"));
+    assert.ok(plists.length >= 1);
+    let legacy = 0;
+    let modern = 0;
+    for (const name of plists) {
+      const body = readFileSync(join(plistDir, name), "utf-8");
+      if (body.includes("run-trigger.sh")) legacy++;
+      if (body.includes("maestro-plist-arch: cadence-bus")) modern++;
+    }
+    assert.equal(legacy, 0, "no legacy plists should remain post-upgrade");
+    assert.equal(modern, plists.length, "every plist must carry the cadence-bus marker");
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade preserves agent-specific files untouched", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const before = {
+      claudemd: readFileSync(join(root, "CLAUDE.md"), "utf-8"),
+      agentTs: readFileSync(join(root, "config/agent.ts"), "utf-8"),
+      decision: readFileSync(join(root, "knowledge/decisions/local-decision.md"), "utf-8"),
+      memory: readFileSync(join(root, "memory/interactions/local-memory.yaml"), "utf-8"),
+      queue: readFileSync(join(root, "state/queues/action-stack.yaml"), "utf-8"),
+      output: readFileSync(join(root, "outputs/local-output.md"), "utf-8"),
+      log: readFileSync(join(root, "logs/local.log"), "utf-8"),
+      env: readFileSync(join(root, ".env"), "utf-8"),
+    };
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    for (const [k, v] of Object.entries(before)) {
+      const path = ({
+        claudemd: "CLAUDE.md",
+        agentTs: "config/agent.ts",
+        decision: "knowledge/decisions/local-decision.md",
+        memory: "memory/interactions/local-memory.yaml",
+        queue: "state/queues/action-stack.yaml",
+        output: "outputs/local-output.md",
+        log: "logs/local.log",
+        env: ".env",
+      })[k];
+      assert.equal(
+        readFileSync(join(root, path), "utf-8"),
+        v,
+        `${path} was modified by upgrade`,
+      );
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade is idempotent (second run is a clean no-op for plists)", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const first = runCli(["upgrade"], root);
+    assert.equal(first.status, 0);
+    // Snapshot the regenerated plist contents.
+    const plistDir = join(root, "scripts/local-triggers/plists");
+    const before = {};
+    for (const name of readdirSync(plistDir)) {
+      before[name] = readFileSync(join(plistDir, name), "utf-8");
+    }
+    const second = runCli(["upgrade"], root);
+    assert.equal(second.status, 0);
+    // The second run should NOT introduce any new backup directory beyond
+    // what the first run created, because there are no legacy plists left.
+    const backups = readdirSync(join(root, ".maestro/backup/plists"));
+    assert.equal(backups.length, 1, "no new backup directory on idempotent run");
+    // Plist contents byte-identical.
+    for (const [name, body] of Object.entries(before)) {
+      assert.equal(readFileSync(join(plistDir, name), "utf-8"), body, `${name} changed`);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade --dry-run reports legacy without modifying anything", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    // Snapshot a known sentinel file.
+    const sentinel = readFileSync(join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"), "utf-8");
+    const r = runCli(["upgrade", "--dry-run"], root);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /still call run-trigger\.sh/);
+    // Sentinel must not have changed.
+    assert.equal(
+      readFileSync(join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"), "utf-8"),
+      sentinel,
+    );
+    // No backup directory created.
+    assert.ok(!existsSync(join(root, ".maestro/backup")), "dry-run must not create backups");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor
+// ---------------------------------------------------------------------------
+
+test("doctor flags legacy plists with actionable remediation", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const r = runCli(["doctor"], root);
+    // doctor exits 1 when issues are found; that's expected here.
+    assert.ok(r.status >= 0);
+    const combined = (r.stdout || "") + (r.stderr || "");
+    assert.match(combined, /run-trigger\.sh/);
+    assert.match(combined, /maestro upgrade/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor recognises new cadence-bus architecture after upgrade", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    runCli(["upgrade"], root);
+    const r = runCli(["doctor"], root);
+    const combined = (r.stdout || "") + (r.stderr || "");
+    assert.match(combined, /cadence-bus architecture/);
+    // 'plist(s) still call run-trigger.sh' must NOT appear.
+    assert.ok(!combined.includes("plist(s) still call run-trigger.sh"));
+  } finally { await rmRoot(root); }
+});

package/docs/guides/poller-daemon-setup.md

@@ -43,16 +43,29 @@ The agent has three concurrent execution modes, powered by different subsystems:
 │  │    Up to 10 parallel claude --print sessions                │    │
 │  └────────────────────────────────────────────────────────────┘    │
 ├─────────────────────────────────────────────────────────────────────┤
-│  MODE 2: SCHEDULED — Run Cadence Workflows                        │
+│  MODE 2: SCHEDULED — Run Cadence Workflows via the Cadence Bus     │
 │                                                                     │
-│  ┌──────────┐  ┌──────────────┐  ┌──────────────────────────┐     │
-│  │  launchd  │─▶│  run-trigger │─▶│  claude --print           │     │
-│  │ (schedule)│  │  .sh         │  │  (non-interactive session)│     │
-│  └──────────┘  └──────────────┘  └──────────────────────────┘     │
+│  ┌──────────┐  ┌────────────────────┐  ┌─────────────────────────┐ │
+│  │  launchd  │─▶│ enqueue-cadence-    │─▶│ state/cadence-bus/     │ │
+│  │ (schedule)│  │ tick.mjs (~10ms)    │  │   inbox/<event>.json    │ │
+│  └──────────┘  └────────────────────┘  └────────────┬────────────┘ │
+│                                                       │              │
+│                                            ┌──────────▼───────────┐ │
+│                                            │ cadence-consumer.mjs  │ │
+│                                            │ (inside daemon)       │ │
+│                                            │                       │ │
+│                                            │ ┌─────┐  ┌──────────┐ │ │
+│                                            │ │inline│  │sub-session│ │ │
+│                                            │ └─────┘  └──────────┘ │ │
+│                                            └──────────────────────┘ │
 │                                                                     │
-│  Triggers: morning-brief, midday-sweep, evening-wrap,              │
-│            backlog-executor, inbox-processor, meeting-prep,        │
-│            meeting-action-capture, weekly-*, quarterly-*           │
+│  Per-cadence policy in scripts/daemon/cadence-handlers.mjs:        │
+│    inline    → housekeeping (heartbeat, recovery)                  │
+│    guarded   → cheap pre-check; escalate only if work pending     │
+│    escalate  → spawn claude --print with schedules/triggers/*.md   │
+│                                                                     │
+│  Cadences: inbox-processor, backlog-executor, meeting-prep,        │
+│            meeting-action-capture, daily-*, weekly-*, quarterly-*  │
 ├─────────────────────────────────────────────────────────────────────┤
 │  MODE 3: PROACTIVE — Execute the Backlog                          │
 │                                                                     │

package/docs/runbooks/perpetual-operations.md

@@ -47,39 +47,43 @@ Key configuration:
 - **KeepAlive.SuccessfulExit**: false -- restarts if the process exits with a non-zero code
 - **ThrottleInterval**: 30 seconds -- prevents rapid restart loops
 
-### Per-Workflow Scheduling
+### Per-Workflow Scheduling (Cadence Bus, 1.8+)
 
-Each workflow also has a corresponding `.plist` file in `schedules/` for direct launchd scheduling. Example for the morning brief:
+As of maestro 1.8, scheduled cadence ticks no longer spawn `claude --print` per tick. Each scheduled workflow has a launchd `.plist` at `scripts/local-triggers/plists/` that calls the lightweight Node cadence enqueue script. That script drops a JSON event onto `state/cadence-bus/inbox/`. The persistent daemon (`scripts/daemon/maestro-daemon.mjs`) hosts the consumer that drains the bus and decides whether to handle each tick inline or escalate to a managed sub-session.
+
+Example trigger plist (generated by `scripts/local-triggers/generate-plists.sh`):
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
+<!-- maestro-plist-arch: cadence-bus v1 -->
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>com.adaptic.ceobrain.morning-brief</string>
+    <string>ai.adaptic.<agent>-inbox-processor</string>
     <key>ProgramArguments</key>
     <array>
-        <string>/usr/local/bin/claude</string>
-        <string>--workflow</string>
-        <string>/Users/sophie/sophie-ai/workflows/daily/morning-brief.yaml</string>
+        <string>/Users/<agent>/<agent>-ai/scripts/cadence/launchd-cadence-wrapper.sh</string>
+        <string>/Users/<agent>/<agent>-ai/scripts/cadence/enqueue-cadence-tick.mjs</string>
+        <string>inbox-processor</string>
+        <string>--source=launchd</string>
+        <string>--quiet</string>
     </array>
-    <key>StartCalendarInterval</key>
-    <dict>
-        <key>Hour</key>
-        <integer>6</integer>
-        <key>Minute</key>
-        <integer>0</integer>
-    </dict>
+    <key>StartInterval</key>
+    <integer>300</integer>
     <key>StandardOutPath</key>
-    <string>/Users/sophie/sophie-ai/logs/morning-brief.log</string>
+    <string>/Users/<agent>/<agent>-ai/logs/daemon/launchd-stdout.log</string>
     <key>StandardErrorPath</key>
-    <string>/Users/sophie/sophie-ai/logs/morning-brief-error.log</string>
+    <string>/Users/<agent>/<agent>-ai/logs/daemon/launchd-stderr.log</string>
 </dict>
 </plist>
 ```
 
+The bus consumer's per-tick decisions are logged to `logs/cadence-bus/<date>.jsonl`. Bus depth and consumer heartbeat are available via `npm run cadence:status`. The consumer writes a heartbeat to `state/cadence-bus/health.json` every ~15 seconds; doctor flags it as stale if it's older than 5 minutes.
+
+**Legacy plists (run-trigger.sh):** Plists that still call `scripts/local-triggers/run-trigger.sh` directly are detected by `maestro doctor` and auto-migrated by `maestro upgrade` (backed up under `.maestro/backup/plists/<utc-timestamp>/`). `run-trigger.sh` itself is preserved for manual one-shot operator use only.
+
 ### Managing Jobs
 
 ```bash

package/docs/runbooks/recovery-and-failover.md

@@ -162,6 +162,48 @@ launchctl load ~/Library/LaunchAgents/com.adaptic.maestro.plist
 launchctl list | grep com.adaptic.maestro
 ```
 
+### Cadence Bus Recovery (1.8+)
+
+The cadence bus at `state/cadence-bus/` is the work queue for scheduled cadence ticks. The daemon's consumer drains it; if the daemon crashes mid-tick, the in-flight event remains in `state/cadence-bus/claimed/` until recovered.
+
+**Symptoms of a stuck bus**:
+- `npm run cadence:status` shows `claimed > 0` and `heartbeat_age_ms > 5 minutes`.
+- `logs/cadence-bus/<date>.jsonl` has `stage:claimed` events with no matching `stage:processed` or `stage:dlq`.
+- Bus inbox depth grows over time (`state/cadence-bus/inbox/` has many events).
+
+**Manual recovery**:
+
+```bash
+# 1. Inspect bus state
+npm run cadence:status
+
+# 2. Recover stale claims (returns claims older than 30 min to inbox/, or
+#    moves them to dlq if past retry budget). The consumer also runs this
+#    automatically every 5 minutes — manual run is for impatient operators.
+node -e "import('./lib/cadence-bus.mjs').then(m => console.log(m.recoverStaleClaims(process.cwd())))"
+
+# 3. If the bus is genuinely stuck, restart the daemon
+launchctl unload ~/Library/LaunchAgents/ai.adaptic.<agent>-daemon.plist
+launchctl load ~/Library/LaunchAgents/ai.adaptic.<agent>-daemon.plist
+```
+
+**Resetting the bus** (last resort — loses pending ticks, but they re-arrive at next cadence interval):
+
+```bash
+# Move all in-flight events to a dated archive, then wipe the bus
+ts=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+mkdir -p .maestro/archive/cadence-bus/$ts
+mv state/cadence-bus/inbox state/cadence-bus/claimed state/cadence-bus/dlq .maestro/archive/cadence-bus/$ts/
+mkdir -p state/cadence-bus/{inbox,claimed,processed,failed,dlq}
+```
+
+**Dead-letter queue** (`state/cadence-bus/dlq/`): events that exceeded their retry budget (default 5) land here. Each file is a full event payload with `last_error` and `failed_at`. Review periodically; re-enqueue manually if appropriate:
+
+```bash
+ls state/cadence-bus/dlq/
+node scripts/cadence/enqueue-cadence-tick.mjs <cadence> --source=manual --metadata=note=dlq-replay
+```
+
 ### Desktop App Crashes (Slack, Safari, WhatsApp)
 
 **Symptoms**: Follow-up messages not sent, comms triage returning empty results, desktop control errors in logs.