@humwick/server 0.0.0-stage → 0.130.1

package/src/services/spawn-agent.ts

@@ -0,0 +1,967 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { bindSpawnProjectCheckout } from "./project-checkout-binding";
+import { REPORT_VERBOSITIES, resolveReportVerbosity } from "@humwick/sdk";
+import { cleanCallerSpawnEnv } from "../spawn-env";
+import { optionalEnum } from "../validation";
+import { optionalNonNegativeInt } from "../validation";
+import { cleanSpawnBudget } from "../spawn-budget";
+import { teamId as newTeamId } from "../db/teams";
+import { getGateway } from "../db/gateway";
+import type { WorkflowSpawnQuota } from "../db/spawn-in-flight";
+// 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 { resolveSpawnApprovalMode } from "./spawn-approval";
+import { assertOrchestratorSupportsLaunchMode, resolveSpawnLaunchMode } from "../launch-mode";
+import { DEFAULT_USER_ID, errMessage, isRecord, stringValue, type LaunchMode, type ReportVerbosity, type SpawnProvider, type TaskDispatch } from "@humwick/sdk";
+import { addProjectRootAsync, countLiveSpawnedAgents, createActivityEventAsync, getAgent, getProject, getTaskDetailAsync, listAgents, listProjects, listWorkspaces, recordTaskSpawnRequestedAsync, reportedRepoRootForCwd, resolveAgentOwnershipAsync, resolveProjectForCwd, rootsForProject, ValidationError, withResolvedProvisioningAsync } from "../db";
+import { acquireCoordinatorTeam } from "./team";
+import { countInFlightSpawnCommands } from "../commands-db";
+import { createSpawnCommandWithinQuotaAsync } from "../commands-write";
+import { emitCommandEvent } from "../command-events";
+import { redactCommandSecrets } from "../command-secrets";
+import { buildSpawnCommand, generateSpawnRequestId } from "../spawn-command"; import { systemTagsForSpawn } from "../agent-system-tags";
+import { resolveSpawnLandBlocked } from "../land-block";
+import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { liveSpawnQuota } from "../spawn-quota";
+import { resolveCanonicalHost } from "../host-identity";
+import { resolveSpawnHostAnchor } from "../spawn-targets";
+import { builtInProfileSpawnDefaults } from "../agent-profile-catalog";
+import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile, getLandingConfig, hostPinForProfile, projectMemoryEnabledForProfile, spawnGrantForProfile } from "../config-store";
+import { profileNotFoundMessage } from "../spawn-profile-errors";
+import { composeSpawnInstructionsWithEventsAsync } from "../project-instructions";
+import { applyDefaultSharedMcp, type SharedMcpSpawnOverride } from "../shared-mcp";
+import { findGitRepoRoot, isInsideGitWorkTree, pathVisibleLocally } from "./canonical-root";
+import { selectSpawnCwdPlacement } from "./spawn-cwd-placement";
+import { isolatedSpawnGitRepoError, resolveSpawnRepoRoot } from "./spawn-repo-probe";
+import { autoSeedProjectForCwdAsync } from "./project"; import { applyProjectCapabilityGates } from "../project-trust";
+import { assertProjectRoleMcpCwd, assertProjectRoleMcpTrusted, projectRoleProfile, projectRoleProvenance, projectRoleSpawnDefaults, withRoleProfile } from "../project-roles";
+import { spawnWarnings } from "./spawn-warnings";
+import { resolveSpawnProjectRole } from "./spawn-project-role";
+import { profileProviderPin, resolveSpawnLaunch } from "./spawn-launch";
+import { hydrateTaskContext, projectTaskHydration } from "./task-context-hydration";
+import { createTaskEntity, getTaskEntityAsync, recordTaskEntityDispatchDecisionAsync } from "./task-entity";
+import { autoSubscribeTaskCoordinator } from "./task-semantic-events"; import { resolveTaskOwnerAgentId } from "../task-owner";
+import { dispatchTaskAsync, type DispatchPin } from "../task-dispatcher";
+import { hasComponentScope, isComponentAuthorizedFor } from "../security";
+import { isOrchestratorLocalToRelay, isPathWithinBase } from "../utils";
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { actingUserIdOf, type AuthContext } from "./auth-context";
+import { replayAdmittedSpawn, spawnReplay } from "./spawn-replay";
+import { resolveSpawnSelfEffortDefault, type SelfEffortSpawnInput } from "./self-effort";
+import type { AgentProfile, AgentCard, AgentLifecycle, Command, CreateCommandInput, SpawnApprovalMode, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceLandMechanism, WorkspaceMode } from "../types";
+import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "../workspace-merge";
+import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
+import { AUTO_SCAFFOLD_TASK_NUDGE, shouldAutoScaffoldTask, spawnBrief, taskSpawnLabel, taskTitleFromBrief } from "./spawn-brief";
+import { buildProspectiveSpawnIdentity, assertBranchFromTargetPlacementWithinBase, generateSpawnAgentId, isolatedWorktreeCwdPrefixes, resolveProspectiveWorkspaceIdentity } from "./spawn-identity";
+import type { WhoamiSpawner } from "../mcp/presentation";
+
+/** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
+const SPAWN_SCOPE = "command:spawn";
+const RETIRED_PROFILE_PROVISIONING_SPAWN_FIELDS = ["projectInstructions", "projectMcp", "projectSettings", "projectSkills"] as const;
+
+/** Reject removed wire fields at the shared boundary so legacy HTTP, MCP, and direct service
+ * callers receive a migration path instead of silently changing profile policy. */
+export function rejectRetiredProfileProvisioningSpawnFields(input: object): void {
+  const fields = RETIRED_PROFILE_PROVISIONING_SPAWN_FIELDS.filter((field) => Object.hasOwn(input, field));
+  if (fields.length > 0) {
+    throw new ValidationError(`${fields.join(", ")} can no longer be set when spawning an agent; configure this on the profile instead`);
+  }
+}
+
+// findGitRepoRoot is the *worktree-local* walk on purpose here: workspace placement and the
+// isolated-spawn repo assertion are about the checkout the spawn physically happens in, not
+// about project identity. Project identity goes through canonicalRoot() (#1597) inside
+// autoSeedProjectForCwdAsync below.
+//
+// #1627 — but that walk runs on THE RELAY's filesystem, which is not where the spawn happens. A
+// relay is a hub; the orchestrator a spawn targets routinely runs on another machine. Statting a
+// maclinux checkout from a relay on macmini2 answers about a path that is not there, so a clean
+// non-bare clone on `main` was refused as "not a git repo" — a claim the relay was in no position
+// to make. With the same home layout on every host it is worse than blind: it can see a DIFFERENT
+// directory at the same absolute path and answer confidently about the wrong one. (The same
+// blindness is why autoSeedProjectForCwdAsync mints no project for such a cwd — which is how ONE
+// condition, "the relay cannot see the orchestrator's disk", surfaced as two unrelated-looking
+// errors, one of them false.)
+//
+// So the relay refuses only what it can actually observe, and only where git agrees:
+//   1. a host-REPORTED repo root covering the cwd (a workspace row written by the runner that
+//      launched there, i.e. `git rev-parse` run on the real filesystem) → accept; host truth
+//      outranks anything this process can guess about a path that is not its own;
+//   2. a `.git` marker on the local walk → accept, so the single-host case pays nothing;
+//   3. the cwd is invisible to the relay → it cannot judge. Defer: the orchestrator's
+//      resolveSpawnWorkspace re-runs this precondition against the real disk with real
+//      `git rev-parse` and throws there, so a genuine non-repo is still rejected — by the only
+//      process able to tell. The cost is that a *same-host* typo'd cwd now fails as a spawn
+//      failure instead of synchronously; refusing a real repo is the worse of the two errors,
+//      because its only fallback is workspaceMode "shared" in a live tree;
+//   4. visible and no marker → ask `git rev-parse --is-inside-work-tree` before refusing, so
+//      layouts the marker walk cannot see (GIT_DIR-style setups) are accepted too.
+async function assertIsolatedSpawnHasGitRepo(cwd: string): Promise<void> {
+  if (reportedRepoRootForCwd(cwd)) return;
+  if (findGitRepoRoot(cwd)) return;
+  if (!pathVisibleLocally(cwd)) return;
+  if (await isInsideGitWorkTree(cwd)) return;
+  throw isolatedSpawnGitRepoError(cwd);
+}
+
+export function acquisitionManifestFor(projectId: string, cwd: string): {
+  mode: "project-root";
+  projectId: string;
+  rootPath: string;
+  cwd: string;
+  remoteUrl: string;
+  ref?: string;
+  sync: "ff-only";
+} | undefined {
+  const root = rootsForProject(projectId)
+    .filter((candidate) => candidate.remoteUrl && isPathWithinBase(cwd, candidate.rootPath))
+    .sort((a, b) => b.rootPath.length - a.rootPath.length)[0];
+  if (!root?.remoteUrl) return undefined;
+  return {
+    mode: "project-root",
+    projectId,
+    rootPath: root.rootPath,
+    cwd,
+    remoteUrl: root.remoteUrl,
+    ...(root.ref ? { ref: root.ref } : {}),
+    sync: "ff-only",
+  };
+}
+
+export async function taskLinkedRepoCwd(taskId: number, callerCwd?: string): Promise<string> {
+  const task = await getTaskDetailAsync(taskId);
+  if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
+  // #2844 — a Task created with `repo:` but no linked issue still names its project repo.
+  const repos = [...new Set([...task.issues.map((issue) => issue.repo), task.repo].filter((repo): repo is string => Boolean(repo)))];
+  if (repos.length === 0) {
+    throw new ValidationError(`task ${taskId} has no linked issue repo; pass cwd/orchestratorId explicitly`);
+  }
+  const candidates = listProjects()
+    .filter((project) => project.issueRepo && repos.includes(project.issueRepo))
+    .flatMap((project) => rootsForProject(project.id).map((root) => ({ project, root })));
+  if (candidates.length === 0) {
+    // #1627 — this refusal is real and names its own cause: with no registered root, relay has no
+    // way to turn "repo owner/name" into a checkout path on a specific host. What made it a trap
+    // was the NEXT step: following its advice (pass cwd + orchestratorId) used to hit the isolated
+    // precondition's local-filesystem probe and get told the repo was "not a git repo". That lie is
+    // fixed at assertIsolatedSpawnHasGitRepo, so the remedy below now works. Name the tool so it is
+    // mechanical rather than a step you have to know exists.
+    throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} but no Relay project root is registered for it, so relay cannot resolve a checkout path for it; pass cwd + orchestratorId explicitly, or register the checkout with relay_project_add_root`);
+  }
+  const matchingCallerRoot = callerCwd
+    ? candidates
+      .filter((candidate) => isPathWithinBase(callerCwd, candidate.root.rootPath))
+      .sort((a, b) => b.root.rootPath.length - a.root.rootPath.length)[0]
+    : undefined;
+  if (matchingCallerRoot) return matchingCallerRoot.root.rootPath;
+  if (candidates.length === 1) return candidates[0]!.root.rootPath;
+  throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} with multiple registered roots; pass cwd explicitly`);
+}
+
+/**
+ * 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 extends SelfEffortSpawnInput {
+  env?: Record<string, string>;
+  budget?: import("@humwick/sdk").DelegationBudget;
+  maxSpawnedAgents?: number;
+  provider?: SpawnProvider | "auto";
+  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;
+  lifecycle?: AgentLifecycle;
+  label?: string;
+  policyName?: string;
+  profile?: string;
+  /** #3043 — a project role (`.agent-relay/roles/<name>.md` at the default-branch commit); excludes `profile`. */
+  role?: string;
+  /** #3043 — read `role` at this landed commit (an ancestor of the default branch); #3045 the workflow run spawning a step; #3091 the base profile its step pins,
+   *  the run's checkout in place of the Task's repo root, and the host to prefer for reading the role (the one the run read its workflow on). Service-only. */
+  roleSnapshot?: import("../project-roles").ProjectRole;
+  workflowCaller?: WorkflowSpawnQuota;
+  roleSha?: string; workflowRunId?: string; roleProfile?: string; taskRepoCwd?: string; roleHost?: string;
+  prompt?: string;
+  systemPromptAppend?: string;
+  /**
+   * #838 — spawn-with-task. When set, relay hydrates the worker's FIRST-TURN context FROM the
+   * durable Task #834 (intent + linked-issue spec/acceptance + recorded decisions + history +
+   * attribution) instead of the caller hand-writing a brief, records the spawn on the Task for
+   * attribution, and (when model/effort are omitted) MAY resolve them from the Task's dispatch
+   * work-shape (#839). Absent = today's behavior, byte-identical.
+   */
+  taskId?: number;
+  /** #3327 — inline work shape for the service's own dispatch; wins over the Task's and the profile's. */
+  dispatch?: TaskDispatch;
+  /** Internal: model/effort pins applied over the work-shape decision the service makes itself (#4961). */
+  dispatchPin?: Pick<DispatchPin, "model" | "effort">;
+  pinSources?: Record<string, string>;
+  /** #3105 — the service's own dispatch prefers a provider outside these when one can run this spawn. Service-only. */
+  avoidProviders?: SpawnProvider[];
+  /**
+   * #867 — explicit escape hatch for utility/standby spawns that carry a prompt but are not
+   * dispatching deliverable work. Known utility profiles are also exempt by default.
+   */
+  taskless?: boolean;
+  /** #838 — the latest one-line steer; the actionable instruction layered over the hydrated Task context. */
+  steer?: string;
+  /**
+   * #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?: SharedMcpSpawnOverride;
+  harnessSubagents?: boolean;
+  landStrategy?: WorkspaceLandingPolicy;
+  landMechanism?: WorkspaceLandMechanism;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
+  /** Permanent explicit no-land request. Task type never implies a block; a built-in's code-owned
+   * spawn default (probe, #2982) fills it only when the caller leaves it unset. */
+  landBlocked?: boolean;
+  /** Bind the child's runner token to its launch host (#2982, replaces the host-pinned preset).
+   * Only ever adds a pin: it cannot lift one the profile or an agent-initiated spawn implies. */
+  hostPinned?: boolean;
+  /**
+   * 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.
+   * Explicit true is preserved in the command payload for compatibility only.
+   */
+  expectReply?: boolean;
+  /**
+   * #1037 — per-spawn report-up verbosity (`quiet` default | `normal` | `verbose`). Persisted in
+   * the spawn command params and stamped onto the child's meta at registration, where the lineage
+   * report-up delivery gate reads it. Absent = `quiet`.
+   */
+  reportVerbosity?: ReportVerbosity;
+  tags?: string[];
+  capabilities?: string[];
+  providerArgs?: string[];
+  /** #2773 — interactive|headless for providers that offer both; absent resolves the central default. */
+  launchMode?: LaunchMode;
+  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;
+  /**
+   * #635 — attach to or branch off an existing managed worktree. Relay validates existence
+   * + live-agent containment before enriching with the resolved worktreePath/workspaceId and
+   * threading to the orchestrator. User provides only `branch` + `mode`; relay fills the rest.
+   */
+  resumeWorkspace?: {
+    branch: string;
+    mode: "attach" | "branch-from";
+    /** Relay-enriched: resolved worktree path from the DB (set during validation, not user input). */
+    worktreePath?: string;
+    /** Relay-enriched: existing workspace id so the record is updated, not duplicated (attach only). */
+    workspaceId?: string;
+    /** Relay-enriched: existing baseRef. */
+    baseRef?: string;
+    /** Relay-enriched: existing baseSha. */
+    baseSha?: string;
+  };
+  /**
+   * #2095 self-compact e2e test rig — force the spawned runner to REPORT a synthetic context
+   * utilization (a 0..1 fraction, or a percentage the route normalizes) so the server's real
+   * lifecycle tick drives ONE real advisory + forced clear-inject cycle. Translated here into the
+   * runner env var `AGENT_RELAY_FORCE_CONTEXT_PCT`; absent = no env var = production behavior. The
+   * strict one-shot latch + the whole compaction path live runner-side (see runner-core).
+   */
+  forceContextPct?: number;
+}
+
+export interface SpawnAgentResult {
+  ok: true;
+  spawnRequestId: string;
+  orchestratorId: string;
+  placementReason: string;
+  provider: SpawnProvider;
+  /** Resolved once the child registers with this spawnRequestId; null on timeout / no wait. */
+  agentId: string | null;
+  registered: boolean;
+  harnessSubagents: boolean;
+  command: Command;
+  /** #1033 — the durable Task this spawn is bound to (explicit taskId or auto-scaffolded), when any. */
+  taskId?: number;
+  task?: { id: number; autoScaffolded: boolean; nudge: string };
+  /** The decision admitted with the command (stored at `command.params.dispatchDecision`), when one was made. */
+  dispatchDecision?: Awaited<ReturnType<typeof dispatchTaskAsync>>;
+  /** #3043 — the spawn went ahead, but the caller should know (a role read from a stale default branch). */
+  warnings?: string[];
+}
+
+/** 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. */
+export 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);
+}
+
+function concreteProvider(value: SpawnAgentInput["provider"]): SpawnProvider | undefined {
+  return value && value !== "auto" ? value : undefined;
+}
+
+function agentIdFromTaskCreator(createdBy: string | undefined): string | undefined {
+  const raw = createdBy?.trim();
+  if (!raw) return undefined;
+  const candidates = [raw, raw.startsWith("agent:") ? raw.slice("agent:".length) : undefined].filter((value): value is string => Boolean(value));
+  return candidates.find((candidate) => getAgent(candidate)) ?? undefined;
+}
+
+/** The agent a spawn inherits its cwd and host from: the caller, else the Task's owner seat (#2862). */
+export function spawnLineageAgentId(ctx: AuthContext, task: Parameters<typeof resolveTaskOwnerAgentId>[0]): string | undefined {
+  return ctx.callerAgentId ?? agentIdFromTaskCreator(resolveTaskOwnerAgentId(task));
+}
+
+/**
+ * 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> {
+  rejectRetiredProfileProvisioningSpawnFields(input);
+  const budget = cleanSpawnBudget(input.budget);
+  const maxSpawnedAgents = optionalNonNegativeInt(input.maxSpawnedAgents, "maxSpawnedAgents");
+  // 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 governed = ctx.actor.kind === "system" ? input.workflowCaller : undefined;
+  const callerId = governed?.agentId ?? ctx.callerAgentId;
+  // Coarse capability: spawning requires command:spawn, on every transport, before any replay or resolution.
+  if (!canSpawn(ctx)) throw new McpAuthError(`spawn requires the ${SPAWN_SCOPE} scope`);
+  // #3327 — an admitted request replays its stored command and decision before any live input is read.
+  const replay = replayAdmittedSpawn(input.spawnRequestId?.trim(), ctx, callerId);
+  if (replay) return replay;
+  const callerEnv = cleanCallerSpawnEnv(input.env);
+  const caller: AgentCard | undefined = (callerId ? getAgent(callerId) : undefined) ?? undefined;
+  let autoScaffoldedTask: SpawnAgentResult["task"] | undefined;
+  let linkedTask = input.taskId !== undefined ? (await getTaskEntityAsync(input.taskId)) ?? undefined : undefined;
+  const lineageAgentId = governed?.agentId ?? spawnLineageAgentId(ctx, linkedTask);
+  const lineageAgent: AgentCard | undefined = (lineageAgentId ? getAgent(lineageAgentId) : undefined) ?? undefined;
+  const callerCwd = stringValue(caller?.meta?.cwd) ?? stringValue(lineageAgent?.meta?.cwd);
+  const taskDefaultCwd = input.taskId !== undefined && (!input.orchestratorId || input.role !== undefined) && !input.cwd
+    ? input.taskRepoCwd ?? await taskLinkedRepoCwd(input.taskId, callerCwd)
+    : undefined;
+  const requestedCwd = input.cwd ?? taskDefaultCwd ?? (input.role !== undefined ? callerCwd : undefined);
+  const roleSpawn = input.roleSnapshot ? { role: input.roleSnapshot, warnings: [] } : input.role === undefined && input.roleSha === undefined ? undefined : await resolveSpawnProjectRole({ role: input.role, roleSha: input.roleSha, profile: input.profile, orchestratorId: input.orchestratorId, cwd: requestedCwd, preferHost: input.roleHost ?? caller?.machine ?? lineageAgent?.machine, allowedOrchestratorIds: ctx.constraints?.orchestrators, canSpawn: canSpawn(ctx) });
+  // #3109 — the host that read the role does not pin the spawn: an omitted orchestratorId still means capacity placement.
+  const projectRole = roleSpawn && withRoleProfile(roleSpawn.role, input.roleProfile);
+
+  const baseProfileName = projectRole?.extends ?? input.profile;
+  const profileEntry = getAgentProfile(baseProfileName ?? DEFAULT_SPAWN_PROFILE_NAME)?.value;
+  if (!profileEntry) throw new McpNotFoundError(projectRole ? `project role "${projectRole.name}" extends unknown profile "${projectRole.extends}"` : profileNotFoundMessage(input.profile));
+  // #2791 — canonicalize once at the seam: everything downstream (task scaffolding, system tags,
+  // token scopes, payload/meta/memoryIdentity profile) uses the STORED case, never the caller's.
+  const profileName = profileEntry.name;
+  const warnings = spawnWarnings(roleSpawn?.warnings, projectRole?.assets, profileName, Boolean(lineageAgentId));
+  const profileSpawnDefaults = projectRoleSpawnDefaults(builtInProfileSpawnDefaults(profileName), projectRole);
+  // Shared workspaces must remain on the caller's host because they use the live tree.
+  const autoHostAnchor = !input.orchestratorId && input.workspaceMode === "shared" && (input.dispatch ?? linkedTask?.dispatch) === undefined
+    ? resolveSpawnHostAnchor({ cwd: requestedCwd, preferHost: caller?.machine ?? lineageAgent?.machine, allowedOrchestratorIds: ctx.constraints?.orchestrators, pinToPreferHost: input.workspaceMode === "shared" })
+    : undefined;
+  const launch = await resolveSpawnLaunch({
+    profile: profileName, pinSources: { ...input.pinSources, ...(!concreteProvider(input.provider) && profileProviderPin(profileEntry) ? { provider: "profile" } : {}) },
+    provider: concreteProvider(input.provider) ?? profileProviderPin(profileEntry), model: input.model, effort: input.effort, dispatchPin: input.dispatchPin,
+    dispatchShape: input.dispatch ?? linkedTask?.dispatch ?? profileSpawnDefaults.dispatch, orchestratorId: input.orchestratorId, avoidProviders: input.avoidProviders, projectRole, providerArgs: input.providerArgs,
+    anchorProviders: autoHostAnchor?.providers, taskId: input.taskId, spawnCap: { callerAgentId: caller?.id, attach: input.resumeWorkspace?.mode === "attach" },
+  });
+  const { provider: resolvedProvider, modelParams, catalog: providerCatalog } = launch;
+  const taskDispatchDecision = launch.decision;
+  const launchMode = resolveSpawnLaunchMode(resolvedProvider, input.launchMode, input.providerArgs);
+  const selfEffort = resolveSpawnSelfEffortDefault(input, resolvedProvider, modelParams.model, providerCatalog, modelParams.effort);
+  // #324 — agent/task spawns default to isolated; resolve before applying host placement policy.
+  const workspaceMode = input.workspaceMode ?? projectRole?.workspace?.mode ?? (callerId || input.taskId !== undefined || shouldAutoScaffoldTask(input, profileName) ? ("isolated" as WorkspaceMode) : undefined);
+  // Stamp the explicit block into trusted spawn params and the prospective identity; a caller cannot lift a role's floor.
+  const landBlockResolution = resolveSpawnLandBlocked({ explicit: (projectRole && profileSpawnDefaults.landBlocked) || (input.landBlocked ?? profileSpawnDefaults.landBlocked), isolated: workspaceMode === "isolated" });
+  // #3109 — a cwd Relay defaulted from the Task's repo names the repository, not a path on one host.
+  const repoSource = !input.orchestratorId && !input.cwd ? taskDefaultCwd : undefined;
+  const { orchestrator, placementReason, resolvedCwd, lazyRoot } = await selectSpawnCwdPlacement({
+    provider: resolvedProvider, orchestratorId: input.orchestratorId, requestedCwd: repoSource ? undefined : requestedCwd, repoSource,
+    resumeWorkspace: input.resumeWorkspace, caller, lineageMachine: lineageAgent?.machine,
+    callerCwd, allowedOrchestratorIds: ctx.constraints?.orchestrators,
+    shared: workspaceMode === "shared", workspaceMode, canLand: !landBlockResolution.landBlocked, model: modelParams.model, effort: modelParams.effort,
+  });
+
+  assertOrchestratorSupportsLaunchMode(orchestrator, launchMode, input.providerArgs);
+
+  // Resolve + validate the named agent profile server-side (was HTTP-only; the MCP path passed
+  // the name through unvalidated). Omitted profile uses Relay's spawn default so coordinator
+  // spawns still get the bundled Relay context/affordances. Explicit profile always wins.
+  let agentProfile = await withResolvedProvisioningAsync(profileEntry, resolvedProvider);
+  if (!agentProfile) throw new McpNotFoundError(profileNotFoundMessage(baseProfileName));
+  if (projectRole) agentProfile = projectRoleProfile(agentProfile, projectRole);
+
+  // Profile policy and current lineage determine the live spawn quota.
+  // Server/admin/dashboard tokens carry no caller identity → unrestricted by design.
+  const quota = liveSpawnQuota(caller, ctx.constraints);
+  const spawnQuota = callerId
+    ? { parentId: callerId, maxSpawnedAgents: governed ? Number.MAX_SAFE_INTEGER : quota, ...(governed ? { workflow: governed } : {}) }
+    : undefined;
+  // #2979 — gate on the orchestrator only, never the caller token's cwdPrefixes: a coordinator may
+  // spawn into any repo under the target host's baseDir (checked in selectSpawnCwdPlacement), which
+  // is the filesystem boundary on every host. The old same-host cwd check (#1018) blocked only
+  // same-host sibling repos while the same spawn pinned elsewhere passed.
+  assertResourceAllowed(ctx, { scope: "agent:write", resource: { orchestratorId: orchestrator.id } });
+
+  // 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 = lineageAgentId ?? input.requestedBy ?? ctx.actor.id;
+
+  // #405 — durable project binding: the project whose registered root contains the spawn cwd.
+  // Stamped on both the child token and an auto-scaffolded Task row so issueless spawned work
+  // stays filterable by project.
+  // Capture the registry state BEFORE auto-seeding. Project trust must not turn an
+  // unregistered cwd into an accepted root merely because this spawn happened to
+  // create one as a side effect.
+  if (!lazyRoot) await bindSpawnProjectCheckout(resolvedCwd, orchestrator.id, lineageAgentId, profileName);
+  const delegatedProjectId = await getGateway().read("spawnTree.validateTarget", { type: "agent.spawn", source: requestedBy, target: orchestrator.agentId ?? orchestrator.id,
+    params: { ...(maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents }), ...(budget ? { budget } : {}), spawnedBy: lineageAgentId, cwd: resolvedCwd, taskId: input.taskId, orchestratorId: orchestrator.id, profile: profileName, ...(input.workflowRunId ? { workflowRunId: input.workflowRunId } : {}) } });
+  if (lazyRoot && delegatedProjectId) throw new ValidationError("SPAWN_PROJECT_ROOT_MISSING: delegated launches require existing checkouts");
+  if (lazyRoot) await addProjectRootAsync(lazyRoot.projectId, lazyRoot.rootPath, { remoteUrl: lazyRoot.remoteUrl, ref: lazyRoot.ref, orchestratorId: orchestrator.id });
+  const registeredProjectBeforeAutoSeed = delegatedProjectId ? getProject(delegatedProjectId) : resolveProjectForCwd(resolvedCwd); let callerProject = registeredProjectBeforeAutoSeed;
+  try {
+    const seeded = delegatedProjectId ? undefined : await autoSeedProjectForCwdAsync(resolvedCwd, requestedBy);
+    callerProject = seeded?.project ?? callerProject;
+    if (seeded?.ingestError) {
+      console.warn(`project auto-seed failed to ingest CLAUDE.md for ${resolvedCwd}: ${seeded.ingestError.message}`);
+    }
+  } catch (err) {
+    if (!callerProject) console.warn(`project auto-seed skipped for ${resolvedCwd}: ${errMessage(err)}`);
+  }
+
+  if (shouldAutoScaffoldTask(input, profileName)) {
+    const brief = spawnBrief(input)!;
+    linkedTask = createTaskEntity({
+      title: taskTitleFromBrief(brief, input.label),
+      intent: brief,
+      latestSteer: input.steer,
+      createdBy: requestedBy,
+      source: "spawn",
+      target: requestedBy,
+      // #889 — ephemeral spawn: done when the worker exits, not when a deliverable lands.
+      doneWhen: "agent-exit",
+      ...(callerProject ? { projectId: callerProject.id, repo: callerProject.issueRepo } : {}),
+    });
+    input = { ...input, taskId: linkedTask.id };
+    autoScaffoldedTask = { id: linkedTask.id, autoScaffolded: true, nudge: AUTO_SCAFFOLD_TASK_NUDGE };
+  }
+
+  // #838 — spawn-with-task hydration. When a taskId is given, relay assembles the worker's
+  // first-turn context FROM the durable Task (intent + linked-issue spec/acceptance + recorded
+  // decisions + history + latest steer), resolved server-side ONCE, and projects it onto the
+  // provider-appropriate channel (Claude → systemPromptAppend; Codex/other → first message).
+  // Caller prompt is not re-appended after hydration: auto-scaffolded prompt is already the Task
+  // intent, and explicit task spawns should use taskId + steer as their single instruction source.
+  // Absent (no taskId) = byte-identical to today: raw prompt/system append pass through.
+  let resolvedSystemPromptAppend = input.systemPromptAppend;
+  let resolvedPrompt = input.prompt;
+  let hydratedTask: Awaited<ReturnType<typeof hydrateTaskContext>> | undefined;
+  if (input.taskId !== undefined) {
+    hydratedTask = await hydrateTaskContext({ taskId: input.taskId, steer: input.steer });
+    const projection = projectTaskHydration(
+      resolvedProvider,
+      hydratedTask.context,
+      hydratedTask.steer,
+      input.systemPromptAppend,
+      input.taskId,
+    );
+    resolvedSystemPromptAppend = projection.systemPromptAppend;
+    resolvedPrompt = projection.prompt;
+  }
+
+  const resolvedLabel = taskSpawnLabel(linkedTask, input.label);
+
+  // #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 approvalMode = resolveSpawnApprovalMode(resolvedProvider, input.approvalMode, caller?.meta?.approvalMode as SpawnApprovalMode | undefined, lineageAgent?.meta?.approvalMode as SpawnApprovalMode | undefined, input.taskId !== undefined, agentProfile.permissions?.mode);
+
+  const lifecycle = input.lifecycle ?? profileSpawnDefaults.lifecycle ?? "persistent"; const systemTags = systemTagsForSpawn({ profile: profileName, requestedVia: input.requestedVia, requestedBy: input.requestedBy });
+  const acquisition = callerProject ? acquisitionManifestFor(callerProject.id, resolvedCwd) : undefined;
+  if (workspaceMode === "isolated" && (input.taskId !== undefined || input.workspaceMode === "isolated")) {
+    if (!acquisition && !orchestrator.apiUrl) await assertIsolatedSpawnHasGitRepo(resolvedCwd);
+  }
+
+  const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
+  const targetAgentId = generateSpawnAgentId();
+
+  // G3 GAP1 (#2073 Opus review): content review reads `resolvedCwd` off THIS relay process's own
+  // disk. That's only trustworthy when the spawn's target orchestrator actually shares this
+  // filesystem — a remote orchestrator's host can coincidentally have the same path with
+  // DIFFERENT content, so the gate is told explicitly rather than inferring from path existence.
+  if (agentProfile.sources?.project) agentProfile = applyProjectCapabilityGates(agentProfile, resolvedCwd, registeredProjectBeforeAutoSeed, { orchestratorLocal: isOrchestratorLocalToRelay(orchestrator), ...(projectRole ? { pinnedMcpCommit: projectRole.source.sha } : {}) });
+  if (projectRole) assertProjectRoleMcpTrusted(projectRole, agentProfile);
+
+  // N7 — project hooks/MCP are executable code and are gated against the project
+  // source matrix plus the pre-existing project-root registry. The helper stamps
+  // only this in-flight profile; persisted profile data is never rewritten here.
+  // #689 — shared host-listener MCP defaults on only for profiles that would otherwise receive
+  // host non-identity MCP. Per-spawn false and the global env kill-switch force direct MCP.
+  // Explicit opt-in still works for zero-host profiles.
+  agentProfile = applyDefaultSharedMcp(agentProfile, projectRole ? false : input.sharedMcp);
+  if (input.harnessSubagents !== undefined) agentProfile = { ...agentProfile, harnessSubagents: input.harnessSubagents };
+
+  // #635 — validate and enrich resumeWorkspace before dispatching to the orchestrator.
+  // The relay has the workspace DB records; the orchestrator has disk access. We do the
+  // "is this a real managed workspace and is it free?" check here, the orchestrator
+  // does the "does the worktree actually exist on disk?" check in resolveSpawnWorkspace.
+  if (input.resumeWorkspace) {
+    const { branch, mode } = input.resumeWorkspace;
+    const existingWs = listWorkspaces().find(
+      (ws) => ws.branch === branch && ws.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(ws.status),
+    );
+    if (!existingWs || !existingWs.worktreePath) {
+      throw new ValidationError(`resumeWorkspace: no active isolated workspace found for branch "${branch}"`);
+    }
+    if (mode === "attach") {
+      // #2614 — attach genuinely reuses THIS worktree, so the same-host base-dir requirement is
+      // correct: keep the original-worktree check (plus the liveness guards) attach-only.
+      if (!isPathWithinBase(existingWs.worktreePath, orchestrator.baseDir)) {
+        throw new ValidationError(`resumeWorkspace: worktree "${existingWs.worktreePath}" is outside orchestrator base dir "${orchestrator.baseDir}"`);
+      }
+      if (isOwnerAlive(existingWs.ownerAgentId)) {
+        throw new ValidationError(`resumeWorkspace: workspace owner "${existingWs.ownerAgentId}" is still alive — cannot double-attach`);
+      }
+      if (worktreeInUseByLiveAgent(existingWs.worktreePath, liveAgentCwds())) {
+        throw new ValidationError(`resumeWorkspace: worktree "${existingWs.worktreePath}" is still in use by a live agent`);
+      }
+    } else {
+      // #2614 — branch-from materializes a FRESH worktree off origin/<branch> under the TARGET
+      // orchestrator's base dir, so the ORIGINAL worktree's path (on its creating host) must not
+      // gate the spawn. This relay-side target-placement check is a CHEAP EARLY HINT only; the
+      // AUTHORITATIVE containment guard is the orchestrator's materialization seam (#2614 review).
+      assertBranchFromTargetPlacementWithinBase({ baseDir: orchestrator.baseDir, repoRoot: findGitRepoRoot(resolvedCwd), spawnRequestId, label: resolvedLabel, policyName: input.policyName });
+    }
+    // Enrich with relay-resolved fields the orchestrator needs.
+    input.resumeWorkspace = {
+      branch,
+      mode,
+      worktreePath: existingWs.worktreePath,
+      workspaceId: existingWs.id,
+      baseRef: existingWs.baseRef,
+      baseSha: existingWs.baseSha,
+    };
+  }
+
+  // #3107 — the lineage coordinator's active team; a coordinator takes its project's seat, never a dissolved id.
+  const callerTeam = lineageAgentId ? acquireCoordinatorTeam(lineageAgentId) : undefined;
+  const privateTeamId = profileName === "sub-coordinator" ? newTeamId() : undefined;
+  const launchTeamId = privateTeamId ?? callerTeam?.id;
+
+  // #409 + #463 + #557 — the instruction-sources half of the launch-assembly contract.
+  // composeSpawnInstructions is the single home that composes the prompt material handed to
+  // providers (project preamble → profile system → profile append → caller/fork context) and
+  // carries the #559 scoped-knowledge seam. Spawns without profile/project material stay
+  // byte-identical to the caller-provided systemPromptAppend.
+  const projectInstructionsEnabled = projectMemoryEnabledForProfile(profileName, agentProfile ?? undefined);
+  // #559 — resolve the child's {profile|user} memory stores READ-ONLY (never create an empty
+  // anchor just by spawning). The profile store is keyed on the resolved profile name; the user
+  // store on the spawn-chain operator (the requesting agent's owner, else the default operator).
+  // Both resolve null until someone has actually written to them, so a fresh deployment stays
+  // byte-identical. Injection of their active (promoted) entries happens in the composer.
+  const sessionUserId = actingUserIdOf(ctx);
+  // #3567 D5 — principal (= memory operator): the signed-in spawner, else the spawner agent's, else default.
+  const operatorId = sessionUserId ?? (lineageAgentId ? (await resolveAgentOwnershipAsync(lineageAgentId)).ownerUserId : DEFAULT_USER_ID);
+  // #1383/#1385 — the injected identity must describe what THIS agent will actually be, not the
+  // coordinator/no-workspace defaults the whoami DB projection falls back to before any workspace row
+  // exists. resolveProspectiveWorkspaceIdentity mirrors the orchestrator's mode resolution and pins an
+  // isolated worker's cwd AND repoRoot to its own worktree (so absolute paths it derives never edit main).
+  let gitRepoRoot = input.resumeWorkspace?.mode === "attach" ? input.resumeWorkspace.worktreePath! : findGitRepoRoot(resolvedCwd);
+  if (input.resumeWorkspace?.mode !== "attach" && (workspaceMode === "isolated" || (workspaceMode !== "shared" && input.policyName))) gitRepoRoot = await resolveSpawnRepoRoot(orchestrator, resolvedCwd, acquisition?.rootPath, workspaceMode === "isolated");
+  const wsIdentity = resolveProspectiveWorkspaceIdentity({
+    baseDir: orchestrator.baseDir,
+    sourceCwd: resolvedCwd,
+    gitRepoRoot,
+    workspaceMode,
+    policyName: input.policyName,
+    spawnRequestId,
+    label: resolvedLabel,
+    // #2033 review BLOCKER 2 — only "attach" actually runs the child IN the resumed worktree
+    // (orchestrator/src/workspace-probe/probe.ts's `resolveSpawnWorkspace`). "branch-from" creates a
+    // FRESH worktree off the resumed branch's HEAD, at the SAME deterministic path a plain isolated
+    // spawn would get (keyed on THIS spawn's own spawnRequestId, never the resumed one) — passing the
+    // resumed worktreePath here for branch-from would widen the child's token to a DIFFERENT (and
+    // possibly still-live) agent's worktree it never runs in. Omitting it for branch-from falls
+    // through to the same fresh-placement branch below that an ordinary isolated spawn takes.
+    ...(input.resumeWorkspace?.mode === "attach" ? { resumeWorktreePath: input.resumeWorkspace.worktreePath } : {}),
+    resumeBranch: input.resumeWorkspace?.branch,
+    landStrategy: input.landStrategy,
+    profileLandingStrategy: agentProfile?.landingStrategy,
+    defaultLandStrategy: getLandingConfig().strategy, systemTags,
+  });
+  if (projectRole) assertProjectRoleMcpCwd(projectRole, wsIdentity.cwd);
+  const identitySpawner: WhoamiSpawner | undefined = lineageAgentId
+    ? { kind: "agent", id: lineageAgentId }
+    : sessionUserId ? { kind: "user", id: sessionUserId }
+    : ctx.actor.kind === "user" ? { kind: "user", id: requestedBy } : undefined;
+  // #1608 — the SAME resolution `memoryIdentityForAgent` uses at clear/compact re-injection, so
+  // the two seams render byte-identical `MemoryIdentity.host` for the same agent.
+  const canonicalHost = resolveCanonicalHost(orchestrator.hostname) ?? orchestrator.hostname;
+  const targetIdentity = buildProspectiveSpawnIdentity({
+    agentId: targetAgentId,
+    provider: resolvedProvider,
+    label: resolvedLabel,
+    tags: input.tags ?? [], systemTags,
+    capabilities: input.capabilities ?? [],
+    machine: canonicalHost,
+    cwd: wsIdentity.cwd,
+    repoRoot: wsIdentity.repoRoot,
+    workspaceMode: wsIdentity.mode,
+    ...(wsIdentity.branch ? { workspaceBranch: wsIdentity.branch } : {}),
+    lifecycle,
+    profileName,
+    modelParams,
+    approvalMode,
+    spawnRequestId,
+    policyName: input.policyName,
+    spawnedBy: lineageAgentId,
+    teamId: launchTeamId,
+    taskId: input.taskId,
+    agentProfile,
+    role: profileName === "sub-coordinator" ? "coordinator" : wsIdentity.role,
+    // #1482 — a landBlocked worker's projected capability tells the truth: capability stays high, but
+    // canLand is false (the whoami prose the reviewer sees now matches the structural enforcement).
+    canLand: wsIdentity.canLand && !landBlockResolution.landBlocked,
+    landStrategy: wsIdentity.landStrategy,
+    ...(identitySpawner ? { spawner: identitySpawner } : {}),
+  });
+  // #2171 — AWAITED: the land-gates config behind the validation preamble is read from
+  // `canonicalHost`'s disk, which for a remote orchestrator means an HTTP read through that host.
+  // The synchronous composer could only serve a cached answer, so a remote host's FIRST spawn would
+  // get no validation block at all.
+  const composedInstructions = await composeSpawnInstructionsWithEventsAsync({
+    projectInstructionsEnabled,
+    ...(resolvedCwd ? { cwd: resolvedCwd } : {}),
+    // The machine the agent will run on — whose `.agent-relay/land-gates.json` is the authoritative
+    // one. Not the relay's, which may hold a coincidentally same-path stale checkout. The read is
+    // recorded against the WORKTREE too (#2171 F1): an isolated agent is recorded at `wsIdentity.cwd`,
+    // so that is the cwd every later re-injection looks it up by.
+    host: canonicalHost, agentRuntimeCwd: wsIdentity.cwd,
+    // #1565 P4 — WHO this agent is, for the unified memory preamble (base → provider → host →
+    // project, audience-filtered by profile). Resolved at spawn, never asked for.
+    memoryIdentity: { operator: operatorId, provider: resolvedProvider, host: canonicalHost, profile: profileName, ...(callerProject ? { projectId: callerProject.id } : {}) },
+    ...(agentProfile ? { profile: agentProfile } : {}),
+    ...(lineageAgentId ? { spawnedBy: lineageAgentId } : {}), ...(selfEffort ? { selfEffort: true } : {}), ...(input.workflowRunId ? { workflowRunId: input.workflowRunId } : {}),
+    agentRelayIdentity: targetIdentity,
+    ...(resolvedSystemPromptAppend ? { callerSystemPromptAppend: resolvedSystemPromptAppend } : {}),
+  });
+  const systemPromptAppend = composedInstructions.systemPromptAppend;
+  // TODO(#569): comms:delivered emitter — deferred, lives on the #575 delivery path.
+
+  // #2033 — an isolated worker's runner process actually runs inside the worktree the orchestrator
+  // creates, not `resolvedCwd` (the source checkout the spawn was requested from). Without this, an
+  // agent-initiated command (relay_schedule_timer{command}) targeting the worker's own cwd either
+  // 403s (worktree outside cwdPrefixes) or silently defaults onto the source checkout. See
+  // `isolatedWorktreeCwdPrefixes` for why widening to this server-derived path is contained.
+  const extraCwdPrefixes = isolatedWorktreeCwdPrefixes(wsIdentity, resolvedCwd);
+
+  // 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 = { ...callerEnv, ...runnerRuntimeTokenEnv({
+    agentId: targetAgentId,
+    orchestratorId: orchestrator.id,
+    cwd: resolvedCwd,
+    provider: resolvedProvider,
+    label: resolvedLabel,
+    policyName: input.policyName,
+    spawnRequestId,
+    taskId: input.taskId,
+    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).
+    // #2245 — `approvalMode` is the EFFECTIVE posture resolved above (explicit, else inherited);
+    // stamped into the signed constraints so the scheduler background-command path can honor `open`
+    // without ever trusting the caller-writable `agent.meta.approvalMode`.
+    profile: profileName, approvalMode, maxSpawnedAgents,
+    ...(lineageAgentId ? { spawnedBy: lineageAgentId } : {}),
+    ...(launchTeamId ? { teamId: launchTeamId } : {}),
+    ...(callerProject ? { projectId: callerProject.id } : {}),
+    hostPinned: input.hostPinned === true || hostPinForProfile(input.profile ?? profileName),
+    // #1259-followup — the caller's own scopes bound what the child may hold (no privilege amplification
+    // through spawn); #3110 review — they become the provenance its restarts are bounded by.
+    authority: { kind: "delegated", callerScopes: ctx.scopes, agentInitiated: Boolean(lineageAgentId) },
+    ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
+  }) };
+
+  // #2095 self-compact e2e test rig — thread the forced-context lever into the child runner env. Kept
+  // as the single env var the runner reads (see forceContextPctFromEnv); absent when the caller omits
+  // forceContextPct, so a normal spawn's env is byte-identical to before.
+  if (input.forceContextPct !== undefined) {
+    writeChildEnv(env, { "AGENT_RELAY_FORCE_CONTEXT_PCT": String(input.forceContextPct) });
+  }
+
+  // #573 — no default reply obligation for spawned children. Report-up is lineage-routed from
+  // captured turn-final responses; explicit true is retained only for old clients inspecting the
+  // command payload.
+  const expectReply = input.expectReply === true;
+
+  const apiExpiryLeadTimeMs = resolvedProvider === "claude-api" && taskDispatchDecision?.factors.apiExpiry?.selected ? taskDispatchDecision.factors.apiExpiry.leadTimeMs : undefined;
+  const commandInput: CreateCommandInput = {
+    type: "agent.spawn",
+    source: "system",
+    target: orchestrator.agentId,
+    correlationId: spawnRequestId,
+    params: buildSpawnCommand({
+      provider: resolvedProvider,
+      modelParams,
+      cwd: resolvedCwd,
+      ...(workspaceMode ? { workspaceMode } : {}),
+      lifecycle,
+      label: resolvedLabel,
+      agentId: targetAgentId,
+      profile: profileName,
+      agentProfile,
+      harnessSubagents: input.harnessSubagents,
+      tags: input.tags ?? [],
+      systemTags,
+      capabilities: input.capabilities ?? [],
+      approvalMode,
+      permissionMode: approvalMode,
+      providerArgs: input.providerArgs ?? [],
+      launchMode,
+      prompt: resolvedPrompt,
+      systemPromptAppend,
+      // #1062 — stash the RAW caller brief (pre-composition) so a dashboard (non-policy) restart can
+      // re-thread it as callerSystemPromptAppend and stay fresh-spawn-identical instead of dropping it.
+      ...(resolvedSystemPromptAppend ? { callerSystemPromptAppend: resolvedSystemPromptAppend } : {}),
+      relayInjectionEvents: composedInstructions.relayInjectionEvents,
+      // #1625 — stamp the memory identity this spawn composed from into immutable params. The host
+      // cell was previously re-derived from the agent's raw reported `machine` instead of the
+      // orchestrator hostname resolved here. Later seams replay this identity; #2134 derives
+      // Project memory inclusion from its current profile rather than persisting an override.
+      ...(composedInstructions.memorySeam ? { memorySeam: composedInstructions.memorySeam } : {}),
+      landStrategy: input.landStrategy,
+      landMechanism: input.landMechanism,
+      autoMerge: input.autoMerge,
+      reviewer: input.reviewer,
+      // #1482 — stamp the server-resolved no-land flag into the IMMUTABLE spawn command params. The
+      // workspace row derives ws.metadata.landBlocked from here on every heartbeat (a trusted read
+      // that an agent-reported heartbeat can't clear), making the guardrail durable + multi-host-safe.
+      ...(landBlockResolution.landBlocked ? { landBlocked: true, landBlockedReason: landBlockResolution.reason } : {}),
+      selfEffort,
+      taskId: input.taskId,
+      resumeWorkspace: input.resumeWorkspace,
+      acquisition,
+      ...(expectReply ? { expectReply } : {}),
+      reportVerbosity: resolveReportVerbosity({ reportVerbosity: optionalEnum(input.reportVerbosity, "reportVerbosity", REPORT_VERBOSITIES), profile: profileName, budget, canSpawn: spawnGrantForProfile(profileName).canSpawn }),
+      policyName: input.policyName,
+      ...(projectRole ? { projectRole: projectRoleProvenance(projectRole) } : {}), workflowRunId: input.workflowRunId,
+      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.
+      // #3567 — registration writes agent_ownership from this; the default admin needs no row.
+      extra: { ...(maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents }), ...(operatorId !== DEFAULT_USER_ID ? { principalUserId: operatorId } : {}), ...(budget ? { budget } : {}), ...(privateTeamId ? { privateTeamId } : {}), ...(lineageAgentId ? { spawnedBy: lineageAgentId } : {}), ...(apiExpiryLeadTimeMs !== undefined ? { apiExpiryLeadTimeMs } : {}), ...(taskDispatchDecision ? { dispatchDecision: taskDispatchDecision } : {}) },
+    }),
+  };
+  // #2694/#2702 — the host agent cap is enforced at the command seam, atomically with the INSERT.
+  // Attach-resume is exempt: the worktree already lives on that host, so there is nowhere else to go.
+  const hostCap = {
+    ...(input.resumeWorkspace?.mode === "attach" ? { exempt: "attach-resume" as const } : {}),
+    ...(callerId ? { callerAgentId: callerId } : {}),
+  };
+  const reserved = await createSpawnCommandWithinQuotaAsync(commandInput, spawnQuota, hostCap, requestedBy, ctx.constraints?.projectId);
+  if (!reserved.command) {
+    throw new ValidationError(`spawn quota reached (${reserved.occupiedSlots}/${spawnQuota?.maxSpawnedAgents} live or in-flight children) — shut one down or wait for one to exit`);
+  }
+  // #3327 — a concurrent attempt lost the admission race: return the winner's command and decision.
+  if (reserved.replayed) return spawnReplay(reserved.command, reserved.registeredAgentId ? getAgent(reserved.registeredAgentId) ?? undefined : undefined);
+  const command: Command = reserved.command;
+  if (privateTeamId) await (await import("./workflow-supervisor")).ensureSupervisor();
+  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).
+  // Command dispatch is already durable. A writer ACK-loss may reject even though this audit commit
+  // landed; never turn that post-dispatch uncertainty into a retryable spawn failure (double-spawn).
+  try {
+    await createActivityEventAsync({
+      clientId: `server-agent-spawn-${resolvedProvider}-${command.id}`,
+      kind: "state",
+      title: `${resolvedProvider} agent spawn requested (via ${orchestrator.id})`,
+      body: resolvedCwd,
+      meta: orchestrator.id,
+      icon: "ti-plus",
+      view: "agents",
+      metadata: {
+        provider: resolvedProvider,
+        orchestratorId: orchestrator.id,
+        approvalMode,
+        launchMode: launchMode ?? null,
+        lifecycle,
+        workspaceMode: workspaceMode ?? null,
+        label: resolvedLabel ?? null,
+        commandId: command.id,
+        spawnRequestId,
+        requestedVia: input.requestedVia ?? null,
+        actor: requestedBy,
+        actorKind: ctx.actor.kind,
+      },
+    });
+  } catch (error) { console.error("spawn activity audit failed after command dispatch", error); }
+
+  // #838 — record the spawn on the Task FOR attribution, keyed on spawnRequestId. Done now (not
+  // after registration) so even a fire-and-forget spawn leaves the durable hook #831 reads to
+  // drive one-shot reap. Best-effort: an attribution write never fails the spawn.
+  if (input.taskId !== undefined) {
+    try {
+      // The audit above crossed the writer boundary. Re-read the Task before its follow-on
+      // attribution so a concurrent steer edit cannot be written back as this spawn's snapshot.
+      const currentTask = await getTaskEntityAsync(input.taskId);
+      // #3327 — the Task's decision is the admitted one, whoever planned it.
+      if (taskDispatchDecision) {
+        await recordTaskEntityDispatchDecisionAsync(input.taskId, {
+          decision: taskDispatchDecision,
+          source: input.dispatchPin ? "dispatch" : "spawn",
+          actor: requestedBy,
+        });
+      }
+      await recordTaskSpawnRequestedAsync(input.taskId, {
+        spawnRequestId,
+        provider: resolvedProvider,
+        requestedBy,
+        ...(currentTask?.latestSteer ? { steer: currentTask.latestSteer } : {}),
+      });
+      autoSubscribeTaskCoordinator(requestedBy, input.taskId);
+    } catch (err) {
+      console.warn(`task ${input.taskId} spawn attribution skipped: ${errMessage(err)}`);
+    }
+  }
+
+  // #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,
+    placementReason,
+    provider: resolvedProvider,
+    agentId,
+    registered: agentId !== null,
+    harnessSubagents: agentProfile.harnessSubagents === true,
+    command,
+    ...(input.taskId !== undefined ? { taskId: input.taskId } : {}),
+    ...(autoScaffoldedTask ? { task: autoScaffoldedTask } : {}),
+    ...(taskDispatchDecision ? { dispatchDecision: taskDispatchDecision } : {}),
+    ...(warnings.length ? { warnings } : {}),
+  };
+}
+
+/**
+ * #734 — strip the heavy resolved-provisioning file CONTENTS from a spawn command before
+ * echoing it back to the CALLER. `withResolvedProvisioning` inlines every bundled plugin/skill
+ * file under `params.agentProfile.provisioning.{skills,plugins}[].files[].content` (~90KB for a
+ * bundled-plugin profile like default-relay), which blows the MCP result token cap and hard-errors
+ * the call. The ORCHESTRATOR-bound command — dispatched on the command bus inside `spawnAgent`
+ * (the row in `listCommands`, not this returned object) — keeps the full bytes so it can still
+ * materialize the plugins on the target host. This returns a structural summary (paths + byte
+ * counts, contents dropped) leaving the dispatched command untouched (the mutated path is
+ * shallow-cloned, never mutated in place).
+ */
+export function summarizeSpawnCommandForCaller(command: Command): Command {
+  // #T764 F2 — the spawn RESPONSE (HTTP agents-spawn, MCP tools-spawn verbose, team-template tools)
+  // must never echo the child's live AGENT_RELAY_TOKEN back to the caller. Redact secret-shaped env
+  // values first — same masking the commands read path applies to a non-orchestrator caller (#1300).
+  // The DISPATCHED command row (the one the orchestrator polls) is untouched: redactCommandSecrets
+  // deep-copies params, and we only ever return the copy.
+  const redacted = redactCommandSecrets(command);
+  const profile = redacted.params.agentProfile;
+  if (!isRecord(profile) || !isRecord(profile.provisioning)) return redacted;
+  const provisioning = profile.provisioning;
+  const stripContents = (assets: unknown): unknown => {
+    if (!Array.isArray(assets)) return assets;
+    return assets.map((asset) => {
+      if (!isRecord(asset) || !Array.isArray(asset.files)) return asset;
+      return {
+        ...asset,
+        files: asset.files.map((file) =>
+          isRecord(file) && typeof file.content === "string"
+            ? { path: file.path, contentBytes: file.content.length }
+            : file,
+        ),
+      };
+    });
+  };
+  return {
+    ...redacted,
+    params: {
+      ...redacted.params,
+      agentProfile: {
+        ...profile,
+        provisioning: {
+          ...provisioning,
+          skills: stripContents(provisioning.skills),
+          plugins: stripContents(provisioning.plugins),
+          hooks: stripContents(provisioning.hooks ?? []),
+        },
+      },
+    },
+  };
+}
+
+/** 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()))));
+  }
+}