agent-relay-orchestrator 0.78.9 → 0.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.78.9",
+  "version": "0.79.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.58"
+    "agent-relay-sdk": "0.2.59"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -9,7 +9,7 @@ import type { RelayClient } from "./relay";
 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 { previewBranchMerge, previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
+import { branchMergePreviewResponse, mergePreviewResponse, recoveryBranchesResponse, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
 
 interface DirectoryEntry {
   name: string;
@@ -506,39 +506,17 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
 
       if (req.method === "GET" && url.pathname === "/api/workspace/merge-preview") {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        try {
-          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
-          const strategy = url.searchParams.get("strategy");
-          return json(previewWorkspaceMerge({
-            worktreePath: target,
-            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);
-        }
+        return mergePreviewResponse(url, config.baseDir);
       }
 
       if (req.method === "GET" && url.pathname === "/api/workspace/branch-merge-preview") {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        try {
-          const { target } = resolveInsideBase(url.searchParams.get("repoRoot") || undefined, config.baseDir);
-          const strategy = url.searchParams.get("strategy");
-          const preview = previewBranchMerge({
-            repoRoot: target,
-            branch: url.searchParams.get("branch") || undefined,
-            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",
-          });
-          if (preview === null) return error("branch not found", 404);
-          return json(preview);
-        } catch (e) {
-          return error((e as Error).message);
-        }
+        return branchMergePreviewResponse(url, config.baseDir);
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/recovery-branches") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        return recoveryBranchesResponse(url, config.baseDir);
       }
 
       if (req.method === "GET" && url.pathname === "/api/providers") {

package/src/control.ts

@@ -4,7 +4,7 @@ import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
 import { readLocalProviderConfigs } from "./provider-config-migration";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
+import { cleanupWorkspace, discardRecoveryBranch, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
 import { armWorkspacePrAutoMerge, mergeWorkspacePr, refreshWorkspacePrBranch } from "./workspace-pr";
 
 interface ControlHandler {
@@ -173,6 +173,15 @@ export function createControlHandler(
           { checkOnly: command.params.checkOnly === true },
         );
         await relay.updateCommand(command.id, "succeeded", { workspaceId: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined, ...result });
+      } else if (command.type === "workspace.recovery-branch-discard") {
+        const result = discardRecoveryBranch({
+          repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
+          branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
+          baseRef: typeof command.params.baseRef === "string" ? command.params.baseRef : undefined,
+          baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
+          force: command.params.force === true,
+        });
+        await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
       } else if (command.type === "workspace.prune") {
         const result = pruneWorktrees({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,

package/src/workspace-probe/index.ts

@@ -5,4 +5,6 @@ export * from "./merge";
 export * from "./names";
 export * from "./parse";
 export * from "./probe";
+export * from "./recovery-branches";
+export * from "./request";
 export type { WorkspaceMergeInput, WorkspaceResolution, WorkspaceResolutionInput } from "./types";

package/src/workspace-probe/merge.ts

@@ -7,6 +7,7 @@ import { refreshWorkspaceDeps } from "./deps";
 import { populateMergeState, resolveBranchRef, syncBaseFromOrigin, upstreamRef, workspaceGitState } from "./git-state";
 import { nextBranchName } from "./names";
 import { parseWorktrees, shortBranch } from "./parse";
+import { json, resolveRequestedPath } from "./request";
 import type { WorkspaceMergeInput } from "./types";
 import { workspacePushEnabled } from "../config";
 
@@ -128,6 +129,38 @@ export function previewBranchMerge(input: {
   return base;
 }
 
+export function mergePreviewResponse(url: URL, baseDir: string): Response {
+  try {
+    const strategy = url.searchParams.get("strategy");
+    return json(previewWorkspaceMerge({
+      worktreePath: resolveRequestedPath(url.searchParams.get("path") || undefined, baseDir),
+      baseRef: url.searchParams.get("baseRef") || undefined,
+      baseSha: url.searchParams.get("baseSha") || undefined,
+      strategy: validPreviewStrategy(strategy),
+      checkPr: url.searchParams.get("checkPr") === "1",
+    }));
+  } catch (e) {
+    return json({ error: (e as Error).message }, 400);
+  }
+}
+
+export function branchMergePreviewResponse(url: URL, baseDir: string): Response {
+  try {
+    const strategy = url.searchParams.get("strategy");
+    const preview = previewBranchMerge({
+      repoRoot: resolveRequestedPath(url.searchParams.get("repoRoot") || undefined, baseDir),
+      branch: url.searchParams.get("branch") || undefined,
+      baseRef: url.searchParams.get("baseRef") || undefined,
+      baseSha: url.searchParams.get("baseSha") || undefined,
+      strategy: validPreviewStrategy(strategy),
+      checkPr: url.searchParams.get("checkPr") === "1",
+    });
+    return preview === null ? json({ error: "branch not found" }, 404) : json(preview);
+  } catch (e) {
+    return json({ error: (e as Error).message }, 400);
+  }
+}
+
 /**
  * Read-only pre-flight for integrating a workspace's work. Reports the strategy
  * `auto` would pick plus whether the merge is clean, would conflict, or is a
@@ -177,6 +210,10 @@ export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?:
   return base;
 }
 
+function validPreviewStrategy(strategy: string | null): "pr" | "rebase-ff" | "auto" | undefined {
+  return strategy === "pr" || strategy === "rebase-ff" || strategy === "auto" ? strategy : undefined;
+}
+
 /**
  * Integrate a workspace's work back into its base branch. Two strategies:
  *  - rebase-ff: rebase the agent branch onto base, fast-forward base to it,

package/src/workspace-probe/recovery-branches.ts

@@ -0,0 +1,124 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { WorkspaceRecoveryBranch, WorkspaceRecoveryBranchDiscardResult } from "agent-relay-sdk";
+import { git } from "../git";
+import { populateMergeState } from "./git-state";
+import { json, resolveRequestedPath } from "./request";
+
+interface BranchSafety {
+  safe: boolean;
+  reason?: string;
+  ahead?: number;
+  unmergedAhead?: number;
+  landed?: boolean;
+  baseRef?: string;
+}
+
+export function listRecoveryBranches(input: { repoRoot?: string; baseRef?: string; baseSha?: string; now?: number }): { repoRoot?: string; branches: WorkspaceRecoveryBranch[]; error?: string } {
+  if (!input.repoRoot) return { branches: [], error: "repoRoot required" };
+  const repoRoot = resolve(input.repoRoot);
+  if (!existsSync(repoRoot)) return { repoRoot, branches: [], error: `repoRoot does not exist: ${repoRoot}` };
+
+  const refs = git(["for-each-ref", "--format=%(refname:short)%00%(objectname)%00%(committerdate:unix)%00%(subject)", "refs/heads/agent"], repoRoot);
+  if (!refs.ok) return { repoRoot, branches: [], error: refs.stderr || "branch listing failed" };
+
+  const now = input.now ?? Date.now();
+  const branches = refs.stdout.split("\n").filter(Boolean).map((line): WorkspaceRecoveryBranch | null => {
+    const [branch, headSha, unix, ...subjectParts] = line.split("\0");
+    if (!branch?.startsWith("agent/")) return null;
+    const safety = recoveryBranchSafety(repoRoot, branch, input.baseRef, input.baseSha);
+    const at = Number(unix) * 1000;
+    const lastCommit = headSha
+      ? { sha: headSha, message: subjectParts.join("\0"), ...(Number.isFinite(at) ? { at } : {}) }
+      : undefined;
+    return {
+      repoRoot,
+      branch,
+      headSha,
+      ...(safety.baseRef ? { baseRef: safety.baseRef } : {}),
+      ...(input.baseSha ? { baseSha: input.baseSha } : {}),
+      ...(safety.ahead !== undefined ? { ahead: safety.ahead } : {}),
+      ...(safety.unmergedAhead !== undefined ? { unmergedAhead: safety.unmergedAhead } : {}),
+      ...(safety.landed !== undefined ? { landed: safety.landed } : {}),
+      ...(lastCommit ? { lastCommit } : {}),
+      ...(lastCommit?.at ? { ageMs: Math.max(0, now - lastCommit.at) } : {}),
+      safeToDelete: safety.safe,
+      ...(safety.reason ? { preserveReason: safety.reason } : {}),
+    };
+  }).filter((branch): branch is WorkspaceRecoveryBranch => Boolean(branch));
+
+  branches.sort((a, b) => (b.ageMs ?? 0) - (a.ageMs ?? 0) || a.branch.localeCompare(b.branch));
+  return { repoRoot, branches };
+}
+
+export function recoveryBranchesResponse(url: URL, baseDir: string): Response {
+  try {
+    return json(listRecoveryBranches({
+      repoRoot: resolveRequestedPath(url.searchParams.get("repoRoot") || undefined, baseDir),
+      baseRef: url.searchParams.get("baseRef") || undefined,
+      baseSha: url.searchParams.get("baseSha") || undefined,
+    }));
+  } catch (e) {
+    return json({ error: (e as Error).message }, 400);
+  }
+}
+
+export function discardRecoveryBranch(input: { repoRoot?: string; branch?: string; baseRef?: string; baseSha?: string; force?: boolean }): WorkspaceRecoveryBranchDiscardResult {
+  if (!input.repoRoot) throw new Error("repoRoot required");
+  if (!input.branch) throw new Error("branch required");
+  if (!input.branch.startsWith("agent/")) throw new Error("only agent/* branches can be discarded through recovery cleanup");
+  const repoRoot = resolve(input.repoRoot);
+  const safety = recoveryBranchSafety(repoRoot, input.branch, input.baseRef, input.baseSha);
+  if (!safety.safe && input.force !== true) {
+    throw new Error(`branch is not safe to delete: ${safety.reason ?? "land-state unavailable"}`);
+  }
+  const head = git(["rev-parse", "--verify", "--quiet", `${input.branch}^{commit}`], repoRoot);
+  const deleted = git(["branch", "-D", input.branch], repoRoot);
+  if (!deleted.ok) throw new Error(deleted.stderr || "branch delete failed");
+  return {
+    repoRoot,
+    branch: input.branch,
+    branchDeleted: true,
+    ...(input.force === true ? { forced: true } : {}),
+    ...(safety.reason ? { preserveReason: safety.reason } : {}),
+    ...(head.stdout ? { headSha: head.stdout } : {}),
+  };
+}
+
+function recoveryBranchSafety(repoRoot: string, branch: string, baseRef?: string, baseSha?: string): BranchSafety {
+  const branchRef = resolveBranchRef(repoRoot, branch);
+  if (!branchRef) return { safe: true, reason: "branch ref already gone" };
+  const base = resolveRecoveryBase(repoRoot, baseRef, baseSha);
+  if (!base) return { safe: false, reason: "base ref unavailable" };
+
+  const gitState = populateMergeState(repoRoot, branchRef, { dirty: false, dirtyCount: 0, branch }, base, baseSha);
+  const ahead = gitState.ahead;
+  const unmergedAhead = gitState.unmergedAhead;
+  if (gitState.error) return { safe: false, reason: gitState.error, baseRef: gitState.baseRef ?? base };
+  if (!gitState.baseRef) return { safe: false, reason: "base ref unavailable", baseRef: base };
+  const effectiveAhead = gitState.landed ? 0 : (unmergedAhead ?? ahead);
+  if (effectiveAhead === undefined) return { safe: false, reason: "ahead count unavailable", baseRef: gitState.baseRef };
+  if (effectiveAhead === 0) return { safe: true, ahead, unmergedAhead, landed: gitState.landed, baseRef: gitState.baseRef };
+  return {
+    safe: false,
+    reason: `${effectiveAhead} unlanded commit(s)`,
+    ahead,
+    unmergedAhead,
+    landed: gitState.landed,
+    baseRef: gitState.baseRef,
+  };
+}
+
+function resolveRecoveryBase(repoRoot: string, baseRef?: string, baseSha?: string): string | undefined {
+  for (const candidate of [baseRef, baseSha, "main", "master"]) {
+    if (candidate && git(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], repoRoot).ok) return candidate;
+  }
+  return undefined;
+}
+
+function resolveBranchRef(repoRoot: string, branch: string): string | undefined {
+  for (const candidate of [branch, `refs/heads/${branch}`]) {
+    if (git(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], repoRoot).ok) return candidate;
+  }
+  return undefined;
+}

package/src/workspace-probe/request.ts

@@ -0,0 +1,22 @@
+import { statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export function resolveRequestedPath(requestedPath: string | undefined, baseDir: string): string {
+  const base = resolve(baseDir);
+  const target = resolve(requestedPath || base);
+  const rel = relative(base, target);
+  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 target;
+}
+
+export function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
+  });
+}