@adaptic/maestro 1.1.8 → 1.5.0

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

@@ -111,13 +111,48 @@ PLIST_SCHED
 PLIST_INTERVAL
     fi
 
+    # ── EnvironmentVariables block ──────────────────────────────────────────
+    # Exports for every spawned process:
+    #   PATH                  — homebrew + standard paths so node/python/etc are findable
+    #   CLAUDE_CODE_TMPDIR    — redirect Claude Code per-cwd temp to external SSD if mounted
+    #   AGENT_ROOT            — used by maestro's singleton lock and other helpers
+    cat >> "$FILE" << PLIST_ENV
+
+    <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>$AGENT_USER</string>
+        <key>AGENT_ROOT</key>
+        <string>$AGENT_DIR</string>
+PLIST_ENV
+
+    if [ -d "/Volumes/4TB-SSD" ]; then
+        cat >> "$FILE" << PLIST_SSD
+        <key>CLAUDE_CODE_TMPDIR</key>
+        <string>/Volumes/4TB-SSD/maestro/${AGENT_FIRST}/claude-tmp</string>
+PLIST_SSD
+    fi
+
+    cat >> "$FILE" << 'PLIST_ENV_END'
+    </dict>
+PLIST_ENV_END
+
+    # Resolve symlinked log path to a real path so launchd can write to it.
+    # If logs/ is a symlink (e.g. when redirected to an external SSD), launchd's
+    # StandardErrorPath/StandardOutPath sometimes fail with EX_CONFIG (78).
+    LOG_REAL=$(cd -P "$AGENT_DIR/logs/daemon" 2>/dev/null && pwd -P || echo "$AGENT_DIR/logs/daemon")
+
     cat >> "$FILE" << PLIST_FOOTER
 
     <key>StandardOutPath</key>
-    <string>$AGENT_DIR/logs/daemon/launchd-stdout.log</string>
+    <string>$LOG_REAL/launchd-stdout.log</string>
 
     <key>StandardErrorPath</key>
-    <string>$AGENT_DIR/logs/daemon/launchd-stderr.log</string>
+    <string>$LOG_REAL/launchd-stderr.log</string>
 </dict>
 </plist>
 PLIST_FOOTER
@@ -126,6 +161,15 @@ PLIST_FOOTER
 }
 
 # ── Helper: trigger plist (runs claude with a trigger prompt) ────────────────
