@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/subagents/lock.test.mjs

@@ -0,0 +1,248 @@
+/**
+ * lock.test.mjs — the registry's on-disk state (§3, §4): the lock (provenance),
+ * the cache (the offline fourth layer), the outbox (offline writes) and the
+ * headless gaps report.
+ * Run: node --test lib/subagents/lock.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 { dirname, join } from "node:path";
+
+import {
+  CACHE_REL,
+  GAPS_REL,
+  LOCK_REL,
+  OUTBOX_REL,
+  acceptDrop,
+  cacheDir,
+  cachePath,
+  emptyLock,
+  gapsPath,
+  isAcceptedDrop,
+  latestCached,
+  listOutbox,
+  lockPath,
+  mergeLock,
+  outboxDir,
+  queueOutbox,
+  readCache,
+  readGaps,
+  readLock,
+  removeOutbox,
+  writeCache,
+  writeGaps,
+  writeLock,
+} from "./lock.mjs";
+
+const root = () => mkdtempSync(join(tmpdir(), "subagent-lock-"));
+
+// ---------------------------------------------------------------------------
+// lock
+// ---------------------------------------------------------------------------
+
+test("paths: the lock is provenance (.maestro/), the rest is scratch (state/)", () => {
+  // Blowing away state/ must DEGRADE the registry (cold cache) but never lose
+  // provenance — that split is the whole reason for two directories.
+  assert.equal(LOCK_REL, join(".maestro", "subagents.lock.json"));
+  assert.equal(CACHE_REL, join("state", "subagents", "cache"));
+  assert.equal(OUTBOX_REL, join("state", "subagents", "outbox"));
+  assert.equal(GAPS_REL, join("state", "subagents", "gaps.json"));
+  const r = root();
+  assert.equal(lockPath(r), join(r, LOCK_REL));
+  assert.equal(cacheDir(r), join(r, CACHE_REL));
+  assert.equal(outboxDir(r), join(r, OUTBOX_REL));
+  assert.equal(gapsPath(r), join(r, GAPS_REL));
+});
+
+test("readLock: missing OR corrupt → the empty-but-valid shape, never null", () => {
+  const r = root();
+  assert.deepEqual(readLock(r), emptyLock());
+  mkdirSync(join(r, ".maestro"), { recursive: true });
+  writeFileSync(lockPath(r), "{ not json");
+  assert.deepEqual(readLock(r), emptyLock());
+  writeFileSync(lockPath(r), '"a string"');
+  assert.deepEqual(readLock(r), emptyLock());
+});
+
+test("readLock: coerces every field so a hand-edited lock cannot crash a consumer", () => {
+  const r = root();
+  mkdirSync(join(r, ".maestro"), { recursive: true });
+  writeFileSync(lockPath(r), JSON.stringify({
+    version: "nope",
+    rosterVersion: "7",
+    degraded: "workspace",
+    acceptedDrops: [{ ref: "x" }, "junk", null],
+    agents: { alpha: { layer: 3, version: "9", contentHash: 5, localEdits: "yes" }, bad: "not-an-object" },
+  }));
+  const lock = readLock(r);
+  assert.equal(lock.version, 1);
+  assert.equal(lock.rosterVersion, 0, "a string rosterVersion is not finite → 0");
+  assert.deepEqual(lock.degraded, []);
+  assert.deepEqual(lock.acceptedDrops, [{ ref: "x" }]);
+  assert.equal(lock.agents.alpha.layer, "3");
+  assert.equal(lock.agents.alpha.version, null);
+  assert.equal(lock.agents.alpha.contentHash, "5");
+  assert.equal(lock.agents.alpha.localEdits, true);
+  assert.equal("bad" in lock.agents, false);
+});
+
+test("writeLock / mergeLock: per-slug merge, null deletes, arrays replace", () => {
+  const r = root();
+  assert.equal(writeLock(r, { ...emptyLock(), agents: { alpha: { layer: "sdk", fileHash: "h1" } } }), true);
+
+  const merged = mergeLock(r, { agents: { alpha: { fileHash: "h2" }, beta: { layer: "workspace" } }, rosterVersion: 5 });
+  assert.equal(merged.agents.alpha.layer, "sdk", "existing keys survive the merge");
+  assert.equal(merged.agents.alpha.fileHash, "h2");
+  assert.equal(merged.agents.beta.layer, "workspace");
+  assert.equal(merged.rosterVersion, 5);
+  assert.deepEqual(readLock(r).agents.beta.layer, "workspace", "written to disk");
+
+  const dropped = mergeLock(r, { agents: { beta: null } });
+  assert.equal("beta" in dropped.agents, false);
+  assert.equal(dropped.rosterVersion, 5, "unsupplied fields are untouched");
+});
+
+test("mergeLock: degraded is deduped", () => {
+  const r = root();
+  const l = mergeLock(r, { degraded: ["workspace", "workspace", "assessment"] });
+  assert.deepEqual(l.degraded, ["workspace", "assessment"]);
+});
+
+test("writeLock: fail-open (returns false) rather than throwing", () => {
+  // A failed lock write degrades the NEXT run to "everything looks locally
+  // edited" — safe. It must not abort the current one, because apply() throws
+  // are fatal to the whole wizard.
+  const r = root();
+  writeFileSync(join(r, ".maestro"), "i am a file, not a directory");
+  assert.equal(writeLock(r, emptyLock()), false);
+});
+
+// ---------------------------------------------------------------------------
+// accepted drops — the section NEVER edits a workflow, it records the location
+// ---------------------------------------------------------------------------
+
+test("acceptDrop: records ref + file:line, dedupes on the same location", () => {
+  const r = root();
+  acceptDrop(r, { ref: "ghost", file: "workflows/a.yaml", line: 12, reason: "vestigial" });
+  acceptDrop(r, { ref: "ghost", file: "workflows/a.yaml", line: 12, reason: "vestigial again" });
+  acceptDrop(r, { ref: "ghost", file: "workflows/b.yaml", line: 3 });
+  const lock = readLock(r);
+  assert.equal(lock.acceptedDrops.length, 2);
+  assert.equal(lock.acceptedDrops[0].reason, "vestigial again");
+  assert.ok(lock.acceptedDrops[0].acceptedAt);
+  assert.equal(isAcceptedDrop(lock, "ghost"), true);
+  assert.equal(isAcceptedDrop(lock, "other"), false);
+  assert.equal(isAcceptedDrop(null, "ghost"), false);
+});
+
+// ---------------------------------------------------------------------------
+// cache — the offline fourth layer
+// ---------------------------------------------------------------------------
+
+test("writeCache / readCache: version lives in the filename so versions coexist", () => {
+  const r = root();
+  assert.equal(writeCache(r, "alpha", 1, "v1 body"), true);
+  assert.equal(writeCache(r, "alpha", 2, "v2 body"), true);
+  assert.equal(readCache(r, "alpha", 1), "v1 body");
+  assert.equal(readCache(r, "alpha", 2), "v2 body");
+  assert.equal(readCache(r, "alpha", 3), null);
+  assert.equal(cachePath(r, "alpha", 2).endsWith("alpha@2.md"), true);
+  assert.equal(cachePath(r, "alpha", null).endsWith("alpha@head.md"), true);
+});
+
+test("latestCached: highest numeric version wins; null when nothing is cached", () => {
+  const r = root();
+  assert.equal(latestCached(r, "alpha"), null);
+  writeCache(r, "alpha", 2, "two");
+  writeCache(r, "alpha", 10, "ten");
+  writeCache(r, "alpha", 3, "three");
+  writeCache(r, "beta", 1, "beta-one");
+  const best = latestCached(r, "alpha");
+  assert.equal(best.version, 10);
+  assert.equal(best.text, "ten");
+  assert.equal(latestCached(r, "gamma"), null, "prefix match must not leak across slugs");
+});
+
+// ---------------------------------------------------------------------------
+// outbox — offline writes
+// ---------------------------------------------------------------------------
+
+test("queueOutbox / listOutbox: chronological, payload stored VERBATIM", () => {
+  const r = root();
+  // Verbatim matters: at replay time the local file may have changed again, and
+  // replaying a different body than the operator approved is the worst outcome.
+  const p1 = queueOutbox(r, "subagent.create", { slug: "alpha", body: "b1" });
+  const p2 = queueOutbox(r, "subagent.pin", { slug: "alpha" });
+  assert.ok(p1 && p2);
+  const list = listOutbox(r);
+  assert.equal(list.length, 2);
+  assert.deepEqual(list.map((e) => e.op).sort(), ["subagent.create", "subagent.pin"]);
+  const create = list.find((e) => e.op === "subagent.create");
+  assert.deepEqual(create.payload, { slug: "alpha", body: "b1" });
+  assert.ok(create.queuedAt);
+  assert.equal(listOutbox(r).map((e) => e.path).every(existsSync), true);
+});
+
+test("queueOutbox: two writes of the SAME op in the same millisecond do not collide", () => {
+  // `create` immediately followed by `pin` queues twice inside one millisecond.
+  // A timestamp-only filename made the second overwrite the first and silently
+  // lost the operator's work — the exact failure the outbox exists to prevent.
+  const r = root();
+  for (let i = 0; i < 25; i++) queueOutbox(r, "subagent.pin", { slug: `s${i}` });
+  const list = listOutbox(r);
+  assert.equal(list.length, 25);
+  assert.deepEqual(list.map((e) => e.payload.slug), Array.from({ length: 25 }, (_, i) => `s${i}`), "and replay order is still chronological");
+});
+
+test("listOutbox: a corrupt entry is skipped, never fatal; missing dir → []", () => {
+  const r = root();
+  assert.deepEqual(listOutbox(r), []);
+  queueOutbox(r, "subagent.pin", { slug: "alpha" });
+  writeFileSync(join(outboxDir(r), "0000-corrupt.json"), "{ nope");
+  const list = listOutbox(r);
+  assert.equal(list.length, 1);
+  assert.equal(list[0].op, "subagent.pin");
+});
+
+test("removeOutbox: removes a replayed entry, fail-open on a missing path", () => {
+  const r = root();
+  const p = queueOutbox(r, "subagent.pin", {});
+  assert.equal(removeOutbox(p), true);
+  assert.deepEqual(listOutbox(r), []);
+  assert.equal(removeOutbox(p), false);
+});
+
+test("queueOutbox: sanitises the op so a hostile op name cannot escape the outbox", () => {
+  const r = root();
+  const p = queueOutbox(r, "subagent.pin/../../evil", {});
+  // The separators are stripped, so the file lands in the outbox directory
+  // itself — path traversal via the op name is not representable.
+  assert.equal(dirname(p), outboxDir(r));
+  assert.equal(listOutbox(r).length, 1);
+});
+
+// ---------------------------------------------------------------------------
+// gaps report
+// ---------------------------------------------------------------------------
+
+test("writeGaps / readGaps: stamps generatedAt and round trips", () => {
+  const r = root();
+  assert.equal(readGaps(r), null);
+  assert.equal(writeGaps(r, { summary: "1 missing", counts: { missing: 1 } }), true);
+  const g = readGaps(r);
+  assert.equal(g.summary, "1 missing");
+  assert.deepEqual(g.counts, { missing: 1 });
+  assert.ok(g.generatedAt);
+  assert.equal(JSON.parse(readFileSync(gapsPath(r), "utf8")).summary, "1 missing");
+});
+
+test("readGaps: fail-open on a corrupt report", () => {
+  const r = root();
+  mkdirSync(join(r, "state", "subagents"), { recursive: true });
+  writeFileSync(gapsPath(r), "{ nope");
+  assert.equal(readGaps(r), null);
+});

package/lib/subagents/manifest.mjs

@@ -0,0 +1,224 @@
+/**
+ * lib/subagents/manifest.mjs — layer 0 (the SDK package) gets a manifest (§2.2).
+ *
+ * WHY. `agents/` is copied verbatim by `create` (bin/maestro.mjs:99-116) and is in
+ * `UPGRADE_PATHS` as a MERGE path — an upgrade adds new files but never touches
+ * one that already exists. That is the correct default (a human's edit is
+ * sacred) and it is also why layer-0 fixes never reached deployed agents: an
+ * upgraded agent.md is indistinguishable from an edited one.
+ *
+ * The manifest breaks that tie WITHOUT a breaking change. `agents/manifest.json`
+ * carries a sha256 per shipped agent; a file on disk whose hash equals a manifest
+ * sha is a pristine COPY (managed — safe to re-materialise) and anything else is
+ * a local edit (sacred — never overwritten without `--force`). This is the graft
+ * that lets `create`'s copy list and `UPGRADE_PATHS` stay exactly as they are —
+ * no migration, no breaking change, no re-scaffold of the deployed fleet.
+ *
+ * It also finally satisfies the phantom read at
+ * `scripts/poller/slack-cloud-relay-client.mjs:66`, which has been reading a
+ * never-generated `agents/index.json` since it was written.
+ *
+ * The manifest is CHECKED IN and regenerated by
+ * `scripts/setup/gen-subagent-manifest.mjs` at prepublish. `agents/` is already
+ * in package.json `files`, so it ships with the npm package with no packaging
+ * change.
+ *
+ * Fail-open everywhere: a missing/corrupt manifest degrades layer 0 to "no
+ * managed files", which makes every on-disk file look locally edited — the SAFE
+ * direction (we never clobber), never the destructive one.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/subagents/manifest
+ */
+
+"use strict";
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+import { checkAgentFile, hashBody, hashFile, normaliseModel, parseAgentMd } from "./schema.mjs";
+
+/** Path of the manifest relative to a maestro/SDK root. */
+export const MANIFEST_REL = join("agents", "manifest.json");
+
+/** @param {string} maestroRoot @returns {string} */
+export function manifestPath(maestroRoot) {
+  return join(maestroRoot, MANIFEST_REL);
+}
+
+/** @param {string} maestroRoot @param {string} slug @returns {string} */
+export function sdkAgentPath(maestroRoot, slug) {
+  return join(maestroRoot, "agents", String(slug), "agent.md");
+}
+
+/**
+ * Read the shipped manifest. Returns a normalised, always-shaped object so
+ * callers never null-check the inner maps. Fail-open → `{sdkVersion:"", agents:{}}`.
+ * @param {string} maestroRoot
+ * @returns {{sdkVersion:string, generatedAt?:string, agents:Record<string,object>}}
+ */
+export function readManifest(maestroRoot) {
+  const p = manifestPath(maestroRoot);
+  if (!existsSync(p)) return { sdkVersion: "", agents: {} };
+  try {
+    const doc = JSON.parse(readFileSync(p, "utf8"));
+    const agents = doc && typeof doc.agents === "object" && doc.agents ? doc.agents : {};
+    return { sdkVersion: String((doc && doc.sdkVersion) || ""), generatedAt: doc && doc.generatedAt, agents };
+  } catch {
+    // A corrupt manifest means "layer 0 has no managed files" — every on-disk
+    // file then classifies as a local edit and is left alone. Degraded, safe.
+    return { sdkVersion: "", agents: {} };
+  }
+}
+
+/** Slugs the SDK ships. @param {object} manifest @returns {string[]} */
+export function manifestSlugs(manifest) {
+  return Object.keys((manifest && manifest.agents) || {}).sort();
+}
+
+/**
+ * Every file-sha the SDK has EVER shipped for any agent, as one set.
+ *
+ * Deliberately flattened across slugs: classification asks "is this file
+ * something the SDK put here", and a file that was moved/renamed between slugs
+ * is still not a human edit. Keeping this a set (rather than a per-slug lookup)
+ * also lets a future manifest carry a `history:[]` of prior shas so an agent that
+ * skipped three releases still classifies its files as managed.
+ * @param {object} manifest
+ * @returns {Set<string>}
+ */
+export function manifestShas(manifest) {
+  const out = new Set();
+  for (const entry of Object.values((manifest && manifest.agents) || {})) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.sha256) out.add(String(entry.sha256));
+    for (const h of Array.isArray(entry.history) ? entry.history : []) if (h) out.add(String(h));
+  }
+  return out;
+}
+
+/**
+ * Is this exact file text something the SDK shipped (i.e. NOT a local edit)?
+ * @param {object} manifest @param {string} fileText @returns {boolean}
+ */
+export function isManagedByManifest(manifest, fileText) {
+  if (typeof fileText !== "string" || !fileText) return false;
+  return manifestShas(manifest).has(hashFile(fileText));
+}
+
+/**
+ * Read a shipped agent.md from the SDK root.
+ * @param {string} maestroRoot @param {string} slug
+ * @returns {{slug:string, path:string, text:string, fileHash:string, frontmatter:object, body:string}|null}
+ */
+export function readSdkAgent(maestroRoot, slug) {
+  const p = sdkAgentPath(maestroRoot, slug);
+  if (!existsSync(p)) return null;
+  let text;
+  try { text = readFileSync(p, "utf8"); } catch { return null; }
+  const parsed = parseAgentMd(text);
+  return { slug: String(slug), path: p, text, fileHash: hashFile(text), frontmatter: parsed.frontmatter, body: parsed.body };
+}
+
+/**
+ * List the agent slugs physically present under `<root>/agents/` — a directory
+ * with an `agent.md` in it. A directory WITHOUT one is not an agent (that empty
+ * directory is exactly what used to pass `doctor`), so it is reported separately
+ * as `empty` rather than silently ignored.
+ * @param {string} root
+ * @returns {{slugs:string[], empty:string[]}}
+ */
+export function listAgentDirs(root) {
+  const dir = join(root, "agents");
+  if (!existsSync(dir)) return { slugs: [], empty: [] };
+  const slugs = [];
+  const empty = [];
+  let names;
+  try { names = readdirSync(dir); } catch { return { slugs: [], empty: [] }; }
+  for (const name of names.sort()) {
+    if (name.startsWith(".")) continue;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (!st.isDirectory()) continue;
+    if (existsSync(join(full, "agent.md"))) slugs.push(name);
+    else empty.push(name);
+  }
+  return { slugs, empty };
+}
+
+/**
+ * Build the manifest by scanning `<maestroRoot>/agents/*`/agent.md.
+ *
+ * Each entry carries the frontmatter facts a REMOTE consumer needs to make a
+ * routing/rewire decision without downloading the body (description, model,
+ * tools, tier, functions) plus the two hashes:
+ *   sha256   — of the whole FILE, for local-edit classification
+ *   bodyHash — of the body only, so it is comparable with hq's
+ *              `SubagentVersion.contentHash` (same preimage as `hashBody`)
+ *
+ * Validation is reported, not enforced: a malformed shipped agent.md still gets
+ * an entry (so it stays classifiable as managed) but is listed under `invalid`
+ * so the generator can fail CI on it.
+ *
+ * @param {{maestroRoot:string, sdkVersion?:string, previous?:object, now?:Date}} o
+ * @returns {{manifest:object, invalid:Array<{slug:string, errors:string[]}>}}
+ */
+export function buildManifest(o = {}) {
+  const maestroRoot = o.maestroRoot;
+  const { slugs, empty } = listAgentDirs(maestroRoot);
+  const prev = (o.previous && o.previous.agents) || {};
+  const agents = {};
+  const invalid = [];
+
+  for (const slug of slugs) {
+    const p = sdkAgentPath(maestroRoot, slug);
+    let text;
+    try { text = readFileSync(p, "utf8"); } catch { continue; }
+    const checked = checkAgentFile(text, slug);
+    if (!checked.ok) invalid.push({ slug, errors: checked.errors });
+
+    const fm = checked.frontmatter || {};
+    const sha256 = hashFile(text);
+    // Carry forward the PREVIOUS sha as history so an agent upgrading across
+    // several releases still classifies its untouched file as managed rather
+    // than as a local edit (which would freeze it forever).
+    const prevEntry = prev[slug] || {};
+    const history = [...new Set([...(Array.isArray(prevEntry.history) ? prevEntry.history : []), prevEntry.sha256].filter(Boolean))]
+      .filter((h) => h !== sha256)
+      .slice(-10);
+
+    agents[slug] = {
+      description: String(fm.description || ""),
+      model: normaliseModel(fm.model) || String(fm.model || ""),
+      tools: Array.isArray(fm.tools) ? fm.tools.map(String) : [],
+      tier: String(fm.tier || "standard"),
+      functions: Array.isArray(fm.functions) ? fm.functions.map(String) : [],
+      tokens: Array.isArray(checked.normalised && checked.normalised.frontmatter.tokens)
+        ? checked.normalised.frontmatter.tokens
+        : [],
+      sha256,
+      bodyHash: hashBody(checked.body || ""),
+      ...(history.length ? { history } : {}),
+    };
+  }
+
+  const manifest = {
+    sdkVersion: String(o.sdkVersion || ""),
+    generatedAt: (o.now || new Date()).toISOString(),
+    agents,
+  };
+  if (empty.length) manifest.emptyDirs = empty;
+  return { manifest, invalid };
+}
+
+/**
+ * Write the manifest atomically. Returns the path.
+ * @param {string} maestroRoot @param {object} manifest @returns {string}
+ */
+export function writeManifest(maestroRoot, manifest) {
+  const p = manifestPath(maestroRoot);
+  writeJsonAtomic(p, manifest);
+  return p;
+}

