@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/setup/sections/verify.test.mjs

@@ -0,0 +1,175 @@
+/**
+ * verify.test.mjs — the INIT-pipeline gate in the verify section (SPEC §5.8).
+ * Run: node --test lib/setup/sections/verify.test.mjs
+ *
+ * The four checks that decide whether the plan an agent just compiled is
+ * TRUSTWORTHY:
+ *   1. it compiles and its obligationsHash matches the compile lock
+ *   2. no obligation cites an unreachable capability
+ *   3. no OUTCOME rests on an LLM-sourced sensor
+ *   4. the mandate cache is fresh (< 24h)
+ *
+ * All four are SOFT — an un-adopted agent legitimately has no plan and setup must
+ * not exit non-zero for that — so the thing under test is that every degradation
+ * is NAMED with a remedy rather than passing silently.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import yaml from "js-yaml";
+
+import verifySection, { planChecks, MANDATE_FRESH_MS } from "./verify.mjs";
+import { loadSections } from "../runner.mjs";
+
+const NOW = Date.parse("2026-08-11T12:00:00.000Z");
+
+const MANIFEST = {
+  schemaVersion: 1,
+  entries: [
+    { id: "crm_list_deals", plane: "org", reachable: true },
+    { id: "board_ready", plane: "org", reachable: true },
+    { id: "email_inbox", plane: "org", reachable: false },
+  ],
+};
+
+function planDoc(over = {}) {
+  return {
+    schemaVersion: 1,
+    obligationsHash: "HASH_OK",
+    obligations: [
+      { key: "schedule.measure.pipeline", kind: "SCHEDULE", status: "active", uses: ["crm_list_deals"] },
+      { key: "outcome.pipeline", kind: "OUTCOME", status: "active", uses: ["crm_list_deals"], sensor: { capability: "crm_list_deals", source: "method" } },
+    ],
+    ...over,
+  };
+}
+
+/**
+ * A fully injected world. Nothing here touches the real filesystem — the point
+ * of the deps seam is that a check can be proven without a scaffolded agent.
+ */
+function deps({ plan = planDoc(), manifest = MANIFEST, lock = { obligationsHash: "HASH_OK" }, cache = { fetchedAt: "2026-08-11T09:00:00.000Z" }, planMissing = false } = {}) {
+  return {
+    yaml,
+    existsSync: (p) => (String(p).endsWith("plan.yaml") ? !planMissing : true),
+    readFileSync: (p) => {
+      if (String(p).endsWith("plan.yaml")) return yaml.dump(plan);
+      throw new Error(`unexpected read: ${p}`);
+    },
+    readManifest: () => manifest,
+    readLock: () => lock,
+    readCache: () => cache,
+  };
+}
+
+const byName = (checks, re) => checks.find((c) => re.test(c.name));
+
+test("a healthy plan passes all four checks", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps());
+  assert.ok(checks.every((c) => c.ok), `all ok, got: ${JSON.stringify(checks.filter((c) => !c.ok))}`);
+  assert.ok(byName(checks, /plan compiled/).ok);
+  assert.ok(byName(checks, /obligationsHash/).ok);
+  assert.ok(byName(checks, /unreachable capability/).ok);
+  assert.ok(byName(checks, /method sensor/).ok);
+  assert.ok(byName(checks, /mandate cache fresh/).ok);
+});
+
+test("no plan on disk is SOFT but named — it never fails setup silently", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ planMissing: true }));
+  assert.equal(checks.length, 1);
+  assert.equal(checks[0].ok, true, "an un-adopted agent is a legitimate state");
+  assert.match(checks[0].remedy, /standard \+ archetype cadences only/);
+});
+
+test("a hand-edited plan.yaml is caught by the compile-lock hash", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ lock: { obligationsHash: "SOMETHING_ELSE" } }));
+  const c = byName(checks, /obligationsHash/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /edited by hand|stale/);
+});
+
+test("a missing compile lock is reported, not treated as a pass", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ lock: null }));
+  const c = byName(checks, /obligationsHash/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /no state\/plan\/compile\.lock/);
+});
+
+test("THE LAW: an obligation citing an unreachable capability fails the check", async () => {
+  // email_inbox is reachable:false in the manifest.
+  const plan = planDoc({
+    obligations: [{ key: "schedule.inbox", kind: "SCHEDULE", status: "active", uses: ["crm_list_deals", "email_inbox"] }],
+  });
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ plan }));
+  const c = byName(checks, /unreachable capability/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /schedule\.inbox → email_inbox/);
+});
+
+test("no capability manifest → the reachability law cannot be checked, and says so", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ manifest: null }));
+  const c = byName(checks, /unreachable capability/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /capability-manifest\.json/);
+});
+
+test("an OUTCOME resting on an LLM sensor fails the honesty gate", async () => {
+  const plan = planDoc({
+    obligations: [{ key: "outcome.vibes", kind: "OUTCOME", status: "active", uses: ["crm_list_deals"], sensor: { capability: "crm_list_deals", source: "llm" } }],
+  });
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ plan }));
+  const c = byName(checks, /method sensor/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /outcome\.vibes/);
+  assert.match(c.remedy, /cannot create work/);
+});
+
+test("a stale mandate cache (>24h) fails freshness", async () => {
+  const stale = { fetchedAt: new Date(NOW - MANDATE_FRESH_MS - 60_000).toISOString() };
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ cache: stale }));
+  const c = byName(checks, /mandate cache fresh/);
+  assert.equal(c.ok, false);
+  assert.match(c.remedy, /self-directed work is suspended/);
+});
+
+test("no mandate cache is soft (un-enrolled agent) but still named", async () => {
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, deps({ cache: null }));
+  const c = byName(checks, /mandate cache present/);
+  assert.equal(c.ok, true);
+  assert.match(c.remedy, /no adopted mandate yet/);
+});
+
+test("an unreadable plan.yaml is a reported failure, not a thrown setup", async () => {
+  const d = deps();
+  d.readFileSync = () => "{{{ not yaml :::";
+  const checks = await planChecks({ agentRoot: "/agent", now: NOW }, d);
+  assert.equal(checks[0].ok, false);
+  assert.match(checks[0].remedy, /generate-plan\.mjs/);
+});
+
+test("planChecks is wired into the verify section's rows under section 'plan'", async () => {
+  const rows = [];
+  const res = await verifySection.verify({
+    agentRoot: "/agent",
+    sections: [],
+    planDeps: deps(),
+  }).catch((e) => ({ error: e }));
+  // The core probes (completeness/claude) may legitimately fail on a fake root;
+  // what must hold is that the plan rows are present and attributed.
+  const planRows = ((res && res.rows) || rows).filter((r) => r.section === "plan");
+  assert.ok(planRows.length >= 4, `expected the plan checks in the rows, got ${JSON.stringify((res && res.rows) || []).slice(0, 200)}`);
+  assert.ok(planRows.some((r) => /obligationsHash/.test(r.name)));
+});
+
+test("the verify section is registered by the directory glob at order 90", async () => {
+  const sections = await loadSections();
+  const v = sections.find((s) => s.id === "verify");
+  assert.ok(v, "verify is discovered by loadSections()");
+  assert.equal(v.order, 90);
+  // It must run AFTER the two init-pipeline sections it gates.
+  const inventory = sections.find((s) => s.id === "inventory");
+  const mandate = sections.find((s) => s.id === "mandate");
+  assert.ok(inventory.order < v.order, "inventory (55) precedes verify (90)");
+  assert.ok(mandate.order < v.order, "mandate (78) precedes verify (90)");
+});

