agent-relay-server 0.83.1 → 0.85.0

package/src/maintenance/jobs.ts

@@ -7,6 +7,7 @@ import {
   createActivityEvent,
   evaluatePoolBindings,
   expireQueuedMessages,
+  getAgent,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
   pruneOldMessages,
@@ -19,6 +20,7 @@ import {
   sweepArtifacts,
 } from "../db";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
+import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { autoMergeCleanFastForwards } from "../workspace-auto-merge";
 import { reapOrphanedWorktrees } from "../workspace-orphans";
 import { getLifecycleManager } from "../lifecycle-manager";
@@ -173,7 +175,10 @@ export const definitions: MaintenanceJobDefinition[] = [
       for (const id of reapedAgentIds) {
         emitAgentStatus(id);
         getLifecycleManager().onAgentDisappeared(id);
-        notifyAgentOffline(id, "heartbeat lost");
+        // #636 — a heartbeat-lost death still gets a best-effort post-mortem from the agent's last
+        // known meta (lastExit/lastError/auth) + heartbeat gap, riding the terminal event.
+        const diagnosis = diagnoseAgentDeath({ agent: getAgent(id), reason: "heartbeat lost" });
+        notifyAgentOffline(id, "heartbeat lost", diagnosis);
         createActivityEvent({
           clientId: "server-agent-" + id + "-heartbeat-lost-" + Date.now(),
           kind: "state",

package/src/maintenance/teams.ts

@@ -2,6 +2,7 @@ import {
   clearTeamZeroMembersSince,
   countLiveTeamMembers,
   createActivityEvent,
+  getCrashReport,
   getTeamBusyState,
   getTeamRoster,
   listActiveTeams,
@@ -13,10 +14,69 @@ import { dissolveTeamById } from "../services/team";
 import { getTeamsConfig } from "../teams-config-store";
 import { teamReapGraceMs } from "./constants";
 import { notifyTarget } from "./events";
-import { teamIdleTracker } from "../team-idle-tracker";
+import { teamIdleTracker, teamMemberWatchTracker, type TeamMemberWatch } from "../team-idle-tracker";
+import type { AgentCard } from "../types";
 
 export function resetTeamIdleWatchdogForTests(): void {
   teamIdleTracker.clear();
+  teamMemberWatchTracker.clear();
+}
+
+/** A member counts as "alive" (worth watching for a future silence) when it's past onboarding and
+ *  heartbeating — i.e. a status that implies it became ready, not a never-started spawn. */
+function memberIsAlive(member: AgentCard, freshCutoff: number): boolean {
+  return (member.status === "idle" || member.status === "busy" || member.status === "online") && member.lastSeen > freshCutoff;
+}
+
+/**
+ * #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.
+ */
+function detectSilentMembers(
+  teamId: string,
+  coordinatorId: string | undefined,
+  now: number,
+  thresholdMs: number,
+  out: { pingedMembers: string[]; watchedMembers: number },
+): void {
+  const freshCutoff = now - thresholdMs;
+  const watch = teamMemberWatchTracker.get(teamId) ?? new Map<string, TeamMemberWatch>();
+  teamMemberWatchTracker.set(teamId, watch);
+
+  for (const member of getTeamRoster(teamId)) {
+    if (member.id === coordinatorId) continue; // the coordinator is the recipient, not a watched worker
+    if (!memberIsAlive(member, freshCutoff)) continue;
+    const existing = watch.get(member.id);
+    // Recovery re-arms the ping: a member seen alive again after a silence can re-trigger later.
+    const recovered = existing ? member.lastSeen > existing.lastActiveAt : false;
+    watch.set(member.id, {
+      lastActiveAt: Math.max(member.lastSeen, existing?.lastActiveAt ?? 0),
+      pinged: recovered ? false : existing?.pinged ?? false,
+      ...(member.label ? { label: member.label } : {}),
+    });
+  }
+
+  out.watchedMembers += watch.size;
+  for (const [memberId, entry] of watch) {
+    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)
+    if (!coordinatorId) continue;
+    const minutes = Math.floor(gapMs / 60_000);
+    notifyTarget(
+      "team.member_silent",
+      { teamId, agentId: memberId },
+      coordinatorId,
+      "Team member went silent",
+      `Member \`${entry.label ?? memberId}\` in team \`${teamId}\` has sent no heartbeat for ${minutes} min — it may have died without a terminal event. Check it and restart its unfinished work, or stand it down.`,
+      { kind: "team.member_silent", teamId, coordinatorId, memberId, label: entry.label, silentForMs: gapMs, lastActiveAt: entry.lastActiveAt },
+    );
+    out.pingedMembers.push(memberId);
+  }
 }
 
 function teamIdlePayload(teamId: string, coordinatorId: string, thresholdMinutes: number, idleForMs: number, firstNoBusyAt: number) {
@@ -79,9 +139,13 @@ export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string
   const pingedTeamIds: string[] = [];
   const alreadyPingedTeamIds: string[] = [];
   const missingCoordinatorTeamIds: string[] = [];
+  const memberSilence = { pingedMembers: [] as string[], watchedMembers: 0 };
 
   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);
     const busy = getTeamBusyState(team.id, cutoff);
     if (busy.busyMemberIds.length > 0) {
       teamIdleTracker.delete(team.id);
@@ -112,6 +176,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);
 
   return {
     enabled: true,
@@ -122,6 +187,8 @@ export function runTeamIdleWatchdog(input: { now?: number } = {}): Record<string
     pingedTeamIds,
     alreadyPingedTeamIds,
     missingCoordinatorTeamIds,
+    silentMemberIds: memberSilence.pingedMembers,
+    watchedMembers: memberSilence.watchedMembers,
   };
 }
 

package/src/mcp/index.ts

@@ -16,7 +16,7 @@ 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 { MESSAGING_TOOLS, relayAgentCrashReport, relayAgentStatus, relayAttachArtifact, relayFindAgents, relayGetMessage, relayGetThread, relayReply, relaySendMessage, relayUploadArtifact } from "./tools-messaging";
 import { SPAWN_TOOLS, relayShutdownAgent, relaySpawnAgent, relaySpawnTargets } from "./tools-spawn";
 import { WORKSPACE_TOOLS, callerIsolatedWorkspace, relayWorkspaceList, relayWorkspaceMutation, relayWorkspaceStatus } from "./tools-workspace";
 
@@ -122,6 +122,7 @@ 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);

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/notification-types.ts

@@ -11,6 +11,7 @@ export type NotificationType =
   | "agent.transient_land_hold"
   | "agent.rate_limit_resume"
   | "team.idle"
+  | "team.member_silent"
   | "plan.bound_agent_exited"
   | "workspace.steward_task"
   | "workspace.conflict"
@@ -62,6 +63,7 @@ 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.conflict": null,

package/src/routes/_shared.ts

@@ -5,7 +5,7 @@ import { ValidationError, createActivityEvent, createCallbackDelivery, finishCal
 import { cleanEpoch, cleanString, optionalEnum } from "../validation";
 import { emitActivityEvent, emitMessageQueued, emitNewMessage } from "../sse";
 import { emitRelayEvent } from "../events";
-import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isRecord, userSinkId } from "agent-relay-sdk";
+import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isHumanAgentId, isRecord, userIdFromAddress, userSinkId } from "agent-relay-sdk";
 import { authorizeAgentForUser, visibleAgentIdsForUser, type AgentAction } from "../agent-authz";
 import { generateSpawnRequestId } from "../spawn-command";
 import { getComponentAuth, getIntegrationAuth, isAuthorized, isRequestAuthorizedFor } from "../security";
@@ -58,13 +58,51 @@ export function authAuditMetadata(req: Request): Record<string, unknown> {
       },
     };
   }
