@cohortapp/agent-sdk 2.4.1 → 2.5.0

package/lib/plan/compile.mjs

@@ -40,6 +40,7 @@
 
 import { createHash } from "node:crypto";
 import { canonical } from "../mandate/cache.mjs";
+import { assertMandateContract } from "../mandate/contract.mjs";
 
 /** Bump when emission rules change — it is part of `inputsHash`. */
 export const COMPILER_VERSION = 1;
@@ -211,7 +212,13 @@ export function busyWindows(events = []) {
  * Compile the plan.
  *
  * @param {object} input
- * @param {object} input.mandate           the cached mandate BODY ({objectives, budgetCentsPerPeriod, reactsTo, collaborators})
+ * @param {import("../mandate/contract.mjs").MandateBody} input.mandate
+ *        the cached mandate BODY — see `lib/mandate/contract.mjs`, which is the
+ *        canonical shape and is mirrored in hq at `methods/mandate/_contract.ts`
+ * @param {(level:string,msg:string)=>void} [input.log]
+ *        where contract violations and unmetered obligations are announced. Pass
+ *        it: a silent degradation here is the exact bug this joint closed.
+ * @param {number} [input.seatBudgetCents] overrides `mandate.seatBudgetCents`
  * @param {number} [input.mandateVersion]
  * @param {object} input.manifest          the capability manifest
  * @param {object} [input.profile]         resolved archetype profile (for the hash + altitude)
@@ -220,7 +227,7 @@ export function busyWindows(events = []) {
  * @param {object[]} [input.archetypeCadences] resolved function+altitude cadences (scope !== "standard")
  * @param {object[]} [input.calendarEvents]  [{weekday,hour}] busy windows
  * @param {number} [input.concurrency=2]
- * @returns {{obligations:object[], inputsHash:string, obligationsHash:string, compilerVersion:number, mandateVersion:number, drift:object[], counts:object}}
+ * @returns {{obligations:object[], inputsHash:string, obligationsHash:string, compilerVersion:number, mandateVersion:number, drift:object[], counts:object, warnings:string[], contract:object}}
  */
 export function compilePlan(input = {}) {
   const mandate = input.mandate && typeof input.mandate === "object" ? input.mandate : {};
@@ -231,8 +238,52 @@ export function compilePlan(input = {}) {
   const drift = [];
   const obligations = [];
 
-  const defaultBudget = Number.isFinite(mandate.budgetCentsPerPeriod) ? mandate.budgetCentsPerPeriod : 500;
-  const seatEnvelope = Number.isFinite(input.seatBudgetCents) ? input.seatBudgetCents : defaultBudget * 20;
+  // ── THE MONEY, AND WHERE IT COMES FROM ──────────────────────────────────
+  // Every figure below is either a number hq published or `null`. There is no
+  // third option and there is no default. The previous `: 500` / `* 20` pair is
+  // the bug this joint closed: hq never emitted `budgetCentsPerPeriod` at all,
+  // `Number.isFinite(undefined)` was false, and the entire fleet compiled every
+  // obligation at a 500c allowance against a 10000c envelope that no column
+  // anywhere had ever produced. It never errored, so it ran for as long as it
+  // ran. A fabricated number is not a safe default — it is a silent one.
+  const warnings = [];
+  const log = typeof input.log === "function"
+    ? input.log
+    // FAIL-OPEN, NEVER FAIL-SILENT. A caller that passes no logger still gets the
+    // degradation on stderr; it does not get to make it disappear.
+    : (level, msg) => { (level === "error" ? console.error : console.warn)(msg); };
+  const note = (level, msg) => { warnings.push(msg); log(level, msg); };
+
+  const contract = assertMandateContract(mandate, (level, msg) => { warnings.push(msg); log(level, msg); }, "compilePlan");
+
+  // A body missing a required key is a PRE-CONTRACT body. It is announced as an
+  // ERROR and surfaced on `plan.contract` — but note what is NOT done here: the
+  // numbers it DOES carry are still used. An explicit figure is a fact even in a
+  // malformed envelope, and replacing it with null would be the same sin in the
+  // other direction. The only thing forbidden is INVENTING one.
+  if (!contract.ok) {
+    note("error",
+      "[compilePlan] the mandate body failed its contract — treat its budgets as " +
+      "unverified. Keys it does not carry compile UNMETERED (null); no default is " +
+      "substituted for them. See lib/mandate/contract.mjs.");
+  }
+
+  /** Default allowance for an obligation with no objective behind it. Null = unmetered. */
+  const defaultBudget = Number.isFinite(mandate.budgetCentsPerPeriod)
+    ? mandate.budgetCentsPerPeriod
+    : null;
+  /** The seat's whole envelope. Null = no ceiling is knowable, so none is enforced. */
+  const seatEnvelope = Number.isFinite(input.seatBudgetCents)
+    ? input.seatBudgetCents
+    : Number.isFinite(mandate.seatBudgetCents)
+      ? mandate.seatBudgetCents
+      : null;
+  if (seatEnvelope == null) {
+    note("warn",
+      "[compilePlan] no seat envelope (mandate.seatBudgetCents is null and no override " +
+      "was passed) — the budget ceiling is NOT enforced and no obligation can be " +
+      "suspended for breaching it.");
+  }
 
   /** Keep only reachable capabilities; record the rest as drift. */
   const resolveUses = (wanted, obKey) => {
@@ -324,10 +375,25 @@ export function compilePlan(input = {}) {
       continue; // an OUTCOME without a reachable method sensor is not emitted
     }
 
-    const budget = Number.isFinite(obj.budgetCentsPerPeriod) ? obj.budgetCentsPerPeriod : defaultBudget;
-    const withinEnvelope = spent + budget <= seatEnvelope;
-    if (!withinEnvelope) drift.push({ kind: "budget_breach", key: `outcome.${okey}`, detail: { seatEnvelope, spent, requested: budget } });
-    else spent += budget;
+    // This node's apportioned share of the seat envelope (hq apportions by
+    // Objective.weight, itself seeded from Charter.rewardWeights). Null when hq
+    // had nothing to apportion — which is a fact about funding, not a licence to
+    // pick a number.
+    const budget = Number.isFinite(obj.budgetCentsPerPeriod)
+      ? obj.budgetCentsPerPeriod
+      : defaultBudget;
+    if (budget == null) {
+      note("warn",
+        `[compilePlan] objective "${okey}" compiles UNMETERED: neither ` +
+        "objectives[].budgetCentsPerPeriod nor the body default carried a figure.");
+    }
+    // An unmetered obligation consumes an UNKNOWN amount, not zero — but a known
+    // ceiling cannot be spent down by an unknown, so it is admitted and named
+    // rather than silently charged 0 or silently charged a default.
+    const cost = Number.isFinite(budget) ? budget : 0;
+    const withinEnvelope = seatEnvelope == null ? true : spent + cost <= seatEnvelope;
+    if (!withinEnvelope) drift.push({ kind: "budget_breach", key: `outcome.${okey}`, detail: { seatEnvelope, spent, requested: cost } });
+    else spent += cost;
     const status = withinEnvelope ? "active" : "suspended";
 
     const measureKey = `schedule.measure.${okey}`;
@@ -464,6 +530,17 @@ export function compilePlan(input = {}) {
     mandateVersion: Number.isFinite(input.mandateVersion) ? input.mandateVersion : 0,
     drift,
     counts,
+    // Contract violations + every unmetered obligation. SEPARATE from `drift`
+    // because drift is a closed enum the org accepts (protocol DRIFT_KINDS) and
+    // "hq published no budget" is not one of its members — inventing a kind to
+    // make it fit would be rejected server-side and swallowed here.
+    warnings,
+    contract: {
+      ok: contract.ok,
+      version: contract.contractVersion,
+      missing: contract.missing,
+      unmetered: contract.unmetered,
+    },
   };
 }
 

package/lib/plan/compile.test.mjs

@@ -193,6 +193,88 @@ test("budget envelope: objectives past the envelope are SUSPENDED with a breach
   assert.equal(p.obligations.filter((o) => o.kind === "OUTCOME").length, 3, "all three still exist — suspended, not dropped");
 });
 
+// ---------------------------------------------------------------------------
+// THE MANDATE BODY JOINT — no invented money, ever
+// ---------------------------------------------------------------------------
+
+test("THE BUG: a mandate with no budget compiles UNMETERED, never 500", () => {
+  // This is the exact failure. hq sent no `budgetCentsPerPeriod`, the compiler
+  // read `undefined`, `Number.isFinite(undefined)` was false, and every single
+  // obligation in the fleet silently took 500c against a 10000c envelope that
+  // no column anywhere produced. Nothing errored, so nothing was ever noticed.
+  const logs = [];
+  const p = compilePlan({
+    mandate: { objectives: [objective()] },
+    manifest: manifest(),
+    standardCadences: STANDARD,
+    log: (level, msg) => logs.push([level, msg]),
+  });
+
+  for (const ob of p.obligations) {
+    assert.equal(ob.budget_cents_per_period, null, `${ob.key} must be unmetered, not a made-up number`);
+    assert.notEqual(ob.budget_cents_per_period, 500, `${ob.key} must never be 500`);
+  }
+  // Unmetered means NO ceiling is invented either — nothing is suspended for
+  // breaching a 10000c envelope that never existed.
+  assert.equal(p.obligations.filter((o) => o.status === "suspended").length, 0);
+  assert.ok(!p.drift.some((d) => d.kind === "budget_breach"));
+  // FAIL-OPEN IS FINE; SILENT IS NOT.
+  assert.ok(logs.length > 0, "the degradation is announced");
+  assert.ok(logs.some(([l]) => l === "error"), "a pre-contract body is an error-level event");
+  assert.equal(p.contract.ok, false);
+  assert.equal(p.contract.unmetered, true);
+  assert.ok(p.warnings.length > 0);
+});
+
+test("a funded hq body puts the MANDATE's number on each obligation", () => {
+  const objs = [
+    objective({ key: "a", id: "a", weight: 3, budgetCentsPerPeriod: 18_750 }),
+    objective({ key: "b", id: "b", weight: 1, budgetCentsPerPeriod: 6_250 }),
+  ];
+  const p = compilePlan({
+    mandate: {
+      contractVersion: 1, memberId: "mem_self", objectives: objs, proposed: [],
+      budgetCentsPerPeriod: null, seatBudgetCents: 25_000, budgetPeriod: "monthly",
+      budgetSource: "employee.payBasis.meteredBudget", collaborators: [], reactsTo: [],
+      degradations: [], generatedAt: "2026-08-11T00:00:00.000Z",
+    },
+    manifest: manifest(), standardCadences: [], log: () => {},
+  });
+  assert.equal(p.contract.ok, true);
+  assert.equal(p.contract.unmetered, false);
+  const byKey = Object.fromEntries(p.obligations.filter((o) => o.kind === "OUTCOME").map((o) => [o.key, o.budget_cents_per_period]));
+  assert.equal(byKey["outcome.a"], 18_750);
+  assert.equal(byKey["outcome.b"], 6_250);
+  // Obligations with no objective behind them stay unmetered — hq holds no
+  // per-obligation column, and `budgetCentsPerPeriod:null` says exactly that.
+  for (const ob of p.obligations.filter((o) => o.kind === "REACT")) {
+    assert.equal(ob.budget_cents_per_period, null);
+  }
+});
+
+test("budgets are NOT part of obligationsHash — funding a seat must not churn every plist", () => {
+  const base = { objectives: [objective({ key: "a", id: "a" })] };
+  const unfunded = compilePlan({ mandate: base, manifest: manifest(), standardCadences: STANDARD, log: () => {} });
+  const funded = compilePlan({
+    mandate: { ...base, objectives: [objective({ key: "a", id: "a", budgetCentsPerPeriod: 9_000 })], seatBudgetCents: 9_000 },
+    manifest: manifest(), standardCadences: STANDARD, log: () => {},
+  });
+  assert.equal(funded.obligationsHash, unfunded.obligationsHash, "funding changes money, not identity");
+});
+
+test("an explicit figure in a MALFORMED body is still used — only invention is forbidden", () => {
+  // The contract failing does not license throwing away a number the caller
+  // actually stated. It licenses refusing to make one up.
+  const logs = [];
+  const p = compilePlan({
+    mandate: { objectives: [objective({ key: "a", id: "a" })], budgetCentsPerPeriod: 700 },
+    manifest: manifest(), standardCadences: [], log: (l, m) => logs.push([l, m]),
+  });
+  assert.equal(p.contract.ok, false, "still a pre-contract body");
+  assert.ok(logs.some(([l]) => l === "error"), "and still loud about it");
+  assert.equal(p.obligations.find((o) => o.kind === "OUTCOME").budget_cents_per_period, 700);
+});
+
 test("validatePlan is FAIL-CLOSED on an unreachable citation and on an llm-sourced OUTCOME", () => {
   const reachable = new Set(["board_ready"]);
   const bad = {

package/lib/plan/emit.test.mjs

@@ -84,7 +84,12 @@ test(".cadence-registry.json carries the EXTENDED shape session-permissions can
   assert.equal(m.mode, "guarded");
   assert.equal(m.guardModule, "lib/goals/loop.mjs");
   assert.equal(m.obligationKey, "schedule.measure.pipeline-coverage");
-  assert.ok(Number.isFinite(m.budgetCents));
+  // PRESENT, and null when the mandate funded nothing — `planWith` builds from a
+  // mandate with no budget, so null is the honest reading. The key must exist
+  // either way: `getCadenceDef` branches on Number.isFinite, and an ABSENT key
+  // and a null one both mean "no cap" while only one of them can be logged.
+  assert.ok(Object.prototype.hasOwnProperty.call(m, "budgetCents"));
+  assert.equal(m.budgetCents, null);
   assert.ok(Array.isArray(m.allowedTools) && m.allowedTools.includes("crm_list_deals"));
   // Back-compat: {mode, prompt} still present for every entry.
   for (const [id, def] of Object.entries(reg)) {

package/lib/setup/sections/mandate.mjs

@@ -48,6 +48,7 @@ import { readAgentJson } from "../sot.mjs";
 import { runScriptAbs } from "../run-generator.mjs";
 import { readManifest } from "../../capability/inventory.mjs";
 import { deriveMandate, toMandateBody } from "../../mandate/derive.mjs";
+import { MANDATE_CONTRACT_VERSION } from "../../mandate/contract.mjs";
 import { readCache, writeCache, stalenessTier, staleSeconds, allObjectives, adoptedObjectives, CACHE_REL } from "../../mandate/cache.mjs";
 import { compilePlan } from "../../plan/compile.mjs";
 import { emitPlan, readLock, PLAN_REL, LOCK_REL } from "../../plan/emit.mjs";
@@ -171,7 +172,10 @@ export async function resolveMandate(o = {}, deps = {}) {
   const { refreshMandate } = await import("../../mandate/refresh.mjs");
   const res = await refreshMandate(agentRoot, {
     now: deps.now ? () => deps.now() : undefined,
-    log: (level, m) => log(m),
+    // Keep the LEVEL. `(level, m) => log(m)` threw it away, so a contract
+    // violation ("this snapshot has no budgets") rendered identically to a
+    // routine dim note and read as noise in a wall of setup output.
+    log: (level, m) => log(level === "error" ? `ERROR ${m}` : m),
     memberId: o.memberId || null,
     callImpl: typeof call === "function" ? call : undefined,
     offline: typeof call !== "function",
@@ -222,6 +226,13 @@ export async function compileAndEmit(o = {}, deps = {}) {
   const { agentRoot, maestroRoot } = o;
   const inputs = o.inputs || (await loadCompilerInputs({ agentRoot, maestroRoot }, deps));
   const record = o.record || readCache(agentRoot, deps) || { body: {}, version: 0 };
+  // The compiler announces contract violations and unmetered obligations through
+  // this. Omit it and a plan built on a budget-less mandate looks identical to
+  // one built on a funded mandate — which is precisely how the 500c fiction
+  // survived for as long as it did.
+  const compileLog = deps.logImpl
+    ? (level, msg) => deps.logImpl(`[${level}] ${msg}`)
+    : (level, msg) => io.note(msg, { dim: level !== "error" });
 
   const plan = compilePlan({
     mandate: record.body || {},
@@ -233,6 +244,7 @@ export async function compileAndEmit(o = {}, deps = {}) {
     archetypeCadences: inputs.archetypeCadences,
     calendarEvents: o.calendarEvents || [],
     concurrency: o.concurrency,
+    log: compileLog,
   });
 
   const emit = await emitPlan({
@@ -321,6 +333,14 @@ export default {
     }
 
     io.note(`[mandate] compiled ${plan.counts.total} obligations (${plan.counts.SCHEDULE} SCHEDULE · ${plan.counts.OUTCOME} OUTCOME · ${plan.counts.REACT} REACT) from ${plan.counts.adoptedObjectives} adopted / ${plan.counts.proposedObjectives} proposed objectives`);
+    // The funding line, printed on EVERY apply. Before the contract there was no
+    // such line because there was nothing true to say: the compiler had already
+    // replaced the unknown with 500 before anyone could report it.
+    io.note(
+      plan.contract.unmetered
+        ? "[mandate] budget: UNMETERED — hq published no funding, so every obligation carries budget_cents_per_period:null and no ceiling is enforced"
+        : `[mandate] budget: metered from hq (contract v${plan.contract.version}) — ${plan.obligations.filter((ob) => Number.isFinite(ob.budget_cents_per_period)).length}/${plan.obligations.length} obligations carry a funded allowance`
+    );
     for (const d of plan.drift) log(`[mandate] drift ${d.kind}${d.key ? ` (${d.key})` : ""}: ${JSON.stringify(d.detail)}`);
 
     // launchd plists — generate-plists.sh reads config/.cadence-plists.tsv
@@ -361,10 +381,32 @@ export default {
       orgContext: inputs.orgContext,
       standardCadences: inputs.standardCadences,
       archetypeCadences: inputs.archetypeCadences,
+      // Silent here means the recompile can read a pre-contract mandate, compile
+      // every obligation unmetered, still match the lock hash (budgets are not
+      // part of `identityOf`) and report a clean bill of health. Route it.
+      log: (level, msg) => { if (level === "error") checks.push({ name: msg, ok: false, remedy: "the cached mandate body predates contract v1 — run `maestro setup --only mandate` to refetch from hq" }); },
     });
     const hashOk = plan.obligationsHash === lock.obligationsHash;
     checks.push({ name: "obligationsHash matches compile.lock", ok: hashOk, remedy: hashOk ? undefined : "inputs changed since the last compile — re-run `maestro setup --only mandate`" });
 
+    // THE FUNDING CHECK. `ok:true` either way — an unfunded seat is a legitimate
+    // state and must not fail setup — but it can never again be invisible, which
+    // is the only property that mattered here.
+    checks.push({
+      name: plan.contract.unmetered
+        ? "mandate budget: UNMETERED (hq published no funding for this seat)"
+        : `mandate budget: metered from hq (contract v${plan.contract.version})`,
+      ok: true,
+      remedy: plan.contract.unmetered
+        ? "obligations carry budget_cents_per_period:null. hq's reasons are in the mandate body's degradations[]; fund the seat via its Employee payBasis.meteredBudget in Cohort."
+        : undefined,
+    });
+    checks.push({
+      name: `mandate body satisfies contract v${MANDATE_CONTRACT_VERSION}`,
+      ok: plan.contract.ok,
+      remedy: plan.contract.ok ? undefined : `missing required key(s): ${plan.contract.missing.join(", ")} — refetch the mandate from hq`,
+    });
+
     const v = validatePlan(plan, { manifest: manifest || { entries: [] } });
     checks.push({ name: "plan validates (no obligation cites an unreachable capability)", ok: v.ok, remedy: v.ok ? undefined : v.errors.slice(0, 3).join("; ") });
 

package/lib/subagents/schema.mjs

@@ -284,10 +284,22 @@ export function stringifyFrontmatter(fm) {
   return lines.length ? `${lines.join("\n")}\n` : "";
 }
 
-/** Re-assemble a full agent.md from a frontmatter object + body. */
+/**
+ * Re-assemble a full agent.md from a frontmatter object + body.
+ *
+ * The body is emitted VERBATIM. It used to have a single leading `\n` stripped,
+ * which looked like a convenience but broke the parse → stringify round trip:
+ * {@link splitFrontmatter} slices the body from just after the closing fence's
+ * own newline, so a file written in the shipped shape (`---\n\nYou are…`) parses
+ * to a body of `"\nYou are…"` — and re-emitting it dropped the blank line.
+ * Every {@link stampProvenance} call took that path, so materialisation changed
+ * bytes it had no business changing and {@link hashFile} (whole-file bytes) then
+ * reported files nobody had edited as locally edited. Byte-identity is the whole
+ * contract here; a "tidy" newline is not worth breaking it for.
+ */
 export function stringifyAgentMd(fm, body) {
   const b = typeof body === "string" ? body : "";
-  return `---\n${stringifyFrontmatter(fm)}---\n${b.startsWith("\n") ? b.slice(1) : b}`;
+  return `---\n${stringifyFrontmatter(fm)}---\n${b}`;
 }
 
 /**

package/lib/subagents/schema.test.mjs

@@ -250,6 +250,28 @@ test("round trip: parse(stringify(x)) === x, and a second pass is byte-identical
   assert.equal(stringifyAgentMd(parsed.frontmatter, parsed.body), once);
 });
 
+test("round trip: a file in the SHIPPED shape (blank line after the fence) survives byte-exact", () => {
+  // Regression. The round-trip test above starts its body at "# alpha", which is
+  // the one shape splitFrontmatter never returns — it slices from just after the
+  // closing fence's newline, so a real file's body ALWAYS starts with "\n".
+  // stringifyAgentMd used to strip exactly that newline, so every shipped
+  // agent.md lost its blank line on re-emit. stampProvenance takes this path on
+  // every materialisation and hashFile compares whole-file bytes, so the drift
+  // showed up as "locally edited" on files nobody had touched.
+  const src = [
+    "---", "name: alpha", "description: d", "model: claude-sonnet-4-6",
+    'tools: ["Read"]', "---", "", "You are the alpha sub-agent.", "",
+  ].join("\n");
+  const parsed = parseAgentMd(src);
+  assert.equal(parsed.ok, true, parsed.errors.join("; "));
+  assert.equal(parsed.body.startsWith("\n"), true, "body keeps its leading \\n");
+  assert.equal(stringifyAgentMd(parsed.frontmatter, parsed.body), src);
+  assert.equal(
+    hashFile(stringifyAgentMd(parsed.frontmatter, parsed.body)), hashFile(src),
+    "re-emit must not move the file hash",
+  );
+});
+
 test("stampProvenance: is IDEMPOTENT — re-stamping produces identical bytes", () => {
   // Non-idempotent stamping would change the file hash on every materialisation
   // and make local-edit detection permanently wrong.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/ci/check-subagent-frontmatter.mjs

@@ -0,0 +1,139 @@
+/**
+ * check-subagent-frontmatter.mjs — CI guard that fails if any
+ * `agents/<slug>/agent.md` would be refused by the sub-agent registry.
+ *
+ * WHY THIS EXISTS. `lib/subagents/schema.validateAgentMd()` has been the rule set
+ * since the registry landed, but nothing ran it over the working tree. The result
+ * was a fleet where 57 of 70 sub-agents failed validation — every one written by
+ * `scripts/setup/generate-capability.mjs`, which emitted `name`/`description`/
+ * `model` and no `tools`. Nobody noticed because the only thing that would have
+ * complained was a unit test asserting the shipped fleet validates, and that test
+ * had simply been red.
+ *
+ * Fixing the generator stops NEW bad agents from being generated. It does not
+ * stop one being hand-written, forked, or pasted in — so the rule is enforced
+ * here, over the whole directory, where a bad definition fails the build instead
+ * of failing silently at dispatch. Two gates, one rule set: this guard and the
+ * hq-side `validate.ts` both call the same validator.
+ *
+ * An EMPTY `agents/<slug>/` directory is a failure too. It used to pass `doctor`
+ * (which only checked that a directory existed), which is precisely how a
+ * sub-agent could be referenced everywhere and defined nowhere.
+ *
+ * Pure, dependency-light: Node builtins + lib/subagents. ESM.
+ *
+ * Usage: `node scripts/ci/check-subagent-frontmatter.mjs`
+ *   exit 0 → every agent.md validates; exit 1 → at least one does not.
+ *
+ * @module scripts/ci/check-subagent-frontmatter
+ */
+
+"use strict";
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { checkAgentFile } from "../../lib/subagents/schema.mjs";
+import { listAgentDirs } from "../../lib/subagents/manifest.mjs";
+
+/** Repo root: two levels up from scripts/ci/. @type {string} */
+const REPO_ROOT = path.resolve(
+  fileURLToPath(new URL(".", import.meta.url)),
+  "..",
+  "..",
+);
+
+/**
+ * Validate every sub-agent definition under `<root>/agents`.
+ *
+ * @param {string} [root=REPO_ROOT]
+ * @returns {{ offenders: Array<{ slug: string, errors: string[] }>, warned: Array<{ slug: string, warnings: string[] }>, checked: number }}
+ *   `offenders` fail the build; `warned` is advisory only (e.g. a declared token
+ *   this renderer does not know), reported but never fatal.
+ */
+export function findInvalidAgents(root = REPO_ROOT) {
+  const { slugs, empty } = listAgentDirs(root);
+  const offenders = [];
+  const warned = [];
+
+  for (const slug of empty) {
+    offenders.push({
+      slug,
+      errors: ["directory exists but contains no agent.md"],
+    });
+  }
+
+  for (const slug of slugs) {
+    const file = path.join(root, "agents", slug, "agent.md");
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch (err) {
+      offenders.push({
+        slug,
+        errors: [`unreadable: ${err && err.message ? err.message : err}`],
+      });
+      continue;
+    }
+    const res = checkAgentFile(text, slug);
+    if (!res.ok) offenders.push({ slug, errors: res.errors });
+    else if (res.warnings && res.warnings.length)
+      warned.push({ slug, warnings: res.warnings });
+  }
+
+  return { offenders, warned, checked: slugs.length + empty.length };
+}
+
+/**
+ * Run the check and print a human report.
+ *
+ * @param {string} [root=REPO_ROOT]
+ * @returns {Promise<number>} exit code (0 = all valid, 1 = at least one invalid).
+ */
+export async function run(root = REPO_ROOT) {
+  const { offenders, warned, checked } = findInvalidAgents(root);
+
+  for (const { slug, warnings } of warned) {
+    for (const w of warnings) {
+      console.warn(`check-subagent-frontmatter: WARN ${slug}: ${w}`);
+    }
+  }
+
+  if (offenders.length === 0) {
+    console.log(
+      `check-subagent-frontmatter: OK (${checked} sub-agent definition(s) validate)`,
+    );
+    return 0;
+  }
+
+  console.error(
+    "check-subagent-frontmatter: FAIL — invalid sub-agent definition(s):",
+  );
+  for (const { slug, errors } of offenders) {
+    for (const e of errors) console.error(`  agents/${slug}/agent.md: ${e}`);
+  }
+  console.error(
+    `check-subagent-frontmatter: ${offenders.length}/${checked} definition(s) would be refused by the registry.`,
+  );
+  console.error(
+    "  Generated agents come from scripts/setup/generate-capability.mjs; repair existing ones with",
+  );
+  console.error(
+    "  `node scripts/setup/repair-subagent-frontmatter.mjs --write`.",
+  );
+  return 1;
+}
+
+// Run when invoked directly (not when imported).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(
+        "check-subagent-frontmatter: ERROR",
+        err && err.message ? err.message : err,
+      );
+      process.exit(2);
+    });
+}

package/scripts/ci/check-subagent-frontmatter.test.mjs

@@ -0,0 +1,124 @@
+/**
+ * Tests for check-subagent-frontmatter.mjs — the sub-agent definition guard.
+ *
+ * Runs against throwaway trees under os.tmpdir() rather than the repo's own
+ * agents/, so the tests still describe the guard's behaviour when the repo is
+ * clean (a guard that can only be tested by breaking the repo is a guard nobody
+ * tests).
+ *
+ * Run: node --test scripts/ci/check-subagent-frontmatter.test.mjs
+ * @module scripts/ci/check-subagent-frontmatter.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { findInvalidAgents } from "./check-subagent-frontmatter.mjs";
+
+/** Build a temp repo root containing `agents/<slug>/agent.md` for each entry. */
+function makeTree(agents) {
+  const root = mkdtempSync(join(tmpdir(), "subagent-guard-"));
+  for (const [slug, text] of Object.entries(agents)) {
+    mkdirSync(join(root, "agents", slug), { recursive: true });
+    if (text !== null)
+      writeFileSync(join(root, "agents", slug, "agent.md"), text);
+  }
+  return root;
+}
+
+const VALID = [
+  "---",
+  "name: alpha",
+  "description: Does the alpha work.",
+  "model: claude-sonnet-4-6",
+  'tools: ["Read", "Grep"]',
+  "---",
+  "",
+  "You are the alpha sub-agent.",
+  "",
+].join("\n");
+
+describe("findInvalidAgents", () => {
+  it("passes a well-formed definition", () => {
+    const { offenders, checked } = findInvalidAgents(
+      makeTree({ alpha: VALID }),
+    );
+    assert.deepEqual(offenders, []);
+    assert.equal(checked, 1);
+  });
+
+  it("catches the exact defect that shipped: frontmatter with no tools key", () => {
+    // This is the whole reason the guard exists — 57 of 70 agents in this repo
+    // were generated in precisely this shape and every one failed at dispatch.
+    const noTools = VALID.split("\n")
+      .filter((l) => !l.startsWith("tools:"))
+      .join("\n");
+    const { offenders } = findInvalidAgents(makeTree({ alpha: noTools }));
+    assert.equal(offenders.length, 1);
+    assert.equal(offenders[0].slug, "alpha");
+    assert.ok(
+      offenders[0].errors.some((e) => e.includes("tools")),
+      `expected a tools error, got: ${offenders[0].errors.join("; ")}`,
+    );
+  });
+
+  it("fails an EMPTY agents/<slug>/ directory rather than passing it", () => {
+    // doctor used to accept this, which is how an agent could be referenced
+    // everywhere and defined nowhere.
+    const { offenders } = findInvalidAgents(makeTree({ ghost: null }));
+    assert.equal(offenders.length, 1);
+    assert.equal(offenders[0].slug, "ghost");
+    assert.match(offenders[0].errors[0], /no agent\.md/);
+  });
+
+  it("fails when frontmatter.name disagrees with the directory name", () => {
+    const renamed = VALID.replace("name: alpha", "name: beta");
+    const { offenders } = findInvalidAgents(makeTree({ alpha: renamed }));
+    assert.equal(offenders.length, 1);
+    assert.ok(offenders[0].errors.some((e) => e.includes("must equal")));
+  });
+
+  it("fails a body that uses a token its tokens list does not declare", () => {
+    const undeclared = VALID.replace(
+      "You are the alpha sub-agent.",
+      "You are {{agent.fullName}}'s alpha sub-agent.",
+    ).replace('tools: ["Read", "Grep"]', 'tools: ["Read"]\ntokens: []');
+    const { offenders } = findInvalidAgents(makeTree({ alpha: undeclared }));
+    assert.equal(offenders.length, 1);
+    assert.ok(offenders[0].errors.some((e) => e.includes("undeclared token")));
+  });
+
+  it("reports an unknown declared token as a WARNING, not a build failure", () => {
+    // Advisory by design: hq does not vendor KNOWN_TOKENS, so a body authored
+    // against a newer vocabulary must not hard-fail an older agent's build.
+    const odd = VALID.replace(
+      'tools: ["Read", "Grep"]',
+      'tools: ["Read"]\ntokens: ["agent.notAThing"]',
+    );
+    const { offenders, warned } = findInvalidAgents(makeTree({ alpha: odd }));
+    assert.deepEqual(offenders, []);
+    assert.equal(warned.length, 1);
+    assert.ok(warned[0].warnings.some((w) => w.includes("agent.notAThing")));
+  });
+
+  it("reports every offender, not just the first", () => {
+    const noTools = VALID.split("\n")
+      .filter((l) => !l.startsWith("tools:"))
+      .join("\n");
+    const { offenders, checked } = findInvalidAgents(
+      makeTree({ alpha: VALID, beta: noTools, gamma: noTools }),
+    );
+    assert.equal(checked, 3);
+    assert.deepEqual(offenders.map((o) => o.slug).sort(), ["beta", "gamma"]);
+  });
+
+  it("treats a missing agents/ directory as nothing to check, not an error", () => {
+    const root = mkdtempSync(join(tmpdir(), "subagent-guard-empty-"));
+    const { offenders, checked } = findInvalidAgents(root);
+    assert.deepEqual(offenders, []);
+    assert.equal(checked, 0);
+  });
+});