agent-relay-server 0.84.0 → 0.86.0

package/src/steward-identity.ts

@@ -0,0 +1,50 @@
+// The steward ↔ branch-agent ↔ coordinator identity triangle (#639/#640).
+//
+// When the relay hands a workspace to a steward, the steward used to know only the
+// `repoRoot`. To make a handoff legible end-to-end it needs the people-graph:
+//   - the workspace's BRANCH AGENT = `ws.ownerAgentId` (already stored on the row), and
+//   - that agent's COORDINATOR = the owner's authoritative `spawnedBy` parent (the agent
+//     that spawned the branch worker), resolved to a LIVE instance via the shared
+//     agent-ref matchers so a coordinator that restarted under a new session id still
+//     resolves to its live twin.
+//
+// One home for this resolution so the wake path, the diagnostics/inspect surface, and the
+// escalation path can never drift on "who is the coordinator for this workspace?".
+
+import { getAgent, listAgents } from "./db";
+import { resolveAgentRef } from "./agent-ref";
+import type { WorkspaceRecord } from "./types";
+
+export interface StewardIdentityTriangle {
+  /** The workspace's branch agent (owner), or undefined when the row has no owner. */
+  ownerAgentId?: string;
+  /** The branch agent's coordinator (owner's `spawnedBy` lineage) resolved to a live id, or null when none resolves. */
+  coordinatorAgentId: string | null;
+}
+
+/**
+ * Resolve the branch agent's coordinator: the owner's authoritative `spawnedBy` parent,
+ * preferring a live instance. Returns the recorded parent id when no live match exists
+ * (store-ahead still delivers to a momentarily-offline coordinator), or null when the
+ * owner is unknown or wasn't spawned by anyone (e.g. a human-launched agent).
+ */
+export function resolveCoordinatorAgentId(ownerAgentId: string | undefined): string | null {
+  if (!ownerAgentId) return null;
+  const spawnedBy = getAgent(ownerAgentId)?.spawnedBy?.trim();
+  if (!spawnedBy) return null;
+  const resolved = resolveAgentRef(spawnedBy, listAgents());
+  if (resolved.status === "resolved") return resolved.agent.id;
+  if (resolved.status === "ambiguous") {
+    // Prefer the exact recorded id among live twins; else the most-recently-seen.
+    return (resolved.candidates.find((a) => a.id === spawnedBy) ?? resolved.candidates[0])!.id;
+  }
+  // No live match — keep the authoritative recorded parent id so escalation/handoff
+  // notices still address the coordinator (store-ahead delivers when it reconnects).
+  return spawnedBy;
+}
+
+/** Resolve the full identity triangle for a workspace handoff (#640). */
+export function resolveStewardIdentity(ws: Pick<WorkspaceRecord, "ownerAgentId">): StewardIdentityTriangle {
+  const ownerAgentId = ws.ownerAgentId ?? undefined;
+  return { ownerAgentId, coordinatorAgentId: resolveCoordinatorAgentId(ownerAgentId) };
+}

package/src/steward.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { basename, resolve } from "node:path";
+import { stewardFallbackTarget } from "./config";
 import { getSpawnPolicy, getStewardConfig, setConfig } from "./config-store";
 import { listOrchestrators } from "./db";
 import { getLifecycleManager } from "./lifecycle-manager";
