agent-relay-orchestrator 0.23.0 → 0.25.0

package/package.json

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

package/src/api.ts

@@ -6,7 +6,7 @@ import { proxyArtifactRequest } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
 import type { RelayClient } from "./relay";
-import { captureSession, captureSessionMirror, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
+import { captureSession, captureSessionMirror, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest, validateTerminalInputData, validateTerminalResize } from "./spawn";
 import { acquireTerminalStream, type TerminalStreamHandle, type TerminalStreamSubscriber } from "./terminal-stream";
 import { VERSION, runtimeMetadata } from "./version";
 import { previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
@@ -751,11 +751,13 @@ function handleTerminalSocketMessage(ws: TerminalSocket, data: string | Buffer):
   const frame = payload as Record<string, unknown>;
   try {
     if (frame.type === "input") {
-      const text = typeof frame.data === "string" ? frame.data : "";
+      // Same envelope as the HTTP input route (#143): type + 4096-char cap. Invalid
+      // frames throw → caught below → terminal error frame, tmux untouched.
+      const text = validateTerminalInputData(frame);
       if (text) ws.data.stream?.write(new TextEncoder().encode(text));
     } else if (frame.type === "resize") {
-      const cols = Number(frame.cols);
-      const rows = Number(frame.rows);
+      // Same bounds as the HTTP resize route (#143): cols 10-500, rows 5-200.
+      const { cols, rows } = validateTerminalResize(frame);
       // First resize sizes the pane and triggers the (size-matched) backfill;
       // later ones just reflow the live stream.
       if (!ws.data.synced) {

package/src/index.ts

@@ -3,7 +3,7 @@ import { loadConfig, initConfigFile } from "./config";
 import { createRelayClient } from "./relay";
 import type { ManagedSessionExitDiagnostics } from "./relay";
 import { createControlHandler } from "./control";
-import { diagnoseSessionExit, isSessionAlive, refreshManagedAgentReport } from "./spawn";
+import { diagnoseSessionExit, hydrateTerminalGuests, isSessionAlive, reapTerminalGuests, refreshManagedAgentReport } from "./spawn";
 import { startApiServer } from "./api";
 import { recoverManagedAgents } from "./recovery";
 import { ProviderProbeCache } from "./provider-probe";
@@ -51,8 +51,10 @@ const control = createControlHandler(config, relay);
 
 const POLL_INTERVAL_MS = 3_000;
 const REGISTER_RETRY_MS = 5_000;
+const GUEST_REAP_INTERVAL_MS = 60_000;
 let pollTimer: Timer | null = null;
 let healthCheckTimer: Timer | null = null;
+let guestReaperTimer: Timer | null = null;
 let apiServer: { stop(): void; url: string } | null = null;
 
 async function startup(): Promise<void> {
@@ -75,12 +77,28 @@ async function startup(): Promise<void> {
   // Recover existing tmux sessions
   await recoverManagedAgents(config, control, relay);
 
+  // Restore guest-terminal TTLs persisted before the last restart, then reap any
+  // that expired (or were orphaned) while the orchestrator was down (#144).
+  hydrateTerminalGuests();
+  const reaped = reapTerminalGuests(config);
+  if (reaped.length > 0) console.error(`[orchestrator] Reaped ${reaped.length} expired guest terminal(s)`);
+
   // Start polling for command requests
   startPolling();
 
   // Periodic health check — remove dead sessions
   healthCheckTimer = setInterval(healthCheck, 60_000);
 
+  // Periodic guest-terminal reaper — enforces guest TTL without requiring a new
+  // guest creation to trigger cleanup (#144).
+  guestReaperTimer = setInterval(() => {
+    try {
+      reapTerminalGuests(config);
+    } catch (err) {
+      console.error(`[orchestrator] Guest reap error: ${err}`);
+    }
+  }, GUEST_REAP_INTERVAL_MS);
+
   console.error("[orchestrator] Ready. Polling for command requests...");
 }
 
@@ -178,6 +196,7 @@ async function shutdown(): Promise<void> {
   console.error("[orchestrator] Shutting down...");
   if (pollTimer) clearInterval(pollTimer);
   if (healthCheckTimer) clearInterval(healthCheckTimer);
+  if (guestReaperTimer) clearInterval(guestReaperTimer);
   if (apiServer) apiServer.stop();
   relay.stopHeartbeatLoop();
   process.exit(0);

package/src/spawn.ts

@@ -146,7 +146,9 @@ 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);
@@ -444,6 +446,7 @@ export async function createTerminalGuest(
     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 };
 }
 
@@ -452,6 +455,7 @@ export function stopTerminalGuest(session: string, config: OrchestratorConfig):
   const running = tmuxHasSession(session);
   if (running) killTmuxSession(session);
   terminalGuests.delete(session);
+  saveGuestState();
   return { session, stopped: running };
 }
 
@@ -547,13 +551,147 @@ function isGuestSessionName(session: string, config: OrchestratorConfig): boolea
   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 {
@@ -1088,15 +1226,39 @@ export function terminalInputTokens(data: string): TerminalInputToken[] {
   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");
-  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 data = validateTerminalInputData(input);
 
   const tokens = terminalInputTokens(data);
   for (const token of tokens) {
@@ -1126,14 +1288,7 @@ export function resizeTerminal(name: string, config: OrchestratorConfig, input:
   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 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",

package/src/workspace-probe.ts

@@ -922,6 +922,9 @@ function mergeRebaseFf(
     }
   }
   const headSha = git(["rev-parse", "HEAD"], worktreePath).stdout;
+  // Subject of the landed commit for the relay's branch.landed notice (#239). Best-effort:
+  // an empty/failed read just omits it from the message body.
+  const landedSubject = git(["log", "-1", "--format=%s", headSha], worktreePath).stdout || undefined;
 
   // Advance base to the rebased branch. If base is checked out somewhere, do a
   // real ff-only merge there so its working tree stays consistent; otherwise
@@ -964,15 +967,15 @@ function mergeRebaseFf(
       // continues from a buildable state (issue #51). No-op when nothing is stale.
       const depsRefresh = refreshWorkspaceDeps(repoRoot, worktreePath);
       const reportDeps = depsRefresh.refreshed || depsRefresh.stale || depsRefresh.error;
-      return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, ...(reportDeps ? { depsRefresh } : {}), error: undefined });
+      return head({ merged: true, status: "active", mergedSha: headSha, subject: landedSubject, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, ...(reportDeps ? { depsRefresh } : {}), error: undefined });
     }
     // Recycle failed — keep the existing branch. Still landed, still active.
-    return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branchDeleted: false, pushed, error: undefined });
+    return head({ merged: true, status: "active", mergedSha: headSha, subject: landedSubject, worktreeRemoved: false, branchDeleted: false, pushed, error: undefined });
   }
   const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
   const worktreeRemoved = removed.ok;
   const branchDeleted = worktreeRemoved ? git(["branch", "-D", branch], repoRoot).ok : false;
-  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, pushed, error: undefined });
+  return head({ merged: true, status: "merged", mergedSha: headSha, subject: landedSubject, worktreeRemoved, branchDeleted, pushed, error: undefined });
 }
 
 async function availableBranch(repoRoot: string, base: string): Promise<string> {