agent-relay-server 0.23.0 → 0.25.0

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");
 }