petbox-wire 0.1.0-ci.1206

package/src/transcript.ts

@@ -0,0 +1,86 @@
+// Shared Claude Code transcript parsing — the ONE implementation both the Stop hook
+// (push-session.ts) and the history importer (import-sessions.ts) use, so what a session
+// "is" cannot drift between live pushes and imports (spec: wiring-single-source).
+//
+// A transcript is JSONL; we keep the user/assistant TEXT turns in order and exclude tool
+// dumps, meta/sidechain entries and harness chrome — tool outputs can carry secrets and
+// the server only wants the dialogue (spec: wiring-history-import).
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+
+export type Msg = { role: string; content: string };
+
+export function extractText(message: unknown): string {
+  const msg = message as { content?: unknown } | null;
+  if (!msg || msg.content == null) return "";
+  if (typeof msg.content === "string") return msg.content.trim();
+  if (Array.isArray(msg.content)) {
+    const parts = msg.content
+      .filter((p: any) => p && p.type === "text" && typeof p.text === "string")
+      .map((p: any) => p.text);
+    return parts.join("\n").trim();
+  }
+  return "";
+}
+
+export function isExcluded(text: string): boolean {
+  return (
+    text.startsWith("<system-reminder") ||
+    text.startsWith("<command-name>") ||
+    text.startsWith("<local-command")
+  );
+}
+
+// Collect the user/assistant text messages in transcript order. No rendering and no cap:
+// the server needs the full, ordered transcript to assign stable per-message ordinals.
+export async function buildMessages(transcriptPath: string): Promise<Msg[]> {
+  const rl = createInterface({
+    input: createReadStream(transcriptPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  const msgs: Msg[] = [];
+  for await (const line of rl) {
+    if (!line || line.trim().length === 0) continue;
+    let e: any;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (e.type !== "user" && e.type !== "assistant") continue;
+    if (e.isMeta || e.isSidechain) continue;
+    const text = extractText(e.message);
+    if (text.length === 0) continue;
+    if (isExcluded(text)) continue;
+    msgs.push({ role: e.type, content: text });
+  }
+  return msgs;
+}
+
+// The cwd a transcript was recorded in (the first entry that carries one). Lets the
+// importer attribute a transcript to a registered project WITHOUT reversing Claude's
+// lossy path-encoding of the directory name.
+export async function readTranscriptCwd(transcriptPath: string, maxLines = 25): Promise<string | null> {
+  const rl = createInterface({
+    input: createReadStream(transcriptPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  let seen = 0;
+  for await (const line of rl) {
+    if (++seen > maxLines) break;
+    if (!line || line.trim().length === 0) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.cwd === "string" && e.cwd.length > 0) {
+        rl.close();
+        return e.cwd;
+      }
+    } catch {
+      /* skip unparseable line */
+    }
+  }
+  return null;
+}

package/src/truthfulness.test.ts

@@ -0,0 +1,544 @@
+// Unit tests for the definition truthfulness gate + default agent definition + apply plans.
+//
+// Run: node --test src/truthfulness.test.ts   (Node >= 23.6 native TS)
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  DEFAULT_AGENT_DEFINITION,
+  validateAgentDefinition,
+  type AgentDefinition,
+} from "./agent-definition.ts";
+import {
+  formatApplyBlocked,
+  planApply,
+  planOpencodeApply,
+  renderAgentMarkdown,
+  renderDroidMarkdown,
+  renderOpencodeAgentMarkdown,
+} from "./apply-artifacts.ts";
+import { hasPetboxMarker } from "./origin-marker.ts";
+import { HARNESS_IDS, harnessCapabilities, hasCapability } from "./harness-capabilities.ts";
+import { allowedModels, classifyModel, isResolvableModel } from "./harness-models.ts";
+import {
+  checkTruthfulness,
+  formatViolations,
+  isModelViolation,
+  modelShapeWarning,
+  type ModelViolation,
+} from "./truthfulness.ts";
+import { classifyApplyExit, WIRE_EXIT } from "./wire-exit.ts";
+
+test("claude-code declares role_files + spawn_subagents + mcp_subagent (verified live 2026-07-12)", () => {
+  const caps = harnessCapabilities("claude-code");
+  assert.equal(caps.has("mcp_main_session"), true);
+  assert.equal(caps.has("dynamic_model_at_spawn"), true);
+  assert.equal(caps.has("builtin_explore_inherits_model"), true);
+  assert.equal(caps.has("hooks"), true);
+  assert.equal(caps.has("role_files"), true);
+  assert.equal(caps.has("spawn_subagents"), true);
+  assert.equal(caps.has("mcp_subagent"), true);
+});
+
+test("opencode declares role_files + mcp_subagent + spawn_subagents, not dynamic_model_at_spawn", () => {
+  const caps = harnessCapabilities("opencode");
+  assert.equal(caps.has("role_files"), true);
+  assert.equal(caps.has("mcp_subagent"), true);
+  assert.equal(caps.has("builtin_explore_inherits_model"), true);
+  assert.equal(caps.has("spawn_subagents"), true);
+  assert.equal(caps.has("dynamic_model_at_spawn"), false);
+});
+
+test("droid matrix from Factory docs: role_files+spawn+mcp+dynamic+hooks; no explore-inherit claim", () => {
+  // https://docs.factory.ai/cli/configuration/custom-droids
+  // https://docs.factory.ai/cli/configuration/mcp
+  const caps = harnessCapabilities("droid");
+  for (const c of [
+    "mcp_main_session",
+    "mcp_subagent",
+    "spawn_subagents",
+    "role_files",
+    "dynamic_model_at_spawn",
+    "hooks",
+  ] as const) {
+    assert.equal(caps.has(c), true, `droid must declare ${c}`);
+  }
+  assert.equal(
+    hasCapability("droid", "builtin_explore_inherits_model"),
+    false,
+    "do not claim CC-style Explore inherit without separate verification",
+  );
+});
+
+test("constructed def requiring missing cap fails with role+capability+harness in message", () => {
+  const def: AgentDefinition = {
+    name: "t",
+    roles: [
+      {
+        slug: "worker",
+        tier: "worker",
+        // opencode does not declare dynamic_model_at_spawn (PR #18588) — a capability
+        // still genuinely absent from a known harness's row, unlike mcp_subagent which
+        // claude-code now declares (verified live 2026-07-12).
+        requiredCapabilities: ["dynamic_model_at_spawn"],
+      },
+    ],
+  };
+  const v = checkTruthfulness(def, "opencode");
+  assert.equal(v.length, 1);
+  assert.deepEqual(v[0], {
+    role: "worker",
+    capability: "dynamic_model_at_spawn",
+    harness: "opencode",
+  });
+  const msg = formatViolations(v);
+  assert.match(msg, /worker/);
+  assert.match(msg, /dynamic_model_at_spawn/);
+  assert.match(msg, /opencode/);
+});
+
+test("DEFAULT is truth-clean on all known harnesses (including droid)", () => {
+  validateAgentDefinition(DEFAULT_AGENT_DEFINITION);
+  for (const h of HARNESS_IDS) {
+    const v = checkTruthfulness(DEFAULT_AGENT_DEFINITION, h);
+    assert.deepEqual(v, [], `default must pass on ${h}: ${formatViolations(v)}`);
+  }
+  const explore = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "explore");
+  assert.ok(explore);
+  assert.ok(!(explore!.notes ?? "").toLowerCase().includes("inheritance forbidden"));
+});
+
+test("gate still fires: role needing undeclared cap on a harness that lacks it", () => {
+  // opencode does not declare dynamic_model_at_spawn (PR #18588)
+  const def: AgentDefinition = {
+    name: "bad",
+    roles: [
+      {
+        slug: "worker",
+        tier: "worker",
+        requiredCapabilities: ["dynamic_model_at_spawn"],
+      },
+    ],
+  };
+  const v = checkTruthfulness(def, "opencode");
+  assert.equal(v.length, 1);
+  const [violation] = v;
+  assert.ok(violation);
+  // Narrow to CapabilityViolation: this def has no model binding, so the only possible
+  // violation kind is the missing-capability one — assert that explicitly rather than
+  // reading `.capability` off the union type (that field does not exist on ModelViolation).
+  assert.ok(!isModelViolation(violation), "expected a capability violation, not a model one");
+  assert.equal(violation.capability, "dynamic_model_at_spawn");
+  assert.equal(violation.harness, "opencode");
+});
+
+test("planApply: paths for claude-code, opencode, droid (.factory/droids)", () => {
+  const portable: AgentDefinition = {
+    name: "portable",
+    roles: [
+      {
+        slug: "worker",
+        tier: "worker",
+        requiredCapabilities: [],
+        spawn: { allowed: false },
+      },
+    ],
+  };
+  const cc = planApply(portable, "claude-code", {});
+  assert.equal(cc.violations.length, 0);
+  assert.ok(cc.files.some((f) => f.relativePath === ".claude/agents/petbox-worker.md"));
+  // Namespacing rename: the pre-prefix name is carried alongside so the writer can clean up
+  // an OWNED leftover from before the rename (never a foreign file — see apply-write.ts).
+  assert.ok(
+    cc.files.some((f) => f.legacyRelativePath === ".claude/agents/worker.md"),
+    "legacyRelativePath must point at the bare pre-namespacing name",
+  );
+
+  const oc = planApply(portable, "opencode", {});
+  assert.equal(oc.violations.length, 0);
+  assert.ok(oc.files.every((f) => f.relativePath.startsWith(".opencode/agent/")));
+  assert.ok(oc.files.some((f) => f.relativePath === ".opencode/agent/petbox-worker.md"));
+
+  const dr = planApply(portable, "droid", {});
+  assert.equal(dr.violations.length, 0);
+  assert.ok(dr.files.every((f) => f.relativePath.startsWith(".factory/droids/")));
+  assert.ok(dr.files.some((f) => f.relativePath === ".factory/droids/petbox-worker.md"));
+  assert.ok(dr.files.some((f) => f.legacyRelativePath === ".factory/droids/worker.md"));
+});
+
+test("planApply DEFAULT writes all three harnesses including droid droids", () => {
+  for (const h of HARNESS_IDS) {
+    const plan = planApply(DEFAULT_AGENT_DEFINITION, h, {});
+    assert.equal(plan.violations.length, 0, formatViolations(plan.violations));
+    assert.ok(plan.files.length >= 5, `${h} should emit all default roles`);
+  }
+  const droid = planApply(DEFAULT_AGENT_DEFINITION, "droid", {
+    orchestrator: "custom:deepseek-v4-pro",
+  });
+  const orch = droid.files.find((f) => f.relativePath.includes("orchestrator"));
+  assert.ok(orch);
+  assert.match(orch!.content, /^---\nname: petbox-orchestrator\n/m);
+  assert.match(orch!.content, /model: custom:deepseek-v4-pro/);
+  assert.match(orch!.content, /mcpServers: \["petbox"\]/);
+  assert.ok(hasPetboxMarker(orch!.content), "every generated file carries the origin marker");
+});
+
+test("renderDroidMarkdown: unbound model is inherit; bound uses roles.json value", () => {
+  const role = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  const inherit = renderDroidMarkdown(role);
+  assert.match(inherit, /name: petbox-worker/);
+  assert.match(inherit, /model: inherit/);
+
+  const pinned = renderDroidMarkdown(role, "claude-sonnet-4-5-20250929");
+  assert.match(pinned, /model: claude-sonnet-4-5-20250929/);
+});
+
+test("planApply: emits clean roles, skips only dirty ones", () => {
+  const def: AgentDefinition = {
+    name: "mixed",
+    roles: [
+      {
+        slug: "worker",
+        tier: "worker",
+        requiredCapabilities: [],
+        spawn: { allowed: false },
+      },
+      {
+        slug: "needs-dyn",
+        tier: "worker",
+        requiredCapabilities: ["dynamic_model_at_spawn"],
+        spawn: { allowed: false },
+      },
+    ],
+  };
+  // opencode lacks dynamic_model_at_spawn
+  const plan = planApply(def, "opencode", {});
+  assert.equal(plan.files.length, 1);
+  assert.ok(plan.files[0]!.relativePath.endsWith("worker.md"));
+  assert.deepEqual(plan.skippedRoles, ["needs-dyn"]);
+  assert.equal(plan.violations.length, 1);
+  assert.match(formatApplyBlocked(plan.violations, "opencode", plan.skippedRoles), /needs-dyn/);
+});
+
+test("planApply: bound model in claude-code frontmatter; unbound omits model (+warns)", () => {
+  const portable: AgentDefinition = {
+    name: "p",
+    roles: [{ slug: "worker", tier: "worker", requiredCapabilities: [] }],
+  };
+  // Must be an id Claude Code actually resolves — the old fixture used a provider-prefixed
+  // "anthropic/claude-sonnet-4", which is exactly the shape the model gate now rejects.
+  const withModel = planApply(portable, "claude-code", { worker: "sonnet" });
+  assert.equal(withModel.violations.length, 0);
+  const worker = withModel.files.find((f) => f.relativePath.endsWith("worker.md"));
+  assert.ok(worker);
+  assert.match(worker!.content, /^---\nname: petbox-worker\nmodel: sonnet\n/m);
+  assert.deepEqual(withModel.warnings, []);
+
+  const unbound = planApply(portable, "claude-code", {});
+  const body = unbound.files[0]!.content;
+  assert.match(body, /^---\nname: petbox-worker\n/m, "name: is always emitted");
+  assert.ok(!/^model:/m.test(body.split("---")[1] ?? ""), "no invented model");
+  // Unbound is legal (inherit) but must not be silent.
+  assert.equal(unbound.violations.length, 0);
+  assert.equal(unbound.warnings.length, 1);
+  assert.match(unbound.warnings[0]!, /inherit the session\/parent model/);
+});
+
+test("model gate: claude-code role bound to a droid id is BLOCKED (not written)", () => {
+  const portable: AgentDefinition = {
+    name: "p",
+    roles: [
+      { slug: "worker", tier: "worker", requiredCapabilities: [] },
+      { slug: "utility", tier: "utility", requiredCapabilities: [] },
+    ],
+  };
+  // The 2026-07-12 incident: droid ids copied into the claude-code block of roles.json.
+  const plan = planApply(portable, "claude-code", {
+    worker: "custom:DeepSeek-V4-Pro-0",
+    utility: "haiku",
+  });
+
+  assert.deepEqual(plan.skippedRoles, ["worker"]);
+  assert.ok(
+    !plan.files.some((f) => f.relativePath.endsWith("worker.md")),
+    "an unresolvable model must never reach .claude/agents/*.md",
+  );
+  assert.ok(plan.files.some((f) => f.relativePath.endsWith("utility.md")));
+
+  assert.equal(plan.violations.length, 1);
+  const v = plan.violations[0]!;
+  assert.ok(isModelViolation(v));
+  assert.equal(v.role, "worker");
+  assert.equal(v.harness, "claude-code");
+  assert.equal(v.model, "custom:DeepSeek-V4-Pro-0");
+  assert.ok(v.allowedModels.includes("sonnet"));
+
+  const msg = formatApplyBlocked(plan.violations, plan.harness, plan.skippedRoles);
+  assert.match(msg, /worker/);
+  assert.match(msg, /custom:DeepSeek-V4-Pro-0/);
+  assert.match(msg, /claude-code/);
+  // Revised 2026-07-13: the gate no longer claims CC silently inherits on a bad id (a live
+  // measurement disproved that — CC fails LOUD at runtime). The message now says the id looks
+  // like another harness's, not this one's.
+  assert.match(msg, /looks like ANOTHER harness's model id/);
+  assert.doesNotMatch(msg, /SILENTLY inherit/);
+  assert.match(msg, /Known claude-code aliases: .*sonnet/);
+
+  // apply's exit contract: a blocked role ⇒ non-zero (3), same as a capability violation.
+  const hadTruthfulnessBlock = plan.violations.length > 0;
+  assert.equal(classifyApplyExit({ hadTruthfulnessBlock }), WIRE_EXIT.truthfulness);
+  assert.notEqual(WIRE_EXIT.truthfulness, 0);
+});
+
+test("model gate tier 1 (known): every claude-code alias in the live roster classifies known", () => {
+  // .claude/agents/*.md of this repo (verified 2026-07-12): opus/sonnet/haiku/fable.
+  for (const m of ["opus", "sonnet", "haiku", "fable", "inherit", "OPUS"]) {
+    assert.equal(classifyModel("claude-code", m), "known", `${m} must be known`);
+    assert.equal(isResolvableModel("claude-code", m), true, `${m} must resolve`);
+  }
+  assert.ok(allowedModels("claude-code")!.length > 0);
+});
+
+test("model gate tier 2 (unknown, non-blocking): shape-valid claude-* ids not on the alias list warn, never block", () => {
+  // Revised 2026-07-13 (model-gate-revision-premise-falsified): a live measurement disproved
+  // the "CC silently inherits on a bad id" premise the old closed list was built on, and showed
+  // CC fails LOUD at runtime instead. A concrete Anthropic id — real (claude-opus-4-8, incl. the
+  // 1M-context suffix form) or a plain TYPO (claude-sonnet-4.6) — is now "unknown": shape-valid,
+  // not on the small known-alias list, NOT blocked. The gate can no longer tell a typo from a
+  // real id it just hasn't heard of yet; that tradeoff is deliberate (see harness-models.ts).
+  for (const m of ["claude-opus-4-8", "claude-sonnet-5", "claude-opus-4-8[1m]", "claude-sonnet-4.6"]) {
+    assert.equal(classifyModel("claude-code", m), "unknown", `${m} must be unknown (shape-valid, unlisted)`);
+    assert.equal(isResolvableModel("claude-code", m), true, `${m} must not be blocked`);
+  }
+});
+
+test("model gate tier 3 (foreign, blocking): another harness's id shape, or no recognizable shape, is refused", () => {
+  for (const m of [
+    "custom:DeepSeek-V4-Pro-0", // droid BYOK scheme
+    "custom:Qwen3.7-Max-[1M-ctx-·-orchestrator]-0",
+    "deepseek/deepseek-v4-pro", // opencode provider/model shape
+    "opencode/some-model",
+    "anthropic/claude-sonnet-4", // provider-prefixed — still opencode's shape, not CC's
+    "gpt-5", // no recognizable shape at all — not claude-*, not provider/model or scheme:id
+  ]) {
+    assert.equal(classifyModel("claude-code", m), "foreign", `${m} must be foreign`);
+    assert.equal(isResolvableModel("claude-code", m), false, `${m} must NOT resolve`);
+  }
+});
+
+test("model gate: planApply WRITES a role bound to an unknown-tier model, with a non-blocking warning", () => {
+  // The whole point of the revision: a real-but-unlisted id (e.g. a future claude-opus-5) must
+  // not be blocked the way the old closed list would have blocked it.
+  const portable: AgentDefinition = {
+    name: "p",
+    roles: [{ slug: "worker", tier: "worker", requiredCapabilities: [] }],
+  };
+  const plan = planApply(portable, "claude-code", { worker: "claude-opus-5" });
+  assert.equal(plan.violations.length, 0, formatViolations(plan.violations));
+  assert.deepEqual(plan.skippedRoles, []);
+  const worker = plan.files.find((f) => f.relativePath.endsWith("worker.md"));
+  assert.ok(worker, "unknown-tier model must still be written, not blocked");
+  assert.match(worker!.content, /model: claude-opus-5/);
+  assert.equal(plan.warnings.length, 1);
+  assert.match(plan.warnings[0]!, /not on the harness's known-alias list/);
+  assert.match(plan.warnings[0]!, /fails LOUD at runtime/);
+
+  // Same fact via the pure helper directly.
+  const role = portable.roles[0]!;
+  const warning = modelShapeWarning(role, "claude-code", "claude-opus-5");
+  assert.ok(warning);
+  assert.equal(modelShapeWarning(role, "claude-code", "sonnet"), null, "known tier warns nothing");
+  assert.equal(
+    modelShapeWarning(role, "claude-code", "custom:DeepSeek-V4-Pro-0"),
+    null,
+    "foreign tier is a violation, not a warning — modelShapeWarning stays silent on it",
+  );
+});
+
+test("model gate: droid/opencode id spaces stay open (no invented allow-list)", () => {
+  // Both resolve ids against a local/provider registry — the kit makes no claim, so a real
+  // binding like custom:DeepSeek-V4-Pro-0 or deepseek/deepseek-v4-pro must NOT be blocked.
+  assert.equal(allowedModels("droid"), null);
+  assert.equal(allowedModels("opencode"), null);
+  assert.equal(isResolvableModel("droid", "custom:DeepSeek-V4-Pro-0"), true);
+  assert.equal(isResolvableModel("opencode", "deepseek/deepseek-v4-pro"), true);
+
+  const droid = planApply(DEFAULT_AGENT_DEFINITION, "droid", {
+    worker: "custom:DeepSeek-V4-Pro-0",
+  });
+  assert.equal(droid.violations.length, 0);
+  const oc = planApply(DEFAULT_AGENT_DEFINITION, "opencode", {
+    worker: "deepseek/deepseek-v4-pro",
+  });
+  assert.equal(oc.violations.length, 0);
+});
+
+test("checkTruthfulness (doctor path) also gates the local model binding", () => {
+  const clean = checkTruthfulness(DEFAULT_AGENT_DEFINITION, "claude-code", {
+    orchestrator: "opus",
+    worker: "sonnet",
+    utility: "haiku",
+    reserve: "fable",
+    explore: "haiku",
+  });
+  assert.deepEqual(clean, [], formatViolations(clean));
+
+  const dirty = checkTruthfulness(DEFAULT_AGENT_DEFINITION, "claude-code", {
+    worker: "custom:DeepSeek-V4-Pro-0",
+  });
+  assert.equal(dirty.length, 1);
+  assert.ok(isModelViolation(dirty[0]!));
+  assert.equal((dirty[0] as ModelViolation).role, "worker");
+});
+
+test("planOpencodeApply: bound model in frontmatter; unbound omits model", () => {
+  const withModel = planOpencodeApply(DEFAULT_AGENT_DEFINITION, {
+    worker: "deepseek/deepseek-v4-pro",
+  });
+  assert.equal(withModel.violations.length, 0);
+  const worker = withModel.files.find((f) => f.relativePath.endsWith("worker.md"));
+  assert.ok(worker);
+  assert.match(worker!.content, /^---\nname: petbox-worker\nmodel: deepseek\/deepseek-v4-pro\n/m);
+});
+
+test("renderOpencodeAgentMarkdown explore body does not forbid inheritance", () => {
+  const explore = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "explore")!;
+  const md = renderOpencodeAgentMarkdown(explore);
+  assert.match(md, /Model inheritance/i);
+  assert.ok(!md.toLowerCase().includes("inheritance forbidden"));
+});
+
+test("validateAgentDefinition rejects role.model and nested model", () => {
+  assert.throws(
+    () =>
+      validateAgentDefinition({
+        name: "x",
+        roles: [
+          {
+            slug: "w",
+            tier: "worker",
+            requiredCapabilities: [],
+            // @ts-expect-error intentional
+            model: "should-not-be-here",
+          },
+        ],
+      }),
+    /model is not allowed/,
+  );
+  assert.throws(
+    () =>
+      validateAgentDefinition({
+        name: "x",
+        // @ts-expect-error intentional
+        model: "root-bad",
+        roles: [{ slug: "w", tier: "worker", requiredCapabilities: [] }],
+      }),
+    /model is not allowed/,
+  );
+  assert.throws(
+    () =>
+      validateAgentDefinition({
+        name: "x",
+        roles: [
+          {
+            slug: "w",
+            tier: "worker",
+            requiredCapabilities: [],
+            spawn: {
+              allowed: false,
+              // @ts-expect-error intentional
+              model: "nested-bad",
+            },
+          },
+        ],
+      }),
+    /model is not allowed/,
+  );
+});
+
+test("renderAgentMarkdown: generated claude-code role file carries name: as first frontmatter key", () => {
+  const role = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  const md = renderAgentMarkdown(role);
+  assert.match(md, /^---\nname: petbox-worker\n/, "name: must be the first frontmatter key, namespaced");
+  // No tools: key — omission means the file inherits the harness's full tool set,
+  // including MCP (that is the intended policy; see harness-capabilities.ts).
+  assert.ok(!/^tools:/m.test(md), "must not emit a tools: key");
+  assert.ok(hasPetboxMarker(md), "generated file must carry the origin marker");
+});
+
+test("emitted agent names are namespaced petbox-<slug> across the whole default roster, every harness", () => {
+  // chore: petbox-namespaced-agent-names — role.slug (internal) stays bare; only the render
+  // is prefixed. Assert it holds for every role x harness, not just worker.
+  for (const harness of HARNESS_IDS) {
+    const plan = planApply(DEFAULT_AGENT_DEFINITION, harness, {});
+    assert.equal(plan.violations.length, 0, formatViolations(plan.violations));
+    for (const role of DEFAULT_AGENT_DEFINITION.roles) {
+      const file = plan.files.find((f) => f.relativePath.includes(`petbox-${role.slug}`));
+      assert.ok(file, `${harness}: expected a petbox-${role.slug} file`);
+      assert.match(file!.content, new RegExp(`name: petbox-${role.slug}\\b`));
+      assert.ok(hasPetboxMarker(file!.content));
+      // Never emit the bare, unprefixed name as the CURRENT (non-legacy) path.
+      assert.ok(
+        !plan.files.some((f) => f.relativePath.endsWith(`/${role.slug}.md`)),
+        `${harness}: must not also emit an unprefixed ${role.slug}.md as a current artifact`,
+      );
+    }
+  }
+});
+
+test("orchestrator body's spawn/escalation prose names the NAMESPACED target roles, not bare slugs", () => {
+  // protocol.ts:62-style bug, generalized: any prose naming a spawn/escalation target must
+  // render the computed identity — never role.slug directly — or a generated file points at
+  // a subagent_type that does not exist on disk.
+  const orchestrator = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "orchestrator")!;
+  const md = renderAgentMarkdown(orchestrator);
+  assert.match(md, /Target roles:.*`petbox-worker`/);
+  assert.match(md, /Target roles:.*`petbox-utility`/);
+  assert.ok(!/Target roles:.*`worker`[,.]/.test(md), "must not list the bare slug");
+
+  const worker = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  const workerMd = renderAgentMarkdown(worker);
+  assert.match(workerMd, /Escalation[\s\S]*`petbox-orchestrator`/);
+});
+
+test("renderAgentMarkdown / renderDroidMarkdown: role.notes land in the rendered body", () => {
+  const role = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "orchestrator")!;
+  assert.ok(role.notes && role.notes.length > 0);
+  const cc = renderAgentMarkdown(role);
+  assert.ok(cc.includes(role.notes!), "claude-code/opencode body must include role.notes");
+  const droid = renderDroidMarkdown(role);
+  assert.ok(droid.includes(role.notes!), "droid body must include role.notes");
+});
+
+test("leaf role body states the no-spawn rule imperatively, independent of harness tool grants", () => {
+  const worker = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  assert.equal(worker.spawn?.allowed, false);
+  const md = renderAgentMarkdown(worker);
+  assert.match(md, /MUST NOT spawn subagents/i);
+});
+
+test("claude-code declares mcp_subagent (verified live 2026-07-12)", () => {
+  assert.equal(hasCapability("claude-code", "mcp_subagent"), true);
+});
+
+test("DEFAULT reserve notes: offline fallback does not invert the live semantics (bug @80 item 5)", () => {
+  // The offline fallback once taught the OPPOSITE rule: "Heavy reasoning / architecture
+  // review / stuck points only" reads as "call reserve when the work is heavy" — the live
+  // server definition says the exact reverse (hard work is a model escalation on a worker;
+  // reserve is for being STUCK, never merely for difficulty). Guard both directions so a
+  // hand-copied fallback cannot silently drift back into the inverted phrasing.
+  const reserve = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "reserve")!;
+  const notes = reserve.notes ?? "";
+  assert.match(notes, /STUCK/, "reserve notes must state the stuck-trigger explicitly");
+  assert.ok(
+    !/heavy reasoning/i.test(notes),
+    "must not reintroduce 'heavy reasoning ... only' framing (the inverted rule)",
+  );
+  assert.ok(
+    /not merely when the work is hard/i.test(notes),
+    "must explicitly rule out 'hard work' as a trigger for reserve",
+  );
+  // requiredCapabilities must target the subagent surface, not mcp_main_session — reserve
+  // exists only as a subagent (finding 4 of the same node, closed alongside this fallback).
+  assert.deepEqual([...reserve.requiredCapabilities], ["mcp_subagent"]);
+});