agent-relay-server 0.17.0 → 0.19.0

package/src/routes.ts

@@ -85,6 +85,8 @@ import {
   getWorkspace,
   listWorkspaces,
   updateWorkspaceStatus,
+  setWorkspaceBranch,
+  patchWorkspaceMetadata,
   releaseMergeLease,
   listRepoStewards,
   listMergeLeases,
@@ -96,6 +98,9 @@ import {
   setMessageReaction,
   ValidationError,
 } from "./db";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { listManagedOrchestratorsForAgent } from "./orchestrator-lookup";
+import { bytesToStream, readBodyBytes } from "./http-body";
 import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
 import {
   deleteConfig,
@@ -110,7 +115,6 @@ import {
   setInsightsConfig,
   getWorkspaceConfigEntry,
   setWorkspaceConfig,
-  workspaceSpawnParams,
   listAgentProfiles,
   listSpawnPolicies,
   listConfig,
@@ -152,10 +156,14 @@ import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, par
 import { listHostDirectories } from "./agent-spawn";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
   getIntegrationAuth,
@@ -192,7 +200,8 @@ import { assertMemoryCreateAllowed, assertMemoryUpdateAllowed } from "./memory-s
 import { captureTaskResultMemory, clearActiveMemories, injectAlwaysReloadMemories, injectMemoryContext, injectMemoryForMessageDelivery, injectMemoryForTaskClaim, memoryBroker, memoryBrokerConfig } from "./memory-service";
 import { postMcp } from "./mcp";
 import { readFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
+import { isPathWithinBase } from "./utils";
 import type { ArtifactKind, ArtifactSensitivity, AttachmentRef, ContextBudget, CreateMemoryInput, MemoryBrokerContext, MemoryConfidence, MemoryQuery, MemoryRedactionState, MemorySensitivity, MemoryType, MemoryVisibility, TaskRoutingHints, TokenConstraints, UpdateMemoryInput } from "./types";
 import { issueIntegrationRuntimeToken, issueInteractiveRunnerRuntimeToken, issueMcpRuntimeToken, issueOrchestratorRuntimeToken, reissueRunnerRuntimeToken, runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { listMaintenanceJobs, runLegacyMaintenanceReaper, runMaintenanceJobNow } from "./maintenance";
@@ -256,44 +265,11 @@ type ParseBodyResult<T> =
 
 async function parseBody<T>(req: Request): Promise<ParseBodyResult<T>> {
   if (!req.body) return { ok: true, body: null };
-
-  const reader = req.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let totalBytes = 0;
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (!value) continue;
-
-    totalBytes += value.byteLength;
-    if (totalBytes > MAX_BODY_BYTES) {
-      try {
-        await reader.cancel();
-      } catch {
-        // Ignore cancellation errors — we already know this request is too large.
-      }
-      return {
-        ok: false,
-        status: 413,
-        error: `request body exceeds ${MAX_BODY_BYTES} bytes`,
-      };
-    }
-
-    chunks.push(value);
-  }
-
-  if (totalBytes === 0) return { ok: true, body: null };
-
-  const merged = new Uint8Array(totalBytes);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-
+  const read = await readBodyBytes(req.body, MAX_BODY_BYTES);
+  if (!read.ok) return { ok: false, status: read.status, error: read.error };
+  if (read.bytes.byteLength === 0) return { ok: true, body: null };
   try {
-    const decoded = new TextDecoder().decode(merged);
+    const decoded = new TextDecoder().decode(read.bytes);
     return { ok: true, body: JSON.parse(decoded) as T };
   } catch {
     return { ok: false, status: 400, error: "invalid JSON body" };
@@ -323,14 +299,10 @@ function parseQueryInt(
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "stale", "offline"] as const;
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
 const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool", "policy"] as const;
-const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
 const VALID_WORKSPACE_STATUSES = ["active", "ready", "conflict", "review_requested", "merge_planned", "merged", "abandoned", "cleanup_requested", "cleaned"] as const;
 const VALID_CHANNEL_BINDING_MODES = ["exclusive", "broadcast"] as const;
 const VALID_AGENT_ACTIONS = ["restart", "shutdown", "reconnect", "compact", "clearContext", "resume", "interrupt"] as const;
 const CLAUDE_RESUME_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
-const VALID_CODEX_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-const VALID_PROVIDER_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 const VALID_CONNECTOR_ACTIONS = ["install", "uninstall", "enable", "disable", "start", "stop", "restart", "status", "doctor"] as const;
 const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
 const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "orphaned", "done", "failed", "canceled"] as const;
@@ -349,34 +321,6 @@ const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"]
 const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
 const integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function pathWithinBase(path: string, baseDir: string): boolean {
-  const base = resolve(baseDir);
-  const target = resolve(path);
-  const rel = relative(base, target);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
-function cleanString(
-  value: unknown,
-  field: string,
-  opts: { required?: boolean; max?: number } = {},
-): string | undefined {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return undefined;
-  }
-  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
-  const trimmed = value.trim();
-  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
-  if (opts.max && trimmed.length > opts.max) {
-    throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
-  }
-  return trimmed || undefined;
-}
 
 function cleanNullableString(value: unknown, field: string, max: number): string | null | undefined {
   if (value === undefined) return undefined;
@@ -384,14 +328,6 @@ function cleanNullableString(value: unknown, field: string, max: number): string
   return cleanString(value, field, { max }) ?? null;
 }
 
-function cleanStringArray(value: unknown, field: string): string[] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
-  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: 80 })).filter(Boolean) as string[];
-  if (cleaned.length > 50) throw new ValidationError(`${field} can contain at most 50 values`);
-  return [...new Set(cleaned)];
-}
-
 function cleanConstraintStringArray(value: unknown, field: string): string[] | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
@@ -447,33 +383,20 @@ function cleanParams(value: unknown, field = "params"): Record<string, unknown>
   return value;
 }
 
