agent-relay-server 0.26.0 → 0.27.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "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.15"
+    "agent-relay-sdk": "0.2.16"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -11066,6 +11066,12 @@ var PAIR_STATUS_COLORS = {
 };
 //#endregion
 //#region ../sdk/src/types.ts
+/** Terminal workspace statuses shared across server + dashboard filters. */
+var TERMINAL_WORKSPACE_STATUS_VALUES = [
+	"cleaned",
+	"merged",
+	"abandoned"
+];
 /** True for a non-null, non-array object. The canonical type guard for the whole repo. */
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -11864,6 +11870,14 @@ var PROVIDER_CATALOG = {
 		label: "Claude Code",
 		defaultModel: "sonnet-4.6",
 		models: [
+			{
+				alias: "fable-5",
+				label: "Fable 5",
+				providerModel: "claude-fable-5",
+				efforts: CLAUDE_LOW_TO_XHIGH_MAX,
+				defaultEffort: "medium",
+				...codeModel({ contextWindowTokens: CONTEXT_1M })
+			},
 			{
 				alias: "opus-4.8",
 				label: "Opus 4.8",
@@ -129474,7 +129488,7 @@ var STATUS_ORDER = {
 	abandoned: 7,
 	cleaned: 8
 };
-var TERMINAL_STATUSES = new Set(["cleaned", "merged"]);
+var TERMINAL_STATUSES = new Set(TERMINAL_WORKSPACE_STATUS_VALUES);
 function shortPath(path) {
 	const parts = path.split("/").filter(Boolean);
 	if (parts.length <= 3) return path || "-";

package/src/routes.ts

@@ -167,7 +167,7 @@ import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFF
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
-import { requestWorkspaceMerge } from "./workspace-merge";
+import { isOwnerAlive, withOwnerOnline } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import {
   applyWorkspaceAction,
@@ -3813,7 +3813,7 @@ const getWorkspaces: Handler = (req) => {
     const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
     const ownerAgentId = cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 240 });
     const status = optionalEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
-    return json(listWorkspaces({ repoRoot, ownerAgentId, status }));
+    return json(listWorkspaces({ repoRoot, ownerAgentId, status }).map(withOwnerOnline));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -3823,7 +3823,7 @@ const getWorkspaces: Handler = (req) => {
 const getWorkspaceById: Handler = (_req, params) => {
   const workspace = getWorkspace(params.id!);
   if (!workspace) return error("workspace not found", 404);
-  return json(workspace);
+  return json(withOwnerOnline(workspace));
 };
 
 // Per-repo coordination state: persistent steward records (survive offline gaps)
@@ -4006,7 +4006,7 @@ const getWorkspaceDiagnostics: Handler = async (_req, params) => {
   const workspace = getWorkspace(params.id!);
   if (!workspace) return error("workspace not found", 404);
   const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
-  const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+  const ownerOnline = isOwnerAlive(workspace.ownerAgentId);
   const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
   const orchOnline = Boolean(orch) && orch!.status === "online";
   const fetched = await fetchWorkspaceGitState(workspace);
@@ -4055,7 +4055,7 @@ const postWorkspaceCleanupStale: Handler = async (req) => {
   const cleaned: string[] = [];
   for (const ws of candidates) {
     const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
-    const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+    const ownerOnline = isOwnerAlive(ws.ownerAgentId);
     if (ownerOnline) continue;                         // never clean a live owner's worktree
     if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
     if (workspaceActiveClaim(ws)) continue;            // respect steward claims
@@ -4117,7 +4117,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
         // plus the directive projection + land receipt so the CLI `--wait` and any
         // HTTP caller get the same legible answer.
         return json({
-          workspace: waited.workspace,
+          workspace: withOwnerOnline(waited.workspace),
           guidance: describeWorkspacePhase(waited.workspace),
           ...(landed ? { landed } : {}),
           fromStatus: waited.fromStatus,
@@ -4125,7 +4125,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
           timedOut: waited.timedOut,
         });
       }
-      return json(workspace);
+      return json(withOwnerOnline(workspace));
     }
 
     // Everything else delegates to the shared core (one home, shared with the
@@ -4138,6 +4138,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
       metadata: cleanMeta(parsed.body.metadata) ?? {},
       strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
       deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
+      force: parsed.body.force === true,
       prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
       prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
       purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
@@ -4146,7 +4147,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
     });
     if (!result.ok) return error(result.error, result.httpStatus);
     if (result.command) emitCommand(result.command);
-    const payload: Record<string, unknown> = { workspace: result.workspace };
+    const payload: Record<string, unknown> = { workspace: withOwnerOnline(result.workspace) };
     if (result.command) payload.command = result.command;
     if (result.claim !== undefined) payload.claim = result.claim;
     return json(payload, result.httpStatus);

package/src/workspace-actions.ts

@@ -19,8 +19,9 @@ import {
   updateWorkspaceStatus,
 } from "./db";
 import { emitActivityEvent } from "./sse";
-import { requestWorkspaceMerge } from "./workspace-merge";
+import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -50,6 +51,8 @@ export interface ApplyWorkspaceActionInput {
   deleteBranch?: boolean;
   prTitle?: string;
   prBody?: string;
+  // cleanup
+  force?: boolean;
   // claim / release-claim
   purpose?: string;
   // deps-refresh
@@ -203,6 +206,20 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   const nextStatus = STATUS_BY_ACTION[action];
   if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
 
+  if (
+    action === "cleanup" &&
+    input.force !== true &&
+    workspace.mode === "isolated" &&
+    !TERMINAL_WORKSPACE_STATUSES.has(workspace.status) &&
+    isOwnerAlive(workspace.ownerAgentId)
+  ) {
+    return {
+      ok: false,
+      httpStatus: 409,
+      error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
+    };
+  }
+
   const updated = updateWorkspaceStatus(workspace.id, nextStatus, {
     ...metadata,
     ...(detail ? { detail } : {}),
@@ -215,7 +232,7 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   let command: Command | undefined;
   if (requiresCommand) {
     // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
     if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
     command = built.command;
   }
@@ -237,7 +254,20 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
 export function buildWorkspaceCleanupCommand(
   workspace: WorkspaceRecord,
   requestedBy: string,
+  opts: { force?: boolean } = {},
 ): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  if (
+    opts.force !== true &&
+    workspace.mode === "isolated" &&
+    !TERMINAL_WORKSPACE_STATUSES.has(workspace.status) &&
+    isOwnerAlive(workspace.ownerAgentId)
+  ) {
+    return {
+      ok: false,
+      status: 409,
+      error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
+    };
+  }
   const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
   const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
   if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };

package/src/workspace-merge.ts

@@ -32,12 +32,16 @@ export type RequestWorkspaceMergeResult =
 
 // The owner is "alive" while its relay agent exists and isn't offline (online or
 // a borderline-stale disconnect both count — don't nuke a worktree on a blip).
-function isOwnerAlive(ownerAgentId: string | undefined): boolean {
+export function isOwnerAlive(ownerAgentId: string | undefined): boolean {
   if (!ownerAgentId) return false;
   const agent = getAgent(ownerAgentId);
   return Boolean(agent) && agent!.status !== "offline";
 }
 
+export function withOwnerOnline<T extends { ownerAgentId?: string }>(workspace: T): T & { ownerOnline: boolean } {
+  return { ...workspace, ownerOnline: isOwnerAlive(workspace.ownerAgentId) };
+}
+
 /**
  * Dispatch a base merge for an isolated workspace, serialized by the per-repo
  * merge lease (issue #157). Single source of truth shared by the manual

package/src/workspace-orphans.ts

@@ -12,13 +12,14 @@
 // prune` (a no-op while the directory exists) never was.
 
 import { resolve } from "node:path";
-import { RELAY_TOKEN_HEADER, errMessage } from "agent-relay-sdk";
-import type { WorkspaceMergePreview, WorkspaceOrphan, WorkspaceProbe, WorkspaceRecord } from "./types";
-import { createActivityEvent, listOrchestrators, listWorkspaces } from "./db";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import type { WorkspaceMergePreview, WorkspaceOrphan, WorkspaceProbe, WorkspaceRecord, WorkspaceStatus } from "./types";
+import { createActivityEvent, getWorkspace, listOrchestrators, listWorkspaces, updateWorkspaceStatus } from "./db";
 import { createCommand } from "./commands-db";
 import { emitRelayEvent } from "./events";
 import { isPathWithinBase } from "./utils";
 import { TERMINAL_WORKSPACE_STATUSES, worktreeReapable, type WorktreeReapState } from "./workspace-phase";
+import { isOwnerAlive } from "./workspace-merge";
 
 // 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
@@ -28,6 +29,7 @@ const UNLANDED_FLAG_COOLDOWN_MS = Number(process.env.AGENT_RELAY_ORPHAN_FLAG_COO
 // remove them (parity with the session reaper's detect-only switch).
 const orphanWorktreeReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
 const flaggedAt = new Map<string, number>();
+const IN_FLIGHT_MISSING_WORKTREE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "cleanup_requested"]);
 
 export function resetOrphanWorktreeStateForTests(): void {
   flaggedAt.clear();
@@ -77,6 +79,39 @@ async function fetchWorktreeReapState(apiUrl: string, worktreePath: string, base
   }
 }
 
+type MissingBranchProbe = { kind: "gone" } | { kind: "preview"; preview: WorkspaceMergePreview } | { kind: "unavailable" };
+
+async function fetchBranchReapState(
+  apiUrl: string,
+  repoRoot: string,
+  branch: string | undefined,
+  baseRef?: string,
+  baseSha?: string,
+): Promise<MissingBranchProbe> {
+  if (!branch) return { kind: "unavailable" };
+  const query = new URLSearchParams({ repoRoot, branch, checkPr: "1" });
+  if (baseRef) query.set("baseRef", baseRef);
+  if (baseSha) query.set("baseSha", baseSha);
+  try {
+    const res = await fetch(`${apiUrl}/api/workspace/branch-merge-preview?${query.toString()}`, {
+      headers: relayHeaders(),
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (res.status === 404) return { kind: "gone" };
+    if (!res.ok) return { kind: "unavailable" };
+    return { kind: "preview", preview: await res.json() as WorkspaceMergePreview };
+  } catch {
+    return { kind: "unavailable" };
+  }
+}
+
+function previewReapable(preview: WorkspaceMergePreview): boolean | undefined {
+  if (preview.error) return undefined;
+  const hasSignal = preview.landed === true || typeof preview.ahead === "number" || typeof preview.unmergedAhead === "number";
+  if (!hasSignal) return undefined;
+  return worktreeReapable({ landed: preview.landed, ahead: preview.ahead, unmergedAhead: preview.unmergedAhead, dirtyCount: 0 });
+}
+
 function onlineOrchestrators(): OnlineOrchestrator[] {
   return listOrchestrators()
     .filter((orch) => orch.status === "online" && orch.apiUrl && orch.agentId)
@@ -93,7 +128,16 @@ function knownRepoRoots(workspaces: WorkspaceRecord[]): string[] {
 export interface CollectOrphansResult {
   orphans: WorkspaceOrphan[];
   /** Live isolated rows whose worktree is missing on disk (DB→disk drift). */
-  missingWorktrees: Array<{ workspaceId: string; worktreePath: string; repoRoot: string; status: string }>;
+  missingWorktrees: Array<{
+    workspaceId: string;
+    worktreePath: string;
+    repoRoot: string;
+    status: WorkspaceStatus;
+    branch?: string;
+    baseRef?: string;
+    baseSha?: string;
+    ownerAgentId?: string;
+  }>;
   reason?: string;
 }
 
@@ -128,7 +172,16 @@ export async function collectWorkspaceOrphans(): Promise<CollectOrphansResult> {
     // DB→disk drift: a live isolated row whose worktree is no longer on disk.
     for (const [path, ws] of liveRowsByPath) {
       if (ws.mode === "isolated" && !onDisk.has(path)) {
-        missingWorktrees.push({ workspaceId: ws.id, worktreePath: ws.worktreePath, repoRoot, status: ws.status });
+        missingWorktrees.push({
+          workspaceId: ws.id,
+          worktreePath: ws.worktreePath,
+          repoRoot,
+          status: ws.status,
+          branch: ws.branch,
+          baseRef: ws.baseRef,
+          baseSha: ws.baseSha,
+          ownerAgentId: ws.ownerAgentId,
+        });
       }
     }
 
@@ -208,6 +261,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
   const reapEnabled = orphanWorktreeReapEnabled();
   const reaped: string[] = [];
   const flagged: string[] = [];
+  const autoAbandoned: string[] = [];
+  const flaggedMissingWorktrees: string[] = [];
   const now = Date.now();
 
   for (const orphan of orphans) {
@@ -255,22 +310,103 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
     });
   }
 
-  // DB→disk drift is observability-only: a live row whose worktree vanished is
-  // surfaced, not auto-deleted (the row may still be mid-land or recoverable).
   for (const missing of missingWorktrees) {
-    const key = `missing:${missing.worktreePath}`;
+    const workspace = getWorkspace(missing.workspaceId);
+    if (!workspace || TERMINAL_WORKSPACE_STATUSES.has(workspace.status) || workspace.mode !== "isolated" || !workspace.worktreePath) continue;
+    const key = `missing:${workspace.worktreePath}`;
+    const ownerAlive = isOwnerAlive(workspace.ownerAgentId);
+    const inFlight = IN_FLIGHT_MISSING_WORKTREE_STATUSES.has(workspace.status);
     const last = flaggedAt.get(key) ?? 0;
+    if (ownerAlive || inFlight) {
+      if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
+      flaggedAt.set(key, now);
+      createActivityEvent({
+        clientId: `workspace-row-no-worktree-${workspace.id}-${now}`,
+        kind: "state",
+        title: "Workspace row has no worktree on disk",
+        body: `Workspace ${workspace.id} (${workspace.status}) points at ${workspace.worktreePath}, which no longer exists on disk — disk/DB drift.`,
+        meta: workspace.id,
+        icon: "ti-unlink",
+        view: "orchestrators",
+        metadata: {
+          source: "server",
+          maintenanceJobId: "workspace-orphan-reaper",
+          workspaceId: workspace.id,
+          worktreePath: workspace.worktreePath,
+          status: workspace.status,
+          ownerAlive,
+          inFlight,
+        },
+      });
+      continue;
+    }
+
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(workspace.repoRoot, candidate.baseDir));
+    const probe = orch?.apiUrl
+      ? await fetchBranchReapState(orch.apiUrl, workspace.repoRoot, workspace.branch, workspace.baseRef, workspace.baseSha)
+      : { kind: "unavailable" } as const;
+    const safeToAbandon = probe.kind === "gone"
+      ? true
+      : probe.kind === "preview"
+        ? previewReapable(probe.preview)
+        : undefined;
+
+    if (safeToAbandon === true) {
+      const reasonText = probe.kind === "gone" ? "missing worktree; branch ref gone" : "missing worktree; branch already landed";
+      const updated = updateWorkspaceStatus(workspace.id, "abandoned", {
+        autoAbandoned: true,
+        abandonedReason: reasonText,
+        abandonedAt: now,
+      });
+      if (!updated) continue;
+      autoAbandoned.push(workspace.id);
+      flaggedAt.delete(key);
+      createActivityEvent({
+        clientId: `workspace-row-auto-abandoned-${workspace.id}-${now}`,
+        kind: "state",
+        title: "Workspace auto-abandoned",
+        body: `${workspace.branch ?? workspace.id} in ${workspace.repoRoot} — worktree missing and ${probe.kind === "gone" ? "branch ref is gone" : "branch has fully landed"}`,
+        meta: workspace.branch ?? workspace.id,
+        icon: "ti-clock-x",
+        view: "orchestrators",
+        metadata: {
+          source: "server",
+          maintenanceJobId: "workspace-orphan-reaper",
+          workspaceId: workspace.id,
+          worktreePath: workspace.worktreePath,
+          branch: workspace.branch,
+          reason: reasonText,
+        },
+      });
+      continue;
+    }
+
     if (now - last < UNLANDED_FLAG_COOLDOWN_MS) continue;
     flaggedAt.set(key, now);
+    flaggedMissingWorktrees.push(workspace.id);
+    const detail = probe.kind === "preview"
+      ? `${probe.preview.unmergedAhead ?? probe.preview.ahead ?? "?"} un-landed commit(s) still recoverable on branch ${workspace.branch ?? workspace.id}`
+      : workspace.branch
+        ? `host could not confirm whether branch ${workspace.branch} has landed`
+        : "host could not confirm whether recoverable branch work remains";
     createActivityEvent({
-      clientId: `workspace-row-no-worktree-${missing.workspaceId}-${now}`,
+      clientId: `workspace-row-needs-attention-${workspace.id}-${now}`,
       kind: "state",
-      title: "Workspace row has no worktree on disk",
-      body: `Workspace ${missing.workspaceId} (${missing.status}) points at ${missing.worktreePath}, which no longer exists on disk — disk/DB drift.`,
-      meta: missing.workspaceId,
-      icon: "ti-unlink",
+      title: "Missing-worktree workspace needs attention",
+      body: `${workspace.id} in ${workspace.repoRoot} has no worktree on disk and cannot be auto-abandoned safely — ${detail}. Recover via the branch if needed, then abandon or clean it up explicitly.`,
+      meta: workspace.id,
+      icon: "ti-alert-triangle",
       view: "orchestrators",
-      metadata: { source: "server", maintenanceJobId: "workspace-orphan-reaper", workspaceId: missing.workspaceId, worktreePath: missing.worktreePath, status: missing.status },
+      metadata: {
+        source: "server",
+        maintenanceJobId: "workspace-orphan-reaper",
+        workspaceId: workspace.id,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        status: workspace.status,
+        probe: probe.kind,
+        ...(probe.kind === "preview" ? { ahead: probe.preview.ahead, unmergedAhead: probe.preview.unmergedAhead, landed: probe.preview.landed } : {}),
+      },
     });
   }
 
@@ -283,6 +419,8 @@ export async function reapOrphanedWorktrees(): Promise<Record<string, unknown>>
     scanned: orphans.length,
     reaped,
     flagged,
+    autoAbandoned,
+    flaggedMissingWorktrees,
     missingWorktrees: missingWorktrees.map((m) => m.workspaceId),
     reapEnabled,
   };

package/src/workspace-phase.ts

@@ -14,12 +14,13 @@
 // "handed off, healthy, wait" guidance, and `actionNeeded:false` is the explicit
 // anti-panic signal.
 
+import { TERMINAL_WORKSPACE_STATUS_VALUES } from "agent-relay-sdk";
 import type { WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // 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>(["cleaned", "merged", "abandoned"]);
+export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(TERMINAL_WORKSPACE_STATUS_VALUES);
 
 // 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: