agent-relay-orchestrator 0.62.2 → 0.63.0

package/package.json

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

package/src/spawn/command.ts

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { artifactProxyBaseUrl } from "../artifact-proxy";
+import type { OrchestratorConfig } from "../config";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { SpawnOptions } from "./types";
+
+export function isWithinBaseDir(path: string, baseDir: string): boolean {
+  const base = resolve(baseDir);
+  const target = resolve(path);
+  const rel = relative(base, target);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function sessionName(config: OrchestratorConfig, provider: string, label: string, uniqueId?: string): string {
+  const clean = sanitizeFsName(label, { replacement: "-", lowercase: true });
+  const suffix = uniqueId ? `-${sanitizeFsName(uniqueId, { replacement: "-", lowercase: true }).slice(-8)}` : "";
+  return `${config.tmuxPrefix}-${provider}-${clean}${suffix}`;
+}
+
+export function defaultSpawnLabel(now = Date.now()): string {
+  return `session-${now}`;
+}
+
+export function buildRunnerCommand(opts: SpawnOptions, config: OrchestratorConfig): string[] {
+  const repoLauncher = resolve(import.meta.dir, "../../../runner/src/index.ts");
+  const installedLauncher = resolve(import.meta.dir, "../../../agent-relay-runner/src/index.ts");
+  const bun = process.env.AGENT_RELAY_BUN_BIN
+    || (process.platform === "darwin" && existsSync("/opt/homebrew/bin/bun") ? "/opt/homebrew/bin/bun" : "bun");
+  const launcher = existsSync(repoLauncher)
+    ? [bun, "run", repoLauncher, opts.provider]
+    : existsSync(installedLauncher)
+      ? [bun, "run", installedLauncher, opts.provider]
+    : [`${opts.provider}-relay`, opts.provider];
+  const args = [
+    ...launcher,
+    "--headless",
+    "--cwd", opts.cwd,
+    "--relay-url", config.relayUrl,
+    "--approval", opts.approvalMode || "guarded",
+  ];
+  if (opts.rig) args.push("--rig", opts.rig);
+  if (opts.model) args.push("--model", opts.model);
+  if (opts.effort) args.push("--effort", opts.effort);
+  if (opts.profile) args.push("--profile", opts.profile);
+  if (opts.label) args.push("--label", opts.label);
+  if (opts.agentId) args.push("--agent-id", opts.agentId);
+  if (opts.prompt) args.push("--prompt", opts.prompt);
+  if (opts.systemPromptAppend) args.push("--system-prompt-append", opts.systemPromptAppend);
+  if (opts.tags?.length) args.push("--tags", opts.tags.join(","));
+  if (opts.capabilities?.length) args.push("--caps", opts.capabilities.join(","));
+  if (opts.providerArgs?.length) args.push("--", ...opts.providerArgs);
+  return args;
+}
+
+export function buildEnv(opts: SpawnOptions & { label: string; agentId: string }, config: OrchestratorConfig, logFile?: string, tmuxSession?: string): Record<string, string> {
+  const currentPath = process.env.PATH || "";
+  const extraPaths = [
+    join(homedir(), ".local", "bin"),
+    join(homedir(), ".bun", "bin"),
+    join(homedir(), ".npm-global", "bin"),
+  ];
+  const fullPath = [...extraPaths, ...currentPath.split(":").filter(Boolean)]
+    .filter((v, i, a) => a.indexOf(v) === i)
+    .join(":");
+
+  return {
+    ...process.env as Record<string, string>,
+    ...(config.token ? { AGENT_RELAY_TOKEN: config.token } : {}),
+    ...config.env,
+    ...agentProfileEnv(opts.agentProfile),
+    ...(opts.env || {}),
+    PATH: fullPath,
+    AGENT_RELAY_URL: config.relayUrl,
+    AGENT_RELAY_ORCHESTRATOR_URL: `http://127.0.0.1:${config.apiPort}`,
+    AGENT_RELAY_ARTIFACT_URL: artifactProxyBaseUrl(config),
+    AGENT_RELAY_APPROVAL: opts.approvalMode || "guarded",
+    ...(opts.profile ? { AGENT_RELAY_AGENT_PROFILE: opts.profile } : {}),
+    ...(opts.agentProfile ? { AGENT_RELAY_AGENT_PROFILE_JSON: JSON.stringify(opts.agentProfile) } : {}),
+    // #330 — tag by TRUE origin. An MCP spawn (an agent spawning a helper) is `agent-spawned`, not
+    // `dashboard-spawned`; the old blanket `dashboard-spawned` mislabeled every headless spawn as
+    // dashboard-originated. Dashboard/CLI/automation spawns (no `requestedVia: "mcp"`) keep the
+    // `dashboard-spawned` tag the smoke test and UI filter on.
+    AGENT_RELAY_TAGS: [...new Set(["headless", opts.requestedVia === "mcp" ? "agent-spawned" : "dashboard-spawned", config.hostname, ...(opts.tags ?? [])])].join(","),
+    AGENT_RELAY_CAPS: [...new Set(opts.capabilities ?? [])].join(","),
+    AGENT_RELAY_CAPABILITIES: [...new Set(opts.capabilities ?? [])].join(","),
+    AGENT_RELAY_HEADLESS: "1",
+    ...(logFile ? { AGENT_RELAY_LOG_FILE: logFile } : {}),
+    ...(tmuxSession ? { AGENT_RELAY_TMUX_SESSION: tmuxSession } : {}),
+    ...(opts.label ? { AGENT_RELAY_LABEL: opts.label } : {}),
+    ...(opts.policyName ? { AGENT_RELAY_POLICY: opts.policyName } : {}),
+    ...(opts.spawnRequestId ? { AGENT_RELAY_SPAWN_REQUEST_ID: opts.spawnRequestId } : {}),
+    AGENT_RELAY_LIFECYCLE: opts.lifecycle ?? "persistent", AGENT_RELAY_WORKSPACE_MODE: opts.workspaceMode ?? "inherit",
+    ...(opts.workspace ? { AGENT_RELAY_WORKSPACE_JSON: JSON.stringify(opts.workspace) } : {}),
+    ...(opts.automationId ? { AGENT_RELAY_AUTOMATION_ID: opts.automationId } : {}),
+    ...(opts.automationRunId ? { AGENT_RELAY_AUTOMATION_RUN_ID: opts.automationRunId } : {}),
+  };
+}
+
+function agentProfileEnv(profile: Record<string, unknown> | undefined): Record<string, string> {
+  const raw = profile?.env;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  return Object.fromEntries(Object.entries(raw).filter((entry): entry is [string, string] => typeof entry[1] === "string"));
+}

package/src/spawn/constants.ts

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const LOG_DIR = join(homedir(), ".agent-relay", "logs");
+export const STATE_FILE = join(homedir(), ".agent-relay", "orchestrator-sessions.json");
+export const SESSION_DIR = join(homedir(), ".agent-relay", "sessions");
+export const RUNNER_INFO_DIR = join(homedir(), ".agent-relay", "runners");
+export const GUEST_TTL_MS = 60 * 60 * 1000;
+export const GUEST_STATE_FILE = join(homedir(), ".agent-relay", "orchestrator-guests.json");
+export const terminalGuests = new Map<string, { expiresAt: number }>();
+export let guestStateHydrated = false;
+
+export function markGuestStateHydrated(): void { guestStateHydrated = true; }

package/src/spawn/guests.ts

@@ -0,0 +1,241 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { OrchestratorConfig } from "../config";
+import { errMessage } from "agent-relay-sdk";
+import { shellEscape } from "agent-relay-sdk/shell-utils";
+import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { GUEST_STATE_FILE, GUEST_TTL_MS, guestStateHydrated, markGuestStateHydrated, terminalGuests } from "./constants";
+import { findSessionRecord, isSessionRecordAlive, readRunnerInfo } from "./runtime";
+import { isWithinBaseDir } from "./command";
+import type { TerminalAttachSpec, TerminalGuestSession } from "./types";
+
+export async function createTerminalGuest(
+  input: { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string },
+  config: OrchestratorConfig,
+): Promise<TerminalGuestSession> {
+  cleanupExpiredTerminalGuests();
+  const record = findSessionRecord(input);
+  if (!record || !isSessionRecordAlive(record)) throw new Error("managed runner session not found");
+  const runner = readRunnerInfo(record);
+  if (!runner?.controlUrl) throw new Error("runner control URL is unavailable; restart the agent to enable terminal attach");
+  const spec = await fetchTerminalAttachSpec(runner.controlUrl);
+  validateAttachSpec(spec, config);
+  const session = guestSessionName(config, spec.provider, record.agentId);
+  killTmuxSession(session);
+  const expiresAt = Date.now() + Math.min(Math.max(spec.ttlMs ?? GUEST_TTL_MS, 60_000), 4 * GUEST_TTL_MS);
+  const shellCmd = spec.command.map(shellEscape).join(" ");
+  const tmuxArgs = ["new-session", "-d", "-s", session, "-x", "200", "-y", "50"];
+  for (const [key, value] of Object.entries(spec.env ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) tmuxArgs.push("-e", `${key}=${value}`);
+  }
+  tmuxArgs.push("-c", spec.cwd, shellCmd);
+  const result = Bun.spawnSync(["tmux", ...tmuxArgs], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(stderr || `tmux guest creation failed with exit code ${result.exitCode}`);
+  }
+  terminalGuests.set(session, { expiresAt });
+  saveGuestState();
+  return { session, mode: "guest", provider: spec.provider, running: true, interactive: true, expiresAt };
+}
+
+export function stopTerminalGuest(session: string, config: OrchestratorConfig): { session: string; stopped: boolean } {
+  if (!isGuestSessionName(session, config)) throw new Error("terminal session is not a guest session");
+  const running = tmuxHasSession(session);
+  if (running) killTmuxSession(session);
+  terminalGuests.delete(session);
+  saveGuestState();
+  return { session, stopped: running };
+}
+
+async function fetchTerminalAttachSpec(controlUrl: string): Promise<TerminalAttachSpec> {
+  const res = await fetch(`${controlUrl}/terminal/attach-spec`, { signal: AbortSignal.timeout(5_000) });
+  const body = await res.json().catch(() => null) as unknown;
+  if (!res.ok) {
+    const message = body && typeof body === "object" && !Array.isArray(body) && typeof (body as { error?: unknown }).error === "string"
+      ? (body as { error: string }).error
+      : `runner attach-spec failed with ${res.status}`;
+    throw new Error(message);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("runner attach-spec response must be an object");
+  return body as TerminalAttachSpec;
+}
+
+function validateAttachSpec(spec: TerminalAttachSpec, config: OrchestratorConfig): void {
+  if (spec.mode !== "guest") throw new Error("runner attach-spec mode must be guest");
+  if (typeof spec.provider !== "string" || !spec.provider.trim()) throw new Error("runner attach-spec provider required");
+  if (typeof spec.cwd !== "string" || !isWithinBaseDir(spec.cwd, config.baseDir)) throw new Error("runner attach-spec cwd must be within base directory");
+  if (!Array.isArray(spec.command) || spec.command.length === 0 || spec.command.some((item) => typeof item !== "string" || !item)) {
+    throw new Error("runner attach-spec command must be a non-empty string array");
+  }
+  if (spec.env !== undefined && (!spec.env || typeof spec.env !== "object" || Array.isArray(spec.env) || Object.values(spec.env).some((value) => typeof value !== "string"))) {
+    throw new Error("runner attach-spec env must be a string record");
+  }
+}
+
+function guestSessionName(config: OrchestratorConfig, provider: string, agentId: string): string {
+  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)}`;
+}
+
+function isGuestSessionName(session: string, config: OrchestratorConfig): boolean {
+  return session.startsWith(`${config.tmuxPrefix}-guest-`);
+}
+
+interface GuestRecord {
+  session: string;
+  expiresAt: number;
+}
+
+interface LiveGuestSession {
+  session: string;
+  createdAtMs: number;
+}
+
+/** Flatten the in-memory guest registry to a persistable, deterministic list. */
+export function serializeGuests(guests: Map<string, { expiresAt: number }>): GuestRecord[] {
+  return [...guests.entries()]
+    .map(([session, { expiresAt }]) => ({ session, expiresAt }))
+    .sort((a, b) => a.session.localeCompare(b.session));
+}
+
+/** Tolerant inverse of serializeGuests — drops malformed entries instead of throwing. */
+export function deserializeGuests(raw: unknown): Map<string, { expiresAt: number }> {
+  const map = new Map<string, { expiresAt: number }>();
+  if (!Array.isArray(raw)) return map;
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const { session, expiresAt } = entry as Record<string, unknown>;
+    if (typeof session === "string" && session && typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
+      map.set(session, { expiresAt });
+    }
+  }
+  return map;
+}
+
+function saveGuestState(): void {
+  try {
+    mkdirSync(join(homedir(), ".agent-relay"), { recursive: true });
+    const tmp = `${GUEST_STATE_FILE}.tmp`;
+    writeFileSync(tmp, JSON.stringify(serializeGuests(terminalGuests), null, 2) + "\n");
+    renameSync(tmp, GUEST_STATE_FILE);
+  } catch {
+    // Persistence is best-effort: a write failure must never break guest creation.
+    // The periodic reaper's tmux age-based fallback still bounds orphan lifetime.
+  }
+}
+
+/**
+ * Rehydrate the in-memory guest registry from disk so guest TTLs survive an
+ * orchestrator restart. Call once at boot before the first reap.
+ */
+export function hydrateTerminalGuests(): void {
+  if (guestStateHydrated) return;
+  markGuestStateHydrated();
+  try {
+    const persisted = deserializeGuests(JSON.parse(readFileSync(GUEST_STATE_FILE, "utf8")));
+    for (const [session, value] of persisted) {
+      if (!terminalGuests.has(session)) terminalGuests.set(session, value);
+    }
+  } catch {
+    // No persisted state (first boot or unreadable) — the age-based fallback in
+    // reapTerminalGuests still cleans any orphaned guest tmux sessions.
+  }
+}
+
+/** Live `<prefix>-guest-*` tmux sessions with their creation time (ms). */
+function listGuestTmuxSessions(config: OrchestratorConfig): LiveGuestSession[] {
+  const result = Bun.spawnSync(["tmux", "list-sessions", "-F", "#{session_name}\t#{session_created}"], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return []; // no tmux server / no sessions
+  const sessions: LiveGuestSession[] = [];
+  for (const line of result.stdout.toString().split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab < 0) continue;
+    const session = line.slice(0, tab);
+    if (!isGuestSessionName(session, config)) continue;
+    const createdSec = Number(line.slice(tab + 1).trim());
+    sessions.push({ session, createdAtMs: Number.isFinite(createdSec) ? createdSec * 1000 : 0 });
+  }
+  return sessions;
+}
+
+/**
+ * Decide which live guest sessions to reap. Pure so the TTL policy is testable
+ * without tmux or fs:
+ * - tracked + past its recorded expiry → reap
+ * - untracked (metadata lost across a restart) + older than the fallback TTL → reap
+ */
+export function selectExpiredGuests(
+  tracked: Map<string, { expiresAt: number }>,
+  liveGuests: LiveGuestSession[],
+  now: number,
+  fallbackTtlMs = GUEST_TTL_MS,
+): string[] {
+  const toReap = new Set<string>();
+  for (const { session, createdAtMs } of liveGuests) {
+    const record = tracked.get(session);
+    if (record) {
+      if (record.expiresAt <= now) toReap.add(session);
+    } else if (now - createdAtMs >= fallbackTtlMs) {
+      toReap.add(session);
+    }
+  }
+  return [...toReap];
+}
+
+/**
+ * Kill guest tmux sessions whose TTL has elapsed, independent of any new guest
+ * creation, and prune tracked entries whose tmux session is already gone. Runs
+ * at boot and on a periodic timer (see orchestrator index).
+ */
+export function reapTerminalGuests(config: OrchestratorConfig, now = Date.now()): string[] {
+  const live = listGuestTmuxSessions(config);
+  const liveNames = new Set(live.map((g) => g.session));
+  const reaped = selectExpiredGuests(terminalGuests, live, now);
+  for (const session of reaped) {
+    killTmuxSession(session);
+    terminalGuests.delete(session);
+  }
+  // Drop tracked guests with no live tmux session (manually killed, or reaped
+  // above) so the registry can't grow without bound.
+  let pruned = false;
+  for (const session of [...terminalGuests.keys()]) {
+    if (!liveNames.has(session)) {
+      terminalGuests.delete(session);
+      pruned = true;
+    }
+  }
+  if (reaped.length || pruned) saveGuestState();
+  return reaped;
+}
+
+function cleanupExpiredTerminalGuests(): void {
+  const now = Date.now();
+  let changed = false;
+  for (const [session, guest] of terminalGuests.entries()) {
+    if (guest.expiresAt > now) continue;
+    killTmuxSession(session);
+    terminalGuests.delete(session);
+    changed = true;
+  }
+  if (changed) saveGuestState();
+}
+
+function killTmuxSession(session: string): void {
+  Bun.spawnSync(["tmux", "kill-session", "-t", session], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+}

package/src/spawn/index.ts

@@ -0,0 +1,10 @@
+export * from "./command";
+export * from "./guests";
+export * from "./log-utils";
+export * from "./runtime";
+export * from "./sessions";
+export * from "./spawn-agent";
+export * from "./supervisor";
+export * from "./systemd";
+export * from "./terminal";
+export type { SessionRecord, SpawnOptions, TerminalSnapshot } from "./types";

package/src/spawn/log-utils.ts

@@ -0,0 +1,22 @@
+export function logLines(content: string, sanitize = true): string[] {
+  const text = sanitize ? sanitizeLogText(content) : content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  return text
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0);
+}
+
+export function sanitizeLogText(content: string): string {
+  return content
+    .replace(/\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)/g, "")
+    .replace(/\x1B[PX^_][\s\S]*?\x1B\\/g, "")
+    .replace(/\x1B\[(\d*)C/g, (_match, count: string) => " ".repeat(Math.min(Number(count || "1"), 120)))
+    .replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\x1B[()#%*+\-.\/ ][ -~]/g, "")
+    .replace(/\x1B[ -/]*[@-~]/g, "")
+    .replace(/\x9B[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\x1B.?/g, "")
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+}

package/src/spawn/runtime.ts

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ManagedAgentReport } from "../relay";
+import { isPidAlive, parseProcStateIsZombie } from "agent-relay-sdk/process-utils";
+import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { LOG_DIR, RUNNER_INFO_DIR, SESSION_DIR, STATE_FILE } from "./constants";
+import { systemdMainPid } from "./systemd";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { RunnerInfo, SessionRecord, SessionSupervisor } from "./types";
+
+export function logFilePath(name: string): string {
+  return join(LOG_DIR, `${name}.log`);
+}
+
+export function runnerInfoPath(name: string): string {
+  const safe = sanitizeFsName(name, { replacement: "-", trimEdge: true, fallback: "runner" });
+  return join(RUNNER_INFO_DIR, `${safe}.json`);
+}
+
+export function ensureLogDir(): void {
+  mkdirSync(LOG_DIR, { recursive: true });
+}
+
+export function ensureSessionDir(): void {
+  mkdirSync(SESSION_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function ensureRunnerInfoDir(): void {
+  mkdirSync(RUNNER_INFO_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function saveState(records: SessionRecord[]): void {
+  mkdirSync(join(homedir(), ".agent-relay"), { recursive: true });
+  // Atomic write: a crash mid-write would otherwise leave truncated JSON and
+  // loadState would silently return [], losing every tracked session.
+  const tmp = `${STATE_FILE}.tmp`;
+  writeFileSync(tmp, JSON.stringify(records, null, 2) + "\n");
+  renameSync(tmp, STATE_FILE);
+}
+
+export function loadState(): SessionRecord[] {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+export function addSessionRecord(record: SessionRecord): void {
+  const records = loadState().filter((r) => r.name !== record.name);
+  records.push(record);
+  saveState(records);
+}
+
+export function removeSessionRecord(name: string): void {
+  saveState(loadState().filter((r) => r.name !== name));
+}
+
+// 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 };
+
+export function sessionSupervisor(record?: Pick<SessionRecord, "supervisor">): SessionSupervisor {
+  return record?.supervisor ?? { type: "process" };
+}
+
+export function isSessionRecordAlive(record: SessionRecord): boolean {
+  const supervisor = sessionSupervisor(record);
+  if (supervisor.type === "systemd" && supervisor.unit) {
+    const pid = systemdMainPid(supervisor.unit);
+    return pid > 0 && isPidAlive(pid);
+  }
+  return isPidAlive(record.pid);
+}
+
+export function currentSessionPid(record: SessionRecord): number {
+  const supervisor = sessionSupervisor(record);
+  if (supervisor.type === "systemd" && supervisor.unit) {
+    const pid = systemdMainPid(supervisor.unit);
+    if (pid > 0) return pid;
+  }
+  return record.pid;
+}
+
+export function sessionReportFields(record: Pick<SessionRecord, "name" | "supervisor" | "runnerInfoFile" | "agentId" | "provider">): Pick<ManagedAgentReport, "sessionName" | "tmuxSession" | "supervisor" | "systemdUnit" | "terminalSession" | "terminalAvailable"> {
+  const supervisor = sessionSupervisor(record);
+  const terminalAvailable = tmuxHasSession(record.name, readRunnerInfo(record)?.tmuxSocket);
+  return {
+    sessionName: record.name,
+    tmuxSession: record.name,
+    supervisor: supervisor.type,
+    ...(supervisor.type === "systemd" && supervisor.unit ? { systemdUnit: supervisor.unit } : {}),
+    terminalSession: record.name,
+    terminalAvailable,
+  };
+}
+
+export function selectSessionRecord(records: SessionRecord[], input: { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string }): SessionRecord | undefined {
+  if (input.tmuxSession) return records.find((record) => record.name === input.tmuxSession);
+
+  if (input.spawnRequestId) {
+    return records.find((record) =>
+      record.spawnRequestId === input.spawnRequestId &&
+      (!input.policyName || record.policyName === input.policyName)
+    );
+  }
+
+  if (input.agentId) {
+    return records.find((record) =>
+      record.agentId === input.agentId &&
+      (!input.policyName || record.policyName === input.policyName)
+    );
+  }
+
+  if (input.policyName) {
+    const policyName = input.policyName;
+    return records
+      .filter((record) => record.policyName === policyName)
+      .reduce<SessionRecord | undefined>((latest, record) => (
+        !latest || record.startedAt > latest.startedAt ? record : latest
+      ), undefined);
+  }
+  return undefined;
+}
+
+export function findSessionRecord(input: { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string }): SessionRecord | undefined {
+  return selectSessionRecord(loadState(), input);
+}
+
+export function readRunnerInfo(record: Pick<SessionRecord, "runnerInfoFile" | "agentId" | "provider">): RunnerInfo | null {
+  if (!record.runnerInfoFile) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(record.runnerInfoFile, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const info = parsed as Record<string, unknown>;
+    if (typeof info.controlUrl !== "string" || !info.controlUrl.startsWith("http://127.0.0.1:")) return null;
+    return {
+      agentId: typeof info.agentId === "string" ? info.agentId : record.agentId,
+      runnerId: typeof info.runnerId === "string" ? info.runnerId : "",
+      provider: typeof info.provider === "string" ? info.provider : record.provider,
+      controlUrl: info.controlUrl,
+      tmuxSession: typeof info.tmuxSession === "string" ? info.tmuxSession : undefined,
+      tmuxSocket: typeof info.tmuxSocket === "string" ? info.tmuxSocket : undefined,
+      pid: typeof info.pid === "number" ? info.pid : undefined,
+      startedAt: typeof info.startedAt === "number" ? info.startedAt : undefined,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/spawn/sessions.ts

@@ -0,0 +1,103 @@
+import type { OrchestratorConfig } from "../config";
+import type { ManagedAgentReport } from "../relay";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { shellEscape } from "agent-relay-sdk/shell-utils";
+import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { cleanupSessionRecord } from "./supervisor";
+import { currentSessionPid, findSessionRecord, isSessionRecordAlive, loadState, readRunnerInfo, saveState, sessionReportFields, sessionSupervisor } from "./runtime";
+import type { SessionInfo, SessionRecord } from "./types";
+
+export function listSessions(prefix: string): SessionInfo[] {
+  return loadState()
+    .filter((r) => r.name.startsWith(`${prefix}-`))
+    .map((r) => {
+      const supervisor = sessionSupervisor(r);
+      return {
+        name: r.name,
+        sessionName: r.name,
+        pid: currentSessionPid(r),
+        alive: isSessionRecordAlive(r),
+        supervisor: supervisor.type,
+        ...(supervisor.type === "systemd" && supervisor.unit ? { systemdUnit: supervisor.unit } : {}),
+        terminalSession: r.name,
+        terminalAvailable: tmuxHasSession(r.name, readRunnerInfo(r)?.tmuxSocket),
+        logFile: r.logFile,
+      };
+    });
+}
+
+export function isSessionAlive(name: string): boolean {
+  const record = loadState().find((r) => r.name === name);
+  return record ? isSessionRecordAlive(record) : false;
+}
+
+export function refreshManagedAgentReport(agent: ManagedAgentReport): ManagedAgentReport {
+  const record = findSessionRecord({
+    tmuxSession: agent.sessionName ?? agent.tmuxSession,
+    agentId: agent.agentId,
+    policyName: agent.policyName,
+    spawnRequestId: agent.spawnRequestId,
+  });
+  if (!record) return agent;
+  return {
+    ...agent,
+    workspaceMode: record.workspaceMode,
+    workspace: record.workspace ?? agent.workspace ?? (record.workspaceMode ? { mode: "shared", requestedMode: record.workspaceMode } : undefined),
+    pid: currentSessionPid(record),
+    ...sessionReportFields(record),
+  };
+}
+
+export async function recoverExistingSessions(
+  config: OrchestratorConfig,
+): Promise<ManagedAgentReport[]> {
+  const records = loadState().filter((r) => r.name.startsWith(`${config.tmuxPrefix}-`));
+  const managed: ManagedAgentReport[] = [];
+  const alive: SessionRecord[] = [];
+
+  for (const record of records) {
+    if (!isSessionRecordAlive(record)) {
+      console.error(`[orchestrator] Stale session: ${record.name} (pid ${record.pid} dead) — removing`);
+      cleanupSessionRecord(record);
+      continue;
+    }
+
+    const pid = currentSessionPid(record);
+    const updatedRecord = { ...record, pid };
+    alive.push(updatedRecord);
+    managed.push({
+      agentId: record.agentId,
+      provider: record.provider as "claude" | "codex",
+      workspaceMode: record.workspaceMode,
+      workspace: record.workspace ?? (record.workspaceMode ? { mode: "shared", requestedMode: record.workspaceMode } : undefined),
+      ...sessionReportFields(updatedRecord),
+      cwd: record.cwd,
+      label: record.label,
+      approvalMode: record.approvalMode || "guarded",
+      policyName: record.policyName,
+      spawnRequestId: record.spawnRequestId,
+      automationRunId: record.automationRunId,
+      pid,
+      startedAt: record.startedAt,
+    });
+
+    console.error(`[orchestrator] Recovered existing session: ${record.name} (pid ${record.pid})`);
+  }
+
+  // Merge rather than overwrite: only replace the records this recovery actually
+  // inspected, so a session added concurrently (or owned by another prefix) is
+  // not erased by writing back a pre-filtered snapshot.
+  const processedNames = new Set(records.map((r) => r.name));
+  const untouched = loadState().filter((r) => !processedNames.has(r.name));
+  saveState([...untouched, ...alive]);
+  return managed;
+}
+
+export function managedAgentId(config: OrchestratorConfig, provider: string, label: string): string {
+  const cleanHost = sanitizeFsName(config.hostname, { replacement: "-", lowercase: true });
+  const cleanLabel = sanitizeFsName(label, { replacement: "-", lowercase: true });
+  return `${cleanHost}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+// Shared shell-quoting; re-exported so `./spawn` consumers + tests resolve it.
+export { shellEscape };