-function cleanEnum<T extends readonly string[]>(
-  value: unknown,
-  field: string,
-  valid: T,
-  fallback?: T[number],
-): T[number] | undefined {
-  if (value === undefined || value === null) return fallback;
-  if (typeof value !== "string" || !valid.includes(value)) {
-    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  }
-  return value as T[number];
-}
-
 function cleanWorkspaceMetadata(value: unknown, field: string): WorkspaceMetadata | undefined {
   if (value === undefined || value === null) return undefined;
   if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
   return {
     id: cleanString(value.id, `${field}.id`, { max: 160 }),
-    mode: cleanEnum(value.mode, `${field}.mode`, VALID_WORKSPACE_MODES, "shared") as WorkspaceMode,
-    requestedMode: cleanEnum(value.requestedMode, `${field}.requestedMode`, VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+    mode: optionalEnum(value.mode, `${field}.mode`, VALID_WORKSPACE_MODES, "shared") as WorkspaceMode,
+    requestedMode: optionalEnum(value.requestedMode, `${field}.requestedMode`, VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
     repoRoot: cleanString(value.repoRoot, `${field}.repoRoot`, { max: 1000 }),
     sourceCwd: cleanString(value.sourceCwd, `${field}.sourceCwd`, { max: 1000 }),
     worktreePath: cleanString(value.worktreePath, `${field}.worktreePath`, { max: 1000 }),
     branch: cleanString(value.branch, `${field}.branch`, { max: 240 }),
     baseRef: cleanString(value.baseRef, `${field}.baseRef`, { max: 240 }),
     baseSha: cleanString(value.baseSha, `${field}.baseSha`, { max: 80 }),
-    status: cleanEnum(value.status, `${field}.status`, VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined,
+    status: optionalEnum(value.status, `${field}.status`, VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined,
     stewardAgentId: cleanString(value.stewardAgentId, `${field}.stewardAgentId`, { max: 240 }),
     probe: isRecord(value.probe) ? value.probe as unknown as WorkspaceProbe : undefined,
   };
@@ -547,16 +470,16 @@ function normalizeAgentInput(body: unknown): RegisterAgentInput {
   const input: RegisterAgentInput = {
     id: cleanString(body.id, "id", { required: true, max: 200 })!,
     name: cleanString(body.name, "name", { required: true, max: 200 })!,
-    kind: cleanEnum(body.kind, "kind", VALID_AGENT_KINDS) as AgentKind | undefined,
+    kind: optionalEnum(body.kind, "kind", VALID_AGENT_KINDS) as AgentKind | undefined,
     status: status as RegisterAgentInput["status"] | undefined,
     ready: body.ready as boolean | undefined,
   };
 
   const label = cleanNullableString(body.label, "label", 120);
   if (label !== undefined) input.label = label;
-  const tags = cleanStringArray(body.tags, "tags");
+  const tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
   if (tags) input.tags = tags;
-  const capabilities = cleanStringArray(body.capabilities, "capabilities");
+  const capabilities = cleanStringArray(body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 });
   if (capabilities) input.capabilities = capabilities;
   const machine = cleanString(body.machine, "machine", { max: 120 });
   if (machine) input.machine = machine;
@@ -655,14 +578,14 @@ function normalizeChannelBindingInput(body: unknown): {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
   const channelId = cleanString(body.channelId, "channelId", { required: true, max: 200 })!;
   const conversationId = cleanString(body.conversationId, "conversationId", { max: 300 });
-  const mode = cleanEnum(body.mode, "mode", VALID_CHANNEL_BINDING_MODES, "exclusive") as ChannelBindingMode | undefined;
+  const mode = optionalEnum(body.mode, "mode", VALID_CHANNEL_BINDING_MODES, "exclusive") as ChannelBindingMode | undefined;
   const priority = typeof body.priority === "number" && Number.isSafeInteger(body.priority) ? body.priority : undefined;
 
   let target: ChannelRouteTarget | undefined;
   if (typeof body.target === "string") {
     target = routeTargetFromAddress(body.target);
   } else if (isRecord(body.target)) {
-    const type = cleanEnum(body.target.type, "target.type", VALID_CHANNEL_BINDING_TARGET_TYPES)!;
+    const type = optionalEnum(body.target.type, "target.type", VALID_CHANNEL_BINDING_TARGET_TYPES)!;
     const id = type === "broadcast" ? undefined : cleanString(body.target.id, "target.id", { required: true, max: 240 })!;
     if (type === "orchestrator") throw new ValidationError("orchestrator channel targets are not supported yet");
     target = type === "broadcast" ? { type: "broadcast" } : { type, id } as ChannelRouteTarget;
@@ -783,8 +706,8 @@ function validateChannelAttachmentItem(item: unknown, field: string): void {
   if (!isRecord(item)) throw new ValidationError(`${field} must be an object`);
   const artifactId = cleanString(item.artifactId, `${field}.artifactId`, { max: 120 });
   if (artifactId) {
-    cleanEnum(item.kind, `${field}.kind`, VALID_ARTIFACT_KINDS);
-    cleanEnum(item.role, `${field}.role`, VALID_ARTIFACT_ROLES);
+    optionalEnum(item.kind, `${field}.kind`, VALID_ARTIFACT_KINDS);
+    optionalEnum(item.role, `${field}.role`, VALID_ARTIFACT_ROLES);
     cleanString(item.title, `${field}.title`, { max: 240 });
     if (item.ref !== undefined) validateChannelAttachmentSourceRef(item.ref, `${field}.ref`);
     return;
@@ -819,8 +742,8 @@ function cleanAttachmentRefs(value: unknown, field = "attachments"): AttachmentR
     const normalizedRef = isRecord(ref) ? { ref: { ...ref } as AttachmentRef["ref"] } : {};
     return {
       artifactId: cleanString(item.artifactId, `${field}[${index}].artifactId`, { required: true, max: 120 })!,
-      kind: cleanEnum(item.kind, `${field}[${index}].kind`, VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
-      role: cleanEnum(item.role, `${field}[${index}].role`, VALID_ARTIFACT_ROLES) as "media" | "patch" | "report" | "log" | "output" | "input" | undefined,
+      kind: optionalEnum(item.kind, `${field}[${index}].kind`, VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
+      role: optionalEnum(item.role, `${field}[${index}].role`, VALID_ARTIFACT_ROLES) as "media" | "patch" | "report" | "log" | "output" | "input" | undefined,
       title: cleanString(item.title, `${field}[${index}].title`, { max: 240 }),
       ...normalizedRef,
       ...(isRecord(item.metadata) ? { metadata: item.metadata } : {}),
@@ -828,14 +751,6 @@ function cleanAttachmentRefs(value: unknown, field = "attachments"): AttachmentR
   });
 }
 
-function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
-}
 
 function normalizeChannelEventBody(body: unknown): {
   body: string;
@@ -869,11 +784,11 @@ function requireChannelSession(req: Request, body: unknown, channel: ChannelSumm
 
 function normalizeIntegrationEvent(body: unknown): IntegrationEventInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
-  const status = cleanEnum(body.status, "status", [...VALID_TASK_STATUSES, "resolved"] as const);
+  const status = optionalEnum(body.status, "status", [...VALID_TASK_STATUSES, "resolved"] as const);
   return {
     source: cleanString(body.source, "source", { max: 120 }),
     type: cleanString(body.type, "type", { max: 80 }) ?? "event",
-    severity: cleanEnum(body.severity, "severity", VALID_TASK_SEVERITIES, "info"),
+    severity: optionalEnum(body.severity, "severity", VALID_TASK_SEVERITIES, "info"),
     status,
     title: cleanString(body.title, "title", { required: true, max: 240 })!,
     body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
@@ -911,13 +826,13 @@ function normalizeIntegrationRegistryInput(name: string, body: unknown): {
     displayName: cleanString(body.displayName, "displayName", { max: 120 }),
     description: cleanString(body.description, "description", { max: 1000 }),
     enabled: body.enabled as boolean | undefined,
-    scopes: cleanStringArray(body.scopes, "scopes"),
-    targets: cleanStringArray(body.targets, "targets"),
-    channels: cleanStringArray(body.channels, "channels"),
+    scopes: cleanStringArray(body.scopes, "scopes", { itemMax: 80, maxItems: 50 }),
+    targets: cleanStringArray(body.targets, "targets", { itemMax: 80, maxItems: 50 }),
+    channels: cleanStringArray(body.channels, "channels", { itemMax: 80, maxItems: 50 }),
     type: cleanString(body.type, "type", { max: 80 }),
     icon: cleanString(body.icon, "icon", { max: 80 }),
     accentColor: cleanString(body.accentColor, "accentColor", { max: 32 }),
-    tags: cleanStringArray(body.tags, "tags"),
+    tags: cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 }),
     homepageUrl: cleanString(body.homepageUrl, "homepageUrl", { max: 500 }),
     repositoryUrl: cleanString(body.repositoryUrl, "repositoryUrl", { max: 500 }),
     docsUrl: cleanString(body.docsUrl, "docsUrl", { max: 500 }),
@@ -975,7 +890,7 @@ function resolveIntegrationEventTarget(input: IntegrationEventInput): Integratio
 
 function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
-  const status = cleanEnum(body.status, "status", VALID_TASK_STATUSES);
+  const status = optionalEnum(body.status, "status", VALID_TASK_STATUSES);
   if (!status) throw new ValidationError("status required");
   return {
     status: status as TaskStatus,
@@ -1111,7 +1026,7 @@ function normalizeActivityInput(body: unknown): ActivityEventInput {
   return {
     operatorId: cleanOperatorId(body.operatorId),
     clientId: cleanString(body.clientId, "clientId", { max: 240 }),
-    kind: cleanEnum(body.kind, "kind", VALID_ACTIVITY_KINDS, "operator") as ActivityKind,
+    kind: optionalEnum(body.kind, "kind", VALID_ACTIVITY_KINDS, "operator") as ActivityKind,
     title: cleanString(body.title, "title", { required: true, max: 200 })!,
     body: cleanString(body.body, "body", { max: 1000 }),
     meta: cleanString(body.meta, "meta", { max: 500 }),
@@ -1241,7 +1156,7 @@ async function postCallback(deliveryId: number, url: string, payload: unknown):
     });
     finishCallbackDelivery(deliveryId, response.ok, response.ok ? undefined : `${response.status} ${response.statusText}`);
   } catch (e) {
-    finishCallbackDelivery(deliveryId, false, e instanceof Error ? e.message : String(e));
+    finishCallbackDelivery(deliveryId, false, errMessage(e));
   } finally {
     clearTimeout(timeout);
   }
@@ -1558,8 +1473,8 @@ async function artifactUploadInput(req: Request): Promise<{
     const file = form.get("file");
     if (!(file instanceof File)) throw new ValidationError("multipart upload requires file");
     if (file.size > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
-    const sensitivity = cleanEnum(form.get("sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity;
-    const kind = cleanEnum(form.get("kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined;
+    const sensitivity = optionalEnum(form.get("sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity;
+    const kind = optionalEnum(form.get("kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined;
     const expiresAtRaw = form.get("expiresAt");
     const expiresAt = typeof expiresAtRaw === "string" && expiresAtRaw.trim() ? Number(expiresAtRaw) : undefined;
     if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= Date.now())) throw new ValidationError("expiresAt must be a future unix timestamp in milliseconds");
@@ -1587,8 +1502,8 @@ async function artifactUploadInput(req: Request): Promise<{
     filename: cleanString(req.headers.get("X-Artifact-Filename"), "filename", { max: 240 }),
     mediaType: contentType || undefined,
     digest: cleanString(req.headers.get("X-Artifact-Digest"), "digest", { max: 80 }),
-    sensitivity: cleanEnum(req.headers.get("X-Artifact-Sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity,
-    kind: cleanEnum(req.headers.get("X-Artifact-Kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
+    sensitivity: optionalEnum(req.headers.get("X-Artifact-Sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity,
+    kind: optionalEnum(req.headers.get("X-Artifact-Kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
     metadata: undefined,
     expiresAt,
   };
@@ -1601,10 +1516,10 @@ function cleanMemoryQueryFromParams(params: URLSearchParams): MemoryQuery {
   const visibility = params.get("visibility");
   const minRelevance = params.get("minRelevance");
   const limit = params.get("limit");
-  if (type) query.type = cleanEnum(type, "type", VALID_MEMORY_TYPES) as MemoryType;
+  if (type) query.type = optionalEnum(type, "type", VALID_MEMORY_TYPES) as MemoryType;
   if (scope) query.scope = cleanString(scope, "scope", { max: 240 });
   const tags = [...params.getAll("tag"), ...(params.get("tags")?.split(",") ?? [])].map((tag) => tag.trim()).filter(Boolean);
-  if (tags.length) query.tags = cleanStringArray(tags, "tags");
+  if (tags.length) query.tags = cleanStringArray(tags, "tags", { itemMax: 80, maxItems: 50 });
   if (minRelevance !== null) {
     const parsed = Number(minRelevance);
     if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) throw new ValidationError("minRelevance must be between 0 and 1");
@@ -1615,7 +1530,7 @@ function cleanMemoryQueryFromParams(params: URLSearchParams): MemoryQuery {
     if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > 100) throw new ValidationError("limit must be an integer between 1 and 100");
     query.limit = parsed;
   }
-  if (visibility) query.visibility = cleanEnum(visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility;
+  if (visibility) query.visibility = optionalEnum(visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility;
   query.includeExpired = params.get("includeExpired") === "true" ? true : undefined;
   query.includeSensitive = params.get("includeSensitive") === "true" ? true : undefined;
   return query;
@@ -1624,9 +1539,9 @@ function cleanMemoryQueryFromParams(params: URLSearchParams): MemoryQuery {
 function cleanMemoryQueryFromBody(body: unknown): MemoryQuery {
   if (!isRecord(body)) throw new ValidationError("memory query body must be an object");
   const query: MemoryQuery = {};
-  query.type = cleanEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType | undefined;
+  query.type = optionalEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType | undefined;
   query.scope = cleanString(body.scope, "scope", { max: 240 });
-  query.tags = cleanStringArray(body.tags, "tags");
+  query.tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
   if (body.minRelevance !== undefined) {
     if (typeof body.minRelevance !== "number" || body.minRelevance < 0 || body.minRelevance > 1) throw new ValidationError("minRelevance must be between 0 and 1");
     query.minRelevance = body.minRelevance;
@@ -1636,7 +1551,7 @@ function cleanMemoryQueryFromBody(body: unknown): MemoryQuery {
     query.limit = body.limit;
   }
   query.includeExpired = typeof body.includeExpired === "boolean" ? body.includeExpired : undefined;
-  query.visibility = cleanEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
+  query.visibility = optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
   query.includeSensitive = typeof body.includeSensitive === "boolean" ? body.includeSensitive : undefined;
   return query;
 }
@@ -1658,15 +1573,15 @@ function cleanCreateMemoryInput(body: unknown, ctx: MemoryBrokerContext): Create
     ? undefined
     : cleanMemoryPositiveInteger(body.ttlMs, "ttlMs");
   return {
-    type: cleanEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType,
+    type: optionalEnum(body.type, "type", VALID_MEMORY_TYPES) as MemoryType,
     scope: cleanString(body.scope, "scope", { required: true, max: 240 })!,
     title: cleanString(body.title, "title", { required: true, max: 240 })!,
     content: cleanString(body.content, "content", { required: true, max: MAX_BODY_BYTES })!,
-    tags: cleanStringArray(body.tags, "tags"),
-    visibility: cleanEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined,
-    sensitivity: cleanEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined,
-    confidence: cleanEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined,
-    redactionState: cleanEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined,
+    tags: cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 }),
+    visibility: optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined,
+    sensitivity: optionalEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined,
+    confidence: optionalEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined,
+    redactionState: optionalEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined,
     relevanceScore: cleanMemoryScore(body.relevanceScore, "relevanceScore"),
     sourceAgent: cleanString(body.sourceAgent, "sourceAgent", { max: 200 }),
     sourceTask: body.sourceTask === undefined ? undefined : cleanMemoryPositiveInteger(body.sourceTask, "sourceTask"),
@@ -1681,11 +1596,11 @@ function cleanUpdateMemoryInput(body: unknown): UpdateMemoryInput {
   const patch: UpdateMemoryInput = {};
   const title = cleanString(body.title, "title", { max: 240 });
   const content = cleanString(body.content, "content", { max: MAX_BODY_BYTES });
-  const tags = cleanStringArray(body.tags, "tags");
-  const visibility = cleanEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
-  const sensitivity = cleanEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined;
-  const confidence = cleanEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined;
-  const redactionState = cleanEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined;
+  const tags = cleanStringArray(body.tags, "tags", { itemMax: 80, maxItems: 50 });
+  const visibility = optionalEnum(body.visibility, "visibility", VALID_MEMORY_VISIBILITIES) as MemoryVisibility | undefined;
+  const sensitivity = optionalEnum(body.sensitivity, "sensitivity", VALID_MEMORY_SENSITIVITIES) as MemorySensitivity | undefined;
+  const confidence = optionalEnum(body.confidence, "confidence", VALID_MEMORY_CONFIDENCES) as MemoryConfidence | undefined;
+  const redactionState = optionalEnum(body.redactionState, "redactionState", VALID_MEMORY_REDACTION_STATES) as MemoryRedactionState | undefined;
   const relevanceScore = cleanMemoryScore(body.relevanceScore, "relevanceScore");
   const metadata = cleanParams(body.metadata, "metadata");
   if (title !== undefined) patch.title = title;
@@ -1714,7 +1629,7 @@ function cleanMemoryInjectInput(body: unknown): {
 } {
   if (!isRecord(body)) throw new ValidationError("memory injection body must be an object");
   const agentId = cleanString(body.agentId ?? body.target, "agentId", { required: true, max: 200 })!;
-  const memoryIds = cleanStringArray(body.memoryIds, "memoryIds") ?? [];
+  const memoryIds = cleanStringArray(body.memoryIds, "memoryIds", { itemMax: 80, maxItems: 50 }) ?? [];
   const query = body.query === undefined ? undefined : cleanMemoryQueryFromBody(body.query);
   if (memoryIds.length === 0 && !query) throw new ValidationError("memoryIds or query required");
   return {
@@ -1736,8 +1651,8 @@ function cleanTaskRoutingHints(value: unknown): TaskRoutingHints | undefined {
     title: cleanString(value.title, "task.title", { max: 240 }),
     text: cleanString(value.text, "task.text", { max: 4000 }),
     scope: cleanString(value.scope, "task.scope", { max: 240 }),
-    tags: cleanStringArray(value.tags, "task.tags"),
-    capabilities: cleanStringArray(value.capabilities, "task.capabilities"),
+    tags: cleanStringArray(value.tags, "task.tags", { itemMax: 80, maxItems: 50 }),
+    capabilities: cleanStringArray(value.capabilities, "task.capabilities", { itemMax: 80, maxItems: 50 }),
     target: cleanString(value.target, "task.target", { max: 200 }),
   };
 }
@@ -2100,7 +2015,7 @@ const patchAgentTags: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
-    const tags = isRecord(parsed.body) ? cleanStringArray(parsed.body.tags, "tags") : undefined;
+    const tags = isRecord(parsed.body) ? cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }) : undefined;
     if (!tags) return error("tags field required");
     const before = getAgent(params.id!);
     const agent = setTags(params.id!, tags);
@@ -2237,18 +2152,15 @@ function agentRuntimeProvider(agent: AgentCard): string | undefined {
 
 function managedControlOrchestrator(agent: AgentCard): NonNullable<ReturnType<typeof getOrchestrator>> | null {
   if (agent.meta?.runnerManaged !== true) return null;
-  const metaSessionName = typeof agent.meta.sessionName === "string" ? agent.meta.sessionName : "";
-  const metaTmuxSession = typeof agent.meta.tmuxSession === "string" ? agent.meta.tmuxSession : "";
-  const metaPolicyName = typeof agent.meta.policyName === "string" ? agent.meta.policyName : "";
-  const metaSpawnRequestId = typeof agent.meta.spawnRequestId === "string" ? agent.meta.spawnRequestId : "";
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
   const candidates = [
-    ...listOrchestrators().filter((orch) => orch.managedAgents.some((managed) =>
-      managed.agentId === agent.id ||
-      (!!metaSessionName && managed.sessionName === metaSessionName) ||
-      (!!metaTmuxSession && managed.tmuxSession === metaTmuxSession) ||
-      (!!metaPolicyName && managed.policyName === metaPolicyName) ||
-      (!!metaSpawnRequestId && managed.spawnRequestId === metaSpawnRequestId)
-    )),
+    ...listManagedOrchestratorsForAgent({
+      agentId: agent.id,
+      sessionName: str(agent.meta.sessionName),
+      tmuxSession: str(agent.meta.tmuxSession),
+      policyName: str(agent.meta.policyName),
+      spawnRequestId: str(agent.meta.spawnRequestId),
+    }),
     ...(agent.machine ? [getOrchestrator(agent.machine)].filter((orch): orch is NonNullable<ReturnType<typeof getOrchestrator>> => Boolean(orch)) : []),
   ];
   return candidates.find((orch) => orch.status === "online") ?? null;
@@ -2281,39 +2193,22 @@ function restartSpawnParamsForAgent(
   const profileName = metaString(agent.meta, "profile");
   const agentProfile = profileName ? getAgentProfile(profileName)?.value : undefined;
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
-  let resolvedModel: Record<string, string> = {};
-  if (model || effort) {
-    try {
-      const selection = resolveProviderSelection({ provider, model, effort });
-      resolvedModel = {
-        ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
-        ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
-        ...(selection.effort ? { effort: selection.effort } : {}),
-      };
-    } catch {
-      resolvedModel = {
-        ...(model ? { model } : {}),
-        ...(effort ? { effort } : {}),
-      };
-    }
-  }
-  const params = {
-    action: "spawn",
+  const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
+  const params = buildSpawnCommand({
     provider,
-    ...resolvedModel,
+    modelParams: resolvedModel,
     cwd,
     workspaceMode,
-    ...(profileName ? { profile: profileName } : {}),
-    ...(agentProfile ? { agentProfile } : {}),
-    ...workspaceSpawnParams(),
-    ...(label ? { label } : {}),
+    profile: profileName || undefined,
+    agentProfile,
+    label: label || undefined,
     agentId: agent.id,
     tags: agent.tags,
     capabilities: agent.capabilities,
     approvalMode: approvalMode ?? "guarded",
     permissionMode: approvalMode ?? "guarded",
-    ...(providerArgs.length ? { providerArgs } : {}),
-    ...(policyName ? { policyName } : {}),
+    providerArgs: providerArgs.length ? providerArgs : undefined,
+    policyName: policyName || undefined,
     headless: true,
     spawnRequestId: requestId,
     env: runnerRuntimeTokenEnv({
@@ -2327,12 +2222,12 @@ function restartSpawnParamsForAgent(
     }),
     requestedBy,
     requestedAt: Date.now(),
-  };
+  });
   return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
 }
 
 function spawnRequestIdForRestart(): string {
-  return `sp_${crypto.randomUUID()}`;
+  return generateSpawnRequestId();
 }
 
 function withClaudeResumeParams(params: Record<string, unknown>, resumeId: string, agentId: string): Record<string, unknown> {
@@ -2388,7 +2283,7 @@ const postAgentAction: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("action required");
-    const action = cleanEnum(parsed.body.action, "action", VALID_AGENT_ACTIONS);
+    const action = optionalEnum(parsed.body.action, "action", VALID_AGENT_ACTIONS);
     if (!action) return error("action required");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
@@ -2504,7 +2399,7 @@ const postAgentPermissionDecision: Handler = async (req, params) => {
   try {
     if (!isRecord(parsed.body)) return error("permission decision required");
     const approvalId = cleanString(parsed.body.approvalId, "approvalId", { required: true, max: 240 })!;
-    const decision = cleanEnum(parsed.body.decision, "decision", ["approve", "approve-session", "deny", "abort", "answer"] as const);
+    const decision = optionalEnum(parsed.body.decision, "decision", ["approve", "approve-session", "deny", "abort", "answer"] as const);
     if (!decision) return error("decision required");
     const reason = cleanString(parsed.body.reason, "reason", { max: 500 });
     // AskUserQuestion answers: { "<question text>": "<chosen label(s)>" }
@@ -2633,20 +2528,20 @@ const postAgentSpawn: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = cleanEnum(parsed.body.provider, "provider", [...VALID_AGENT_SPAWN_PROVIDERS, "claude"] as const);
+    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS);
     if (!provider) return error("provider required");
     const selection = cleanSpawnSelection(parsed.body, provider as SpawnProvider);
-    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const approvalMode = optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
     const label = cleanString(parsed.body.label, "label", { max: 120 });
-    const workspaceMode = cleanEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
+    const workspaceMode = optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
 
     const orchestrators = listOrchestrators().filter(
       (o) => o.status === "online" && o.providers.includes(provider as SpawnProvider),
     );
 	    const orch = orchestrators[0];
 	    if (!orch) return error("no orchestrator available for provider: " + provider);
-	    if (cwd && !pathWithinBase(cwd, orch.baseDir)) {
+	    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
 	      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
 	    }
 	    const requestId = spawnRequestId();
@@ -2660,10 +2555,9 @@ const postAgentSpawn: Handler = async (req) => {
 	      source: "system",
 	      target: orch.agentId,
 	      correlationId: requestId,
-	      params: {
-	        action: "spawn",
+	      params: buildSpawnCommand({
 	        provider,
-	        ...selection,
+	        modelParams: selection,
 	        cwd: cwd || orch.baseDir,
 	        workspaceMode,
 	        label,
@@ -2679,7 +2573,7 @@ const postAgentSpawn: Handler = async (req) => {
 	          spawnRequestId: requestId,
 	          createdBy: "dashboard",
 	        }),
-	      },
+	      }),
 	    });
     emitCommand(command);
     auditEvent({
@@ -2837,7 +2731,7 @@ function cleanTokenProfileInput(body: unknown, partial = false) {
   const name = cleanString(body.name, "name", { required: !partial, max: 120 });
   const description = cleanString(body.description, "description", { max: 500 });
   const role = cleanString(body.role, "role", { required: !partial, max: 80 });
-  const scope = cleanStringArray(body.scope ?? body.scopes, "scope");
+  const scope = cleanStringArray(body.scope ?? body.scopes, "scope", { itemMax: 80, maxItems: 50 });
   if (!partial && !scope?.length) throw new ValidationError("scope must contain at least one scope");
   const constraints = body.constraints === null ? undefined : cleanTokenConstraints(body.constraints);
   const ttlSeconds = cleanTtlSeconds(body.ttlSeconds);
@@ -2861,7 +2755,7 @@ const postToken: Handler = async (req) => {
     const role = cleanString(parsed.body.role, "role", { max: 80 }) ?? profile?.role;
     if (!role) return error("role required");
     const sub = cleanString(parsed.body.sub, "sub", { max: 160 }) ?? role;
-    const scope = cleanStringArray(parsed.body.scope ?? parsed.body.scopes, "scope");
+    const scope = cleanStringArray(parsed.body.scope ?? parsed.body.scopes, "scope", { itemMax: 80, maxItems: 50 });
     const constraints = cleanTokenConstraints(parsed.body.constraints);
     const createdBy = cleanString(parsed.body.createdBy, "createdBy", { max: 120 });
     const ttlSeconds = cleanTtlSeconds(parsed.body.ttlSeconds);
@@ -2949,7 +2843,7 @@ const postInteractiveRunnerRuntimeToken: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("runtime token body required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
     const cwd = cleanString(parsed.body.cwd, "cwd", { required: true, max: 500 })!;
     const runnerId = cleanString(parsed.body.runnerId, "runnerId", { required: true, max: 240 })!;
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
@@ -2996,9 +2890,9 @@ const postMcpRuntimeToken: Handler = async (req) => {
     if (!isRecord(parsed.body)) return error("runtime token body required");
     const sessionId = cleanString(parsed.body.sessionId, "sessionId", { required: true, max: 240 })!;
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
-    const targets = cleanStringArray(parsed.body.targets, "targets");
-    const channels = cleanStringArray(parsed.body.channels, "channels");
-    const memoryScopes = cleanStringArray(parsed.body.memoryScopes, "memoryScopes");
+    const targets = cleanStringArray(parsed.body.targets, "targets", { itemMax: 80, maxItems: 50 });
+    const channels = cleanStringArray(parsed.body.channels, "channels", { itemMax: 80, maxItems: 50 });
+    const memoryScopes = cleanStringArray(parsed.body.memoryScopes, "memoryScopes", { itemMax: 80, maxItems: 50 });
     const runtimeToken = issueMcpRuntimeToken({
       sessionId,
       agentId,
@@ -3037,8 +2931,8 @@ const postIntegrationRuntimeToken: Handler = async (req) => {
   try {
     if (!isRecord(parsed.body)) return error("runtime token body required");
     const name = cleanString(parsed.body.name, "name", { required: true, max: 120 })!;
-    const targets = cleanStringArray(parsed.body.targets, "targets");
-    const channels = cleanStringArray(parsed.body.channels, "channels");
+    const targets = cleanStringArray(parsed.body.targets, "targets", { itemMax: 80, maxItems: 50 });
+    const channels = cleanStringArray(parsed.body.channels, "channels", { itemMax: 80, maxItems: 50 });
     const runtimeToken = issueIntegrationRuntimeToken({
       name,
       targets,
@@ -3131,9 +3025,6 @@ const postTokenRevoke: Handler = (_req, params) => {
 
 // --- Orchestrator routes ---
 
-const VALID_ORCHESTRATOR_PROVIDERS = ["claude", "codex"] as const;
-const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-
 function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
@@ -3141,27 +3032,17 @@ function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
   return value;
 }
 
-function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): { model?: string; effort?: ProviderEffort; providerModel?: string } {
+function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): SpawnModelParams {
   const model = cleanString(body.model, "model", { max: 120 });
-  const effort = cleanEnum(body.effort, "effort", VALID_PROVIDER_EFFORTS) as ProviderEffort | undefined;
-  let resolved;
-  try {
-    resolved = resolveProviderSelection({ provider, model, effort });
-  } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
-  }
-  return {
-    model: resolved.modelAlias,
-    providerModel: resolved.providerModel,
-    effort: resolved.effort,
-  };
+  const effort = optionalEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  return resolveSpawnModelParams(provider, model, effort);
 }
 
 function validateSpawnSelectionForOrchestrator(
   orch: NonNullable<ReturnType<typeof getOrchestrator>>,
   provider: SpawnProvider,
   body: Record<string, unknown>,
-): { model?: string; effort?: ProviderEffort; providerModel?: string } | Response {
+): SpawnModelParams | Response {
   if (!orch.providers.includes(provider)) {
     return error(`orchestrator does not have provider available: ${provider}`, 409);
   }
@@ -3218,15 +3099,15 @@ const postOrchestrator: Handler = async (req) => {
     const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
     const hostname = cleanString(parsed.body.hostname, "hostname", { required: true, max: 120 })!;
     const baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
-    const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
+    const providers = cleanStringArray(parsed.body.providers, "providers", { itemMax: 80, maxItems: 50 }) as SpawnProvider[] | undefined;
     if (providers) {
       for (const p of providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-          return error(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) {
+          return error(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
         }
       }
     }
-    const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys");
+    const envKeys = cleanStringArray(parsed.body.envKeys, "envKeys", { itemMax: 80, maxItems: 50 });
     const apiUrl = cleanString(parsed.body.apiUrl, "apiUrl", { max: 500 });
     const packageMetadata = cleanRuntimePackageMetadata(parsed.body.package);
     const contracts = cleanRuntimeContracts(parsed.body.contracts);
@@ -3299,13 +3180,13 @@ const postOrchestratorHeartbeat: Handler = async (req, params) => {
       version: cleanString(body.version, "version", { max: 80 }),
       protocolVersion: cleanProtocolVersion(body.protocolVersion),
       gitSha: cleanString(body.gitSha, "gitSha", { max: 80 }),
-      providers: cleanStringArray(body.providers, "providers") as SpawnProvider[] | undefined,
+      providers: cleanStringArray(body.providers, "providers", { itemMax: 80, maxItems: 50 }) as SpawnProvider[] | undefined,
       providerStatus: cleanJsonArray(body.providerStatus, "providerStatus") as OrchestratorRuntimeInput["providerStatus"],
       providerCatalog: cleanJsonArray(body.providerCatalog, "providerCatalog") as OrchestratorRuntimeInput["providerCatalog"],
     };
     if (runtime.providers) {
       for (const p of runtime.providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
       }
     }
     const orch = orchestratorHeartbeat(params.id!, runtime);
@@ -3325,16 +3206,16 @@ const postOrchestratorBootstrap: Handler = async (req) => {
     if (!isRecord(parsed.body)) return error("body required");
     const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
     const baseDir = cleanString(parsed.body.baseDir, "baseDir", { required: true, max: 500 })!;
-    const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
+    const providers = cleanStringArray(parsed.body.providers, "providers", { itemMax: 80, maxItems: 50 }) as SpawnProvider[] | undefined;
     const apiPort = cleanSafeNumber(parsed.body.apiPort) ?? 4860;
     if (!Number.isInteger(apiPort) || apiPort < 1 || apiPort > 65535) throw new ValidationError("apiPort must be an integer from 1 to 65535");
     const relayUrl = cleanString(parsed.body.relayUrl, "relayUrl", { max: 500 }) ?? new URL(req.url).origin;
     const version = cleanString(parsed.body.version, "version", { max: 80 }) ?? VERSION;
-    const pathPrefix = cleanStringArray(parsed.body.pathPrefix, "pathPrefix");
+    const pathPrefix = cleanStringArray(parsed.body.pathPrefix, "pathPrefix", { itemMax: 80, maxItems: 50 });
     const providerList = providers?.length ? providers : ["claude", "codex"];
     for (const p of providerList) {
-      if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-        throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+      if (!SPAWN_PROVIDERS.includes(p as any)) {
+        throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
       }
     }
     const bootstrapToken = createToken({
@@ -3425,19 +3306,19 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
         ?? cleanString(a.tmuxSession, "tmuxSession", { required: true, max: 240 })!;
       return {
         agentId: cleanString(a.agentId, "agentId", { max: 240 }) || "",
-        provider: cleanEnum(a.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider,
+        provider: optionalEnum(a.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider,
         sessionName,
         tmuxSession: cleanString(a.tmuxSession, "tmuxSession", { max: 240 }) ?? sessionName,
-        supervisor: cleanEnum(a.supervisor, "supervisor", ["process", "systemd", "launchd", "unknown"] as const),
+        supervisor: optionalEnum(a.supervisor, "supervisor", ["process", "systemd", "launchd", "unknown"] as const),
         systemdUnit: cleanString(a.systemdUnit, "systemdUnit", { max: 240 }),
         terminalSession: cleanString(a.terminalSession, "terminalSession", { max: 240 }),
         terminalAvailable: typeof a.terminalAvailable === "boolean" ? a.terminalAvailable : undefined,
         cwd: cleanString(a.cwd, "cwd", { required: true, max: 500 })!,
         profile: cleanString(a.profile, "profile", { max: 120 }),
-        workspaceMode: cleanEnum(a.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
+        workspaceMode: optionalEnum(a.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
         workspace: cleanWorkspaceMetadata(a.workspace, "workspace"),
         label: cleanString(a.label, "label", { max: 120 }),
-        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") ?? "guarded") as SpawnApprovalMode,
+        approvalMode: (optionalEnum(a.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") ?? "guarded") as SpawnApprovalMode,
         policyName: cleanString(a.policyName, "policyName", { max: 120 }),
         spawnRequestId: cleanString(a.spawnRequestId, "spawnRequestId", { max: 160 }),
         automationRunId: cleanString(a.automationRunId, "automationRunId", { max: 160 }),
@@ -3502,7 +3383,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
 
 function cleanManagedSessionExitDiagnostics(value: unknown, index: number): ManagedSessionExitDiagnostics {
   if (!isRecord(value)) throw new ValidationError(`exitedAgents[${index}] must be an object`);
-  const provider = cleanEnum(value.provider, `exitedAgents[${index}].provider`, VALID_ORCHESTRATOR_PROVIDERS);
+  const provider = optionalEnum(value.provider, `exitedAgents[${index}].provider`, SPAWN_PROVIDERS);
   if (!provider) throw new ValidationError(`exitedAgents[${index}].provider required`);
   const systemd = isRecord(value.systemd)
     ? {
@@ -3531,7 +3412,7 @@ function cleanManagedSessionExitDiagnostics(value: unknown, index: number): Mana
   const diagnostics: ManagedSessionExitDiagnostics = {
     agentId: cleanString(value.agentId, `exitedAgents[${index}].agentId`, { required: true, max: 240 })!,
     provider: provider as SpawnProvider,
-    workspaceMode: cleanEnum(value.workspaceMode, `exitedAgents[${index}].workspaceMode`, VALID_WORKSPACE_MODES),
+    workspaceMode: optionalEnum(value.workspaceMode, `exitedAgents[${index}].workspaceMode`, VALID_WORKSPACE_MODES),
     workspace: cleanWorkspaceMetadata(value.workspace, `exitedAgents[${index}].workspace`),
     sessionName: cleanString(value.sessionName, `exitedAgents[${index}].sessionName`, { max: 240 }),
     tmuxSession: cleanString(value.tmuxSession, `exitedAgents[${index}].tmuxSession`, { required: true, max: 240 })!,
@@ -3540,7 +3421,7 @@ function cleanManagedSessionExitDiagnostics(value: unknown, index: number): Mana
     policyName: cleanString(value.policyName, `exitedAgents[${index}].policyName`, { max: 120 }),
     spawnRequestId: cleanString(value.spawnRequestId, `exitedAgents[${index}].spawnRequestId`, { max: 160 }),
     automationRunId: cleanString(value.automationRunId, `exitedAgents[${index}].automationRunId`, { max: 160 }),
-    supervisor: cleanEnum(value.supervisor, `exitedAgents[${index}].supervisor`, ["process", "systemd", "launchd", "unknown"] as const, "unknown")!,
+    supervisor: optionalEnum(value.supervisor, `exitedAgents[${index}].supervisor`, ["process", "systemd", "launchd", "unknown"] as const, "unknown")!,
     systemdUnit: cleanString(value.systemdUnit, `exitedAgents[${index}].systemdUnit`, { max: 240 }),
     terminalSession: cleanString(value.terminalSession, `exitedAgents[${index}].terminalSession`, { max: 240 }),
     terminalAvailable: typeof value.terminalAvailable === "boolean" ? value.terminalAvailable : undefined,
@@ -3576,22 +3457,22 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
     if (orch.status !== "online") return error("orchestrator is offline", 409);
 
     if (!isRecord(parsed.body)) return error("body required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    const provider = optionalEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
     const selection = validateSpawnSelectionForOrchestrator(orch, provider, parsed.body);
     if (selection instanceof Response) return selection;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
-    if (cwd && !pathWithinBase(cwd, orch.baseDir)) {
+    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
       return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
     }
     const label = cleanString(parsed.body.label, "label", { max: 120 });
-    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const approvalMode = optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
     const prompt = cleanString(parsed.body.prompt, "prompt", { max: 16000 });
     const systemPromptAppend = cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 });
-    const tags = cleanStringArray(parsed.body.tags, "tags") ?? [];
-    const capabilities = cleanStringArray(parsed.body.capabilities, "capabilities") ?? [];
-    const providerArgs = cleanStringArray(parsed.body.providerArgs, "providerArgs") ?? [];
+    const tags = cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }) ?? [];
+    const capabilities = cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }) ?? [];
+    const providerArgs = cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }) ?? [];
     const profile = cleanString(parsed.body.profile, "profile", { max: 120 });
-    const workspaceMode = cleanEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
+    const workspaceMode = optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
     const agentProfile = profile ? getAgentProfile(profile)?.value : undefined;
     if (profile && !agentProfile) return error("agent profile not found", 404);
 	    const policyName = cleanString(parsed.body.policyName, "policyName", { max: 120 });
@@ -3607,12 +3488,9 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
       source: "system",
       target: orch.agentId,
 	      correlationId: requestId,
-      params: {
-        action: "spawn",
+      params: buildSpawnCommand({
         provider,
-        model: selection.model,
-        providerModel: selection.providerModel,
-        effort: selection.effort,
+        modelParams: { model: selection.model, providerModel: selection.providerModel, effort: selection.effort },
         cwd: cwd || orch.baseDir,
         workspaceMode,
         label,
@@ -3622,7 +3500,6 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
         permissionMode: approvalMode,
         profile,
         agentProfile,
-        ...workspaceSpawnParams(),
         providerArgs,
         prompt,
         systemPromptAppend,
@@ -3639,7 +3516,7 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
 	        }),
 	        requestedBy: "dashboard",
         requestedAt: Date.now(),
-      },
+      }),
     });
     emitCommand(command);
     auditEvent({
@@ -3769,7 +3646,7 @@ const postOrchestratorAction: Handler = async (req, params) => {
     if (!orch) return error("orchestrator not found", 404);
 
     if (!isRecord(parsed.body)) return error("body required");
-    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown", "upgrade"] as const);
+    const action = optionalEnum(parsed.body.action, "action", ["restart", "shutdown", "upgrade"] as const);
     if (!action) return error("action required");
 
     if (action === "upgrade") {
@@ -3778,7 +3655,7 @@ const postOrchestratorAction: Handler = async (req, params) => {
       const targetVersion = cleanString(parsed.body.targetVersion, "targetVersion", { max: 80 }) ?? VERSION;
       if (!ORCH_UPGRADE_SEMVER_RE.test(targetVersion)) return error("targetVersion must be a semver like 0.10.20");
       const force = parsed.body.force === true;
-      const providers = (cleanStringArray(parsed.body.providers, "providers") ?? ["orchestrator"])
+      const providers = (cleanStringArray(parsed.body.providers, "providers", { itemMax: 80, maxItems: 50 }) ?? ["orchestrator"])
         .filter((p) => (VALID_ORCH_UPGRADE_PROVIDERS as readonly string[]).includes(p));
       if (!providers.length) return error(`providers must be any of: ${VALID_ORCH_UPGRADE_PROVIDERS.join(", ")}`);
       const selfUpgradeError = orchestratorSelfUpgradeError(orch);
@@ -3908,7 +3785,7 @@ const getWorkspaces: Handler = (req) => {
     const url = new URL(req.url);
     const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
     const ownerAgentId = cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 240 });
-    const status = cleanEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+    const status = optionalEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
     return json(listWorkspaces({ repoRoot, ownerAgentId, status }));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -3936,7 +3813,7 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
     return json({ available: false, reason: "no isolated worktree" });
   }
   const orch = listOrchestrators().find(
-    (candidate) => candidate.status === "online" && candidate.apiUrl && pathWithinBase(workspace.sourceCwd, candidate.baseDir),
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
   );
   if (!orch?.apiUrl) return json({ available: false, reason: "owning orchestrator offline" });
   const query = new URLSearchParams({ path: workspace.worktreePath });
@@ -3945,7 +3822,7 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
   for (const [key, value] of Object.entries(extraQuery ?? {})) query.set(key, value);
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(`${orch.apiUrl}${hostPath}?${query.toString()}`, {
       headers,
@@ -3987,11 +3864,11 @@ const getWorkspaceOrphans: Handler = async () => {
   const repoRoots = [...new Set(all.map((ws) => ws.repoRoot).filter(Boolean))];
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   const orphans: WorkspaceOrphan[] = [];
 
   for (const repoRoot of repoRoots) {
-    const orch = orchestrators.find((candidate) => candidate.apiUrl && pathWithinBase(repoRoot, candidate.baseDir));
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     let probe: WorkspaceProbe | undefined;
     try {
@@ -4029,7 +3906,7 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
     // Refuse to reclaim a path that still backs a live workspace row.
     const live = listWorkspaces().find((ws) => ws.worktreePath && resolve(ws.worktreePath) === resolve(worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
     if (live) return error(`path backs live workspace ${live.id}; clean it through the workspace, not orphan reclaim`, 409);
-    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && pathWithinBase(repoRoot, candidate.baseDir));
+    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
     if (!orch) return error("no online orchestrator owns this path", 409);
     const command = createCommand({
       type: "workspace.cleanup",
@@ -4055,6 +3932,191 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
   }
 };
 
+// Build a `workspace.cleanup` command for a worktree's owning orchestrator. Shared
+// by the manual cleanup action and the cleanup-stale sweep (#208) so both resolve
+// the owner and shape params identically. Queues (no TTL) when the owner is offline;
+// hard-fails only when no orchestrator owns the path (DELETE is then the escape).
+function buildWorkspaceCleanupCommand(workspace: WorkspaceRecord, requestedBy: string): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
+  const command = createCommand({
+    type: "workspace.cleanup",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "cleanup",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      branch: workspace.branch,
+      requestedBy,
+      requestedAt: Date.now(),
+      deleteBranch: true,
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+// Build a `workspace.deps-refresh` command for a worktree's owning orchestrator
+// (issue #51). Re-provisions deps the shared symlinked node_modules has gone stale
+// on, or — checkOnly — just reports staleness. Same owner-resolution as cleanup.
+function buildWorkspaceDepsRefreshCommand(workspace: WorkspaceRecord, requestedBy: string, checkOnly: boolean): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  if (!owner) return { ok: false, status: 409, error: "no online orchestrator owns this workspace path" };
+  const command = createCommand({
+    type: "workspace.deps-refresh",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "deps-refresh",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      checkOnly,
+      requestedBy,
+      requestedAt: Date.now(),
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+// Fetch + parse a workspace's live git state from its owning host, or report why
+// it's unavailable. Thin typed wrapper over the same host route the proxy uses.
+async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ state: WorkspaceGitState } | { unavailable: string }> {
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) return { unavailable: "no isolated worktree" };
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return { unavailable: "owning orchestrator offline" };
+  const query = new URLSearchParams({ path: workspace.worktreePath });
+  if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
+  if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}/api/workspace/state?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { unavailable: `host returned ${res.status}` };
+    return { state: await res.json() as WorkspaceGitState };
+  } catch (e) {
+    return { unavailable: `orchestrator unreachable: ${(e as Error).message}` };
+  }
+}
+
+// Recommend the next action for a workspace from its joined state — the steward's
+// (and a release agent's) "what should happen here?" without reconstructing it.
+function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnline: boolean; gitState?: WorkspaceGitState; claim: ReturnType<typeof workspaceActiveClaim> }): WorkspaceDiagnostics["recommendation"] {
+  const { workspace, ownerOnline, gitState, claim } = input;
+  if (claim) return { action: "wait", confidence: "high", reason: `claimed by ${claim.by ?? "steward"}` };
+  if (TERMINAL_WORKSPACE_STATUSES.has(workspace.status)) return { action: "none", confidence: "high", reason: `workspace is ${workspace.status}` };
+  if (!gitState || gitState.error) return { action: "review", confidence: "low", reason: gitState?.error ? `git state error: ${gitState.error}` : "git state unavailable" };
+  if (gitState.missing) return { action: "cleanup", confidence: "high", reason: "worktree no longer exists on disk" };
+  const ahead = gitState.unmergedAhead ?? gitState.ahead ?? 0;
+  const landed = gitState.landed === true;
+  if ((gitState.dirtyCount ?? 0) > 0) return { action: "review", confidence: "medium", reason: `${gitState.dirtyCount} uncommitted change(s)` };
+  if (ahead === 0 || landed) {
+    if (!ownerOnline) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner offline" : "no unmerged commits; owner offline" };
+    return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
+  }
+  if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
+    return { action: "wait", confidence: "medium", reason: "owner active and not awaiting review" };
+  }
+  if (workspace.status === "conflict") return { action: "rebase", confidence: "high", reason: "conflict — rebase onto base and resolve" };
+  if ((gitState.behind ?? 0) > 0) return { action: "rebase", confidence: "medium", reason: `${gitState.behind} behind base — rebase then merge` };
+  return { action: "merge", confidence: "high", reason: `${ahead} commit(s) ready to land` };
+}
+
+// Joined steward briefing for one workspace (#208): row + owner/orchestrator
+// liveness + live git state + branch mismatch + active claim + recommended action.
+const getWorkspaceDiagnostics: Handler = async (_req, params) => {
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+  const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+  const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const orchOnline = Boolean(orch) && orch!.status === "online";
+  const fetched = await fetchWorkspaceGitState(workspace);
+  const gitState = "state" in fetched ? fetched.state : undefined;
+  const claim = workspaceActiveClaim(workspace);
+  const liveBranch = gitState?.branch;
+  const diagnostics: WorkspaceDiagnostics = {
+    workspaceId: workspace.id,
+    status: workspace.status,
+    mode: workspace.mode,
+    repoRoot: workspace.repoRoot,
+    worktreePath: workspace.worktreePath,
+    recordedBranch: workspace.branch,
+    liveBranch,
+    baseRef: workspace.baseRef,
+    branchMismatch: workspace.branch && liveBranch ? workspace.branch !== liveBranch : undefined,
+    owner: { id: workspace.ownerAgentId, status: owner?.status, online: ownerOnline },
+    orchestrator: { id: orch?.id, online: orchOnline },
+    ...(claim ? { claim: { by: claim.by, purpose: claim.purpose, expiresAt: claim.expiresAt } } : {}),
+    ...(gitState ? { gitState } : { gitStateUnavailable: "unavailable" in fetched ? fetched.unavailable : "unknown" }),
+    recommendation: recommendWorkspaceAction({ workspace, ownerOnline, gitState, claim }),
+  };
+  return json(diagnostics);
+};
+
+// Guarded batch cleanup of stale worktrees (#208 / steward report §3). Defaults to
+// dry-run and only ever proposes/cleans worktrees that are provably safe: offline
+// owner, not claimed, clean tree, and (landed-only) work already in base or empty.
+// Never touches a live owner. Reuses the same cleanup command path as the manual action.
+const postWorkspaceCleanupStale: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(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 });
+  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),
+  );
+
+  const rows: Array<Record<string, unknown>> = [];
+  const cleaned: string[] = [];
+  for (const ws of candidates) {
+    const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
+    const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+    if (ownerOnline) continue;                         // never clean a live owner's worktree
+    if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
+    if (workspaceActiveClaim(ws)) continue;            // respect steward claims
+    const fetched = await fetchWorkspaceGitState(ws);
+    const gitState = "state" in fetched ? fetched.state : undefined;
+    const missing = gitState?.missing === true;
+    const dirtyCount = gitState?.dirtyCount;
+    const ahead = gitState?.unmergedAhead ?? gitState?.ahead ?? 0;
+    const landed = gitState?.landed === true;
+    // Safe = gone from disk, OR clean tree with no unmerged work (landed/empty).
+    const safe = missing || (gitState !== undefined && (dirtyCount ?? 1) === 0 && (!landedOnly || landed || ahead === 0));
+    const proof = { ownerStatus: owner?.status ?? "missing", ownerOnline, ahead, behind: gitState?.behind, landed, dirtyCount, missing, gitStateUnavailable: gitState ? undefined : ("unavailable" in fetched ? fetched.unavailable : undefined) };
+    const row: Record<string, unknown> = { workspaceId: ws.id, branch: ws.branch, worktreePath: ws.worktreePath, repoRoot: ws.repoRoot, safe, proof };
+    if (safe && !dryRun) {
+      const built = buildWorkspaceCleanupCommand(ws, "cleanup-stale");
+      if (built.ok) {
+        updateWorkspaceStatus(ws.id, "cleanup_requested", { lastWorkspaceAction: "cleanup-stale", lastWorkspaceActionAt: Date.now(), cleanupProof: proof });
+        emitCommand(built.command);
+        row.commandId = built.command.id;
+        cleaned.push(ws.id);
+      } else {
+        row.cleanupError = built.error;
+      }
+    }
+    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);
+};
+
 const postWorkspaceAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -4062,7 +4124,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
     if (!isRecord(parsed.body)) return error("body required");
     const workspace = getWorkspace(params.id!);
     if (!workspace) return error("workspace not found", 404);
-    const action = cleanEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup"] as const);
+    const action = optionalEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup", "claim", "release-claim", "deps-refresh"] as const);
     if (!action) return error("action required", 400);
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
     const detail = cleanString(parsed.body.detail, "detail", { max: 4000 });
@@ -4076,10 +4138,30 @@ const postWorkspaceAction: Handler = async (req, params) => {
     const denied = authorizeRoute(req, { scope: requiresCommand ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
     if (denied) return denied;
     if (action === "status") return json(workspace);
+    // Steward claim/lease (#208): a TTL'd metadata lease that auto-merge yields to,
+    // so deterministic landing can't race a steward mid-validation. No status change.
+    if (action === "claim" || action === "release-claim") {
+      const release = action === "release-claim";
+      const purpose = cleanString(parsed.body.purpose, "purpose", { max: 120 });
+      const updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", purpose));
+      if (!updated) return error("workspace not found", 404);
+      auditEvent({
+        clientId: `workspace-${action}-${workspace.id}-${Date.now()}`,
+        kind: "state",
+        title: release ? "Workspace claim released" : "Workspace claimed",
+        body: detail ?? purpose ?? workspace.worktreePath,
+        meta: workspace.branch ?? workspace.id,
+        icon: "ti-lock",
+        view: "orchestrators",
+        agentId,
+        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, ...authAuditMetadata(req) },
+      });
+      return json({ workspace: updated, claim: workspaceActiveClaim(updated) });
+    }
     // Base merges go through the shared helper (lease + command + bind), the same
     // path the auto-merge job uses, so both serialize per repo (issue #157).
     if (action === "merge") {
-      const strategy = cleanEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy;
+      const strategy = optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy;
       const result = requestWorkspaceMerge(workspace, {
         requestedBy: agentId ?? "dashboard",
         strategy,
@@ -4103,6 +4185,31 @@ const postWorkspaceAction: Handler = async (req, params) => {
       });
       return json({ workspace: result.workspace, command: result.command }, 202);
     }
+    // Deps refresh (#51): self-service for the owning agent — re-provision deps the
+    // shared symlinked node_modules has gone stale on. Emits a host command but is
+    // authorized at agent:write (it only touches the agent's own worktree), so the
+    // agent can run it themselves the moment typecheck reports a missing module.
+    if (action === "deps-refresh") {
+      if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+        return error(`workspace ${workspace.id} has no isolated worktree to refresh`, 422);
+      }
+      const checkOnly = parsed.body.checkOnly === true;
+      const built = buildWorkspaceDepsRefreshCommand(workspace, agentId ?? "agent", checkOnly);
+      if (!built.ok) return error(built.error, built.status);
+      emitCommand(built.command);
+      auditEvent({
+        clientId: `workspace-deps-refresh-${workspace.id}-${Date.now()}`,
+        kind: "state",
+        title: checkOnly ? "Workspace deps check" : "Workspace deps refresh",
+        body: detail ?? workspace.worktreePath,
+        meta: workspace.branch ?? workspace.id,
+        icon: "ti-package",
+        view: "orchestrators",
+        agentId,
+        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, checkOnly, commandId: built.command.id, ...authAuditMetadata(req) },
+      });
+      return json({ workspace, command: built.command }, 202);
+    }
     const statusByAction: Record<string, WorkspaceStatus | undefined> = {
       status: undefined,
       ready: "ready",
@@ -4123,30 +4230,9 @@ const postWorkspaceAction: Handler = async (req, params) => {
     let command: Command | undefined;
     if (requiresCommand) {
       // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-      // Cleanup may queue: if the owning orchestrator is offline, the command (no
-      // TTL) waits and reconciles when it reconnects. Only hard-fail when no
-      // orchestrator owns the path at all — then DELETE is the escape.
-      const owners = listOrchestrators().filter((candidate) => pathWithinBase(workspace.sourceCwd, candidate.baseDir));
-      const onlineOwner = owners.find((candidate) => candidate.status === "online");
-      const owner = onlineOwner ?? owners[0];
-      if (!owner) return error("no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record", 409);
-      command = createCommand({
-        type: "workspace.cleanup",
-        source: "system",
-        target: owner.agentId,
-        correlationId: workspace.id,
-        params: {
-          action: "cleanup",
-          workspaceId: workspace.id,
-          repoRoot: workspace.repoRoot,
-          worktreePath: workspace.worktreePath,
-          branch: workspace.branch,
-          requestedBy: agentId ?? "dashboard",
-          requestedAt: Date.now(),
-          deleteBranch: true,
-          queued: owner.status !== "online",
-        },
-      });
+      const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+      if (!built.ok) return error(built.error, built.status);
+      command = built.command;
       emitCommand(command);
     }
     auditEvent({
@@ -4198,7 +4284,7 @@ async function proxyOrchestratorGet(req: Request, orchestratorId: string, path:
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(proxyUrl, { headers, signal: AbortSignal.timeout(10_000) });
     const contentType = res.headers.get("content-type") ?? "";
@@ -4223,7 +4309,7 @@ async function proxyOrchestratorPost(req: Request, orchestratorId: string, path:
     "Content-Type": req.headers.get("content-type") ?? "application/json",
   };
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const body = await req.text();
     const res = await fetch(proxyUrl, {
@@ -4248,7 +4334,7 @@ async function proxyOrchestratorDelete(req: Request, orchestratorId: string, pat
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(proxyUrl, {
       method: "DELETE",
@@ -4269,7 +4355,7 @@ async function proxyOrchestratorJson(orchestratorId: string, path: string, metho
   if (orch.status !== "online") return error("orchestrator is offline", 422);
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(`${orch.apiUrl}${path}`, {
       method,
@@ -4294,11 +4380,11 @@ const getOrchestratorProviders: Handler = async (req, params) => {
   const payload = await res.clone().json().catch(() => null) as unknown;
   if (!isRecord(payload)) return res;
   try {
-    const providers = cleanStringArray(payload.providers, "providers") as SpawnProvider[] | undefined;
+    const providers = cleanStringArray(payload.providers, "providers", { itemMax: 80, maxItems: 50 }) as SpawnProvider[] | undefined;
     if (providers) {
       for (const p of providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-          throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) {
+          throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
         }
       }
     }
@@ -4438,7 +4524,7 @@ const patchCommand: Handler = async (req, params) => {
     if (!current) return error("command not found", 404);
     const denied = authorizeRoute(req, { scope: "command:write", resource: commandAuthorizationResource(current) });
     if (denied) return denied;
-    const status = cleanEnum(parsed.body.status, "status", VALID_COMMAND_STATUSES);
+    const status = optionalEnum(parsed.body.status, "status", VALID_COMMAND_STATUSES);
     const result = cleanParams(parsed.body.result, "result");
     const err = cleanString(parsed.body.error, "error", { max: 4000 });
     const command = updateCommand(params.id!, { status: status as CommandStatus | undefined, result, error: err });
@@ -4476,13 +4562,25 @@ const patchCommand: Handler = async (req, params) => {
       }
       if (command.status === "succeeded" && isRecord(command.result)) {
         const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
-        const resultStatus = cleanEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+        const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
         if (workspaceId && resultStatus) {
           updateWorkspaceStatus(workspaceId, resultStatus, {
             mergeResult: command.result,
             mergeCommandId: command.id,
             mergedAt: Date.now(),
+            // The land consumes the steward's claim (#208 steward contract / vent
+            // #62): a successful land must release it, or `steward inspect` keeps
+            // showing a stale claim on the recycled workspace and blocks the next
+            // automation. Clearing a null claim (auto-merge path) is a harmless no-op.
+            ...claimMetadataPatch(true),
           });
+          // Land-and-continue (#206): the worktree was recycled onto a fresh branch.
+          // Repoint the row so the next merge targets the live branch, not the deleted one.
+          const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+          if (newBranch) {
+            const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
+            setWorkspaceBranch(workspaceId, newBranch, mergedSha);
+          }
         }
       } else if (command.status === "failed" && command.correlationId) {
         // Merge couldn't complete — don't leave it stuck in merge_planned.
@@ -4497,7 +4595,7 @@ const patchCommand: Handler = async (req, params) => {
     }
     if (command.type === "workspace.reconcile" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
-      const resultStatus = cleanEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+      const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
       const removed = command.result.removed === true;
       if (workspaceId && resultStatus) {
         // Only act on workspaces the agent left in a live state; never overwrite
@@ -4530,6 +4628,14 @@ const patchCommand: Handler = async (req, params) => {
         }
       }
     }
+    if (command.type === "workspace.deps-refresh" && command.status === "succeeded" && isRecord(command.result)) {
+      // Record the outcome on the row without touching status (#51) — observability
+      // for the dashboard; the CLI reads the result straight off the command.
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      if (workspaceId) {
+        patchWorkspaceMetadata(workspaceId, { lastDepsRefresh: command.result, lastDepsRefreshCommandId: command.id, lastDepsRefreshAt: Date.now() });
+      }
+    }
     settleFailedOrchestratorUpgrade(command);
     emitCommand(command);
     auditCommandOutcome(command);
@@ -4774,7 +4880,7 @@ const getConfigKeyHistory: Handler = (req, params) => {
 // --- Spawn policy routes ---
 
 function spawnRequestId(): string {
-  return `sp_${crypto.randomUUID()}`;
+  return generateSpawnRequestId();
 }
 
 function policyStatusPayload(policy: SpawnPolicy) {
@@ -4996,13 +5102,13 @@ const getProviderConfigsRoute: Handler = () => {
 };
 
 const getProviderConfigRoute: Handler = (_req, params) => {
-  const provider = cleanEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
   if (!provider) return error("provider required");
   return json(providerConfigPublic(loadProviderConfig(provider)));
 };
 
 const putProviderConfigRoute: Handler = async (req, params) => {
-  const provider = cleanEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
   if (!provider) return error("provider required");
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -5012,13 +5118,13 @@ const putProviderConfigRoute: Handler = async (req, params) => {
     const headless = isRecord(parsed.body.headless) ? parsed.body.headless : {};
     const config: ProviderConfig = {
       command: cleanString(parsed.body.command, "command", { required: true, max: 500 })!,
-      defaultArgs: cleanStringArray(parsed.body.defaultArgs, "defaultArgs") ?? defaults.defaultArgs,
+      defaultArgs: cleanStringArray(parsed.body.defaultArgs, "defaultArgs", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultArgs,
       env: cleanEnvRecord(parsed.body.env),
-      pluginDirs: cleanStringArray(parsed.body.pluginDirs, "pluginDirs") ?? defaults.pluginDirs,
-      defaultCapabilities: cleanStringArray(parsed.body.defaultCapabilities, "defaultCapabilities") ?? defaults.defaultCapabilities,
+      pluginDirs: cleanStringArray(parsed.body.pluginDirs, "pluginDirs", { itemMax: 80, maxItems: 50 }) ?? defaults.pluginDirs,
+      defaultCapabilities: cleanStringArray(parsed.body.defaultCapabilities, "defaultCapabilities", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultCapabilities,
       defaultApprovalMode: cleanString(parsed.body.defaultApprovalMode, "defaultApprovalMode", { max: 80 }) ?? defaults.defaultApprovalMode,
-      defaultTags: cleanStringArray(parsed.body.defaultTags, "defaultTags") ?? defaults.defaultTags,
-      chatCaptureMode: (cleanEnum(parsed.body.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
+      defaultTags: cleanStringArray(parsed.body.defaultTags, "defaultTags", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultTags,
+      chatCaptureMode: (optionalEnum(parsed.body.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
       headless: {
         tmuxPrefix: cleanString(headless.tmuxPrefix, "headless.tmuxPrefix", { max: 120 }) ?? defaults.headless.tmuxPrefix,
         shutdownTimeoutMs: cleanPositiveInt(headless.shutdownTimeoutMs, "headless.shutdownTimeoutMs") ?? defaults.headless.shutdownTimeoutMs,
@@ -5032,7 +5138,7 @@ const putProviderConfigRoute: Handler = async (req, params) => {
 };
 
 const postProviderConfigTestRoute: Handler = async (_req, params) => {
-  const provider = cleanEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
   if (!provider) return error("provider required");
   const config = loadProviderConfig(provider);
   const proc = Bun.spawn(["bash", "-lc", `command -v "$1"`, "bash", config.command], {
@@ -5107,7 +5213,7 @@ const postMessageDeliveryAttempt: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) throw new ValidationError("body must be an object");
-    const status = cleanEnum(parsed.body.status, "status", VALID_DELIVERY_STATUSES);
+    const status = optionalEnum(parsed.body.status, "status", VALID_DELIVERY_STATUSES);
     if (!status) throw new ValidationError("status required");
     const nextRetryAt = cleanPositiveId(parsed.body.nextRetryAt, "nextRetryAt");
     const result = recordMessageDeliveryAttempt(id, {
@@ -5133,7 +5239,7 @@ const postMessageDeliveryAction: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) throw new ValidationError("body must be an object");
-    const action = cleanEnum(parsed.body.action, "action", VALID_DELIVERY_ACTIONS);
+    const action = optionalEnum(parsed.body.action, "action", VALID_DELIVERY_ACTIONS);
     if (!action) throw new ValidationError("action required");
     const result = applyMessageDeliveryAction(id, {
       action,
@@ -5182,7 +5288,7 @@ const postMessage: Handler = async (req) => {
           const memoryInjection = await injectMemoryForMessageDelivery(result.message, autoMemoryTarget, memoryContext(req));
           if (memoryInjection) emitCommand(memoryInjection.command);
         } catch (e) {
-          console.warn(`[memory] automatic message context assembly failed: ${e instanceof Error ? e.message : String(e)}`);
+          console.warn(`[memory] automatic message context assembly failed: ${errMessage(e)}`);
         }
       }
       if (result.message.deliveryStatus === "queued") {
@@ -5686,7 +5792,7 @@ const postConnectorAction: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) throw new ValidationError("JSON object body required");
-    const action = cleanEnum(parsed.body.action, "action", VALID_CONNECTOR_ACTIONS)!;
+    const action = optionalEnum(parsed.body.action, "action", VALID_CONNECTOR_ACTIONS)!;
     const result = await runConnectorAction(params.id!, action);
     return json(result, result.ok ? 200 : 502);
   } catch (e) {
@@ -6166,7 +6272,7 @@ const postClaimTask: Handler = async (req, params) => {
     const memoryInjection = await injectMemoryForTaskClaim(result.task!, agentId);
     if (memoryInjection) emitCommand(memoryInjection.command);
   } catch (e) {
-    console.warn(`[memory] automatic task context assembly failed: ${e instanceof Error ? e.message : String(e)}`);
+    console.warn(`[memory] automatic task context assembly failed: ${errMessage(e)}`);
   }
   void dispatchTaskCallbacks(id, "task.claimed");
   return json(result.task);
@@ -6572,9 +6678,11 @@ const routes: Route[] = [
   route("GET", "/api/workspaces/orphans", getWorkspaceOrphans),
   route("POST", "/api/workspaces/orphans/reclaim", postWorkspaceOrphanReclaim),
   route("GET", "/api/workspaces/stewards", getWorkspaceStewards),
+  route("POST", "/api/workspaces/actions/cleanup-stale", postWorkspaceCleanupStale),
   route("GET", "/api/workspaces/:id", getWorkspaceById),
   route("GET", "/api/workspaces/:id/git-state", getWorkspaceGitState),
   route("GET", "/api/workspaces/:id/merge-preview", getWorkspaceMergePreview),
+  route("GET", "/api/workspaces/:id/diagnostics", getWorkspaceDiagnostics),
   route("GET", "/api/workspaces/:id/diff", getWorkspaceDiff),
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),