agent-relay-server 0.89.2 → 0.91.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.89.2",
+    "version": "0.91.0",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.89.2",
+  "version": "0.91.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.68",
+    "agent-relay-sdk": "0.2.70",
     "ajv": "^8.20.0"
   },
   "scripts": {

package/runner/src/adapter.ts

@@ -100,6 +100,10 @@ export interface RunnerSpawnConfig {
   // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
   // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
   relayMcpEndpoint?: string;
+  // #672: the shared host-listener URL the per-agent `callmux bridge` connects to, when the
+  // profile/spawn opted into `agentProfile.sharedMcp`. Resolved runner-side (env → default);
+  // the launch assembler only emits the bridge entry when sharedMcp is on.
+  sharedMcpUrl?: string;
   monitor?: {
     deliver(messages: Message[]): Promise<number[]>;
   };

package/src/config-store.ts

@@ -5,6 +5,8 @@ import { DEFAULT_QUOTA_THRESHOLD_CONFIG, validateQuotaThresholdConfig } from "./
 import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-resume-config";
 import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
 import { PROJECT_INSTRUCTION_POLICY_NAMES } from "./project-instructions";
+import { PROJECT_MCP_POLICY_NAMES } from "./project-mcp";
+import { SHARED_MCP_POLICY_NAMES } from "./shared-mcp";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES } from "agent-relay-sdk"; import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import type {
@@ -225,6 +227,28 @@ function cleanAgentProfileProjectInstructions(value: unknown): AgentProfile["pro
   return { policy: cleanEnum(policy, "projectInstructions.policy", PROJECT_INSTRUCTION_POLICY_NAMES) as NonNullable<AgentProfile["projectInstructions"]>["policy"] };
 }
 
+// #667 — project `.mcp.json` projection profile default. Mirrors projectInstructions:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileProjectMcp(value: unknown): AgentProfile["projectMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("projectMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "projectMcp.policy", PROJECT_MCP_POLICY_NAMES) as NonNullable<AgentProfile["projectMcp"]>["policy"] };
+}
+
+// #672 — shared host-listener MCP projection profile default. Mirrors projectMcp:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileSharedMcp(value: unknown): AgentProfile["sharedMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("sharedMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "sharedMcp.policy", SHARED_MCP_POLICY_NAMES) as NonNullable<AgentProfile["sharedMcp"]>["policy"] };
+}
+
 function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Partial<AgentProfile>): AgentProfile {
   const isolated = input.base !== "host";
   // "vanilla" (#552) additionally suppresses the REPO instruction cascade
@@ -245,6 +269,8 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
       globalInstructions: input.instructions?.globalInstructions ?? (isolated ? "ignore" : "allow"),
     },
     ...(input.projectInstructions ? { projectInstructions: input.projectInstructions } : {}),
