agent-relay-server 0.20.0 → 0.22.0

package/runner/src/adapter.ts

@@ -159,7 +159,7 @@ export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: ke
   return config.agentProfile?.relay?.[feature] !== false;
 }
 
-export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_spawn_agent, and relay_shutdown_agent. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
+export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present you can stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 

package/scripts/install-bin-shim.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, chmodSync } = require("node:fs");
+const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, chmodSync, unlinkSync } = require("node:fs");
 const { homedir } = require("node:os");
 const { delimiter, join, relative } = require("node:path");
 
@@ -31,12 +31,24 @@ function pathContains(dir, env) {
   return String(env.PATH || "").split(delimiter).some((entry) => entry === dir);
 }
 
+function pathEntries(env) {
+  return String(env.PATH || "").split(delimiter).filter(Boolean);
+}
+
 function chooseBinDir(env, home) {
   if (env.AGENT_RELAY_USER_BIN_DIR) return env.AGENT_RELAY_USER_BIN_DIR;
   const localBin = join(home, ".local", "bin");
   const bunBin = join(home, ".bun", "bin");
-  if (pathContains(localBin, env)) return localBin;
-  if (pathContains(bunBin, env)) return bunBin;
+  const candidates = new Set([localBin, bunBin]);
+  const entries = pathEntries(env);
+  for (const entry of entries) {
+    if (!candidates.has(entry)) continue;
+    const shimPath = join(entry, "agent-relay");
+    if (existsSync(shimPath) && canOverwriteShim(shimPath)) return entry;
+  }
+  for (const entry of entries) {
+    if (candidates.has(entry)) return entry;
+  }
   return localBin;
 }
 
@@ -82,6 +94,7 @@ function installShim(env = process.env) {
   }
 
   mkdirSync(binDir, { recursive: true });
+  if (existsSync(shimPath) && lstatSync(shimPath).isSymbolicLink()) unlinkSync(shimPath);
   writeFileSync(shimPath, renderShim(cliPath), "utf8");
   chmodSync(shimPath, 0o755);
 

package/src/agent-ref.ts

