agent-relay-server 0.84.0 → 0.86.0

package/src/maintenance/workspaces.ts

@@ -13,7 +13,8 @@ import {
   updateWorkspaceStatus,
 } from "../db";
 import type { WorkspaceMergePreview, WorkspaceStatus } from "../types";
-import { reconcileLandedWorkspace } from "../branch-landed";
+import { notifyStewardHandoff, reconcileLandedWorkspace } from "../branch-landed";
+import { resolveStewardIdentity } from "../steward-identity";
 import { getStewardConfig } from "../config-store";
 import { preparePrCompletionScan, reconcileLandedPr } from "../workspace-pr-completion";
 import { applyBranchFreshness, fetchHostMergePreview, workspacePathWithinBase } from "../workspace-probe";
@@ -97,15 +98,22 @@ export async function scanWorkspaceConflicts(): Promise<Record<string, unknown>>
         if (woke) notifiedStewards.push(woke);
       } else if (ws.stewardAgentId) {
         try {
+          // #640 — carry the identity triangle (branch agent + its coordinator) so the
+          // elected steward can address them; #641/#642 notify owner + coordinator of the handoff.
+          const { ownerAgentId, coordinatorAgentId } = resolveStewardIdentity(ws);
+          const coordinatorLine = coordinatorAgentId
+            ? ` Escalate to the branch agent's coordinator \`${coordinatorAgentId}\` (not the system fallback) if you can't resolve it.`
+            : "";
           notifyTarget(
             "workspace.conflict",
-            { workspaceId: ws.id, repoRoot: ws.repoRoot },
+            { workspaceId: ws.id, repoRoot: ws.repoRoot, author: ownerAgentId, parent: coordinatorAgentId ?? undefined },
             ws.stewardAgentId,
             "Workspace merge conflict",
-            `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
-            { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
+            `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind).${ownerAgentId ? ` Branch agent (owner): \`${ownerAgentId}\`.` : ""} As repo steward, please coordinate resolution.${coordinatorLine}`,
+            { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind, ownerAgentId, coordinatorAgentId },
           );
           notifiedStewards.push(ws.stewardAgentId);
+          notifyStewardHandoff({ workspace: ws, stewardId: ws.stewardAgentId, coordinatorAgentId, reason: "conflict" });
         } catch {}
       }
     } else if (p.conflict === false && ws.status === "conflict" && meta.autoConflict === true) {
@@ -168,13 +176,18 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
 
     if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
     if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
+    // #642 — escalate to the branch agent's coordinator (owner's `spawnedBy`), falling back to
+    // the configured `stewardFallbackTarget` only when no coordinator resolves. The bare
+    // fallback was an unset `system` dead-end in the live incident.
+    const { coordinatorAgentId } = resolveStewardIdentity(fresh);
+    const escalationTarget = coordinatorAgentId ?? fallbackTarget;
     const sent = notifyTarget(
       "workspace.stranded_escalation",
-      { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
-      fallbackTarget,
+      { workspaceId: fresh.id, repoRoot: fresh.repoRoot, author: fresh.ownerAgentId, parent: coordinatorAgentId ?? undefined },
+      escalationTarget,
       "Stranded workspace needs an owner",
-      `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
-      { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt },
+      `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h.${coordinatorAgentId ? ` You are the branch agent \`${fresh.ownerAgentId ?? "?"}\`'s coordinator.` : ""} Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
+      { kind: "workspace.stranded-escalation", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch, status: fresh.status, strandedAt, coordinatorAgentId },
     );
     if (sent) escalationTargets.push(sent);
     patchWorkspaceMetadata(fresh.id, { escalatedAt: now });
@@ -183,11 +196,11 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
       clientId: `workspace-gc-escalate-${fresh.id}-${now}`,
       kind: "state",
       title: "Workspace escalated",
-      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated${fallbackTarget ? ` to ${fallbackTarget}` : " (no fallback configured)"}`,
+      body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - stranded ${fresh.status} escalated${escalationTarget ? ` to ${escalationTarget}${coordinatorAgentId ? " (coordinator)" : ""}` : " (no coordinator or fallback configured)"}`,
       meta: fresh.branch ?? fresh.id,
       icon: "ti-alert-octagon",
       view: "orchestrators",
