agent-relay-server 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.24.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.13"
+    "agent-relay-sdk": "0.2.15"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -10168,6 +10168,8 @@ function parseSseFrame(frame) {
 }
 //#endregion
 //#region src/lib/api.ts
+var API_TIMEOUT_MS = 2e4;
+var SSE_STALE_MS = 35e3;
 var authToken = "";
 function setAuthToken(token) {
 	authToken = token;
@@ -10211,11 +10213,11 @@ function openTerminalWebSocket(orchestratorId, session) {
 	return new WebSocket(url);
 }
 function openRelayEventStream(token, handlers) {
-	const abort = new AbortController();
 	const eventUrl = new URL("api/events", baseUrl()).toString();
 	let closed = false;
 	let retryMs = 5e3;
 	let reconnectTimer = null;
+	let activeAbort = null;
 	const scheduleReconnect = () => {
 		if (closed) return;
 		reconnectTimer = setTimeout(connect, retryMs);
@@ -10226,6 +10228,11 @@ function openRelayEventStream(token, handlers) {
 		if (data.length > 0) handlers.message(event, data.join("\n"));
 	};
 	const connect = async () => {
+		if (closed) return;
+		const ac = new AbortController();
+		activeAbort = ac;
+		let lastFrameAt = Date.now();
+		let staleTimer = null;
 		try {
 			const headers = { Accept: "text/event-stream" };
 			const effectiveToken = token || getAuthToken();
@@ -10233,10 +10240,14 @@ function openRelayEventStream(token, handlers) {
 			const response = await fetch(eventUrl, {
 				headers,
 				cache: "no-store",
-				signal: abort.signal
+				signal: ac.signal
 			});
 			if (!response.ok || !response.body) throw new Error(`SSE failed: ${response.status}`);
 			handlers.connected?.();
+			lastFrameAt = Date.now();
+			staleTimer = setInterval(() => {
+				if (Date.now() - lastFrameAt > SSE_STALE_MS) ac.abort();
+			}, 5e3);
 			const reader = response.body.getReader();
 			const decoder = new TextDecoder();
 			let buffer = "";
@@ -10246,6 +10257,7 @@ function openRelayEventStream(token, handlers) {
 					buffer += decoder.decode();
 					break;
 				}
+				lastFrameAt = Date.now();
 				buffer += decoder.decode(value, { stream: true });
 				let frameEnd = buffer.indexOf("\n\n");
 				while (frameEnd >= 0) {
@@ -10256,6 +10268,7 @@ function openRelayEventStream(token, handlers) {
 				}
 			}
 		} catch {} finally {
+			if (staleTimer) clearInterval(staleTimer);
 			if (closed) return;
 			handlers.disconnected?.();
 			scheduleReconnect();
@@ -10265,13 +10278,14 @@ function openRelayEventStream(token, handlers) {
 	return { close() {
 		closed = true;
 		if (reconnectTimer) clearTimeout(reconnectTimer);
-		abort.abort();
+		activeAbort?.abort();
 	} };
 }
 async function api(method, path, body) {
 	const opts = {
 		method,
-		headers: {}
+		headers: {},
+		signal: AbortSignal.timeout(API_TIMEOUT_MS)
 	};
 	const headers = opts.headers;
 	if (authToken) headers["X-Agent-Relay-Token"] = authToken;
@@ -12991,10 +13005,13 @@ var useRelayStore = create$1()(persist((set, get) => ({
 	connectSSE() {
 		get().disconnectSSE();
 		set({ _es: openRelayEventStream(get().authToken, {
-			connected: () => set(get().connectionError ? {
-				connected: true,
-				connectionError: false
-			} : { connected: true }),
+			connected: () => {
+				set(get().connectionError ? {
+					connected: true,
+					connectionError: false
+				} : { connected: true });
+				get().refreshLiveData();
+			},
 			disconnected: () => set({ connected: false }),
 			message: (event, data) => {
 				if (event === "connected") return;

package/src/branch-landed.ts

@@ -0,0 +1,111 @@
+import { emitRelayEvent } from "./events";
+import { getNotificationsConfig } from "./config-store";
+import { notifySystemMessage } from "./notify";
+import { listAgents } from "./db";
+import { isAgentOnline } from "./agent-ref";
+import type { AgentCard, WorkspaceRecord } from "./types";
+
+export interface BranchLandedInput {
+  /**
+   * The workspace as it was AT land time — `branch` must be the branch that landed,
+   * captured before any land-and-continue recycle repoints the row (#206). `ownerAgentId`
+   * is the author the "landed" notice is pushed to.
+   */
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  /** SHA the base now points at after the land. */
+  mergedSha?: string;
+  /** Subject line of the landed commit, when the orchestrator reported it. */
+  subject?: string;
+  /** Fresh branch the worktree was recycled onto (land-and-continue), if any. */
+  newBranch?: string;
+}
+
+/**
+ * #239 — turn an authoritative land completion into a relay-driven push so the author
+ * stops polling to learn it merged. Always emits the durable `branch.landed` event (the
+ * rest of the bus does the same); only the agent-facing push is gated, since it wakes the
+ * recipient. Offline authors get it on next poll via store-ahead (#234).
+ *
+ * Agents-on-main fan-out (the second #239 recipient class) lands in a follow-up commit.
+ */
+export function notifyBranchLanded(input: BranchLandedInput): void {
+  const { workspace } = input;
+  const base = workspace.baseRef ?? "base";
+  const landedBranch = workspace.branch;
+  const shortSha = input.mergedSha ? input.mergedSha.slice(0, 12) : undefined;
+
+  emitRelayEvent({
+    type: "branch.landed",
+    source: "server",
+    subject: workspace.id,
+    data: {
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      branch: landedBranch,
+      base,
+      sha: input.mergedSha,
+      subject: input.subject,
+      author: workspace.ownerAgentId,
+      newBranch: input.newBranch,
+    },
+  });
+
+  const config = getNotificationsConfig();
+  if (!config.enabled || !config.branchLanded) return;
+
+  const author = workspace.ownerAgentId;
+  const shaLabel = shortSha ? ` as \`${shortSha}\`` : "";
+  const subjectLabel = input.subject ? ` — "${input.subject}"` : "";
+  const payload = {
+    kind: "branch.landed",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: landedBranch,
+    base,
+    sha: input.mergedSha,
+    author,
+    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/config-store.ts

@@ -10,6 +10,7 @@ import type {
   InsightsConfig,
   ManagedAgentState,
   ManagedAgentStatus,
+  NotificationsConfig,
   SpawnApprovalMode,
   SpawnPolicy,
   SpawnProvider,
@@ -24,6 +25,8 @@ const STEWARD_NAMESPACE = "steward";
 const STEWARD_KEY = "default";
 const INSIGHTS_NAMESPACE = "insights";
 const INSIGHTS_KEY = "default";
+const NOTIFICATIONS_NAMESPACE = "notifications";
+const NOTIFICATIONS_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
 const WORKSPACE_KEY = "default";
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
@@ -460,6 +463,26 @@ function validateInsightsConfig(value: unknown): InsightsConfig {
   };
 }
 
+// Relay-driven lifecycle push notifications (#239 event bus). Default-on; the
+// operator can flip the master switch or individual events off via the generic
+// config route. Push messages wake recipients, so they must be suppressible.
+const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
+  enabled: true,
+  branchLanded: true,
+};
+
+function validateNotificationsConfig(value: unknown): NotificationsConfig {
+  if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
+  return {
+    enabled: value.enabled === undefined
+      ? NOTIFICATIONS_CONFIG_DEFAULTS.enabled
+      : cleanBoolean(value.enabled, "enabled"),
+    branchLanded: value.branchLanded === undefined
+      ? NOTIFICATIONS_CONFIG_DEFAULTS.branchLanded
+      : cleanBoolean(value.branchLanded, "branchLanded"),
+  };
+}
+
 // Global workspace provisioning config for isolated worktrees (#159 follow-up).
 // Defaults seed the two untracked paths an isolated agent almost always needs:
 // the agent guide and the rig config, both gitignored so a fresh worktree lacks them.
@@ -487,6 +510,7 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === AGENT_PROFILE_NAMESPACE) return validateAgentProfile(key, value);
   if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
+  if (namespace === NOTIFICATIONS_NAMESPACE) return validateNotificationsConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;
@@ -620,6 +644,13 @@ export function getInsightsConfigEntry(): ConfigEntry<InsightsConfig> {
   };
 }
 
+/** Lifecycle-notification config (#239), merged over defaults (always usable). */
+export function getNotificationsConfig(): NotificationsConfig {
+  const entry = getConfig<Partial<NotificationsConfig>>(NOTIFICATIONS_NAMESPACE, NOTIFICATIONS_KEY);
+  if (!entry) return { ...NOTIFICATIONS_CONFIG_DEFAULTS };
+  return validateNotificationsConfig({ ...NOTIFICATIONS_CONFIG_DEFAULTS, ...entry.value });
+}
+
 export function setInsightsConfig(value: unknown, updatedBy?: string): ConfigEntry<InsightsConfig> {
   return setConfig(INSIGHTS_NAMESPACE, INSIGHTS_KEY, value as InsightsConfig, updatedBy);
 }

package/src/maintenance.ts

@@ -27,14 +27,14 @@ import {
   releaseExpiredMergeLeases,
   releaseOrphanedTasks,
   runDbMaintenance,
-  sendMessage,
   sweepArtifacts,
   updateWorkspaceStatus,
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
-import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+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";
 import { ensureRepoSteward } from "./steward";
@@ -46,11 +46,11 @@ import {
   emitAgentStatus,
   emitMessageClaimReleased,
   emitMessageExpired,
-  emitNewMessage,
   emitOrchestratorStatus,
   emitPoolBindingChanged,
   emitTaskChanged,
 } from "./sse";
+import { notifySystemMessage } from "./notify";
 import { pruneExpiredTokenRecords } from "./token-db";
 import type { Command, MaintenanceJob, MaintenanceJobRun } from "./types";
 
@@ -67,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
@@ -83,7 +87,10 @@ const STEWARD_WAKE_COOLDOWN_MS = Number(process.env.AGENT_RELAY_STEWARD_WAKE_COO
 const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
 const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
 // Statuses that need an owner — a stranded one of these is what escalation rescues.
-const STRANDABLE_STATUSES = new Set<WorkspaceStatus>(["review_requested", "conflict"]);
+// Derived from the shared ready-to-land set (#242) plus `conflict`, so a stranded
+// `ready` worktree (no online steward) escalates to the fallback target instead of
+// rotting silently — same gap that left the original #242 branch parked.
+const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
 // Live statuses worth scanning. Terminal (cleaned/merged/abandoned) and
 // in-flight (cleanup_requested) states are skipped.
 const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
@@ -394,7 +401,7 @@ const definitions: MaintenanceJobDefinition[] = [
   {
     id: "workspace-auto-merge",
     title: "Workspace auto-merge",
-    description: "Auto-merge any non-conflicting review_requested worktree into base under the per-repo lease (rebasing when the base moved on); only real or unknown conflicts are left for the steward.",
+    description: "Auto-merge any non-conflicting ready/review_requested worktree into base under the per-repo lease (rebasing when the base moved on); only real or unknown conflicts are left for the steward.",
     intervalMs: WORKSPACE_AUTO_MERGE_INTERVAL_MS,
     runOnStart: false,
     timeoutMs: 60 * 1000,
@@ -409,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 {
@@ -532,15 +548,11 @@ function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
   const policyName = ensureRepoSteward(ws.repoRoot);
   if (!policyName) return null;
   try {
-    const msg = sendMessage({
-      from: "system",
-      to: `policy:${policyName}`,
-      kind: "system",
+    notifySystemMessage(`policy:${policyName}`, {
       subject: `Steward: ${ws.status} workspace needs attention`,
       body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
       payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
     });
-    emitNewMessage(msg);
     getLifecycleManager().onMessageForPolicy(policyName);
     patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
     return policyName;
@@ -631,15 +643,11 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
         if (woke) notifiedStewards.push(woke);
       } else if (ws.stewardAgentId) {
         try {
-          const msg = sendMessage({
-            from: "system",
-            to: ws.stewardAgentId,
-            kind: "system",
+          notifySystemMessage(ws.stewardAgentId, {
             subject: "Workspace merge conflict",
             body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
             payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
           });
-          emitNewMessage(msg);
           notifiedStewards.push(ws.stewardAgentId);
         } catch {
           // Steward unregistered/stale — the activity event still records it.
@@ -657,9 +665,11 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards };
 }
 
-// Deterministic auto-land (Layer 0, issue #167 / #207). Walk the "ready to land"
-// queue (`review_requested` isolated worktrees) and land any whose merge is
-// predicted conflict-free, via the shared lease-serialized merge helper — even
+// Deterministic auto-land (Layer 0, issue #167 / #207 / #242). Walk the "ready to
+// land" queue (isolated worktrees in any READY_TO_LAND status — `ready` from
+// `relay_workspace_ready`, or `review_requested` from a failed-merge retry) and
+// land any whose merge is predicted conflict-free, via the shared lease-serialized
+// merge helper — even
 // when the base moved on (behind>0): mergeRebaseFf rebases onto the current base
 // before fast-forwarding. Only a predicted conflict or an unknown merge state is
 // left for the steward; clean parallel work lands with no agent in the loop.
@@ -669,7 +679,7 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
 
   const candidates = listWorkspaces().filter(
-    (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && ws.status === "review_requested",
+    (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && READY_TO_LAND_STATUSES.has(ws.status),
   );
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
@@ -738,7 +748,7 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
 function notifyTarget(target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
   if (!target) return null;
   try {
-    emitNewMessage(sendMessage({ from: "system", to: target, kind: "system", subject, body, payload }));
+    notifySystemMessage(target, { subject, body, payload });
     return target;
   } catch {
     return null;

package/src/notify.ts

@@ -0,0 +1,31 @@
+import { sendMessage } from "./db";
+import { emitNewMessage } from "./sse";
+import type { Message, MessageKind } from "./types";
+
+export interface SystemNotifyOptions {
+  subject?: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  /** Defaults to "system" — a bypass-targeting kind that wakes the recipient like a prompt. */
+  kind?: MessageKind;
+  /** Sender id; defaults to "system". */
+  from?: string;
+}
+
+/**
+ * Post a system DM to one agent and fan it out over the bus. This is the one home for
+ * "relay tells an agent something happened" — store-ahead delivers it on next poll if the
+ * recipient is offline (#234). Used by the GC sweep (maintenance) and lifecycle events (#239).
+ */
+export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Message {
+  const msg = sendMessage({
+    from: opts.from ?? "system",
+    to,
+    kind: opts.kind ?? "system",
+    subject: opts.subject,
+    body: opts.body,
+    payload: opts.payload,
+  });
+  emitNewMessage(msg);
+  return msg;
+}

package/src/routes.ts

@@ -177,6 +177,8 @@ import {
   WORKSPACE_ACTIONS,
 } 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,
@@ -3878,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) => {
@@ -3926,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",
@@ -4478,6 +4467,9 @@ const patchCommand: Handler = async (req, params) => {
         const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
         const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
         if (workspaceId && resultStatus) {
+          // Snapshot the row BEFORE the recycle repoints `branch` (#206) — the landed
+          // branch name + author (#239 branch.landed push) come from this pre-mutation state.
+          const landedWorkspace = getWorkspace(workspaceId);
           updateWorkspaceStatus(workspaceId, resultStatus, {
             mergeResult: command.result,
             mergeCommandId: command.id,
@@ -4491,10 +4483,20 @@ const patchCommand: Handler = async (req, params) => {
           // Land-and-continue (#206): the worktree was recycled onto a fresh branch.
           // Repoint the row so the next merge targets the live branch, not the deleted one.
           const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+          const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
           if (newBranch) {
-            const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
             setWorkspaceBranch(workspaceId, newBranch, mergedSha);
           }
+          // #239 — push the author a "your branch landed" notice (no polling). Only on a
+          // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
+          if (command.result.merged === true && landedWorkspace) {
+            notifyBranchLanded({
+              workspace: landedWorkspace,
+              mergedSha,
+              subject: cleanString(command.result.subject, "result.subject", { max: 200 }),
+              newBranch,
+            });
+          }
         }
       } else if (command.status === "failed" && command.correlationId) {
         // Merge couldn't complete — don't leave it stuck in merge_planned.

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

@@ -21,6 +21,55 @@ import type { WorkspaceRecord, WorkspaceStatus } from "./types";
 // initialize primer (don't brief an agent on a dead workspace). Was duplicated.
 export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
 
+// The "handed off, waiting to land" statuses — an agent has finished and the
+// auto-merge-back is responsible for getting the branch onto base. SINGLE HOME:
+// the auto-land consumer (maintenance `autoMergeCleanFastForwards`) and the
+// strand-escalation set MUST both derive from this. They drifted before (#242):
+// `relay_workspace_ready` sets `ready`, but the consumer only scanned
+// `review_requested`, so a clean `ready` worktree was never a merge candidate and
+// parked forever while this phase view kept reporting "healthy, wait." Producer
+// and consumer now read the same set so a `ready` can never silently fall out of
+// the land queue again. (`review_requested` is the same healthy hand-off state —
+// 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
+// sweeps means something is wrong (wrong status filter, no online orchestrator,
+// an unpushed branch, a wedged steward) and the agent/human should be told —
+// instead of the old behavior where it looked healthy for 90 minutes.
+export const LAND_PENDING_STALL_MS = 15 * 60 * 1000;
+
 export type WorkspacePhase =
   | "working" // active — your turn: commit, then mark ready
   | "land-pending" // ready | review_requested — handed off; auto-merge will land it
@@ -66,7 +115,17 @@ const READY_ACTION: WorkspaceNextAction = {
 // Map every WorkspaceStatus to the branch agent's mental model. Statuses that
 // look scary but are healthy (review_requested, conflict) carry actionNeeded:false
 // and an explicit "not your job" hint.
-export function describeWorkspacePhase(workspace: Pick<WorkspaceRecord, "status" | "branch" | "stewardAgentId">): WorkspacePhaseView {
+//
+// `opts.now` (defaults to wall-clock) drives the #242 stall watchdog: a workspace
+// pending-to-land past LAND_PENDING_STALL_MS flips from the "healthy, wait" view
+// to needs-attention with a real blocker, so the status surface the agent polls
+// can't keep masking a stuck land. The clock is `readyAt` (set once when the agent
+// marks ready, immune to the heartbeat `updated_at` bump) — not `updatedAt`, which
+// keeps ticking on every heartbeat and made the stall look fresh forever.
+export function describeWorkspacePhase(
+  workspace: Pick<WorkspaceRecord, "status" | "branch" | "stewardAgentId" | "readyAt">,
+  opts: { now?: number; stallMs?: number } = {},
+): WorkspacePhaseView {
   switch (workspace.status) {
     case "active":
       return {
@@ -78,10 +137,27 @@ export function describeWorkspacePhase(workspace: Pick<WorkspaceRecord, "status"
         blockers: [],
       };
     case "ready":
-    case "review_requested":
+    case "review_requested": {
       // The #235 crux: these are the SAME healthy "handed off, waiting" state.
       // `review_requested` reads like an escalation but is the normal post-ready
       // node; an absent steward is the healthy case, not a stall.
+      const now = opts.now ?? Date.now();
+      const stallMs = opts.stallMs ?? LAND_PENDING_STALL_MS;
+      const pendingMs = typeof workspace.readyAt === "number" ? now - workspace.readyAt : undefined;
+      // #242 watchdog: past the bound this is no longer "healthy, wait." Surface it
+      // as needs-attention with a real blocker instead of the anti-panic view, so
+      // the agent (and the dashboard) stop reporting a wedged land as healthy.
+      if (pendingMs !== undefined && pendingMs > stallMs) {
+        const mins = Math.round(pendingMs / 60_000);
+        return {
+          phase: "land-pending",
+          headline: `Stalled — handed off ${mins} min ago but still hasn't landed. A clean auto-merge runs every ~2 min, so this is past the healthy window and likely stuck (no online orchestrator, an unpushed branch, or a wedged merge/steward).`,
+          hint: "Do NOT merge, push, rebase, or touch the main checkout yourself. Flag this to a human or the repo steward — the auto-merge/steward path isn't progressing and needs attention.",
+          actionNeeded: true,
+          nextActions: [WAIT_ACTION],
+          blockers: [`pending land for ~${mins} min with no progress — auto-merge/steward isn't landing it`],
+        };
+      }
       return {
         phase: "land-pending",
         headline: "Handed off — waiting for the auto-merge to land your branch. This is the normal, healthy post-ready state (not an escalation).",
@@ -90,6 +166,7 @@ export function describeWorkspacePhase(workspace: Pick<WorkspaceRecord, "status"
         nextActions: [WAIT_ACTION],
         blockers: [],
       };
+    }
     case "merge_planned":
       return {
         phase: "landing",
@@ -157,7 +234,7 @@ export function worktreeMcpInstructions(workspace: Pick<WorkspaceRecord, "branch
     `You are in an isolated git worktree on branch ${branch}, based on ${base} — NOT the main checkout. ${base} moves under you as other agents land in parallel; that's expected.`,
     "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
     "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
-    "After `ready` the status is `review_requested` — that is the NORMAL, healthy hand-off state, not a stall. Call `relay_workspace_status` with `wait:true` to block until your branch lands; you'll then continue on a fresh rebased branch (name gains a `--N` suffix).",
+    "After `ready` the status is `ready` (a normal, healthy hand-off state, not a stall). Call `relay_workspace_status` with `wait:true` to block until your branch lands; you'll then continue on a fresh rebased branch (name gains a `--N` suffix).",
     "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
   ].join("\n");
 }