@cohortapp/agent-sdk 2.3.0

package/lib/setup/runner.mjs

@@ -0,0 +1,244 @@
+/**
+ * lib/setup/runner.mjs — the `maestro setup` orchestrator.
+ *
+ * Globs `lib/setup/sections/*.mjs`, sorts by `order`, and runs the
+ * detect → (skip if complete & not forced) → prompt → apply → verify →
+ * checkpoint loop. The on-disk SoT is authoritative; the checkpoint
+ * (state/setup/progress.json) is a resume hint.
+ *
+ * SetupSection contract (design §3.3) — the seam WS2/3/4 register against by
+ * dropping a file into sections/ (no core edit):
+ *
+ *   @typedef {Object} SetupSection
+ *    @property {string}  id
+ *    @property {string}  label
+ *    @property {number}  order                 // gaps of 10 so others insert
+ *    @property {(ctx)=>boolean|'partial'} [enabledFor]
+ *    @property {(ctx)=>Promise<{status:'unconfigured'|'partial'|'complete',summary?,missing?}>} detect
+ *    @property {(ctx)=>Promise<void>} prompt    // only this touches the TTY; honors headless
+ *    @property {(ctx)=>Promise<void>} apply     // writes SoT + runs generators; idempotent
+ *    @property {(ctx)=>Promise<{ok,checks:Array<{name,ok,remedy?}>}>} verify
+ *
+ * The ctx passed to every hook:
+ *   { agentRoot, maestroRoot, flags, answers, io, sections, enrichSpawn? }
+ *
+ * Flags (parsed with node:util parseArgs): --resume --from <id> --only <ids>
+ *   --status --headless --answers <file> --no-enrich --dry-run --verbose.
+ *
+ * @module lib/setup/runner
+ */
+
+"use strict";
+
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import * as io from "./io.mjs";
+import { markSection, hashAnswers, mergeAnswers } from "./state.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SECTIONS_DIR = join(HERE, "sections");
+const DEFAULT_MAESTRO_ROOT = join(HERE, "..", "..");
+
+/** parseArgs spec for `maestro setup`. */
+export const FLAG_SPEC = {
+  resume: { type: "boolean", default: false },
+  from: { type: "string" },
+  only: { type: "string" },
+  status: { type: "boolean", default: false },
+  headless: { type: "boolean", default: false },
+  answers: { type: "string" },
+  "no-enrich": { type: "boolean", default: false },
+  "dry-run": { type: "boolean", default: false },
+  verbose: { type: "boolean", default: false },
+  help: { type: "boolean", default: false },
+};
+
+/**
+ * Parse argv (without node/script) into a normalized flags object + a positional
+ * section id (the optional `[section]` argument).
+ * @param {string[]} argv
+ */
+export function parseFlags(argv = []) {
+  const { values, positionals } = parseArgs({ args: argv, options: FLAG_SPEC, allowPositionals: true, strict: false });
+  return {
+    section: positionals[0] || null,
+    flags: {
+      resume: !!values.resume,
+      from: values.from || null,
+      only: values.only ? String(values.only).split(",").map((s) => s.trim()).filter(Boolean) : null,
+      status: !!values.status,
+      headless: !!values.headless,
+      answersFile: values.answers || null,
+      noEnrich: !!values["no-enrich"],
+      dryRun: !!values["dry-run"],
+      verbose: !!values.verbose,
+      help: !!values.help,
+    },
+  };
+}
+
+/** Dynamically import every section module under sections/, sorted by order. */
+export async function loadSections(dir = SECTIONS_DIR) {
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith(".mjs") && !f.endsWith(".test.mjs")).sort();
+  const sections = [];
+  for (const f of files) {
+    try {
+      const mod = await import(pathToFileURL(join(dir, f)).href);
+      const sec = mod.default || mod.section;
+      if (sec && typeof sec === "object" && sec.id && typeof sec.order === "number") sections.push(sec);
+    } catch (e) {
+      io.note(`[setup] skipping section ${f}: ${e && e.message ? e.message : e}`, { dim: true });
+    }
+  }
+  sections.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+  return sections;
+}
+
+/** Load + merge the answers file (if any) into a flat answers bag. */
+function loadAnswers(flags) {
+  if (!flags.answersFile) return {};
+  if (!existsSync(flags.answersFile)) throw new Error(`--answers file not found: ${flags.answersFile}`);
+  try { return JSON.parse(readFileSync(flags.answersFile, "utf-8")); }
+  catch (e) { throw new Error(`--answers file is not valid JSON: ${e && e.message ? e.message : e}`); }
+}
+
+/** Filter the section list per --from / --only / positional section. */
+function selectSections(sections, sectionArg, flags) {
+  let list = sections;
+  if (flags.only && flags.only.length) {
+    const set = new Set(flags.only);
+    list = sections.filter((s) => set.has(s.id));
+  } else if (sectionArg) {
+    list = sections.filter((s) => s.id === sectionArg);
+  } else if (flags.from) {
+    const fromIdx = sections.findIndex((s) => s.id === flags.from);
+    if (fromIdx >= 0) list = sections.slice(fromIdx);
+  }
+  return list;
+}
+
+/**
+ * Print the status table (--status): each section's detect() outcome.
+ * @param {object} ctx
+ * @param {SetupSection[]} sections
+ */
+export async function printStatus(ctx, sections) {
+  io.note("");
+  io.note(`maestro setup — status (${ctx.agentRoot})`);
+  for (const s of sections) {
+    let d;
+    try { d = await s.detect(ctx); } catch (e) { d = { status: "error", summary: e && e.message ? e.message : String(e) }; }
+    const badge = d.status === "complete" ? "✓ complete  " : d.status === "partial" ? "~ partial   " : d.status === "error" ? "! error     " : "· todo      ";
+    const detail = d.summary ? d.summary : d.missing ? `missing: ${(d.missing || []).join(", ")}` : "";
+    io.note(`  [${badge}] ${String(s.order).padStart(2, " ")} ${s.id.padEnd(18)} ${detail}`);
+  }
+}
+
+/**
+ * Run the wizard.
+ * @param {object} [opts]
+ * @param {string} [opts.agentRoot=process.cwd()]
+ * @param {string} [opts.maestroRoot]
+ * @param {string[]} [opts.argv]                CLI args (without node/script)
+ * @param {object} [opts.flags]                 pre-parsed flags (overrides argv)
+ * @param {string} [opts.section]               positional section
+ * @param {object} [opts.answers]               extra answers (merged over file)
+ * @param {Function} [opts.enrichSpawn]         injectable enrich spawn (tests)
+ * @param {SetupSection[]} [opts.sections]      inject sections (tests)
+ * @returns {Promise<{ok:boolean, ran:string[], skipped:string[], verify?:object}>}
+ */
+export async function runSetup(opts = {}) {
+  const agentRoot = opts.agentRoot || process.cwd();
+  const maestroRoot = opts.maestroRoot || DEFAULT_MAESTRO_ROOT;
+  const parsed = opts.flags ? { flags: opts.flags, section: opts.section || null } : parseFlags(opts.argv || []);
+  const flags = parsed.flags;
+  const sectionArg = opts.section || parsed.section;
+
+  const fileAnswers = loadAnswers(flags);
+  const answers = { ...fileAnswers, ...(opts.answers || {}) };
+
+  const allSections = (opts.sections ? [...opts.sections] : await loadSections())
+    .sort((a, b) => a.order - b.order || String(a.id).localeCompare(String(b.id)));
+  const ctx = { agentRoot, maestroRoot, flags, answers, io, sections: allSections, enrichSpawn: opts.enrichSpawn };
+
+  // --status: print and return.
+  if (flags.status) {
+    await printStatus(ctx, allSections);
+    return { ok: true, ran: [], skipped: allSections.map((s) => s.id), status: true };
+  }
+
+  const targeted = selectSections(allSections, sectionArg, flags);
+
+  const ran = [];
+  const skipped = [];
+  let verifyResult = null;
+
+  for (const section of targeted) {
+    // enabledFor gate (optional).
+    if (typeof section.enabledFor === "function") {
+      try { const en = section.enabledFor(ctx); if (en === false) { skipped.push(section.id); continue; } } catch { /* default-enabled */ }
+    }
+
+    // detect — the on-disk SoT is authoritative.
+    let det;
+    try { det = await section.detect(ctx); } catch (e) { det = { status: "error", summary: e && e.message ? e.message : String(e) }; }
+
+    const forced = !!(flags.only || sectionArg || flags.from);
+    const answersHash = hashAnswers(answers);
+
+    // Skip when the SoT already satisfies this section and we are not forcing a
+    // re-run. detect() (not the checkpoint) is authoritative — the checkpoint is
+    // only a hint. `verify` is never skipped (it has no persisted "done" state).
+    if (det.status === "complete" && !forced && section.id !== "verify") {
+      skipped.push(section.id);
+      if (!flags.dryRun) markSection(agentRoot, section.id, { status: "complete", answersHash });
+      continue;
+    }
+
+    if (flags.dryRun) {
+      io.note(`  [dry-run] ${section.id} (${section.order}) — status: ${det.status}${det.missing ? `, missing: ${(det.missing || []).join(", ")}` : ""}`, { dim: true });
+      ran.push(section.id);
+      continue;
+    }
+
+    // prompt (TTY-only; headless returns pre-supplied answers, never blocks).
+    if (typeof section.prompt === "function") {
+      try { await section.prompt(ctx); } catch (e) {
+        io.note(`[setup] ${section.id} prompt error: ${e && e.message ? e.message : e}`, { dim: true });
+      }
+    }
+    // Persist the answers bag (durable across sections / resumes).
+    mergeAnswers(agentRoot, answers);
+
+    // apply — writes SoT + runs generators. A throw here is fatal (the operating
+    // model must be coherent); record the failure on the checkpoint first.
+    try {
+      if (typeof section.apply === "function") await section.apply(ctx);
+    } catch (e) {
+      markSection(agentRoot, section.id, { status: "failed", answersHash, verify: { ok: false, error: e && e.message ? e.message : String(e) } });
+      throw new Error(`setup section "${section.id}" failed in apply(): ${e && e.message ? e.message : e}`);
+    }
+
+    // verify.
+    let ver = { ok: true, checks: [] };
+    try { if (typeof section.verify === "function") ver = await section.verify(ctx); }
+    catch (e) { ver = { ok: false, checks: [{ name: `${section.id} verify`, ok: false, remedy: e && e.message ? e.message : String(e) }] }; }
+
+    if (section.id === "verify") {
+      verifyResult = ver;
+      // Always render the capability table — it's the operator's at-a-glance
+      // report and is plain text (harmless in scripted/headless runs too).
+      if (typeof section.renderTable === "function") section.renderTable(ver);
+    }
+
+    markSection(agentRoot, section.id, { status: ver.ok ? "complete" : "partial", answersHash, verify: { ok: ver.ok } });
+    ran.push(section.id);
+  }
+
+  return { ok: verifyResult ? !!verifyResult.ok : true, ran, skipped, verify: verifyResult };
+}
+
+export { SECTIONS_DIR, DEFAULT_MAESTRO_ROOT };

package/lib/setup/runner.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * runner.test.mjs — section ordering, flag parsing, skip-complete, dry-run.
+ * Uses injected fake sections so it stays fast + deterministic.
+ * Run: `node --test lib/setup/runner.test.mjs`
+ * @module lib/setup/runner.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseFlags, loadSections, runSetup } from "./runner.mjs";
+import { loadProgress, progressPath } from "./state.mjs";
+
+function tmpRoot() { return mkdtempSync(join(tmpdir(), "maestro-runner-")); }
+
+test("parseFlags parses --only, --from, --headless, --dry-run", () => {
+  const a = parseFlags(["--only", "identity,company", "--headless"]);
+  assert.deepEqual(a.flags.only, ["identity", "company"]);
+  assert.equal(a.flags.headless, true);
+  const b = parseFlags(["company", "--from", "model", "--dry-run", "--no-enrich"]);
+  assert.equal(b.section, "company");
+  assert.equal(b.flags.from, "model");
+  assert.equal(b.flags.dryRun, true);
+  assert.equal(b.flags.noEnrich, true);
+});
+
+test("loadSections discovers the real sections sorted by order", async () => {
+  const sections = await loadSections();
+  const ids = sections.map((s) => s.id);
+  // core WS1 sections present and ordered
+  assert.ok(ids.includes("identity"));
+  assert.ok(ids.includes("operating-model"));
+  assert.ok(ids.includes("verify"));
+  const orders = sections.map((s) => s.order);
+  assert.deepEqual(orders, [...orders].sort((x, y) => x - y), "sections sorted by order");
+  // identity precedes operating-model precedes verify
+  assert.ok(ids.indexOf("identity") < ids.indexOf("operating-model"));
+  assert.ok(ids.indexOf("operating-model") < ids.indexOf("verify"));
+});
+
+function fakeSection(id, order, opts = {}) {
+  return {
+    id, order,
+    label: id,
+    applied: 0,
+    async detect() { return { status: opts.complete ? "complete" : "unconfigured" }; },
+    async prompt(ctx) { ctx[`prompted_${id}`] = true; },
+    async apply(ctx) { ctx[`applied_${id}`] = (ctx[`applied_${id}`] || 0) + 1; },
+    async verify() { return { ok: opts.verifyOk !== false, checks: [{ name: id, ok: opts.verifyOk !== false }] }; },
+  };
+}
+
+test("runSetup runs sections in order and records checkpoint", async () => {
+  const root = tmpRoot();
+  const order = [];
+  const mk = (id, o) => ({
+    id, order: o, label: id,
+    async detect() { return { status: "unconfigured" }; },
+    async prompt() {},
+    async apply() { order.push(id); },
+    async verify() { return { ok: true, checks: [] }; },
+  });
+  const sections = [mk("b", 20), mk("a", 10), mk("c", 30)];
+  const res = await runSetup({ agentRoot: root, sections, flags: baseFlags() });
+  assert.deepEqual(order, ["a", "b", "c"], "executed in ascending order");
+  assert.deepEqual(res.ran, ["a", "b", "c"]);
+  const p = loadProgress(root);
+  assert.equal(p.sections.a.status, "complete");
+});
+
+test("runSetup skips already-complete sections (resume default)", async () => {
+  const root = tmpRoot();
+  const applied = [];
+  const mk = (id, o, complete) => ({
+    id, order: o, label: id,
+    async detect() { return { status: complete ? "complete" : "unconfigured" }; },
+    async prompt() {},
+    async apply() { applied.push(id); },
+    async verify() { return { ok: true, checks: [] }; },
+  });
+  const sections = [mk("a", 10, true), mk("b", 20, false)];
+  const res = await runSetup({ agentRoot: root, sections, flags: baseFlags() });
+  assert.deepEqual(applied, ["b"], "complete section a was skipped");
+  assert.ok(res.skipped.includes("a"));
+});
+
+test("runSetup --dry-run writes nothing", async () => {
+  const root = tmpRoot();
+  const sections = [fakeSection("x", 10), fakeSection("y", 20)];
+  const res = await runSetup({ agentRoot: root, sections, flags: { ...baseFlags(), dryRun: true } });
+  assert.equal(existsSync(progressPath(root)), false, "no progress.json on dry-run");
+  // nothing under the temp root was created
+  assert.equal(readdirSync(root).length, 0, "dry-run created no files");
+  assert.deepEqual(res.ran, ["x", "y"]);
+});
+
+test("runSetup --only restricts and forces the named sections", async () => {
+  const root = tmpRoot();
+  const applied = [];
+  const mk = (id, o) => ({
+    id, order: o, label: id,
+    async detect() { return { status: "complete" }; }, // would normally skip
+    async prompt() {},
+    async apply() { applied.push(id); },
+    async verify() { return { ok: true, checks: [] }; },
+  });
+  const sections = [mk("a", 10), mk("b", 20), mk("c", 30)];
+  await runSetup({ agentRoot: root, sections, flags: { ...baseFlags(), only: ["b"] } });
+  assert.deepEqual(applied, ["b"], "only b runs, and forced despite complete detect");
+});
+
+test("runSetup --status returns without applying", async () => {
+  const root = tmpRoot();
+  const applied = [];
+  const sections = [{
+    id: "a", order: 10, label: "a",
+    async detect() { return { status: "partial", summary: "x" }; },
+    async prompt() {}, async apply() { applied.push("a"); },
+    async verify() { return { ok: true, checks: [] }; },
+  }];
+  const res = await runSetup({ agentRoot: root, sections, flags: { ...baseFlags(), status: true } });
+  assert.equal(res.status, true);
+  assert.deepEqual(applied, [], "status mode applies nothing");
+});
+
+function baseFlags() {
+  return { resume: false, from: null, only: null, status: false, headless: true, answersFile: null, noEnrich: false, dryRun: false, verbose: false, help: false };
+}

