agent-relay-orchestrator 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.9"
+    "agent-relay-sdk": "0.2.10"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -1,5 +1,5 @@
 import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
-import { stringValue } from "agent-relay-sdk";
+import { errMessage, stringValue } from "agent-relay-sdk";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import type { ServerWebSocket } from "bun";
 import { proxyArtifactRequest } from "./artifact-proxy";
@@ -694,7 +694,7 @@ function startTerminalSocket(ws: TerminalSocket): void {
       if (!ws.data.synced) void syncAndBackfill(ws);
     }, 700);
   } catch (e) {
-    ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));
+    ws.send(JSON.stringify({ type: "error", error: errMessage(e) }));
     ws.close();
   }
 }
@@ -771,7 +771,7 @@ function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer):
       if (ws.data.synced) void sendBackfill(ws);
     }
   } catch (e) {
-    ws.send(JSON.stringify({ type: "error", error: e instanceof Error ? e.message : String(e) }));
+    ws.send(JSON.stringify({ type: "error", error: errMessage(e) }));
   }
 }
 

package/src/control.ts

@@ -1,9 +1,9 @@
-import { isRecord } from "agent-relay-sdk";
+import { errMessage, isRecord, normalizeWorkspaceMode } from "agent-relay-sdk";
 import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace, mergeWorkspace, pruneWorktrees, reconcileWorkspace } from "./workspace-probe";
+import { cleanupWorkspace, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps } from "./workspace-probe";
 
 interface ControlHandler {
   handleCommand(command: RelayCommand): Promise<boolean>;
@@ -121,6 +121,13 @@ export function createControlHandler(
           prBody: typeof command.params.prBody === "string" ? command.params.prBody : undefined,
         });
         await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
