@adaptic/maestro 1.8.3 → 1.9.0

package/lib/feature-init.mjs

@@ -0,0 +1,297 @@
+/**
+ * Maestro — Feature Init Tracking
+ *
+ * Pairs the framework's `framework-features.json` (versioned registry) with
+ * each agent's `.maestro/features.json` (per-agent installed state) so
+ * `maestro upgrade` and `maestro init` can:
+ *
+ *   1. Detect new framework features the agent has not yet initialised.
+ *   2. Auto-run low-risk init steps (mkdir, scaffold, copy).
+ *   3. Defer init steps that need user input (RAG repo selection, backup
+ *      credentials) onto a `pending` queue.
+ *   4. Surface the pending queue via a SessionStart hook banner so the
+ *      operator (or Claude) sees "run `maestro init` to complete setup"
+ *      every time a Claude Code session opens in the agent's directory.
+ *
+ * Storage:
+ *   ~/maestro/framework-features.json     ← framework SOT
+ *   ~/<agent>/.maestro/features.json      ← agent's installed state
+ *
+ * Agent file shape:
+ *   {
+ *     "framework_version": "1.9.0",
+ *     "schema_version": "1",
+ *     "last_upgrade": "2026-05-12T10:00:00Z",
+ *     "initialized": {
+ *       "<feature-name>": { "version": "1", "initialized_at": "..." }
+ *     },
+ *     "pending": [
+ *       { "feature": "...", "added_at": "...", "version": "1" }
+ *     ]
+ *   }
+ *
+ * The library is dep-free (only node:fs / node:path / node:child_process)
+ * and exits cleanly on missing files — fresh agents that haven't been
+ * upgraded yet simply have no `.maestro/features.json`.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const FEATURE_REGISTRY_RELATIVE = "framework-features.json";
+export const AGENT_STATE_RELATIVE = ".maestro/features.json";
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+export function resolveAgentRoot(agentRoot) {
+  return resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+}
+
+export function getStatePath(agentRoot) {
+  return join(resolveAgentRoot(agentRoot), AGENT_STATE_RELATIVE);
+}
+
+// ---------------------------------------------------------------------------
+// Registry / state loaders
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the framework feature registry. Pass the absolute path to
+ * `framework-features.json` (typically resolved relative to the maestro
+ * CLI entry point). Returns the parsed registry or throws if missing.
+ */
+export function loadRegistry(registryPath) {
+  if (!existsSync(registryPath)) {
+    throw new Error(`framework-features.json not found at ${registryPath}`);
+  }
+  try {
+    return JSON.parse(readFileSync(registryPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`failed to parse framework-features.json: ${err.message}`);
+  }
+}
+
+/**
+ * Load the per-agent install state. Returns a fresh empty state if the
+ * file doesn't exist yet — callers should treat that as "every feature is
+ * pending init for the first time".
+ */
+export function loadAgentState(agentRoot) {
+  const statePath = getStatePath(agentRoot);
+  if (!existsSync(statePath)) {
+    return {
+      framework_version: null,
+      schema_version: "1",
+      last_upgrade: null,
+      initialized: {},
+      pending: [],
+    };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(statePath, "utf-8"));
+    // Defensive defaults so partially-written state still works.
+    raw.initialized = raw.initialized || {};
+    raw.pending = Array.isArray(raw.pending) ? raw.pending : [];
+    raw.schema_version = raw.schema_version || "1";
+    return raw;
+  } catch {
+    return {
+      framework_version: null,
+      schema_version: "1",
+      last_upgrade: null,
+      initialized: {},
+      pending: [],
+    };
+  }
+}
+
+export function saveAgentState(agentRoot, state) {
+  const statePath = getStatePath(agentRoot);
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Diff between registry and agent state
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a list of features that need initialisation. A feature is "needs
+ * init" when the registry's `version` is strictly newer than the agent's
+ * recorded version, OR when the agent has no entry at all.
+ *
+ * Returns: [{ name, version, definition, status: "new" | "upgraded" }]
+ */
+export function diffFeatures(registry, agentState) {
+  const out = [];
+  const installed = agentState.initialized || {};
+  for (const [name, def] of Object.entries(registry.features || {})) {
+    const current = installed[name];
+    if (!current) {
+      out.push({ name, version: def.version, definition: def, status: "new" });
+      continue;
+    }
+    if (String(current.version) !== String(def.version)) {
+      out.push({ name, version: def.version, definition: def, status: "upgraded" });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Init runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile the agent's state with the registry. For each diffed feature:
+ *   - if `init.auto === true` and `runAuto`, execute init.command (spawn
+ *     /bin/bash -lc so wrappers / npx scripts resolve correctly).
+ *   - else, add to pending list.
+ *
+ * Options:
+ *   maestroRoot   absolute path to ~/maestro (used to resolve init scripts)
+ *   agentRoot     absolute path to the agent's repo
+ *   registry      parsed registry (loaded by loadRegistry)
+ *   runAuto       boolean; default true. Set false during dry-run/plan modes.
+ *   logger        optional fn({ stage, feature, status, message })
+ *
+ * Returns: { ranAuto: [...], pending: [...], failed: [...] }
+ */
+export function reconcileFeatures({ maestroRoot, agentRoot, registry, runAuto = true, logger } = {}) {
+  const root = resolveAgentRoot(agentRoot);
+  const state = loadAgentState(root);
+  const diff = diffFeatures(registry, state);
+  const result = { ranAuto: [], pending: [], failed: [] };
+  const log = logger || (() => {});
+  const now = new Date().toISOString();
+
+  for (const item of diff) {
+    const init = item.definition.init || {};
+    const isAuto = init.auto === true;
+
+    if (isAuto && runAuto) {
+      log({ stage: "running", feature: item.name, message: init.description });
+      const ran = runInitCommand({ maestroRoot, agentRoot: root, command: init.command });
+      if (ran.ok) {
+        state.initialized[item.name] = { version: String(item.version), initialized_at: now };
+        result.ranAuto.push(item.name);
+        log({ stage: "completed", feature: item.name });
+      } else {
+        result.failed.push({ name: item.name, error: ran.error });
+        // Push to pending so user can retry manually.
+        pushPending(state, item, now);
+        log({ stage: "failed", feature: item.name, message: ran.error });
+      }
+    } else {
+      pushPending(state, item, now);
+      result.pending.push(item.name);
+      log({ stage: "pending", feature: item.name, message: init.description });
+    }
+  }
+
+  // After reconciliation, prune any pending entries that are now
+  // initialised (e.g. user ran the init manually).
+  state.pending = (state.pending || []).filter((p) => !state.initialized[p.feature]);
+
+  state.framework_version = registry.framework_version || state.framework_version;
+  state.last_upgrade = now;
+  saveAgentState(root, state);
+  return result;
+}
+
+function pushPending(state, item, now) {
+  const existing = (state.pending || []).find((p) => p.feature === item.name);
+  if (existing) {
+    existing.version = String(item.version);
+    existing.added_at = existing.added_at || now;
+    return;
+  }
+  state.pending = state.pending || [];
+  state.pending.push({
+    feature: item.name,
+    version: String(item.version),
+    added_at: now,
+    title: item.definition.title || item.name,
+    description: item.definition.init?.description || "",
+    command: item.definition.init?.command || "",
+  });
+}
+
+/**
+ * Run an init command in the agent repo. Accepts simple shell strings
+ * (executed via /bin/bash -lc) so init scripts can rely on PATH having
+ * homebrew/nvm bins. Always runs with cwd = agentRoot and inherits the
+ * caller's env plus AGENT_ROOT.
+ */
+function runInitCommand({ maestroRoot, agentRoot, command }) {
+  if (!command || command === "true") return { ok: true };
+  // If the command names a path that exists relative to maestroRoot,
+  // resolve to its absolute path so the init script doesn't depend on
+  // the agent having a copy of the script already.
+  const parts = command.split(/\s+/);
+  // Support: `node scripts/setup/init-xxx.mjs`
+  if (parts[0] === "node" && parts[1]) {
+    const candidateAgent = join(agentRoot, parts[1]);
+    const candidateFramework = maestroRoot ? join(maestroRoot, parts[1]) : null;
+    let scriptPath = null;
+    if (existsSync(candidateAgent)) scriptPath = candidateAgent;
+    else if (candidateFramework && existsSync(candidateFramework)) scriptPath = candidateFramework;
+    if (scriptPath) {
+      const args = [scriptPath, ...parts.slice(2)];
+      const r = spawnSync(process.execPath, args, {
+        cwd: agentRoot,
+        env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot, MAESTRO_ROOT: maestroRoot || "" },
+        encoding: "utf-8",
+      });
+      if (r.status === 0) return { ok: true, stdout: r.stdout };
+      return { ok: false, error: (r.stderr || `exit ${r.status}`).trim() };
+    }
+    return { ok: false, error: `init script not found: ${parts[1]}` };
+  }
+  // Generic shell fallback.
+  const r = spawnSync("/bin/bash", ["-lc", command], {
+    cwd: agentRoot,
+    env: { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot, MAESTRO_ROOT: maestroRoot || "" },
+    encoding: "utf-8",
+  });
+  if (r.status === 0) return { ok: true, stdout: r.stdout };
+  return { ok: false, error: (r.stderr || `exit ${r.status}`).trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Pending queue accessors (used by banner + `maestro init`)
+// ---------------------------------------------------------------------------
+
+export function listPending(agentRoot) {
+  const state = loadAgentState(agentRoot);
+  return state.pending || [];
+}
+
+export function markInitialised(agentRoot, featureName, version) {
+  const state = loadAgentState(agentRoot);
+  state.initialized = state.initialized || {};
+  state.initialized[featureName] = {
+    version: String(version),
+    initialized_at: new Date().toISOString(),
+  };
+  state.pending = (state.pending || []).filter((p) => p.feature !== featureName);
+  saveAgentState(agentRoot, state);
+}
+
+export function bannerSnapshot(agentRoot) {
+  const state = loadAgentState(agentRoot);
+  return {
+    pending_count: (state.pending || []).length,
+    pending: state.pending || [],
+    last_upgrade: state.last_upgrade,
+    framework_version: state.framework_version,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {
@@ -12,7 +12,9 @@
     "./executor": "./lib/action-executor.js",
     "./singleton": "./lib/singleton.js",
     "./cadence-bus": "./lib/cadence-bus.mjs",
+    "./feature-init": "./lib/feature-init.mjs",
     "./tts": "./lib/tts.mjs",
+    "./framework-features.json": "./framework-features.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -35,7 +37,8 @@
     ".claude/settings.json",
     ".env.example",
     ".gitignore",
-    "README.md"
+    "README.md",
+    "framework-features.json"
   ],
   "publishConfig": {
     "access": "public",

package/scaffold/config/known-agents.json

@@ -1,35 +1,84 @@
 {
-  "_comment": "Registry of all AI agents in the organisation. Used by the daemon classifier to prevent cross-agent message interception — when a message @-mentions a specific agent, only that agent's daemon should respond. Each agent repo should have its own copy of this file. Update when agents are added or removed.",
+  "$schema": "https://adaptic.ai/schemas/maestro/known-agents.v1.json",
+  "schema_version": "1",
+  "_comment": "Registry of all AI agents in the organisation. Read by scripts/daemon/classifier.mjs to prevent cross-agent message interception — when a message @-mentions a specific agent's name or Slack ID, only that agent's daemon should respond. Each agent repo holds its own copy of this file. Edit when peer agents are added/removed. The framework's scaffolded version reflects the current Adaptic roster; agents may extend with peer agents specific to their own scope.",
   "agents": [
     {
       "name": "Sophie",
+      "fullName": "Sophie Nguyen",
       "slackId": "U099N1JFPRQ",
       "role": "Chief of Staff",
       "repo": "sophie-ai"
     },
     {
       "name": "Ravi",
+      "fullName": "Ravi Patel",
       "slackId": "U099N1JE0LA",
-      "role": "CTO",
+      "role": "VP, AI Models & Learning Systems",
       "repo": "ravi-ai"
     },
+    {
+      "name": "Jacob",
+      "fullName": "Jacob Stein",
+      "slackId": "U099N19NXT4",
+      "role": "Chief AI Scientist",
+      "repo": "jacob-ai"
+    },
     {
       "name": "Lucas",
+      "fullName": "Lucas Carter",
       "slackId": "U099N17LVCJ",
       "role": "Head of Legal Ops",
       "repo": "lucas-ai"
     },
-    {
-      "name": "Jacob",
-      "slackId": "U099N19NXT4",
-      "role": "Head of Engineering",
-      "repo": "jacob-ai"
-    },
     {
       "name": "Hessa",
+      "fullName": "Hessa Mohammed",
       "slackId": "U0ALUES7ERY",
       "role": "Head of AI Research",
       "repo": "hessa-surface"
+    },
+    {
+      "name": "Isla",
+      "fullName": "Isla Brennan",
+      "slackId": "",
+      "role": "Head of Engineering",
+      "repo": "isla-ai"
+    },
+    {
+      "name": "Nadia",
+      "fullName": "Nadia Al-Saadi",
+      "slackId": "",
+      "role": "Head of Compliance",
+      "repo": "nadia-ai"
+    },
+    {
+      "name": "Luca",
+      "fullName": "Luca Romano",
+      "slackId": "",
+      "role": "Head of Product",
+      "repo": "luca-ai"
+    },
+    {
+      "name": "Amara",
+      "fullName": "Amara Okonkwo",
+      "slackId": "",
+      "role": "Head of Investor Relations",
+      "repo": "amara-ai"
+    },
+    {
+      "name": "Kai",
+      "fullName": "Kai Tanaka",
+      "slackId": "",
+      "role": "Head of Fund Operations",
+      "repo": "kai-ai"
+    },
+    {
+      "name": "Rowan",
+      "fullName": "Rowan Mitchell",
+      "slackId": "",
+      "role": "Head of Quant Engineering",
+      "repo": "rowan-ai"
     }
   ]
 }

package/scripts/cost/track-claude-usage.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * scripts/cost/track-claude-usage.mjs — Lightweight cost ledger for
+ * Claude Code sessions spawned by the cadence consumer and dispatcher.
+ *
+ * Two modes:
+ *
+ *  1. `record` — Append a per-session row to state/cost-tracking/<date>.jsonl.
+ *     Called by the cadence consumer after every spawn.
+ *
+ *       node scripts/cost/track-claude-usage.mjs record \
+ *         --cadence inbox-processor --model sonnet --duration-ms 12345 \
+ *         --input-tokens 1500 --output-tokens 320 --exit 0
+ *
+ *  2. `summarise` — Rollup the last N days into state/dashboards/cost-summary.yaml.
+ *     Called daily (cadence: nightly-cost-rollup) and on demand.
+ *
+ *       node scripts/cost/track-claude-usage.mjs summarise --days 7
+ *
+ * Token-cost estimation uses a static price table (./pricing.json if present,
+ * otherwise sensible defaults). Numbers are estimates — the source of truth
+ * for billing is the Anthropic console. Goal here is local observability,
+ * not exact accounting.
+ */
+
+import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const LEDGER_DIR = join(AGENT_DIR, "state/cost-tracking");
+
+// Default pricing (USD per 1K tokens). Update when Anthropic changes prices.
+const DEFAULT_PRICES = {
+  opus:   { input: 0.015,  output: 0.075 },
+  sonnet: { input: 0.003,  output: 0.015 },
+  haiku:  { input: 0.0008, output: 0.004 },
+};
+const PRICING_FILE = join(__dirname, "pricing.json");
+function loadPrices() {
+  if (!existsSync(PRICING_FILE)) return DEFAULT_PRICES;
+  try { return { ...DEFAULT_PRICES, ...JSON.parse(readFileSync(PRICING_FILE, "utf-8")) }; }
+  catch { return DEFAULT_PRICES; }
+}
+
+function todayUtc() { return new Date().toISOString().slice(0, 10); }
+
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (argv[i + 1] && !argv[i + 1].startsWith("--")) flags[key] = argv[++i];
+      else flags[key] = "true";
+    }
+  }
+  return flags;
+}
+
+function recordCmd(flags) {
+  mkdirSync(LEDGER_DIR, { recursive: true });
+  const row = {
+    ts: new Date().toISOString(),
+    cadence: flags.cadence || "unknown",
+    source: flags.source || "cadence-consumer",
+    model: (flags.model || "sonnet").toLowerCase(),
+    duration_ms: Number(flags["duration-ms"] || 0),
+    input_tokens: Number(flags["input-tokens"] || 0),
+    output_tokens: Number(flags["output-tokens"] || 0),
+    exit_code: Number(flags.exit ?? 0),
+  };
+  const prices = loadPrices()[row.model] || DEFAULT_PRICES.sonnet;
+  row.estimated_usd = +((row.input_tokens / 1000) * prices.input + (row.output_tokens / 1000) * prices.output).toFixed(6);
+  const file = join(LEDGER_DIR, `${todayUtc()}.jsonl`);
+  appendFileSync(file, JSON.stringify(row) + "\n");
+  process.stdout.write(JSON.stringify({ ok: true, file, estimated_usd: row.estimated_usd }) + "\n");
+}
+
+function summariseCmd(flags) {
+  const days = Math.max(1, Number(flags.days || 7));
+  if (!existsSync(LEDGER_DIR)) {
+    writeSummary({ window_days: days, totals: empty(), by_model: {}, by_cadence: {} });
+    return;
+  }
+  const cutoff = Date.now() - days * 86_400_000;
+  const totals = empty();
+  const byModel = {};
+  const byCadence = {};
+  for (const name of readdirSync(LEDGER_DIR)) {
+    if (!name.endsWith(".jsonl")) continue;
+    let body;
+    try { body = readFileSync(join(LEDGER_DIR, name), "utf-8"); } catch { continue; }
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      let row;
+      try { row = JSON.parse(line); } catch { continue; }
+      if (new Date(row.ts).getTime() < cutoff) continue;
+      totals.sessions += 1;
+      totals.input_tokens += row.input_tokens || 0;
+      totals.output_tokens += row.output_tokens || 0;
+      totals.estimated_usd = +(totals.estimated_usd + (row.estimated_usd || 0)).toFixed(6);
+      byModel[row.model] = byModel[row.model] || empty();
+      byModel[row.model].sessions += 1;
+      byModel[row.model].input_tokens += row.input_tokens || 0;
+      byModel[row.model].output_tokens += row.output_tokens || 0;
+      byModel[row.model].estimated_usd = +(byModel[row.model].estimated_usd + (row.estimated_usd || 0)).toFixed(6);
+      byCadence[row.cadence] = byCadence[row.cadence] || empty();
+      byCadence[row.cadence].sessions += 1;
+      byCadence[row.cadence].input_tokens += row.input_tokens || 0;
+      byCadence[row.cadence].output_tokens += row.output_tokens || 0;
+      byCadence[row.cadence].estimated_usd = +(byCadence[row.cadence].estimated_usd + (row.estimated_usd || 0)).toFixed(6);
+    }
+  }
+  writeSummary({ window_days: days, totals, by_model: byModel, by_cadence: byCadence });
+}
+
+function empty() { return { sessions: 0, input_tokens: 0, output_tokens: 0, estimated_usd: 0 }; }
+
+function writeSummary(payload) {
+  const out = {
+    generated: new Date().toISOString(),
+    ...payload,
+  };
+  mkdirSync(join(AGENT_DIR, "state/dashboards"), { recursive: true });
+  const yaml = toYaml(out);
+  writeFileSync(join(AGENT_DIR, "state/dashboards/cost-summary.yaml"), yaml);
+  process.stdout.write(JSON.stringify({ ok: true, ...out }, null, 2) + "\n");
+}
+
+// Tiny YAML writer (good enough for cost-summary shape).
+function toYaml(obj, indent = 0) {
+  const pad = "  ".repeat(indent);
+  if (obj === null) return "null";
+  if (typeof obj === "string") return `"${obj.replace(/"/g, '\\"')}"`;
+  if (typeof obj !== "object") return String(obj);
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return "[]";
+    return "\n" + obj.map((v) => `${pad}- ${toYaml(v, indent + 1).trimStart()}`).join("\n");
+  }
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return "{}";
+  return "\n" + keys.map((k) => `${pad}${k}:${typeof obj[k] === "object" && obj[k] !== null ? toYaml(obj[k], indent + 1) : " " + toYaml(obj[k], indent + 1)}`).join("\n");
+}
+
+const cmd = process.argv[2];
+const flags = parseFlags(process.argv.slice(3));
+if (cmd === "record") recordCmd(flags);
+else if (cmd === "summarise" || cmd === "summarize") summariseCmd(flags);
+else {
+  process.stderr.write(`usage: ${process.argv[1]} <record|summarise> [flags]\n`);
+  process.exit(2);
+}

package/scripts/daemon/cadence-consumer.mjs

@@ -46,6 +46,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
 
 import {
   ensureBusDirs,
@@ -92,6 +93,40 @@ function defaultLogger(entry) {
   }
 }
 
+/**
+ * Resolve an absolute path to the Claude CLI. launchd's bare environment
+ * does NOT include /Users/<u>/.local/bin or homebrew on PATH, so a plain
+ * `spawn('claude', …)` fails with ENOENT — which is exactly what was
+ * stuck in ravi-ai's DLQ. This resolver returns the first existing
+ * candidate among:
+ *
+ *   1. $CLAUDE_BIN env var (if set + executable)
+ *   2. ~/.local/bin/claude              (default Claude Code install path)
+ *   3. /opt/homebrew/bin/claude          (homebrew on Apple Silicon)
+ *   4. /usr/local/bin/claude             (homebrew on Intel)
+ *   5. /usr/bin/claude
+ *
+ * Falls back to bare "claude" so the spawn's own error stays informative
+ * when nothing is found.
+ */
+let _resolvedClaude = null;
+function resolveClaudeBin() {
+  if (_resolvedClaude) return _resolvedClaude;
+  const envOverride = process.env.CLAUDE_BIN;
+  const candidates = [
+    envOverride,
+    join(homedir(), ".local/bin/claude"),
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+    "/usr/bin/claude",
+  ].filter(Boolean);
+  for (const c of candidates) {
+    if (existsSync(c)) { _resolvedClaude = c; return c; }
+  }
+  _resolvedClaude = "claude"; // last-resort; spawn will report ENOENT
+  return _resolvedClaude;
+}
+
 /**
  * Spawn a sub-session running the cadence's trigger prompt and resolve
  * with { exit_code, durationMs }. Reads the prompt at call time so the
@@ -111,9 +146,27 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       return;
     }
 
-    const bin = process.env.CLAUDE_BIN || "claude";
+    const bin = resolveClaudeBin();
     const args = ["--print", "--dangerously-skip-permissions", body];
-    const env = { ...process.env, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot };
+    // Augment PATH so any tool the subsession invokes (jq, node, etc.)
+    // can still be found. launchd's bare env strips /opt/homebrew/bin etc.
+    const augmentedPath = [
+      process.env.PATH || "",
+      `${homedir()}/.local/bin`,
+      "/opt/homebrew/bin",
+      "/opt/homebrew/sbin",
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+      "/usr/sbin",
+      "/sbin",
+    ].filter(Boolean).join(":");
+    const env = {
+      ...process.env,
+      AGENT_ROOT: agentRoot,
+      AGENT_DIR: agentRoot,
+      PATH: augmentedPath,
+    };
     const started = Date.now();
 
     log({ level: "info", stage: "subsession_spawn", cadence, bin });
@@ -137,6 +190,24 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       clearTimeout(timer);
       const durationMs = Date.now() - started;
       const exit_code = typeof code === "number" ? code : (signal ? -1 : -5);
+      // Record cost-ledger row. Token counts are 0 until we parse the
+      // session's JSON output; for now exit-code + duration are enough
+      // to spot pathological retry loops.
+      try {
+        const trackerPath = join(agentRoot, "scripts/cost/track-claude-usage.mjs");
+        if (existsSync(trackerPath)) {
+          spawn(process.execPath, [
+            trackerPath, "record",
+            "--cadence", cadence,
+            "--source", "cadence-consumer",
+            "--model", "sonnet",
+            "--duration-ms", String(durationMs),
+            "--input-tokens", "0",
+            "--output-tokens", "0",
+            "--exit", String(exit_code),
+          ], { stdio: "ignore", env: { ...env, AGENT_ROOT: agentRoot } }).unref();
+        }
+      } catch { /* cost tracking is best-effort */ }
       resolveOut({
         ok: exit_code === 0,
         exit_code,