agent-relay-orchestrator 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.17.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.8"
+    "agent-relay-sdk": "0.2.10"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -1,4 +1,5 @@
 import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+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";
@@ -693,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();
   }
 }
@@ -770,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) }));
   }
 }
 
@@ -797,7 +798,3 @@ function cleanTerminalGuestInput(value: unknown): { agentId?: string; policyName
   }
   return result;
 }
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}

package/src/artifact-proxy.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import type { OrchestratorConfig } from "./config";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 const SAFE_ARTIFACT_ID = /^[a-zA-Z0-9._-]{1,160}$/;
 const CONTENT_ROUTE = /^\/api\/artifacts\/([^/]+)\/content$/;
@@ -77,7 +78,7 @@ function forwardHeaders(req: Request, config: OrchestratorConfig): Headers {
     if (value) headers.set(name, value);
   }
   const token = config.token || req.headers.get("x-agent-relay-token");
-  if (token) headers.set("X-Agent-Relay-Token", token);
+  if (token) headers.set(RELAY_TOKEN_HEADER, token);
   return headers;
 }
 

package/src/control.ts

@@ -1,8 +1,9 @@
+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>;
@@ -115,10 +116,18 @@ export function createControlHandler(
           baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
           strategy: command.params.strategy === "pr" || command.params.strategy === "rebase-ff" || command.params.strategy === "auto" ? command.params.strategy : undefined,
           deleteBranch: command.params.deleteBranch !== false,
+          push: command.params.push !== false,
           prTitle: typeof command.params.prTitle === "string" ? command.params.prTitle : undefined,
           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,
@@ -135,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;
     }
   }
@@ -174,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;
@@ -241,11 +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;
-}
-
-function isRecord(value: unknown): value is Record<string, any> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

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/relay.ts

@@ -2,7 +2,8 @@ import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
 import { detectSelfSupervision } from "./self-supervision";
 import { GIT_SHA, ORCHESTRATOR_PROTOCOL_VERSION, VERSION, runtimeMetadata } from "./version";
-import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+import type { WorkspaceMetadata, WorkspaceMode, ManagedSessionExitDiagnostics as SdkManagedSessionExitDiagnostics } from "agent-relay-sdk";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 export interface RelayClient {
   register(): Promise<void>;
@@ -46,46 +47,8 @@ export interface ManagedAgentReport {
   startedAt: number;
 }
 
-export interface ManagedSessionExitDiagnostics {
-  agentId: string;
-  provider: "claude" | "codex";
-  workspaceMode?: WorkspaceMode;
-  workspace?: WorkspaceMetadata;
-  sessionName?: string;
-  tmuxSession: string;
-  cwd: string;
-  label?: string;
-  policyName?: string;
-  spawnRequestId?: string;
-  automationRunId?: string;
-  supervisor: "process" | "systemd" | "launchd" | "unknown";
-  systemdUnit?: string;
-  terminalSession?: string;
-  terminalAvailable?: boolean;
-  pid?: number;
-  currentPid?: number;
-  startedAt: number;
-  detectedAt: number;
-  runtimeMs: number;
-  logFile?: string;
-  logBytes?: number;
-  logEmpty?: boolean;
-  logTail?: string[];
-  runnerInfoFile?: string;
-  runnerInfoPresent?: boolean;
-  systemd?: {
-    unit: string;
-    activeState?: string;
-    subState?: string;
-    result?: string;
-    execMainCode?: string;
-    execMainStatus?: string;
-    mainPid?: number;
-    unavailable?: string;
-  };
-  unavailable?: string[];
-  lastError: string;
-}
+// Canonical shape lives in agent-relay-sdk — alias and re-export, never re-declare.
+export type ManagedSessionExitDiagnostics = SdkManagedSessionExitDiagnostics;
 
 export interface RelayCommand {
   id: string;
@@ -133,7 +96,7 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
   function headers(): Record<string, string> {
     const h: Record<string, string> = { "Content-Type": "application/json" };
     const token = runtimeToken ?? config.token;
-    if (token) h["X-Agent-Relay-Token"] = token;
+    if (token) h[RELAY_TOKEN_HEADER] = token;
     return h;
   }
 

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/version.ts

@@ -1,15 +1,17 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
 
 export const PACKAGE_NAME = pkg.name || "agent-relay-orchestrator";
 export const VERSION = pkg.version || "0.0.0";
-export const ORCHESTRATOR_PROTOCOL_VERSION = 3;
-export const RUNNER_PROTOCOL_VERSION = 1;
-export const PROVIDER_PLUGIN_PROTOCOL_VERSION = 1;
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const ORCHESTRATOR_PROTOCOL_VERSION = CONTRACT_VERSIONS.orchestratorProtocol;
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
 export const GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
 
 export const CONTRACTS = {

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) };
   }
 }
 