+      } else if (command.type === "workspace.deps-refresh") {
+        const result = refreshWorkspaceDeps(
+          typeof command.params.repoRoot === "string" ? command.params.repoRoot : "",
+          typeof command.params.worktreePath === "string" ? command.params.worktreePath : "",
+          { checkOnly: command.params.checkOnly === true },
+        );
+        await relay.updateCommand(command.id, "succeeded", { workspaceId: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined, ...result });
       } else if (command.type === "workspace.prune") {
         const result = pruneWorktrees({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
@@ -137,7 +144,7 @@ export function createControlHandler(
       await relay.updateManagedAgents(managedAgents);
       return true;
     } catch (error) {
-      await relay.updateCommand(command.id, "failed", undefined, error instanceof Error ? error.message : String(error));
+      await relay.updateCommand(command.id, "failed", undefined, errMessage(error));
       return false;
     }
   }
@@ -176,59 +183,43 @@ function shutdownTimeoutMs(ctrl: Record<string, any>): number | undefined {
   return Number.isSafeInteger(ctrl.timeoutMs) && ctrl.timeoutMs > 0 ? Math.min(ctrl.timeoutMs, 60_000) : undefined;
 }
 
-export function spawnOptionsFromControl(ctrl: Record<string, any>, config: OrchestratorConfig): SpawnOptions {
+// Both the control-spawn and restart-source paths build SpawnOptions from a
+// loose record in the same way. The two prior copies differed only in two
+// immaterial spots, unified here to the safer form:
+//   - provider: `=== "codex" ? "codex" : "claude"` (SPAWN_PROVIDERS is exactly
+//     claude|codex, so this matches control's `|| "claude"` for every valid
+//     input and stays defensive against junk).
+//   - cwd: `source.cwd || baseDir` — an empty-string cwd now falls back to
+//     baseDir on the restart path too (was a latent bug; empty cwd is invalid).
+export function spawnOptionsFromRecord(source: Record<string, any>, config: OrchestratorConfig): SpawnOptions {
   return {
-    provider: ctrl.provider || "claude",
-    cwd: ctrl.cwd || config.baseDir,
-    rig: typeof ctrl.rig === "string" ? ctrl.rig : undefined,
-    model: modelFromControl(ctrl),
-    effort: typeof ctrl.effort === "string" ? ctrl.effort : undefined,
-    profile: typeof ctrl.profile === "string" ? ctrl.profile : undefined,
-    workspaceMode: workspaceMode(ctrl.workspaceMode),
-    workspaceSymlinks: stringArray(ctrl.workspaceSymlinks),
-    agentProfile: isRecord(ctrl.agentProfile) ? ctrl.agentProfile : undefined,
-    label: typeof ctrl.label === "string" ? ctrl.label : undefined,
-    agentId: typeof ctrl.agentId === "string" ? ctrl.agentId : undefined,
-    approvalMode: typeof ctrl.approvalMode === "string" ? ctrl.approvalMode : "guarded",
-    prompt: typeof ctrl.prompt === "string" ? ctrl.prompt : undefined,
-    systemPromptAppend: typeof ctrl.systemPromptAppend === "string" ? ctrl.systemPromptAppend : undefined,
-    tags: stringArray(ctrl.tags),
-    capabilities: stringArray(ctrl.capabilities),
-    providerArgs: stringArray(ctrl.providerArgs),
-    env: stringRecord(ctrl.env),
-    policyName: typeof ctrl.policyName === "string" ? ctrl.policyName : undefined,
-    spawnRequestId: typeof ctrl.spawnRequestId === "string" ? ctrl.spawnRequestId : undefined,
-    automationId: typeof ctrl.automationId === "string" ? ctrl.automationId : undefined,
-    automationRunId: typeof ctrl.automationRunId === "string" ? ctrl.automationRunId : undefined,
+    provider: source.provider === "codex" ? "codex" : "claude",
+    cwd: source.cwd || config.baseDir,
+    rig: typeof source.rig === "string" ? source.rig : undefined,
+    model: modelFromControl(source),
+    effort: typeof source.effort === "string" ? source.effort : undefined,
+    profile: typeof source.profile === "string" ? source.profile : undefined,
+    workspaceMode: normalizeWorkspaceMode(source.workspaceMode),
+    workspaceSymlinks: stringArray(source.workspaceSymlinks),
+    agentProfile: isRecord(source.agentProfile) ? source.agentProfile : undefined,
+    label: typeof source.label === "string" ? source.label : undefined,
+    agentId: typeof source.agentId === "string" ? source.agentId : undefined,
+    approvalMode: typeof source.approvalMode === "string" ? source.approvalMode : "guarded",
+    prompt: typeof source.prompt === "string" ? source.prompt : undefined,
+    systemPromptAppend: typeof source.systemPromptAppend === "string" ? source.systemPromptAppend : undefined,
+    tags: stringArray(source.tags),
+    capabilities: stringArray(source.capabilities),
+    providerArgs: stringArray(source.providerArgs),
+    env: stringRecord(source.env),
+    policyName: typeof source.policyName === "string" ? source.policyName : undefined,
+    spawnRequestId: typeof source.spawnRequestId === "string" ? source.spawnRequestId : undefined,
+    automationId: typeof source.automationId === "string" ? source.automationId : undefined,
+    automationRunId: typeof source.automationRunId === "string" ? source.automationRunId : undefined,
   };
 }
 
-export function spawnOptionsFromRestartSource(restartSource: Record<string, any>, config: OrchestratorConfig): SpawnOptions {
-  return {
-    provider: restartSource.provider === "codex" ? "codex" : "claude",
-    cwd: typeof restartSource.cwd === "string" ? restartSource.cwd : config.baseDir,
-    rig: typeof restartSource.rig === "string" ? restartSource.rig : undefined,
-    model: modelFromControl(restartSource),
-    effort: typeof restartSource.effort === "string" ? restartSource.effort : undefined,
-    profile: typeof restartSource.profile === "string" ? restartSource.profile : undefined,
-    workspaceMode: workspaceMode(restartSource.workspaceMode),
-    workspaceSymlinks: stringArray(restartSource.workspaceSymlinks),
-    agentProfile: isRecord(restartSource.agentProfile) ? restartSource.agentProfile : undefined,
-    label: typeof restartSource.label === "string" ? restartSource.label : undefined,
-    agentId: typeof restartSource.agentId === "string" ? restartSource.agentId : undefined,
-    approvalMode: typeof restartSource.approvalMode === "string" ? restartSource.approvalMode : "guarded",
-    prompt: typeof restartSource.prompt === "string" ? restartSource.prompt : undefined,
-    systemPromptAppend: typeof restartSource.systemPromptAppend === "string" ? restartSource.systemPromptAppend : undefined,
-    tags: stringArray(restartSource.tags),
-    capabilities: stringArray(restartSource.capabilities),
-    providerArgs: stringArray(restartSource.providerArgs),
-    env: stringRecord(restartSource.env),
-    policyName: typeof restartSource.policyName === "string" ? restartSource.policyName : undefined,
-    spawnRequestId: typeof restartSource.spawnRequestId === "string" ? restartSource.spawnRequestId : undefined,
-    automationId: typeof restartSource.automationId === "string" ? restartSource.automationId : undefined,
-    automationRunId: typeof restartSource.automationRunId === "string" ? restartSource.automationRunId : undefined,
-  };
-}
+export const spawnOptionsFromControl = spawnOptionsFromRecord;
+export const spawnOptionsFromRestartSource = spawnOptionsFromRecord;
 
 function modelFromControl(ctrl: Record<string, any>): string | undefined {
   return typeof ctrl.providerModel === "string" ? ctrl.providerModel : typeof ctrl.model === "string" ? ctrl.model : undefined;
@@ -243,7 +234,3 @@ function stringRecord(value: unknown): Record<string, string> | undefined {
 function stringArray(value: unknown): string[] | undefined {
   return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined;
 }
-
-function workspaceMode(value: unknown): SpawnOptions["workspaceMode"] {
-  return value === "isolated" || value === "shared" || value === "inherit" ? value : undefined;
-}

package/src/provider-probe.ts

@@ -2,6 +2,7 @@ import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 import { providerCatalogList, type ProviderCatalogEntry } from "agent-relay-sdk/provider-catalog";
+import { errMessage } from "agent-relay-sdk";
 import type { OrchestratorConfig } from "./config";
 import { VERSION } from "./version";
 
@@ -130,7 +131,7 @@ async function probeCommand(
     };
   } catch (error) {
     try { proc?.kill("SIGKILL"); } catch {}
-    return { command: displayCommand, path, ok: false, error: error instanceof Error ? error.message : String(error) };
+    return { command: displayCommand, path, ok: false, error: errMessage(error) };
   }
 }
 

package/src/spawn.ts

@@ -6,6 +6,11 @@ import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, ManagedSessionExitDiagnostics } from "./relay";
 import { resolveSpawnWorkspace } from "./workspace-probe";
 import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { isPidAlive, parseProcStateIsZombie } from "agent-relay-sdk/process-utils";
+import { shellEscape } from "agent-relay-sdk/shell-utils";
+import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 
 export interface SpawnOptions {
   provider: "claude" | "codex";
@@ -151,8 +156,8 @@ export function isWithinBaseDir(path: string, baseDir: string): boolean {
 }
 
 export function sessionName(config: OrchestratorConfig, provider: string, label: string, uniqueId?: string): string {
-  const clean = label.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
-  const suffix = uniqueId ? `-${uniqueId.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase().slice(-8)}` : "";
+  const clean = sanitizeFsName(label, { replacement: "-", lowercase: true });
+  const suffix = uniqueId ? `-${sanitizeFsName(uniqueId, { replacement: "-", lowercase: true }).slice(-8)}` : "";
   return `${config.tmuxPrefix}-${provider}-${clean}${suffix}`;
 }
 
@@ -242,7 +247,7 @@ function logFilePath(name: string): string {
 }
 
 function runnerInfoPath(name: string): string {
-  const safe = name.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "runner";
+  const safe = sanitizeFsName(name, { replacement: "-", trimEdge: true, fallback: "runner" });
   return join(RUNNER_INFO_DIR, `${safe}.json`);
 }
 
@@ -285,30 +290,9 @@ function removeSessionRecord(name: string): void {
   saveState(loadState().filter((r) => r.name !== name));
 }
 
-// A zombie process still has a PID-table entry, so kill(pid, 0) succeeds even
-// though it is dead and unreapable. We never wait() our spawned children, so
-// they linger as zombies; treat them as not-alive (Linux-only via /proc).
-export function parseProcStateIsZombie(statusText: string): boolean {
-  const match = statusText.match(/^State:\s+(\w)/m);
-  return match?.[1] === "Z";
-}
-
-function isZombie(pid: number): boolean {
-  try {
-    return parseProcStateIsZombie(readFileSync(`/proc/${pid}/status`, "utf8"));
-  } catch {
-    return false;
-  }
-}
-
-export function isPidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-  } catch {
-    return false;
-  }
-  return !isZombie(pid);
-}
+// Zombie-aware liveness primitives are shared with the runner via the SDK.
+// Re-exported so existing `./spawn` consumers (and tests) keep resolving them.
+export { isPidAlive, parseProcStateIsZombie };
 
 function sessionSupervisor(record?: Pick<SessionRecord, "supervisor">): SessionSupervisor {
   return record?.supervisor ?? { type: "process" };
@@ -554,8 +538,8 @@ function validateAttachSpec(spec: TerminalAttachSpec, config: OrchestratorConfig
 }
 
 function guestSessionName(config: OrchestratorConfig, provider: string, agentId: string): string {
-  const cleanProvider = provider.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase() || "provider";
-  const cleanAgent = agentId.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase().slice(0, 48) || "agent";
+  const cleanProvider = sanitizeFsName(provider, { replacement: "-", lowercase: true, fallback: "provider" });
+  const cleanAgent = sanitizeFsName(agentId, { replacement: "-", lowercase: true, maxLen: 48, fallback: "agent" });
   return `${config.tmuxPrefix}-guest-${cleanProvider}-${cleanAgent}-${crypto.randomUUID().slice(0, 8)}`;
 }
 
@@ -585,7 +569,7 @@ function spawnRunner(name: string, command: string[], cwd: string, env: Record<s
     try {
       return spawnSystemdRunner(name, command, cwd, env, logFile);
     } catch (error) {
-      console.error(`[orchestrator] systemd runner supervisor unavailable for ${name}: ${error instanceof Error ? error.message : String(error)}`);
+      console.error(`[orchestrator] systemd runner supervisor unavailable for ${name}: ${errMessage(error)}`);
       console.error("[orchestrator] Falling back to process child; this agent will not survive orchestrator service restart.");
     }
   }
@@ -660,12 +644,12 @@ function spawnSystemdRunner(name: string, command: string[], cwd: string, env: R
 }
 
 export function systemdUnitName(session: string): string {
-  const safe = session.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+  const safe = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "agent" });
   return `agent-relay-managed-${safe}`.slice(0, 180);
 }
 
 function launchScriptPath(session: string): string {
-  const safe = session.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+  const safe = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "agent" });
   return join(SESSION_DIR, `${safe}.sh`);
 }
 