@@ -20,23 +21,30 @@ export function repoStewardPolicyName(repoRoot: string): string {
  * its diagnostics, rebase/resolve/check, land green ones, release on escalation.
  */
 export function buildStewardPrompt(repoRoot: string): string {
+  // #642 — escalation routes to the branch agent's COORDINATOR (named per-workspace in the
+  // wake/task message via #640), not a static `system` dead-end. The fallback target below is
+  // used ONLY when a wake message names no coordinator.
+  const fallback = stewardFallbackTarget();
+  const fallbackTarget = fallback ? `\`${fallback}\`` : "the human operator who configured this relay";
   return [
     `You are the autonomous repository steward for ${repoRoot}.`,
     "",
     "Multiple agents work this repo in isolated git worktrees. The relay auto-merges any branch that rebases cleanly — including ones whose base moved on; it hands YOU only what it can't land deterministically: real merge conflicts, or an unknown/ambiguous merge state. Your job is to land that work with no human in the loop whenever you safely can.",
     "",
+    "Each workspace belongs to a BRANCH AGENT (the owner who did the work) who in turn has a COORDINATOR (the agent that spawned it and is responsible for the merge landing). Your wake/task message names both — the `ownerAgentId` and the `coordinatorAgentId` — and `agent-relay steward inspect <id>` shows them. When you can't land work yourself, the coordinator is who you escalate to.",
+    "",
     "Use the `agent-relay` CLI for EVERY relay interaction — it wraps the relay API and is the supported toolkit, and it already attaches your session token with the right scopes. Do NOT hand-curl the HTTP API (`/api/workspaces`, …): the CLI exists so you never have to. If you ever truly must call the API directly, authenticate with the `X-Agent-Relay-Token: <your session token>` header — NOT `Authorization: Bearer $AGENT_RELAY_TOKEN`; the admin env token is not present in your environment, so Bearer will 401.",
     "Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
     "",
     "1. See the queue: `agent-relay steward queue` (workspaces in conflict / review_requested / merge_planned for this repo). The wake message(s) also name a `workspaceId`.",
     "2. CLAIM it FIRST: `agent-relay workspace claim --id <id> --purpose steward`. This stops the deterministic auto-merge from racing you while you validate. The claim auto-expires, so a crash never blocks the repo.",
-    "3. Understand it: `agent-relay steward inspect <id>` — a diagnostics briefing (owner liveness, live git state, ahead/behind, recorded-vs-live branch mismatch, and a recommended action). `agent-relay steward checks <id>` suggests check commands from the changed files.",
-    "4. `cd` into the workspace's `worktreePath` and rebase the branch onto its `baseRef` (`git rebase <baseRef>`). Resolve conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate.",
+    "3. Understand it: `agent-relay steward inspect <id>` — a diagnostics briefing (the branch agent owner + its coordinator, owner liveness, live git state, ahead/behind, recorded-vs-live branch mismatch, and a recommended action). `agent-relay steward checks <id>` suggests check commands from the changed files.",
+    "4. `cd` into the workspace's `worktreePath` and rebase the branch onto its `baseRef` (`git rebase <baseRef>`). Resolve conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate to the coordinator.",
     "5. Run the repo's checks/tests (the suggested ones, plus the project's documented commands). Fix trivial breakage you caused while rebasing; do not paper over real failures.",
     "6. If green, land it: `agent-relay workspace land --id <id> --strategy rebase-ff`. The relay rebases onto the latest base, fast-forwards, and pushes to origin under the lease. The land consumes your claim.",
-    "7. If you must stop without landing, RELEASE the claim so automation can resume: `agent-relay workspace release --id <id>`, then send a clear, specific summary to the fallback/human target.",
+    "7. If you must stop without landing, RELEASE the claim so automation can resume: `agent-relay workspace release --id <id>`, then send a clear, specific summary to the workspace's COORDINATOR (the `coordinatorAgentId` from the wake message) — they own the work and can act on it. Reply to the wake message or message that agent id directly.",
     "",
-    "Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. Never force-merge a red branch, never `git push --force` to a shared base, never discard committed work.",
+    `Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. ALWAYS escalate to the branch agent's coordinator (the \`coordinatorAgentId\` in the wake message). Only if the wake message names NO coordinator, escalate to ${fallbackTarget}. Never force-merge a red branch, never \`git push --force\` to a shared base, never discard committed work.`,
     "",
     "Be terminal-efficient and decisive. When the queue is empty, you're done — you'll be woken again when there's more.",
   ].join("\n");

package/src/team-idle-tracker.ts

@@ -11,3 +11,18 @@ export const teamIdleTracker = new Map<string, TeamIdleEntry>();
 export function getTeamIdleEntry(teamId: string): TeamIdleEntry | undefined {
   return teamIdleTracker.get(teamId);
 }
+
+// #634 — per-member heartbeat-gap watch. Kept in-memory (not derived from the live roster) ON
+// PURPOSE: a member that was ready/busy and then vanished from the roster entirely escapes any
+// roster-only enumeration, so the watch must remember it independently to detect the silence gap.
+export interface TeamMemberWatch {
+  /** Most recent time the member was seen alive (non-offline heartbeat). */
+  lastActiveAt: number;
+  /** Whether the member's CURRENT silence has already pinged the coordinator (re-armed on recovery). */
+  pinged: boolean;
+  /** Member label for a readable ping. */
+  label?: string;
+}
+
+// teamId → (memberId → watch)
+export const teamMemberWatchTracker = new Map<string, Map<string, TeamMemberWatch>>();

package/src/workspace-actions.ts

@@ -25,7 +25,7 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
-import { scheduleRepoMerge } from "./workspace-auto-merge";
+import { CLEAR_MERGE_NO_PROGRESS, scheduleRepoMerge } from "./workspace-auto-merge";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -235,6 +235,10 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
     ...metadata,
     ...(detail ? { detail } : {}),
     ...(agentId ? { updatedByAgentId: agentId } : {}),
+    // #638 — a fresh ready/request-review hand-off means the owner did more work, so a
+    // prior auto-merge no-progress back-off should clear: the new commits may resolve
+    // whatever blocked the land (e.g. a base that's since been synced). Re-arm the lane.
+    ...(READY_TO_LAND_STATUSES.has(nextStatus) ? CLEAR_MERGE_NO_PROGRESS : {}),
     lastWorkspaceAction: action,
     lastWorkspaceActionAt: Date.now(),
   });

