agent-relay-server 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.9"
+    "agent-relay-sdk": "0.2.10"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -10830,6 +10830,10 @@ function stringValue(value) {
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : void 0;
 }
+/** Extract a human-readable message from any thrown value. */
+function errMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region src/lib/display.ts
 function toTimestamp(value) {
@@ -123777,7 +123781,7 @@ function TerminalViewer({ orchestratorId, session, interactive: initialInteracti
 		try {
 			writeSnapshot(await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/terminal/${encodeURIComponent(session)}`));
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			inFlightRef.current = false;
 		}
@@ -123834,7 +123838,7 @@ function TerminalViewer({ orchestratorId, session, interactive: initialInteracti
 		for (const chunk of chunks) inputQueueRef.current = inputQueueRef.current.then(() => apiCall("POST", `/orchestrators/${encodeURIComponent(orchestratorId)}/terminal/${encodeURIComponent(session)}/input`, { data: chunk })).then(() => {
 			setError(null);
 		}).catch((e) => {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		});
 	}
 	function handleTerminalData(data) {
@@ -124429,7 +124433,7 @@ function useFileRead(orchestratorId, selectedPath) {
 		}).catch((e) => {
 			if (!cancelled) {
 				setFile(null);
-				setError(e instanceof Error ? e.message : String(e));
+				setError(errMessage(e));
 			}
 		}).finally(() => {
 			if (!cancelled) setLoading(false);
@@ -124467,7 +124471,7 @@ function useFileListing(orchestratorId, selectedPath, git = false) {
 		}).catch((e) => {
 			if (!cancelled) {
 				setListing(null);
-				setError(e instanceof Error ? e.message : String(e));
+				setError(errMessage(e));
 			}
 		}).finally(() => {
 			if (!cancelled) setLoading(false);
@@ -124783,7 +124787,7 @@ function FileBrowser({ overlay = false }) {
 			setPathDraft(result.path);
 			setReadError("");
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setLoading(false);
 		}
@@ -128124,7 +128128,7 @@ function LogViewer({ orchestratorId, session, lines = 200 }) {
 			setLogLines((await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/logs/${encodeURIComponent(session)}?lines=${lines}${stream === "mirror" ? "&stream=mirror" : ""}`)).lines || []);
 			setError(null);
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		}
 	}
 	(0, import_react.useEffect)(() => {
@@ -152926,7 +152930,7 @@ function InsightsView() {
 			setProjects(obs.projects);
 			setNow(Date.now());
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		}
 	}
 	(0, import_react.useEffect)(() => {
@@ -152946,7 +152950,7 @@ function InsightsView() {
 			setVersion(entry.version);
 		} catch (e) {
 			setConfig(previous);
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setSaving(false);
 		}
@@ -156470,7 +156474,7 @@ function DirectoryBrowserDialog({ open, onOpenChange, onSelect, orchestratorId,
 			const query = path ? `?path=${encodeURIComponent(path)}` : "";
 			setListing(await apiCall("GET", `/orchestrators/${encodeURIComponent(orchestratorId)}/directories${query}`));
 		} catch (e) {
-			setError(e instanceof Error ? e.message : String(e));
+			setError(errMessage(e));
 		} finally {
 			setLoading(false);
 		}
@@ -156494,7 +156498,7 @@ function DirectoryBrowserDialog({ open, onOpenChange, onSelect, orchestratorId,
 			setCreating(false);
 			setNewDirName("");
 		} catch (e) {
-			setCreateError(e instanceof Error ? e.message : String(e));
+			setCreateError(errMessage(e));
 		}
 	}
 	function handleSelect() {

package/runner/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { stringValue } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ProviderConfig } from "./adapter";
 
 interface GlobalRunnerConfig {
@@ -98,7 +99,7 @@ export function providerConfigPublic(config: LoadedProviderConfig): Record<strin
 
 export function runnerId(provider: string, cwd: string, label?: string): string {
   const project = cwd.split("/").filter(Boolean).at(-1) || "workspace";
-  const cleanLabel = (label || project).replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  const cleanLabel = sanitizeFsName(label || project, { replacement: "-", lowercase: true });
   return `${hostname()}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
 }
 

package/src/automations.ts

@@ -13,11 +13,11 @@ import {
   ValidationError,
 } from "./db";
 import { createCommand } from "./commands-db";
-import { cleanString } from "./validation";
+import { cleanEnum, cleanString, cleanStringArray, optionalEnum } from "./validation";
 import { getAgentProfile, getSpawnPolicy } from "./config-store";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
-import { VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { errMessage, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import type {
   AgentCard,
@@ -119,27 +119,12 @@ function rowToAutomationRun(row: any): AutomationRun {
   };
 }
 
-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`);
-  return [...new Set(value.map((item) => cleanString(item, `${field} item`, { max: 100 })).filter(Boolean) as string[])];
-}
-
 function cleanBool(value: unknown, field: string): boolean | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
   return value;
 }
 
-function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] {
-  if (value === undefined || value === null) {
-    if (fallback !== undefined) return fallback;
-    throw new ValidationError(`${field} required`);
-  }
-  if (typeof value !== "string" || !valid.includes(value)) throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  return value as T[number];
-}
-
 function cleanMeta(value: unknown, field = "metadata"): Record<string, unknown> | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError(`${field} must be an object`);
@@ -153,7 +138,7 @@ function normalizeTaskTemplate(value: unknown): AutomationTaskTemplate {
   return {
     title: cleanString(input.title, "taskTemplate.title", { required: true, max: 240 })!,
     body: cleanString(input.body, "taskTemplate.body", { required: true, max: 200_000 })!,
-    severity: cleanEnum(input.severity, "taskTemplate.severity", ["info", "warning", "critical"] as const, "info") as TaskSeverity,
+    severity: optionalEnum(input.severity, "taskTemplate.severity", ["info", "warning", "critical"] as const, "info") as TaskSeverity,
     dedupeKey: cleanString(input.dedupeKey, "taskTemplate.dedupeKey", { max: 240 }),
     externalUrl: cleanString(input.externalUrl, "taskTemplate.externalUrl", { max: 1000 }),
     metadata: cleanMeta(input.metadata, "taskTemplate.metadata"),
@@ -207,13 +192,13 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
       selector: {
         provider: cleanString(selectorInput.provider, "targetPolicy.selector.provider", { max: 40 }) as "claude" | "codex" | undefined,
         label: cleanString(selectorInput.label, "targetPolicy.selector.label", { max: 120 }),
-        tags: cleanStringArray(selectorInput.tags, "targetPolicy.selector.tags"),
-        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities"),
+        tags: cleanStringArray(selectorInput.tags, "targetPolicy.selector.tags", { itemMax: 100 }),
+        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities", { itemMax: 100 }),
       },
-      ifNoMatch: cleanEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
+      ifNoMatch: optionalEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
     };
   }
-  const provider = cleanEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex");
+  const provider = optionalEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex");
   const model = cleanString(input.model, "targetPolicy.model", { max: 120 });
   const effort = input.effort === undefined || input.effort === null ? undefined : cleanEnum(input.effort, "targetPolicy.effort", VALID_EFFORTS) as ProviderEffort;
   const profile = cleanString(input.profile, "targetPolicy.profile", { max: 120 });
@@ -221,7 +206,7 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
   try {
     resolveProviderSelection({ provider, model, effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   return {
     mode,
@@ -229,9 +214,9 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
     model,
     effort,
     cwd: cleanString(input.cwd, "targetPolicy.cwd", { max: 500 }),
-    workspaceMode: cleanEnum(input.workspaceMode, "targetPolicy.workspaceMode", VALID_WORKSPACE_MODES, "inherit"),
+    workspaceMode: optionalEnum(input.workspaceMode, "targetPolicy.workspaceMode", VALID_WORKSPACE_MODES, "inherit"),
     profile,
-    approvalMode: cleanEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
+    approvalMode: optionalEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
     keepAlive: cleanBool(input.keepAlive, "targetPolicy.keepAlive") ?? false,
     runtimeBudget: normalizeRuntimeBudget(input),
     shutdownAfterMs: typeof input.shutdownAfterMs === "number" && Number.isSafeInteger(input.shutdownAfterMs) && input.shutdownAfterMs >= 0
@@ -251,8 +236,8 @@ function normalizeCreateInput(input: CreateAutomationInput): Required<Omit<Creat
     enabled: cleanBool(input.enabled, "enabled") ?? true,
     schedule,
     timezone,
-    catchUpPolicy: cleanEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
-    concurrencyPolicy: cleanEnum(input.concurrencyPolicy, "concurrencyPolicy", ["skip", "queue", "replace"] as const, DEFAULT_CONCURRENCY),
+    catchUpPolicy: optionalEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
+    concurrencyPolicy: optionalEnum(input.concurrencyPolicy, "concurrencyPolicy", ["skip", "queue", "replace"] as const, DEFAULT_CONCURRENCY),
     orchestratorId: cleanString(input.orchestratorId, "orchestratorId", { required: true, max: 160 })!,
     targetPolicy: normalizeTargetPolicy(input.targetPolicy),
     taskTemplate: normalizeTaskTemplate(input.taskTemplate),
@@ -511,7 +496,7 @@ function dispatchAutomationRun(automation: Automation, run: AutomationRun, now:
     updateRun(run.id, {
       status: "failed",
       finishedAt: now,
-      error: e instanceof Error ? e.message : String(e),
+      error: errMessage(e),
     }, now);
     return { automation, run: getAutomationRun(run.id)! };
   }

package/src/bus.ts

@@ -14,7 +14,7 @@ import {
   type BusFrame,
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
-import { isRecord, stringValue } from "agent-relay-sdk";
+import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, Task } from "./types";
 
@@ -79,7 +79,7 @@ export function busHandleMessage(ws: BusWebSocket, data: string | Buffer): void
   try {
     handleFrame(ws, frame);
   } catch (error) {
-    sendError(ws, frame.id, "FRAME_FAILED", error instanceof Error ? error.message : String(error));
+    sendError(ws, frame.id, "FRAME_FAILED", errMessage(error));
   }
 }
 

package/src/cli.ts

@@ -44,7 +44,9 @@ import {
 import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "./memory-broker-smoke";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sdk/context-probe";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 
 const HELP = `
 agent-relay ${VERSION}
@@ -63,7 +65,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--execute] [--json]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]
@@ -231,6 +233,11 @@ Isolated workspaces
     agent-relay workspace status   Show your workspace's branch, base, status.
   The base branch will move as other agents land in parallel — that is normal,
   let the merge handle it. Never push your branch yourself; it is local-only.
+  If typecheck/build fails on a missing module (a dep added to the base after
+  your worktree was created), do NOT run a clean install — it mutates the shared
+  node_modules. Instead refresh your worktree's deps in isolation:
+    agent-relay workspace deps     Re-provision deps that have gone stale.
+    agent-relay workspace deps --check   Report staleness without installing.
 
 Rules of thumb
   If you are handling relay message #123, reply with:
@@ -626,10 +633,6 @@ async function readStdin(): Promise<string> {
   return value;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
 function currentClaudeStatusLineCommand(): string | undefined {
   const settingsPath = join(process.env.HOME || homedir(), ".claude", "settings.json");
   try {
@@ -1421,6 +1424,35 @@ function formatWorkspaceStatus(ws: any): string {
   return lines.join("\n");
 }
 
+// Poll a command to a terminal state (succeeded/failed). Returns undefined on
+// timeout so the caller can degrade to "dispatched, check later".
+async function pollCommand(id: string, timeoutMs: number): Promise<{ status?: string; result?: unknown; error?: string } | undefined> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const cmd = await apiRequest("GET", `/api/commands/${encodeURIComponent(id)}`) as { status?: string; result?: unknown; error?: string };
+    if (cmd.status === "succeeded" || cmd.status === "failed") return cmd;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return undefined;
+}
+
+function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolean): string {
+  if (result.error && (!result.dirs || result.dirs.length === 0)) return `Deps ${checkOnly ? "check" : "refresh"}: ${result.error}`;
+  const lines: string[] = [];
+  for (const d of result.dirs) {
+    const icon = d.status === "installed" ? "↻" : d.status === "stale" ? "✗" : d.status === "failed" ? "!" : "✓";
+    const detail = d.status === "ok" ? "up to date"
+      : d.status === "installed" ? `reinstalled${d.wasSymlink ? " (was symlinked)" : ""}`
+      : d.status === "stale" ? `stale — missing ${d.missing?.join(", ") ?? "?"}`
+      : `failed — ${d.error ?? "unknown"}`;
+    lines.push(`  ${icon} ${d.dir}: ${detail}`);
+  }
+  const header = checkOnly
+    ? (result.stale ? "Deps check: stale dirs found — run `agent-relay workspace deps` to refresh" : "Deps check: all dirs up to date")
+    : (result.refreshed ? "Deps refreshed" : result.error ? "Deps refresh hit errors" : "Deps already up to date");
+  return [header, ...lines].join("\n");
+}
+
 // Self-service workspace lifecycle for agents in isolated worktrees (#205) plus
 // steward coordination (#208).
 //   status — read your workspace row     ready — hand off for review/landing
@@ -1430,9 +1462,9 @@ function formatWorkspaceStatus(ws: any): string {
 //   cleanup-stale — guarded batch cleanup of stale worktrees (dry-run by default)
 async function handleWorkspaceCommand(args: string[]): Promise<void> {
   const action = args[0];
-  const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale"]);
+  const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
   if (!action || !valid.has(action)) {
-    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--execute] [--json]");
+    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]");
   }
 
   let id = currentWorkspaceId();
@@ -1440,6 +1472,7 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
   let purpose: string | undefined;
   let repo: string | undefined;
   let execute = false;
+  let check = false;
   let json = false;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -1448,6 +1481,8 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
     else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
     else if (arg === "--execute") execute = true;
+    else if (arg === "--check") check = true;
+    else if (arg === "--refresh") check = false; // explicit no-op default for clarity
     else if (arg === "--json") json = true;
     else throw new Error(`Unknown workspace option "${arg}".`);
   }
@@ -1477,6 +1512,32 @@ async function handleWorkspaceCommand(args: string[]): Promise<void> {
     return;
   }
 
+  // Refresh (or --check) deps the shared symlinked node_modules has gone stale on
+  // (#51). Emits a host command; poll it to a terminal state so the agent gets a
+  // synchronous result and knows when to re-run typecheck.
+  if (action === "deps") {
+    const from = await detectAgentId();
+    const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, { action: "deps-refresh", agentId: from, checkOnly: check }) as { command?: { id?: string } };
+    const commandId = res.command?.id;
+    const settled = commandId ? await pollCommand(commandId, 180_000) : undefined;
+    const result = (settled?.result ?? null) as WorkspaceDepsRefreshResult | null;
+    if (json) {
+      console.log(JSON.stringify(settled ?? res, null, 2));
+      return;
+    }
+    if (settled?.status === "failed") {
+      console.error(`Deps ${check ? "check" : "refresh"} failed: ${settled.error ?? "unknown error"}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!result) {
+      console.log(`Deps ${check ? "check" : "refresh"} dispatched (command ${commandId ?? "?"}) — host did not report back in time. Check \`agent-relay workspace deps --json\`.`);
+      return;
+    }
+    console.log(formatDepsRefresh(result, check));
+    return;
+  }
+
   const from = await detectAgentId();
   const actionBody: Record<string, unknown> =
     action === "ready" ? { action: "request-review", agentId: from }

package/src/config-store.ts

@@ -1,7 +1,7 @@
 import { getDb, ValidationError } from "./db";
-import { cleanString } from "./validation";
+import { cleanEnum, cleanString, cleanStringArray } from "./validation";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { isRecord, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type {
   AgentProfile,
   AgentProfileBase,
@@ -155,17 +155,6 @@ function rowToManagedAgentState(row: ManagedAgentStateRow): ManagedAgentState {
   };
 }
 
-function cleanStringArray(value: unknown, field: string, opts: { required?: boolean } = {}): string[] {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return [];
-  }
-  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
-  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: 120 })).filter(Boolean) as string[];
-  if (cleaned.length > 100) throw new ValidationError(`${field} can contain at most 100 values`);
-  return [...new Set(cleaned)];
-}
-
 function cleanStringRecord(value: unknown, field: string): Record<string, string> {
   if (value === undefined || value === null) return {};
   if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
@@ -196,13 +185,6 @@ function cleanNumber(value: unknown, field: string, opts: { min: number; max: nu
   return value;
 }
 
-function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
-  if (typeof value !== "string" || !valid.includes(value)) {
-    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  }
-  return value as T[number];
-}
-
 function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Partial<AgentProfile>): AgentProfile {
   const isolated = input.base !== "host";
   return {
@@ -279,7 +261,7 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
       : cleanEnum(value.provider, "provider", VALID_PROFILE_PROVIDERS),
     instructions: {
       system: cleanString(instructions.system, "instructions.system", { max: 16_000 }),
-      append: cleanStringArray(instructions.append, "instructions.append"),
+      append: cleanStringArray(instructions.append, "instructions.append", { itemMax: 120, maxItems: 100 }) ?? [],
       repoInstructions: instructions.repoInstructions === undefined
         ? defaults.instructions.repoInstructions
         : cleanEnum(instructions.repoInstructions, "instructions.repoInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
@@ -332,10 +314,10 @@ function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
     model: cleanString(value.model, "model", { max: 120 }),
     effort: value.effort === undefined || value.effort === null ? undefined : cleanEnum(value.effort, "effort", VALID_EFFORTS) as ProviderEffort,
     profile: cleanString(value.profile, "profile", { max: 120 }),
-    providerArgs: cleanStringArray(value.providerArgs, "providerArgs"),
+    providerArgs: cleanStringArray(value.providerArgs, "providerArgs", { itemMax: 120, maxItems: 100 }) ?? [],
     prompt: cleanString(value.prompt, "prompt", { max: 16_000 }),
-    tags: cleanStringArray(value.tags, "tags"),
-    capabilities: cleanStringArray(value.capabilities, "capabilities"),
+    tags: cleanStringArray(value.tags, "tags", { itemMax: 120, maxItems: 100 }) ?? [],
+    capabilities: cleanStringArray(value.capabilities, "capabilities", { itemMax: 120, maxItems: 100 }) ?? [],
     label: cleanString(value.label, "label", { max: 120 }),
     mode,
     permissionMode: cleanEnum(value.permissionMode, "permissionMode", VALID_PERMISSION_MODES),
@@ -346,7 +328,7 @@ function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
   try {
     resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   if (policy.profile && !getAgentProfile(policy.profile)) throw new ValidationError("agent profile not found");
   if (mode === "on-demand") policy.onDemand = cleanOnDemand(value.onDemand);
@@ -409,7 +391,7 @@ function validateStewardConfig(value: unknown): StewardConfig {
   try {
     resolveProviderSelection({ provider: config.provider, model: config.model, effort: config.effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   return config;
 }
@@ -467,7 +449,7 @@ const WORKSPACE_CONFIG_DEFAULTS: WorkspaceConfig = {
 
 function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
   if (!isRecord(value)) throw new ValidationError("workspace config value must be an object");
-  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths");
+  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths", { itemMax: 120, maxItems: 100 }) ?? [];
   // Reject absolute paths and parent-traversal up front: symlink sources must stay
   // inside the main checkout. The orchestrator re-checks containment at link time,
   // but failing here gives the operator immediate feedback in the dashboard.

package/src/daemon.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { constants, existsSync } from "node:fs";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -460,10 +461,6 @@ function quoteSystemdArg(value: string): string {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
 function xmlEscape(value: string): string {
   return value
     .replace(/&/g, "&")

package/src/db.ts

@@ -5079,14 +5079,21 @@ function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord |
     // preserved and metadata is merged, not replaced.
     const existing = getWorkspace(workspace.id);
     const preserveStatus = existing != null && existing.status !== "active";
+    // The branch (and advanced base) change ONLY via the relay's own land-and-continue
+    // recycle (setWorkspaceBranch repoints to `<branch>-N` and bumps base_sha). The
+    // runner keeps re-reporting its spawn-time branch on every heartbeat, and the
+    // recycle returns status to "active" — so without this the next heartbeat clobbers
+    // the repoint back to the original branch, and the next land targets a deleted
+    // branch and strands the work (vent #62 follow-up). Trust the existing row's
+    // branch/base over registration; only a brand-new row takes the runner's values.
     return upsertWorkspace({
       id: workspace.id,
       repoRoot: workspace.repoRoot,
       sourceCwd: workspace.sourceCwd ?? agent.cwd,
       worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
+      branch: existing?.branch ?? workspace.branch,
       baseRef: workspace.baseRef,
-      baseSha: workspace.baseSha,
+      baseSha: existing?.baseSha ?? workspace.baseSha,
       mode: workspace.mode,
       requestedMode: workspace.requestedMode,
       status: preserveStatus ? existing!.status : (workspace.status ?? "active"),

package/src/dev.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname as osHostname } from "node:os";
@@ -504,7 +505,3 @@ function quote(value: string): string {
   if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) return value;
   return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
 }
-
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}

package/src/http-body.ts

@@ -0,0 +1,49 @@
+/** Concatenate body chunks into a single contiguous Uint8Array. */
+export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const output = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return output;
+}
+
+/** Wrap bytes in a single-chunk ReadableStream (e.g. for artifact `storage.store`). */
+export function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Drain a request body stream into a single Uint8Array, enforcing a byte cap.
+ * Returns a 413 result the moment the running total exceeds `maxBytes` (cancels
+ * the reader). Single home for the read-loop that `parseBody` (routes) and
+ * `parseJsonRpcRequest` (mcp) each open-coded — they differed only in the cap.
+ * Callers handle body-absence and decoding.
+ */
+export async function readBodyBytes(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 413; error: string }> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {});
+      return { ok: false, status: 413, error: `request body exceeds ${maxBytes} bytes` };
+    }
+    chunks.push(value);
+  }
+  return { ok: true, bytes: concatBytes(chunks) };
+}

package/src/index.ts

@@ -30,6 +30,7 @@ import {
 } from "./security";
 import { handleCli } from "./cli";
 import { startMaintenanceScheduler } from "./maintenance";
+import { errMessage } from "agent-relay-sdk";
 
 async function main(): Promise<void> {
   const result = await handleCli(process.argv.slice(2));
@@ -393,7 +394,7 @@ function staticContentType(pathname: string): string | undefined {
 
 if (import.meta.main) {
   main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(errMessage(error));
     process.exit(1);
   });
 }

package/src/maintenance.ts

@@ -34,7 +34,7 @@ import {
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
-import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
 import { emitRelayEvent } from "./events";
@@ -931,7 +931,7 @@ async function runDueMaintenanceJobs(): Promise<void> {
   for (const row of rows) {
     const definition = definitions.find((job) => job.id === row.id);
     if (definition) void runJob(definition).catch((error) => {
-      console.warn(`maintenance job ${definition.id} failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.warn(`maintenance job ${definition.id} failed: ${errMessage(error)}`);
     });
   }
 }
@@ -999,7 +999,7 @@ async function runJob(definition: MaintenanceJobDefinition, options: { force?: b
   } catch (error) {
     const finishedAt = Date.now();
     const durationMs = finishedAt - startedAt;
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errMessage(error);
     db.query(`
       UPDATE maintenance_jobs
       SET last_run_at = ?, next_run_at = ?, last_duration_ms = ?, last_status = 'failed',