agent-relay-server 0.29.0 → 0.30.1

package/src/workspace-phase.ts

@@ -15,13 +15,23 @@
 // anti-panic signal.
 
 import { TERMINAL_WORKSPACE_STATUS_VALUES } from "agent-relay-sdk";
-import type { WorkspaceRecord, WorkspaceStatus } from "./types";
+import type { BranchState, WorkspaceRecord, WorkspaceStatus } from "./types";
+import { workspaceActiveClaim } from "./workspace-claim";
 
 // Statuses where the worktree's lifecycle is over — landed or torn down. Single
 // home; imported by maintenance (stale reap), routes (orphan scan), and the MCP
 // initialize primer (don't brief an agent on a dead workspace). Was duplicated.
 export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(TERMINAL_WORKSPACE_STATUS_VALUES);
 
+// The "this is the worktree the agent is actively branch-working in" predicate:
+// isolated mode and not yet landed/torn down. SINGLE HOME — the MCP owner-workspace
+// resolver, the db owner lookup, and the #236 badge enrichment all mean the same
+// thing; they drifted into private copies before. listWorkspaces is ORDER BY
+// updated_at DESC, so the first match per owner is the most recent live worktree.
+export function isLiveIsolatedWorkspace(ws: Pick<WorkspaceRecord, "mode" | "status">): boolean {
+  return ws.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(ws.status);
+}
+
 // 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
@@ -209,6 +219,64 @@ export function describeWorkspacePhase(
   }
 }
 
+function metaNumber(meta: Record<string, unknown> | undefined, key: string): number | undefined {
+  const v = meta?.[key];
+  return typeof v === "number" ? v : undefined;
+}
+
+// THE branch-state projection for the human (#236) — the sibling of
+// describeWorkspacePhase, which targets the agent. Maps a workspace to one compact
+// state for the agent-card/chat badge, so the recurring "does this agent have
+// unlanded work, and where is it in the merge-back" question is answered at a
+// glance. SINGLE HOME (server-side); the dashboard never recomputes it.
+//
+// idle/changes need the worktree's ahead/dirty counts, which the relay isn't in the
+// git path to know live — the ~2 min conflict scan stashes them in metadata
+// (`gitAhead`/`gitDirtyCount`). Until the first scan they're absent, so an active
+// worktree shows the optimistic `changes` (the high-value "mark ready" affordance);
+// the scan then settles it to `idle` when genuinely empty (#236 v1 option a).
+//
+// Returns undefined for non-branch / torn-down workspaces (no badge).
+export function deriveBranchState(
+  workspace: Pick<WorkspaceRecord, "status" | "metadata" | "readyAt"> | null | undefined,
+  opts: { now?: number; stallMs?: number } = {},
+): BranchState | undefined {
+  if (!workspace) return undefined;
+  const now = opts.now ?? Date.now();
+  switch (workspace.status) {
+    case "active": {
+      const meta = workspace.metadata as Record<string, unknown> | undefined;
+      const ahead = metaNumber(meta, "gitAhead");
+      const dirty = metaNumber(meta, "gitDirtyCount");
+      if (ahead === undefined && dirty === undefined) return "changes";
+      return (ahead ?? 0) > 0 || (dirty ?? 0) > 0 ? "changes" : "idle";
+    }
+    case "ready":
+    case "review_requested":
+      // Handed off, waiting for the auto-merge. A steward holding the claim means a
+      // human-out-of-loop reconciliation is underway → 🟠, otherwise the robot has it → 🔵.
+      return workspaceActiveClaim(workspace, now)?.purpose === "steward" ? "steward" : "ready";
+    case "merge_planned":
+      // Merge dispatched / under reconciliation — robot-or-steward, either way not the human's move.
+      return "steward";
+    case "conflict": {
+      // Held by a steward → reconciling (🟠). Past the stall window with nobody
+      // holding it → the steward path isn't progressing → escalate to the human (🔴).
+      if (workspaceActiveClaim(workspace, now)?.purpose === "steward") return "steward";
+      const stallMs = opts.stallMs ?? LAND_PENDING_STALL_MS;
+      const since = typeof workspace.readyAt === "number" ? now - workspace.readyAt : undefined;
+      if (since !== undefined && since > stallMs) return "blocked";
+      return "steward";
+    }
+    case "merged":
+    case "abandoned":
+    case "cleanup_requested":
+    case "cleaned":
+      // Terminal/torn down: the owner lookup filters these out, so the badge clears.
+      return undefined;
+  }
+}
+
 // Plain-language contract printed/returned right when an agent marks a workspace
 // ready, so the whole "what happens next" is stated up front instead of being
 // decoded from status enums over the following minutes (#235).