@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/scripts/daemon/inbox-wake.test.mjs

@@ -0,0 +1,199 @@
+/**
+ * inbox-wake.test.mjs — the daemon's "something landed" wake signal.
+ *
+ * Exercised against a REAL temp filesystem (fs.watch semantics are the thing
+ * under test), plus one injected-watch case that proves the scan floor carries
+ * the load when every watcher is dead — the property that keeps a missed event
+ * from turning into a silently late agent.
+ *
+ * Run: node --test scripts/daemon/inbox-wake.test.mjs
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  waitForInboxWake,
+  signalInbox,
+  findLiveInboxService,
+  isLiveItemName,
+  resetInboxWake,
+  DEFAULT_SERVICES,
+} from "./inbox-wake.mjs";
+
+function makeRoot() {
+  const root = mkdtempSync(join(tmpdir(), "inbox-wake-"));
+  mkdirSync(join(root, "state", "inbox", "cohort"), { recursive: true });
+  return root;
+}
+
+function writeItem(root, service, name, body = "id: x\n") {
+  writeFileSync(join(root, "state", "inbox", service, name), body);
+}
+
+// --- the predicate ----------------------------------------------------------
+
+test("isLiveItemName: only un-drained, non-dot files count as work", () => {
+  assert.equal(isLiveItemName("2026-08-11-abc.yaml"), true);
+  assert.equal(isLiveItemName("2026-08-11-abc.yaml.processed"), false);
+  assert.equal(isLiveItemName("2026-08-11-abc.yaml.deferred"), false);
+  assert.equal(isLiveItemName("2026-08-11-abc.yaml.processed-bundled"), false);
+  assert.equal(isLiveItemName(".DS_Store"), false);
+  assert.equal(isLiveItemName(""), false);
+});
+
+test("findLiveInboxService: names the service holding work, else null", () => {
+  const root = makeRoot();
+  try {
+    assert.equal(findLiveInboxService({ agentRoot: root }), null);
+    writeItem(root, "cohort", "a.yaml.processed");
+    assert.equal(findLiveInboxService({ agentRoot: root }), null, "a drained item is not work");
+    writeItem(root, "cohort", "b.yaml");
+    assert.equal(findLiveInboxService({ agentRoot: root }), "cohort");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("the cohort + orgmail dirs are in the default service set (the ones that were missed)", () => {
+  assert.ok(DEFAULT_SERVICES.includes("cohort"));
+  assert.ok(DEFAULT_SERVICES.includes("orgmail"));
+  assert.ok(DEFAULT_SERVICES.includes("telegram"));
+});
+
+// --- the wake ---------------------------------------------------------------
+
+test("returns immediately when work is already waiting (never sleep on a full inbox)", async () => {
+  const root = makeRoot();
+  try {
+    writeItem(root, "cohort", "a.yaml");
+    const r = await waitForInboxWake({ agentRoot: root, timeoutMs: 5_000 });
+    assert.equal(r.woke, true);
+    assert.equal(r.reason, "pending");
+    assert.equal(r.service, "cohort");
+    assert.equal(r.waitedMs, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("wakes on a file written by another writer, far inside the 60s poll interval", async () => {
+  const root = makeRoot();
+  try {
+    const started = Date.now();
+    const waiting = waitForInboxWake({ agentRoot: root, timeoutMs: 8_000 });
+    setTimeout(() => writeItem(root, "cohort", "late.yaml"), 50);
+    const r = await waiting;
+    assert.equal(r.woke, true);
+    assert.ok(["watch", "scan"].includes(r.reason), `unexpected reason ${r.reason}`);
+    assert.equal(r.service, "cohort");
+    assert.ok(Date.now() - started < 3_000, "a wake must not take seconds");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("does NOT wake when the only change is an item being drained", async () => {
+  const root = makeRoot();
+  try {
+    writeItem(root, "cohort", "a.yaml");
+    // Drain it, then wait: renaming to `.processed` raises watch events for BOTH
+    // names, so an event-driven wake would spin here.
+    renameSync(
+      join(root, "state", "inbox", "cohort", "a.yaml"),
+      join(root, "state", "inbox", "cohort", "a.yaml.processed")
+    );
+    const r = await waitForInboxWake({ agentRoot: root, timeoutMs: 400 });
+    assert.equal(r.woke, false);
+    assert.equal(r.reason, "timeout");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("times out cleanly with an empty inbox (the loop shape is unchanged)", async () => {
+  const root = makeRoot();
+  try {
+    const r = await waitForInboxWake({ agentRoot: root, timeoutMs: 200 });
+    assert.deepEqual(
+      { woke: r.woke, reason: r.reason, service: r.service },
+      { woke: false, reason: "timeout", service: null }
+    );
+    assert.ok(r.waitedMs >= 150);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("signalInbox wakes an in-process waiter (the dispatcher's promote path)", async () => {
+  const root = makeRoot();
+  resetInboxWake();
+  try {
+    const waiting = waitForInboxWake({ agentRoot: root, timeoutMs: 5_000, scanMs: 60_000 });
+    setTimeout(() => {
+      // Simulate promoteDeferred: the file becomes live, then we nudge.
+      writeItem(root, "cohort", "promoted.yaml");
+      signalInbox("promote");
+    }, 20);
+    const r = await waiting;
+    assert.equal(r.woke, true);
+    assert.equal(r.service, "cohort");
+  } finally {
+    resetInboxWake();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("signalInbox with no work does NOT wake (a spurious nudge is free)", async () => {
+  const root = makeRoot();
+  resetInboxWake();
+  try {
+    const waiting = waitForInboxWake({ agentRoot: root, timeoutMs: 400, scanMs: 60_000 });
+    setTimeout(() => signalInbox("noise"), 20);
+    const r = await waiting;
+    assert.equal(r.woke, false);
+  } finally {
+    resetInboxWake();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("with EVERY watcher dead the scan floor still wakes it — and says so once", async () => {
+  const root = makeRoot();
+  const logs = [];
+  try {
+    const watchImpl = () => {
+      throw new Error("EMFILE: watcher limit reached");
+    };
+    const waiting = waitForInboxWake({
+      agentRoot: root,
+      timeoutMs: 6_000,
+      scanMs: 100,
+      watchImpl,
+      log: (m) => logs.push(m),
+    });
+    setTimeout(() => writeItem(root, "cohort", "floor.yaml"), 30);
+    const r = await waiting;
+    assert.equal(r.woke, true);
+    assert.equal(r.reason, "scan", "correctness must not depend on fs.watch");
+    assert.equal(logs.length, 1, "a dead watcher is reported — fail-open, never silent");
+    assert.match(logs[0], /falling back to the 100ms rescan/);
+  } finally {
+    resetInboxWake();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a missing service dir is not an error (an un-enrolled agent just times out)", async () => {
+  const root = mkdtempSync(join(tmpdir(), "inbox-wake-bare-"));
+  try {
+    const r = await waitForInboxWake({ agentRoot: root, timeoutMs: 200 });
+    assert.equal(r.woke, false);
+    assert.equal(r.reason, "timeout");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/scripts/daemon/prompt-builder.mjs

@@ -6,6 +6,7 @@
 import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { compileContext } from "./context-compiler.mjs";
+import { loadPersonaBlock } from "../../lib/identity/persona.mjs";
 import { wrapExternalContent } from "../../lib/security/external-content.mjs";
 import { isEnabled as orgEnabled } from "../../lib/org/client.mjs";
 import { recall as orgRecall } from "../../lib/org/knowledge.mjs";
@@ -118,6 +119,27 @@ async function buildOrgKnowledgeBlock(item, classResult, queueItem) {
 // Cached identity preamble — extracted from CLAUDE.md on first call
 let cachedPreamble = null;
 
+// Cached persona block — rendered from config/agent.json (the SoT, kept in sync
+// with the Cohort server) on first call. This leads every prompt and is
+// AUTHORITATIVE over the CLAUDE.md-scraped preamble that follows it: a scaffolded
+// repo still carries "your identity has not yet been configured" prose in
+// CLAUDE.md long after the org record is populated, and without an explicit
+// precedence rule the model would take that placeholder at face value and fall
+// back to a generic-assistant register.
+let cachedPersona = null;
+
+/** Render (once per process) the persona block from config/agent.json. */
+function loadPersona() {
+  if (cachedPersona !== null) return cachedPersona;
+  cachedPersona = loadPersonaBlock(AGENT_REPO_DIR) || "";
+  return cachedPersona;
+}
+
+/** For tests: drop the cached persona so a fresh config/agent.json is re-read. */
+export function _resetPersonaCache() {
+  cachedPersona = null;
+}
+
 function loadPreamble() {
   if (cachedPreamble) return cachedPreamble;
 
@@ -185,7 +207,10 @@ function buildFallbackPreamble() {
   const principal = a.principal || {};
   const principalName = principal.fullName || "the principal";
   const principalTitle = principal.title || "principal";
-  return `You are ${a.fullName}, ${a.title} to ${principalName}, ${principalTitle} of ${a.company}.
+  // "<title> to <principal>" only reads correctly for assistant-shaped titles;
+  // for a functional seat ("SVP AI Systems & Agent Platform") it turns the role
+  // into a service relationship. State the seat, then the reporting line.
+  return `You are ${a.fullName}, ${a.title} at ${a.company}. You report to ${principalName}, ${principalTitle}.
 You operate as the autonomous executive command layer for the company.
 
 ${a.companyDescription || a.company}.
@@ -552,6 +577,21 @@ export async function buildPrompt(item, classResult, options = {}) {
 
   const parts = [];
 
+  // 1. Persona block (cached) — rendered from config/agent.json, which the
+  // Cohort enrollment pull keeps current. Leads the prompt and outranks the
+  // CLAUDE.md preamble below, because a scaffolded CLAUDE.md carries
+  // "identity not yet configured" placeholder prose that would otherwise
+  // contradict a perfectly good org record.
+  const persona = loadPersona();
+  if (persona) {
+    parts.push(persona);
+    parts.push("");
+    parts.push(
+      "The section above is your identity, resolved from your organisation's record of you. Where anything below conflicts with it, the section above wins.",
+    );
+    parts.push("");
+  }
+
   // 1. Identity preamble (cached)
   parts.push(preamble);
   parts.push("");

package/scripts/daemon/typing-registry.mjs

@@ -19,9 +19,31 @@
 
 "use strict";
 
+import { cohortTypingAdapter } from "../../lib/org/typing.mjs";
+
 /** @type {Map<string, { startTypingHeartbeat:Function, stopTypingHeartbeat:Function }>} */
 const ADAPTERS = new Map();
 
+/**
+ * Services whose adapter is BUILT IN rather than created by the daemon's
+ * channel-bus loop, resolved on first use.
+ *
+ * `cohort` is the org substrate itself: there is no channel adapter object for
+ * it anywhere (the messaging-inbound cadence writes inbox YAML directly), so
+ * nothing would ever have called `registerTypingAdapter("cohort", …)` — and an
+ * SDK-driven agent, which is now the ONLY responder for its own rooms
+ * (hq `llm-responder/sdk-driven.ts` stands hq down for a live daemon), would
+ * show no "composing" indicator at all while it worked. The adapter is a plain
+ * `messaging.typing` client (`lib/org/typing.mjs`) that no-ops when the agent is
+ * not enrolled, so resolving it lazily here costs nothing for an agent that has
+ * no org.
+ *
+ * @type {Record<string, () => object>}
+ */
+const BUILTIN_ADAPTERS = {
+  cohort: () => cohortTypingAdapter(),
+};
+
 /** Register a channel adapter under its service name (e.g. "telegram"). */
 export function registerTypingAdapter(service, adapter) {
   if (!service || !adapter) return;
@@ -29,6 +51,37 @@ export function registerTypingAdapter(service, adapter) {
   ADAPTERS.set(service, adapter);
 }
 
+/**
+ * Resolve the adapter for a service: an explicitly registered one wins (so a
+ * test or a future real cohort adapter can override), else a built-in.
+ * Fail-open: a built-in that cannot be constructed yields null and the caller
+ * no-ops, but the reason is logged — a silently missing indicator is exactly
+ * the class of bug this module exists to fix.
+ */
+function adapterFor(service) {
+  if (!service) return null;
+  const registered = ADAPTERS.get(service);
+  if (registered) return registered;
+  const builtin = BUILTIN_ADAPTERS[service];
+  if (!builtin) return null;
+  try {
+    const made = builtin();
+    if (!made || typeof made.startTypingHeartbeat !== "function") return null;
+    ADAPTERS.set(service, made);
+    return made;
+  } catch (err) {
+    try {
+      console.warn(
+        `[typing-registry] built-in typing adapter for "${service}" failed to load ` +
+          `(${err && err.message}) — sessions will run without a typing indicator`
+      );
+    } catch {
+      /* never throw from logging */
+    }
+    return null;
+  }
+}
+
 export function clearTypingAdapters() {
   ADAPTERS.clear();
 }
@@ -57,7 +110,7 @@ export function sourceFromItem(item) {
 export function startTyping(item) {
   try {
     const service = item?.service;
-    const adapter = service && ADAPTERS.get(service);
+    const adapter = adapterFor(service);
     if (!adapter) return null;
     const source = sourceFromItem(item);
     if (!source || !source.chatId) return null;
@@ -71,7 +124,7 @@ export function startTyping(item) {
 export function stopTyping(item) {
   try {
     const service = item?.service;
-    const adapter = service && ADAPTERS.get(service);
+    const adapter = adapterFor(service);
     if (!adapter) return;
     const source = sourceFromItem(item);
     if (!source || !source.chatId) return;

package/scripts/daemon/typing-registry.test.mjs

@@ -16,6 +16,7 @@ import {
   stopTyping,
   sourceFromItem,
 } from "./typing-registry.mjs";
+import { resetCohortTypingAdapter } from "../../lib/org/typing.mjs";
 
 function fakeAdapter() {
   return {
@@ -68,6 +69,30 @@ test("sourceFromItem prefers a structured source, else reconstructs from item",
   assert.equal(group.threadRef, "77");
 });
 
+test("cohort resolves the BUILT-IN adapter with nothing registered (the SDK parity gap)", () => {
+  clearTypingAdapters();
+  resetCohortTypingAdapter();
+  // No registerTypingAdapter("cohort", …) anywhere — nothing constructs a
+  // cohort channel adapter, which is why the indicator was missing entirely.
+  const item = { service: "cohort", channel_id: "ch_1", channel: "#build", thread_id: "" };
+  assert.doesNotThrow(() => startTyping(item));
+  assert.doesNotThrow(() => stopTyping(item));
+  clearTypingAdapters();
+  resetCohortTypingAdapter();
+});
+
+test("an explicitly registered cohort adapter still wins over the built-in", () => {
+  clearTypingAdapters();
+  resetCohortTypingAdapter();
+  const fake = fakeAdapter();
+  registerTypingAdapter("cohort", fake);
+  startTyping({ service: "cohort", channel_id: "ch_1", channel: "#build" });
+  assert.equal(fake.started.length, 1);
+  assert.equal(fake.started[0].chatId, "ch_1");
+  clearTypingAdapters();
+  resetCohortTypingAdapter();
+});
+
 test("registerTypingAdapter ignores adapters lacking startTypingHeartbeat", () => {
   clearTypingAdapters();
   registerTypingAdapter("bad", { foo: 1 });

package/scripts/local-triggers/generate-plists.test.mjs

@@ -107,7 +107,7 @@ function listPlists(agentRoot) {
 // Tests
 // ---------------------------------------------------------------------------
 
-test("generator emits 21 standard plists with the agent's first name", async () => {
+test("generator emits 22 standard plists with the agent's first name", async () => {
   // Standard inventory (cadence-bus v1 + slack-socket-mode v1), with NO
   // config/.cadence-plists.tsv present (no archetype cadences):
   //   daemon, poll-relay, slack-socket (3 infra), PLUS one trigger plist per
@@ -118,8 +118,8 @@ test("generator emits 21 standard plists with the agent's first name", async ()
   //   economics/scheduling cadences nightly-cost-reconcile, fleet-cost-digest,
   //   org-cost-sync, monitoring-alerts, dynamic-jobs (5), PLUS the SP10
   //   messaging-inbound cadence (1), PLUS the 2026-07 Directory & Design
-  //   stewards directory-hygiene + brand-steward (2). = 3 infra + 18 trigger
-  //   = 21 total.
+  //   stewards directory-hygiene + brand-steward (2), PLUS the D3 self-directed
+  //   loop goal-steward (1). = 3 infra + 19 trigger = 22 total.
   // org-pulse used to be declared standard but was OMITTED by the old hardcoded
   // list (it never got a plist); deriving from the SoT fixes that drift.
   // The former weekly-* cadences are still ARCHETYPE-DRIVEN (function × altitude),
@@ -129,7 +129,7 @@ test("generator emits 21 standard plists with the agent's first name", async ()
     const r = runGenerator(root);
     assert.equal(r.status, 0, r.stderr);
     const plists = listPlists(root);
-    assert.equal(plists.length, 21, `expected 21 standard plists; got ${plists.join(",")}`);
+    assert.equal(plists.length, 22, `expected 22 standard plists; got ${plists.join(",")}`);
     assert.ok(plists.includes("ai.maestro.alice-messaging-inbound.plist"),
       "messaging-inbound (SP10 standard cadence) must get a SoT-derived plist");
     for (const id of ["directory-hygiene", "brand-steward"]) {
@@ -200,7 +200,7 @@ test("archetype cadences from config/.cadence-plists.tsv emit extra trigger plis
     const r = runGenerator(root);
     assert.equal(r.status, 0, r.stderr);
     const plists = listPlists(root);
-    assert.equal(plists.length, 23, `expected 21 standard + 2 archetype; got ${plists.join(",")}`);
+    assert.equal(plists.length, 24, `expected 22 standard + 2 archetype; got ${plists.join(",")}`);
     const dir = join(root, "scripts/local-triggers/plists");
     const eng = readFileSync(join(dir, "ai.maestro.erin-engineering-health.plist"), "utf-8");
     assert.match(eng, /<key>Weekday<\/key>\s*<integer>3<\/integer>/); // base64 schedule decoded

package/scripts/setup/gen-subagent-manifest.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * gen-subagent-manifest.mjs — generate `agents/manifest.json`, layer 0's index
+ * (Sub-Agent Registry v1 §2.2).
+ *
+ * WHY THIS SCRIPT EXISTS. `agents/` ships in the npm package and is copied
+ * verbatim by `maestro create`, then MERGED (never overwritten) by
+ * `UPGRADE_PATHS`. That means an SDK fix to a shipped agent.md can never reach a
+ * deployed agent — an upgraded file and a hand-edited one look identical on disk.
+ * The manifest's per-agent sha256 breaks the tie: a file whose hash matches a
+ * manifest sha is a pristine copy and may be re-materialised; anything else is a
+ * human's edit and is sacred. That single fact is what lets `create`'s copy list
+ * and `UPGRADE_PATHS` stay EXACTLY as they are — no migration, no breaking change.
+ *
+ * Run at prepublish and commit the result:
+ *   node scripts/setup/gen-subagent-manifest.mjs
+ *   node scripts/setup/gen-subagent-manifest.mjs --check   # CI: fail on drift
+ *
+ * `--check` is the CI gate: it rebuilds the manifest in memory and fails when it
+ * differs from the committed one, so a shipped agent.md can never change without
+ * its sha changing with it (which would silently reclassify every deployed copy
+ * as a local edit and freeze it forever).
+ *
+ * Exit codes: 0 ok · 1 drift (with --check) · 2 an agent.md failed validation.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module scripts/setup/gen-subagent-manifest
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildManifest, manifestPath, readManifest, writeManifest } from "../../lib/subagents/manifest.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT =
+  process.env.MAESTRO_ROOT && existsSync(join(process.env.MAESTRO_ROOT, "lib", "subagents", "manifest.mjs"))
+    ? process.env.MAESTRO_ROOT
+    : resolve(HERE, "..", "..");
+
+/** Read the package version so the manifest can name the release it describes. */
+function sdkVersion(root) {
+  try { return String(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version || ""); }
+  catch { return ""; }
+}
+
+/**
+ * Compare two manifests ignoring `generatedAt` — a timestamp differing on every
+ * run would make `--check` permanently red and train everyone to ignore it.
+ */
+function sameManifest(a, b) {
+  const strip = (m) => JSON.stringify({ sdkVersion: m.sdkVersion || "", agents: m.agents || {}, emptyDirs: m.emptyDirs || [] });
+  return strip(a || {}) === strip(b || {});
+}
+
+export function main(argv = process.argv.slice(2), root = MAESTRO_ROOT) {
+  const check = argv.includes("--check");
+  const strict = argv.includes("--strict");
+  const previous = readManifest(root);
+  const { manifest, invalid } = buildManifest({ maestroRoot: root, sdkVersion: sdkVersion(root), previous });
+
+  for (const bad of invalid) {
+    console.error(`[gen-subagent-manifest] agents/${bad.slug}/agent.md is invalid:`);
+    for (const e of bad.errors) console.error(`    - ${e}`);
+  }
+
+  if (check) {
+    if (!existsSync(manifestPath(root))) {
+      console.error(`[gen-subagent-manifest] ${manifestPath(root)} does not exist — run this script and commit it.`);
+      return 1;
+    }
+    if (!sameManifest(previous, manifest)) {
+      console.error("[gen-subagent-manifest] agents/manifest.json is STALE — an agent.md changed without regenerating it.");
+      console.error("    fix: node scripts/setup/gen-subagent-manifest.mjs && git add agents/manifest.json");
+      return 1;
+    }
+    console.log(`[gen-subagent-manifest] up to date (${Object.keys(manifest.agents).length} agents).`);
+    return invalid.length && strict ? 2 : 0;
+  }
+
+  const p = writeManifest(root, manifest);
+  console.log(`[gen-subagent-manifest] wrote ${p} (${Object.keys(manifest.agents).length} agents, sdk ${manifest.sdkVersion || "?"}).`);
+  if (manifest.emptyDirs && manifest.emptyDirs.length) {
+    console.warn(`[gen-subagent-manifest] ${manifest.emptyDirs.length} agents/ directory(ies) have no agent.md: ${manifest.emptyDirs.join(", ")}`);
+  }
+  return invalid.length && strict ? 2 : 0;
+}
+
+// Only run when invoked directly (importable for tests).
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  process.exit(main());
+}

package/scripts/setup/gen-subagent-manifest.test.mjs

@@ -0,0 +1,124 @@
+/**
+ * gen-subagent-manifest.test.mjs — the layer-0 manifest generator + its CI gate.
+ * Run: node --test scripts/setup/gen-subagent-manifest.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 { fileURLToPath } from "node:url";
+
+import { main } from "./gen-subagent-manifest.mjs";
+import { buildManifest, manifestPath, readManifest } from "../../lib/subagents/manifest.mjs";
+import { hashFile, stringifyAgentMd } from "../../lib/subagents/schema.mjs";
+
+const MAESTRO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function put(root, slug, body = `# ${slug}\n\nprose\n`, over = {}) {
+  const text = stringifyAgentMd({ name: slug, description: `${slug} does things`, model: "sonnet", tools: ["Read"], ...over }, body);
+  mkdirSync(join(root, "agents", slug), { recursive: true });
+  writeFileSync(join(root, "agents", slug, "agent.md"), text);
+  return text;
+}
+function fixture(version = "1.2.3") {
+  const root = mkdtempSync(join(tmpdir(), "gen-manifest-"));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ version }));
+  return root;
+}
+/** Run main() with its console noise captured. */
+function runMain(argv, root) {
+  const log = console.log, warn = console.warn, error = console.error;
+  const out = [];
+  console.log = console.warn = console.error = (...a) => out.push(a.join(" "));
+  try { return { code: main(argv, root), out: out.join("\n") }; }
+  finally { console.log = log; console.warn = warn; console.error = error; }
+}
+
+test("writes agents/manifest.json with the package version and per-agent shas", () => {
+  const root = fixture("1.2.3");
+  const text = put(root, "alpha");
+  const { code } = runMain([], root);
+  assert.equal(code, 0);
+  assert.equal(existsSync(manifestPath(root)), true);
+  const m = readManifest(root);
+  assert.equal(m.sdkVersion, "1.2.3");
+  assert.equal(m.agents.alpha.sha256, hashFile(text));
+});
+
+test("--check passes when the committed manifest is current", () => {
+  const root = fixture();
+  put(root, "alpha");
+  runMain([], root);
+  const { code, out } = runMain(["--check"], root);
+  assert.equal(code, 0);
+  assert.match(out, /up to date \(1 agents\)/);
+});
+
+test("--check FAILS when an agent.md changed without regenerating the manifest", () => {
+  // Without this gate a shipped agent.md could change while its sha did not,
+  // which would silently reclassify every deployed copy as a local edit and
+  // freeze it forever.
+  const root = fixture();
+  put(root, "alpha");
+  runMain([], root);
+  put(root, "alpha", "# alpha\n\nEDITED UPSTREAM\n");
+  const { code, out } = runMain(["--check"], root);
+  assert.equal(code, 1);
+  assert.match(out, /STALE/);
+  assert.match(out, /gen-subagent-manifest\.mjs && git add/);
+});
+
+test("--check fails when the manifest has never been generated", () => {
+  const root = fixture();
+  put(root, "alpha");
+  const { code, out } = runMain(["--check"], root);
+  assert.equal(code, 1);
+  assert.match(out, /does not exist/);
+});
+
+test("--check ignores generatedAt (a per-run timestamp must not make CI permanently red)", () => {
+  const root = fixture();
+  put(root, "alpha");
+  runMain([], root);
+  const doc = JSON.parse(readFileSync(manifestPath(root), "utf8"));
+  doc.generatedAt = "1999-01-01T00:00:00.000Z";
+  writeFileSync(manifestPath(root), JSON.stringify(doc, null, 2));
+  assert.equal(runMain(["--check"], root).code, 0);
+});
+
+test("an invalid agent.md is REPORTED, and only --strict makes it an exit code", () => {
+  const root = fixture();
+  put(root, "alpha", "# alpha\n\nprose\n", { name: "wrong-name" });
+  const loose = runMain([], root);
+  assert.equal(loose.code, 0);
+  assert.match(loose.out, /agents\/alpha\/agent\.md is invalid/);
+  assert.match(loose.out, /must equal the directory name/);
+  assert.equal(runMain(["--strict"], root).code, 2);
+});
+
+test("empty agents/<slug>/ directories are warned about", () => {
+  const root = fixture();
+  put(root, "alpha");
+  mkdirSync(join(root, "agents", "hollow"), { recursive: true });
+  const { out } = runMain([], root);
+  assert.match(out, /have no agent\.md: hollow/);
+});
+
+test("regenerating carries the previous sha into history", () => {
+  const root = fixture();
+  const v1 = put(root, "alpha", "v1\n");
+  runMain([], root);
+  put(root, "alpha", "v2\n");
+  runMain([], root);
+  assert.deepEqual(readManifest(root).agents.alpha.history, [hashFile(v1)]);
+});
+
+test("the REAL SDK tree would pass the gate (no invalid shipped agents)", () => {
+  // Nothing is written to disk — buildManifest is pure. This only proves the
+  // shipped corpus is generatable, so `--check` can be wired into CI safely.
+  const { invalid } = buildManifest({ maestroRoot: MAESTRO_ROOT, sdkVersion: "test" });
+  assert.deepEqual(invalid.map((i) => i.slug), []);
+});