agent-relay-orchestrator 0.10.19 → 0.10.21

package/src/spawn.ts

@@ -0,0 +1,1267 @@
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } 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 type { ManagedAgentReport, ManagedSessionExitDiagnostics } from "./relay";
+import { resolveSpawnWorkspace } from "./workspace-probe";
+import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+
+export interface SpawnOptions {
+  provider: "claude" | "codex";
+  cwd: string;
+  rig?: string;
+  model?: string;
+  effort?: string;
+  profile?: string;
+  workspaceMode?: WorkspaceMode;
+  workspace?: WorkspaceMetadata;
+  agentProfile?: Record<string, unknown>;
+  label?: string;
+  agentId?: string;
+  approvalMode: string;
+  prompt?: string;
+  systemPromptAppend?: string;
+  env?: Record<string, string>;
+  tags?: string[];
+  capabilities?: string[];
+  providerArgs?: string[];
+  policyName?: string;
+  spawnRequestId?: string;
+  automationId?: string;
+  automationRunId?: string;
+}
+
+interface SessionInfo {
+  name: string;
+  sessionName: string;
+  pid: number;
+  alive: boolean;
+  supervisor: SessionSupervisor["type"];
+  systemdUnit?: string;
+  terminalSession?: string;
+  terminalAvailable: boolean;
+  logFile: string;
+}
+
+export interface TerminalGuestSession {
+  session: string;
+  mode: "guest";
+  provider: string;
+  running: boolean;
+  interactive: boolean;
+  expiresAt: number;
+}
+
+export interface TerminalSnapshot {
+  session: string;
+  content: string;
+  running: boolean;
+  // `running` only means the tmux pane still exists — tmux keeps a pane after the
+  // process inside it exits. `agentAlive` is the real liveness of the agent process
+  // (pid / systemd unit) so the dashboard can flag an orphaned, stale terminal.
+  agentAlive: boolean;
+  cols?: number;
+  rows?: number;
+  cursorX?: number;
+  cursorY?: number;
+  capturedAt: number;
+}
+
+type TerminalInputToken =
+  | { type: "literal"; value: string }
+  | { type: "key"; value: string };
+
+interface TerminalInputResult {
+  session: string;
+  running: boolean;
+  sent: number;
+  capturedAt: number;
+}
+
+export interface SessionRecord {
+  name: string;
+  pid: number;
+  supervisor?: SessionSupervisor;
+  provider: string;
+  model?: string;
+  effort?: string;
+  profile?: string;
+  workspaceMode?: WorkspaceMode;
+  workspace?: WorkspaceMetadata;
+  label?: string;
+  cwd: string;
+  logFile: string;
+  runnerInfoFile?: string;
+  agentId: string;
+  approvalMode: string;
+  policyName?: string;
+  spawnRequestId?: string;
+  automationId?: string;
+  automationRunId?: string;
+  startedAt: number;
+}
+
+interface SessionSupervisor {
+  type: "process" | "systemd";
+  unit?: string;
+  launchScript?: string;
+}
+
+interface SpawnedRunner {
+  pid: number;
+  supervisor: SessionSupervisor;
+}
+
+interface RunnerInfo {
+  agentId: string;
+  runnerId: string;
+  provider: string;
+  controlUrl: string;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  pid?: number;
+  startedAt?: number;
+}
+
+interface TerminalAttachSpec {
+  mode: "guest";
+  provider: string;
+  cwd: string;
+  command: string[];
+  env?: Record<string, string>;
+  title?: string;
+  ttlMs?: number;
+}
+
+const LOG_DIR = join(homedir(), ".agent-relay", "logs");
+const STATE_FILE = join(homedir(), ".agent-relay", "orchestrator-sessions.json");
+const SESSION_DIR = join(homedir(), ".agent-relay", "sessions");
+const RUNNER_INFO_DIR = join(homedir(), ".agent-relay", "runners");
+const GUEST_TTL_MS = 60 * 60 * 1000;
+const terminalGuests = new Map<string, { expiresAt: number }>();
+
+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 = label.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  const suffix = uniqueId ? `-${uniqueId.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase().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) } : {}),
+    AGENT_RELAY_TAGS: [...new Set(["headless", "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_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"));
+}
+
+function logFilePath(name: string): string {
+  return join(LOG_DIR, `${name}.log`);
+}
+
+function runnerInfoPath(name: string): string {
+  const safe = name.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "runner";
+  return join(RUNNER_INFO_DIR, `${safe}.json`);
+}
+
+function ensureLogDir(): void {
+  mkdirSync(LOG_DIR, { recursive: true });
+}
+
+function ensureSessionDir(): void {
+  mkdirSync(SESSION_DIR, { recursive: true, mode: 0o700 });
+}
+
+function ensureRunnerInfoDir(): void {
+  mkdirSync(RUNNER_INFO_DIR, { recursive: true, mode: 0o700 });
+}
+
+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);
+}
+
+function loadState(): SessionRecord[] {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+function addSessionRecord(record: SessionRecord): void {
+  const records = loadState().filter((r) => r.name !== record.name);
+  records.push(record);
+  saveState(records);
+}
+
+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);
+}
+
+function sessionSupervisor(record?: Pick<SessionRecord, "supervisor">): SessionSupervisor {
+  return record?.supervisor ?? { type: "process" };
+}
+
+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);
+}
+
+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;
+}
+
+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 async function spawnAgent(
+  opts: SpawnOptions,
+  config: OrchestratorConfig,
+): Promise<ManagedAgentReport> {
+  const label = opts.label || defaultSpawnLabel();
+  const agentId = opts.agentId || managedAgentId(config, opts.provider, label);
+  const name = sessionName(config, opts.provider, label, opts.spawnRequestId ?? agentId);
+
+  if (!existsSync(opts.cwd)) {
+    throw new Error(`cwd does not exist: ${opts.cwd}`);
+  }
+  if (!isWithinBaseDir(opts.cwd, config.baseDir)) {
+    throw new Error(`cwd must be within base directory: ${config.baseDir}`);
+  }
+
+  const resolvedWorkspace = await resolveSpawnWorkspace({
+    ...opts,
+    label,
+    workspaceRoot: join(resolve(config.baseDir), ".agent-relay", "workspaces"),
+  });
+  const spawnOpts = { ...opts, label, agentId, cwd: resolvedWorkspace.cwd, workspace: resolvedWorkspace.workspace };
+
+  const command = buildRunnerCommand(spawnOpts, config);
+
+  ensureLogDir();
+  ensureRunnerInfoDir();
+  const logFile = logFilePath(name);
+  const runnerInfoFile = runnerInfoPath(name);
+  rmSync(runnerInfoFile, { force: true });
+  const env = buildEnv({ ...spawnOpts, env: { ...(spawnOpts.env ?? {}), AGENT_RELAY_RUNNER_INFO_FILE: runnerInfoFile } }, config, logFile, name);
+  const logFd = openSync(logFile, "w");
+
+  console.error(`[orchestrator] Spawning ${opts.provider} agent: ${name}`);
+  console.error(`[orchestrator]   cwd: ${opts.cwd}`);
+  console.error(`[orchestrator]   command: ${command.join(" ")}`);
+  console.error(`[orchestrator]   log: ${logFile}`);
+
+  closeSync(logFd);
+
+  const runner = spawnRunner(name, command, spawnOpts.cwd, env, logFile);
+
+  addSessionRecord({
+    name,
+    pid: runner.pid,
+    supervisor: runner.supervisor,
+    provider: spawnOpts.provider,
+    model: spawnOpts.model,
+    effort: spawnOpts.effort,
+    profile: spawnOpts.profile,
+    workspaceMode: spawnOpts.workspaceMode,
+    workspace: spawnOpts.workspace,
+    label,
+    cwd: spawnOpts.cwd,
+    logFile,
+    runnerInfoFile,
+    agentId,
+    approvalMode: spawnOpts.approvalMode,
+    policyName: spawnOpts.policyName,
+    spawnRequestId: spawnOpts.spawnRequestId,
+    automationId: spawnOpts.automationId,
+    automationRunId: spawnOpts.automationRunId,
+    startedAt: Date.now(),
+  });
+
+  return {
+    agentId,
+    provider: spawnOpts.provider,
+    model: spawnOpts.model,
+    effort: spawnOpts.effort,
+    profile: spawnOpts.profile,
+    workspaceMode: spawnOpts.workspaceMode,
+    workspace: spawnOpts.workspace,
+    ...sessionReportFields({ name, supervisor: runner.supervisor, runnerInfoFile, agentId, provider: spawnOpts.provider }),
+    cwd: spawnOpts.cwd,
+    label,
+    approvalMode: spawnOpts.approvalMode || "guarded",
+    policyName: spawnOpts.policyName,
+    spawnRequestId: spawnOpts.spawnRequestId,
+    automationRunId: spawnOpts.automationRunId,
+    pid: runner.pid,
+    startedAt: Date.now(),
+  };
+}
+
+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 });
+  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);
+  return { session, stopped: running };
+}
+
+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)
+    );
+  }
+
+  // Policy-only lookup: a respawn leaves multiple records for one policy. The
+  // live session is the most recent one, so pick the highest startedAt rather
+  // than the first match (which is the stale, already-replaced session).
+  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;
+}
+
+function findSessionRecord(input: { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string }): SessionRecord | undefined {
+  return selectSessionRecord(loadState(), input);
+}
+
+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;
+  }
+}
+
+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 = provider.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase() || "provider";
+  const cleanAgent = agentId.replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase().slice(0, 48) || "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-`);
+}
+
+function cleanupExpiredTerminalGuests(): void {
+  const now = Date.now();
+  for (const [session, guest] of terminalGuests.entries()) {
+    if (guest.expiresAt > now) continue;
+    killTmuxSession(session);
+    terminalGuests.delete(session);
+  }
+}
+
+function killTmuxSession(session: string): void {
+  Bun.spawnSync(["tmux", "kill-session", "-t", session], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+}
+
+function spawnRunner(name: string, command: string[], cwd: string, env: Record<string, string>, logFile: string): SpawnedRunner {
+  if (shouldUseSystemdSupervisor()) {
+    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] Falling back to process child; this agent will not survive orchestrator service restart.");
+    }
+  }
+
+  const launchScript = launchScriptPath(name);
+  ensureSessionDir();
+  writeFileSync(launchScript, buildLaunchScript(command, cwd, env), { mode: 0o700 });
+  chmodSync(launchScript, 0o700);
+
+  const logFd = openSync(logFile, "a");
+  try {
+    const proc = Bun.spawn([launchScript], {
+      cwd,
+      env,
+      stdin: "ignore",
+      stdout: logFd,
+      stderr: logFd,
+    });
+    return { pid: proc.pid, supervisor: { type: "process", launchScript } };
+  } finally {
+    closeSync(logFd);
+  }
+}
+
+function shouldUseSystemdSupervisor(): boolean {
+  if (process.platform !== "linux") return false;
+  if (process.env.AGENT_RELAY_DISABLE_SYSTEMD_SUPERVISOR === "1") return false;
+  if (process.env.AGENT_RELAY_FORCE_SYSTEMD_SUPERVISOR === "1") return true;
+  const result = Bun.spawnSync(["systemctl", "--user", "show-environment"], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return result.exitCode === 0;
+}
+
+function spawnSystemdRunner(name: string, command: string[], cwd: string, env: Record<string, string>, logFile: string): SpawnedRunner {
+  const unit = systemdUnitName(name);
+  const launchScript = launchScriptPath(name);
+  ensureSessionDir();
+  writeFileSync(launchScript, buildLaunchScript(command, cwd, env), { mode: 0o700 });
+  chmodSync(launchScript, 0o700);
+
+  Bun.spawnSync(["systemctl", "--user", "stop", `${unit}.service`], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+
+  const result = Bun.spawnSync([
+    "systemd-run",
+    "--user",
+    `--unit=${unit}`,
+    "--collect",
+    "--property=KillMode=control-group",
+    `--property=StandardOutput=append:${logFile}`,
+    `--property=StandardError=append:${logFile}`,
+    launchScript,
+  ], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(stderr || `systemd-run failed with exit code ${result.exitCode}`);
+  }
+
+  const pid = waitForSystemdMainPid(unit, 2_000);
+  if (!pid) throw new Error(`systemd unit ${unit}.service started without a MainPID`);
+  return { pid, supervisor: { type: "systemd", unit, launchScript } };
+}
+
+export function systemdUnitName(session: string): string {
+  const safe = session.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "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";
+  return join(SESSION_DIR, `${safe}.sh`);
+}
+
+export function buildLaunchScript(command: string[], cwd: string, env: Record<string, string>): string {
+  const exports = Object.entries(env)
+    .filter(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && value !== undefined)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `export ${key}=${shellEscape(String(value))}`);
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    ...exports,
+    `cd ${shellEscape(cwd)}`,
+    `exec ${command.map(shellEscape).join(" ")}`,
+    "",
+  ].join("\n");
+}
+
+function waitForSystemdMainPid(unit: string, timeoutMs: number): number {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const pid = systemdMainPid(unit);
+    if (pid > 0 && isPidAlive(pid)) return pid;
+    Bun.sleepSync(50);
+  }
+  return 0;
+}
+
+function systemdMainPid(unit: string): number {
+  const result = Bun.spawnSync(["systemctl", "--user", "show", `${unit}.service`, "-p", "MainPID", "--value"], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return 0;
+  const pid = Number(result.stdout.toString().trim());
+  return Number.isFinite(pid) ? pid : 0;
+}
+
+function systemdUnitDiagnostics(unit: string): NonNullable<ManagedSessionExitDiagnostics["systemd"]> {
+  const result = Bun.spawnSync([
+    "systemctl", "--user", "show", `${unit}.service`,
+    "-p", "ActiveState",
+    "-p", "SubState",
+    "-p", "Result",
+    "-p", "ExecMainCode",
+    "-p", "ExecMainStatus",
+    "-p", "MainPID",
+  ], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    return {
+      unit,
+      unavailable: result.stderr.toString().trim() || `systemctl show exited with ${result.exitCode}`,
+    };
+  }
+  const props = new Map<string, string>();
+  for (const line of result.stdout.toString().split("\n")) {
+    const index = line.indexOf("=");
+    if (index <= 0) continue;
+    props.set(line.slice(0, index), line.slice(index + 1));
+  }
+  const mainPid = Number(props.get("MainPID"));
+  return {
+    unit,
+    activeState: props.get("ActiveState") || undefined,
+    subState: props.get("SubState") || undefined,
+    result: props.get("Result") || undefined,
+    execMainCode: props.get("ExecMainCode") || undefined,
+    execMainStatus: props.get("ExecMainStatus") || undefined,
+    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : undefined,
+  };
+}
+
+function logFileDiagnostics(logFile: string): Pick<ManagedSessionExitDiagnostics, "logBytes" | "logEmpty" | "logTail"> & { logUnavailable?: string } {
+  try {
+    const stat = statSync(logFile);
+    if (stat.size === 0) return { logBytes: 0, logEmpty: true, logTail: [] };
+    const content = readFileSync(logFile, "utf8");
+    return {
+      logBytes: stat.size,
+      logEmpty: false,
+      logTail: logLines(content).slice(-20),
+    };
+  } catch (error) {
+    return {
+      logUnavailable: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function describeSessionExit(record: SessionRecord, diagnostics: Omit<ManagedSessionExitDiagnostics, "lastError">): string {
+  const seconds = Math.max(0, Math.round(diagnostics.runtimeMs / 1000));
+  const parts = [`managed ${record.provider} session ${record.name} exited after ${seconds}s`];
+  if (diagnostics.systemd?.unavailable) {
+    parts.push(`systemd status unavailable: ${diagnostics.systemd.unavailable}`);
+  } else if (diagnostics.systemd) {
+    const state = [diagnostics.systemd.activeState, diagnostics.systemd.subState].filter(Boolean).join("/") || "unknown";
+    const result = diagnostics.systemd.result || "unknown";
+    const exit = [diagnostics.systemd.execMainCode, diagnostics.systemd.execMainStatus].filter(Boolean).join("/") || "unknown";
+    parts.push(`systemd ${diagnostics.systemd.unit}.service state=${state} result=${result} exit=${exit}`);
+  }
+  if (diagnostics.logEmpty) {
+    parts.push("stdout/stderr log is empty");
+  } else if (diagnostics.logBytes === undefined) {
+    parts.push("stdout/stderr log unavailable");
+  }
+  if (!diagnostics.runnerInfoPresent) parts.push("runner info was not written");
+  return parts.join("; ");
+}
+
+export function diagnoseSessionExit(input: { agentId?: string; policyName?: string; spawnRequestId?: string; tmuxSession?: string }): ManagedSessionExitDiagnostics | null {
+  const record = findSessionRecord(input);
+  if (!record) return null;
+  const detectedAt = Date.now();
+  const supervisor = sessionSupervisor(record);
+  const currentPid = currentSessionPid(record);
+  const terminalAvailable = tmuxHasSession(record.name, readRunnerInfo(record)?.tmuxSocket);
+  const log = logFileDiagnostics(record.logFile);
+  const runnerInfoPresent = record.runnerInfoFile ? existsSync(record.runnerInfoFile) : false;
+  const unavailable = [
+    ...(log.logUnavailable ? [`stdout/stderr log unavailable: ${log.logUnavailable}`] : []),
+    ...(log.logEmpty ? ["stdout/stderr log empty"] : []),
+    ...(!runnerInfoPresent ? ["runner info unavailable"] : []),
+  ];
+  const base: Omit<ManagedSessionExitDiagnostics, "lastError"> = {
+    agentId: record.agentId,
+    provider: record.provider as "claude" | "codex",
+    workspaceMode: record.workspaceMode,
+    workspace: record.workspace ?? (record.workspaceMode ? { mode: "shared", requestedMode: record.workspaceMode } : undefined),
+    sessionName: record.name,
+    tmuxSession: record.name,
+    cwd: record.cwd,
+    label: record.label,
+    policyName: record.policyName,
+    spawnRequestId: record.spawnRequestId,
+    automationRunId: record.automationRunId,
+    supervisor: supervisor.type,
+    ...(supervisor.type === "systemd" && supervisor.unit ? { systemdUnit: supervisor.unit } : {}),
+    terminalSession: record.name,
+    terminalAvailable,
+    pid: record.pid,
+    currentPid,
+    startedAt: record.startedAt,
+    detectedAt,
+    runtimeMs: Math.max(0, detectedAt - record.startedAt),
+    logFile: record.logFile,
+    logBytes: log.logBytes,
+    logEmpty: log.logEmpty,
+    logTail: log.logTail,
+    runnerInfoFile: record.runnerInfoFile,
+    runnerInfoPresent,
+    ...(supervisor.type === "systemd" && supervisor.unit ? { systemd: systemdUnitDiagnostics(supervisor.unit) } : {}),
+    ...(unavailable.length ? { unavailable } : {}),
+  };
+  return {
+    ...base,
+    lastError: describeSessionExit(record, base),
+  };
+}
+
+function stopSystemdUnit(unit: string): void {
+  Bun.spawnSync(["systemctl", "--user", "stop", `${unit}.service`], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+}
+
+function killSystemdUnit(unit: string): void {
+  Bun.spawnSync(["systemctl", "--user", "kill", "--kill-whom=all", "--signal=SIGKILL", `${unit}.service`], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+}
+
+function cleanupSupervisor(supervisor: SessionSupervisor): void {
+  if (supervisor.type === "systemd" && supervisor.unit) stopSystemdUnit(supervisor.unit);
+  if (supervisor.launchScript) rmSync(supervisor.launchScript, { force: true });
+}
+
+function cleanupSessionRecord(record: SessionRecord): void {
+  cleanupSupervisor(sessionSupervisor(record));
+  if (record.runnerInfoFile) rmSync(record.runnerInfoFile, { force: true });
+}
+
+export async function stopSession(name: string, config: OrchestratorConfig, reason: string, graceful = true, timeoutMs?: number): Promise<{ stopped: boolean; wasRunning: boolean }> {
+  if (!name.startsWith(`${config.tmuxPrefix}-`)) throw new Error("session is not managed by this orchestrator");
+
+  const records = loadState();
+  const record = records.find((r) => r.name === name);
+  if (!record || !isSessionRecordAlive(record)) {
+    if (record) cleanupSessionRecord(record);
+    removeSessionRecord(name);
+    return { stopped: false, wasRunning: false };
+  }
+
+  const pid = currentSessionPid(record);
+  console.error(`[orchestrator] Stopping session ${name} (pid ${pid}): ${reason}`);
+
+  const supervisor = sessionSupervisor(record);
+  const gracefulTimeoutMs = sessionStopTimeoutMs(graceful, timeoutMs);
+  if (supervisor.type === "systemd" && supervisor.unit) {
+    stopSystemdUnit(supervisor.unit);
+    const deadline = Date.now() + gracefulTimeoutMs;
+    while (Date.now() < deadline && isSessionRecordAlive(record)) {
+      await Bun.sleep(200);
+    }
+    if (isSessionRecordAlive(record)) {
+      killSystemdUnit(supervisor.unit);
+      const killDeadline = Date.now() + 2_000;
+      while (Date.now() < killDeadline && isSessionRecordAlive(record)) {
+        await Bun.sleep(100);
+      }
+    }
+    if (isSessionRecordAlive(record)) return { stopped: false, wasRunning: true };
+    cleanupSessionRecord(record);
+    removeSessionRecord(name);
+    return { stopped: true, wasRunning: true };
+  }
+
+  if (graceful) {
+    try { process.kill(pid, "SIGTERM"); } catch {}
+    const deadline = Date.now() + gracefulTimeoutMs;
+    while (Date.now() < deadline && isPidAlive(pid)) {
+      await Bun.sleep(200);
+    }
+  }
+
+  if (isPidAlive(pid)) {
+    try { process.kill(pid, "SIGKILL"); } catch {}
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline && isPidAlive(pid)) {
+      await Bun.sleep(100);
+    }
+  }
+
+  // Never report success while the process is still alive: deleting the session
+  // record here would orphan a running process with no handle to stop it again.
+  if (isPidAlive(pid)) {
+    console.error(`[orchestrator] Session ${name} (pid ${pid}) survived SIGKILL; keeping record for retry`);
+    return { stopped: false, wasRunning: true };
+  }
+
+  cleanupSessionRecord(record);
+  removeSessionRecord(name);
+  return { stopped: true, wasRunning: true };
+}
+
+function sessionStopTimeoutMs(graceful: boolean, timeoutMs?: number): number {
+  if (!graceful) return 2_000;
+  if (!Number.isSafeInteger(timeoutMs) || !timeoutMs || timeoutMs <= 0) return 10_000;
+  return Math.min(timeoutMs, 60_000);
+}
+
+export function captureSession(
+  name: string,
+  config: OrchestratorConfig,
+  lines = 100,
+  options: { raw?: boolean } = {},
+): { session: string; lines: string[]; running: boolean } {
+  if (!name.startsWith(`${config.tmuxPrefix}-`)) throw new Error("session is not managed by this orchestrator");
+
+  const records = loadState();
+  const record = records.find((r) => r.name === name);
+  const logFile = record?.logFile ?? logFilePath(name);
+  const running = record ? isSessionRecordAlive(record) : false;
+
+  let content: string;
+  try {
+    content = readFileSync(logFile, "utf8");
+  } catch {
+    return { session: name, lines: [], running };
+  }
+
+  const allLines = logLines(content, !options.raw);
+  const safeLines = Math.min(Math.max(lines, 1), 1000);
+  return {
+    session: name,
+    lines: allLines.slice(-safeLines),
+    running,
+  };
+}
+
+export function captureTerminal(name: string, config: OrchestratorConfig): TerminalSnapshot {
+  if (!name.startsWith(`${config.tmuxPrefix}-`)) throw new Error("session is not managed by this orchestrator");
+
+  const agentAlive = isSessionAlive(name);
+  const socketName = tmuxSocketForSession(name);
+  const running = tmuxHasSession(name, socketName);
+  if (!running) {
+    return { session: name, content: "", running: false, agentAlive, capturedAt: Date.now() };
+  }
+
+  const size = tmuxPaneSize(name, socketName);
+  const cursor = tmuxCursorPos(name, socketName);
+  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-e", "-S", "-1000", "-t", name), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(stderr || `tmux capture-pane failed with exit code ${result.exitCode}`);
+  }
+
+  return {
+    session: name,
+    content: result.stdout.toString(),
+    running: true,
+    agentAlive,
+    ...size,
+    ...cursor,
+    capturedAt: Date.now(),
+  };
+}
+
+export function terminalInputTokens(data: string): TerminalInputToken[] {
+  const tokens: TerminalInputToken[] = [];
+  let literal = "";
+  const flushLiteral = () => {
+    if (!literal) return;
+    tokens.push({ type: "literal", value: literal });
+    literal = "";
+  };
+  const escapeSequences: Array<[string, string]> = [
+    ["\x1b[A", "Up"],
+    ["\x1b[B", "Down"],
+    ["\x1b[C", "Right"],
+    ["\x1b[D", "Left"],
+    ["\x1b[H", "Home"],
+    ["\x1b[F", "End"],
+    ["\x1b[3~", "Delete"],
+  ];
+
+  for (let index = 0; index < data.length;) {
+    const match = escapeSequences.find(([sequence]) => data.startsWith(sequence, index));
+    if (match) {
+      flushLiteral();
+      tokens.push({ type: "key", value: match[1] });
+      index += match[0].length;
+      continue;
+    }
+
+    const ch = data[index]!;
+    if (ch === "\r" || ch === "\n") {
+      flushLiteral();
+      tokens.push({ type: "key", value: "Enter" });
+    } else if (ch === "\t") {
+      flushLiteral();
+      tokens.push({ type: "key", value: "Tab" });
+    } else if (ch === "\u0003") {
+      flushLiteral();
+      tokens.push({ type: "key", value: "C-c" });
+    } else if (ch === "\u007f" || ch === "\b") {
+      flushLiteral();
+      tokens.push({ type: "key", value: "BSpace" });
+    } else if (ch === "\x1b") {
+      flushLiteral();
+      tokens.push({ type: "key", value: "Escape" });
+    } else if (ch >= " " || ch > "\x7f") {
+      literal += ch;
+    }
+    index += 1;
+  }
+
+  flushLiteral();
+  return tokens;
+}
+
+export function sendTerminalInput(name: string, config: OrchestratorConfig, input: unknown): TerminalInputResult {
+  if (!name.startsWith(`${config.tmuxPrefix}-`)) throw new Error("session is not managed by this orchestrator");
+  const socketName = tmuxSocketForSession(name);
+  if (!tmuxHasSession(name, socketName)) throw new Error("terminal session is not running");
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("terminal input body must be an object");
+
+  const data = (input as { data?: unknown }).data;
+  if (typeof data !== "string") throw new Error("terminal input data must be a string");
+  if (data.length > 4096) throw new Error("terminal input exceeds 4096 characters");
+
+  const tokens = terminalInputTokens(data);
+  for (const token of tokens) {
+    const args = token.type === "literal"
+      ? tmuxCommand(socketName, "send-keys", "-t", name, "-l", token.value)
+      : tmuxCommand(socketName, "send-keys", "-t", name, token.value);
+    const result = Bun.spawnSync(args, {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(stderr || `tmux send-keys failed with exit code ${result.exitCode}`);
+    }
+  }
+
+  return {
+    session: name,
+    running: true,
+    sent: tokens.length,
+    capturedAt: Date.now(),
+  };
+}
+
+export function resizeTerminal(name: string, config: OrchestratorConfig, input: unknown): { session: string; cols: number; rows: number } {
+  if (!name.startsWith(`${config.tmuxPrefix}-`)) throw new Error("session is not managed by this orchestrator");
+  const socketName = tmuxSocketForSession(name);
+  if (!tmuxHasSession(name, socketName)) throw new Error("terminal session is not running");
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("resize body must be an object");
+
+  const cols = (input as { cols?: unknown }).cols;
+  const rows = (input as { rows?: unknown }).rows;
+  if (typeof cols !== "number" || typeof rows !== "number") throw new Error("cols and rows must be numbers");
+  if (cols < 10 || cols > 500 || rows < 5 || rows > 200) throw new Error("cols must be 10-500, rows must be 5-200");
+
+  const clamped = { cols: Math.round(cols), rows: Math.round(rows) };
+  const result = Bun.spawnSync(tmuxCommand(socketName, "resize-window", "-t", name, "-x", String(clamped.cols), "-y", String(clamped.rows)), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(stderr || `tmux resize-window failed with exit code ${result.exitCode}`);
+  }
+
+  return { session: name, ...clamped };
+}
+
+function tmuxSocketForSession(name: string): string | undefined {
+  const record = loadState().find((item) => item.name === name);
+  return record ? readRunnerInfo(record)?.tmuxSocket : undefined;
+}
+
+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;
+}
+
+function tmuxPaneSize(name: string, socketName?: string): { cols?: number; rows?: number } {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "display-message", "-p", "-t", name, "#{pane_width} #{pane_height}"), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return {};
+  const [colsRaw, rowsRaw] = result.stdout.toString().trim().split(/\s+/, 2);
+  const cols = Number(colsRaw);
+  const rows = Number(rowsRaw);
+  return {
+    ...(Number.isFinite(cols) && cols > 0 ? { cols } : {}),
+    ...(Number.isFinite(rows) && rows > 0 ? { rows } : {}),
+  };
+}
+
+function tmuxCursorPos(name: string, socketName?: string): { cursorX?: number; cursorY?: number } {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "display-message", "-p", "-t", name, "#{cursor_x} #{cursor_y}"), {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return {};
+  const [xRaw, yRaw] = result.stdout.toString().trim().split(/\s+/, 2);
+  const cursorX = Number(xRaw);
+  const cursorY = Number(yRaw);
+  return {
+    ...(Number.isFinite(cursorX) ? { cursorX } : {}),
+    ...(Number.isFinite(cursorY) ? { cursorY } : {}),
+  };
+}
+
+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, "");
+}
+
+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;
+}
+
+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();
+  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, "'\\''")}'`;
+}