@cohortapp/agent-sdk 2.3.0

package/lib/setup/sections/recovery.mjs

@@ -0,0 +1,159 @@
+/**
+ * sections/recovery.mjs — reboot/outage recovery + resource governance (WS4, order 85).
+ *
+ * Cross-workstream seam (design §3.2): registered by dropping this file into
+ * sections/ (no core edit). It installs the recovery config the resource
+ * governor / watchdog / budget guard read, and verifies the self-healing
+ * recovery wiring (watchdog script + heartbeat, governor sizing, pmset
+ * autorestart). Order 85 (after learning/80, before verify/90) per design §3.2.
+ *
+ * Cardinal rule surfaced to the operator: the ONLY thing that permanently
+ * stops the agent is a HUMAN writing .emergency-stop. Everything here is about
+ * degrading gracefully and recovering automatically — never bricking.
+ *
+ * Every hook is non-blocking under --headless (detect/apply/verify never read
+ * the TTY; prompt honours `io` headless resolution). Idempotent.
+ *
+ * @module lib/setup/sections/recovery
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import * as io from "../io.mjs";
+
+const CONFIG_REL = join("config", "recovery.yaml");
+const WATCHDOG_REL = join("scripts", "watchdog", "memory-watchdog.sh");
+
+/** Write config/recovery.yaml from the scaffold (or a minimal stub). Idempotent. */
+function ensureConfig(ctx) {
+  const dst = join(ctx.agentRoot, CONFIG_REL);
+  if (existsSync(dst)) return; // never clobber an operator-customised file
+  mkdirSync(join(ctx.agentRoot, "config"), { recursive: true });
+  const scaffold = join(ctx.maestroRoot, "scaffold", "config", "recovery.yaml");
+  if (existsSync(scaffold)) {
+    try { copyFileSync(scaffold, dst); return; } catch { /* fall through to stub */ }
+  }
+  writeFileSync(dst, [
+    "# config/recovery.yaml — Reboot/outage recovery + resource governance (WS4)",
+    "# Defaults apply when keys are omitted. The watchdog NEVER writes",
+    "# .emergency-stop — that flag is human-only.",
+    "governor:",
+    "  ram_fraction: 0.60",
+    "budget:",
+    "  daily_spend_cap_usd: 25",
+    "pmset_autorestart_required: true",
+    "",
+  ].join("\n"));
+}
+
+/** Is pmset autorestart enabled? Returns true/false/null (unknown / non-mac). */
+function pmsetAutorestart() {
+  try {
+    const out = execFileSync("pmset", ["-g"], { encoding: "utf-8" });
+    const m = out.match(/\bautorestart\s+(\d)/);
+    if (!m) return null;
+    return m[1] === "1";
+  } catch {
+    return null; // pmset unavailable (non-mac / CI) — soft signal
+  }
+}
+
+/** Compute the governor's dynamicMax for this host (sizing sanity in verify). */
+function computeDynamicMax() {
+  try {
+    const totalmem = os.totalmem();
+    const cpus = Math.max(1, os.cpus().length || 1);
+    const byRam = Math.floor((totalmem * 0.6) / (750 * 1024 * 1024));
+    return Math.min(Math.min(10, cpus), Math.max(1, byRam));
+  } catch { return null; }
+}
+
+export default {
+  id: "recovery",
+  label: "Recovery & resource governance",
+  order: 85,
+
+  async detect(ctx) {
+    const missing = [];
+    if (!existsSync(join(ctx.agentRoot, CONFIG_REL))) missing.push("config/recovery.yaml");
+    if (!existsSync(join(ctx.agentRoot, WATCHDOG_REL))) missing.push("scripts/watchdog/memory-watchdog.sh");
+    if (missing.length === 0) return { status: "complete", summary: "recovery + governance configured" };
+    if (missing.length === 2) return { status: "unconfigured", missing };
+    return { status: "partial", summary: "recovery partially configured", missing };
+  },
+
+  async prompt(ctx) {
+    // The only operator choice worth surfacing is the daily spend cap; the rest
+    // are sensible self-healing defaults. Headless → uses the pre-supplied
+    // answer or leaves the default.
+    const cap = await io.text(ctx, {
+      message: "Daily Claude spend cap (USD) before the agent goes essential-only (inbox-only)?",
+      key: "dailySpendCapUsd",
+      default: "25",
+    });
+    ctx.answers.dailySpendCapUsd = cap;
+  },
+
+  async apply(ctx) {
+    ensureConfig(ctx);
+    // If the operator set a cap, fold it into the config (best-effort line edit;
+    // the env var DAILY_SPEND_CAP_USD also overrides at runtime).
+    const cap = ctx.answers && ctx.answers.dailySpendCapUsd;
+    if (cap && /^\d+(\.\d+)?$/.test(String(cap))) {
+      try {
+        const p = join(ctx.agentRoot, CONFIG_REL);
+        let body = readFileSync(p, "utf-8");
+        if (/daily_spend_cap_usd:/.test(body)) {
+          body = body.replace(/(\n\s*daily_spend_cap_usd:\s*)\S+/, `$1${cap}`);
+        } else {
+          body += `\nbudget:\n  daily_spend_cap_usd: ${cap}\n`;
+        }
+        writeFileSync(p, body);
+      } catch { /* fail-open */ }
+    }
+    // Ensure the runtime state dirs the governance layer writes to exist so the
+    // first watchdog/governor run doesn't race a missing directory.
+    for (const d of ["state", "state/sessions/resume-pending", "state/rate-limits", "state/cost-tracking"]) {
+      try { mkdirSync(join(ctx.agentRoot, d), { recursive: true }); } catch { /* */ }
+    }
+  },
+
+  async verify(ctx) {
+    const checks = [];
+
+    const cfgOk = existsSync(join(ctx.agentRoot, CONFIG_REL));
+    checks.push({ name: "config/recovery.yaml present", ok: cfgOk, remedy: cfgOk ? undefined : "run `maestro setup --only recovery`" });
+
+    const wdPath = join(ctx.agentRoot, WATCHDOG_REL);
+    const wdOk = existsSync(wdPath);
+    checks.push({ name: "memory-watchdog.sh installed", ok: wdOk, remedy: wdOk ? undefined : "run `maestro upgrade` to install the watchdog" });
+
+    // The watchdog must NOT write .emergency-stop on OOM (the brick fix). Cheap
+    // static guard: the OOM path's run_watchdog body must not echo into the flag.
+    if (wdOk) {
+      let safe = true;
+      try {
+        const body = readFileSync(wdPath, "utf-8");
+        // A *write* to .emergency-stop would look like `> "...emergency-stop"`.
+        safe = !/>\s*"?\$?\{?[A-Z_]*\}?[^"\n]*\.emergency-stop"?/.test(body);
+      } catch { /* unreadable — leave safe=true, doctor covers runtime */ }
+      checks.push({ name: "watchdog does not write .emergency-stop on OOM (human-only)", ok: safe, remedy: safe ? undefined : "watchdog still writes .emergency-stop — run `maestro upgrade`" });
+    }
+
+    // Governor sizing sanity (informational; always ok).
+    const dMax = computeDynamicMax();
+    checks.push({ name: `governor dynamicMax=${dMax ?? "?"} for this host`, ok: true });
+
+    // pmset autorestart — SOFT check (null on non-mac/CI is tolerated).
+    const ar = pmsetAutorestart();
+    if (ar === true) checks.push({ name: "pmset autorestart=1 (recovers from power loss)", ok: true });
+    else if (ar === false) checks.push({ name: "pmset autorestart enabled", ok: false, remedy: "sudo pmset -a autorestart 1" });
+    else checks.push({ name: "pmset autorestart (skipped — non-mac/CI)", ok: true });
+
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};

