agent-relay-server 0.32.3 → 0.33.0

package/src/config-store.ts

@@ -469,17 +469,21 @@ function validateInsightsConfig(value: unknown): InsightsConfig {
 const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
   enabled: true,
   branchLanded: true,
+  agentReady: true,
+  agentExited: true,
+  agentSpawnFailed: true,
 };
 
 function validateNotificationsConfig(value: unknown): NotificationsConfig {
   if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
+  const bool = (key: keyof NotificationsConfig): boolean =>
+    value[key] === undefined ? NOTIFICATIONS_CONFIG_DEFAULTS[key] : cleanBoolean(value[key], key);
   return {
-    enabled: value.enabled === undefined
-      ? NOTIFICATIONS_CONFIG_DEFAULTS.enabled
-      : cleanBoolean(value.enabled, "enabled"),
-    branchLanded: value.branchLanded === undefined
-      ? NOTIFICATIONS_CONFIG_DEFAULTS.branchLanded
-      : cleanBoolean(value.branchLanded, "branchLanded"),
+    enabled: bool("enabled"),
+    branchLanded: bool("branchLanded"),
+    agentReady: bool("agentReady"),
+    agentExited: bool("agentExited"),
+    agentSpawnFailed: bool("agentSpawnFailed"),
   };
 }
 

package/src/maintenance.ts