package/src/workspace-auto-merge.ts

@@ -25,6 +25,8 @@ import {
   listWorkspaces,
   patchWorkspaceMetadata,
 } from "./db";
+import { notifyBranchLandFailed, notifyStewardHandoff } from "./branch-landed";
+import { resolveStewardIdentity } from "./steward-identity";
 import { emitCommandEvent } from "./command-events";
 import { getLandingConfig, getStewardConfig } from "./config-store";
 import { getLifecycleManager } from "./lifecycle-manager";
@@ -36,7 +38,7 @@ import { workspaceActiveClaim } from "./workspace-claim";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
 import { fetchHostMergePreview, workspacePathWithinBase } from "./workspace-probe";
 import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
-import { STEWARD_WAKE_COOLDOWN_MS, workspaceAutoMergeEnabled } from "./config";
+import { STEWARD_WAKE_COOLDOWN_MS, stewardFallbackTarget, workspaceAutoMergeEnabled } from "./config";
 
 // Don't re-wake the managed steward for the same workspace more than once per this
 // window — a persistent conflict/behind row would otherwise re-ping every sweep.
@@ -51,26 +53,126 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
   if (lastWoke && Date.now() - lastWoke < STEWARD_WAKE_COOLDOWN_MS) return null;
   const policyName = ensureRepoSteward(ws.repoRoot);
   if (!policyName) return null;