package/lib/setup/sections/recovery.test.mjs

@@ -0,0 +1,98 @@
+/**
+ * recovery.test.mjs — WS4 setup section (order 85) tests.
+ * Run: node --test lib/setup/sections/recovery.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import recovery from "./recovery.mjs";
+import * as io from "../io.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+function tmpRoot() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-recsec-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  return root;
+}
+function ctxFor(root, answers = {}) {
+  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io };
+}
+/** Copy the real watchdog into the test root so verify checks the real body. */
+function installWatchdog(root) {
+  mkdirSync(join(root, "scripts/watchdog"), { recursive: true });
+  copyFileSync(join(MAESTRO_ROOT, "scripts/watchdog/memory-watchdog.sh"), join(root, "scripts/watchdog/memory-watchdog.sh"));
+}
+
+test("section shape: id/order=85/hooks", () => {
+  assert.equal(recovery.id, "recovery");
+  assert.equal(recovery.order, 85);
+  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof recovery[h], "function");
+});
+
+test("detect: unconfigured before apply", async () => {
+  const root = tmpRoot();
+  const before = await recovery.detect(ctxFor(root));
+  assert.equal(before.status, "unconfigured");
+  assert.ok(before.missing.includes("config/recovery.yaml"));
+});
+
+test("apply writes config/recovery.yaml from scaffold + seeds state dirs", async () => {
+  const root = tmpRoot();
+  await recovery.apply(ctxFor(root, {}));
+  assert.ok(existsSync(join(root, "config", "recovery.yaml")));
+  // Runtime state dirs the governance layer writes to are pre-created.
+  assert.ok(existsSync(join(root, "state/sessions/resume-pending")));
+  assert.ok(existsSync(join(root, "state/rate-limits")));
+  // The scaffold carries the governance knobs.
+  const body = readFileSync(join(root, "config", "recovery.yaml"), "utf8");
+  assert.match(body, /ram_fraction/);
+  assert.match(body, /daily_spend_cap_usd/);
+});
+
+test("apply folds the operator's daily spend cap into the config", async () => {
+  const root = tmpRoot();
+  await recovery.apply(ctxFor(root, { dailySpendCapUsd: "40" }));
+  const body = readFileSync(join(root, "config", "recovery.yaml"), "utf8");
+  assert.match(body, /daily_spend_cap_usd:\s*40/);
+});
+
+test("apply is idempotent — never clobbers an existing recovery.yaml", async () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config", "recovery.yaml"), "# custom\nbudget:\n  daily_spend_cap_usd: 99\n");
+  await recovery.apply(ctxFor(root, { dailySpendCapUsd: "40" }));
+  const body = readFileSync(join(root, "config", "recovery.yaml"), "utf8");
+  // The operator's existing file is preserved (cap line edited in place, custom comment kept).
+  assert.match(body, /# custom/);
+} );
+
+test("verify passes when config + watchdog present and watchdog is OOM-brick-safe", async () => {
+  const root = tmpRoot();
+  await recovery.apply(ctxFor(root, {}));
+  installWatchdog(root);
+  const res = await recovery.verify(ctxFor(root));
+  const byName = Object.fromEntries(res.checks.map((c) => [c.name, c.ok]));
+  assert.equal(byName["config/recovery.yaml present"], true);
+  assert.equal(byName["memory-watchdog.sh installed"], true);
+  // The crux: the installed watchdog must NOT write .emergency-stop on OOM.
+  assert.equal(byName["watchdog does not write .emergency-stop on OOM (human-only)"], true);
+});
+
+test("verify flags a watchdog that DOES write .emergency-stop on OOM (regression guard)", async () => {
+  const root = tmpRoot();
+  await recovery.apply(ctxFor(root, {}));
+  mkdirSync(join(root, "scripts/watchdog"), { recursive: true });
+  // A legacy-style watchdog that bricks on OOM.
+  writeFileSync(join(root, "scripts/watchdog/memory-watchdog.sh"),
+    `#!/bin/bash\nMAESTRO_DIR=/x\necho "OOM" > "$MAESTRO_DIR/.emergency-stop"\n`);
+  const res = await recovery.verify(ctxFor(root));
+  const check = res.checks.find((c) => /does not write .emergency-stop/.test(c.name));
+  assert.equal(check.ok, false, "must flag a watchdog that writes the human-only flag");
+  assert.ok(check.remedy);
+});

