agent-relay-orchestrator 0.120.2 → 0.120.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.120.2",
+  "version": "0.120.4",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.3",
-    "agent-relay-sdk": "0.2.108",
+    "agent-relay-sdk": "0.2.109",
     "callmux": "0.23.0"
   },
   "devDependencies": {

package/src/spawn/acquisition.ts

@@ -6,13 +6,19 @@ import { git, requireGit } from "../git";
 import { execProcess } from "../process";
 import type { ProjectAcquisitionManifest } from "./types";
 
+export type ProjectRootSyncAction = "synced" | "noop" | "skipped-dirty" | "skipped-diverged";
+
 export interface ProjectAcquisitionResult {
   applied: boolean;
   action: "cloned" | "synced" | "noop";
+  syncAction: ProjectRootSyncAction;
   rootPath: string;
   remoteUrl: string;
   ref?: string;
   headSha?: string;
+  baseRef?: string;
+  baseSha?: string;
+  syncTarget?: string;
 }
 
 const inFlight = new Map<string, Promise<ProjectAcquisitionResult>>();
@@ -68,15 +74,19 @@ async function applyManifestLocked(manifest: ProjectAcquisitionManifest, baseDir
     await cloneRoot(manifest, baseDir);
     action = "cloned";
   }
-  const syncAction = await syncRoot(manifest);
-  if (syncAction === "synced" && action !== "cloned") action = "synced";
+  const sync = await syncRoot(manifest);
+  if (sync.action === "synced" && action !== "cloned") action = "synced";
   return {
     applied: true,
     action,
+    syncAction: sync.action,
     rootPath,
     remoteUrl,
     ...(manifest.ref ? { ref: manifest.ref } : {}),
     headSha: (await git(["rev-parse", "HEAD"], rootPath)).stdout || undefined,
+    ...(sync.baseRef ? { baseRef: sync.baseRef } : {}),
+    ...(sync.baseSha ? { baseSha: sync.baseSha } : {}),
+    ...(sync.target ? { syncTarget: sync.target } : {}),
   };
 }
 
@@ -114,26 +124,48 @@ async function cloneRoot(manifest: ProjectAcquisitionManifest, baseDir: string):
   }
 }
 
-async function syncRoot(manifest: ProjectAcquisitionManifest): Promise<"synced" | "noop"> {
+interface SyncTarget {
+  target?: string;
+  branch?: string;
+  baseRef?: string;
+}
+
+interface RootSyncResult extends SyncTarget {
+  action: ProjectRootSyncAction;
+  baseSha?: string;
+}
+
+async function syncRoot(manifest: ProjectAcquisitionManifest): Promise<RootSyncResult> {
   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 target = await resolveSyncTarget(rootPath, manifest.ref);
+  const baseSha = target.target ? await requireGit(["rev-parse", target.target], rootPath) : undefined;
+  const status = await git(["status", "--porcelain"], rootPath);
+  if (!status.ok) throw new Error(`git status failed for ${rootPath}: ${status.stderr}`);
+  if (status.stdout.trim()) {
+    warnSyncSkipped(rootPath, target.target, "skipped-dirty", "local changes");
+    return { ...target, action: "skipped-dirty", ...(baseSha ? { baseSha } : {}) };
+  }
+  if (!target.target) return { ...target, action: "noop", ...(baseSha ? { baseSha } : {}) };
+
+  const localRef = target.branch && await localBranchExists(rootPath, target.branch) ? `refs/heads/${target.branch}` : "HEAD";
+  const head = await requireGit(["rev-parse", localRef], rootPath);
+  if (!baseSha || head === baseSha) return { ...target, action: "noop", ...(baseSha ? { baseSha } : {}) };
+  if (!(await git(["merge-base", "--is-ancestor", localRef, target.target], rootPath)).ok) {
+    warnSyncSkipped(rootPath, target.target, "skipped-diverged", `${localRef} is ahead of or diverged from target`);
+    return { ...target, action: "skipped-diverged", baseSha };
   }
-  const merged = await git(["merge", "--ff-only", target], rootPath);
+
+  if (target.branch) {
+    const checked = await checkoutBranchForSync(rootPath, target.branch, target.target);
+    if (!checked.ok) throw new Error(`git checkout ${target.branch} failed for ${rootPath}: ${checked.stderr || checked.stdout}`);
+  }
+  const merged = await git(["merge", "--ff-only", target.target], rootPath);
   if (!merged.ok) throw new Error(`git ff-only sync failed for ${rootPath}: ${merged.stderr || merged.stdout}`);
-  return "synced";
+  return { ...target, action: "synced", baseSha };
 }
 
 async function assertExistingGitRoot(rootPath: string): Promise<void> {
@@ -156,34 +188,44 @@ async function assertRemote(rootPath: string, remoteUrl: string): Promise<void>
   }
 }
 
