agent-relay-orchestrator 0.10.20 → 0.10.21

package/package.json

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

package/src/api.ts

@@ -8,7 +8,7 @@ import type { ProviderProbeCache } from "./provider-probe";
 import { captureSession, captureTerminal, createTerminalGuest, listSessions, sendTerminalInput, resizeTerminal, stopTerminalGuest } from "./spawn";
 import type { TerminalSnapshot } from "./spawn";
 import { VERSION, runtimeMetadata } from "./version";
-import { probeWorkspace } from "./workspace-probe";
+import { previewWorkspaceMerge, probeWorkspace, workspaceDiff, workspaceGitState } from "./workspace-probe";
 
 interface DirectoryEntry {
   name: string;
@@ -373,6 +373,51 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
         }
       }
 
+      if (req.method === "GET" && url.pathname === "/api/workspace/state") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(workspaceGitState({
+            worktreePath: target,
+            baseRef: url.searchParams.get("baseRef") || undefined,
+            baseSha: url.searchParams.get("baseSha") || undefined,
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      if (req.method === "GET" && url.pathname === "/api/workspace/diff") {
+        if (!authorized(req, config)) return error("unauthorized", 401);
+        try {
+          const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
+          return json(workspaceDiff({
+            worktreePath: target,
+            baseRef: url.searchParams.get("baseRef") || undefined,
+            baseSha: url.searchParams.get("baseSha") || undefined,
+            includePatch: url.searchParams.get("patch") !== "0",
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
+      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,
+          }));
+        } catch (e) {
+          return error((e as Error).message);
+        }
+      }
+
       if (req.method === "GET" && url.pathname === "/api/providers") {
         return (async () => {
           const snapshot = await probeCache.getSnapshot(url.searchParams.get("refresh") === "1");

package/src/control.ts

@@ -1,7 +1,8 @@
 import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
+import { handleSelfUpgrade } from "./self-upgrade";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace } from "./workspace-probe";
+import { cleanupWorkspace, mergeWorkspace, reconcileWorkspace } from "./workspace-probe";
 
 interface ControlHandler {
   handleCommand(command: RelayCommand): Promise<boolean>;
@@ -74,8 +75,39 @@ export function createControlHandler(
           id: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
           worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : undefined,
+          branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
+          deleteBranch: command.params.deleteBranch !== false,
         });
         await relay.updateCommand(command.id, "succeeded", result);
+      } else if (command.type === "workspace.reconcile") {
+        const result = reconcileWorkspace({
+          id: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
+          repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
+          worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : 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,
+        });
+        await relay.updateCommand(command.id, "succeeded", result);
+      } else if (command.type === "workspace.merge") {
+        const result = mergeWorkspace({
+          id: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
+          repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
+          worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : 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,
+          strategy: command.params.strategy === "pr" || command.params.strategy === "rebase-ff" || command.params.strategy === "auto" ? command.params.strategy : undefined,
+          deleteBranch: command.params.deleteBranch !== false,
+          prTitle: typeof command.params.prTitle === "string" ? command.params.prTitle : undefined,
+          prBody: typeof command.params.prBody === "string" ? command.params.prBody : undefined,
+        });
+        await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
+      } else if (command.type === "orchestrator.upgrade") {
+        // Install + restart ourselves. Intentionally NOT marked "succeeded": the
+        // relay settles it by reconciling the version we report after we restart,
+        // since the success ack can't survive our own process teardown.
+        await handleSelfUpgrade(command, config, relay);
       } else {
         throw new Error(`unsupported orchestrator command: ${command.type}`);
       }

package/src/relay.ts

@@ -1,5 +1,6 @@
 import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
+import { detectSelfSupervision } from "./self-supervision";
 import { GIT_SHA, ORCHESTRATOR_PROTOCOL_VERSION, VERSION, runtimeMetadata } from "./version";
 import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
 
@@ -99,6 +100,7 @@ export function buildRegistrationMeta(
   now = Date.now,
   pid = process.pid,
 ): Record<string, unknown> {
+  const supervision = detectSelfSupervision();
   return {
     ...runtime,
     pid,
@@ -107,6 +109,9 @@ export function buildRegistrationMeta(
     version: VERSION,
     protocolVersion: ORCHESTRATOR_PROTOCOL_VERSION,
     gitSha: GIT_SHA,
+    supervisor: supervision.supervisor,
+    ...(supervision.selfUnit ? { selfUnit: supervision.selfUnit } : {}),
+    ...(supervision.runtimePrefix ? { runtimePrefix: supervision.runtimePrefix } : {}),
   };
 }
 

package/src/self-supervision.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export interface SelfSupervision {
+  supervisor: "process" | "systemd" | "unknown";
+  selfUnit?: string;
+  runtimePrefix?: string;
+}
+
+let cached: SelfSupervision | undefined;
+
+/**
+ * Detect how this orchestrator process is supervised so the relay can target a
+ * remote self-upgrade at the correct systemd unit and install prefix. Result is
+ * stable for the process lifetime, so it is computed once and cached.
+ */
+export function detectSelfSupervision(moduleUrl: string = import.meta.url): SelfSupervision {
+  if (cached) return cached;
+  cached = { supervisor: detectSupervisorRaw(), runtimePrefix: detectRuntimePrefix(moduleUrl) };
+  const unit = detectSystemdUnit();
+  if (unit) {
+    cached.supervisor = "systemd";
+    cached.selfUnit = unit;
+  }
+  return cached;
+}
+
+/** Reset the cache. Test-only. */
+export function resetSelfSupervisionCache(): void {
+  cached = undefined;
+}
+
+function detectSupervisorRaw(): SelfSupervision["supervisor"] {
+  // /proc only exists on Linux; on macOS (launchd) we can't introspect cheaply.
+  try {
+    readFileSync("/proc/self/cgroup", "utf8");
+    return "process";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Parse the systemd unit owning this process from /proc/self/cgroup. A
+ * --user service cgroup looks like:
+ *   0::/user.slice/user-1000.slice/user@1000.service/app.slice/agent-relay-orchestrator.service
+ * We want the LAST `*.service` segment that isn't the user manager itself.
+ */
+export function parseSystemdUnitFromCgroup(cgroup: string): string | undefined {
+  const services = cgroup
+    .split("\n")
+    .flatMap((line) => line.split("/"))
+    .filter((seg) => seg.endsWith(".service"))
+    .filter((seg) => !/^user@\d+\.service$/.test(seg) && seg !== "init.scope");
+  const last = services.at(-1);
+  return last && last.length > ".service".length ? last : undefined;
+}
+
+function detectSystemdUnit(): string | undefined {
+  try {
+    return parseSystemdUnitFromCgroup(readFileSync("/proc/self/cgroup", "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The install prefix is the directory above `node_modules` when the orchestrator
+ * runs from an installed package (e.g. ~/.agent-relay/runtime). Undefined when
+ * running from a source/workspace checkout.
+ */
+export function detectRuntimePrefix(moduleUrl: string): string | undefined {
+  let path: string;
+  try {
+    path = fileURLToPath(moduleUrl);
+  } catch {
+    return undefined;
+  }
+  const marker = "/node_modules/";
+  const idx = path.indexOf(marker);
+  return idx >= 0 ? path.slice(0, idx) : undefined;
+}

package/src/self-upgrade.ts

@@ -0,0 +1,143 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { OrchestratorConfig } from "./config";
+import type { RelayClient, RelayCommand } from "./relay";
+import { detectSelfSupervision } from "./self-supervision";
+
+const VALID_PROVIDERS = new Set(["auto", "all", "codex", "claude", "orchestrator"]);
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+export interface SelfUpgradeRunner {
+  run(cmd: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }>;
+  commandExists(name: string): boolean;
+}
+
+const defaultRunner: SelfUpgradeRunner = {
+  async run(cmd) {
+    const proc = Bun.spawn({ cmd, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const exitCode = await proc.exited;
+    return { exitCode, stdout, stderr };
+  },
+  commandExists(name) {
+    try {
+      return Bun.spawnSync({ cmd: ["which", name], stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+    } catch {
+      return false;
+    }
+  },
+};
+
+export interface SelfUpgradePlan {
+  targetVersion: string;
+  providers: string[];
+  unit: string;
+  runtimePrefix?: string;
+  binary: string;
+  installCmd: string[];
+  restartCmd: string[];
+  /** restart runs decoupled from this process's cgroup (transient unit) */
+  restartDetached: boolean;
+}
+
+/**
+ * Build the upgrade plan from a command's params + detected self-supervision.
+ * Throws (with an operator-facing message) when the request is invalid or the
+ * host can't self-restart — caught by the caller and reported as a failed command.
+ */
+export function planSelfUpgrade(
+  params: Record<string, unknown>,
+  supervision = detectSelfSupervision(),
+  runner: SelfUpgradeRunner = defaultRunner,
+): SelfUpgradePlan {
+  const targetVersion = typeof params.targetVersion === "string" ? params.targetVersion.trim() : "";
+  if (!SEMVER_RE.test(targetVersion)) {
+    throw new Error(`invalid targetVersion "${targetVersion}" (expected x.y.z)`);
+  }
+  const providers = normalizeProviders(params.providers);
+
+  if (supervision.supervisor !== "systemd" || !supervision.selfUnit) {
+    throw new Error("orchestrator is not under systemd --user; remote self-upgrade requires a systemd unit (P1)");
+  }
+  const unit = supervision.selfUnit;
+  const binary = resolveBinary(supervision.runtimePrefix);
+
+  const installCmd = [
+    binary, "upgrade",
+    "--version", targetVersion,
+    "--providers", providers.join(","),
+    "--no-restart",
+    "--yes",
+  ];
+  if (supervision.runtimePrefix) installCmd.push("--runtime-prefix", supervision.runtimePrefix);
+
+  // Decouple the restart from this orchestrator's own cgroup: restarting our unit
+  // SIGTERMs us, and a child in our cgroup would be killed mid-restart. systemd-run
+  // schedules it as an independent transient unit that survives our teardown.
+  const restartDetached = runner.commandExists("systemd-run");
+  const restartCmd = restartDetached
+    ? ["systemd-run", "--user", "--collect", "--description", "agent-relay orchestrator self-upgrade restart", "systemctl", "--user", "restart", unit]
+    : ["setsid", "systemctl", "--user", "restart", unit];
+
+  return { targetVersion, providers, unit, runtimePrefix: supervision.runtimePrefix, binary, installCmd, restartCmd, restartDetached };
+}
+
+/**
+ * Handle an orchestrator.upgrade command: validate, install the target version
+ * WITHOUT restart (so install failures are caught while we're still alive), then
+ * launch a decoupled restart. The command is intentionally left "running" — the
+ * relay settles it by reconciling the version we report after we come back up.
+ */
+export async function handleSelfUpgrade(
+  command: RelayCommand,
+  _config: OrchestratorConfig,
+  relay: RelayClient,
+  runner: SelfUpgradeRunner = defaultRunner,
+): Promise<void> {
+  const plan = planSelfUpgrade(command.params, detectSelfSupervision(), runner);
+  await relay.updateCommand(command.id, "running", {
+    phase: "installing",
+    targetVersion: plan.targetVersion,
+    providers: plan.providers,
+    unit: plan.unit,
+  });
+
+  const install = await runner.run(plan.installCmd);
+  if (install.exitCode !== 0) {
+    throw new Error(`install failed (exit ${install.exitCode}): ${(install.stderr || install.stdout).trim().slice(-500)}`);
+  }
+
+  await relay.updateCommand(command.id, "running", {
+    phase: "restart-pending",
+    targetVersion: plan.targetVersion,
+    unit: plan.unit,
+    restartDetached: plan.restartDetached,
+  });
+
+  // Fire the restart and return. We do not await its effect — it tears us down.
+  const restart = await runner.run(plan.restartCmd);
+  if (restart.exitCode !== 0) {
+    throw new Error(`restart failed (exit ${restart.exitCode}): ${(restart.stderr || restart.stdout).trim().slice(-500)}`);
+  }
+  console.error(`[orchestrator] self-upgrade to ${plan.targetVersion} installed; restart dispatched for ${plan.unit}`);
+}
+
+function normalizeProviders(value: unknown): string[] {
+  const list = Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string").map((v) => v.trim()).filter(Boolean)
+    : [];
+  const filtered = list.filter((p) => VALID_PROVIDERS.has(p));
+  const providers = filtered.length ? filtered : ["orchestrator"];
+  return [...new Set(providers)];
+}
+
+function resolveBinary(runtimePrefix?: string): string {
+  if (runtimePrefix) {
+    const local = join(runtimePrefix, "node_modules", ".bin", "agent-relay");
+    if (existsSync(local)) return local;
+  }
+  return "agent-relay";
+}

package/src/workspace-probe.ts

@@ -1,8 +1,10 @@
-import { mkdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree } from "agent-relay-sdk";
+import type { WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus } from "agent-relay-sdk";
+
+const MAX_DIFF_PATCH_BYTES = 200_000;
 
 interface WorkspaceResolutionInput {
   cwd: string;
@@ -145,13 +147,336 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
   };
 }
 
-export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string }): { workspaceId?: string; removed: boolean; worktreePath?: string } {
+export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; deleteBranch?: boolean }): { workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean } {
   if (!workspace.worktreePath) throw new Error("worktreePath required");
   const path = resolve(workspace.worktreePath);
   const repo = workspace.repoRoot ? resolve(workspace.repoRoot) : path;
   const result = git(["worktree", "remove", "--force", path], repo);
   if (!result.ok) throw new Error(result.stderr || `failed to remove workspace ${path}`);
-  return { workspaceId: workspace.id, removed: true, worktreePath: path };
+  // Once the worktree is gone the agent/... branch is litter — delete it so
+  // branches don't accumulate. Best-effort: don't fail cleanup if it can't
+  // (e.g. branch already gone, or checked out elsewhere).
+  let branchDeleted = false;
+  if (workspace.branch && workspace.deleteBranch !== false) {
+    branchDeleted = git(["branch", "-D", workspace.branch], repo).ok;
+  }
+  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted };
+}
+
+/**
+ * Read-only git interrogation of a worktree: how much work it holds (commits
+ * ahead/behind base, dirty files, last commit). Computed on the host because
+ * that is where git and the worktree live. Never throws — failures land in the
+ * returned `error`/`missing` fields so callers can degrade gracefully.
+ */
+export function workspaceGitState(input: { worktreePath?: string; baseRef?: string; baseSha?: string }): WorkspaceGitState {
+  if (!input.worktreePath) return { error: "worktreePath required" };
+  const path = resolve(input.worktreePath);
+  if (!existsSync(path)) return { missing: true };
+
+  const status = git(["status", "--porcelain"], path);
+  if (!status.ok) return { error: status.stderr || "git status failed" };
+  const dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+
+  const state: WorkspaceGitState = { dirty: dirtyCount > 0, dirtyCount };
+
+  const log = git(["log", "-1", "--format=%H%x1f%ct%x1f%s"], path);
+  if (log.ok && log.stdout) {
+    const [sha, ct, ...rest] = log.stdout.split("\x1f");
+    if (sha) {
+      const at = Number(ct) * 1000;
+      state.lastCommit = { sha, message: rest.join("\x1f"), ...(Number.isFinite(at) ? { at } : {}) };
+    }
+  }
+
+  // Resolve a base to diff against: prefer the named branch (gives real behind
+  // counts), fall back to the fork SHA (behind is then always 0, ahead is the
+  // agent's new commits — still the signal we care about for cleanup).
+  const base = resolveBaseRef(path, input.baseRef, input.baseSha);
+  if (base) {
+    state.baseRef = base;
+    const counts = git(["rev-list", "--left-right", "--count", `${base}...HEAD`], path);
+    if (counts.ok && counts.stdout) {
+      const [behind, ahead] = counts.stdout.split(/\s+/).map((n) => Number(n));
+      if (Number.isFinite(behind)) state.behind = behind;
+      if (Number.isFinite(ahead)) state.ahead = ahead;
+    }
+  }
+
+  return state;
+}
+
+function resolveBaseRef(worktreePath: string, baseRef?: string, baseSha?: string): string | undefined {
+  for (const candidate of [baseRef, baseSha]) {
+    if (candidate && git(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], worktreePath).ok) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Exit-time decision for an orphaned worktree (owner agent disappeared). Probe
+ * the worktree and either remove it (genuinely empty — clean tree, no commits
+ * ahead of base) or leave it intact and report a status the relay can flag for
+ * review. Never destroys work on uncertainty: any error or unknown ahead-count
+ * results in a flag, not a delete.
+ */
+export function reconcileWorkspace(workspace: { id?: string; repoRoot?: string; worktreePath?: string; branch?: string; baseRef?: string; baseSha?: string }): {
+  workspaceId?: string;
+  removed: boolean;
+  status: WorkspaceStatus;
+  gitState: WorkspaceGitState;
+} {
+  const gitState = workspaceGitState(workspace);
+  if (gitState.missing) {
+    return { workspaceId: workspace.id, removed: false, status: "cleaned", gitState };
+  }
+  const empty = gitState.error === undefined && gitState.dirtyCount === 0 && gitState.ahead === 0;
+  if (empty) {
+    cleanupWorkspace({ id: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, branch: workspace.branch });
+    return { workspaceId: workspace.id, removed: true, status: "cleaned", gitState };
+  }
+  return { workspaceId: workspace.id, removed: false, status: "review_requested", gitState };
+}
+
+/**
+ * Diff a worktree's committed work against its base (base...HEAD): per-file
+ * line counts plus a size-capped unified patch, so the dashboard can show what
+ * an agent produced without an SSH session. Read-only; degrades into fields.
+ */
+export function workspaceDiff(input: { worktreePath?: string; baseRef?: string; baseSha?: string; includePatch?: boolean }): WorkspaceDiff {
+  if (!input.worktreePath) return { files: [], error: "worktreePath required" };
+  const path = resolve(input.worktreePath);
+  if (!existsSync(path)) return { files: [], missing: true };
+
+  const base = resolveBaseRef(path, input.baseRef, input.baseSha);
+  const range = base ? `${base}...HEAD` : "HEAD";
+  const result: WorkspaceDiff = { files: [], baseRef: base };
+
+  const status = git(["status", "--porcelain"], path);
+  if (status.ok) result.dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+
+  if (base) {
+    const counts = git(["rev-list", "--count", `${base}..HEAD`], path);
+    if (counts.ok && counts.stdout) {
+      const ahead = Number(counts.stdout);
+      if (Number.isFinite(ahead)) result.ahead = ahead;
+    }
+  }
+
+  const numstat = git(["diff", "--numstat", range], path);
+  if (!numstat.ok) return { ...result, error: numstat.stderr || "git diff failed" };
+  result.files = parseNumstat(numstat.stdout);
+
+  if (input.includePatch !== false) {
+    const patch = git(["diff", range], path);
+    if (patch.ok && patch.stdout) {
+      if (patch.stdout.length > MAX_DIFF_PATCH_BYTES) {
+        result.patch = patch.stdout.slice(0, MAX_DIFF_PATCH_BYTES);
+        result.truncated = true;
+      } else {
+        result.patch = patch.stdout;
+      }
+    }
+  }
+  return result;
+}
+
+function parseNumstat(output: string): WorkspaceDiffFile[] {
+  if (!output) return [];
+  return output.split("\n").filter(Boolean).map((line) => {
+    const [add, del, ...rest] = line.split("\t");
+    const path = rest.join("\t");
+    const binary = add === "-" && del === "-";
+    return {
+      path,
+      binary,
+      ...(binary ? {} : { additions: Number(add) || 0, deletions: Number(del) || 0 }),
+    };
+  }).filter((file) => file.path);
+}
+
+interface WorkspaceMergeInput {
+  id?: string;
+  repoRoot?: string;
+  worktreePath?: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+  strategy?: "pr" | "rebase-ff" | "auto";
+  deleteBranch?: boolean;
+  prTitle?: string;
+  prBody?: string;
+}
+
+function hasOriginRemote(cwd: string): boolean {
+  return git(["remote", "get-url", "origin"], cwd).ok;
+}
+
+function ghAvailable(): boolean {
+  return Boolean(Bun.which("gh"));
+}
+
+/**
+ * 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
+ * = conflicts. Anything else is treated as "unknown" (undefined).
+ */
+function predictConflict(worktreePath: string, base: string): boolean | undefined {
+  const result = git(["merge-tree", "--write-tree", "--name-only", base, "HEAD"], worktreePath);
+  if (result.ok) return false;
+  // git exits 1 specifically for merge conflicts; other failures are unknown.
+  return /CONFLICT|conflict/.test(result.stdout + result.stderr) || result.stdout.length > 0 ? true : undefined;
+}
+
+/** Branch name a base ref points at (only meaningful for refs/heads). */
+function baseBranchName(worktreePath: string, baseRef?: string): string | undefined {
+  if (!baseRef) return undefined;
+  const ref = baseRef.startsWith("refs/heads/") ? baseRef.slice("refs/heads/".length) : baseRef;
+  return git(["show-ref", "--verify", "--quiet", `refs/heads/${ref}`], worktreePath).ok ? ref : undefined;
+}
+
+/** Locate the worktree (if any) that currently has `branch` checked out. */
+function worktreeForBranch(repoRoot: string, branch: string): { path: string; dirty: boolean } | undefined {
+  const list = git(["worktree", "list", "--porcelain"], repoRoot);
+  if (!list.ok) return undefined;
+  const match = parseWorktrees(list.stdout).find((worktree) => worktree.branch === branch);
+  if (!match) return undefined;
+  const status = git(["status", "--porcelain"], match.path);
+  return { path: match.path, dirty: status.ok ? status.stdout.length > 0 : true };
+}
+
+/**
+ * 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
+ * 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 {
+  const gitState = workspaceGitState(input);
+  const remote = input.worktreePath ? hasOriginRemote(resolve(input.worktreePath)) : false;
+  const gh = ghAvailable();
+  const baseBranch = input.worktreePath ? baseBranchName(resolve(input.worktreePath), input.baseRef) : undefined;
+  // PR needs a remote, gh, and a real base branch to target; otherwise land locally.
+  const strategy: "pr" | "rebase-ff" = input.strategy === "pr" || input.strategy === "rebase-ff"
+    ? input.strategy
+    : remote && gh && baseBranch ? "pr" : "rebase-ff";
+  const base: WorkspaceMergePreview = { strategy, hasRemote: remote, ghAvailable: gh, baseRef: baseBranch ?? gitState.baseRef };
+
+  if (gitState.missing) return { ...base, missing: true, reason: "worktree no longer exists" };
+  if (gitState.error) return { ...base, error: gitState.error };
+  base.ahead = gitState.ahead;
+  base.behind = gitState.behind;
+  base.dirtyCount = gitState.dirtyCount;
+  if ((gitState.dirtyCount ?? 0) > 0) return { ...base, reason: "worktree has uncommitted changes" };
+  if ((gitState.ahead ?? 0) === 0) return { ...base, reason: "no commits to merge" };
+  if (gitState.baseRef && input.worktreePath) {
+    const conflict = predictConflict(resolve(input.worktreePath), gitState.baseRef);
+    base.conflict = conflict;
+    base.cleanFastForward = conflict === false && (gitState.behind ?? 0) === 0;
+  }
+  return base;
+}
+
+/**
+ * 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,
+ *    then remove the worktree and delete the branch. Lands work locally.
+ *  - pr: push the branch to origin and open a PR via gh. Leaves the worktree
+ *    and branch intact (the PR needs them).
+ * Refuses on a dirty worktree, predicted conflicts, or nothing to merge. Never
+ * destroys work on uncertainty.
+ */
+export function mergeWorkspace(input: WorkspaceMergeInput): WorkspaceMergeResult {
+  if (!input.worktreePath) return { strategy: "rebase-ff", merged: false, status: "review_requested", error: "worktreePath required", workspaceId: input.id };
+  const worktreePath = resolve(input.worktreePath);
+  const repoRoot = input.repoRoot ? resolve(input.repoRoot) : worktreePath;
+  const branch = input.branch ?? shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath).stdout || undefined);
+  const preview = previewWorkspaceMerge({ worktreePath, baseRef: input.baseRef, baseSha: input.baseSha, strategy: input.strategy });
+  const strategy = preview.strategy;
+  const head = (field: Partial<WorkspaceMergeResult>): WorkspaceMergeResult => ({ workspaceId: input.id, strategy, merged: false, status: "review_requested", branch, baseRef: preview.baseRef, ...field });
+
+  if (preview.missing) return head({ status: "cleaned", error: preview.reason });
+  if (preview.error) return head({ status: "review_requested", error: preview.error });
+  if (preview.reason) return head({ status: "review_requested", error: preview.reason });
+  if (preview.conflict) return head({ conflict: true, status: "conflict", error: "merge would conflict with base" });
+
+  if (strategy === "pr") return mergePr(input, worktreePath, branch, preview, head);
+  return mergeRebaseFf(input, worktreePath, repoRoot, branch, preview, head);
+}
+
+function mergePr(
+  input: WorkspaceMergeInput,
+  worktreePath: string,
+  branch: string | undefined,
+  preview: WorkspaceMergePreview,
+  head: (field: Partial<WorkspaceMergeResult>) => WorkspaceMergeResult,
+): WorkspaceMergeResult {
+  if (!branch) return head({ status: "review_requested", error: "cannot determine branch to push" });
+  const base = preview.baseRef;
+  const push = git(["push", "-u", "origin", branch], worktreePath);
+  if (!push.ok) return head({ status: "review_requested", error: push.stderr || "git push failed" });
+
+  const title = input.prTitle || git(["log", "-1", "--format=%s"], worktreePath).stdout || `Merge ${branch}`;
+  const body = input.prBody || `Automated PR for agent workspace branch \`${branch}\`.`;
+  const args = ["pr", "create", "--head", branch, "--title", title, "--body", body];
+  if (base) args.push("--base", base);
+  const proc = Bun.spawnSync(["gh", ...args], { cwd: worktreePath, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const stdout = proc.stdout.toString().trim();
+  if (proc.exitCode !== 0) {
+    return head({ status: "review_requested", error: proc.stderr.toString().trim() || "gh pr create failed" });
+  }
+  const prUrl = stdout.split("\n").map((line) => line.trim()).find((line) => /^https?:\/\//.test(line));
+  // PR opened: work is on its way out but not landed. Keep the worktree/branch
+  // alive for the PR; record the plan with the URL.
+  return head({ status: "merge_planned", prUrl, error: undefined });
+}
+
+function mergeRebaseFf(
+  input: WorkspaceMergeInput,
+  worktreePath: string,
+  repoRoot: string,
+  branch: string | undefined,
+  preview: WorkspaceMergePreview,
+  head: (field: Partial<WorkspaceMergeResult>) => WorkspaceMergeResult,
+): WorkspaceMergeResult {
+  const base = preview.baseRef;
+  if (!base) return head({ status: "review_requested", error: "no base branch to merge into" });
+  if (!branch) return head({ status: "review_requested", error: "cannot determine agent branch" });
+
+  // Rebase the agent branch onto base so base can fast-forward to it.
+  if ((preview.behind ?? 0) > 0) {
+    const rebase = git(["rebase", base], worktreePath);
+    if (!rebase.ok) {
+      git(["rebase", "--abort"], worktreePath);
+      return head({ conflict: true, status: "conflict", error: rebase.stderr || "rebase onto base failed" });
+    }
+  }
+  const headSha = git(["rev-parse", "HEAD"], worktreePath).stdout;
+
+  // 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
+  // just move the ref. Refuse if the base worktree has uncommitted changes.
+  const baseWorktree = worktreeForBranch(repoRoot, base);
+  if (baseWorktree) {
+    if (baseWorktree.dirty) return head({ status: "review_requested", error: `base branch '${base}' has uncommitted changes in ${baseWorktree.path}` });
+    const ff = git(["merge", "--ff-only", branch], baseWorktree.path);
+    if (!ff.ok) return head({ status: "review_requested", error: ff.stderr || "fast-forward into base failed" });
+  } else {
+    const update = git(["update-ref", `refs/heads/${base}`, headSha], repoRoot);
+    if (!update.ok) return head({ status: "review_requested", error: update.stderr || "failed to advance base ref" });
+  }
+
+  // Work is landed. Tear down the worktree and delete the agent branch.
+  const deleteBranch = input.deleteBranch !== false;
+  let worktreeRemoved = false;
+  let branchDeleted = false;
+  if (deleteBranch) {
+    const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
+    worktreeRemoved = removed.ok;
+    if (worktreeRemoved) branchDeleted = git(["branch", "-D", branch], repoRoot).ok;
+  }
+  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, error: undefined });
 }
 
 async function availableBranch(repoRoot: string, base: string): Promise<string> {