agent-relay-orchestrator 0.10.19 → 0.10.21

package/src/version.ts

@@ -3,8 +3,37 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { version?: string };
+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;
 export const GIT_SHA = process.env.AGENT_RELAY_GIT_SHA || process.env.GIT_SHA || undefined;
+
+export const CONTRACTS = {
+  orchestratorProtocol: ORCHESTRATOR_PROTOCOL_VERSION,
+  runnerProtocol: RUNNER_PROTOCOL_VERSION,
+  providerPluginProtocol: PROVIDER_PLUGIN_PROTOCOL_VERSION,
+} as const;
+
+export const RUNTIME_CAPABILITIES = {
+  directoryBrowse: true,
+  relayCommandBus: true,
+  authenticatedLogProxy: true,
+  artifactProxy: true,
+  managedAgentReports: true,
+  durableRunnerSupervisor: true,
+} as const;
+
+export function runtimeMetadata() {
+  return {
+    package: {
+      name: PACKAGE_NAME,
+      version: VERSION,
+    },
+    contracts: CONTRACTS,
+    capabilities: RUNTIME_CAPABILITIES,
+  };
+}

package/src/workspace-probe.ts

@@ -0,0 +1,513 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import type { WorkspaceDiff, WorkspaceDiffFile, WorkspaceGitState, WorkspaceMergePreview, WorkspaceMergeResult, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceProbeWorktree, WorkspaceStatus } from "agent-relay-sdk";
+
+const MAX_DIFF_PATCH_BYTES = 200_000;
+
+interface WorkspaceResolutionInput {
+  cwd: string;
+  label?: string;
+  policyName?: string;
+  spawnRequestId?: string;
+  workspaceMode?: WorkspaceMode;
+  workspaceRoot?: string;
+  automationId?: string;
+  automationRunId?: string;
+}
+
+interface WorkspaceResolution {
+  cwd: string;
+  workspace: WorkspaceMetadata;
+}
+
+interface GitResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+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(),
+  };
+}
+
+function requireGit(args: string[], cwd: string): string {
+  const result = git(args, cwd);
+  if (!result.ok) throw new Error(result.stderr || `git ${args.join(" ")} failed`);
+  return result.stdout;
+}
+
+function shortBranch(ref: string | undefined): string | undefined {
+  if (!ref || ref === "HEAD") return undefined;
+  return ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+}
+
+function parseWorktrees(output: string): WorkspaceProbeWorktree[] {
+  const blocks = output.split(/\n\s*\n/).map((block) => block.trim()).filter(Boolean);
+  return blocks.map((block) => {
+    const worktree: WorkspaceProbeWorktree = { path: "" };
+    for (const line of block.split("\n")) {
+      if (line.startsWith("worktree ")) worktree.path = line.slice("worktree ".length);
+      else if (line.startsWith("HEAD ")) worktree.headSha = line.slice("HEAD ".length);
+      else if (line.startsWith("branch ")) worktree.branch = shortBranch(line.slice("branch ".length));
+      else if (line === "bare") worktree.bare = true;
+      else if (line === "detached") worktree.detached = true;
+      else if (line.startsWith("prunable")) {
+        worktree.prunable = true;
+        const reason = line.slice("prunable".length).trim();
+        if (reason) worktree.reason = reason;
+      } else if (line.startsWith("locked")) {
+        worktree.locked = true;
+        const reason = line.slice("locked".length).trim();
+        if (reason) worktree.reason = reason;
+      }
+    }
+    return worktree;
+  }).filter((worktree) => worktree.path);
+}
+
+export async function probeWorkspace(requestedPath: string): Promise<WorkspaceProbe> {
+  const path = resolve(requestedPath);
+  try {
+    const stat = statSync(path);
+    if (!stat.isDirectory()) return { path, isGitRepo: false, error: `Not a directory: ${path}` };
+  } catch (error) {
+    return { path, isGitRepo: false, error: error instanceof Error ? error.message : String(error) };
+  }
+
+  const root = git(["rev-parse", "--show-toplevel"], path);
+  if (!root.ok || !root.stdout) return { path, isGitRepo: false };
+
+  const repoRoot = root.stdout;
+  const branchRef = git(["symbolic-ref", "--quiet", "--short", "HEAD"], repoRoot);
+  const head = git(["rev-parse", "HEAD"], repoRoot);
+  const status = git(["status", "--porcelain"], repoRoot);
+  const worktrees = git(["worktree", "list", "--porcelain"], repoRoot);
+  const branch = shortBranch(branchRef.stdout);
+
+  return {
+    path,
+    isGitRepo: true,
+    repoRoot,
+    ...(branch ? { branch } : {}),
+    ...(head.ok && head.stdout ? { headSha: head.stdout } : {}),
+    dirty: status.ok ? status.stdout.length > 0 : undefined,
+    detached: !branch,
+    ...(worktrees.ok ? { worktrees: parseWorktrees(worktrees.stdout) } : {}),
+  };
+}
+
+export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Promise<WorkspaceResolution> {
+  const requestedMode = input.workspaceMode ?? "inherit";
+  const sourceCwd = resolve(input.cwd);
+  const probe = await probeWorkspace(sourceCwd);
+  const inheritedMode = input.policyName || input.automationRunId ? "isolated" : "shared";
+  const mode: WorkspaceMode = requestedMode === "inherit" ? inheritedMode : requestedMode;
+  if (mode !== "isolated" || !probe.isGitRepo || !probe.repoRoot) {
+    return {
+      cwd: sourceCwd,
+      workspace: { mode: "shared", requestedMode, sourceCwd, probe },
+    };
+  }
+
+  const id = workspaceId(input);
+  const repoRoot = probe.repoRoot;
+  const baseSha = probe.headSha ?? requireGit(["rev-parse", "HEAD"], repoRoot);
+  const branch = await availableBranch(repoRoot, branchName(input, id));
+  const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : join(homedir(), ".agent-relay", "workspaces");
+  const worktreePath = join(workspaceRoot, repoSlug(repoRoot), id);
+  mkdirSync(join(worktreePath, ".."), { recursive: true });
+  requireGit(["worktree", "add", "-b", branch, worktreePath, baseSha], repoRoot);
+
+  return {
+    cwd: worktreePath,
+    workspace: {
+      id,
+      mode: "isolated",
+      requestedMode,
+      repoRoot,
+      sourceCwd,
+      worktreePath,
+      branch,
+      baseRef: probe.branch,
+      baseSha,
+      status: "active",
+      probe,
+    },
+  };
+}
+
+export function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; deleteBranch?: boolean }): { workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean } {
+  if (!workspace.worktreePath) throw new Error("worktreePath required");
+  const path = resolve(workspace.worktreePath);
+  const repo = workspace.repoRoot ? resolve(workspace.repoRoot) : path;
+  const result = git(["worktree", "remove", "--force", path], repo);
+  if (!result.ok) throw new Error(result.stderr || `failed to remove workspace ${path}`);
+  // Once the worktree is gone the agent/... branch is litter — delete it so
+  // branches don't accumulate. Best-effort: don't fail cleanup if it can't
+  // (e.g. branch already gone, or checked out elsewhere).
+  let branchDeleted = false;
+  if (workspace.branch && workspace.deleteBranch !== false) {
+    branchDeleted = git(["branch", "-D", workspace.branch], repo).ok;
+  }
+  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted };
+}
+
+/**
+ * Read-only git interrogation of a worktree: how much work it holds (commits
+ * ahead/behind base, dirty files, last commit). Computed on the host because
+ * that is where git and the worktree live. Never throws — failures land in the
+ * returned `error`/`missing` fields so callers can degrade gracefully.
+ */
+export function workspaceGitState(input: { worktreePath?: string; baseRef?: string; baseSha?: string }): WorkspaceGitState {
+  if (!input.worktreePath) return { error: "worktreePath required" };
+  const path = resolve(input.worktreePath);
+  if (!existsSync(path)) return { missing: true };
+
+  const status = git(["status", "--porcelain"], path);
+  if (!status.ok) return { error: status.stderr || "git status failed" };
+  const dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+
+  const state: WorkspaceGitState = { dirty: dirtyCount > 0, dirtyCount };
+
+  const log = git(["log", "-1", "--format=%H%x1f%ct%x1f%s"], path);
+  if (log.ok && log.stdout) {
+    const [sha, ct, ...rest] = log.stdout.split("\x1f");
+    if (sha) {
+      const at = Number(ct) * 1000;
+      state.lastCommit = { sha, message: rest.join("\x1f"), ...(Number.isFinite(at) ? { at } : {}) };
+    }
+  }
+
+  // Resolve a base to diff against: prefer the named branch (gives real behind
+  // counts), fall back to the fork SHA (behind is then always 0, ahead is the
+  // agent's new commits — still the signal we care about for cleanup).
+  const base = resolveBaseRef(path, input.baseRef, input.baseSha);
+  if (base) {
+    state.baseRef = base;
+    const counts = git(["rev-list", "--left-right", "--count", `${base}...HEAD`], path);
+    if (counts.ok && counts.stdout) {
+      const [behind, ahead] = counts.stdout.split(/\s+/).map((n) => Number(n));
+      if (Number.isFinite(behind)) state.behind = behind;
+      if (Number.isFinite(ahead)) state.ahead = ahead;
+    }
+  }
+
+  return state;
+}
+
+function resolveBaseRef(worktreePath: string, baseRef?: string, baseSha?: string): string | undefined {
+  for (const candidate of [baseRef, baseSha]) {
+    if (candidate && git(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], worktreePath).ok) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Exit-time decision for an orphaned worktree (owner agent disappeared). Probe
+ * the worktree and either remove it (genuinely empty — clean tree, no commits
+ * ahead of base) or leave it intact and report a status the relay can flag for
+ * review. Never destroys work on uncertainty: any error or unknown ahead-count
+ * results in a flag, not a delete.
+ */
+export function reconcileWorkspace(workspace: { id?: string; repoRoot?: string; worktreePath?: string; branch?: string; baseRef?: string; baseSha?: string }): {
+  workspaceId?: string;
+  removed: boolean;
+  status: WorkspaceStatus;
+  gitState: WorkspaceGitState;
+} {
+  const gitState = workspaceGitState(workspace);
+  if (gitState.missing) {
+    return { workspaceId: workspace.id, removed: false, status: "cleaned", gitState };
+  }
+  const empty = gitState.error === undefined && gitState.dirtyCount === 0 && gitState.ahead === 0;
+  if (empty) {
+    cleanupWorkspace({ id: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, branch: workspace.branch });
+    return { workspaceId: workspace.id, removed: true, status: "cleaned", gitState };
+  }
+  return { workspaceId: workspace.id, removed: false, status: "review_requested", gitState };
+}
+
+/**
+ * Diff a worktree's committed work against its base (base...HEAD): per-file
+ * line counts plus a size-capped unified patch, so the dashboard can show what
+ * an agent produced without an SSH session. Read-only; degrades into fields.
+ */
+export function workspaceDiff(input: { worktreePath?: string; baseRef?: string; baseSha?: string; includePatch?: boolean }): WorkspaceDiff {
+  if (!input.worktreePath) return { files: [], error: "worktreePath required" };
+  const path = resolve(input.worktreePath);
+  if (!existsSync(path)) return { files: [], missing: true };
+
+  const base = resolveBaseRef(path, input.baseRef, input.baseSha);
+  const range = base ? `${base}...HEAD` : "HEAD";
+  const result: WorkspaceDiff = { files: [], baseRef: base };
+
+  const status = git(["status", "--porcelain"], path);
+  if (status.ok) result.dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+
+  if (base) {
+    const counts = git(["rev-list", "--count", `${base}..HEAD`], path);
+    if (counts.ok && counts.stdout) {
+      const ahead = Number(counts.stdout);
+      if (Number.isFinite(ahead)) result.ahead = ahead;
+    }
+  }
+
+  const numstat = git(["diff", "--numstat", range], path);
+  if (!numstat.ok) return { ...result, error: numstat.stderr || "git diff failed" };
+  result.files = parseNumstat(numstat.stdout);
+
+  if (input.includePatch !== false) {
+    const patch = git(["diff", range], path);
+    if (patch.ok && patch.stdout) {
+      if (patch.stdout.length > MAX_DIFF_PATCH_BYTES) {
+        result.patch = patch.stdout.slice(0, MAX_DIFF_PATCH_BYTES);
+        result.truncated = true;
+      } else {
+        result.patch = patch.stdout;
+      }
+    }
+  }
+  return result;
+}
+
+function parseNumstat(output: string): WorkspaceDiffFile[] {
+  if (!output) return [];
+  return output.split("\n").filter(Boolean).map((line) => {
+    const [add, del, ...rest] = line.split("\t");
+    const path = rest.join("\t");
+    const binary = add === "-" && del === "-";
+    return {
+      path,
+      binary,
+      ...(binary ? {} : { additions: Number(add) || 0, deletions: Number(del) || 0 }),
+    };
+  }).filter((file) => file.path);
+}
+
+interface WorkspaceMergeInput {
+  id?: string;
+  repoRoot?: string;
+  worktreePath?: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+  strategy?: "pr" | "rebase-ff" | "auto";
+  deleteBranch?: boolean;
+  prTitle?: string;
+  prBody?: string;
+}
+
+function hasOriginRemote(cwd: string): boolean {
+  return git(["remote", "get-url", "origin"], cwd).ok;
+}
+
+function ghAvailable(): boolean {
+  return Boolean(Bun.which("gh"));
+}
+
+/**
+ * Predict whether merging the branch's commits into base would conflict, using
+ * git's three-way merge-tree (no working-tree changes). Exit 0 = clean, exit 1
+ * = conflicts. Anything else is treated as "unknown" (undefined).
+ */
+function predictConflict(worktreePath: string, base: string): boolean | undefined {
+  const result = git(["merge-tree", "--write-tree", "--name-only", base, "HEAD"], worktreePath);
+  if (result.ok) return false;
+  // git exits 1 specifically for merge conflicts; other failures are unknown.
+  return /CONFLICT|conflict/.test(result.stdout + result.stderr) || result.stdout.length > 0 ? true : undefined;
+}
+
+/** Branch name a base ref points at (only meaningful for refs/heads). */
+function baseBranchName(worktreePath: string, baseRef?: string): string | undefined {
+  if (!baseRef) return undefined;
+  const ref = baseRef.startsWith("refs/heads/") ? baseRef.slice("refs/heads/".length) : baseRef;
+  return git(["show-ref", "--verify", "--quiet", `refs/heads/${ref}`], worktreePath).ok ? ref : undefined;
+}
+
+/** Locate the worktree (if any) that currently has `branch` checked out. */
+function worktreeForBranch(repoRoot: string, branch: string): { path: string; dirty: boolean } | undefined {
+  const list = git(["worktree", "list", "--porcelain"], repoRoot);
+  if (!list.ok) return undefined;
+  const match = parseWorktrees(list.stdout).find((worktree) => worktree.branch === branch);
+  if (!match) return undefined;
+  const status = git(["status", "--porcelain"], match.path);
+  return { path: match.path, dirty: status.ok ? status.stdout.length > 0 : true };
+}
+
+/**
+ * Read-only pre-flight for integrating a workspace's work. Reports the strategy
+ * `auto` would pick plus whether the merge is clean, would conflict, or is a
+ * no-op — so the dashboard can warn before the user commits to it.
+ */
+export function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?: string; baseSha?: string; strategy?: "pr" | "rebase-ff" | "auto" }): WorkspaceMergePreview {
+  const gitState = workspaceGitState(input);
+  const remote = input.worktreePath ? hasOriginRemote(resolve(input.worktreePath)) : false;
+  const gh = ghAvailable();
+  const baseBranch = input.worktreePath ? baseBranchName(resolve(input.worktreePath), input.baseRef) : undefined;
+  // PR needs a remote, gh, and a real base branch to target; otherwise land locally.
+  const strategy: "pr" | "rebase-ff" = input.strategy === "pr" || input.strategy === "rebase-ff"
+    ? input.strategy
+    : remote && gh && baseBranch ? "pr" : "rebase-ff";
+  const base: WorkspaceMergePreview = { strategy, hasRemote: remote, ghAvailable: gh, baseRef: baseBranch ?? gitState.baseRef };
+
+  if (gitState.missing) return { ...base, missing: true, reason: "worktree no longer exists" };
+  if (gitState.error) return { ...base, error: gitState.error };
+  base.ahead = gitState.ahead;
+  base.behind = gitState.behind;
+  base.dirtyCount = gitState.dirtyCount;
+  if ((gitState.dirtyCount ?? 0) > 0) return { ...base, reason: "worktree has uncommitted changes" };
+  if ((gitState.ahead ?? 0) === 0) return { ...base, reason: "no commits to merge" };
+  if (gitState.baseRef && input.worktreePath) {
+    const conflict = predictConflict(resolve(input.worktreePath), gitState.baseRef);
+    base.conflict = conflict;
+    base.cleanFastForward = conflict === false && (gitState.behind ?? 0) === 0;
+  }
+  return base;
+}
+
+/**
+ * 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.
+ *  - 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
+ * destroys work on uncertainty.
+ */
+export function mergeWorkspace(input: WorkspaceMergeInput): 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;
+  const branch = input.branch ?? shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath).stdout || undefined);
+  const preview = previewWorkspaceMerge({ worktreePath, baseRef: input.baseRef, baseSha: input.baseSha, strategy: input.strategy });
+  const strategy = preview.strategy;
+  const head = (field: Partial<WorkspaceMergeResult>): WorkspaceMergeResult => ({ workspaceId: input.id, strategy, merged: false, status: "review_requested", branch, baseRef: preview.baseRef, ...field });
+
+  if (preview.missing) return head({ status: "cleaned", error: preview.reason });
+  if (preview.error) return head({ status: "review_requested", error: preview.error });
+  if (preview.reason) return head({ status: "review_requested", error: preview.reason });
+  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);
+}
+
+function mergePr(
+  input: WorkspaceMergeInput,
+  worktreePath: string,
+  branch: string | undefined,
+  preview: WorkspaceMergePreview,
+  head: (field: Partial<WorkspaceMergeResult>) => WorkspaceMergeResult,
+): WorkspaceMergeResult {
+  if (!branch) return head({ status: "review_requested", error: "cannot determine branch to push" });
+  const base = preview.baseRef;
+  const push = git(["push", "-u", "origin", branch], worktreePath);
+  if (!push.ok) return head({ status: "review_requested", error: push.stderr || "git push failed" });
+
+  const title = input.prTitle || git(["log", "-1", "--format=%s"], worktreePath).stdout || `Merge ${branch}`;
+  const body = input.prBody || `Automated PR for agent workspace branch \`${branch}\`.`;
+  const args = ["pr", "create", "--head", branch, "--title", title, "--body", body];
+  if (base) args.push("--base", base);
+  const proc = Bun.spawnSync(["gh", ...args], { cwd: worktreePath, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const stdout = proc.stdout.toString().trim();
+  if (proc.exitCode !== 0) {
+    return head({ status: "review_requested", error: proc.stderr.toString().trim() || "gh pr create failed" });
+  }
+  const prUrl = stdout.split("\n").map((line) => line.trim()).find((line) => /^https?:\/\//.test(line));
+  // PR opened: work is on its way out but not landed. Keep the worktree/branch
+  // alive for the PR; record the plan with the URL.
+  return head({ status: "merge_planned", prUrl, error: undefined });
+}
+
+function mergeRebaseFf(
+  input: WorkspaceMergeInput,
+  worktreePath: string,
+  repoRoot: string,
+  branch: string | undefined,
+  preview: WorkspaceMergePreview,
+  head: (field: Partial<WorkspaceMergeResult>) => WorkspaceMergeResult,
+): 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" });
+
+  // Rebase the agent branch onto base so base can fast-forward to it.
+  if ((preview.behind ?? 0) > 0) {
+    const rebase = git(["rebase", base], worktreePath);
+    if (!rebase.ok) {
+      git(["rebase", "--abort"], worktreePath);
+      return head({ conflict: true, status: "conflict", error: rebase.stderr || "rebase onto base failed" });
+    }
+  }
+  const headSha = git(["rev-parse", "HEAD"], worktreePath).stdout;
+
+  // Advance base to the rebased branch. If base is checked out somewhere, do a
+  // real ff-only merge there so its working tree stays consistent; otherwise
+  // just move the ref. Refuse if the base worktree has uncommitted changes.
+  const baseWorktree = worktreeForBranch(repoRoot, base);
+  if (baseWorktree) {
+    if (baseWorktree.dirty) return head({ status: "review_requested", error: `base branch '${base}' has uncommitted changes in ${baseWorktree.path}` });
+    const ff = git(["merge", "--ff-only", branch], baseWorktree.path);
+    if (!ff.ok) return head({ status: "review_requested", error: ff.stderr || "fast-forward into base failed" });
+  } else {
+    const update = git(["update-ref", `refs/heads/${base}`, headSha], repoRoot);
+    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.
+  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;
+  }
+  return head({ merged: true, status: "merged", mergedSha: headSha, worktreeRemoved, branchDeleted, error: undefined });
+}
+
+async function availableBranch(repoRoot: string, base: string): Promise<string> {
+  for (let i = 0; i < 50; i++) {
+    const candidate = i === 0 ? base : `${base}-${i + 1}`;
+    const existing = git(["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`], repoRoot);
+    if (!existing.ok) return candidate;
+  }
+  throw new Error(`could not find available branch name for ${base}`);
+}
+
+function workspaceId(input: WorkspaceResolutionInput): string {
+  const raw = input.spawnRequestId || input.automationRunId || crypto.randomUUID();
+  return safeSegment(raw, 80);
+}
+
+function branchName(input: WorkspaceResolutionInput, id: string): string {
+  const owner = input.policyName || input.label || input.automationId || "manual";
+  return `agent/${safeSegment(owner, 48)}/${safeSegment(id.replace(/^sp[_-]?/, ""), 24)}`;
+}
+
+function repoSlug(repoRoot: string): string {
+  const hash = createHash("sha1").update(resolve(repoRoot)).digest("hex").slice(0, 10);
+  return `${safeSegment(basename(repoRoot), 60)}-${hash}`;
+}
+
+function safeSegment(value: string, max: number): string {
+  return value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, max)
+    || "workspace";
+}