@@ -33,6 +33,8 @@ import {
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { reconcileLandedWorkspace } from "./branch-landed";
+import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
 import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
@@ -251,6 +253,9 @@ const definitions: MaintenanceJobDefinition[] = [
       for (const id of reapedAgentIds) {
         emitAgentStatus(id);
         getLifecycleManager().onAgentDisappeared(id);
+        // #308 — if a reaped agent was a spawned child, wake its parent: exited (it had become
+        // ready) vs spawn_failed (it never did — crash-loop / onboarding gate). No-op otherwise.
+        notifyAgentOffline(id, "heartbeat lost");
         createActivityEvent({
           clientId: "server-agent-" + id + "-heartbeat-lost-" + Date.now(),
           kind: "state",
@@ -434,8 +439,11 @@ function workspacePathWithinBase(path: string | undefined, baseDir: string | und
   return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
 }
 
-async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord): Promise<WorkspaceMergePreview | { available: false } | null> {
-  const query = new URLSearchParams({ path: workspace.worktreePath, checkPr: "1" });
+async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord, opts: { checkPr?: boolean } = {}): Promise<WorkspaceMergePreview | { available: false } | null> {
+  // `checkPr` costs a `gh` round-trip, so the caller opts in only where PR-merge ground
+  // truth is actionable (reconcile/land candidates), not for every badge-probe (#304).
+  const checkPr = opts.checkPr !== false;
+  const query = new URLSearchParams({ path: workspace.worktreePath, ...(checkPr ? { checkPr: "1" } : {}) });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
@@ -577,10 +585,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
-    const preview = await fetchHostMergePreview(orch.apiUrl, ws);
+    // Spend the `gh` PR-state round-trip only on reconcile-eligible rows; active/ready
+    // are excluded from reconcile, so their scan stays git-only (#304).
+    const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: LANDED_RECONCILE_STATUSES.has(ws.status) });
     if (!preview || (preview as { available?: false }).available === false) continue;
     const p = preview as WorkspaceMergePreview;
-    if (p.error || p.missing || p.conflict === undefined) continue;
+    if (p.error || p.missing) continue;
 
     const meta = ws.metadata as Record<string, unknown>;
 
@@ -605,29 +615,23 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     // merge_planned forever otherwise, and the conflict scan can even pin a
     // landed branch to `conflict`). Reconcile to the terminal `merged` status so
     // the dashboard stops showing it as unmerged and GC prunes it on schedule.
+    // This runs BEFORE the conflict-undefined skip below: a PR merged via a regular
+    // merge commit makes the branch an ancestor (ahead=0 → no-op → conflict comes
+    // back undefined), which the skip would otherwise drop, stranding the row at
+    // merge_planned — the exact #304 stall.
+    // Reconcile + finalize (record SHA, fire branch.landed) in branch-landed.ts so the
+    // giant doesn't grow (#291) and land-notify stays single-homed (#304).
     const landed = p.landed === true || p.prMerged === true;
     if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
-      updateWorkspaceStatus(ws.id, "merged", {
-        autoMerged: true,
-        mergedFromStatus: ws.status,
-        landedDetectedAt: Date.now(),
-        landedVia: p.prMerged === true ? "pr" : "git",
-        autoConflict: false,
-      });
+      reconcileLandedWorkspace(ws, p);
       merged.push(ws.id);
-      createActivityEvent({
-        clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
-        kind: "state",
-        title: "Workspace work landed in base",
-        body: `${ws.branch ?? ws.id} is ${p.prMerged === true ? "merged on the remote (PR)" : "already merged into base"} ${p.baseRef ? `(${p.baseRef})` : ""} — marking merged`,
-        meta: ws.branch ?? ws.id,
-        icon: "ti-git-merge",
-        view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status },
-      });
       continue;
     }
 
+    // Past here we act on the conflict signal — skip when the host couldn't assess it
+    // (undefined): never flag/clear a conflict on incomplete data.
+    if (p.conflict === undefined) continue;
+
     if (p.conflict === true && ws.status !== "conflict") {
       updateWorkspaceStatus(ws.id, "conflict", {
         autoConflict: true,

package/src/mcp-errors.ts

@@ -0,0 +1,7 @@
+// Typed MCP errors shared between the MCP endpoint (src/mcp.ts) and the spawn-target
+// selection it delegates (src/spawn-targets.ts). callTool maps these to JSON-RPC error
+// codes + HTTP statuses (auth → 403/-32001, not-found → 404/-32004, else 400/-32602).
+// Kept in their own module so spawn-targets.ts can throw them without importing mcp.ts
+// (which would be a cycle: mcp.ts → spawn-targets.ts → mcp.ts).
+export class McpAuthError extends Error {}
+export class McpNotFoundError extends Error {}

package/src/mcp.ts

@@ -8,6 +8,8 @@ import { listManagedOrchestratorsForAgent } from "./orchestrator-lookup";
 import { bytesToStream, readBodyBytes } from "./http-body";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "./config-store";
+import { buildSpawnTargets, selectSpawnOrchestrator, spawnCapablePrimer } from "./spawn-targets";
+import { McpAuthError, McpNotFoundError } from "./mcp-errors";
 import {
   countLiveSpawnedAgents,
   createArtifact,
@@ -45,7 +47,7 @@ import {
   isIntegrationAllowed,
 } from "./security";
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
-import { applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
+import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
@@ -274,6 +276,16 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_spawn_targets",
+    description: "Return the LIVE spawn capability matrix before you spawn: which orchestrators/hosts are online, which providers actually run on each (orchestrator-probed, not a static guess), each provider's models with per-model effort levels + defaults, your own host (isSelf) and remaining spawn quota, and named profiles you can spawn by role. Call this first whenever you decide to spawn — it removes the guesswork that otherwise only surfaces as a runtime rejection. Requires the command:spawn scope.",
+    requiredScopes: ["command:spawn"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_shutdown_agent",
     description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children. Admin tokens keep full reach.",
@@ -413,12 +425,18 @@ export async function postMcp(req: Request): Promise<Response> {
     if (method === "initialize") {
       // Mode-tailored primer (#214 §3): surface the worktree merge-back map only
       // to callers that own an isolated worktree; shared-workspace agents omit it.
+      // #308: append the spawn primer only when the token actually grants command:spawn —
+      // authoritative scope-gating, eager + thin, so non-spawn agents get nothing.
       const worktree = callerIsolatedWorkspace(auth);
+      const instructions = [
+        worktree ? worktreeMcpInstructions(worktree) : "",
+        spawnCapablePrimer({ canSpawn: hasAnyScope(auth, ["command:spawn"]), quota: auth.component?.constraints?.maxSpawnedAgents }),
+      ].filter(Boolean).join("\n\n");
       return Response.json(jsonRpcResult(id, {
         protocolVersion: MCP_PROTOCOL_VERSION,
         capabilities: { tools: {} },
         serverInfo: { name: "agent-relay", title: "Agent Relay", version: VERSION },
-        ...(worktree ? { instructions: worktreeMcpInstructions(worktree) } : {}),
+        ...(instructions ? { instructions } : {}),
       }));
     }
     if (method === "notifications/initialized") {
@@ -488,6 +506,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
     else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
+    else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
@@ -774,8 +793,10 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
   const preferHost = callerId ? getAgent(callerId)?.machine : undefined;
   const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd, preferHost);
   const resolvedCwd = cwd || orchestrator.baseDir;
+  // #308 §3 — cwd must resolve within the TARGET host's base dir. A path valid on your own host
+  // may not exist on a different orchestrator, so validate against the chosen host and say which.
   if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
-    throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
+    throw new ValidationError(`cwd '${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.`);
   }
   const selection = providerSelection(provider, args);
   const approvalMode = optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined ?? "guarded";
@@ -843,6 +864,9 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
       requestedVia: "mcp",
       requestedAt: Date.now(),
       orchestratorId: orchestrator.id,
+      // #308 — stamp the spawning parent so a failed agent.spawn command can be routed back to
+      // it (the child never registers, so there's no agent record to resolve `spawnedBy` from).
+      ...(callerId ? { extra: { spawnedBy: callerId } } : {}),
     }),
   });
   emitCommand(command);
@@ -1011,7 +1035,7 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
     action,
     agentId: callerAgentId(auth) ?? auth.actor,
     detail: optionalString(args.detail, "detail", 4000),
-    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const) as WorkspaceMergeStrategy | undefined) : undefined,
+    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", LAND_STRATEGIES) as WorkspaceMergeStrategy | undefined) : undefined,
     deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
     prTitle: optionalString(args.prTitle, "prTitle", 240),
     prBody: optionalString(args.prBody, "prBody", 8000),
@@ -1087,35 +1111,12 @@ function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolic
   };
 }
 
