agent-relay-orchestrator 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.7"
+    "agent-relay-sdk": "0.2.9"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api.ts

@@ -1,4 +1,5 @@
 import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { stringValue } from "agent-relay-sdk";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import type { ServerWebSocket } from "bun";
 import { proxyArtifactRequest } from "./artifact-proxy";
@@ -797,7 +798,3 @@ function cleanTerminalGuestInput(value: unknown): { agentId?: string; policyName
   }
   return result;
 }
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}

package/src/artifact-proxy.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import type { OrchestratorConfig } from "./config";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 const SAFE_ARTIFACT_ID = /^[a-zA-Z0-9._-]{1,160}$/;
 const CONTENT_ROUTE = /^\/api\/artifacts\/([^/]+)\/content$/;
@@ -77,7 +78,7 @@ function forwardHeaders(req: Request, config: OrchestratorConfig): Headers {
     if (value) headers.set(name, value);
   }
   const token = config.token || req.headers.get("x-agent-relay-token");
-  if (token) headers.set("X-Agent-Relay-Token", token);
+  if (token) headers.set(RELAY_TOKEN_HEADER, token);
   return headers;
 }
 

package/src/control.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "agent-relay-sdk";
 import type { OrchestratorConfig } from "./config";
 import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
@@ -115,6 +116,7 @@ export function createControlHandler(
           baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
           strategy: command.params.strategy === "pr" || command.params.strategy === "rebase-ff" || command.params.strategy === "auto" ? command.params.strategy : undefined,
           deleteBranch: command.params.deleteBranch !== false,
+          push: command.params.push !== false,
           prTitle: typeof command.params.prTitle === "string" ? command.params.prTitle : undefined,
           prBody: typeof command.params.prBody === "string" ? command.params.prBody : undefined,
         });
@@ -183,6 +185,7 @@ export function spawnOptionsFromControl(ctrl: Record<string, any>, config: Orche
     effort: typeof ctrl.effort === "string" ? ctrl.effort : undefined,
     profile: typeof ctrl.profile === "string" ? ctrl.profile : undefined,
     workspaceMode: workspaceMode(ctrl.workspaceMode),
+    workspaceSymlinks: stringArray(ctrl.workspaceSymlinks),
     agentProfile: isRecord(ctrl.agentProfile) ? ctrl.agentProfile : undefined,
     label: typeof ctrl.label === "string" ? ctrl.label : undefined,
     agentId: typeof ctrl.agentId === "string" ? ctrl.agentId : undefined,
@@ -209,6 +212,7 @@ export function spawnOptionsFromRestartSource(restartSource: Record<string, any>
     effort: typeof restartSource.effort === "string" ? restartSource.effort : undefined,
     profile: typeof restartSource.profile === "string" ? restartSource.profile : undefined,
     workspaceMode: workspaceMode(restartSource.workspaceMode),
+    workspaceSymlinks: stringArray(restartSource.workspaceSymlinks),
     agentProfile: isRecord(restartSource.agentProfile) ? restartSource.agentProfile : undefined,
     label: typeof restartSource.label === "string" ? restartSource.label : undefined,
     agentId: typeof restartSource.agentId === "string" ? restartSource.agentId : undefined,
@@ -243,7 +247,3 @@ function stringArray(value: unknown): string[] | undefined {
 function workspaceMode(value: unknown): SpawnOptions["workspaceMode"] {
   return value === "isolated" || value === "shared" || value === "inherit" ? value : undefined;
 }
-
-function isRecord(value: unknown): value is Record<string, any> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

package/src/relay.ts

@@ -2,7 +2,8 @@ import type { OrchestratorConfig } from "./config";
 import type { ProviderProbeCache } from "./provider-probe";
 import { detectSelfSupervision } from "./self-supervision";
 import { GIT_SHA, ORCHESTRATOR_PROTOCOL_VERSION, VERSION, runtimeMetadata } from "./version";
-import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+import type { WorkspaceMetadata, WorkspaceMode, ManagedSessionExitDiagnostics as SdkManagedSessionExitDiagnostics } from "agent-relay-sdk";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 export interface RelayClient {
   register(): Promise<void>;
@@ -46,46 +47,8 @@ export interface ManagedAgentReport {
   startedAt: number;
 }
 
-export interface ManagedSessionExitDiagnostics {
-  agentId: string;
-  provider: "claude" | "codex";
-  workspaceMode?: WorkspaceMode;
-  workspace?: WorkspaceMetadata;
-  sessionName?: string;
-  tmuxSession: string;
-  cwd: string;
-  label?: string;
-  policyName?: string;
-  spawnRequestId?: string;
-  automationRunId?: string;
-  supervisor: "process" | "systemd" | "launchd" | "unknown";
-  systemdUnit?: string;
-  terminalSession?: string;
-  terminalAvailable?: boolean;
-  pid?: number;
-  currentPid?: number;
-  startedAt: number;
-  detectedAt: number;
-  runtimeMs: number;
-  logFile?: string;
-  logBytes?: number;
-  logEmpty?: boolean;
-  logTail?: string[];
-  runnerInfoFile?: string;
-  runnerInfoPresent?: boolean;
-  systemd?: {
-    unit: string;
-    activeState?: string;
-    subState?: string;
-    result?: string;
-    execMainCode?: string;
-    execMainStatus?: string;
-    mainPid?: number;
-    unavailable?: string;
-  };
-  unavailable?: string[];
-  lastError: string;
-}
+// Canonical shape lives in agent-relay-sdk — alias and re-export, never re-declare.
+export type ManagedSessionExitDiagnostics = SdkManagedSessionExitDiagnostics;
 
 export interface RelayCommand {
   id: string;
@@ -133,7 +96,7 @@ export function createRelayClient(config: OrchestratorConfig, probeCache: Provid
   function headers(): Record<string, string> {
     const h: Record<string, string> = { "Content-Type": "application/json" };
     const token = runtimeToken ?? config.token;
-    if (token) h["X-Agent-Relay-Token"] = token;
+    if (token) h[RELAY_TOKEN_HEADER] = token;
     return h;
   }
 

package/src/spawn.ts

@@ -16,6 +16,8 @@ export interface SpawnOptions {
   profile?: string;
   workspaceMode?: WorkspaceMode;
   workspace?: WorkspaceMetadata;
+  /** Untracked files/dirs to symlink from main into an isolated worktree (relay's global workspace config). */
+  workspaceSymlinks?: string[];
   agentProfile?: Record<string, unknown>;
   label?: string;
   agentId?: string;
@@ -361,6 +363,7 @@ export async function spawnAgent(
   const resolvedWorkspace = await resolveSpawnWorkspace({
     ...opts,
     label,
+    workspaceSymlinks: opts.workspaceSymlinks,
     workspaceRoot: join(resolve(config.baseDir), ".agent-relay", "workspaces"),
   });
   const spawnOpts = { ...opts, label, agentId, cwd: resolvedWorkspace.cwd, workspace: resolvedWorkspace.workspace };

package/src/version.ts

@@ -1,15 +1,17 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
 
 export const PACKAGE_NAME = pkg.name || "agent-relay-orchestrator";
 export const VERSION = pkg.version || "0.0.0";
-export const ORCHESTRATOR_PROTOCOL_VERSION = 3;
-export const RUNNER_PROTOCOL_VERSION = 1;
-export const PROVIDER_PLUGIN_PROTOCOL_VERSION = 1;
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const ORCHESTRATOR_PROTOCOL_VERSION = CONTRACT_VERSIONS.orchestratorProtocol;
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
 export const GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
 
 export const CONTRACTS = {

package/src/workspace-probe.ts

@@ -1,8 +1,8 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, statSync, symlinkSync, type Dirent } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
-import type { WorkspaceDepsProvision, WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus } from "agent-relay-sdk";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import type { WorkspaceDepsProvision, WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus, WorkspaceSymlinkProvision } from "agent-relay-sdk";
 
 const MAX_DIFF_PATCH_BYTES = 200_000;
 
@@ -13,6 +13,7 @@ interface WorkspaceResolutionInput {
   spawnRequestId?: string;
   workspaceMode?: WorkspaceMode;
   workspaceRoot?: string;
+  workspaceSymlinks?: string[];
   automationId?: string;
   automationRunId?: string;
 }
@@ -134,6 +135,10 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
   // runner so the agent can typecheck/test/build without manual setup (#159).
   const deps = provisionWorkspaceDeps(repoRoot, worktreePath);
 
+  // Symlink configured untracked paths (AGENTS.md, .claude-rig, …) from main. Like
+  // node_modules, these are gitignored so the fresh worktree lacks them (#159 follow-up).
+  const symlinks = provisionWorkspaceSymlinks(repoRoot, worktreePath, input.workspaceSymlinks ?? []);
+
   return {
     cwd: worktreePath,
     workspace: {
@@ -148,6 +153,7 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
       baseSha,
       status: "active",
       deps,
+      ...(symlinks.linked.length || symlinks.errors ? { symlinks } : {}),
       probe,
     },
   };
@@ -226,6 +232,74 @@ function symlinkNodeModules(repoRoot: string, worktreePath: string): string[] {
   return linked;
 }
 
+const GLOB_META = /[*?[\]{}!()]/;
+
+/**
+ * Resolve one config entry to the relative paths it covers within `repoRoot`.
+ * Plain entries are taken literally (match files AND dirs via existsSync); entries
+ * with glob metacharacters are expanded against main with dotfiles included. Anything
+ * that resolves outside the repo (absolute / `..` traversal) or doesn't exist is dropped.
+ */
+function resolveSymlinkPattern(repoRoot: string, pattern: string): string[] {
+  const within = (rel: string): boolean => {
+    const abs = resolve(repoRoot, rel);
+    const back = relative(repoRoot, abs);
+    return back !== "" && !back.startsWith("..") && !isAbsolute(back);
+  };
+
+  if (GLOB_META.test(pattern)) {
+    const matches: string[] = [];
+    for (const rel of new Bun.Glob(pattern).scanSync({ cwd: repoRoot, dot: true, onlyFiles: false })) {
+      if (within(rel)) matches.push(rel);
+    }
+    return matches;
+  }
+
+  if (!within(pattern)) return [];
+  return existsSync(join(repoRoot, pattern)) ? [pattern] : [];
+}
+
+/**
+ * Symlink configured untracked files/dirs from the main checkout into a fresh isolated
+ * worktree. Only links paths that exist in main and aren't already present in the worktree
+ * (git-tracked files are left untouched). Best-effort: a failed link never blocks the spawn.
+ */
+export function provisionWorkspaceSymlinks(
+  repoRoot: string,
+  worktreePath: string,
+  patterns: string[],
+): WorkspaceSymlinkProvision {
+  const linked: string[] = [];
+  const seen = new Set<string>();
+  const errors: string[] = [];
+
+  for (const pattern of patterns) {
+    let rels: string[];
+    try {
+      rels = resolveSymlinkPattern(repoRoot, pattern);
+    } catch (error) {
+      errors.push(`${pattern}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    for (const rel of rels) {
+      if (seen.has(rel)) continue;
+      seen.add(rel);
+      const source = join(repoRoot, rel);
+      const target = join(worktreePath, rel);
+      if (pathExists(target)) continue; // git-tracked or already linked — don't clobber
+      try {
+        mkdirSync(dirname(target), { recursive: true });
+        symlinkSync(source, target, lstatSync(source).isDirectory() ? "dir" : "file");
+        linked.push(rel);
+      } catch (error) {
+        errors.push(`${rel}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  return errors.length ? { linked, errors } : { linked };
+}
+
 /** Run a package install in each dir that owns a lockfile. Root install covers
  * the package manager's workspace members; standalone sub-projects with their
  * own lockfile (e.g. dashboard) get a separate install. */
@@ -320,6 +394,8 @@ export function workspaceGitState(input: { worktreePath?: string; baseRef?: stri
   const dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
 
   const state: WorkspaceGitState = { dirty: dirtyCount > 0, dirtyCount };
+  const liveBranch = shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], path).stdout || undefined);
+  if (liveBranch) state.branch = liveBranch;
 
   const log = git(["log", "-1", "--format=%H%x1f%ct%x1f%s"], path);
   if (log.ok && log.stdout) {
@@ -478,10 +554,22 @@ interface WorkspaceMergeInput {
   baseSha?: string;
   strategy?: "pr" | "rebase-ff" | "auto";
   deleteBranch?: boolean;
+  /** Push the advanced base to its upstream (origin) after a rebase-ff land.
+   * Defaults to true; auto-skipped when base has no upstream. Disable with
+   * AGENT_RELAY_WORKSPACE_PUSH=0. */
+  push?: boolean;
   prTitle?: string;
   prBody?: string;
 }
 
+/** Behind-count of HEAD relative to `base`, from inside `worktreePath`. */
+function countBehind(worktreePath: string, base: string): number {
+  const counts = git(["rev-list", "--left-right", "--count", `${base}...HEAD`], worktreePath);
+  if (!counts.ok || !counts.stdout) return 0;
+  const behind = Number(counts.stdout.split(/\s+/)[0]);
+  return Number.isFinite(behind) ? behind : 0;
+}
+
 function hasOriginRemote(cwd: string): boolean {
   return git(["remote", "get-url", "origin"], cwd).ok;
 }
@@ -605,7 +693,8 @@ export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?:
 /**
  * Integrate a workspace's work back into its base branch. Two strategies:
  *  - rebase-ff: rebase the agent branch onto base, fast-forward base to it,
- *    then remove the worktree and delete the branch. Lands work locally.
+ *    push base to origin, then (unless deleteBranch is false) remove the worktree
+ *    and delete the branch. Lands work locally and publishes it.
  *  - pr: push the branch to origin and open a PR via gh. Leaves the worktree
  *    and branch intact (the PR needs them).
  * Refuses on a dirty worktree, predicted conflicts, or nothing to merge. Never
@@ -668,8 +757,24 @@ function mergeRebaseFf(
   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" });
 
+  // Reconcile with origin before landing (#190/#203). When base tracks an
+  // upstream (e.g. main -> origin/main) and we'll push, fetch it and refuse if
+  // origin has moved ahead of local base: pushing would then be a non-fast-forward,
+  // and we won't rewrite published history or strand a local-only land. The
+  // refusal happens BEFORE we mutate anything, so a diverged base is a clean no-op.
+  const upstream = upstreamRef(worktreePath, base);
+  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 && process.env.AGENT_RELAY_WORKSPACE_PUSH !== "0" && Boolean(remote);
+  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) {
+      return head({ status: "review_requested", error: `origin moved ahead of local ${base}; sync ${base} with ${upstream} before landing` });
+    }
+  }
+
   // Rebase the agent branch onto base so base can fast-forward to it.
-  if ((preview.behind ?? 0) > 0) {
+  if (countBehind(worktreePath, base) > 0) {
     const rebase = git(["rebase", base], worktreePath);
     if (!rebase.ok) {
       git(["rebase", "--abort"], worktreePath);
@@ -691,16 +796,38 @@ function mergeRebaseFf(
     if (!update.ok) return head({ status: "review_requested", error: update.stderr || "failed to advance base ref" });
   }
 
-  // Work is landed. Tear down the worktree and delete the agent branch.
+  // Publish the advanced base so local and origin converge (#190). We verified
+  // origin was an ancestor of base above, so this is a fast-forward; a failure
+  // means origin raced us — surface it instead of claiming an unpublished land.
+  let pushed = false;
+  if (upstream && remote && pushEnabled) {
+    const push = git(["push", remote, `${base}:${base}`], worktreePath);
+    if (!push.ok) return head({ status: "review_requested", mergedSha: headSha, error: push.stderr || `git push to ${remote}/${base} failed` });
+    pushed = true;
+  }
+
+  // Work is landed (and published). Tear down only when the owner is gone:
+  // deleteBranch is false for a live owner (the relay sets it from owner liveness,
+  // #204). A live owner keeps its worktree and is recycled onto a fresh branch cut
+  // from the advanced base (#206) so it continues the next task from clean, current
+  // state in the same CWD; status returns to `active`. An absent owner gets the
+  // worktree reclaimed.
   const deleteBranch = input.deleteBranch !== false;
-  let worktreeRemoved = false;
-  let branchDeleted = false;
-  if (deleteBranch) {
-    const removed = git(["worktree", "remove", "--force", worktreePath], repoRoot);
-    worktreeRemoved = removed.ok;
-    if (worktreeRemoved) branchDeleted = git(["branch", "-D", branch], repoRoot).ok;
+  if (!deleteBranch) {
+    const fresh = nextBranchName(repoRoot, branch);
+    const switched = git(["checkout", "-B", fresh, base], worktreePath);
+    if (switched.ok) {
+      // The old branch now equals base (just fast-forwarded) — drop the litter.
+      const oldDeleted = git(["branch", "-D", branch], repoRoot).ok;
+      return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branch: fresh, newBranch: fresh, branchDeleted: oldDeleted, pushed, error: undefined });
+    }
+    // Recycle failed — keep the existing branch. Still landed, still active.
+    return head({ merged: true, status: "active", mergedSha: headSha, worktreeRemoved: false, branchDeleted: false, pushed, error: undefined });
   }
-  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, 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, worktreeRemoved, branchDeleted, pushed, error: undefined });
 }
 
 async function availableBranch(repoRoot: string, base: string): Promise<string> {
@@ -722,6 +849,17 @@ function branchName(input: WorkspaceResolutionInput, id: string): string {
   return `agent/${safeSegment(owner, 48)}/${safeSegment(id.replace(/^sp[_-]?/, ""), 24)}`;
 }
 
+/** Next free `<branch>-N` cycle name for a recycled worktree (#206). Strips any
+ * existing -N suffix so cycles increment instead of nesting. */
+function nextBranchName(repoRoot: string, branch: string): string {
+  const stem = branch.replace(/-\d+$/, "");
+  for (let i = 2; i < 1000; i++) {
+    const candidate = `${stem}-${i}`;
+    if (!git(["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`], repoRoot).ok) return candidate;
+  }
+  return `${stem}-${Date.now()}`;
+}
+
 function repoSlug(repoRoot: string): string {
   const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 10);
   return `${safeSegment(basename(repoRoot), 60)}-${hash}`;