-async function checkoutSyncTarget(rootPath: string, ref: string | undefined): Promise<string | undefined> {
+async function resolveSyncTarget(rootPath: string, ref: string | undefined): Promise<SyncTarget> {
   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}`;
+      return { target: `origin/${name}`, branch: name, baseRef: 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;
+      return {};
     }
     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;
+  if (upstream.ok && upstream.stdout) return { target: upstream.stdout, baseRef: remoteBranchName(upstream.stdout) };
   const originHead = await git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], rootPath);
-  if (originHead.ok && originHead.stdout) return originHead.stdout;
+  if (originHead.ok && originHead.stdout) return { target: originHead.stdout, baseRef: remoteBranchName(originHead.stdout) };
   throw new Error(`project root ${rootPath} has no upstream or origin/HEAD for ff-only sync`);
 }
 
+async function localBranchExists(rootPath: string, branch: string): Promise<boolean> {
+  return (await git(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], rootPath)).ok;
+}
+
+async function checkoutBranchForSync(rootPath: string, branch: string, target: string): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  if (await localBranchExists(rootPath, branch)) return await git(["checkout", branch], rootPath);
+  return await git(["checkout", "-B", branch, target], rootPath);
+}
+
+function remoteBranchName(ref: string | undefined): string | undefined {
+  const trimmed = ref?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.startsWith("origin/") ? trimmed.slice("origin/".length) : trimmed;
+}
+
+function warnSyncSkipped(rootPath: string, target: string | undefined, action: ProjectRootSyncAction, reason: string): void {
+  console.warn(`[orchestrator] project acquisition root sync ${action} for ${rootPath}${target ? ` -> ${target}` : ""}: ${reason}`);
+}
+
 async function runGit(args: string[], cwd: string): Promise<{ ok: boolean; stdout: string; stderr: string }> {
   return await execProcess(["git", ...args], { cwd });
 }

package/src/spawn/spawn-agent.ts

@@ -52,7 +52,7 @@ export async function spawnAgent(
   if (!isWithinBaseDir(opts.cwd, config.baseDir)) {
     throw new Error(`cwd must be within base directory: ${config.baseDir}`);
   }
-  await d.applyProjectAcquisitionManifest(opts.acquisition, config.baseDir);
+  const acquisition = await d.applyProjectAcquisitionManifest(opts.acquisition, config.baseDir);
   if (!existsSync(opts.cwd)) {
     throw new Error(`cwd does not exist: ${opts.cwd}`);
   }
@@ -63,6 +63,7 @@ export async function spawnAgent(
     ...opts,
     label,
     workspaceSymlinks: opts.workspaceSymlinks,
+    ...(acquisition?.baseRef && acquisition.baseSha ? { baseRef: acquisition.baseRef, baseSha: acquisition.baseSha } : {}),
     workspaceRoot: workspacesRoot(config.baseDir),
   });
   if (resolvedWorkspace.reusedExisting) {

package/src/workspace-probe/probe.ts

@@ -139,8 +139,8 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
 
   const id = workspaceId(input);
   const repoRoot = probe.repoRoot;
-  const baseRef = await terminalBaseRef(repoRoot, probe.branch);
-  const baseSha = probe.headSha ?? await requireGit(["rev-parse", "HEAD"], repoRoot);
+  const baseRef = input.baseRef ?? await terminalBaseRef(repoRoot, probe.branch);
+  const baseSha = input.baseSha ?? probe.headSha ?? await requireGit(["rev-parse", "HEAD"], repoRoot);
   const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : workspacesRoot(homedir());
   const worktreePath = join(workspaceRoot, repoSlug(repoRoot), id);
   const existing = await existingRegisteredWorktree(repoRoot, worktreePath);

package/src/workspace-probe/types.ts

@@ -24,6 +24,9 @@ export interface WorkspaceResolutionInput {
   workspaceMode?: WorkspaceMode;
   workspaceRoot?: string;
   workspaceSymlinks?: string[];
+  /** Preferred base for a fresh isolated worktree, e.g. fetched origin/main after project acquisition. */
+  baseRef?: string;
+  baseSha?: string;
   automationId?: string;
   automationRunId?: string;
   /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */