agent-relay-server 0.18.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "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

@@ -39,12 +39,15 @@ import {
   detectUpgradeSnapshot,
   executeUpgradePlan,
   formatUpgradePlan,
+  resolveLocalOrchestratorId,
   type UpgradeProvider,
 } from "./upgrade";
 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 { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 
 const HELP = `
 agent-relay ${VERSION}
@@ -53,6 +56,8 @@ Usage:
   agent-relay [start]
   agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--runtime-prefix DIR] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
   agent-relay upgrade [--dry-run] [--version VERSION] [--runtime-prefix DIR] [--providers auto|all|codex|claude|orchestrator] [--no-restart] [--yes]
+  agent-relay upgrade --host ID [--host ID2 ...] [--version VERSION] [--providers ...]   (upgrade remote orchestrator hosts over the relay)
+  agent-relay upgrade --all-hosts [...]                                                  (upgrade this host, then every behind remote host)
   agent-relay setup upgrade [same options as upgrade]
   agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
   agent-relay orchestrator install [options]
@@ -63,7 +68,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]
@@ -133,6 +138,8 @@ Upgrade options:
   --version VERSION Target version (default: latest published server version)
   --runtime-prefix DIR  Isolated Agent Relay npm prefix (default: ~/.agent-relay/runtime)
   --providers LIST  Provider integrations to upgrade: auto, all, codex, claude, orchestrator
+  --host ID         Upgrade a remote orchestrator host over the relay (repeatable). Skips the local upgrade
+  --all-hosts       Upgrade this host, then fan out to every connected remote host that is behind
   --no-restart      Do not restart agent-relay.service
   --dry-run         Print detected state and planned commands
   --yes             Skip confirmation prompts
@@ -231,6 +238,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:
@@ -384,6 +396,8 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
   let runtimePrefix: string | undefined;
   const pathPrefix: string[] = [];
   const providers: UpgradeProvider[] = [];
+  const hosts: string[] = [];
+  let allHosts = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -392,6 +406,8 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
     else if (arg === "--providers" && i + 1 < args.length) {
       for (const provider of args[++i]!.split(",")) providers.push(parseUpgradeProvider(provider));
     } else if (arg === "--provider" && i + 1 < args.length) providers.push(parseUpgradeProvider(args[++i]!));
+    else if (arg === "--host" && i + 1 < args.length) hosts.push(args[++i]!);
+    else if (arg === "--all-hosts") allHosts = true;
     else if (arg === "--codex") providers.push("codex");
     else if (arg === "--claude") providers.push("claude");
     else if (arg === "--orchestrator") providers.push("orchestrator");
@@ -403,6 +419,14 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
     else throw new Error(`Unknown upgrade option "${arg}"`);
   }
 
+  // Remote-only: drive named hosts' self-upgrade over the relay command bus and
+  // skip the local upgrade entirely (#210). `--all-hosts` instead upgrades this
+  // host first, then fans out to every behind remote (handled after the local run).
+  if (hosts.length && !allHosts) {
+    await runRemoteOrchestratorUpgrades({ hosts, targetVersion, providers, json, dryRun, yes });
+    return;
+  }
+
   const snapshot = await detectUpgradeSnapshot({
     ...(targetVersion ? { targetVersion } : {}),
     ...(runtimePrefix ? { runtimePrefix } : {}),
@@ -418,11 +442,13 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
 
   if (json) {
     console.log(JSON.stringify({ plan }, null, 2));
+    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, dryRun: true });
     return;
   }
 
   if (dryRun) {
     console.log(formatUpgradePlan(plan, { dryRun: true }));
+    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, dryRun: true });
     return;
   }
 
@@ -436,6 +462,101 @@ async function handleUpgradeCommand(args: string[]): Promise<void> {
   }
 
   console.log(await executeUpgradePlan(plan));
+
+  if (allHosts) {
+    await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, yes: true });
+  }
+}
+
+/**
+ * Trigger orchestrator self-upgrade on remote hosts via the relay command bus
+ * (#210). Each host installs its own runtime + self-restarts; the relay settles
+ * the version when it re-registers. Replaces the manual ssh + npm install dance.
+ */
+async function runRemoteOrchestratorUpgrades(opts: {
+  hosts?: string[];
+  allBehind?: boolean;
+  targetVersion?: string;
+  providers: UpgradeProvider[];
+  json?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+}): Promise<void> {
+  const targetVersion = opts.targetVersion ?? VERSION;
+  const orchestrators = (await apiRequest("GET", "/api/orchestrators")) as Array<{
+    id: string;
+    version?: string;
+  }>;
+  const byId = new Map(orchestrators.map((orch) => [orch.id, orch]));
+  const localId = resolveLocalOrchestratorId();
+  // Default to "all" so a remote host's provider runner is upgraded too, not just
+  // the orchestrator package (matters for hosts running claude/codex agents).
+  const remoteProviders: UpgradeProvider[] = opts.providers.length ? opts.providers : ["all"];
+
+  let targets: string[];
+  if (opts.allBehind) {
+    targets = orchestrators
+      .filter((orch) => orch.id !== localId && orch.version && orch.version !== targetVersion)
+      .map((orch) => orch.id);
+    if (!targets.length) {
+      if (opts.json) console.log(JSON.stringify({ remoteUpgrades: [] }, null, 2));
+      else console.log(`No remote orchestrators behind ${targetVersion}.`);
+      return;
+    }
+  } else {
+    targets = opts.hosts ?? [];
+  }
+
+  if (opts.dryRun) {
+    const lines = targets.map((id) => {
+      const orch = byId.get(id);
+      const from = orch ? orch.version ?? "unknown" : "(not connected)";
+      return `  ${id}: ${from} → ${targetVersion} (providers: ${remoteProviders.join(",")})`;
+    });
+    if (opts.json) console.log(JSON.stringify({ remoteUpgrades: targets.map((id) => ({ id, targetVersion, providers: remoteProviders, dryRun: true })) }, null, 2));
+    else console.log(`Remote orchestrator upgrade plan → ${targetVersion}:\n${lines.join("\n")}`);
+    return;
+  }
+
+  if (!opts.yes && !opts.json) {
+    console.log(`Trigger remote orchestrator upgrade → ${targetVersion} for: ${targets.join(", ")}`);
+    const ok = await confirm("Send remote upgrade command(s)?");
+    if (!ok) {
+      console.log("Remote upgrade cancelled.");
+      return;
+    }
+  }
+
+  const results: Array<{ id: string; ok: boolean; message: string }> = [];
+  for (const id of targets) {
+    if (!byId.has(id)) {
+      results.push({ id, ok: false, message: "not connected to the relay" });
+      continue;
+    }
+    try {
+      const res = (await apiRequest("POST", `/api/orchestrators/${encodeURIComponent(id)}/action`, {
+        action: "upgrade",
+        targetVersion,
+        providers: remoteProviders,
+      })) as { command?: { id?: string } };
+      const from = byId.get(id)?.version;
+      results.push({ id, ok: true, message: `queued ${from ?? "?"} → ${targetVersion} (command ${res?.command?.id ?? "?"})` });
+    } catch (err) {
+      results.push({ id, ok: false, message: errMessage(err) });
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ remoteUpgrades: results }, null, 2));
+    return;
+  }
+  console.log(`\nRemote orchestrator upgrades → ${targetVersion}:`);
+  for (const result of results) console.log(`  ${result.ok ? "✓" : "✗"} ${result.id}: ${result.message}`);
+  console.log("\nEach host installs and self-restarts; the relay reconciles the version when it re-registers.");
+  console.log("Track progress in the dashboard Orchestrators view or via GET /api/orchestrators.");
+  if (results.some((result) => !result.ok)) {
+    process.exitCode = 1;
+  }
 }
 
 function parseUpgradeProvider(value: string): UpgradeProvider {
@@ -626,10 +747,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 +1538,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 +1576,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 +1586,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 +1595,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 +1626,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.