agent-relay-server 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.24.0",
+  "version": "0.25.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.14"
   },
   "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,77 @@
+import { emitRelayEvent } from "./events";
+import { getNotificationsConfig } from "./config-store";
+import { notifySystemMessage } from "./notify";
+import type { 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;
+  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.";
+
+  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,
+    },
+  });
+}

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,13 @@ 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 { 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 +45,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";
 
@@ -83,7 +82,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 +396,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,
@@ -532,15 +534,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 +629,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 +651,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 +665,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 +734,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,7 @@ import {
   WORKSPACE_ACTIONS,
 } from "./workspace-actions";
 import { describeWorkspacePhase, landReceipt, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { notifyBranchLanded } from "./branch-landed";
 import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
@@ -4478,6 +4479,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 +4495,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-phase.ts

@@ -21,6 +21,26 @@ 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"]);
+
+// 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 +86,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 +108,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 +137,7 @@ export function describeWorkspacePhase(workspace: Pick<WorkspaceRecord, "status"
         nextActions: [WAIT_ACTION],
         blockers: [],
       };
+    }
     case "merge_planned":
       return {
         phase: "landing",
@@ -157,7 +205,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");
 }