agent-relay-server 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.14"
+    "agent-relay-sdk": "0.2.15"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/src/branch-landed.ts

@@ -1,7 +1,9 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
 import { notifySystemMessage } from "./notify";
-import type { WorkspaceRecord } from "./types";
+import { listAgents } from "./db";
+import { isAgentOnline } from "./agent-ref";
+import type { AgentCard, WorkspaceRecord } from "./types";
 
 export interface BranchLandedInput {
   /**
@@ -52,26 +54,58 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
   if (!config.enabled || !config.branchLanded) return;
 
   const author = workspace.ownerAgentId;
-  if (!author) return;
-
-  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "Your branch";
   const shaLabel = shortSha ? ` as \`${shortSha}\`` : "";
   const subjectLabel = input.subject ? ` — "${input.subject}"` : "";
-  const continueLabel = input.newBranch
-    ? ` You're now on \`${input.newBranch}\` — keep working there.`
-    : " Worktree reclaimed.";
+  const payload = {
+    kind: "branch.landed",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: landedBranch,
+    base,
+    sha: input.mergedSha,
+    author,
+    newBranch: input.newBranch,
+  };
 
-  notifySystemMessage(author, {
-    subject: "Your branch landed",
-    body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${continueLabel}`,
-    payload: {
-      kind: "branch.landed",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      branch: landedBranch,
-      base,
-      sha: input.mergedSha,
-      newBranch: input.newBranch,
-    },
+  // The branch author cares most — push regardless of online (store-ahead delivers it on
+  // next poll if they've moved on, #234). They land-and-continue onto the recycled branch.
+  if (author) {
+    const branchLabel = landedBranch ? `\`${landedBranch}\`` : "Your branch";
+    const continueLabel = input.newBranch
+      ? ` You're now on \`${input.newBranch}\` — keep working there.`
+      : " Worktree reclaimed.";
+    notifySystemMessage(author, {
+      subject: "Your branch landed",
+      body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${continueLabel}`,
+      payload,
+    });
+  }
+
+  // Agents on `main` — those whose cwd IS the main checkout (not an isolated worktree) —
+  // get a live "merged" notice so a long-lived main agent's context stays current as work
+  // lands under it (#239). Online-only: a stale/exited main session needs no wake, and
+  // store-ahead to it would just pile up noise. The author is in a worktree (cwd ≠ repoRoot)
+  // so it's naturally excluded; guard anyway for shared-mode owners.
+  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
+  const authorLabel = author ? ` by \`${author}\`` : "";
+  for (const agent of agentsOnMain(workspace.repoRoot, author)) {
+    notifySystemMessage(agent.id, {
+      subject: `Merged to ${base}`,
+      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.`,
+      payload,
+    });
+  }
+}
+
+// An agent is "on `main`" when its registered cwd equals the repo's main checkout — i.e. it
+// works in the base, not an isolated worktree. Excludes the author, pseudo agents (system/
+// user), channels, and offline sessions.
+function agentsOnMain(repoRoot: string, author: string | undefined): AgentCard[] {
+  return listAgents().filter((a) => {
+    if (a.id === author || a.id === "system" || a.id === "user") return false;
+    if (a.kind === "channel" || a.meta?.kind === "channel") return false;
+    const cwd = a.meta?.cwd;
+    if (typeof cwd !== "string" || cwd !== repoRoot) return false;
+    return isAgentOnline(a);
   });
 }

package/src/maintenance.ts

@@ -33,6 +33,7 @@ import {
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
+import { reapOrphanedWorktrees } from "./workspace-orphans";
 import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
@@ -66,6 +67,10 @@ const DB_VACUUM_EVERY = Number(process.env.AGENT_RELAY_DB_VACUUM_EVERY) || 7;
 let dbMaintenanceRuns = 0;
 const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
 const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
+// Disk⇄DB orphan reconcile cadence (#244). Runs on start for a boot-time pass,
+// then periodically — orphans accrue slowly (one per crashed/killed session), so
+// a 30-min sweep is plenty without hammering the hosts with probes.
+const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS) || 30 * 60 * 1000;
 // Deterministic auto-land (Layer 0): merge clean fast-forwards with no human in
 // the loop. Default on for the seamless workflow; set AGENT_RELAY_WORKSPACE_AUTO_MERGE=0
 // to require a manual or steward merge per repo. Read at call-time so operators can
@@ -411,6 +416,15 @@ const definitions: MaintenanceJobDefinition[] = [
     timeoutMs: 60 * 1000,
     handler: workspaceGC,
   },
+  {
+    id: "workspace-orphan-reaper",
+    title: "Workspace orphan reaper",
+    description: "Reconcile disk⇄DB: reap orphaned worktrees whose work has landed (or is empty), flag orphans holding un-landed work as needs-attention instead of deleting, and report rows whose worktree vanished. git worktree prune can't do this — it no-ops while the directory still exists.",
+    intervalMs: WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+    runOnStart: true,
+    timeoutMs: 2 * 60 * 1000,
+    handler: reapOrphanedWorktrees,
+  },
 ];
 
 function workspacePathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {

package/src/routes.ts

@@ -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,
@@ -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",

package/src/workspace-orphans.ts

@@ -0,0 +1,289 @@
+// 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, errMessage } from "agent-relay-sdk";
+import type { WorkspaceMergePreview, WorkspaceOrphan, WorkspaceProbe, WorkspaceRecord } from "./types";
+import { createActivityEvent, listOrchestrators, listWorkspaces } 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";
+
+// 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>();
+
+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;
+  }
+}
+
+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: 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 });
+      }
+    }
+
+    // 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 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 },
+    });
+  }
+
+  // DB→disk drift is observability-only: a live row whose worktree vanished is
+  // surfaced, not auto-deleted (the row may still be mid-land or recoverable).
+  for (const missing of missingWorktrees) {
+    const key = `missing:${missing.worktreePath}`;
+    const last = flaggedAt.get(key) ?? 0;
+    if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+    flaggedAt.set(key, now);
+    createActivityEvent({
+      clientId: `workspace-row-no-worktree-${missing.workspaceId}-${now}`,
+      kind: "state",
+      title: "Workspace row has no worktree on disk",
+      body: `Workspace ${missing.workspaceId} (${missing.status}) points at ${missing.worktreePath}, which no longer exists on disk — disk/DB drift.`,
+      meta: missing.workspaceId,
+      icon: "ti-unlink",
+      view: "orchestrators",
+      metadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", workspaceId: missing.workspaceId, worktreePath: missing.worktreePath, status: missing.status },
+    });
+  }
+
+  // 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,
+    missingWorktrees: missingWorktrees.map((m) => m.workspaceId),
+    reapEnabled,
+  };
+}

package/src/workspace-phase.ts

@@ -33,6 +33,35 @@ export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned",
 // it's also where a failed auto-merge lands for a retry, see routes.ts.)
 export const READY_TO_LAND_STATUSES = new Set<WorkspaceStatus>(["ready", "review_requested"]);
 
+// Land-state shape a host reports for a worktree (subset of WorkspaceMergePreview
+// / WorkspaceGitState — the fields that decide reapability). Kept structural so
+// both the merge-preview path and a raw git-state probe satisfy it.
+export interface WorktreeReapState {
+  /** Work already in base (squash/cherry/PR-merged). Detection only under-reports. */
+  landed?: boolean;
+  /** Commits ahead of base by raw count (a squash-landed branch still shows >0). */
+  ahead?: number;
+  /** Commits ahead whose patch is NOT already in base — the squash-aware count. */
+  unmergedAhead?: number;
+  /** Uncommitted working-tree changes. */
+  dirtyCount?: number;
+}
+
+// THE reap-safety invariant (#244): a worktree may be removed only when nothing
+// would be lost — clean tree AND (no commits ahead OR the work already landed).
+// SINGLE HOME: the orphan reaper, the orphan-reclaim gate, and the host's
+// exit-time `reconcileWorkspace` "empty" check all mean the same thing; they
+// drifted into three private copies and a land-blind force-remove slipped
+// through (the recovered NUL-guard test was one keystroke from deletion).
+// Mirror `reconcileWorkspace`: landing detection can only under-report, so an
+// uncertain worktree is NEVER reapable — it gets flagged for review instead.
+export function worktreeReapable(state: WorktreeReapState | null | undefined): boolean {
+  if (!state) return false;
+  if ((state.dirtyCount ?? 0) > 0) return false;
+  if (state.landed === true) return true;
+  return (state.unmergedAhead ?? state.ahead ?? 0) === 0;
+}
+
 // How long a workspace may sit in a ready-to-land status before the directive
 // projection stops saying "healthy, just wait" and surfaces it as needs-attention
 // (#242 watchdog). A clean auto-merge runs ~every 2 min, so a handful of missed