@cohortapp/agent-sdk 2.3.0

package/scripts/setup/init-model-router.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * init-model-router.mjs — Idempotent init step for the model-router feature.
+ *
+ * Called by `maestro init` / `maestro upgrade` (via the feature-init
+ * tracker). Safe to run repeatedly.
+ *
+ * What it does (in order):
+ *   1. Confirms scaffold/config/model-routing.yaml.example is in the
+ *      framework install.
+ *   2. If the agent already has config/model-routing.yaml, validates that
+ *      it parses and points at known backends; otherwise copies the
+ *      example file into place as `config/model-routing.yaml.disabled`
+ *      (operator renames it once they've added their keys).
+ *   3. Patches .env.example with placeholder lines for MOONSHOT_API_KEY
+ *      and OPENROUTER_API_KEY if they aren't there yet (idempotent).
+ *   4. Prints a short summary of detected backends and which env vars
+ *      need to be filled in.
+ *
+ * The router itself is opt-in: a disabled file means "the framework is
+ * aware of routing, the operator has not yet chosen to switch on
+ * non-Anthropic backends". Existing daemon behaviour is preserved
+ * verbatim until the operator renames .disabled → .yaml.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-model-router]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-model-router]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-model-router]  · ${m}\n`);
+
+// ── Resolve scaffold example
+const examplePath = join(MAESTRO_ROOT, "scaffold/config/model-routing.yaml.example");
+const exampleAlt = join(MAESTRO_ROOT, "scaffold", "config", "model-routing.yaml.example");
+const exampleSrc = existsSync(examplePath) ? examplePath : existsSync(exampleAlt) ? exampleAlt : null;
+if (!exampleSrc) {
+  warn(`scaffold/config/model-routing.yaml.example not found in framework install at ${MAESTRO_ROOT}`);
+  warn("This feature requires maestro >= 1.12.0 — run `npm run upgrade` then retry.");
+  process.exit(1);
+}
+
+// ── Place the disabled config file (idempotent)
+const cfgDir = join(AGENT_DIR, "config");
+mkdirSync(cfgDir, { recursive: true });
+
+const activePath = join(cfgDir, "model-routing.yaml");
+const disabledPath = join(cfgDir, "model-routing.yaml.disabled");
+
+if (existsSync(activePath)) {
+  // Active config already in place — try to parse + validate.
+  try {
+    const { loadRoutingConfig, listBackends } = await import(
+      pathToFileUrl(join(MAESTRO_ROOT, "lib/model-router.mjs"))
+    );
+    const cfg = loadRoutingConfig(AGENT_DIR);
+    if (!cfg) {
+      warn("config/model-routing.yaml exists but loader returned null");
+    } else {
+      const names = Object.keys(cfg.backends);
+      ok(`model-routing.yaml is active with backends: ${names.join(", ")}`);
+      reportMissingEnv(cfg);
+    }
+  } catch (err) {
+    warn(`failed to load existing model-routing.yaml: ${err.message}`);
+  }
+} else if (existsSync(disabledPath)) {
+  info("model-routing.yaml.disabled is present; rename to model-routing.yaml to activate.");
+} else {
+  copyFileSync(exampleSrc, disabledPath);
+  ok("placed scaffold/model-routing.yaml.example at config/model-routing.yaml.disabled");
+  info("Activate by:");
+  info("  1. Edit config/model-routing.yaml.disabled to remove unused backends.");
+  info("  2. Add MOONSHOT_API_KEY / OPENROUTER_API_KEY to .env as needed.");
+  info("  3. Rename → config/model-routing.yaml");
+  info("  4. Restart the daemon: launchctl unload + load the .plist");
+}
+
+// ── Patch .env.example with placeholder env var lines (idempotent)
+const envExamplePath = join(AGENT_DIR, ".env.example");
+if (existsSync(envExamplePath)) {
+  let envBody = readFileSync(envExamplePath, "utf-8");
+  let changed = false;
+  for (const [key, comment] of [
+    ["MOONSHOT_API_KEY", "Moonshot AI (Kimi K2.6) — https://platform.moonshot.ai/"],
+    ["OPENROUTER_API_KEY", "OpenRouter (Qwen3-Coder etc.) — https://openrouter.ai/keys"],
+  ]) {
+    if (!new RegExp(`^${key}=`, "m").test(envBody)) {
+      if (!envBody.endsWith("\n")) envBody += "\n";
+      envBody += `\n# ${comment}\n${key}=\n`;
+      changed = true;
+    }
+  }
+  if (changed) {
+    writeFileSync(envExamplePath, envBody);
+    ok("appended MOONSHOT_API_KEY / OPENROUTER_API_KEY placeholders to .env.example");
+  } else {
+    info(".env.example already has router env-var placeholders");
+  }
+}
+
+ok("done");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function reportMissingEnv(cfg) {
+  for (const [name, b] of Object.entries(cfg.backends || {})) {
+    if (!b.auth_env) continue;
+    if (!process.env[b.auth_env]) {
+      warn(`backend "${name}" needs ${b.auth_env} but it's not set in your env`);
+    }
+  }
+}
+
+function pathToFileUrl(p) {
+  // Cross-platform absolute-path → file:// URL for dynamic import.
+  if (p.startsWith("/")) return "file://" + p;
+  return "file:///" + p.replace(/\\/g, "/");
+}

