@cohortapp/agent-sdk 2.17.0 → 2.18.5

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

@@ -1,118 +0,0 @@
-/**
- * orgmail.test.mjs — workspace-email setup section (order 77) tests.
- * Section shape, gate-file write/idempotency, non-blocking verify with an
- * injected fetchImpl (org/messaging section-test pattern).
- * Run: node --test lib/setup/sections/orgmail.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import yaml from "js-yaml";
-
-import orgmail, { readOrgmailConfig, mailboxHint } from "./orgmail.mjs";
-import * as io from "../io.mjs";
-
-const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
-
-// Ambient COHORT_* vars must not leak into hint/enrollment resolution.
-for (const k of ["COHORT_AGENT_EMAIL", "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_ORGMAIL_ENABLED"]) delete process.env[k];
-
-function tmpRoot() {
-  const root = mkdtempSync(join(tmpdir(), "maestro-orgmail-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  return root;
-}
-function ctxFor(root, answers = {}, fetchImpl) {
-  return { agentRoot: root, maestroRoot: MAESTRO_ROOT, flags: { headless: true }, answers, io, fetchImpl };
-}
-function writeOrg(root, cohort) {
-  writeFileSync(join(root, "config", "org.yaml"), yaml.dump({ org: { cohort } }));
-}
-const ENROLLED = { enabled: true, base: "https://org.example", orgId: "acme", token: "tok-1" };
-
-test("section shape: id/order=77/hooks are functions", () => {
-  assert.equal(orgmail.id, "orgmail");
-  assert.equal(orgmail.order, 77);
-  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof orgmail[h], "function");
-});
-
-test("detect: unenrolled org → unconfigured pointing at the org section", async () => {
-  const root = tmpRoot();
-  const d = await orgmail.detect(ctxFor(root));
-  assert.equal(d.status, "unconfigured");
-  assert.match(d.missing[0], /org/);
-});
-
-test("detect: enrolled without a gate file → unconfigured; enabled gate → complete", async () => {
-  const root = tmpRoot();
-  writeOrg(root, ENROLLED);
-  assert.equal((await orgmail.detect(ctxFor(root))).status, "unconfigured");
-  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
-  assert.equal((await orgmail.detect(ctxFor(root))).status, "complete");
-  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: false } }));
-  assert.equal((await orgmail.detect(ctxFor(root))).status, "partial");
-});
-
-test("apply: writes the gate file with defaults; idempotent; preserves operator overrides", async () => {
-  const root = tmpRoot();
-  writeOrg(root, ENROLLED);
-  await orgmail.apply(ctxFor(root, { orgmailEnabled: true }));
-  const first = await readOrgmailConfig(root);
-  assert.deepEqual(first, { enabled: true, poll_seconds: 45, mark_read: true });
-  // Operator tunes the cadence; re-apply must not clobber it.
-  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true, poll_seconds: 120, mark_read: false } }));
-  await orgmail.apply(ctxFor(root, { orgmailEnabled: true }));
-  const second = await readOrgmailConfig(root);
-  assert.deepEqual(second, { enabled: true, poll_seconds: 120, mark_read: false });
-});
-
-test("mailboxHint: env wins, else config/agent.json agentEmail/email, else empty", () => {
-  const root = tmpRoot();
-  assert.equal(mailboxHint(root, {}), "");
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ email: "astra@agents.example" }));
-  assert.equal(mailboxHint(root, {}), "astra@agents.example");
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify({ agentEmail: "astra@corp.example", email: "x@y.z" }));
-  assert.equal(mailboxHint(root, {}), "astra@corp.example", "agentEmail (the MemberProfileDTO field) preferred");
-  assert.equal(mailboxHint(root, { COHORT_AGENT_EMAIL: "hint@env.example" }), "hint@env.example");
-});
-
-test("verify: missing gate file fails with a remedy; dormant enrollment stays ok-with-remedy", async () => {
-  const root = tmpRoot();
-  const v = await orgmail.verify(ctxFor(root));
-  assert.equal(v.ok, false);
-  assert.match(v.checks[0].remedy, /setup --only orgmail/);
-  // gate present but org unenrolled → dormant (ok:true, remedy points at enrollment)
-  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
-  const v2 = await orgmail.verify(ctxFor(root));
-  assert.equal(v2.ok, true);
-  assert.match(v2.checks.at(-1).name, /dormant/);
-});
-
-test("verify: enrolled probe — reachable mailbox surfaces the address; failure WARNS, never hard-fails", async () => {
-  const root = tmpRoot();
-  writeOrg(root, ENROLLED);
-  writeFileSync(join(root, "config", "orgmail.yaml"), yaml.dump({ orgmail: { enabled: true } }));
-
-  const okFetch = async (url) => ({ ok: true, status: 200, headers: { get: () => undefined }, json: async () => ({ ok: true, result: { mailbox: { address: "astra@agents.example" }, messages: [] } }) });
-  const v = await orgmail.verify(ctxFor(root, {}, okFetch));
-  assert.equal(v.ok, true);
-  assert.match(v.checks.at(-1).name, /astra@agents\.example/);
-
-  const notFound = async () => ({ ok: false, status: 404, headers: { get: () => undefined }, json: async () => ({ ok: false, error: { code: "NOT_FOUND", message: "no mailbox for member" } }) });
-  const v2 = await orgmail.verify(ctxFor(root, {}, notFound));
-  assert.equal(v2.ok, true, "no-mailbox-yet is a WARN (admin's Settings → Email job), not a wizard failure");
-  assert.match(v2.checks.at(-1).remedy, /Settings → Email/);
-});
-
-test("prompt: headless ctx takes the default (enable) without touching the TTY", async () => {
-  const root = tmpRoot();
-  writeOrg(root, ENROLLED);
-  const ctx = ctxFor(root);
-  await orgmail.prompt(ctx);
-  assert.equal(ctx.answers.orgmailEnabled, true);
-});

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

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

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

@@ -1,429 +0,0 @@
-/**
- * subagents.test.mjs — the sub-agent registry init step (order 40).
- *
- * §6 names the degradation branches as the least-exercised path in the design,
- * so they are tested explicitly here — cold cache, a 500 from hq, a timeout and
- * a missing env — not just the happy path. The contract that makes them matter:
- * a throw in `apply` is FATAL to the whole wizard (lib/setup/runner.mjs:220-227).
- *
- * Run: node --test lib/setup/sections/subagents.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import section, { HEADLESS_SAFE, assess, planActions, readAgentConfig, resolveRoster } from "./subagents.mjs";
-import * as io from "../io.mjs";
-import { buildManifest, writeManifest } from "../../subagents/manifest.mjs";
-import { readGaps, readLock, writeCache } from "../../subagents/lock.mjs";
-import { agentFilePath } from "../../subagents/resolve.mjs";
-import { stringifyAgentMd } from "../../subagents/schema.mjs";
-
-const ENV = { COHORT_BASE: "https://hq.example.com", COHORT_API_KEY: "sk-test", COHORT_ORG_ID: "org_1" };
-
-function md(slug, body = `# ${slug}\n\nsdk body\n`, over = {}) {
-  return stringifyAgentMd({ name: slug, description: `${slug} does things`, model: "sonnet", tools: ["Read"], ...over }, body);
-}
-function put(root, slug, text) {
-  mkdirSync(join(root, "agents", slug), { recursive: true });
-  writeFileSync(join(root, "agents", slug, "agent.md"), text);
-  return text;
-}
-function sdkWith(slugs) {
-  const root = mkdtempSync(join(tmpdir(), "subagent-sec-sdk-"));
-  for (const s of slugs) put(root, s, md(s));
-  writeManifest(root, buildManifest({ maestroRoot: root, sdkVersion: "9.9.9" }).manifest);
-  return root;
-}
-function agentRepo(cfg = { firstName: "Isla", function: "executive-operator", altitude: "c-suite" }) {
-  const root = mkdtempSync(join(tmpdir(), "subagent-sec-agent-"));
-  mkdirSync(join(root, "config"), { recursive: true });
-  mkdirSync(join(root, "workflows"), { recursive: true });
-  writeFileSync(join(root, "config", "agent.json"), JSON.stringify(cfg));
-  return root;
-}
-function fakeFetch(reply) {
-  const calls = [];
-  const fn = async (url, init) => {
-    calls.push({ url: String(url), body: init && init.body ? JSON.parse(init.body) : null });
-    const r = typeof reply === "function" ? reply(String(url), calls.length) : reply;
-    if (r instanceof Error) throw r;
-    return { ok: r.ok !== false, status: r.status || 200, json: async () => r.body };
-  };
-  fn.calls = calls;
-  return fn;
-}
-const okFrame = (result) => ({ ok: true, status: 200, body: { ok: true, result } });
-const surface = (ids) => async () => ({ standardAgents: ids.map((id) => ({ id, role: id })), roleAgents: [] });
-
-function ctxFor(agentRoot, maestroRoot, extra = {}) {
-  return {
-    agentRoot, maestroRoot, io,
-    flags: { headless: true },
-    answers: {},
-    env: {},
-    ...extra,
-  };
-}
-/** Silence io.note for the duration of a call — the wizard is chatty by design. */
-async function quiet(fn) {
-  const log = console.log;
-  console.log = () => {};
-  try { return await fn(); } finally { console.log = log; }
-}
-
-// ---------------------------------------------------------------------------
-// contract
-// ---------------------------------------------------------------------------
-
-test("section shape: id/label/order=40 and the four hooks", () => {
-  assert.equal(section.id, "subagents");
-  assert.equal(section.label, "Sub-agents");
-  assert.equal(section.order, 40, "the lowest free slot: before tools (50) and operating-model (60)");
-  for (const h of ["detect", "prompt", "apply", "verify"]) assert.equal(typeof section[h], "function");
-});
-
-test("HEADLESS_SAFE: only the two unambiguous adoptions — never create/fork", () => {
-  assert.deepEqual([...HEADLESS_SAFE].sort(), ["adopt-sdk", "adopt-workspace"]);
-  for (const v of ["create", "fork", "rewire", "drop-workflow-step"]) assert.equal(HEADLESS_SAFE.has(v), false);
-});
-
-test("readAgentConfig: fail-open on missing/corrupt config", () => {
-  assert.deepEqual(readAgentConfig(mkdtempSync(join(tmpdir(), "cfg-"))), {});
-  const root = agentRepo();
-  writeFileSync(join(root, "config", "agent.json"), "{ nope");
-  assert.deepEqual(readAgentConfig(root), {});
-});
-
-test("resolveRoster: injected surface wins; a throwing surface fails open to []", async () => {
-  const cfg = { function: "executive-operator", altitude: "c-suite" };
-  assert.deepEqual((await resolveRoster({ resolveSurfaceImpl: surface(["alpha"]) }, cfg)).map((a) => a.id), ["alpha"]);
-  assert.deepEqual(await resolveRoster({ resolveSurfaceImpl: async () => { throw new Error("boom"); } }, cfg), []);
-  assert.deepEqual(await resolveRoster({}, {}), [], "no function/altitude → no authoritative roster");
-});
-
-// ---------------------------------------------------------------------------
-// detect — non-blocking, no input, NO NETWORK
-// ---------------------------------------------------------------------------
-
-test("detect: never touches the network, even when the agent IS enrolled", async () => {
-  // It runs under --headless, doctor and CI. Everything it needs is on disk.
-  const f = fakeFetch(okFrame({ rosterVersion: 1, entries: [] }));
-  const ctx = ctxFor(agentRepo(), sdkWith(["alpha"]), { env: ENV, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha"]) });
-  await section.detect(ctx);
-  assert.deepEqual(f.calls, []);
-});
-
-test("detect: complete when everything resolves and nothing dangles", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: alpha\n");
-  const det = await section.detect(ctxFor(agent, sdkWith(["alpha"]), { resolveSurfaceImpl: surface(["alpha"]) }));
-  assert.equal(det.status, "complete");
-  assert.match(det.summary, /1 sub-agents resolved/);
-  assert.match(det.summary, /workspace layer off — not enrolled/, "an un-enrolled agent is a legitimate steady state");
-});
-
-test("detect: partial lists missing slugs AND dangling refs, capped", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: ghost-writer\n");
-  const det = await section.detect(ctxFor(agent, sdkWith(["alpha"]), { resolveSurfaceImpl: surface(["alpha", "beta"]) }));
-  assert.equal(det.status, "partial");
-  assert.ok(det.missing.includes("missing: beta"));
-  assert.ok(det.missing.includes("dangling ref: ghost-writer"));
-  assert.ok(det.missing.length <= 12);
-});
-
-test("detect: unconfigured when the roster is known and NOTHING resolves", async () => {
-  const det = await section.detect(ctxFor(agentRepo(), sdkWith([]), { resolveSurfaceImpl: surface(["alpha"]) }));
-  assert.equal(det.status, "unconfigured");
-});
-
-// ---------------------------------------------------------------------------
-// planActions
-// ---------------------------------------------------------------------------
-
-test("planActions: workspace pin → adopt-workspace, SDK → adopt-sdk, neither → defer", async () => {
-  const agent = agentRepo();
-  const sdk = sdkWith(["from-sdk"]);
-  const a = await assess(ctxFor(agent, sdk, { resolveSurfaceImpl: surface(["from-sdk", "pinned", "nowhere"]) }), { network: false });
-  a.pins = [{ slug: "pinned" }];
-  a.gaps.missing = [{ slug: "from-sdk" }, { slug: "pinned" }, { slug: "nowhere" }];
-  const plan = planActions(a);
-  assert.deepEqual(plan.filter((p) => ["from-sdk", "pinned", "nowhere"].includes(p.slug)).map((p) => [p.slug, p.action]),
-    [["from-sdk", "adopt-sdk"], ["pinned", "adopt-workspace"], ["nowhere", "defer"]]);
-});
-
-test("planActions: create/fork are NEVER a default — both mint a row in hq", () => {
-  const plan = planActions({
-    resolved: { bySlug: new Map(), entries: [] },
-    manifest: { agents: {} },
-    pins: [],
-    gaps: { missing: [{ slug: "nowhere" }] },
-  });
-  assert.deepEqual(plan.map((p) => p.action), ["defer"]);
-});
-
-test("planActions: a resolved winner that is not yet on disk is an adoption", async () => {
-  const a = await assess(ctxFor(agentRepo(), sdkWith(["alpha"]), { resolveSurfaceImpl: surface([]) }), { network: false });
-  assert.deepEqual(planActions(a), [{ slug: "alpha", action: "adopt-sdk", reason: "resolved from sdk but not on disk" }]);
-});
-
-// ---------------------------------------------------------------------------
-// apply — happy path
-// ---------------------------------------------------------------------------
-
-test("apply: materialises every winner, records the lock, and is idempotent", async () => {
-  const agent = agentRepo();
-  const sdk = sdkWith(["alpha", "beta"]);
-  const ctx = ctxFor(agent, sdk, { resolveSurfaceImpl: surface(["alpha", "beta"]) });
-
-  await quiet(() => section.apply(ctx));
-  assert.equal(existsSync(agentFilePath(agent, "alpha")), true);
-  const lock = readLock(agent);
-  assert.equal(lock.agents.alpha.layer, "sdk");
-  assert.ok(lock.agents.alpha.fileHash);
-
-  const before = readFileSync(agentFilePath(agent, "alpha"), "utf8");
-  await quiet(() => section.apply(ctx));
-  assert.equal(readFileSync(agentFilePath(agent, "alpha"), "utf8"), before, "a second apply changes nothing");
-});
-
-test("apply: the workspace layer wins and the roster version lands in the lock", async () => {
-  const agent = agentRepo();
-  const sdk = sdkWith(["alpha"]);
-  const f = fakeFetch(okFrame({
-    rosterVersion: 42,
-    entries: [{ slug: "alpha", definitionId: "d1", version: 5, contentHash: "h", frontmatter: { name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, body: "# alpha\n\nWORKSPACE\n" }],
-  }));
-  await quiet(() => section.apply(ctxFor(agent, sdk, { env: ENV, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha"]) })));
-  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /WORKSPACE/);
-  assert.equal(readLock(agent).rosterVersion, 42);
-});
-
-test("apply: a local edit survives — the wizard never force-overwrites", async () => {
-  const agent = agentRepo();
-  const mine = put(agent, "alpha", md("alpha", "# alpha\n\nMINE\n"));
-  await quiet(() => section.apply(ctxFor(agent, sdkWith(["alpha"]), { resolveSurfaceImpl: surface(["alpha"]) })));
-  assert.equal(readFileSync(agentFilePath(agent, "alpha"), "utf8"), mine);
-});
-
-// ---------------------------------------------------------------------------
-// apply — the degradation branches (§6: the least-exercised path)
-// ---------------------------------------------------------------------------
-
-test("apply degradation: a 500 from hq returns NORMALLY and records degraded", async () => {
-  const agent = agentRepo();
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), {
-    env: ENV,
-    subagentFetchImpl: fakeFetch({ ok: false, status: 500, body: { ok: false, error: { code: "INTERNAL", message: "boom" } } }),
-    resolveSurfaceImpl: surface(["alpha"]),
-  });
-  await quiet(() => section.apply(ctx));
-  assert.deepEqual(readLock(agent).degraded, ["workspace"]);
-  assert.equal(existsSync(agentFilePath(agent, "alpha")), true, "…and the SDK layer still materialises");
-});
-
-test("apply degradation: a timeout returns NORMALLY and records degraded", async () => {
-  // The 5 s AbortController path itself is exercised in
-  // lib/subagents/client.test.mjs with an injected 20 ms budget; here we hand
-  // the section the AbortError that path produces, so the section's own
-  // degradation branch is covered without five seconds of wall clock.
-  const agent = agentRepo();
-  const timedOut = fakeFetch(Object.assign(new Error("timeout after 5000ms"), { name: "AbortError" }));
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), { env: ENV, subagentFetchImpl: timedOut, resolveSurfaceImpl: surface(["alpha"]) });
-  await quiet(() => section.apply(ctx));
-  assert.deepEqual(readLock(agent).degraded, ["workspace"]);
-  assert.equal(existsSync(agentFilePath(agent, "alpha")), true, "the SDK layer still materialises");
-});
-
-test("apply degradation: a connection refusal returns NORMALLY", async () => {
-  const agent = agentRepo();
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), { env: ENV, subagentFetchImpl: fakeFetch(new Error("ECONNREFUSED")), resolveSurfaceImpl: surface(["alpha"]) });
-  await quiet(() => section.apply(ctx));
-  assert.deepEqual(readLock(agent).degraded, ["workspace"]);
-});
-
-test("apply degradation: MISSING env is not degradation — layer 1 simply does not exist", async () => {
-  const agent = agentRepo();
-  const f = fakeFetch(okFrame({}));
-  await quiet(() => section.apply(ctxFor(agent, sdkWith(["alpha"]), { env: {}, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha"]) })));
-  assert.deepEqual(f.calls, [], "an un-enrolled agent must not attempt a call");
-  assert.deepEqual(readLock(agent).degraded, []);
-  assert.equal(existsSync(agentFilePath(agent, "alpha")), true);
-});
-
-test("apply degradation: COLD CACHE + offline still resolves the workspace pin from the lock", async () => {
-  const agent = agentRepo();
-  const sdk = sdkWith(["alpha"]);
-  // Pretend a previous online run pinned alpha at v3 and cached its body.
-  const { mergeLock } = await import("../../subagents/lock.mjs");
-  mergeLock(agent, { agents: { alpha: { layer: "workspace", definitionId: "d1", version: 3, contentHash: "h" } } });
-  writeCache(agent, "alpha", 3, stringifyAgentMd({ name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, "# alpha\n\nCACHED\n"));
-
-  await quiet(() => section.apply(ctxFor(agent, sdk, { env: ENV, subagentFetchImpl: fakeFetch(new Error("offline")), resolveSurfaceImpl: surface(["alpha"]) })));
-  assert.match(readFileSync(agentFilePath(agent, "alpha"), "utf8"), /CACHED/, "not silently demoted to the SDK body");
-});
-
-test("apply degradation: even a failing ASSESSMENT does not abort the wizard", async () => {
-  const agent = agentRepo();
-  const ctx = ctxFor(agent, sdkWith(["alpha"]));
-  // A throw here would kill the whole setup run (runner.mjs:220-227).
-  Object.defineProperty(ctx, "subagentCfg", { get() { throw new Error("exploded"); } });
-  await quiet(() => section.apply(ctx));
-  assert.deepEqual(readLock(agent).degraded, ["assessment"]);
-});
-
-// ---------------------------------------------------------------------------
-// apply — headless safety
-// ---------------------------------------------------------------------------
-
-test("apply headless: NEVER creates or forks unattended, and leaves a gaps report", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: ghost-writer\n");
-  const f = fakeFetch(okFrame({ definitionId: "d1", version: 1 }));
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), {
-    env: ENV, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha", "beta"]),
-    answers: { subagentChoices: { beta: "create", alpha: "fork" } },
-  });
-
-  await quiet(() => section.apply(ctx));
-  assert.deepEqual(f.calls.filter((c) => /create|fork|pin/.test(c.url)), [], "no row is minted without a human");
-
-  const gaps = readGaps(agent);
-  assert.ok(gaps, "state/subagents/gaps.json is the headless verdict");
-  assert.deepEqual(gaps.missing.map((m) => m.slug), ["beta"]);
-  assert.ok(gaps.plan.length >= 1);
-  assert.match(gaps.summary, /missing/);
-});
-
-test("apply: a drop verdict records the accepted drop and NEVER edits the workflow", async () => {
-  const agent = agentRepo();
-  const wf = join(agent, "workflows", "w.yaml");
-  const original = "steps:\n  - agent: ghost-writer\n";
-  writeFileSync(wf, original);
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), {
-    resolveSurfaceImpl: surface(["alpha"]),
-    answers: { subagentChoices: { "ref:ghost-writer": "drop-workflow-step" } },
-  });
-
-  await quiet(() => section.apply(ctx));
-  assert.equal(readFileSync(wf, "utf8"), original, "a workflow step's removal changes runtime behaviour — a human owns that diff");
-  const drop = readLock(agent).acceptedDrops[0];
-  assert.equal(drop.ref, "ghost-writer");
-  assert.equal(drop.file, "workflows/w.yaml");
-  assert.equal(drop.line, 2, "file:line is recorded so the operator knows exactly what to delete");
-});
-
-test("apply: a rewire verdict is advice only — nothing on disk changes", async () => {
-  const agent = agentRepo();
-  const wf = join(agent, "workflows", "w.yaml");
-  writeFileSync(wf, "steps:\n  - agent: ghost-writer\n");
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), {
-    resolveSurfaceImpl: surface(["alpha"]),
-    answers: { subagentChoices: { "ref:ghost-writer": "rewire:alpha" } },
-  });
-  await quiet(() => section.apply(ctx));
-  assert.equal(readFileSync(wf, "utf8"), "steps:\n  - agent: ghost-writer\n");
-  assert.deepEqual(readLock(agent).acceptedDrops, []);
-});
-
-// ---------------------------------------------------------------------------
-// prompt
-// ---------------------------------------------------------------------------
-
-test("prompt: records the assessment and the per-slug verdicts (headless answers)", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: ghost-writer\n");
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), {
-    resolveSurfaceImpl: surface(["alpha", "beta"]),
-    answers: { "subagent.beta": "defer", "subagent.ref.ghost-writer": "drop-workflow-step" },
-  });
-  await quiet(() => section.prompt(ctx));
-  assert.deepEqual(ctx.answers.subagentAssessment.counts.missing, 1);
-  assert.equal(ctx.answers.subagentChoices.beta, "defer");
-  assert.equal(ctx.answers.subagentChoices["ref:ghost-writer"], "drop-workflow-step");
-});
-
-test("prompt: nothing to decide → no choices are recorded", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: alpha\n");
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), { resolveSurfaceImpl: surface(["alpha"]) });
-  await quiet(() => section.prompt(ctx));
-  assert.equal(ctx.answers.subagentChoices, undefined);
-});
-
-// ---------------------------------------------------------------------------
-// verify — pure local
-// ---------------------------------------------------------------------------
-
-test("verify: a materialised repo passes every check", async () => {
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: alpha\n");
-  const ctx = ctxFor(agent, sdkWith(["alpha"]), { resolveSurfaceImpl: surface(["alpha"]) });
-  await quiet(() => section.apply(ctx));
-  const v = await section.verify(ctx);
-  assert.equal(v.ok, true, JSON.stringify(v.checks));
-  assert.ok(v.checks.length >= 3);
-});
-
-test("verify: an INVALID on-disk definition fails the first check", async () => {
-  const agent = agentRepo();
-  put(agent, "alpha", md("alpha", "# alpha\n\nb\n", { name: "wrong-name" }));
-  const v = await section.verify(ctxFor(agent, sdkWith([]), { resolveSurfaceImpl: surface([]) }));
-  const c = v.checks[0];
-  assert.equal(c.ok, false);
-  assert.match(c.remedy, /must equal the directory name/);
-  assert.equal(v.ok, false);
-});
-
-test("verify: a lock entry pointing at a file that no longer exists is a broken lock", async () => {
-  const agent = agentRepo();
-  const { mergeLock } = await import("../../subagents/lock.mjs");
-  mergeLock(agent, { agents: { vanished: { layer: "sdk", fileHash: "h" } } });
-  const v = await section.verify(ctxFor(agent, sdkWith([]), { resolveSurfaceImpl: surface([]) }));
-  const c = v.checks.find((x) => x.name.startsWith("lock matches disk"));
-  assert.equal(c.ok, false);
-  assert.match(c.remedy, /subagents pull/);
-});
-
-test("verify: dangling references WARN but never fail (a fresh agent starts with ~15)", async () => {
-  // `create` copies maestro's own workflows verbatim, so hard-failing here would
-  // make every new agent's setup red on day one.
-  const agent = agentRepo();
-  writeFileSync(join(agent, "workflows", "w.yaml"), "steps:\n  - agent: ghost-writer\n  - agent: another-ghost\n");
-  const v = await section.verify(ctxFor(agent, sdkWith([]), { resolveSurfaceImpl: surface([]) }));
-  const c = v.checks.find((x) => x.name.startsWith("sub-agent references resolve"));
-  assert.equal(c.ok, true);
-  assert.match(c.name, /2 dangling/);
-  assert.match(c.remedy, /subagents status/);
-  assert.equal(v.ok, true);
-});
-
-test("verify: never touches the network", async () => {
-  const f = fakeFetch(okFrame({}));
-  const ctx = ctxFor(agentRepo(), sdkWith(["alpha"]), { env: ENV, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha"]) });
-  await section.verify(ctx);
-  assert.deepEqual(f.calls, []);
-});
-
-// ---------------------------------------------------------------------------
-// assess
-// ---------------------------------------------------------------------------
-
-test("assess: network:false never calls out; network:true does", async () => {
-  const agent = agentRepo();
-  const sdk = sdkWith(["alpha"]);
-  const f = fakeFetch(okFrame({ rosterVersion: 2, entries: [] }));
-  const ctx = ctxFor(agent, sdk, { env: ENV, subagentFetchImpl: f, resolveSurfaceImpl: surface(["alpha"]) });
-
-  await assess(ctx, { network: false });
-  assert.deepEqual(f.calls, []);
-  const on = await assess(ctx, { network: true });
-  assert.deepEqual(f.calls.map((c) => c.url.split("/v1/")[1]), ["subagent.resolve"]);
-  assert.equal(on.rosterVersion, 2);
-  assert.deepEqual(on.degraded, []);
-});