agent-relay-server 0.85.0 → 0.87.0

package/src/maintenance/jobs.ts

@@ -1,4 +1,5 @@
 import { getArtifactStorage } from "../artifact-storage";
+import { deriveAgentBusyHealth } from "../agent-busy-health";
 import { expireStaleBusAgents } from "../bus";
 import { pruneOutbox } from "../bus-outbox";
 import { expireCommands } from "../commands-db";
@@ -8,9 +9,11 @@ import {
   evaluatePoolBindings,
   expireQueuedMessages,
   getAgent,
+  listAgents,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
   pruneOldMessages,
+  pruneProviderQuotaHistory,
   reapStaleAgents,
   reapStaleOrchestrators,
   releaseExpiredClaims,
@@ -34,6 +37,7 @@ import {
   emitPoolBindingChanged,
   emitTaskChanged,
 } from "../sse";
+import { routeNotification } from "../notification-router";
 import { pruneExpiredTokenRecords } from "../token-db";
 import { reapTransientAgents } from "../services/transient-agent-reaper";
 import { reapUnregisteredSpawnCommands } from "../services/spawn-registration-watchdog";
@@ -45,6 +49,8 @@ import {
   DAY_MS,
   ORPHAN_REAPER_INTERVAL_MS,
   OUTBOX_RETENTION_MS,
+  QUOTA_HISTORY_PRUNE_INTERVAL_MS,
+  QUOTA_HISTORY_RETENTION_MS,
   TOKEN_RECORD_RETENTION_SECONDS,
   WORKSPACE_AUTO_MERGE_INTERVAL_MS,
   WORKSPACE_GC_INTERVAL_MS,
@@ -60,6 +66,70 @@ import type { MaintenanceJobDefinition } from "./types";
 
 let dbMaintenanceRuns = 0;
 
+function isManagedBusyWatchCandidate(agent: ReturnType<typeof listAgents>[number]): boolean {
+  if (agent.kind !== "provider") return false;
+  if (agent.status !== "busy") return false;
+  if (agent.id === "user" || agent.id === "system") return false;
+  return agent.meta?.runnerManaged === true ||
+    typeof agent.meta?.policyName === "string" ||
+    agent.providerCapabilities?.lifecycle?.managed === true;
+}
+
+function stuckBusyBody(agentId: string, health: NonNullable<ReturnType<typeof deriveAgentBusyHealth>>): string {
+  const staleMinutes = Math.max(1, Math.floor(health.staleForMs / 60_000));
+  const work = health.activeWorkLabel || health.activeWorkKind || health.activeWorkId || health.kind;
+  return `Agent \`${agentId}\` appears stuck busy in ${work} for ${staleMinutes} min with no provider progress. Use interrupt first if available; restart or shutdown if the turn is wedged.`;
+}
+
+export function runStuckBusyWatchdog(input: { now?: number } = {}): Record<string, unknown> {
+  const now = input.now ?? Date.now();
+  const stuckAgentIds: string[] = [];
+  const notifiedAgentIds: string[] = [];
+  const checkedAgentIds: string[] = [];
+
+  for (const agent of listAgents({ status: "busy" })) {
+    if (!isManagedBusyWatchCandidate(agent)) continue;
+    checkedAgentIds.push(agent.id);
+    const health = deriveAgentBusyHealth(agent, now);
+    if (health?.status !== "stuck-busy") continue;
+    stuckAgentIds.push(agent.id);
+
+    const idempotencyKey = `agent-stuck-busy:${agent.id}:${health.kind}:${health.activeWorkStartedAt}:${health.thresholdMs}`;
+    createActivityEvent({
+      clientId: idempotencyKey,
+      kind: "state",
+      title: "Agent stuck busy",
+      body: stuckBusyBody(agent.id, health),
+      icon: "ti-alert-triangle",
+      view: "agents",
+      agentId: agent.id,
+      metadata: {
+        source: "server",
+        maintenanceJobId: "stuck-busy-watchdog",
+        severity: "warning",
+        busyHealth: health,
+      },
+    });
+
+    const messages = routeNotification({
+      type: "agent.stuck_busy",
+      scope: { agentId: agent.id, parent: agent.spawnedBy, teamId: agent.teamId },
+      recipients: ["user"],
+      message: {
+        subject: "Agent stuck busy",
+        body: stuckBusyBody(agent.id, health),
+        payload: { kind: "agent.stuck_busy", agentId: agent.id, busyHealth: health },
+        idempotencyKey,
+        replyExpected: false,
+      },
+    });
+    if (messages.length > 0) notifiedAgentIds.push(agent.id);
+    emitAgentStatus(agent.id);
+  }
+
+  return { checkedAgentIds, stuckAgentIds, notifiedAgentIds };
+}
+
 export const LEGACY_REAPER_JOB_IDS = [
   "claim-cleanup",
   "task-orphan-release",
@@ -216,6 +286,14 @@ export const definitions: MaintenanceJobDefinition[] = [
   },
   { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: reapTransientAgents },
   { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: resumeRateLimitedAgents },
+  {
+    id: "stuck-busy-watchdog",
+    title: "Stuck busy watchdog",
+    description: "Warn when a managed provider stays busy past the threshold without provider progress (#53).",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: false,
+    handler: runStuckBusyWatchdog,
+  },
   {
     id: "team-reap",
     title: "Team lifecycle close-out",
@@ -280,6 +358,16 @@ export const definitions: MaintenanceJobDefinition[] = [
       return runDbMaintenance({ vacuum });
     },
   },
+  {
+    id: "quota-history-prune",
+    title: "Quota history prune",
+    description: "Delete per-provider quota history snapshots (incl. unavailable markers) beyond the 30-day retention window (#609).",
+    intervalMs: QUOTA_HISTORY_PRUNE_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      return { prunedQuotaHistoryRows: pruneProviderQuotaHistory(Date.now() - QUOTA_HISTORY_RETENTION_MS) };
+    },
+  },
   {
     id: "bus-outbox-prune",
     title: "Bus outbox prune",

package/src/maintenance/teams.ts

@@ -2,24 +2,33 @@ import {
   clearTeamZeroMembersSince,
   countLiveTeamMembers,
   createActivityEvent,
+  getAgent,
   getCrashReport,
+  hasTerminalEvent,
   getTeamBusyState,
   getTeamRoster,
   listActiveTeams,
   setTeamZeroMembersSince,
 } from "../db";
-import { STALE_TTL_MS } from "../config";
+import { STALE_TTL_MS, stewardFallbackTarget } from "../config";
 import { agentProviderState } from "../provider-state";
 import { dissolveTeamById } from "../services/team";
+import { resolveCoordinatorAgentId } from "../steward-identity";
 import { getTeamsConfig } from "../teams-config-store";
 import { teamReapGraceMs } from "./constants";
 import { notifyTarget } from "./events";
-import { teamIdleTracker, teamMemberWatchTracker, type TeamMemberWatch } from "../team-idle-tracker";
+import {
+  teamCoordinatorWatchTracker,
+  teamIdleTracker,
+  teamMemberWatchTracker,
+  type TeamMemberWatch,
+} from "../team-idle-tracker";
 import type { AgentCard } from "../types";
 
 export function resetTeamIdleWatchdogForTests(): void {
   teamIdleTracker.clear();
   teamMemberWatchTracker.clear();
+  teamCoordinatorWatchTracker.clear();
 }
 
 /** A member counts as "alive" (worth watching for a future silence) when it's past onboarding and
@@ -32,8 +41,10 @@ function memberIsAlive(member: AgentCard, freshCutoff: number): boolean {
  * #634 — detect a team member that was ready/busy and then went silent (heartbeat-gap), EVEN IF it
  * dropped from the roster entirely, and ping the coordinator once. The in-memory watch remembers
  * each member's last-active time, so a vanished agent (no roster row) is still caught. Re-arms when
- * a member recovers. Skips the ping when a #633 crash report already exists (the coordinator was
- * already woken by the terminal event) — this is the backstop for the NO-terminal-event case.
+ * a member recovers. Skips the ping when any terminal event already fired — a #633 crash report (a
+ * DEATH the coordinator was already woken on) OR a #645 clean terminus (a transient worker reaped
+ * after its land, a graceful shutdown). This watchdog must surface ONLY a genuine silent death:
+ * an agent that went quiet with NO terminal event of any kind.
  */
 function detectSilentMembers(
   teamId: string,
@@ -64,7 +75,9 @@ function detectSilentMembers(
     const gapMs = now - entry.lastActiveAt;
     if (gapMs < thresholdMs || entry.pinged) continue;
     entry.pinged = true;
-    if (getCrashReport(memberId)) continue; // terminal event already woke the coordinator (#633)
+    // A terminal event already fired — a #633 crash report (death) or a #645 clean terminus
+    // (transient reap after land / graceful shutdown). Either way this is not a silent death.
+    if (getCrashReport(memberId) || hasTerminalEvent(memberId)) continue;
     if (!coordinatorId) continue;
     const minutes = Math.floor(gapMs / 60_000);
     notifyTarget(
@@ -79,6 +92,95 @@ function detectSilentMembers(
   }
 }
 
+/**
+ * #412/#468 — detect a team's COORDINATOR going silent and escalate to a human, instead of the team
+ * stalling forever. The member watchdog above SKIPS the coordinator (it's the ping recipient), and a
+ * missing/dead coordinator otherwise only gets recorded — never surfaced — so a silently-dead
+ * coordinator means nobody is driving and no member is even being listened to (#412's single point of
+ * failure). Reuses the SAME aliveness predicate (`memberIsAlive`) + terminal-event suppression
+ * (`getCrashReport || hasTerminalEvent`) as the member watch so a CLEANLY-exited coordinator does not
+ * false-positive. Escalates ONCE per gone-spell (re-arms on recovery) up the lineage — the gone
+ * coordinator's own coordinator (#639 resolver), falling back to the configured human/steward target
+ * — never dead-ending at `system`. A coordinator-gone team is always surfaced, never silently
+ * abandoned (no-silent-dissolve).
+ */
+function detectGoneCoordinator(
+  teamId: string,
+  coordinatorId: string | undefined,
+  now: number,
+  thresholdMs: number,
+  out: { escalatedTeamIds: string[]; suppressedTeamIds: string[]; goneCoordinatorIds: string[] },
+): void {
+  if (!coordinatorId) return; // no coordinator on the row — nothing to watch (idle path records this)
+  const freshCutoff = now - thresholdMs;
+  const existing = teamCoordinatorWatchTracker.get(teamId);
+  // A re-elected/claimed coordinator is a fresh identity — drop a watch left over from the old one.
+  if (existing && existing.coordinatorId !== coordinatorId) teamCoordinatorWatchTracker.delete(teamId);
+
+  const coord = getAgent(coordinatorId);
+  if (coord && memberIsAlive(coord, freshCutoff)) {
+    const prior = existing?.coordinatorId === coordinatorId ? existing : undefined;
+    teamCoordinatorWatchTracker.set(teamId, {
+      coordinatorId,
+      lastActiveAt: Math.max(coord.lastSeen, prior?.lastActiveAt ?? 0),
+      escalated: false, // alive again ⇒ re-arm the escalation
+      ...(coord.label ? { label: coord.label } : {}),
+    });
+    return;
+  }
+
+  // Coordinator is NOT alive (offline, heartbeat-stale, or vanished). Only escalate a coordinator we
+  // actually observed alive — never fire on cold/unknown startup state (mirrors the member watch).
+  const watch = teamCoordinatorWatchTracker.get(teamId);
+  if (!watch || watch.coordinatorId !== coordinatorId || watch.escalated) return;
+  watch.escalated = true; // one escalation per gone-spell, regardless of outcome below
+  out.goneCoordinatorIds.push(coordinatorId);
+
+  // A terminal marker means a #645 clean terminus (graceful shutdown) or a #633 crash the operator was
+  // already surfaced on — not a SILENT death. Suppress.
+  if (getCrashReport(coordinatorId) || hasTerminalEvent(coordinatorId)) {
+    out.suppressedTeamIds.push(teamId);
+    return;
+  }
+
+  // Escalate up the lineage, falling back to the configured human/steward target (#639/#642 pattern).
+  const escalationTarget = resolveCoordinatorAgentId(coordinatorId) ?? stewardFallbackTarget();
+  const label = watch.label ?? coordinatorId;
+  const sent = escalationTarget
+    ? notifyTarget(
+        "team.coordinator_gone",
+        { teamId, agentId: coordinatorId, parent: resolveCoordinatorAgentId(coordinatorId) ?? undefined },
+        escalationTarget,
+        "Team coordinator went silent",
+        `Coordinator \`${label}\` of team \`${teamId}\` has gone silent with no terminal event — nobody is driving the team and its members are no longer being listened to. Take over coordination, restart the team, or stand it down.`,
+        { kind: "team.coordinator_gone", teamId, coordinatorId, escalationTarget, label: watch.label },
+      )
+    : null;
+  if (sent) out.escalatedTeamIds.push(teamId);
+
+  // No-silent-dissolve: surface the coordinator-gone team on the dashboard even when there is no
+  // escalation target configured — it must never be silently abandoned.
+  createActivityEvent({
+    clientId: `team-coordinator-gone-${teamId}-${coordinatorId}-${now}`,
+    kind: "state",
+    title: "Team coordinator went silent",
+    body: sent
+      ? `Coordinator ${label} of team ${teamId} went silent — escalated to ${sent}.`
+      : `Coordinator ${label} of team ${teamId} went silent — no escalation target configured (set AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK).`,
+    meta: teamId,
+    icon: "ti-user-x",
+    view: "teams",
+    agentId: coordinatorId,
+    metadata: {
+      source: "server",
+      maintenanceJobId: "team-idle-watchdog",
+      teamId,
+      coordinatorId,
+      escalationTarget: sent ?? null,
+    },
+  });
+}
+
 function teamIdlePayload(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number) {
   const roster = getTeamRoster(teamId).map((member) => {
     const providerState = agentProviderState(member);
@@ -140,12 +242,17 @@ export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string
   const alreadyPingedTeamIds: string[] = [];
   const missingCoordinatorTeamIds: string[] = [];
   const memberSilence = { pingedMembers: [] as string[], watchedMembers: 0 };
+  const coordinatorGone = { escalatedTeamIds: [] as string[], suppressedTeamIds: [] as string[], goneCoordinatorIds: [] as string[] };
 
   for (const team of listActiveTeams()) {
     seen.add(team.id);
     // #634 — runs every cycle, independent of the team-level idle gate below: a single silent
     // member must surface even while OTHER members keep the team "busy".
     detectSilentMembers(team.id, team.coordinatorId, now, thresholdMs, memberSilence);
+    // #412/#468 — coordinator-gone escalation, also every cycle and independent of the idle gate: a
+    // dead coordinator must surface even if the team isn't (yet) idle, and the idle-ping path can't
+    // reach it (it would just ping the void).
+    detectGoneCoordinator(team.id, team.coordinatorId, now, thresholdMs, coordinatorGone);
     const busy = getTeamBusyState(team.id, cutoff);
     if (busy.busyMemberIds.length > 0) {
       teamIdleTracker.delete(team.id);
@@ -177,6 +284,7 @@ export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string
 
   for (const key of teamIdleTracker.keys()) if (!seen.has(key)) teamIdleTracker.delete(key);
   for (const key of teamMemberWatchTracker.keys()) if (!seen.has(key)) teamMemberWatchTracker.delete(key);
+  for (const key of teamCoordinatorWatchTracker.keys()) if (!seen.has(key)) teamCoordinatorWatchTracker.delete(key);
 
   return {
     enabled: true,
@@ -189,6 +297,9 @@ export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string
     missingCoordinatorTeamIds,
     silentMemberIds: memberSilence.pingedMembers,
     watchedMembers: memberSilence.watchedMembers,
+    coordinatorGoneTeamIds: coordinatorGone.escalatedTeamIds,
+    coordinatorGoneSuppressedTeamIds: coordinatorGone.suppressedTeamIds,
+    goneCoordinatorIds: coordinatorGone.goneCoordinatorIds,
   };
 }
 

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

@@ -17,7 +17,7 @@ import type { JsonRpcId, JsonRpcRequest, McpAuthContext, ToolDefinition } from "
 import { positiveIdOrUndefined, recordField, stringField } from "./validation";
 import { IDENTITY_TOOLS, hasAnyScope, mcpAuthContext, relayCompactAndResume, relayRecall, relayWhoami } from "./identity";
 import { MESSAGING_TOOLS, relayAgentCrashReport, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
-import { SPAWN_TOOLS, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
+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";
@@ -129,6 +129,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     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-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

@@ -5,6 +5,7 @@ export type NotificationType =
   | "agent.exited"
   | "agent.spawn_failed"
   | "agent.context_threshold"
+  | "agent.stuck_busy"
   | "agent.quota_threshold"
   | "agent.resume_budget_warning"
   | "agent.resume_budget_exhausted"
@@ -12,8 +13,10 @@ export type NotificationType =
   | "agent.rate_limit_resume"
   | "team.idle"
   | "team.member_silent"
+  | "team.coordinator_gone"
   | "plan.bound_agent_exited"
   | "workspace.steward_task"
+  | "workspace.steward_handoff"
   | "workspace.conflict"
   | "workspace.steward_reassigned"
   | "workspace.stranded_escalation"
@@ -57,6 +60,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.exited": null,
   "agent.spawn_failed": null,
   "agent.context_threshold": 15 * MINUTES,
+  "agent.stuck_busy": null,
   "agent.quota_threshold": 15 * MINUTES,
   "agent.resume_budget_warning": null,
   "agent.resume_budget_exhausted": null,
@@ -64,8 +68,10 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.rate_limit_resume": 15 * MINUTES,
   "team.idle": null,
   "team.member_silent": null,
+  "team.coordinator_gone": 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/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" }),