@@ -755,7 +739,7 @@ function logFileDiagnostics(logFile: string): Pick<ManagedSessionExitDiagnostics
     };
   } catch (error) {
     return {
-      logUnavailable: error instanceof Error ? error.message : String(error),
+      logUnavailable: errMessage(error),
     };
   }
 }
@@ -954,9 +938,10 @@ export function captureSession(
   };
 }
 
-// Mirrors the runner's safeLogName so the orchestrator resolves the same filename.
+// Shared with the runner's logger via the SDK helper, so reader + writer
+// resolve the same session-mirror filename for a given agent id.
 function safeMirrorLogName(value: string): string {
-  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180);
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180 });
 }
 
 // Read the clean, ANSI-free session-mirror diagnostics log for a managed agent.
@@ -1167,18 +1152,8 @@ export function tmuxSocketForSession(name: string): string | undefined {
   return record ? readRunnerInfo(record)?.tmuxSocket : undefined;
 }
 
-export function tmuxCommand(socketName: string | undefined, ...args: string[]): string[] {
-  return socketName ? ["tmux", "-L", socketName, ...args] : ["tmux", ...args];
-}
-
-function tmuxHasSession(name: string, socketName?: string): boolean {
-  const result = Bun.spawnSync(tmuxCommand(socketName, "has-session", "-t", name), {
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-  });
-  return result.exitCode === 0;
-}
+// Shared tmux helpers; tmuxCommand re-exported for ./terminal-stream.
+export { tmuxCommand };
 
 // Lightweight liveness for the live terminal stream's backfill metadata — avoids a full
 // capture-pane just to learn whether the pane/agent are still up.