-  return hasPresentedCredential(req) ? { auth: { type: "root" } } : {};
+  if (!hasPresentedCredential(req)) return {};
+  // Root (god-token) credential: stamp the seeded-admin identity it now carries (#389 break-glass),
+  // so the audit trail records *who* acted instead of an anonymous root.
+  const acting = resolveActingUser(req);
+  return acting
+    ? { auth: { type: "root", userId: acting.userId, source: acting.source } }
+    : { auth: { type: "root" } };
 }
 
 export function isRootCredentialRequest(req: Request): boolean {
   return hasPresentedCredential(req) && isAuthorized(req) && !getComponentAuth(req) && !getIntegrationAuth(req);
 }
 
+/**
+ * Which human is acting, and how their request was authenticated (#389). The single bridge from a
+ * request to a `users.id`:
+ * - a human session token (component token whose `sub` is a `user:<id>` address) → that user, via
+ *   the SDK resolver (never a hand-rolled namespace) — `source: "session"`;
+ * - the raw god-token / root credential (`isRootCredentialRequest`) → the seeded admin
+ *   `DEFAULT_USER_ID` with `source: "break-glass"`. This is what gives the env token an *identity*
+ *   instead of the anonymous "server" it carried before, while it KEEPS bypassing scope checks
+ *   unchanged (the gate in src/index.ts is untouched). Works with zero `auth_identities` rows, so
+ *   it is simultaneously the break-glass path and the first-user bootstrap.
+ *
+ * Returns null for a machine component/integration token (no human is acting).
+ */
+export type ActingUserSource = "session" | "break-glass";
+
+export interface ActingUser {
+  userId: string;
+  source: ActingUserSource;
+}
+
+export function resolveActingUser(req: Request): ActingUser | null {
+  const component = getComponentAuth(req);
+  if (component && isHumanAgentId(component.sub)) {
+    const userId = userIdFromAddress(component.sub);
+    if (userId) return { userId, source: "session" };
+  }
+  if (isRootCredentialRequest(req)) {
+    return { userId: DEFAULT_USER_ID, source: "break-glass" };
+  }
+  return null;
+}
+
 function sanitizeAttribution(raw: unknown): string | undefined {
   if (typeof raw !== "string") return undefined;
   // eslint-disable-next-line no-control-regex

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/auth.ts

@@ -0,0 +1,107 @@
+// Authentication & session routes (#389). These four paths sit on a pre-auth PUBLIC ALLOWLIST
+// (src/index.ts) so they are reachable unauthenticated — each handler owns its own auth: login
+// verifies credentials, refresh validates the refresh token, logout revokes the presented session.
+// Everything else on the relay still flows through the existing component-token gate.
+import { isRecord, type User } from "agent-relay-sdk";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getAuthProvider, listAuthProviders, mintUserSession, resolveRefreshToken } from "../auth";
+import { getAuthIdentity, getUser } from "../db";
+import { revokeToken } from "../token-db.ts";
+import { getComponentAuth } from "../security";
+
+/** Public projection of a user for login/refresh responses — never leaks internal-only columns. */
+function userView(user: User): Record<string, unknown> {
+  return {
+    id: user.id,
+    handle: user.handle,
+    displayName: user.displayName,
+    role: user.role,
+    tenantId: user.tenantId,
+    avatarUrl: user.avatarUrl,
+  };
+}
+
+function sessionResponse(user: User): Response {
+  const session = mintUserSession(user);
+  return json({
+    tokenType: "Bearer",
+    accessToken: session.accessToken,
+    refreshToken: session.refreshToken,
+    expiresIn: session.expiresIn,
+    user: userView(user),
+  });
+}
+
+/** GET /api/auth/providers — the login screen reads this to render available login methods. */
+export const getAuthProvidersRoute: Handler = () =>
+  json({
+    providers: listAuthProviders().map((provider) => ({
+      id: provider.id,
+      displayName: provider.displayName,
+      flow: provider.flow,
+    })),
+  });
+
+/**
+ * POST /api/auth/login — body `{ provider, ...credentials }`. Resolves the provider, verifies the
+ * credentials to a `providerSubject`, maps it through `auth_identities` to a user, and mints a
+ * session. Every failure returns the same generic 401 (no provider/user/credential enumeration).
+ */
+export const postAuthLoginRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("login body required", 400);
+  const providerId = parsed.body.provider;
+  if (typeof providerId !== "string" || !providerId) return error("provider required", 400);
+
+  const provider = getAuthProvider(providerId);
+  if (!provider) return error("invalid credentials", 401);
+
+  const result = await provider.verify(parsed.body);
+  if (!result) return error("invalid credentials", 401);
+
+  const identity = getAuthIdentity(provider.id, result.providerSubject);
+  if (!identity) return error("invalid credentials", 401);
+
+  const user = getUser(identity.userId);
+  if (!user || user.status !== "active") return error("invalid credentials", 401);
+
+  return sessionResponse(user);
+};
+
+/**
+ * POST /api/auth/refresh — body `{ refreshToken }`. Validates the refresh token and mints a fresh
+ * session, rotating the refresh token: the consumed one is revoked so a captured refresh token is
+ * single-use. Returns the same generic 401 on any invalid/expired/revoked token.
+ */
+export const postAuthRefreshRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("refresh body required", 400);
+  const refreshToken = parsed.body.refreshToken;
+  if (typeof refreshToken !== "string" || !refreshToken) return error("refreshToken required", 400);
+
+  const resolved = resolveRefreshToken(refreshToken);
+  if (!resolved) return error("invalid refresh token", 401);
+
+  const response = sessionResponse(resolved.user);
+  // Rotate: revoke the consumed refresh token so it can't be replayed (the fresh pair supersedes it).
+  if (resolved.payload.jti) revokeToken(resolved.payload.jti, "rotation");
+  return response;
+};
+
+/**
+ * POST /api/auth/logout — revokes the presented session token and, if supplied, its refresh token.
+ * Idempotent: revoking an already-revoked or absent token is a no-op. Always returns 204.
+ */
+export const postAuthLogoutRoute: Handler = async (req) => {
+  const component = getComponentAuth(req);
+  if (component?.jti) revokeToken(component.jti, "admin");
+
+  const parsed = await parseBody<unknown>(req);
+  if (parsed.ok && isRecord(parsed.body) && typeof parsed.body.refreshToken === "string") {
+    const resolved = resolveRefreshToken(parsed.body.refreshToken);
+    if (resolved?.payload.jti) revokeToken(resolved.payload.jti, "admin");
+  }
+  return new Response(null, { status: 204 });
+};

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";
@@ -18,6 +18,7 @@ import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute,
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
 import { error, type Handler } from "./_shared";