+  // #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`).
+  const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(ws);
+  const coordinatorLine = coordinatorAgentId
+    ? ` Escalate to the branch agent's coordinator \`${coordinatorAgentId}\` (not the system fallback) if you can't land it.`
+    : "";
+  const ownerLine = ownerAgentId ? ` Branch agent (owner): \`${ownerAgentId}\`.` : "";
   try {
     // Obligation (ttl null by type default): a steward task must survive until claimed/handled.
     routeNotification({
       type: "workspace.steward_task",
-      scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
+      scope: { workspaceId: ws.id, repoRoot: ws.repoRoot, author: ownerAgentId, parent: coordinatorAgentId ?? undefined },
       recipients: [`policy:${policyName}`],
       message: {
         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 },
+        body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}).${ownerLine} 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.${coordinatorLine}`,
+        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);
-    patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
+    patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName, coordinatorAgentId: coordinatorAgentId ?? undefined });
+    // #641/#642 — tell the owner which steward took over and proactively loop in its coordinator.
+    notifyStewardHandoff({ workspace: ws, stewardId: policyName, coordinatorAgentId, reason });
     return policyName;
   } catch {
     return null;
   }
 }
 
+// #638 — auto-merge loop breaker. A `workspace.merge` the orchestrator settles `failed`
+// (no progress: origin moved ahead of local base, a replay conflict the clean-preview
+// didn't predict, a push race) returns the workspace to a landable status
+// (`review_requested`). The on-settle re-trigger (routes/commands.ts → scheduleRepoMerge)
+// then re-dispatches it within a few seconds — forever. That's a silent merge-command
+// storm that churns the per-repo lease and 409s every manual land (the live incident).
+// Cap consecutive no-progress attempts per workspace; past the cap, stop dispatching and
+// escalate. The count is incremented by the merge-result handler (server owns the
+// transition) and cleared on genuine progress or a fresh ready/request-review hand-off.
+export const MAX_NO_PROGRESS_MERGE_ATTEMPTS = 3;
+
+// Don't re-escalate a backed-off lane more than once per this window.
+const NO_PROGRESS_ESCALATION_COOLDOWN_MS = 30 * 60 * 1000;
+
+/** The recorded count of consecutive no-progress merge attempts for a workspace (#638). */
+export function mergeNoProgressCount(metadata: Record<string, unknown>): number {
+  const n = metadata.autoMergeNoProgressCount;
+  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/** Metadata patch recording one more no-progress merge attempt (#638). Applied by the
+ * merge-result handler when a dispatched merge settles `failed` without landing. */
+export function noteMergeNoProgress(metadata: Record<string, unknown>): Record<string, unknown> {
+  return { autoMergeNoProgressCount: mergeNoProgressCount(metadata) + 1, autoMergeNoProgressAt: Date.now() };
+}
+
+/** Metadata patch that clears the no-progress back-off — genuine progress (a land/recycle)
+ * or a fresh hand-off means the lane is worth attempting again (#638). */
+export const CLEAR_MERGE_NO_PROGRESS: Record<string, unknown> = {
+  autoMergeNoProgressCount: 0,
+  autoMergeNoProgressAt: undefined,
+  autoMergeBackedOffAt: undefined,
+};
+
+// Surface a lane auto-merge can't advance (#638): wake the repo steward (if enabled) and
+// route a stranded-escalation notice to the configured fallback / workspace owner, so a
+// no-progress lane raises attention instead of churning silently. Cooldown-guarded so a
+// persistently-stuck row isn't re-escalated every sweep.
+function escalateNoProgressMerge(ws: WorkspaceRecord): void {
+  const meta = ws.metadata as Record<string, unknown>;
+  const lastEscalated = typeof meta.autoMergeBackedOffAt === "number" ? meta.autoMergeBackedOffAt : 0;
+  if (lastEscalated && Date.now() - lastEscalated < NO_PROGRESS_ESCALATION_COOLDOWN_MS) return;
+  const mergeError = typeof meta.mergeError === "string" && meta.mergeError ? meta.mergeError : "merge made no progress";
+  if (getStewardConfig().enabled) {
+    wakeRepoSteward(ws, `auto-merge backed off after ${MAX_NO_PROGRESS_MERGE_ATTEMPTS} no-progress attempts (${mergeError})`);
+  }
+  // Emit the owner-facing `landed-failure` wake — the SAME actionable notice the live
+  // merge_planned→failed settle fires (routes/commands.ts → notifyBranchLandFailed). The
+  // loop-breaker stops dispatching once a lane hits the no-progress cap, so without this
+  // the dispatch-coupled wake never fires again and a backed-off lane (e.g. a dirty base
+  // checkout, #638/#644) goes silent until a human re-arms it via manual request-review.
+  // The branch worker is parked specifically on `landed-failure`; the `stranded_escalation`
+  // below is a separate fallback/steward signal, not the wake the owner awaits. Cooldown is
+  // already enforced by the early-return above, so this fires at most once per backoff.
+  // (Coordinator routing — owner's `spawnedBy` — is the #642 coordinator-awareness epic.)
+  notifyBranchLandFailed({
+    workspace: ws,
+    reason: `auto-merge backed off after ${MAX_NO_PROGRESS_MERGE_ATTEMPTS} no-progress attempts (${mergeError})`,
+  });
+  // #642 — escalation must reach the branch agent's coordinator (owner's `spawnedBy`), not
+  // just the configured fallback. When steward is enabled, wakeRepoSteward above already
+  // notified the coordinator of the handoff; including it here covers the steward-disabled
+  // path too so a backed-off lane always reaches the agent responsible for the work.
+  const { coordinatorAgentId } = resolveStewardIdentity(ws);
+  const fallback = stewardFallbackTarget();
+  const recipients = [...new Set([coordinatorAgentId, fallback, ws.ownerAgentId].filter((r): r is string => Boolean(r)))];
+  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: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} failed to land ${MAX_NO_PROGRESS_MERGE_ATTEMPTS}× without progress (${mergeError}). Auto-merge has backed off to stop a merge-command loop. Sync \`${ws.baseRef ?? "base"}\` and land manually, or release the workspace.`,
+        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 },
+      },
+    });
+  }
+  patchWorkspaceMetadata(ws.id, { autoMergeBackedOffAt: Date.now() });
+  createActivityEvent({
+    clientId: `workspace-auto-merge-backoff-${ws.id}-${Date.now()}`,
+    kind: "state",
+    title: "Auto-merge backed off (no progress)",
+    body: `${ws.branch ?? ws.id} → ${ws.baseRef ?? "base"} failed to land ${MAX_NO_PROGRESS_MERGE_ATTEMPTS}× without progress — stopping the merge loop (${mergeError})`,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-alert-octagon",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-auto-merge", workspaceId: ws.id, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS },
+  });
+}
+
 interface LandSweepResult {
   scanned: number;
   merged: string[];
@@ -78,12 +180,13 @@ interface LandSweepResult {
   heldByClaim: string[];
   heldByPause: string[];
   heldAwaitingApproval: string[];
+  backedOff: string[];
   leftForSteward: string[];
   wokeStewards: string[];
 }
 
 function emptyLandSweep(): LandSweepResult {
-  return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], leftForSteward: [], wokeStewards: [] };
+  return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], backedOff: [], leftForSteward: [], wokeStewards: [] };
 }
 
 // Deterministic auto-land (Layer 0, #167/#207/#242): land conflict-free ready work
