agent-relay-orchestrator 0.120.0 → 0.120.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.120.0",
+  "version": "0.120.2",
   "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.107",
+    "agent-relay-sdk": "0.2.108",
     "callmux": "0.23.0"
   },
   "devDependencies": {

package/src/control.ts

@@ -373,6 +373,8 @@ export function createControlHandler(
           baseRef: typeof command.params.baseRef === "string" ? command.params.baseRef : undefined,
           baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
           deleteBranch: command.params.deleteBranch !== false,
+          force: command.params.force === true,
+          reason: typeof command.params.reason === "string" ? command.params.reason : undefined,
           workspacesRoot: workspacesRoot(config.baseDir),
         });
         await relay.updateCommand(command.id, "succeeded", result);

package/src/process.ts

@@ -271,9 +271,10 @@ export async function execProcess(cmd: string[], options: ExecOptions = {}): Pro
     const msg = abortMessage(cmd, options);
     stderr = stderr ? `${stderr}\n${msg}` : msg;
   }
+  const reportedExitCode = timedOut || aborted || outputLimitExceeded ? null : exitCode;
   return {
-    ok: !timedOut && !aborted && !outputLimitExceeded && exitCode === 0,
-    exitCode,
+    ok: !timedOut && !aborted && !outputLimitExceeded && reportedExitCode === 0,
+    exitCode: reportedExitCode,
     stdout: options.trimStdout === false ? stdout : stdout.trim(),
     stderr: options.trimStderr === false ? stderr : stderr.trim(),
     ...(timedOut ? { timedOut } : {}),

package/src/spawn/supervisor.ts

@@ -1,4 +1,4 @@
-import { chmodSync, closeSync, existsSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { OrchestratorConfig } from "../config";
 import type { ManagedSessionExitDiagnostics } from "../relay";
@@ -15,26 +15,33 @@ import { systemdMainPidAsync, systemdUnitDiagnostics, systemdUnitName } from "./
 import type { SessionRecord, SessionSupervisor, SpawnedRunner } from "./types";
 import { execProcess } from "../process";
 
+const FILE_BACKED_ENV_PAYLOADS = new Map<string, string>([
+  ["AGENT_RELAY_AGENT_PROFILE_JSON", "agent-profile.json"],
+  ["AGENT_RELAY_WORKSPACE_JSON", "workspace.json"],
+  ["AGENT_RELAY_INJECTION_EVENTS_JSON", "relay-injection-events.json"],
+]);
+
 export async function spawnRunner(name: string, command: string[], cwd: string, env: Record<string, string>, logFile: string): Promise<SpawnedRunner> {
+  const launchScript = launchScriptPath(name);
+  const launch = materializeLaunchPayload(launchScript, command, env);
   if (await shouldUseSystemdSupervisor()) {
     try {
-      return await spawnSystemdRunner(name, command, cwd, env, logFile);
+      return await spawnSystemdRunner(name, launch.command, cwd, launch.env, logFile);
     } catch (error) {
       console.error(`[orchestrator] systemd runner supervisor unavailable for ${name}: ${errMessage(error)}`);
       console.error("[orchestrator] Falling back to process child; this agent will not survive orchestrator service restart.");
     }
   }
 
-  const launchScript = launchScriptPath(name);
   ensureSessionDir();
-  writeFileSync(launchScript, buildLaunchScript(command, cwd, env), { mode: 0o700 });
+  writeFileSync(launchScript, buildLaunchScript(launch.command, cwd, launch.env), { mode: 0o700 });
   chmodSync(launchScript, 0o700);
 
   const logFd = openSync(logFile, "a");
   try {
     const proc = Bun.spawn([launchScript], {
       cwd,
-      env,
+      env: launch.env,
       stdin: "ignore",
       stdout: logFd,
       stderr: logFd,
@@ -86,6 +93,47 @@ function launchScriptPath(session: string): string {
   return join(SESSION_DIR, `${safe}.sh`);
 }
 
+function launchPayloadDirPath(launchScript: string): string {
+  return `${launchScript}.d`;
+}
+
+function payloadFilePath(launchScript: string, filename: string): string {
+  return join(launchPayloadDirPath(launchScript), filename);
+}
+
+function materializeEnvPayload(env: Record<string, string>, launchScript: string): Record<string, string> {
+  const nextEnv = { ...env };
+  for (const [envKey, filename] of FILE_BACKED_ENV_PAYLOADS) {
+    const value = nextEnv[envKey];
+    if (typeof value !== "string" || value.length === 0) continue;
+    const filePath = payloadFilePath(launchScript, filename);
+    mkdirSync(launchPayloadDirPath(launchScript), { recursive: true });
+    writeFileSync(filePath, value);
+    delete nextEnv[envKey];
+    nextEnv[`${envKey}_FILE`] = filePath;
+  }
+  return nextEnv;
+}
+
+function materializeCommandArg(command: string[], env: Record<string, string>, launchScript: string, flag: string, envKey: string, filename: string): void {
+  const index = command.indexOf(flag);
+  if (index < 0 || !command[index + 1]) return;
+  const filePath = payloadFilePath(launchScript, filename);
+  mkdirSync(launchPayloadDirPath(launchScript), { recursive: true });
+  writeFileSync(filePath, command[index + 1]!);
+  command.splice(index, 2);
+  env[`${envKey}_FILE`] = filePath;
+}
+
+export function materializeLaunchPayload(launchScript: string, command: string[], env: Record<string, string>): { command: string[]; env: Record<string, string> } {
+  const nextCommand = [...command];
+  const nextEnv = materializeEnvPayload(env, launchScript);
+  materializeCommandArg(nextCommand, nextEnv, launchScript, "--prompt", "AGENT_RELAY_PROMPT", "prompt.txt");
+  materializeCommandArg(nextCommand, nextEnv, launchScript, "--system-prompt-append", "AGENT_RELAY_SYSTEM_PROMPT_APPEND", "system-prompt-append.txt");
+  materializeCommandArg(nextCommand, nextEnv, launchScript, "--append-system-prompt", "AGENT_RELAY_SYSTEM_PROMPT_APPEND", "system-prompt-append.txt");
+  return { command: nextCommand, env: nextEnv };
+}
+
 export function buildLaunchScript(command: string[], cwd: string, env: Record<string, string>): string {
   const exports = Object.entries(env)
     .filter(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && value !== undefined)
@@ -252,7 +300,10 @@ function killSystemdUnit(unit: string): void {
 
 function cleanupSupervisor(supervisor: SessionSupervisor): void {
   if (supervisor.type === "systemd" && supervisor.unit) stopSystemdUnit(supervisor.unit);
-  if (supervisor.launchScript) rmSync(supervisor.launchScript, { force: true });
+  if (supervisor.launchScript) {
+    rmSync(supervisor.launchScript, { force: true });
+    rmSync(launchPayloadDirPath(supervisor.launchScript), { recursive: true, force: true });
+  }
 }
 
 export function cleanupSessionRecord(record: SessionRecord): void {

package/src/workspace-probe/cleanup.ts

@@ -22,13 +22,20 @@ export async function owningRepoRoot(worktreePath: string, fallback: string): Pr
   return existsSync(root) ? root : fallback;
 }
 
-export async function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; baseRef?: string; baseSha?: string; deleteBranch?: boolean; workspacesRoot?: string }): Promise<{ workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean; branchPreservedReason?: string; containerRemoved?: boolean }> {
+export async function cleanupWorkspace(workspace: { repoRoot?: string; worktreePath?: string; id?: string; branch?: string; baseRef?: string; baseSha?: string; deleteBranch?: boolean; workspacesRoot?: string; force?: boolean; reason?: string }): Promise<{ workspaceId?: string; removed: boolean; worktreePath?: string; branchDeleted?: boolean; branchPreservedReason?: string; containerRemoved?: boolean; dirtySnapshotRef?: string }> {
   if (!workspace.worktreePath) throw new Error("worktreePath required");
   const path = resolve(workspace.worktreePath);
   const recordedRepo = workspace.repoRoot ? resolve(workspace.repoRoot) : path;
   // Remove via the REAL owning repo, not the recorded (chained/deleted) repoRoot which
   // would silently no-op and leak the dir while the relay marks it `cleaned` (#307).
   const repo = await owningRepoRoot(path, recordedRepo);
+  let dirtySnapshotRef: string | undefined;
+  if (existsSync(path)) {
+    const safety = await worktreeSafeToRemove(path, workspace.baseRef, workspace.baseSha);
+    const explicitForce = workspace.force === true && Boolean(workspace.reason?.trim());
+    if (!safety.safe && !explicitForce) throw new Error(`unsafe workspace cleanup refused: ${safety.reason}`);
+    if (!safety.safe) dirtySnapshotRef = await snapshotDirtyWorktree(path, workspace.id);
+  }
   const result = await git(["worktree", "remove", "--force", path], repo);
   // Trust the filesystem, not git's exit code (a remove against the wrong repo "succeeds"
   // touching nothing). If the dir survives, surface failure so the relay leaves the row
@@ -53,7 +60,39 @@ export async function cleanupWorkspace(workspace: { repoRoot?: string; worktreeP
     }
   }
   const containerRemoved = workspace.workspacesRoot ? removeEmptyContainer(dirname(path), resolve(workspace.workspacesRoot)) : false;
-  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted, ...(branchPreservedReason ? { branchPreservedReason } : {}), containerRemoved };
+  return { workspaceId: workspace.id, removed: true, worktreePath: path, branchDeleted, ...(branchPreservedReason ? { branchPreservedReason } : {}), containerRemoved, ...(dirtySnapshotRef ? { dirtySnapshotRef } : {}) };
+}
+
+async function worktreeSafeToRemove(worktreePath: string, baseRef?: string, baseSha?: string): Promise<{ safe: boolean; reason?: string }> {
+  const status = await git(["status", "--porcelain"], worktreePath);
+  if (!status.ok) return { safe: false, reason: status.stderr || "git status unavailable" };
+  const dirtyCount = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+  if (dirtyCount > 0) return { safe: false, reason: `${dirtyCount} uncommitted change(s)` };
+
+  const base = await resolveCleanupBase(worktreePath, baseRef, baseSha);
+  if (!base) return { safe: false, reason: "base ref unavailable" };
+  const counts = await git(["rev-list", "--left-right", "--count", `${base}...HEAD`], worktreePath);
+  if (!counts.ok || !counts.stdout) return { safe: false, reason: counts.stderr || "ahead count unavailable" };
+  const ahead = Number(counts.stdout.split(/\s+/)[1]);
+  if (!Number.isFinite(ahead)) return { safe: false, reason: "ahead count unavailable" };
+  if (ahead === 0) return { safe: true };
+
+  const cherryBase = await upstreamRef(worktreePath, base) ?? base;
+  if ((await git(["diff", "--quiet", cherryBase, "HEAD"], worktreePath)).ok) return { safe: true };
+  const cherry = await git(["cherry", cherryBase, "HEAD"], worktreePath);
+  if (!cherry.ok) return { safe: false, reason: cherry.stderr || "unmerged commit check unavailable" };
+  const unmergedAhead = cherry.stdout ? cherry.stdout.split("\n").filter((line) => line.startsWith("+")).length : 0;
+  return unmergedAhead === 0 ? { safe: true } : { safe: false, reason: `${unmergedAhead} unlanded commit(s)` };
+}
+
+async function snapshotDirtyWorktree(worktreePath: string, workspaceId: string | undefined): Promise<string | undefined> {
+  const snapshot = await git(["stash", "create", `agent-relay cleanup snapshot ${workspaceId ?? "workspace"}`], worktreePath);
+  const commit = snapshot.ok ? snapshot.stdout.trim() : "";
+  if (!commit) return undefined;
+  const safe = (workspaceId ?? basename(worktreePath)).replace(/[^A-Za-z0-9._/-]+/g, "-").replace(/^\/+|\/+$/g, "").slice(0, 180) || "workspace";
+  const ref = `refs/agent-relay/workspace-tips/${safe}-dirty-${Date.now()}`;
+  const updated = await git(["update-ref", ref, commit], worktreePath);
+  return updated.ok ? ref : undefined;
 }
 
 export async function branchSafeToDelete(repo: string, branch: string, baseRef?: string, baseSha?: string): Promise<{ safe: boolean; reason?: string }> {

package/src/workspace-probe/merge.ts

@@ -3,7 +3,6 @@ import { join, resolve } from "node:path";
 import { errMessage, type BaseWorktreeSyncResult, type WorkspaceMergePreview, type WorkspaceMergeResult } from "agent-relay-sdk";
 import { git, gitRaw } from "../git";
 import { execProcess } from "../process";
-import { prMergedState } from "../workspace-pr";
 import { deleteBranchIfSafe, owningRepoRoot } from "./cleanup";
 import { refreshWorkspaceDeps } from "./deps";
 import { type LandGatesResult } from "./land-gates-runner";
@@ -11,6 +10,8 @@ import { populateMergeState, resolveBranchRef, syncBaseFromOrigin, upstreamRef,
 import { type MergePhase, mergePhaseTimeoutMs, throwIfMergeAborted, withMergePhaseTimeout } from "./merge-timeouts";
 import { nextBranchName } from "./names";
 import { parseWorktrees, shortBranch } from "./parse";
+import { applyPrMergeState } from "./pr-preview";
+import { protectWorkspaceTip } from "./protected-tip";
 import { json, resolveRequestedPath } from "./request";
 import type { WorkspaceMergeInput } from "./types";
 import { workspacePushEnabled } from "../config";
@@ -210,24 +211,6 @@ function logBaseWorktreeStrand(base: string, worktreePath: string, sync: BaseWor
   );
 }
 
-// Populate a preview's PR fields from `gh` ground truth; returns whether the PR is merged
-// (#168/#304). One home for the PR-landing rule so the worktree- and repoRoot-based previews
-// can't drift. On a merge it stamps the merge SHA so the relay can finalize a parked pr land.
-async function applyPrMergeState(base: WorkspaceMergePreview, cwd: string, branch: string | undefined): Promise<boolean> {
-  const pr = await prMergedState(cwd, branch);
-  if (!pr) return false;
-  base.prState = pr.state;
-  if (pr.url) base.prUrl = pr.url;
-  if (pr.number) base.prNumber = pr.number;
-  if (pr.reviewDecision) base.reviewDecision = pr.reviewDecision;
-  if (pr.statusCheckRollup) base.statusCheckRollup = pr.statusCheckRollup; if (pr.mergeable) base.mergeable = pr.mergeable; if (pr.mergeStateStatus) base.mergeStateStatus = pr.mergeStateStatus;
-  if (pr.state !== "merged") return false;
-  base.prMerged = true;
-  if (pr.sha) base.prMergeSha = pr.sha;
-  if (pr.title) base.prMergeSubject = pr.title;
-  return true;
-}
-
 export async function previewBranchMerge(input: {
   repoRoot?: string;
   branch?: string;
@@ -283,6 +266,7 @@ export async function mergePreviewResponse(url: URL, baseDir: string): Promise<R
       baseSha: url.searchParams.get("baseSha") || undefined,
       strategy: validPreviewStrategy(strategy),
       checkPr: url.searchParams.get("checkPr") === "1",
+      workspaceId: url.searchParams.get("workspaceId") || undefined, protectTip: url.searchParams.get("protectTip") === "1",
     }));
   } catch (e) {
     return json({ error: (e as Error).message }, 400);
@@ -311,7 +295,7 @@ export async function branchMergePreviewResponse(url: URL, baseDir: string): Pro
  * `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 async function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?: string; baseSha?: string; strategy?: "pr" | "rebase-ff" | "auto"; checkPr?: boolean }): Promise<WorkspaceMergePreview> {
+export async function previewWorkspaceMerge(input: { worktreePath?: string; baseRef?: string; baseSha?: string; strategy?: "pr" | "rebase-ff" | "auto"; checkPr?: boolean; workspaceId?: string; protectTip?: boolean }): Promise<WorkspaceMergePreview> {
   const gitState = await workspaceGitState(input);
   const remote = input.worktreePath ? await hasOriginRemote(resolve(input.worktreePath)) : false;
   const gh = ghAvailable();
@@ -328,6 +312,7 @@ export async function previewWorkspaceMerge(input: { worktreePath?: string; base
   base.unmergedAhead = gitState.unmergedAhead;
   base.landed = gitState.landed;
   base.behind = gitState.behind;
+  base.headSha = gitState.lastCommit?.sha;
   base.dirtyCount = gitState.dirtyCount;
   if ((gitState.dirtyCount ?? 0) > 0) return { ...base, reason: "worktree has uncommitted changes" };
   let effectiveAhead = gitState.landed ? 0 : (gitState.unmergedAhead ?? gitState.ahead ?? 0);
@@ -337,6 +322,17 @@ export async function previewWorkspaceMerge(input: { worktreePath?: string; base
   if (input.checkPr && strategy === "pr" && input.worktreePath) {
     if (await applyPrMergeState(base, resolve(input.worktreePath), gitState.branch)) effectiveAhead = 0;
   }
+  if (input.protectTip && input.worktreePath) {
+    const protection = await protectWorkspaceTip({
+      worktreePath: resolve(input.worktreePath), workspaceId: input.workspaceId, branch: gitState.branch,
+      baseRef: gitState.baseRef, headSha: gitState.lastCommit?.sha, dirtyCount: gitState.dirtyCount, effectiveAhead,
+    });
+    Object.assign(base, protection);
+    if (protection.protectedTipRestored) {
+      return { ...await previewWorkspaceMerge({ ...input, protectTip: false }), ...protection };
+    }
+    if (protection.protectedTipReachable === false) return base;
+  }
   if (effectiveAhead === 0) {
     const reason = base.prMerged
       ? "PR merged on remote"

package/src/workspace-probe/pr-preview.ts

@@ -0,0 +1,22 @@
+import type { WorkspaceMergePreview } from "agent-relay-sdk";
+import { prMergedState } from "../workspace-pr";
+
+// Populate a preview's PR fields from `gh` ground truth; returns whether the PR is merged
+// (#168/#304). One home for the PR-landing rule so the worktree- and repoRoot-based previews
+// can't drift. On a merge it stamps the merge SHA so the relay can finalize a parked pr land.
+export async function applyPrMergeState(base: WorkspaceMergePreview, cwd: string, branch: string | undefined): Promise<boolean> {
+  const pr = await prMergedState(cwd, branch);
+  if (!pr) return false;
+  base.prState = pr.state;
+  if (pr.url) base.prUrl = pr.url;
+  if (pr.number) base.prNumber = pr.number;
+  if (pr.reviewDecision) base.reviewDecision = pr.reviewDecision;
+  if (pr.statusCheckRollup) base.statusCheckRollup = pr.statusCheckRollup;
+  if (pr.mergeable) base.mergeable = pr.mergeable;
+  if (pr.mergeStateStatus) base.mergeStateStatus = pr.mergeStateStatus;
+  if (pr.state !== "merged") return false;
+  base.prMerged = true;
+  if (pr.sha) base.prMergeSha = pr.sha;
+  if (pr.title) base.prMergeSubject = pr.title;
+  return true;
+}

package/src/workspace-probe/probe.ts

@@ -91,7 +91,9 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
   if (input.resumeWorkspace?.mode === "branch-from") {
     const resume = input.resumeWorkspace;
     const repoRoot = probe.repoRoot;
-    const baseSha = await requireGit(["rev-parse", resume.branch], repoRoot);
+    const startSha = await requireGit(["rev-parse", resume.branch], repoRoot);
+    const baseRef = resume.baseRef ?? await terminalBaseRef(repoRoot, resume.branch);
+    const baseSha = resume.baseSha ?? (baseRef ? await requireGit(["rev-parse", baseRef], repoRoot) : undefined);
     const id = workspaceId(input);
     const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : workspacesRoot(homedir());
     const worktreePath = join(workspaceRoot, repoSlug(repoRoot), id);
@@ -103,7 +105,7 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
         sourceCwd,
         worktreePath,
         branch: existing.branch,
-        baseRef: resume.branch,
+        baseRef,
         baseSha,
         requestedMode,
         probe,
@@ -112,7 +114,7 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
 
     const branch = await availableBranch(repoRoot, branchName(input, id));
     mkdirSync(join(worktreePath, ".."), { recursive: true });
-    await requireGit(["worktree", "add", "-b", branch, worktreePath, baseSha], repoRoot);
+    await requireGit(["worktree", "add", "-b", branch, worktreePath, startSha], repoRoot);
     const deps = await provisionWorkspaceDeps(repoRoot, worktreePath);
     const symlinks = provisionWorkspaceSymlinks(repoRoot, worktreePath, input.workspaceSymlinks ?? []);
     return {
@@ -125,8 +127,8 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
         sourceCwd,
         worktreePath,
         branch,
-        baseRef: resume.branch,
-        baseSha,
+        ...(baseRef ? { baseRef } : {}),
+        ...(baseSha ? { baseSha } : {}),
         status: "active",
         deps,
         ...(symlinks.linked.length || symlinks.errors ? { symlinks } : {}),

package/src/workspace-probe/protected-tip.ts

@@ -0,0 +1,108 @@
+import { git } from "../git";
+import { mergePhaseTimeoutMs, throwIfMergeAborted } from "./merge-timeouts";
+
+async function previewGit(args: string[], cwd: string, timeoutLabel: string, signal?: AbortSignal): ReturnType<typeof git> {
+  throwIfMergeAborted(signal);
+  return git(args, cwd, {
+    timeoutMs: mergePhaseTimeoutMs("preview"),
+    timeoutLabel,
+    signal,
+  });
+}
+
+function gitError(result: Awaited<ReturnType<typeof git>>, fallback: string): string {
+  return result.stderr || result.stdout || fallback;
+}
+
+function protectedTipRef(workspaceId: string | undefined): string | undefined {
+  const safe = workspaceId?.replace(/[^A-Za-z0-9._/-]+/g, "-").replace(/^\/+|\/+$/g, "").slice(0, 180);
+  return safe ? `refs/agent-relay/workspace-tips/${safe}` : undefined;
+}
+
+function discardedTipRef(ref: string): string {
+  return `${ref}-discarded-${Date.now()}`;
+}
+
+async function readCommit(cwd: string, ref: string, signal?: AbortSignal): Promise<string | undefined> {
+  const result = await previewGit(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], cwd, `workspace preview read ${ref}`, signal);
+  return result.ok && result.stdout ? result.stdout.trim() : undefined;
+}
+
+async function isAncestor(cwd: string, ancestor: string, descendant: string, signal?: AbortSignal): Promise<boolean> {
+  return (await previewGit(["merge-base", "--is-ancestor", ancestor, descendant], cwd, "workspace preview ancestor check", signal)).ok;
+}
+
+async function patchEquivalentOrContained(cwd: string, oldTip: string, currentTip: string, signal?: AbortSignal): Promise<boolean> {
+  const cherry = await previewGit(["cherry", currentTip, oldTip], cwd, "workspace preview protected-tip patch-equivalence", signal);
+  if (!cherry.ok) return false;
+  return !cherry.stdout.split("\n").some((line) => line.startsWith("+"));
+}
+
+export interface ProtectedTipCheck {
+  protectedTipRef?: string;
+  protectedTip?: string;
+  protectedTipReachable?: boolean;
+  protectedTipRestored?: boolean;
+  protectedTipDiscardedRef?: string;
+  protectedTipDiscardedHead?: string;
+  protectedTipError?: string;
+}
+
+export async function protectWorkspaceTip(input: {
+  worktreePath: string;
+  workspaceId?: string;
+  branch?: string;
+  baseRef?: string;
+  headSha?: string;
+  dirtyCount?: number;
+  effectiveAhead: number;
+  signal?: AbortSignal;
+}): Promise<ProtectedTipCheck> {
+  const ref = protectedTipRef(input.workspaceId);
+  if (!ref || !input.headSha) return {};
+
+  const existing = await readCommit(input.worktreePath, ref, input.signal);
+  if (!existing) {
+    if (input.effectiveAhead <= 0) return { protectedTipRef: ref };
+    const update = await previewGit(["update-ref", ref, input.headSha], input.worktreePath, "workspace preview protect worker tip", input.signal);
+    return update.ok
+      ? { protectedTipRef: ref, protectedTip: input.headSha, protectedTipReachable: true }
+      : { protectedTipRef: ref, protectedTipError: gitError(update, "failed to protect worker branch tip") };
+  }
+
+  if (await isAncestor(input.worktreePath, existing, input.headSha, input.signal)) {
+    if (input.effectiveAhead > 0 && existing !== input.headSha) {
+      const update = await previewGit(["update-ref", ref, input.headSha, existing], input.worktreePath, "workspace preview advance protected worker tip", input.signal);
+      if (!update.ok) return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: true, protectedTipError: gitError(update, "failed to advance protected worker tip") };
+      return { protectedTipRef: ref, protectedTip: input.headSha, protectedTipReachable: true };
+    }
+    return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: true };
+  }
+
+  if (input.baseRef && await isAncestor(input.worktreePath, existing, input.baseRef, input.signal)) {
+    return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: true };
+  }
+
+  if (await patchEquivalentOrContained(input.worktreePath, existing, input.headSha, input.signal)) {
+    const update = await previewGit(["update-ref", ref, input.headSha, existing], input.worktreePath, "workspace preview advance rebased protected worker tip", input.signal);
+    if (!update.ok) return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: true, protectedTipError: gitError(update, "failed to advance rebased protected worker tip") };
+    return { protectedTipRef: ref, protectedTip: input.headSha, protectedTipReachable: true };
+  }
+
+  if ((input.dirtyCount ?? 0) > 0) {
+    return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: false, protectedTipError: "protected worker tip is no longer reachable, and the worktree is dirty" };
+  }
+  if (!input.branch) {
+    return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: false, protectedTipError: "protected worker tip is no longer reachable, and the current branch is unknown" };
+  }
+
+  const discardedRef = discardedTipRef(ref);
+  const snapshot = await previewGit(["update-ref", discardedRef, input.headSha], input.worktreePath, "workspace preview snapshot discarded worker head", input.signal);
+  if (!snapshot.ok) {
+    return { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: false, protectedTipError: gitError(snapshot, "failed to snapshot discarded worker head before protected-tip restore") };
+  }
+  const restore = await previewGit(["checkout", "-B", input.branch, existing], input.worktreePath, "workspace preview restore protected worker tip", input.signal);
+  return restore.ok
+    ? { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: true, protectedTipRestored: true, protectedTipDiscardedRef: discardedRef, protectedTipDiscardedHead: input.headSha }
+    : { protectedTipRef: ref, protectedTip: existing, protectedTipReachable: false, protectedTipDiscardedRef: discardedRef, protectedTipDiscardedHead: input.headSha, protectedTipError: gitError(restore, "failed to restore protected worker tip") };
+}