package/lib/setup/sections/comms.mjs

@@ -0,0 +1,173 @@
+/**
+ * sections/comms.mjs — messaging channels (WS2, order 45).
+ *
+ * Replaces the WS1 stub. This section is the cross-workstream seam for
+ * channels (design §3.2): it wires each selected channel by running its
+ * idempotent `init-*` script and then runs a verify-inbound probe — a
+ * generalised form of the Slack doctor "did the listener connect / did an
+ * inbox item appear" check.
+ *
+ * Order 45 (between core comms placeholder 40 and tools 50) so it runs after
+ * identity/company/model but before tools, per design §3.2.
+ *
+ * Registered via the file-drop section interface (runner.mjs globs sections/).
+ * Every hook is non-blocking under --headless: detect/apply/verify never read
+ * the TTY; prompt honours `io` headless resolution.
+ *
+ * @module lib/setup/sections/comms
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, statSync, readdirSync } from "node:fs";
+import * as io from "../io.mjs";
+import { runGenerator } from "../run-generator.mjs";
+
+/** Channel → signals that indicate it is configured, its init script, and probe. */
+const CHANNELS = {
+  slack: {
+    label: "Slack",
+    env: ["SLACK_USER_TOKEN", "SLACK_BOT_TOKEN", "SLACK_APP_LEVEL_TOKEN"],
+    init: "init-slack-socket-mode.mjs",
+    probe: { kind: "log", file: "logs/polling", suffix: "-slack-socket.jsonl", markers: ["hello — connected to Slack Socket Mode", "inbox-item-written", "starting Socket Mode listener"] },
+  },
+  gmail: { label: "Email (Gmail)", env: ["GMAIL_APP_PASSWORD"], probe: { kind: "inbox", service: "gmail" } },
+  sms: { label: "SMS", env: ["TWILIO_ACCOUNT_SID"], probe: { kind: "inbox", service: "sms" } },
+  whatsapp: { label: "WhatsApp", gate: ["config/whatsapp.yaml"], init: "init-whatsapp-baileys.mjs", probe: { kind: "inbox", service: "whatsapp" } },
+  telegram: { label: "Telegram", gate: ["config/telegram.yaml"], init: "init-telegram.mjs", probe: { kind: "inbox", service: "telegram" } },
+  voice: { label: "Voice / phone", gate: ["config/voice.yaml"], probe: { kind: "inbox", service: "voice" } },
+};
+
+function readEnv(agentRoot) {
+  const p = join(agentRoot, ".env");
+  return existsSync(p) ? readFileSync(p, "utf-8") : "";
+}
+
+/** Which channels look configured right now (env key set OR gate file present). */
+export function detectConfiguredChannels(agentRoot) {
+  const env = readEnv(agentRoot);
+  const configured = [];
+  for (const [name, sig] of Object.entries(CHANNELS)) {
+    const envHit = (sig.env || []).some((k) => new RegExp(`^${k}=.+`, "m").test(env));
+    const gateHit = (sig.gate || []).some((f) => existsSync(join(agentRoot, f)));
+    if (envHit || gateHit) configured.push(name);
+  }
+  return configured;
+}
+
+/**
+ * Verify-inbound probe for one channel. Generalises the Slack doctor probe:
+ *   - "log"  : a recent connect/inbox marker in a JSONL log file (last 60 min).
+ *   - "inbox": at least one item file present under state/inbox/<service>/.
+ * Returns { ok, detail }. Probes never block — they read the filesystem only.
+ *
+ * @param {string} agentRoot
+ * @param {object} probe
+ * @param {number} [windowMs]
+ */
+export function probeInbound(agentRoot, probe, windowMs = 60 * 60_000) {
+  if (!probe) return { ok: true, detail: "no probe configured" };
+  if (probe.kind === "inbox") {
+    const dir = join(agentRoot, "state/inbox", probe.service);
+    if (!existsSync(dir)) return { ok: false, detail: `no items in state/inbox/${probe.service}/ yet` };
+    let count = 0;
+    try { count = readdirSync(dir).filter((f) => f.endsWith(".yaml") || f.endsWith(".json") || f.includes(".processed")).length; } catch { /* */ }
+    return count > 0
+      ? { ok: true, detail: `${count} item(s) seen in state/inbox/${probe.service}/` }
+      : { ok: false, detail: `no items in state/inbox/${probe.service}/ yet` };
+  }
+  if (probe.kind === "log") {
+    const today = new Date().toISOString().slice(0, 10);
+    const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+    for (const day of [today, yesterday]) {
+      const logPath = join(agentRoot, probe.file, `${day}${probe.suffix}`);
+      if (!existsSync(logPath)) continue;
+      try {
+        const stat = statSync(logPath);
+        const buf = readFileSync(logPath, "utf-8");
+        void stat;
+        for (const line of buf.split("\n").reverse()) {
+          if (!line) continue;
+          try {
+            const entry = JSON.parse(line);
+            if (probe.markers.some((m) => entry.message === m)) {
+              const ageMs = Date.now() - new Date(entry.ts).getTime();
+              if (ageMs >= 0 && ageMs < windowMs) return { ok: true, detail: `listener active ${Math.round(ageMs / 60000)}m ago` };
+              return { ok: false, detail: `last connect ${Math.round(ageMs / 60000)}m ago — may be stalled` };
+            }
+          } catch { /* skip */ }
+        }
+      } catch { /* unreadable */ }
+    }
+    return { ok: false, detail: "listener has not produced a connect log yet" };
+  }
+  return { ok: true, detail: "" };
+}
+
+/** Resolve which channels to wire: explicit answers, else currently-configured. */
+function selectedChannels(ctx) {
+  const ans = (ctx.answers && (ctx.answers.channels || ctx.answers.comms)) || null;
+  if (Array.isArray(ans) && ans.length) return ans.filter((c) => CHANNELS[c]);
+  // Fall back to whatever already looks configured (resume / non-interactive).
+  return detectConfiguredChannels(ctx.agentRoot);
+}
+
+export default {
+  id: "comms",
+  label: "Messaging channels",
+  order: 45,
+
+  async detect(ctx) {
+    const configured = detectConfiguredChannels(ctx.agentRoot);
+    if (configured.length === 0) return { status: "unconfigured", missing: ["no channels configured"] };
+    // "complete" iff every configured channel passes its inbound probe; else partial.
+    const failing = configured.filter((c) => !probeInbound(ctx.agentRoot, CHANNELS[c]?.probe).ok);
+    if (failing.length === 0) return { status: "complete", summary: `wired: ${configured.join(", ")}` };
+    return { status: "partial", summary: `configured: ${configured.join(", ")}`, missing: failing.map((c) => `${c} (no inbound yet)`) };
+  },
+
+  async prompt(ctx) {
+    const configured = detectConfiguredChannels(ctx.agentRoot);
+    io.note(`Messaging channels detected: ${configured.length ? configured.join(", ") : "none yet"}.`, { dim: true });
+    // Offer a multiselect of channels to wire (defaults to currently-configured).
+    const chosen = await io.multiselect(ctx, {
+      message: "Channels to wire now (runs each channel's init script)",
+      key: "channels",
+      choices: Object.entries(CHANNELS).map(([value, c]) => ({ value, label: c.label })),
+      default: configured,
+    });
+    ctx.answers.channels = Array.isArray(chosen) && chosen.length ? chosen : configured;
+  },
+
+  async apply(ctx) {
+    const channels = selectedChannels(ctx);
+    for (const name of channels) {
+      const spec = CHANNELS[name];
+      if (!spec || !spec.init) continue; // gmail/sms/voice configured elsewhere
+      const r = runGenerator(spec.init, ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+      if (!r.ok) {
+        // Non-fatal: a channel's interactive init may need a TTY/token. Surface
+        // it but don't abort the whole operating-model apply.
+        io.note(`[comms] ${name} init reported: ${(r.stderr || r.stdout || "").trim().slice(0, 200)}`, { dim: true });
+      }
+    }
+  },
+
+  async verify(ctx) {
+    const configured = detectConfiguredChannels(ctx.agentRoot);
+    const checks = configured.map((name) => {
+      const res = probeInbound(ctx.agentRoot, CHANNELS[name]?.probe);
+      return {
+        name: `${CHANNELS[name]?.label || name} inbound`,
+        ok: res.ok,
+        remedy: res.ok ? undefined : `${res.detail}${CHANNELS[name]?.init ? ` — run node scripts/setup/${CHANNELS[name].init}` : ""}`,
+      };
+    });
+    if (checks.length === 0) checks.push({ name: "messaging channels (0 configured)", ok: true });
+    // Channels are optional → a not-yet-connected channel WARNs (remedy shown)
+    // but does not hard-fail setup. ok reflects whether configured channels are
+    // live; the runner records partial when not.
+    return { ok: checks.every((c) => c.ok), checks };
+  },
+};

package/lib/setup/sections/company.mjs

@@ -0,0 +1,120 @@
+/**
+ * sections/company.mjs — company interview → config/company.json, gather the
+ * deterministic context pack, render docs/company/overview.md.  (order 20)
+ *
+ * @module lib/setup/sections/company
+ */
+
+"use strict";
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import * as io from "../io.mjs";
+import { gatherContextPack } from "../context-pack.mjs";
+import { runGenerator } from "../run-generator.mjs";
+
+function readCompany(agentRoot) {
+  const p = join(agentRoot, "config", "company.json");
+  try { return existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : {}; } catch { return {}; }
+}
+
+function writeCompany(agentRoot, obj) {
+  const p = join(agentRoot, "config", "company.json");
+  mkdirSync(join(agentRoot, "config"), { recursive: true });
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf-8");
+  renameSync(tmp, p);
+}
+
+function isUnset(v) { return v === undefined || v === null || v === "" || v === "UNCONFIGURED"; }
+
+export default {
+  id: "company",
+  label: "Company context",
+  order: 20,
+
+  async detect(ctx) {
+    const c = readCompany(ctx.agentRoot);
+    if (isUnset(c.name)) return { status: "unconfigured", missing: ["company.name"] };
+    const missing = [];
+    if (isUnset(c.website) && isUnset(c.domain)) missing.push("company.website");
+    if (missing.length === 0) return { status: "complete", summary: `${c.name}${c.website ? ` (${c.website})` : ""}` };
+    return { status: "partial", missing };
+  },
+
+  async prompt(ctx) {
+    const cur = readCompany(ctx.agentRoot);
+    const name = await io.text(ctx, { message: "Company name", key: "companyName", default: isUnset(cur.name) ? "" : cur.name });
+    const website = await io.text(ctx, { message: "Company website", key: "companyWebsite", default: cur.website || "" });
+    const domain = await io.text(ctx, { message: "Email/domain (e.g. acme.com)", key: "companyDomain", default: cur.domain || deriveDomain(website) });
+    const industry = await io.text(ctx, { message: "Industry", key: "companyIndustry", default: cur.industry || "" });
+    const stage = await io.text(ctx, { message: "Stage (e.g. Series A, public)", key: "companyStage", default: cur.stage || "" });
+    const tagline = await io.text(ctx, { message: "One-line tagline (optional)", key: "companyTagline", default: cur.tagline || "" });
+    ctx.answers.company = { name, website, domain, industry, stage, tagline };
+  },
+
+  async apply(ctx) {
+    const a = (ctx.answers && ctx.answers.company) || pull(ctx);
+    const cur = readCompany(ctx.agentRoot);
+    const merged = { ...cur };
+    if (a) {
+      if (a.name) merged.name = a.name;
+      if (a.website) merged.website = a.website;
+      if (a.domain) merged.domain = a.domain;
+      if (a.industry) merged.industry = a.industry;
+      if (a.stage) merged.stage = a.stage;
+      if (a.tagline) merged.tagline = a.tagline;
+    }
+    // Keep arrays present (scaffold ships them) — never drop.
+    for (const k of ["locations", "jurisdictions", "products", "competitors", "strategicPriorities", "keyPeople", "contextDocs", "repos"]) {
+      if (!Array.isArray(merged[k])) merged[k] = [];
+    }
+    writeCompany(ctx.agentRoot, merged);
+    // Mirror the company name/domain into the agent SoT so {{company.*}} and the
+    // env file stay consistent.
+    try {
+      const aj = join(ctx.agentRoot, "config", "agent.json");
+      if (existsSync(aj)) {
+        const id = JSON.parse(readFileSync(aj, "utf-8"));
+        id.company = merged.name || id.company;
+        id.companyDomain = merged.domain || id.companyDomain;
+        const tmp = `${aj}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(id, null, 2) + "\n", "utf-8");
+        renameSync(tmp, aj);
+      }
+    } catch { /* fail-open */ }
+
+    gatherContextPack(ctx.agentRoot);
+    runGenerator("generate-company.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+    runGenerator("generate-agent-env.mjs", ctx.agentRoot, { maestroRoot: ctx.maestroRoot });
+  },
+
+  async verify(ctx) {
+    const c = readCompany(ctx.agentRoot);
+    const nameOk = !isUnset(c.name);
+    const overviewOk = existsSync(join(ctx.agentRoot, "docs", "company", "overview.md"));
+    return {
+      ok: nameOk && overviewOk,
+      checks: [
+        { name: "company.json populated", ok: nameOk, remedy: nameOk ? undefined : "run `maestro setup --only company`" },
+        { name: "company overview generated", ok: overviewOk, remedy: overviewOk ? undefined : "run generate-company.mjs" },
+      ],
+    };
+  },
+};
+
+function deriveDomain(website) {
+  if (!website) return "";
+  try { return new URL(website.startsWith("http") ? website : `https://${website}`).hostname.replace(/^www\./, ""); }
+  catch { return ""; }
+}
+
+function pull(ctx) {
+  const ans = ctx.answers || {};
+  if (ans.company) return ans.company;
+  const map = { name: "companyName", website: "companyWebsite", domain: "companyDomain", industry: "companyIndustry", stage: "companyStage", tagline: "companyTagline" };
+  const out = {};
+  let any = false;
+  for (const [k, src] of Object.entries(map)) { if (src in ans) { out[k] = ans[src]; any = true; } }
+  return any ? out : null;
+}