@@ -95,13 +198,22 @@ async function landCandidates(
 ): Promise<LandSweepResult> {
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
-  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
+  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], backedOff: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
 
   for (const ws of candidates) {
     if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
     // A claimed workspace is being validated by a steward — don't race it (#208).
     if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
     if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
+    // #638 loop breaker: a lane whose last N merges settled `failed` without landing
+    // can't be advanced by re-dispatching — stop the storm, escalate once, and leave it
+    // for a steward/human. Cleared on genuine progress or a fresh hand-off (the agent did
+    // more work), so this is a back-off, not a permanent ban.
+    if (mergeNoProgressCount(ws.metadata) >= MAX_NO_PROGRESS_MERGE_ATTEMPTS) {
+      backedOff.push(ws.id);
+      escalateNoProgressMerge(ws);
+      continue;
+    }
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
@@ -164,7 +276,7 @@ async function landCandidates(
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, backedOff, leftForSteward, wokeStewards };
 }
 
 // Coalesced, fire-and-forget per-repo land trigger (see module header). A run already

package/src/workspace-merge.ts

@@ -3,6 +3,7 @@ import { isRecord, stringValue } from "agent-relay-sdk";
 import { createCommand } from "./commands-db";
 import {
   acquireMergeLease,
+  getActiveMergePause,
   getAgent,
   listAgents,
   listOrchestrators,
@@ -186,6 +187,15 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
   if (workspace.mode !== "isolated" || !workspace.worktreePath) {
     return { ok: false, status: 422, error: `workspace ${workspace.id} has no worktree to merge` };
   }
+  // #638 — an active merge-pause is the operator's tourniquet for a merge loop on this
+  // repo. The auto-merge job already honors it (workspace-auto-merge.ts), but gate the
+  // shared dispatcher too as defense-in-depth: never let an auto-merge-originated request
+  // acquire the lease + storm while paused, regardless of which caller dispatched it. A
+  // manual/steward land (any other `requestedBy`) is the intended RECOVERY path during a
+  // pause, so it's allowed through.
+  if (opts.requestedBy === "auto-merge" && getActiveMergePause(workspace.repoRoot, workspace.baseRef ?? "main")) {
+    return { ok: false, status: 409, error: `auto-merge paused for ${workspace.repoRoot}` };
+  }
   const lease = acquireMergeLease(workspace.repoRoot, workspace.id, opts.requestedBy);
   if (!lease.ok) {
     return {

package/src/workspace-pr-completion.ts

@@ -155,6 +155,12 @@ function prRefreshForRelayMerge(workspace: WorkspaceRecord, preview: WorkspaceMe
   if (policy === "on-approval" && preview.reviewDecision !== "APPROVED") return { ok: false };
   if (preview.conflict === true) return { ok: false };
   if ((preview.behind ?? 0) <= 0) return { ok: false };
+  // #458: self-heal ONLY a PR that went red *purely because its base advanced* — its checks are
+  // failing AND the branch is behind base. A green (or still-pending) PR is never refreshed: it's
+  // left to the merge path / native auto-merge, so we don't re-trigger CI on a branch that isn't
+  // actually red. A red+up-to-date PR (behind=0, handled above) is red on its own merits, not by
+  // divergence, so it must not be refreshed into a loop either.
+  if (!statusChecksRed(preview.statusCheckRollup)) return { ok: false };
 
   const mergeable = text(preview.mergeable)?.toUpperCase();
   if (mergeable && mergeable !== "MERGEABLE") return { ok: false };
@@ -233,6 +239,26 @@ function statusChecksGreen(rollup: unknown): boolean {
   return rollup.every(statusNodeGreen);
 }
 
+// "Red" = at least one check has a definitive FAILING conclusion/state. Distinct from
+// `!statusChecksGreen` on purpose: a still-pending or no-checks-yet rollup is NOT red, so the
+// #458 base-divergence refresh never interrupts an in-flight run or a PR that hasn't reported.
+const FAILING_CONCLUSIONS = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "STALE"]);
+const FAILING_STATES = new Set(["FAILURE", "ERROR"]);
+
+function statusChecksRed(rollup: unknown): boolean {
+  if (!Array.isArray(rollup) || rollup.length === 0) return false;
+  return rollup.some(statusNodeRed);
+}
+
+function statusNodeRed(node: unknown): boolean {
+  if (!isRecord(node)) return false;
+  const conclusion = text(node.conclusion)?.toUpperCase();
+  if (conclusion) return FAILING_CONCLUSIONS.has(conclusion);
+  const state = text(node.state)?.toUpperCase();
+  if (state) return FAILING_STATES.has(state);
+  return false;
+}
+
 function prMergeable(preview: WorkspaceMergePreview): boolean {
   const mergeable = text(preview.mergeable)?.toUpperCase();
   if (mergeable !== "MERGEABLE") return false;