agent-relay-server 0.18.0 → 0.19.1

package/src/routes.ts

@@ -98,7 +98,9 @@ import {
   setMessageReaction,
   ValidationError,
 } from "./db";
-import { cleanString } from "./validation";
+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,
@@ -155,7 +157,7 @@ import { listHostDirectories } from "./agent-spawn";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+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";
@@ -263,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" };
@@ -359,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`);
@@ -422,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,
   };
@@ -522,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;
@@ -630,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;
@@ -758,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;
@@ -794,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 } : {}),
@@ -803,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;
@@ -844,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 })!,
@@ -886,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 }),
@@ -950,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,
@@ -1086,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 }),
@@ -1216,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);
   }
@@ -1533,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");
@@ -1562,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,
   };
@@ -1576,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");
@@ -1590,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;
@@ -1599,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;
@@ -1611,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;
 }
@@ -1633,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"),
@@ -1656,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;
@@ -1689,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 {
@@ -1711,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 }),
   };
 }
@@ -2075,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);
@@ -2212,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;
@@ -2346,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);
@@ -2462,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)>" }
@@ -2591,13 +2528,13 @@ 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", SPAWN_PROVIDERS);
+    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", APPROVAL_MODES, "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),
@@ -2794,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);
@@ -2818,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);
@@ -2906,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", SPAWN_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 });
@@ -2953,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,
@@ -2994,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,
@@ -3097,7 +3034,7 @@ function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
 
 function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): SpawnModelParams {
   const model = cleanString(body.model, "model", { max: 120 });
-  const effort = cleanEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  const effort = optionalEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
   return resolveSpawnModelParams(provider, model, effort);
 }
 
@@ -3162,7 +3099,7 @@ 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 (!SPAWN_PROVIDERS.includes(p as any)) {
@@ -3170,7 +3107,7 @@ const postOrchestrator: Handler = async (req) => {
         }
       }
     }
-    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);
@@ -3243,7 +3180,7 @@ 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"],
     };
@@ -3269,12 +3206,12 @@ 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 (!SPAWN_PROVIDERS.includes(p as any)) {
@@ -3369,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", SPAWN_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", APPROVAL_MODES, "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 }),
@@ -3446,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`, SPAWN_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)
     ? {
@@ -3475,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 })!,
@@ -3484,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,
@@ -3520,7 +3457,7 @@ 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", SPAWN_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 });
@@ -3528,14 +3465,14 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
       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", APPROVAL_MODES, "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 });
@@ -3709,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") {
@@ -3718,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);
@@ -3848,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);
@@ -4023,6 +3960,32 @@ function buildWorkspaceCleanupCommand(workspace: WorkspaceRecord, requestedBy: s
   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 }> {
@@ -4161,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", "claim", "release-claim"] 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 });
@@ -4198,7 +4161,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
     // 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,
@@ -4222,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",
@@ -4392,7 +4380,7 @@ 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 (!SPAWN_PROVIDERS.includes(p as any)) {
@@ -4536,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 });
@@ -4574,12 +4562,17 @@ 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.
@@ -4602,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
@@ -4635,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);
@@ -5101,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);
@@ -5117,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,
@@ -5137,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], {
@@ -5212,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, {
@@ -5238,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,
@@ -5287,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") {
@@ -5791,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) {
@@ -6271,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);