@cohortapp/agent-sdk 2.3.0

package/schedules/triggers/weekly-strategic-memo.md

@@ -0,0 +1,124 @@
+You are {{agent.fullName}}, {{agent.title}} to {{agent.principal.fullName}}, {{agent.principal.title}} of {{agent.company}}.
+
+## Workflow: Weekly Strategic Memo
+
+## Cadence: Friday 14:00 GST
+
+## Working Directory: the agent repo root (your current working directory)
+
+### Instructions
+
+1. Read `state/dashboards/executive-summary.yaml`
+2. Read `config/priorities.yaml`
+3. Read `knowledge/syntheses/strategic-synthesis.yaml`
+4. Review this week's interactions from `memory/interactions/` — key themes and signals
+5. Review this week's decisions from `knowledge/decisions/`
+6. Check `state/queues/narrative-opportunities.yaml` for content opportunities
+
+7. **Strategic coherence check:**
+   - Read `config/priorities.yaml` for the 5 strategic priorities
+   - Scan all queue items across all 15 queues in `state/queues/` — map each to a priority using context
+   - Flag and include in the memo:
+     - Priorities with zero active queue items (stalled — nobody working on it)
+     - Queue items not mappable to any priority (unlinked work — effort without strategic purpose)
+     - Priorities where all items are blocked (stuck — needs intervention)
+     - Any apparent conflicts between initiatives
+
+8. **Cadence quality audit:**
+   - Read `memory/interactions/meetings/` for all meetings this week
+   - For each meeting, check:
+     - Were actions captured? (meeting record exists with non-empty actions list)
+     - Were actions assigned owners and deadlines?
+     - Were previous meeting's actions closed?
+   - Calculate and include in memo:
+     - Meetings this week: total count
+     - Action capture rate: % of meetings with captured actions
+     - Action closure rate: % of last week's meeting actions now closed
+     - Flag: meetings with consistently zero outputs (suggest cancellation)
+     - Flag: meetings where actions captured but never closed (accountability gap)
+
+9. **Update living strategy state:**
+   - Read `knowledge/syntheses/strategy-state.yaml`
+   - Update based on this week's developments:
+     - Refresh `strategic_position` if anything material changed
+     - Update `key_assumptions` status based on new evidence
+     - Add any `emerging_signals` observed this week
+     - Update `strategic_risks` severity/likelihood based on new information
+     - Add this week's decisions to `recent_decisions`
+     - Refresh `next_quarter_focus` if priorities shifted
+   - Write updated file back
+
+10. **Leadership effectiveness scorecard:**
+    - Read `state/dashboards/leadership-accountability.yaml`
+    - For each leader: summarise commitments met/missed, response quality, trend
+    - Flag patterns: consistently missing deadlines, going silent, declining accountability
+    - Include {{agent.firstName}}'s candid assessment and specific recommendations
+    - NOTE: This section is sensitive — send via DM to {{agent.principal.firstName}}, not in any channel
+
+11. **Relationship pipeline update:**
+    - Read `state/dashboards/relationship-pipeline.yaml`
+    - Review `memory/interactions/` for all external interactions this week
+    - Update relationship stages and warmth based on interaction recency
+    - Flag cooling relationships (no interaction >2 weeks for active relationships)
+    - Flag overdue next-actions on relationships
+    - Write updated pipeline to `state/dashboards/relationship-pipeline.yaml`
+
+12. **Commercial position assessment:**
+    - Read market signals from `memory/precedents/market-signals/`
+    - Assess: ICP clarity, pipeline warmth, partner engagement, competitive positioning
+    - Synthesise into "Commercial Position" section in the memo
+
+13. **Founder dependency flag:**
+    - Read `state/dashboards/org-health.yaml` founder_dependency section
+    - If threshold_breached (>60%), include prominent flag in memo with delegation recommendations
+
+14. **Advisor utilisation review:**
+    - Read `state/dashboards/relationship-pipeline.yaml` advisors section
+    - For each advisor: when was last interaction? Was value extracted?
+    - Flag advisors not contacted in >30 days
+    - Recommend specific re-engagement actions for underutilised advisors
+
+15. **Risk register review:**
+    - Read `state/dashboards/risk-register.yaml`
+    - For each risk: is the review date approaching or past?
+    - Have any risk conditions changed based on this week's developments?
+    - Update risk severity/likelihood if warranted
+    - Flag any new risks identified this week
+    - Write updated risk register back
+
+16. **Capital position update:**
+    - Read `state/dashboards/capital-readiness.yaml`
+    - Update fundraising readiness components based on this week's progress
+    - Update investor and corp dev pipeline counts
+    - Note any approaching capital-related milestones
+    - Write updated dashboard back
+
+17. Synthesise a weekly strategic memo covering:
+    - Week in review: key accomplishments and setbacks
+    - Strategic position: how did we advance this week?
+    - Strategy scorecard: per-priority status from `state/dashboards/strategy-scorecard.yaml`
+    - **Coherence check findings** (stalled priorities, unlinked work, conflicts)
+    - Emerging signals: what changed in the environment?
+    - **Cadence health** (meeting → action capture rate, closure rate, flagged meetings)
+    - **Leadership effectiveness scorecard** ({{agent.principal.firstName}} DM only)
+    - **Engineering health** from `state/dashboards/engineering-health.yaml`
+    - **Relationship pipeline health** (warming/cooling/overdue)
+    - **Commercial position** (ICP, pipeline, competitive)
+    - **Founder dependency alert** (if >60%)
+    - **Advisor utilisation** (who's engaged, who's dormant, re-engagement recs)
+    - **Risk register update** (new risks, changed severity, overdue reviews)
+    - **Capital position** (runway, readiness score, pipeline, approaching milestones)
+    - Next week preview: what matters most?
+    - Recommendations: 2-3 things {{agent.firstName}} recommends the {{agent.principal.title}} focus on
+18. Write memo to `outputs/memos/{date}-strategic-memo.md`
+19. Send to {{agent.principal.firstName}} via Slack or email (executive-quality document)
+20. Update `knowledge/syntheses/strategic-synthesis.yaml` with any new insights
+21. Prepare week-ahead items: update Monday's priorities queue
+22. Log to `logs/workflows/{date}-weekly-strategic-memo.jsonl`
+
+### Operating Rules
+
+- This is the most important written output of the week — quality matters
+- Be analytical and forward-looking, not just retrospective
+- Include {{agent.firstName}}'s own strategic observations and recommendations
+- If using PDF generation, use: `npm run pdf:memo -- --input outputs/memos/{date}-strategic-memo.md`