package/lib/setup/sections/tools.mjs

@@ -0,0 +1,132 @@
+/**
+ * sections/tools.mjs — select channels + MCP servers to enable.  (order 50)
+ *
+ * Records selections only (per WS1 scope): channel choices land as commented
+ * .env key stubs the operator fills in, and MCP selections are recorded in
+ * config/mcp-servers.yaml's `enabled` list. The per-channel deep wiring (Socket
+ * Mode, Baileys auth, relay) is WS2's comms section.
+ *
+ * @module lib/setup/sections/tools
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, renameSync, appendFileSync, mkdirSync } from "node:fs";
+import * as io from "../io.mjs";
+
+const CHANNELS = [
+  { value: "slack", label: "Slack", hint: "DMs, channels, threads" },
+  { value: "gmail", label: "Email (Gmail)", hint: "IMAP + send" },
+  { value: "whatsapp", label: "WhatsApp", hint: "Baileys" },
+  { value: "telegram", label: "Telegram", hint: "grammY (WS2)" },
+  { value: "sms", label: "SMS", hint: "Twilio" },
+  { value: "voice", label: "Voice / phone", hint: "Realtime" },
+];
+
+/** .env stub keys we drop (commented) per selected channel. */
+const CHANNEL_ENV_STUBS = {
+  slack: ["# SLACK_USER_TOKEN=", "# SLACK_BOT_TOKEN=", "# SLACK_APP_LEVEL_TOKEN=xapp-1-…"],
+  gmail: ["# GMAIL_APP_PASSWORD="],
+  sms: ["# TWILIO_ACCOUNT_SID=", "# TWILIO_AUTH_TOKEN=", "# TWILIO_FROM_NUMBER="],
+  whatsapp: ["# WHATSAPP_ENABLED=1"],
+  telegram: ["# TELEGRAM_BOT_TOKEN="],
+  voice: ["# VOICE_ENABLED=1"],
+};
+
+function readMcpServers(agentRoot) {
+  const p = join(agentRoot, "config", "mcp-servers.yaml");
+  return existsSync(p) ? readFileSync(p, "utf-8") : "";
+}
+
+export default {
+  id: "tools",
+  label: "Channels & MCP servers",
+  order: 50,
+
+  async detect(ctx) {
+    const recorded = readSelections(ctx.agentRoot);
+    if (!recorded) return { status: "unconfigured", missing: ["no selections recorded"] };
+    return { status: "partial", summary: `channels: ${(recorded.channels || []).join(", ") || "none"}` };
+  },
+
+  async prompt(ctx) {
+    const channels = await io.multiselect(ctx, {
+      message: "Which messaging channels will this agent use?",
+      key: "channels",
+      choices: CHANNELS,
+      default: [],
+    });
+    // Offer MCP servers the role declared (from generate-capability), if present.
+    const declared = parseDeclaredMcp(readMcpServers(ctx.agentRoot));
+    let mcp = [];
+    if (declared.length) {
+      mcp = await io.multiselect(ctx, {
+        message: "Enable which MCP servers now?",
+        key: "mcp",
+        choices: declared.map((m) => ({ value: m, label: m })),
+        default: [],
+      });
+    }
+    ctx.answers.tools = { channels, mcp };
+  },
+
+  async apply(ctx) {
+    const a = (ctx.answers && ctx.answers.tools) || pull(ctx);
+    if (!a) return;
+    // 1. Record selections sidecar (durable, machine-readable).
+    writeSelections(ctx.agentRoot, { channels: a.channels || [], mcp: a.mcp || [], recordedAt: new Date().toISOString() });
+    // 2. Drop commented .env stubs for each selected channel (never overwrite a set key).
+    const envPath = join(ctx.agentRoot, ".env");
+    const env = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
+    const additions = [];
+    for (const ch of a.channels || []) {
+      for (const stub of CHANNEL_ENV_STUBS[ch] || []) {
+        const realKey = stub.replace(/^#\s*/, "").split("=")[0];
+        if (!new RegExp(`^${realKey}=.+`, "m").test(env) && !env.includes(stub)) additions.push(stub);
+      }
+    }
+    if (additions.length) {
+      const prefix = env.endsWith("\n") || env === "" ? "" : "\n";
+      appendFileSync(envPath, `${prefix}# ── channel stubs (maestro setup; fill in) ──\n${additions.join("\n")}\n`);
+    }
+  },
+
+  async verify(ctx) {
+    const recorded = readSelections(ctx.agentRoot);
+    const ok = !!recorded;
+    return { ok: true, checks: [{ name: `channel/MCP selections recorded (${ok ? (recorded.channels || []).length : 0})`, ok: true }] };
+  },
+};
+
+function selectionsPath(agentRoot) { return join(agentRoot, "state", "setup", "selections.json"); }
+
+function readSelections(agentRoot) {
+  const p = selectionsPath(agentRoot);
+  try { return existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : null; } catch { return null; }
+}
+function writeSelections(agentRoot, obj) {
+  const p = selectionsPath(agentRoot);
+  mkdirSync(join(agentRoot, "state", "setup"), { recursive: true });
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf-8");
+  renameSync(tmp, p);
+}
+
+/** Pull MCP server ids declared by generate-capability (best-effort line scan). */
+function parseDeclaredMcp(body) {
+  if (!body) return [];
+  const out = [];
+  for (const line of body.split("\n")) {
+    const m = line.match(/^\s*-\s*(?:id|name):\s*([A-Za-z0-9_.-]+)/);
+    if (m) out.push(m[1]);
+  }
+  return [...new Set(out)];
+}
+
+function pull(ctx) {
+  const ans = ctx.answers || {};
+  if (ans.tools) return ans.tools;
+  if ("channels" in ans || "mcp" in ans) return { channels: ans.channels || [], mcp: ans.mcp || [] };
+  return null;
+}

package/lib/setup/sections/verify.mjs

@@ -0,0 +1,97 @@
+/**
+ * sections/verify.mjs — final verification + capability summary table.  (order 90)
+ *
+ * apply() is a no-op (verification writes nothing). verify() aggregates every
+ * other section's verify() result + the Claude API probe + the completeness
+ * gate, then builds an N/M capability table with a remedy line per failure.
+ *
+ * HARD failures (cause setup to exit non-zero) are limited to:
+ *   - no identity / config/agent.json missing
+ *   - unresolvable archetype
+ *   - Claude API unreachable
+ * Everything else is reported but non-fatal (channels optional, enrichment
+ * best-effort), per design §4 "Exit non-zero only on hard failures".
+ *
+ * @module lib/setup/sections/verify
+ */
+
+"use strict";
+
+import { probeClaude } from "../claude-probe.mjs";
+import { assertComplete } from "../completeness.mjs";
+import * as io from "../io.mjs";
+
+export default {
+  id: "verify",
+  label: "Verification & capability summary",
+  order: 90,
+
+  async detect() {
+    // verify always runs (it has no persisted "done" state of its own).
+    return { status: "partial", summary: "runs the live capability probe" };
+  },
+
+  async prompt() { /* none */ },
+
+  async apply() { /* verification is read-only */ },
+
+  /**
+   * Aggregate verification. Optionally pass the live section list via
+   * `ctx.sections` so we can run each section's verify(); otherwise we still
+   * run the core probes (completeness + Claude API).
+   */
+  async verify(ctx) {
+    const rows = [];
+
+    // Per-section verify (skip self to avoid recursion).
+    const sections = (ctx.sections || []).filter((s) => s.id !== "verify");
+    for (const s of sections) {
+      try {
+        const r = await s.verify(ctx);
+        for (const c of r.checks || []) rows.push({ section: s.id, ...c });
+      } catch (e) {
+        rows.push({ section: s.id, name: `${s.id} verify`, ok: false, remedy: `verify threw: ${e && e.message ? e.message : e}` });
+      }
+    }
+
+    // Core probes (always, even if no sections passed in).
+    const complete = await assertComplete(ctx.agentRoot);
+    const probe = probeClaude(ctx.agentRoot);
+
+    // Hard-fail conditions.
+    const noIdentity = complete.missing.some((m) => m.artifact === "config/agent.json");
+    const archetypeOk = complete.archetypeOk;
+    const hardFail = noIdentity || !archetypeOk || !probe.ok;
+
+    return {
+      ok: !hardFail,
+      hardFail,
+      rows,
+      complete,
+      probe,
+      checks: rows,
+    };
+  },
+
+  /**
+   * Render the capability table to stdout. Separated from verify() so the
+   * runner can call it; pure presentation.
+   * @param {{rows:Array, complete:object, probe:object}} result
+   */
+  renderTable(result) {
+    const rows = result.rows || [];
+    const passed = rows.filter((r) => r.ok).length;
+    io.note("");
+    io.note(`Capability summary — ${passed}/${rows.length} checks passing`);
+    for (const r of rows) {
+      const mark = r.ok ? "  ✓" : "  ✗";
+      const where = r.section ? ` [${r.section}]` : "";
+      io.note(`${mark} ${r.name}${where}`);
+      if (!r.ok && r.remedy) io.note(`      ↳ ${r.remedy}`, { dim: true });
+    }
+    if (result.probe && !result.probe.ok && result.probe.remedy) {
+      io.note(`  ✗ ${result.probe.name}`);
+      io.note(`      ↳ ${result.probe.remedy}`, { dim: true });
+    }
+  },
+};

package/lib/setup/sot.mjs

@@ -0,0 +1,205 @@
+/**
+ * lib/setup/sot.mjs — single-source-of-truth helpers for agent identity.
+ *
+ * `config/agent.json` is the canonical store. `config/agent.ts` is a generated
+ * thin re-export wrapper over it (the migrate-agent-to-sot.mjs end-state); this
+ * module owns reading/merging the JSON and (re)writing the wrapper idempotently.
+ *
+ *   readAgentJson(agentRoot)            → object | null
+ *   mergeAgentJson(agentRoot, patch)    → merged object (deep merge-by-key, atomic)
+ *   ensureSotWrapper(agentRoot)         → { wrote, path }  (writes config/agent.ts iff needed)
+ *   isWrapper(tsSource)                 → boolean (does this .ts re-export agent.json?)
+ *   WRAPPER_TEMPLATE                    → the canonical wrapper body
+ *
+ * Atomic writes (tmp + rename). `mergeAgentJson` deep-merges plain objects and
+ * never drops keys the patch did not mention.
+ *
+ * @module lib/setup/sot
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const JSON_REL = "config/agent.json";
+const TS_REL = "config/agent.ts";
+
+/** Path helpers. */
+export function agentJsonPath(agentRoot) { return join(agentRoot, JSON_REL); }
+export function agentTsPath(agentRoot) { return join(agentRoot, TS_REL); }
+
+/**
+ * Read config/agent.json. Returns null when missing; throws on malformed JSON
+ * (a corrupt SoT is a real error the caller should surface, unlike the
+ * fail-soft progress store).
+ * @param {string} agentRoot
+ * @returns {object|null}
+ */
+export function readAgentJson(agentRoot) {
+  const p = agentJsonPath(agentRoot);
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+
+function writeAtomic(path, body) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, body, "utf-8");
+  renameSync(tmp, path);
+}
+
+/** Write config/agent.json atomically (stable 2-space JSON + trailing newline). */
+export function writeAgentJson(agentRoot, obj) {
+  writeAtomic(agentJsonPath(agentRoot), JSON.stringify(obj, null, 2) + "\n");
+  return obj;
+}
+
+/**
+ * Deep merge: plain objects merge key-by-key (patch wins per leaf), arrays and
+ * scalars are replaced wholesale by the patch. Unrelated existing keys are
+ * always preserved. Returns a new object; inputs are not mutated.
+ * @param {object} base @param {object} patch @returns {object}
+ */
+export function deepMergeByKey(base, patch) {
+  if (patch === null || patch === undefined) return clone(base);
+  if (Array.isArray(base) || Array.isArray(patch)) return clone(patch);
+  if (typeof base !== "object" || typeof patch !== "object") return clone(patch);
+  const out = clone(base);
+  for (const k of Object.keys(patch)) {
+    const b = out[k];
+    const p = patch[k];
+    if (b && p && typeof b === "object" && typeof p === "object" && !Array.isArray(b) && !Array.isArray(p)) {
+      out[k] = deepMergeByKey(b, p);
+    } else if (p !== undefined) {
+      out[k] = clone(p);
+    }
+  }
+  return out;
+}
+
+function clone(v) { return v === undefined ? undefined : JSON.parse(JSON.stringify(v)); }
+
+/**
+ * Merge a patch into config/agent.json (creating it from the patch if absent),
+ * writing atomically. Never drops unrelated fields.
+ * @param {string} agentRoot
+ * @param {object} patch
+ * @returns {object} the merged object
+ */
+export function mergeAgentJson(agentRoot, patch) {
+  const current = readAgentJson(agentRoot) || {};
+  const merged = deepMergeByKey(current, patch || {});
+  return writeAgentJson(agentRoot, merged);
+}
+
+/**
+ * Heuristic: is the supplied agent.ts source a thin wrapper that re-exports
+ * from ./agent.json (rather than a standalone literal `export const agent = {…}`)?
+ * @param {string} tsSource
+ * @returns {boolean}
+ */
+export function isWrapper(tsSource) {
+  if (typeof tsSource !== "string") return false;
+  const importsJson = /import\s+\w+\s+from\s+['"]\.\/agent\.json['"]/.test(tsSource);
+  // A standalone literal assigns an inline object to `agent`.
+  const inlineLiteral = /export\s+const\s+agent\s*(?::[^=]+)?=\s*\{/.test(tsSource);
+  return importsJson && !inlineLiteral;
+}
+
+/**
+ * Ensure config/agent.ts is the thin wrapper. Idempotent: if it already is a
+ * wrapper, no write occurs. Returns { wrote, path }.
+ * @param {string} agentRoot
+ * @returns {{wrote:boolean, path:string}}
+ */
+export function ensureSotWrapper(agentRoot) {
+  const p = agentTsPath(agentRoot);
+  if (existsSync(p)) {
+    const src = readFileSync(p, "utf-8");
+    if (isWrapper(src)) return { wrote: false, path: p };
+  }
+  writeAtomic(p, WRAPPER_TEMPLATE);
+  return { wrote: true, path: p };
+}
+
+/**
+ * The canonical thin-wrapper body for config/agent.ts. Mirrors
+ * scripts/setup/migrate-agent-to-sot.mjs `inlineWrapper()` so a repo migrated by
+ * either path ends up byte-identical.
+ */
+export const WRAPPER_TEMPLATE = `/**
+ * Maestro — Agent Configuration (TypeScript wrapper)
+ *
+ * The canonical source of truth is \`config/agent.json\`. Edit that file,
+ * then run \`node scripts/setup/generate-agent-env.mjs\` to regenerate the
+ * shell environment file.
+ *
+ * This wrapper exposes typed access plus a few computed convenience values.
+ */
+
+import agentData from './agent.json' with { type: 'json' };
+
+export interface VoiceMode {
+  id: string;
+  label: string;
+  description: string;
+}
+
+export interface PrincipalConfig {
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  title: string;
+  email: string;
+  slackMemberId: string;
+}
+
+export interface AgentConfig {
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  title: string;
+  archetype: string;
+
+  email: string;
+  phone: string;
+  slackMemberId: string;
+
+  company: string;
+  companyDomain: string;
+  companyDescription: string;
+
+  principal: PrincipalConfig;
+
+  machineName: string;
+  repoSlug: string;
+  launchdLabelPrefix: string;
+
+  timezone: string;
+  locale: string;
+
+  schedule: {
+    morningBrief: string;
+    commsTriage: string[];
+    eveningWrap: string;
+    overnightMonitoring: string;
+  };
+
+  communication: {
+    defaultTone: string;
+    externalTone: string;
+    voiceModes: VoiceMode[];
+  };
+
+  responsibilities: string[];
+  operatingPrinciples: string[];
+}
+
+export const agent: AgentConfig = agentData as AgentConfig;
+
+export const AGENT_UPPER = agent.firstName.toUpperCase();
+export const AGENT_LOWER = agent.firstName.toLowerCase();
+export const REPO_DIR = \`~/\${agent.repoSlug}\`;
+export const EMAIL_SIGNATURE = \`\${agent.fullName} | \${agent.title} | \${agent.company}\`;
+`;