agent-relay-server 0.91.3 → 0.92.0

package/src/maintenance/workspaces.ts

@@ -11,6 +11,7 @@ import {
   reelectRepoSteward,
   releaseExpiredMergeLeases,
   updateWorkspaceStatus,
+  setWorkspaceBranch,
 } from "../db";
 import type { WorkspaceMergePreview, WorkspaceStatus } from "../types";
 import { notifyStewardHandoff, reconcileLandedWorkspace } from "../branch-landed";
@@ -262,3 +263,78 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
     escalationTargets,
   };
 }
+
+/**
+ * Proactively refresh idle branch-agent workspaces against origin/main (#478).
+ *
+ * For each `active` isolated workspace whose owner agent is NOT busy and whose
+ * stored probe data indicates no WIP (dirty=0, ahead=0), dispatch a
+ * `workspace.idle-refresh` command to the owning orchestrator. The orchestrator
+ * re-verifies liveness, fetches origin, and — when the worktree is cleanly
+ * behind — performs a `checkout -B <fresh> origin/main` so the agent is already
+ * current when it next wakes. Workspaces with WIP, commits ahead, or busy owners
+ * are skipped silently.
+ */
+export async function refreshIdleWorkspaces(): Promise<Record<string, unknown>> {
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.agentId);
+  if (!orchestrators.length) return { dispatched: 0, skipped: 0, reason: "no online orchestrators" };
+
+  const candidates = listWorkspaces().filter(
+    (ws) => ws.mode === "isolated" && ws.status === "active" && Boolean(ws.worktreePath),
+  );
+
+  const dispatched: string[] = [];
+  const skipped: string[] = [];
+  const now = Date.now();
+
+  for (const ws of candidates) {
+    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
+    if (!orch?.agentId) { skipped.push(`${ws.id}:no-orchestrator`); continue; }
+
+    // Gate: owner must exist and not be busy.
+    const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
+    if (!owner || owner.status === "busy") { skipped.push(`${ws.id}:owner-busy`); continue; }
+
+    // Gate: skip if stored metadata shows WIP or commits ahead.
+    // The orchestrator re-checks live before mutating; stored data is a fast pre-filter.
+    const meta = ws.metadata as Record<string, unknown>;
+    const gitAhead = typeof meta.gitAhead === "number" ? meta.gitAhead : undefined;
+    const gitDirtyCount = typeof meta.gitDirtyCount === "number" ? meta.gitDirtyCount : undefined;
+    if (gitAhead !== undefined && gitAhead > 0) { skipped.push(`${ws.id}:ahead`); continue; }
+    if (gitDirtyCount !== undefined && gitDirtyCount > 0) { skipped.push(`${ws.id}:dirty`); continue; }
+
+    const command = createCommand({
+      type: "workspace.idle-refresh",
+      source: "system",
+      target: orch.agentId,
+      correlationId: ws.id,
+      params: {
+        workspaceId: ws.id,
+        repoRoot: ws.repoRoot,
+        worktreePath: ws.worktreePath,
+        branch: ws.branch,
+        baseRef: ws.baseRef,
+        baseSha: ws.baseSha,
+        requestedBy: "workspace-idle-refresh",
+        requestedAt: now,
+      },
+    });
+    emitCommand(command);
+    dispatched.push(ws.id);
+  }
+
+  return { dispatched, skipped };
+}
+
+/**
+ * Apply the result of a settled `workspace.idle-refresh` command.
+ * When the orchestrator refreshed the worktree, repoint the DB row to the
+ * new branch and update base_sha so the next merge targets the live branch.
+ */
+export function applyIdleRefreshResult(workspaceId: string, result: Record<string, unknown>): boolean {
+  const newBranch = typeof result.newBranch === "string" ? result.newBranch : undefined;
+  const baseSha = typeof result.baseSha === "string" ? result.baseSha : undefined;
+  if (!newBranch || result.refreshed !== true) return false;
+  setWorkspaceBranch(workspaceId, newBranch, baseSha);
+  return true;
+}

package/src/managed-policy.ts

@@ -2,6 +2,7 @@ import { getAgentProfile } from "./config-store";
 import { withResolvedProvisioning } from "./db";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
