agent-relay-orchestrator 0.118.3 → 0.118.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.118.3",
+  "version": "0.118.5",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {

package/src/control.ts

@@ -6,6 +6,7 @@ import { handleSelfUpgrade } from "./self-upgrade";
 import { readLocalProviderConfigs } from "./provider-config-migration";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
 import { cleanupWorkspace, discardRecoveryBranch, idleRefreshWorktree, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
+import { withMergePhaseTimeout } from "./workspace-probe/merge-timeouts";
 import { armWorkspacePrAutoMerge, mergeWorkspacePr, refreshWorkspacePrBranch } from "./workspace-pr";
 import type { WorkspaceMergeResult } from "agent-relay-sdk";
 
@@ -118,26 +119,42 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, "succeeded", result);
       } else if (command.type === "workspace.merge") {
-        const result = await 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,
-          push: command.params.push !== false,
-          prTitle: typeof command.params.prTitle === "string" ? command.params.prTitle : undefined,
-          prBody: typeof command.params.prBody === "string" ? command.params.prBody : undefined,
-          autoMerge: command.params.autoMerge === "on-green" || command.params.autoMerge === "on-approval" || command.params.autoMerge === "manual" ? command.params.autoMerge : undefined,
-          prLanded: isRecord(command.params.prLanded)
-            ? {
-                sha: typeof command.params.prLanded.sha === "string" ? command.params.prLanded.sha : undefined,
-                subject: typeof command.params.prLanded.subject === "string" ? command.params.prLanded.subject : undefined,
-              }
-            : undefined,
-        });
+        let result: WorkspaceMergeResult;
+        try {
+          result = await withMergePhaseTimeout("total", () => 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,
+            push: command.params.push !== false,
+            prTitle: typeof command.params.prTitle === "string" ? command.params.prTitle : undefined,
+            prBody: typeof command.params.prBody === "string" ? command.params.prBody : undefined,
+            autoMerge: command.params.autoMerge === "on-green" || command.params.autoMerge === "on-approval" || command.params.autoMerge === "manual" ? command.params.autoMerge : undefined,
+            prLanded: isRecord(command.params.prLanded)
+              ? {
+                  sha: typeof command.params.prLanded.sha === "string" ? command.params.prLanded.sha : undefined,
+                  subject: typeof command.params.prLanded.subject === "string" ? command.params.prLanded.subject : undefined,
+                }
+              : undefined,
+          }));
+        } catch (err) {
+          const branch = typeof command.params.branch === "string" ? command.params.branch : undefined;
+          const baseRef = typeof command.params.baseRef === "string" ? command.params.baseRef : undefined;
+          result = {
+            workspaceId: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
+            strategy: command.params.strategy === "pr" ? "pr" : "rebase-ff",
+            merged: false,
+            status: "review_requested",
+            ...(branch ? { branch } : {}),
+            ...(baseRef ? { baseRef } : {}),
+            error: errMessage(err),
+          };
+          console.error(`[orchestrator] workspace.merge failed before completion: ${result.error}`);
+        }
         // #638 — settle `failed` (carrying the error) for a no-op merge instead of
         // `succeeded`; see mergeCommandStatus.
         await relay.updateCommand(command.id, mergeCommandStatus(result), result as unknown as Record<string, unknown>, result.error);

package/src/git.ts

@@ -3,21 +3,23 @@
 // `git -C` invocation lives in one place.
 
 import { execProcess } from "./process";
+import type { ExecResult } from "./process";
 
