agent-relay-orchestrator 0.62.2 → 0.63.0

package/src/spawn.ts

@@ -1,1477 +1 @@
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, 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, workspacesRoot } from "./workspace-probe";
-import type { AgentLifecycle, WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
-import { errMessage, extractClaudeModelUnavailableMessage } 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";
-  cwd: string;
-  rig?: string;
-  model?: string;
-  effort?: string;
-  profile?: string; workspaceMode?: WorkspaceMode; lifecycle?: AgentLifecycle;
-  workspace?: WorkspaceMetadata;
-  /** Untracked files/dirs to symlink from main into an isolated worktree (relay's global workspace config). */
-  workspaceSymlinks?: string[];
-  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;
-  /** How the spawn was requested (`mcp` = an agent via the MCP surface, else dashboard/CLI). Drives
-   * the origin tag so an MCP-spawned worker isn't mislabeled `dashboard-spawned` (#330). */
-  requestedVia?: string;
-}
-
-interface SessionInfo {
-  name: string;
-  sessionName: string;
-  pid: number;
-  alive: boolean;
-  supervisor: SessionSupervisor["type"];
-  systemdUnit?: string;
-  terminalSession?: string;
-  terminalAvailable: boolean;
-  logFile: string;
-}
-
-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; lifecycle?: AgentLifecycle;
-  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 GUEST_STATE_FILE = join(homedir(), ".agent-relay", "orchestrator-guests.json");
-const terminalGuests = new Map<string, { expiresAt: number }>();
-let guestStateHydrated = false;
-
-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"));
-}
-
-function logFilePath(name: string): string {
-  return join(LOG_DIR, `${name}.log`);
-}
-
-function runnerInfoPath(name: string): string {
-  const safe = sanitizeFsName(name, { replacement: "-", trimEdge: true, fallback: "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));
-}
-
-// 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" };
-}
-
-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,
-    workspaceSymlinks: opts.workspaceSymlinks,
-    workspaceRoot: workspacesRoot(config.baseDir),
-  });
-  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, lifecycle: spawnOpts.lifecycle ?? "persistent",
-    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, lifecycle: spawnOpts.lifecycle ?? "persistent",
-    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 });
-  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 };
-}
-
-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 = 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;
-  guestStateHydrated = true;
-  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",
-  });
-}
-
-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}: ${errMessage(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 = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "agent" });
-  return `agent-relay-managed-${safe}`.slice(0, 180);
-}
-
-function launchScriptPath(session: string): string {
-  const safe = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "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: errMessage(error),
-    };
-  }
-}
-
-function describeSessionExit(record: SessionRecord, diagnostics: Omit<ManagedSessionExitDiagnostics, "lastError">): string {
-  if (record.provider === "claude") {
-    const modelUnavailable = extractClaudeModelUnavailableMessage((diagnostics.logTail ?? []).join("\n"));
-    if (modelUnavailable) return modelUnavailable;
-  }
-  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,
-  };
-}
-
-// 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 sanitizeFsName(value, { replacement: "_", maxLen: 180 });
-}
-
-// Read the clean, ANSI-free session-mirror diagnostics log for a managed agent.
-// Accepts either the tmux session name or the agent id; the mirror log is keyed by
-// agent id. Returns the same shape as captureSession so the proxy is uniform.
-export function captureSessionMirror(
-  name: string,
-  _config: OrchestratorConfig,
-  lines = 200,
-): { session: string; lines: string[]; running: boolean; mirror: true } {
-  const records = loadState();
-  const record = records.find((r) => r.name === name) ?? records.find((r) => r.agentId === name);
-  const agentId = record?.agentId ?? name;
-  const running = record ? isSessionRecordAlive(record) : false;
-  // The mirror log lives in the same directory as the provider log (both written
-  // by the same user on this host). Derive from the record's logFile when known so
-  // it tracks any per-session log relocation.
-  const logDir = record?.logFile ? dirname(record.logFile) : process.env.AGENT_RELAY_LOG_DIR || LOG_DIR;
-  const mirrorPath = join(logDir, `session-mirror-${safeMirrorLogName(agentId)}.log`);
-  let content: string;
-  try {
-    content = readFileSync(mirrorPath, "utf8");
-  } catch {
-    return { session: name, lines: [], running, mirror: true };
-  }
-  const allLines = content.split(/\r?\n/).filter(Boolean);
-  const safeLines = Math.min(Math.max(lines, 1), 2000);
-  return { session: name, lines: allLines.slice(-safeLines), running, mirror: true };
-}
-
-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 { content, cursor } = captureConsistent(
-    () => captureContent(name, socketName),
-    () => tmuxCursorPos(name, socketName),
-  );
-
-  return {
-    session: name,
-    content,
-    running: true,
-    agentAlive,
-    ...size,
-    ...cursor,
-    capturedAt: Date.now(),
-  };
-}
-
-// Capture cursor and content *consistently*. They come from separate tmux invocations,
-// so if the pane scrolls between them (e.g. tool output streaming while the agent
-// "thinks"), cursorY ends up off-by-one against the captured grid — the parked cursor
-// then lands a row off and the TUI's next relative redraw stacks a stale statusline row
-// (bottom-box ghost). Read content, then cursor, then content again; accept only when the
-// two content reads bracket the cursor read unchanged, which proves the cursor reflects
-// that exact grid. Fall through with the latest capture if the pane never holds still.
-export function captureConsistent(
-  readContent: () => string,
-  readCursor: () => { cursorX?: number; cursorY?: number },
-  maxAttempts = 4,
-): { content: string; cursor: { cursorX?: number; cursorY?: number } } {
-  let content = readContent();
-  let cursor = readCursor();
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const recheck = readContent();
-    if (recheck === content) break;
-    content = recheck;
-    cursor = readCursor();
-  }
-  return { content, cursor };
-}
-
-function captureContent(name: string, socketName?: string): string {
-  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 result.stdout.toString();
-}
-
-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;
-}
-
-// Validation contract shared by the HTTP terminal routes and the websocket terminal
-// frames (orchestrator/src/api.ts). Both transports MUST enforce the same envelope —
-// keep these the single source of truth (see #143). Pure: no tmux, safe to unit-test.
-const TERMINAL_INPUT_MAX = 4096;
-
-export function validateTerminalInputData(input: unknown): string {
-  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 > TERMINAL_INPUT_MAX) throw new Error(`terminal input exceeds ${TERMINAL_INPUT_MAX} characters`);
-  return data;
-}
-
-export function validateTerminalResize(input: unknown): { cols: number; rows: number } {
-  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;
-  // typeof narrows for the bounds comparison; Number.isFinite additionally rejects
-  // NaN/Infinity — without it NaN slips past the bounds check below (every NaN
-  // comparison is false), the exact malformed-resize frame the websocket path used to
-  // forward via Number(frame.cols).
-  if (typeof cols !== "number" || typeof rows !== "number" || !Number.isFinite(cols) || !Number.isFinite(rows)) {
-    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");
-  return { cols: Math.round(cols), rows: Math.round(rows) };
-}
-
-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");
-  const data = validateTerminalInputData(input);
-
-  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");
-  const clamped = validateTerminalResize(input);
-  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 };
-}
-
-export function tmuxSocketForSession(name: string): string | undefined {
-  const record = loadState().find((item) => item.name === name);
-  return record ? readRunnerInfo(record)?.tmuxSocket : undefined;
-}
-
-// 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.
-export function sessionLiveness(name: string): { running: boolean; agentAlive: boolean } {
-  const socketName = tmuxSocketForSession(name);
-  return { running: tmuxHasSession(name, socketName), agentAlive: isSessionAlive(name) };
-}
-
-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 = 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 };
+export * from "./spawn/index";