-      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, fallback: fallbackTarget || null },
+      metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id, escalationTarget: escalationTarget || null, coordinatorAgentId: coordinatorAgentId ?? null },
     });
   }
 

package/src/mcp/index.ts

@@ -16,8 +16,8 @@ import { errMessage, isRecord } from "agent-relay-sdk";
 import type { JsonRpcId, JsonRpcRequest, McpAuthContext, ToolDefinition } from "./types";
 import { positiveIdOrUndefined, recordField, stringField } from "./validation";
 import { IDENTITY_TOOLS, hasAnyScope, mcpAuthContext, relayCompactAndResume, relayRecall, relayWhoami } from "./identity";
-import { MESSAGING_TOOLS, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
-import { SPAWN_TOOLS, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
+import { MESSAGING_TOOLS, relayAgentCrashReport, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
+import { SPAWN_TOOLS, relayMyAgents, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
 import { WORKSPACE_TOOLS, callerIsolatedWorkspace, relayWorkspaceList, relayWorkspaceMutation, relayWorkspaceStatus } from "./tools-workspace";
 
 const MCP_PROTOCOL_VERSION = "2024-11-05";
@@ -122,12 +122,14 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
     else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
+    else if (name === "relay_agent_crash_report") result = relayAgentCrashReport(auth, args);
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
     else if (name === "relay_compact_and_resume") result = relayCompactAndResume(auth, args);
     else if (name === "relay_recall") result = relayRecall(auth, args);
     else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
+    else if (name === "relay_my_agents") result = relayMyAgents(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
     else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);

package/src/mcp/tools-messaging.ts

@@ -8,7 +8,9 @@ import {
   createArtifact,
   getAgent,
   getArtifact,
+  getCrashReport,
   getMessage,
+  listCrashReports,
   getOrchestrator,
   getTask,
   getThread,
@@ -190,6 +192,19 @@ export const MESSAGING_TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_agent_crash_report",
+    description: "Retrieve the post-mortem for a dead agent (#636): a likely-cause label (oom · killed · clean-exit · token-401 · onboarding-gate · provider-crash · transport-loss · unknown) + log tail + heartbeat/active-work context. Pass agentId for one report (yourself or a child you spawned); omit it to list your own spawned children's reports. The report survives the reaper, so it answers 'why did my worker die?' after it's gone.",
+    requiredScopes: ["agents:read", "agent:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string", description: "The dead agent's id. Must be yourself or one of your spawned children. Omit to list your own children's crash reports." },
+        limit: { type: "integer", minimum: 1, maximum: 200, description: "Max reports when listing (default 50)." },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 function runMcpSend(auth: McpAuthContext, input: SendMessageInput): Message & { delivery: DeliveryReceipt } {
@@ -450,6 +465,29 @@ export function relayFindAgents(auth: McpAuthContext, args: Record<string, unkno
   return { agents: safe, total, count: safe.length, truncated: true, nextOffset: offset + safe.length };
 }
 
+// #636 — self/parent-scoped crash post-mortem retrieval. A caller may read its OWN report or any of
+// its spawned children's; never an unrelated agent's. Survives the reaper (separate crash_reports table).
+export function relayAgentCrashReport(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const caller = callerAgentId(auth);
+  const agentId = optionalString(args.agentId, "agentId", 240);
+  if (agentId) {
+    // Authorize FIRST, regardless of whether a report exists — the self/parent contract must hold
+    // even for an agentId with no report (else any agent:read caller leaks `{report:null}`). Prefer
+    // the live agent row's lineage; fall back to the report's recorded parent once the agent is reaped.
+    const agent = getAgent(agentId);
+    const report = getCrashReport(agentId);
+    const parent = agent?.spawnedBy ?? report?.parentId;
+    const authorized = !!caller && (caller === agentId || (parent !== undefined && caller === parent));
+    if (!authorized) throw new McpAuthError("crash report is scoped to the agent itself or its spawn-parent");
+    return { agentId, report: report ?? null };
+  }
+  // No agentId: list the caller's own spawned children's reports.
+  if (!caller) throw new McpAuthError("relay_agent_crash_report requires a resolvable caller agent to list reports");
+  const limit = optionalPositiveInt(args.limit, "limit");
+  const reports = listCrashReports({ parentId: caller, ...(limit ? { limit } : {}) });
+  return { reports, count: reports.length };
+}
+
 function payloadWithAttachments(
   payload: Record<string, unknown> | undefined,
   attachments: AttachmentRef[] | undefined,

package/src/mcp/tools-spawn.ts

@@ -4,15 +4,16 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../servic
 import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
-import { ValidationError } from "../db";
+import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } from "../db";
+import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
 import { optionalEnum } from "../validation";
-import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { APPROVAL_MODES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import type { AgentLifecycle, SpawnApprovalMode, SpawnProvider, WorkspaceMode } from "../types";
+import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceMode, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
 import { callerAgentId } from "./identity";
-import { enumField, optionalNonNegativeInt, optionalPositiveInt, optionalString, optionalStringArray } from "./validation";
+import { enumField, optionalBoolean, optionalNonNegativeInt, optionalPositiveInt, optionalString, optionalStringArray } from "./validation";
 
 export const SPAWN_TOOLS: ToolDefinition[] = [
   {
@@ -57,6 +58,19 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_my_agents",
+    description: "List the spawned children owned by YOUR token lineage, with lean lifecycle rows and spawn quota at a glance. This is the canonical spawn-tracking tool: use it after relay_spawn_agent to see your own children and choose a spawnRequestId for relay_shutdown_agent. Self-scoped: no agentId/spawnedBy parameter is accepted.",
+    requiredScopes: ["command:spawn"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeReaped: { type: "boolean", description: "Include recent exited/offline child rows in addition to live/pending children. Default false." },
+        limit: { type: "integer", minimum: 1, maximum: 50, description: "Maximum rows to return when includeReaped is true. Default 20, capped at 50." },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_shutdown_agent",
     description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children, addressed by agentId or spawnRequestId (policyName/tmuxSession are admin-only broad targets). Admin tokens keep full reach.",
@@ -112,6 +126,53 @@ export function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown>
   });
 }
 
+type MyAgentRow = {
+  label: string | null;
+  spawnRequestId: string | null;
+  agentId: string | null;
+  status: string;
+  provider: string | null;
+  model: string | null;
+  machine: string | null;
+  branch: string | null;
+  landState: string | null;
+  lastSeen: number;
+};
+
+export function relayMyAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const callerId = callerAgentId(auth);
+  if (!callerId) throw new McpAuthError("relay_my_agents requires a single caller agent identity");
+  const includeReaped = optionalBoolean(args.includeReaped, "includeReaped") === true;
+  const limit = Math.min(optionalPositiveInt(args.limit, "limit") ?? 20, 50);
+  const quotaMax = auth.component?.constraints?.maxSpawnedAgents ?? 0;
+  const liveChildren = countLiveSpawnedAgents(callerId);
+  const registered = listAgents()
+    .filter((agent) => agent.spawnedBy === callerId)
+    .filter((agent) => includeReaped || isLiveChild(agent))
+    .map(agentChildRow);
+  const registeredSpawnRequestIds = new Set(registered.map((row) => row.spawnRequestId).filter((value): value is string => Boolean(value)));
+  const pending = activeSpawnCommandsFor(callerId)
+    .filter((command) => {
+      const spawnRequestId = stringValue(command.params.spawnRequestId) ?? command.correlationId;
+      return Boolean(spawnRequestId && !registeredSpawnRequestIds.has(spawnRequestId));
+    })
+    .map(commandChildRow);
+  const agents = [...pending, ...registered]
+    .sort((a, b) => b.lastSeen - a.lastSeen)
+    .slice(0, includeReaped ? limit : undefined);
+
+  return {
+    quota: {
+      liveChildren,
+      max: quotaMax,
+      remaining: Math.max(0, quotaMax - liveChildren),
+    },
+    agents,
+    count: agents.length,
+    includeReaped,
+  };
+}
+
 export function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const agentId = optionalString(args.agentId, "agentId", 240);
   const policyName = optionalString(args.policyName, "policyName", 120);
@@ -144,3 +205,57 @@ export function relayShutdownAgent(auth: McpAuthContext, args: Record<string, un
     throw e;
   }
 }
+
+function isLiveChild(agent: AgentCard): boolean {
+  return agent.ready && agent.status !== "offline" && agent.status !== "stale";
+}
+
+function agentChildRow(agent: AgentCard): MyAgentRow {
+  const workspace = latestWorkspaceFor(agent.id);
+  return {
+    label: agent.label ?? agent.name ?? null,
+    spawnRequestId: stringValue(agent.meta?.spawnRequestId) ?? null,
+    agentId: agent.id,
+    status: childLifecycleStatus(agent),
+    provider: agent.providerCapabilities?.model?.provider ?? stringValue(agent.meta?.provider) ?? null,
+    model: agent.providerCapabilities?.model?.id ?? stringValue(agent.meta?.model) ?? stringValue(agent.meta?.providerModel) ?? null,
+    machine: agent.machine ?? null,
+    branch: workspace?.branch ?? null,
+    landState: workspace?.status ?? null,
+    lastSeen: agent.lastSeen,
+  };
+}
+
+function commandChildRow(command: Command): MyAgentRow {
+  return {
+    label: stringValue(command.params.label) ?? null,
+    spawnRequestId: stringValue(command.params.spawnRequestId) ?? command.correlationId ?? null,
+    agentId: null,
+    status: "spawning",
+    provider: stringValue(command.params.provider) ?? null,
+    model: stringValue(command.params.model) ?? stringValue(command.params.providerModel) ?? null,
+    machine: stringValue(command.params.orchestratorId) ?? null,
+    branch: null,
+    landState: null,
+    lastSeen: command.updatedAt,
+  };
+}
+
+function childLifecycleStatus(agent: AgentCard): string {
+  const action = stringValue(agent.meta?.lifecycleAction);
+  if (action) return action;
+  if (agent.status === "offline" || agent.status === "stale") return "exited";
+  if (!agent.ready) return "starting";
+  if (agent.status === "online") return "ready";
+  return agent.status;
+}
+
+function activeSpawnCommandsFor(callerId: string): Command[] {
+  return listCommands({ type: "agent.spawn", limit: 500 })
+    .filter((command) => ["pending", "accepted", "running"].includes(command.status))
+    .filter((command) => stringValue(command.params.spawnedBy) === callerId);
+}
+
+function latestWorkspaceFor(agentId: string): WorkspaceRecord | undefined {
+  return listWorkspaces({ ownerAgentId: agentId })[0];
+}

package/src/notification-types.ts

@@ -11,8 +11,10 @@ export type NotificationType =
   | "agent.transient_land_hold"
   | "agent.rate_limit_resume"
   | "team.idle"
+  | "team.member_silent"
   | "plan.bound_agent_exited"
   | "workspace.steward_task"
+  | "workspace.steward_handoff"
   | "workspace.conflict"
   | "workspace.steward_reassigned"
   | "workspace.stranded_escalation"
@@ -62,8 +64,10 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.transient_land_hold": null,
   "agent.rate_limit_resume": 15 * MINUTES,
   "team.idle": null,
+  "team.member_silent": null,
   "plan.bound_agent_exited": null,
   "workspace.steward_task": null,
+  "workspace.steward_handoff": null,
   "workspace.conflict": null,
   "workspace.steward_reassigned": null,
   "workspace.stranded_escalation": null,

package/src/provider-catalog-store.ts

@@ -150,6 +150,9 @@ function normalizeOverrideInput(input: ProviderModelOverrideInput): ProviderMode
   if (contextThreshold) entry.contextThreshold = contextThreshold;
   else delete entry.contextThreshold;
   delete entry.disabled;
+  // #368 — unavailable is a static catalog fact (provider-side suspension), not an operator toggle;
+  // strip it from DB overrides so an admin can't accidentally clear a catalog-level suspension.
+  delete entry.unavailable;
   return {
     ...input,
     alias,

package/src/routes/agents.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Domain: agents.
 import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent, canViewAgentRoute, error, json, memoryContext, memoryErrorResponse, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, visibleAgentIdsForRequest, type Handler } from "./_shared";
-import { ValidationError, deleteAgent, getAgent, getAgentTimeline, heartbeat, listAgentChatHistory, listAgents, listArtifactsForEntity, listContextSnapshots, listPendingReplyObligations, listQuotaSnapshots, markReady, searchAgents, setLabel, setStatus, setTags, validateAgentSession } from "../db";
+import { ValidationError, deleteAgent, getAgent, getAgentTimeline, getCrashReport, heartbeat, listAgentChatHistory, listAgents, listArtifactsForEntity, listContextSnapshots, listPendingReplyObligations, listQuotaSnapshots, markReady, searchAgents, setLabel, setStatus, setTags, validateAgentSession } from "../db";
 import { attachBranchState, attachBranchStates } from "../agent-branch-state";
 import { attachIssueRepo, attachIssueRepos } from "../agent-issue-repo";
 import { cleanStringArray } from "../validation";
@@ -68,6 +68,16 @@ export const getAgentById: Handler = (req, params) => {
   return json(attachIssueRepo(attachBranchState(agent)));
 };
 
+// #636 — "why did it die" data source. The crash report outlives the agent row (separate table),
+// so this resolves even after the reaper removed the agent. Existence-hiding still applies WHILE the
+// agent exists; once reaped, an authenticated operator can read the post-mortem.
+export const getAgentCrashReportRoute: Handler = (req, params) => {
+  const id = params.id!;
+  const agent = getAgent(id);
+  if (agent && !canViewAgentRoute(req, agent.id)) return error("agent not found", 404);
+  return json({ agentId: id, report: getCrashReport(id) });
+};
+
 export const getAgentReplyObligations: Handler = (_req, params) => {
   const agent = getAgent(params.id!);
   return agent ? json(listPendingReplyObligations(agent.id)) : error("agent not found", 404);

package/src/routes/commands.ts

@@ -16,7 +16,7 @@ import { notifyBranchLandFailed, notifyBranchLanded } from "../branch-landed";
 import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
-import { scheduleRepoMerge } from "../workspace-auto-merge";
+import { CLEAR_MERGE_NO_PROGRESS, noteMergeNoProgress, scheduleRepoMerge } from "../workspace-auto-merge";
 import { enqueueContinuationInjectionAfterSelfResume } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 
@@ -220,6 +220,11 @@ export const patchCommand: Handler = async (req, params) => {
             mergeResult: command.result,
             mergeCommandId: command.id,
             mergedAt: Date.now(),
+            // A merge that settles `succeeded` made genuine progress (land / recycle /
+            // noop-resolve / PR-opened) — clear any prior no-progress back-off so the lane
+            // is attempted normally next time (#638).
+            ...CLEAR_MERGE_NO_PROGRESS,
+            mergeError: undefined,
             ...(normalizedStatus !== resultStatus ? { mergeStatusNormalizedFrom: resultStatus } : {}),
             // The land consumes the steward's claim (#208 steward contract / vent
             // #62): a successful land must release it, or `steward inspect` keeps
@@ -259,12 +264,25 @@ export const patchCommand: Handler = async (req, params) => {
           }
         }
       } else if (command.status === "failed" && command.correlationId) {
-        // Merge couldn't complete — don't leave it stuck in merge_planned.
+        // Merge couldn't complete — don't leave it stuck in merge_planned. A no-progress
+        // merge now settles `failed` (orchestrator #638) carrying the result; honor the
+        // orchestrator's intended target status when it gave a valid one so a real
+        // `conflict` routes to the steward (a non-landable status the auto-merge job
+        // skips, which itself stops the loop) rather than bouncing back to the landable
+        // `review_requested`. Surface the error and count the no-progress attempt so the
+        // auto-merge job backs off after N instead of busy-looping (#638).
         const current = getWorkspace(command.correlationId);
         if (current && current.status === "merge_planned") {
-          updateWorkspaceStatus(command.correlationId, "review_requested", {
+          const failedResultStatus = isRecord(command.result)
+            ? optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined
+            : undefined;
+          const nextStatus: WorkspaceStatus = failedResultStatus && failedResultStatus !== "merge_planned"
+            ? failedResultStatus
+            : "review_requested";
+          updateWorkspaceStatus(command.correlationId, nextStatus, {
             mergeCommandId: command.id,
             mergeError: command.error ?? "merge failed",
+            ...noteMergeNoProgress(current.metadata),
           });
           notifyBranchLandFailed({
             workspace: current,

package/src/routes/index.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Router: route table + matchRoute dispatch.
-import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
+import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentCrashReportRoute, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
 import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, putAgentProfileRoute } from "./agent-profiles";
 import { deleteAgentTerminalSession, getAgentDrive, getAgentPresence, postAgentAction, postAgentDrive, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
 import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, headUserAvatar, patchMe, patchUserById, postMyAvatar, postUserAvatarById } from "./users";
@@ -121,6 +121,7 @@ const routes: Route[] = [
   route("GET", "/api/agents/:id/timeline", getAgentTimelineRoute),
   route("GET", "/api/agents/:id/active-memories", getAgentActiveMemories),
   route("GET", "/api/agents/:id/reply-obligations", getAgentReplyObligations),
+  route("GET", "/api/agents/:id/crash-report", getAgentCrashReportRoute),
   route("DELETE", "/api/agents/:id/active-memories", deleteAgentActiveMemories),
   route("GET", "/api/agents/:id", getAgentById),
   route("PATCH", "/api/agents/:id/status", patchAgentStatus),

package/src/routes/orchestrator.ts

@@ -2,6 +2,7 @@
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, parseRuntimePackage, type RuntimeCapabilities, type RuntimeContracts, type RuntimePackageMetadata } from "../contracts";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
+import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { VERSION } from "../config";
 import { ValidationError, deleteOrchestrator, getOrchestrator, listOrchestrators, orchestratorHeartbeat, recordAgentExitDiagnostics, setOrchestratorUpgradeState, updateManagedAgents, upsertOrchestrator } from "../db";
 import { auditEvent, authAuditMetadata, authorizeRoute, cleanJsonArray, cleanSafeNumber, dashboardAttribution, emitCommand, error, isRootCredentialRequest, json, parseBody, spawnRequestId, type Handler } from "./_shared";
@@ -209,7 +210,10 @@ export const patchOrchestratorAgents: Handler = async (req, params) => {
         // (its WHERE excludes status='offline'), guaranteeing a single notifyAgentOffline emission.
         // notifyAgentOffline no-ops for non-spawned agents. Only fire when we actually recorded the
         // exit (agent !== null) so an already-offline row can't double-notify.
-        notifyAgentOffline(exited.agentId, exitReason(exited));
+        // #636 — classify the death from the captured exit diagnostics + agent state and ride the
+        // verdict on the terminal event (also persisted as a crash report inside notifyAgentOffline).
+        const diagnosis = diagnoseAgentDeath({ agent, reason: exitReason(exited), exit: exited });
+        notifyAgentOffline(exited.agentId, exitReason(exited), diagnosis);
       }
       auditEvent({
         clientId: [
@@ -324,6 +328,15 @@ function cleanManagedSessionExitDiagnostics(value: unknown, index: number): Mana
     runnerInfoFile: cleanString(value.runnerInfoFile, `exitedAgents[${index}].runnerInfoFile`, { max: 500 }),
     runnerInfoPresent: typeof value.runnerInfoPresent === "boolean" ? value.runnerInfoPresent : undefined,
     systemd,
+    // #636 — termination signal / exit code / OOM probe captured by the orchestrator.
+    signal: cleanString(value.signal, `exitedAgents[${index}].signal`, { max: 40 }),
+    exitCode: cleanSafeNumber(value.exitCode),
+    oom: isRecord(value.oom)
+      ? {
+        source: cleanString(value.oom.source, `exitedAgents[${index}].oom.source`, { required: true, max: 80 })!,
+        detail: cleanString(value.oom.detail, `exitedAgents[${index}].oom.detail`, { max: 240 }),
+      }
+      : undefined,
     unavailable,
     lastError: cleanString(value.lastError, `exitedAgents[${index}].lastError`, { required: true, max: 1000 })!,
   };

package/src/routes/workspaces.ts

@@ -13,6 +13,7 @@ import { resolve } from "node:path";
 import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecoveryBranch, type WorkspaceRecord, type WorkspaceStatus } from "../types";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { workspaceActiveClaim } from "../workspace-claim";
+import { resolveCoordinatorAgentId } from "../steward-identity";
 import { relayToken } from "../config";
 
 export const getWorkspaces: Handler = (req) => {
@@ -337,6 +338,9 @@ export const getWorkspaceDiagnostics: Handler = async (_req, params) => {
   if (!workspace) return error("workspace not found", 404);
   const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
   const ownerOnline = isOwnerAlive(workspace.ownerAgentId);
+  // #640 — surface the branch agent's coordinator (owner's `spawnedBy` lineage) so a steward
+  // inspecting the workspace knows who to escalate to, not just `repoRoot`.
+  const coordinatorAgentId = resolveCoordinatorAgentId(workspace.ownerAgentId);
   const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
   const orchOnline = Boolean(orch) && orch!.status === "online";
   const fetched = await fetchWorkspaceGitState(workspace);
@@ -354,6 +358,7 @@ export const getWorkspaceDiagnostics: Handler = async (_req, params) => {
     baseRef: workspace.baseRef,
     branchMismatch: workspace.branch && liveBranch ? workspace.branch !== liveBranch : undefined,
     owner: { id: workspace.ownerAgentId, status: owner?.status, online: ownerOnline },
+    coordinator: { id: coordinatorAgentId, online: coordinatorAgentId ? isOwnerAlive(coordinatorAgentId) : false },
     orchestrator: { id: orch?.id, online: orchOnline },
     ...(claim ? { claim: { by: claim.by, purpose: claim.purpose, expiresAt: claim.expiresAt } } : {}),
     ...(gitState ? { gitState } : { gitStateUnavailable: "unavailable" in fetched ? fetched.unavailable : "unknown" }),

package/src/services/terminal-provider-exit.ts

@@ -0,0 +1,33 @@
+// #633 — owning service for the silent clean-exit terminal event. A runner whose provider
+// terminally exits stays alive (manual-resume hold), so neither the orchestrator tmux-gone path nor
+// the heartbeat reaper fires. The runner marks the offline status edge with a `terminalProviderExit`
+// blob; this service turns that edge into a terminal `agent.exited` event with a #636 diagnosis, and
+// clears the hold when the provider genuinely resumes. Kept out of the bus transport so the
+// transport stays thin (transport-thinness ratchet, #348).
+import { isRecord } from "agent-relay-sdk";
+import { clearAgentMetaKeys } from "../db";
+import { notifyAgentOffline } from "../agent-lifecycle-events";
+import { diagnoseAgentDeath } from "../agent-death-diagnosis";
+import type { AgentCard } from "../types";
+
+/**
+ * React to an agent status transition observed on the bus.
+ * - dead→live with a stale marker: clear the hold so a keepalive can resurrect normally and a future
+ *   death isn't mislabelled off a stale marker.
+ * - live→offline carrying a `terminalProviderExit` marker: fire the terminal event once (edge), with
+ *   a death diagnosis (also persisted as a crash report inside notifyAgentOffline). No-op for
+ *   non-spawned agents (notifyAgentOffline guards on lineage) and graceful shutdowns (no marker).
+ */
+export function reconcileTerminalProviderExit(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): void {
+  if (after && after.status !== "offline" && before?.status === "offline" && isRecord(after.meta?.terminalProviderExit)) {
+    clearAgentMetaKeys(agentId, ["terminalProviderExit"]);
+    return;
+  }
+  if (!after || after.status !== "offline") return;
+  if (before && before.status === "offline") return;
+  const marker = after.meta?.terminalProviderExit;
+  if (!isRecord(marker)) return;
+  const reasonText = typeof marker.reason === "string" ? marker.reason : "provider exited";
+  const reason = `provider exited (${reasonText})`;
+  notifyAgentOffline(agentId, reason, diagnoseAgentDeath({ agent: after, reason }));
+}

package/src/services/transient-agent-reaper.ts

@@ -1,6 +1,6 @@
 import { createCommand } from "../commands-db";
 import { emitRelayEvent } from "../events";
-import { createActivityEvent, getAgent, listAgents, listWorkspaces } from "../db";
+import { createActivityEvent, getAgent, listAgents, listWorkspaces, recordTerminalEvent } from "../db";
 import { routeNotification } from "../notification-router";
 import { isProviderBlocked } from "../provider-state";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
@@ -135,6 +135,9 @@ export function reapTransientAgents(): Record<string, unknown> {
     });
     emitRelayEvent({ type: "command.requested", source: command.source, subject: command.id, data: { command } });
     emitRelayEvent({ type: "agent.exited", source: "server", subject: agent.id, data: { agentId: agent.id, parent: agent.spawnedBy, reason: "transient-complete", workspaceId: land.workspaceId, workspaceStatus: land.status } });
+    // #645 — persist a clean terminal marker so the #634 heartbeat-gap watchdog reads this benign
+    // completion as a terminus (not a silent death) once the reaped worker stops heartbeating.
+    recordTerminalEvent({ agentId: agent.id, reason: "transient-complete", kind: "agent.exited", createdAt: now });
     createActivityEvent({
       clientId: `transient-agent-reaped-${agent.id}-${now}`,
       kind: "state",

package/src/spawn-targets.ts

@@ -48,28 +48,44 @@ export function buildSpawnTargets(input: { callerId?: string; quota: number }):
 interface SpawnCatalogish {
   provider: SpawnProvider;
   defaultModel?: string;
-  models: Array<{ alias: string; providerModel: string; efforts: readonly string[]; defaultEffort?: string }>;
+  models: Array<{ alias: string; providerModel: string; efforts: readonly string[]; defaultEffort?: string; disabled?: boolean; unavailable?: string }>;
 }
 
 function providerMatrixFor(o: Orchestrator): Array<Record<string, unknown>> {
   const reported: ProviderCatalogSummary[] = o.providerCatalog ?? [];
   const global = effectiveProviderCatalogList();
+  // #643 — drop disabled models so relay_spawn_targets advertises only spawnable models (parity
+  // with the #485 dashboard pickers' `!model.disabled` filter). The disabled flag is a relay-side
+  // override (provider_model_overrides) that the effective catalog carries but the orchestrator-
+  // REPORTED catalog does not, so cross-reference the effective catalog by alias regardless of
+  // which source supplies the matrix entry — otherwise the reported path keeps advertising a model
+  // the server then rejects with "model is disabled".
+  // #368 — also drop models marked unavailable in the static catalog (provider-side suspension,
+  // e.g. export-control; semantically distinct from the operator-toggle disabled flag).
+  const disabledAliasesFor = (provider: SpawnProvider): Set<string> =>
+    new Set(global.find((e) => e.provider === provider)?.models.filter((m) => m.disabled).map((m) => m.alias) ?? []);
+  const unavailableAliasesFor = (provider: SpawnProvider): Set<string> =>
+    new Set(global.find((e) => e.provider === provider)?.models.filter((m) => m.unavailable).map((m) => m.alias) ?? []);
   return o.providers.map((provider) => {
     const cat: SpawnCatalogish | undefined =
       reported.find((s) => s.provider === provider) ?? global.find((e) => e.provider === provider);
+    const disabled = disabledAliasesFor(provider);
+    const unavailable = unavailableAliasesFor(provider);
     return {
       provider,
       available: true,
       ...(cat
         ? {
             defaultModel: cat.defaultModel,
-            models: cat.models.map((m) => ({
-              id: m.alias,
-              providerModel: m.providerModel,
-              default: cat.defaultModel === m.alias,
-              effortLevels: m.efforts,
-              ...(m.defaultEffort ? { defaultEffort: m.defaultEffort } : {}),
-            })),
+            models: cat.models
+              .filter((m) => !m.disabled && !disabled.has(m.alias) && !m.unavailable && !unavailable.has(m.alias))
+              .map((m) => ({
+                id: m.alias,
+                providerModel: m.providerModel,
+                default: cat.defaultModel === m.alias,
+                effortLevels: m.efforts,
+                ...(m.defaultEffort ? { defaultEffort: m.defaultEffort } : {}),
+              })),
           }
         : { models: [] }),
     };
@@ -111,6 +127,7 @@ export function spawnCapablePrimer(input: { canSpawn: boolean; quota?: number })
     "- Default to your OWN host. Only set orchestratorId to spawn onto another host when it runs a provider/model yours doesn't, or the work must run there.",
     `- Prefer a named profile (profile: "<name>") over hand-assembling provider+model+effort+approvalMode. Omitting profile applies ${DEFAULT_SPAWN_PROFILE_NAME}; omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.`,
     "- Set spawnRequestId for idempotency so a retried spawn doesn't double-create.",
+    "- After spawning, use relay_my_agents for your self-scoped child roster + quota and copy a returned spawnRequestId into relay_shutdown_agent when you need to reap.",
     "- Spawn is fire-and-forget: pass waitForRegistrationMs:0 and keep working — you'll be PUSHED agent.ready when the child is genuinely ready (past onboarding), or agent.spawn_failed / agent.exited otherwise. Don't block-poll.",
     "- Spawned children cannot themselves spawn (no grandchildren).",
   ].join("\n");