@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/subagents/client.test.mjs

@@ -0,0 +1,309 @@
+/**
+ * client.test.mjs — the hq half of the registry (§2.1, §4). The contract under
+ * test is FAIL-OPEN: nothing in this module may throw, because `apply()` throws
+ * are fatal to the whole wizard (lib/setup/runner.mjs:220-227).
+ * Run: node --test lib/subagents/client.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  TIMEOUT_MS,
+  createDefinition,
+  fetchResolve,
+  fetchRoster,
+  flushOutbox,
+  forkDefinition,
+  getDefinition,
+  getRead,
+  listDefinitions,
+  pinDefinition,
+  postRpc,
+  publishVersion,
+  resolveConfig,
+  unpinDefinition,
+  writeVerb,
+  yankDefinition,
+} from "./client.mjs";
+import { latestCached, listOutbox, queueOutbox } from "./lock.mjs";
+import { hashBody, parseAgentMd } from "./schema.mjs";
+
+const CFG = { enabled: true, base: "https://hq.example.com", token: "sk-test", orgId: "org_1", memberId: "mem_1" };
+const root = () => mkdtempSync(join(tmpdir(), "subagent-client-"));
+
+/** A recording fake fetch. `reply(url, init)` returns {ok,status,body} or throws. */
+function fakeFetch(reply) {
+  const calls = [];
+  const fn = async (url, init) => {
+    calls.push({ url: String(url), method: init && init.method, headers: (init && init.headers) || {}, body: init && init.body ? JSON.parse(init.body) : null });
+    const r = typeof reply === "function" ? await reply(String(url), init, 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 errFrame = (status, code, message) => ({ ok: false, status, body: { ok: false, error: { code, message } } });
+/** A fetch that never resolves — exercises the AbortController timeout. */
+const hangingFetch = () => async (_u, init) => new Promise((_res, rej) => {
+  if (init && init.signal) init.signal.addEventListener("abort", () => rej(Object.assign(new Error("aborted"), { name: "AbortError" })));
+});
+
+// ---------------------------------------------------------------------------
+// config
+// ---------------------------------------------------------------------------
+
+test("resolveConfig: env supplies base/token/org; enabled needs BOTH base and token", () => {
+  const c = resolveConfig({ cfg: {}, env: { COHORT_BASE: "https://hq.example.com/", COHORT_API_KEY: "sk", COHORT_ORG_ID: "org_9", COHORT_MEMBER_ID: "mem_9" } });
+  assert.equal(c.base, "https://hq.example.com", "trailing slash trimmed");
+  assert.equal(c.token, "sk");
+  assert.equal(c.orgId, "org_9");
+  assert.equal(c.memberId, "mem_9");
+  assert.equal(c.enabled, true);
+
+  assert.equal(resolveConfig({ cfg: {}, env: {} }).enabled, false);
+  assert.equal(resolveConfig({ cfg: {}, env: { COHORT_BASE: "https://x" } }).enabled, false);
+});
+
+test("resolveConfig: not enrolled is a legitimate steady state, not an error", () => {
+  // §4 — layer 1 simply does not exist; the section reports status:"skipped".
+  const c = resolveConfig({ cfg: {}, env: {} });
+  assert.deepEqual(c, { enabled: false, base: "", token: "", orgId: "", memberId: "" });
+});
+
+// ---------------------------------------------------------------------------
+// transport
+// ---------------------------------------------------------------------------
+
+test("postRpc: POSTs /v1/<method> with bearer, protocol and tenant-pin headers", async () => {
+  const f = fakeFetch(okFrame({ hello: "world" }));
+  const r = await postRpc("subagent.list", { a: 1 }, { cfg: CFG, fetchImpl: f, idempotencyKey: "k1" });
+  assert.deepEqual(r, { ok: true, result: { hello: "world" } });
+  const call = f.calls[0];
+  assert.equal(call.url, "https://hq.example.com/v1/subagent.list");
+  assert.equal(call.method, "POST");
+  assert.equal(call.headers.authorization, "Bearer sk-test");
+  assert.equal(call.headers["x-org-protocol"], "1");
+  assert.equal(call.headers["x-org-id"], "org_1");
+  assert.equal(call.headers["x-idempotency-key"], "k1");
+  assert.deepEqual(call.body, { a: 1 });
+});
+
+test("postRpc: a REJECTION (the server said no) is not degraded", async () => {
+  const r = await postRpc("subagent.pin", {}, { cfg: CFG, fetchImpl: fakeFetch(errFrame(403, "FORBIDDEN", "nope")) });
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, false, "the distinction that decides outbox-queue vs surface-the-error");
+  assert.equal(r.error.code, "FORBIDDEN");
+  assert.equal(r.status, 403);
+});
+
+test("postRpc: a transport failure (no answer) IS degraded, and never throws", async () => {
+  const r = await postRpc("subagent.pin", {}, { cfg: CFG, fetchImpl: fakeFetch(new Error("ECONNREFUSED")) });
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, true);
+  assert.match(r.error.message, /ECONNREFUSED/);
+});
+
+test("postRpc: a hung server aborts on the timeout and reports it as degraded", async () => {
+  const r = await postRpc("subagent.list", {}, { cfg: CFG, fetchImpl: hangingFetch(), timeoutMs: 20 });
+  assert.equal(r.degraded, true);
+  assert.match(r.error.message, /timeout after 20ms/);
+  assert.equal(TIMEOUT_MS, 5000, "5 s — a human waiting on a dead server is the worse outcome");
+});
+
+test("postRpc: unparseable / non-frame JSON is an error, not a crash", async () => {
+  const r = await postRpc("subagent.list", {}, { cfg: CFG, fetchImpl: fakeFetch({ ok: true, status: 200, body: "not-a-frame" }) });
+  assert.equal(r.ok, false);
+  assert.equal(r.error.code, "HTTP_200");
+});
+
+test("postRpc / getRead: no base or token → UNAUTHORIZED + degraded, with NO request made", async () => {
+  const f = fakeFetch(okFrame({}));
+  const r = await postRpc("subagent.list", {}, { cfg: { base: "", token: "" }, fetchImpl: f });
+  assert.equal(r.degraded, true);
+  assert.equal(r.error.code, "UNAUTHORIZED");
+  assert.equal((await getRead("subagent.roster", { cfg: {}, fetchImpl: f })).error.code, "UNAUTHORIZED");
+  assert.equal(f.calls.length, 0);
+});
+
+test("getRead: reads return the BARE payload on 200 (not an envelope)", async () => {
+  const f = fakeFetch({ ok: true, status: 200, body: { rosterVersion: 4, entries: [] } });
+  const r = await getRead("subagent.roster", { cfg: CFG, fetchImpl: f });
+  assert.deepEqual(r.payload, { rosterVersion: 4, entries: [] });
+  assert.equal(f.calls[0].method, "GET");
+  assert.equal("content-type" in f.calls[0].headers, false, "no body, no content-type");
+});
+
+// ---------------------------------------------------------------------------
+// reads
+// ---------------------------------------------------------------------------
+
+test("fetchRoster: the cheap poll — rosterVersion + bodiless entries", async () => {
+  const f = fakeFetch({ ok: true, status: 200, body: { rosterVersion: 11, entries: [{ slug: "alpha", definitionId: "d1", version: 3, contentHash: "h" }] } });
+  const r = await fetchRoster({ cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.rosterVersion, 11);
+  assert.equal(r.entries[0].slug, "alpha");
+  assert.equal(f.calls[0].url, "https://hq.example.com/v1/subagent.roster");
+});
+
+test("fetchRoster: a dead server returns an empty, degraded roster — never throws", async () => {
+  const r = await fetchRoster({ cfg: CFG, fetchImpl: fakeFetch(new Error("down")) });
+  assert.deepEqual([r.ok, r.degraded, r.rosterVersion, r.entries], [false, true, 0, []]);
+});
+
+test("fetchResolve: sends the selector params and returns bodies + advice", async () => {
+  const f = fakeFetch(okFrame({ rosterVersion: 5, entries: [], rewire: [{ ref: "x", suggest: "y" }], unmatched: ["z"] }));
+  const r = await fetchResolve({ cfg: CFG, memberId: "mem_1", function: "executive-operator", altitude: "c-suite", refs: ["ghost"], fetchImpl: f });
+  assert.deepEqual(f.calls[0].body, { memberId: "mem_1", function: "executive-operator", altitude: "c-suite", refs: ["ghost"] });
+  assert.equal(r.rosterVersion, 5);
+  assert.deepEqual(r.unmatched, ["z"]);
+  assert.equal(r.rewire[0].suggest, "y");
+});
+
+test("fetchResolve: every returned body is cached so the NEXT run needs no network", async () => {
+  const agentRoot = root();
+  const f = fakeFetch(okFrame({
+    rosterVersion: 5,
+    entries: [{ slug: "alpha", version: 3, contentHash: "h", frontmatter: { name: "alpha", description: "d", model: "sonnet", tools: ["Read"] }, body: "# alpha\n\ncached body\n" }],
+  }));
+  await fetchResolve({ cfg: CFG, agentRoot, fetchImpl: f });
+  const cached = latestCached(agentRoot, "alpha");
+  assert.equal(cached.version, 3);
+  // Emitted through the same serializer the resolver parses with — lossless.
+  const parsed = parseAgentMd(cached.text);
+  assert.equal(parsed.frontmatter.name, "alpha");
+  assert.equal(parsed.body, "# alpha\n\ncached body\n");
+});
+
+test("fetchResolve: a failure yields an empty degraded result (layer 1 just vanishes)", async () => {
+  const r = await fetchResolve({ cfg: CFG, fetchImpl: fakeFetch(new Error("down")) });
+  assert.deepEqual([r.ok, r.degraded, r.entries.length], [false, true, 0]);
+});
+
+test("listDefinitions / getDefinition: shaped results, fail-open on error", async () => {
+  const l = await listDefinitions({ cfg: CFG, fetchImpl: fakeFetch(okFrame({ items: [{ slug: "alpha" }] })) });
+  assert.deepEqual(l.items, [{ slug: "alpha" }]);
+  const bad = await listDefinitions({ cfg: CFG, fetchImpl: fakeFetch(new Error("x")) });
+  assert.deepEqual(bad.items, []);
+  const g = await getDefinition("alpha", { cfg: CFG, fetchImpl: fakeFetch(okFrame({ slug: "alpha" })) });
+  assert.deepEqual(g.definition, { slug: "alpha" });
+  assert.equal((await getDefinition("alpha", { cfg: CFG, fetchImpl: fakeFetch(errFrame(404, "NOT_FOUND", "x")) })).definition, null);
+});
+
+// ---------------------------------------------------------------------------
+// writes + the outbox — the distinction that keeps work from being lost
+// ---------------------------------------------------------------------------
+
+test("writeVerb: a DEGRADED failure queues to the outbox for `maestro sync`", async () => {
+  const agentRoot = root();
+  const r = await writeVerb("subagent.create", { slug: "alpha" }, { cfg: CFG, agentRoot, fetchImpl: fakeFetch(new Error("offline")) });
+  assert.equal(r.degraded, true);
+  assert.ok(r.queued);
+  const queued = listOutbox(agentRoot);
+  assert.equal(queued.length, 1);
+  assert.deepEqual(queued[0].payload, { slug: "alpha" }, "queued verbatim — never re-derived at replay time");
+});
+
+test("writeVerb: a REJECTION is NOT queued (it would be rejected forever, invisibly)", async () => {
+  const agentRoot = root();
+  const r = await writeVerb("subagent.pin", { slug: "alpha" }, { cfg: CFG, agentRoot, fetchImpl: fakeFetch(errFrame(403, "FORBIDDEN", "nope")) });
+  assert.equal(r.ok, false);
+  assert.equal(r.degraded, false);
+  assert.equal(r.queued, undefined);
+  assert.deepEqual(listOutbox(agentRoot), []);
+});
+
+test("writeVerb: queue:false opts out (used where a caller wants the raw verdict)", async () => {
+  const agentRoot = root();
+  await writeVerb("subagent.pin", {}, { cfg: CFG, agentRoot, fetchImpl: fakeFetch(new Error("offline")), queue: false });
+  assert.deepEqual(listOutbox(agentRoot), []);
+});
+
+test("createDefinition: stamps contentHash, strips provenance, sends an idempotency key", async () => {
+  const f = fakeFetch(okFrame({ definitionId: "d1", version: 1 }));
+  await createDefinition({
+    slug: "alpha", title: "Alpha", summary: "s", tags: ["x"], functions: ["f"], altitudes: ["a"],
+    frontmatter: { name: "alpha", layer: "sdk", source: "sdk://1/alpha", contentHash: "old" },
+    body: "# alpha\n",
+  }, { cfg: CFG, fetchImpl: f });
+  const sent = f.calls[0].body;
+  assert.equal(sent.contentHash, hashBody("# alpha\n"));
+  assert.deepEqual(Object.keys(sent.frontmatter), ["name"], "a definition is prose, not a record of one copy of it");
+  assert.equal(sent.baseLayer, "none");
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "subagent.create:org_1:alpha");
+});
+
+test("publishVersion: the idempotency key is (slug, contentHash) — a replay is a no-op", async () => {
+  const f = fakeFetch(okFrame({ version: 4 }));
+  await publishVersion({ slug: "alpha", definitionId: "d1", frontmatter: { name: "alpha" }, body: "b\n" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], `subagent.publishVersion:alpha:${hashBody("b\n")}`);
+  assert.equal(f.calls[0].body.definitionId, "d1");
+});
+
+test("forkDefinition: records baseLayer/baseSlug and a fork generator", async () => {
+  const f = fakeFetch(okFrame({ definitionId: "d2", version: 1 }));
+  await forkDefinition({ slug: "alpha-mine", baseSlug: "alpha", frontmatter: { name: "alpha-mine" }, body: "b\n" }, { cfg: CFG, fetchImpl: f });
+  const sent = f.calls[0].body;
+  assert.equal(sent.baseLayer, "sdk");
+  assert.equal(sent.baseSlug, "alpha");
+  assert.deepEqual(sent.generator, { source: "fork", forkedFrom: "alpha" });
+});
+
+test("pin / unpin / yank: send only the identifiers they were given", async () => {
+  const f = fakeFetch(okFrame({}));
+  await pinDefinition({ slug: "alpha", definitionId: "d1", version: 3 }, { cfg: CFG, fetchImpl: f });
+  await unpinDefinition({ slug: "alpha" }, { cfg: CFG, fetchImpl: f });
+  await yankDefinition({ slug: "alpha", reason: "superseded" }, { cfg: CFG, fetchImpl: f });
+  assert.deepEqual(f.calls.map((c) => c.url.split("/v1/")[1]), ["subagent.pin", "subagent.unpin", "subagent.yank"]);
+  assert.equal(f.calls[0].body.version, 3);
+  assert.equal(f.calls[0].body.memberId, undefined, "an absent memberId means 'me' — hq fills it from the actor");
+  assert.equal(f.calls[2].body.reason, "superseded");
+});
+
+// ---------------------------------------------------------------------------
+// replay
+// ---------------------------------------------------------------------------
+
+test("flushOutbox: replays oldest-first and removes what landed", async () => {
+  const agentRoot = root();
+  queueOutbox(agentRoot, "subagent.create", { slug: "alpha" });
+  queueOutbox(agentRoot, "subagent.pin", { slug: "alpha" });
+  const f = fakeFetch(okFrame({}));
+  const r = await flushOutbox({ agentRoot, cfg: CFG, fetchImpl: f });
+  assert.deepEqual([r.replayed, r.remaining, r.stopped], [2, 0, false]);
+  assert.deepEqual(listOutbox(agentRoot), []);
+});
+
+test("flushOutbox: STOPS at the first degraded failure (the server is down again)", async () => {
+  const agentRoot = root();
+  queueOutbox(agentRoot, "subagent.create", { slug: "a" });
+  queueOutbox(agentRoot, "subagent.pin", { slug: "a" });
+  const f = fakeFetch((_u, _i, n) => (n === 1 ? okFrame({}) : new Error("down")));
+  const r = await flushOutbox({ agentRoot, cfg: CFG, fetchImpl: f });
+  assert.deepEqual([r.replayed, r.stopped, r.remaining], [1, true, 1]);
+  assert.equal(listOutbox(agentRoot).length, 1, "the undelivered write is still queued");
+});
+
+test("flushOutbox: DROPS a rejected entry and reports it (or the outbox never empties)", async () => {
+  const agentRoot = root();
+  queueOutbox(agentRoot, "subagent.pin", { slug: "a" });
+  queueOutbox(agentRoot, "subagent.pin", { slug: "b" });
+  const f = fakeFetch((_u, _i, n) => (n === 1 ? errFrame(409, "CONFLICT", "already there") : okFrame({})));
+  const r = await flushOutbox({ agentRoot, cfg: CFG, fetchImpl: f });
+  assert.equal(r.replayed, 1);
+  assert.equal(r.dropped.length, 1);
+  assert.equal(r.dropped[0].error.code, "CONFLICT");
+  assert.deepEqual(listOutbox(agentRoot), []);
+});
+
+test("flushOutbox: an empty outbox is a clean no-op", async () => {
+  const r = await flushOutbox({ agentRoot: root(), cfg: CFG, fetchImpl: fakeFetch(okFrame({})) });
+  assert.deepEqual(r, { replayed: 0, dropped: [], remaining: 0, stopped: false });
+});

package/lib/subagents/gap.mjs

@@ -0,0 +1,268 @@
+/**
+ * lib/subagents/gap.mjs — the three-way diff between the roster, the resolved
+ * layers, and what the repo actually references (§2.3).
+ *
+ * Three questions, three sets:
+ *
+ *   missing     the capability pack says this agent should exist, and no layer
+ *               resolves it. → the registry's actual job: adopt/fork/create.
+ *
+ *   unrostered  a workflow / team / routing entry references a slug the roster
+ *               does not contain. Today this is the ONLY check `doctor` does, and
+ *               it reports it as a bare "missing agent", which is almost always
+ *               the wrong framing: the reference is usually vestigial, copied in
+ *               by `create` from maestro's own `workflows/**` (which are the CEO
+ *               agent's workflows, not this agent's). 15 such refs exist in every
+ *               freshly-created agent.
+ *
+ *   idle        a roster agent that NOTHING references. This check does not exist
+ *               anywhere today, and it is the one that tells you the capability
+ *               pack generated prose nobody dispatches to.
+ *
+ * WHY UNROSTERED IS BIASED TO "DROP". The rewire classifier matches a dangling
+ * ref against roster agents using the charter pillars, `orgProfile.skills`, and
+ * governance themes. In real configs those are frequently EMPTY — `title:""` and
+ * `company:"UNCONFIGURED"` are common in the wild — so the semantic signal is
+ * often nil. A classifier with no signal that still confidently proposes a rewire
+ * would silently re-point a workflow step at the wrong agent. So: rewire is
+ * proposed only on real lexical evidence, and the default verdict is
+ * `drop-or-create` with `drop` recommended, because the correct fix for a
+ * vestigial step is almost always deleting it.
+ *
+ * And the section NEVER performs the drop: it records the accepted drop in the
+ * lock and prints file:line. Rewriting a workflow changes runtime behaviour; a
+ * human owns that diff.
+ *
+ * Pure — no I/O, no network. Everything is injected. ESM.
+ *
+ * @module lib/subagents/gap
+ */
+
+"use strict";
+
+import { groupRefs } from "./refs.mjs";
+import { isAcceptedDrop } from "./lock.mjs";
+
+/** Words too common to carry any signal in a slug/skill match. */
+const STOPWORDS = new Set([
+  "agent", "agents", "the", "and", "for", "with", "ops", "op", "team", "lead",
+  "sub", "of", "to", "a", "an", "manager", "operator", "assistant", "specialist",
+]);
+
+/**
+ * Split an identifier or a phrase into comparable lowercase tokens.
+ * Handles `kebab-case`, `snake_case`, `camelCase` and free text alike, because
+ * the three signal sources are all different shapes: slugs are kebab, skills are
+ * free text, governance themes are sentences.
+ * @param {string} s
+ * @returns {string[]}
+ */
+export function tokenize(s) {
+  return String(s || "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+
+/**
+ * Build the semantic corpus for one roster agent: its slug, role, purpose/mandate
+ * and team, plus any charter pillars / skills / governance themes that mention
+ * it. The corpus is what a dangling reference is matched against.
+ * @param {object} agent @param {object} [context]
+ * @returns {Set<string>}
+ */
+export function agentCorpus(agent, context = {}) {
+  const parts = [
+    agent && agent.id,
+    agent && agent.role,
+    agent && agent.purpose,
+    agent && agent.mandate,
+    agent && agent.team,
+    ...(Array.isArray(agent && agent.towers) ? agent.towers : []),
+  ];
+  const tokens = new Set(parts.flatMap((p) => tokenize(p)));
+  // Contextual reinforcement: an org skill or charter pillar that shares tokens
+  // with this agent strengthens its corpus, which is how "the org actually does
+  // compliance" tips a `regulatory-watch` ref toward the compliance agent.
+  for (const extra of [...(context.skills || []), ...(context.pillars || []), ...(context.governance || [])]) {
+    const et = tokenize(extra);
+    if (et.some((t) => tokens.has(t))) for (const t of et) tokens.add(t);
+  }
+  return tokens;
+}
+
+/**
+ * Score a dangling reference against a roster agent: the fraction of the
+ * REFERENCE's tokens the agent's corpus covers. Reference-normalised (not
+ * Jaccard) on purpose — a rich agent corpus should not be penalised for being
+ * rich, but a two-token ref must match both tokens to score 1.
+ * @param {string} ref @param {Set<string>} corpus
+ * @returns {number} 0..1
+ */
+export function scoreRef(ref, corpus) {
+  const rt = tokenize(ref);
+  if (!rt.length) return 0;
+  let hit = 0;
+  for (const t of rt) if (corpus.has(t)) hit++;
+  return hit / rt.length;
+}
+
+/**
+ * The evidence bar a rewire suggestion must clear. Set high (2/3 of the
+ * reference's tokens) precisely because the classifier runs against frequently
+ * empty configs — see the module header. Below the bar we do not guess.
+ */
+export const REWIRE_THRESHOLD = 0.67;
+
+/**
+ * Classify one unrostered reference.
+ * @param {string} ref
+ * @param {{roster:Array<object>, context?:object}} o
+ * @returns {{ref:string, action:"rewire"|"drop-or-create", suggest:string|null, score:number, reason:string, recommend:"rewire"|"drop"}}
+ */
+export function classifyRef(ref, o = {}) {
+  const roster = Array.isArray(o.roster) ? o.roster : [];
+  const context = o.context || {};
+  let best = { id: null, score: 0 };
+  for (const a of roster) {
+    const s = scoreRef(ref, agentCorpus(a, context));
+    if (s > best.score) best = { id: a.id, score: s };
+  }
+  if (best.id && best.score >= REWIRE_THRESHOLD) {
+    return {
+      ref,
+      action: "rewire",
+      suggest: best.id,
+      score: Number(best.score.toFixed(3)),
+      recommend: "rewire",
+      reason: `"${ref}" overlaps ${Math.round(best.score * 100)}% with the roster agent "${best.id}"`,
+    };
+  }
+  return {
+    ref,
+    action: "drop-or-create",
+    suggest: best.id,
+    score: Number(best.score.toFixed(3)),
+    recommend: "drop",
+    reason: best.id
+      ? `no roster agent covers "${ref}" (closest: "${best.id}" at ${Math.round(best.score * 100)}%) — most likely a vestigial step copied by \`create\``
+      : `no roster agent resembles "${ref}" — most likely a vestigial step copied by \`create\``,
+  };
+}
+
+/**
+ * Normalise a capability surface into the flat roster the diff works over.
+ * `standardAgents ∪ roleAgents` per §2.3.
+ * @param {object} surface the resolveCapabilitySurface result
+ * @returns {Array<{id:string, role:string, purpose:string, team?:string, tier?:string, source:string}>}
+ */
+export function rosterFromSurface(surface) {
+  const out = [];
+  for (const a of (surface && surface.standardAgents) || []) {
+    if (a && a.id) out.push({ ...a, source: "standard" });
+  }
+  for (const a of (surface && surface.roleAgents) || []) {
+    if (a && a.id) out.push({ ...a, source: "role" });
+  }
+  // Dedupe by id, first wins (standard defaults are authoritative for their ids).
+  const seen = new Set();
+  return out.filter((a) => (seen.has(a.id) ? false : (seen.add(a.id), true)));
+}
+
+/**
+ * The three-way diff.
+ *
+ * @param {object} o
+ * @param {Array<object>} o.roster        the authoritative roster (rosterFromSurface)
+ * @param {object} o.resolved             the resolveSubagents result
+ * @param {Array<object>} o.refs          scanAgentRefs output
+ * @param {object} [o.lock]               for acceptedDrops
+ * @param {object} [o.context]            {skills, pillars, governance} semantic signal
+ * @returns {{missing:Array, unrostered:Array, idle:Array, localEdits:string[], status:"complete"|"partial"|"unconfigured", summary:string}}
+ */
+export function computeGaps(o = {}) {
+  const roster = Array.isArray(o.roster) ? o.roster : [];
+  const rosterIds = new Set(roster.map((a) => a.id));
+  const resolved = o.resolved || { bySlug: new Map(), entries: [] };
+  const bySlug = resolved.bySlug instanceof Map ? resolved.bySlug : new Map((resolved.entries || []).map((e) => [e.slug, e]));
+  const refs = Array.isArray(o.refs) ? o.refs : [];
+  const lock = o.lock || { acceptedDrops: [] };
+  const byRef = groupRefs(refs);
+
+  // 1. missing = roster ∖ resolved-layers
+  const missing = roster
+    .filter((a) => !bySlug.has(a.id))
+    .map((a) => ({
+      slug: a.id,
+      role: a.role || "",
+      purpose: a.purpose || a.mandate || "",
+      team: a.team || "",
+      source: a.source,
+      // What a human can do about it, in the order the prompt offers them.
+      actions: ["adopt-sdk", "fork", "create", "defer"],
+    }));
+
+  // 2. unrostered = parsed refs ∖ roster
+  const unrostered = [];
+  for (const [ref, locations] of byRef) {
+    if (rosterIds.has(ref)) continue;
+    const cls = classifyRef(ref, { roster, context: o.context });
+    unrostered.push({
+      ...cls,
+      locations,
+      resolves: bySlug.has(ref), // referenced, off-roster, but a file DOES exist
+      accepted: isAcceptedDrop(lock, ref),
+    });
+  }
+  unrostered.sort((a, b) => b.score - a.score || a.ref.localeCompare(b.ref));
+
+  // 3. idle = roster agents nothing references
+  const idle = roster
+    .filter((a) => !byRef.has(a.id))
+    .map((a) => ({ slug: a.id, role: a.role || "", team: a.team || "", source: a.source, resolves: bySlug.has(a.id) }));
+
+  // `complete` demands no missing roster agents AND every drop-or-create verdict
+  // already accepted by a human. A rewire suggestion alone does NOT block
+  // completion — it is advisory (§5.6) and the operator may legitimately ignore it.
+  const openDrops = unrostered.filter((u) => u.action === "drop-or-create" && !u.accepted && !u.resolves);
+  const status = missing.length === 0 && openDrops.length === 0 ? "complete" : (bySlug.size ? "partial" : "unconfigured");
+
+  const summary = status === "complete"
+    ? `${bySlug.size} sub-agent${bySlug.size === 1 ? "" : "s"} resolved, roster complete${idle.length ? `, ${idle.length} idle` : ""}`
+    : `${missing.length} missing, ${openDrops.length} unresolved reference${openDrops.length === 1 ? "" : "s"}, ${idle.length} idle`;
+
+  return {
+    missing,
+    unrostered,
+    openDrops,
+    idle,
+    localEdits: Array.isArray(resolved.localEdits) ? resolved.localEdits : [],
+    emptyDirs: Array.isArray(resolved.emptyDirs) ? resolved.emptyDirs : [],
+    counts: { roster: roster.length, resolved: bySlug.size, missing: missing.length, unrostered: unrostered.length, idle: idle.length },
+    status,
+    summary,
+  };
+}
+
+/**
+ * Distil the semantic signal the classifier uses from the agent's own config.
+ * Tolerant of every field being absent — which, per the module header, is the
+ * common case and is exactly why the classifier is biased to drop.
+ * @param {{agentConfig?:object, charter?:object}} o
+ * @returns {{skills:string[], pillars:string[], governance:string[]}}
+ */
+export function contextFromConfig(o = {}) {
+  const cfg = o.agentConfig || {};
+  const org = cfg.orgProfile || {};
+  const charter = o.charter || cfg.charter || {};
+  const skills = Array.isArray(org.skills) ? org.skills.map(String) : [];
+  const pillars = [
+    ...(Array.isArray(cfg.responsibilities) ? cfg.responsibilities.map(String) : []),
+    ...(Array.isArray(charter.sections) ? charter.sections.map((s) => `${(s && s.title) || ""} ${(s && s.body) || ""}`) : []),
+  ];
+  const governance = Array.isArray(org.governance)
+    ? org.governance.map((g) => (g && typeof g === "object" ? `${g.theme || ""} ${g.title || ""} ${g.description || ""}` : String(g)))
+    : [];
+  return { skills, pillars, governance };
+}