agent-relay-server 0.121.0 → 0.121.1

package/src/spawn-targets.ts

@@ -500,7 +500,25 @@ export function selectSpawnOrchestrator(
   orchestratorId?: string,
   cwd?: string,
   preferHost?: string,
+  /**
+   * #1034 — the caller token's `constraints.orchestrators` allow-set. When present, host
+   * SELECTION must stay INSIDE it: never silently fall back to a host the token isn't
+   * authorized for. Previously, when neither an explicit id nor a cwd nor a resolvable
+   * `preferHost` pinned the host (e.g. the caller's `machine` was transiently unset, or the
+   * caller's own host briefly flapped offline), selection grabbed `candidates[0]` — an
+   * arbitrary online host. If that host was outside the token's allow-set, the downstream
+   * `assertResourceAllowed` gate then rejected the spawn with a MISLEADING `-32001 component
+   * token cannot access this resource`, which cleared "seconds later" once the caller's host
+   * re-appeared (issue #1034). Filtering candidates to the allow-set makes selection
+   * authz-consistent: for the common single-authorized-host token it deterministically returns
+   * that host regardless of transient machine/cwd resolution, so concurrent spawns no longer
+   * spuriously reject; when the authorized host is genuinely offline, the error is an honest
+   * "authorized host offline", not a confusing authz denial. Undefined/empty = no filtering
+   * (admin `*` tokens, byte-identical to before).
+   */
+  allowedOrchestratorIds?: string[],
 ): Orchestrator {
+  const allowSet = allowedOrchestratorIds?.length ? new Set(allowedOrchestratorIds) : null;
   if (orchestratorId) {
     const orchestrator = getOrchestrator(orchestratorId);
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
@@ -515,7 +533,9 @@ export function selectSpawnOrchestrator(
     }
     return orchestrator;
   }
-  const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
+  const candidates = listOrchestrators().filter(
+    (item) => item.status === "online" && item.providers.includes(provider) && (!allowSet || allowSet.has(item.id)),
+  );
   if (cwd) {
     const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
@@ -530,6 +550,11 @@ export function selectSpawnOrchestrator(
   }
   const orchestrator = candidates[0];
   if (!orchestrator) {
+    // #1034 — when the token's host allow-set is what emptied the candidate list, say so plainly
+    // (the caller's authorized host is offline) instead of the generic "no orchestrator" miss.
+    if (allowSet) {
+      throw new McpNotFoundError(`no online orchestrator authorized for this token runs provider '${provider}'. Your token is scoped to host(s): ${[...allowSet].join(", ")} — check that one is online (call relay_spawn_targets for the live matrix).`);
+    }
     throw new McpNotFoundError(`no online orchestrator runs provider '${provider}'. Available: ${spawnAlternatives()} (call relay_spawn_targets for the live matrix).`);
   }
   return orchestrator;

package/src/sse.ts

@@ -1,5 +1,5 @@
 import { getAgent, getOrchestrator, matchingDeliveryAgents, onWorkspaceChange, sendMessageWithResult, setChannelSubscriberProbe } from "./db";
-import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
+import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
@@ -348,8 +348,7 @@ interface ReplayPlan {
 function replayPlan(lastEventId: number): ReplayPlan {
   const since = Number.isSafeInteger(lastEventId) && lastEventId > 0 ? lastEventId : 0;
   if (since === 0) return { requested: false, since: 0, available: false, gap: false };
-  const oldest = getOldestOutboxCursor();
-  const gap = oldest > 0 && oldest > since + 1;
+  const gap = hasReplayGap(since);
   return { requested: true, since, available: !gap, gap };
 }
 
@@ -359,9 +358,18 @@ function replayEventsToConnection(conn: Connection | undefined, plan: ReplayPlan
     send(conn, "replay.gap", { since: plan.since }, getOutboxCursor());
     return;
   }
+  // Drain the whole backlog in pages. A single capped replay dropped everything past the first 500
+  // events between the client's cursor and the outbox head (#1022 F1) — the SSE stream then went
+  // live from the head with no signal, so the tail was lost. Loop until the page is not truncated.
   const agentCache = new Map<string, AgentCard | null>();
-  for (const event of replayEvents(plan.since)) {
-    sendReplayEvent(conn, outboxToRelayEvent(event), agentCache);
+  let since = plan.since;
+  for (;;) {
+    const slice = replayEventsSlice(since);
+    for (const event of slice.events) {
+      sendReplayEvent(conn, outboxToRelayEvent(event), agentCache);
+    }
+    if (!slice.truncated) break;
+    since = slice.lastSeq;
   }
 }
 

package/src/workspace-auto-merge.ts

@@ -43,6 +43,7 @@ import { settleWorkspaceCommand } from "./workspace-command-settle";
 import { CLEAR_MERGE_NO_PROGRESS, MAX_NO_PROGRESS_MERGE_ATTEMPTS, mergeNoProgressCount, noteMergeNoProgress } from "./workspace-merge-progress";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { workspaceActiveClaim } from "./workspace-claim";
+import { notifyWorkspaceHumanEscalation } from "./workspace-human-escalation";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
 import { fetchHostMergePreview } from "./workspace-probe";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
@@ -119,20 +120,33 @@ function autoMergeRequestOptions(ws: WorkspaceRecord): AutoMergeRequestOptions {
 // auto-provision the policy on the workspace-owning host, then queue a `policy:` wake
 // message (which also spawns the on-demand agent now via onMessageForPolicy). Honors a
 // per-workspace cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
-// Returns the steward policy name on a fresh wake, or null (disabled / no owner / cooled down).
-export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
+// The result of trying to wake the managed steward (#1021 A1). `ok` carries the policy name
+// only when a steward is genuinely alive or was just spawned. On `!ok`, `cooldown` tells a
+// fresh failure (nothing spawned — the caller should advance the loop-breaker) apart from a
+// recent successful wake still inside its cooldown window (NOT a failure — leave it be).
+export type StewardWakeOutcome =
+  | { ok: true; policy: string }
+  | { ok: false; cooldown: boolean; error?: string };
+
+// Wake the managed per-host/repo steward for a workspace it should handle: auto-provision
+// the policy on the workspace-owning host, queue a `policy:` wake message, and spawn the
+// on-demand agent. Only reports `ok` when the spawn actually happened (or a steward was
+// already live) — a queued message alone is NOT a wake (#1021 A1). Honors a per-workspace
+// cooldown so a persistent conflict/behind row isn't re-pinged every sweep.
+export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): StewardWakeOutcome {
   const meta = ws.metadata as Record<string, unknown>;
   const lastWoke = typeof meta.stewardWokenAt === "number" ? meta.stewardWokenAt : 0;
-  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return null;
+  if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return { ok: false, cooldown: true };
   const ownerResult = stewardOwnerForWorkspace(ws);
   if ("error" in ownerResult) {
     patchWorkspaceMetadata(ws.id, { stewardWakeError: ownerResult.error, stewardWakeErrorAt: Date.now() });
-    return null;
+    return { ok: false, cooldown: false, error: ownerResult.error };
   }
   const policyName = ensureRepoSteward(ws.repoRoot, ownerResult.owner);
   if (!policyName) {
-    patchWorkspaceMetadata(ws.id, { stewardWakeError: "cannot spawn steward: steward policy could not be provisioned", stewardWakeErrorAt: Date.now() });
-    return null;
+    const error = "cannot spawn steward: steward policy could not be provisioned";
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: error, stewardWakeErrorAt: Date.now() });
+    return { ok: false, cooldown: false, error };
   }
   // #640 — resolve the identity triangle so the steward isn't blind to the people-graph:
   // the workspace's branch agent (owner) and that agent's coordinator (owner's `spawnedBy`).
@@ -163,7 +177,16 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
         payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason, ownerAgentId, coordinatorAgentId },
       },
     });
