agent-relay-orchestrator 0.11.8 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.11.8",
+  "version": "0.12.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.4"
+    "agent-relay-sdk": "0.2.6"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -1,9 +1,10 @@
-import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import type { ServerWebSocket } from "bun";
 import { proxyArtifactRequest } from "./artifact-proxy";
 import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
+import type { RelayClient } from "./relay";
 import { captureSession, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
 import { acquireTerminalStream, type TerminalStreamHandle, type TerminalStreamSubscriber } from "./terminal-stream";
 import { VERSION, runtimeMetadata } from "./version";
@@ -21,10 +22,16 @@ interface DirectoryListing {
   entries: DirectoryEntry[];
 }
 
+export type GitFileStatus = "staged" | "unstaged" | "staged-unstaged" | "untracked";
+
 export interface FileEntry {
   name: string;
   path: string;
   type: "file" | "directory" | "symlink";
+  /** True when the directory entry is itself a symlink (resolved type is reported in `type`). */
+  symlink?: boolean;
+  /** Working-tree git status for this entry (or aggregate, for directories). */
+  gitStatus?: GitFileStatus;
   size?: number;
   modifiedAt?: number;
 }
@@ -40,7 +47,7 @@ export interface FileReadResult {
   path: string;
   name: string;
   mediaType: string;
-  encoding: "utf8" | "binary";
+  encoding: "utf8" | "binary" | "base64";
   size: number;
   modifiedAt?: number;
   truncated: boolean;
@@ -57,6 +64,7 @@ export interface FileStatResult {
 }
 
 const MAX_FILE_PREVIEW_BYTES = 1024 * 1024;
+const MAX_IMAGE_PREVIEW_BYTES = 8 * 1024 * 1024;
 
 interface TerminalSocketData {
   kind: "terminal";
@@ -117,19 +125,23 @@ function createDirectory(parentPath: string, name: string, baseDir: string): Dir
   return listDirectories(target, baseDir);
 }
 
+// Containment is lexical (resolve + relative), per the project's path-containment
+// rule. This intentionally follows symlinks wherever they point: the `path` query
+// param itself can't escape baseDir with `../`, but symlinks placed inside baseDir
+// by the operator are treated as first-class entries (same trust level as the
+// authenticated dashboard, which can already open a host terminal).
 function resolveInsideBase(requestedPath: string | undefined, baseDir: string): { base: string; target: string } {
-  const base = realpathSync(resolve(baseDir));
-  const candidate = resolve(requestedPath || base);
-  let target: string;
-  try {
-    target = realpathSync(candidate);
-  } catch {
-    throw new Error(`Path does not exist: ${candidate}`);
-  }
+  const base = resolve(baseDir);
+  const target = resolve(requestedPath || base);
   const rel = relative(base, target);
-  if (rel && (rel.startsWith("..") || rel.startsWith("/"))) {
+  if (rel && (rel.startsWith("..") || isAbsolute(rel))) {
     throw new Error(`Path must be within baseDir: ${baseDir}`);
   }
+  try {
+    statSync(target);
+  } catch {
+    throw new Error(`Path does not exist: ${target}`);
+  }
   return { base, target };
 }
 
@@ -139,42 +151,51 @@ function parentInsideBase(target: string, base: string): string | undefined {
   return parentRel && !parentRel.startsWith("..") && !parentRel.startsWith("/") && parent !== target ? parent : undefined;
 }
 
-export function listFiles(requestedPath: string | undefined, baseDir: string): FileListing {
+export function listFiles(requestedPath: string | undefined, baseDir: string, options: { git?: boolean } = {}): FileListing {
   const { base, target } = resolveInsideBase(requestedPath, baseDir);
   const stat = statSync(target);
   if (!stat.isDirectory()) throw new Error(`Not a directory: ${target}`);
 
+  // Perf: directories need no stat at all (Dirent already tells us the kind).
+  // Files need one statSync for size/mtime; symlinks need one statSync (which
+  // follows the link) to resolve their target kind. This replaces the previous
+  // lstat + realpath + stat triple per entry.
   const entries = readdirSync(target, { withFileTypes: true })
-    .map((entry): FileEntry | null => {
+    .map((entry): FileEntry => {
       const entryPath = join(target, entry.name);
-      let type: FileEntry["type"] = entry.isDirectory() ? "directory" : "file";
-      let statForSize;
-      try {
-        const lst = lstatSync(entryPath);
-        if (lst.isSymbolicLink()) type = "symlink";
-        const resolved = realpathSync(entryPath);
-        const rel = relative(base, resolved);
-        if (rel && (rel.startsWith("..") || rel.startsWith("/"))) return null;
-        statForSize = statSync(resolved);
-        if (type !== "symlink") type = statForSize.isDirectory() ? "directory" : "file";
-      } catch {
-        return null;
+      const isLink = entry.isSymbolicLink();
+      const result: FileEntry = { name: entry.name, path: entryPath, type: "file" };
+      if (isLink) result.symlink = true;
+
+      if (isLink) {
+        try {
+          const st = statSync(entryPath); // follows the link
+          result.type = st.isDirectory() ? "directory" : "file";
+          if (st.isFile()) result.size = st.size;
+          result.modifiedAt = st.mtimeMs;
+        } catch {
+          result.type = "symlink"; // broken link — surface it rather than hide it
+          try { result.modifiedAt = lstatSync(entryPath).mtimeMs; } catch { /* ignore */ }
+        }
+      } else if (entry.isDirectory()) {
+        result.type = "directory";
+      } else {
+        try {
+          const st = statSync(entryPath);
+          result.size = st.size;
+          result.modifiedAt = st.mtimeMs;
+        } catch { /* entry vanished mid-listing */ }
       }
-      return {
-        name: entry.name,
-        path: entryPath,
-        type,
-        ...(statForSize.isFile() ? { size: statForSize.size } : {}),
-        modifiedAt: statForSize.mtimeMs,
-      };
+      return result;
     })
-    .filter((entry): entry is FileEntry => Boolean(entry))
     .sort((a, b) => {
       if (a.type === "directory" && b.type !== "directory") return -1;
       if (a.type !== "directory" && b.type === "directory") return 1;
       return a.name.localeCompare(b.name);
     });
 
+  if (options.git) applyGitStatus(target, entries);
+
   return {
     path: target,
     parent: parentInsideBase(target, base),
@@ -183,6 +204,59 @@ export function listFiles(requestedPath: string | undefined, baseDir: string): F
   };
 }
 
+/** Overlay working-tree git status onto directory entries (best-effort, never throws). */
+function applyGitStatus(target: string, entries: FileEntry[]): void {
+  const root = runGitIn(["rev-parse", "--show-toplevel"], target);
+  if (root === null) return; // not a git repo
+
+  // `--no-renames` reports renames as delete+add, sidestepping the two-path -z
+  // parse. The `.` pathspec scopes output to this directory's subtree.
+  const raw = runGitIn(["status", "--porcelain", "-z", "--no-renames", "--", "."], target);
+  if (!raw) return;
+
+  // name -> { staged, unstaged, untracked }, aggregated across descendants so a
+  // directory inherits the status of files changed beneath it.
+  const agg = new Map<string, { staged: boolean; unstaged: boolean; untracked: boolean }>();
+  for (const token of raw.split("\0")) {
+    if (token.length < 4) continue;
+    const x = token[0];
+    const y = token[1];
+    const p = token.slice(3);
+    const abs = resolve(root, p);
+    const rel = relative(target, abs);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) continue;
+    const name = (rel.split("/")[0] ?? "").replace(/\/$/, "");
+    if (!name) continue;
+    const cur = agg.get(name) ?? { staged: false, unstaged: false, untracked: false };
+    if (x === "?" && y === "?") cur.untracked = true;
+    else {
+      if (x !== " " && x !== "?") cur.staged = true;
+      if (y !== " " && y !== "?") cur.unstaged = true;
+    }
+    agg.set(name, cur);
+  }
+
+  for (const entry of entries) {
+    const a = agg.get(entry.name);
+    if (!a) continue;
+    if (a.staged && a.unstaged) entry.gitStatus = "staged-unstaged";
+    else if (a.staged) entry.gitStatus = "staged";
+    else if (a.unstaged) entry.gitStatus = "unstaged";
+    else if (a.untracked) entry.gitStatus = "untracked";
+  }
+}
+
+/** Run git in `cwd`, returning trimmed stdout, or null on failure. */
+function runGitIn(args: string[], cwd: string): string | null {
+  try {
+    const proc = Bun.spawnSync(["git", "-C", cwd, ...args], { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+    if (proc.exitCode !== 0) return null;
+    return proc.stdout.toString().replace(/\n+$/, "");
+  } catch {
+    return null;
+  }
+}
+
 export function statFilePath(requestedPath: string | undefined, baseDir: string): FileStatResult {
   if (!requestedPath) throw new Error("path is required");
   const { base, target } = resolveInsideBase(requestedPath, baseDir);
@@ -198,20 +272,23 @@ export function statFilePath(requestedPath: string | undefined, baseDir: string)
   };
 }
 
+function readBytes(target: string, count: number): Buffer {
+  const buffer = Buffer.alloc(count);
+  const fd = openSync(target, "r");
+  try {
+    readSync(fd, buffer, 0, count, 0);
+  } finally {
+    closeSync(fd);
+  }
+  return buffer;
+}
+
 export function readFilePreview(requestedPath: string | undefined, baseDir: string): FileReadResult {
   if (!requestedPath) throw new Error("path is required");
   const { target } = resolveInsideBase(requestedPath, baseDir);
   const stat = statSync(target);
   if (!stat.isFile()) throw new Error(`Not a file: ${target}`);
 
-  const bytesToRead = Math.min(stat.size, MAX_FILE_PREVIEW_BYTES);
-  const buffer = Buffer.alloc(bytesToRead);
-  const fd = openSync(target, "r");
-  try {
-    readSync(fd, buffer, 0, bytesToRead, 0);
-  } finally {
-    closeSync(fd);
-  }
   const mediaType = mediaTypeForPath(target);
   const resultBase = {
     path: target,
@@ -219,15 +296,28 @@ export function readFilePreview(requestedPath: string | undefined, baseDir: stri
     mediaType,
     size: stat.size,
     modifiedAt: stat.mtimeMs,
-    truncated: stat.size > MAX_FILE_PREVIEW_BYTES,
   };
 
+  // Images are returned as base64 so the dashboard can render them inline. They
+  // must be read whole — a truncated image would be corrupt — so they get a
+  // higher cap and fall back to a plain binary marker when too large.
+  if (mediaType.startsWith("image/")) {
+    if (stat.size > MAX_IMAGE_PREVIEW_BYTES) {
+      return { ...resultBase, truncated: true, encoding: "binary" };
+    }
+    return { ...resultBase, truncated: false, encoding: "base64", content: readBytes(target, stat.size).toString("base64") };
+  }
+
+  const buffer = readBytes(target, Math.min(stat.size, MAX_FILE_PREVIEW_BYTES));
+  const truncated = stat.size > MAX_FILE_PREVIEW_BYTES;
+
   if (isBinaryBuffer(buffer)) {
-    return { ...resultBase, encoding: "binary" };
+    return { ...resultBase, truncated, encoding: "binary" };
   }
 
   return {
     ...resultBase,
+    truncated,
     encoding: "utf8",
     content: new TextDecoder("utf-8", { fatal: true }).decode(buffer),
   };
@@ -255,6 +345,14 @@ function mediaTypeForPath(path: string): string {
   if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return "text/javascript";
   if (ext === ".ts" || ext === ".tsx" || ext === ".jsx") return "text/typescript";
   if (ext === ".txt" || ext === ".log" || ext === ".sh" || name.startsWith(".env")) return "text/plain";
+  if (ext === ".png") return "image/png";
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".svg") return "image/svg+xml";
+  if (ext === ".bmp") return "image/bmp";
+  if (ext === ".ico") return "image/x-icon";
+  if (ext === ".avif") return "image/avif";
   return "application/octet-stream";
 }
 
@@ -276,7 +374,7 @@ function authorized(req: Request, config: OrchestratorConfig): boolean {
   return req.headers.get("x-agent-relay-token") === config.token;
 }
 
-export function startApiServer(config: OrchestratorConfig, probeCache: ProviderProbeCache): { stop(): void; url: string } {
+export function startApiServer(config: OrchestratorConfig, probeCache: ProviderProbeCache, relay?: RelayClient): { stop(): void; url: string } {
   const server = Bun.serve<TerminalSocketData>({
     port: config.apiPort,
     hostname: "0.0.0.0",
@@ -293,6 +391,22 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
         });
       }
 
+      // Runner self-heal: a runner whose runtime token expired proxies it here to
+      // get a fresh one. No orchestrator-token auth (the runner doesn't hold it) —
+      // the relay is the gate: it only re-mints a genuine, non-revoked runner token
+      // owned by this orchestrator. The signed (even expired) token is the identity.
+      if (req.method === "POST" && url.pathname === "/api/runtime-tokens/runner-renew") {
+        if (!relay) return error("re-mint unavailable", 503);
+        const body = await req.json().catch(() => null);
+        const token = body && typeof body === "object" && typeof (body as { token?: unknown }).token === "string"
+          ? (body as { token: string }).token
+          : "";
+        if (!token) return error("token required", 400);
+        const reminted = await relay.remintRunnerToken(token);
+        if (!reminted) return error("runner token re-mint failed", 502);
+        return json(reminted);
+      }
+
       if (url.pathname === "/api/artifacts" || url.pathname.startsWith("/api/artifacts/")) {
         if (!authorized(req, config)) return error("unauthorized", 401);
         return proxyArtifactRequest(req, config).catch((e) => error((e as Error).message, 502));
@@ -321,7 +435,8 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
       if (req.method === "GET" && url.pathname === "/api/files/list") {
         if (!authorized(req, config)) return error("unauthorized", 401);
         try {
-          return json(listFiles(url.searchParams.get("path") || undefined, config.baseDir));
+          const git = url.searchParams.get("git") === "1";
+          return json(listFiles(url.searchParams.get("path") || undefined, config.baseDir, { git }));
         } catch (e) {
           return error((e as Error).message);
         }
@@ -394,6 +509,7 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
             baseRef: url.searchParams.get("baseRef") || undefined,
             baseSha: url.searchParams.get("baseSha") || undefined,
             strategy: strategy === "pr" || strategy === "rebase-ff" || strategy === "auto" ? strategy : undefined,
+            checkPr: url.searchParams.get("checkPr") === "1",
           }));
         } catch (e) {
           return error((e as Error).message);

package/src/control.ts

@@ -33,10 +33,26 @@ export function createControlHandler(
   async function handleShutdown(ctrl: Record<string, any>, restart = false): Promise<Record<string, unknown>> {
     const current = managedAgentShutdownTarget(managedAgents, ctrl);
     const session = current?.sessionName ?? current?.tmuxSession;
-    if (!session) return { stopped: false, wasRunning: false };
+    const restartSpawn = isRecord(ctrl.restartSpawn) ? ctrl.restartSpawn : undefined;
+    if (!session) {
+      let restarted: ManagedAgentReport | undefined;
+      if (restart && restartSpawn) {
+        restarted = await spawnAgent(spawnOptionsFromRestartSource(restartSpawn, config), config);
+        managedAgents.push(restarted);
+        console.error(`[orchestrator] Restarted ${restarted.provider} agent without prior live session: ${restarted.tmuxSession}`);
+      }
+      return {
+        stopped: false,
+        wasRunning: false,
+        restart,
+        restarted: Boolean(restarted),
+        ...(restarted ? { agent: restarted } : {}),
+        policyName: ctrl.policyName,
+        spawnRequestId: ctrl.spawnRequestId,
+      };
+    }
     const result = await stopSession(session, config, typeof ctrl.reason === "string" ? ctrl.reason : restart ? "restart" : "shutdown", ctrl.graceful !== false, shutdownTimeoutMs(ctrl));
     managedAgents = managedAgents.filter((agent) => (agent.sessionName ?? agent.tmuxSession) !== session);
-    const restartSpawn = isRecord(ctrl.restartSpawn) ? ctrl.restartSpawn : undefined;
     // A managed restart carries a fresh spawnRequestId in restartSpawn — keep it.
     // Falling back to the live agent's params would reuse the stale id and break
     // relay correlation, so drop it and let spawnAgent assign a new identity.

package/src/index.ts

@@ -63,7 +63,7 @@ async function startup(): Promise<void> {
   console.error(`[orchestrator]   env keys: ${Object.keys(config.env).length}`);
 
   // Start API server before registration so we can advertise the URL
-  apiServer = startApiServer(config, probeCache);
+  apiServer = startApiServer(config, probeCache, relay);
   console.error(`[orchestrator]   apiUrl: ${apiServer.url}`);
 
   // Register with relay. The server and orchestrator are often restarted

package/src/relay.ts

@@ -13,9 +13,15 @@ export interface RelayClient {
   setApiUrl(url: string): void;
   startHeartbeatLoop(): void;
   stopHeartbeatLoop(): void;
+  remintRunnerToken(currentToken: string): Promise<RunnerTokenRemint | null>;
   connected: boolean;
 }
 
+export interface RunnerTokenRemint {
+  token: string;
+  record: { jti: string; profileId?: string; expiresAt?: number };
+}
+
 export interface ManagedAgentReport {
   agentId: string;
   provider: "claude" | "codex";
@@ -268,6 +274,18 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
     setApiUrl(url: string) { apiUrl = url; },
     startHeartbeatLoop,
     stopHeartbeatLoop,
+    // Proxy a runner's expired token to the relay using our (long-lived)
+    // orchestrator credential, returning a freshly minted runner token. Lets a
+    // live runner self-heal an expired token instead of stranding the session.
+    async remintRunnerToken(currentToken: string): Promise<RunnerTokenRemint | null> {
+      try {
+        const res = await apiCall("POST", `/orchestrators/${config.id}/runner-token`, { token: currentToken });
+        if (!res.ok) return null;
+        return await res.json() as RunnerTokenRemint;
+      } catch {
+        return null;
+      }
+    },
     get connected() { return connected; },
   };
 }

package/src/workspace-probe.ts

@@ -490,6 +490,34 @@ function ghAvailable(): boolean {
   return Boolean(Bun.which("gh"));
 }
 
+/**
+ * Ground-truth merge state for the branch checked out at `worktreePath`, via gh.
+ * This is the only reliable signal once a PR is squash-merged AND base has moved
+ * on: the squash re-creates the work as one new commit (patch ids no longer
+ * match, so `git cherry` can't see it) and the trees diverge (so tree-equality
+ * can't either), leaving local git convinced the branch is still unmerged.
+ * Returns undefined when there's no PR, no detached/unknown branch, or gh fails —
+ * we never invent a merge.
+ */
+function prMergedState(worktreePath: string): { state: "merged" | "open"; url?: string } | undefined {
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], worktreePath);
+  if (!branch.ok || !branch.stdout || branch.stdout === "HEAD") return undefined;
+  const proc = Bun.spawnSync(["gh", "pr", "view", branch.stdout, "--json", "state,url"], {
+    cwd: worktreePath,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (proc.exitCode !== 0) return undefined; // no PR for the branch, or gh unavailable/unauthed
+  try {
+    const data = JSON.parse(proc.stdout.toString()) as { state?: string; url?: string };
+    if (!data.state) return undefined;
+    return { state: data.state === "MERGED" ? "merged" : "open", url: data.url };
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Predict whether merging the branch's commits into base would conflict, using
  * git's three-way merge-tree (no working-tree changes). Exit 0 = clean, exit 1
@@ -524,7 +552,7 @@ function worktreeForBranch(repoRoot: string, branch: string): { path: string; di
  * `auto` would pick plus whether the merge is clean, would conflict, or is a
  * no-op — so the dashboard can warn before the user commits to it.
  */
-export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?: string; baseSha?: string; strategy?: "pr" | "rebase-ff" | "auto" }): WorkspaceMergePreview {
+export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?: string; baseSha?: string; strategy?: "pr" | "rebase-ff" | "auto"; checkPr?: boolean }): WorkspaceMergePreview {
   const gitState = workspaceGitState(input);
   const remote = input.worktreePath ? hasOriginRemote(resolve(input.worktreePath)) : false;
   const gh = ghAvailable();
@@ -543,9 +571,28 @@ export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?:
   base.behind = gitState.behind;
   base.dirtyCount = gitState.dirtyCount;
   if ((gitState.dirtyCount ?? 0) > 0) return { ...base, reason: "worktree has uncommitted changes" };
-  const effectiveAhead = gitState.landed ? 0 : (gitState.unmergedAhead ?? gitState.ahead ?? 0);
+  let effectiveAhead = gitState.landed ? 0 : (gitState.unmergedAhead ?? gitState.ahead ?? 0);
+  // Local git still thinks there's unmerged work, but a squash-merged PR whose
+  // base has moved on is invisible to it. When the caller opts in (checkPr) and
+  // the strategy targets a PR, ask gh for the truth — a MERGED PR means landed.
+  if (effectiveAhead > 0 && input.checkPr && strategy === "pr" && input.worktreePath) {
+    const pr = prMergedState(resolve(input.worktreePath));
+    if (pr) {
+      base.prState = pr.state;
+      if (pr.url) base.prUrl = pr.url;
+      if (pr.state === "merged") {
+        base.prMerged = true;
+        effectiveAhead = 0;
+      }
+    }
+  }
   if (effectiveAhead === 0) {
-    return { ...base, reason: gitState.landed ? "already merged into base (squash/cherry-pick)" : "no commits to merge" };
+    const reason = base.prMerged
+      ? "PR merged on remote"
+      : gitState.landed
+        ? "already merged into base (squash/cherry-pick)"
+        : "no commits to merge";
+    return { ...base, reason };
   }
   if (gitState.baseRef && input.worktreePath) {
     const conflict = predictConflict(resolve(input.worktreePath), gitState.baseRef);