@cohortapp/agent-sdk 2.3.1 → 2.4.0

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

@@ -0,0 +1,429 @@
+/**
+ * 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, []);
+});

package/lib/setup/sections/verify.mjs

@@ -17,10 +17,120 @@
 
 "use strict";
 
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { probeClaude } from "../claude-probe.mjs";
 import { assertComplete } from "../completeness.mjs";
 import * as io from "../io.mjs";
 
+/** Freshness ceiling for the mandate cache (SPEC §6.4: < 24h is "full"). */
+export const MANDATE_FRESH_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The four INIT-pipeline checks (SPEC §5.8). Split out of verify() so they are
+ * unit-testable with injected fakes and so a caller can run them alone.
+ *
+ * These are SOFT by design — an agent whose human has not yet adopted any
+ * objective legitimately has no plan and no mandate cache, and setup must not
+ * exit non-zero for that. But every degradation is NAMED with a remedy: a
+ * silently absent plan is exactly the failure mode this whole design exists to
+ * prevent.
+ *
+ * @param {object} o - { agentRoot, now? }
+ * @param {object} [deps] - { existsSync, readFileSync, yaml, readManifest, readLock, readCache }
+ * @returns {Promise<Array<{name,ok,remedy?}>>}
+ */
+export async function planChecks(o = {}, deps = {}) {
+  const agentRoot = o.agentRoot;
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const ex = deps.existsSync || existsSync;
+  const rd = deps.readFileSync || readFileSync;
+  const checks = [];
+
+  const planPath = join(agentRoot, "config", "plan.yaml");
+  if (!ex(planPath)) {
+    checks.push({ name: "plan compiled (config/plan.yaml)", ok: true, remedy: "no compiled plan — the agent runs standard + archetype cadences only; run `maestro setup --only mandate`" });
+    return checks;
+  }
+
+  let plan = null;
+  try {
+    const yaml = deps.yaml || (await import("js-yaml").then((m) => m.default || m));
+    plan = yaml.load(rd(planPath, "utf-8"));
+  } catch (e) {
+    checks.push({ name: "plan compiled (config/plan.yaml)", ok: false, remedy: `config/plan.yaml is unreadable (${e && e.message ? e.message : e}) — re-run \`node scripts/setup/generate-plan.mjs\`` });
+    return checks;
+  }
+  const obligations = (plan && plan.obligations) || [];
+  checks.push({ name: `plan compiled: ${obligations.length} obligations`, ok: !!plan && obligations.length > 0, remedy: obligations.length ? undefined : "plan.yaml has no obligations — re-run `node scripts/setup/generate-plan.mjs`" });
+
+  // 1. hashes match the compile lock (a hand-edited plan.yaml is drift).
+  let lock = null;
+  try {
+    const emit = deps.readLock ? { readLock: deps.readLock } : await import("../../plan/emit.mjs");
+    lock = emit.readLock(agentRoot, deps);
+  } catch { lock = null; }
+  const hashOk = !!(lock && plan && lock.obligationsHash && lock.obligationsHash === plan.obligationsHash);
+  checks.push({
+    name: "obligationsHash matches state/plan/compile.lock",
+    ok: hashOk,
+    remedy: hashOk ? undefined : (lock ? "config/plan.yaml was edited by hand or is stale — re-run `node scripts/setup/generate-plan.mjs`" : "no state/plan/compile.lock — re-run `node scripts/setup/generate-plan.mjs`"),
+  });
+
+  // 2. zero obligations citing an unreachable capability. This is THE law the
+  //    inventory step establishes; a violation means the plan promises work the
+  //    agent cannot actually do.
+  let manifest = null;
+  try {
+    const inv = deps.readManifest ? { readManifest: deps.readManifest } : await import("../../capability/inventory.mjs");
+    manifest = inv.readManifest(agentRoot, deps);
+  } catch { manifest = null; }
+  if (manifest) {
+    const reachable = new Set((manifest.entries || []).filter((e) => e && e.reachable).map((e) => e.id));
+    const offenders = [];
+    for (const ob of obligations) {
+      for (const u of ob.uses || []) if (!reachable.has(u)) offenders.push(`${ob.key} → ${u}`);
+    }
+    checks.push({
+      name: `no obligation cites an unreachable capability (${offenders.length} violation(s))`,
+      ok: offenders.length === 0,
+      remedy: offenders.length ? `unreachable: ${offenders.slice(0, 5).join(", ")}${offenders.length > 5 ? ` (+${offenders.length - 5} more)` : ""} — re-run the inventory section, then recompile` : undefined,
+    });
+  } else {
+    checks.push({ name: "no obligation cites an unreachable capability", ok: false, remedy: "no config/capability-manifest.json — run `maestro setup --only inventory`" });
+  }
+
+  // 3. zero OUTCOME obligations resting on an LLM-sourced sensor. An llm sample
+  //    is advisory and may never close the loop into created work (§6.3 honesty gate).
+  const llmSensors = obligations.filter((ob) => ob.kind === "OUTCOME" && ob.sensor && ob.sensor.source && ob.sensor.source !== "method");
+  checks.push({
+    name: `every OUTCOME has a method sensor (${llmSensors.length} advisory)`,
+    ok: llmSensors.length === 0,
+    remedy: llmSensors.length ? `${llmSensors.map((o2) => o2.key).slice(0, 5).join(", ")} rest on a non-method sensor — they cannot create work; bind a reachable capability or retire them` : undefined,
+  });
+
+  // 4. mandate cache freshness (< 24h). Past 24h Loop C suspends; past 7d the
+  //    daemon idles (§6.4). Soft here, because an un-enrolled agent has no cache.
+  let cache = null;
+  try {
+    const cm = deps.readCache ? { readCache: deps.readCache } : await import("../../mandate/cache.mjs");
+    cache = cm.readCache(agentRoot, deps);
+  } catch { cache = null; }
+  if (!cache) {
+    checks.push({ name: "mandate cache present", ok: true, remedy: "no state/mandate/cache.json — the agent has no adopted mandate yet; propose objectives with `maestro setup --only mandate`" });
+  } else {
+    const age = now - Date.parse(cache.fetchedAt || 0);
+    const fresh = Number.isFinite(age) && age < MANDATE_FRESH_MS;
+    checks.push({
+      name: `mandate cache fresh (${Number.isFinite(age) ? `${Math.round(age / 3600000)}h` : "unknown"} old)`,
+      ok: fresh,
+      remedy: fresh ? undefined : "mandate cache is >24h old — self-directed work is suspended until it refreshes (`mandate.get`)",
+    });
+  }
+
+  return checks;
+}
+
 export default {
   id: "verify",
   label: "Verification & capability summary",
@@ -58,6 +168,17 @@ export default {
     const complete = await assertComplete(ctx.agentRoot);
     const probe = probeClaude(ctx.agentRoot);
 
+    // INIT-pipeline gate (SPEC §5.8): the plan compiles, its hashes match, it
+    // cites nothing unreachable, no OUTCOME rests on an LLM sensor, and the
+    // mandate cache is fresh. Soft-fail, but every degradation is named.
+    try {
+      for (const c of await planChecks({ agentRoot: ctx.agentRoot }, (ctx.planDeps || {}))) {
+        rows.push({ section: "plan", ...c });
+      }
+    } catch (e) {
+      rows.push({ section: "plan", name: "plan checks", ok: false, remedy: `plan verification threw: ${e && e.message ? e.message : e}` });
+    }
+
     // Hard-fail conditions.
     const noIdentity = complete.missing.some((m) => m.artifact === "config/agent.json");
     const archetypeOk = complete.archetypeOk;