agent-relay-orchestrator 0.117.1 → 0.118.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.117.1",
+  "version": "0.118.1",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.1",
-    "agent-relay-sdk": "0.2.99",
+    "agent-relay-sdk": "0.2.101",
     "callmux": "0.23.0"
   },
   "devDependencies": {

package/src/command-poller.ts

@@ -8,14 +8,20 @@ interface CommandPollerOptions {
   relay: Pick<RelayClient, "connected" | "pollCommands">;
   control: CommandPollerControl;
   log?: (message: string) => void;
+  intervalMs?: number;
+  errorBackoffMs?: number;
 }
 
-export function createCommandPoller({ relay, control, log = console.error }: CommandPollerOptions) {
+export function createCommandPoller({ relay, control, log = console.error, intervalMs = 3_000, errorBackoffMs = 3_000 }: CommandPollerOptions) {
   let inFlight = false;
+  let stopped = true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastTickErrored = false;
 
   async function tick(): Promise<boolean> {
     if (!relay.connected || inFlight) return false;
     inFlight = true;
+    lastTickErrored = false;
     try {
       const commands = await relay.pollCommands();
       if (commands.length > 0) {
@@ -27,6 +33,7 @@ export function createCommandPoller({ relay, control, log = console.error }: Com
       }
       return true;
     } catch (err) {
+      lastTickErrored = true;
       log(`[orchestrator] Poll error: ${err}`);
       return false;
     } finally {
@@ -34,8 +41,44 @@ export function createCommandPoller({ relay, control, log = console.error }: Com
     }
   }
 
+  function schedule(delayMs: number): void {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      timer = undefined;
+      void runCycle();
+    }, delayMs);
+    timer.unref?.();
+  }
+
+  async function runCycle(): Promise<void> {
+    let errored = false;
+    try {
+      await tick();
+      errored = lastTickErrored;
+    } catch (err) {
+      errored = true;
+      log(`[orchestrator] Poll loop error: ${err}`);
+    } finally {
+      if (!stopped) schedule(errored ? errorBackoffMs : intervalMs);
+    }
+  }
+
+  function start(): void {
+    if (!stopped) return;
+    stopped = false;
+    schedule(0);
+  }
+
+  function stop(): void {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  }
+
   return {
     tick,
+    start,
+    stop,
     get inFlight() {
       return inFlight;
     },

package/src/control.ts

@@ -33,16 +33,10 @@ export function createControlHandler(
 
   async function handleSpawn(ctrl: Record<string, any>): Promise<boolean> {
     const opts = spawnOptionsFromControl(ctrl, config);
-
-    try {
-      const agent = await spawnAgent(opts, config);
-      managedAgents.push(agent);
-      console.error(`[orchestrator] Spawned ${opts.provider} agent: ${agent.tmuxSession}`);
-      return true;
-    } catch (err) {
-      console.error(`[orchestrator] Spawn failed: ${err}`);
-      return false;
-    }
+    const agent = await spawnAgent(opts, config);
+    managedAgents.push(agent);
+    console.error(`[orchestrator] Spawned ${opts.provider} agent: ${agent.tmuxSession}`);
+    return true;
   }
 
   async function handleShutdown(ctrl: Record<string, any>, restart = false): Promise<Record<string, unknown>> {
@@ -124,7 +118,7 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, "succeeded", result);
       } else if (command.type === "workspace.merge") {
-        const result = mergeWorkspace({
+        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,
@@ -297,6 +291,7 @@ function spawnOptionsFromRecord(source: Record<string, any>, config: Orchestrato
     automationRunId: typeof source.automationRunId === "string" ? source.automationRunId : undefined,
     requestedVia: typeof source.requestedVia === "string" ? source.requestedVia : undefined,
     resumeWorkspace: parseResumeWorkspace(source.resumeWorkspace),
+    acquisition: parseProjectAcquisition(source.acquisition),
   };
 }
 
@@ -331,3 +326,22 @@ function parseResumeWorkspace(value: unknown): import("./workspace-probe/types")
     baseSha: typeof value.baseSha === "string" ? value.baseSha : undefined,
   };
 }
+
+function parseProjectAcquisition(value: unknown): import("./spawn/types").ProjectAcquisitionManifest | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.mode !== "project-root" || value.sync !== "ff-only") return undefined;
+  const projectId = typeof value.projectId === "string" ? value.projectId : undefined;
+  const rootPath = typeof value.rootPath === "string" ? value.rootPath : undefined;
+  const cwd = typeof value.cwd === "string" ? value.cwd : undefined;
+  const remoteUrl = typeof value.remoteUrl === "string" ? value.remoteUrl : undefined;
+  if (!projectId || !rootPath || !cwd || !remoteUrl) return undefined;
+  return {
+    mode: "project-root",
+    projectId,
+    rootPath,
+    cwd,
+    remoteUrl,
+    ref: typeof value.ref === "string" ? value.ref : undefined,
+    sync: "ff-only",
+  };
+}

package/src/index.ts

@@ -60,7 +60,7 @@ const sharedCallmux = new SharedCallmuxSupervisor(config);
 const POLL_INTERVAL_MS = 3_000;
 const REGISTER_RETRY_MS = 5_000;
 const GUEST_REAP_INTERVAL_MS = 60_000;
-let pollTimer: Timer | null = null;
+let commandPoller: ReturnType<typeof createCommandPoller> | null = null;
 let healthCheckTimer: Timer | null = null;
 let guestReaperTimer: Timer | null = null;
 let apiServer: { stop(): void; url: string } | null = null;
@@ -124,10 +124,8 @@ async function startup(): Promise<void> {
 }
 
 function startPolling(): void {
-  const commandPoller = createCommandPoller({ relay, control });
-  pollTimer = setInterval(async () => {
-    await commandPoller.tick();
-  }, POLL_INTERVAL_MS);
+  commandPoller = createCommandPoller({ relay, control, intervalMs: POLL_INTERVAL_MS, errorBackoffMs: POLL_INTERVAL_MS });
+  commandPoller.start();
 }
 
 async function registerUntilConnected(): Promise<void> {
@@ -208,7 +206,7 @@ async function healthCheck(): Promise<void> {
 
 async function shutdown(): Promise<void> {
   console.error("[orchestrator] Shutting down...");
-  if (pollTimer) clearInterval(pollTimer);
+  commandPoller?.stop();
   if (healthCheckTimer) clearInterval(healthCheckTimer);
   if (guestReaperTimer) clearInterval(guestReaperTimer);
   if (apiServer) apiServer.stop();

package/src/spawn/acquisition.ts

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { errMessage, isPathWithinBase } from "agent-relay-sdk";
+import { git, requireGit } from "../git";
+import type { ProjectAcquisitionManifest } from "./types";
+
+export interface ProjectAcquisitionResult {
+  applied: boolean;
+  action: "cloned" | "synced" | "noop";
+  rootPath: string;
+  remoteUrl: string;
+  ref?: string;
+  headSha?: string;
+}
+
+const inFlight = new Map<string, Promise<ProjectAcquisitionResult>>();
+const LOCK_TIMEOUT_MS = 5 * 60_000;
+const LOCK_POLL_MS = 100;
+
+export async function applyProjectAcquisitionManifest(
+  manifest: ProjectAcquisitionManifest | undefined,
+  baseDir: string,
+): Promise<ProjectAcquisitionResult | undefined> {
+  if (!manifest) return undefined;
+  const rootPath = resolve(manifest.rootPath);
+  const prior = inFlight.get(rootPath);
+  if (prior) return prior;
+  const run = withAcquisitionLock(rootPath, baseDir, () => applyManifestLocked(manifest, baseDir));
+  inFlight.set(rootPath, run);
+  try {
+    return await run;
+  } finally {
+    if (inFlight.get(rootPath) === run) inFlight.delete(rootPath);
+  }
+}
+
+async function withAcquisitionLock(rootPath: string, baseDir: string, fn: () => ProjectAcquisitionResult): Promise<ProjectAcquisitionResult> {
+  const lockDir = join(resolve(baseDir), ".agent-relay", "locks", `acquire-${hash(rootPath)}.lock`);
+  mkdirSync(dirname(lockDir), { recursive: true });
+  const started = Date.now();
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      writeFileSync(join(lockDir, "owner"), `${process.pid}\n${rootPath}\n`);
+      break;
+    } catch (error) {
+      if (Date.now() - started > LOCK_TIMEOUT_MS) {
+        throw new Error(`repo acquisition lock timed out for ${rootPath}: ${errMessage(error)}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function applyManifestLocked(manifest: ProjectAcquisitionManifest, baseDir: string): ProjectAcquisitionResult {
+  validateManifest(manifest, baseDir);
+  const rootPath = resolve(manifest.rootPath);
+  const remoteUrl = manifest.remoteUrl.trim();
+  let action: ProjectAcquisitionResult["action"] = "noop";
+  if (!existsSync(rootPath)) {
+    cloneRoot(manifest, baseDir);
+    action = "cloned";
+  }
+  const syncAction = syncRoot(manifest);
+  if (syncAction === "synced" && action !== "cloned") action = "synced";
+  return {
+    applied: true,
+    action,
+    rootPath,
+    remoteUrl,
+    ...(manifest.ref ? { ref: manifest.ref } : {}),
+    headSha: git(["rev-parse", "HEAD"], rootPath).stdout || undefined,
+  };
+}
+
+function validateManifest(manifest: ProjectAcquisitionManifest, baseDir: string): void {
+  const rootPath = resolve(manifest.rootPath);
+  if (!manifest.remoteUrl.trim()) throw new Error("project acquisition remoteUrl is required");
+  if (!isPathWithinBase(rootPath, baseDir) || rootPath === resolve(baseDir)) {
+    throw new Error(`project acquisition rootPath must be within orchestrator baseDir: ${baseDir}`);
+  }
+  if (!isPathWithinBase(resolve(manifest.cwd), rootPath)) {
+    throw new Error(`project acquisition cwd must be within rootPath: ${manifest.cwd}`);
+  }
+}
+
+function cloneRoot(manifest: ProjectAcquisitionManifest, baseDir: string): void {
+  const rootPath = resolve(manifest.rootPath);
+  const parent = dirname(rootPath);
+  if (!isPathWithinBase(parent, baseDir)) throw new Error(`project acquisition parent must be within orchestrator baseDir: ${parent}`);
+  mkdirSync(parent, { recursive: true });
+  const tmp = join(parent, `.${basename(rootPath)}.agent-relay-clone-${process.pid}-${Date.now()}`);
+  rmSync(tmp, { recursive: true, force: true });
+  const args = ["clone", "--origin", "origin"];
+  if (manifest.ref) args.push("--branch", manifest.ref);
+  args.push(manifest.remoteUrl.trim(), tmp);
+  const cloned = runGit(args, parent);
+  if (!cloned.ok) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`git clone failed for ${rootPath}: ${cloned.stderr || cloned.stdout}`);
+  }
+  try {
+    renameSync(tmp, rootPath);
+  } catch (error) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`failed to install cloned repo at ${rootPath}: ${errMessage(error)}`);
+  }
+}
+
+function syncRoot(manifest: ProjectAcquisitionManifest): "synced" | "noop" {
+  const rootPath = resolve(manifest.rootPath);
+  assertExistingGitRoot(rootPath);
+  assertRemote(rootPath, manifest.remoteUrl.trim());
+  const status = git(["status", "--porcelain"], rootPath);
+  if (!status.ok) throw new Error(`git status failed for ${rootPath}: ${status.stderr}`);
+  if (status.stdout.trim()) throw new Error(`project root ${rootPath} has local changes; refusing ff-only sync before spawn`);
+  const fetch = git(["fetch", "--prune", "origin"], rootPath);
+  if (!fetch.ok) throw new Error(`git fetch failed for ${rootPath}: ${fetch.stderr || fetch.stdout}`);
+  const target = checkoutSyncTarget(rootPath, manifest.ref);
+  if (!target) return "noop";
+  const head = requireGit(["rev-parse", "HEAD"], rootPath);
+  const targetHead = requireGit(["rev-parse", target], rootPath);
+  if (head === targetHead) return "noop";
+  if (!git(["merge-base", "--is-ancestor", "HEAD", target], rootPath).ok) {
+    throw new Error(`project root ${rootPath} has diverged from ${target}; refusing non-fast-forward sync`);
+  }
+  const merged = git(["merge", "--ff-only", target], rootPath);
+  if (!merged.ok) throw new Error(`git ff-only sync failed for ${rootPath}: ${merged.stderr || merged.stdout}`);
+  return "synced";
+}
+
+function assertExistingGitRoot(rootPath: string): void {
+  let stat;
+  try {
+    stat = statSync(rootPath);
+  } catch (error) {
+    throw new Error(`project root does not exist after acquisition: ${rootPath}: ${errMessage(error)}`);
+  }
+  if (!stat.isDirectory()) throw new Error(`project root exists but is not a directory: ${rootPath}`);
+  const top = git(["rev-parse", "--show-toplevel"], rootPath);
+  if (!top.ok || resolve(top.stdout) !== rootPath) throw new Error(`project root exists but is not a git checkout root: ${rootPath}`);
+}
+
+function assertRemote(rootPath: string, remoteUrl: string): void {
+  const current = git(["remote", "get-url", "origin"], rootPath);
+  if (!current.ok || !current.stdout) throw new Error(`project root ${rootPath} has no origin remote`);
+  if (current.stdout.trim() !== remoteUrl) {
+    throw new Error(`project root ${rootPath} origin mismatch: expected ${remoteUrl}, found ${current.stdout.trim()}`);
+  }
+}
+
+function checkoutSyncTarget(rootPath: string, ref: string | undefined): string | undefined {
+  if (ref?.trim()) {
+    const name = ref.trim();
+    const remoteBranch = `refs/remotes/origin/${name}`;
+    if (git(["show-ref", "--verify", "--quiet", remoteBranch], rootPath).ok) {
+      if (git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`], rootPath).ok) {
+        const checked = git(["checkout", name], rootPath);
+        if (!checked.ok) throw new Error(`git checkout ${name} failed for ${rootPath}: ${checked.stderr || checked.stdout}`);
+      } else {
+        const checked = git(["checkout", "-B", name, `origin/${name}`], rootPath);
+        if (!checked.ok) throw new Error(`git checkout ${name} failed for ${rootPath}: ${checked.stderr || checked.stdout}`);
+      }
+      return `origin/${name}`;
+    }
+    if (git(["rev-parse", "--verify", name], rootPath).ok) {
+      const checked = git(["checkout", name], rootPath);
+      if (!checked.ok) throw new Error(`git checkout ${name} failed for ${rootPath}: ${checked.stderr || checked.stdout}`);
+      return undefined;
+    }
+    throw new Error(`project acquisition ref "${name}" not found on origin for ${rootPath}`);
+  }
+  const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], rootPath);
+  if (upstream.ok && upstream.stdout) return upstream.stdout;
+  const originHead = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], rootPath);
+  if (originHead.ok && originHead.stdout) return originHead.stdout;
+  throw new Error(`project root ${rootPath} has no upstream or origin/HEAD for ff-only sync`);
+}
+
+function runGit(args: string[], cwd: string): { ok: boolean; stdout: string; stderr: string } {
+  const proc = Bun.spawnSync(["git", ...args], {
+    cwd,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    ok: proc.exitCode === 0,
+    stdout: proc.stdout.toString().trim(),
+    stderr: proc.stderr.toString().trim(),
+  };
+}
+
+function hash(value: string): string {
+  return createHash("sha1").update(resolve(value)).digest("hex").slice(0, 16);
+}

package/src/spawn/index.ts

@@ -1,4 +1,5 @@
 export * from "./command";
+export * from "./acquisition";
 export * from "./guests";
 export * from "./log-utils";
 export * from "./runtime";

package/src/spawn/spawn-agent.ts

@@ -2,6 +2,7 @@ import { closeSync, existsSync, openSync, rmSync } from "node:fs";
 import type { OrchestratorConfig } from "../config";
 import { resolveSpawnWorkspace, workspacesRoot } from "../workspace-probe";
 import type { ManagedAgentReport } from "../relay";
+import { applyProjectAcquisitionManifest } from "./acquisition";
 import { buildEnv, buildRunnerCommand, defaultSpawnLabel, isWithinBaseDir, sessionName } from "./command";
 import { addSessionRecord, currentSessionPid, findSessionRecord, ensureLogDir, ensureRunnerInfoDir, logFilePath, runnerInfoPath, sessionRecordLiveness, sessionReportFields } from "./runtime";
 import { managedAgentId } from "./sessions";
@@ -10,6 +11,7 @@ import type { SpawnOptions } from "./types";
 
 interface SpawnAgentDeps {
   resolveSpawnWorkspace: typeof resolveSpawnWorkspace;
+  applyProjectAcquisitionManifest: typeof applyProjectAcquisitionManifest;
   spawnRunner: typeof spawnRunner;
   addSessionRecord: typeof addSessionRecord;
   findSessionRecord: typeof findSessionRecord;
@@ -24,6 +26,7 @@ interface SpawnAgentDeps {
 
 const defaultSpawnAgentDeps: SpawnAgentDeps = {
   resolveSpawnWorkspace,
+  applyProjectAcquisitionManifest,
   spawnRunner,
   addSessionRecord,
   findSessionRecord,
@@ -46,12 +49,13 @@ export async function spawnAgent(
   const agentId = opts.agentId || managedAgentId(config, opts.provider, label);
   const name = sessionName(config, opts.provider, label, opts.spawnRequestId ?? agentId);
 
-  if (!existsSync(opts.cwd)) {
-    throw new Error(`cwd does not exist: ${opts.cwd}`);
-  }
   if (!isWithinBaseDir(opts.cwd, config.baseDir)) {
     throw new Error(`cwd must be within base directory: ${config.baseDir}`);
   }
+  await d.applyProjectAcquisitionManifest(opts.acquisition, config.baseDir);
+  if (!existsSync(opts.cwd)) {
+    throw new Error(`cwd does not exist: ${opts.cwd}`);
+  }
   const existing = existingSpawnSession(opts, d);
   if (existing) return existing;
 

package/src/spawn/types.ts

@@ -2,6 +2,16 @@ import type { OrchestratorConfig } from "../config";
 import type { AgentLifecycle, SpawnProvider, WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
 import type { ResumeWorkspaceTarget } from "../workspace-probe/types";
 
+export interface ProjectAcquisitionManifest {
+  mode: "project-root";
+  projectId: string;
+  rootPath: string;
+  cwd: string;
+  remoteUrl: string;
+  ref?: string;
+  sync: "ff-only";
+}
+
 export interface SpawnOptions {
   provider: SpawnProvider;
   cwd: string;
@@ -33,6 +43,8 @@ export interface SpawnOptions {
   requestedVia?: string;
   /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */
   resumeWorkspace?: ResumeWorkspaceTarget;
+  /** #410 — lazy clone/sync manifest, applied on the host before worktree prep. */
+  acquisition?: ProjectAcquisitionManifest;
 }
 
 export interface SessionInfo {

package/src/workspace-probe/land-gates-runner.ts

@@ -0,0 +1,226 @@
+import { resolve } from "node:path";
+import { errMessage } from "agent-relay-sdk";
+import type { LandGate, LandGateRunResult } from "agent-relay-sdk";
+import { loadRepoLandGates } from "agent-relay-sdk/land-gates";
+
+// #902 — execute a repo's configured land gates against the candidate merged tree
+// inside the landing worktree, BEFORE the ref advance in `mergeRebaseFf`. A repo
+// with no `.agent-relay/land-gates.json` loads zero gates, so the caller takes the
+// exact unchanged land path (ironclad opt-in / zero regression). A required gate
+// failing blocks the land (ref NOT advanced); optional gates only warn.
+
+/** Per-gate default timeout when the gate didn't declare `timeoutMs`. Land gates
+ *  are meant to be a FAST high-signal subset, not the full suite — keep the ceiling
+ *  generous but bounded so a hung gate can't wedge the per-repo merge lease forever. */
+const DEFAULT_GATE_TIMEOUT_MS = 5 * 60 * 1000;
+const TIMEOUT_KILL_GRACE_MS = 1_000;
+const OUTPUT_CANCEL_GRACE_MS = 50;
+/** Cap on the full output streamed to the relay artifact (the notification only ever
+ *  carries the tail). Errors usually surface at the END, so we keep the tail on overflow. */
+const MAX_FULL_OUTPUT_BYTES = 256 * 1024;
+/** Bytes of the tail put in the notification body — enough to show the failure, small
+ *  enough never to flood relay. */
+const TAIL_BYTES = 4000;
+
+function keepTail(text: string, maxBytes: number, label: string): string {
+  if (text.length <= maxBytes) return text;
+  const dropped = text.length - maxBytes;
+  return `…(${dropped} earlier ${label} truncated)…\n${text.slice(text.length - maxBytes)}`;
+}
+
+function combineOutput(stdout: string, stderr: string): string {
+  if (stdout && stderr) return `${stdout}\n${stderr}`;
+  return stdout || stderr;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface OutputCapture {
+  done: Promise<void>;
+  text(): string;
+  cancel(): void;
+}
+
+function captureProcessOutput(pipe: unknown): OutputCapture {
+  if (!(pipe instanceof ReadableStream)) {
+    return { done: Promise.resolve(), text: () => "", cancel: () => {} };
+  }
+
+  const reader = pipe.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 {
+      // A timeout cancels the reader intentionally so pipe EOF cannot hold up the gate result.
+    } finally {
+      try { reader.releaseLock(); } catch {}
+    }
+  })();
+
+  return {
+    done,
+    text: () => output,
+    cancel: () => {
+      canceled = true;
+      void reader.cancel().catch(() => {});
+    },
+  };
+}
+
+function signalGateProcessGroup(proc: ReturnType<typeof Bun.spawn>, signal: NodeJS.Signals): void {
+  if (typeof proc.pid === "number" && proc.pid > 0) {
+    try {
+      process.kill(-proc.pid, signal);
+      return;
+    } catch (err) {
+      if ((err as { code?: string }).code !== "ESRCH") {
+        try { proc.kill(signal); } catch {}
+      }
+      return;
+    }
+  }
+  try { proc.kill(signal); } catch {}
+}
+
+/** Run a single gate and capture its outcome. Never throws — a spawn failure (e.g.
+ *  the command can't launch) is reported as a non-passing result so the caller can
+ *  decide block-vs-warn from the gate's `optional` flag. */
+export async function runOneLandGate(worktreePath: string, gate: LandGate): Promise<LandGateRunResult> {
+  const cwd = gate.cwd ? resolve(worktreePath, gate.cwd) : worktreePath;
+  const timeoutMs = gate.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS;
+  const started = Date.now();
+  const base = { name: gate.name, command: gate.command, optional: gate.optional === true } as const;
+
+  let proc: ReturnType<typeof Bun.spawn>;
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let killTimeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    // A login shell so PATH (bun, node, project bins) resolves like the worker's own
+    // environment; `env: process.env` makes runtime env mutations visible to the child.
+    proc = Bun.spawn(["bash", "-lc", gate.command], {
+      cwd,
+      env: process.env,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      detached: true,
+    });
+  } catch (err) {
+    const durationMs = Date.now() - started;
+    const output = `land gate "${gate.name}" could not be launched: ${errMessage(err)}`;
+    return { ...base, passed: false, exitCode: null, timedOut: false, durationMs, outputTail: output, output };
+  }
+
+  const stdoutCapture = captureProcessOutput(proc.stdout);
+  const stderrCapture = captureProcessOutput(proc.stderr);
+  let timeoutTriggeredResolve: () => void = () => {};
+  const timeoutTriggered = new Promise<void>((resolve) => { timeoutTriggeredResolve = resolve; });
+  timeout = setTimeout(() => {
+    timedOut = true;
+    timeoutTriggeredResolve();
+    signalGateProcessGroup(proc, "SIGTERM");
+    stdoutCapture.cancel();
+    stderrCapture.cancel();
+    killTimeout = setTimeout(() => {
+      signalGateProcessGroup(proc, "SIGKILL");
+      stdoutCapture.cancel();
+      stderrCapture.cancel();
+    }, TIMEOUT_KILL_GRACE_MS);
+    killTimeout.unref?.();
+  }, timeoutMs);
+  timeout.unref?.();
+
+  const exitCodeRaw = await Promise.race([
+    proc.exited,
+    timeoutTriggered.then(async () => {
+      await Promise.race([proc.exited.then(() => undefined), sleep(TIMEOUT_KILL_GRACE_MS + OUTPUT_CANCEL_GRACE_MS)]);
+      return null;
+    }),
+  ]).finally(() => {
+    if (timeout) clearTimeout(timeout);
+    if (killTimeout) clearTimeout(killTimeout);
+  });
+  if (timedOut) {
+    stdoutCapture.cancel();
+    stderrCapture.cancel();
+    await Promise.race([Promise.allSettled([stdoutCapture.done, stderrCapture.done]), sleep(OUTPUT_CANCEL_GRACE_MS)]);
+  } else {
+    await Promise.all([stdoutCapture.done, stderrCapture.done]);
+  }
+  const durationMs = Date.now() - started;
+  const stdout = stdoutCapture.text();
+  const stderr = stderrCapture.text();
+  let combined = combineOutput(stdout, stderr);
+  const exitCode = timedOut ? null : typeof exitCodeRaw === "number" ? exitCodeRaw : null;
+  const passed = exitCode === 0;
+  if (timedOut) combined = `${combined}\n[land-gate] timed out after ${timeoutMs}ms`.trimStart();
+  if (!combined) combined = passed ? "(gate produced no output)" : "(gate produced no output)";
+
+  return {
+    ...base,
+    passed,
+    exitCode,
+    timedOut,
+    durationMs,
+    outputTail: keepTail(combined, TAIL_BYTES, "bytes"),
+    output: keepTail(combined, MAX_FULL_OUTPUT_BYTES, "bytes"),
+  };
+}
+
+export interface LandGatesResult {
+  /** Number of gates configured + run (0 ⇒ no config ⇒ caller's land path is unchanged). */
+  ran: number;
+  /** First REQUIRED gate that failed — its presence means the land MUST be aborted
+   *  without advancing the ref. */
+  failure?: LandGateRunResult;
+  /** Optional gates that failed (warn-only); the land still proceeds. */
+  warnings: LandGateRunResult[];
+}
+
+/**
+ * Load + run the repo's configured land gates against `worktreePath`. Returns
+ * `ran: 0` with no failure/warnings when the repo declares no gates — the load is the
+ * ONLY thing that runs in that case (a missing file → empty list, no subprocess), so
+ * the opt-in is byte-clean. Stops at the first failing REQUIRED gate (it blocks the
+ * land); optional failures accumulate as warnings and never block.
+ *
+ * A PRESENT-but-malformed `.agent-relay/land-gates.json` is itself a blocking failure
+ * (surfaced as a synthetic required gate) rather than an unhandled throw that would
+ * crash the merge command — the worker fixes the config and re-lands.
+ */
+export async function runLandGates(worktreePath: string): Promise<LandGatesResult> {
+  const warnings: LandGateRunResult[] = [];
+  let gates: LandGate[];
+  try {
+    gates = loadRepoLandGates(worktreePath);
+  } catch (err) {
+    const output = `invalid .agent-relay/land-gates.json: ${errMessage(err)}`;
+    return {
+      ran: 1,
+      failure: { name: "land-gates-config", command: "(config validation)", optional: false, passed: false, exitCode: null, timedOut: false, durationMs: 0, outputTail: output, output },
+      warnings,
+    };
+  }
+  if (gates.length === 0) return { ran: 0, warnings };
+
+  for (const gate of gates) {
+    const result = await runOneLandGate(worktreePath, gate);
+    if (result.passed) continue;
+    if (result.optional) { warnings.push(result); continue; }
+    // First required failure blocks the land — don't run the rest (the worker fixes
+    // this gate and re-lands, which re-runs from the top).
+    return { ran: gates.length, failure: result, warnings };
+  }
+  return { ran: gates.length, warnings };
+}

package/src/workspace-probe/merge.ts

@@ -1,9 +1,11 @@
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+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 { git, gitRaw } from "../git";
 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 { nextBranchName } from "./names";
 import { parseWorktrees, shortBranch } from "./parse";
@@ -344,7 +346,7 @@ function validPreviewStrategy(strategy: string | null): "pr" | "rebase-ff" | "au
  * Refuses on a dirty worktree, predicted conflicts, or nothing to merge. Never
  * destroys work on uncertainty.
  */
-export function mergeWorkspace(input: WorkspaceMergeInput): WorkspaceMergeResult {
+export async function mergeWorkspace(input: WorkspaceMergeInput): Promise<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;
@@ -389,7 +391,7 @@ export function mergeWorkspace(input: WorkspaceMergeInput): WorkspaceMergeResult
   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);
+  return await mergeRebaseFf(input, worktreePath, repoRoot, branch, preview, head);
 }
 
 /**
@@ -523,9 +525,14 @@ function landMergeMessage(branch: string | undefined, subject: string | undefine
 // with plumbing: compute the merged tree, commit it with both parents (base first, so
 // `--first-parent` still reads as base's mainline), then advance the ref with a CAS on
 // the old value. Preserves the branch's commit SHAs without a working tree.
-function recordNoFfMerge(
+// Synthesize (but do NOT advance any ref to) the no-ff merge commit of `branchSha` into
+// `baseSha`: compute the merged tree with `merge-tree`, then commit it with both parents
+// (base first, so `--first-parent` reads as base's mainline). This is the exact commit/tree
+// that will become base's new tip — used both to gate the TRUE integrated tree before any ref
+// moves (#902/#903) and, via {@link recordNoFfMerge}, to advance base when no working tree is
+// available. Pure object creation: no ref is touched, so a caller can throw it away freely.
+function synthesizeNoFfMerge(
   repoRoot: string,
-  base: string,
   baseSha: string,
   branchSha: string,
   message: string,
@@ -539,10 +546,65 @@ function recordNoFfMerge(
     repoRoot,
   );
   if (!commit.ok || !commit.stdout) return { ok: false, error: commit.stderr || "commit-tree failed" };
-  const mergeSha = commit.stdout;
-  const update = git(["update-ref", `refs/heads/${base}`, mergeSha, baseSha], repoRoot);
+  return { ok: true, mergeSha: commit.stdout };
+}
+
+function recordNoFfMerge(
+  repoRoot: string,
+  base: string,
+  baseSha: string,
+  branchSha: string,
+  message: string,
+): { ok: true; mergeSha: string } | { ok: false; conflict?: boolean; error: string } {
+  const synth = synthesizeNoFfMerge(repoRoot, baseSha, branchSha, message);
+  if (!synth.ok) return synth;
+  const update = git(["update-ref", `refs/heads/${base}`, synth.mergeSha, baseSha], repoRoot);
   if (!update.ok) return { ok: false, error: update.stderr || "failed to advance base ref" };
-  return { ok: true, mergeSha };
+  return { ok: true, mergeSha: synth.mergeSha };
+}
+
+/**
+ * Run the repo's configured land gates against the EXACT tree that will become base's new tip,
+ * BEFORE any ref advance (#902 BLOCKING 1 / closes #903). The candidate tree depends on `behind`:
+ *  - behind === 0: the landing worktree HEAD already IS that tree (a clean fast-forward), so gates
+ *    run in `worktreePath` in place — byte-identical to today's straight-FF path.
+ *  - behind  >  0: base has advanced, so the tree that will land is the no-ff MERGE of
+ *    `integrationBaseSha` and `headSha`, NOT the worktree HEAD. Synthesize that merge commit with
+ *    plumbing (no ref moved), check it out in a throwaway DETACHED worktree, and gate THAT tree.
+ *    The temp worktree is torn down on EVERY exit path (including a gate that throws), so a land
+ *    can never strand an orphan worktree or leave the synthesized merge half-applied.
+ * Returns the gate outcome, or an `abort` describing a merge result the caller must return early
+ * (a real merge conflict computing the integrated tree, or a failure materializing it).
+ */
+async function runLandGatesOnIntegratedTree(
+  repoRoot: string,
+  worktreePath: string,
+  behind: number,
+  integrationBaseSha: string,
+  headSha: string,
+  mergeMessage: string,
+): Promise<{ gates: LandGatesResult } | { abort: { conflict?: boolean; error: string } }> {
+  if (behind === 0) return { gates: await runLandGates(worktreePath) };
+
+  const synth = synthesizeNoFfMerge(repoRoot, integrationBaseSha, headSha, mergeMessage);
+  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
+  // without disturbing the landing worktree, the base checkout, or any ref. `git worktree add`
+  // 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 = git(["worktree", "add", "--detach", tmpWorktree, synth.mergeSha], repoRoot);
+  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) };
+  } finally {
+    git(["worktree", "remove", "--force", tmpWorktree], repoRoot);
+    rmSync(tmpParent, { recursive: true, force: true });
+  }
 }
 
 /**
@@ -581,14 +643,14 @@ function syncLocalBaseToUpstream(
   return { ok: true, baseSync };
 }
 
-function mergeRebaseFf(
+async function mergeRebaseFf(
   input: WorkspaceMergeInput,
   worktreePath: string,
   repoRoot: string,
   branch: string | undefined,
   preview: WorkspaceMergePreview,
   head: (field: Partial<WorkspaceMergeResult>) => WorkspaceMergeResult,
-): WorkspaceMergeResult {
+): Promise<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" });
@@ -615,6 +677,24 @@ function mergeRebaseFf(
   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);
+
+  // SHA preservation (#287): never rebase the agent branch — rewriting its commits
+  // 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 = git(["rev-parse", "HEAD"], worktreePath).stdout;
+  // Subject of the landed commit for the relay's branch.landed notice (#239). Best-effort:
+  // an empty/failed read just omits it from the message body.
+  const landedSubject = git(["log", "-1", "--format=%s", headSha], worktreePath).stdout || undefined;
+
+  // #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
+  // concurrent case (#638): we still fetch fresh origin to compute the real merge, but we defer
+  // 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 = git(["rev-parse", base], repoRoot).stdout;
+  let needSync = false;
   if (upstream && remote && pushEnabled) {
     git(["fetch", remote, base], worktreePath); // best-effort freshness; a stale ref can only under-detect divergence
     if (!git(["merge-base", "--is-ancestor", upstream, base], worktreePath).ok) {
@@ -623,21 +703,47 @@ function mergeRebaseFf(
       if (!git(["merge-base", "--is-ancestor", base, upstream], worktreePath).ok) {
         return head({ status: "review_requested", error: `local ${base} has diverged from ${upstream} (commits not on origin); sync before landing` });
       }
-      const synced = syncLocalBaseToUpstream(repoRoot, worktreePath, base, upstream);
-      if (!synced.ok) return head({ status: "review_requested", error: synced.error });
-      baseSync = mergeBaseSyncResults(baseSync, synced.baseSync);
+      const upstreamSha = git(["rev-parse", "--verify", upstream], worktreePath).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;
+      needSync = true;
     }
   }
 
-  // SHA preservation (#287): never rebase the agent branch — rewriting its commits
-  // 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 = git(["rev-parse", "HEAD"], worktreePath).stdout;
-  // Subject of the landed commit for the relay's branch.landed notice (#239). Best-effort:
-  // an empty/failed read just omits it from the message body.
-  const landedSubject = git(["log", "-1", "--format=%s", headSha], worktreePath).stdout || undefined;
-  const behind = countBehind(worktreePath, base);
+  // Behind relative to the TRUE integration base (origin-ahead ⟹ behind>0 ⟹ a real no-ff merge).
+  const behind = countBehind(worktreePath, integrationBaseSha);
+
+  // #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
+  // that tree (clean fast-forward); behind>0 → the synthesized no-ff merge of integrationBaseSha +
+  // HEAD, gated in a throwaway worktree (see runLandGatesOnIntegratedTree). A repo with no
+  // `.agent-relay/land-gates.json` runs ZERO gates (missing-file → empty list, no subprocess), so
+  // behind===0 is byte-identical to the prior land path (ironclad opt-in / zero regression). A
+  // failing REQUIRED gate aborts the land here WITHOUT advancing/syncing the ref — returned as
+  // status:"review_requested" carrying `gateFailure`, NOT "conflict": gate failures bounce back to
+  // the worker, never the merge-conflict/steward path. Optional-gate failures ride along as
+  // `gateWarnings` on the successful land below.
+  const gateRun = await runLandGatesOnIntegratedTree(repoRoot, worktreePath, behind, integrationBaseSha, headSha, landMergeMessage(branch, landedSubject));
+  if ("abort" in gateRun) {
+    return gateRun.abort.conflict
+      ? head({ conflict: true, status: "conflict", error: gateRun.abort.error })
+      : head({ status: "review_requested", error: gateRun.abort.error });
+  }
+  const gates = gateRun.gates;
+  if (gates.failure) {
+    return head({ status: "review_requested", gateFailure: gates.failure, error: `land gate failed: ${gates.failure.name}` });
+  }
+  const gateWarningsField = gates.warnings.length ? { gateWarnings: gates.warnings } : {};
+
+  // Gates passed — only NOW is it safe to touch `refs/heads/<base>`. If origin moved ahead, sync
+  // local base up to the fetched upstream first (#638); this is the FIRST mutation of the base ref
+  // in the whole land path, so a gate failure above can never leave it advanced (#902 BLOCKING 2).
+  if (needSync) {
+    const synced = syncLocalBaseToUpstream(repoRoot, worktreePath, base, upstream!);
+    if (!synced.ok) return head({ status: "review_requested", error: synced.error });
+    baseSync = mergeBaseSyncResults(baseSync, synced.baseSync);
+  }
 
   // Advance base. `baseTip` is base's new tip after the land: it equals headSha on a
   // clean fast-forward, or the merge commit on a no-ff merge. Operate IN the base worktree
@@ -716,13 +822,13 @@ function mergeRebaseFf(
       // continues from a buildable state (issue #51). No-op when nothing is stale.
       const depsRefresh = refreshWorkspaceDeps(repoRoot, worktreePath);
       const reportDeps = depsRefresh.refreshed || depsRefresh.stale || depsRefresh.error;
-      return head({ merged: true, status: "active", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, ...(reportDeps ? { depsRefresh } : {}), ...baseWorktreeSyncField, error: undefined });
+      return head({ merged: true, status: "active", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, ...(reportDeps ? { depsRefresh } : {}), ...baseWorktreeSyncField, ...gateWarningsField, error: undefined });
     }
     // 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, error: undefined });
+    return head({ merged: true, status: "active", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved: false, branchDeleted: false, pushed, ...baseWorktreeSyncField, ...gateWarningsField, error: undefined });
   }
   const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
   const worktreeRemoved = removed.ok;
   const branchDeleted = worktreeRemoved ? git(["branch", "-D", branch], repoRoot).ok : false;
-  return head({ merged: true, status: "merged", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved, branchDeleted, pushed, ...baseWorktreeSyncField, error: undefined });
+  return head({ merged: true, status: "merged", mergedSha: headSha, baseSha: baseTip, subject: landedSubject, worktreeRemoved, branchDeleted, pushed, ...baseWorktreeSyncField, ...gateWarningsField, error: undefined });
 }