@@ -1329,12 +1304,10 @@ export async function recoverExistingSessions(
 }
 
 function managedAgentId(config: OrchestratorConfig, provider: string, label: string): string {
-  const cleanHost = config.hostname.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
-  const cleanLabel = label.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  const cleanHost = sanitizeFsName(config.hostname, { replacement: "-", lowercase: true });
+  const cleanLabel = sanitizeFsName(label, { replacement: "-", lowercase: true });
   return `${cleanHost}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
 }
 
-export function shellEscape(s: string): string {
-  if (/^[a-zA-Z0-9._\-/:=@]+$/.test(s)) return s;
-  return `'${s.replace(/'/g, "'\\''")}'`;
-}
+// Shared shell-quoting; re-exported so `./spawn` consumers + tests resolve it.
+export { shellEscape };

package/src/terminal-stream.ts

@@ -27,6 +27,7 @@
 
 import { captureConsistent, sessionLiveness, tmuxCommand, tmuxSocketForSession, type TerminalSnapshot } from "./spawn";
 import type { OrchestratorConfig } from "./config";
+import { errMessage } from "agent-relay-sdk";
 
 const FLUSH_MS = Math.max(0, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MS) || 6);
 const FLUSH_MAX_BYTES = Math.max(4096, Number(process.env.AGENT_RELAY_TERMINAL_FLUSH_MAX_BYTES) || 65536);