package/scripts/archive-email.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# archive-email.sh — Archive non-actionable Gmail messages via IMAP
+# Usage: ./scripts/archive-email.sh
+# Requires GMAIL_APP_PASSWORD environment variable
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+# Pull AGENT_EMAIL + GMAIL_APP_PASSWORD from agent.env + .env
+[ -f "$AGENT_REPO_DIR/config/agent.env" ] && source "$AGENT_REPO_DIR/config/agent.env"
+[ -f "$AGENT_REPO_DIR/.env" ] && source "$AGENT_REPO_DIR/.env"
+
+if [ -z "${GMAIL_APP_PASSWORD:-}" ]; then
+  echo "ERROR: GMAIL_APP_PASSWORD not set" >&2
+  exit 1
+fi
+export AGENT_EMAIL
+export GMAIL_APP_PASSWORD
+
+python3 << 'PYEOF'
+import imaplib
+import os
+
+user = os.environ.get("AGENT_EMAIL", "")
+password = os.environ["GMAIL_APP_PASSWORD"]
+if not user:
+    raise SystemExit("AGENT_EMAIL not set — check config/agent.env")
+
+mail = imaplib.IMAP4_SSL("imap.gmail.com")
+mail.login(user, password)
+mail.select("INBOX")
+
+# Non-actionable sender domains to auto-archive
+junk_domains = [
+    "greptile.com", "gamma.app", "linear.app", "netlify.com",
+    "consensus.app", "zapier.com", "calendly.com", "jam.dev",
+    "send.zapier.com", "mail.consensus.app", "send.calendly.com",
+    "noreply@netlify.com", "hello@greptile.com", "hello@gamma.app",
+]
+
+archived = 0
+for domain in junk_domains:
+    status, messages = mail.search(None, f'(UNSEEN FROM "{domain}")')
+    if status == "OK" and messages[0]:
+        for num in messages[0].split():
+            mail.store(num, '+FLAGS', '\\Seen')
+            mail.copy(num, '"[Gmail]/All Mail"')
+            mail.store(num, '+FLAGS', '\\Deleted')
+            archived += 1
+
+mail.expunge()
+mail.logout()
+print(f"Archived {archived} non-actionable emails")
+PYEOF