+#
+# Routes through scripts/daemon/launchd-wrapper-generic.sh so the trigger's
+# stdout/stderr lands on the SSD (when /Volumes/{name}-SSD is mounted) and
+# CLAUDE_CODE_TMPDIR is set for any Claude Code session it spawns.
+#
+# IMPORTANT: run-trigger.sh expects the trigger NAME (e.g. "meeting-prep"),
+# not the full path to the .md file. The script constructs the full path
+# itself. Passing the full path causes a doubled path bug:
+# /agent/schedules/triggers//agent/schedules/triggers/meeting-prep.md.md
 
 generate_trigger_plist() {
     local TRIGGER_NAME="$1"
@@ -133,11 +177,11 @@ generate_trigger_plist() {
     local INTERVAL="$3"
 
     local LABEL="ai.adaptic.${AGENT_FIRST}-${TRIGGER_NAME}"
-    local TRIGGER_FILE="$AGENT_DIR/schedules/triggers/${TRIGGER_NAME}.md"
     local RUN_TRIGGER="$AGENT_DIR/scripts/local-triggers/run-trigger.sh"
+    local WRAPPER="$AGENT_DIR/scripts/daemon/launchd-wrapper-generic.sh"
 
     generate_plist "$LABEL" \
-        "$RUN_TRIGGER|$TRIGGER_FILE" \
+        "$WRAPPER|$RUN_TRIGGER|$TRIGGER_NAME" \
         "$SCHEDULE" \
         "$INTERVAL" \
         ""
@@ -148,15 +192,23 @@ generate_trigger_plist() {
 echo ""
 echo "Generating launchd plist files..."
 
-# 1. Main daemon (KeepAlive)
+# 1. Main daemon (KeepAlive) — uses wrapper to bootstrap env (HOME, PATH, etc).
+#    Wrapper is at scripts/daemon/launchd-wrapper.sh. This avoids passing
+#    EnvironmentVariables in the plist, which has been observed to cause
+#    EX_CONFIG (78) failures on macOS when the agent's logs/state dirs are
+#    symlinked to an external SSD.
 generate_plist "ai.adaptic.${AGENT_FIRST}-daemon" \
-    "${NODE_PATH}|${AGENT_DIR}/scripts/daemon/maestro-daemon.mjs" \
+    "${AGENT_DIR}/scripts/daemon/launchd-wrapper.sh" \
     "" "" "true"
 
-# 2. Slack events server (KeepAlive) — real-time Slack message handling
-generate_plist "ai.adaptic.${AGENT_FIRST}-slack-events" \
-    "${NODE_PATH}|${AGENT_DIR}/scripts/slack-events-server.mjs" \
-    "" "" "true"
+# 2. Slack events relay polling job (every 5 sec).
+#    The local Mac mini polls the Railway-hosted webhook relay for buffered
+#    Slack events. This replaces the older local slack-events-server.mjs which
+#    needed an inbound tunnel from the Mac. See docs/guides/webhook-relay-setup.md.
+#    Routed through the generic wrapper so its output goes to the SSD.
+generate_plist "ai.adaptic.${AGENT_FIRST}-poll-relay" \
+    "${AGENT_DIR}/scripts/daemon/launchd-wrapper-generic.sh|${AGENT_DIR}/scripts/poll-slack-events.sh" \
+    "" "5" ""
 
 # 3. Inbox processor (every 5 minutes)
 generate_trigger_plist "inbox-processor" "" "300"

package/scripts/poller/imap-client.mjs

@@ -157,6 +157,7 @@ export async function pollImapInbox({
   const now = new Date().toISOString();
   let newCount = 0;
   let skipped = 0;
+  let unseenCount = 0;
   let lastMid = cursor.last_message_id;
   let totalProcessed = cursor.messages_processed;
 
@@ -185,7 +186,8 @@ export async function pollImapInbox({
         return { newCount: 0, errors };
       }
 
-      console.log(`${logPrefix} Found ${unseen.length} unseen messages`);
+      unseenCount = unseen.length;
+      console.log(`${logPrefix} Found ${unseenCount} unseen messages`);
 
       // Rate limit: process most recent N
       const toFetch = unseen.length > MAX_EMAILS_PER_CYCLE
@@ -273,7 +275,7 @@ export async function pollImapInbox({
     await client.logout();
 
     console.log(
-      `${logPrefix} Poll complete: ${newCount} new, ${skipped} skipped, ${unseen.length} unseen total`,
+      `${logPrefix} Poll complete: ${newCount} new, ${skipped} skipped, ${unseenCount} unseen total`,
     );
   } catch (err) {
     errors.push(`${logPrefix} IMAP error: ${err.message}`);

package/scripts/poller/slack-poller.mjs

@@ -82,25 +82,42 @@ async function getMonitoredChannels() {
 const CEO_USER_ID = "U097N5R0M7U";
 const SOPHIE_USER_ID = "U099N1JFPRQ";
 
-// Rate-limit-aware delay: space requests ~1500ms apart to stay under Slack Tier 3 limits
-// (~50 req/min for conversations.history). With ~25 calls per cycle (half channels
-// rotated), 1500ms spacing = ~38s total, well within the 60s poll interval.
-// Previous: 800ms caused persistent rate limiting with 11 channels + threads.
-const INTER_REQUEST_DELAY_MS = 1500;
+// Rate-limit-aware delay with random jitter to reduce Slack API rate limiting.
+// Base delay 400ms + random 0-600ms jitter = 400-1000ms between requests.
+// With broader-fetch elimination and DM/thread rotation, total calls per cycle
+// are ~20-30 (down from 90+), so this timing keeps us well under both the
+// Slack Tier 3 limit (~50 req/min) and the 50s cycle budget.
+// Previous: fixed 1500ms with redundant broader fetches caused 25-30 min cycles.
+const INTER_REQUEST_BASE_MS = 400;
+const INTER_REQUEST_JITTER_MS = 600;
 const MAX_RETRIES = 3;
 
+// Cycle time budget — abort non-critical work if approaching this limit.
+// Launchd fires every 60s; we must finish well before the next invocation.
+const CYCLE_TIME_BUDGET_MS = 55_000;
+let cycleStartTime = 0;
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 let lastRequestTime = 0;
 
+/**
+ * Check whether the cycle time budget has been exceeded.
+ * Returns true if we should skip non-critical work to finish on time.
+ */
+function isCycleBudgetExceeded() {
+  return cycleStartTime > 0 && (Date.now() - cycleStartTime) > CYCLE_TIME_BUDGET_MS;
+}
+
 async function slackApi(method, params = {}) {
-  // Enforce minimum spacing between requests
+  // Enforce minimum spacing between requests with random jitter
   const now = Date.now();
+  const jitteredDelay = INTER_REQUEST_BASE_MS + Math.floor(Math.random() * INTER_REQUEST_JITTER_MS);
   const elapsed = now - lastRequestTime;
-  if (elapsed < INTER_REQUEST_DELAY_MS) {
-    await sleep(INTER_REQUEST_DELAY_MS - elapsed);
+  if (elapsed < jitteredDelay) {
+    await sleep(jitteredDelay - elapsed);
   }
   lastRequestTime = Date.now();
 
@@ -219,6 +236,8 @@ function getChannelsForCycle(allChannels) {
 }
 
 export async function pollSlack() {
+  cycleStartTime = Date.now();
+
   if (!SLACK_TOKEN) {
     return { items: [], errors: ["SLACK_TOKEN not set"] };
   }
@@ -243,6 +262,12 @@ export async function pollSlack() {
   }
 
   for (const channel of channelsThisCycle) {
+    // Check cycle time budget — skip remaining channels if running long
+    if (isCycleBudgetExceeded()) {
+      errors.push("Cycle time budget exceeded — skipping remaining channels");
+      break;
+    }
+
     try {
       const result = await slackApi("conversations.history", {
         channel: channel.id,
@@ -256,31 +281,14 @@ export async function pollSlack() {
       }
 
       // Track channel threads with replies so the thread scanner picks them up.
-      // IMPORTANT: conversations.history only returns messages newer than `oldest`,
-      // but threads with old parent messages can have NEW replies. We must also
-      // check slightly older messages to discover threads with recent activity.
+      // Thread discovery relies on persisted activeThreads state (which survives
+      // across cycles) plus any threaded messages found in the current history
+      // response. The previous "broader" second fetch (without oldest filter)
+      // has been removed — it doubled API calls per channel and was the primary
+      // cause of rate-limiting. Active threads with old parent messages are
+      // already tracked in activeThreads from prior cycles.
       const channelThreads = new Set(activeThreads[channel.id] || []);
 
-      // Second pass: fetch recent messages WITHOUT oldest filter to find threads
-      // with new replies. Parent messages older than cursor are invisible to the
-      // first pass, but their threads can have new replies we need to scan.
-      // Always run this — it's the only way to discover active threads in channels.
-      try {
-        const broader = await slackApi("conversations.history", {
-          channel: channel.id,
-          limit: 15,
-        });
-        if (broader.ok) {
-          for (const m of broader.messages || []) {
-            if (m.reply_count > 0 && m.ts) {
-              // Track ALL threads with replies — the thread scanner will
-              // filter by cursor timestamp when fetching individual replies
-              channelThreads.add(m.ts);
-            }
-          }
-        }
-      } catch { /* non-critical — thread discovery is best-effort */ }
-
       for (const msg of result.messages || []) {
         // Register any message with replies as an active thread (even Sophie's)
         if (msg.reply_count > 0 && msg.ts) {
@@ -357,14 +365,33 @@ export async function pollSlack() {
     }
   }
 
-  // Also check DMs
+  // Also check DMs — with rotation.
+  // CEO DMs are polled every cycle (critical). Other DMs rotate in halves
+  // to reduce API calls. DM thread discovery uses persisted activeThreads
+  // state instead of a redundant broader fetch (same fix as channels above).
+  // Cache CEO DM channel IDs for thread scanning priority later.
+  const ceoDMChannelIds = new Set();
   try {
     const convos = await slackApi("conversations.list", {
       types: "im",
       limit: 50,
     });
     if (convos.ok) {
-      for (const im of convos.channels || []) {
+      const allDMs = convos.channels || [];
+      // Separate CEO DMs (always poll) from other DMs (rotate in halves)
+      const ceoDMs = allDMs.filter((im) => im.user === CEO_USER_ID);
+      for (const dm of ceoDMs) ceoDMChannelIds.add(dm.id);
+      const otherDMs = allDMs.filter((im) => im.user !== CEO_USER_ID);
+      const rotatedOtherDMs = otherDMs.filter((_, i) => i % 2 === pollCycleCount % 2);
+      const dmsThisCycle = [...ceoDMs, ...rotatedOtherDMs];
+
+      for (const im of dmsThisCycle) {
+        // Check cycle time budget — skip remaining DMs if running long
+        if (isCycleBudgetExceeded()) {
+          errors.push("Cycle time budget exceeded — skipping remaining DMs");
+          break;
+        }
+
         const history = await slackApi("conversations.history", {
           channel: im.id,
           oldest,
@@ -372,26 +399,10 @@ export async function pollSlack() {
         });
         if (!history.ok) continue;
 
-        // Track threads discovered from DM history messages with replies
+        // Track threads discovered from DM history — uses persisted state
+        // from prior cycles instead of a redundant broader API call.
         const channelThreads = new Set(activeThreads[im.id] || []);
 
-        // Broader thread discovery for DMs — same pattern as channels.
-        // Fetch recent messages WITHOUT oldest filter to find DM threads
-        // whose parent message predates the cursor but have new replies.
-        try {
-          const broader = await slackApi("conversations.history", {
-            channel: im.id,
-            limit: 10,
-          });
-          if (broader.ok) {
-            for (const m of broader.messages || []) {
-              if (m.reply_count > 0 && m.ts) {
-                channelThreads.add(m.ts);
-              }
-            }
-          }
-        } catch { /* non-critical — DM thread discovery is best-effort */ }
-
         for (const msg of history.messages || []) {
           // Register any message with replies as an active thread
           if (msg.reply_count > 0 && msg.ts) {
@@ -474,6 +485,11 @@ export async function pollSlack() {
   // This catches thread replies that conversations.history misses.
   // Use a 30-minute lookback window instead of the exact cursor to avoid
   // missing replies that arrived between poll cycles or during processing.
+  //
+  // Thread scanning rotation: threads in high-priority channels (CEO DMs,
+  // critical/high channels) are scanned every cycle. Threads in normal
+  // channels rotate in halves to reduce API calls. If the cycle time
+  // budget is exceeded, remaining thread scans are skipped.
   const THREAD_LOOKBACK_MS = 30 * 60 * 1000;
   const threadOldest = String((Date.now() - THREAD_LOOKBACK_MS) / 1000);
   const threadOldestTs = parseFloat(threadOldest);
@@ -490,9 +506,37 @@ export async function pollSlack() {
     existingInboxFiles = readdirSync(SLACK_INBOX);
   } catch { /* inbox dir may not exist yet */ }
 
-  for (const [channelId, threadTsList] of Object.entries(activeThreads)) {
+  // Determine which channels are high-priority for thread scanning.
+  // ceoDMChannelIds was populated during DM polling above — no extra API call needed.
+  const highPriorityChannelIds = new Set(
+    allChannels
+      .filter((c) => c.priority === "critical" || c.priority === "high")
+      .map((c) => c.id),
+  );
+
+  const threadEntries = Object.entries(activeThreads);
+  // Sort: high-priority channels first, then rotate others
+  const priorityThreadEntries = threadEntries.filter(
+    ([chId]) => highPriorityChannelIds.has(chId) || ceoDMChannelIds.has(chId),
+  );
+  const normalThreadEntries = threadEntries.filter(
+    ([chId]) => !highPriorityChannelIds.has(chId) && !ceoDMChannelIds.has(chId),
+  );
+  // Rotate normal thread entries in halves
+  const rotatedNormalThreadEntries = normalThreadEntries.filter(
+    (_, i) => i % 2 === pollCycleCount % 2,
+  );
+  const threadEntriesToScan = [...priorityThreadEntries, ...rotatedNormalThreadEntries];
+
+  for (const [channelId, threadTsList] of threadEntriesToScan) {
     if (!threadTsList || threadTsList.length === 0) continue;
 
+    // Check cycle time budget before scanning this channel's threads
+    if (isCycleBudgetExceeded()) {
+      errors.push("Cycle time budget exceeded — skipping remaining thread scans");
+      break;
+    }
+
     for (const threadTs of threadTsList) {
       try {
         const repliesResult = await slackApi("conversations.replies", {
@@ -727,5 +771,13 @@ export async function pollSlack() {
   }
 
   writeCursor("slack", new Date().toISOString());
+
+  const cycleDurationMs = Date.now() - cycleStartTime;
+  const cycleDurationSec = (cycleDurationMs / 1000).toFixed(1);
+  console.log(
+    `[slack-poller] Cycle ${pollCycleCount} completed in ${cycleDurationSec}s ` +
+    `(${channelsThisCycle.length} channels, ${items.length} items, ${errors.length} errors)`,
+  );
+
   return { items, errors };
 }

package/scripts/setup/init-agent.sh

@@ -109,6 +109,94 @@ fi
 
 echo ""
 
+# ---------------------------------------------------------------------------
+# Step 1b: Claude-Mem (persistent session memory plugin)
+# ---------------------------------------------------------------------------
+
+log "Setting up Claude-Mem (persistent session memory)..."
+
+if command -v claude &>/dev/null; then
+    # Install via Claude Code plugin system
+    if npx claude-mem install --non-interactive 2>/dev/null; then
+        ok "Claude-Mem installed and configured"
+    else
+        warn "Claude-Mem auto-install failed — install manually: npx claude-mem install"
+    fi
+else
+    warn "Claude CLI required for Claude-Mem — install Claude CLI first, then run: npx claude-mem install"
+fi
+
+echo ""
+
+# ---------------------------------------------------------------------------
+# Step 1c: Claude-Pace (real-time rate limit tracker)
+# ---------------------------------------------------------------------------
+
+log "Setting up Claude-Pace (rate limit tracker)..."
+
+if command -v claude &>/dev/null; then
+    # Install via Claude Code plugin system
+    if claude plugin marketplace add Astro-Han/claude-pace 2>/dev/null && \
+       claude plugin install claude-pace 2>/dev/null; then
+        ok "Claude-Pace installed"
+    else
+        warn "Claude-Pace auto-install failed — install manually:"
+        warn "  claude plugin marketplace add Astro-Han/claude-pace"
+        warn "  claude plugin install claude-pace"
+    fi
+else
+    warn "Claude CLI required for Claude-Pace — install Claude CLI first"
+fi
+
+echo ""
+
+# ---------------------------------------------------------------------------
+# Step 1d: Claudraband (persistent sessions + daemon mode) [optional]
+# ---------------------------------------------------------------------------
+
+log "Checking claudraband availability (persistent session backend)..."
+
+if npx @halfwhey/claudraband --version &>/dev/null 2>&1; then
+    ok "Claudraband available (npx @halfwhey/claudraband)"
+else
+    warn "Claudraband not cached — will be fetched on first use via npx"
+    warn "  Pre-cache: npx @halfwhey/claudraband --version"
+fi
+
+echo ""
+
+# ---------------------------------------------------------------------------
+# Step 1e: ClawTeam swarm orchestrator [optional]
+# ---------------------------------------------------------------------------
+
+if [ "${MAESTRO_ENABLE_SWARM:-0}" = "1" ]; then
+    log "Setting up ClawTeam swarm orchestrator..."
+
+    CLAWTEAM_DIR="$HOME/ClawTeam-OpenClaw"
+    if [ -d "$CLAWTEAM_DIR" ]; then
+        ok "ClawTeam already cloned at $CLAWTEAM_DIR"
+        (cd "$CLAWTEAM_DIR" && git pull --ff-only 2>/dev/null) && ok "ClawTeam updated" || warn "ClawTeam update failed — check manually"
+    else
+        if git clone https://github.com/win4r/ClawTeam-OpenClaw.git "$CLAWTEAM_DIR" 2>/dev/null; then
+            ok "ClawTeam cloned to $CLAWTEAM_DIR"
+        else
+            warn "ClawTeam clone failed — install manually: git clone https://github.com/win4r/ClawTeam-OpenClaw.git ~/ClawTeam-OpenClaw"
+        fi
+    fi
+
+    # Ensure tmux is available (required by ClawTeam)
+    if ! command -v tmux &>/dev/null; then
+        warn "tmux not found — ClawTeam requires tmux. Install via: brew install tmux"
+    else
+        ok "tmux $(tmux -V 2>/dev/null)"
+    fi
+
+    echo ""
+else
+    log "Skipping ClawTeam (set MAESTRO_ENABLE_SWARM=1 to enable)"
+    echo ""
+fi
+
 # ---------------------------------------------------------------------------
 # Step 2: npm install
 # ---------------------------------------------------------------------------
@@ -351,7 +439,9 @@ cat > "$CLAUDE_SETTINGS" << 'SETTINGS_EOF'
     "mcp-server-dev@claude-plugins-official": true,
     "zapier@claude-plugins-official": true,
     "explanatory-output-style@claude-plugins-official": true,
-    "learning-output-style@claude-plugins-official": true
+    "learning-output-style@claude-plugins-official": true,
+    "claude-mem": true,
+    "claude-pace": true
   },
   "effortLevel": "high",
   "skipDangerousModePermissionPrompt": true

package/scripts/setup/install-dev-tools.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# install-dev-tools.sh — Install and configure approved dev tooling for Maestro agents
+#
+# Approved tools (audited 2026-04-18 from #dev-tooling channel):
+#   - claude-pace     — Rate limit status line tracker (Bash plugin)
+#   - agents-observe  — Multi-agent observability dashboard (CC plugin)
+#   - ccxray          — Claude Code token/cost observability proxy
+#   - ClawTeam        — Git worktree swarm orchestrator (CLI)
+#   - code-review-graph — Tree-sitter codebase knowledge graph (MCP)
+#
+# Skipped:
+#   - Superset        — GUI-only, Elastic License v2, not automatable
+#   - claudraband     — Evaluate later; overlaps with maestro session mgmt
+#
+# Usage: ./scripts/setup/install-dev-tools.sh [--all | --tool <name>]
+# Examples:
+#   ./scripts/setup/install-dev-tools.sh --all
+#   ./scripts/setup/install-dev-tools.sh --tool claude-pace
+#   ./scripts/setup/install-dev-tools.sh --tool ccxray
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+info()  { echo "  [INFO]  $1"; }
+ok()    { echo "  [OK]    $1"; }
+skip()  { echo "  [SKIP]  $1"; }
+fail()  { echo "  [FAIL]  $1" >&2; }
+
+# ── Tool installers ─────────────────────────────────────────────────────────
+
+install_claude_pace() {
+  info "Installing claude-pace (rate limit status line tracker)..."
+  if command -v claude >/dev/null 2>&1; then
+    # Install as Claude Code plugin
+    claude plugin install claude-pace 2>/dev/null && ok "claude-pace plugin installed" || {
+      info "Plugin install failed, trying npx setup..."
+      npx claude-pace setup 2>/dev/null && ok "claude-pace configured via npx" || skip "claude-pace: manual setup needed — see https://github.com/Astro-Han/claude-pace"
+    }
+  else
+    skip "claude-pace: Claude Code CLI not found"
+  fi
+}
+
+install_agents_observe() {
+  info "Installing agents-observe (multi-agent observability dashboard)..."
+  if command -v claude >/dev/null 2>&1; then
+    claude plugin install agents-observe 2>/dev/null && ok "agents-observe plugin installed" || {
+      info "Plugin install failed, trying npm global..."
+      npm install -g agents-observe 2>/dev/null && ok "agents-observe installed globally" || skip "agents-observe: manual setup needed — see https://github.com/simple10/agents-observe"
+    }
+  else
+    skip "agents-observe: Claude Code CLI not found"
+  fi
+}
+
+install_ccxray() {
+  info "Installing ccxray (Claude Code token/cost observability)..."
+  # ccxray is zero-install via npx — just verify it's accessible
+  if npx ccxray --version >/dev/null 2>&1; then
+    ok "ccxray available via npx"
+  else
+    info "ccxray will be available via: npx ccxray claude"
+    ok "ccxray: zero-install, run with 'npx ccxray claude' when needed"
+  fi
+
+  # Create a convenience wrapper
+  cat > "$AGENT_DIR/scripts/ccxray-session.sh" << 'WRAPPER'
+#!/bin/bash
+# Launch Claude Code through ccxray observability proxy
+# Usage: ./scripts/ccxray-session.sh [claude args...]
+exec npx ccxray claude "$@"
+WRAPPER
+  chmod +x "$AGENT_DIR/scripts/ccxray-session.sh"
+  ok "Created scripts/ccxray-session.sh convenience wrapper"
+}
+
+install_clawteam() {
+  info "Installing ClawTeam (git worktree swarm orchestrator)..."
+  if command -v pip3 >/dev/null 2>&1; then
+    pip3 install clawteam 2>/dev/null && ok "ClawTeam installed via pip" || {
+      info "pip install failed, trying git clone..."
+      if [ ! -d "$HOME/.clawteam" ]; then
+        git clone https://github.com/win4r/ClawTeam-OpenClaw.git "$HOME/.clawteam" 2>/dev/null && ok "ClawTeam cloned to ~/.clawteam" || skip "ClawTeam: manual setup needed — see https://github.com/win4r/ClawTeam-OpenClaw"
+      else
+        ok "ClawTeam already present at ~/.clawteam"
+      fi
+    }
+  else
+    skip "ClawTeam: pip3 not found"
+  fi
+}
+
+install_code_review_graph() {
+  info "Installing code-review-graph (Tree-sitter codebase knowledge graph)..."
+  if npx code-review-graph --version >/dev/null 2>&1; then
+    ok "code-review-graph available via npx"
+  else
+    npm install -g code-review-graph 2>/dev/null && ok "code-review-graph installed globally" || {
+      info "code-review-graph: available via npx when needed"
+      ok "Run with: npx code-review-graph"
+    }
+  fi
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+echo "=========================================="
+echo "  Maestro Dev Tooling Installer"
+echo "  Agent dir: $AGENT_DIR"
+echo "=========================================="
+echo ""
+
+TOOL="${2:-}"
+case "${1:-}" in
+  --all)
+    install_claude_pace
+    install_agents_observe
+    install_ccxray
+    install_clawteam
+    install_code_review_graph
+    ;;
+  --tool)
+    case "$TOOL" in
+      claude-pace)       install_claude_pace ;;
+      agents-observe)    install_agents_observe ;;
+      ccxray)            install_ccxray ;;
+      clawteam)          install_clawteam ;;
+      code-review-graph) install_code_review_graph ;;
+      *) echo "Unknown tool: $TOOL"; echo "Available: claude-pace, agents-observe, ccxray, clawteam, code-review-graph"; exit 1 ;;
+    esac
+    ;;
+  *)
+    echo "Usage: $0 [--all | --tool <name>]"
+    echo ""
+    echo "Available tools:"
+    echo "  claude-pace        — Rate limit status line tracker"
+    echo "  agents-observe     — Multi-agent observability dashboard"
+    echo "  ccxray             — Token/cost observability proxy"
+    echo "  clawteam           — Git worktree swarm orchestrator"
+    echo "  code-review-graph  — Tree-sitter codebase knowledge graph"
+    exit 0
+    ;;
+esac
+
+echo ""
+echo "Done. See docs/guides/dev-tooling.md for usage details."

package/scripts/spawn-session.sh

@@ -67,16 +67,31 @@ YAML
 echo "[$TIMESTAMP] Spawning session $SESSION_ID (budget: ${TIME_BUDGET}s)" | tee -a "$LOG_FILE"
 
 # Spawn Claude Code session in background with timeout
-(
-    timeout "$TIME_BUDGET" claude -p "$TASK_CONTENT
+# Supports two backends:
+#   MAESTRO_SESSION_BACKEND=claude      (default) — direct claude -p
+#   MAESTRO_SESSION_BACKEND=claudraband — persistent sessions via claudraband daemon
+SESSION_BACKEND="${MAESTRO_SESSION_BACKEND:-claude}"
+
+SESSION_PROMPT="$TASK_CONTENT
 
-IMPORTANT: You are a sub-session spawned by Sophie Nguyen, Chief of Staff at Adaptic.ai.
+IMPORTANT: You are a sub-session spawned for an Adaptic AI agent.
 Write your output to: $SESSION_DIR/output.md
 When complete, write 'DONE' to: $SESSION_DIR/complete
 Working directory: $SOPHIE_AI_DIR
-Do NOT send any communications. Only produce the requested output." \
-    --output-format text \
-    >> "$LOG_FILE" 2>&1
+Do NOT send any communications. Only produce the requested output."
+
+(
+    if [ "$SESSION_BACKEND" = "claudraband" ]; then
+        # Use claudraband for persistent, resumable sessions
+        timeout "$TIME_BUDGET" npx @halfwhey/claudraband "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    else
+        # Default: direct claude -p
+        timeout "$TIME_BUDGET" claude -p "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    fi
 
     EXIT_CODE=$?