@cohortapp/agent-sdk 2.3.0

package/bin/maestro.test.mjs

@@ -0,0 +1,1015 @@
+/**
+ * maestro.test.mjs — CLI tests for the bin/maestro.mjs commands.
+ *
+ * Covers:
+ *   • `create` scaffolds the cadence-bus directory tree, the enqueue
+ *     script, the consumer, and the cadence handlers under the new agent.
+ *   • `upgrade` migrates a legacy-style agent repo: backs up old plists,
+ *     bootstraps state/cadence-bus/, regenerates plists.
+ *   • `upgrade` preserves agent-specific files (CLAUDE.md, config/,
+ *     knowledge/, memory/, state/, logs/, outputs/, .env) untouched.
+ *   • `upgrade` is idempotent when run twice on the same repo.
+ *   • `doctor` flags legacy plists with actionable remediation.
+ *
+ * Note: `create` runs `npm install` at the end, which is heavyweight. To
+ * keep test runtime reasonable we skip the npm install step by passing
+ * an alternate npm shim on PATH that is a no-op. Same trick for git.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "fs";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { tmpdir } from "os";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "node:url";
+import { spawnSync, execFileSync } from "node:child_process";
+import { chmodSync, statSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(__dirname, "..");
+const MAESTRO_CLI = resolve(__dirname, "maestro.mjs");
+
+// Pure predicates exported from the CLI module (importing does not dispatch).
+const { evaluateCostTripwire, summariseLedgerRows, evaluateStaleness } = await import(MAESTRO_CLI);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function tmpRoot(prefix = "maestro-cli-test") {
+  const path = join(
+    tmpdir(),
+    `${prefix}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+
+async function rmRoot(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+/**
+ * Build a PATH that shadows `npm` (and optionally `git`) with no-op shims
+ * so `create` doesn't actually try to install dependencies. Returns the new
+ * env block plus the shim dir (for cleanup).
+ */
+async function withShim() {
+  const dir = await tmpRoot("maestro-shim");
+  const npm = join(dir, "npm");
+  writeFileSync(npm, "#!/bin/bash\necho '[shim npm]' \"$@\" >&2\nexit 0\n");
+  await fsp.chmod(npm, 0o755);
+  // Keep real git (we want git init to actually init).
+  const env = { ...process.env, PATH: `${dir}:${process.env.PATH || ""}` };
+  return { env, dir };
+}
+
+function runCli(args, cwd, env) {
+  return spawnSync(process.execPath, [MAESTRO_CLI, ...args], {
+    cwd: cwd || process.cwd(),
+    env: env || process.env,
+    encoding: "utf-8",
+  });
+}
+
+/** Like runCli but pipes `input` to the child's stdin (for `secrets rotate`). */
+function runCliStdin(args, cwd, input, env) {
+  return spawnSync(process.execPath, [MAESTRO_CLI, ...args], {
+    cwd: cwd || process.cwd(),
+    env: env || process.env,
+    input,
+    encoding: "utf-8",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+
+test("create scaffolds cadence-bus dirs and enqueue/consumer/handlers", async () => {
+  const parent = await tmpRoot("maestro-create");
+  const { env, dir: shim } = await withShim();
+  try {
+    const r = runCli(["create", "test-agent"], parent, env);
+    assert.equal(r.status, 0, r.stderr || r.stdout);
+    const agent = join(parent, "test-agent");
+
+    // Cadence bus directory tree
+    for (const d of [
+      "state/cadence-bus",
+      "state/cadence-bus/inbox",
+      "state/cadence-bus/claimed",
+      "state/cadence-bus/processed",
+      "state/cadence-bus/failed",
+      "state/cadence-bus/dlq",
+      "logs/cadence-bus",
+    ]) {
+      assert.ok(existsSync(join(agent, d)), `missing ${d}`);
+    }
+
+    // New framework files copied into the agent repo.
+    for (const f of [
+      "lib/cadence-bus.mjs",
+      "scripts/cadence/enqueue-cadence-tick.mjs",
+      "scripts/cadence/launchd-cadence-wrapper.sh",
+      "scripts/cadence/cadence-status.mjs",
+      "scripts/daemon/cadence-consumer.mjs",
+      "scripts/daemon/cadence-handlers.mjs",
+    ]) {
+      assert.ok(existsSync(join(agent, f)), `missing ${f}`);
+    }
+
+    // Agent package.json has the cadence:* scripts.
+    const pkg = JSON.parse(readFileSync(join(agent, "package.json"), "utf-8"));
+    assert.ok(pkg.scripts["cadence:enqueue"]);
+    assert.ok(pkg.scripts["cadence:consume"]);
+    assert.ok(pkg.scripts["cadence:status"]);
+  } finally {
+    await rmRoot(parent);
+    await rmRoot(shim);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// upgrade — migration
+// ---------------------------------------------------------------------------
+
+async function makeLegacyAgent() {
+  const root = await tmpRoot("maestro-legacy");
+  // Minimal identity so `upgrade` recognises this as a Maestro repo.
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "CLAUDE.md"), "# legacy agent\n");
+  writeFileSync(join(root, "config/agent.ts"), "export const AGENT = { firstName: 'legacy' };\n");
+  writeFileSync(join(root, "package.json"), '{"name":"legacy-agent","version":"1.0.0"}\n');
+  // Personal/local agent state that must NOT be touched.
+  mkdirSync(join(root, "knowledge/decisions"), { recursive: true });
+  mkdirSync(join(root, "memory/interactions"), { recursive: true });
+  mkdirSync(join(root, "state/queues"), { recursive: true });
+  mkdirSync(join(root, "outputs"), { recursive: true });
+  mkdirSync(join(root, "logs"), { recursive: true });
+  writeFileSync(join(root, "knowledge/decisions/local-decision.md"), "# do not touch");
+  writeFileSync(join(root, "memory/interactions/local-memory.yaml"), "# do not touch");
+  writeFileSync(join(root, "state/queues/action-stack.yaml"), "items:\n  - id: P1\n    title: local item\n");
+  writeFileSync(join(root, "outputs/local-output.md"), "# my draft");
+  writeFileSync(join(root, "logs/local.log"), "audit data");
+  writeFileSync(join(root, ".env"), "ANTHROPIC_API_KEY=sk-x\n");
+
+  // Legacy plist that calls run-trigger.sh directly.
+  mkdirSync(join(root, "scripts/local-triggers/plists"), { recursive: true });
+  writeFileSync(
+    join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"),
+    `<?xml version="1.0"?><plist><dict>
+<key>ProgramArguments</key><array>
+  <string>/foo/scripts/local-triggers/run-trigger.sh</string>
+  <string>inbox-processor</string>
+</array></dict></plist>`
+  );
+
+  // Init git so smart-merge sees the working tree as clean.
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["add", "-A"], { cwd: root });
+  execFileSync(
+    "git",
+    ["-c", "user.email=test@test", "-c", "user.name=test", "commit", "-q", "-m", "init"],
+    { cwd: root },
+  );
+  return root;
+}
+
+test("upgrade backs up legacy plists and regenerates with cadence-bus marker", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    // Backup directory exists.
+    const backupRoot = join(root, ".maestro/backup/plists");
+    assert.ok(existsSync(backupRoot), "backup root must exist");
+    const stamps = readdirSync(backupRoot);
+    assert.ok(stamps.length >= 1);
+    const backedUp = readdirSync(join(backupRoot, stamps[0]));
+    assert.ok(backedUp.some((n) => /legacy-inbox-processor\.plist$/.test(n)));
+
+    // After regeneration, plists carry the cadence-bus marker and none
+    // reference run-trigger.sh.
+    const plistDir = join(root, "scripts/local-triggers/plists");
+    const plists = readdirSync(plistDir).filter((n) => n.endsWith(".plist"));
+    assert.ok(plists.length >= 1);
+    let legacy = 0;
+    let modern = 0;
+    for (const name of plists) {
+      const body = readFileSync(join(plistDir, name), "utf-8");
+      if (body.includes("run-trigger.sh")) legacy++;
+      if (body.includes("maestro-plist-arch: cadence-bus")) modern++;
+    }
+    assert.equal(legacy, 0, "no legacy plists should remain post-upgrade");
+    assert.equal(modern, plists.length, "every plist must carry the cadence-bus marker");
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade preserves agent-specific files untouched", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const before = {
+      claudemd: readFileSync(join(root, "CLAUDE.md"), "utf-8"),
+      agentTs: readFileSync(join(root, "config/agent.ts"), "utf-8"),
+      decision: readFileSync(join(root, "knowledge/decisions/local-decision.md"), "utf-8"),
+      memory: readFileSync(join(root, "memory/interactions/local-memory.yaml"), "utf-8"),
+      queue: readFileSync(join(root, "state/queues/action-stack.yaml"), "utf-8"),
+      output: readFileSync(join(root, "outputs/local-output.md"), "utf-8"),
+      log: readFileSync(join(root, "logs/local.log"), "utf-8"),
+      env: readFileSync(join(root, ".env"), "utf-8"),
+    };
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+    for (const [k, v] of Object.entries(before)) {
+      const path = ({
+        claudemd: "CLAUDE.md",
+        agentTs: "config/agent.ts",
+        decision: "knowledge/decisions/local-decision.md",
+        memory: "memory/interactions/local-memory.yaml",
+        queue: "state/queues/action-stack.yaml",
+        output: "outputs/local-output.md",
+        log: "logs/local.log",
+        env: ".env",
+      })[k];
+      assert.equal(
+        readFileSync(join(root, path), "utf-8"),
+        v,
+        `${path} was modified by upgrade`,
+      );
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade is idempotent (second run is a clean no-op for plists)", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const first = runCli(["upgrade"], root);
+    assert.equal(first.status, 0);
+    // Snapshot the regenerated plist contents.
+    const plistDir = join(root, "scripts/local-triggers/plists");
+    const before = {};
+    for (const name of readdirSync(plistDir)) {
+      before[name] = readFileSync(join(plistDir, name), "utf-8");
+    }
+    const second = runCli(["upgrade"], root);
+    assert.equal(second.status, 0);
+    // The second run should NOT introduce any new backup directory beyond
+    // what the first run created, because there are no legacy plists left.
+    const backups = readdirSync(join(root, ".maestro/backup/plists"));
+    assert.equal(backups.length, 1, "no new backup directory on idempotent run");
+    // Plist contents byte-identical.
+    for (const [name, body] of Object.entries(before)) {
+      assert.equal(readFileSync(join(plistDir, name), "utf-8"), body, `${name} changed`);
+    }
+  } finally { await rmRoot(root); }
+});
+
+test("upgrade --dry-run reports legacy without modifying anything", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    // Snapshot a known sentinel file.
+    const sentinel = readFileSync(join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"), "utf-8");
+    const r = runCli(["upgrade", "--dry-run"], root);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /still call run-trigger\.sh/);
+    // Sentinel must not have changed.
+    assert.equal(
+      readFileSync(join(root, "scripts/local-triggers/plists/ai.adaptic.legacy-inbox-processor.plist"), "utf-8"),
+      sentinel,
+    );
+    // No backup directory created.
+    assert.ok(!existsSync(join(root, ".maestro/backup")), "dry-run must not create backups");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor
+// ---------------------------------------------------------------------------
+
+test("doctor flags legacy plists with actionable remediation", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    const r = runCli(["doctor"], root);
+    // doctor exits 1 when issues are found; that's expected here.
+    assert.ok(r.status >= 0);
+    const combined = (r.stdout || "") + (r.stderr || "");
+    assert.match(combined, /run-trigger\.sh/);
+    assert.match(combined, /maestro upgrade/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor recognises new cadence-bus architecture after upgrade", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    runCli(["upgrade"], root);
+    const r = runCli(["doctor"], root);
+    const combined = (r.stdout || "") + (r.stderr || "");
+    assert.match(combined, /cadence-bus architecture/);
+    // 'plist(s) still call run-trigger.sh' must NOT appear.
+    assert.ok(!combined.includes("plist(s) still call run-trigger.sh"));
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// setup (WS1 wizard) — CLI surface
+// ---------------------------------------------------------------------------
+
+test("setup --help runs in a non-agent dir without throwing (exit 0)", async () => {
+  const dir = await tmpRoot("maestro-setup-help");
+  try {
+    const r = runCli(["setup", "--help"], dir);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /maestro setup/);
+    assert.match(r.stdout, /--headless/);
+  } finally { await rmRoot(dir); }
+});
+
+test("setup --status in a non-agent dir prints a graceful message (exit 0)", async () => {
+  const dir = await tmpRoot("maestro-setup-status");
+  try {
+    const r = runCli(["setup", "--status"], dir);
+    assert.equal(r.status, 0, r.stderr);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /Not a Maestro agent directory/);
+  } finally { await rmRoot(dir); }
+});
+
+test("setup --status in an agent dir lists section detect() statuses", async () => {
+  const dir = await tmpRoot("maestro-setup-agent");
+  try {
+    mkdirSync(join(dir, "config"), { recursive: true });
+    // Minimal SoT so the agent-repo guard passes + sections can detect.
+    writeFileSync(join(dir, "config/agent.json"), JSON.stringify({
+      firstName: "UNCONFIGURED", lastName: "AGENT", title: "Unconfigured Role", email: "",
+      function: "executive-operator", altitude: "c-suite",
+    }, null, 2));
+    const r = runCli(["setup", "--status"], dir);
+    assert.equal(r.status, 0, r.stderr);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /identity/);
+    assert.match(out, /operating-model/);
+    assert.match(out, /verify/);
+  } finally { await rmRoot(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor cost-telemetry tripwire — pure predicate (observability F2)
+// ---------------------------------------------------------------------------
+
+test("summariseLedgerRows sums estimated_usd and counts rows; tolerates junk", () => {
+  const s = summariseLedgerRows([
+    { estimated_usd: 0.5 },
+    { estimated_usd: 1.25 },
+    { estimated_usd: "0.25" }, // numeric string coerced
+    { estimated_usd: NaN },    // ignored as 0
+    {},                        // counts as a row, $0
+    null,                      // skipped entirely
+    "garbage",                 // skipped entirely
+  ]);
+  assert.equal(s.rowCount, 5, "only object rows count");
+  assert.equal(s.totalUsd, 2, "0.5 + 1.25 + 0.25 = 2.00");
+});
+
+test("summariseLedgerRows on empty input is zeroed", () => {
+  assert.deepEqual(summariseLedgerRows([]), { rowCount: 0, totalUsd: 0 });
+  assert.deepEqual(summariseLedgerRows(undefined), { rowCount: 0, totalUsd: 0 });
+});
+
+test("evaluateCostTripwire: rows exist but spend is $0 → RED (telemetry blind)", () => {
+  const t = evaluateCostTripwire({
+    rows: [{ estimated_usd: 0 }, { estimated_usd: 0 }, { estimated_usd: 0 }],
+    sessionCount: 0,
+  });
+  assert.equal(t.red, true);
+  assert.equal(t.status, "red");
+  assert.equal(t.rowCount, 3);
+  assert.equal(t.totalUsd, 0);
+  assert.match(t.reason, /blind/i);
+});
+
+test("evaluateCostTripwire: no rows but heartbeat-active session → RED", () => {
+  // Daemon is live (heartbeat) but the ledger is empty → still blind.
+  const t = evaluateCostTripwire({ rows: [], sessionCount: 1 });
+  assert.equal(t.red, true);
+  assert.equal(t.status, "red");
+  assert.match(t.reason, /blind/i);
+});
+
+test("evaluateCostTripwire: no sessions and no rows → GREEN (nothing to measure)", () => {
+  const t = evaluateCostTripwire({ rows: [], sessionCount: 0 });
+  assert.equal(t.red, false);
+  assert.equal(t.status, "green");
+  assert.match(t.reason, /nothing to measure/i);
+});
+
+test("evaluateCostTripwire: spend > 0 → GREEN even with sessions", () => {
+  const t = evaluateCostTripwire({
+    rows: [{ estimated_usd: 0 }, { estimated_usd: 0.42 }],
+    sessionCount: 1,
+  });
+  assert.equal(t.red, false);
+  assert.equal(t.status, "green");
+  assert.equal(t.totalUsd, 0.42);
+  assert.match(t.reason, /live/i);
+});
+
+test("evaluateCostTripwire: defaults (no args) are GREEN, not a false alarm", () => {
+  const t = evaluateCostTripwire();
+  assert.equal(t.red, false);
+  assert.equal(t.status, "green");
+});
+
+// ---------------------------------------------------------------------------
+// doctor cost-telemetry tripwire — end-to-end against a real ledger file
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal agent repo that doctor can run against without exploding before our
+ * checks. doctor exits 1 on any issue (a bare repo has many), so these tests
+ * assert on the specific lines our checks emit rather than the exit code.
+ */
+async function makeBareAgent() {
+  const root = await tmpRoot("maestro-doctor");
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({
+    firstName: "test", function: "executive-operator", altitude: "c-suite",
+  }, null, 2));
+  writeFileSync(join(root, "CLAUDE.md"), "# test agent\n");
+  return root;
+}
+
+function utcDate() { return new Date().toISOString().slice(0, 10); }
+
+test("doctor RED when today's ledger has rows but $0 spend", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, "state/cost-tracking"), { recursive: true });
+    const ledger = join(root, "state/cost-tracking", `${utcDate()}.jsonl`);
+    writeFileSync(ledger,
+      JSON.stringify({ ts: new Date().toISOString(), cadence: "inbox-processor", model: "sonnet", input_tokens: 0, output_tokens: 0, estimated_usd: 0 }) + "\n" +
+      JSON.stringify({ ts: new Date().toISOString(), cadence: "backlog-executor", model: "opus", input_tokens: 0, output_tokens: 0, estimated_usd: 0 }) + "\n"
+    );
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /Cost telemetry BLIND/);
+    assert.match(out, /track-claude-usage\.mjs/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor GREEN when today's ledger records real spend", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, "state/cost-tracking"), { recursive: true });
+    const ledger = join(root, "state/cost-tracking", `${utcDate()}.jsonl`);
+    writeFileSync(ledger,
+      JSON.stringify({ ts: new Date().toISOString(), cadence: "inbox-processor", model: "sonnet", input_tokens: 1500, output_tokens: 320, estimated_usd: 0.0093 }) + "\n"
+    );
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /Cost telemetry live/);
+    assert.ok(!out.includes("Cost telemetry BLIND"), "must not flag blind when spend>0");
+  } finally { await rmRoot(root); }
+});
+
+test("doctor GREEN (nothing to measure) when no ledger exists today", async () => {
+  const root = await makeBareAgent();
+  try {
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /no sessions recorded today/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor .env permission check (setup-onboarding W4)
+// ---------------------------------------------------------------------------
+
+test("doctor flags a group/world-readable .env with the chmod fix", { skip: typeof process.getuid !== "function" }, async () => {
+  const root = await makeBareAgent();
+  try {
+    const envPath = join(root, ".env");
+    writeFileSync(envPath, "ANTHROPIC_API_KEY=sk-secret\n");
+    chmodSync(envPath, 0o644);
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /\.env is mode 644/);
+    assert.match(out, /chmod 600 \.env/);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor passes a chmod-600 .env", { skip: typeof process.getuid !== "function" }, async () => {
+  const root = await makeBareAgent();
+  try {
+    const envPath = join(root, ".env");
+    writeFileSync(envPath, "ANTHROPIC_API_KEY=sk-secret\n");
+    chmodSync(envPath, 0o600);
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /\.env permissions are owner-only/);
+    assert.ok(!out.includes(".env is mode"), "must not flag a 600 .env");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// evaluateStaleness (pure) — the router data-file staleness ladder (graft #18)
+// ---------------------------------------------------------------------------
+
+test("evaluateStaleness: fresh data is green", () => {
+  const now = Date.UTC(2026, 5, 11);
+  const v = evaluateStaleness({ fetched: "2026-06-10", now });
+  assert.equal(v.status, "green");
+  assert.equal(v.ageDays, 1);
+});
+
+test("evaluateStaleness: >7d but <30d is a WARN", () => {
+  const now = Date.UTC(2026, 5, 30);
+  const v = evaluateStaleness({ fetched: "2026-06-10", now });
+  assert.equal(v.status, "warn");
+  assert.ok(v.ageDays >= 7 && v.ageDays < 30);
+});
+
+test("evaluateStaleness: >=30d is a FAIL", () => {
+  const now = Date.UTC(2026, 6, 15);
+  const v = evaluateStaleness({ fetched: "2026-06-10", now });
+  assert.equal(v.status, "fail");
+  assert.ok(v.ageDays >= 30);
+});
+
+test("evaluateStaleness: a stale volatile catalog escalates the FAIL reason", () => {
+  const now = Date.UTC(2026, 6, 15);
+  const v = evaluateStaleness({ fetched: "2026-06-10", now, hasVolatile: true, label: "catalog" });
+  assert.equal(v.status, "fail");
+  assert.match(v.reason, /volatile/);
+});
+
+test("evaluateStaleness: a missing fetch date is a WARN (provenance unknown)", () => {
+  const v = evaluateStaleness({ fetched: null });
+  assert.equal(v.status, "warn");
+  assert.match(v.reason, /no fetch date/);
+});
+
+// ---------------------------------------------------------------------------
+// router CLI — `maestro router why` / `maestro router validate`
+// ---------------------------------------------------------------------------
+
+const V2_ROUTER_YAML = `
+schema_version: 2
+aliases:
+  frontier: anthropic/claude-opus-4-8
+  default: anthropic/claude-sonnet-4-6
+  fast: anthropic/claude-haiku-4-5
+  cheap: deepseek/deepseek-v4-flash
+defaults:
+  data_class: sensitive
+backends:
+  anthropic: { allowed_data_classes: [public, internal, sensitive] }
+  deepseek: { allowed_data_classes: [public] }
+routing_policy:
+  - match: { task_class: classify.inbox }
+    harness: direct
+    chain: [fast, cheap, rules]
+    needs_tool_use: false
+  - default: true
+    chain: [default, fast]
+fallback_to_anthropic: true
+`;
+
+async function makeV2RouterAgent() {
+  const root = await makeBareAgent();
+  writeFileSync(join(root, "config/model-routing.yaml"), V2_ROUTER_YAML);
+  return root;
+}
+
+test("router why: prints chosen + explain + chain for a session request", async () => {
+  const root = await makeV2RouterAgent();
+  try {
+    const r = runCli(["router", "why", "session.responder"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /chosen/);
+    assert.match(out, /anthropic\/claude-sonnet-4-6/);
+    assert.match(out, /explain/);
+    assert.match(out, /chain/);
+  } finally { await rmRoot(root); }
+});
+
+test("router why: accepts inline request JSON and reports tried[] skips", async () => {
+  const root = await makeV2RouterAgent();
+  try {
+    const r = runCli(
+      ["router", "why", '{"task_class":"classify.inbox","data_class":"public"}'],
+      root
+    );
+    const out = (r.stdout || "") + (r.stderr || "");
+    // No keys present → cheap deepseek + anthropic haiku-direct are unreachable;
+    // the deterministic "rules" fallback wins and the skips are listed.
+    assert.match(out, /tried/);
+    assert.match(out, /missing_credential/);
+  } finally { await rmRoot(root); }
+});
+
+test("router validate: a clean v2 config validates (exit 0)", async () => {
+  const root = await makeV2RouterAgent();
+  try {
+    const r = runCli(["router", "validate"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 0, out);
+    assert.match(out, /valid/);
+  } finally { await rmRoot(root); }
+});
+
+test("router validate: an unknown match key fails validation (exit 1)", async () => {
+  const root = await makeBareAgent();
+  try {
+    writeFileSync(
+      join(root, "config/model-routing.yaml"),
+      "schema_version: 2\naliases:\n  default: anthropic/claude-sonnet-4-6\nrouting_policy:\n  - match: { taks_class: x }\n    chain: [default]\n  - default: true\n    chain: [default]\n"
+    );
+    const r = runCli(["router", "validate"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1, out);
+    assert.match(out, /unknown match key/);
+  } finally { await rmRoot(root); }
+});
+
+test("router help: bare `router` prints usage", async () => {
+  const root = await makeBareAgent();
+  try {
+    const r = runCli(["router"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /router why/);
+    assert.match(out, /router validate/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// audit — security-posture audit + attestation (G15)
+// ---------------------------------------------------------------------------
+
+const GOOD_AUDIT_SETTINGS = JSON.stringify({
+  hooks: {
+    PreToolUse: [
+      { matcher: "mcp__claude_ai_Slack__slack_send_message", hooks: [{ type: "command", command: "./scripts/hooks/block-mcp-slack-send.sh" }] },
+      { matcher: "mcp__claude_ai_Gmail__gmail_create_draft", hooks: [{ type: "command", command: "./scripts/hooks/pre-send-audit.sh gmail" }] },
+    ],
+    PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: "./scripts/hooks/post-action-log.sh" }] }],
+    Stop: [{ matcher: "", hooks: [{ type: "command", command: "./scripts/hooks/session-end-log.sh" }] }],
+  },
+}, null, 2);
+
+/** A conformant agent repo (every audit check passes when scoped-perms is set). */
+async function makeConformantAgent() {
+  const root = await makeBareAgent();
+  mkdirSync(join(root, ".claude"), { recursive: true });
+  mkdirSync(join(root, "scripts/hooks"), { recursive: true });
+  mkdirSync(join(root, ".maestro"), { recursive: true });
+  mkdirSync(join(root, "policies"), { recursive: true });
+  // config/agent.json already written by makeBareAgent.
+  const envPath = join(root, ".env");
+  writeFileSync(envPath, "ANTHROPIC_API_KEY=sk-test\nMAESTRO_SCOPED_PERMISSIONS=1\n");
+  chmodSync(envPath, 0o600);
+  writeFileSync(join(root, ".claude/settings.json"), GOOD_AUDIT_SETTINGS);
+  for (const s of ["block-mcp-slack-send.sh", "pre-send-audit.sh", "post-action-log.sh", "session-end-log.sh"]) {
+    writeFileSync(join(root, "scripts/hooks", s), "#!/bin/bash\nexit 0\n");
+  }
+  writeFileSync(join(root, ".maestro/backup-config.yaml"), "enabled: true\nprovider: s3\nbucket: b\n");
+  writeFileSync(join(root, "config/validation-rules.yaml"), "ai_disclosure:\n  enabled: true\n  severity: block\n");
+  writeFileSync(join(root, "policies/action-classification.yaml"), "classes: []\n");
+  return root;
+}
+
+test("audit: a conformant agent exits 0 and reports posture conformant", async () => {
+  const root = await makeConformantAgent();
+  try {
+    const r = runCli(["audit"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 0, out);
+    assert.match(out, /checks passed/);
+    assert.match(out, /attestation:/);
+    assert.match(out, /Posture conformant/);
+  } finally { await rmRoot(root); }
+});
+
+test("audit: a group-readable .env makes the run exit non-zero with the fix", async () => {
+  const root = await makeConformantAgent();
+  try {
+    chmodSync(join(root, ".env"), 0o644);
+    const r = runCli(["audit"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1, out);
+    assert.match(out, /env-mode-600/);
+    assert.match(out, /chmod 600/);
+    assert.match(out, /unsuppressed failure/);
+  } finally { await rmRoot(root); }
+});
+
+test("audit --fix: repairs a group-readable .env and then exits 0", async () => {
+  const root = await makeConformantAgent();
+  try {
+    chmodSync(join(root, ".env"), 0o644);
+    const r = runCli(["audit", "--fix"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 0, out);
+    assert.match(out, /applied 1 safe fix/);
+    assert.equal(statSync(join(root, ".env")).mode & 0o777, 0o600);
+  } finally { await rmRoot(root); }
+});
+
+test("audit: a suppressed-with-reason failure exits 0", async () => {
+  const root = await makeConformantAgent();
+  try {
+    chmodSync(join(root, ".env"), 0o644); // would fail env-mode-600
+    writeFileSync(join(root, "config/audit-suppressions.yaml"),
+      "- id: env-mode-600\n  reason: ephemeral CI runner\n");
+    const r = runCli(["audit"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 0, out);
+    assert.match(out, /SUPPRESSED/);
+    assert.match(out, /ephemeral CI runner/);
+  } finally { await rmRoot(root); }
+});
+
+test("audit --json: emits structured results + a hash-locked attestation", async () => {
+  const root = await makeConformantAgent();
+  try {
+    const r = runCli(["audit", "--json"], root);
+    assert.equal(r.status, 0, r.stderr || r.stdout);
+    const doc = JSON.parse(r.stdout);
+    assert.equal(doc.ok, true);
+    assert.ok(Array.isArray(doc.results) && doc.results.length >= 8);
+    assert.equal(typeof doc.attestation.hash, "string");
+    assert.equal(doc.attestation.schema, "maestro.audit.attestation.v1");
+    assert.equal(doc.attestation.identity.function, "executive-operator");
+  } finally { await rmRoot(root); }
+});
+
+test("audit --json: missing scoped-permissions makes ok:false and exit 1", async () => {
+  const root = await makeConformantAgent();
+  try {
+    writeFileSync(join(root, ".env"), "ANTHROPIC_API_KEY=sk-test\n"); // drop opt-in
+    chmodSync(join(root, ".env"), 0o600);
+    const r = runCli(["audit", "--json"], root);
+    assert.equal(r.status, 1);
+    const doc = JSON.parse(r.stdout);
+    assert.equal(doc.ok, false);
+    const sp = doc.results.find((x) => x.id === "scoped-permissions-configured");
+    assert.equal(sp.ok, false);
+    assert.equal(sp.severity, "critical");
+  } finally { await rmRoot(root); }
+});
+
+test("audit: exits 1 with a clear message outside a Maestro agent dir", async () => {
+  const dir = await tmpRoot("maestro-audit-nonagent");
+  try {
+    const r = runCli(["audit"], dir);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1);
+    assert.match(out, /Not a Maestro agent directory/);
+  } finally { await rmRoot(dir); }
+});
+
+test("audit --help: prints usage and exits 0", async () => {
+  const dir = await tmpRoot("maestro-audit-help");
+  try {
+    const r = runCli(["audit", "--help"], dir);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /maestro audit/);
+    assert.match(r.stdout, /--fix/);
+  } finally { await rmRoot(dir); }
+});
+
+// ---------------------------------------------------------------------------
+// secrets — list / rotate (subcommand, gaps-enterprise-ops G12)
+// ---------------------------------------------------------------------------
+
+test("secrets --help prints usage and exits 0", async () => {
+  const dir = await tmpRoot("maestro-secrets-help");
+  try {
+    const r = runCli(["secrets", "--help"], dir);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /maestro secrets/);
+    assert.match(r.stdout, /names only/);
+  } finally { await rmRoot(dir); }
+});
+
+test("secrets: exits 1 outside a Maestro agent dir", async () => {
+  const dir = await tmpRoot("maestro-secrets-nonagent");
+  try {
+    const r = runCli(["secrets", "list"], dir);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1);
+    assert.match(out, /Not a Maestro agent directory/);
+  } finally { await rmRoot(dir); }
+});
+
+test("secrets rotate then list shows the NAME but never the value", async () => {
+  const root = await makeBareAgent();
+  try {
+    // config/secrets.yaml selects the local file provider.
+    writeFileSync(join(root, "config/secrets.yaml"), "provider: file\n");
+
+    // Rotate a secret with the value supplied on stdin (never in argv).
+    const rot = runCliStdin(["secrets", "rotate", "--name", "DB_PASSWORD"], root, "p@ss-SECRET-123");
+    const rotOut = (rot.stdout || "") + (rot.stderr || "");
+    assert.equal(rot.status, 0, rotOut);
+    assert.match(rotOut, /Rotated "DB_PASSWORD"/);
+
+    // list shows the name...
+    const ls = runCli(["secrets", "list"], root);
+    const lsOut = (ls.stdout || "") + (ls.stderr || "");
+    assert.equal(ls.status, 0, lsOut);
+    assert.match(lsOut, /DB_PASSWORD/);
+    // ...but never the value, in either command's output.
+    assert.ok(!lsOut.includes("p@ss-SECRET-123"), "list must not print the value");
+    assert.ok(!rotOut.includes("p@ss-SECRET-123"), "rotate must not echo the value");
+
+    // The on-disk store is sealed (ciphertext != plaintext).
+    const store = readFileSync(join(root, "state/secrets/.secrets.json"), "utf-8");
+    assert.ok(!store.includes("p@ss-SECRET-123"), "value sealed at rest");
+
+    // The audit log records the name, not the value.
+    const audit = readFileSync(join(root, "logs/audit/secrets.jsonl"), "utf-8");
+    assert.match(audit, /DB_PASSWORD/);
+    assert.ok(!audit.includes("p@ss-SECRET-123"), "audit is names-only");
+  } finally { await rmRoot(root); }
+});
+
+test("secrets rotate without --name exits 1 with usage", async () => {
+  const root = await makeBareAgent();
+  try {
+    const r = runCliStdin(["secrets", "rotate"], root, "v");
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1);
+    assert.match(out, /--name/);
+  } finally { await rmRoot(root); }
+});
+
+test("secrets sync without a configured broker exits 1", async () => {
+  const root = await makeBareAgent();
+  try {
+    writeFileSync(join(root, "config/secrets.yaml"), "provider: file\n");
+    const r = runCli(["secrets", "sync"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.equal(r.status, 1);
+    assert.match(out, /No broker configured/);
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor — backup-config DR check (gaps-enterprise-ops G16)
+// ---------------------------------------------------------------------------
+
+test("doctor RED when no backup target is configured", async () => {
+  const root = await makeBareAgent();
+  try {
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /No backup target configured/);
+    assert.match(out, /backup-config\.yaml/);
+    // doctor exits 1 whenever any issue is found; the missing backup is one.
+    assert.equal(r.status, 1, out);
+  } finally { await rmRoot(root); }
+});
+
+test("doctor GREEN for backup when configured + a fresh successful run is recorded", async () => {
+  const root = await makeBareAgent();
+  try {
+    mkdirSync(join(root, ".maestro"), { recursive: true });
+    writeFileSync(join(root, ".maestro/backup-config.yaml"), "enabled: true\nprovider: s3\nbucket: agent-backups\n");
+    writeFileSync(join(root, ".maestro/last-backup.json"), JSON.stringify({
+      completed_at: new Date().toISOString(), provider: "s3", bucket: "agent-backups",
+    }));
+    const r = runCli(["doctor"], root);
+    const out = (r.stdout || "") + (r.stderr || "");
+    assert.match(out, /Backup configured \+ fresh/);
+    assert.ok(!out.includes("No backup target configured"), "must not flag missing backup when fresh");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// framework-features.json — registry validity + new-system enrollment
+// (registry-scaffold-exports integration lane)
+// ---------------------------------------------------------------------------
+
+test("framework-features.json is valid JSON and registers the new systems", async () => {
+  const raw = readFileSync(join(MAESTRO_ROOT, "framework-features.json"), "utf-8");
+  const reg = JSON.parse(raw); // throws if invalid → test fails
+  assert.ok(reg.features && typeof reg.features === "object", "features map present");
+  const ids = Object.keys(reg.features);
+  // Every new system added by this lane must be enrolled in the registry.
+  for (const id of [
+    "org-cohort", "org-credential-broker", "secrets-lifecycle",
+    "diagnostics-spine", "alerting", "hook-bus", "dynamic-scheduling",
+    "send-gate", "knowledge-plane",
+  ]) {
+    assert.ok(ids.includes(id), `framework-features.json missing feature id: ${id}`);
+  }
+  // Pre-existing core systems still enrolled (no regression).
+  for (const id of ["model-router", "cadence-bus"]) {
+    assert.ok(ids.includes(id), `framework-features.json lost feature id: ${id}`);
+  }
+  // Schema fidelity: each new entry matches the existing feature schema.
+  for (const id of ["org-cohort", "secrets-lifecycle", "diagnostics-spine"]) {
+    const f = reg.features[id];
+    assert.equal(typeof f.version, "string", `${id}.version`);
+    assert.equal(typeof f.since, "string", `${id}.since`);
+    assert.equal(typeof f.title, "string", `${id}.title`);
+    assert.ok(f.init && typeof f.init === "object", `${id}.init`);
+    assert.equal(typeof f.init.auto, "boolean", `${id}.init.auto`);
+    assert.equal(typeof f.init.command, "string", `${id}.init.command`);
+    assert.equal(typeof f.init.description, "string", `${id}.init.description`);
+    // init.command must be a single-line string (feature-init trust-boundary guard).
+    assert.ok(!/[\0\r\n]/.test(f.init.command), `${id}.init.command must be single-line`);
+  }
+  // Honest enablement: org/cohort + its broker default OFF until configured.
+  assert.equal(reg.features["org-cohort"].init.auto, false, "org-cohort must not auto-enroll");
+  assert.equal(reg.features["org-credential-broker"].init.auto, false, "broker must not auto-enable");
+});
+
+// ---------------------------------------------------------------------------
+// create — ships the new disabled-by-default scaffold configs
+// ---------------------------------------------------------------------------
+
+test("create ships disabled-by-default org.yaml + secrets.yaml templates", async () => {
+  const parent = await tmpRoot("maestro-create-cfg");
+  const { env, dir: shim } = await withShim();
+  try {
+    const r = runCli(["create", "cfg-agent"], parent, env);
+    assert.equal(r.status, 0, r.stderr || r.stdout);
+    const agent = join(parent, "cfg-agent");
+
+    const orgYaml = join(agent, "config/org.yaml");
+    const secretsYaml = join(agent, "config/secrets.yaml");
+    assert.ok(existsSync(orgYaml), "config/org.yaml must be scaffolded");
+    assert.ok(existsSync(secretsYaml), "config/secrets.yaml must be scaffolded");
+
+    // org.yaml is disabled by default (the agent runs standalone).
+    const orgBody = readFileSync(orgYaml, "utf-8");
+    assert.match(orgBody, /enabled:\s*false/, "org enrollment must default OFF");
+    assert.match(orgBody, /cohort/);
+
+    // secrets.yaml defaults to the local file provider.
+    const secBody = readFileSync(secretsYaml, "utf-8");
+    assert.match(secBody, /provider:\s*file/, "secrets must default to the local file provider");
+  } finally {
+    await rmRoot(parent);
+    await rmRoot(shim);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// upgrade — propagates new config templates to existing agents (add-only)
+// ---------------------------------------------------------------------------
+
+test("upgrade adds new scaffold config templates without clobbering existing ones", async () => {
+  const root = await makeLegacyAgent();
+  try {
+    // Seed an operator-customised alerts.yaml that upgrade must NOT overwrite.
+    mkdirSync(join(root, "config"), { recursive: true });
+    const customAlerts = "alerts:\n  webhook: https://hooks.example/custom\n";
+    writeFileSync(join(root, "config/alerts.yaml"), customAlerts);
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "seed alerts"], { cwd: root });
+
+    const r = runCli(["upgrade"], root);
+    assert.equal(r.status, 0, r.stderr);
+
+    // New templates landed.
+    assert.ok(existsSync(join(root, "config/org.yaml")), "org.yaml must be delivered on upgrade");
+    assert.ok(existsSync(join(root, "config/secrets.yaml")), "secrets.yaml must be delivered on upgrade");
+    assert.match(readFileSync(join(root, "config/org.yaml"), "utf-8"), /enabled:\s*false/);
+
+    // Existing operator config preserved byte-for-byte.
+    assert.equal(readFileSync(join(root, "config/alerts.yaml"), "utf-8"), customAlerts,
+      "upgrade must not clobber an existing operator config");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// doctor — surfaces the new framework systems
+// ---------------------------------------------------------------------------
+
+test("doctor surfaces the new framework systems (org / secrets / diagnostics)", async () => {
+  // Use a freshly-created agent so lib/* + the scaffold configs are present.
+  const parent = await tmpRoot("maestro-doctor-systems");
+  const { env, dir: shim } = await withShim();
+  try {
+    const cr = runCli(["create", "doc-agent"], parent, env);
+    assert.equal(cr.status, 0, cr.stderr || cr.stdout);
+    const agent = join(parent, "doc-agent");
+    const r = runCli(["doctor"], agent);
+    const out = (r.stdout || "") + (r.stderr || "");
+    // 2.0: the presence-only org line became real connectivity probes; a fresh
+    // (unenrolled) create short-circuits on the single "not enrolled" line.
+    assert.match(out, /Org plane: not enrolled|Org enrollment resolved/);
+    assert.match(out, /Secret lifecycle/);
+    assert.match(out, /Diagnostics spine present/);
+    assert.match(out, /Alerting configured/);
+    // None of the new lib modules should be flagged missing in a fresh create.
+    assert.ok(!/module missing/.test(out), "fresh create must ship every new lib module");
+  } finally {
+    await rmRoot(parent);
+    await rmRoot(shim);
+  }
+});