@@ -230,7 +231,7 @@ class SessionStream {
         stderr: "ignore",
       });
     } catch (e) {
-      this.fail(e instanceof Error ? e.message : String(e));
+      this.fail(errMessage(e));
       return;
     }
     void this.readLoop();

package/src/workspace-probe.ts

@@ -1,8 +1,10 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, statSync, symlinkSync, type Dirent } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, type Dirent } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import type { WorkspaceDepsProvision, WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus, WorkspaceSymlinkProvision } from "agent-relay-sdk";
+import type { WorkspaceDepsProvision, WorkspaceDepsRefreshDir, WorkspaceDepsRefreshResult, WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus, WorkspaceSymlinkProvision } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 
 const MAX_DIFF_PATCH_BYTES = 200_000;
 
@@ -83,7 +85,7 @@ export async function probeWorkspace(requestedPath: string): Promise<WorkspacePr
     const stat = statSync(path);
     if (!stat.isDirectory()) return { path, isGitRepo: false, error: `Not a directory: ${path}` };
   } catch (error) {
-    return { path, isGitRepo: false, error: error instanceof Error ? error.message : String(error) };
+    return { path, isGitRepo: false, error: errMessage(error) };
   }
 
   const root = git(["rev-parse", "--show-toplevel"], path);
@@ -278,7 +280,7 @@ export function provisionWorkspaceSymlinks(
     try {
       rels = resolveSymlinkPattern(repoRoot, pattern);
     } catch (error) {
-      errors.push(`${pattern}: ${error instanceof Error ? error.message : String(error)}`);
+      errors.push(`${pattern}: ${errMessage(error)}`);
       continue;
     }
     for (const rel of rels) {
@@ -292,7 +294,7 @@ export function provisionWorkspaceSymlinks(
         symlinkSync(source, target, lstatSync(source).isDirectory() ? "dir" : "file");
         linked.push(rel);
       } catch (error) {
-        errors.push(`${rel}: ${error instanceof Error ? error.message : String(error)}`);
+        errors.push(`${rel}: ${errMessage(error)}`);
       }
     }
   }
@@ -300,6 +302,17 @@ export function provisionWorkspaceSymlinks(
   return errors.length ? { linked, errors } : { linked };
 }
 