package/lib/setup/sot.mjs

@@ -192,6 +192,8 @@ export interface AgentConfig {
     voiceModes: VoiceMode[];
   };
 
+  /** Free prose background/bio, authored by the org (Cohort profile section). */
+  persona?: string;
   responsibilities: string[];
   operatingPrinciples: string[];
 }

package/lib/subagents/cli.mjs

@@ -0,0 +1,463 @@
+/**
+ * lib/subagents/cli.mjs — backs `maestro subagents <sub>` (§2.4).
+ *
+ * WHY A LIBRARY AND NOT A `case` BLOCK IN bin/maestro.mjs. `bin/maestro.mjs` is a
+ * 3000-line dispatcher that no test can import without executing; putting the
+ * registry's whole verb surface in it would make it untestable, which for a
+ * module that writes files and calls a remote API is not acceptable. `run()`
+ * returns `{ok, code, lines}` and only PRINTS when asked to, so every subcommand
+ * has a unit test. bin/maestro.mjs keeps a four-line `case "subagents"`.
+ *
+ * Commands (all local-first; only `pull`/`publish`/`add`/`fork`/`drop` network,
+ * and all of those degrade to the outbox):
+ *
+ *   list                    resolved roster + winning layer + version per slug
+ *   status                  the §2.3 three-way diff (what `doctor` renders)
+ *   show <slug>             resolved body + provenance
+ *   diff <slug>             local file vs the layer it was materialised from
+ *   add <slug>              new local def from the generator skeleton → create+pin
+ *   fork <slug> [--as <n>]  copy the resolved body into a new org definition
+ *   publish <slug>          publishVersion from the on-disk file
+ *   pull [--force]          re-resolve + re-materialise (--force overwrites edits)
+ *   drop <slug> [--yank]    unpin (and yank with --yank) — never a row delete
+ *   export <slug> --to-sdk  write into a local SDK checkout + print the PR line
+ *
+ * `export --to-sdk` is the ENTIRE "push upstream to the global set" story in v1:
+ * no new auth, no PAT, no hq surface (§5.4). The global channel is the npm
+ * package; promotion is a human PR.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/subagents/cli
+ */
+
+"use strict";
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { writeFileAtomic, writeJsonAtomic } from "../fs-atomic.mjs";
+import { resolveAgentRoot } from "../agent-root.mjs";
+import * as client from "./client.mjs";
+import { acceptDrop, mergeLock, readLock } from "./lock.mjs";
+import { buildManifest, manifestPath, readManifest } from "./manifest.mjs";
+import { computeGaps, contextFromConfig, rosterFromSurface } from "./gap.mjs";
+import { scanAgentRefs } from "./refs.mjs";
+import { agentFilePath, materialiseAll, renderEntry, resolveSubagents } from "./resolve.mjs";
+import { checkAgentFile, hashFile, parseAgentMd, stringifyAgentMd, stripProvenance } from "./schema.mjs";
+
+/** Flags every subcommand shares. */
+const FLAGS = {
+  force: { type: "boolean", default: false },
+  yank: { type: "boolean", default: false },
+  json: { type: "boolean", default: false },
+  as: { type: "string" },
+  "to-sdk": { type: "string" },
+  "no-network": { type: "boolean", default: false },
+};
+
+/** Read config/agent.json. Fail-open → {}. */
+function readAgentConfig(agentRoot) {
+  const p = join(agentRoot, "config", "agent.json");
+  if (!existsSync(p)) return {};
+  try { return JSON.parse(readFileSync(p, "utf8")) || {}; } catch { return {}; }
+}
+
+/**
+ * Assemble everything the local-first commands need in one pass: the pins
+ * (network-optional), the resolution, the roster and the reference scan.
+ *
+ * `pins` come from `subagent.resolve` when the network is available and from the
+ * cache otherwise — the caller never has to know which, which is the point of
+ * §4's local-first contract.
+ *
+ * `force` is passed straight through to the resolver, where it DEMOTES the local
+ * layer so `pull --force` can actually re-resolve an edited file to its upstream
+ * layer. Every other command leaves it off, so a local edit always wins there.
+ *
+ * @param {{agentRoot:string, maestroRoot:string, network?:boolean, force?:boolean, fetchImpl?:Function, env?:object}} o
+ */
+export async function loadState(o = {}) {
+  const agentRoot = o.agentRoot;
+  const maestroRoot = o.maestroRoot;
+  const cfg = client.resolveConfig({ agentRoot, env: o.env });
+  const lock = readLock(agentRoot);
+  const manifest = readManifest(maestroRoot);
+  const agentConfig = readAgentConfig(agentRoot);
+
+  let pins = [];
+  let degraded = [];
+  let rosterVersion = lock.rosterVersion;
+  if (o.network !== false && cfg.enabled) {
+    const r = await client.fetchResolve({
+      cfg,
+      agentRoot,
+      memberId: cfg.memberId || undefined,
+      function: agentConfig.function,
+      altitude: agentConfig.altitude,
+      fetchImpl: o.fetchImpl,
+    });
+    if (r.ok) { pins = r.entries; rosterVersion = r.rosterVersion; }
+    else degraded = ["workspace"];
+  } else if (!cfg.enabled) {
+    // Not enrolled is not a failure — layer 1 simply does not exist (§4).
+    degraded = [];
+  } else {
+    degraded = ["workspace"];
+  }
+
+  // With no live pins, reconstruct layer 1 from the lock + cache so an offline
+  // run still resolves workspace-pinned agents rather than silently demoting
+  // them to SDK (which would materialise the WRONG body).
+  if (!pins.length) {
+    pins = Object.entries(lock.agents || {})
+      .filter(([, e]) => e && e.layer === "workspace")
+      .map(([slug, e]) => ({ slug, definitionId: e.definitionId, version: e.version, contentHash: e.contentHash }));
+  }
+
+  const resolved = resolveSubagents({ agentRoot, maestroRoot, pins, manifest, lock, orgSlug: cfg.orgId, force: !!o.force });
+  const refs = scanAgentRefs({ agentRoot });
+  return { cfg, lock, manifest, agentConfig, pins, resolved, refs, degraded, rosterVersion };
+}
+
+/** Resolve the authoritative roster from the capability surface. Fail-open → []. */
+export async function loadRoster(agentConfig, opts = {}) {
+  if (typeof opts.resolveSurfaceImpl === "function") {
+    try { return rosterFromSurface(await opts.resolveSurfaceImpl({ function: agentConfig.function, altitude: agentConfig.altitude })); }
+    catch { return []; }
+  }
+  if (!agentConfig.function || !agentConfig.altitude) return [];
+  try {
+    const mod = await import("../capability.mjs");
+    const surface = await mod.resolveCapabilitySurface({ function: agentConfig.function, altitude: agentConfig.altitude });
+    return rosterFromSurface(surface);
+  } catch {
+    // No capability pack for this function → no authoritative roster. Everything
+    // on disk still resolves; only `missing`/`idle` go unreported.
+    return [];
+  }
+}
+
+/**
+ * Run a `maestro subagents` subcommand.
+ *
+ * @param {string[]} argv args AFTER `subagents`
+ * @param {{agentRoot?:string, maestroRoot?:string, fetchImpl?:Function, env?:object, print?:boolean, resolveSurfaceImpl?:Function}} [opts]
+ * @returns {Promise<{ok:boolean, code:number, lines:string[], data?:object}>}
+ */
+export async function run(argv = [], opts = {}) {
+  const agentRoot = opts.agentRoot || resolveAgentRoot();
+  const maestroRoot = opts.maestroRoot || join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+  const lines = [];
+  const say = (s) => { lines.push(s); if (opts.print !== false) console.log(s); };
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: FLAGS, allowPositionals: true, strict: false });
+  } catch (e) {
+    return { ok: false, code: 2, lines: [`subagents: ${e && e.message ? e.message : e}`] };
+  }
+  const [sub, ...rest] = parsed.positionals;
+  const flags = parsed.values;
+  const network = !flags["no-network"];
+  const ctx = { agentRoot, maestroRoot, network, fetchImpl: opts.fetchImpl, env: opts.env };
+
+  switch (sub) {
+    case undefined:
+    case "help":
+      say(usage());
+      return { ok: true, code: 0, lines };
+
+    case "list": {
+      const st = await loadState(ctx);
+      if (flags.json) { say(JSON.stringify(st.resolved.entries.map(slim), null, 2)); return { ok: true, code: 0, lines, data: st.resolved }; }
+      say(`Sub-agents (${st.resolved.entries.length}) — agentRoot ${agentRoot}`);
+      for (const e of st.resolved.entries) {
+        const v = e.version == null ? "-" : String(e.version);
+        say(`  ${e.slug.padEnd(28)} ${e.layer.padEnd(10)} v${v.padEnd(8)} ${e.localEdits ? "(local edit)" : e.orphaned ? "(orphaned)" : ""}`);
+      }
+      if (st.degraded.length) say(`  ! degraded: ${st.degraded.join(", ")} — resolved from cache/local only`);
+      return { ok: true, code: 0, lines, data: st.resolved };
+    }
+
+    case "status": {
+      const st = await loadState(ctx);
+      const roster = await loadRoster(st.agentConfig, opts);
+      const gaps = computeGaps({
+        roster, resolved: st.resolved, refs: st.refs, lock: st.lock,
+        context: contextFromConfig({ agentConfig: st.agentConfig }),
+      });
+      if (flags.json) { say(JSON.stringify(gaps, null, 2)); return { ok: gaps.status === "complete", code: 0, lines, data: gaps }; }
+      say(`Sub-agent registry — ${gaps.summary}`);
+      if (gaps.missing.length) {
+        say(`\n  MISSING (${gaps.missing.length}) — on the roster, no layer resolves them:`);
+        for (const m of gaps.missing) say(`    ${m.slug.padEnd(28)} ${m.role || ""}`);
+      }
+      if (gaps.unrostered.length) {
+        say(`\n  UNROSTERED (${gaps.unrostered.length}) — referenced but not on the roster:`);
+        for (const u of gaps.unrostered) {
+          const at = u.locations[0] ? `${u.locations[0].file}:${u.locations[0].line}` : "";
+          say(`    ${u.ref.padEnd(28)} ${u.action}${u.suggest ? ` → ${u.suggest}` : ""}${u.accepted ? " (drop accepted)" : ""}  ${at}`);
+        }
+      }
+      if (gaps.idle.length) {
+        say(`\n  IDLE (${gaps.idle.length}) — on the roster, referenced by nothing:`);
+        for (const i of gaps.idle) say(`    ${i.slug}`);
+      }
+      if (gaps.localEdits.length) say(`\n  LOCAL EDITS (${gaps.localEdits.length}): ${gaps.localEdits.join(", ")}`);
+      if (gaps.emptyDirs.length) say(`\n  EMPTY DIRS (${gaps.emptyDirs.length}) — agents/<slug>/ with no agent.md: ${gaps.emptyDirs.join(", ")}`);
+      return { ok: gaps.status === "complete", code: 0, lines, data: gaps };
+    }
+
+    case "show": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents show <slug>");
+      const st = await loadState(ctx);
+      const e = st.resolved.bySlug.get(slug);
+      if (!e) return fail(lines, `no sub-agent resolves for "${slug}"`);
+      say(`# ${slug}`);
+      say(`layer:   ${e.layer}`);
+      say(`source:  ${e.source}`);
+      say(`version: ${e.version == null ? "-" : e.version}`);
+      say(`hash:    ${e.contentHash}`);
+      say("");
+      say(e.body);
+      return { ok: true, code: 0, lines, data: e };
+    }
+
+    case "diff": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents diff <slug>");
+      const st = await loadState(ctx);
+      const e = st.resolved.bySlug.get(slug);
+      if (!e) return fail(lines, `no sub-agent resolves for "${slug}"`);
+      const p = agentFilePath(agentRoot, slug);
+      const onDisk = existsSync(p) ? readFileSync(p, "utf8") : "";
+      // Render through the SAME function materialise uses. Deriving the expected
+      // bytes any other way skips normalisation and reports every managed file as
+      // differing from the layer it was written from.
+      const rendered = renderEntry(e);
+      if (!rendered.ok) return fail(lines, `${slug}: cannot render the ${e.layer} layer — ${rendered.reason}`);
+      const want = rendered.text;
+      if (onDisk === want) { say(`${slug}: identical to the ${e.layer} layer`); return { ok: true, code: 0, lines }; }
+      say(`${slug}: differs from the ${e.layer} layer`);
+      for (const l of lineDiff(onDisk, want)) say(l);
+      return { ok: true, code: 0, lines, data: { slug, onDiskHash: hashFile(onDisk), layerHash: hashFile(want) } };
+    }
+
+    case "pull": {
+      // --force here is two things at once: demote the local layer during
+      // resolution AND permit the write. Both are needed — either alone is a
+      // no-op against an edited file.
+      const st = await loadState({ ...ctx, force: !!flags.force });
+      const out = materialiseAll({ agentRoot, resolved: st.resolved, force: !!flags.force });
+      mergeLock(agentRoot, { agents: out.lockAgents, rosterVersion: st.rosterVersion, degraded: st.degraded });
+      say(`pull: ${out.written} written, ${out.results.length - out.written} unchanged/refused`);
+      for (const r of out.results) if (!r.written && r.errors) say(`  ! ${r.slug}: ${r.reason}`);
+      if (st.degraded.length) say(`  ! degraded: ${st.degraded.join(", ")}`);
+      return { ok: true, code: 0, lines, data: out };
+    }
+
+    case "add": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents add <slug>");
+      const st = await loadState(ctx);
+      const p = agentFilePath(agentRoot, slug);
+      if (existsSync(p) && !flags.force) return fail(lines, `agents/${slug}/agent.md already exists (use --force to re-scaffold)`);
+      const text = skeleton(slug, st.agentConfig);
+      mkdirSync(join(agentRoot, "agents", slug), { recursive: true });
+      writeFileAtomic(p, text);
+      say(`wrote agents/${slug}/agent.md`);
+      const parsedMd = parseAgentMd(text);
+      const r = await client.createDefinition(
+        { slug, title: slug, summary: parsedMd.frontmatter.description || slug, frontmatter: parsedMd.frontmatter, body: parsedMd.body, generator: { source: "human" } },
+        { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl },
+      );
+      if (r.ok) {
+        say(`created workspace definition ${slug}`);
+        const pinRes = await client.pinDefinition({ slug, definitionId: r.result && r.result.definitionId, version: r.result && r.result.version }, { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl });
+        say(pinRes.ok ? `pinned ${slug}` : `pin queued/failed: ${describe(pinRes)}`);
+      } else {
+        say(`workspace create ${describe(r)}`);
+      }
+      return { ok: true, code: 0, lines, data: { slug, path: p } };
+    }
+
+    case "fork": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents fork <slug> [--as <new-slug>]");
+      const st = await loadState(ctx);
+      const src = st.resolved.bySlug.get(slug);
+      if (!src) return fail(lines, `no sub-agent resolves for "${slug}"`);
+      const target = String(flags.as || slug);
+      // A fork OWNS its body: the copy's frontmatter.name must be the NEW slug or
+      // it will fail validation the moment it is materialised (name == dirname).
+      const fm = { ...stripProvenance(src.frontmatter), name: target };
+      const r = await client.forkDefinition(
+        { slug: target, baseLayer: src.layer === "sdk" ? "sdk" : "none", baseSlug: slug, title: target, summary: fm.description || target, frontmatter: fm, body: src.body },
+        { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl },
+      );
+      say(r.ok ? `forked ${slug} → ${target}` : `fork ${describe(r)}`);
+      if (r.ok) {
+        const pinRes = await client.pinDefinition({ slug: target, definitionId: r.result && r.result.definitionId, version: r.result && r.result.version }, { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl });
+        say(pinRes.ok ? `pinned ${target}` : `pin ${describe(pinRes)}`);
+      }
+      return { ok: !!r.ok, code: r.ok ? 0 : 1, lines, data: r };
+    }
+
+    case "publish": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents publish <slug>");
+      const p = agentFilePath(agentRoot, slug);
+      if (!existsSync(p)) return fail(lines, `agents/${slug}/agent.md does not exist`);
+      const text = readFileSync(p, "utf8");
+      const checked = checkAgentFile(text, slug);
+      if (!checked.ok) {
+        // Refuse locally rather than let hq reject it — the operator gets the
+        // full error list instead of one server-side message.
+        for (const err of checked.errors) say(`  ! ${err}`);
+        return fail(lines, `${slug} does not validate; fix it before publishing`);
+      }
+      const st = await loadState(ctx);
+      const lockEntry = st.lock.agents[slug] || {};
+      const r = await client.publishVersion(
+        { slug, definitionId: lockEntry.definitionId || undefined, frontmatter: stripProvenance(checked.frontmatter), body: checked.body, generator: { source: "human" } },
+        { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl },
+      );
+      say(r.ok ? `published ${slug} v${(r.result && r.result.version) || "?"}` : `publish ${describe(r)}`);
+      return { ok: !!r.ok, code: r.ok ? 0 : 1, lines, data: r };
+    }
+
+    case "drop": {
+      const slug = rest[0];
+      if (!slug) return fail(lines, "usage: maestro subagents drop <slug> [--yank]");
+      const st = await loadState(ctx);
+      const lockEntry = st.lock.agents[slug] || {};
+      const r = await client.unpinDefinition({ slug, definitionId: lockEntry.definitionId || undefined }, { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl });
+      say(r.ok ? `unpinned ${slug}` : `unpin ${describe(r)}`);
+      if (flags.yank) {
+        const y = await client.yankDefinition({ slug, definitionId: lockEntry.definitionId || undefined, reason: "dropped from CLI" }, { cfg: st.cfg, agentRoot, fetchImpl: opts.fetchImpl });
+        say(y.ok ? `yanked ${slug}` : `yank ${describe(y)}`);
+      }
+      // The file is NOT deleted: dropping a pin removes the workspace layer, and
+      // the next `pull` will re-resolve the slug to SDK or leave the local file.
+      acceptDrop(agentRoot, { ref: slug, reason: "unpinned via CLI" });
+      return { ok: !!r.ok, code: r.ok ? 0 : 1, lines, data: r };
+    }
+
+    case "export": {
+      const slug = rest[0];
+      const toSdk = flags["to-sdk"];
+      if (!slug || !toSdk) return fail(lines, "usage: maestro subagents export <slug> --to-sdk <path-to-sdk-checkout>");
+      const st = await loadState(ctx);
+      const e = st.resolved.bySlug.get(slug);
+      if (!e) return fail(lines, `no sub-agent resolves for "${slug}"`);
+      // Provenance is stripped: what lands in the SDK is the DEFINITION, not a
+      // record of one org's copy of it.
+      const text = stringifyAgentMd({ ...stripProvenance(e.frontmatter), name: slug }, e.body);
+      const dest = join(toSdk, "agents", slug, "agent.md");
+      mkdirSync(join(toSdk, "agents", slug), { recursive: true });
+      writeFileAtomic(dest, text);
+      const built = buildManifest({ maestroRoot: toSdk, sdkVersion: readManifest(toSdk).sdkVersion, previous: readManifest(toSdk) });
+      writeJsonAtomic(manifestPath(toSdk), built.manifest);
+      say(`wrote ${dest}`);
+      say(`updated ${manifestPath(toSdk)}`);
+      say("");
+      say("Promotion to the global set is a human PR (v1 has no hq global catalogue):");
+      say(`  cd ${toSdk} && git checkout -b subagent/${slug} && git add agents/${slug} agents/manifest.json \\`);
+      say(`    && git commit -m "feat(agents): add ${slug}" \\`);
+      say(`    && gh pr create --title "feat(agents): add ${slug}" --body "Promoted from a workspace definition."`);
+      return { ok: true, code: 0, lines, data: { dest } };
+    }
+
+    default:
+      say(usage());
+      return { ok: false, code: 2, lines };
+  }
+}
+
+function fail(lines, msg) {
+  lines.push(msg);
+  console.error(msg);
+  return { ok: false, code: 1, lines };
+}
+
+function describe(r) {
+  if (r.queued) return `queued offline → ${r.queued}`;
+  if (r.degraded) return "not sent (server unreachable, not enrolled, or no outbox)";
+  return `failed: ${(r.error && r.error.message) || "unknown error"}`;
+}
+
+function slim(e) {
+  return { slug: e.slug, layer: e.layer, version: e.version, source: e.source, contentHash: e.contentHash, localEdits: !!e.localEdits };
+}
+
+/** A minimal unified-ish line diff — enough to see what changed, no dependency. */
+function lineDiff(a, b) {
+  const al = String(a).split("\n");
+  const bl = String(b).split("\n");
+  const out = [];
+  const max = Math.max(al.length, bl.length);
+  for (let i = 0; i < max; i++) {
+    if (al[i] === bl[i]) continue;
+    if (al[i] !== undefined) out.push(`  - ${al[i]}`);
+    if (bl[i] !== undefined) out.push(`  + ${bl[i]}`);
+  }
+  return out.slice(0, 200);
+}
+
+/**
+ * The `add` skeleton — the SAME shape `scripts/setup/generate-capability.mjs`
+ * renders, with a FULL model id and a `tools` array (the two fields that used to
+ * drift between shipped and generated agents).
+ */
+export function skeleton(slug, agentConfig = {}) {
+  const who = agentConfig.fullName || "the agent";
+  const fm = {
+    name: slug,
+    description: `TODO — one sentence describing when to delegate to ${slug}.`,
+    model: "claude-sonnet-4-6",
+    tools: ["Read", "Write", "Edit", "Glob", "Grep"],
+    tokens: [],
+  };
+  const body = `# ${slug}
+
+## Mandate
+
+TODO — what this sub-agent owns, in one paragraph.
+
+## Operating rules
+
+- Act within {{agent.firstName}}'s autonomy model and decision rights — see \`config/operating-charter.md\`.
+- Follow \`policies/communication-style.md\` for any outbound communication.
+- Escalate anything beyond your remit to {{agent.firstName}}.
+
+_Scaffolded by \`maestro subagents add ${slug}\` for ${who}. Enrich this mandate before publishing._
+`;
+  // Tokens are DECLARED from the body so the file validates on the first pass.
+  const used = [...new Set((body.match(/\{\{\s*([\w.]+)\s*\}\}/g) || []).map((m) => m.replace(/[{}\s]/g, "")))].sort();
+  fm.tokens = used;
+  return stringifyAgentMd(fm, body);
+}
+
+function usage() {
+  return [
+    "usage: maestro subagents <command>",
+    "",
+    "  list                          resolved roster (winning layer + version per slug)",
+    "  status [--json]               the three-way gap diff (roster / refs / layers)",
+    "  show <slug>                   resolved body + provenance",
+    "  diff <slug>                   local file vs the layer it came from",
+    "  add <slug>                    scaffold a new local def, then create + pin it",
+    "  fork <slug> [--as <new>]      copy the resolved body into a new org definition",
+    "  publish <slug>                promote the on-disk file as a new version",
+    "  pull [--force]                re-resolve + re-materialise (--force overwrites edits)",
+    "  drop <slug> [--yank]          unpin (and yank) — never a row delete",
+    "  export <slug> --to-sdk <path> write into an SDK checkout + print the PR line",
+    "",
+    "  --no-network                  never call hq (resolve from lock + cache + SDK)",
+  ].join("\n");
+}
+
+export { usage };