package/scripts/setup/init-rag.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * init-rag.mjs — Bootstrap the local RAG index.
+ *
+ * (1) Auto-discovers candidate repos under ~/ and writes them to
+ *     config/repo-registry.yaml. By default this is *not* auto-run because
+ *     repo selection needs operator judgement; pass --yes to take all
+ *     discovered candidates.
+ * (2) Installs ai.maestro.<firstname>-rag-reindex.plist so the FTS5 index
+ *     refreshes hourly.
+ * (3) Optionally runs the initial index build (--build).
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+import { installPlist, bootInLaunchd } from "./lib/install-plist.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-rag]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-rag]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-rag]  · ${m}\n`);
+
+const args = new Set(process.argv.slice(2));
+const autoYes = args.has("--yes") || args.has("-y");
+const skipPlists = args.has("--skip-plists");
+const skipBoot = args.has("--skip-boot");
+const runBuild = args.has("--build");
+
+function loadFirstname() {
+  const agentJsonPath = join(AGENT_DIR, "config/agent.json");
+  if (existsSync(agentJsonPath)) {
+    try {
+      const j = JSON.parse(readFileSync(agentJsonPath, "utf-8"));
+      const n = j.firstName || j.fullName?.split(/\s+/)[0] || "";
+      return n.toLowerCase().replace(/[^a-z0-9]/g, "");
+    } catch { /* fall through */ }
+  }
+  return "agent";
+}
+const firstname = loadFirstname();
+
+for (const d of ["state/rag", "state/rag/index", "scripts/rag"]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Discover candidate repos under $HOME.
+function discoverRepos() {
+  const home = homedir();
+  const candidates = [];
+  for (const name of readdirSync(home)) {
+    if (name.startsWith(".") || name === "ravi-ai" || name === "Library" || name === "Applications") continue;
+    const full = join(home, name);
+    try {
+      const st = statSync(full);
+      if (!st.isDirectory()) continue;
+      // Heuristic: looks like a code repo (.git or package.json or pyproject.toml).
+      const isRepo =
+        existsSync(join(full, ".git")) ||
+        existsSync(join(full, "package.json")) ||
+        existsSync(join(full, "pyproject.toml")) ||
+        existsSync(join(full, "go.mod")) ||
+        existsSync(join(full, "Cargo.toml"));
+      if (isRepo) {
+        candidates.push({ name, path: full });
+      }
+    } catch { /* ignore */ }
+  }
+  return candidates;
+}
+
+const candidates = discoverRepos();
+ok(`discovered ${candidates.length} candidate repo(s) under ${homedir()}`);
+
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+let registry = { repositories: [] };
+if (existsSync(registryPath)) {
+  // Crude YAML re-read: just check whether `repositories: []` is empty.
+  const body = readFileSync(registryPath, "utf-8");
+  if (/repositories:\s*\[\s*\]/.test(body) || /repositories:\s*$/m.test(body)) {
+    // empty list — overwrite with discovered set if user opted in.
+  } else {
+    ok("config/repo-registry.yaml already populated — leaving as-is");
+    process.exit(0);
+  }
+}
+
+if (!autoYes) {
+  warn("Not running interactively — to populate, run with --yes:");
+  warn("  node scripts/setup/init-rag.mjs --yes");
+  warn("Candidates that would be added:");
+  for (const c of candidates) warn(`  - ${c.name} (${c.path})`);
+  process.exit(0);
+}
+
+// Build the YAML.
+const lines = [
+  "# Source Repository Registry",
+  "# Populated by scripts/setup/init-rag.mjs. Add/remove entries as needed.",
+  "# Format:",
+  "#   - name:    repo-slug",
+  "#     path:    ~/repo-slug",
+  "#     purpose: what this repo contains",
+  "#     index:   true | false  (indexed by state/rag/)",
+  "",
+  "repositories:",
+];
+for (const c of candidates) {
+  lines.push(`  - name: ${c.name}`);
+  lines.push(`    path: ${c.path}`);
+  lines.push(`    purpose: ""`);
+  lines.push(`    index: true`);
+}
+writeFileSync(registryPath, lines.join("\n") + "\n");
+ok(`wrote ${candidates.length} entries to config/repo-registry.yaml`);
+
+// ── Install rag-reindex plist (hourly FTS5 refresh) ────────────────────────
+if (skipPlists) {
+  info("--skip-plists set — leaving ~/Library/LaunchAgents/ untouched");
+} else {
+  const templatePath = join(AGENT_DIR, "scripts/local-triggers/templates/rag-reindex.plist.template");
+  if (!existsSync(templatePath)) {
+    warn(`template not found: ${templatePath} — skipping rag-reindex plist`);
+  } else {
+    try {
+      const { installedPath, changed, label } = installPlist({
+        templatePath,
+        firstname,
+        agentRoot: AGENT_DIR,
+        label: "rag-reindex",
+      });
+      ok(`${changed ? "installed" : "no-op (up-to-date)"} ${label} → ${installedPath}`);
+      if (!skipBoot && changed) {
+        try {
+          bootInLaunchd(installedPath);
+          ok(`booted ${label}`);
+        } catch (err) {
+          warn(`bootstrap failed: ${err.message}`);
+        }
+      }
+    } catch (err) {
+      warn(`failed to install rag-reindex plist: ${err.message}`);
+    }
+  }
+}
+
+// ── Optional initial index build ───────────────────────────────────────────
+if (runBuild) {
+  const indexer = join(AGENT_DIR, "scripts/rag/build-index.mjs");
+  if (existsSync(indexer)) {
+    info("running initial RAG index build (this may take a minute)…");
+    try {
+      execFileSync(process.argv[0], [indexer, "--quiet"], { stdio: "inherit" });
+      ok("initial RAG index built");
+    } catch (err) {
+      warn(`initial index build failed: ${err.message}`);
+      warn("  retry manually: node scripts/rag/build-index.mjs");
+    }
+  } else {
+    warn(`indexer not present at ${indexer}`);
+  }
+}
+
+ok("done");
+info("Next: ensure OPENAI_API_KEY is set in .env (used for text-embedding-3-small).");
+info("Manual reindex any time: node scripts/rag/build-index.mjs");

package/scripts/setup/init-session-router.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * init-session-router.mjs — Opt-in session router enablement.
+ *
+ * Session router enables LRU reuse of long-running Claude sessions for
+ * conversational items (Slack threads, Gmail threads). Requires
+ * SESSION_ROUTER_ENABLED=1 in .env. This init step appends that line if
+ * absent, but is intentionally `auto: false` in the registry so the
+ * operator confirms the decision.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-session-router]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-session-router]  ⚠ ${m}\n`);
+
+const envFile = join(AGENT_DIR, ".env");
+if (!existsSync(envFile)) {
+  warn(".env not present — create it first (copy .env.example).");
+  process.exit(0);
+}
+
+const body = readFileSync(envFile, "utf-8");
+if (/^SESSION_ROUTER_ENABLED=/m.test(body)) {
+  ok("SESSION_ROUTER_ENABLED already configured");
+} else {
+  const updated = body.replace(/\n*$/, "") + `\n\n# Session router (LRU reuse) — disabled by default. Set to 1 to enable.\nSESSION_ROUTER_ENABLED=1\n`;
+  writeFileSync(envFile, updated);
+  ok("appended SESSION_ROUTER_ENABLED=1 to .env");
+}
+
+// Touch the registry dir.
+mkdirSync(join(AGENT_DIR, "state/sessions"), { recursive: true });
+ok("done");