+/** Run the detected package manager's install in a single dir. Shared by fresh
+ * provisioning and the deps refresh (issue #51) so the install invocation lives
+ * in one place. */
+function installDir(dir: string): { ok: boolean; packageManager?: string; error?: string } {
+  const pm = detectPackageManager(dir);
+  if (!pm) return { ok: false, error: "no recognized lockfile" };
+  const proc = Bun.spawnSync(pm.install, { cwd: dir, stdin: "ignore", stdout: "ignore", stderr: "pipe", env: process.env });
+  if (proc.exitCode === 0) return { ok: true, packageManager: pm.pm };
+  return { ok: false, packageManager: pm.pm, error: proc.stderr.toString().trim().slice(0, 300) };
+}
+
 /** Run a package install in each dir that owns a lockfile. Root install covers
  * the package manager's workspace members; standalone sub-projects with their
  * own lockfile (e.g. dashboard) get a separate install. */
@@ -309,21 +322,117 @@ function installNodeModules(worktreePath: string): { installed: string[]; packag
   let packageManager: string | undefined;
   let error: string | undefined;
   for (const rel of dirs) {
-    const dir = join(worktreePath, rel);
-    const pm = detectPackageManager(dir);
-    if (!pm) continue;
-    packageManager = pm.pm;
-    const proc = Bun.spawnSync(pm.install, { cwd: dir, stdin: "ignore", stdout: "ignore", stderr: "pipe", env: process.env });
-    if (proc.exitCode === 0) {
+    const result = installDir(join(worktreePath, rel));
+    if (result.packageManager) packageManager = result.packageManager;
+    if (result.ok) {
       installed.push(rel || ".");
     } else {
-      const detail = `${rel || "."}: ${proc.stderr.toString().trim().slice(0, 200)}`;
+      const detail = `${rel || "."}: ${result.error ?? "install failed"}`;
       error = error ? `${error}; ${detail}` : detail;
     }
   }
   return { installed, packageManager, error };
 }
 
+const DEP_FIELDS = ["dependencies", "devDependencies"] as const;
+
+/** Top-level deps a package.json declares that MUST be present for typecheck/build
+ * (dependencies + devDependencies). peer/optional are excluded — their absence is
+ * legitimate and would cause spurious refreshes. */
+function declaredDeps(pkgPath: string): string[] {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+    const names = new Set<string>();
+    for (const field of DEP_FIELDS) {
+      const deps = pkg[field];
+      if (deps && typeof deps === "object") for (const name of Object.keys(deps as Record<string, unknown>)) names.add(name);
+    }
+    return [...names];
+  } catch {
+    return [];
+  }
+}
+
+/** Declared deps absent from `dir`/node_modules (resolves through a symlink to the
+ * shared source). `join` handles scoped names (`@scope/pkg`). This is the staleness
+ * signal: a dep added to the base after the worktree's node_modules was provisioned. */
+function missingDeps(dir: string): string[] {
+  const nm = join(dir, "node_modules");
+  return declaredDeps(join(dir, "package.json")).filter((name) => !existsSync(join(nm, name)));
+}
+
+function isSymlink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Re-provision an isolated worktree's deps when the shared (symlinked) node_modules
+ * has gone stale relative to the worktree's package.json — i.e. a dep was added to
+ * the base AFTER the worktree was created (issue #51). For each stale project dir,
+ * replace the shared symlink with a REAL, isolated install so we never `bun install`
+ * through the symlink into the source checkout (forbidden + races sibling worktrees).
+ * `checkOnly` reports staleness without installing. Never throws.
+ */
+export function refreshWorkspaceDeps(repoRoot: string, worktreePath: string, opts: { checkOnly?: boolean } = {}): WorkspaceDepsRefreshResult {
+  const requested = (process.env.AGENT_RELAY_WORKSPACE_DEPS || "symlink").toLowerCase();
+  if (requested === "none") return { refreshed: false, dirs: [], error: "deps provisioning disabled (AGENT_RELAY_WORKSPACE_DEPS=none)" };
+
+  try {
+    const dirs = scanProjectDirs(worktreePath, NODE_MODULES_SCAN_DEPTH, (dir) => existsSync(join(dir, "package.json")) && detectPackageManager(dir) !== undefined);
+    const results: WorkspaceDepsRefreshDir[] = [];
+    for (const rel of dirs) {
+      const dir = join(worktreePath, rel);
+      const missing = missingDeps(dir);
+      const label = rel || ".";
+      if (missing.length === 0) {
+        results.push({ dir: label, status: "ok" });
+        continue;
+      }
+      if (opts.checkOnly) {
+        results.push({ dir: label, status: "stale", missing: missing.slice(0, 20), wasSymlink: isSymlink(join(dir, "node_modules")) });
+        continue;
+      }
+      const nm = join(dir, "node_modules");
+      const wasSymlink = isSymlink(nm);
+      // Drop the shared symlink first so the install writes a real dir here, not
+      // through the link into the source checkout. rmSync on a symlink unlinks only
+      // the link — the source node_modules is untouched.
+      if (wasSymlink) {
+        try { rmSync(nm); } catch { /* fall through; install may still succeed */ }
+      }
+      const result = installDir(dir);
+      if (result.ok) {
+        const stillMissing = missingDeps(dir);
+        results.push({
+          dir: label,
+          status: stillMissing.length ? "failed" : "installed",
+          missing: missing.slice(0, 20),
+          wasSymlink,
+          ...(result.packageManager ? { packageManager: result.packageManager } : {}),
+          ...(stillMissing.length ? { error: `still missing after install: ${stillMissing.slice(0, 10).join(", ")}` } : {}),
+        });
+      } else {
+        // Install failed — restore the prior symlink so the worktree isn't left with
+        // NO deps at all (worse than stale). Best-effort.
+        if (wasSymlink) {
+          try { symlinkSync(join(repoRoot, rel, "node_modules"), nm, "dir"); } catch { /* leave as-is */ }
+        }
+        results.push({ dir: label, status: "failed", missing: missing.slice(0, 20), wasSymlink, ...(result.packageManager ? { packageManager: result.packageManager } : {}), ...(result.error ? { error: result.error } : {}) });
+      }
+    }
+    const refreshed = results.some((r) => r.status === "installed");
+    const stale = results.some((r) => r.status === "stale" || r.status === "failed");
+    const failed = results.find((r) => r.status === "failed");
+    return { refreshed, ...(stale ? { stale } : {}), dirs: results, ...(failed ? { error: `${failed.dir}: ${failed.error ?? "install failed"}` } : {}) };
+  } catch (error) {
+    return { refreshed: false, dirs: [], error: errMessage(error) };
+  }
+}
+
 /**
  * Provision node_modules into a freshly created isolated worktree (#159).
  * Default: symlink the source checkout's node_modules (instant, matches what
@@ -351,7 +460,7 @@ export function provisionWorkspaceDeps(repoRoot: string, worktreePath: string):
       ...(result.error ? { error: result.error } : {}),
     };
   } catch (error) {
-    return { mode: "none", error: error instanceof Error ? error.message : String(error) };
+    return { mode: "none", error: errMessage(error) };
   }
 }
 
@@ -819,7 +928,12 @@ function mergeRebaseFf(
     if (switched.ok) {
       // The old branch now equals base (just fast-forwarded) — drop the litter.
       const oldDeleted = git(["branch", "-D", branch], repoRoot).ok;
-      return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, error: undefined });
+      // The worktree just moved onto the advanced base, which may declare deps the
+      // shared (symlinked) node_modules lacks. Re-provision so the recycled session
+      // continues from a buildable state (issue #51). No-op when nothing is stale.
+      const depsRefresh = refreshWorkspaceDeps(repoRoot, worktreePath);
+      const reportDeps = depsRefresh.refreshed || depsRefresh.stale || depsRefresh.error;
+      return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, ...(reportDeps ? { depsRefresh } : {}), error: undefined });
     }
     // Recycle failed — keep the existing branch. Still landed, still active.
     return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branchDeleted: false, pushed, error: undefined });
@@ -866,10 +980,5 @@ function repoSlug(repoRoot: string): string {
 }
 
 function safeSegment(value: string, max: number): string {
-  return value
-    .trim()
-    .replace(/[^a-zA-Z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, max)
-    || "workspace";
+  return sanitizeFsName(value, { replacement: "-", trimWhitespace: true, trimEdge: true, maxLen: max, fallback: "workspace" });
 }