package/scripts/cadence/cadence-status.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * cadence-status.mjs — Print the current cadence-bus depth + heartbeat.
+ *
+ * Used by `npm run cadence:status` and by `maestro doctor` for a quick
+ * snapshot. Reads files only; never mutates state.
+ *
+ * Output (JSON):
+ *   {
+ *     "depth":  { "inbox": N, "claimed": N, "dlq": N, "failed": N },
+ *     "health": { ... } | null,
+ *     "heartbeat_age_ms": N | null
+ *   }
+ *
+ * Exit code is always 0 — health interpretation is the caller's job.
+ */
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { busDepth, readHealth, getBusPaths } = await import(
+  resolve(__dirname, "..", "..", "lib", "cadence-bus.mjs")
+);
+
+const paths = getBusPaths();
+const depth = busDepth();
+const health = readHealth();
+const heartbeatAgeMs = health?.ts ? Date.now() - new Date(health.ts).getTime() : null;
+
+process.stdout.write(JSON.stringify({
+  agent_root: paths.agentRoot,
+  depth,
+  health,
+  heartbeat_age_ms: heartbeatAgeMs,
+}, null, 2) + "\n");

package/scripts/cadence/enqueue-cadence-tick.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Maestro — enqueue-cadence-tick.mjs
+ *
+ * Lightweight cadence-bus enqueue CLI. Designed to be invoked from launchd
+ * plists (or manual scripting) in place of `claude --print` per tick. The
+ * heavy lifting — running the cadence, deciding whether to spawn a sub-
+ * session, etc. — is owned by the persistent Maestro daemon, which consumes
+ * events from the bus.
+ *
+ * Design constraints:
+ *   • Must finish in well under a second so launchd never piles up.
+ *   • Must never spawn Claude Code itself.
+ *   • Must be safe to call when the daemon is down (event still lands on
+ *     disk and is processed on next consumer startup).
+ *   • Must honour .emergency-stop (no event lands in inbox/; suppressed
+ *     event is still recorded in queue.jsonl for audit).
+ *
+ * Usage:
+ *   node scripts/cadence/enqueue-cadence-tick.mjs <cadence-name> [options]
+ *
+ * Options:
+ *   --source=<label>          launchd | manual | daemon | init-maestro | upgrade  (default: manual)
+ *   --workflow=<path>         e.g. continuous/inbox-processor
+ *   --priority=<high|normal|low>
+ *   --correlation-id=<id>
+ *   --interval=<seconds>      Cadence interval in seconds (WS4). When present,
+ *                             the bus enforces at-most-once delivery per
+ *                             interval (grace window + stale fast-forward after
+ *                             an outage). Passed by generate-plists.sh from the
+ *                             plist's StartInterval/StartCalendarInterval. Absent
+ *                             → legacy behaviour (every fire enqueues).
+ *   --metadata=<key=value>    May be repeated. Comma-separated pairs also accepted.
+ *   --quiet                   Suppress stdout JSON line.
+ *   --help                    Show this help.
+ *
+ * Exit codes:
+ *   0  — enqueued (or suppressed by emergency-stop, which is still success)
+ *   2  — invalid usage / missing required arg
+ *   3  — internal failure (disk full, permissions, etc.) — caller should retry
+ *
+ * Examples:
+ *   # Launchd plist invokes this every 10 minutes:
+ *   node scripts/cadence/enqueue-cadence-tick.mjs backlog-executor --source=launchd
+ *
+ *   # Manual smoke-test:
+ *   node scripts/cadence/enqueue-cadence-tick.mjs inbox-processor --source=manual --metadata=note=smoke
+ */
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Resolve cadence-bus relative to this script so the same enqueue works
+// whether invoked from the framework repo (~/maestro/scripts/cadence/...)
+// or from a generated agent repo (~/<agent>/scripts/cadence/...).
+const { enqueueTick, BUS_VERSION } = await import(
+  resolve(__dirname, "..", "..", "lib", "cadence-bus.mjs")
+);
+
+function printHelp() {
+  process.stdout.write(`enqueue-cadence-tick — Maestro cadence bus producer
+
+Usage:
+  node scripts/cadence/enqueue-cadence-tick.mjs <cadence-name> [options]
+
+Options:
+  --source=<label>             launchd | manual | daemon | init-maestro | upgrade
+  --workflow=<path>            e.g. continuous/inbox-processor
+  --priority=<high|normal|low>
+  --correlation-id=<id>
+  --metadata=<key=value>       repeatable, or comma-separated pairs
+  --quiet                      suppress JSON output to stdout
+  --version                    print bus version and exit
+  --help, -h                   show this help
+
+Exits 0 on success (including emergency-stop suppression).
+`);
+}
+
+function parseMetadata(raw) {
+  // Accept --metadata=key=value, repeated, or --metadata=k1=v1,k2=v2.
+  const out = {};
+  for (const item of raw) {
+    if (!item) continue;
+    for (const pair of String(item).split(",")) {
+      const idx = pair.indexOf("=");
+      if (idx === -1) continue;
+      const k = pair.slice(0, idx).trim();
+      const v = pair.slice(idx + 1).trim();
+      if (k) out[k] = v;
+    }
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const args = { cadence: null, source: "manual", metadata: [], quiet: false };
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") return { help: true };
+    if (arg === "--version") return { version: true };
+    if (arg === "--quiet") { args.quiet = true; continue; }
+    if (arg.startsWith("--source=")) { args.source = arg.slice("--source=".length); continue; }
+    if (arg.startsWith("--workflow=")) { args.workflow = arg.slice("--workflow=".length); continue; }
+    if (arg.startsWith("--priority=")) { args.priority = arg.slice("--priority=".length); continue; }
+    if (arg.startsWith("--correlation-id=")) { args.correlation_id = arg.slice("--correlation-id=".length); continue; }
+    if (arg.startsWith("--interval=")) { args.interval = arg.slice("--interval=".length); continue; }
+    if (arg.startsWith("--metadata=")) { args.metadata.push(arg.slice("--metadata=".length)); continue; }
+    if (arg.startsWith("--")) {
+      process.stderr.write(`enqueue-cadence-tick: unknown flag: ${arg}\n`);
+      return { invalid: true };
+    }
+    if (!args.cadence) { args.cadence = arg; continue; }
+    process.stderr.write(`enqueue-cadence-tick: unexpected positional arg: ${arg}\n`);
+    return { invalid: true };
+  }
+  return args;
+}
+
+const argv = process.argv.slice(2);
+const parsed = parseArgs(argv);
+
+if (parsed.help) {
+  printHelp();
+  process.exit(0);
+}
+if (parsed.version) {
+  process.stdout.write(`${BUS_VERSION}\n`);
+  process.exit(0);
+}
+if (parsed.invalid) {
+  printHelp();
+  process.exit(2);
+}
+if (!parsed.cadence) {
+  process.stderr.write("enqueue-cadence-tick: <cadence-name> required\n");
+  printHelp();
+  process.exit(2);
+}
+
+// Convert --interval=<seconds> to milliseconds for the bus. Non-numeric or
+// non-positive values are ignored (falls back to legacy every-fire behaviour).
+let intervalMs;
+if (parsed.interval !== undefined) {
+  const secs = Number(parsed.interval);
+  if (Number.isFinite(secs) && secs > 0) intervalMs = Math.round(secs * 1000);
+}
+
+try {
+  const result = enqueueTick({
+    cadence: parsed.cadence,
+    source: parsed.source,
+    workflow: parsed.workflow,
+    priority: parsed.priority,
+    correlation_id: parsed.correlation_id,
+    intervalMs,
+    metadata: parseMetadata(parsed.metadata),
+  });
+  if (!parsed.quiet) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      id: result.id,
+      cadence: parsed.cadence,
+      path: result.path,
+      fallback_only: result.fallbackOnly,
+      skipped: result.skipped || null,
+    }) + "\n");
+  }
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(`enqueue-cadence-tick: ${err.message}\n`);
+  process.exit(3);
+}

