agent-relay-orchestrator 0.91.4 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.91.4",
+  "version": "0.92.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.71"
+    "agent-relay-sdk": "0.2.72"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/control.ts

@@ -4,7 +4,7 @@ import type { ManagedAgentReport, RelayClient, RelayCommand } from "./relay";
 import { handleSelfUpgrade } from "./self-upgrade";
 import { readLocalProviderConfigs } from "./provider-config-migration";
 import { spawnAgent, stopSession, type SpawnOptions } from "./spawn";
-import { cleanupWorkspace, discardRecoveryBranch, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
+import { cleanupWorkspace, discardRecoveryBranch, idleRefreshWorktree, mergeWorkspace, pruneWorktrees, reconcileWorkspace, refreshWorkspaceDeps, workspacesRoot } from "./workspace-probe";
 import { armWorkspacePrAutoMerge, mergeWorkspacePr, refreshWorkspacePrBranch } from "./workspace-pr";
 import type { WorkspaceMergeResult } from "agent-relay-sdk";
 
@@ -195,6 +195,16 @@ export function createControlHandler(
           force: command.params.force === true,
         });
         await relay.updateCommand(command.id, "succeeded", result as unknown as Record<string, unknown>);
+      } else if (command.type === "workspace.idle-refresh") {
+        const result = 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,
+          branch: typeof command.params.branch === "string" ? command.params.branch : undefined,
+          baseRef: typeof command.params.baseRef === "string" ? command.params.baseRef : undefined,
+          baseSha: typeof command.params.baseSha === "string" ? command.params.baseSha : undefined,
+        });
+        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({
           repoRoot: typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined,
@@ -289,6 +299,7 @@ function spawnOptionsFromRecord(source: Record<string, any>, config: Orchestrato
     automationId: typeof source.automationId === "string" ? source.automationId : undefined,
     automationRunId: typeof source.automationRunId === "string" ? source.automationRunId : undefined,
     requestedVia: typeof source.requestedVia === "string" ? source.requestedVia : undefined,
+    resumeWorkspace: parseResumeWorkspace(source.resumeWorkspace),
   };
 }
 
@@ -308,3 +319,18 @@ function stringRecord(value: unknown): Record<string, string> | undefined {
 function stringArray(value: unknown): string[] | undefined {
   return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined;
 }
+
+function parseResumeWorkspace(value: unknown): import("./workspace-probe/types").ResumeWorkspaceTarget | undefined {
+  if (!isRecord(value)) return undefined;
+  const branch = typeof value.branch === "string" ? value.branch : undefined;
+  const mode = value.mode === "attach" || value.mode === "branch-from" ? value.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return {
+    branch,
+    mode,
+    worktreePath: typeof value.worktreePath === "string" ? value.worktreePath : undefined,
+    workspaceId: typeof value.workspaceId === "string" ? value.workspaceId : undefined,
+    baseRef: typeof value.baseRef === "string" ? value.baseRef : undefined,
+    baseSha: typeof value.baseSha === "string" ? value.baseSha : undefined,
+  };
+}

package/src/index.ts

@@ -4,7 +4,7 @@ import { loadConfig, initConfigFile } from "./config";
 import { createRelayClient } from "./relay";
 import type { ManagedSessionExitDiagnostics } from "./relay";
 import { createControlHandler } from "./control";
-import { diagnoseSessionExit, hydrateTerminalGuests, isSessionAlive, reapTerminalGuests, refreshManagedAgentReport } from "./spawn";
+import { diagnoseSessionExit, hydrateTerminalGuests, managedSessionLiveness, reapTerminalGuests, refreshManagedAgentReport } from "./spawn";
 import { startApiServer } from "./api";
 import { recoverManagedAgents } from "./recovery";
 import { ProviderProbeCache } from "./provider-probe";
@@ -166,8 +166,12 @@ async function healthCheck(): Promise<void> {
       changed = true;
     }
     const sessionName = refreshed.sessionName ?? refreshed.tmuxSession;
-    const alive = isSessionAlive(sessionName);
-    if (!alive) {
+    const liveness = managedSessionLiveness(sessionName);
+    if (liveness === "unknown") {
+      console.error(`[orchestrator] Session liveness unknown: ${sessionName}; preserving and retrying next health check`);
+      continue;
+    }
+    if (liveness === "dead") {
       const diagnostics = diagnoseSessionExit({
         agentId: refreshed.agentId,
         policyName: refreshed.policyName,

package/src/spawn/runtime.ts

@@ -5,7 +5,7 @@ import type { ManagedAgentReport } from "../relay";
 import { isPidAlive, parseProcStateIsZombie } from "agent-relay-sdk/process-utils";
 import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { LOG_DIR, RUNNER_INFO_DIR, SESSION_DIR, STATE_FILE } from "./constants";
-import { systemdMainPid } from "./systemd";
+import { systemdMainPid, systemdUnitLiveness, type SystemdUnitLiveness } from "./systemd";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { RunnerInfo, SessionRecord, SessionSupervisor } from "./types";
 
@@ -66,12 +66,15 @@ export function sessionSupervisor(record?: Pick<SessionRecord, "supervisor">): S
 }
 
 export function isSessionRecordAlive(record: SessionRecord): boolean {
+  return sessionRecordLiveness(record) === "alive";
+}
+
+export function sessionRecordLiveness(record: SessionRecord): SystemdUnitLiveness {
   const supervisor = sessionSupervisor(record);
   if (supervisor.type === "systemd" && supervisor.unit) {
-    const pid = systemdMainPid(supervisor.unit);
-    return pid > 0 && isPidAlive(pid);
+    return systemdUnitLiveness(supervisor.unit);
   }
-  return isPidAlive(record.pid);
+  return isPidAlive(record.pid) ? "alive" : "dead";
 }
 
 export function currentSessionPid(record: SessionRecord): number {

package/src/spawn/sessions.ts

@@ -4,7 +4,7 @@ import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { shellEscape } from "agent-relay-sdk/shell-utils";
 import { tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { cleanupSessionRecord } from "./supervisor";
-import { currentSessionPid, findSessionRecord, isSessionRecordAlive, loadState, readRunnerInfo, saveState, sessionReportFields, sessionSupervisor } from "./runtime";
+import { currentSessionPid, findSessionRecord, isSessionRecordAlive, loadState, readRunnerInfo, saveState, sessionRecordLiveness, sessionReportFields, sessionSupervisor } from "./runtime";
 import type { SessionInfo, SessionRecord } from "./types";
 
 export function listSessions(prefix: string): SessionInfo[] {
@@ -31,6 +31,11 @@ export function isSessionAlive(name: string): boolean {
   return record ? isSessionRecordAlive(record) : false;
 }
 
+export function managedSessionLiveness(name: string): "alive" | "dead" | "unknown" {
+  const record = loadState().find((r) => r.name === name);
+  return record ? sessionRecordLiveness(record) : "dead";
+}
+
 export function refreshManagedAgentReport(agent: ManagedAgentReport): ManagedAgentReport {
   const record = findSessionRecord({
     tmuxSession: agent.sessionName ?? agent.tmuxSession,
@@ -56,7 +61,10 @@ export async function recoverExistingSessions(
   const alive: SessionRecord[] = [];
 
   for (const record of records) {
-    if (!isSessionRecordAlive(record)) {
+    const liveness = sessionRecordLiveness(record);
+    if (liveness === "unknown") {
+      console.error(`[orchestrator] Session liveness unknown: ${record.name} (pid ${record.pid}) — preserving`);
+    } else if (liveness === "dead") {
       console.error(`[orchestrator] Stale session: ${record.name} (pid ${record.pid} dead) — removing`);
       cleanupSessionRecord(record);
       continue;

package/src/spawn/supervisor.ts

@@ -11,7 +11,7 @@ import { SESSION_DIR } from "./constants";
 import { disableSystemdSupervisor, forceSystemdSupervisor } from "../config";
 import { logLines } from "./log-utils";
 import { currentSessionPid, ensureSessionDir, findSessionRecord, isSessionRecordAlive, loadState, logFilePath, readRunnerInfo, removeSessionRecord, sessionSupervisor } from "./runtime";
-import { systemdMainPid, systemdUnitName } from "./systemd";
+import { systemdMainPid, systemdUnitDiagnostics, systemdUnitName } from "./systemd";
 import type { SessionRecord, SessionSupervisor, SpawnedRunner } from "./types";
 
 export function spawnRunner(name: string, command: string[], cwd: string, env: Record<string, string>, logFile: string): SpawnedRunner {
@@ -123,44 +123,6 @@ function waitForSystemdMainPid(unit: string, timeoutMs: number): number {
   return 0;
 }
 
-function systemdUnitDiagnostics(unit: string): NonNullable<ManagedSessionExitDiagnostics["systemd"]> {
-  const result = Bun.spawnSync([
-    "systemctl", "--user", "show", `${unit}.service`,
-    "-p", "ActiveState",
-    "-p", "SubState",
-    "-p", "Result",
-    "-p", "ExecMainCode",
-    "-p", "ExecMainStatus",
-    "-p", "MainPID",
-  ], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  if (result.exitCode !== 0) {
-    return {
-      unit,
-      unavailable: result.stderr.toString().trim() || `systemctl show exited with ${result.exitCode}`,
-    };
-  }
-  const props = new Map<string, string>();
-  for (const line of result.stdout.toString().split("\n")) {
-    const index = line.indexOf("=");
-    if (index <= 0) continue;
-    props.set(line.slice(0, index), line.slice(index + 1));
-  }
-  const mainPid = Number(props.get("MainPID"));
-  return {
-    unit,
-    activeState: props.get("ActiveState") || undefined,
-    subState: props.get("SubState") || undefined,
-    result: props.get("Result") || undefined,
-    execMainCode: props.get("ExecMainCode") || undefined,
-    execMainStatus: props.get("ExecMainStatus") || undefined,
-    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : undefined,
-  };
-}
-
 function logFileDiagnostics(logFile: string): Pick<ManagedSessionExitDiagnostics, "logBytes" | "logEmpty" | "logTail"> & { logUnavailable?: string } {
   try {
     const stat = statSync(logFile);

package/src/spawn/systemd.ts

@@ -1,17 +1,84 @@
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { isPidAlive } from "agent-relay-sdk/process-utils";
+
+export type SystemdUnitLiveness = "alive" | "dead" | "unknown";
+
+export interface SystemdUnitDiagnostics {
+  unit: string;
+  activeState?: string;
+  subState?: string;
+  result?: string;
+  execMainCode?: string;
+  execMainStatus?: string;
+  mainPid?: number;
+  unavailable?: string;
+}
 
 export function systemdUnitName(session: string): string {
   const safe = sanitizeFsName(session, { replacement: "-", trimEdge: true, fallback: "agent" });
   return `agent-relay-managed-${safe}`.slice(0, 180);
 }
 
-export function systemdMainPid(unit: string): number {
-  const result = Bun.spawnSync(["systemctl", "--user", "show", `${unit}.service`, "-p", "MainPID", "--value"], {
+export function systemdUnitDiagnostics(unit: string): SystemdUnitDiagnostics {
+  const result = Bun.spawnSync([
+    "systemctl", "--user", "show", `${unit}.service`,
+    "-p", "ActiveState",
+    "-p", "SubState",
+    "-p", "Result",
+    "-p", "ExecMainCode",
+    "-p", "ExecMainStatus",
+    "-p", "MainPID",
+  ], {
     stdin: "ignore",
     stdout: "pipe",
-    stderr: "ignore",
+    stderr: "pipe",
   });
-  if (result.exitCode !== 0) return 0;
-  const pid = Number(result.stdout.toString().trim());
-  return Number.isFinite(pid) ? pid : 0;
+  if (result.exitCode !== 0) {
+    return {
+      unit,
+      unavailable: result.stderr.toString().trim() || `systemctl show exited with ${result.exitCode}`,
+    };
+  }
+  const props = new Map<string, string>();
+  for (const line of result.stdout.toString().split("\n")) {
+    const index = line.indexOf("=");
+    if (index <= 0) continue;
+    props.set(line.slice(0, index), line.slice(index + 1));
+  }
+  const mainPid = Number(props.get("MainPID"));
+  return {
+    unit,
+    activeState: props.get("ActiveState") || undefined,
+    subState: props.get("SubState") || undefined,
+    result: props.get("Result") || undefined,
+    execMainCode: props.get("ExecMainCode") || undefined,
+    execMainStatus: props.get("ExecMainStatus") || undefined,
+    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : undefined,
+  };
+}
+
+export function systemdUnitLivenessFromDiagnostics(
+  diagnostics: SystemdUnitDiagnostics,
+  isAlive: (pid: number) => boolean,
+): SystemdUnitLiveness {
+  if (diagnostics.mainPid && isAlive(diagnostics.mainPid)) return "alive";
+  if (diagnostics.unavailable) return "unknown";
+
+  const activeState = diagnostics.activeState?.toLowerCase();
+  const subState = diagnostics.subState?.toLowerCase();
+  if (activeState === "inactive" || activeState === "failed" || subState === "dead" || subState === "failed") {
+    return "dead";
+  }
+  if (activeState === "active" || activeState === "activating" || activeState === "reloading" || activeState === "deactivating") {
+    return "unknown";
+  }
+  return "unknown";
+}
+
+export function systemdUnitLiveness(unit: string): SystemdUnitLiveness {
+  return systemdUnitLivenessFromDiagnostics(systemdUnitDiagnostics(unit), isPidAlive);
+}
+
+export function systemdMainPid(unit: string): number {
+  return systemdUnitDiagnostics(unit).mainPid ?? 0;
 }

package/src/spawn/types.ts

@@ -1,5 +1,6 @@
 import type { OrchestratorConfig } from "../config";
 import type { AgentLifecycle, WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
+import type { ResumeWorkspaceTarget } from "../workspace-probe/types";
 
 export interface SpawnOptions {
   provider: "claude" | "codex";
@@ -29,6 +30,8 @@ export interface SpawnOptions {
   /** How the spawn was requested (`mcp` = an agent via the MCP surface, else dashboard/CLI). Drives
    * the origin tag so an MCP-spawned worker isn't mislabeled `dashboard-spawned` (#330). */
   requestedVia?: string;
+  /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */
+  resumeWorkspace?: ResumeWorkspaceTarget;
 }
 
 export interface SessionInfo {

package/src/workspace-probe/idle-refresh.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { git } from "../git";
+import { refreshWorkspaceDeps } from "./deps";
+import { syncBaseFromOrigin } from "./git-state";
+import { nextBranchName } from "./names";
+import { shortBranch } from "./parse";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+
+export interface IdleRefreshResult {
+  workspaceId?: string;
+  /** True when the worktree was successfully refreshed to origin/main. */
+  refreshed: boolean;
+  /** New branch name after refresh (`nextBranchName` --N). Present when `refreshed`. */
+  newBranch?: string;
+  /** SHA of origin/main the worktree now sits on. Present when `refreshed`. */
+  baseSha?: string;
+  /** Human-readable skip reason when `refreshed` is false and there is no error. */
+  reason?: string;
+  /** Git/system error that prevented the refresh. */
+  error?: string;
+  depsRefresh?: WorkspaceDepsRefreshResult;
+}
+
+/**
+ * Proactively refresh an idle branch-agent worktree to the current upstream tip
+ * (origin/main or equivalent), making it current before the agent's next turn.
+ *
+ * Safety predicates — ALL must hold before the worktree is touched:
+ *   1. Worktree is clean (zero uncommitted/untracked changes, re-verified live).
+ *   2. No commits ahead of base (nothing to lose on a branch reset).
+ *   3. A remote upstream is configured for the base branch (we know who to follow).
+ *   4. HEAD is an ancestor of the upstream tip (FF-only; divergence = skip).
+ *   5. HEAD is not already AT the upstream tip (skip if already current).
+ *
+ * On success: `checkout -B <fresh> <upstream>`, old branch deleted, deps refreshed.
+ * On any predicate failure: returns `{ refreshed: false, reason }` — never mutates.
+ */
+export function idleRefreshWorktree(input: {
+  id?: string;
+  worktreePath?: string;
+  repoRoot?: string;
+  branch?: string;
+  baseRef?: string;
+  baseSha?: string;
+}): IdleRefreshResult {
+  if (!input.worktreePath) return { refreshed: false, error: "worktreePath required" };
+  const worktreePath = resolve(input.worktreePath);
+  if (!existsSync(worktreePath)) return { workspaceId: input.id, refreshed: false, reason: "worktree missing" };
+  const repoRoot = input.repoRoot ? resolve(input.repoRoot) : worktreePath;
+
+  // Predicate 1: re-check live dirty count (stored metadata may be stale).
+  const status = git(["status", "--porcelain"], worktreePath);
+  if (!status.ok) return { workspaceId: input.id, refreshed: false, error: status.stderr || "git status failed" };
+  const dirty = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+  if (dirty > 0) return { workspaceId: input.id, refreshed: false, reason: "worktree has uncommitted changes" };
+
+  const base = input.baseRef;
+  if (!base) return { workspaceId: input.id, refreshed: false, reason: "no base ref" };
+
+  // Predicate 2: no commits ahead of base.
+  const countResult = git(["rev-list", "--count", `${base}..HEAD`], worktreePath);
+  const ahead = countResult.ok ? Number(countResult.stdout.trim()) : NaN;
+  if (!Number.isFinite(ahead)) return { workspaceId: input.id, refreshed: false, reason: "could not determine ahead count" };
+  if (ahead > 0) return { workspaceId: input.id, refreshed: false, reason: "workspace has commits ahead of base" };
+
+  // Predicate 3: fetch origin and resolve an upstream ref.
+  const startRef = syncBaseFromOrigin(worktreePath, base);
+  if (!startRef || startRef === base) {
+    return { workspaceId: input.id, refreshed: false, reason: "no upstream configured for base branch" };
+  }
+
+  // Predicate 5: skip if already current (HEAD SHA == upstream tip).
+  const headSha = git(["rev-parse", "HEAD"], worktreePath).stdout.trim();
+  const upstreamSha = git(["rev-parse", startRef], worktreePath).stdout.trim();
+  if (headSha && headSha === upstreamSha) {
+    return { workspaceId: input.id, refreshed: false, reason: "already current with origin" };
+  }
+
+  // Predicate 4: FF-only guard — HEAD must be an ancestor of the upstream tip.
+  // If not, the base has diverged; leave it for the conflict scan.
+  if (!git(["merge-base", "--is-ancestor", "HEAD", startRef], worktreePath).ok) {
+    return { workspaceId: input.id, refreshed: false, reason: "diverged from origin — leaving for conflict scan" };
+  }
+
+  // All predicates passed — safe to advance.
+  const liveBranch = shortBranch(git(["symbolic-ref", "--quiet", "--short", "HEAD"], worktreePath).stdout || undefined);
+  const branch = liveBranch ?? input.branch;
+  if (!branch) return { workspaceId: input.id, refreshed: false, reason: "could not determine current branch" };
+
+  const fresh = nextBranchName(repoRoot, branch);
+  if (!git(["checkout", "-B", fresh, startRef], worktreePath).ok) {
+    return { workspaceId: input.id, refreshed: false, error: "git checkout failed" };
+  }
+
+  // Old branch is now orphaned (no commits of its own) — safe to delete.
+  git(["branch", "-D", branch], repoRoot);
+
+  const baseSha = git(["rev-parse", "HEAD"], worktreePath).stdout.trim() || undefined;
+  const depsRefresh = refreshWorkspaceDeps(repoRoot, worktreePath);
+  const reportDeps = depsRefresh.refreshed || depsRefresh.stale || depsRefresh.error;
+
+  return {
+    workspaceId: input.id,
+    refreshed: true,
+    newBranch: fresh,
+    ...(baseSha ? { baseSha } : {}),
+    ...(reportDeps ? { depsRefresh } : {}),
+  };
+}

package/src/workspace-probe/index.ts

@@ -1,5 +1,6 @@
 export * from "./cleanup";
 export * from "./deps";
+export * from "./idle-refresh";
 export * from "./git-state";
 export * from "./merge";
 export * from "./names";

package/src/workspace-probe/merge.ts

@@ -373,7 +373,11 @@ function resolveNoopMerge(
     const base = preview.baseRef;
     if (base && branch) {
       const fresh = nextBranchName(repoRoot, branch);
-      const start = startRef ?? base;
+      // #478 — cut from the FETCHED upstream tip so even a plain noop recycle (no
+      // startRef) advances to origin/main, not the stale local base. The PR-land
+      // recycle (#423) already passes startRef (the verified upstream sha); this
+      // makes the rebase-ff noop path equally multi-host-correct.
+      const start = startRef ?? syncBaseFromOrigin(worktreePath, base) ?? base;
       if (git(["checkout", "-B", fresh, start], worktreePath).ok) {
         // Old branch's tree is already in base (that's what noop means) — safe to drop.
         const oldDeleted = git(["branch", "-D", branch], repoRoot).ok;

package/src/workspace-probe/probe.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import type { WorkspaceMode, WorkspaceProbe } from "agent-relay-sdk";
@@ -61,6 +61,63 @@ export async function resolveSpawnWorkspace(input: WorkspaceResolutionInput): Pr
     };
   }
 
+  // #635 — attach to an existing worktree instead of creating a fresh one.
+  if (input.resumeWorkspace?.mode === "attach") {
+    const resume = input.resumeWorkspace;
+    const wtp = resume.worktreePath;
+    if (!wtp) throw new Error("resumeWorkspace attach: worktreePath is required");
+    if (!existsSync(wtp)) throw new Error(`resumeWorkspace attach: worktree does not exist: ${wtp}`);
+    return {
+      cwd: wtp,
+      workspace: {
+        ...(resume.workspaceId ? { id: resume.workspaceId } : { id: workspaceId(input) }),
+        mode: "isolated",
+        requestedMode,
+        repoRoot: probe.repoRoot,
+        sourceCwd,
+        worktreePath: wtp,
+        branch: resume.branch,
+        ...(resume.baseRef ? { baseRef: resume.baseRef } : {}),
+        ...(resume.baseSha ? { baseSha: resume.baseSha } : {}),
+        status: "active",
+        probe,
+      },
+    };
+  }
+
+  // #635 — create a fresh worktree off an existing branch's HEAD instead of main's HEAD.
+  if (input.resumeWorkspace?.mode === "branch-from") {
+    const resume = input.resumeWorkspace;
+    const repoRoot = probe.repoRoot;
+    const baseSha = requireGit(["rev-parse", resume.branch], repoRoot);
+    const id = workspaceId(input);
+    const branch = await availableBranch(repoRoot, branchName(input, id));
+    const workspaceRoot = input.workspaceRoot ? resolve(input.workspaceRoot) : workspacesRoot(homedir());
+    const worktreePath = join(workspaceRoot, repoSlug(repoRoot), id);
+    mkdirSync(join(worktreePath, ".."), { recursive: true });
+    requireGit(["worktree", "add", "-b", branch, worktreePath, baseSha], repoRoot);
+    const deps = provisionWorkspaceDeps(repoRoot, worktreePath);
+    const symlinks = provisionWorkspaceSymlinks(repoRoot, worktreePath, input.workspaceSymlinks ?? []);
+    return {
+      cwd: worktreePath,
+      workspace: {
+        id,
+        mode: "isolated",
+        requestedMode,
+        repoRoot,
+        sourceCwd,
+        worktreePath,
+        branch,
+        baseRef: resume.branch,
+        baseSha,
+        status: "active",
+        deps,
+        ...(symlinks.linked.length || symlinks.errors ? { symlinks } : {}),
+        probe,
+      },
+    };
+  }
+
   const id = workspaceId(input);
   const repoRoot = probe.repoRoot;
   const baseRef = terminalBaseRef(repoRoot, probe.branch);

package/src/workspace-probe/types.ts

@@ -1,6 +1,21 @@
 import type { WorkspaceMetadata, WorkspaceMode } from "agent-relay-sdk";
 import type { WorkspaceMergeResult } from "agent-relay-sdk";
 
+/** Attach to or branch off an existing managed worktree instead of creating a fresh one (#635). */
+export interface ResumeWorkspaceTarget {
+  branch: string;
+  /** `attach` = reuse the existing worktree as-is (crash recovery). `branch-from` = new worktree off the existing branch HEAD. */
+  mode: "attach" | "branch-from";
+  /** Resolved worktree path from the relay DB. For `attach`: must exist on disk. For `branch-from`: unused (HEAD resolved from branch). */
+  worktreePath?: string;
+  /** Existing workspace DB id. For `attach`: passed back so the relay reuses the same record (avoids duplicates). */
+  workspaceId?: string;
+  /** Preserved baseRef from the original workspace. For `attach` only. */
+  baseRef?: string;
+  /** Preserved baseSha from the original workspace. For `attach` only. */
+  baseSha?: string;
+}
+
 export interface WorkspaceResolutionInput {
   cwd: string;
   label?: string;
@@ -11,6 +26,8 @@ export interface WorkspaceResolutionInput {
   workspaceSymlinks?: string[];
   automationId?: string;
   automationRunId?: string;
+  /** #635 — attach to or branch off an existing worktree instead of creating a fresh one. */
+  resumeWorkspace?: ResumeWorkspaceTarget;
 }
 
 export interface WorkspaceResolution {