-export function selectSpawnOrchestrator(
-  provider: SpawnProvider,
-  orchestratorId?: string,
-  cwd?: string,
-  preferHost?: string,
-): NonNullable<ReturnType<typeof getOrchestrator>> {
-  if (orchestratorId) {
-    const orchestrator = getOrchestrator(orchestratorId);
-    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
-    if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
-    if (!orchestrator.providers.includes(provider)) throw new ValidationError(`orchestrator does not have provider available: ${provider}`);
-    return orchestrator;
-  }
-  const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
-  if (cwd) {
-    const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
-    if (match) return match;
-  }
-  // #255: with neither an explicit id nor a cwd to pin the host, default to the CALLER's own
-  // host instead of silently grabbing candidates[0] (a foreign host whose baseDir would then
-  // reject the caller's cwd — the footgun the spawn recipe warned about). An agent's `machine`
-  // is its OS hostname; match it against the orchestrator hostname (or id, defensively).
-  if (preferHost) {
-    const own = candidates.find((item) => item.hostname === preferHost || item.id === preferHost);
-    if (own) return own;
-  }
-  const orchestrator = candidates[0];
-  if (!orchestrator) throw new McpNotFoundError(`no orchestrator available for provider: ${provider}`);
-  return orchestrator;
+// #308 — thin auth wrapper over the spawn capability matrix (src/spawn-targets.ts owns the build).
+function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {
+  return buildSpawnTargets({
+    callerId: callerAgentId(auth),
+    quota: auth.component?.constraints?.maxSpawnedAgents ?? 0,
+  });
 }
 
 function selectControlOrchestrator(input: {
@@ -1396,6 +1397,3 @@ function optionalAttachments(value: unknown): AttachmentRef[] | undefined {
 function encodedLength(value: string): number {
   return new TextEncoder().encode(value).byteLength;
 }
-
-class McpAuthError extends Error {}
-export class McpNotFoundError extends Error {}

package/src/routes/agents-spawn.ts

@@ -1,6 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
-import { McpNotFoundError, selectSpawnOrchestrator } from "../mcp";
+import { McpNotFoundError } from "../mcp-errors";
+import { selectSpawnOrchestrator } from "../spawn-targets";
 import { VALID_AGENT_STATUSES, auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, metaString, parseBody, spawnRequestId, type Handler } from "./_shared";
 import { ValidationError, getAgent, getOrchestrator, listAgents, resolveQueuedPolicyMessages, upsertAgent } from "../db";
 import { buildSpawnCommand, resolveSpawnModelParams, type SpawnModelParams } from "../spawn-command";
@@ -8,6 +9,7 @@ import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optional
 import { createCommand } from "../commands-db";
 import { emitAgentStatus, emitManagedAgentStateChanged, emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
 import { getAgentProfile, getManagedAgentState, updateManagedAgentState } from "../config-store";
+import { notifyAgentReady } from "../agent-lifecycle-events";
 import { getCompactionWatch } from "../compaction-watch";
 import { getComponentAuth } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -98,6 +100,12 @@ export const postAgent: Handler = async (req) => {
       }
     }
     emitAgentStatus(agent.id);
+    // #308 — a spawned child registering already-ready (the common isolated-worktree case: it
+    // comes up ready+idle) is genuinely ready; wake its parent so it can stop block-polling.
+    // Fire on the first-ever ready (no prior record, or prior record wasn't ready yet) — the
+    // ready/false→true flip path is handled in patchAgentReady. notifyAgentReady no-ops for
+    // non-spawned agents and dedups repeats.
+    if (agent.ready && !existing?.ready) notifyAgentReady(agent.id);
     // A real PreCompact / SessionStart(clear) hook reports progress via the
     // agent's timelineEvent — clears any pending stall watch for this agent.
     // timelineEvent is latched, so pass its timestamp: only a fresh event

package/src/routes/agents.ts

@@ -5,6 +5,7 @@ import { attachBranchState, attachBranchStates } from "../agent-branch-state";
 import { cleanStringArray } from "../validation";
 import { clearActiveMemories, memoryBroker } from "../memory-service";
 import { emitAgentRemoved, emitAgentStatus } from "../sse";
+import { notifyAgentReady } from "../agent-lifecycle-events";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
 import { type AgentCard } from "../types";
@@ -231,6 +232,10 @@ export const patchAgentReady: Handler = async (req, params) => {
     const before = getAgent(params.id!);
     if (!markReady(params.id!, body.ready, guard)) return error("agent not found", 404);
     auditAgentStateTransition(params.id!, before, getAgent(params.id!));
+    // #308 — a spawned child flipping false→true ready is "genuinely ready" (past onboarding):
+    // wake its parent so it can stop block-polling. notifyAgentReady no-ops for non-spawned
+    // agents and dedups repeat readies.
+    if (body.ready && !before?.ready) notifyAgentReady(params.id!);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;

package/src/routes/commands.ts

@@ -11,6 +11,7 @@ import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
 import { isRequestAuthorizedFor } from "../security";
 import { notifyBranchLanded } from "../branch-landed";
+import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
@@ -298,6 +299,20 @@ export const patchCommand: Handler = async (req, params) => {
         patchWorkspaceMetadata(workspaceId, { lastDepsRefresh: command.result, lastDepsRefreshCommandId: command.id, lastDepsRefreshAt: Date.now() });
       }
     }
+    // #308 — a failed agent.spawn command never produces a child agent, so route the failure
+    // straight to the spawning parent stamped on the command (provider unavailable, bad cwd,
+    // launch error). The never-became-ready crash-loop case is covered separately by the reaper.
+    if (command.type === "agent.spawn" && command.status === "failed") {
+      const parent = isRecord(command.params) ? cleanString(command.params.spawnedBy, "params.spawnedBy", { max: 240 }) : undefined;
+      if (parent) {
+        notifyAgentSpawnFailed({
+          parent,
+          spawnRequestId: isRecord(command.params) ? cleanString(command.params.spawnRequestId, "params.spawnRequestId", { max: 160 }) : undefined,
+          provider: isRecord(command.params) ? cleanString(command.params.provider, "params.provider", { max: 40 }) : undefined,
+          reason: command.error ?? "spawn command failed",
+        });
+      }
+    }
     settleFailedOrchestratorUpgrade(command);
     emitCommand(command);
     auditCommandOutcome(command);

package/src/routes/workspaces.ts

@@ -7,7 +7,7 @@ import { WORKSPACE_ACTIONS, applyWorkspaceAction, buildWorkspaceCleanupCommand,
 import { auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, parseBody, type Handler } from "./_shared";
 import { collectWorkspaceOrphans } from "../workspace-orphans";
 import { createCommand } from "../commands-db";
-import { isOwnerAlive, withOwnerOnline } from "../workspace-merge";
+import { LAND_STRATEGIES, isOwnerAlive, withOwnerOnline } from "../workspace-merge";
 import { isPathWithinBase } from "../utils";
 import { resolve } from "node:path";
 import { type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
@@ -220,12 +220,18 @@ export const postWorkspaceCleanupStale: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const body = isRecord(parsed.body) ? parsed.body : {};
   const repoRoot = cleanString(body.repoRoot, "repoRoot", { max: 1000 });
+  // Scope the sweep to a single workspace when the caller named one (#307). Without
+  // this, `--id` was silently ignored and a sweep scoped to one id went repo-wide —
+  // a destructive-action footgun. Now an explicit id narrows the candidate set.
+  const workspaceId = cleanString(body.workspaceId, "workspaceId", { max: 160 });
   const dryRun = body.dryRun !== false; // safe by default
   const landedOnly = body.landedOnly !== false;
   const offlineOwnerOnly = body.offlineOwnerOnly !== false;
 
   const candidates = listWorkspaces().filter((ws) =>
-    ws.mode === "isolated" && Boolean(ws.worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status) && (!repoRoot || ws.repoRoot === repoRoot),
+    ws.mode === "isolated" && Boolean(ws.worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status)
+    && (!repoRoot || ws.repoRoot === repoRoot)
+    && (!workspaceId || ws.id === workspaceId),
   );
 
   const rows: Array<Record<string, unknown>> = [];
@@ -259,7 +265,7 @@ export const postWorkspaceCleanupStale: Handler = async (req) => {
     }
     rows.push(row);
   }
-  return json({ dryRun, landedOnly, offlineOwnerOnly, repoRoot, scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
+  return json({ dryRun, landedOnly, offlineOwnerOnly, repoRoot, ...(workspaceId ? { workspaceId } : {}), scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
 };
 
 export const postWorkspaceAction: Handler = async (req, params) => {
@@ -313,7 +319,10 @@ export const postWorkspaceAction: Handler = async (req, params) => {
       agentId,
       detail: cleanString(parsed.body.detail, "detail", { max: 4000 }),
       metadata: cleanMeta(parsed.body.metadata) ?? {},
-      strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
+      // No inline fallback: an absent strategy stays undefined and the shared core
+      // (requestWorkspaceMerge) applies DEFAULT_MERGE_STRATEGY, identically to the
+      // MCP land tool — one resolution point, no per-surface drift (#304).
+      strategy: optionalEnum(parsed.body.strategy, "strategy", LAND_STRATEGIES) as WorkspaceMergeStrategy | undefined,
       deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
       force: parsed.body.force === true,
       prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),

package/src/spawn-targets.ts

@@ -0,0 +1,159 @@
+import { countLiveSpawnedAgents, getAgent, getOrchestrator, listOrchestrators, ValidationError } from "./db";
+import { listAgentProfiles } from "./config-store";
+import { effectiveProviderCatalogList } from "./provider-catalog-store";
+import { isPathWithinBase } from "./utils";
+import { McpNotFoundError } from "./mcp-errors";
+import type { Orchestrator, ProviderCatalogSummary, SpawnProvider } from "./types";
+
+// #308 — spawn discovery + target selection. Home for the live capability matrix that
+// relay_spawn_targets returns, the scope-gated startup primer, and the orchestrator-selection
+// (with structured "name the nearest valid alternative" errors). Lives in its own module so the
+// already-large src/mcp.ts only carries the thin auth wrappers that call in here.
+
+// === relay_spawn_targets: the live spawn capability matrix ===
+
+// Reuses the per-host catalog each orchestrator already reports on heartbeat (orchestrator-probed
+// availability, not a static config guess), so the agent learns what it can spawn (and where)
+// upfront instead of from a runtime rejection. Caller identity + quota come from the MCP auth.
+export function buildSpawnTargets(input: { callerId?: string; quota: number }): Record<string, unknown> {
+  const me = input.callerId ? getAgent(input.callerId) : undefined;
+  const preferHost = me?.machine;
+  const orchestrators = listOrchestrators();
+  const self = preferHost ? orchestrators.find((o) => o.hostname === preferHost || o.id === preferHost) : undefined;
+  const liveChildren = input.callerId ? countLiveSpawnedAgents(input.callerId) : 0;
+
+  return {
+    self: {
+      orchestratorId: self?.id,
+      host: self?.hostname ?? preferHost,
+      spawnQuota: { max: input.quota, liveChildren, remaining: Math.max(0, input.quota - liveChildren) },
+    },
+    orchestrators: orchestrators
+      .filter((o) => o.status === "online")
+      .map((o) => ({
+        orchestratorId: o.id,
+        host: o.hostname,
+        online: true,
+        isSelf: self ? o.id === self.id : false,
+        providers: providerMatrixFor(o),
+      })),
+    profiles: spawnProfilesSummary(),
+    guidance:
+      "Default to your own host (isSelf:true); only set orchestratorId to spawn onto another host that runs a provider/model yours doesn't. Omitting model/effort uses the provider default (marked below). Prefer a named profile over assembling raw knobs; set spawnRequestId for idempotency. After spawning you'll be pushed agent.ready / agent.exited / agent.spawn_failed — don't block-poll.",
+  };
+}
+
+// The subset of the (orchestrator-reported OR global) catalog the matrix projects. Both
+// ProviderCatalogSummary and ProviderCatalogEntry are structurally compatible with this shape.
+interface SpawnCatalogish {
+  provider: SpawnProvider;
+  defaultModel?: string;
+  models: Array<{ alias: string; providerModel: string; efforts: readonly string[]; defaultEffort?: string }>;
+}
+
+function providerMatrixFor(o: Orchestrator): Array<Record<string, unknown>> {
+  const reported: ProviderCatalogSummary[] = o.providerCatalog ?? [];
+  const global = effectiveProviderCatalogList();
+  return o.providers.map((provider) => {
+    const cat: SpawnCatalogish | undefined =
+      reported.find((s) => s.provider === provider) ?? global.find((e) => e.provider === provider);
+    return {
+      provider,
+      available: true,
+      ...(cat
+        ? {
+            defaultModel: cat.defaultModel,
+            models: cat.models.map((m) => ({
+              id: m.alias,
+              providerModel: m.providerModel,
+              default: cat.defaultModel === m.alias,
+              effortLevels: m.efforts,
+              ...(m.defaultEffort ? { defaultEffort: m.defaultEffort } : {}),
+            })),
+          }
+        : { models: [] }),
+    };
+  });
+}
+
+function spawnProfilesSummary(): Array<Record<string, unknown>> {
+  return listAgentProfiles().map(({ key, value }) => ({
+    name: value.name ?? key,
+    description: value.description,
+    provider: value.provider,
+    approvalMode: value.permissions?.mode,
+    ...(value.maxSpawnedAgents !== undefined ? { maxSpawnedAgents: value.maxSpawnedAgents } : {}),
+    builtIn: value.builtIn ?? false,
+  }));
+}
+
+// A human-readable list of (provider@host) an agent can spawn onto right now, so a structured
+// rejection names the nearest valid alternative instead of a bare "offline".
+function spawnAlternatives(provider?: SpawnProvider): string {
+  const live = listOrchestrators()
+    .filter((o) => o.status === "online")
+    .flatMap((o) => o.providers.filter((p) => !provider || p === provider).map((p) => `${p}@${o.hostname}`));
+  return live.length ? live.join(", ") : "none currently online";
+}
+
+// === Startup primer (eager, scope-gated) ===
+
+// Thin, eager startup primer for spawn-capable agents only (canSpawn = token carries
+// command:spawn). Names the exact discovery tool (relay_spawn_targets) so there's zero discovery
+// cost under lazy tool-loading, plus the same-host-default + fire-and-forget rules. The full matrix
+// stays lazy — fetched only when the agent actually decides to spawn. Returns "" for non-spawn agents.
+export function spawnCapablePrimer(input: { canSpawn: boolean; quota?: number }): string {
+  if (!input.canSpawn) return "";
+  const quotaLabel = typeof input.quota === "number" && input.quota > 0 ? ` (live-children quota: ${input.quota})` : "";
+  return [
+    `You can spawn long-living child agents${quotaLabel}. Shut your own down with relay_shutdown_agent.`,
+    "- BEFORE spawning, call relay_spawn_targets: it returns the LIVE matrix of hosts × providers × models × per-model effort, your remaining quota, and named profiles. Don't guess — that tool is the discovery path.",
+    "- Default to your OWN host. Only set orchestratorId to spawn onto another host when it runs a provider/model yours doesn't, or the work must run there.",
+    "- Prefer a named profile (profile: \"<name>\") over hand-assembling provider+model+effort+approvalMode. Omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.",
+    "- Set spawnRequestId for idempotency so a retried spawn doesn't double-create.",
+    "- Spawn is fire-and-forget: pass waitForRegistrationMs:0 and keep working — you'll be PUSHED agent.ready when the child is genuinely ready (past onboarding), or agent.spawn_failed / agent.exited otherwise. Don't block-poll.",
+    "- Spawned children cannot themselves spawn (no grandchildren).",
+  ].join("\n");
+}
+
+// === Orchestrator selection ===
+
+export function selectSpawnOrchestrator(
+  provider: SpawnProvider,
+  orchestratorId?: string,
+  cwd?: string,
+  preferHost?: string,
+): Orchestrator {
+  if (orchestratorId) {
+    const orchestrator = getOrchestrator(orchestratorId);
+    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
+    // #308 — name the nearest valid alternative on a miss instead of a bare "offline"/"unavailable",
+    // so the agent can re-target without a second relay_spawn_targets round trip.
+    if (orchestrator.status !== "online") {
+      throw new ValidationError(`orchestrator ${orchestratorId} is offline. Available: ${spawnAlternatives(provider)} (call relay_spawn_targets for the live matrix).`);
+    }
+    if (!orchestrator.providers.includes(provider)) {
+      const has = orchestrator.providers.length ? orchestrator.providers.join(", ") : "no providers";
+      throw new ValidationError(`orchestrator ${orchestratorId} does not run provider '${provider}' (it has: ${has}). Available for '${provider}': ${spawnAlternatives(provider)}.`);
+    }
+    return orchestrator;
+  }
+  const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
+  if (cwd) {
+    const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
+    if (match) return match;
+  }
+  // #255: with neither an explicit id nor a cwd to pin the host, default to the CALLER's own
+  // host instead of silently grabbing candidates[0] (a foreign host whose baseDir would then
+  // reject the caller's cwd — the footgun the spawn recipe warned about). An agent's `machine`
+  // is its OS hostname; match it against the orchestrator hostname (or id, defensively).
+  if (preferHost) {
+    const own = candidates.find((item) => item.hostname === preferHost || item.id === preferHost);
+    if (own) return own;
+  }
+  const orchestrator = candidates[0];
+  if (!orchestrator) {
+    throw new McpNotFoundError(`no online orchestrator runs provider '${provider}'. Available: ${spawnAlternatives()} (call relay_spawn_targets for the live matrix).`);
+  }
+  return orchestrator;
+}

package/src/utils.ts

@@ -1,4 +1,19 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Expand a leading `~` / `~/` to the current user's home directory. Leaves any
+ * other value (absolute paths, `./rel`, embedded `~` mid-string) untouched.
+ *
+ * Folds the identical hand-rolled copies in `cli.ts` (`expandHomePath`, used for
+ * orchestrator `--base-dir`/`--runtime-prefix`/`--path-prefix`) and
+ * `artifact-storage.ts` (artifact root). Import this; never re-declare it.
+ */
+export function expandTilde(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
 
 /**
  * Path containment check — is `path` inside (or equal to) `baseDir`?

package/src/workspace-actions.ts

@@ -20,6 +20,9 @@ import {
 } from "./db";
 import { emitActivityEvent } from "./sse";
 import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
+// Re-export the land-strategy contract so the MCP land tool validates against the same
+// tuple as the HTTP route without a second import hop (one source: workspace-merge, #304).
+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";
@@ -161,7 +164,10 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   if (action === "merge") {
     const result = requestWorkspaceMerge(workspace, {
       requestedBy: agentId ?? "dashboard",
-      strategy: input.strategy ?? "auto",
+      // Pass the strategy through verbatim (undefined when unset) — the single
+      // default lives in requestWorkspaceMerge, so both land surfaces resolve it
+      // identically instead of each applying its own fallback (#304).
+      strategy: input.strategy,
       deleteBranch: input.deleteBranch !== false,
       prTitle: input.prTitle,
       prBody: input.prBody,

package/src/workspace-merge.ts

@@ -10,6 +10,17 @@ import {
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { isPathWithinBase } from "./utils";
 
+// One home for the land-strategy contract, shared by BOTH land surfaces — the HTTP
+// route (`POST /api/workspaces/:id/actions`, driven by `agent-relay workspace land`)
+// and the `relay_workspace_land` MCP tool. They validate against the same tuple and
+// fall back to the same default, so the effective strategy can't drift by surface
+// (#304: the CLI used to omit the strategy and let the server default while MCP
+// passed its own — two encodings of one rule). The default is applied ONCE, in
+// `requestWorkspaceMerge` below; callers pass `strategy` through verbatim (undefined
+// when unset) so there is a single resolution point, not one per entrypoint.
+export const LAND_STRATEGIES = ["pr", "rebase-ff", "auto"] as const;
+export const DEFAULT_MERGE_STRATEGY: WorkspaceMergeStrategy = "auto";
+
 interface RequestWorkspaceMergeOptions {
   /** Who asked for the merge (lease holder + audit). e.g. an agent id, "dashboard", "auto-merge". */
   requestedBy: string;
@@ -103,7 +114,7 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
         branch: workspace.branch,
         baseRef: workspace.baseRef,
         baseSha: workspace.baseSha,
-        strategy: opts.strategy ?? "auto",
+        strategy: opts.strategy ?? DEFAULT_MERGE_STRATEGY,
         deleteBranch,
         push: opts.push !== false,
         prTitle: opts.prTitle,