agent-relay-orchestrator 0.117.1 → 0.118.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.117.1",
+  "version": "0.118.0",
   "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.100",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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

@@ -0,0 +1,127 @@
+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;
+/** 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;
+}
+
+/** 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 function runOneLandGate(worktreePath: string, gate: LandGate): 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.spawnSync>;
+  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.spawnSync(["bash", "-lc", gate.command], {
+      cwd,
+      env: process.env,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: timeoutMs,
+    });
+  } 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 durationMs = Date.now() - started;
+  const stdout = proc.stdout ? proc.stdout.toString() : "";
+  const stderr = proc.stderr ? proc.stderr.toString() : "";
+  let combined = combineOutput(stdout, stderr);
+  const exitCode = typeof proc.exitCode === "number" ? proc.exitCode : null;
+  const timedOut = proc.exitedDueToTimeout === true;
+  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 function runLandGates(worktreePath: string): 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 = 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";
@@ -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).
+ */
+function runLandGatesOnIntegratedTree(
+  repoRoot: string,
+  worktreePath: string,
+  behind: number,
+  integrationBaseSha: string,
+  headSha: string,
+  mergeMessage: string,
+): { gates: LandGatesResult } | { abort: { conflict?: boolean; error: string } } {
+  if (behind === 0) return { gates: 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: runLandGates(tmpWorktree) };
+  } finally {
+    git(["worktree", "remove", "--force", tmpWorktree], repoRoot);
+    rmSync(tmpParent, { recursive: true, force: true });
+  }
 }
 
 /**
@@ -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 = 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 });
 }