@cohortapp/agent-sdk 2.3.0

package/lib/setup/integration.test.mjs

@@ -0,0 +1,162 @@
+/**
+ * integration.test.mjs — end-to-end `maestro setup` acceptance (WS1 done-bar).
+ *
+ * Creates a temp agent repo seeded from scaffold/config, runs the runner in
+ * --headless with a fixture answers file (maestroRoot = the real repo so the
+ * deterministic generators run for real), and asserts:
+ *   1. a GREEN completeness gate after the run,
+ *   2. config/agent.ts is a thin SoT wrapper,
+ *   3. re-running is a no-op (operating-model + identity skipped).
+ *
+ * The `claude --print` enrichment spawn is INJECTED (fake) so the test is
+ * hermetic — no network. Generators that only template from agent.json run real.
+ *
+ * Run: `node --test lib/setup/integration.test.mjs`
+ * @module lib/setup/integration.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runSetup, loadSections } from "./runner.mjs";
+import { assertComplete } from "./completeness.mjs";
+import { isWrapper } from "./sot.mjs";
+import { loadProgress } from "./state.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(HERE, "..", "..");
+
+/** A fixture answers file: everything the headless sections need. */
+const ANSWERS = {
+  firstName: "Jacob", lastName: "Chen", title: "VP, Engineering", email: "jacob@acme.com",
+  function: "technical-leader", altitude: "vp",
+  principalName: "Dana Reyes", principalTitle: "CEO", principalEmail: "dana@acme.com",
+  companyName: "Acme", companyWebsite: "https://acme.com", companyDomain: "acme.com",
+  companyIndustry: "Developer tooling", companyStage: "Series B", companyTagline: "Ship faster",
+  provider: "subscription",
+  channels: ["slack", "gmail"],
+};
+
+/** Fake enrichment spawn — returns valid JSON for whatever keys are requested. */
+function fakeEnrichSpawn(prompt) {
+  // The system prompt lists the keys as JSON; pick a sensible filler per key.
+  const m = prompt.system.match(/ONLY these keys:\s*(\[[^\]]*\])/);
+  let keys = [];
+  try { keys = m ? JSON.parse(m[1]) : []; } catch { keys = []; }
+  const out = {};
+  for (const k of keys) {
+    if (k === "responsibilities" || k === "operatingPrinciples") {
+      out[k] = ["Own platform reliability and delivery confidence", "Keep the engineering org unblocked and accountable"];
+    } else if (k === "persona") {
+      out[k] = "A pragmatic engineering leader who keeps delivery honest and the team focused on outcomes.";
+    } else if (k === "description") {
+      out[k] = "Acme builds developer tooling that helps fintechs ship faster with confidence.";
+    } else {
+      out[k] = "Concrete, company-specific copy that reads like a colleague wrote it.";
+    }
+  }
+  return Promise.resolve(JSON.stringify(out));
+}
+
+function seedAgentRepo() {
+  const root = mkdtempSync(join(tmpdir(), "maestro-int-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  // Seed agent.json from the scaffold (placeholder identity) + agent.ts standalone literal.
+  copyFileSync(join(MAESTRO_ROOT, "scaffold", "config", "agent.json"), join(root, "config", "agent.json"));
+  copyFileSync(join(MAESTRO_ROOT, "scaffold", "config", "agent.ts"), join(root, "config", "agent.ts"));
+  copyFileSync(join(MAESTRO_ROOT, "scaffold", "config", "company.json"), join(root, "config", "company.json"));
+  writeFileSync(join(root, "README.md"), "# Acme agent\nAutonomous engineering leader for Acme.\n");
+  writeFileSync(join(root, ".env"), "");
+  return root;
+}
+
+test("maestro setup --headless produces a green operating model + wrapper, re-run is a no-op", async () => {
+  const root = seedAgentRepo();
+  const sections = await loadSections();
+
+  // First run.
+  const res = await runSetup({
+    agentRoot: root,
+    maestroRoot: MAESTRO_ROOT,
+    sections,
+    flags: { resume: false, from: null, only: null, status: false, headless: true, answersFile: null, noEnrich: false, dryRun: false, verbose: false, help: false },
+    answers: ANSWERS,
+    enrichSpawn: fakeEnrichSpawn,
+  });
+
+  // identity + company + operating-model all ran.
+  assert.ok(res.ran.includes("identity"), "identity ran");
+  assert.ok(res.ran.includes("operating-model"), "operating-model ran");
+
+  // 1. Green completeness gate.
+  const gate = await assertComplete(root);
+  assert.equal(gate.ok, true, "completeness gate green; missing: " + JSON.stringify(gate.missing));
+
+  // 2. agent.ts is the thin wrapper (born unified).
+  assert.ok(isWrapper(readFileSync(join(root, "config", "agent.ts"), "utf-8")), "agent.ts is a SoT wrapper");
+
+  // identity was actually written.
+  const id = JSON.parse(readFileSync(join(root, "config", "agent.json"), "utf-8"));
+  assert.equal(id.firstName, "Jacob");
+  assert.equal(id.function, "technical-leader");
+  assert.equal(id.altitude, "vp");
+  // enriched prose landed.
+  assert.ok(Array.isArray(id.responsibilities) && id.responsibilities.length >= 1, "responsibilities enriched");
+
+  // verify section produced a result and it is ok (no hard failures).
+  assert.ok(res.verify, "verify ran");
+
+  // 3. Re-run is a no-op for the heavy sections.
+  const res2 = await runSetup({
+    agentRoot: root,
+    maestroRoot: MAESTRO_ROOT,
+    sections,
+    flags: { resume: true, from: null, only: null, status: false, headless: true, answersFile: null, noEnrich: false, dryRun: false, verbose: false, help: false },
+    answers: ANSWERS,
+    enrichSpawn: fakeEnrichSpawn,
+  });
+  assert.ok(res2.skipped.includes("identity"), "identity skipped on re-run");
+  assert.ok(res2.skipped.includes("operating-model"), "operating-model skipped on re-run");
+  assert.ok(res2.skipped.includes("company"), "company skipped on re-run");
+
+  // checkpoint recorded the completed sections.
+  const prog = loadProgress(root);
+  assert.equal(prog.sections["operating-model"].status, "complete");
+});
+
+test("maestro setup --status runs detect on every section without writing", async () => {
+  const root = seedAgentRepo();
+  const sections = await loadSections();
+  const res = await runSetup({
+    agentRoot: root,
+    maestroRoot: MAESTRO_ROOT,
+    sections,
+    flags: { resume: false, from: null, only: null, status: true, headless: true, answersFile: null, noEnrich: false, dryRun: false, verbose: false, help: false },
+    answers: {},
+  });
+  assert.equal(res.status, true);
+  // status must not have generated the operating model.
+  assert.equal(existsSync(join(root, "config", "operating-charter.md")), false);
+});
+
+test("maestro setup --no-enrich leaves prose skeletons but still completes the gate", async () => {
+  const root = seedAgentRepo();
+  const sections = await loadSections();
+  await runSetup({
+    agentRoot: root,
+    maestroRoot: MAESTRO_ROOT,
+    sections,
+    flags: { resume: false, from: null, only: null, status: false, headless: true, answersFile: null, noEnrich: true, dryRun: false, verbose: false, help: false },
+    answers: ANSWERS,
+  });
+  // The deterministic operating-model artifacts still exist...
+  assert.ok(existsSync(join(root, "config", "agent-roster.yaml")));
+  // ...but the charter still carries TBD slots (not enriched), so the gate is NOT green.
+  const gate = await assertComplete(root);
+  assert.equal(gate.ok, false, "without enrichment, charter TBD slots keep the gate red");
+});

package/lib/setup/io.mjs

@@ -0,0 +1,360 @@
+/**
+ * lib/setup/io.mjs — terminal prompt helpers for the `maestro setup` wizard.
+ *
+ * House style: Node built-ins only (`node:readline/promises` + raw-mode stdin),
+ * no new npm dependency. Every helper accepts a `{ headless, answers }` context;
+ * in headless/non-TTY mode each returns the pre-supplied answer
+ * (`answers[key]` → env → default) and NEVER blocks on input.
+ *
+ * Helpers:
+ *   text(ctx, opts)        → string
+ *   select(ctx, opts)      → value of the chosen choice
+ *   multiselect(ctx, opts) → array of chosen values
+ *   confirm(ctx, opts)     → boolean
+ *   secret(ctx, opts)      → string (masked echo, never persisted by io)
+ *   note(...)              → void (stderr-free informational print)
+ *
+ * Pure helpers: no side effects beyond stdio. The wizard sections own all file
+ * writes; io only reads input and prints prompts.
+ *
+ * @module lib/setup/io
+ */
+
+"use strict";
+
+import { createInterface } from "node:readline/promises";
+import { stdin as defaultIn, stdout as defaultOut } from "node:process";
+
+/** ANSI escape helpers (kept tiny + dependency-free). */
+const ESC = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  reset: "\x1b[0m",
+};
+
+/**
+ * Is this context running without an interactive TTY (so prompts must not
+ * block)? True when `headless` is set, when stdin lacks `isTTY`, or when raw
+ * mode is unavailable.
+ * @param {object} [ctx]
+ * @param {NodeJS.ReadStream} [input]
+ * @returns {boolean}
+ */
+export function isHeadless(ctx = {}, input = defaultIn) {
+  if (ctx.headless) return true;
+  if (!input || !input.isTTY) return true;
+  return typeof input.setRawMode !== "function";
+}
+
+/**
+ * Resolve a pre-supplied answer for `key` from the context answers bag, then
+ * the environment, then the provided default. Returns `undefined` when nothing
+ * is available (caller decides whether that is fatal).
+ * @param {object} ctx
+ * @param {string} [key]
+ * @param {{env?:string, default?:*}} [opts]
+ */
+export function resolveAnswer(ctx, key, opts = {}) {
+  const answers = (ctx && ctx.answers) || {};
+  if (key && Object.prototype.hasOwnProperty.call(answers, key) && answers[key] !== undefined) {
+    return answers[key];
+  }
+  if (opts.env && process.env[opts.env] !== undefined && process.env[opts.env] !== "") {
+    return process.env[opts.env];
+  }
+  if (Object.prototype.hasOwnProperty.call(opts, "default")) return opts.default;
+  return undefined;
+}
+
+/** Strip bracketed-paste markers a terminal may wrap pasted input with. */
+export function stripBracketedPaste(s) {
+  if (typeof s !== "string") return s;
+  // ESC [ 200 ~  … ESC [ 201 ~  (and any bare occurrence of the markers).
+  return s.replace(/\x1b\[20[01]~/g, "");
+}
+
+/**
+ * Free-text prompt.
+ * @param {object} ctx wizard context ({ headless, answers })
+ * @param {{message:string, key?:string, env?:string, default?:string, trim?:boolean}} opts
+ * @returns {Promise<string>}
+ */
+export async function text(ctx, opts = {}) {
+  const trim = opts.trim !== false;
+  if (isHeadless(ctx)) {
+    const v = resolveAnswer(ctx, opts.key, opts);
+    const s = v === undefined || v === null ? "" : String(v);
+    return trim ? s.trim() : s;
+  }
+  const rl = createInterface({ input: defaultIn, output: defaultOut });
+  try {
+    const def = resolveAnswer(ctx, opts.key, opts);
+    const suffix = def ? ` ${ESC.dim(`(${def})`)}` : "";
+    const answer = await rl.question(`${opts.message}${suffix}: `);
+    const clean = stripBracketedPaste(answer);
+    const out = trim ? clean.trim() : clean;
+    if (!out && def !== undefined && def !== null) return trim ? String(def).trim() : String(def);
+    return out;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Yes/no confirmation.
+ * @param {object} ctx
+ * @param {{message:string, key?:string, env?:string, default?:boolean}} opts
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(ctx, opts = {}) {
+  const dflt = opts.default !== undefined ? !!opts.default : false;
+  if (isHeadless(ctx)) {
+    const v = resolveAnswer(ctx, opts.key, { ...opts, default: dflt });
+    return coerceBool(v, dflt);
+  }
+  const rl = createInterface({ input: defaultIn, output: defaultOut });
+  try {
+    const hint = dflt ? "Y/n" : "y/N";
+    const answer = (await rl.question(`${opts.message} ${ESC.dim(`(${hint})`)} `)).trim().toLowerCase();
+    if (!answer) return dflt;
+    return /^y(es)?$/.test(answer);
+  } finally {
+    rl.close();
+  }
+}
+
+function coerceBool(v, dflt) {
+  if (typeof v === "boolean") return v;
+  if (v === undefined || v === null || v === "") return dflt;
+  return /^(1|y|yes|true|on)$/i.test(String(v).trim());
+}
+
+/**
+ * Single-choice select. Choices: `[{ label, value }]` or bare strings.
+ * Interactive mode uses raw ↑/↓ + enter; headless/non-TTY returns the
+ * pre-supplied answer (matched against value or label) or the default.
+ * @param {object} ctx
+ * @param {{message:string, choices:Array, key?:string, env?:string, default?:*}} opts
+ * @returns {Promise<*>}
+ */
+export async function select(ctx, opts = {}) {
+  const choices = normalizeChoices(opts.choices);
+  if (choices.length === 0) throw new Error("select: choices must be non-empty");
+
+  if (isHeadless(ctx)) {
+    const v = resolveAnswer(ctx, opts.key, opts);
+    const match = matchChoice(choices, v);
+    if (match) return match.value;
+    return (matchChoice(choices, opts.default) || choices[0]).value;
+  }
+  const idx = await rawSelect(opts.message, choices, defaultIndex(choices, resolveAnswer(ctx, opts.key, opts)));
+  return choices[idx].value;
+}
+
+/**
+ * Multi-choice select (space toggles, enter confirms). Headless returns the
+ * pre-supplied answer array (each matched against value/label) or default.
+ * @param {object} ctx
+ * @param {{message:string, choices:Array, key?:string, env?:string, default?:Array}} opts
+ * @returns {Promise<Array>}
+ */
+export async function multiselect(ctx, opts = {}) {
+  const choices = normalizeChoices(opts.choices);
+  if (choices.length === 0) return [];
+
+  if (isHeadless(ctx)) {
+    const raw = resolveAnswer(ctx, opts.key, opts);
+    const arr = Array.isArray(raw) ? raw : raw == null || raw === "" ? (opts.default || []) : [raw];
+    const out = [];
+    for (const item of arr) {
+      const m = matchChoice(choices, item);
+      if (m) out.push(m.value);
+    }
+    return out;
+  }
+  const preselected = new Set();
+  const def = resolveAnswer(ctx, opts.key, opts);
+  if (Array.isArray(def)) for (const d of def) { const m = matchChoice(choices, d); if (m) preselected.add(choices.indexOf(m)); }
+  const chosen = await rawMultiSelect(opts.message, choices, preselected);
+  return chosen.map((i) => choices[i].value);
+}
+
+/**
+ * Masked secret prompt. Echoes `*` per character; strips bracketed-paste
+ * markers. Falls back to a non-masked readline if raw mode is unavailable but
+ * stdin is still a TTY (rare). Headless returns the pre-supplied answer.
+ * `io` never persists secrets — the caller writes them.
+ * @param {object} ctx
+ * @param {{message:string, key?:string, env?:string, default?:string}} opts
+ * @returns {Promise<string>}
+ */
+export async function secret(ctx, opts = {}) {
+  if (isHeadless(ctx)) {
+    const v = resolveAnswer(ctx, opts.key, opts);
+    return v === undefined || v === null ? "" : String(v);
+  }
+  const input = defaultIn;
+  const output = defaultOut;
+  if (typeof input.setRawMode !== "function") {
+    // Non-raw TTY fallback (no masking possible) — still functional.
+    const rl = createInterface({ input, output });
+    try { return stripBracketedPaste((await rl.question(`${opts.message}: `)).trim()); }
+    finally { rl.close(); }
+  }
+
+  return new Promise((resolve, reject) => {
+    output.write(`${opts.message}: `);
+    let buf = "";
+    const prevRaw = input.isRaw;
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+
+    const cleanup = () => {
+      input.setRawMode(prevRaw || false);
+      input.pause();
+      input.removeListener("data", onData);
+      output.write("\n");
+    };
+
+    const onData = (chunk) => {
+      const data = stripBracketedPaste(chunk);
+      for (const ch of data) {
+        if (ch === "\r" || ch === "\n") { cleanup(); resolve(buf); return; }
+        if (ch === "") { cleanup(); reject(new Error("cancelled")); return; } // Ctrl-C
+        if (ch === "" || ch === "\b") { // backspace
+          if (buf.length > 0) { buf = buf.slice(0, -1); output.write("\b \b"); }
+          continue;
+        }
+        if (ch < " ") continue; // ignore other control chars
+        buf += ch;
+        output.write("*");
+      }
+    };
+    input.on("data", onData);
+  });
+}
+
+/** Informational line — printed to stdout, never to stderr (not an error). */
+export function note(message, { dim = false } = {}) {
+  defaultOut.write(`${dim ? ESC.dim(message) : message}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+
+function normalizeChoices(choices) {
+  if (!Array.isArray(choices)) return [];
+  return choices.map((c) =>
+    c && typeof c === "object" && "value" in c
+      ? { label: c.label != null ? String(c.label) : String(c.value), value: c.value, hint: c.hint }
+      : { label: String(c), value: c }
+  );
+}
+
+function matchChoice(choices, needle) {
+  if (needle === undefined || needle === null) return null;
+  const n = String(needle).trim().toLowerCase();
+  return (
+    choices.find((c) => String(c.value).toLowerCase() === n) ||
+    choices.find((c) => c.label.toLowerCase() === n) ||
+    null
+  );
+}
+
+function defaultIndex(choices, needle) {
+  const m = matchChoice(choices, needle);
+  const i = m ? choices.indexOf(m) : 0;
+  return i < 0 ? 0 : i;
+}
+
+/** Raw-mode single select returning the chosen index. */
+function rawSelect(message, choices, start = 0) {
+  return new Promise((resolve, reject) => {
+    const input = defaultIn;
+    const output = defaultOut;
+    let cur = start;
+    const prevRaw = input.isRaw;
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+
+    const render = (first) => {
+      if (!first) output.write(`\x1b[${choices.length + 1}A`); // move cursor up to redraw
+      output.write(`${ESC.bold(message)}  ${ESC.dim("(↑/↓, enter)")}\n`);
+      choices.forEach((c, i) => {
+        const marker = i === cur ? ESC.cyan("❯") : " ";
+        const label = i === cur ? ESC.cyan(c.label) : c.label;
+        const hint = c.hint ? ` ${ESC.dim(c.hint)}` : "";
+        output.write(`\x1b[2K${marker} ${label}${hint}\n`);
+      });
+    };
+
+    const cleanup = () => {
+      input.setRawMode(prevRaw || false);
+      input.pause();
+      input.removeListener("data", onData);
+    };
+
+    const onData = (chunk) => {
+      const data = stripBracketedPaste(chunk);
+      if (data === "") { cleanup(); reject(new Error("cancelled")); return; }
+      if (data === "\r" || data === "\n") { cleanup(); resolve(cur); return; }
+      if (data === "" || data === "k") cur = (cur - 1 + choices.length) % choices.length;
+      else if (data === "" || data === "j") cur = (cur + 1) % choices.length;
+      else { const n = parseInt(data, 10); if (!Number.isNaN(n) && n >= 1 && n <= choices.length) cur = n - 1; }
+      render(false);
+    };
+    render(true);
+    input.on("data", onData);
+  });
+}
+
+/** Raw-mode multi select returning the chosen indices (sorted). */
+function rawMultiSelect(message, choices, preselected = new Set()) {
+  return new Promise((resolve, reject) => {
+    const input = defaultIn;
+    const output = defaultOut;
+    let cur = 0;
+    const chosen = new Set(preselected);
+    const prevRaw = input.isRaw;
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf8");
+
+    const render = (first) => {
+      if (!first) output.write(`\x1b[${choices.length + 1}A`);
+      output.write(`${ESC.bold(message)}  ${ESC.dim("(↑/↓, space, enter)")}\n`);
+      choices.forEach((c, i) => {
+        const cursor = i === cur ? ESC.cyan("❯") : " ";
+        const box = chosen.has(i) ? ESC.green("◉") : "◯";
+        const label = i === cur ? ESC.cyan(c.label) : c.label;
+        const hint = c.hint ? ` ${ESC.dim(c.hint)}` : "";
+        output.write(`\x1b[2K${cursor} ${box} ${label}${hint}\n`);
+      });
+    };
+
+    const cleanup = () => {
+      input.setRawMode(prevRaw || false);
+      input.pause();
+      input.removeListener("data", onData);
+    };
+
+    const onData = (chunk) => {
+      const data = stripBracketedPaste(chunk);
+      if (data === "") { cleanup(); reject(new Error("cancelled")); return; }
+      if (data === "\r" || data === "\n") { cleanup(); resolve([...chosen].sort((a, b) => a - b)); return; }
+      if (data === " ") { if (chosen.has(cur)) chosen.delete(cur); else chosen.add(cur); }
+      else if (data === "" || data === "k") cur = (cur - 1 + choices.length) % choices.length;
+      else if (data === "" || data === "j") cur = (cur + 1) % choices.length;
+      render(false);
+    };
+    render(true);
+    input.on("data", onData);
+  });
+}
+
+export default { text, select, multiselect, confirm, secret, note, isHeadless, resolveAnswer, stripBracketedPaste };

package/lib/setup/io.test.mjs

@@ -0,0 +1,77 @@
+/**
+ * io.test.mjs — headless-mode + helper tests for lib/setup/io.mjs.
+ * Interactive raw-mode paths are not exercised here (no TTY in CI); we test the
+ * pure helpers and the headless contract (no blocking, pre-supplied answers).
+ * Run: `node --test lib/setup/io.test.mjs`
+ * @module lib/setup/io.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  text, select, multiselect, confirm, secret,
+  isHeadless, resolveAnswer, stripBracketedPaste,
+} from "./io.mjs";
+
+const HL = { headless: true, answers: {} };
+
+test("isHeadless is true when ctx.headless set", () => {
+  assert.equal(isHeadless({ headless: true }), true);
+});
+
+test("resolveAnswer prefers answers, then env, then default", () => {
+  assert.equal(resolveAnswer({ answers: { k: "a" } }, "k", { default: "d" }), "a");
+  process.env.__IO_TEST_ENV = "fromenv";
+  assert.equal(resolveAnswer({ answers: {} }, "k", { env: "__IO_TEST_ENV", default: "d" }), "fromenv");
+  delete process.env.__IO_TEST_ENV;
+  assert.equal(resolveAnswer({ answers: {} }, "k", { default: "d" }), "d");
+  assert.equal(resolveAnswer({ answers: {} }, "k", {}), undefined);
+});
+
+test("stripBracketedPaste removes paste markers", () => {
+  assert.equal(stripBracketedPaste("\x1b[200~hello\x1b[201~"), "hello");
+  assert.equal(stripBracketedPaste("plain"), "plain");
+});
+
+test("text returns pre-supplied answer in headless mode (never blocks)", async () => {
+  const v = await text({ ...HL, answers: { name: "Jacob" } }, { message: "Name?", key: "name" });
+  assert.equal(v, "Jacob");
+});
+
+test("text falls back to default when no answer", async () => {
+  const v = await text(HL, { message: "Name?", key: "missing", default: "Anon" });
+  assert.equal(v, "Anon");
+});
+
+test("confirm coerces headless answer strings", async () => {
+  assert.equal(await confirm({ ...HL, answers: { ok: "yes" } }, { message: "?", key: "ok" }), true);
+  assert.equal(await confirm({ ...HL, answers: { ok: false } }, { message: "?", key: "ok" }), false);
+  assert.equal(await confirm(HL, { message: "?", key: "x", default: true }), true);
+});
+
+test("select matches by value or label, falls back to first/default", async () => {
+  const choices = [{ label: "Sonnet", value: "sonnet" }, { label: "Haiku", value: "haiku" }];
+  assert.equal(await select({ ...HL, answers: { m: "haiku" } }, { message: "?", key: "m", choices }), "haiku");
+  assert.equal(await select({ ...HL, answers: { m: "Sonnet" } }, { message: "?", key: "m", choices }), "sonnet");
+  assert.equal(await select(HL, { message: "?", key: "m", choices, default: "haiku" }), "haiku");
+  assert.equal(await select(HL, { message: "?", key: "m", choices }), "sonnet"); // first
+});
+
+test("multiselect returns matched values, ignoring unknowns", async () => {
+  const choices = [{ label: "Slack", value: "slack" }, { label: "Email", value: "email" }, { label: "SMS", value: "sms" }];
+  const v = await multiselect({ ...HL, answers: { ch: ["slack", "sms", "nope"] } }, { message: "?", key: "ch", choices });
+  assert.deepEqual(v, ["slack", "sms"]);
+});
+
+test("multiselect default applies when answer absent", async () => {
+  const choices = ["a", "b", "c"];
+  const v = await multiselect(HL, { message: "?", key: "ch", choices, default: ["b"] });
+  assert.deepEqual(v, ["b"]);
+});
+
+test("secret returns pre-supplied answer headless, never echoing", async () => {
+  const v = await secret({ ...HL, answers: { token: "xapp-123" } }, { message: "Token", key: "token" });
+  assert.equal(v, "xapp-123");
+});

package/lib/setup/run-generator.mjs

@@ -0,0 +1,81 @@
+/**
+ * lib/setup/run-generator.mjs — invoke a scripts/setup/*.mjs generator with the
+ * shared execution contract (cwd = agent repo; env MAESTRO_ROOT / AGENT_ROOT).
+ *
+ * Generators that only template from config/agent.json run for real. The runner
+ * surfaces failures to the caller, which decides whether they are fatal (the
+ * operating-model section treats a generator failure as fatal; verify reports it).
+ *
+ * @module lib/setup/run-generator
+ */
+
+"use strict";
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = join(HERE, "..", "..");
+
+/**
+ * Run a generator script. Returns { ok, stdout, stderr, code }. Never throws on
+ * a non-zero exit (captured), but a spawn failure (ENOENT) is captured too.
+ *
+ * @param {string} script  filename under scripts/setup/ (e.g. "generate-charter.mjs")
+ * @param {string} agentRoot
+ * @param {object} [opts]
+ * @param {string} [opts.maestroRoot]
+ * @param {boolean} [opts.bash]  run via /bin/bash (for .sh generators)
+ * @param {string[]} [opts.args]
+ * @returns {{ok:boolean, stdout:string, stderr:string, code:number}}
+ */
+export function runGenerator(script, agentRoot, opts = {}) {
+  const maestroRoot = opts.maestroRoot || MAESTRO_ROOT;
+  const scriptPath = join(maestroRoot, "scripts", "setup", script);
+  if (!existsSync(scriptPath)) {
+    return { ok: false, stdout: "", stderr: `generator not found: ${scriptPath}`, code: 127 };
+  }
+  const cmd = opts.bash ? "/bin/bash" : process.execPath;
+  const argv = opts.bash ? [scriptPath, ...(opts.args || [])] : [scriptPath, ...(opts.args || [])];
+  try {
+    const stdout = execFileSync(cmd, argv, {
+      cwd: agentRoot,
+      env: { ...process.env, MAESTRO_ROOT: maestroRoot, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot },
+      encoding: "utf-8",
+    });
+    return { ok: true, stdout: stdout || "", stderr: "", code: 0 };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: e && e.stdout ? String(e.stdout) : "",
+      stderr: e && e.stderr ? String(e.stderr) : (e && e.message ? e.message : String(e)),
+      code: e && typeof e.status === "number" ? e.status : 1,
+    };
+  }
+}
+
+/** Run a script that lives somewhere other than scripts/setup (absolute path). */
+export function runScriptAbs(scriptPath, agentRoot, opts = {}) {
+  const maestroRoot = opts.maestroRoot || MAESTRO_ROOT;
+  if (!existsSync(scriptPath)) return { ok: false, stdout: "", stderr: `script not found: ${scriptPath}`, code: 127 };
+  const cmd = opts.bash ? "/bin/bash" : process.execPath;
+  try {
+    const stdout = execFileSync(cmd, [scriptPath, ...(opts.args || [])], {
+      cwd: agentRoot,
+      env: { ...process.env, MAESTRO_ROOT: maestroRoot, AGENT_ROOT: agentRoot, AGENT_DIR: agentRoot },
+      encoding: "utf-8",
+    });
+    return { ok: true, stdout: stdout || "", stderr: "", code: 0 };
+  } catch (e) {
+    return {
+      ok: false,
+      stdout: e && e.stdout ? String(e.stdout) : "",
+      stderr: e && e.stderr ? String(e.stderr) : (e && e.message ? e.message : String(e)),
+      code: e && typeof e.status === "number" ? e.status : 1,
+    };
+  }
+}
+
+export { MAESTRO_ROOT as DEFAULT_MAESTRO_ROOT };