package/lib/subagents/manifest.test.mjs

@@ -0,0 +1,175 @@
+/**
+ * manifest.test.mjs — layer 0's index (§2.2): the sha256 classification that
+ * makes shipped agent.md files updatable WITHOUT touching `create`'s copy list
+ * or `UPGRADE_PATHS`.
+ * Run: node --test lib/subagents/manifest.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  MANIFEST_REL,
+  buildManifest,
+  isManagedByManifest,
+  listAgentDirs,
+  manifestPath,
+  manifestShas,
+  manifestSlugs,
+  readManifest,
+  readSdkAgent,
+  writeManifest,
+} from "./manifest.mjs";
+import { hashBody, hashFile, stringifyAgentMd } from "./schema.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function sdkRoot() {
+  return mkdtempSync(join(tmpdir(), "subagent-manifest-"));
+}
+function putAgent(root, slug, over = {}, body = "# body\n\nprose\n") {
+  const fm = { name: slug, description: `${slug} does things`, model: "sonnet", tools: ["Read"], ...over };
+  const text = stringifyAgentMd(fm, body);
+  mkdirSync(join(root, "agents", slug), { recursive: true });
+  writeFileSync(join(root, "agents", slug, "agent.md"), text);
+  return text;
+}
+
+// ---------------------------------------------------------------------------
+
+test("listAgentDirs: an agents/<slug>/ with NO agent.md is reported empty, not ignored", () => {
+  // That empty directory is exactly what used to pass `doctor`.
+  const root = sdkRoot();
+  putAgent(root, "alpha");
+  mkdirSync(join(root, "agents", "hollow"), { recursive: true });
+  writeFileSync(join(root, "agents", "loose-file.txt"), "x");
+  const { slugs, empty } = listAgentDirs(root);
+  assert.deepEqual(slugs, ["alpha"]);
+  assert.deepEqual(empty, ["hollow"]);
+});
+
+test("listAgentDirs: fail-open when agents/ does not exist", () => {
+  assert.deepEqual(listAgentDirs(sdkRoot()), { slugs: [], empty: [] });
+});
+
+test("buildManifest: one entry per agent, with BOTH hashes and the routing facts", () => {
+  const root = sdkRoot();
+  const text = putAgent(root, "alpha", { tier: "standard", functions: ["executive-operator"] }, "# alpha\n\nhi {{agent.firstName}}\n");
+  const { manifest, invalid } = buildManifest({ maestroRoot: root, sdkVersion: "9.9.9", now: new Date("2026-01-01T00:00:00Z") });
+
+  assert.deepEqual(invalid, []);
+  assert.equal(manifest.sdkVersion, "9.9.9");
+  assert.equal(manifest.generatedAt, "2026-01-01T00:00:00.000Z");
+  const e = manifest.agents.alpha;
+  assert.equal(e.sha256, hashFile(text), "sha256 is the WHOLE file (local-edit classification)");
+  assert.equal(e.bodyHash, hashBody("# alpha\n\nhi {{agent.firstName}}\n"), "bodyHash matches hq's contentHash preimage");
+  assert.notEqual(e.sha256, e.bodyHash);
+  assert.equal(e.model, "claude-sonnet-4-6", "the alias is normalised in the manifest");
+  assert.deepEqual(e.tools, ["Read"]);
+  assert.equal(e.tier, "standard");
+  assert.deepEqual(e.functions, ["executive-operator"]);
+  assert.deepEqual(e.tokens, ["agent.firstName"]);
+});
+
+test("buildManifest: an INVALID agent.md still gets an entry (so it stays classifiable)", () => {
+  const root = sdkRoot();
+  putAgent(root, "alpha", { name: "wrong-name" });
+  const { manifest, invalid } = buildManifest({ maestroRoot: root });
+  assert.equal(invalid.length, 1);
+  assert.equal(invalid[0].slug, "alpha");
+  assert.ok(manifest.agents.alpha, "still listed — otherwise every deployed copy would freeze as a local edit");
+});
+
+test("buildManifest: carries the PREVIOUS sha forward as history (multi-release upgrades)", () => {
+  const root = sdkRoot();
+  putAgent(root, "alpha", {}, "v1\n");
+  const first = buildManifest({ maestroRoot: root, sdkVersion: "1.0.0" }).manifest;
+  const shaV1 = first.agents.alpha.sha256;
+
+  putAgent(root, "alpha", {}, "v2\n");
+  const second = buildManifest({ maestroRoot: root, sdkVersion: "2.0.0", previous: first }).manifest;
+  assert.notEqual(second.agents.alpha.sha256, shaV1);
+  assert.deepEqual(second.agents.alpha.history, [shaV1]);
+
+  // An agent still holding the v1 bytes classifies as MANAGED, not locally edited.
+  assert.equal(manifestShas(second).has(shaV1), true);
+});
+
+test("buildManifest: history never contains the current sha and is capped at 10", () => {
+  const root = sdkRoot();
+  let manifest = { agents: {} };
+  for (let i = 0; i < 14; i++) {
+    putAgent(root, "alpha", {}, `v${i}\n`);
+    manifest = buildManifest({ maestroRoot: root, previous: manifest }).manifest;
+  }
+  const e = manifest.agents.alpha;
+  assert.equal(e.history.length, 10);
+  assert.equal(e.history.includes(e.sha256), false);
+});
+
+test("buildManifest: empty directories are recorded on the manifest", () => {
+  const root = sdkRoot();
+  putAgent(root, "alpha");
+  mkdirSync(join(root, "agents", "hollow"), { recursive: true });
+  assert.deepEqual(buildManifest({ maestroRoot: root }).manifest.emptyDirs, ["hollow"]);
+});
+
+test("writeManifest / readManifest round trip, and manifestSlugs is sorted", () => {
+  const root = sdkRoot();
+  putAgent(root, "zeta");
+  putAgent(root, "alpha");
+  const { manifest } = buildManifest({ maestroRoot: root, sdkVersion: "3.2.1" });
+  const p = writeManifest(root, manifest);
+  assert.equal(p, manifestPath(root));
+  assert.equal(p.endsWith(MANIFEST_REL), true);
+  const read = readManifest(root);
+  assert.equal(read.sdkVersion, "3.2.1");
+  assert.deepEqual(manifestSlugs(read), ["alpha", "zeta"]);
+});
+
+test("readManifest: fail-open on a missing OR corrupt manifest — degrades SAFELY", () => {
+  // Degrading to "layer 0 has no managed files" makes every on-disk file look
+  // locally edited, which means nothing is overwritten. Safe direction.
+  const root = sdkRoot();
+  assert.deepEqual(readManifest(root), { sdkVersion: "", agents: {} });
+  mkdirSync(join(root, "agents"), { recursive: true });
+  writeFileSync(manifestPath(root), "{ not json");
+  assert.deepEqual(readManifest(root), { sdkVersion: "", agents: {} });
+  assert.deepEqual([...manifestShas(readManifest(root))], []);
+});
+
+test("isManagedByManifest: exact file bytes only", () => {
+  const root = sdkRoot();
+  const text = putAgent(root, "alpha");
+  const { manifest } = buildManifest({ maestroRoot: root });
+  assert.equal(isManagedByManifest(manifest, text), true);
+  assert.equal(isManagedByManifest(manifest, text + "\n# edited\n"), false);
+  assert.equal(isManagedByManifest(manifest, ""), false);
+  assert.equal(isManagedByManifest(manifest, null), false);
+});
+
+test("readSdkAgent: returns parsed text + fileHash, null when absent", () => {
+  const root = sdkRoot();
+  const text = putAgent(root, "alpha");
+  const a = readSdkAgent(root, "alpha");
+  assert.equal(a.slug, "alpha");
+  assert.equal(a.text, text);
+  assert.equal(a.fileHash, hashFile(text));
+  assert.equal(a.frontmatter.name, "alpha");
+  assert.equal(readSdkAgent(root, "nope"), null);
+});
+
+test("the REAL SDK tree builds a manifest with no invalid agents", () => {
+  const { manifest, invalid } = buildManifest({ maestroRoot: MAESTRO_ROOT, sdkVersion: "test" });
+  assert.deepEqual(invalid.map((i) => i.slug), []);
+  assert.ok(Object.keys(manifest.agents).length >= 1);
+  for (const [slug, e] of Object.entries(manifest.agents)) {
+    const text = readFileSync(join(MAESTRO_ROOT, "agents", slug, "agent.md"), "utf8");
+    assert.equal(e.sha256, hashFile(text), `${slug} sha must be the file hash`);
+  }
+});