agent-relay-server 0.25.0 → 0.27.0

package/src/routes.ts

@@ -167,7 +167,7 @@ import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFF
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
-import { requestWorkspaceMerge } from "./workspace-merge";
+import { isOwnerAlive, withOwnerOnline } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import {
   applyWorkspaceAction,
@@ -178,6 +178,7 @@ import {
 } from "./workspace-actions";
 import { describeWorkspacePhase, landReceipt, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import { notifyBranchLanded } from "./branch-landed";
+import { collectWorkspaceOrphans } from "./workspace-orphans";
 import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
@@ -3812,7 +3813,7 @@ const getWorkspaces: Handler = (req) => {
     const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
     const ownerAgentId = cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 240 });
     const status = optionalEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
-    return json(listWorkspaces({ repoRoot, ownerAgentId, status }));
+    return json(listWorkspaces({ repoRoot, ownerAgentId, status }).map(withOwnerOnline));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -3822,7 +3823,7 @@ const getWorkspaces: Handler = (req) => {
 const getWorkspaceById: Handler = (_req, params) => {
   const workspace = getWorkspace(params.id!);
   if (!workspace) return error("workspace not found", 404);
-  return json(workspace);
+  return json(withOwnerOnline(workspace));
 };
 
 // Per-repo coordination state: persistent steward records (survive offline gaps)
@@ -3879,41 +3880,14 @@ const getWorkspaceDiff: Handler = (req, params) => {
 };
 
 // Worktrees found on disk (agent/* branches) with no live workspace row — left
-// behind by crashes or failed cleanups. Probes each known repo's owning host
-// and subtracts active DB rows. Reclaim them via POST .../orphans/reclaim.
+// behind by crashes or failed cleanups. Probes each known repo's owning host and
+// subtracts live DB rows, enriching each with land-state so reap-safe cruft is
+// distinguishable from stranded work. Also reports the inverse drift (live rows
+// whose worktree vanished). Discovery is shared with the scheduled reaper
+// (workspace-orphan-reaper). Reclaim via POST .../orphans/reclaim.
 const getWorkspaceOrphans: Handler = async () => {
-  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
-  if (!orchestrators.length) return json({ orphans: [], reason: "no online orchestrators" });
-  const all = listWorkspaces();
-  const repoRoots = [...new Set(all.map((ws) => ws.repoRoot).filter(Boolean))];
-  const headers: Record<string, string> = {};
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
-  const orphans: WorkspaceOrphan[] = [];
-
-  for (const repoRoot of repoRoots) {
-    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
-    if (!orch?.apiUrl) continue;
-    let probe: WorkspaceProbe | undefined;
-    try {
-      const res = await fetch(`${orch.apiUrl}/api/workspace/probe?path=${encodeURIComponent(repoRoot)}`, { headers, signal: AbortSignal.timeout(10_000) });
-      if (!res.ok) continue;
-      probe = await res.json() as WorkspaceProbe;
-    } catch {
-      continue;
-    }
-    const rowsByPath = new Map(all.filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath).map((ws) => [resolve(ws.worktreePath), ws]));
-    for (const worktree of probe?.worktrees ?? []) {
-      if (!worktree.path || resolve(worktree.path) === resolve(repoRoot)) continue;
-      // Only agent-relay-created worktrees (agent/* branches) are reclaimable —
-      // never touch a user's own linked worktrees.
-      if (!worktree.branch?.startsWith("agent/")) continue;
-      const row = rowsByPath.get(resolve(worktree.path));
-      if (row && !TERMINAL_WORKSPACE_STATUSES.has(row.status)) continue; // tracked & live
-      orphans.push({ worktreePath: worktree.path, repoRoot, branch: worktree.branch, headSha: worktree.headSha, hadTerminalRow: Boolean(row) });
-    }
-  }
-  return json({ orphans });
+  const { orphans, missingWorktrees, reason } = await collectWorkspaceOrphans();
+  return json(reason ? { orphans, missingWorktrees, reason } : { orphans, missingWorktrees });
 };
 
 const postWorkspaceOrphanReclaim: Handler = async (req) => {
@@ -3927,11 +3901,25 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
     const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
     const branch = cleanString(parsed.body.branch, "branch", { max: 240 });
     if (!worktreePath || !repoRoot) return error("worktreePath and repoRoot required", 400);
+    const force = parsed.body.force === true;
     // Refuse to reclaim a path that still backs a live workspace row.
     const live = listWorkspaces().find((ws) => ws.worktreePath && resolve(ws.worktreePath) === resolve(worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
     if (live) return error(`path backs live workspace ${live.id}; clean it through the workspace, not orphan reclaim`, 409);
     const orch = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
     if (!orch) return error("no online orchestrator owns this path", 409);
+    // Land-safety gate (#244): reclaim force-removes the worktree, so refuse when
+    // it holds un-landed work unless the caller explicitly opts into discarding
+    // it. Mirrors the scheduled reaper — never destroy work on uncertainty.
+    if (!force) {
+      const { orphans } = await collectWorkspaceOrphans();
+      const target = orphans.find((o) => resolve(o.worktreePath) === resolve(worktreePath));
+      if (target && target.safeToReap !== true) {
+        const why = target.safeToReap === undefined
+          ? "land-state could not be determined"
+          : target.dirty ? "uncommitted changes" : `${target.unmergedAhead ?? target.ahead ?? "?"} un-landed commit(s)`;
+        return error(`worktree holds un-landed work (${why}); recover it first, or pass {"force":true} to discard`, 409);
+      }
+    }
     const command = createCommand({
       type: "workspace.cleanup",
       source: "system",
@@ -4018,7 +4006,7 @@ const getWorkspaceDiagnostics: Handler = async (_req, params) => {
   const workspace = getWorkspace(params.id!);
   if (!workspace) return error("workspace not found", 404);
   const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
-  const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+  const ownerOnline = isOwnerAlive(workspace.ownerAgentId);
   const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
   const orchOnline = Boolean(orch) && orch!.status === "online";
   const fetched = await fetchWorkspaceGitState(workspace);
@@ -4067,7 +4055,7 @@ const postWorkspaceCleanupStale: Handler = async (req) => {
   const cleaned: string[] = [];
   for (const ws of candidates) {
     const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
-    const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+    const ownerOnline = isOwnerAlive(ws.ownerAgentId);
     if (ownerOnline) continue;                         // never clean a live owner's worktree
     if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
     if (workspaceActiveClaim(ws)) continue;            // respect steward claims
@@ -4129,7 +4117,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
         // plus the directive projection + land receipt so the CLI `--wait` and any
         // HTTP caller get the same legible answer.
         return json({
-          workspace: waited.workspace,
+          workspace: withOwnerOnline(waited.workspace),
           guidance: describeWorkspacePhase(waited.workspace),
           ...(landed ? { landed } : {}),
           fromStatus: waited.fromStatus,
@@ -4137,7 +4125,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
           timedOut: waited.timedOut,
         });
       }
-      return json(workspace);
+      return json(withOwnerOnline(workspace));
     }
 
     // Everything else delegates to the shared core (one home, shared with the
@@ -4150,6 +4138,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
       metadata: cleanMeta(parsed.body.metadata) ?? {},
       strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
       deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
+      force: parsed.body.force === true,
       prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
       prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
       purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
@@ -4158,7 +4147,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
     });
     if (!result.ok) return error(result.error, result.httpStatus);
     if (result.command) emitCommand(result.command);
-    const payload: Record<string, unknown> = { workspace: result.workspace };
+    const payload: Record<string, unknown> = { workspace: withOwnerOnline(result.workspace) };
     if (result.command) payload.command = result.command;
     if (result.claim !== undefined) payload.claim = result.claim;
     return json(payload, result.httpStatus);

package/src/workspace-actions.ts

@@ -19,8 +19,9 @@ import {
   updateWorkspaceStatus,
 } from "./db";
 import { emitActivityEvent } from "./sse";
-import { requestWorkspaceMerge } from "./workspace-merge";
+import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -50,6 +51,8 @@ export interface ApplyWorkspaceActionInput {
   deleteBranch?: boolean;
   prTitle?: string;
   prBody?: string;
+  // cleanup
+  force?: boolean;
   // claim / release-claim
   purpose?: string;
   // deps-refresh
@@ -203,6 +206,20 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   const nextStatus = STATUS_BY_ACTION[action];
   if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
 
+  if (
+    action === "cleanup" &&
+    input.force !== true &&
+    workspace.mode === "isolated" &&
+    !TERMINAL_WORKSPACE_STATUSES.has(workspace.status) &&
+    isOwnerAlive(workspace.ownerAgentId)
+  ) {
+    return {
+      ok: false,
+      httpStatus: 409,
+      error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
+    };
+  }
+
   const updated = updateWorkspaceStatus(workspace.id, nextStatus, {
     ...metadata,
     ...(detail ? { detail } : {}),
@@ -215,7 +232,7 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   let command: Command | undefined;
   if (requiresCommand) {
     // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
     if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
     command = built.command;
   }
@@ -237,7 +254,20 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
 export function buildWorkspaceCleanupCommand(
   workspace: WorkspaceRecord,
   requestedBy: string,
+  opts: { force?: boolean } = {},
 ): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  if (
+    opts.force !== true &&
+    workspace.mode === "isolated" &&
+    !TERMINAL_WORKSPACE_STATUSES.has(workspace.status) &&
+    isOwnerAlive(workspace.ownerAgentId)
+  ) {
+    return {
+      ok: false,
+      status: 409,
+      error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
+    };
+  }
   const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
   const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
   if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };

package/src/workspace-merge.ts

@@ -32,12 +32,16 @@ export type RequestWorkspaceMergeResult =
 
 // The owner is "alive" while its relay agent exists and isn't offline (online or
 // a borderline-stale disconnect both count — don't nuke a worktree on a blip).
-function isOwnerAlive(ownerAgentId: string | undefined): boolean {
+export function isOwnerAlive(ownerAgentId: string | undefined): boolean {
   if (!ownerAgentId) return false;
   const agent = getAgent(ownerAgentId);
   return Boolean(agent) && agent!.status !== "offline";
 }
 
+export function withOwnerOnline<T extends { ownerAgentId?: string }>(workspace: T): T & { ownerOnline: boolean } {
+  return { ...workspace, ownerOnline: isOwnerAlive(workspace.ownerAgentId) };
+}
+
 /**
  * Dispatch a base merge for an isolated workspace, serialized by the per-repo
  * merge lease (issue #157). Single source of truth shared by the manual

package/src/workspace-orphans.ts

@@ -0,0 +1,427 @@
+// Orphaned-worktree reconciliation (#244). An isolated worktree on disk with no
+// live DB row is "orphaned" — left behind when a session ended without a clean
+// teardown (crash, killed runner, a reaped row). Symmetrically, a live row whose
+// worktree is gone from disk is the other half of the same drift. Neither is
+// visible to the agent or the dashboard, so unlanded work can sit stranded for
+// weeks (one real casualty: a CI-guard test, recovered by hand).
+//
+// THE invariant (single home, see `worktreeReapable`): reaping is gated on
+// "nothing would be lost" — landed or empty — NEVER on session liveness or a
+// timer. A worktree holding un-landed commits is flagged for attention, never
+// force-removed. This module is the disk⇄DB reconciler the GC's `git worktree
+// prune` (a no-op while the directory exists) never was.
+
+import { resolve } from "node:path";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import type { WorkspaceMergePreview, WorkspaceOrphan, WorkspaceProbe, WorkspaceRecord, WorkspaceStatus } from "./types";
+import { createActivityEvent, getWorkspace, listOrchestrators, listWorkspaces, updateWorkspaceStatus } from "./db";
+import { createCommand } from "./commands-db";
+import { emitRelayEvent } from "./events";
+import { isPathWithinBase } from "./utils";
+import { TERMINAL_WORKSPACE_STATUSES, worktreeReapable, type WorktreeReapState } from "./workspace-phase";
+import { isOwnerAlive } from "./workspace-merge";
+
+// Don't re-flag the same un-landed orphan every sweep — surface it once, then
+// stay quiet for this window. In-memory (keyed by worktree path) like the
+// orphaned-session reaper: a restart re-announces, which is acceptable noise.
+const UNLANDED_FLAG_COOLDOWN_MS = Number(process.env.AGENT_RELAY_ORPHAN_FLAG_COOLDOWN_MS) || 6 * 60 * 60 * 1000;
+// Set AGENT_RELAY_ORPHAN_WORKTREE_REAP=0 to detect + report orphans but never
+// remove them (parity with the session reaper's detect-only switch).
+const orphanWorktreeReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
+const flaggedAt = new Map<string, number>();
+const IN_FLIGHT_MISSING_WORKTREE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "cleanup_requested"]);
+
+export function resetOrphanWorktreeStateForTests(): void {
+  flaggedAt.clear();
+}
+
+interface OnlineOrchestrator {
+  id: string;
+  agentId: string;
+  apiUrl?: string;
+  baseDir?: string;
+}
+
+function relayHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {};
+  const token = process.env.AGENT_RELAY_TOKEN;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
+  return headers;
+}
+
+async function fetchHostProbe(apiUrl: string, repoRoot: string): Promise<WorkspaceProbe | null> {
+  try {
+    const res = await fetch(`${apiUrl}/api/workspace/probe?path=${encodeURIComponent(repoRoot)}`, {
+      headers: relayHeaders(),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return null;
+    return await res.json() as WorkspaceProbe;
+  } catch {
+    return null;
+  }
+}
+
+// Land-state for a single worktree path. Reuses the host merge-preview (squash-
+// aware `landed`, `unmergedAhead`, `dirtyCount`) the conflict scan already trusts.
+async function fetchWorktreeReapState(apiUrl: string, worktreePath: string, baseRef?: string): Promise<WorkspaceMergePreview | null> {
+  const query = new URLSearchParams({ path: worktreePath, checkPr: "1" });
+  if (baseRef) query.set("baseRef", baseRef);
+  try {
+    const res = await fetch(`${apiUrl}/api/workspace/merge-preview?${query.toString()}`, {
+      headers: relayHeaders(),
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!res.ok) return null;
+    return await res.json() as WorkspaceMergePreview;
+  } catch {
+    return null;
+  }
+}
+
+type MissingBranchProbe = { kind: "gone" } | { kind: "preview"; preview: WorkspaceMergePreview } | { kind: "unavailable" };
+
+async function fetchBranchReapState(
+  apiUrl: string,
+  repoRoot: string,
+  branch: string | undefined,
+  baseRef?: string,
+  baseSha?: string,
+): Promise<MissingBranchProbe> {
+  if (!branch) return { kind: "unavailable" };
+  const query = new URLSearchParams({ repoRoot, branch, checkPr: "1" });
+  if (baseRef) query.set("baseRef", baseRef);
+  if (baseSha) query.set("baseSha", baseSha);
+  try {
+    const res = await fetch(`${apiUrl}/api/workspace/branch-merge-preview?${query.toString()}`, {
+      headers: relayHeaders(),
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (res.status === 404) return { kind: "gone" };
+    if (!res.ok) return { kind: "unavailable" };
+    return { kind: "preview", preview: await res.json() as WorkspaceMergePreview };
+  } catch {
+    return { kind: "unavailable" };
+  }
+}
+
+function previewReapable(preview: WorkspaceMergePreview): boolean | undefined {
+  if (preview.error) return undefined;
+  const hasSignal = preview.landed === true || typeof preview.ahead === "number" || typeof preview.unmergedAhead === "number";
+  if (!hasSignal) return undefined;
+  return worktreeReapable({ landed: preview.landed, ahead: preview.ahead, unmergedAhead: preview.unmergedAhead, dirtyCount: 0 });
+}
+
+function onlineOrchestrators(): OnlineOrchestrator[] {
+  return listOrchestrators()
+    .filter((orch) => orch.status === "online" && orch.apiUrl && orch.agentId)
+    .map((orch) => ({ id: orch.id, agentId: orch.agentId!, apiUrl: orch.apiUrl, baseDir: orch.baseDir }));
+}
+
+/** Repo roots any workspace row references — the seeds we probe for orphans.
+ * One probe per repo returns ALL its worktrees, so a single (even shared) row
+ * per repo is enough to discover every orphan under it. */
+function knownRepoRoots(workspaces: WorkspaceRecord[]): string[] {
+  return [...new Set(workspaces.map((ws) => ws.repoRoot).filter(Boolean))];
+}
+
+export interface CollectOrphansResult {
+  orphans: WorkspaceOrphan[];
+  /** Live isolated rows whose worktree is missing on disk (DB→disk drift). */
+  missingWorktrees: Array<{
+    workspaceId: string;
+    worktreePath: string;
+    repoRoot: string;
+    status: WorkspaceStatus;
+    branch?: string;
+    baseRef?: string;
+    baseSha?: string;
+    ownerAgentId?: string;
+  }>;
+  reason?: string;
+}
+
+/**
+ * The disk⇄DB reconcile pass. For every known repo with an online owning host:
+ * probe its worktrees, subtract live DB rows → orphans (disk without a live row),
+ * and the inverse → live rows whose worktree is gone (DB without disk). Each
+ * orphan is enriched with land-state so callers can tell reap-safe cruft from
+ * stranded work. Shared by the `/orphans` route and the scheduled reaper.
+ */
+export async function collectWorkspaceOrphans(): Promise<CollectOrphansResult> {
+  const orchestrators = onlineOrchestrators();
+  if (!orchestrators.length) return { orphans: [], missingWorktrees: [], reason: "no online orchestrators" };
+
+  const all = listWorkspaces();
+  const orphans: WorkspaceOrphan[] = [];
+  const missingWorktrees: CollectOrphansResult["missingWorktrees"] = [];
+
+  for (const repoRoot of knownRepoRoots(all)) {
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch?.apiUrl) continue;
+    const probe = await fetchHostProbe(orch.apiUrl, repoRoot);
+    if (!probe?.worktrees) continue;
+
+    const liveRowsByPath = new Map(
+      all
+        .filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath && !TERMINAL_WORKSPACE_STATUSES.has(ws.status))
+        .map((ws) => [resolve(ws.worktreePath), ws]),
+    );
+    const onDisk = new Set(probe.worktrees.map((wt) => (wt.path ? resolve(wt.path) : "")).filter(Boolean));
+
+    // DB→disk drift: a live isolated row whose worktree is no longer on disk.
+    for (const [path, ws] of liveRowsByPath) {
+      if (ws.mode === "isolated" && !onDisk.has(path)) {
+        missingWorktrees.push({
+          workspaceId: ws.id,
+          worktreePath: ws.worktreePath,
+          repoRoot,
+          status: ws.status,
+          branch: ws.branch,
+          baseRef: ws.baseRef,
+          baseSha: ws.baseSha,
+          ownerAgentId: ws.ownerAgentId,
+        });
+      }
+    }
+
+    // disk→DB drift: a worktree on disk with no live row.
+    const rowsByPath = new Map(
+      all.filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath).map((ws) => [resolve(ws.worktreePath), ws]),
+    );
+    for (const worktree of probe.worktrees) {
+      if (!worktree.path || resolve(worktree.path) === resolve(repoRoot)) continue;
+      // Only agent-relay-created worktrees (agent/* branches) are reclaimable —
+      // never touch a user's own linked worktrees.
+      if (!worktree.branch?.startsWith("agent/")) continue;
+      const row = rowsByPath.get(resolve(worktree.path));
+      if (row && !TERMINAL_WORKSPACE_STATUSES.has(row.status)) continue; // tracked & live
+
+      const orphan: WorkspaceOrphan = {
+        worktreePath: worktree.path,
+        repoRoot,
+        branch: worktree.branch,
+        headSha: worktree.headSha,
+        hadTerminalRow: Boolean(row),
+      };
+      const preview = await fetchWorktreeReapState(orch.apiUrl, worktree.path, probe.branch);
+      if (preview && !preview.missing && !preview.error) {
+        const state: WorktreeReapState = {
+          landed: preview.landed,
+          ahead: preview.ahead,
+          unmergedAhead: preview.unmergedAhead,
+          dirtyCount: preview.dirtyCount,
+        };
+        orphan.landed = preview.landed;
+        orphan.ahead = preview.ahead;
+        orphan.unmergedAhead = preview.unmergedAhead;
+        orphan.dirty = (preview.dirtyCount ?? 0) > 0;
+        orphan.safeToReap = worktreeReapable(state);
+      }
+      // No probe → safeToReap stays undefined (treated as not-safe by callers).
+      orphans.push(orphan);
+    }
+  }
+
+  return { orphans, missingWorktrees };
+}
+
+function dispatchCleanup(orch: OnlineOrchestrator, orphan: WorkspaceOrphan): string {
+  const command = createCommand({
+    type: "workspace.cleanup",
+    source: "system",
+    target: orch.agentId,
+    params: {
+      action: "cleanup",
+      worktreePath: orphan.worktreePath,
+      repoRoot: orphan.repoRoot,
+      branch: orphan.branch,
+      deleteBranch: true,
+      reclaim: true,
+      requestedBy: "workspace-orphan-reaper",
+      requestedAt: Date.now(),
+    },
+  });
+  emitRelayEvent({ type: `command.${command.status}`, source: command.source, subject: command.id, data: { command } });
+  return command.id;
+}
+
+/**
+ * Scheduled reaper (maintenance job). Auto-removes orphaned worktrees that are
+ * safe to reap (landed/empty, clean tree) and flags the rest — un-landed work or
+ * an un-probeable host — as needs-attention instead of destroying them. Also
+ * reports the inverse drift (live rows whose worktree vanished) so both
+ * directions surface. Never removes on uncertainty.
+ */
+export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>> {
+  const { orphans, missingWorktrees, reason } = await collectWorkspaceOrphans();
+  if (reason) return { skipped: reason };
+
+  const orchestrators = onlineOrchestrators();
+  const reapEnabled = orphanWorktreeReapEnabled();
+  const reaped: string[] = [];
+  const flagged: string[] = [];
+  const autoAbandoned: string[] = [];
+  const flaggedMissingWorktrees: string[] = [];
+  const now = Date.now();
+
+  for (const orphan of orphans) {
+    const orch = orchestrators.find((candidate) => isPathWithinBase(orphan.repoRoot, candidate.baseDir));
+    if (!orch) continue;
+
+    if (orphan.safeToReap === true) {
+      if (!reapEnabled) continue; // detect-only mode
+      const commandId = dispatchCleanup(orch, orphan);
+      reaped.push(orphan.worktreePath);
+      flaggedAt.delete(orphan.worktreePath);
+      createActivityEvent({
+        clientId: `workspace-orphan-reaped-${orphan.worktreePath}-${now}`,
+        kind: "state",
+        title: "Orphaned worktree reaped",
+        body: `${orphan.branch ?? orphan.worktreePath} — ${orphan.landed ? "work already landed" : "no work to preserve"}; removing the stale worktree`,
+        meta: orphan.branch ?? orphan.worktreePath,
+        icon: "ti-trash",
+        view: "orchestrators",
+        metadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", worktreePath: orphan.worktreePath, repoRoot: orphan.repoRoot, commandId, landed: orphan.landed },
+      });
+      continue;
+    }
+
+    // Not safe (un-landed work, dirty tree, or un-probeable) — flag once per
+    // cooldown, never remove. This is the stranded-work needs-attention entry.
+    const last = flaggedAt.get(orphan.worktreePath) ?? 0;
+    if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+    flaggedAt.set(orphan.worktreePath, now);
+    flagged.push(orphan.worktreePath);
+    const detail = orphan.safeToReap === undefined
+      ? "host could not be probed for land-state"
+      : orphan.dirty
+        ? "uncommitted changes in the worktree"
+        : `${orphan.unmergedAhead ?? orphan.ahead ?? "?"} un-landed commit(s)`;
+    createActivityEvent({
+      clientId: `workspace-orphan-stranded-${orphan.worktreePath}-${now}`,
+      kind: "state",
+      title: "Stranded worktree needs attention",
+      body: `${orphan.branch ?? orphan.worktreePath} in ${orphan.repoRoot} is orphaned (no live workspace row) and holds work that hasn't landed — ${detail}. Reclaim with force to discard, or recover the commits before removing.`,
+      meta: orphan.branch ?? orphan.worktreePath,
+      icon: "ti-alert-triangle",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", worktreePath: orphan.worktreePath, repoRoot: orphan.repoRoot, branch: orphan.branch, ahead: orphan.ahead, unmergedAhead: orphan.unmergedAhead, dirty: orphan.dirty, headSha: orphan.headSha },
+    });
+  }
+
+  for (const missing of missingWorktrees) {
+    const workspace = getWorkspace(missing.workspaceId);
+    if (!workspace || TERMINAL_WORKSPACE_STATUSES.has(workspace.status) || workspace.mode !== "isolated" || !workspace.worktreePath) continue;
+    const key = `missing:${workspace.worktreePath}`;
+    const ownerAlive = isOwnerAlive(workspace.ownerAgentId);
+    const inFlight = IN_FLIGHT_MISSING_WORKTREE_STATUSES.has(workspace.status);
+    const last = flaggedAt.get(key) ?? 0;
+    if (ownerAlive || inFlight) {
+      if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+      flaggedAt.set(key, now);
+      createActivityEvent({
+        clientId: `workspace-row-no-worktree-${workspace.id}-${now}`,
+        kind: "state",
+        title: "Workspace row has no worktree on disk",
+        body: `Workspace ${workspace.id} (${workspace.status}) points at ${workspace.worktreePath}, which no longer exists on disk — disk/DB drift.`,
+        meta: workspace.id,
+        icon: "ti-unlink",
+        view: "orchestrators",
+        metadata: {
+          source: "server",
+          maintenanceJobId: "workspace-orphan-reaper",
+          workspaceId: workspace.id,
+          worktreePath: workspace.worktreePath,
+          status: workspace.status,
+          ownerAlive,
+          inFlight,
+        },
+      });
+      continue;
+    }
+
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(workspace.repoRoot, candidate.baseDir));
+    const probe = orch?.apiUrl
+      ? await fetchBranchReapState(orch.apiUrl, workspace.repoRoot, workspace.branch, workspace.baseRef, workspace.baseSha)
+      : { kind: "unavailable" } as const;
+    const safeToAbandon = probe.kind === "gone"
+      ? true
+      : probe.kind === "preview"
+        ? previewReapable(probe.preview)
+        : undefined;
+
+    if (safeToAbandon === true) {
+      const reasonText = probe.kind === "gone" ? "missing worktree; branch ref gone" : "missing worktree; branch already landed";
+      const updated = updateWorkspaceStatus(workspace.id, "abandoned", {
+        autoAbandoned: true,
+        abandonedReason: reasonText,
+        abandonedAt: now,
+      });
+      if (!updated) continue;
+      autoAbandoned.push(workspace.id);
+      flaggedAt.delete(key);
+      createActivityEvent({
+        clientId: `workspace-row-auto-abandoned-${workspace.id}-${now}`,
+        kind: "state",
+        title: "Workspace auto-abandoned",
+        body: `${workspace.branch ?? workspace.id} in ${workspace.repoRoot} — worktree missing and ${probe.kind === "gone" ? "branch ref is gone" : "branch has fully landed"}`,
+        meta: workspace.branch ?? workspace.id,
+        icon: "ti-clock-x",
+        view: "orchestrators",
+        metadata: {
+          source: "server",
+          maintenanceJobId: "workspace-orphan-reaper",
+          workspaceId: workspace.id,
+          worktreePath: workspace.worktreePath,
+          branch: workspace.branch,
+          reason: reasonText,
+        },
+      });
+      continue;
+    }
+
+    if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+    flaggedAt.set(key, now);
+    flaggedMissingWorktrees.push(workspace.id);
+    const detail = probe.kind === "preview"
+      ? `${probe.preview.unmergedAhead ?? probe.preview.ahead ?? "?"} un-landed commit(s) still recoverable on branch ${workspace.branch ?? workspace.id}`
+      : workspace.branch
+        ? `host could not confirm whether branch ${workspace.branch} has landed`
+        : "host could not confirm whether recoverable branch work remains";
+    createActivityEvent({
+      clientId: `workspace-row-needs-attention-${workspace.id}-${now}`,
+      kind: "state",
+      title: "Missing-worktree workspace needs attention",
+      body: `${workspace.id} in ${workspace.repoRoot} has no worktree on disk and cannot be auto-abandoned safely — ${detail}. Recover via the branch if needed, then abandon or clean it up explicitly.`,
+      meta: workspace.id,
+      icon: "ti-alert-triangle",
+      view: "orchestrators",
+      metadata: {
+        source: "server",
+        maintenanceJobId: "workspace-orphan-reaper",
+        workspaceId: workspace.id,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        status: workspace.status,
+        probe: probe.kind,
+        ...(probe.kind === "preview" ? { ahead: probe.preview.ahead, unmergedAhead: probe.preview.unmergedAhead, landed: probe.preview.landed } : {}),
+      },
+    });
+  }
+
+  // Forget cooldown entries for orphans that are gone (reaped/recovered) so a
+  // future re-orphaning of the same path re-announces immediately.
+  const liveKeys = new Set([...orphans.map((o) => o.worktreePath), ...missingWorktrees.map((m) => `missing:${m.worktreePath}`)]);
+  for (const key of flaggedAt.keys()) if (!liveKeys.has(key) && !reaped.includes(key)) flaggedAt.delete(key);
+
+  return {
+    scanned: orphans.length,
+    reaped,
+    flagged,
+    autoAbandoned,
+    flaggedMissingWorktrees,
+    missingWorktrees: missingWorktrees.map((m) => m.workspaceId),
+    reapEnabled,
+  };
+}