package/scripts/cadence/enqueue-cadence-tick.test.mjs

@@ -0,0 +1,187 @@
+/**
+ * enqueue-cadence-tick.test.mjs — node:test coverage for the CLI enqueue
+ * script (the entry point used by launchd plists).
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, readFileSync, existsSync } 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 ENQUEUE_SCRIPT = resolve(__dirname, "enqueue-cadence-tick.mjs");
+
+async function makeAgentRoot() {
+  const path = join(
+    tmpdir(),
+    `enqueue-cli-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function run(cwd, args, env = {}) {
+  return spawnSync(process.execPath, [ENQUEUE_SCRIPT, ...args], {
+    cwd,
+    env: { ...process.env, AGENT_ROOT: cwd, ...env },
+    encoding: "utf-8",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Happy path
+// ---------------------------------------------------------------------------
+
+test("CLI enqueues a tick and writes inbox JSON", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["inbox-processor", "--source=launchd"]);
+    assert.equal(r.status, 0, r.stderr);
+    const out = JSON.parse(r.stdout.trim());
+    assert.equal(out.ok, true);
+    assert.equal(out.cadence, "inbox-processor");
+    assert.equal(out.fallback_only, false);
+    assert.ok(out.path);
+    assert.ok(existsSync(out.path));
+    const event = JSON.parse(readFileSync(out.path, "utf-8"));
+    assert.equal(event.source, "launchd");
+    assert.equal(event.cadence, "inbox-processor");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI accepts metadata pairs (repeated and comma-separated)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, [
+      "weekly-strategic-memo",
+      "--source=manual",
+      "--metadata=note=launch",
+      "--metadata=k1=v1,k2=v2",
+    ]);
+    assert.equal(r.status, 0);
+    const out = JSON.parse(r.stdout.trim());
+    const event = JSON.parse(readFileSync(out.path, "utf-8"));
+    assert.equal(event.metadata.note, "launch");
+    assert.equal(event.metadata.k1, "v1");
+    assert.equal(event.metadata.k2, "v2");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --interval enables the at-most-once gate (duplicate fire suppressed)", async () => {
+  const root = await makeAgentRoot();
+  try {
+    // First fire admits.
+    const r1 = run(root, ["inbox-processor", "--source=launchd", "--interval=300"]);
+    assert.equal(r1.status, 0, r1.stderr);
+    const out1 = JSON.parse(r1.stdout.trim());
+    assert.ok(out1.path, "first interval-bearing tick admits");
+    // Immediate second fire (well within the grace window) is suppressed.
+    const r2 = run(root, ["inbox-processor", "--source=launchd", "--interval=300"]);
+    assert.equal(r2.status, 0, r2.stderr);
+    const out2 = JSON.parse(r2.stdout.trim());
+    assert.equal(out2.path, null);
+    assert.equal(out2.skipped, "before-grace-window");
+    // schedule.json was created.
+    assert.ok(existsSync(join(root, "state/cadence-bus/schedule.json")));
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --interval=0 / non-numeric falls back to legacy every-fire behaviour", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const a = run(root, ["inbox-processor", "--source=launchd", "--interval=0"]);
+    const b = run(root, ["inbox-processor", "--source=launchd", "--interval=oops"]);
+    assert.equal(a.status, 0);
+    assert.equal(b.status, 0);
+    assert.ok(JSON.parse(a.stdout.trim()).path);
+    assert.ok(JSON.parse(b.stdout.trim()).path);
+    // No schedule.json created when the gate is inactive.
+    assert.equal(existsSync(join(root, "state/cadence-bus/schedule.json")), false);
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --quiet suppresses stdout JSON", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["inbox-processor", "--source=launchd", "--quiet"]);
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout.trim(), "");
+  } finally { await rmRoot(root); }
+});
+
+test("CLI --version prints bus schema version", async () => {
+  const r = spawnSync(process.execPath, [ENQUEUE_SCRIPT, "--version"], { encoding: "utf-8" });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /^\d+$/m);
+});
+
+test("CLI --help prints usage and exits 0", async () => {
+  const r = spawnSync(process.execPath, [ENQUEUE_SCRIPT, "--help"], { encoding: "utf-8" });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /enqueue-cadence-tick/);
+});
+
+// ---------------------------------------------------------------------------
+// Error paths
+// ---------------------------------------------------------------------------
+
+test("CLI exits 2 with no cadence", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, []);
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /required/);
+  } finally { await rmRoot(root); }
+});
+
+test("CLI exits 2 on unknown flag", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const r = run(root, ["x", "--what-is-this"]);
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /unknown flag/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Emergency stop
+// ---------------------------------------------------------------------------
+
+test("CLI returns 0 with skipped=emergency-stop when stop flag exists", async () => {
+  const root = await makeAgentRoot();
+  try {
+    writeFileSync(join(root, ".emergency-stop"), "now");
+    const r = run(root, ["weekly-strategic-memo", "--source=launchd"]);
+    assert.equal(r.status, 0);
+    const out = JSON.parse(r.stdout.trim());
+    assert.equal(out.skipped, "emergency-stop");
+    assert.equal(out.fallback_only, true);
+    assert.equal(out.path, null);
+    // No file landed in inbox/.
+    assert.ok(!existsSync(join(root, "state/cadence-bus/inbox", `${out.id}.json`)));
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// Bus-handoff sanity — the CLI must finish in well under a second so launchd
+// never piles up; we don't pin a number, just a generous ceiling.
+// ---------------------------------------------------------------------------
+
+test("CLI completes in well under 2 seconds", async () => {
+  const root = await makeAgentRoot();
+  try {
+    const t0 = Date.now();
+    const r = run(root, ["inbox-processor", "--source=launchd", "--quiet"]);
+    const dt = Date.now() - t0;
+    assert.equal(r.status, 0);
+    assert.ok(dt < 2000, `enqueue took ${dt}ms`);
+  } finally { await rmRoot(root); }
+});

package/scripts/cadence/launchd-cadence-wrapper.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# launchd-cadence-wrapper.sh — Bootstraps env and execs the Node cadence
+# enqueue script under launchd.
+#
+# Usage in a plist:
+#   <key>ProgramArguments</key>
+#   <array>
+#     <string>/path/to/scripts/cadence/launchd-cadence-wrapper.sh</string>
+#     <string>/path/to/scripts/cadence/enqueue-cadence-tick.mjs</string>
+#     <string>cadence-name</string>
+#     <string>--source=launchd</string>
+#   </array>
+#
+# What it does:
+#   1. Sets HOME, PATH, USER, AGENT_ROOT (launchd's bare env doesn't include them).
+#   2. Picks a node binary (nvm, homebrew, system fallback).
+#   3. Redirects stdout/stderr to logs/cadence-bus/launchd-YYYY-MM-DD.log.
+#   4. Exec's `node <enqueue-script> "$@"`.
+#
+# This is a *pure enqueue* wrapper — it must NOT spawn Claude Code. The
+# heavyweight cadence work happens inside the persistent daemon's cadence
+# consumer, not here.
+
+set -e
+
+if [ $# -lt 1 ]; then
+  echo "[cadence-wrapper] FATAL: enqueue script path required" >&2
+  exit 64
+fi
+
+ENQUEUE_SCRIPT="$1"
+shift
+
+# Walk up from the enqueue script to find the agent root. AGENT_ROOT is the
+# nearest ancestor with both package.json and config/.
+TARGET_DIR="$(cd "$(dirname "$ENQUEUE_SCRIPT")" && pwd -P)"
+CANDIDATE="$TARGET_DIR"
+AGENT_ROOT=""
+while [ "$CANDIDATE" != "/" ]; do
+  if [ -f "$CANDIDATE/package.json" ] && [ -d "$CANDIDATE/config" ]; then
+    AGENT_ROOT="$CANDIDATE"
+    break
+  fi
+  CANDIDATE="$(dirname "$CANDIDATE")"
+done
+AGENT_ROOT="${AGENT_ROOT:-$TARGET_DIR}"
+
+export AGENT_ROOT
+export AGENT_DIR="$AGENT_ROOT"
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$HOME/.nvm/versions/node/v24/bin/node" \
+  "$HOME/.nvm/versions/node/v22/bin/node" \
+  "$HOME/.nvm/versions/node/v20/bin/node" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  /usr/bin/node; do
+  if [ -x "$candidate" ]; then
+    NODE_BIN="$candidate"
+    break
+  fi
+done
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[cadence-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+LOG_DATE="$(date +%Y-%m-%d)"
+LOG_DIR="$AGENT_ROOT/logs/cadence-bus"
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+LOG_FILE="$LOG_DIR/launchd-${LOG_DATE}.log"
+
+# Exec the enqueue script. stdin is closed; stdout/stderr go to the log.
+exec "$NODE_BIN" "$ENQUEUE_SCRIPT" "$@" >> "$LOG_FILE" 2>&1