@adaptic/maestro 1.9.1 → 1.9.3

package/.env.example

@@ -16,11 +16,29 @@
 # The agent's reasoning engines. At minimum you need Anthropic (Claude).
 #
 
-# REQUIRED — Primary reasoning engine (Claude Code uses this)
-# Get your key: https://console.anthropic.com/settings/keys
-# Subscription: Anthropic API plan (pay-per-token) or Max subscription
+# REQUIRED — Primary reasoning engine. Two ways to authenticate:
+#
+#   Option A — API key (pay-per-token)
+#     Set ANTHROPIC_API_KEY below to a valid sk-ant-api03-... key.
+#     Get one: https://console.anthropic.com/settings/keys
+#
+#   Option B — Claude Code subscription (Pro/Max, OAuth via Keychain)
+#     LEAVE ANTHROPIC_API_KEY EMPTY *and* set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1.
+#     This tells the cadence consumer to strip ANTHROPIC_API_KEY from every
+#     sub-session spawn so claude --print falls back to the keychain OAuth
+#     token. Most agents on a Mac mini with a Claude Code subscription
+#     should use this option — routine cadence ticks cost zero API credits.
+#
+# Doctor validates the key against api.anthropic.com on every run; an
+# invalid key here will cascade 401s through every sub-session spawn.
 ANTHROPIC_API_KEY=
 
+# OPTIONAL — When set to 1, the cadence consumer strips ANTHROPIC_API_KEY
+# from every claude --print sub-session env so claude falls back to
+# Claude Code subscription auth (Keychain OAuth). Use this when the
+# agent's Mac has a Claude Code Pro/Max subscription.
+MAESTRO_PREFER_SUBSCRIPTION_AUTH=
+
 # OPTIONAL — Supplemental model access (GPT-4, embeddings)
 # Get your key: https://platform.openai.com/api-keys
 # Subscription: OpenAI API plan (pay-per-token)

package/bin/maestro.mjs

