@cohortapp/agent-sdk 2.3.0

package/scripts/local-triggers/generate-plists.test.mjs

@@ -0,0 +1,413 @@
+/**
+ * generate-plists.test.mjs — Coverage for scripts/local-triggers/generate-plists.sh
+ *
+ * Builds a fixture agent repo (minimal config/agent.ts + script tree),
+ * runs the generator, and asserts every emitted plist matches the
+ * cadence-bus architecture marker and never references the legacy
+ * run-trigger.sh spawn-per-tick pattern.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(__dirname, "..", "..");
+const GENERATOR = resolve(__dirname, "generate-plists.sh");
+
+async function makeAgent(firstName) {
+  const root = join(
+    tmpdir(),
+    `plist-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(root, { recursive: true });
+
+  // Minimal agent identity.
+  await fsp.mkdir(join(root, "config"), { recursive: true });
+  writeFileSync(
+    join(root, "config/agent.ts"),
+    `export const AGENT = { firstName: '${firstName}', lastName: 'Tester' };\n`
+  );
+  writeFileSync(join(root, "package.json"), '{"name":"t"}');
+
+  // Copy the scripts the generator references.
+  await fsp.mkdir(join(root, "scripts/local-triggers"), { recursive: true });
+  await fsp.mkdir(join(root, "scripts/daemon"), { recursive: true });
+  await fsp.mkdir(join(root, "scripts/cadence"), { recursive: true });
+  // The generator now derives the standard cadence set from the canonical
+  // STANDARD_CADENCES in lib/cadences.mjs (SoT), so the fixture needs the
+  // module + its local import chain (capability → archetype).
+  await fsp.mkdir(join(root, "lib"), { recursive: true });
+  for (const m of ["lib/cadences.mjs", "lib/capability.mjs", "lib/archetype.mjs"]) {
+    copyFileSync(join(MAESTRO_ROOT, m), join(root, m));
+  }
+  copyFileSync(GENERATOR, join(root, "scripts/local-triggers/generate-plists.sh"));
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/local-triggers/run-trigger.sh"),
+    join(root, "scripts/local-triggers/run-trigger.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/daemon/launchd-wrapper.sh"),
+    join(root, "scripts/daemon/launchd-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/daemon/launchd-wrapper-generic.sh"),
+    join(root, "scripts/daemon/launchd-wrapper-generic.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-cadence-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-cadence-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/enqueue-cadence-tick.mjs"),
+    join(root, "scripts/cadence/enqueue-cadence-tick.mjs"),
+  );
+
+  // Make scripts executable.
+  for (const p of [
+    "scripts/local-triggers/generate-plists.sh",
+    "scripts/local-triggers/run-trigger.sh",
+    "scripts/daemon/launchd-wrapper.sh",
+    "scripts/daemon/launchd-wrapper-generic.sh",
+    "scripts/cadence/launchd-cadence-wrapper.sh",
+    "scripts/cadence/launchd-socket-mode-wrapper.sh",
+  ]) {
+    await fsp.chmod(join(root, p), 0o755);
+  }
+  return root;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function runGenerator(agentRoot) {
+  return spawnSync("/bin/bash", [join(agentRoot, "scripts/local-triggers/generate-plists.sh")], {
+    cwd: agentRoot,
+    encoding: "utf-8",
+    env: { ...process.env },
+  });
+}
+
+function listPlists(agentRoot) {
+  const dir = join(agentRoot, "scripts/local-triggers/plists");
+  return readdirSync(dir).filter((n) => n.endsWith(".plist"));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test("generator emits 21 standard plists with the agent's first name", async () => {
+  // Standard inventory (cadence-bus v1 + slack-socket-mode v1), with NO
+  // config/.cadence-plists.tsv present (no archetype cadences):
+  //   daemon, poll-relay, slack-socket (3 infra), PLUS one trigger plist per
+  //   STANDARD_CADENCES entry in lib/cadences.mjs (the SoT):
+  //   inbox-processor, backlog-executor, meeting-prep, meeting-action-capture,
+  //   daily-morning-brief, daily-midday-sweep, daily-evening-wrap,
+  //   quarterly-self-assessment, org-pulse, skill-curator (10), PLUS the
+  //   economics/scheduling cadences nightly-cost-reconcile, fleet-cost-digest,
+  //   org-cost-sync, monitoring-alerts, dynamic-jobs (5), PLUS the SP10
+  //   messaging-inbound cadence (1), PLUS the 2026-07 Directory & Design
+  //   stewards directory-hygiene + brand-steward (2). = 3 infra + 18 trigger
+  //   = 21 total.
+  // org-pulse used to be declared standard but was OMITTED by the old hardcoded
+  // list (it never got a plist); deriving from the SoT fixes that drift.
+  // The former weekly-* cadences are still ARCHETYPE-DRIVEN (function × altitude),
+  // emitted from config/.cadence-plists.tsv (scripts/setup/generate-cadences.mjs).
+  const root = await makeAgent("alice");
+  try {
+    const r = runGenerator(root);
+    assert.equal(r.status, 0, r.stderr);
+    const plists = listPlists(root);
+    assert.equal(plists.length, 21, `expected 21 standard plists; got ${plists.join(",")}`);
+    assert.ok(plists.includes("ai.maestro.alice-messaging-inbound.plist"),
+      "messaging-inbound (SP10 standard cadence) must get a SoT-derived plist");
+    for (const id of ["directory-hygiene", "brand-steward"]) {
+      assert.ok(plists.includes(`ai.maestro.alice-${id}.plist`),
+        `Directory/Design steward "${id}" must get a SoT-derived plist; got ${plists.join(",")}`);
+    }
+    assert.ok(plists.includes("ai.maestro.alice-org-pulse.plist"),
+      "org-pulse (declared standard) must get a plist now it's SoT-derived");
+    // The newly-wired economics/scheduling cadences each get a plist.
+    for (const id of ["nightly-cost-reconcile", "fleet-cost-digest", "org-cost-sync", "dynamic-jobs"]) {
+      assert.ok(plists.includes(`ai.maestro.alice-${id}.plist`),
+        `economics cadence "${id}" must get a SoT-derived plist; got ${plists.join(",")}`);
+    }
+    for (const p of plists) {
+      assert.match(p, /^ai\.maestro\.alice-/);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("every cadence resolved by resolveCadences() gets a generated plist (incl. org-pulse)", async () => {
+  // Single-source-of-truth guarantee: the launchd plist set is derived from the
+  // canonical cadence resolution, so a cadence declared in lib/cadences.mjs can
+  // never silently lack a job (the org-pulse-never-fires class of bug).
+  const root = await makeAgent("hana");
+  try {
+    // Drive the archetype TSV too, so we cover standard + archetype in one pass.
+    const { resolveCadences } = await import(join(MAESTRO_ROOT, "lib/cadences.mjs"));
+    const cadences = await resolveCadences({ function: "technical-leader", altitude: "c-suite" });
+    // Emit the archetype (non-standard) cadences via the TSV, exactly as
+    // generate-cadences.mjs does (id|interval| / id||base64(sched)).
+    const tsvLines = [];
+    for (const c of cadences) {
+      if (c.scope === "standard") continue;
+      if (typeof c.interval === "number") tsvLines.push(`${c.id}|${c.interval}|`);
+      else if (c.calendar) {
+        const cal = c.calendar;
+        let x = "";
+        if (cal.weekday != null) x += `        <key>Weekday</key>\n        <integer>${cal.weekday}</integer>\n`;
+        if (cal.day != null) x += `        <key>Day</key>\n        <integer>${cal.day}</integer>\n`;
+        x += `        <key>Hour</key>\n        <integer>${cal.hour ?? 9}</integer>\n        <key>Minute</key>\n        <integer>${cal.minute ?? 0}</integer>`;
+        tsvLines.push(`${c.id}||${Buffer.from(x, "utf-8").toString("base64")}`);
+      }
+    }
+    writeFileSync(join(root, "config/.cadence-plists.tsv"), tsvLines.join("\n") + (tsvLines.length ? "\n" : ""));
+
+    const r = runGenerator(root);
+    assert.equal(r.status, 0, r.stderr);
+    const plists = new Set(listPlists(root));
+    for (const c of cadences) {
+      // skill-curator has a calendar; every resolved cadence here has a
+      // schedule, so each must produce exactly one trigger plist.
+      const label = `ai.maestro.hana-${c.id}.plist`;
+      assert.ok(plists.has(label), `resolved cadence "${c.id}" (${c.scope}) has no plist; got ${[...plists].join(",")}`);
+    }
+    // Spot-check the specific regression: org-pulse is standard and present.
+    assert.ok(plists.has("ai.maestro.hana-org-pulse.plist"), "org-pulse must be present");
+  } finally { await rmRoot(root); }
+});
+
+test("archetype cadences from config/.cadence-plists.tsv emit extra trigger plists", async () => {
+  const root = await makeAgent("erin");
+  try {
+    const calXml = "        <key>Weekday</key>\n        <integer>3</integer>\n        <key>Hour</key>\n        <integer>10</integer>\n        <key>Minute</key>\n        <integer>0</integer>";
+    const tsv =
+      `engineering-health||${Buffer.from(calXml, "utf-8").toString("base64")}\n` +
+      `quality-pulse|1800|\n`;
+    writeFileSync(join(root, "config/.cadence-plists.tsv"), tsv);
+    const r = runGenerator(root);
+    assert.equal(r.status, 0, r.stderr);
+    const plists = listPlists(root);
+    assert.equal(plists.length, 23, `expected 21 standard + 2 archetype; got ${plists.join(",")}`);
+    const dir = join(root, "scripts/local-triggers/plists");
+    const eng = readFileSync(join(dir, "ai.maestro.erin-engineering-health.plist"), "utf-8");
+    assert.match(eng, /<key>Weekday<\/key>\s*<integer>3<\/integer>/); // base64 schedule decoded
+    assert.match(eng, /enqueue-cadence-tick\.mjs/);
+    const qp = readFileSync(join(dir, "ai.maestro.erin-quality-pulse.plist"), "utf-8");
+    assert.match(qp, /<integer>1800<\/integer>/); // interval path
+  } finally { await rmRoot(root); }
+});
+
+test("every trigger plist carries the cadence-bus architecture marker", async () => {
+  const root = await makeAgent("bob");
+  try {
+    runGenerator(root);
+    const dir = join(root, "scripts/local-triggers/plists");
+    for (const name of listPlists(root)) {
+      const body = readFileSync(join(dir, name), "utf-8");
+      assert.match(body, /maestro-plist-arch: cadence-bus/, `${name} missing arch marker`);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("NO trigger plist invokes run-trigger.sh", async () => {
+  const root = await makeAgent("carol");
+  try {
+    runGenerator(root);
+    const dir = join(root, "scripts/local-triggers/plists");
+    for (const name of listPlists(root)) {
+      const body = readFileSync(join(dir, name), "utf-8");
+      // Exception: the daemon/poll-relay/slack-socket plists don't run cadence
+      // triggers at all (the first two are KeepAlive workers; slack-socket is
+      // a KeepAlive WSS listener). The trigger plists must invoke
+      // enqueue-cadence-tick.mjs.
+      if (name.endsWith("-daemon.plist") || name.endsWith("-poll-relay.plist") ||
+          name.endsWith("-slack-socket.plist")) {
+        continue;
+      }
+      assert.ok(!body.includes("run-trigger.sh"),
+        `${name} still references run-trigger.sh:\n${body}`);
+      assert.ok(body.includes("enqueue-cadence-tick.mjs"),
+        `${name} should invoke enqueue script`);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("trigger plists pass --source=launchd to the enqueue script", async () => {
+  const root = await makeAgent("dana");
+  try {
+    runGenerator(root);
+    const dir = join(root, "scripts/local-triggers/plists");
+    const triggerPlist = join(dir, "ai.maestro.dana-inbox-processor.plist");
+    const body = readFileSync(triggerPlist, "utf-8");
+    assert.match(body, /<string>--source=launchd<\/string>/);
+    assert.match(body, /<string>inbox-processor<\/string>/);
+    // StartInterval 300 (every 5 min).
+    assert.match(body, /<integer>300<\/integer>/);
+  } finally { await rmRoot(root); }
+});
+
+test("interval trigger plists pass --interval=<seconds> for the at-most-once gate (WS4)", async () => {
+  const root = await makeAgent("gita");
+  try {
+    runGenerator(root);
+    const dir = join(root, "scripts/local-triggers/plists");
+    // StartInterval cadence: --interval mirrors the interval seconds.
+    const inbox = readFileSync(join(dir, "ai.maestro.gita-inbox-processor.plist"), "utf-8");
+    assert.match(inbox, /<string>--interval=300<\/string>/);
+    // Calendar cadence (daily): carries a daily catch-up interval so an outage
+    // spanning the trigger time fast-forwards to exactly one catch-up tick.
+    const morning = readFileSync(join(dir, "ai.maestro.gita-daily-morning-brief.plist"), "utf-8");
+    assert.match(morning, /<string>--interval=86400<\/string>/);
+    // Still a StartCalendarInterval-driven plist (wall-clock trigger unchanged).
+    assert.match(morning, /<key>StartCalendarInterval<\/key>/);
+  } finally { await rmRoot(root); }
+});
+
+test("economics/scheduling cadences emit plists with the right schedule + enqueue wiring", async () => {
+  const root = await makeAgent("nadia");
+  try {
+    runGenerator(root);
+    const dir = join(root, "scripts/local-triggers/plists");
+    // nightly-cost-reconcile: calendar 03:30, daily catch-up, enqueue wiring.
+    const reconcile = readFileSync(join(dir, "ai.maestro.nadia-nightly-cost-reconcile.plist"), "utf-8");
+    assert.match(reconcile, /<key>StartCalendarInterval<\/key>/);
+    assert.match(reconcile, /<key>Hour<\/key>\s*<integer>3<\/integer>/);
+    assert.match(reconcile, /<key>Minute<\/key>\s*<integer>30<\/integer>/);
+    assert.match(reconcile, /<string>--interval=86400<\/string>/); // daily catch-up
+    assert.match(reconcile, /enqueue-cadence-tick\.mjs/);
+    assert.match(reconcile, /<string>nightly-cost-reconcile<\/string>/);
+    // fleet-cost-digest: calendar 07:00.
+    const digest = readFileSync(join(dir, "ai.maestro.nadia-fleet-cost-digest.plist"), "utf-8");
+    assert.match(digest, /<key>Hour<\/key>\s*<integer>7<\/integer>/);
+    // org-cost-sync: hourly StartInterval.
+    const sync = readFileSync(join(dir, "ai.maestro.nadia-org-cost-sync.plist"), "utf-8");
+    assert.match(sync, /<key>StartInterval<\/key>\s*<integer>3600<\/integer>/);
+    assert.match(sync, /<string>--interval=3600<\/string>/);
+    // dynamic-jobs: 60s StartInterval.
+    const jobs = readFileSync(join(dir, "ai.maestro.nadia-dynamic-jobs.plist"), "utf-8");
+    assert.match(jobs, /<key>StartInterval<\/key>\s*<integer>60<\/integer>/);
+    assert.match(jobs, /<string>--interval=60<\/string>/);
+  } finally { await rmRoot(root); }
+});
+
+test("daemon plist remains a KeepAlive job (not a cadence enqueue)", async () => {
+  const root = await makeAgent("erin");
+  try {
+    runGenerator(root);
+    const path = join(root, "scripts/local-triggers/plists/ai.maestro.erin-daemon.plist");
+    const body = readFileSync(path, "utf-8");
+    // KeepAlive switched 1.9.2 from plain `<true/>` to a dict with
+    // SuccessfulExit:false / Crashed:true so emergency-stop doesn't trigger
+    // a restart treadmill but real crashes still do.
+    assert.match(body, /<key>KeepAlive<\/key>/);
+    assert.match(body, /<key>SuccessfulExit<\/key>\s*<false\/>/);
+    assert.match(body, /<key>Crashed<\/key>\s*<true\/>/);
+    assert.match(body, /launchd-wrapper\.sh/);
+    assert.ok(!body.includes("enqueue-cadence-tick.mjs"),
+      "daemon plist should not enqueue ticks — it IS the consumer");
+  } finally { await rmRoot(root); }
+});
+
+test("generator reads firstName from agent.json when agent.ts is type-only (SOT layout)", async () => {
+  // Reproduce the SOT layout where agent.ts only declares interfaces
+  // (containing `firstName: string;` as a type, not a value) and the
+  // actual identity lives in agent.json. The legacy resolver matched the
+  // interface line and produced labels like
+  // `ai.maestro.  firstname:   string;-…` — guard against regression.
+  const root = join(
+    tmpdir(),
+    `plist-sot-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(root, { recursive: true });
+  // Manually wire the same fixture-builder used by other tests, except
+  // overwrite agent.ts to look like a type-only TypeScript file and add
+  // a real agent.json.
+  await fsp.mkdir(join(root, "config"), { recursive: true });
+  writeFileSync(
+    join(root, "config/agent.ts"),
+    `// Type declarations only — value lives in agent.json
+export interface PrincipalConfig { firstName: string; }
+export interface AgentConfig { firstName: string; }
+`,
+  );
+  writeFileSync(
+    join(root, "config/agent.json"),
+    JSON.stringify({ firstName: "Sigrid", lastName: "Test" }) + "\n",
+  );
+  writeFileSync(join(root, "package.json"), '{"name":"t"}');
+
+  await fsp.mkdir(join(root, "scripts/local-triggers"), { recursive: true });
+  await fsp.mkdir(join(root, "scripts/daemon"), { recursive: true });
+  await fsp.mkdir(join(root, "scripts/cadence"), { recursive: true });
+  // Same set of helper scripts as makeAgent().
+  const { copyFileSync } = await import("node:fs");
+  copyFileSync(GENERATOR, join(root, "scripts/local-triggers/generate-plists.sh"));
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/local-triggers/run-trigger.sh"),
+    join(root, "scripts/local-triggers/run-trigger.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/daemon/launchd-wrapper.sh"),
+    join(root, "scripts/daemon/launchd-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/daemon/launchd-wrapper-generic.sh"),
+    join(root, "scripts/daemon/launchd-wrapper-generic.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-cadence-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-cadence-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+  );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/enqueue-cadence-tick.mjs"),
+    join(root, "scripts/cadence/enqueue-cadence-tick.mjs"),
+  );
+  await fsp.chmod(join(root, "scripts/local-triggers/generate-plists.sh"), 0o755);
+
+  try {
+    const r = runGenerator(root);
+    assert.equal(r.status, 0, r.stderr);
+    const plists = listPlists(root);
+    assert.ok(plists.length >= 1);
+    for (const p of plists) {
+      assert.match(p, /^ai\.maestro\.sigrid-/, `expected "sigrid" label, got: ${p}`);
+      assert.ok(!p.includes("string"),
+        `label leaked the TypeScript type: ${p}`);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("regeneration clears stale plists", async () => {
+  const root = await makeAgent("frank");
+  try {
+    // Plant a stale plist for a long-gone agent — intentionally using the legacy
+    // ai.adaptic.* namespace to confirm pre-rename plists are also cleared on regen.
+    const dir = join(root, "scripts/local-triggers/plists");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "ai.adaptic.OLD-AGENT-stale.plist"), "<plist/>");
+    runGenerator(root);
+    const remaining = listPlists(root);
+    assert.ok(!remaining.includes("ai.adaptic.OLD-AGENT-stale.plist"),
+      "generator must clear stale plists");
+    for (const p of remaining) {
+      assert.match(p, /^ai\.maestro\.frank-/);
+    }
+  } finally { await rmRoot(root); }
+});

package/scripts/local-triggers/install-all.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Install all local agent triggers as macOS launchd daemons
+# Usage: ./scripts/local-triggers/install-all.sh
+#
+# This generates plist files from agent config and installs them.
+# The generate-plists.sh script reads config/agent.ts to determine
+# the agent name and generates properly configured plist files.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PLIST_DIR="$SCRIPT_DIR/plists"
+GENERATOR="$SCRIPT_DIR/generate-plists.sh"
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+
+mkdir -p "$LAUNCH_AGENTS_DIR"
+
+# Generate plists from agent config
+if [ -x "$GENERATOR" ]; then
+    echo "Generating plist files from agent config..."
+    bash "$GENERATOR"
+else
+    echo "Warning: generate-plists.sh not found — using existing plists"
+fi
+
+echo ""
+echo "Installing local triggers..."
+
+for plist in "$PLIST_DIR"/*.plist; do
+    [ -f "$plist" ] || continue
+    PLIST_NAME=$(basename "$plist")
+    LABEL=$(basename "$plist" .plist)
+    DST="$LAUNCH_AGENTS_DIR/$PLIST_NAME"
+
+    # Unload if already loaded
+    launchctl unload "$DST" 2>/dev/null || true
+
+    # Copy and load
+    cp "$plist" "$DST"
+    launchctl load "$DST"
+
+    echo "  Installed: $LABEL"
+done
+
+echo ""
+echo "All local triggers installed."
+echo "Check status: launchctl list | grep -E 'maestro|adaptic'"
+echo "Uninstall all: for f in ~/Library/LaunchAgents/ai.{maestro,adaptic}.*.plist; do launchctl unload \"\$f\" && rm \"\$f\"; done"

package/scripts/local-triggers/run-trigger.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Run a local scheduled trigger via Claude Code CLI (legacy / manual path).
+#
+# Usage: run-trigger.sh <trigger-name>
+#
+# Reads the prompt from schedules/triggers/<trigger-name>.md and runs it as
+# a non-interactive `claude --print` session.
+#
+# ⚠ LEGACY PATH — DO NOT USE FROM LAUNCHD ⚠
+#
+# As of the cadence-bus architecture (maestro 1.8), scheduled cadence ticks
+# go through scripts/cadence/enqueue-cadence-tick.mjs instead of running
+# claude directly. The persistent maestro-daemon.mjs consumes events from
+# state/cadence-bus/ and decides whether to handle them inline or escalate
+# to a managed sub-session.
+#
+# This script remains available for two specific purposes:
+#   1. Manual one-shot invocation by an operator who wants to run a single
+#      cadence prompt immediately, without waiting for the daemon.
+#   2. Compatibility with very old launchd plists during migration. Doctor
+#      / upgrade will flag plists that still call this script and rewrite
+#      them through the cadence bus.
+#
+# Prefer instead:
+#   node scripts/cadence/enqueue-cadence-tick.mjs <trigger-name> --source=manual
+
+set -e
+
+TRIGGER_NAME="${1:?Trigger name required}"
+AGENT_REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+PROMPT_FILE="$AGENT_REPO_DIR/schedules/triggers/$TRIGGER_NAME.md"
+CLAUDE_BIN="${CLAUDE_BIN:-claude}"
+LOG_DIR="$AGENT_REPO_DIR/logs/workflows"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+DATE=$(date +%Y-%m-%d)
+LOG_FILE="$LOG_DIR/$DATE-$TRIGGER_NAME.jsonl"
+
+# Check emergency stop
+if [ -f "$AGENT_REPO_DIR/.emergency-stop" ]; then
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"trigger\":\"$TRIGGER_NAME\",\"status\":\"blocked\",\"reason\":\"emergency-stop\"}" >> "$LOG_FILE"
+    exit 0
+fi
+
+# Check prompt file exists
+if [ ! -f "$PROMPT_FILE" ]; then
+    echo "ERROR: Prompt file not found: $PROMPT_FILE" >&2
+    exit 1
+fi
+
+# Read the prompt
+PROMPT=$(cat "$PROMPT_FILE")
+
+# Log trigger start
+mkdir -p "$LOG_DIR"
+echo "{\"timestamp\":\"$TIMESTAMP\",\"trigger\":\"$TRIGGER_NAME\",\"status\":\"started\"}" >> "$LOG_FILE"
+
+# Run Claude Code in non-interactive mode
+cd "$AGENT_REPO_DIR"
+"$CLAUDE_BIN" --print --dangerously-skip-permissions "$PROMPT" >> "$LOG_DIR/$DATE-$TRIGGER_NAME.log" 2>&1
+
+EXIT_CODE=$?
+END_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+echo "{\"timestamp\":\"$END_TIMESTAMP\",\"trigger\":\"$TRIGGER_NAME\",\"status\":\"completed\",\"exit_code\":$EXIT_CODE}" >> "$LOG_FILE"

package/scripts/local-triggers/templates/rag-reindex.plist.template

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- maestro-plist-arch: cadence-bus v1 -->
+<!-- rag-reindex plist template — refresh the FTS5 index every hour so
+     newly-written memory / decisions / briefs are searchable promptly. -->
+<!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>ai.maestro.{{FIRSTNAME}}-rag-reindex</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_BIN}}</string>
+        <string>{{AGENT_ROOT}}/scripts/rag/build-index.mjs</string>
+        <string>--quiet</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{AGENT_ROOT}}</string>
+
+    <!-- Every 60 minutes; FTS5 incremental updates are fast (<1s for
+         a few hundred files) so the cost is negligible. -->
+    <key>StartInterval</key>
+    <integer>3600</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>USER</key>
+        <string>{{USER}}</string>
+        <key>AGENT_ROOT</key>
+        <string>{{AGENT_ROOT}}</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>{{AGENT_ROOT}}/logs/rag/reindex-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{AGENT_ROOT}}/logs/rag/reindex-stderr.log</string>
+</dict>
+</plist>

package/scripts/local-triggers/templates/voice-relay-poller.plist.template

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- maestro-plist-arch: cadence-bus v1 -->
+<!-- voice-relay-poller plist template — long-running daemon that polls
+     the Railway-hosted voice cloud-relay for buffered OpenAI
+     realtime.call.incoming events and forwards them to the local
+     voice-webhook-server on port 3200. -->
+<!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>ai.maestro.{{FIRSTNAME}}-voice-relay-poller</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_BIN}}</string>
+        <string>{{AGENT_ROOT}}/scripts/poller/voice-cloud-relay-client.mjs</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{AGENT_ROOT}}</string>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>ThrottleInterval</key>
+    <integer>15</integer>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>USER</key>
+        <string>{{USER}}</string>
+        <key>AGENT_ROOT</key>
+        <string>{{AGENT_ROOT}}</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/relay-poller-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/relay-poller-stderr.log</string>
+</dict>
+</plist>