@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/subagents/gap.test.mjs

@@ -0,0 +1,234 @@
+/**
+ * gap.test.mjs — the three-way diff (§2.3): missing / unrostered / idle, and the
+ * deliberately drop-biased rewire classifier.
+ * Run: node --test lib/subagents/gap.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  REWIRE_THRESHOLD,
+  agentCorpus,
+  classifyRef,
+  computeGaps,
+  contextFromConfig,
+  rosterFromSurface,
+  scoreRef,
+  tokenize,
+} from "./gap.mjs";
+
+const resolvedOf = (slugs) => ({ entries: slugs.map((s) => ({ slug: s })), bySlug: new Map(slugs.map((s) => [s, { slug: s }])), localEdits: [], emptyDirs: [] });
+const ref = (r, file = "workflows/a.yaml", line = 3, kind = "workflow") => ({ ref: r, file, line, kind });
+
+// ---------------------------------------------------------------------------
+// tokenisation / scoring
+// ---------------------------------------------------------------------------
+
+test("tokenize: handles kebab, snake, camel and free text; drops stopwords and 1-2 char noise", () => {
+  assert.deepEqual(tokenize("regulatory-watch"), ["regulatory", "watch"]);
+  assert.deepEqual(tokenize("regulatory_watch"), ["regulatory", "watch"]);
+  assert.deepEqual(tokenize("regulatoryWatch"), ["regulatory", "watch"]);
+  assert.deepEqual(tokenize("the compliance agent for ops"), ["compliance"]);
+  assert.deepEqual(tokenize(null), []);
+});
+
+test("scoreRef: reference-normalised — a rich corpus is not penalised for being rich", () => {
+  const corpus = new Set(["compliance", "regulatory", "watch", "filings", "audit"]);
+  assert.equal(scoreRef("regulatory-watch", corpus), 1);
+  assert.equal(scoreRef("regulatory-digest", corpus), 0.5);
+  assert.equal(scoreRef("nothing-here", corpus), 0);
+  assert.equal(scoreRef("the-a", corpus), 0, "a ref with no signal tokens scores 0, never NaN");
+});
+
+test("agentCorpus: contextual skills/pillars only reinforce a corpus they already touch", () => {
+  const agent = { id: "compliance-officer", role: "Compliance", purpose: "regulatory filings" };
+  const bare = agentCorpus(agent);
+  assert.equal(bare.has("regulatory"), true);
+  assert.equal(bare.has("sox"), false);
+  const reinforced = agentCorpus(agent, { skills: ["regulatory sox reporting"], pillars: [], governance: [] });
+  assert.equal(reinforced.has("sox"), true, "shares 'regulatory' → the whole skill joins the corpus");
+  const unrelated = agentCorpus(agent, { skills: ["kubernetes cluster tuning"] });
+  assert.equal(unrelated.has("kubernetes"), false, "an unrelated skill must not pollute the corpus");
+});
+
+// ---------------------------------------------------------------------------
+// the classifier — biased to DROP because the signal is usually empty
+// ---------------------------------------------------------------------------
+
+test("classifyRef: proposes a rewire only on real lexical evidence", () => {
+  const roster = [{ id: "compliance-officer", role: "Compliance", purpose: "regulatory watch and filings" }];
+  const hit = classifyRef("regulatory-watch", { roster });
+  assert.equal(hit.action, "rewire");
+  assert.equal(hit.suggest, "compliance-officer");
+  assert.equal(hit.recommend, "rewire");
+  assert.ok(hit.score >= REWIRE_THRESHOLD);
+});
+
+test("classifyRef: below the bar it does NOT guess — the verdict is drop-or-create", () => {
+  // With title:"" and company:"UNCONFIGURED" common in the wild, a classifier
+  // with no signal that still proposes a rewire silently re-points a workflow
+  // step at the wrong agent.
+  const roster = [{ id: "compliance-officer", role: "Compliance", purpose: "regulatory filings" }];
+  const miss = classifyRef("slide-deck-builder", { roster });
+  assert.equal(miss.action, "drop-or-create");
+  assert.equal(miss.recommend, "drop");
+  assert.match(miss.reason, /vestigial step copied by `create`/);
+});
+
+test("classifyRef: an EMPTY roster still yields a usable drop verdict", () => {
+  const none = classifyRef("ghost-writer", { roster: [] });
+  assert.equal(none.action, "drop-or-create");
+  assert.equal(none.suggest, null);
+  assert.equal(none.score, 0);
+});
+
+// ---------------------------------------------------------------------------
+// roster shaping
+// ---------------------------------------------------------------------------
+
+test("rosterFromSurface: standardAgents ∪ roleAgents, deduped, tagged with its source", () => {
+  const roster = rosterFromSurface({
+    standardAgents: [{ id: "alpha", role: "A" }, { id: "shared", role: "S-standard" }],
+    roleAgents: [{ id: "shared", role: "S-role" }, { id: "beta", role: "B" }],
+  });
+  assert.deepEqual(roster.map((a) => [a.id, a.source]), [["alpha", "standard"], ["shared", "standard"], ["beta", "role"]]);
+});
+
+test("rosterFromSurface: tolerates a null/empty surface", () => {
+  assert.deepEqual(rosterFromSurface(null), []);
+  assert.deepEqual(rosterFromSurface({ standardAgents: [{ noId: 1 }] }), []);
+});
+
+// ---------------------------------------------------------------------------
+// the three-way diff
+// ---------------------------------------------------------------------------
+
+test("computeGaps: missing = roster ∖ resolved layers", () => {
+  const g = computeGaps({
+    roster: [{ id: "alpha", role: "A" }, { id: "beta", role: "B" }],
+    resolved: resolvedOf(["alpha"]),
+    refs: [ref("alpha"), ref("beta")],
+  });
+  assert.deepEqual(g.missing.map((m) => m.slug), ["beta"]);
+  assert.deepEqual(g.missing[0].actions, ["adopt-sdk", "fork", "create", "defer"]);
+});
+
+test("computeGaps: unrostered = refs ∖ roster, with file:line for the human to delete", () => {
+  const g = computeGaps({
+    roster: [{ id: "alpha" }],
+    resolved: resolvedOf(["alpha"]),
+    refs: [ref("alpha"), ref("ghost-writer", "workflows/vestigial.yaml", 12)],
+  });
+  assert.deepEqual(g.unrostered.map((u) => u.ref), ["ghost-writer"]);
+  assert.deepEqual(g.unrostered[0].locations, [{ file: "workflows/vestigial.yaml", line: 12, kind: "workflow" }]);
+});
+
+test("computeGaps: idle = roster agents NOTHING references (the check that did not exist)", () => {
+  const g = computeGaps({
+    roster: [{ id: "alpha" }, { id: "never-called", role: "Idle" }],
+    resolved: resolvedOf(["alpha", "never-called"]),
+    refs: [ref("alpha")],
+  });
+  assert.deepEqual(g.idle.map((i) => i.slug), ["never-called"]);
+  assert.equal(g.idle[0].resolves, true, "it exists — it is just dispatched to by nothing");
+});
+
+test("computeGaps: status is complete only with no missing AND no open drops", () => {
+  const clean = computeGaps({ roster: [{ id: "alpha" }], resolved: resolvedOf(["alpha"]), refs: [ref("alpha")] });
+  assert.equal(clean.status, "complete");
+  assert.match(clean.summary, /roster complete/);
+
+  const dirty = computeGaps({ roster: [{ id: "alpha" }], resolved: resolvedOf(["alpha"]), refs: [ref("ghost")] });
+  assert.equal(dirty.status, "partial");
+  assert.equal(dirty.openDrops.length, 1);
+});
+
+test("computeGaps: an ACCEPTED drop stops blocking completion (and stays visible)", () => {
+  const lock = { acceptedDrops: [{ ref: "ghost", file: "workflows/a.yaml", line: 3 }] };
+  const g = computeGaps({ roster: [{ id: "alpha" }], resolved: resolvedOf(["alpha"]), refs: [ref("alpha"), ref("ghost")], lock });
+  assert.equal(g.status, "complete");
+  assert.equal(g.openDrops.length, 0);
+  assert.equal(g.unrostered[0].accepted, true, "still reported — accepting is not forgetting");
+});
+
+test("computeGaps: an off-roster ref that DOES resolve on disk is not an open drop", () => {
+  const g = computeGaps({ roster: [{ id: "alpha" }], resolved: resolvedOf(["alpha", "extra"]), refs: [ref("alpha"), ref("extra")] });
+  assert.equal(g.unrostered[0].resolves, true);
+  assert.equal(g.openDrops.length, 0);
+  assert.equal(g.status, "complete");
+});
+
+test("computeGaps: a rewire suggestion alone is advisory and does not block completion", () => {
+  const roster = [{ id: "compliance-officer", role: "Compliance", purpose: "regulatory watch and filings" }];
+  const g = computeGaps({ roster, resolved: resolvedOf(["compliance-officer"]), refs: [ref("compliance-officer"), ref("regulatory-watch")] });
+  assert.equal(g.unrostered[0].action, "rewire");
+  assert.equal(g.openDrops.length, 0);
+  assert.equal(g.status, "complete");
+});
+
+test("computeGaps: unrostered is sorted by score, then alphabetically", () => {
+  const roster = [{ id: "compliance-officer", purpose: "regulatory watch" }];
+  const g = computeGaps({
+    roster,
+    resolved: resolvedOf([]),
+    refs: [ref("zulu-thing"), ref("alpha-thing"), ref("regulatory-watch")],
+  });
+  assert.deepEqual(g.unrostered.map((u) => u.ref), ["regulatory-watch", "alpha-thing", "zulu-thing"]);
+});
+
+test("computeGaps: carries localEdits/emptyDirs through and counts everything", () => {
+  const resolved = { ...resolvedOf(["alpha"]), localEdits: ["alpha"], emptyDirs: ["hollow"] };
+  const g = computeGaps({ roster: [{ id: "alpha" }, { id: "beta" }], resolved, refs: [ref("alpha"), ref("ghost")] });
+  assert.deepEqual(g.localEdits, ["alpha"]);
+  assert.deepEqual(g.emptyDirs, ["hollow"]);
+  assert.deepEqual(g.counts, { roster: 2, resolved: 1, missing: 1, unrostered: 1, idle: 1 });
+});
+
+test("computeGaps: nothing at all is 'complete' — there is nothing to decide", () => {
+  // An agent whose function has no capability pack has no authoritative roster.
+  // That must not block setup, so it reports complete rather than unconfigured.
+  const g = computeGaps({});
+  assert.equal(g.status, "complete");
+  assert.deepEqual(g.counts, { roster: 0, resolved: 0, missing: 0, unrostered: 0, idle: 0 });
+});
+
+test("computeGaps: 'unconfigured' means we know what is needed and NONE of it resolves", () => {
+  const g = computeGaps({ roster: [{ id: "alpha" }, { id: "beta" }], resolved: resolvedOf([]), refs: [] });
+  assert.equal(g.status, "unconfigured");
+  assert.equal(g.missing.length, 2);
+  // …and once even one resolves, it is merely partial.
+  assert.equal(computeGaps({ roster: [{ id: "alpha" }, { id: "beta" }], resolved: resolvedOf(["alpha"]), refs: [] }).status, "partial");
+});
+
+test("computeGaps: accepts a resolved shape with entries but no bySlug Map", () => {
+  const g = computeGaps({ roster: [{ id: "alpha" }], resolved: { entries: [{ slug: "alpha" }] }, refs: [ref("alpha")] });
+  assert.equal(g.status, "complete");
+});
+
+// ---------------------------------------------------------------------------
+// context extraction
+// ---------------------------------------------------------------------------
+
+test("contextFromConfig: pulls skills, responsibilities/charter pillars and governance themes", () => {
+  const c = contextFromConfig({
+    agentConfig: {
+      orgProfile: {
+        skills: ["regulatory reporting"],
+        governance: [{ theme: "risk", title: "Risk council", description: "quarterly" }, "plain string"],
+      },
+      responsibilities: ["own compliance"],
+      charter: { sections: [{ title: "Mandate", body: "watch filings" }] },
+    },
+  });
+  assert.deepEqual(c.skills, ["regulatory reporting"]);
+  assert.deepEqual(c.pillars, ["own compliance", "Mandate watch filings"]);
+  assert.equal(c.governance.length, 2);
+  assert.match(c.governance[0], /risk/);
+});
+
+test("contextFromConfig: every field absent is the COMMON case, and must not throw", () => {
+  assert.deepEqual(contextFromConfig({}), { skills: [], pillars: [], governance: [] });
+  assert.deepEqual(contextFromConfig({ agentConfig: { orgProfile: { skills: "not-an-array" } } }).skills, []);
+});

package/lib/subagents/lock.mjs

@@ -0,0 +1,296 @@
+/**
+ * lib/subagents/lock.mjs — the registry's on-disk state (§3, §4).
+ *
+ * Four artefacts, each with a distinct job and a distinct failure mode:
+ *
+ *   .maestro/subagents.lock.json   WHAT WAS MATERIALISED AND FROM WHERE. This is
+ *     the only thing that makes local-edit detection possible: without a record
+ *     of the bytes we wrote, an updated file and an edited file are
+ *     indistinguishable. Committed with the agent repo — it is provenance, not
+ *     cache.
+ *
+ *   state/subagents/cache/<slug>@<v>.md   THE OFFLINE FOURTH LAYER. Bodies fetched
+ *     from hq, kept so `apply` can materialise with no network. Accepted risk
+ *     (§6): it can go stale invisibly; `rosterVersion` in the lock vs the roster
+ *     read is the only tell, which is why `doctor` surfaces it.
+ *
+ *   state/subagents/outbox/<ts>-<op>.json   WRITES MADE OFFLINE. Replayed by
+ *     `maestro sync`. Idempotent by `contentHash` + `(orgId, slug)`, so a replay
+ *     of a write that actually landed is a no-op server-side.
+ *
+ *   state/subagents/gaps.json   THE HEADLESS VERDICT. `apply` under `--headless`
+ *     never creates an agent unattended; it writes what it found here for a human.
+ *
+ * `.maestro/` is the agent-local metadata directory (same convention as the rest
+ * of the wizard's checkpoints); `state/` is runtime scratch. The split matters:
+ * blowing away `state/` must degrade the registry (cold cache) but must NOT lose
+ * provenance.
+ *
+ * Every read is fail-open and returns a fully-shaped object; every write is
+ * atomic (lib/fs-atomic) because a half-written lock is worse than no lock — it
+ * would mark managed files as locally edited and freeze them.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/subagents/lock
+ */
+
+"use strict";
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { writeJsonAtomic, writeFileAtomic } from "../fs-atomic.mjs";
+
+export const LOCK_REL = join(".maestro", "subagents.lock.json");
+export const CACHE_REL = join("state", "subagents", "cache");
+export const OUTBOX_REL = join("state", "subagents", "outbox");
+export const GAPS_REL = join("state", "subagents", "gaps.json");
+
+/** The empty-but-valid lock. Every reader gets this shape, never null. */
+export function emptyLock() {
+  return { version: 1, rosterVersion: 0, degraded: [], acceptedDrops: [], agents: {} };
+}
+
+export function lockPath(agentRoot) { return join(agentRoot, LOCK_REL); }
+export function cacheDir(agentRoot) { return join(agentRoot, CACHE_REL); }
+export function outboxDir(agentRoot) { return join(agentRoot, OUTBOX_REL); }
+export function gapsPath(agentRoot) { return join(agentRoot, GAPS_REL); }
+
+/**
+ * Read the lock. Fail-open → {@link emptyLock}. Fields are coerced to their
+ * declared types so a hand-edited lock can never make a consumer crash on
+ * `.agents[x].contentHash` of a string.
+ * @param {string} agentRoot
+ * @returns {{version:number, rosterVersion:number, degraded:string[], acceptedDrops:object[], agents:Record<string,object>}}
+ */
+export function readLock(agentRoot) {
+  const p = lockPath(agentRoot);
+  if (!existsSync(p)) return emptyLock();
+  let doc;
+  try { doc = JSON.parse(readFileSync(p, "utf8")); } catch { return emptyLock(); }
+  if (!doc || typeof doc !== "object") return emptyLock();
+  const agents = {};
+  for (const [slug, e] of Object.entries(doc.agents && typeof doc.agents === "object" ? doc.agents : {})) {
+    if (!e || typeof e !== "object") continue;
+    agents[slug] = {
+      layer: String(e.layer || ""),
+      definitionId: e.definitionId ? String(e.definitionId) : null,
+      version: Number.isFinite(e.version) ? e.version : null,
+      contentHash: e.contentHash ? String(e.contentHash) : "",
+      fileHash: e.fileHash ? String(e.fileHash) : "",
+      source: e.source ? String(e.source) : "",
+      localEdits: !!e.localEdits,
+      materialisedAt: e.materialisedAt ? String(e.materialisedAt) : "",
+    };
+  }
+  return {
+    version: Number.isFinite(doc.version) ? doc.version : 1,
+    rosterVersion: Number.isFinite(doc.rosterVersion) ? doc.rosterVersion : 0,
+    degraded: Array.isArray(doc.degraded) ? doc.degraded.map(String) : [],
+    acceptedDrops: Array.isArray(doc.acceptedDrops) ? doc.acceptedDrops.filter((d) => d && typeof d === "object") : [],
+    agents,
+  };
+}
+
+/**
+ * Write the lock atomically. Returns false (never throws) on IO failure — a
+ * failed lock write degrades the NEXT run to "everything looks locally edited",
+ * which is safe, so it must not abort the current one (and `apply` throws are
+ * fatal in lib/setup/runner.mjs:220-227).
+ * @param {string} agentRoot @param {object} lock @returns {boolean}
+ */
+export function writeLock(agentRoot, lock) {
+  try {
+    writeJsonAtomic(lockPath(agentRoot), lock);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read-modify-write the lock. `patch` may carry `agents` (merged per slug),
+ * `degraded`/`acceptedDrops` (replaced when supplied) and `rosterVersion`.
+ * @param {string} agentRoot
+ * @param {object} patch
+ * @returns {object} the merged lock (written to disk)
+ */
+export function mergeLock(agentRoot, patch = {}) {
+  const cur = readLock(agentRoot);
+  const next = { ...cur };
+  if (Number.isFinite(patch.rosterVersion)) next.rosterVersion = patch.rosterVersion;
+  if (Array.isArray(patch.degraded)) next.degraded = [...new Set(patch.degraded.map(String))];
+  if (Array.isArray(patch.acceptedDrops)) next.acceptedDrops = patch.acceptedDrops;
+  if (patch.agents && typeof patch.agents === "object") {
+    next.agents = { ...cur.agents };
+    for (const [slug, e] of Object.entries(patch.agents)) {
+      if (e === null) { delete next.agents[slug]; continue; }
+      next.agents[slug] = { ...(cur.agents[slug] || {}), ...e };
+    }
+  }
+  writeLock(agentRoot, next);
+  return next;
+}
+
+/**
+ * Record an accepted drop: the operator agreed that a reference is vestigial and
+ * the workflow step should go. We store the LOCATION, never edit the file (§2.3 —
+ * "never auto-edits or deletes a workflow"), because a workflow step's removal
+ * changes runtime behaviour and only a human should own that diff.
+ * @param {string} agentRoot
+ * @param {{ref:string, file?:string, line?:number, reason?:string}} drop
+ * @returns {object} the merged lock
+ */
+export function acceptDrop(agentRoot, drop) {
+  const cur = readLock(agentRoot);
+  const key = `${drop.ref}@${drop.file || ""}:${drop.line || 0}`;
+  const kept = cur.acceptedDrops.filter((d) => `${d.ref}@${d.file || ""}:${d.line || 0}` !== key);
+  kept.push({
+    ref: String(drop.ref),
+    file: drop.file ? String(drop.file) : "",
+    line: Number.isFinite(drop.line) ? drop.line : 0,
+    reason: drop.reason ? String(drop.reason) : "",
+    acceptedAt: new Date().toISOString(),
+  });
+  return mergeLock(agentRoot, { acceptedDrops: kept });
+}
+
+/** Is this reference already an accepted drop? @returns {boolean} */
+export function isAcceptedDrop(lock, ref) {
+  return (lock && Array.isArray(lock.acceptedDrops) ? lock.acceptedDrops : []).some((d) => d && d.ref === ref);
+}
+
+// ---------------------------------------------------------------------------
+// Cache (the offline fourth layer)
+// ---------------------------------------------------------------------------
+
+/** `<slug>@<version>.md` — version in the NAME so several versions coexist. */
+export function cachePath(agentRoot, slug, version) {
+  return join(cacheDir(agentRoot), `${slug}@${version == null ? "head" : version}.md`);
+}
+
+/** Write a fetched body to the cache. Fail-open → false. */
+export function writeCache(agentRoot, slug, version, text) {
+  try {
+    writeFileAtomic(cachePath(agentRoot, slug, version), typeof text === "string" ? text : "");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read a specific cached version. @returns {string|null} */
+export function readCache(agentRoot, slug, version) {
+  const p = cachePath(agentRoot, slug, version);
+  if (!existsSync(p)) return null;
+  try { return readFileSync(p, "utf8"); } catch { return null; }
+}
+
+/**
+ * The highest-versioned cached body for a slug — what a cold-start offline
+ * resolution falls back to. Returns null when nothing is cached.
+ * @param {string} agentRoot @param {string} slug
+ * @returns {{version:number|null, text:string, path:string}|null}
+ */
+export function latestCached(agentRoot, slug) {
+  const dir = cacheDir(agentRoot);
+  if (!existsSync(dir)) return null;
+  let names;
+  try { names = readdirSync(dir); } catch { return null; }
+  const prefix = `${slug}@`;
+  let best = null;
+  for (const n of names) {
+    if (!n.startsWith(prefix) || !n.endsWith(".md")) continue;
+    const v = n.slice(prefix.length, -3);
+    const num = /^\d+$/.test(v) ? Number(v) : null;
+    if (!best || (num !== null && (best.version === null || num > best.version))) best = { version: num, name: n };
+  }
+  if (!best) return null;
+  const p = join(dir, best.name);
+  try { return { version: best.version, text: readFileSync(p, "utf8"), path: p }; } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// Outbox (offline writes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Monotonic within a process. Together with the random suffix below it is what
+ * makes two queued writes in the SAME millisecond distinct files.
+ */
+let outboxSeq = 0;
+
+/**
+ * Queue a write that could not reach hq. The filename carries the timestamp so
+ * replay is chronological, and the payload carries everything needed to retry
+ * verbatim — no re-derivation at replay time (the local file may have changed
+ * again by then, and replaying a DIFFERENT body than the operator approved is the
+ * worst outcome available).
+ *
+ * WHY THE NAME IS NOT JUST THE TIMESTAMP. `create` immediately followed by `pin`
+ * (the `add`/`fork` path, and the section's apply) queues two writes inside the
+ * same millisecond. With a timestamp-only name the second silently OVERWRITES
+ * the first and the operator's work is lost — the exact failure the outbox
+ * exists to prevent. The sequence counter orders writes within a process and the
+ * random suffix keeps two processes from colliding on the same millisecond.
+ *
+ * @param {string} agentRoot @param {string} op @param {object} payload
+ * @returns {string|null} the queued path, or null on IO failure
+ */
+export function queueOutbox(agentRoot, op, payload) {
+  try {
+    mkdirSync(outboxDir(agentRoot), { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const seq = String(++outboxSeq).padStart(4, "0");
+    const salt = randomBytes(3).toString("hex");
+    const p = join(outboxDir(agentRoot), `${ts}-${seq}-${salt}-${String(op).replace(/[^\w.-]/g, "_")}.json`);
+    writeFileSync(p, JSON.stringify({ op: String(op), payload: payload || {}, queuedAt: new Date().toISOString() }, null, 2));
+    return p;
+  } catch {
+    return null;
+  }
+}
+
+/** List queued writes, oldest first. Fail-open → []. */
+export function listOutbox(agentRoot) {
+  const dir = outboxDir(agentRoot);
+  if (!existsSync(dir)) return [];
+  let names;
+  try { names = readdirSync(dir).filter((n) => n.endsWith(".json")).sort(); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    const p = join(dir, n);
+    try {
+      const doc = JSON.parse(readFileSync(p, "utf8"));
+      if (doc && doc.op) out.push({ path: p, op: String(doc.op), payload: doc.payload || {}, queuedAt: doc.queuedAt || "" });
+    } catch { /* a corrupt entry is skipped, not fatal */ }
+  }
+  return out;
+}
+
+/** Remove a replayed outbox entry. Fail-open → false. */
+export function removeOutbox(path) {
+  try { unlinkSync(path); return true; } catch { return false; }
+}
+
+// ---------------------------------------------------------------------------
+// Gaps report
+// ---------------------------------------------------------------------------
+
+/** Persist the headless gap verdict. Fail-open → false. */
+export function writeGaps(agentRoot, gaps) {
+  try {
+    writeJsonAtomic(gapsPath(agentRoot), { generatedAt: new Date().toISOString(), ...gaps });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read the last gap verdict. @returns {object|null} */
+export function readGaps(agentRoot) {
+  const p = gapsPath(agentRoot);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}