petbox-wire 0.1.0-ci.1206

package/src/agent-def-fetch.ts

@@ -0,0 +1,409 @@
+// Fetch a portable agent definition from PetBox for petbox-wire apply.
+//
+// Contract (server: AgentDefsApi):
+//   GET {baseUrl}/api/{projectKey}/agent-defs/{key}
+//   header X-Api-Key; scope agents:read
+//   200 → { key, version, definition: { name, roles: [...] }, created?, updated? }
+//
+// Polarity (definition-offline-lkg / wiring-memory-canon):
+//   Server is authoritative; disk is LKG replica under ~/.petbox/cache/<project>.agent-def.json.
+//   roles.json is the opposite polarity (disk authoritative) — not touched here.
+//
+// Resolution order on apply:
+//   1. live server fetch (unless --offline)
+//   2. LKG cache from last successful fetch (with explicit staleness mark)
+//   3. DEFAULT_AGENT_DEFINITION only when no cache exists (fresh machine)
+//
+// Best-effort: network / 404 / auth / bad JSON / timeout → null from fetch (never throws).
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentDefinition, AgentRole, RoleEscalation, RoleSpawn } from "./agent-definition.ts";
+import { DEFAULT_AGENT_DEFINITION, validateAgentDefinition } from "./agent-definition.ts";
+
+export const DEFAULT_DEFINITION_KEY = "default";
+export const AGENT_DEF_FETCH_TIMEOUT_MS = 8000;
+
+/** Shown when apply uses LKG cache instead of a live server fetch (definition-offline-lkg). */
+export const AGENT_DEF_STALE_MARKER =
+  "⚠ Agent definition is from the local LKG cache (PetBox unreachable) — may be stale.";
+
+/** Successful server fetch: key + version envelope around a portable definition. */
+export type FetchedAgentDefinition = {
+  readonly key: string;
+  readonly version: number;
+  readonly definition: AgentDefinition;
+};
+
+export type FetchAgentDefinitionOptions = {
+  readonly baseUrl: string;
+  readonly projectKey: string;
+  readonly apiKey: string;
+  /** Document key; defaults to `default`. */
+  readonly definitionKey?: string;
+  readonly timeoutMs?: number;
+  /** Injected for tests; defaults to global fetch. */
+  readonly fetchImpl?: typeof fetch;
+};
+
+export type AgentDefCacheRecord = {
+  readonly key: string;
+  readonly version: number;
+  readonly fetchedAt: string;
+  readonly definition: AgentDefinition;
+};
+
+/** Where a resolved definition came from (for logs / tests). */
+export type AgentDefSource = "server" | "lkg" | "default";
+
+export type ResolvedAgentDefinition = {
+  readonly definition: AgentDefinition;
+  readonly source: AgentDefSource;
+  /** True when source === "lkg" (explicit staleness). */
+  readonly stale: boolean;
+  readonly key?: string;
+  readonly version?: number;
+  /** Human-facing line for apply logs when stale. */
+  readonly staleMarker?: string;
+};
+
+export function agentDefCacheDir(homeDir: string = homedir()): string {
+  return join(homeDir, ".petbox", "cache");
+}
+
+/** Path: ~/.petbox/cache/<project>.agent-def.json (project may contain $ etc.). */
+export function agentDefCachePath(projectKey: string, homeDir: string = homedir()): string {
+  // Same sanitization style as canon: use project key as filename stem.
+  const stem = String(projectKey).trim() || "unknown";
+  return join(agentDefCacheDir(homeDir), `${stem}.agent-def.json`);
+}
+
+/**
+ * Pure JSON → definition mapping. Returns null on any invalid/incomplete shape.
+ * Tolerates extra fields; rejects role.model (portable roster only).
+ */
+export function parseAgentDefinitionResponse(json: unknown): FetchedAgentDefinition | null {
+  if (!json || typeof json !== "object") return null;
+  const root = json as Record<string, unknown>;
+
+  const key = typeof root["key"] === "string" && root["key"].trim() ? root["key"].trim() : null;
+  const version = parseVersion(root["version"]);
+  if (key === null || version === null) return null;
+
+  const defRaw = root["definition"];
+  if (!defRaw || typeof defRaw !== "object") return null;
+  const def = defRaw as Record<string, unknown>;
+
+  const name = typeof def["name"] === "string" && def["name"].trim() ? def["name"].trim() : null;
+  if (name === null) return null;
+  if (!Array.isArray(def["roles"]) || def["roles"].length === 0) return null;
+
+  const roles: AgentRole[] = [];
+  for (const item of def["roles"]) {
+    const role = mapRole(item);
+    if (role === null) return null;
+    roles.push(role);
+  }
+
+  return {
+    key,
+    version,
+    definition: { name, roles },
+  };
+}
+
+/**
+ * GET the named agent definition. Returns the mapped definition on 200 + valid body;
+ * null on any failure (network, timeout, non-OK status, bad JSON, invalid shape).
+ * Never throws. Does NOT write LKG — caller uses writeAgentDefCache on success.
+ */
+export async function fetchAgentDefinition(
+  opts: FetchAgentDefinitionOptions,
+): Promise<FetchedAgentDefinition | null> {
+  try {
+    const base = String(opts.baseUrl ?? "").replace(/\/+$/, "");
+    const project = String(opts.projectKey ?? "").trim();
+    const apiKey = String(opts.apiKey ?? "").trim();
+    const defKey = (opts.definitionKey?.trim() || DEFAULT_DEFINITION_KEY).trim();
+    if (!base || !project || !apiKey || !defKey) return null;
+
+    const timeoutMs =
+      typeof opts.timeoutMs === "number" && opts.timeoutMs > 0
+        ? opts.timeoutMs
+        : AGENT_DEF_FETCH_TIMEOUT_MS;
+    const fetchFn = opts.fetchImpl ?? fetch;
+
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const url = `${base}/api/${encodeURIComponent(project)}/agent-defs/${encodeURIComponent(defKey)}`;
+      const resp = await fetchFn(url, {
+        method: "GET",
+        // Connection: close — no lingering keep-alive socket after a short-lived hook
+        // process's single request (see canon.ts's fetchCanon for the full rationale).
+        headers: { "X-Api-Key": apiKey, Connection: "close" },
+        signal: ctrl.signal,
+      });
+      if (!resp.ok) return null;
+      const body = (await resp.json().catch(() => null)) as unknown;
+      return parseAgentDefinitionResponse(body);
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/** Persist LKG after a successful fetch. Never throws. */
+export function writeAgentDefCache(
+  projectKey: string,
+  fetched: FetchedAgentDefinition,
+  homeDir: string = homedir(),
+  now: () => string = () => new Date().toISOString(),
+): void {
+  try {
+    const dir = agentDefCacheDir(homeDir);
+    mkdirSync(dir, { recursive: true });
+    const record: AgentDefCacheRecord = {
+      key: fetched.key,
+      version: fetched.version,
+      fetchedAt: now(),
+      definition: fetched.definition,
+    };
+    writeFileSync(agentDefCachePath(projectKey, homeDir), JSON.stringify(record, null, 2) + "\n", "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+/** Read LKG cache. Returns null if missing/corrupt. Never throws. */
+export function readAgentDefCache(
+  projectKey: string,
+  homeDir: string = homedir(),
+): AgentDefCacheRecord | null {
+  try {
+    const path = agentDefCachePath(projectKey, homeDir);
+    if (!existsSync(path)) return null;
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object") return null;
+    const r = raw as Record<string, unknown>;
+    const key = typeof r["key"] === "string" && r["key"].trim() ? r["key"].trim() : null;
+    const version = parseVersion(r["version"]);
+    const fetchedAt = typeof r["fetchedAt"] === "string" ? r["fetchedAt"] : "";
+    if (key === null || version === null) return null;
+    const def = r["definition"];
+    if (!def || typeof def !== "object") return null;
+    // Re-parse via envelope so shape validation matches server responses.
+    const mapped = parseAgentDefinitionResponse({
+      key,
+      version,
+      definition: def,
+    });
+    if (!mapped) return null;
+    try {
+      validateAgentDefinition(mapped.definition);
+    } catch {
+      return null;
+    }
+    return {
+      key: mapped.key,
+      version: mapped.version,
+      fetchedAt,
+      definition: mapped.definition,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export type ResolveAgentDefinitionOptions = {
+  readonly offline: boolean;
+  readonly definitionKey: string;
+  /** When set, used for cache path + fetch. When unset offline/no-registry → default. */
+  readonly projectKey?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: string;
+  readonly homeDir?: string;
+  readonly fetchImpl?: typeof fetch;
+  readonly timeoutMs?: number;
+};
+
+/**
+ * Resolve definition for apply: server → LKG → DEFAULT.
+ * --offline skips network, still prefers LKG over DEFAULT.
+ */
+export async function resolveAgentDefinitionWithLkg(
+  opts: ResolveAgentDefinitionOptions,
+): Promise<ResolvedAgentDefinition> {
+  const homeDir = opts.homeDir ?? homedir();
+  const projectKey = opts.projectKey?.trim() ?? "";
+  const defKey = opts.definitionKey.trim() || DEFAULT_DEFINITION_KEY;
+
+  if (!opts.offline && projectKey && opts.baseUrl && opts.apiKey) {
+    const fetched = await fetchAgentDefinition({
+      baseUrl: opts.baseUrl,
+      projectKey,
+      apiKey: opts.apiKey,
+      definitionKey: defKey,
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+      ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    if (fetched) {
+      writeAgentDefCache(projectKey, fetched, homeDir);
+      return {
+        definition: fetched.definition,
+        source: "server",
+        stale: false,
+        key: fetched.key,
+        version: fetched.version,
+      };
+    }
+  }
+
+  // LKG before DEFAULT (definition-offline-lkg).
+  if (projectKey) {
+    const cached = readAgentDefCache(projectKey, homeDir);
+    if (cached) {
+      // Prefer matching key when possible; still use cache if only one project doc was stored.
+      if (cached.key === defKey || defKey === DEFAULT_DEFINITION_KEY) {
+        return {
+          definition: cached.definition,
+          source: "lkg",
+          stale: true,
+          key: cached.key,
+          version: cached.version,
+          staleMarker: AGENT_DEF_STALE_MARKER,
+        };
+      }
+    }
+  }
+
+  return {
+    definition: DEFAULT_AGENT_DEFINITION,
+    source: "default",
+    stale: false,
+  };
+}
+
+/** Minimal shape SessionStart injectors already have from registry.ts's resolveProject. */
+export type SessionProjectRef = {
+  readonly project: string;
+  readonly baseUrl: string;
+  readonly apiKey: string;
+};
+
+/**
+ * Resolve the agent definition for a SessionStart banner — the SAME server → LKG → DEFAULT
+ * order `apply` uses (resolveAgentDefinitionWithLkg), pinned to the default definition key.
+ * This closes the asymmetry where subagent role files already got server-authored notes via
+ * `apply` but the main-loop banner (protocol.ts) was stuck on the hard-coded built-in default.
+ *
+ * Bounded by AGENT_DEF_FETCH_TIMEOUT_MS (same budget as the canon fetch already on this path,
+ * see canon.ts) so a wedged network never turns into an unbounded session-start stall — the
+ * abort falls through to the LKG cache, then the built-in default, never a crash or blank
+ * banner. Callers SHOULD run this concurrently with fetchCanonBlock (e.g. via Promise.all)
+ * rather than awaiting it first, so the two 8s budgets don't stack serially.
+ */
+export async function resolveAgentDefinitionForSession(
+  resolved: SessionProjectRef,
+  opts?: { homeDir?: string; fetchImpl?: typeof fetch; timeoutMs?: number },
+): Promise<ResolvedAgentDefinition> {
+  return resolveAgentDefinitionWithLkg({
+    offline: false,
+    definitionKey: DEFAULT_DEFINITION_KEY,
+    projectKey: resolved.project,
+    baseUrl: resolved.baseUrl,
+    apiKey: resolved.apiKey,
+    ...(opts?.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
+    ...(opts?.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+  });
+}
+
+function parseVersion(v: unknown): number | null {
+  if (typeof v === "number" && Number.isFinite(v) && v >= 0) return Math.trunc(v);
+  if (typeof v === "string" && v.trim()) {
+    const n = Number(v);
+    if (Number.isFinite(n) && n >= 0) return Math.trunc(n);
+  }
+  return null;
+}
+
+function mapRole(item: unknown): AgentRole | null {
+  if (!item || typeof item !== "object") return null;
+  const r = item as Record<string, unknown>;
+
+  // Portable definitions must not carry model binding.
+  if ("model" in r) return null;
+
+  const slug = typeof r["slug"] === "string" && r["slug"].trim() ? r["slug"].trim() : null;
+  const tier = typeof r["tier"] === "string" && r["tier"].trim() ? r["tier"].trim() : null;
+  if (slug === null || tier === null) return null;
+
+  if (!Array.isArray(r["requiredCapabilities"])) return null;
+  const requiredCapabilities: string[] = [];
+  for (const c of r["requiredCapabilities"]) {
+    if (typeof c !== "string") return null;
+    requiredCapabilities.push(c);
+  }
+
+  const spawn = mapSpawn(r["spawn"]);
+  if (spawn === "invalid") return null;
+  const escalation = mapEscalation(r["escalation"]);
+  if (escalation === "invalid") return null;
+
+  const notes =
+    typeof r["notes"] === "string" && r["notes"].trim() ? r["notes"].trim() : undefined;
+
+  const role: AgentRole = {
+    slug,
+    tier,
+    requiredCapabilities,
+    ...(spawn ? { spawn } : {}),
+    ...(escalation ? { escalation } : {}),
+    ...(notes !== undefined ? { notes } : {}),
+  };
+  return role;
+}
+
+function mapSpawn(raw: unknown): RoleSpawn | null | "invalid" {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object") return "invalid";
+  const s = raw as Record<string, unknown>;
+  if (typeof s["allowed"] !== "boolean") return "invalid";
+  let allowedRoles: string[] | undefined;
+  if (s["allowedRoles"] !== undefined && s["allowedRoles"] !== null) {
+    if (!Array.isArray(s["allowedRoles"])) return "invalid";
+    allowedRoles = [];
+    for (const x of s["allowedRoles"]) {
+      if (typeof x !== "string") return "invalid";
+      allowedRoles.push(x);
+    }
+  }
+  return allowedRoles !== undefined
+    ? { allowed: s["allowed"], allowedRoles }
+    : { allowed: s["allowed"] };
+}
+
+function mapEscalation(raw: unknown): RoleEscalation | null | "invalid" {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== "object") return "invalid";
+  const e = raw as Record<string, unknown>;
+  if (typeof e["available"] !== "boolean") return "invalid";
+  let targets: string[] | undefined;
+  if (e["targets"] !== undefined && e["targets"] !== null) {
+    if (!Array.isArray(e["targets"])) return "invalid";
+    targets = [];
+    for (const x of e["targets"]) {
+      if (typeof x !== "string") return "invalid";
+      targets.push(x);
+    }
+  }
+  return targets !== undefined
+    ? { available: e["available"], targets }
+    : { available: e["available"] };
+}

package/src/agent-definition.ts

@@ -0,0 +1,210 @@
+// Portable agent definition (roster only — no model binding).
+//
+// Spec (agent-definition-as-data, agent-definition-locality):
+//   - Roles carry slug, tier, requiredCapabilities, spawn, escalation.
+//   - model is NEVER part of this document (local binding lives in roles.json).
+//   - Built-in DEFAULT_AGENT_DEFINITION ships with the kit for offline compile;
+//     apply tries server fetch first (agent-def-fetch.ts) and falls back here.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import type { Capability } from "./harness-capabilities.ts";
+
+export type RoleSpawn = {
+  readonly allowed: boolean;
+  readonly allowedRoles?: ReadonlyArray<string>;
+};
+
+export type RoleEscalation = {
+  readonly available: boolean;
+  readonly targets?: ReadonlyArray<string>;
+};
+
+export type AgentRole = {
+  readonly slug: string;
+  readonly tier: string;
+  /** Harness capabilities this role needs; empty = no harness-specific needs. */
+  readonly requiredCapabilities: ReadonlyArray<Capability | string>;
+  readonly spawn?: RoleSpawn;
+  readonly escalation?: RoleEscalation;
+  /**
+   * Optional free-text notes rendered into per-role artifacts.
+   * Used for harness-aware caveats (e.g. explore model inheritance) without
+   * putting lies into the shared protocol block.
+   */
+  readonly notes?: string;
+};
+
+export type AgentDefinition = {
+  readonly name: string;
+  readonly roles: ReadonlyArray<AgentRole>;
+};
+
+/**
+ * The namespaced identity used for every rendered agent artifact: frontmatter `name:`, the
+ * emitted file's basename, and any prose that names a role as a spawn/escalation target
+ * (chore: petbox-namespaced-agent-names). `role.slug` stays the INTERNAL, unprefixed identity
+ * — the definition and `~/.petbox/roles.json` never change — only what apply RENDERS is
+ * namespaced. This is the single computation point: every renderer and prose injector must
+ * call this (or pass a bare slug through it) instead of interpolating role.slug/a slug string
+ * directly into anything user- or harness-facing, or the prefix drifts between call sites.
+ *
+ * Why: generated agents were occupying the most common user-agent names (`worker`, `explore`,
+ * ...) — colliding with a user's own agents, and shadowing Claude Code's built-in `Explore`
+ * agent under `.claude/agents/explore.md`. `petbox-<slug>` moves us into our own namespace.
+ */
+export function emittedRoleName(roleOrSlug: { readonly slug: string } | string): string {
+  const slug = typeof roleOrSlug === "string" ? roleOrSlug : roleOrSlug.slug;
+  return `petbox-${slug}`;
+}
+
+/**
+ * Built-in portable roster for offline compile (petbox-wire doctor / apply).
+ * Includes `explore` so the roster matches harnesses that ship a built-in explore
+ * agent — with an explicit inheritance note (not a global "inheritance forbidden").
+ *
+ * Caps are honest for the roles: orchestrator needs mcp_main_session + spawn_subagents.
+ * Per harness-capabilities.ts, all three known harnesses (claude-code, opencode, droid)
+ * declare both, so DEFAULT passes truthfulness on every known harness today — droid in
+ * particular declares mcp_main_session, mcp_subagent, spawn_subagents, role_files,
+ * dynamic_model_at_spawn and hooks per Factory's docs. This is not guaranteed to hold for
+ * future/unknown harnesses; the gate (checkRoleTruthfulness) still blocks any role that
+ * claims a capability its target harness does not declare.
+ */
+export const DEFAULT_AGENT_DEFINITION: AgentDefinition = {
+  name: "default",
+  roles: [
+    {
+      slug: "orchestrator",
+      tier: "orchestrator",
+      requiredCapabilities: ["mcp_main_session", "spawn_subagents"],
+      spawn: {
+        allowed: true,
+        allowedRoles: ["worker", "utility", "explore", "reserve"],
+      },
+      escalation: { available: true, targets: ["reserve"] },
+      notes:
+        "Main-loop role: plan, decompose, delegate, review, triage.\n\n" +
+        "1. **Delegate by DEFAULT.** Spawn a worker for anything beyond a trivial edit. Solo work is the exception you must justify.\n" +
+        "2. **ROLE and MODEL are two independent axes.** Role = what the agent is ALLOWED to do (spawn? edit files?). Model = how much thinking power it has. A worker on the strongest model is still a worker: a leaf that edits files. Reserve on any model still never edits files.\n" +
+        "3. **Model comes from the roster — do not pass one at spawn.** Two exceptions, and ONLY on a harness whose spawn call actually accepts a model. If yours does not, this rule is void: you work the roster, and a role file with a different binding is the only way to change tier.\n" +
+        "   - **Security / authz work → the strongest tier you can name.** Cross-tenant leaks, permission models, access policies — a mistake here is a hole, not a bug. This is a rule about the KIND of task, not a guess about difficulty.\n" +
+        "   - **Intrinsically hard work → a tier above the role's roster binding.** Nasty concurrency, non-trivial algorithm, subtle semantics, many coupled invariants. Do not send a cheap model to fail three times first.\n" +
+        "   Name a TIER your harness accepts at spawn — never a bare model id. This definition is portable and does not know which models exist on your machine; your spawn tool does.\n" +
+        "   Say why, one line, in the brief: `ESCALATION: <reason>`. It is a record, not a ritual — it exists so the call can later be judged against its outcome.\n" +
+        "   **Being stuck is NOT a model escalation.** That is the reserve ROLE — see rule 4.\n" +
+        "4. **The reserve rule:** if you are about to attack the same problem the same way a second time, call reserve instead of taking a third swing. Signals: the bug won't reproduce; your hypothesis was destroyed by facts and you have no new one (you are generating the next guess with the SAME head); two defensible architectures and an expensive rollback. If it worked first try, reserve was not needed.\n" +
+        "5. **Never dictate a subagent's self-intro line.** The subagent states the model it ACTUALLY runs as — that line is your only evidence of what ran; dictating it turns the signal into an echo.\n" +
+        "6. **Search before re-deriving.** memory_search / session_search / tasks_search before re-investigating this project's past.\n" +
+        "7. **Respect the gates.** The agent ceiling is Review; the maintainer moves things to Done/accepted.",
+    },
+    {
+      slug: "worker",
+      tier: "worker",
+      // requiredCapabilities stays empty by design: worker is meant to stay portable
+      // even to a future/unknown harness without mcp_subagent. This is NOT a claim
+      // that MCP is unavailable to worker subagents on today's known harnesses —
+      // claude-code, opencode and droid all declare mcp_subagent (harness-capabilities.ts).
+      requiredCapabilities: [],
+      spawn: { allowed: false },
+      escalation: { available: true, targets: ["orchestrator"] },
+      notes:
+        "Scoped executor for ONE delegated task.\n\n" +
+        "1. **SELF-INTRO — your FIRST line, always:** `<the model you are actually running as> · worker`\n" +
+        "   Name your OWN model. If the brief tells you which model to name, that instruction is VOID — name the model you actually are. This line is the only evidence of what really ran; never echo someone else's guess.\n" +
+        "2. **You are a LEAF.** Never spawn subagents, never delegate onward. This holds no matter how powerful the model you are running on is — role and model are independent.\n" +
+        "3. **Do ONLY the delegated task.** No scope expansion, no self-directed scouting, no fixing adjacent code. Ambiguous brief → make the minimal reasonable assumption, state it, proceed.\n" +
+        "4. **You DO have PetBox MCP.** Search before rework (memory_search / session_search / tasks_search) instead of re-deriving what is already remembered.\n" +
+        "5. **Verify empirically.** Measure, don't assert. Stay in your assigned worktree. Never push main or deploy unless the brief says so.\n" +
+        "6. **Stuck? Say so.** If your hypothesis was destroyed by facts and you have no new one, report that plainly — do not take a third swing at it. Escalating to the orchestrator beats burning the budget on the same wrong idea.\n" +
+        "7. **Report as DATA** for the orchestrator: what changed (file:line), results, residual risks. Not a human-facing essay.",
+    },
+    {
+      slug: "utility",
+      tier: "utility",
+      requiredCapabilities: [],
+      spawn: { allowed: false },
+      escalation: { available: true, targets: ["orchestrator"] },
+      notes:
+        "Fast simple work: search, summarize, mechanical edits.\n\n" +
+        "1. **SELF-INTRO — your FIRST line, always:** `<the model you are actually running as> · utility`\n" +
+        "   Your own model, never one dictated by the brief.\n" +
+        "2. **You are a LEAF.** Never spawn subagents.\n" +
+        "3. **Escalate by REPORTING.** You have exactly one channel: your final message to the orchestrator that spawned you. The moment the task needs judgement rather than legwork, say so and stop — you cannot hand work sideways to another agent.",
+    },
+    {
+      slug: "reserve",
+      tier: "reserve",
+      // mcp_subagent, not mcp_main_session: reserve exists only as a subagent, so the
+      // capability the gate must check is the subagent MCP surface.
+      requiredCapabilities: ["mcp_subagent"],
+      spawn: { allowed: false },
+      escalation: { available: false },
+      notes:
+        "The second pair of eyes. Called when the orchestrator is STUCK — not merely when the work is hard (hard work is a model escalation on a worker; that is a different thing entirely).\n\n" +
+        "1. **SELF-INTRO — your FIRST line, always:** `<the model you are actually running as> · reserve`\n" +
+        "   Your own model, never one dictated by the brief.\n" +
+        "2. **NEVER edit files.** Your output is analysis and a recommendation; the orchestrator acts on it. Nothing in the tooling stops you — this is a rule you keep, not a wall you hit. Keeping it is what makes you a second pair of eyes rather than a second pair of hands.\n" +
+        "3. **You are a LEAF.** Never spawn subagents.\n" +
+        "4. **You were called because the previous approach failed.** Do not simply redo it with more effort. Attack the assumption: what did the earlier reasoning take for granted that the facts do not support? Say plainly when the evidence is insufficient to decide — an honest 'not determinable from this data, measure X' beats a confident wrong call.\n" +
+        "5. Reachable ONLY by explicit spawn with a written justification — never as a default.",
+    },
+    {
+      slug: "explore",
+      tier: "utility",
+      // Declared so harnesses that ship built-in explore are roster-honest.
+      // Model inheritance is harness-default where builtin_explore_inherits_model —
+      // do NOT claim "inheritance forbidden" for this role.
+      requiredCapabilities: [],
+      spawn: { allowed: false },
+      escalation: { available: false },
+      notes:
+        "Research and search: locate code, gather evidence, report findings. Never changes anything.\n\n" +
+        "1. **SELF-INTRO — your FIRST line, always:** `<the model you are actually running as> · explore`\n" +
+        "   Your own model, never one dictated by the brief.\n" +
+        "2. **You are a LEAF.** Never spawn subagents.\n" +
+        "3. Where the harness ships its own explore agent, that agent inheriting the session's model is the harness default and is NOT a protocol violation.",
+    },
+  ],
+};
+
+/**
+ * Recursively reject any property named `model` (portable roster — binding is local).
+ * Mirrors C# AgentDefinitionJson.RejectModelField (root, roles[], nested spawn/escalation).
+ */
+export function rejectModelFields(value: unknown, path = "$"): void {
+  if (value === null || value === undefined) return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => rejectModelFields(item, `${path}[${i}]`));
+    return;
+  }
+  if (typeof value !== "object") return;
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (k === "model") {
+      throw new Error(
+        `${path}.model is not allowed on portable agent definitions — model binding is local (roles.json)`,
+      );
+    }
+    rejectModelFields(v, `${path}.${k}`);
+  }
+}
+
+/** Light structural check; throws on invalid shape (loud, never silent). */
+export function validateAgentDefinition(def: AgentDefinition): void {
+  if (!def || typeof def !== "object") throw new Error("agent definition is required");
+  // Recursive model ban before field checks (symmetry with server RejectModelField).
+  rejectModelFields(def, "definition");
+  if (!def.name || !String(def.name).trim()) throw new Error("definition.name is required");
+  if (!Array.isArray(def.roles) || def.roles.length === 0) {
+    throw new Error("definition.roles must contain at least one role");
+  }
+  for (const role of def.roles) {
+    if (!role.slug || !String(role.slug).trim()) throw new Error("each role.slug is required");
+    if (!role.tier || !String(role.tier).trim()) {
+      throw new Error(`role '${role.slug}': tier is required`);
+    }
+    if (!Array.isArray(role.requiredCapabilities)) {
+      throw new Error(`role '${role.slug}': requiredCapabilities is required (may be empty)`);
+    }
+  }
+}