agent-relay-orchestrator 0.62.3 → 0.63.1

package/package.json

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

package/src/artifact-proxy.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
-import type { OrchestratorConfig } from "./config";
+import { artifactCacheDirFromEnv, type OrchestratorConfig } from "./config";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 const SAFE_ARTIFACT_ID = /^[a-zA-Z0-9._-]{1,160}$/;
@@ -42,7 +42,7 @@ export function artifactProxyBaseUrl(config: Pick<OrchestratorConfig, "apiPort">
 }
 
 function artifactCacheRoot(): string {
-  const configured = process.env.AGENT_RELAY_ARTIFACT_CACHE_DIR || "~/.agent-relay/cache/artifacts";
+  const configured = artifactCacheDirFromEnv();
   if (configured === "~") return homedir();
   if (configured.startsWith("~/")) return join(homedir(), configured.slice(2));
   return configured;

package/src/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir, hostname as osHostname } from "node:os";
 import { join, dirname } from "node:path";
+import { DEFAULT_RELAY_URL } from "agent-relay-sdk";
 
 export interface OrchestratorConfig {
   id: string;
@@ -17,6 +18,63 @@ export interface OrchestratorConfig {
 
 const DEFAULT_CONFIG_PATH = join(homedir(), ".agent-relay", "orchestrator.json");
 
+function envNumberOrDefault(name: string, fallback: number): number {
+  return Number(process.env[name]) || fallback;
+}
+
+function envNonNegativeMax(name: string, fallback: number, min: number): number {
+  return Math.max(min, envNumberOrDefault(name, fallback));
+}
+
+export function gitShaFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
+}
+
+export function agentRelayHome(): string {
+  return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
+}
+
+export function artifactCacheDirFromEnv(): string {
+  return process.env.AGENT_RELAY_ARTIFACT_CACHE_DIR || "~/.agent-relay/cache/artifacts";
+}
+
+export function bunBinFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_BUN_BIN;
+}
+
+export function disableSystemdSupervisor(): boolean {
+  return process.env.AGENT_RELAY_DISABLE_SYSTEMD_SUPERVISOR === "1";
+}
+
+export function forceSystemdSupervisor(): boolean {
+  return process.env.AGENT_RELAY_FORCE_SYSTEMD_SUPERVISOR === "1";
+}
+
+export function logDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LOG_DIR;
+}
+
+export function workspacePushEnabled(): boolean {
+  return process.env.AGENT_RELAY_WORKSPACE_PUSH !== "0";
+}
+
+export function workspaceDepsMode(): string {
+  return (process.env.AGENT_RELAY_WORKSPACE_DEPS || "symlink").toLowerCase();
+}
+
+export const TERMINAL_FLUSH_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_FLUSH_MS", 6, 0);
+export const TERMINAL_FLUSH_MAX_BYTES = envNonNegativeMax("AGENT_RELAY_TERMINAL_FLUSH_MAX_BYTES", 65536, 4096);
+export const TERMINAL_BACKPRESSURE_MAX_BYTES = envNonNegativeMax("AGENT_RELAY_TERMINAL_BACKPRESSURE_MAX_BYTES", 8 << 20, 1 << 20);
+export const TERMINAL_RESIZE_SETTLE_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESIZE_SETTLE_MS", 90, 0);
+export const TERMINAL_RESYNC_DEBOUNCE_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_DEBOUNCE_MS", 120, 0);
+export const TERMINAL_RESYNC_MAX_INTERVAL_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_MAX_INTERVAL_MS", 350, 0);
+export const TERMINAL_RESYNC_GROUND_RETRY_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_GROUND_RETRY_MS", 16, 1);
+export const TERMINAL_RESYNC_GROUND_DEFER_MAX_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_RESYNC_GROUND_DEFER_MAX_MS", 500, 0);
+export const TERMINAL_COMMAND_TIMEOUT_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_COMMAND_TIMEOUT_MS", 2000, 100);
+export const TERMINAL_GROUND_WAIT_MAX_MS = envNonNegativeMax("AGENT_RELAY_TERMINAL_GROUND_WAIT_MAX_MS", 500, 0);
+export const TERMINAL_BACKFILL_SCROLLBACK_LINES = envNonNegativeMax("AGENT_RELAY_TERMINAL_BACKFILL_SCROLLBACK", 1000, 0);
+export const TERMINAL_DEBUG = process.env.AGENT_RELAY_TERMINAL_DEBUG === "1";
+
 interface RawConfig {
   id?: string;
   hostname?: string;
@@ -40,7 +98,7 @@ export function loadConfig(path?: string): OrchestratorConfig {
 
   const id = raw.id || process.env.AGENT_RELAY_ORCHESTRATOR_ID || osHostname().replace(/\./g, "-");
   const hostname = raw.hostname || process.env.AGENT_RELAY_ORCHESTRATOR_HOSTNAME || osHostname();
-  const relayUrl = raw.relayUrl || process.env.AGENT_RELAY_URL || "http://localhost:4850";
+  const relayUrl = raw.relayUrl || process.env.AGENT_RELAY_URL || DEFAULT_RELAY_URL;
   const token = raw.token || process.env.AGENT_RELAY_TOKEN || undefined;
   const providers = (raw.providers || process.env.AGENT_RELAY_ORCHESTRATOR_PROVIDERS?.split(",") || ["claude", "codex"]) as ("claude" | "codex")[];
   const baseDir = raw.baseDir || process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR || join(homedir(), "projects");
@@ -58,7 +116,7 @@ export function initConfigFile(config: Partial<RawConfig>): string {
   const defaults: RawConfig = {
     id: osHostname().replace(/\./g, "-"),
     hostname: osHostname(),
-    relayUrl: "http://localhost:4850",
+    relayUrl: DEFAULT_RELAY_URL,
     providers: ["claude", "codex"],
     baseDir: join(homedir(), "projects"),
     apiPort: 4860,

package/src/provider-config-migration.ts

@@ -1,16 +1,13 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { join } from "node:path";
+import { agentRelayHome } from "./config";
 
 interface ProviderConfigMigrationPayload {
   host: string;
   configs: Record<string, unknown>;
 }
 
-function agentRelayHome(): string {
-  return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
-}
-
 /**
  * Read the host-local per-provider config files (`~/.agent-relay/providers/*.json`)
  * so the relay can seed the central `provider-config` rows with server authority

package/src/spawn/command.ts

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

package/src/spawn/constants.ts

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

package/src/spawn/guests.ts

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

package/src/spawn/index.ts

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

package/src/spawn/log-utils.ts

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