+    ...(input.projectMcp ? { projectMcp: input.projectMcp } : {}),
+    ...(input.sharedMcp ? { sharedMcp: input.sharedMcp } : {}),
     relay: {
       context: input.relay?.context ?? !isolated,
       skills: input.relay?.skills ?? !isolated,
@@ -319,6 +345,8 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
         : cleanEnum(instructions.globalInstructions, "instructions.globalInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
     },
     projectInstructions: cleanAgentProfileProjectInstructions(value.projectInstructions),
+    projectMcp: cleanAgentProfileProjectMcp(value.projectMcp),
+    sharedMcp: cleanAgentProfileSharedMcp(value.sharedMcp),
     relay: {
       context: relay.context === undefined ? defaults.relay.context : cleanBoolean(relay.context, "relay.context"),
       skills: relay.skills === undefined ? defaults.relay.skills : cleanBoolean(relay.skills, "relay.skills"),

package/src/mcp/tools-spawn.ts

@@ -4,6 +4,8 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../servic
 import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
+import { parseProjectMcp, PROJECT_MCP_POLICY_NAMES } from "../project-mcp";
+import { parseSharedMcp, SHARED_MCP_POLICY_NAMES } from "../shared-mcp";
 import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } from "../db";
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
@@ -34,6 +36,8 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         expectReply: { type: "boolean", description: "Legacy compatibility flag. Spawned workers now report up automatically: each turn-final response is routed to the spawner by lineage, without a reply obligation or idle nag." },
         systemPromptAppend: { type: "string" },
         projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
+        projectMcp: { type: "object", description: "#667 — project `.mcp.json` MCP projection (default OFF). When set, the worker gets the MCP servers committed in the spawn cwd's `.mcp.json` (e.g. an app's playtest/manuscript servers), injected by relay through the controlled `--mcp-config` path that survives `--strict-mcp-config` — sourced from the project, not ambient host MCP, and without triggering Claude's project-trust modal. `policy: \"all\"` (the default) injects every declared server. Omit to keep current host-only behavior.", properties: { policy: { type: "string", enum: PROJECT_MCP_POLICY_NAMES } }, additionalProperties: false },
+        sharedMcp: { type: "object", description: "#672 — shared host-listener MCP (default OFF). When set, the worker's NON-IDENTITY MCP (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via a per-agent `callmux bridge --cwd \"$WORKTREE\"`, so the MCP session survives a listener/downstream restart and each isolated worktree keeps session-cwd isolation. Rides the controlled `--mcp-config` path (composes with `--strict-mcp-config`). The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener. `policy: \"all\"` (the default) routes the listener's full non-identity set. Omit to keep current per-agent injection.", properties: { policy: { type: "string", enum: SHARED_MCP_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: `Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use \`${DEFAULT_SPAWN_PROFILE_NAME}\`.` },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -108,6 +112,8 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
     projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
+    projectMcp: parseProjectMcp(args.projectMcp, (m) => new ValidationError(m)),
+    sharedMcp: parseSharedMcp(args.sharedMcp, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),

package/src/project-mcp.ts

@@ -0,0 +1,52 @@
+// Project `.mcp.json` MCP projection (#667) — the relay-owned, OPT-IN path that hands a
+// spawned worker its spawn-cwd's COMMITTED `.mcp.json` servers, sourced from the PROJECT
+// (in-repo, trusted) rather than ambient host MCP. Sibling seam to project-instructions
+// (#409): same opt-in + projection shape, default OFF.
+//
+// PROVENANCE, NOT TYPE: "vanilla/zero-host-bleed" means relay OWNS provisioning and sources
+// it from the project, never the host. A repo's `.mcp.json` is part of the code the agent
+// works in; it should travel with the repo like it does for a human who clones it.
+//
+// DIVISION OF LABOR: relay only carries the OPT-IN DECISION (this module + the spawn
+// param/profile field). The actual file read + `--mcp-config` injection happens RUNNER-side
+// (launch-assembly.ts → resolveProjectMcpServers), which is the filesystem authority for the
+// spawn cwd (relay may run on a different host than the orchestrator). It composes with #662
+// `--strict-mcp-config` — the controlled inject path strict PRESERVES — and deliberately does
+// NOT enable Claude's ambient project-`.mcp.json` discovery, whose trust modal wedges headless
+// agents (the very reason #662 added strict to all managed launches).
+
+export const PROJECT_MCP_POLICY_NAMES = ["all"] as const;
+export type ProjectMcpPolicyName = (typeof PROJECT_MCP_POLICY_NAMES)[number];
+
+/** Per-spawn projection request. Presence (a non-undefined value) means "inject project
+ * MCP"; absence means OFF. `policy` selects the server set (`all` = every declared server;
+ * the sole value today). */
+export interface ProjectMcpPolicy {
+  policy?: ProjectMcpPolicyName;
+}
+
+/**
+ * Parse a spawn-transport's `projectMcp` wire value into the normalized policy (or
+ * undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift. Mirrors
+ * parseProjectInstructions exactly:
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseProjectMcp(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectMcpPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectMcp must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !PROJECT_MCP_POLICY_NAMES.includes(policy as ProjectMcpPolicyName)) {
+    throw onInvalid(`projectMcp.policy must be one of: ${PROJECT_MCP_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectMcpPolicyName };
+}

package/src/routes/agents-spawn.ts

@@ -7,6 +7,8 @@ import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optional
 import { registerAgent } from "../services/register-agent";
 import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
 import { parseProjectInstructions } from "../project-instructions";
+import { parseProjectMcp } from "../project-mcp";
+import { parseSharedMcp } from "../shared-mcp";
 import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
@@ -121,6 +123,8 @@ export const postAgentSpawn: Handler = async (req) => {
       prompt: cleanString(parsed.body.prompt, "prompt", { max: 16000 }),
       systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
       projectInstructions: parseProjectInstructions(parsed.body.projectInstructions, (m) => new ValidationError(m)),
+      projectMcp: parseProjectMcp(parsed.body.projectMcp, (m) => new ValidationError(m)),
+      sharedMcp: parseSharedMcp(parsed.body.sharedMcp, (m) => new ValidationError(m)),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),

package/src/routes/provider-quotas.ts

@@ -1,7 +1,8 @@
 import { isRecord } from "agent-relay-sdk";
-import { acquireProviderQuotaLease, getOrchestrator, listProviderQuotas, releaseProviderQuotaLease, upsertProviderQuota } from "../db";
+import { acquireProviderQuotaLease, getOrchestrator, getProviderQuotaLease, listProviderQuotas, releaseProviderQuotaLease, upsertProviderQuota } from "../db";
 import { emitRelayEvent } from "../events";
 import { quotaStateFromUnknown, providerQuotaErrorFromUnknown } from "../quota";
+import { authContextFromRequest } from "../services/auth-context";
 import { cleanString } from "../validation";
 import { authorizeRoute, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
 import type { ProviderQuotaUpdateInput } from "../types";
@@ -45,6 +46,8 @@ export const postProviderQuotaRoute: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const input = cleanProviderQuotaUpdate(parsed.body);
   if (typeof input === "string") return error(input);
+  const providerWriteGate = authorizeProviderQuotaWrite(req, input);
+  if (providerWriteGate) return providerWriteGate;
   const record = upsertProviderQuota(input);
   emitRelayEvent({ type: "provider-quota.updated", source: "server", subject: `${record.provider}:${record.accountKey}`, data: {} });
   return json(record, 201);
@@ -82,12 +85,36 @@ function cleanPublisherLeaseBody(body: unknown): {
 
 const runnerLeaseHolderId = (sourceAgentId: string) => `runner:${sourceAgentId}`;
 
+function authorizeProviderQuotaSourceAgent(req: Request, sourceAgentId: string): Response | null {
+  const ctx = authContextFromRequest(req);
+  if (ctx.component?.role !== "provider") return null;
+  const denied = authorizeRoute(req, { scope: "quota:write" });
+  if (denied) return denied;
+  return ctx.callerAgentId === sourceAgentId ? null : error("forbidden", 403);
+}
+
+function authorizeProviderQuotaWrite(req: Request, input: ProviderQuotaUpdateInput): Response | null {
+  const ctx = authContextFromRequest(req);
+  if (ctx.component?.role !== "provider") return null;
+  if (!input.sourceAgentId) return error("sourceAgentId required for provider quota writer", 403);
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
+  if (denied) return denied;
+  const lease = getProviderQuotaLease(input.provider, input.accountKey);
+  const activeLease = lease && lease.expiresAt > Date.now() ? lease : null;
+  if (activeLease?.orchestratorId === runnerLeaseHolderId(input.sourceAgentId)) return null;
+  return json({
+    skipped: true,
+    reason: "provider quota lease not held by source agent",
+    ...(activeLease ? { holder: { orchestratorId: activeLease.orchestratorId, expiresAt: activeLease.expiresAt } } : {}),
+  }, 202);
+}
+
 export const postProviderQuotaPublisherLeaseAcquireRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const input = cleanPublisherLeaseBody(parsed.body);
   if (typeof input === "string") return error(input);
-  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
   if (denied) return denied;
   return json(acquireProviderQuotaLease({
     provider: input.provider,
@@ -104,7 +131,7 @@ export const postProviderQuotaPublisherLeaseReleaseRoute: Handler = async (req)
   const input = cleanPublisherLeaseBody(parsed.body);
   if (typeof input === "string") return error(input);
   if (!input.leaseToken) return error("leaseToken required");
-  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
   if (denied) return denied;
   return json({
     released: releaseProviderQuotaLease({

package/src/services/spawn-agent.ts

@@ -33,6 +33,8 @@ import { runnerRuntimeTokenEnv } from "../runtime-tokens";
 import { selectSpawnOrchestrator } from "../spawn-targets";
 import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile } from "../config-store";
 import { composeSpawnInstructionsWithEvents, type ProjectInstructionPolicy } from "../project-instructions";
+import type { ProjectMcpPolicy } from "../project-mcp";
+import type { SharedMcpPolicy } from "../shared-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -74,6 +76,25 @@ export interface SpawnAgentInput {
    * `vanilla` (manual+promoted; excludes `ingested` host-CLAUDE.md content).
    */
   projectInstructions?: ProjectInstructionPolicy;
+  /**
+   * #667 — project `.mcp.json` MCP projection. When set, the runner reads the spawn cwd's
+   * COMMITTED `.mcp.json` and injects those servers via the controlled `--mcp-config`
+   * (composing with #662 `--strict-mcp-config`), so a worker spawned into a repo gets that
+   * repo's MCP servers — sourced from the project, never ambient host MCP. Additive-from-
+   * empty + opt-in: absent (undefined) = OFF → the launch is byte-identical to today. Sibling
+   * to projectInstructions; carried to the runner on the in-flight `agentProfile.projectMcp`.
+   */
+  projectMcp?: ProjectMcpPolicy;
+  /**
+   * #672 — shared host-listener MCP. When set, the runner emits a per-agent `callmux bridge`
+   * stdio entry so the agent's NON-IDENTITY MCP (tokenlean, github) flows through the
+   * orchestrator-owned shared listener instead of per-agent server processes — the session
+   * survives a listener/downstream restart, with `--cwd "$WORKTREE"` session-cwd isolation.
+   * Additive-from-empty + opt-in: absent (undefined) = OFF → the launch is byte-identical to
+   * today. Sibling to projectMcp; carried to the runner on the in-flight `agentProfile.sharedMcp`.
+   * The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener.
+   */
+  sharedMcp?: SharedMcpPolicy;
   /**
    * Legacy report-back contract flag. Spawned children now report up by lineage: their
    * turn-final response is delivered to the spawner automatically, without a reply obligation.
@@ -170,6 +191,21 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const agentProfile = withResolvedProvisioning(getAgentProfile(profileName)?.value, input.provider);
   if (!agentProfile) throw new McpNotFoundError(input.profile ? "agent profile not found" : `default agent profile ${DEFAULT_SPAWN_PROFILE_NAME} not found`);
 
+  // #667 — project `.mcp.json` projection: a per-spawn `projectMcp` overrides the profile
+  // default. The runner does the filesystem read + injection from `agentProfile.projectMcp`
+  // (it owns the spawn cwd), so thread the resolved decision onto the in-flight profile copy
+  // (withResolvedProvisioning returned a fresh object; mutating it never touches the cached
+  // config). Like projectInstructions, an explicit `false` parses to undefined and so cannot
+  // turn a profile default OFF — opt-in is the trust gate, not opt-out.
+  if (input.projectMcp !== undefined) agentProfile.projectMcp = input.projectMcp;
+
+  // #672 — shared host-listener MCP: a per-spawn `sharedMcp` overrides the profile default,
+  // same opt-in trust gate as projectMcp (an explicit `false` parses to undefined and so
+  // cannot turn a profile default OFF). The runner emits the bridge entry from
+  // `agentProfile.sharedMcp` (it owns the spawn cwd → `--cwd "$WORKTREE"`); thread the resolved
+  // decision onto the in-flight profile copy (a fresh object, never the cached config).
+  if (input.sharedMcp !== undefined) agentProfile.sharedMcp = input.sharedMcp;
+
   // --- THE GATE (uniform across transports) ---------------------------------
   // Coarse capability: spawning requires command:spawn. The MCP dispatcher already enforced
   // this; the HTTP route did not — asserting here makes it transport-invariant.

package/src/shared-mcp.ts

@@ -0,0 +1,57 @@
+// Shared host-listener MCP (#672, Phase 1 of epic #670) — the relay-owned, OPT-IN path that
+// routes a spawned worker's NON-IDENTITY MCP (tokenlean, github) through ONE orchestrator-owned
+// shared `callmux` listener per host, attached via a per-agent `callmux bridge` with
+// `--cwd "$WORKTREE"` for session-cwd isolation. Sibling seam to project-mcp (#667): same
+// opt-in + parse shape, default OFF.
+//
+// WHY: a shared listener turns "an MCP/listener restart kills the agent" into "the agent never
+// notices" (the bridge reconnects + retries once on the next tool call — the #659 work-loss
+// class), and collapses N per-agent server processes into one shared set (~100MB saved per
+// extra listener). The spike (#671) proved both: session survives a listener restart, and
+// session-cwd routing gives each isolated worktree its own cwd from the single shared listener.
+//
+// INVARIANT (epic #670): callmux owns transport; relay owns authz. The shared listener carries
+// ONLY non-identity servers — the identity-bearing relay endpoint stays per-agent on #215 and
+// is NEVER routed through the shared listener (the spike proved a shared listener can't carry
+// per-agent relay tokens; that's Phase 2, gated on callmux#36).
+//
+// DIVISION OF LABOR: relay carries the OPT-IN DECISION (this module + the spawn
+// param/profile field). The orchestrator owns the shared listener lifecycle/config (#673),
+// and runner owns bridge-arg emission (launch-assembly.ts → sharedMcpBridgeServer), the
+// filesystem/launch authority.
+
+export const SHARED_MCP_POLICY_NAMES = ["all"] as const;
+export type SharedMcpPolicyName = (typeof SHARED_MCP_POLICY_NAMES)[number];
+
+/** Per-spawn shared-listener request. Presence (a non-undefined value) means "route
+ * non-identity MCP through the shared listener"; absence means OFF. `policy` selects the
+ * server set (`all` = the listener's full non-identity set; the sole value today). */
+export interface SharedMcpPolicy {
+  policy?: SharedMcpPolicyName;
+}
+
+/**
+ * Parse a spawn-transport's `sharedMcp` wire value into the normalized policy (or
+ * undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift. Mirrors
+ * parseProjectMcp exactly:
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseSharedMcp(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): SharedMcpPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("sharedMcp must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !SHARED_MCP_POLICY_NAMES.includes(policy as SharedMcpPolicyName)) {
+    throw onInvalid(`sharedMcp.policy must be one of: ${SHARED_MCP_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as SharedMcpPolicyName };
+}