@@ -1462,6 +1462,43 @@ function doctor() {
     check("ANTHROPIC_API_KEY", true);
     check("SLACK_USER_TOKEN", false);
     check("GMAIL_APP_PASSWORD", false);
+
+    // Auth validity: if ANTHROPIC_API_KEY is set, ping the API to
+    // verify it works. An invalid key in .env will silently be sent
+    // to every `claude --print` sub-session and cause cascading 401s
+    // (exactly the ravi-ai inbox-processor runaway). Better to catch
+    // it here. Skips the check if the user opted out via
+    // MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 (subscription wins).
+    const keyMatch = env.match(/^ANTHROPIC_API_KEY=(.+)$/m);
+    const preferSubsMatch = env.match(/^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(.+)$/m);
+    const preferSubs = preferSubsMatch && /^1|true|yes$/i.test(preferSubsMatch[1].trim());
+    if (keyMatch && !preferSubs) {
+      const key = keyMatch[1].trim().replace(/^"|"$/g, "");
+      try {
+        const result = spawnSync("curl", [
+          "-s", "-o", "/dev/null", "-w", "%{http_code}",
+          "-X", "POST",
+          "-H", `x-api-key: ${key}`,
+          "-H", "anthropic-version: 2023-06-01",
+          "-H", "content-type: application/json",
+          "--max-time", "8",
+          "https://api.anthropic.com/v1/messages",
+          "-d", JSON.stringify({ model: "claude-haiku-4-5", max_tokens: 5, messages: [{ role: "user", content: "ping" }] }),
+        ], { encoding: "utf-8" });
+        const code = (result.stdout || "").trim();
+        if (code === "200") ok("ANTHROPIC_API_KEY validated against api.anthropic.com");
+        else if (code === "401") {
+          warn(`ANTHROPIC_API_KEY is INVALID (HTTP 401 from api.anthropic.com).`);
+          warn(`  This will cause every sub-session spawn to fail. Either:`);
+          warn(`    1. Replace the key in .env with a valid one, OR`);
+          warn(`    2. Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to use Claude Code subscription auth.`);
+          issues++;
+        } else if (code) warn(`ANTHROPIC_API_KEY check returned HTTP ${code} (expected 200)`);
+        else warn(`ANTHROPIC_API_KEY check skipped (no network / curl missing)`);
+      } catch { warn("ANTHROPIC_API_KEY check failed (curl error)"); }
+    } else if (preferSubs) {
+      ok("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 — using Claude Code subscription (Keychain OAuth)");
+    }
   } else {
     fail(".env file not found — copy from .env.example");
     issues++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {

package/scripts/daemon/cadence-consumer.mjs

@@ -183,6 +183,20 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       AGENT_DIR: agentRoot,
       PATH: augmentedPath,
     };
+    // Auth handling. Claude Code authenticates via macOS Keychain
+    // (OAuth from the user's Pro/Max subscription) when no API key is
+    // set, OR via the ANTHROPIC_API_KEY env var when one is present.
+    // If the env key is present BUT looks like a placeholder / empty
+    // string, we strip it so claude can fall back to Keychain OAuth.
+    // Set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 in .env to always strip
+    // the API key (force subscription auth) — useful when the agent
+    // owns a Claude Code Pro/Max subscription and shouldn't burn API
+    // credits for routine ticks.
+    const preferSubscription = process.env.MAESTRO_PREFER_SUBSCRIPTION_AUTH === "1";
+    const apiKey = env.ANTHROPIC_API_KEY || "";
+    if (preferSubscription || !apiKey.trim() || /^(your-api-key|placeholder|xxx+|sk-ant-xxx)/i.test(apiKey)) {
+      delete env.ANTHROPIC_API_KEY;
+    }
     const started = Date.now();
 
     // Per-run log file. Pattern is short enough to be tail-friendly.

package/scripts/daemon/maestro-daemon.mjs

@@ -3,18 +3,22 @@
 // Maestro Daemon — Reactive event-driven message processor
 // =============================================================================
 //
-// Generic entry point that loads agent identity from config/agent.ts and
+// Generic entry point that loads agent identity from config/agent.json and
 // delegates to the core daemon logic. This file is agent-name-agnostic.
 //
+// Lifecycle:
+//   1. Honour .emergency-stop BEFORE doing anything (don't acquire singleton
+//      lock, don't start consumer, don't import sophie-daemon). Stops the
+//      launchd restart treadmill cold.
+//   2. Acquire the daemon singleton lock so only one instance runs.
+//   3. Start the cadence consumer (state/cadence-bus/ drain loop).
+//   4. Import the core daemon (sophie-daemon.mjs or legacy <firstName>-daemon.mjs).
+//
 // Run: node scripts/daemon/maestro-daemon.mjs
-// Install: launchd plist with KeepAlive: true
+// Install: launchd plist with KeepAlive.SuccessfulExit: false (clean exits
+// during emergency-stop should NOT trigger restart; non-zero exits should).
 // =============================================================================
 
-// The core daemon implementation is in sophie-daemon.mjs by default, but
-// older agent repos may have a renamed copy at <firstname>-daemon.mjs (a
-// pre-1.7 convention). This entry-point auto-detects the correct file so
-// the launchd plist stays stable regardless of agent identity history.
-
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
@@ -22,25 +26,44 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AGENT_DIR = process.env.AGENT_DIR || resolve(__dirname, "../..");
 
-// Set AGENT_DIR as env var so all modules can use it
 process.env.AGENT_DIR = AGENT_DIR;
 process.env.AGENT_ROOT = AGENT_DIR;
 
-// Singleton guard — prevent duplicate daemon instances
+// ---------------------------------------------------------------------------
+// 1. Emergency-stop gate
+// ---------------------------------------------------------------------------
+// If the operator dropped .emergency-stop, we exit cleanly (code 0). With
+// KeepAlive.SuccessfulExit:false this means launchd will NOT restart us
+// until the flag is lifted + the plist is reloaded by resume-operations.sh.
+// Older plists with plain KeepAlive:true will still restart, so we hold
+// the process for 30s before exiting to give launchd's ThrottleInterval
+// something to throttle.
+if (existsSync(join(AGENT_DIR, ".emergency-stop"))) {
+  console.error("[DAEMON] .emergency-stop flag present — refusing to start.");
+  console.error("[DAEMON] Lift with: scripts/resume-operations.sh");
+  await new Promise((r) => setTimeout(r, 30_000));
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// 2. Singleton guard
+// ---------------------------------------------------------------------------
 try {
   const { acquireLock } = await import(resolve(process.env.HOME, "maestro/lib/singleton.js"));
   if (!acquireLock("daemon")) {
     console.log("[DAEMON] Already running — exiting");
     process.exit(0);
   }
-} catch { /* maestro singleton not available */ }
+} catch { /* maestro singleton not available — proceed without lock */ }
 
-// Start the cadence consumer alongside the reactive event loop. This is the
-// single persistent owner of cadence housekeeping — launchd plists enqueue
-// cadence ticks onto state/cadence-bus/ and the consumer drains them here,
-// either handling them inline or escalating to a sub-session when warranted.
-// Failure to start the consumer must NOT take the reactive daemon down, so
-// we isolate startup errors.
+// ---------------------------------------------------------------------------
+// 3. Cadence consumer (cadence bus drain loop)
+// ---------------------------------------------------------------------------
+// Start alongside the reactive event loop. This is the single persistent
+// owner of cadence housekeeping — launchd plists enqueue cadence ticks
+// onto state/cadence-bus/ and the consumer drains them here, either
+// handling them inline or escalating to a sub-session when warranted.
+// Failure to start the consumer must NOT take the reactive daemon down.
 try {
   const { startConsumer } = await import("./cadence-consumer.mjs");
   const consumer = startConsumer({ agentRoot: AGENT_DIR });
@@ -55,7 +78,10 @@ try {
   // Reactive daemon continues. Doctor / healthcheck will surface this.
 }
 
-// Locate the core daemon module. Try, in order:
+// ---------------------------------------------------------------------------
+// 4. Core daemon import
+// ---------------------------------------------------------------------------
+// Resolve the core daemon module. Try, in order:
 //   1. ./sophie-daemon.mjs  — canonical filename (post-Phase-2.5 SOT)
 //   2. ./<firstName>-daemon.mjs — legacy rename from init-maestro Phase 1
 //   3. The first scripts/daemon/*-daemon.mjs that isn't this file

package/scripts/local-triggers/generate-plists.sh

@@ -129,13 +129,18 @@ PLIST_MID
         cat >> "$FILE" << 'PLIST_KEEPALIVE'
 
     <key>KeepAlive</key>
-    <true/>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
 
     <key>RunAtLoad</key>
     <true/>
 
     <key>ThrottleInterval</key>
-    <integer>5</integer>
+    <integer>30</integer>
 PLIST_KEEPALIVE
     fi
 

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

@@ -167,7 +167,12 @@ test("daemon plist remains a KeepAlive job (not a cadence enqueue)", async () =>
     runGenerator(root);
     const path = join(root, "scripts/local-triggers/plists/ai.adaptic.erin-daemon.plist");
     const body = readFileSync(path, "utf-8");
-    assert.match(body, /<key>KeepAlive<\/key>\s*<true\/>/);
+    // 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");