+import { getAuthProvidersRoute, postAuthLoginRoute, postAuthLogoutRoute, postAuthRefreshRoute } from "./auth";
 import { getActivityEvents, postActivityEvent } from "./activity";
 import { getAnalyticsRoute, getHealthRoute, getMaintenanceJobs, getStatsRoute, postMaintenanceJobRun, postSystemReap } from "./stats";
 import { getApiDocs, getApiSpec } from "./spec";
@@ -69,6 +70,13 @@ function route(method: string, path: string, handler: Handler): Route {
 }
 
 const routes: Route[] = [
+  // Auth & sessions (#389). On the pre-auth public allowlist (src/index.ts) — each handler owns
+  // its own auth (login verifies credentials, refresh validates the refresh token, logout revokes).
+  route("GET", "/api/auth/providers", getAuthProvidersRoute),
+  route("POST", "/api/auth/login", postAuthLoginRoute),
+  route("POST", "/api/auth/refresh", postAuthRefreshRoute),
+  route("POST", "/api/auth/logout", postAuthLogoutRoute),
+
   route("POST", "/api/artifacts", postArtifact),
   route("GET", "/api/artifacts", getArtifacts),
   route("GET", "/api/artifacts/:id/content", getArtifactContent),
@@ -113,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/tokens.ts

@@ -1,7 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: tokens.
-import { SPAWN_PROVIDERS, isRecord } from "agent-relay-sdk";
+import { SPAWN_PROVIDERS, isRecord, userSinkId } from "agent-relay-sdk";
 import { ValidationError, getOrchestrator, upsertIntegrationRegistry } from "../db";
-import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, type Handler } from "./_shared";
+import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, resolveActingUser, type Handler } from "./_shared";
 import { cleanString, cleanStringArray, cleanTokenConstraints, optionalEnum } from "../validation";
 import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenProfiles, listTokens, renewToken, revokeToken, updateTokenProfile, upsertTokenProfile } from "../token-db";
 import { getComponentAuth, getIntegrationAuth, isAuthorized } from "../security";
@@ -36,6 +36,12 @@ export const getTokenMe: Handler = (req) => {
   }
 
   if (isAuthorized(req)) {
+    // Root (god-token) now carries the seeded-admin identity (#389): report *who* is acting
+    // (break-glass → user:default) instead of the anonymous "server" it showed before.
+    const acting = resolveActingUser(req);
+    if (acting) {
+      return json({ actor: userSinkId(acting.userId), userId: acting.userId, source: acting.source, kind: "server", scopes: ["*"] });
+    }
     return json({ actor: "server", kind: "server", scopes: ["*"] });
   }
   return error("unauthorized", 401);

package/src/security.ts

@@ -539,7 +539,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId") {
+    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId" || key === "projectId" || key === "tenantId") {
       if (typeof item !== "string") return false;
     } else if (key === "maxSpawnedAgents") {
       if (typeof item !== "number") return false;

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