package/scripts/setup/init-slack-socket-mode.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * init-slack-socket-mode.mjs — Interactive init for the Slack Socket Mode
+ * feature.
+ *
+ * Called by `maestro init slack-socket-mode --apply`. Walks the operator
+ * through enabling Socket Mode on the Slack app, generating an app-level
+ * token with the `connections:write` scope, and dropping it into .env.
+ * Then ensures the launchd plist exists + loads it.
+ *
+ * Safe to run repeatedly — every step is idempotent and the script never
+ * overwrites an existing token. If the operator already configured the
+ * feature, the script confirms each piece is in place and exits 0.
+ */
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-slack-socket-mode]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-slack-socket-mode]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-slack-socket-mode]    ${m}\n`);
+const fail = (m) => process.stderr.write(`[init-slack-socket-mode]  ✗ ${m}\n`);
+
+// ---------------------------------------------------------------------------
+// Step 1 — Print the Slack admin walkthrough
+// ---------------------------------------------------------------------------
+
+function printWalkthrough() {
+  process.stdout.write(`
+================================================================================
+Slack Socket Mode Setup — 3 steps in the Slack admin UI
+================================================================================
+
+This feature gives the agent a persistent WebSocket to Slack so DMs and
+@mentions arrive in real time instead of being polled every 60 seconds.
+You need a Slack app with Socket Mode enabled and an app-level token.
+
+Step 1 — Create or open the agent's Slack app
+   Open https://api.slack.com/apps
+   If you already have an app for this agent's bot, click into it.
+   Otherwise: "Create New App" → "From scratch" → pick a workspace.
+
+Step 2 — Enable Socket Mode + Event Subscriptions
+   In the left sidebar:
+     a. "Socket Mode" → toggle ON
+        When prompted, generate an App-Level Token. Give it a name
+        (e.g. "maestro-socket") and add the connections:write scope.
+        Copy the token (xapp-1-…) somewhere safe — you'll paste it
+        below in step 3.
+     b. "Event Subscriptions" → toggle ON
+        Subscribe to BOT events:
+          - message.channels
+          - message.groups
+          - message.im
+          - message.mpim
+          - app_mention
+        Reinstall the app to your workspace when prompted.
+
+Step 3 — Add the app-level token to .env
+   Paste it on the prompt below, or skip and add it manually as:
+     SLACK_APP_LEVEL_TOKEN=xapp-1-…
+   in ${join(AGENT_DIR, ".env")}.
+
+================================================================================
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — Check .env for SLACK_APP_LEVEL_TOKEN and offer to add it
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `.env` into a plain object. Best-effort — no fancy quoting. Used
+ * only to detect whether the token line is present.
+ */
+function readEnv(envPath) {
+  if (!existsSync(envPath)) return {};
+  const map = {};
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) map[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return map;
+}
+
+/**
+ * Append a single `KEY=VALUE` line to .env. Does NOT rewrite existing keys
+ * — the operator should hand-edit if they need to change a value.
+ */
+function appendEnvLine(envPath, key, value) {
+  if (!existsSync(envPath)) {
+    writeFileSync(envPath, `${key}=${value}\n`);
+    return;
+  }
+  const body = readFileSync(envPath, "utf-8");
+  const suffix = body.endsWith("\n") ? "" : "\n";
+  appendFileSync(envPath, `${suffix}${key}=${value}\n`);
+}
+
+async function promptForToken() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Paste your SLACK_APP_LEVEL_TOKEN (xapp-1-…), or press ENTER to skip: ");
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function ensureTokenInEnv() {
+  const envPath = join(AGENT_DIR, ".env");
+  const env = readEnv(envPath);
+  const existing = env.SLACK_APP_LEVEL_TOKEN || "";
+  if (existing.startsWith("xapp-")) {
+    ok("SLACK_APP_LEVEL_TOKEN already set in .env");
+    return true;
+  }
+
+  // Skip the prompt when running in a non-interactive environment (CI,
+  // upgrade in --apply mode, etc). The operator can re-run interactively
+  // later or hand-edit .env.
+  if (!process.stdin.isTTY) {
+    warn("SLACK_APP_LEVEL_TOKEN missing and stdin is non-interactive — skipping prompt.");
+    info(`Add the token manually to ${envPath}:`);
+    info("  SLACK_APP_LEVEL_TOKEN=xapp-1-…");
+    return false;
+  }
+
+  const token = await promptForToken();
+  if (!token) {
+    warn("No token provided — skipping. Add it manually before launchd-loading the plist.");
+    info(`  echo 'SLACK_APP_LEVEL_TOKEN=xapp-1-…' >> ${envPath}`);
+    return false;
+  }
+  if (!token.startsWith("xapp-")) {
+    fail(`Token must start with 'xapp-' — got '${token.slice(0, 8)}…'. Skipping.`);
+    return false;
+  }
+  appendEnvLine(envPath, "SLACK_APP_LEVEL_TOKEN", token);
+  ok(`SLACK_APP_LEVEL_TOKEN appended to ${envPath}`);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — Ensure the launchd plist exists, then load it
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the agent's launchd label prefix from config/agent.json or fall
+ * back to the directory name. Mirrors the resolution in
+ * scripts/local-triggers/generate-plists.sh.
+ */
+function resolveAgentFirstName() {
+  try {
+    const a = JSON.parse(readFileSync(join(AGENT_DIR, "config/agent.json"), "utf-8"));
+    if (a.firstName && typeof a.firstName === "string") {
+      return a.firstName.toLowerCase();
+    }
+  } catch { /* try fallback */ }
+  return AGENT_DIR.split("/").pop().replace(/-ai$/, "").toLowerCase();
+}
+
+function regenPlistsIfNeeded(firstName) {
+  const plistDir = join(AGENT_DIR, "scripts/local-triggers/plists");
+  const expected = join(plistDir, `ai.maestro.${firstName}-slack-socket.plist`);
+  if (existsSync(expected)) {
+    ok(`plist already generated: ${expected}`);
+    return expected;
+  }
+  // Run the generator. It's idempotent and lives in the agent repo.
+  const generator = join(AGENT_DIR, "scripts/local-triggers/generate-plists.sh");
+  if (!existsSync(generator)) {
+    warn(`generator missing at ${generator} — cannot create plist`);
+    return null;
+  }
+  info(`generating plists via ${generator}`);
+  const r = spawnSync("/bin/bash", [generator], { cwd: AGENT_DIR, encoding: "utf-8" });
+  if (r.status !== 0) {
+    fail(`generator failed (exit ${r.status}): ${(r.stderr || "").trim()}`);
+    return null;
+  }
+  if (existsSync(expected)) {
+    ok(`plist generated: ${expected}`);
+    return expected;
+  }
+  warn(`generator ran but ${expected} not found. Re-check generate-plists.sh.`);
+  return null;
+}
+
+/**
+ * Copy the generated plist into ~/Library/LaunchAgents/ and launchctl-load
+ * it. Idempotent: if already loaded, unload-then-load to pick up changes.
+ */
+function loadPlist(plistPath, label) {
+  const home = process.env.HOME || "";
+  if (!home) {
+    warn("HOME not set — cannot install plist");
+    return false;
+  }
+  const installedDir = join(home, "Library/LaunchAgents");
+  mkdirSync(installedDir, { recursive: true });
+  const installed = join(installedDir, `${label}.plist`);
+
+  // Copy (preserve atomicity by writing-then-renaming).
+  try {
+    const body = readFileSync(plistPath, "utf-8");
+    writeFileSync(installed + ".tmp", body);
+    // Use rename to make the install atomic.
+    spawnSync("/bin/mv", [installed + ".tmp", installed], { encoding: "utf-8" });
+    ok(`copied to ${installed}`);
+  } catch (err) {
+    fail(`could not install plist: ${err.message}`);
+    return false;
+  }
+
+  // Unload any existing instance, then load the fresh one.
+  spawnSync("launchctl", ["unload", installed], { encoding: "utf-8" });
+  const loadRes = spawnSync("launchctl", ["load", installed], { encoding: "utf-8" });
+  if (loadRes.status !== 0) {
+    warn(`launchctl load returned ${loadRes.status}: ${(loadRes.stderr || "").trim()}`);
+    info("You can retry manually: launchctl load " + installed);
+    return false;
+  }
+  ok(`launchctl loaded ${label}`);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  printWalkthrough();
+  const tokenOk = await ensureTokenInEnv();
+
+  const firstName = resolveAgentFirstName();
+  const label = `ai.maestro.${firstName}-slack-socket`;
+  const plistPath = regenPlistsIfNeeded(firstName);
+
+  if (plistPath && tokenOk) {
+    loadPlist(plistPath, label);
+  } else if (plistPath && !tokenOk) {
+    info("Skipping launchctl load — add SLACK_APP_LEVEL_TOKEN to .env first, then run:");
+    info(`  launchctl load ~/Library/LaunchAgents/${label}.plist`);
+  }
+
+  ok("init-slack-socket-mode complete");
+  info("Verify with: maestro doctor   (checks token + plist + recent connect log)");
+}
+
+main().catch((err) => {
+  fail(`unexpected error: ${err.message}`);
+  process.stderr.write(`${err.stack}\n`);
+  process.exit(1);
+});