@@ -0,0 +1,217 @@
+// Shared agent-reference resolution. ONE home for "given a string an agent typed,
+// which agent(s) does it mean?" — so messaging (send/reply) and pairing can never
+// drift apart again (they used to: messaging matched exact id only, pairing had a
+// rich matcher). See #222.
+//
+// A reference can be:
+//   - an explicit selector: id:  label:  name:  tag:  cap:/capability:  machine:  rig:
+//   - a bare exact match on id, label, name, a tag, a capability, or rig
+//   - a unique id *segment* (the "number part" of a session id), e.g. `c14bd37f`
+//
+// Resolution prefers ONLINE agents so a dead twin can't manufacture ambiguity, and
+// never silently picks among several — it reports candidates instead.
+
+import { STALE_TTL_MS } from "./config";
+import type { AgentCard } from "./types";
+
+export interface ResolveOptions {
+  /** Exclude this agent id from matches (e.g. the requester, when pairing). */
+  excludeId?: string;
+  /** Clock injection for tests. */
+  now?: number;
+}
+
+export type ResolveResult =
+  | { status: "resolved"; agent: AgentCard }
+  | { status: "ambiguous"; candidates: AgentCard[] }
+  | { status: "not_found"; offlineMatches: AgentCard[] };
+
+/** Canonical "is this agent reachable right now" predicate. Single source of truth. */
+export function isAgentOnline(agent: AgentCard, now: number = Date.now()): boolean {
+  return agent.status !== "offline" && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+interface Selector {
+  field: "id" | "label" | "name" | "tag" | "capability" | "machine" | "rig";
+  value: string;
+}
+
+const SELECTOR_PREFIXES: Array<[string, Selector["field"]]> = [
+  ["id:", "id"],
+  ["label:", "label"],
+  ["name:", "name"],
+  ["tag:", "tag"],
+  ["capability:", "capability"],
+  ["cap:", "capability"],
+  ["machine:", "machine"],
+  ["rig:", "rig"],
+];
+
+function parseSelector(ref: string): Selector | null {
+  for (const [prefix, field] of SELECTOR_PREFIXES) {
+    if (ref.startsWith(prefix)) return { field, value: ref.slice(prefix.length).trim() };
+  }
+  return null;
+}
+
+function matchesSelector(agent: AgentCard, selector: Selector): boolean {
+  switch (selector.field) {
+    case "id": return agent.id === selector.value;
+    case "label": return agent.label === selector.value;
+    case "name": return agent.name === selector.value;
+    case "tag": return agent.tags.includes(selector.value);
+    case "capability": return agent.capabilities.includes(selector.value);
+    case "machine": return agent.machine === selector.value;
+    case "rig": return agent.rig === selector.value;
+  }
+}
+
+function matchesExact(agent: AgentCard, ref: string): boolean {
+  return (
+    agent.id === ref ||
+    agent.label === ref ||
+    agent.name === ref ||
+    agent.rig === ref ||
+    agent.tags.includes(ref) ||
+    agent.capabilities.includes(ref)
+  );
+}
+
+// A reference matches an id "segment" when it equals — or is a prefix of — one of the
+// id's delimiter-separated tokens. `session-1780922734580/c14bd37f-fe5d` tokenizes to
+// [session, 1780922734580, c14bd37f, fe5d], so `c14bd37f`, `1780`, or `fe5d` all match.
+function idMatchesSegment(id: string, ref: string): boolean {
+  if (!ref) return false;
+  const tokens = id.split(/[-/_:.]+/).filter(Boolean);
+  return tokens.some((token) => token === ref || token.startsWith(ref));
+}
+
+/**
+ * All agents matching `ref`, using tiered logic: explicit selector wins; otherwise an
+ * exact match (id/label/name/tag/cap/rig) is preferred, and only if there are NO exact
+ * matches do we fall back to id-segment matching. No online filtering, no uniqueness —
+ * the caller decides what to do with multiplicity.
+ */
+export function matchAgents(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): AgentCard[] {
+  const trimmed = ref.trim();
+  if (!trimmed) return [];
+  const pool = opts.excludeId ? agents.filter((a) => a.id !== opts.excludeId) : agents;
+
+  const selector = parseSelector(trimmed);
+  if (selector) return selector.value ? pool.filter((a) => matchesSelector(a, selector)) : [];
+
+  const exact = pool.filter((a) => matchesExact(a, trimmed));
+  if (exact.length) return exact;
+  return pool.filter((a) => idMatchesSegment(a.id, trimmed));
+}
+
+/**
+ * Resolve `ref` to a SINGLE agent. Prefers online matches; reports ambiguity rather
+ * than guessing. On not_found, returns any offline matches so callers can say "exists
+ * but offline" instead of "unknown".
+ */
+export function resolveAgentRef(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): ResolveResult {
+  const now = opts.now ?? Date.now();
+  const matches = matchAgents(ref, agents, opts);
+  if (matches.length === 0) return { status: "not_found", offlineMatches: [] };
+
+  const online = matches.filter((a) => isAgentOnline(a, now));
+  if (online.length === 1) return { status: "resolved", agent: online[0]! };
+  if (online.length > 1) return { status: "ambiguous", candidates: online };
+  return { status: "not_found", offlineMatches: matches };
+}
+
+// --- messaging send planning -------------------------------------------------
+
+export interface DeliveryReceipt {
+  /** A live recipient exists right now. */
+  delivered: boolean;
+  /** Whether the sender should expect a reply (false ⇒ don't block waiting). */
+  expectReply: boolean;
+  /** Online recipient agent ids this message will reach. */
+  recipients: string[];
+  /** Durable fan-out target with no online members — held until one appears. */
+  queued?: boolean;
+  /** Human reason when not delivered. */
+  reason?: string;
+}
+
+export type SendPlan =
+  // resolved/fan-out/passthrough carry the (possibly rewritten) canonical `to`
+  | { kind: "direct" | "fanout" | "passthrough"; to: string; receipt: DeliveryReceipt }
+  | { kind: "not_found"; message: string }
+  | { kind: "ambiguous"; message: string; candidates: AgentCard[] };
+
+const FANOUT_PREFIXES = ["tag:", "cap:", "capability:", "label:"];
+const PASSTHROUGH_PREFIXES = ["policy:", "orchestrator:", "pool:"];
+const RESERVED_TARGETS = new Set(["user", "system"]);
+
+function isPseudoAgent(agent: AgentCard): boolean {
+  return agent.id !== "user" && agent.id !== "system" && agent.kind !== "channel" && (agent.meta?.kind as unknown) !== "channel";
+}
+
+function describeAgent(agent: AgentCard): string {
+  return agent.label ? `${agent.id} (${agent.label})` : agent.id;
+}
+
+function ambiguousMessage(ref: string, candidates: AgentCard[]): string {
+  const list = candidates.slice(0, 8).map(describeAgent).join(", ");
+  const more = candidates.length > 8 ? `, +${candidates.length - 8} more` : "";
+  return `agent reference "${ref}" is ambiguous — matches ${candidates.length}: ${list}${more}. Use a full id, label, or a fan-out selector (tag:/cap:/label:).`;
+}
+
+function notFoundMessage(ref: string, agents: AgentCard[]): string {
+  const needle = ref.toLowerCase();
+  const near = agents
+    .filter((a) => isPseudoAgent(a) && (a.id.toLowerCase().includes(needle) || a.label?.toLowerCase().includes(needle)))
+    .slice(0, 3)
+    .map(describeAgent);
+  const hint = near.length ? ` Did you mean: ${near.join(", ")}?` : "";
+  return `no agent matches "${ref}".${hint}`;
+}
+
+/**
+ * Classify a message target and produce a synchronous delivery receipt. Direct targets
+ * are resolved to a canonical agent id (so poll-time matching works) and report whether
+ * a live recipient exists; fan-out targets report how many online members they reach;
+ * reserved/policy targets pass through unchanged.
+ */
+export function planSend(to: string, agents: AgentCard[], now: number = Date.now()): SendPlan {
+  const target = to.trim();
+
+  if (target === "broadcast") {
+    const recipients = agents.filter((a) => isPseudoAgent(a) && isAgentOnline(a, now)).map((a) => a.id);
+    return { kind: "fanout", to: target, receipt: fanoutReceipt(recipients) };
+  }
+  if (FANOUT_PREFIXES.some((p) => target.startsWith(p))) {
+    const recipients = matchAgents(target.replace(/^cap:/, "capability:"), agents)
+      .filter((a) => isAgentOnline(a, now)).map((a) => a.id);
+    return { kind: "fanout", to: target, receipt: fanoutReceipt(recipients) };
+  }
+  if (RESERVED_TARGETS.has(target) || PASSTHROUGH_PREFIXES.some((p) => target.startsWith(p))) {
+    return { kind: "passthrough", to: target, receipt: { delivered: true, expectReply: true, recipients: [target] } };
+  }
+
+  // Direct single-agent reference.
+  const resolved = resolveAgentRef(target, agents, { now });
+  if (resolved.status === "resolved") {
+    return { kind: "direct", to: resolved.agent.id, receipt: { delivered: true, expectReply: true, recipients: [resolved.agent.id] } };
+  }
+  if (resolved.status === "ambiguous") {
+    return { kind: "ambiguous", message: ambiguousMessage(target, resolved.candidates), candidates: resolved.candidates };
+  }
+  // not_found online — maybe it exists but is offline.
+  const offline = resolved.offlineMatches;
+  if (offline.length === 1) {
+    return { kind: "direct", to: offline[0]!.id, receipt: { delivered: false, expectReply: false, recipients: [], reason: "recipient offline" } };
+  }
+  if (offline.length > 1) {
+    return { kind: "ambiguous", message: ambiguousMessage(target, offline), candidates: offline };
+  }
+  return { kind: "not_found", message: notFoundMessage(target, agents) };
+}
+
+function fanoutReceipt(recipients: string[]): DeliveryReceipt {
+  if (recipients.length === 0) return { delivered: false, expectReply: false, recipients: [], queued: true, reason: "no online members — queued" };
+  return { delivered: true, expectReply: true, recipients };
+}

package/src/automations.ts

@@ -14,7 +14,7 @@ import {
 } from "./db";
 import { createCommand } from "./commands-db";
 import { cleanEnum, cleanString, cleanStringArray, optionalEnum } from "./validation";
-import { getAgentProfile, getSpawnPolicy } from "./config-store";
+import { getAgentProfile, getSpawnPolicy, spawnGrantForProfile } from "./config-store";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
 import { errMessage, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
@@ -511,6 +511,7 @@ function dispatchOnDemandAutomation(
 ): AutomationDispatchResult {
   if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not have provider available: ${policy.provider}`);
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const grant = spawnGrantForProfile(policy.profile);
   const label = automationRunLabel(automation.id, run.id);
   const command = createCommand({
     type: "agent.spawn",
@@ -535,6 +536,8 @@ function dispatchOnDemandAutomation(
         provider: policy.provider,
         label,
         createdBy: "automation",
+        canSpawn: grant.canSpawn,
+        maxSpawnedAgents: grant.maxSpawnedAgents,
       }),
     }),
   });

package/src/cli.ts

@@ -48,6 +48,9 @@ import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sd
 import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "./workspace-phase";
+
+export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
 
 const HELP = `
 agent-relay ${VERSION}
@@ -68,7 +71,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]
@@ -235,9 +238,17 @@ Isolated workspaces
   Relay does. Just commit your work in the worktree, then:
     agent-relay workspace ready    Hand off: Relay rebases onto the latest base,
                                    lands your work, and pushes.
-    agent-relay workspace status   Show your workspace's branch, base, status.
+    agent-relay workspace status   Show your workspace's state + what to do next.
+    agent-relay workspace status --wait
+                                   Block until your branch lands (returns the
+                                   moment the auto-merge completes).
+  After "ready", status is "review_requested" — this is NORMAL, not an
+  escalation. Relay auto-merges clean rebases ~every 2 min; a steward agent is
+  spawned only if it can't land deterministically, so no steward = healthy. On
+  landing you move onto a fresh rebased branch (name gains a "--N" suffix).
   The base branch will move as other agents land in parallel — that is normal,
-  let the merge handle it. Never push your branch yourself; it is local-only.
+  let the merge handle it. Never push, merge, resolve conflicts, or touch the
+  main checkout yourself; it is local-only and Relay (and the steward) own that.
   If typecheck/build fails on a missing module (a dep added to the base after
   your worktree was created), do NOT run a clean install — it mutates the shared
   node_modules. Instead refresh your worktree's deps in isolation:
@@ -1527,14 +1538,31 @@ function currentWorkspaceId(): string | undefined {
   }
 }
 
-function formatWorkspaceStatus(ws: any): string {
+function formatWorkspaceStatus(ws: any, extra?: { guidance?: WorkspacePhaseView; landed?: string | null }): string {
+  // Render the directive projection so the agent gets "what does this mean / what
+  // do I do next" inline, not a bare enum it has to decode (#235). Computed
+  // client-side from the record (the projection is pure) unless the wait response
+  // already carried it.
+  const guidance = extra?.guidance ?? describeWorkspacePhase(ws);
   const lines = [
     `Workspace ${ws.id}`,
-    `  status:   ${ws.status}`,
+    `  status:   ${ws.status}  (${guidance.phase}${guidance.actionNeeded ? "" : " — no action needed"})`,
     `  branch:   ${ws.branch ?? "(none)"}`,
     `  base:     ${ws.baseRef ?? "(none)"}`,
     `  worktree: ${ws.worktreePath ?? "(none)"}`,
+    "",
+    `  ${guidance.headline}`,
+    `  ${guidance.hint}`,
   ];
+  if (guidance.blockers.length) {
+    lines.push("", "  Blockers:");
+    for (const b of guidance.blockers) lines.push(`    - ${b}`);
+  }
+  if (guidance.nextActions.length) {
+    lines.push("", "  Next:");
+    for (const a of guidance.nextActions) lines.push(`    - ${a.cli ?? a.tool} — ${a.when}`);
+  }
+  if (extra?.landed) lines.push("", `  ${extra.landed}`);
   return lines.join("\n");
 }
 
@@ -1577,8 +1605,12 @@ function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolea
 async function handleWorkspaceCommand(args: string[]): Promise<void> {
   const action = args[0];
   const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
+  if (action === "--help" || action === "-h" || action === "help") {
+    console.log(WORKSPACE_USAGE);
+    return;
+  }
   if (!action || !valid.has(action)) {
-    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]");
+    throw new Error(WORKSPACE_USAGE);
   }
 
   let id = currentWorkspaceId();
@@ -1588,6 +1620,8 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   let execute = false;
   let check = false;
   let json = false;
+  let wait = false;
+  let timeoutSeconds: number | undefined;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--id" && i + 1 < args.length) id = args[++i];
@@ -1597,6 +1631,12 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     else if (arg === "--execute") execute = true;
     else if (arg === "--check") check = true;
     else if (arg === "--refresh") check = false; // explicit no-op default for clarity
+    else if (arg === "--wait") wait = true;
+    else if (arg === "--timeout" && i + 1 < args.length) {
+      const parsed = Number.parseInt(args[++i]!, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--timeout must be a positive number of seconds");
+      timeoutSeconds = parsed;
+    }
     else if (arg === "--json") json = true;
     else throw new Error(`Unknown workspace option "${arg}".`);
   }
@@ -1615,6 +1655,20 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   if (!id) throw new Error("No current workspace detected (AGENT_RELAY_WORKSPACE_JSON unset). Pass --id WORKSPACE_ID — only isolated-workspace agents have one.");
 
   if (action === "status") {
+    // --wait long-polls via the action endpoint (server blocks until the status
+    // changes — the blessed way to wait for an auto-merge to land, #235), and the
+    // response carries the directive projection + land receipt. Plain status is a
+    // bare GET; the projection is computed client-side for rendering.
+    if (wait) {
+      const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, {
+        action: "status",
+        wait: true,
+        ...(timeoutSeconds ? { timeoutSeconds } : {}),
+      }) as { workspace?: any; guidance?: WorkspacePhaseView; landed?: string | null };
+      if (json) { console.log(JSON.stringify(res, null, 2)); return; }
+      console.log(formatWorkspaceStatus(res.workspace ?? res, { guidance: res.guidance, landed: res.landed }));
+      return;
+    }
     const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`);
     if (json) console.log(JSON.stringify(ws, null, 2));
     else console.log(formatWorkspaceStatus(ws));
@@ -1663,9 +1717,15 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (action === "ready") {
+    // Print the whole contract up front so the agent isn't left decoding status
+    // enums over the next minutes (#235). `result.workspace` is the post-ready row.
+    const ws = (result as { workspace?: any }).workspace ?? { status: "review_requested" };
+    console.log(`Workspace ${id} marked ready.\n\n${readyContract(ws)}`);
+    return;
+  }
   console.log(
-    action === "ready" ? `Workspace ${id} marked ready — Relay will rebase onto the latest base, land, and push.`
-    : action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
+    action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
     : action === "release" ? `Workspace ${id} claim released.`
     : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
   );

package/src/config-store.ts

@@ -173,6 +173,20 @@ function cleanJsonRecord(value: unknown, field: string): Record<string, unknown>
   return value;
 }
 
+function cleanAgentProfileProviderOptions(value: unknown): Record<string, unknown> {
+  const options = cleanJsonRecord(value, "providerOptions");
+  if (options.codex === undefined || options.codex === null) return options;
+  if (!isRecord(options.codex)) throw new ValidationError("providerOptions.codex must be an object");
+  const codex = { ...options.codex };
+  if ("toolOutputTokenLimit" in codex && codex.toolOutputTokenLimit !== null) {
+    codex.toolOutputTokenLimit = cleanNumber(codex.toolOutputTokenLimit, "providerOptions.codex.toolOutputTokenLimit", {
+      min: 1_000,
+      max: 200_000,
+    });
+  }
+  return { ...options, codex };
+}
+
 function cleanBoolean(value: unknown, field: string): boolean {
   if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
   return value;
@@ -221,6 +235,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
     },
     env: input.env ?? {},
     providerOptions: input.providerOptions ?? {},
+    ...(input.maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents: input.maxSpawnedAgents }),
   };
 }
 
@@ -295,7 +310,10 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
         : cleanEnum(permissions.filesystem, "permissions.filesystem", VALID_PROFILE_FILESYSTEM_SCOPES),
     },
     env: cleanStringRecord(value.env, "env"),
-    providerOptions: cleanJsonRecord(value.providerOptions, "providerOptions"),
+    providerOptions: cleanAgentProfileProviderOptions(value.providerOptions),
+    maxSpawnedAgents: value.maxSpawnedAgents === undefined || value.maxSpawnedAgents === null
+      ? undefined
+      : cleanNumber(value.maxSpawnedAgents, "maxSpawnedAgents", { min: 0, max: 100 }),
   });
 }
 
@@ -657,6 +675,22 @@ export function getAgentProfile(name: string): ConfigEntry<AgentProfile> | null
   return getConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE, name);
 }
 
+/**
+ * Resolve the spawn grant for a named profile (#221). `canSpawn` gates whether the agent's
+ * runtime token gets the `command:spawn`/`command:shutdown` scope; `maxSpawnedAgents` is the
+ * live-children quota baked into the token. Unknown/absent profile or `0` → no spawn (strict
+ * default). Callers pass `agentInitiated: true` for agent-requested spawns to force the child
+ * to NEVER be spawn-capable (no grandchildren), regardless of the child's profile.
+ */
+export function spawnGrantForProfile(
+  profileName: string | undefined,
+  agentInitiated = false,
+): { canSpawn: boolean; maxSpawnedAgents: number } {
+  if (agentInitiated) return { canSpawn: false, maxSpawnedAgents: 0 };
+  const n = profileName ? (getAgentProfile(profileName)?.value.maxSpawnedAgents ?? 0) : 0;
+  return { canSpawn: n > 0, maxSpawnedAgents: n };
+}
+
 export function listAgentProfiles(): ConfigEntry<AgentProfile>[] {
   const custom = listConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE);
   return [

package/src/context-router.ts

@@ -1,4 +1,5 @@
 import type { AgentCard } from "./types";
+import { matchAgents } from "./agent-ref";
 
 export interface RouteAdvisorInput {
   text?: string;
@@ -39,7 +40,7 @@ function routeEligible(agent: AgentCard, input: RouteAdvisorInput, maxUtilizatio
   if (agent.id === "user" || agent.id === "system" || agent.kind === "channel") return false;
   if (agent.meta?.kind === "channel" || agent.tags.includes("channel")) return false;
   if (agent.status === "offline" || agent.status === "stale") return false;
-  if (input.target && !agentMatchesTarget(agent, input.target)) return false;
+  if (input.target && !matchesRouteTarget(agent, input.target)) return false;
   if (input.capabilities?.length && !input.capabilities.every((cap) => agent.capabilities.includes(cap))) return false;
   if (input.tags?.length && !input.tags.every((tag) => agent.tags.includes(tag))) return false;
   if (maxUtilization !== undefined && (agent.context?.utilization ?? 0) > maxUtilization) return false;
@@ -67,11 +68,10 @@ function scoreAgent(agent: AgentCard, input: RouteAdvisorInput, terms: Set<strin
   };
 }
 
-function agentMatchesTarget(agent: AgentCard, target: string): boolean {
-  if (target === "broadcast") return true;
-  if (target.startsWith("tag:")) return agent.tags.includes(target.slice(4));
-  if (target.startsWith("cap:")) return agent.capabilities.includes(target.slice(4));
-  return agent.id === target || agent.label === target;
+// Broadcast matches every candidate; everything else delegates to the shared resolver
+// (src/agent-ref.ts) so routing accepts the same ref forms as messaging and pairing.
+function matchesRouteTarget(agent: AgentCard, target: string): boolean {
+  return target === "broadcast" || matchAgents(target, [agent]).length > 0;
 }
 
 function termsFromText(text: string | undefined): Set<string> {
@@ -100,7 +100,7 @@ function affinityScore(agent: AgentCard, input: RouteAdvisorInput): number {
   }
   if (input.target) {
     possible++;
-    score += agentMatchesTarget(agent, input.target) ? 1 : 0;
+    score += matchesRouteTarget(agent, input.target) ? 1 : 0;
   }
   return possible === 0 ? 0.5 : score / possible;
 }