@adaptic/maestro 1.8.2 → 1.8.3

package/scripts/huddle/huddle-controller.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Sophie Huddle — Controller
+ * Maestro Huddle — Controller
  *
  * Controls the Slack desktop app via Chrome DevTools Protocol for huddle
  * participation. Connects to Slack launched with --remote-debugging-port
@@ -430,7 +430,7 @@ export class HuddleController extends EventEmitter {
   }
 
   /**
-   * Mute/unmute Sophie's microphone in the huddle.
+   * Mute/unmute the agent's microphone in the huddle.
    * @param {boolean} muted - true to mute, false to unmute
    */
   async setMute(muted) {
@@ -449,7 +449,7 @@ export class HuddleController extends EventEmitter {
   // -------------------------------------------------------------------------
 
   /**
-   * Check if Sophie is currently in a huddle.
+   * Check if the agent is currently in a huddle.
    * @returns {Promise<boolean>}
    */
   async isInHuddle() {

package/scripts/huddle/huddle-server.mjs

@@ -17,7 +17,7 @@
  * Usage:
  *   node huddle-server.mjs                    # Start and listen for huddles
  *   node huddle-server.mjs --join #general    # Join huddle in #general
- *   node huddle-server.mjs --call mehran      # Initiate huddle with Mehran
+ *   node huddle-server.mjs --call principal  # Initiate huddle with the agent's principal
  */
 
 import dotenv from "dotenv";
@@ -635,14 +635,28 @@ class HuddleServer extends EventEmitter {
    * Used for access control (CEO gets write tools) and personalized greetings.
    */
   _resolveHuddleParticipant(identifier) {
-    // Known mappings — channel names and person names to access levels
+    // Seed `knownParticipants` with the agent's PRINCIPAL from
+    // config/agent.json (SOT) — replaces the previously-hardcoded "mehran"
+    // entry. Falls back to common operational handles for back-compat.
     const knownParticipants = {
-      "mehran": { slug: "mehran-granfar", name: "Mehran Granfar", accessLevel: "ceo" },
-      "mehran-granfar": { slug: "mehran-granfar", name: "Mehran Granfar", accessLevel: "ceo" },
-      "hootan": { slug: "hootan-yazhari", name: "Hootan Yazhari", accessLevel: "leadership" },
-      "nima": { slug: "nima-masroori", name: "Nima Masroori", accessLevel: "leadership" },
       "#ceo-office": { slug: "ceo-office", name: "CEO Office Channel", accessLevel: "ceo" },
     };
+    try {
+      const agentPath = join(AGENT_REPO_DIR, "config/agent.json");
+      const agentJson = JSON.parse(readFileSync(agentPath, "utf-8"));
+      const principal = agentJson?.principal;
+      if (principal?.firstName) {
+        const slug = `${principal.firstName}-${principal.lastName || ""}`.toLowerCase().replace(/\s+/g, "-").replace(/-+$/, "");
+        const entry = {
+          slug,
+          name: principal.fullName || `${principal.firstName} ${principal.lastName || ""}`.trim(),
+          accessLevel: "ceo",
+        };
+        knownParticipants[principal.firstName.toLowerCase()] = entry;
+        knownParticipants[slug] = entry;
+        knownParticipants["principal"] = entry;
+      }
+    } catch { /* agent.json unavailable — only #ceo-office remains */ }
 
     const key = (identifier || "").toLowerCase().replace(/^#/, "");
     const match = knownParticipants[key];
@@ -1015,7 +1029,7 @@ PERSONALITY:
 ABOUT ADAPTIC:
 - Adaptic is a global AI-native institutional asset management group
 - Headquartered in DIFC, Dubai with entities across seven plus jurisdictions
-- CEO and founder: Mehran Granfar
+- CEO and founder: the principal (resolved from config/agent.json)
 - Building Adaptic OS, an algorithmic trading platform
 - Currently in regulatory licensing phase
 

package/scripts/huddle/launch-slack.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 # ---------------------------------------------------------------------------
-# Sophie Huddle — Slack Launcher with CDP
+# Maestro Huddle — Slack Launcher with CDP
 #
 # Launches (or relaunches) the Slack desktop app with Chrome DevTools Protocol
 # enabled on port 9222. This allows Playwright/Puppeteer to connect and
@@ -207,7 +207,7 @@ show_status() {
 main() {
   log ""
   log "=========================================="
-  log "  Sophie Huddle — Slack Launcher"
+  log "  Maestro Huddle — Slack Launcher"
   log "  $(date)"
   log "=========================================="
 

package/scripts/huddle/package-lock.json

@@ -1,11 +1,11 @@
 {
-  "name": "sophie-huddle",
+  "name": "maestro-huddle",
   "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "sophie-huddle",
+      "name": "maestro-huddle",
       "version": "1.0.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0",

package/scripts/huddle/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "sophie-huddle",
+  "name": "maestro-huddle",
   "version": "1.0.0",
-  "description": "Sophie Nguyen — Slack Huddle Voice Participation",
+  "description": "Maestro — Slack huddle voice participation (agent-neutral)",
   "main": "huddle-server.mjs",
   "type": "module",
   "scripts": {

package/scripts/huddle/setup-audio.sh

@@ -2,13 +2,13 @@
 set -euo pipefail
 
 # ---------------------------------------------------------------------------
-# Sophie Huddle — Audio Setup
+# Maestro Huddle — Audio Setup
 #
 # Installs and configures BlackHole virtual audio devices for Slack huddle
 # participation. Two separate virtual devices prevent feedback loops:
 #
 #   BlackHole 2ch  → Slack's Speaker output (captures what others say)
-#   BlackHole 16ch → Slack's Mic input    (carries Sophie's synthesized voice)
+#   BlackHole 16ch → Slack's Mic input    (carries the agent's synthesized voice)
 #
 # Usage:
 #   ./setup-audio.sh           # Full install + verify
@@ -81,7 +81,7 @@ install_blackhole_16ch() {
     return 0
   fi
 
-  log "Installing BlackHole 16ch (Sophie mic input)..."
+  log "Installing BlackHole 16ch (agent mic input)..."
   brew install blackhole-16ch
 
   sleep 2
@@ -144,7 +144,7 @@ verify_audio_devices() {
     log "  Speaker:    BlackHole 2ch"
     log "  Microphone: BlackHole 16ch"
     log ""
-    log "This routes huddle audio through Sophie's capture pipeline."
+    log "This routes huddle audio through the agent's capture pipeline."
     log "System audio remains on built-in devices (no disruption)."
     return 0
   else
@@ -163,7 +163,7 @@ test_audio_capture() {
   log ""
   log "Recording 3 seconds from BlackHole 2ch..."
 
-  local test_file="/tmp/sophie-audio-test-$(date +%s).wav"
+  local test_file="/tmp/agent-audio-test-$(date +%s).wav"
 
   # Record 3 seconds from BlackHole 2ch
   if sox -t coreaudio "BlackHole 2ch" -r 16000 -c 1 -b 16 "$test_file" trim 0 3 2>/dev/null; then
@@ -207,7 +207,7 @@ test_audio_playback() {
 main() {
   log ""
   log "=========================================="
-  log "  Sophie Huddle — Audio Setup"
+  log "  Maestro Huddle — Audio Setup"
   log "  $(date)"
   log "=========================================="
   log ""

package/scripts/huddle/start-call.mjs

@@ -8,7 +8,7 @@
  *   3. Launch the huddle server to connect audio bridge
  *
  * Usage:
- *   node start-call.mjs mehran
+ *   node start-call.mjs principal
  *   node start-call.mjs hootan
  */
 
@@ -24,7 +24,7 @@ dotenv.config({ path: join(__dirname, "../..", ".env") });
 
 const execFileAsync = promisify(execFile);
 const CDP_URL = "http://localhost:9222";
-const target = process.argv[2] || "mehran";
+const target = process.argv[2] || "principal";
 
 // ---------------------------------------------------------------------------
 // Helper: send CDP command

package/scripts/huddle/test-pipeline.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Sophie Huddle — Pipeline Test
+ * Maestro Huddle — Pipeline Test
  *
  * Verifies each component of the huddle pipeline:
  *   1. CDP connection to Slack
@@ -38,7 +38,7 @@ function skip(name, detail = "") {
 
 async function main() {
   console.log("\n==========================================");
-  console.log("  Sophie Huddle — Pipeline Test");
+  console.log("  Maestro Huddle — Pipeline Test");
   console.log("  " + new Date().toISOString());
   console.log("==========================================\n");
 

package/scripts/parse-voice-transcript.mjs

@@ -31,17 +31,12 @@
  */
 
 // ---------------------------------------------------------------------------
-// Known callers — maps phone numbers to identities
-// Keep in sync with voice-ai/server.js CALLER_GREETINGS
+// Known callers — phone numbers to identities. Loaded from
+// config/caller-id-map.yaml at runtime; falls back to an empty map. Keep
+// caller-id-map.yaml in sync with voice-ai/server.js CALLER_GREETINGS.
 // ---------------------------------------------------------------------------
 
-const KNOWN_CALLERS = {
-  "+971585291799": {
-    name: "mehran-granfar",
-    role: "ceo",
-    privilege: "ceo",
-  },
-};
+const KNOWN_CALLERS = {}; // populated lazily from config/caller-id-map.yaml on first use
 
 // ---------------------------------------------------------------------------
 // Action item detection patterns

package/scripts/poller/gmail-poller.mjs

@@ -62,11 +62,17 @@ function extractSenderEmail(from) {
 }
 
 /**
- * Determine sender privilege from email address.
+ * Determine sender privilege from email address. The principal (CEO) is
+ * recognised by matching against the agent's `principal.email` or
+ * `principal.firstName` from config/agent.json — never hardcode names.
  */
 function resolveSenderPrivilege(email) {
   const lower = email.toLowerCase();
-  if (lower.includes("mehran")) return "ceo";
+  const me = loadAgent();
+  const principalEmail = (me.principal?.email || "").toLowerCase();
+  const principalFirst = (me.principal?.firstName || "").toLowerCase();
+  if (principalEmail && lower === principalEmail) return "ceo";
+  if (principalFirst && lower.includes(principalFirst)) return "ceo";
   if (lower.includes("adaptic.ai")) return "internal";
   return "external";
 }

package/scripts/poller/intra-session-check.mjs

@@ -167,15 +167,16 @@ async function checkCriticalChannels() {
             : false,
         });
 
-        // If CEO posted in a critical channel, also create a trigger
+        // If the principal posted in a critical channel, also create a trigger.
         const ceoMsgs = relevant.filter((m) => m.user === CEO_USER_ID);
         if (ceoMsgs.length > 0) {
+          const principalSlug = (_agent.principal?.fullName || "principal").toLowerCase().replace(/\s+/g, "-");
           writePriorityTrigger(
             `slack:${ch.id}:${ceoMsgs[0].ts}`,
-            "mehran-granfar",
+            principalSlug,
             ch.name,
             ceoMsgs[0].text,
-            `CEO message in #${ch.name} during intra-session poll`,
+            `Principal message in #${ch.name} during intra-session poll`,
           );
         }
       }

package/scripts/poller-launchd/install.sh

@@ -1,27 +1,65 @@
 #!/bin/bash
-# Install the Sophie poller as a macOS launchd daemon
+# Install the agent's poller as a macOS launchd daemon
 # Usage: ./scripts/poller-launchd/install.sh
+#
+# Agent identity is read from config/agent.json (SOT). The first-name slug
+# (lowercase) is used to build the launchd Label so multiple agents can run
+# their poller daemons side by side on the same Mac.
 
 set -e
 
-PLIST_NAME="ai.adaptic.sophie-poller"
-PLIST_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$PLIST_NAME.plist"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+AGENT_JSON="$AGENT_DIR/config/agent.json"
+
+# Resolve the agent's first name from the SOT. Prefer jq, fall back to awk.
+AGENT_FIRST=""
+if [ -f "$AGENT_JSON" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        AGENT_FIRST=$(jq -r '.firstName // empty' "$AGENT_JSON" | tr '[:upper:]' '[:lower:]')
+    else
+        AGENT_FIRST=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_JSON")
+    fi
+fi
+# Fallback chain: directory name (strip -ai suffix) → "agent".
+if [ -z "$AGENT_FIRST" ]; then
+    AGENT_FIRST=$(basename "$AGENT_DIR" | sed 's/-ai$//')
+fi
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST="agent"
+
+PLIST_NAME="ai.adaptic.${AGENT_FIRST}-poller"
+PLIST_SRC="$SCRIPT_DIR/$PLIST_NAME.plist"
 PLIST_DST="$HOME/Library/LaunchAgents/$PLIST_NAME.plist"
 
-echo "Installing Sophie poller daemon..."
+# Back-compat: the canonical plist on disk is still ai.adaptic.sophie-poller
+# until the per-agent generator catches up. If a $AGENT_FIRST-poller plist is
+# absent, fall back to the sophie one so the installer still works during
+# the rename transition.
+if [ ! -f "$PLIST_SRC" ]; then
+    SOPHIE_PLIST="$SCRIPT_DIR/ai.adaptic.sophie-poller.plist"
+    if [ -f "$SOPHIE_PLIST" ]; then
+        PLIST_SRC="$SOPHIE_PLIST"
+        echo "[install] using sophie poller plist as template (no ${AGENT_FIRST}-specific plist found)"
+    else
+        echo "[install] FATAL: no poller plist template found at $PLIST_SRC" >&2
+        exit 1
+    fi
+fi
+
+echo "Installing ${AGENT_FIRST} poller daemon..."
 
-# Copy plist to LaunchAgents
+# Copy plist to LaunchAgents and rewrite its Label so the installed copy
+# matches the agent's identity (handles the sophie-fallback case above).
 cp "$PLIST_SRC" "$PLIST_DST"
+sed -i '' "s|<string>ai.adaptic.[a-z][a-z0-9-]*-poller</string>|<string>$PLIST_NAME</string>|g" "$PLIST_DST"
 
 # Update node path to actual location
 NODE_PATH=$(which node)
 sed -i '' "s|/usr/local/bin/node|$NODE_PATH|g" "$PLIST_DST"
 
 # Inject environment variables from .env if it exists
-SOPHIE_AI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-ENV_FILE="$SOPHIE_AI_DIR/.env"
+ENV_FILE="$AGENT_DIR/.env"
 if [ -f "$ENV_FILE" ]; then
-    # Read SLACK_USER_TOKEN from .env and inject into plist
     SLACK_TOKEN=$(grep '^SLACK_USER_TOKEN=' "$ENV_FILE" | cut -d= -f2-)
     if [ -n "$SLACK_TOKEN" ]; then
         sed -i '' "s|<string>production</string>|<string>production</string>\n        <key>SLACK_USER_TOKEN</key>\n        <string>$SLACK_TOKEN</string>|g" "$PLIST_DST"
@@ -33,6 +71,6 @@ fi
 launchctl unload "$PLIST_DST" 2>/dev/null || true
 launchctl load "$PLIST_DST"
 
-echo "Sophie poller daemon installed and running."
-echo "Check status: launchctl list | grep sophie"
+echo "${AGENT_FIRST} poller daemon installed and running."
+echo "Check status: launchctl list | grep ${AGENT_FIRST}"
 echo "Uninstall: launchctl unload $PLIST_DST && rm $PLIST_DST"

package/scripts/pre_draft_lookup.py

@@ -11,10 +11,10 @@ logs the error and returns None — never blocks a send.
 
 Usage (Python import):
     from pre_draft_lookup import pre_draft_lookup
-    context = pre_draft_lookup("Mehran Granfar", message_type="slack")
+    context = pre_draft_lookup("<recipient name>", message_type="slack")
 
 Usage (CLI — for shell scripts):
-    python3 scripts/pre_draft_lookup.py --recipient "Mehran Granfar" --type slack --channel C099ABC
+    python3 scripts/pre_draft_lookup.py --recipient "<recipient name>" --type slack --channel C099ABC
 
 Created: 2026-04-04 — Memory Enhancement Phase 7
 """

package/scripts/self-optimization/compute-metrics.py

@@ -33,6 +33,26 @@ from collections import defaultdict
 REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 
 
+def _load_principal_slug():
+    """Load the principal's slug from config/agent.json (SOT).
+
+    Falls back to "principal" if agent.json is unavailable; metrics tagged
+    with the literal string "principal" then no-op gracefully rather than
+    being matched against a hardcoded name.
+    """
+    try:
+        with open(REPO_ROOT / "config" / "agent.json") as fh:
+            agent = json.load(fh)
+    except Exception:
+        return "principal"
+    p = agent.get("principal") or {}
+    full = p.get("fullName") or f"{p.get('firstName', '')} {p.get('lastName', '')}".strip()
+    return full.lower().replace(" ", "-") if full else "principal"
+
+
+PRINCIPAL_SLUG = _load_principal_slug()
+
+
 def parse_jsonl(filepath):
     """Parse a JSONL file, skipping malformed lines."""
     entries = []
@@ -216,8 +236,9 @@ def compute_metrics(date_str):
 
     # --- CEO Satisfaction ---
 
-    # ceo_correction_rate & ceo_positive_signal_rate: from interaction patterns
-    ceo_responses = [r for r in responses if r.get('sender') == 'mehran-granfar']
+    # ceo_correction_rate & ceo_positive_signal_rate: from interaction patterns.
+    # Principal slug resolved from config/agent.json (SOT) — never hardcoded.
+    ceo_responses = [r for r in responses if r.get('sender') == PRINCIPAL_SLUG]
     metrics['ceo_correction_rate'] = {
         'value': len(ceo_responses),
         'unit': 'ceo_interactions',

package/scripts/setup/boot-claude-session.sh

@@ -6,12 +6,12 @@
 # Opens Terminal.app with a Claude Code interactive session in the agent's
 # working directory. Called via launchd at login.
 #
-# This is separate from the sophie-daemon (which runs headless as a Node.js
+# This is separate from the maestro daemon (which runs headless as a Node.js
 # process for polling/dispatching). This script provides a visible, interactive
 # Claude Code session that the operator can observe and interact with.
 #
 # Usage:
-#   ./scripts/setup/boot-claude-session.sh [agent-dir]
+#   ./scripts/setup/boot-claude-session.sh <agent-dir>
 #
 # =============================================================================
 
@@ -20,14 +20,23 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 MAESTRO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Detect agent directory — prefer sophie-ai if it exists
-AGENT_DIR="${1:?Agent directory required as first argument (e.g. ~/sophie-ai)}"
+# Agent directory required as first argument (e.g. ~/<firstname>-ai).
+AGENT_DIR="${1:?Agent directory required as first argument (e.g. ~/<firstname>-ai)}"
 if [ ! -d "$AGENT_DIR" ]; then
   echo "ERROR: Agent directory does not exist: $AGENT_DIR" >&2
   exit 1
 fi
 
 AGENT_NAME=$(basename "$AGENT_DIR")
+# Resolve the agent's display name from config/agent.json (SOT), falling
+# back to the directory basename. Used for the Terminal window banner.
+AGENT_DISPLAY="$AGENT_NAME"
+if [ -f "$AGENT_DIR/config/agent.json" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    fn=$(jq -r '.fullName // empty' "$AGENT_DIR/config/agent.json")
+    [ -n "$fn" ] && AGENT_DISPLAY="$fn"
+  fi
+fi
 LOG_FILE="$MAESTRO_DIR/logs/watchdog/$(date +%Y-%m-%d)-boot-session.log"
 mkdir -p "$(dirname "$LOG_FILE")"
 
@@ -76,7 +85,7 @@ osascript <<APPLESCRIPT
 tell application "Terminal"
     activate
     -- Open a new window with claude running in the agent directory
-    do script "cd '$AGENT_DIR' && clear && echo '╔══════════════════════════════════════════════════════════╗' && echo '║  Sophie AI — Boot Session ($(date +%Y-%m-%d))              ║' && echo '╠══════════════════════════════════════════════════════════╣' && echo '║  Agent dir: $AGENT_DIR' && echo '║  Claude:    $CLAUDE_PATH' && echo '╚══════════════════════════════════════════════════════════╝' && echo '' && '$CLAUDE_PATH'"
+    do script "cd '$AGENT_DIR' && clear && echo '╔══════════════════════════════════════════════════════════╗' && echo '║  $AGENT_DISPLAY — Boot Session ($(date +%Y-%m-%d))' && echo '╠══════════════════════════════════════════════════════════╣' && echo '║  Agent dir: $AGENT_DIR' && echo '║  Claude:    $CLAUDE_PATH' && echo '╚══════════════════════════════════════════════════════════╝' && echo '' && '$CLAUDE_PATH'"
     -- Set the window title
     set custom title of front window to "$AGENT_NAME — Claude Code"
 end tell

package/scripts/setup/render-environment-yaml.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * render-environment-yaml.mjs
+ *
+ * Derive `config/environment.yaml` from `config/agent.json` (the SOT).
+ * Replaces the previously-static, agent-name-hardcoded environment.yaml so
+ * that operator_persona / operator_role / ceo / hostname / paths / agent
+ * blocks always reflect what agent.json says.
+ *
+ * Called by `maestro upgrade` (post-merge) and safe to run by hand:
+ *
+ *   node scripts/setup/render-environment-yaml.mjs               # write
+ *   node scripts/setup/render-environment-yaml.mjs --dry-run     # preview
+ *   node scripts/setup/render-environment-yaml.mjs --check       # exit 1 if drift
+ *
+ * Output is canonical (deterministic). If the existing file already matches,
+ * nothing is written. The first 5 lines of the rendered file always include
+ * a `# regenerated-from: config/agent.json` banner so operators editing it
+ * directly know they're editing a derived file.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+const AGENT_JSON = join(AGENT_DIR, "config", "agent.json");
+const TARGET = join(AGENT_DIR, "config", "environment.yaml");
+
+function fail(msg) {
+  process.stderr.write(`[render-environment-yaml] ${msg}\n`);
+  process.exit(1);
+}
+
+if (!existsSync(AGENT_JSON)) {
+  fail(`config/agent.json not found at ${AGENT_JSON} — nothing to derive from.`);
+}
+
+let agent;
+try {
+  agent = JSON.parse(readFileSync(AGENT_JSON, "utf-8"));
+} catch (err) {
+  fail(`failed to parse agent.json: ${err.message}`);
+}
+
+// Render a stable, predictable YAML. We don't use a YAML library to keep
+// this script dep-free and to control the exact formatting & comment
+// placement. Mind the trailing newline on every value.
+function quote(s) {
+  if (typeof s !== "string") return `"${s ?? ""}"`;
+  // No double-quotes in agent identity strings expected; if any appear,
+  // escape them properly.
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function yamlValue(v) {
+  if (v === null || v === undefined) return '""';
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return quote(String(v));
+}
+
+function render(agent) {
+  const repoSlug = agent.repoSlug || `${(agent.firstName || "agent").toLowerCase()}-ai`;
+  const home = `~/${repoSlug}`;
+  const lines = [
+    "# Environment Configuration",
+    "# regenerated-from: config/agent.json by scripts/setup/render-environment-yaml.mjs",
+    "# DO NOT EDIT BY HAND — changes will be overwritten on every upgrade.",
+    "# Edit config/agent.json (the SOT) and re-run the renderer instead.",
+    "",
+    "system:",
+    `  name: maestro`,
+    `  version: 1.0.0`,
+    `  operator_persona: ${yamlValue(agent.fullName)}`,
+    `  operator_role: ${yamlValue(agent.title)}`,
+    `  company: ${yamlValue(agent.company)}`,
+    `  ceo: ${yamlValue(agent.principal?.fullName || "")}`,
+    `  timezone: ${yamlValue(agent.timezone || "UTC")}`,
+    "",
+    "machine:",
+    `  type: mac-mini`,
+    `  os: macOS`,
+    `  hostname: ${yamlValue(agent.machineName || "")}`,
+    `  purpose: Autonomous agent operations node`,
+    "",
+    "paths:",
+    `  agent_home: ${home}`,
+    `  logs: ${home}/logs`,
+    `  outputs: ${home}/outputs`,
+    "",
+    "agent:",
+    `  name: ${yamlValue(agent.fullName)}`,
+    `  email: ${yamlValue(agent.email)}`,
+    `  phone: ${yamlValue(agent.phone || "")}`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+const rendered = render(agent);
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run") || args.includes("-n");
+const check = args.includes("--check");
+
+if (check) {
+  if (!existsSync(TARGET)) {
+    process.stdout.write("config/environment.yaml missing\n");
+    process.exit(1);
+  }
+  const current = readFileSync(TARGET, "utf-8");
+  if (current === rendered) {
+    process.stdout.write("environment.yaml is up to date with agent.json\n");
+    process.exit(0);
+  }
+  process.stdout.write("environment.yaml drifts from agent.json — rerun the renderer\n");
+  process.exit(1);
+}
+
+if (dryRun) {
+  process.stdout.write(rendered);
+  process.exit(0);
+}
+
+// Skip the write if already up to date — keeps `upgrade` idempotent.
+if (existsSync(TARGET)) {
+  const current = readFileSync(TARGET, "utf-8");
+  if (current === rendered) {
+    process.stdout.write("environment.yaml already up to date\n");
+    process.exit(0);
+  }
+}
+
+writeFileSync(TARGET, rendered);
+process.stdout.write(`environment.yaml regenerated from agent.json (${rendered.split("\n").length} lines)\n`);

package/scripts/watchdog/ai.maestro.memory-watchdog.plist

@@ -8,7 +8,7 @@
     <key>ProgramArguments</key>
     <array>
         <string>/bin/bash</string>
-        <string>/Users/sophie/maestro/scripts/watchdog/memory-watchdog.sh</string>
+        <string>__AGENT_DIR__/scripts/watchdog/memory-watchdog.sh</string>
     </array>
 
     <key>StartInterval</key>
@@ -18,10 +18,10 @@
     <true/>
 
     <key>StandardOutPath</key>
-    <string>/Users/sophie/maestro/logs/watchdog/launchd-stdout.log</string>
+    <string>__AGENT_DIR__/logs/watchdog/launchd-stdout.log</string>
 
     <key>StandardErrorPath</key>
-    <string>/Users/sophie/maestro/logs/watchdog/launchd-stderr.log</string>
+    <string>__AGENT_DIR__/logs/watchdog/launchd-stderr.log</string>
 
     <key>EnvironmentVariables</key>
     <dict>

package/scripts/watchdog/force-reboot.sh

@@ -12,7 +12,7 @@
 #   ./scripts/watchdog/force-reboot.sh --status      # Check heartbeat and uptime
 #
 # Remote usage (from another machine via SSH):
-#   ssh sophie@mac-mini.local "~/maestro/scripts/watchdog/force-reboot.sh --graceful"
+#   ssh <user>@<mac-mini> "~/maestro/scripts/watchdog/force-reboot.sh --graceful"
 #
 # =============================================================================
 #
@@ -43,8 +43,8 @@
 #    - With `pmset autorestart 1`, it will boot automatically
 #
 # 5. SSH + SYSDIAGNOSE RESET (partial freeze, SSH still works):
-#    - ssh sophie@mac-mini.local "sudo reboot"
-#    - Or: ssh sophie@mac-mini.local "sudo shutdown -r now"
+#    - ssh <user>@<mac-mini> "sudo reboot"
+#    - Or: ssh <user>@<mac-mini> "sudo shutdown -r now"
 #
 # =============================================================================