agent-relay-orchestrator 0.118.0 → 0.118.2

package/package.json

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

package/src/api.ts

@@ -479,7 +479,7 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
         if (!authorized(req, config)) return error("unauthorized", 401);
         try {
           const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
-          return json(workspaceGitState({
+          return json(await workspaceGitState({
             worktreePath: target,
             baseRef: url.searchParams.get("baseRef") || undefined,
             baseSha: url.searchParams.get("baseSha") || undefined,
@@ -493,7 +493,7 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
         if (!authorized(req, config)) return error("unauthorized", 401);
         try {
           const { target } = resolveInsideBase(url.searchParams.get("path") || undefined, config.baseDir);
-          return json(workspaceDiff({
+          return json(await workspaceDiff({
             worktreePath: target,
             baseRef: url.searchParams.get("baseRef") || undefined,
             baseSha: url.searchParams.get("baseSha") || undefined,
@@ -506,17 +506,17 @@ export function startApiServer(config: OrchestratorConfig, probeCache: ProviderP
 
       if (req.method === "GET" && url.pathname === "/api/workspace/merge-preview") {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        return mergePreviewResponse(url, config.baseDir);
+        return await mergePreviewResponse(url, config.baseDir);
       }
 
       if (req.method === "GET" && url.pathname === "/api/workspace/branch-merge-preview") {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        return branchMergePreviewResponse(url, config.baseDir);
+        return await branchMergePreviewResponse(url, config.baseDir);
       }
 
       if (req.method === "GET" && url.pathname === "/api/workspace/recovery-branches") {
         if (!authorized(req, config)) return error("unauthorized", 401);
-        return recoveryBranchesResponse(url, config.baseDir);
+        return await recoveryBranchesResponse(url, config.baseDir);
       }
 
       if (req.method === "GET" && url.pathname === "/api/providers") {

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>> {
@@ -102,7 +96,7 @@ export function createControlHandler(
         const result = await handleShutdown(command.params, command.type === "agent.restart");
         await relay.updateCommand(command.id, "succeeded", result);
       } else if (command.type === "workspace.cleanup") {
-        const result = cleanupWorkspace({
+        const result = await cleanupWorkspace({
           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,
@@ -114,7 +108,7 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, "succeeded", result);
       } else if (command.type === "workspace.reconcile") {
-        const result = reconcileWorkspace({
+        const result = await reconcileWorkspace({
           id: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined,
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
           worktreePath: typeof command.params.worktreePath === "string" ? command.params.worktreePath : undefined,
@@ -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,
@@ -149,7 +143,7 @@ export function createControlHandler(
         await relay.updateCommand(command.id, mergeCommandStatus(result), result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.pr-arm-auto-merge") {
         const rawPrNumber = command.params.prNumber;
-        const result = armWorkspacePrAutoMerge({
+        const result = await armWorkspacePrAutoMerge({
           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,
@@ -160,7 +154,7 @@ export function createControlHandler(
         await relay.updateCommand(command.id, result.autoMergeArmed ? "succeeded" : "failed", result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.pr-merge") {
         const rawPrNumber = command.params.prNumber;
-        const result = mergeWorkspacePr({
+        const result = await mergeWorkspacePr({
           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,
@@ -171,7 +165,7 @@ export function createControlHandler(
         await relay.updateCommand(command.id, result.relayMerged ? "succeeded" : "failed", result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.pr-refresh") {
         const rawPrNumber = command.params.prNumber;
-        const result = refreshWorkspacePrBranch({
+        const result = await refreshWorkspacePrBranch({
           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,
@@ -181,14 +175,14 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, result.prRefreshed ? "succeeded" : "failed", result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.deps-refresh") {
-        const result = refreshWorkspaceDeps(
+        const result = await refreshWorkspaceDeps(
           typeof command.params.repoRoot === "string" ? command.params.repoRoot : "",
           typeof command.params.worktreePath === "string" ? command.params.worktreePath : "",
           { checkOnly: command.params.checkOnly === true },
         );
         await relay.updateCommand(command.id, "succeeded", { workspaceId: typeof command.params.workspaceId === "string" ? command.params.workspaceId : undefined, ...result });
       } else if (command.type === "workspace.recovery-branch-discard") {
-        const result = discardRecoveryBranch({
+        const result = await discardRecoveryBranch({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
           branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
           baseRef: typeof command.params.baseRef === "string" ? command.params.baseRef : undefined,
@@ -197,7 +191,7 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
       } else if (command.type === "workspace.idle-refresh") {
-        const result = idleRefreshWorktree({
+        const result = await idleRefreshWorktree({
           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,
@@ -207,7 +201,7 @@ export function createControlHandler(
         });
         await relay.updateCommand(command.id, result.error ? "failed" : "succeeded", result as unknown as Record<string, unknown>, result.error);
       } else if (command.type === "workspace.prune") {
-        const result = pruneWorktrees({
+        const result = await pruneWorktrees({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
         });
         await relay.updateCommand(command.id, "succeeded", result);
@@ -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/git.ts

@@ -2,6 +2,8 @@
 // Extracted from workspace-probe.ts so that giant keeps shrinking (epic #291) and the
 // `git -C` invocation lives in one place.
 
+import { execProcess } from "./process";
+
 interface GitResult {
   ok: boolean;
   stdout: string;
@@ -9,36 +11,18 @@ interface GitResult {
 }
 
 /** Run `git -C cwd <args>` and capture trimmed stdout/stderr; never throws. */
-export function git(args: string[], cwd: string): GitResult {
-  const proc = Bun.spawnSync(["git", "-C", cwd, ...args], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  return {
-    ok: proc.exitCode === 0,
-    stdout: proc.stdout.toString().trim(),
-    stderr: proc.stderr.toString().trim(),
-  };
+export async function git(args: string[], cwd: string): Promise<GitResult> {
+  return await execProcess(["git", "-C", cwd, ...args]);
 }
 
 /** Run `git -C cwd <args>` and preserve stdout exactly for path-safe parsers. */
-export function gitRaw(args: string[], cwd: string): GitResult {
-  const proc = Bun.spawnSync(["git", "-C", cwd, ...args], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  return {
-    ok: proc.exitCode === 0,
-    stdout: proc.stdout.toString(),
-    stderr: proc.stderr.toString().trim(),
-  };
+export async function gitRaw(args: string[], cwd: string): Promise<GitResult> {
+  return await execProcess(["git", "-C", cwd, ...args], { trimStdout: false });
 }
 
 /** Like {@link git} but throws on a non-zero exit, returning stdout on success. */
-export function requireGit(args: string[], cwd: string): string {
-  const result = git(args, cwd);
+export async function requireGit(args: string[], cwd: string): Promise<string> {
+  const result = await git(args, cwd);
   if (!result.ok) throw new Error(result.stderr || `git ${args.join(" ")} failed`);
   return result.stdout;
 }

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/process.ts

@@ -0,0 +1,41 @@
+export interface ExecResult {
+  ok: boolean;
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+interface ExecOptions {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stdout?: "pipe" | "ignore";
+  stderr?: "pipe" | "ignore";
+  trimStdout?: boolean;
+  trimStderr?: boolean;
+}
+
+async function readStream(stream: ReadableStream<Uint8Array> | undefined): Promise<string> {
+  if (!stream) return "";
+  return await new Response(stream).text();
+}
+
+export async function execProcess(cmd: string[], options: ExecOptions = {}): Promise<ExecResult> {
+  const proc = Bun.spawn(cmd, {
+    cwd: options.cwd,
+    env: options.env,
+    stdin: "ignore",
+    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),
+  ]);
+  return {
+    ok: exitCode === 0,
+    exitCode,
+    stdout: options.trimStdout === false ? stdout : stdout.trim(),
+    stderr: options.trimStderr === false ? stderr : stderr.trim(),
+  };
+}

package/src/relay.ts

@@ -68,6 +68,8 @@ export interface RelayCommand {
 const RECONNECT_INITIAL_MS = 30_000;
 const RECONNECT_MAX_MS = 3_600_000; // 1 hour
 const RECONNECT_JITTER_MS = 1_000;
+const TRANSIENT_ABORT_RECONNECT_MS = 250;
+const ABORT_FAILURES_BEFORE_DISCONNECT = 3;
 
 export function buildRegistrationMeta(
   config: Pick<OrchestratorConfig, "tmuxPrefix">,
@@ -94,6 +96,7 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
   const agentId = `orchestrator-${config.id}`;
   let heartbeatTimer: Timer | null = null;
   let connected = false;
+  let abortFailures = 0;
   const reconnectMgr = new ReconnectionManager({ initialMs: RECONNECT_INITIAL_MS, maxMs: RECONNECT_MAX_MS, jitterMs: RECONNECT_JITTER_MS });
   let cursorFloor = 0;
   let apiUrl: string | undefined;
@@ -134,6 +137,7 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
     const registered = await res.json().catch(() => null) as { runtimeToken?: { token?: string } } | null;
     if (registered?.runtimeToken?.token) http.setToken(registered.runtimeToken.token);
     connected = true;
+    abortFailures = 0;
     reconnectMgr.reset();
 
     // Bootstrap message cursor
@@ -167,7 +171,20 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
         connected = true;
         reconnectMgr.reset();
       }
+      abortFailures = 0;
     } catch (err) {
+      if (isAbortError(err)) {
+        abortFailures += 1;
+        if (connected && abortFailures === 1) {
+          console.error(`[orchestrator] Relay heartbeat timed out: ${err}; retrying quickly`);
+        }
+        if (abortFailures < ABORT_FAILURES_BEFORE_DISCONNECT) {
+          await reconnect(TRANSIENT_ABORT_RECONNECT_MS);
+          return;
+        }
+      } else {
+        abortFailures = 0;
+      }
       if (connected) {
         console.error(`[orchestrator] Lost connection to relay: ${err}`);
         connected = false;
@@ -176,9 +193,10 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
     }
   }
 
-  async function reconnect(): Promise<void> {
-    const delayMs = reconnectMgr.nextDelay();
-    console.error(`[orchestrator] Reconnecting in ${Math.round(delayMs / 1000)}s...`);
+  async function reconnect(delayOverrideMs?: number): Promise<void> {
+    const delayMs = delayOverrideMs ?? reconnectMgr.nextDelay();
+    const label = delayMs < 1000 ? `${delayMs}ms` : `${Math.round(delayMs / 1000)}s`;
+    console.error(`[orchestrator] Reconnecting in ${label}...`);
     await new Promise((resolve) => setTimeout(resolve, delayMs));
     try {
       await register();
@@ -258,3 +276,8 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
     get connected() { return connected; },
   };
 }
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError"
+    || typeof error === "object" && error !== null && (error as { name?: string }).name === "AbortError";
+}

package/src/spawn/acquisition.ts

@@ -0,0 +1,193 @@
+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 { execProcess } from "../process";
+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: () => Promise<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 await fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+async function applyManifestLocked(manifest: ProjectAcquisitionManifest, baseDir: string): Promise<ProjectAcquisitionResult> {
+  validateManifest(manifest, baseDir);
+  const rootPath = resolve(manifest.rootPath);
+  const remoteUrl = manifest.remoteUrl.trim();
+  let action: ProjectAcquisitionResult["action"] = "noop";
+  if (!existsSync(rootPath)) {
+    await cloneRoot(manifest, baseDir);
+    action = "cloned";
+  }
+  const syncAction = await syncRoot(manifest);
+  if (syncAction === "synced" && action !== "cloned") action = "synced";
+  return {
+    applied: true,
+    action,
+    rootPath,
+    remoteUrl,
+    ...(manifest.ref ? { ref: manifest.ref } : {}),
+    headSha: (await 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}`);
+  }
+}
+
+async function cloneRoot(manifest: ProjectAcquisitionManifest, baseDir: string): Promise<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 = await 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)}`);
+  }
+}
+
+async function syncRoot(manifest: ProjectAcquisitionManifest): Promise<"synced" | "noop"> {
+  const rootPath = resolve(manifest.rootPath);
+  await assertExistingGitRoot(rootPath);
+  await assertRemote(rootPath, manifest.remoteUrl.trim());
+  const status = await 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 = await git(["fetch", "--prune", "origin"], rootPath);
+  if (!fetch.ok) throw new Error(`git fetch failed for ${rootPath}: ${fetch.stderr || fetch.stdout}`);
+  const target = await checkoutSyncTarget(rootPath, manifest.ref);
+  if (!target) return "noop";
+  const head = await requireGit(["rev-parse", "HEAD"], rootPath);
+  const targetHead = await requireGit(["rev-parse", target], rootPath);
+  if (head === targetHead) return "noop";
+  if (!(await 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 = await 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";
+}
+
+async function assertExistingGitRoot(rootPath: string): Promise<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 = await 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}`);
+}
+
+async function assertRemote(rootPath: string, remoteUrl: string): Promise<void> {
+  const current = await 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()}`);
+  }
+}
+
+async function checkoutSyncTarget(rootPath: string, ref: string | undefined): Promise<string | undefined> {
+  if (ref?.trim()) {
+    const name = ref.trim();
+    const remoteBranch = `refs/remotes/origin/${name}`;
+    if ((await git(["show-ref", "--verify", "--quiet", remoteBranch], rootPath)).ok) {
+      if ((await git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`], rootPath)).ok) {
+        const checked = await git(["checkout", name], rootPath);
+        if (!checked.ok) throw new Error(`git checkout ${name} failed for ${rootPath}: ${checked.stderr || checked.stdout}`);
+      } else {
+        const checked = await 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 ((await git(["rev-parse", "--verify", name], rootPath)).ok) {
+      const checked = await 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 = await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], rootPath);
+  if (upstream.ok && upstream.stdout) return upstream.stdout;
+  const originHead = await 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`);
+}
+
+async function runGit(args: string[], cwd: string): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  return await execProcess(["git", ...args], { cwd });
+}
+
+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";