-    getLifecycleManager().onMessageForPolicy(policyName);
+    // #1021 A1 — the durable `policy:` obligation is enqueued above (it survives until a
+    // steward claims it), but a wake is only real if a steward actually spawned or is
+    // already live. If nothing spawned (host offline / provider error), record the error and
+    // report failure — do NOT stamp stewardWokenAt (which arms the cooldown) or claim a
+    // hand-off that never happened.
+    const spawn = getLifecycleManager().onMessageForPolicy(policyName);
+    if (!spawn.woke) {
+      patchWorkspaceMetadata(ws.id, { stewardWakeError: spawn.reason, stewardWakeErrorAt: Date.now() });
+      return { ok: false, cooldown: false, error: spawn.reason };
+    }
     patchWorkspaceMetadata(ws.id, {
       stewardWokenAt: Date.now(),
       stewardPolicy: policyName,
@@ -173,10 +196,11 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
     });
     // #641/#642 — tell the owner which steward took over and proactively loop in its coordinator.
     notifyStewardHandoff({ workspace: ws, stewardId: policyName, coordinatorAgentId, reason });
-    return policyName;
+    return { ok: true, policy: policyName };
   } catch (e) {
-    patchWorkspaceMetadata(ws.id, { stewardWakeError: e instanceof Error ? e.message : "failed to wake steward", stewardWakeErrorAt: Date.now() });
-    return null;
+    const error = e instanceof Error ? e.message : "failed to wake steward";
+    patchWorkspaceMetadata(ws.id, { stewardWakeError: error, stewardWakeErrorAt: Date.now() });
+    return { ok: false, cooldown: false, error };
   }
 }
 