-interface GitResult {
-  ok: boolean;
-  stdout: string;
-  stderr: string;
+type GitResult = Pick<ExecResult, "ok" | "stdout" | "stderr" | "exitCode" | "timedOut">;
+
+interface GitOptions {
+  timeoutMs?: number;
+  timeoutLabel?: string;
 }
 
 /** Run `git -C cwd <args>` and capture trimmed stdout/stderr; never throws. */
-export async function git(args: string[], cwd: string): Promise<GitResult> {
-  return await execProcess(["git", "-C", cwd, ...args]);
+export async function git(args: string[], cwd: string, options: GitOptions = {}): Promise<GitResult> {
+  return await execProcess(["git", "-C", cwd, ...args], options);
 }
 
 /** Run `git -C cwd <args>` and preserve stdout exactly for path-safe parsers. */
-export async function gitRaw(args: string[], cwd: string): Promise<GitResult> {
-  return await execProcess(["git", "-C", cwd, ...args], { trimStdout: false });
+export async function gitRaw(args: string[], cwd: string, options: GitOptions = {}): Promise<GitResult> {
+  return await execProcess(["git", "-C", cwd, ...args], { ...options, trimStdout: false });
 }
 
 /** Like {@link git} but throws on a non-zero exit, returning stdout on success. */

package/src/process.ts

@@ -3,6 +3,7 @@ export interface ExecResult {
   exitCode: number | null;
   stdout: string;
   stderr: string;
+  timedOut?: boolean;
 }
 
 interface ExecOptions {
@@ -12,11 +13,56 @@ interface ExecOptions {
   stderr?: "pipe" | "ignore";
   trimStdout?: boolean;
   trimStderr?: boolean;
+  timeoutMs?: number;
+  timeoutLabel?: string;
+  streamDrainGraceMs?: number;
 }
 
-async function readStream(stream: ReadableStream<Uint8Array> | undefined): Promise<string> {
-  if (!stream) return "";
-  return await new Response(stream).text();
+const DEFAULT_STREAM_DRAIN_GRACE_MS = 1_000;
+
+interface StreamCapture {
+  done: Promise<void>;
+  text(): string;
+  cancel(): void;
+}
+
+function captureStream(stream: ReadableStream<Uint8Array> | undefined): StreamCapture {
+  if (!stream) return { done: Promise.resolve(), text: () => "", cancel: () => {} };
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let output = "";
+  let canceled = false;
+  const done = (async () => {
+    try {
+      while (!canceled) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        output += decoder.decode(chunk.value, { stream: true });
+      }
+      output += decoder.decode();
+    } catch {
+      // Intentional cancellation on process timeout or a stuck post-exit pipe.
+    } finally {
+      try { reader.releaseLock(); } catch {}
+    }
+  })();
+  return {
+    done,
+    text: () => output,
+    cancel: () => {
+      canceled = true;
+      void reader.cancel().catch(() => {});
+    },
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function timeoutMessage(cmd: string[], options: ExecOptions): string {
+  const label = options.timeoutLabel ?? cmd.join(" ");
+  return `${label} timed out after ${options.timeoutMs}ms`;
 }
 
 export async function execProcess(cmd: string[], options: ExecOptions = {}): Promise<ExecResult> {
@@ -27,15 +73,50 @@ export async function execProcess(cmd: string[], options: ExecOptions = {}): Pro
     stdout: options.stdout ?? "pipe",
     stderr: options.stderr ?? "pipe",
   });
-  const [exitCode, stdout, stderr] = await Promise.all([
-    proc.exited,
-    options.stdout === "ignore" ? Promise.resolve("") : readStream(proc.stdout),
-    options.stderr === "ignore" ? Promise.resolve("") : readStream(proc.stderr),
-  ]);
+  const stdoutCapture = options.stdout === "ignore" ? captureStream(undefined) : captureStream(proc.stdout);
+  const stderrCapture = options.stderr === "ignore" ? captureStream(undefined) : captureStream(proc.stderr);
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let killTimeout: ReturnType<typeof setTimeout> | undefined;
+  let timeoutResolve: ((value: null) => void) | undefined;
+  const timeoutPromise = new Promise<null>((resolve) => { timeoutResolve = resolve; });
+  if (options.timeoutMs && options.timeoutMs > 0) {
+    timeout = setTimeout(() => {
+      timedOut = true;
+      try { proc.kill("SIGTERM"); } catch {}
+      killTimeout = setTimeout(() => {
+        try { proc.kill("SIGKILL"); } catch {}
+      }, 1_000);
+      killTimeout.unref?.();
+      timeoutResolve?.(null);
+    }, options.timeoutMs);
+    timeout.unref?.();
+  }
+
+  const exitCode = await (timeout ? Promise.race([proc.exited, timeoutPromise]) : proc.exited);
+  if (timeout) clearTimeout(timeout);
+  if (!timedOut && killTimeout) clearTimeout(killTimeout);
+  if (timedOut) {
+    stdoutCapture.cancel();
+    stderrCapture.cancel();
+  }
+
+  const drainGraceMs = options.streamDrainGraceMs ?? DEFAULT_STREAM_DRAIN_GRACE_MS;
+  await Promise.race([Promise.allSettled([stdoutCapture.done, stderrCapture.done]), sleep(drainGraceMs)]);
+  stdoutCapture.cancel();
+  stderrCapture.cancel();
+
+  const stdout = stdoutCapture.text();
+  let stderr = stderrCapture.text();
+  if (timedOut) {
+    const msg = timeoutMessage(cmd, options);
+    stderr = stderr ? `${stderr}\n${msg}` : msg;
+  }
   return {
-    ok: exitCode === 0,
+    ok: !timedOut && exitCode === 0,
     exitCode,
     stdout: options.trimStdout === false ? stdout : stdout.trim(),
     stderr: options.trimStderr === false ? stderr : stderr.trim(),
+    ...(timedOut ? { timedOut } : {}),
   };
 }

package/src/workspace-probe/merge-timeouts.ts

@@ -0,0 +1,45 @@
+export type MergePhase = "total" | "prep" | "preview" | "fetch" | "rebase" | "gates" | "synthesize" | "worktree-add" | "cleanup";
+
+const MERGE_PHASE_TIMEOUTS_MS: Record<MergePhase, number> = {
+  total: 10 * 60_000,
+  prep: 60_000,
+  preview: 30_000,
+  fetch: 60_000,
+  rebase: 60_000,
+  gates: 5 * 60_000,
+  synthesize: 60_000,
+  "worktree-add": 60_000,
+  cleanup: 30_000,
+};
+
+function positiveEnvMs(name: string): number | undefined {
+  const raw = process.env[name];
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function mergePhaseTimeoutMs(phase: MergePhase): number {
+  const key = `AGENT_RELAY_WORKSPACE_MERGE_${phase.toUpperCase().replace(/-/g, "_")}_TIMEOUT_MS`;
+  return positiveEnvMs(key)
+    ?? positiveEnvMs("AGENT_RELAY_WORKSPACE_MERGE_PHASE_TIMEOUT_MS")
+    ?? MERGE_PHASE_TIMEOUTS_MS[phase];
+}
+
+export async function withMergePhaseTimeout<T>(phase: MergePhase, run: () => Promise<T>): Promise<T> {
+  const timeoutMs = mergePhaseTimeoutMs(phase);
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const work = run();
+  work.catch(() => {});
+  try {
+    return await Promise.race([
+      work,
+      new Promise<T>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(`workspace merge phase "${phase}" timed out after ${timeoutMs}ms`)), timeoutMs);
+        timeout.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}

package/src/workspace-probe/merge.ts

@@ -1,34 +1,51 @@
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import type { BaseWorktreeSyncResult, WorkspaceMergePreview, WorkspaceMergeResult } from "agent-relay-sdk";
+import { errMessage, type BaseWorktreeSyncResult, type WorkspaceMergePreview, type WorkspaceMergeResult } from "agent-relay-sdk";
 import { git, gitRaw } from "../git";
 import { execProcess } from "../process";
 import { prMergedState } from "../workspace-pr";
 import { refreshWorkspaceDeps } from "./deps";
 import { type LandGatesResult, runLandGates } from "./land-gates-runner";
-import { populateMergeState, resolveBranchRef, syncBaseFromOrigin, upstreamRef, workspaceGitState } from "./git-state";
+import { populateMergeState, resolveBranchRef, syncBaseFromOrigin, workspaceGitState } from "./git-state";
+import { type MergePhase, mergePhaseTimeoutMs, withMergePhaseTimeout } from "./merge-timeouts";
 import { nextBranchName } from "./names";
 import { parseWorktrees, shortBranch } from "./parse";
 import { json, resolveRequestedPath } from "./request";
 import type { WorkspaceMergeInput } from "./types";
 import { workspacePushEnabled } from "../config";
 
+async function mergeGit(args: string[], cwd: string, phase: MergePhase, timeoutLabel?: string): ReturnType<typeof git> {
+  return git(args, cwd, {
+    timeoutMs: mergePhaseTimeoutMs(phase),
+    timeoutLabel: timeoutLabel ?? `workspace merge ${phase} git ${args.join(" ")}`,
+  });
+}
+
+async function mergeGitRaw(args: string[], cwd: string, phase: MergePhase, timeoutLabel?: string): ReturnType<typeof gitRaw> {
+  return gitRaw(args, cwd, {
+    timeoutMs: mergePhaseTimeoutMs(phase),
+    timeoutLabel: timeoutLabel ?? `workspace merge ${phase} git ${args.join(" ")}`,
+  });
+}
+
+function gitError(result: Awaited<ReturnType<typeof git>>, fallback: string): string {
+  return result.stderr || result.stdout || fallback;
+}
+
 /** Behind-count of HEAD relative to `base`, from inside `worktreePath`. */
-async function countBehind(worktreePath: string, base: string): Promise<number> {
-  const counts = await git(["rev-list", "--left-right", "--count", `${base}...HEAD`], worktreePath);
-  if (!counts.ok || !counts.stdout) return 0;
+async function countBehind(worktreePath: string, base: string): Promise<{ behind: number } | { error: string }> {
+  const counts = await mergeGit(["rev-list", "--left-right", "--count", `${base}...HEAD`], worktreePath, "rebase", "workspace merge count behind integration base");
+  if (!counts.ok || !counts.stdout) return { error: gitError(counts, "failed to count branch behind integration base") };
   const behind = Number(counts.stdout.split(/\s+/)[0]);
-  return Number.isFinite(behind) ? behind : 0;
+  return Number.isFinite(behind) ? { behind } : { error: "git rev-list produced an invalid behind count" };
 }
 
 async function hasOriginRemote(cwd: string): Promise<boolean> {
   return (await git(["remote", "get-url", "origin"], cwd)).ok;
 }
 
-function ghAvailable(): boolean {
-  return Boolean(Bun.which("gh"));
-}
+function ghAvailable(): boolean { return Boolean(Bun.which("gh")); }
 
 /**
  * Ground-truth merge state for `branch`, via gh.
@@ -60,11 +77,11 @@ async function baseBranchName(worktreePath: string, baseRef?: string): Promise<s
 
 /** Locate the worktree (if any) that currently has `branch` checked out. */
 async function worktreeForBranch(repoRoot: string, branch: string): Promise<{ path: string; dirty: boolean } | undefined> {
-  const list = await git(["worktree", "list", "--porcelain"], repoRoot);
+  const list = await mergeGit(["worktree", "list", "--porcelain"], repoRoot, "rebase", "workspace merge list worktrees");
   if (!list.ok) return undefined;
   const match = parseWorktrees(list.stdout).find((worktree) => worktree.branch === branch);
   if (!match) return undefined;
-  const status = await git(["status", "--porcelain"], match.path);
+  const status = await mergeGit(["status", "--porcelain"], match.path, "rebase", `workspace merge status ${branch} worktree`);
   return { path: match.path, dirty: status.ok ? status.stdout.length > 0 : true };
 }
 
@@ -73,7 +90,7 @@ function splitNul(stdout: string): string[] {
 }
 
 async function dirtyPathSet(worktreePath: string): Promise<Set<string>> {
-  const status = await gitRaw(["status", "--porcelain=v1", "-z", "--untracked-files=all"], worktreePath);
+  const status = await mergeGitRaw(["status", "--porcelain=v1", "-z", "--untracked-files=all"], worktreePath, "rebase", "workspace merge dirty path scan");
   if (!status.ok) return new Set<string>();
   const paths = new Set<string>();
   const entries = splitNul(status.stdout);
@@ -89,25 +106,25 @@ async function dirtyPathSet(worktreePath: string): Promise<Set<string>> {
 }
 
 async function changedPathList(worktreePath: string, oldBaseTip: string, newBaseTip: string): Promise<string[]> {
-  const diff = await gitRaw(["diff", "--name-only", "-z", oldBaseTip, newBaseTip], worktreePath);
+  const diff = await mergeGitRaw(["diff", "--name-only", "-z", oldBaseTip, newBaseTip], worktreePath, "rebase", "workspace merge changed path scan");
   return diff.ok ? splitNul(diff.stdout) : [];
 }
 
 async function restorePathsFromHead(worktreePath: string, paths: string[]): Promise<boolean> {
   if (paths.length === 0) return true;
-  return (await git(["restore", "--staged", "--worktree", "--", ...paths], worktreePath)).ok;
+  return (await mergeGit(["restore", "--staged", "--worktree", "--", ...paths], worktreePath, "rebase", "workspace merge restore clean landed paths")).ok;
 }
 
 async function resetIndexPathsToHead(worktreePath: string, paths: string[]): Promise<boolean> {
   if (paths.length === 0) return true;
-  return (await git(["reset", "-q", "HEAD", "--", ...paths], worktreePath)).ok;
+  return (await mergeGit(["reset", "-q", "HEAD", "--", ...paths], worktreePath, "rebase", "workspace merge reset preserved paths")).ok;
 }
 
 /** Landed paths whose working copy still differs from the advanced HEAD (ground truth, not
  *  exit codes): the checkout is mixed for these — reads/builds/publishes see STALE files. */
 async function pathsDifferingFromHead(worktreePath: string, paths: string[]): Promise<string[]> {
   if (paths.length === 0) return [];
-  const diff = await gitRaw(["diff", "--name-only", "-z", "HEAD", "--", ...paths], worktreePath);
+  const diff = await mergeGitRaw(["diff", "--name-only", "-z", "HEAD", "--", ...paths], worktreePath, "rebase", "workspace merge verify base worktree sync");
   // A failed diff can't prove the checkout is clean — treat every landed path as suspect.
   return diff.ok ? splitNul(diff.stdout) : [...paths];
 }
@@ -151,7 +168,7 @@ async function syncDirtyBaseWorktreeAfterRefAdvance(
   dirtyBefore: Set<string> | undefined,
 ): Promise<BaseWorktreeSyncResult> {
   if (!baseWorktree?.dirty || !dirtyBefore) return RECONCILED;
-  const readTree = await git(["read-tree", "-m", "-u", oldBaseTip, newBaseTip], baseWorktree.path);
+  const readTree = await mergeGit(["read-tree", "-m", "-u", oldBaseTip, newBaseTip], baseWorktree.path, "rebase", "workspace merge sync dirty base worktree");
   if (readTree.ok) return RECONCILED;
 
   const changedPaths = await changedPathList(baseWorktree.path, oldBaseTip, newBaseTip);
@@ -351,13 +368,19 @@ export async function mergeWorkspace(input: WorkspaceMergeInput): Promise<Worksp
   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;
+  console.error(`[orchestrator] workspace.merge prep-start workspace=${input.id ?? "(unknown)"} worktree=${worktreePath} repo=${repoRoot}`);
   // Probe the live HEAD branch first — it's the authoritative source. Fall back to the
   // DB-recorded branch only when the live probe fails (detached HEAD, missing worktree, etc.).
   // This fixes #232: a stale DB branch value (non-null mismatch) would pass through the
   // `input.branch ?? ...` guard unchanged and cause git to attempt merging a non-existent ref.
-  const liveBranch = shortBranch((await git(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath)).stdout || undefined);
+  const liveBranch = shortBranch((await mergeGit(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath, "prep", "workspace merge resolve live branch")).stdout || undefined);
   const branch = liveBranch ?? input.branch;
-  const preview = await previewWorkspaceMerge({ worktreePath, baseRef: input.baseRef, baseSha: input.baseSha, strategy: input.strategy });
+  let preview: WorkspaceMergePreview;
+  try {
+    preview = await withMergePhaseTimeout("preview", () => previewWorkspaceMerge({ worktreePath, baseRef: input.baseRef, baseSha: input.baseSha, strategy: input.strategy }));
+  } catch (err) {
+    return { workspaceId: input.id, strategy: "rebase-ff", merged: false, status: "review_requested", branch, error: errMessage(err) };
+  }
   const strategy = preview.strategy;
   const head = (field: Partial<WorkspaceMergeResult>): WorkspaceMergeResult => ({ workspaceId: input.id, strategy, merged: false, status: "review_requested", branch, baseRef: preview.baseRef, ...field });
 
@@ -392,6 +415,7 @@ export async function mergeWorkspace(input: WorkspaceMergeInput): Promise<Worksp
   if (preview.conflict) return head({ conflict: true, status: "conflict", error: "merge would conflict with base" });
 
   if (strategy === "pr") return await mergePr(input, worktreePath, branch, preview, head);
+  console.error(`[orchestrator] workspace.merge rebase-start workspace=${input.id ?? "(unknown)"} branch=${branch ?? "(unknown)"} base=${preview.baseRef ?? "(unknown)"}`);
   return await mergeRebaseFf(input, worktreePath, repoRoot, branch, preview, head);
 }
 
@@ -531,14 +555,16 @@ async function synthesizeNoFfMerge(
   baseSha: string,
   branchSha: string,
   message: string,
+  timeoutMs?: number,
 ): Promise<{ ok: true; mergeSha: string } | { ok: false; conflict?: boolean; error: string }> {
-  const tree = await git(["merge-tree", "--write-tree", baseSha, branchSha], repoRoot);
+  const tree = await git(["merge-tree", "--write-tree", baseSha, branchSha], repoRoot, { timeoutMs, timeoutLabel: "workspace merge synthesize merge-tree" });
   if (!tree.ok) return { ok: false, conflict: true, error: tree.stdout || tree.stderr || "merge conflict computing tree" };
   const treeOid = tree.stdout.split("\n")[0]?.trim();
   if (!treeOid) return { ok: false, error: "merge-tree produced no tree oid" };
   const commit = await git(
     ["-c", `user.name=${LAND_COMMITTER.name}`, "-c", `user.email=${LAND_COMMITTER.email}`, "commit-tree", treeOid, "-p", baseSha, "-p", branchSha, "-m", message],
     repoRoot,
+    { timeoutMs, timeoutLabel: "workspace merge synthesize commit-tree" },
   );
   if (!commit.ok || !commit.stdout) return { ok: false, error: commit.stderr || "commit-tree failed" };
   return { ok: true, mergeSha: commit.stdout };
@@ -551,9 +577,9 @@ async function recordNoFfMerge(
   branchSha: string,
   message: string,
 ): Promise<{ ok: true; mergeSha: string } | { ok: false; conflict?: boolean; error: string }> {
-  const synth = await synthesizeNoFfMerge(repoRoot, baseSha, branchSha, message);
+  const synth = await synthesizeNoFfMerge(repoRoot, baseSha, branchSha, message, mergePhaseTimeoutMs("synthesize"));
   if (!synth.ok) return synth;
-  const update = await git(["update-ref", `refs/heads/${base}`, synth.mergeSha, baseSha], repoRoot);
+  const update = await mergeGit(["update-ref", `refs/heads/${base}`, synth.mergeSha, baseSha], repoRoot, "rebase", `workspace merge advance ${base} to synthesized merge`);
   if (!update.ok) return { ok: false, error: update.stderr || "failed to advance base ref" };
   return { ok: true, mergeSha: synth.mergeSha };
 }
@@ -579,9 +605,15 @@ async function runLandGatesOnIntegratedTree(
   headSha: string,
   mergeMessage: string,
 ): Promise<{ gates: LandGatesResult } | { abort: { conflict?: boolean; error: string } }> {
-  if (behind === 0) return { gates: await runLandGates(worktreePath) };
+  console.error(`[orchestrator] workspace.merge gate-start worktree=${worktreePath} behind=${behind}`);
+  if (behind === 0) return { gates: await withMergePhaseTimeout("gates", () => runLandGates(worktreePath)) };
 
-  const synth = await synthesizeNoFfMerge(repoRoot, integrationBaseSha, headSha, mergeMessage);
+  let synth: Awaited<ReturnType<typeof synthesizeNoFfMerge>>;
+  try {
+    synth = await withMergePhaseTimeout("synthesize", () => synthesizeNoFfMerge(repoRoot, integrationBaseSha, headSha, mergeMessage, mergePhaseTimeoutMs("synthesize")));
+  } catch (err) {
+    return { abort: { error: errMessage(err) } };
+  }
   if (!synth.ok) return { abort: { conflict: synth.conflict, error: synth.error } };
 
   // Detached worktree in an isolated temp dir so the gates see the integrated tree on disk
@@ -589,15 +621,33 @@ async function runLandGatesOnIntegratedTree(
   // creates the leaf, so hand it a not-yet-existing path under a freshly made parent dir.
   const tmpParent = mkdtempSync(join(tmpdir(), "agent-relay-landgate-"));
   const tmpWorktree = join(tmpParent, "tree");
-  const add = await git(["worktree", "add", "--detach", tmpWorktree, synth.mergeSha], repoRoot);
+  let add: Awaited<ReturnType<typeof git>>;
+  try {
+    add = await withMergePhaseTimeout("worktree-add", () => git(
+      ["worktree", "add", "--detach", tmpWorktree, synth.mergeSha],
+      repoRoot,
+      { timeoutMs: mergePhaseTimeoutMs("worktree-add"), timeoutLabel: "workspace merge land-gate worktree add" },
+    ));
+  } catch (err) {
+    rmSync(tmpParent, { recursive: true, force: true });
+    return { abort: { error: errMessage(err) } };
+  }
   if (!add.ok) {
     rmSync(tmpParent, { recursive: true, force: true });
     return { abort: { error: add.stderr || "failed to materialize integrated tree for land gates" } };
   }
   try {
-    return { gates: await runLandGates(tmpWorktree) };
+    return { gates: await withMergePhaseTimeout("gates", () => runLandGates(tmpWorktree)) };
   } finally {
-    await git(["worktree", "remove", "--force", tmpWorktree], repoRoot);
+    try {
+      await withMergePhaseTimeout("cleanup", () => git(
+        ["worktree", "remove", "--force", tmpWorktree],
+        repoRoot,
+        { timeoutMs: mergePhaseTimeoutMs("cleanup"), timeoutLabel: "workspace merge land-gate worktree cleanup" },
+      ));
+    } catch (err) {
+      console.error(`[orchestrator] land-gate integrated worktree cleanup timed out/failed: ${errMessage(err)}`);
+    }
     rmSync(tmpParent, { recursive: true, force: true });
   }
 }
@@ -616,7 +666,7 @@ async function syncLocalBaseToUpstream(
   base: string,
   upstream: string,
 ): Promise<{ ok: true; baseSync?: BaseWorktreeSyncResult } | { ok: false; error: string }> {
-  const upstreamSha = (await git(["rev-parse", "--verify", upstream], worktreePath)).stdout;
+  const upstreamSha = (await mergeGit(["rev-parse", "--verify", upstream], worktreePath, "rebase", `workspace merge resolve ${upstream}`)).stdout;
   if (!upstreamSha) return { ok: false, error: `cannot resolve ${upstream} to sync ${base}` };
   const baseWorktree = await worktreeForBranch(repoRoot, base);
   // Sync IN the base worktree only when it's clean — that keeps its working tree consistent
@@ -625,14 +675,14 @@ async function syncLocalBaseToUpstream(
   // lands: advance the ref directly with update-ref, then best-effort sync the checked-out
   // index/worktree forward for paths that are not human-modified (#681).
   if (baseWorktree && !baseWorktree.dirty) {
-    const ff = await git(["merge", "--ff-only", upstream], baseWorktree.path);
+    const ff = await mergeGit(["merge", "--ff-only", upstream], baseWorktree.path, "rebase", `workspace merge fast-forward ${base} to ${upstream}`);
     if (!ff.ok) return { ok: false, error: ff.stderr || `failed to fast-forward ${base} to ${upstream}` };
     return { ok: true };
   }
-  const oldBaseTip = (await git(["rev-parse", base], repoRoot)).stdout;
+  const oldBaseTip = (await mergeGit(["rev-parse", base], repoRoot, "rebase", `workspace merge resolve ${base} before upstream sync`)).stdout;
   const dirtyBefore = baseWorktree?.dirty ? await dirtyPathSet(baseWorktree.path) : undefined;
   const updateArgs = oldBaseTip ? ["update-ref", `refs/heads/${base}`, upstreamSha, oldBaseTip] : ["update-ref", `refs/heads/${base}`, upstreamSha];
-  const update = await git(updateArgs, repoRoot);
+  const update = await mergeGit(updateArgs, repoRoot, "rebase", `workspace merge update ${base} to ${upstream}`);
   if (!update.ok) return { ok: false, error: update.stderr || `failed to advance ${base} to ${upstream}` };
   const baseSync = oldBaseTip ? await syncDirtyBaseWorktreeAfterRefAdvance(base, baseWorktree, oldBaseTip, upstreamSha, dirtyBefore) : undefined;
   return { ok: true, baseSync };
@@ -668,7 +718,8 @@ async function mergeRebaseFf(
   // points (the upstream sync below and the final land). A mixed state from either is surfaced
   // loudly rather than swallowed as a log warning (#824).
   let baseSync: BaseWorktreeSyncResult | undefined;
-  const upstream = await upstreamRef(worktreePath, base);
+  const upstreamResult = await mergeGit(["rev-parse", "--abbrev-ref", `${base}@{upstream}`], worktreePath, "rebase", `workspace merge resolve upstream for ${base}`);
+  const upstream = upstreamResult.ok && upstreamResult.stdout ? upstreamResult.stdout : undefined;
   const slash = upstream ? upstream.indexOf("/") : -1;
   const remote = slash > 0 ? upstream!.slice(0, slash) : undefined; // remote of a `remote/branch` upstream
   const pushEnabled = input.push !== false && workspacePushEnabled() && Boolean(remote);
@@ -677,10 +728,12 @@ async function mergeRebaseFf(
   // gives them new SHAs and breaks traceability (the branch.landed SHA must exist on
   // base verbatim). headSha is the preserved landed commit; when base has advanced we
   // tie the branch in with a no-ff merge so the agent's commits keep their identity.
-  const headSha = (await git(["rev-parse", "HEAD"], worktreePath)).stdout;
+  const headResult = await mergeGit(["rev-parse", "HEAD"], worktreePath, "rebase", "workspace merge resolve workspace HEAD before gates");
+  const headSha = headResult.stdout;
+  if (!headResult.ok || !headSha) return head({ status: "review_requested", error: gitError(headResult, "failed to resolve workspace HEAD before gates") });
   // 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 = (await git(["log", "-1", "--format=%s", headSha], worktreePath)).stdout || undefined;
+  const landedSubject = (await mergeGit(["log", "-1", "--format=%s", headSha], worktreePath, "rebase", "workspace merge read landed commit subject")).stdout || undefined;
 
   // #902 BLOCKING 2 — NO mutation of `refs/heads/<base>` may happen until gates pass, so resolve
   // the SHA the work will integrate onto WITHOUT moving the ref. Origin-ahead is the common
@@ -688,17 +741,28 @@ async function mergeRebaseFf(
   // the local-base sync to AFTER the gates. On a gate failure `refs/heads/<base>` must be byte-
   // identical to before the land attempt — so the only `refs/heads/<base>` mutation is the
   // sync+advance below, all of it gated.
-  let integrationBaseSha = (await git(["rev-parse", base], repoRoot)).stdout;
+  const integrationBaseResult = await mergeGit(["rev-parse", base], repoRoot, "rebase", `workspace merge resolve integration base ${base}`);
+  let integrationBaseSha = integrationBaseResult.stdout;
+  if (!integrationBaseResult.ok || !integrationBaseSha) return head({ status: "review_requested", error: gitError(integrationBaseResult, `failed to resolve integration base ${base}`) });
   let needSync = false;
   if (upstream && remote && pushEnabled) {
-    await git(["fetch", remote, base], worktreePath); // best-effort freshness; a stale ref can only under-detect divergence
-    if (!(await git(["merge-base", "--is-ancestor", upstream, base], worktreePath)).ok) {
+    try {
+      const fetch = await withMergePhaseTimeout("fetch", () => git(
+        ["fetch", remote, base],
+        worktreePath,
+        { timeoutMs: mergePhaseTimeoutMs("fetch"), timeoutLabel: `workspace merge fetch ${remote}/${base}` },
+      ));
+      if (!fetch.ok && fetch.timedOut) return head({ status: "review_requested", error: fetch.stderr || `fetch ${remote}/${base} timed out` });
+    } catch (err) {
+      return head({ status: "review_requested", error: errMessage(err) });
+    }
+    if (!(await mergeGit(["merge-base", "--is-ancestor", upstream, base], worktreePath, "rebase", `workspace merge compare ${upstream} to ${base}`)).ok) {
       // Origin moved ahead. Sync-then-land iff local base is cleanly behind (ancestor
       // of upstream); otherwise it's genuine divergence — refuse without mutating.
-      if (!(await git(["merge-base", "--is-ancestor", base, upstream], worktreePath)).ok) {
+      if (!(await mergeGit(["merge-base", "--is-ancestor", base, upstream], worktreePath, "rebase", `workspace merge compare ${base} to ${upstream}`)).ok) {
         return head({ status: "review_requested", error: `local ${base} has diverged from ${upstream} (commits not on origin); sync before landing` });
       }
-      const upstreamSha = (await git(["rev-parse", "--verify", upstream], worktreePath)).stdout;
+      const upstreamSha = (await mergeGit(["rev-parse", "--verify", upstream], worktreePath, "rebase", `workspace merge resolve ${upstream} for integration`)).stdout;
       if (!upstreamSha) return head({ status: "review_requested", error: `cannot resolve ${upstream} to sync ${base}` });
       // Integrate onto fresh origin (the tree that will land), but DON'T advance local base yet.
       integrationBaseSha = upstreamSha;
@@ -707,7 +771,9 @@ async function mergeRebaseFf(
   }
 
   // Behind relative to the TRUE integration base (origin-ahead ⟹ behind>0 ⟹ a real no-ff merge).
-  const behind = await countBehind(worktreePath, integrationBaseSha);
+  const behindResult = await countBehind(worktreePath, integrationBaseSha);
+  if ("error" in behindResult) return head({ status: "review_requested", error: behindResult.error });
+  const behind = behindResult.behind;
 
   // #902 BLOCKING 1 / closes #903 — run the repo's configured land gates against the EXACT tree
   // that will become base's new tip, BEFORE advancing the ref. behind===0 → the worktree HEAD IS
@@ -752,28 +818,32 @@ async function mergeRebaseFf(
   const dirtyBasePathsBefore = baseWorktree?.dirty ? await dirtyPathSet(baseWorktree.path) : undefined;
   if (baseWorktree && !baseWorktree.dirty) {
     if (behind === 0) {
-      const ff = await git(["merge", "--ff-only", branch], baseWorktree.path);
+      const ff = await mergeGit(["merge", "--ff-only", branch], baseWorktree.path, "rebase", `workspace merge fast-forward ${base} to ${branch}`);
       if (!ff.ok) return head({ status: "review_requested", error: ff.stderr || "fast-forward into base failed" });
     } else {
-      const merge = await git(
+      const merge = await mergeGit(
         ["-c", `user.name=${LAND_COMMITTER.name}`, "-c", `user.email=${LAND_COMMITTER.email}`, "merge", "--no-ff", "-m", landMergeMessage(branch, landedSubject), branch],
         baseWorktree.path,
+        "rebase",
+        `workspace merge no-ff ${branch} into ${base}`,
       );
       if (!merge.ok) {
-        await git(["merge", "--abort"], baseWorktree.path);
+        await mergeGit(["merge", "--abort"], baseWorktree.path, "rebase", `workspace merge abort failed no-ff ${branch}`);
         return head({ conflict: true, status: "conflict", error: merge.stderr || "merge into base failed" });
       }
-      baseTip = (await git(["rev-parse", "HEAD"], baseWorktree.path)).stdout;
+      baseTip = (await mergeGit(["rev-parse", "HEAD"], baseWorktree.path, "rebase", `workspace merge resolve ${base} after no-ff`)).stdout;
     }
   } else if (behind === 0) {
-    const oldBaseTip = (await git(["rev-parse", base], repoRoot)).stdout;
+    const oldBaseTip = (await mergeGit(["rev-parse", base], repoRoot, "rebase", `workspace merge resolve ${base} before fast-forward ref update`)).stdout;
     const update = oldBaseTip
-      ? await git(["update-ref", `refs/heads/${base}`, headSha, oldBaseTip], repoRoot)
-      : await git(["update-ref", `refs/heads/${base}`, headSha], repoRoot);
+      ? await mergeGit(["update-ref", `refs/heads/${base}`, headSha, oldBaseTip], repoRoot, "rebase", `workspace merge update ${base} fast-forward`)
+      : await mergeGit(["update-ref", `refs/heads/${base}`, headSha], repoRoot, "rebase", `workspace merge create/update ${base} fast-forward`);
     if (!update.ok) return head({ status: "review_requested", error: update.stderr || "failed to advance base ref" });
     if (oldBaseTip) baseSync = mergeBaseSyncResults(baseSync, await syncDirtyBaseWorktreeAfterRefAdvance(base, baseWorktree, oldBaseTip, headSha, dirtyBasePathsBefore));
   } else {
-    const baseSha = (await git(["rev-parse", base], repoRoot)).stdout;
+    const baseShaResult = await mergeGit(["rev-parse", base], repoRoot, "rebase", `workspace merge resolve ${base} before no-ff ref update`);
+    const baseSha = baseShaResult.stdout;
+    if (!baseShaResult.ok || !baseSha) return head({ status: "review_requested", error: gitError(baseShaResult, `failed to resolve ${base} before no-ff ref update`) });
     const merged = await recordNoFfMerge(repoRoot, base, baseSha, headSha, landMergeMessage(branch, landedSubject));
     if (!merged.ok) return head(merged.conflict ? { conflict: true, status: "conflict", error: merged.error } : { status: "review_requested", error: merged.error });
     baseTip = merged.mergeSha;
@@ -793,7 +863,7 @@ async function mergeRebaseFf(
   // means origin raced us — surface it instead of claiming an unpublished land.
   let pushed = false;
   if (upstream && remote && pushEnabled) {
-    const push = await git(["push", remote, `${base}:${base}`], worktreePath);
+    const push = await mergeGit(["push", remote, `${base}:${base}`], worktreePath, "rebase", `workspace merge push ${base} to ${remote}`);
     if (!push.ok) return head({ status: "review_requested", mergedSha: headSha, error: push.stderr || `git push to ${remote}/${base} failed` });
     pushed = true;
   }
@@ -807,11 +877,11 @@ async function mergeRebaseFf(
   const deleteBranch = input.deleteBranch !== false;
   if (!deleteBranch) {
     const fresh = await nextBranchName(repoRoot, branch);
-    const switched = await git(["checkout", "-B", fresh, base], worktreePath);
+    const switched = await mergeGit(["checkout", "-B", fresh, base], worktreePath, "rebase", `workspace merge recycle worktree to ${fresh}`);
     if (switched.ok) {
       // The old branch is now fully contained in base (fast-forwarded, or merged in
       // as the no-ff merge's second parent) — drop the litter.
-      const oldDeleted = (await git(["branch", "-D", branch], repoRoot)).ok;
+      const oldDeleted = (await mergeGit(["branch", "-D", branch], repoRoot, "cleanup", `workspace merge delete landed branch ${branch}`)).ok;
       // The worktree just moved onto the advanced base, which may declare deps the
       // shared (symlinked) node_modules lacks. Re-provision so the recycled session
       // continues from a buildable state (issue #51). No-op when nothing is stale.
@@ -822,8 +892,8 @@ async function mergeRebaseFf(
     // Recycle failed — keep the existing branch. Still landed, still active.
     return head({ merged: true, status: "active", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved: false, branchDeleted: false, pushed, ...baseWorktreeSyncField, ...gateWarningsField, error: undefined });
   }
-  const removed = await git(["worktree", "remove", "--force", worktreePath], repoRoot);
+  const removed = await mergeGit(["worktree", "remove", "--force", worktreePath], repoRoot, "cleanup", "workspace merge remove landed worktree");
   const worktreeRemoved = removed.ok;
-  const branchDeleted = worktreeRemoved ? (await git(["branch", "-D", branch], repoRoot)).ok : false;
+  const branchDeleted = worktreeRemoved ? (await mergeGit(["branch", "-D", branch], repoRoot, "cleanup", `workspace merge delete landed branch ${branch}`)).ok : false;
   return head({ merged: true, status: "merged", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved, branchDeleted, pushed, ...baseWorktreeSyncField, ...gateWarningsField, error: undefined });
 }