@@ -394,6 +503,8 @@ export function workspaceGitState(input: { worktreePath?: string; baseRef?: stri
   const dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
 
   const state: WorkspaceGitState = { dirty: dirtyCount > 0, dirtyCount };
+  const liveBranch = shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], path).stdout || undefined);
+  if (liveBranch) state.branch = liveBranch;
 
   const log = git(["log", "-1", "--format=%H%x1f%ct%x1f%s"], path);
   if (log.ok && log.stdout) {
@@ -552,10 +663,22 @@ interface WorkspaceMergeInput {
   baseSha?: string;
   strategy?: "pr" | "rebase-ff" | "auto";
   deleteBranch?: boolean;
+  /** Push the advanced base to its upstream (origin) after a rebase-ff land.
+   * Defaults to true; auto-skipped when base has no upstream. Disable with
+   * AGENT_RELAY_WORKSPACE_PUSH=0. */
+  push?: boolean;
   prTitle?: string;
   prBody?: string;
 }
 
+/** Behind-count of HEAD relative to `base`, from inside `worktreePath`. */
+function countBehind(worktreePath: string, base: string): number {
+  const counts = git(["rev-list", "--left-right", "--count", `${base}...HEAD`], worktreePath);
+  if (!counts.ok || !counts.stdout) return 0;
+  const behind = Number(counts.stdout.split(/\s+/)[0]);
+  return Number.isFinite(behind) ? behind : 0;
+}
+
 function hasOriginRemote(cwd: string): boolean {
   return git(["remote", "get-url", "origin"], cwd).ok;
 }
@@ -679,7 +802,8 @@ export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?:
 /**
  * Integrate a workspace's work back into its base branch. Two strategies:
  *  - rebase-ff: rebase the agent branch onto base, fast-forward base to it,
- *    then remove the worktree and delete the branch. Lands work locally.
+ *    push base to origin, then (unless deleteBranch is false) remove the worktree
+ *    and delete the branch. Lands work locally and publishes it.
  *  - pr: push the branch to origin and open a PR via gh. Leaves the worktree
  *    and branch intact (the PR needs them).
  * Refuses on a dirty worktree, predicted conflicts, or nothing to merge. Never
@@ -742,8 +866,24 @@ function mergeRebaseFf(
   if (!base) return head({ status: "review_requested", error: "no base branch to merge into" });
   if (!branch) return head({ status: "review_requested", error: "cannot determine agent branch" });
 
+  // Reconcile with origin before landing (#190/#203). When base tracks an
+  // upstream (e.g. main -> origin/main) and we'll push, fetch it and refuse if
+  // origin has moved ahead of local base: pushing would then be a non-fast-forward,
+  // and we won't rewrite published history or strand a local-only land. The
+  // refusal happens BEFORE we mutate anything, so a diverged base is a clean no-op.
+  const upstream = upstreamRef(worktreePath, base);
+  const slash = upstream ? upstream.indexOf("/") : -1;
+  const remote = slash > 0 ? upstream!.slice(0, slash) : undefined; // remote of a `remote/branch` upstream
+  const pushEnabled = input.push !== false && process.env.AGENT_RELAY_WORKSPACE_PUSH !== "0" && Boolean(remote);
+  if (upstream && remote && pushEnabled) {
+    git(["fetch", remote, base], worktreePath); // best-effort freshness; a stale ref can only under-detect divergence
+    if (!git(["merge-base", "--is-ancestor", upstream, base], worktreePath).ok) {
+      return head({ status: "review_requested", error: `origin moved ahead of local ${base}; sync ${base} with ${upstream} before landing` });
+    }
+  }
+
   // Rebase the agent branch onto base so base can fast-forward to it.
-  if ((preview.behind ?? 0) > 0) {
+  if (countBehind(worktreePath, base) > 0) {
     const rebase = git(["rebase", base], worktreePath);
     if (!rebase.ok) {
       git(["rebase", "--abort"], worktreePath);
@@ -765,16 +905,43 @@ function mergeRebaseFf(
     if (!update.ok) return head({ status: "review_requested", error: update.stderr || "failed to advance base ref" });
   }
 
-  // Work is landed. Tear down the worktree and delete the agent branch.
+  // Publish the advanced base so local and origin converge (#190). We verified
+  // origin was an ancestor of base above, so this is a fast-forward; a failure
+  // means origin raced us — surface it instead of claiming an unpublished land.
+  let pushed = false;
+  if (upstream && remote && pushEnabled) {
+    const push = git(["push", remote, `${base}:${base}`], worktreePath);
+    if (!push.ok) return head({ status: "review_requested", mergedSha: headSha, error: push.stderr || `git push to ${remote}/${base} failed` });
+    pushed = true;
+  }
+
+  // Work is landed (and published). Tear down only when the owner is gone:
+  // deleteBranch is false for a live owner (the relay sets it from owner liveness,
+  // #204). A live owner keeps its worktree and is recycled onto a fresh branch cut
+  // from the advanced base (#206) so it continues the next task from clean, current
+  // state in the same CWD; status returns to `active`. An absent owner gets the
+  // worktree reclaimed.
   const deleteBranch = input.deleteBranch !== false;
-  let worktreeRemoved = false;
-  let branchDeleted = false;
-  if (deleteBranch) {
-    const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
-    worktreeRemoved = removed.ok;
-    if (worktreeRemoved) branchDeleted = git(["branch", "-D", branch], repoRoot).ok;
+  if (!deleteBranch) {
+    const fresh = nextBranchName(repoRoot, branch);
+    const switched = git(["checkout", "-B", fresh, base], worktreePath);
+    if (switched.ok) {
+      // The old branch now equals base (just fast-forwarded) — drop the litter.
+      const oldDeleted = git(["branch", "-D", branch], repoRoot).ok;
+      // 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 });
   }
-  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, error: undefined });
+  const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
+  const worktreeRemoved = removed.ok;
+  const branchDeleted = worktreeRemoved ? git(["branch", "-D", branch], repoRoot).ok : false;
+  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, pushed, error: undefined });
 }
 
 async function availableBranch(repoRoot: string, base: string): Promise<string> {
@@ -796,16 +963,22 @@ function branchName(input: WorkspaceResolutionInput, id: string): string {
   return `agent/${safeSegment(owner, 48)}/${safeSegment(id.replace(/^sp[_-]?/, ""), 24)}`;
 }
 
+/** Next free `<branch>-N` cycle name for a recycled worktree (#206). Strips any
+ * existing -N suffix so cycles increment instead of nesting. */
+function nextBranchName(repoRoot: string, branch: string): string {
+  const stem = branch.replace(/-\d+$/, "");
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${stem}-${i}`;
+    if (!git(["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`], repoRoot).ok) return candidate;
+  }
+  return `${stem}-${Date.now()}`;
+}
+
 function repoSlug(repoRoot: string): string {
   const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 10);
   return `${safeSegment(basename(repoRoot), 60)}-${hash}`;
 }
 
 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" });
 }