@@ -227,25 +251,36 @@ function escalateNoProgressMerge(ws: WorkspaceRecord): void {
   const { coordinatorAgentId } = resolveStewardIdentity(ws);
   const fallback = stewardFallbackTarget();
   const recipients = [...new Set([coordinatorAgentId, fallback, ws.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  const subject = "Workspace can't auto-land — needs attention";
+  const body = renderTemplate("steward.merge-stall", {
+    branch: `\`${ws.branch ?? ws.id}\``,
+    repoRoot: ws.repoRoot,
+    attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
+    mergeError,
+    baseRef: ws.baseRef ?? "base",
+  });
+  const payload = { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError };
+  let escalated = false;
   if (recipients.length) {
     routeNotification({
       type: "workspace.stranded_escalation",
       scope: { workspaceId: ws.id, repoRoot: ws.repoRoot, author: ws.ownerAgentId, parent: coordinatorAgentId ?? undefined },
       recipients,
       message: {
-        subject: "Workspace can't auto-land — needs attention",
-        body: renderTemplate("steward.merge-stall", {
-          branch: `\`${ws.branch ?? ws.id}\``,
-          repoRoot: ws.repoRoot,
-          attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
-          mergeError,
-          baseRef: ws.baseRef ?? "base",
-        }),
-        payload: { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError },
+        subject,
+        body,
+        payload,
       },
     });
+    escalated = true;
+  } else {
+    const human = notifyWorkspaceHumanEscalation({ subject, body, payload, source: "workspace-auto-merge" });
+    escalated = human.accepted;
+    if (!human.accepted) {
+      console.warn(`[workspace-auto-merge] no-progress escalation for ${ws.id} had zero agent recipients and no human channel: ${human.reason ?? "unknown reason"}`);
+    }
   }
-  patchWorkspaceMetadata(ws.id, { autoMergeBackedOffAt: Date.now() });
+  if (escalated) patchWorkspaceMetadata(ws.id, { autoMergeBackedOffAt: Date.now() });
   createActivityEvent({
     clientId: `workspace-auto-merge-backoff-${ws.id}-${Date.now()}`,
     kind: "state",
@@ -349,6 +384,22 @@ async function landCandidates(
     const preview = await fetchFirstUsableMergePreview(ws, orchestrators);
     if (!preview) {
       previewUnavailable.push(ws.id);
+      // #1025 A5 — a lane whose preview is persistently unusable (owner host offline, the
+      // worktree path is gone, or every probe returns error/missing) used to exit here with
+      // ZERO side effects: no no-progress, no wake, no notify — a ready branch would strand
+      // silently forever. Give it the SAME no-progress/strand path as the unknown-merge-state
+      // lane so no status is escalation-blind: advance the loop-breaker, and once it crosses
+      // the cap, escalateNoProgressMerge fires the owner `landed-failure` wake + steward/
+      // coordinator escalation. A transient blip self-clears when a usable preview returns.
+      const held = patchWorkspaceMetadata(ws.id, {
+        ...noteMergeNoProgress(ws.metadata),
+        mergeError: "no online host returned a usable merge preview (owner offline, worktree missing, or probe error)",
+        lastPreviewUnavailableAt: Date.now(),
+      }) ?? ws;
+      if (mergeNoProgressCount(held.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+        backedOff.push(ws.id);
+        escalateNoProgressMerge(held);
+      }
       continue;
     }
     const p = preview as WorkspaceMergePreview;
@@ -401,21 +452,26 @@ async function landCandidates(
         }
       }
       leftForSteward.push(ws.id);
-      let woke: string | null = null;
       if (stewardEnabled) {
-        woke = wakeRepoSteward(handoffWorkspace, p.conflict === true ? "conflict" : "merge state unknown");
-        if (woke) wokeStewards.push(woke);
-      }
-      if (stewardEnabled && !woke && p.conflict === true) {
-        const failedHandoff = patchWorkspaceMetadata(ws.id, {
-          ...noteMergeNoProgress(ws.metadata),
-          mergeError: "cannot spawn steward on the workspace owning host",
-          lastStewardWakeFailedAt: Date.now(),
-        }) ?? ws;
-        if (mergeNoProgressCount(failedHandoff.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
-          backedOff.push(ws.id);
-          escalateNoProgressMerge(failedHandoff);
-          continue;
+        const wake = wakeRepoSteward(handoffWorkspace, p.conflict === true ? "conflict" : "merge state unknown");
+        if (wake.ok) {
+          wokeStewards.push(wake.policy);
+        } else if (!wake.cooldown && p.conflict === true) {
+          // #1021 A1+A2 — a GENUINE wake failure (nothing spawned: host offline / provider
+          // error) now correctly yields !ok, so the conflict lane's loop-breaker advances and
+          // escalateNoProgressMerge becomes reachable. A cooldown means a steward WAS woken
+          // recently and is presumably working — that is not a failure, so don't count it (and
+          // don't mislabel the cooldown as a spawn failure in mergeError). Carry the real error.
+          const failedHandoff = patchWorkspaceMetadata(ws.id, {
+            ...noteMergeNoProgress(ws.metadata),
+            mergeError: wake.error ?? "cannot spawn steward on the workspace owning host",
+            lastStewardWakeFailedAt: Date.now(),
+          }) ?? ws;
+          if (mergeNoProgressCount(failedHandoff.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+            backedOff.push(ws.id);
+            escalateNoProgressMerge(failedHandoff);
+            continue;
+          }
         }
       }
       if (p.conflict === true) {

package/src/workspace-escalation.ts

@@ -1,23 +1,43 @@
 import { stewardFallbackTarget } from "./config";
 import { routeNotification } from "./notification-router";
+import { raiseOperatorAlarm } from "./operator-alarm";
 import { resolveStewardIdentity } from "./steward-identity";
+import { notifyWorkspaceHumanEscalation } from "./workspace-human-escalation";
 import type { NotificationType } from "./notification-types";
 import type { WorkspaceRecord, WorkspaceStatus } from "./types";
 
 export const READY_TO_LAND_ESCALATION_STATUSES = new Set<WorkspaceStatus>(["ready", "review_requested"]);
 
-export function routeWorkspaceCustodyEscalation(input: {
+export interface WorkspaceCustodyEscalationInput {
   workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "status" | "ownerAgentId">;
   type?: NotificationType;
   subject: string;
   body: string;
   payload: Record<string, unknown>;
   idempotencyKey?: string;
-}): string[] {
+}
+
+export function routeWorkspaceCustodyEscalation(input: WorkspaceCustodyEscalationInput): string[] {
   const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(input.workspace);
   const fallback = stewardFallbackTarget();
   const recipients = [...new Set([ownerAgentId, coordinatorAgentId, fallback].filter((value): value is string => Boolean(value)))];
-  if (!recipients.length) return [];
+  if (!recipients.length) {
+    const payload = {
+      ...input.payload,
+      coordinatorAgentId,
+      ownerAgentId,
+      fallbackTarget: fallback || undefined,
+    };
+    const human = notifyWorkspaceHumanEscalation({
+      subject: input.subject,
+      body: input.body,
+      payload,
+      source: "workspace-custody",
+    });
+    if (human.accepted && human.channelId) return [human.channelId];
+    console.warn(`[workspace-escalation] zero agent recipients and no human channel for workspace ${input.workspace.id}: ${human.reason ?? "unknown reason"}`);
+    return [];
+  }
 
   routeNotification({
     type: input.type ?? "workspace.stranded_escalation",
@@ -43,3 +63,32 @@ export function routeWorkspaceCustodyEscalation(input: {
   });
   return recipients;
 }
+
+// Route a custody escalation, and if it resolves to ZERO reachable recipients — owner
+// exited, coordinator idle, no `AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK` configured —
+// raise a louder operator-visible alarm instead of letting the caller silently record it
+// as "escalated" (#1025 C1/C4, same class as #1021 A4). A disk-only orphan (ownerAgentId
+// undefined) and most `review_requested` auto-abandons have no agent to page by default,
+// so without this the notice is swallowed and the strand loops in the dark. Returns the
+// (possibly empty) recipient list so the caller can still decide whether to stamp state.
+export function routeWorkspaceCustodyEscalationOrAlarm(
+  input: WorkspaceCustodyEscalationInput & { source: string },
+): string[] {
+  const { source, ...escalation } = input;
+  const targets = routeWorkspaceCustodyEscalation(escalation);
+  if (!targets.length) {
+    raiseOperatorAlarm({
+      clientId: `${escalation.idempotencyKey ?? `${escalation.workspace.id}:${escalation.subject}`}:no-recipients`,
+      source,
+      subject: escalation.subject,
+      detail: `${escalation.body} — no owner, coordinator, or fallback configured to escalate to. Configure AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK or reclaim the worktree manually.`,
+      metadata: {
+        workspaceId: escalation.workspace.id,
+        repoRoot: escalation.workspace.repoRoot,
+        branch: escalation.workspace.branch,
+        status: escalation.workspace.status,
+      },
+    });
+  }
+  return targets;
+}

package/src/workspace-human-escalation.ts

@@ -0,0 +1,68 @@
+import { errMessage } from "agent-relay-sdk";
+import { stewardFallbackTarget } from "./config";
+import { getChannel } from "./db";
+import { relayEgressToChannel, relayNotifyNtfy } from "./mcp-egress-tools";
+import { getResolvedNotificationsConfig } from "./notification-settings-store";
+
+const DEFAULT_NTFY_CHANNEL_ID = "ntfy:default";
+const WARN = "no human-reachable escalation target - stranded workspaces will page nobody. Set AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK or configure ntfy.";
+
+export interface WorkspaceHumanEscalationInput {
+  subject: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  priority?: "min" | "low" | "default" | "high" | "urgent";
+  tags?: string[];
+  source?: string;
+}
+
+export interface WorkspaceHumanEscalationResult {
+  accepted: boolean;
+  channelId?: string;
+  reason?: string;
+}
+
+export function workspaceHumanEscalationChannelId(): string {
+  return getResolvedNotificationsConfig().humanEscalationChannelId.trim();
+}
+
+export function hasHumanEscalationChannel(): boolean {
+  const channelId = workspaceHumanEscalationChannelId();
+  return Boolean(channelId && getChannel(channelId));
+}
+
+export function hasHumanReachableEscalationTarget(): boolean {
+  return Boolean(stewardFallbackTarget() || hasHumanEscalationChannel());
+}
+
+export function warnIfNoHumanReachableEscalationTarget(log: (message: string) => void = console.warn): boolean {
+  if (hasHumanReachableEscalationTarget()) return false;
+  log(WARN);
+  return true;
+}
+
+export function notifyWorkspaceHumanEscalation(input: WorkspaceHumanEscalationInput): WorkspaceHumanEscalationResult {
+  const channelId = workspaceHumanEscalationChannelId();
+  if (!channelId) return { accepted: false, reason: "no human escalation channel configured" };
+  if (!getChannel(channelId)) return { accepted: false, reason: `human escalation channel ${channelId} is not registered` };
+
+  const event: Record<string, unknown> = {
+    title: input.subject,
+    body: input.body,
+    priority: input.priority ?? "urgent",
+    tags: input.tags ?? ["agent-relay", "workspace"],
+    ...(input.payload ? { relay: input.payload } : {}),
+    ...(input.source ? { source: input.source } : {}),
+  };
+
+  try {
+    if (channelId === DEFAULT_NTFY_CHANNEL_ID) {
+      relayNotifyNtfy(event);
+    } else {
+      relayEgressToChannel({ channelId, event });
+    }
+    return { accepted: true, channelId };
+  } catch (error) {
+    return { accepted: false, channelId, reason: errMessage(error) };
+  }
+}

package/src/workspace-orphans.ts

@@ -30,7 +30,7 @@ import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "./workspa
 import { applyWorkspaceAction } from "./workspace-actions";
 import { workspaceOwnerOrchestrator } from "./workspace-host";
 import { UNLANDED_FLAG_COOLDOWN_MS, orphanGraceMs, orphanWorktreeReapEnabled, relayToken } from "./config";
-import { READY_TO_LAND_ESCALATION_STATUSES, routeWorkspaceCustodyEscalation } from "./workspace-escalation";
+import { READY_TO_LAND_ESCALATION_STATUSES, routeWorkspaceCustodyEscalationOrAlarm } from "./workspace-escalation";
 
 // 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
@@ -425,7 +425,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         ? "uncommitted changes in the worktree"
         : `${orphan.unmergedAhead ?? orphan.ahead ?? "?"} un-landed commit(s)`;
     if (orphanHasWorkEvidence(orphan)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace: { id: `orphan:${orphan.worktreePath}`, repoRoot: orphan.repoRoot, branch: orphan.branch, status: "review_requested", ownerAgentId: undefined },
         subject: "Stranded worktree needs attention",
         body: `${orphan.branch ?? orphan.worktreePath} in ${orphan.repoRoot} is orphaned and holds work that has not landed - ${detail}. Recover the commits before removing it.`,
@@ -456,7 +457,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
       if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
       flaggedAt.set(key, now);
       if (workspaceNeedsCustodyEscalation(workspace, false)) {
-        routeWorkspaceCustodyEscalation({
+        routeWorkspaceCustodyEscalationOrAlarm({
+          source: "workspace-orphan-reaper",
           workspace,
           subject: "Workspace row has no worktree on disk",
           body: `Workspace \`${workspace.branch ?? workspace.id}\` in ${workspace.repoRoot} is ${workspace.status}, but its worktree ${workspace.worktreePath} is missing on disk. This was in Relay custody; recover or explicitly abandon it.`,
@@ -506,7 +508,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
       autoAbandoned.push(workspace.id);
       flaggedAt.delete(key);
       if (workspaceNeedsCustodyEscalation(workspace, previewHasWorkEvidence(probe.kind === "preview" ? probe.preview : null))) {
-        routeWorkspaceCustodyEscalation({
+        routeWorkspaceCustodyEscalationOrAlarm({
+          source: "workspace-orphan-reaper",
           workspace,
           type: "workspace.auto_abandoned",
           subject: "Workspace auto-abandoned",
@@ -547,7 +550,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         ? `host could not confirm whether branch ${workspace.branch} has landed`
         : "host could not confirm whether recoverable branch work remains";
     if (workspaceNeedsCustodyEscalation(workspace, hasWorkEvidence)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace,
         subject: "Missing-worktree workspace needs attention",
         body: `${workspace.id} in ${workspace.repoRoot} has no worktree on disk and cannot be auto-abandoned safely - ${detail}. Recover it, then abandon or clean it up explicitly.`,
@@ -657,7 +661,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
         : `${preview?.unmergedAhead ?? preview?.ahead ?? "?"} un-landed commit(s)`;
     const hasWorkEvidence = previewHasWorkEvidence(preview);
     if (workspaceNeedsCustodyEscalation(workspace, hasWorkEvidence)) {
-      routeWorkspaceCustodyEscalation({
+      routeWorkspaceCustodyEscalationOrAlarm({
+        source: "workspace-orphan-reaper",
         workspace,
         subject: "Dead-owner worktree needs attention",
         body: `${workspace.branch ?? workspace.id} in ${workspace.repoRoot} is owned by gone agent ${workspace.ownerAgentId ?? "?"} and holds work that has not landed (${detail}). Recover the commits, then clean it up explicitly.`,

package/src/workspace-phase.ts

@@ -200,7 +200,27 @@ export function describeWorkspacePhase(
         blockers: [],
       };
     }
-    case "merge_planned":
+    case "merge_planned": {
+      // #1025 A6 — a merge is dispatched and normally settles in seconds; the in-flight
+      // watchdog recovers a genuinely-stuck one at ~20 min. But a lost merge command/result
+      // (target host gone) could leave the row here indefinitely while this view reported
+      // "healthy, wait" forever. Give it the same #242 stall clock as land-pending: past the
+      // bound, surface it as needs-attention with a real blocker instead of the anti-panic
+      // view. Clocked on `readyAt` (the stable hand-off time, immune to heartbeat bumps).
+      const now = opts.now ?? Date.now();
+      const stallMs = opts.stallMs ?? LAND_PENDING_STALL_MS;
+      const pendingMs = typeof workspace.readyAt === "number" ? now - workspace.readyAt : undefined;
+      if (pendingMs !== undefined && pendingMs > stallMs) {
+        const mins = Math.round(pendingMs / 60_000);
+        return {
+          phase: "landing",
+          headline: `Stalled — merge was dispatched ${mins} min ago but hasn't settled. A merge normally lands in seconds, so this is past the healthy window and likely stuck (the owning host went offline mid-merge, or the merge result was lost).`,
+          hint: "Do NOT merge, push, rebase, or touch the main checkout yourself. Flag this to a human or the repo steward — the merge dispatch isn't settling and needs attention.",
+          actionNeeded: true,
+          nextActions: [WAIT_ACTION],
+          blockers: [`merge dispatched ~${mins} min ago with no result — the land isn't settling`],
+        };
+      }
       return {
         phase: "landing",
         headline: renderTemplate("workspace.phase.merge-planned.headline"),
@@ -209,6 +229,7 @@ export function describeWorkspacePhase(
         nextActions: [WAIT_ACTION],
         blockers: [],
       };
+    }
     case "conflict":
       return {
         phase: "steward",