agent-relay-server 0.36.2 → 0.38.0

package/src/services/shutdown-agent.ts

@@ -0,0 +1,234 @@
+// Transport convergence (epic #342, slice #347) — the agent-shutdown service.
+//
+// ONE home for "shut down an agent": the #221 parent→child authorization gate, the
+// control-orchestrator resolution, and the canonical `agent.shutdown` command payload
+// + side-effects. Previously the gate existed ONLY on the MCP path (mcp.ts
+// `relayShutdownAgent`), while the HTTP route (`postAgentAction`) and the bus command
+// frame (`handleCommandFrame`) created `agent.shutdown` commands with NO parent→child
+// gate — so a scoped `agent:write`/`command:write` caller could shut down agents the
+// MCP gate would refuse. This converges all three UP to the strict #221 model: an
+// agent caller may shut down only its OWN live spawned children, addressed by agentId;
+// admin/server/system tokens (no resolved caller-agent identity) keep full reach.
+//
+// The gate is IDENTITY-based (`ctx.callerAgentId`), not scope-based: the coarse command
+// scope stays enforced at each transport's existing layer (HTTP `agent:write`, bus
+// `command:write`, MCP `command:shutdown`); this service adds the fine parent→child gate
+// uniformly. Search-verified (#347): no first-party non-admin caller hits these surfaces
+// today, so the tightening blocks no legitimate flow — it closes the HTTP/bus bypass.
+//
+// SCOPE BOUNDARY (inherited by #348's transport-thinness ratchet): this service backs
+// the THREE per-agent shutdown surfaces — HTTP `/api/agents/:id/actions` (action
+// "shutdown"), the bus `agent.shutdown` command frame, and MCP `relay_shutdown_agent`.
+// It deliberately does NOT back the OPERATOR surfaces that emit `agent.shutdown` as a
+// side effect of policy/host management (`routes/spawn-policy.ts`, `routes/orchestrator.ts`)
+// nor the internal lifecycle flows (`lifecycle-manager.stopAgent`, the maintenance
+// reaper, automations, recipe-runner): those have no per-caller-agent identity and keep
+// their own admin/`command:write` auth. Do not fold them in — gating an operator on the
+// agent's `spawnedBy` parentage is a category error.
+import {
+  ValidationError,
+  createActivityEvent,
+  getAgent,
+  getOrchestrator,
+  mergeAgentMeta,
+} from "../db";
+import { createCommand } from "../commands-db";
+import { emitCommandEvent } from "../command-events";
+import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
+import { emitActivityEvent, emitAgentStatus } from "../sse";
+import { stringValue } from "agent-relay-sdk";
+import type { AuthContext } from "./auth-context";
+import type { AgentCard, Command } from "../types";
+
+/** The caller is not authorized to shut down the target. Mapped by transports to
+ * HTTP 403 / MCP `McpAuthError` (-32001) / bus `rejected`. */
+export class ShutdownAuthError extends Error {}
+/** No agent/orchestrator matched the shutdown target. Mapped to HTTP 404 / MCP
+ * `McpNotFoundError` (-32004) / bus `failed`. */
+export class ShutdownTargetError extends Error {}
+
+type OnlineOrchestrator = NonNullable<ReturnType<typeof getOrchestrator>>;
+
+export interface ShutdownAgentInput {
+  agentId?: string;
+  policyName?: string;
+  spawnRequestId?: string;
+  tmuxSession?: string;
+  orchestratorId?: string;
+  graceful?: boolean;
+  timeoutMs?: number;
+  reason?: string;
+  /** Transport that originated the shutdown — recorded on the command for audit. */
+  requestedVia: "http" | "bus" | "mcp";
+  /** Attribution label for the audit trail (e.g. "dashboard", the MCP actor id). */
+  requestedBy?: string;
+  /** Transport-specific audit attribution merged into the activity-event metadata
+   * (e.g. the HTTP path's `dashboardAttribution` surface + `authAuditMetadata` token jti),
+   * which the service can't derive from the AuthContext alone. */
+  auditMetadata?: Record<string, unknown>;
+}
+
+export interface ShutdownAgentResult {
+  command: Command;
+  orchestratorId: string;
+  agent: AgentCard | null;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** Build a ShutdownAgentInput from a WS-bus `agent.shutdown` command frame's target +
+ * params. Lives here (not in bus.ts) so the bus transport stays a thin dispatcher and the
+ * shutdown-input shape has one home. */
+export function shutdownInputFromBusFrame(
+  target: string,
+  params: Record<string, unknown>,
+  requestedByFallback?: string,
+): ShutdownAgentInput {
+  return {
+    agentId: stringValue(params.agentId) ?? target,
+    policyName: stringValue(params.policyName),
+    spawnRequestId: stringValue(params.spawnRequestId),
+    tmuxSession: stringValue(params.tmuxSession),
+    orchestratorId: stringValue(params.orchestratorId),
+    graceful: typeof params.graceful === "boolean" ? params.graceful : undefined,
+    timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : undefined,
+    reason: stringValue(params.reason),
+    requestedVia: "bus",
+    requestedBy: stringValue(params.requestedBy) ?? requestedByFallback,
+  };
+}
+
+/** The #221 parent→child gate — the single home for shutdown authorization across all
+ * three transports. Throws `ShutdownAuthError` on denial; returns for full-reach callers. */
+export function authorizeShutdown(ctx: AuthContext, input: ShutdownAgentInput): void {
+  const callerId = ctx.callerAgentId;
+  // Full reach: admin/server/system (no resolved caller identity) and multi-agent tokens.
+  if (!callerId) return;
+  // A scoped agent caller may target only its OWN live spawned children, addressed by
+  // agentId. Broad targeting (policy/spawnRequestId/tmux) and cross-agent kills stay
+  // full-reach-only — otherwise spawn permission silently becomes kill-anyone permission.
+  if (!input.agentId || input.policyName || input.spawnRequestId || input.tmuxSession) {
+    throw new ShutdownAuthError("agents may only shut down their own spawned children, addressed by agentId");
+  }
+  const target = getAgent(input.agentId);
+  if (!target || target.spawnedBy !== callerId) {
+    throw new ShutdownAuthError(`agent ${input.agentId} is not one of your spawned children`);
+  }
+}
+
+/** Resolve the online control orchestrator for the target — the canonical resolver,
+ * lifted from mcp.ts `selectControlOrchestrator` (its sole caller) and widened to also
+ * consider the agent's `sessionName` (the HTTP path's candidate), so HTTP and MCP
+ * resolve the SAME orchestrator for the same agent. Requires an online orchestrator —
+ * a managed agent can't be shut down without one (the command would target a dead
+ * agent). The previous HTTP path silently emitted an orphaned command when none was
+ * online; this converges to a clear error. */
+function resolveControlOrchestrator(input: ShutdownAgentInput, agent: AgentCard | null): OnlineOrchestrator {
+  if (input.orchestratorId) {
+    const orchestrator = getOrchestrator(input.orchestratorId);
+    if (!orchestrator) throw new ShutdownTargetError(`orchestrator ${input.orchestratorId} not found`);
+    if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
+    return orchestrator;
+  }
+  const candidates: OnlineOrchestrator[] = [
+    ...listManagedOrchestratorsForAgent({
+      agentId: agent?.id ?? input.agentId,
+      sessionName: str(agent?.meta?.sessionName),
+      tmuxSession: input.tmuxSession ?? str(agent?.meta?.tmuxSession),
+      policyName: input.policyName ?? str(agent?.meta?.policyName),
+      spawnRequestId: input.spawnRequestId ?? str(agent?.meta?.spawnRequestId),
+    }),
+    ...(agent?.machine
+      ? [getOrchestrator(agent.machine)].filter((o): o is OnlineOrchestrator => Boolean(o))
+      : []),
+  ];
+  const online = candidates.find((o) => o.status === "online");
+  if (!online) {
+    if (candidates.length === 0) throw new ShutdownTargetError("no orchestrator found for agent control target");
+    throw new ValidationError("orchestrator is offline");
+  }
+  return online;
+}
+
+/** Shut down an agent through its control orchestrator. Authorizes (#221), resolves the
+ * orchestrator + target, builds the canonical command, emits it, marks the agent
+ * shutting-down (uniform across transports — MCP previously skipped this), and writes the
+ * audit row. The single fat-service entry point the three thin transports call. */
+export function shutdownAgent(input: ShutdownAgentInput, ctx: AuthContext): ShutdownAgentResult {
+  authorizeShutdown(ctx, input);
+
+  const agent = input.agentId ? getAgent(input.agentId) : null;
+  const orchestrator = resolveControlOrchestrator(input, agent);
+  const targetAgentId = input.agentId ?? agent?.id;
+  const policyName = input.policyName ?? str(agent?.meta?.policyName);
+  const spawnRequestId = input.spawnRequestId ?? str(agent?.meta?.spawnRequestId);
+  const tmuxSession = input.tmuxSession ?? str(agent?.meta?.tmuxSession);
+  const sessionName = str(agent?.meta?.sessionName);
+
+  const command = createCommand({
+    type: "agent.shutdown",
+    source: "system",
+    target: orchestrator.agentId,
+    correlationId: spawnRequestId,
+    params: {
+      action: "shutdown",
+      ...(targetAgentId ? { agentId: targetAgentId } : {}),
+      ...(policyName ? { policyName } : {}),
+      ...(spawnRequestId ? { spawnRequestId } : {}),
+      ...(tmuxSession ? { tmuxSession } : {}),
+      ...(sessionName ? { sessionName } : {}),
+      graceful: input.graceful ?? true,
+      timeoutMs: input.timeoutMs ?? 10_000,
+      reason: input.reason ?? `${input.requestedVia}-shutdown`,
+      orchestratorId: orchestrator.id,
+      requestedBy: input.requestedBy ?? "system",
+      requestedVia: input.requestedVia,
+      requestedAt: Date.now(),
+    },
+  });
+  emitCommandEvent(command, "command.requested");
+
+  // Lifecycle indicator — uniform across transports. The MCP path previously skipped
+  // this, so an MCP-initiated shutdown left the agent with no "shutting down" signal in
+  // the dashboard until it actually exited; now every transport sets it. We set ONLY the
+  // `lifecycleAction` meta (which drives the dashboard pill) and DON'T flip `ready` — the
+  // agent is still alive until the command executes, and a child mid-shutdown must keep
+  // occupying its parent's spawn-quota slot (`countLiveSpawnedAgents` counts ready=1)
+  // until it genuinely exits. The agent clears `ready` itself on exit / via the reaper.
+  if (agent) {
+    mergeAgentMeta(agent.id, {
+      lifecycleAction: "shutting-down",
+      lifecycleActionAt: Date.now(),
+      lifecycleCommandId: command.id,
+    });
+    emitAgentStatus(agent.id);
+  }
+
+  if (targetAgentId) {
+    const event = createActivityEvent({
+      clientId: `server-agent-${targetAgentId}-action-shutdown-${command.id}`,
+      kind: "state",
+      title: "Agent shutdown requested",
+      body: "shutdown",
+      meta: targetAgentId,
+      icon: "ti-power",
+      view: "agents",
+      agentId: targetAgentId,
+      metadata: {
+        action: "shutdown",
+        commandId: command.id,
+        orchestratorId: orchestrator.id,
+        actor: ctx.actor.id,
+        actorKind: ctx.actor.kind,
+        requestedVia: input.requestedVia,
+        ...(input.auditMetadata ?? {}),
+        source: "server",
+      },
+    });
+    emitActivityEvent(event);
+  }
+
+  return { command, orchestratorId: orchestrator.id, agent };
+}

package/src/services/spawn-agent.ts

@@ -0,0 +1,284 @@
+// Transport convergence (epic #342, slice #349) — the agent-spawn service.
+//
+// ONE home for "spawn a provider agent through the orchestrator". Previously the
+// security core was inlined in the MCP `relay_spawn_agent` handler ONLY: the
+// `command:spawn` scope, the #221 no-grandchild + maxSpawnedAgents quota gate, the
+// #323 orchestrator-resource gate, authoritative `spawnedBy` lineage stamping, and
+// the #328/#331/#324 caller-context inheritance (host / cwd / approvalMode / isolated
+// workspace). The HTTP `POST /api/agents/spawn` route did NONE of it — it authorized
+// on `agent:write` and emitted an ungated, un-parented spawn command. A spawn-capable
+// token reaching HTTP bypassed the entire gate (masked today only because the dashboard
+// uses an admin `*` token). That is exactly the "fixed in one transport, not the other"
+// drift epic #342 kills.
+//
+// Transports now shrink to: parse wire → `authContextFrom*` → `spawnAgent` → serialize.
+// Both the MCP and HTTP paths feed ONE `AuthContext`; identity (`ctx.callerAgentId`),
+// scopes, and signed constraints are read identically, so the gate cannot diverge. The
+// parity harness (spawn-agent.parity.test.ts) asserts both transports produce a
+// byte-identical command payload + identical gate behavior through this service.
+//
+// NOTE — internal callers (managed-policy auto-spawn, automations, agent-session resume)
+// are SYSTEM-actor spawns with their own lineage semantics (policy/scheduled, not
+// agent-parented); the agent-caller gate genuinely no-ops for them. They stay on the
+// shared `buildSpawnCommand`/`buildManagedSpawnParams` payload home directly. Folding
+// them through `spawnAgent(systemCtx)` is a clean belt-and-suspenders follow-up (#342),
+// deliberately out of scope here — this slice converges the two external TRANSPORTS.
+import type { SpawnProvider } from "agent-relay-sdk";
+import { stringValue } from "agent-relay-sdk";
+import { countLiveSpawnedAgents, createActivityEvent, getAgent, listAgents, ValidationError } from "../db";
+import { createCommand } from "../commands-db";
+import { emitCommandEvent } from "../command-events";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { selectSpawnOrchestrator } from "../spawn-targets";
+import { getAgentProfile } from "../config-store";
+import { hasComponentScope, isComponentAuthorizedFor } from "../security";
+import { isPathWithinBase } from "../utils";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import type { AuthContext } from "./auth-context";
+import type { AgentCard, Command, SpawnApprovalMode, WorkspaceMode } from "../types";
+
+/** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
+const SPAWN_SCOPE = "command:spawn";
+
+/**
+ * A normalized spawn request — every transport validates its own wire shape (enums,
+ * lengths) and hands the service this. Caller-context defaults (cwd, approvalMode,
+ * workspaceMode, host) are resolved INSIDE the service from `ctx`, so `undefined`
+ * here means "not explicitly set; apply the unified default", never "transport forgot".
+ */
+export interface SpawnAgentInput {
+  provider: SpawnProvider;
+  orchestratorId?: string;
+  cwd?: string;
+  /** Raw model/effort; resolved to a {model,providerModel,effort} payload by the service. */
+  model?: string;
+  effort?: string;
+  approvalMode?: SpawnApprovalMode;
+  workspaceMode?: WorkspaceMode;
+  label?: string;
+  policyName?: string;
+  profile?: string;
+  prompt?: string;
+  systemPromptAppend?: string;
+  tags?: string[];
+  capabilities?: string[];
+  providerArgs?: string[];
+  spawnRequestId?: string;
+  /** Transport provenance label baked into the command payload (e.g. "mcp", "dashboard"). */
+  requestedVia?: string;
+  /** Provenance actor override (the dashboard records "dashboard"); falls back to caller id / actor. */
+  requestedBy?: string;
+  /** Poll for the spawned child's registration this long (ms). 0 = fire-and-forget (HTTP). */
+  waitForRegistrationMs?: number;
+}
+
+export interface SpawnAgentResult {
+  ok: true;
+  spawnRequestId: string;
+  orchestratorId: string;
+  provider: SpawnProvider;
+  /** Resolved once the child registers with this spawnRequestId; null on timeout / no wait. */
+  agentId: string | null;
+  registered: boolean;
+  command: Command;
+}
+
+/** Reject when a component token's signed resource constraints disallow the target (#323). */
+function assertResourceAllowed(ctx: AuthContext, check: Parameters<typeof isComponentAuthorizedFor>[1]): void {
+  if (ctx.component && !isComponentAuthorizedFor(ctx.component, check)) {
+    throw new McpAuthError("component token cannot access this resource");
+  }
+}
+
+/** True if the principal holds the spawn scope. System callers bypass; admin `*`/`admin:*` pass. */
+function canSpawn(ctx: AuthContext): boolean {
+  if (ctx.actor.kind === "system") return true;
+  if (ctx.scopes.includes("*") || ctx.scopes.includes("admin:*")) return true;
+  if (ctx.component) return hasComponentScope(ctx.component, SPAWN_SCOPE);
+  return ctx.scopes.includes(SPAWN_SCOPE);
+}
+
+/**
+ * Spawn a provider agent. Transport-agnostic: every gate + side effect lives here so the
+ * MCP and HTTP paths cannot drift. Throws `McpAuthError` (→403) on a gate denial,
+ * `ValidationError` (→400) on bad input/quota, `McpNotFoundError` (→404) on a missing
+ * orchestrator. With `waitForRegistrationMs > 0` it resolves the child's agent id by
+ * polling its registration; otherwise it returns immediately (fire-and-forget).
+ */
+export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Promise<SpawnAgentResult> {
+  // The authenticated caller's own agent card (when the token resolves to one). Drives both
+  // the #221 gate AND the #328/#331/#324 caller-context inheritance — one lookup, reused.
+  const callerId = ctx.callerAgentId;
+  const caller: AgentCard | undefined = (callerId ? getAgent(callerId) : undefined) ?? undefined;
+
+  // #255/#328 — bias the host to the caller's own machine when neither an explicit
+  // orchestratorId nor a cwd pins it, so an agent spawning a helper lands on its own host.
+  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, input.cwd, caller?.machine);
+
+  // #308 §3 — an explicit cwd must resolve within the TARGET host's base dir (a path valid on
+  // your host may not exist on a different orchestrator).
+  if (input.cwd && !isPathWithinBase(input.cwd, orchestrator.baseDir)) {
+    throw new ValidationError(`cwd '${input.cwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
+  }
+  // #328 — default cwd to the caller's OWN repo (so "spawn a helper for my current task" Just
+  // Works, esp. isolated mode which needs a git repo), but only when it resolves within the
+  // target host's base. Precedence: explicit cwd > caller cwd > base dir.
+  const callerCwd = stringValue(caller?.meta?.cwd);
+  const inheritedCwd = callerCwd && isPathWithinBase(callerCwd, orchestrator.baseDir) ? callerCwd : undefined;
+  const resolvedCwd = input.cwd || inheritedCwd || orchestrator.baseDir;
+
+  const modelParams = resolveSpawnModelParams(input.provider, input.model, input.effort);
+
+  // #331 — default the child's approval mode to the CALLER's, not a hardcoded `guarded` (a
+  // headless `guarded` child wedges on its first tool-call approval prompt). Explicit always
+  // wins and can NARROW a child; non-agent callers keep the safe `guarded` default.
+  const callerApprovalMode = caller?.meta?.approvalMode as SpawnApprovalMode | undefined;
+  const approvalMode = input.approvalMode ?? callerApprovalMode ?? "guarded";
+
+  // #324 — agent-initiated spawns (a real caller behind the token) default to `isolated` (a
+  // branch worker that auto-lands); non-agent callers (admin/dashboard) keep the orchestrator's
+  // `inherit` fallback. Explicit wins.
+  const workspaceMode = input.workspaceMode ?? (callerId ? ("isolated" as WorkspaceMode) : undefined);
+
+  const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
+
+  // Resolve + validate the named agent profile server-side (was HTTP-only; the MCP path passed
+  // the name through unvalidated). Both transports now 404 on an unknown profile and ship the
+  // resolved value to the orchestrator.
+  const agentProfile = input.profile ? getAgentProfile(input.profile)?.value : undefined;
+  if (input.profile && !agentProfile) throw new McpNotFoundError("agent profile not found");
+
+  // --- 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.
+  if (!canSpawn(ctx)) {
+    throw new McpAuthError(`spawn requires the ${SPAWN_SCOPE} scope`);
+  }
+  // #221 — a real spawning agent: no grandchildren, and within its maxSpawnedAgents quota.
+  // Server/admin/dashboard tokens carry no caller identity → unrestricted by design.
+  if (callerId) {
+    if (caller?.spawnedBy) {
+      throw new McpAuthError("spawned agents cannot spawn further agents (no grandchildren)");
+    }
+    const quota = ctx.constraints?.maxSpawnedAgents ?? 0;
+    const live = countLiveSpawnedAgents(callerId);
+    if (live >= quota) {
+      throw new ValidationError(`spawn quota reached (${live}/${quota} live children) — shut one down or wait for one to exit`);
+    }
+  }
+  // Gate the child spawn on the token's legit bounds: the target orchestrator AND the spawn cwd
+  // (`cwdPrefixes`/`cwd` constraint). Excludes the #323 footguns (spawnRequestIds/policies) — those
+  // are self-scoping per-spawn ids the CHILD gets fresh, so gating on them makes the quota
+  // unreachable. The cwd bound was enforced by the old HTTP route (resource.cwd) but NOT by the MCP
+  // path; unifying here converges UP to the strict union — a scoped dashboard token still can't spawn
+  // outside its cwd prefix, and MCP now honors the same bound.
+  assertResourceAllowed(ctx, { scope: "agent:write", resource: { orchestratorId: orchestrator.id, cwd: resolvedCwd } });
+
+  // Provenance actor: the resolved caller agent when known, else the transport's label, else
+  // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
+  const requestedBy = callerId ?? input.requestedBy ?? ctx.actor.id;
+
+  // Child runner token. `agentInitiated` (set whenever an agent is the caller) forces a
+  // non-spawn-capable child (no grandchildren); `spawnedBy` stamps authoritative lineage the
+  // child can't forge (it registers with spawnedBy = caller, read from the signed token).
+  const env = runnerRuntimeTokenEnv({
+    orchestratorId: orchestrator.id,
+    cwd: resolvedCwd,
+    provider: input.provider,
+    label: input.label,
+    policyName: input.policyName,
+    spawnRequestId,
+    createdBy: requestedBy,
+    // Thread the resolved profile into the mint so the spawn grant (command:spawn/shutdown +
+    // maxSpawnedAgents quota) is honored — parity with the HTTP path (agent-sessions.ts). #349
+    // dropped this when it unified the spawn service, silently un-spawning every default-spawner
+    // (P0 regression #364). For an agent caller, agentInitiated still forces a non-spawn-capable
+    // child regardless of profile (no grandchildren).
+    profile: input.profile || undefined,
+    ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
+  });
+
+  const command = createCommand({
+    type: "agent.spawn",
+    source: "system",
+    target: orchestrator.agentId,
+    correlationId: spawnRequestId,
+    params: buildSpawnCommand({
+      provider: input.provider,
+      modelParams,
+      cwd: resolvedCwd,
+      ...(workspaceMode ? { workspaceMode } : {}),
+      label: input.label,
+      profile: input.profile || undefined,
+      agentProfile,
+      tags: input.tags ?? [],
+      capabilities: input.capabilities ?? [],
+      approvalMode,
+      permissionMode: approvalMode,
+      providerArgs: input.providerArgs ?? [],
+      prompt: input.prompt,
+      systemPromptAppend: input.systemPromptAppend,
+      policyName: input.policyName,
+      spawnRequestId,
+      env,
+      requestedBy,
+      requestedVia: input.requestedVia,
+      requestedAt: Date.now(),
+      orchestratorId: orchestrator.id,
+      // #308 — stamp the spawning parent so a FAILED agent.spawn command (child never registers,
+      // so there's no agent row to resolve `spawnedBy` from) can be routed back to it.
+      ...(callerId ? { extra: { spawnedBy: callerId } } : {}),
+    }),
+  });
+  emitCommandEvent(command, "command.requested");
+
+  // ONE spawn-request audit row, identical across transports (the MCP path previously emitted
+  // none of its own — only the generic tool-call telemetry; the HTTP path emitted one).
+  createActivityEvent({
+    clientId: `server-agent-spawn-${input.provider}-${command.id}`,
+    kind: "state",
+    title: `${input.provider} agent spawn requested (via ${orchestrator.id})`,
+    body: resolvedCwd,
+    meta: orchestrator.id,
+    icon: "ti-plus",
+    view: "agents",
+    metadata: {
+      provider: input.provider,
+      orchestratorId: orchestrator.id,
+      approvalMode,
+      workspaceMode: workspaceMode ?? null,
+      label: input.label ?? null,
+      commandId: command.id,
+      spawnRequestId,
+      requestedVia: input.requestedVia ?? null,
+      actor: requestedBy,
+      actorKind: ctx.actor.kind,
+    },
+  });
+
+  // #255 — resolve the spawned child's id once it registers back to THIS relay (same DB) with
+  // meta.spawnRequestId set. Bounded poll; 0 opts out (pure fire-and-forget, e.g. the HTTP 202).
+  const waitMs = Math.min(input.waitForRegistrationMs ?? 0, 30_000);
+  const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
+  return {
+    ok: true,
+    spawnRequestId,
+    orchestratorId: orchestrator.id,
+    provider: input.provider,
+    agentId,
+    registered: agentId !== null,
+    command,
+  };
+}
+
+/** Poll the agents table for the child that registers with this spawnRequestId (#255). */
+async function waitForSpawnedAgent(spawnRequestId: string, timeoutMs: number, pollMs = 300): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const match = listAgents().find((a) => a.meta?.spawnRequestId === spawnRequestId);
+    if (match) return match.id;
+    if (Date.now() >= deadline) return null;
+    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+  }
+}

package/src/workspace-actions.ts

@@ -25,7 +25,7 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
-import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
 // the MCP tool surface both import this so they can never drift out of sync.
@@ -54,6 +54,8 @@ interface ApplyWorkspaceActionInput {
   deleteBranch?: boolean;
   prTitle?: string;
   prBody?: string;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
   // cleanup
   force?: boolean;
   // claim / release-claim
@@ -171,6 +173,8 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
       deleteBranch: input.deleteBranch !== false,
       prTitle: input.prTitle,
       prBody: input.prBody,
+      autoMerge: input.autoMerge,
+      reviewer: input.reviewer,
       metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
     });
     if (!result.ok) return { ok: false, httpStatus: result.status, error: result.error };