+import { applyDefaultSharedMcp } from "./shared-mcp";
 import type { SpawnPolicy, WorkspaceMode } from "./types";
 
 export function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
@@ -29,7 +30,8 @@ interface ManagedSpawnContext {
 export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> {
   const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
-  const agentProfile = withResolvedProvisioning(policy.profile ? getAgentProfile(policy.profile)?.value : undefined, policy.provider);
+  const resolvedProfile = withResolvedProvisioning(policy.profile ? getAgentProfile(policy.profile)?.value : undefined, policy.provider);
+  const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
   return buildSpawnCommand({
     provider: policy.provider,
     orchestratorId: policy.orchestratorId,

package/src/mcp/tools-spawn.ts

@@ -5,18 +5,22 @@ import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
 import { parseProjectMcp, PROJECT_MCP_POLICY_NAMES } from "../project-mcp";
+import { parseProjectSettings, PROJECT_SETTINGS_POLICY_NAMES } from "../project-settings";
+import { parseProjectSkills, PROJECT_SKILLS_POLICY_NAMES } from "../project-skills";
 import { parseSharedMcp, SHARED_MCP_POLICY_NAMES } from "../shared-mcp";
 import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } from "../db";
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
 import { optionalEnum } from "../validation";
-import { APPROVAL_MODES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceMode, WorkspaceRecord } from "../types";
+import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
 import { callerAgentId } from "./identity";
 import { enumField, optionalBoolean, optionalNonNegativeInt, optionalPositiveInt, optionalString, optionalStringArray } from "./validation";
 
+const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
+
 export const SPAWN_TOOLS: ToolDefinition[] = [
   {
     name: "relay_spawn_agent",
@@ -37,7 +41,18 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         systemPromptAppend: { type: "string" },
         projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
         projectMcp: { type: "object", description: "#667 — project `.mcp.json` MCP projection (default OFF). When set, the worker gets the MCP servers committed in the spawn cwd's `.mcp.json` (e.g. an app's playtest/manuscript servers), injected by relay through the controlled `--mcp-config` path that survives `--strict-mcp-config` — sourced from the project, not ambient host MCP, and without triggering Claude's project-trust modal. `policy: \"all\"` (the default) injects every declared server. Omit to keep current host-only behavior.", properties: { policy: { type: "string", enum: PROJECT_MCP_POLICY_NAMES } }, additionalProperties: false },
-        sharedMcp: { type: "object", description: "#672 — shared host-listener MCP (default OFF). When set, the worker's NON-IDENTITY MCP (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via a per-agent `callmux bridge --cwd \"$WORKTREE\"`, so the MCP session survives a listener/downstream restart and each isolated worktree keeps session-cwd isolation. Rides the controlled `--mcp-config` path (composes with `--strict-mcp-config`). The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener. `policy: \"all\"` (the default) routes the listener's full non-identity set. Omit to keep current per-agent injection.", properties: { policy: { type: "string", enum: SHARED_MCP_POLICY_NAMES } }, additionalProperties: false },
+        projectSkills: { type: "object", description: "#668 — project `.claude/skills` projection for Claude workers (default OFF). When set, the worker gets skill dirs committed under the spawn cwd's `.claude/skills`, materialized into Relay's managed Claude config home. Host/global skills stay excluded. `policy: \"all\"` (the default) includes every valid skill dir. Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_SKILLS_POLICY_NAMES } }, additionalProperties: false },
+        projectSettings: { type: "object", description: "#669 — project `.claude/settings.json` projection for Claude workers (default OFF). When set, Relay reads the spawn cwd's committed settings, strips permission/security keys that could widen the worker, and injects the safe remainder through `--settings`. Relay approvalMode/permission gates stay authoritative. Host/global settings stay excluded. `policy: \"all\"` (the default) applies the settings file. Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_SETTINGS_POLICY_NAMES } }, additionalProperties: false },
+        sharedMcp: {
+          anyOf: [
+            { type: "boolean" },
+            { type: "object", properties: { policy: { type: "string", enum: SHARED_MCP_POLICY_NAMES } }, additionalProperties: false },
+          ],
+          description: "#689 — shared host-listener MCP. Host-MCP profiles default ON: the worker's NON-IDENTITY MCP (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via a per-agent `callmux bridge --cwd \"$WORKTREE\"`, so the MCP session survives listener/downstream restart and keeps isolated worktree cwd routing. Profiles that suppress host MCP stay OFF unless explicitly opted in. Pass `false` as a per-spawn kill-switch to force direct/per-agent MCP injection. The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener.",
+        },
+        landStrategy: { type: "string", enum: SPAWN_LAND_STRATEGIES, description: "#421 — per-spawn workspace land strategy. Omit to use the instance landing.strategy. `direct` keeps deterministic rebase/fast-forward landing; `pr` opens a PR." },
+        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "#421/#305 — PR auto-merge policy when landStrategy resolves to `pr`. `on-green` auto-merges after checks, `on-approval` waits for reviewer approval, `manual` opens the PR only." },
+        reviewer: { type: "string", description: "#421/#305 — optional reviewer handle or policy target for reviewer-first PR lands, used with landStrategy `pr` and autoMerge `on-approval`." },
         profile: { type: "string", description: `Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use \`${DEFAULT_SPAWN_PROFILE_NAME}\`.` },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -46,6 +61,16 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         spawnRequestId: { type: "string" },
         lifecycle: { type: "string", enum: VALID_AGENT_LIFECYCLES, description: "Lifecycle mode. `persistent` keeps the agent until explicitly stopped. `transient` lets Relay auto-shutdown the child after it is idle and, for isolated workers, after its branch has landed. Default: persistent." },
         workspaceMode: { type: "string", enum: VALID_WORKSPACE_MODES, description: "Git workspace for the worker. `isolated` = its own worktree on an `agent/session-*` branch off main that auto-lands when ready (delegate a unit of work, get a branch worker). `shared` = edits your live checkout (a sidecar). `inherit` = let the orchestrator decide. DEFAULT for agent-initiated spawns is `isolated` so a delegated worker lands to main instead of editing your tree; pass `shared`/`inherit` to override." },
+        resumeWorkspace: {
+          type: "object",
+          description: "#635 — attach a new worker to an EXISTING managed worktree/branch instead of always creating a fresh one. `attach`: reuse the worktree as-is (crash recovery — WIP is preserved); `branch-from`: fresh worktree off the existing branch HEAD (phased work, sequential hand-off). Guard: `attach` is rejected when the original owner is still alive. The resumed worker's branch auto-lands normally on completion.",
+          properties: {
+            branch: { type: "string", description: "The existing agent branch to attach to or branch from (e.g. `agent/build-389/.../...`)." },
+            mode: { type: "string", enum: ["attach", "branch-from"], description: "`attach` = reuse the existing worktree directory (WIP preserved). `branch-from` = fresh worktree off the branch HEAD (committed history carried, WIP not)." },
+          },
+          required: ["branch", "mode"],
+          additionalProperties: false,
+        },
         waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
       },
       required: ["provider"],
@@ -95,6 +120,15 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
   },
 ];
 
+function parseResumeWorkspace(value: unknown): { branch: string; mode: "attach" | "branch-from" } | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const obj = value as Record<string, unknown>;
+  const branch = optionalString(obj.branch, "resumeWorkspace.branch", 500);
+  const mode = obj.mode === "attach" || obj.mode === "branch-from" ? obj.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return { branch, mode };
+}
+
 export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const input: SpawnAgentInput = {
     provider: enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
@@ -113,13 +147,19 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
     projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
     projectMcp: parseProjectMcp(args.projectMcp, (m) => new ValidationError(m)),
+    projectSkills: parseProjectSkills(args.projectSkills, (m) => new ValidationError(m)),
+    projectSettings: parseProjectSettings(args.projectSettings, (m) => new ValidationError(m)),
     sharedMcp: parseSharedMcp(args.sharedMcp, (m) => new ValidationError(m)),
+    landStrategy: optionalEnum(args.landStrategy, "landStrategy", SPAWN_LAND_STRATEGIES) as WorkspaceLandingPolicy | undefined,
+    autoMerge: optionalEnum(args.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined,
+    reviewer: optionalString(args.reviewer, "reviewer", 240),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),
     spawnRequestId: optionalString(args.spawnRequestId, "spawnRequestId", 160),
     requestedVia: "mcp",
     waitForRegistrationMs: optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000,
+    resumeWorkspace: parseResumeWorkspace(args.resumeWorkspace),
   };
   const result = await spawnAgent(input, authContextFromMcp(auth));
   return { ...result };

package/src/project-settings.ts

@@ -0,0 +1,27 @@
+// Project `.claude/settings.json` projection (#669) — sibling to projectMcp (#667).
+// Relay carries only the opt-in decision; the runner reads/sanitizes the project settings
+// and injects them through the controlled Claude `--settings` path.
+
+export const PROJECT_SETTINGS_POLICY_NAMES = ["all"] as const;
+export type ProjectSettingsPolicyName = (typeof PROJECT_SETTINGS_POLICY_NAMES)[number];
+
+export interface ProjectSettingsPolicy {
+  policy?: ProjectSettingsPolicyName;
+}
+
+export function parseProjectSettings(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectSettingsPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectSettings must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !PROJECT_SETTINGS_POLICY_NAMES.includes(policy as ProjectSettingsPolicyName)) {
+    throw onInvalid(`projectSettings.policy must be one of: ${PROJECT_SETTINGS_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectSettingsPolicyName };
+}

package/src/project-skills.ts

@@ -0,0 +1,27 @@
+// Project `.claude/skills` projection (#668) — sibling to projectMcp (#667).
+// Relay carries only the opt-in decision; the runner reads the spawn cwd and materializes
+// project-committed skills into the managed Claude config home.
+
+export const PROJECT_SKILLS_POLICY_NAMES = ["all"] as const;
+export type ProjectSkillsPolicyName = (typeof PROJECT_SKILLS_POLICY_NAMES)[number];
+
+export interface ProjectSkillsPolicy {
+  policy?: ProjectSkillsPolicyName;
+}
+
+export function parseProjectSkills(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectSkillsPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectSkills must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !PROJECT_SKILLS_POLICY_NAMES.includes(policy as ProjectSkillsPolicyName)) {
+    throw onInvalid(`projectSkills.policy must be one of: ${PROJECT_SKILLS_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectSkillsPolicyName };
+}

package/src/routes/agent-sessions.ts

@@ -6,6 +6,7 @@ import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady
 import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
+import { applyDefaultSharedMcp } from "../shared-mcp";
 import { cleanString, optionalEnum } from "../validation";
 import { createCommand } from "../commands-db";
 import { emitAgentStatus, emitDashboardPresence, emitNewMessage } from "../sse";
@@ -119,7 +120,8 @@ function restartSpawnParamsForAgent(
   const effort = metaString(agent.meta, "effort") as ProviderEffort | undefined;
   const providerArgs = metaStringArray(agent.meta, "providerArgs");
   const profileName = metaString(agent.meta, "profile");
-  const agentProfile = withResolvedProvisioning(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
+  const resolvedProfile = withResolvedProvisioning(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
+  const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
   const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
   const params = buildSpawnCommand({

package/src/routes/agents-spawn.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
-import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
 import { ValidationError, listAgents } from "../db";
@@ -8,15 +8,26 @@ import { registerAgent } from "../services/register-agent";
 import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
 import { parseProjectInstructions } from "../project-instructions";
 import { parseProjectMcp } from "../project-mcp";
+import { parseProjectSettings } from "../project-settings";
+import { parseProjectSkills } from "../project-skills";
 import { parseSharedMcp } from "../shared-mcp";
 import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
 import { quotaStateFromUnknown } from "../quota";
-import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceMode } from "../types";
+import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceAutoMergePolicy, type WorkspaceLandingPolicy, type WorkspaceMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
+const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
+
+function parseResumeWorkspaceHttp(value: unknown): { branch: string; mode: "attach" | "branch-from" } | undefined {
+  if (!value || !isRecord(value)) return undefined;
+  const branch = cleanString(value.branch, "resumeWorkspace.branch", { max: 500 });
+  const mode = value.mode === "attach" || value.mode === "branch-from" ? value.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return { branch, mode };
+}
 
 function normalizeAgentInput(body: unknown): RegisterAgentInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
@@ -124,13 +135,19 @@ export const postAgentSpawn: Handler = async (req) => {
       systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
       projectInstructions: parseProjectInstructions(parsed.body.projectInstructions, (m) => new ValidationError(m)),
       projectMcp: parseProjectMcp(parsed.body.projectMcp, (m) => new ValidationError(m)),
+      projectSkills: parseProjectSkills(parsed.body.projectSkills, (m) => new ValidationError(m)),
+      projectSettings: parseProjectSettings(parsed.body.projectSettings, (m) => new ValidationError(m)),
       sharedMcp: parseSharedMcp(parsed.body.sharedMcp, (m) => new ValidationError(m)),
+      landStrategy: optionalEnum(parsed.body.landStrategy, "landStrategy", SPAWN_LAND_STRATEGIES) as WorkspaceLandingPolicy | undefined,
+      autoMerge: optionalEnum(parsed.body.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined,
+      reviewer: cleanString(parsed.body.reviewer, "reviewer", { max: 240 }),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),
       spawnRequestId: cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 }),
       requestedVia: "dashboard",
       requestedBy: "dashboard",
+      resumeWorkspace: parseResumeWorkspaceHttp(parsed.body.resumeWorkspace),
       // HTTP is fire-and-forget (202): the dashboard polls registration separately via the
       // returned spawnRequestId.
       waitForRegistrationMs: 0,

package/src/routes/agents.ts

@@ -7,6 +7,8 @@ import { cleanStringArray } from "../validation";
 import { clearActiveMemories, memoryBroker } from "../memory-service";
 import { emitAgentRemoved, emitAgentStatus } from "../sse";
 import { notifyAgentReady } from "../agent-lifecycle-events";
+import { flushQueuedDirectMessages } from "../services/managed-running";
+import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
 import { type AgentCard } from "../types";
@@ -210,7 +212,15 @@ export const postHeartbeat: Handler = async (req, params) => {
     const guard = normalizeAgentSessionGuard(req, parsed.body);
     const session = validateAgentSession(params.id!, guard);
     if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
-    return heartbeat(params.id!, guard) ? json({ ok: true }) : error("agent not found", 404);
+    // #416 — capture unavailability before heartbeat to detect the transition.
+    const beforeHeartbeat = getAgent(params.id!);
+    const wasUnavailable = beforeHeartbeat ? isAgentUnavailable(beforeHeartbeat) : false;
+    if (!heartbeat(params.id!, guard)) return error("agent not found", 404);
+    if (wasUnavailable) {
+      const after = getAgent(params.id!);
+      if (after && !isAgentUnavailable(after)) flushQueuedDirectMessages(params.id!);
+    }
+    return json({ ok: true });
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -287,7 +297,12 @@ export const patchAgentReady: Handler = async (req, params) => {
     // #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!);
+    if (body.ready && !before?.ready) {
+      notifyAgentReady(params.id!);
+      // #416 — also flush queued direct messages: a not-ready agent that becomes ready
+      // may have queued messages waiting (e.g. starting up, clearing context).
+      flushQueuedDirectMessages(params.id!);
+    }
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;

package/src/routes/commands.ts

@@ -13,6 +13,7 @@ import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
 import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLandFailed, notifyBranchLanded } from "../branch-landed";
+import { applyIdleRefreshResult } from "../maintenance/workspaces";
 import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
@@ -186,6 +187,10 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.idle-refresh" && command.status === "succeeded" && isRecord(command.result)) {
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      if (workspaceId) applyIdleRefreshResult(workspaceId, command.result);
+    }
     if (command.type === "workspace.merge") {
       // Merge settled (either way) — free the per-repo merge lease so the next
       // base merge can proceed (issue #157).

package/src/services/managed-running.ts

@@ -12,7 +12,7 @@
 // Composed by `registerAgent` (HTTP + bus registration) and called directly by the
 // orchestrator-report projection in lifecycle-manager. It does NOT upsert the agent
 // row — the agent registers itself over HTTP/bus; this only reconciles managed state.
-import { createActivityEvent, resolveQueuedPolicyMessages } from "../db";
+import { createActivityEvent, resolveQueuedDirectMessages, resolveQueuedPolicyMessages } from "../db";
 import { getManagedAgentState, updateManagedAgentState } from "../config-store";
 import { emitRelayEvent } from "../events";
 import { emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
@@ -129,3 +129,20 @@ function recordManagedTransition(
     },
   });
 }
+
+/**
+ * Flush queued messages addressed directly to `agentId` (#416). Called when a registered agent
+ * transitions back to available: heartbeat stale→idle, re-registration after restart/compact, or
+ * rate-limit resume. Emits the same `message.available` / `message.new` / `message.delivery_updated`
+ * events that the policy flush emits so SSE subscribers and the dashboard react identically.
+ * No-op when there are no queued direct messages.
+ */
+export function flushQueuedDirectMessages(agentId: string): void {
+  const available = resolveQueuedDirectMessages(agentId);
+  if (!available.length) return;
+  emitMessageAvailable("direct", agentId, available);
+  for (const message of available) {
+    emitNewMessage(message);
+    emitMessageDeliveryUpdated(message);
+  }
+}

package/src/services/rate-limit-resume.ts

@@ -1,5 +1,6 @@
 import { createActivityEvent, listAgents, mergeAgentMeta } from "../db";
 import { routeNotification } from "../notification-router";
+import { flushQueuedDirectMessages } from "./managed-running";
 import {
   TRANSIENT_RATE_LIMIT_BACKOFF_MS,
   agentProviderState,
@@ -134,6 +135,8 @@ export function resumeRateLimitedAgents(): Record<string, unknown> {
 
     if (transient) mergeAgentMeta(agent.id, { providerState: nextTransientState(state as Record<string, unknown>, now, attempts) });
 
+    // #416 — flush messages queued while the agent was rate-limited.
+    flushQueuedDirectMessages(agent.id);
     resumed.push(agent.id);
     createActivityEvent({
       clientId: `rate-limit-resume-${agent.id}-${now}`,

package/src/services/register-agent.ts

@@ -15,7 +15,8 @@ import { emitAgentStatus, emitNewMessage } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
 import { notifyAgentReady } from "../agent-lifecycle-events";
 import { resolveSpawnLineage, resolveTeamLineage } from "../security";
-import { markManagedAgentRunning } from "./managed-running";
+import { flushQueuedDirectMessages, markManagedAgentRunning } from "./managed-running";
+import { isAgentUnavailable } from "../db/agent-predicates";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, RegisterAgentInput } from "../types";
 
@@ -71,6 +72,11 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
   // transport. notifyAgentReady no-ops for non-spawned agents and dedups repeats.
   if (agent.ready && !existing?.ready) notifyAgentReady(agent.id);
 
+  // #416 — flush queued direct messages when a re-registering agent was previously unavailable
+  // (stale, compacting, blocked) or a new agent becomes ready. No-op for brand-new agents
+  // (no queued messages yet) and when no queued messages exist.
+  if (existing && isAgentUnavailable(existing) && agent.ready) flushQueuedDirectMessages(agent.id);
+
   if (!existing) {
     // #413 — a spawned worker with a report-back contract gets a pending reply obligation to its
     // spawner so it can't idle with its verdict undelivered (vent #121). First-registration only.

package/src/services/spawn-agent.ts

@@ -25,7 +25,7 @@
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
 import type { SpawnProvider } from "agent-relay-sdk";
 import { errMessage, stringValue } from "agent-relay-sdk";
-import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, listAgents, resolveProjectForCwd, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
+import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, listAgents, listWorkspaces, resolveProjectForCwd, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
 import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -34,13 +34,17 @@ import { selectSpawnOrchestrator } from "../spawn-targets";
 import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile } from "../config-store";
 import { composeSpawnInstructionsWithEvents, type ProjectInstructionPolicy } from "../project-instructions";
 import type { ProjectMcpPolicy } from "../project-mcp";
-import type { SharedMcpPolicy } from "../shared-mcp";
+import type { ProjectSettingsPolicy } from "../project-settings";
+import type { ProjectSkillsPolicy } from "../project-skills";
+import { applyDefaultSharedMcp, type SharedMcpSpawnOverride } from "../shared-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import type { AuthContext } from "./auth-context";
-import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, WorkspaceMode } from "../types";
+import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode } from "../types";
+import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "../workspace-merge";
+import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 
 /** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
 const SPAWN_SCOPE = "command:spawn";
@@ -85,6 +89,8 @@ export interface SpawnAgentInput {
    * to projectInstructions; carried to the runner on the in-flight `agentProfile.projectMcp`.
    */
   projectMcp?: ProjectMcpPolicy;
+  projectSkills?: ProjectSkillsPolicy;
+  projectSettings?: ProjectSettingsPolicy;
   /**
    * #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
@@ -94,7 +100,10 @@ export interface SpawnAgentInput {
    * today. Sibling to projectMcp; carried to the runner on the in-flight `agentProfile.sharedMcp`.
    * The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener.
    */
-  sharedMcp?: SharedMcpPolicy;
+  sharedMcp?: SharedMcpSpawnOverride;
+  landStrategy?: WorkspaceLandingPolicy;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
   /**
    * 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.
@@ -111,6 +120,23 @@ export interface SpawnAgentInput {
   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;
+  };
 }
 
 export interface SpawnAgentResult {
@@ -188,7 +214,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // 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.
   const profileName = input.profile ?? DEFAULT_SPAWN_PROFILE_NAME;
-  const agentProfile = withResolvedProvisioning(getAgentProfile(profileName)?.value, input.provider);
+  let agentProfile = withResolvedProvisioning(getAgentProfile(profileName)?.value, input.provider);
   if (!agentProfile) throw new McpNotFoundError(input.profile ? "agent profile not found" : `default agent profile ${DEFAULT_SPAWN_PROFILE_NAME} not found`);
 
   // #667 — project `.mcp.json` projection: a per-spawn `projectMcp` overrides the profile
@@ -198,13 +224,13 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // config). Like projectInstructions, an explicit `false` parses to undefined and so cannot
   // turn a profile default OFF — opt-in is the trust gate, not opt-out.
   if (input.projectMcp !== undefined) agentProfile.projectMcp = input.projectMcp;
+  if (input.projectSkills !== undefined) agentProfile.projectSkills = input.projectSkills;
+  if (input.projectSettings !== undefined) agentProfile.projectSettings = input.projectSettings;
 
-  // #672 — shared host-listener MCP: a per-spawn `sharedMcp` overrides the profile default,
-  // same opt-in trust gate as projectMcp (an explicit `false` parses to undefined and so
-  // cannot turn a profile default OFF). The runner emits the bridge entry from
-  // `agentProfile.sharedMcp` (it owns the spawn cwd → `--cwd "$WORKTREE"`); thread the resolved
-  // decision onto the in-flight profile copy (a fresh object, never the cached config).
-  if (input.sharedMcp !== undefined) agentProfile.sharedMcp = input.sharedMcp;
+  // #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, input.sharedMcp);
 
   // --- THE GATE (uniform across transports) ---------------------------------
   // Coarse capability: spawning requires command:spawn. The MCP dispatcher already enforced
@@ -232,6 +258,40 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // outside its cwd prefix, and MCP now honors the same bound.
   assertResourceAllowed(ctx, { scope: "agent:write", resource: { orchestratorId: orchestrator.id, cwd: resolvedCwd } });
 
+  // #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 (!isPathWithinBase(existingWs.worktreePath, orchestrator.baseDir)) {
+      throw new ValidationError(`resumeWorkspace: worktree "${existingWs.worktreePath}" is outside orchestrator base dir "${orchestrator.baseDir}"`);
+    }
+    if (mode === "attach") {
+      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`);
+      }
+    }
+    // Enrich with relay-resolved fields the orchestrator needs.
+    input.resumeWorkspace = {
+      branch,
+      mode,
+      worktreePath: existingWs.worktreePath,
+      workspaceId: existingWs.id,
+      baseRef: existingWs.baseRef,
+      baseSha: existingWs.baseSha,
+    };
+  }
+
   // Provenance actor: the resolved caller agent when known, else the transport's label, else
   // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
   const requestedBy = callerId ?? input.requestedBy ?? ctx.actor.id;
@@ -317,6 +377,10 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       prompt: input.prompt,
       systemPromptAppend,
       relayInjectionEvents: composedInstructions.relayInjectionEvents,
+      landStrategy: input.landStrategy,
+      autoMerge: input.autoMerge,
+      reviewer: input.reviewer,
+      resumeWorkspace: input.resumeWorkspace,
       ...(expectReply ? { expectReply } : {}),
       policyName: input.policyName,
       spawnRequestId,