agent-relay-server 0.83.1 → 0.85.0

package/src/auth/password.ts

@@ -0,0 +1,122 @@
+// Password authentication provider (#389). The only built-in provider in Phase 1. Secrets are
+// hashed with scrypt (node:crypto — no dependency) and compared with `timingSafeEqual`, the same
+// constant-time primitive the token layer uses. The hash is stored in `auth_identities.secret_hash`
+// keyed by (provider="password", provider_subject=<username>).
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { createAuthIdentity, getAuthIdentity, type AuthIdentity } from "../db/auth-identities.ts";
+import { isRecord } from "agent-relay-sdk";
+import type { AuthProvider, AuthVerifyResult } from "./provider.ts";
+
+/** The provider id stored in `auth_identities.provider` and sent in a login request's `provider`. */
+export const PASSWORD_PROVIDER_ID = "password";
+
+// scrypt cost parameters. N=2^14 keeps 128*N*r ≈ 16MB under node's 32MB default maxmem; r=8/p=1 are
+// the standard interactive-login settings. keylen 64. Encoded into the hash string so a future cost
+// bump stays verifiable against existing hashes.
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEYLEN = 64;
+const SALT_BYTES = 16;
+export const DUMMY_PASSWORD_HASH =
+  `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${"00".repeat(SALT_BYTES)}$${"00".repeat(KEYLEN)}`;
+
+type PasswordVerifier = (password: string, stored: string | null) => boolean;
+type PasswordIdentityLookup = (provider: string, providerSubject: string) => AuthIdentity | undefined;
+
+interface PasswordVerifyAttempt {
+  valid: boolean;
+  attemptedKdf: boolean;
+}
+
+/** Hash a plaintext password into a self-describing `scrypt$N$r$p$saltHex$hashHex` string. */
+export function hashPassword(password: string): string {
+  const salt = randomBytes(SALT_BYTES);
+  const derived = scryptSync(password, salt, KEYLEN, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
+  return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt.toString("hex")}$${derived.toString("hex")}`;
+}
+
+function verifyPasswordAttempt(password: string, stored: string | null): PasswordVerifyAttempt {
+  if (!stored) return { valid: false, attemptedKdf: false };
+  const parts = stored.split("$");
+  if (parts.length !== 6 || parts[0] !== "scrypt") return { valid: false, attemptedKdf: false };
+  const [, nRaw, rRaw, pRaw, saltHex, hashHex] = parts as [string, string, string, string, string, string];
+  const N = Number(nRaw);
+  const r = Number(rRaw);
+  const p = Number(pRaw);
+  if (!Number.isInteger(N) || !Number.isInteger(r) || !Number.isInteger(p)) return { valid: false, attemptedKdf: false };
+  const expected = Buffer.from(hashHex, "hex");
+  if (expected.length <= 0) return { valid: false, attemptedKdf: false };
+  let derived: Buffer;
+  try {
+    derived = scryptSync(password, Buffer.from(saltHex, "hex"), expected.length, { N, r, p });
+  } catch {
+    return { valid: false, attemptedKdf: false };
+  }
+  return { valid: derived.length === expected.length && timingSafeEqual(derived, expected), attemptedKdf: true };
+}
+
+/** Constant-time verify a plaintext password against a stored `scrypt$...` hash. */
+export function verifyPassword(password: string, stored: string | null): boolean {
+  return verifyPasswordAttempt(password, stored).valid;
+}
+
+function verifyPasswordWithDummyFallback(password: string, stored: string | null): boolean {
+  const result = verifyPasswordAttempt(password, stored);
+  if (result.attemptedKdf) return result.valid;
+  verifyPasswordAttempt(password, DUMMY_PASSWORD_HASH);
+  return false;
+}
+
+/**
+ * Link a password login to a user (admin pre-link / first-user bootstrap). Hashes the password and
+ * inserts an `auth_identities` row. `username` is the `provider_subject` the user logs in with.
+ */
+export function createPasswordIdentity(input: {
+  userId: string;
+  username: string;
+  password: string;
+  metadata?: Record<string, unknown>;
+}): AuthIdentity {
+  return createAuthIdentity({
+    userId: input.userId,
+    provider: PASSWORD_PROVIDER_ID,
+    providerSubject: input.username,
+    secretHash: hashPassword(input.password),
+    metadata: input.metadata,
+  });
+}
+
+/** Parse `{ username, password }` from a login request body. */
+function readCredentials(credentials: unknown): { username: string; password: string } | null {
+  if (!isRecord(credentials)) return null;
+  const username = credentials.username ?? credentials.handle ?? credentials.email;
+  const password = credentials.password;
+  if (typeof username !== "string" || !username || typeof password !== "string" || !password) return null;
+  return { username, password };
+}
+
+export function verifyPasswordCredentials(
+  credentials: unknown,
+  opts: { lookupIdentity?: PasswordIdentityLookup; verifyStoredPassword?: PasswordVerifier } = {},
+): AuthVerifyResult | null {
+  const creds = readCredentials(credentials);
+  if (!creds) return null;
+  const lookupIdentity = opts.lookupIdentity ?? getAuthIdentity;
+  const verifyStoredPassword = opts.verifyStoredPassword ?? verifyPasswordWithDummyFallback;
+  const identity = lookupIdentity(PASSWORD_PROVIDER_ID, creds.username);
+  const passwordMatches = verifyStoredPassword(creds.password, identity?.secretHash ?? DUMMY_PASSWORD_HASH);
+  if (!identity || !passwordMatches) return null;
+  return { providerSubject: creds.username };
+}
+
+export const passwordAuthProvider: AuthProvider = {
+  id: PASSWORD_PROVIDER_ID,
+  displayName: "Password",
+  flow: "password",
+  verify(credentials: unknown): AuthVerifyResult | null {
+    // Unknown username, malformed stored hash, and wrong password all pay one scrypt verification
+    // before returning null, so login failure timing does not identify linked accounts.
+    return verifyPasswordCredentials(credentials);
+  },
+};

package/src/auth/provider.ts

@@ -0,0 +1,60 @@
+// Pluggable authentication providers (#389). An AuthProvider turns a login request into a
+// `providerSubject` — the stable external identifier (a username, an OAuth `sub`, an email) that
+// `auth_identities` maps onto a `users.id`. The login route is provider-agnostic: it resolves the
+// provider, calls `verify()`, then looks the returned subject up in `auth_identities`. Adding a
+// provider (GitHub OAuth in Phase 2, magic-link, …) is a `register()` call plus rows — no schema
+// change, no route change (the pluggability guarantee #389 must hold).
+//
+// In-process registry. The registry knows ONLY the interface — concrete providers register
+// themselves via the composition root (src/auth/index.ts), which keeps this module free of any
+// dependency on a concrete provider (no registry ↔ plugin cycle).
+
+/** How a provider proves identity — drives the login UI and which fields `verify()` reads. */
+export type AuthProviderFlow = "password" | "oauth" | "magic-link";
+
+/** Result of a successful `verify()`: the external subject to resolve against `auth_identities`. */
+export interface AuthVerifyResult {
+  providerSubject: string;
+  /** Optional provider-supplied profile bits (display name, email) for first-link/auto-provision. */
+  profile?: Record<string, unknown>;
+}
+
+export interface AuthProvider {
+  /** Stable id; the `auth_identities.provider` value and the `provider` field a login request sends. */
+  id: string;
+  /** Human label for the login UI. */
+  displayName: string;
+  flow: AuthProviderFlow;
+  /**
+   * Begin an interactive (redirect) flow — returns where to send the user (e.g. an OAuth authorize
+   * URL). Optional: password is single-step and omits it. Phase 2 (GitHub OAuth) implements it.
+   */
+  begin?(req: Request): Promise<{ redirectUrl: string } | null> | ({ redirectUrl: string } | null);
+  /**
+   * Verify the presented credentials and return the authenticated subject, or null on failure.
+   * MUST be constant-ish on failure (no "unknown user" vs "bad password" distinction leaking to
+   * the caller — both return null). The route maps a non-null subject to a user.
+   */
+  verify(credentials: unknown): Promise<AuthVerifyResult | null> | (AuthVerifyResult | null);
+}
+
+const registry = new Map<string, AuthProvider>();
+
+/** Register (or replace) a provider. Idempotent by id — re-registering overrides, which is how
+ * tests install a throwaway provider to prove pluggability. */
+export function registerAuthProvider(provider: AuthProvider): void {
+  registry.set(provider.id, provider);
+}
+
+/** Remove a provider by id (test teardown / runtime disable). Returns true if one was removed. */
+export function unregisterAuthProvider(id: string): boolean {
+  return registry.delete(id);
+}
+
+export function getAuthProvider(id: string): AuthProvider | undefined {
+  return registry.get(id);
+}
+
+export function listAuthProviders(): AuthProvider[] {
+  return [...registry.values()];
+}

package/src/auth/session.ts

@@ -0,0 +1,92 @@
+// Human session tokens (#389). A session is a component token minted via the existing `createToken`
+// — the `tokens` table IS the session store, so `verifyComponentToken` already enforces expiry and
+// revocation, and "sign out everywhere" is just revoking every token for a `sub`. The session token
+// reuses ONLY the signing primitive: it carries a new `sub` namespace (`user:<id>`) and a new
+// `role` ("user"), so no machine-token path branches on it.
+import { userSinkId, userIdFromAddress, isHumanAgentId, type User, type UserRole } from "agent-relay-sdk";
+import { createToken } from "../token-db.ts";
+import { verifyComponentToken } from "../security.ts";
+import { getUser } from "../db/users.ts";
+import type { ComponentToken } from "../types.ts";
+
+/** Access token lifetime (~1h) — short, because refresh re-mints it silently. */
+export const ACCESS_TTL_SECONDS = 60 * 60;
+/** Refresh token lifetime (~30d) — the dashboard re-mints the access token until this expires. */
+export const REFRESH_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** Marker scope carried ONLY by refresh tokens. It matches no route's required scope, so a refresh
+ * token can never act as an access token; the refresh route validates it explicitly. */
+export const REFRESH_SCOPE = "auth:refresh";
+
+/** The `role` stamped on a human session token. New namespace — no machine path branches on it. */
+export const USER_TOKEN_ROLE = "user";
+
+/**
+ * Map a user role to the scopes its session carries. STOPGAP for #392 (real RBAC): admins get full
+ * access via the `admin:*` alias (→ `system:admin`, which `hasScope` short-circuits everywhere), and
+ * everyone else gets a read-only baseline. When #392 lands the per-role scope matrix, replace this
+ * one function — every session inherits the new policy with no other change.
+ */
+export function scopesForUserRole(role: UserRole): string[] {
+  if (role === "admin") return ["admin:*"];
+  if (role === "operator") return ["agent:read", "agent:write", "message:read", "message:send", "task:read", "task:write"];
+  return ["agent:read", "message:read", "task:read"];
+}
+
+export interface MintedSession {
+  accessToken: string;
+  refreshToken: string;
+  accessJti: string;
+  refreshJti: string;
+  expiresIn: number;
+}
+
+/**
+ * Mint an access + refresh token pair for a logged-in user. `constraints.tenantId` carries the
+ * SaaS seam (identity-only — enforces nothing). Both tokens share the `user:<id>` sub so a single
+ * "sign out everywhere" revoke (by sub) kills the whole session family.
+ */
+export function mintUserSession(user: User): MintedSession {
+  const sub = userSinkId(user.id);
+  const constraints = user.tenantId ? { tenantId: user.tenantId } : undefined;
+  const access = createToken({
+    sub,
+    role: USER_TOKEN_ROLE,
+    scope: scopesForUserRole(user.role),
+    constraints,
+    ttlSeconds: ACCESS_TTL_SECONDS,
+    createdBy: `auth:login:${user.id}`,
+  });
+  const refresh = createToken({
+    sub,
+    role: USER_TOKEN_ROLE,
+    scope: [REFRESH_SCOPE],
+    constraints,
+    ttlSeconds: REFRESH_TTL_SECONDS,
+    createdBy: `auth:refresh:${user.id}`,
+  });
+  return {
+    accessToken: access.token,
+    refreshToken: refresh.token,
+    accessJti: access.record.jti,
+    refreshJti: refresh.record.jti,
+    expiresIn: ACCESS_TTL_SECONDS,
+  };
+}
+
+/**
+ * Validate a refresh token and resolve it to its live user. Returns null unless the token verifies
+ * (signature + unexpired + unrevoked, via `verifyComponentToken`), carries the refresh scope, names
+ * a human `sub`, and that user still exists and is active. The caller mints a fresh session for the
+ * user.
+ */
+export function resolveRefreshToken(token: string): { user: User; payload: ComponentToken } | null {
+  const payload = verifyComponentToken(token);
+  if (!payload) return null;
+  if (!payload.scope.includes(REFRESH_SCOPE)) return null;
+  if (!isHumanAgentId(payload.sub)) return null;
+  const userId = userIdFromAddress(payload.sub);
+  if (!userId) return null;
+  const user = getUser(userId);
+  if (!user || user.status !== "active") return null;
+  return { user, payload };
+}

package/src/bus.ts

@@ -7,6 +7,7 @@ import { getCommand, updateCommand } from "./commands-db";
 import { emitCommandEvent } from "./command-events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
+import { reconcileTerminalProviderExit } from "./services/terminal-provider-exit";
 import { registerAgent } from "./services/register-agent";
 import { authContextFromBus } from "./services/auth-context";
 import { commandAuthorizationResource, dispatchCommand } from "./services/dispatch-command";
@@ -143,10 +144,19 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
     case "heartbeat":
       withRegistered(ws, frame, (conn) => {
         if (conn.agentId) {
-          const runtime = runtimeFromMeta(frame.payload.meta);
-          heartbeat(conn.agentId, { instanceId: conn.instanceId, epoch: conn.epoch }, runtime);
-          if (frame.payload.status) setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
-          emitAgentStatusEvent(conn.agentId);
+          // #633 — a runner whose provider terminally exited stays alive and keeps sending idle
+          // keepalives (semanticStatus is never "offline"). Those must NOT resurrect an agent the
+          // server already marked offline for that terminal exit, or the death would keep masking
+          // itself. Ignore the keepalive (the row ages out via the normal offline-prune); a genuine
+          // resume sends a `status`/`register` frame, which clears the hold below.
+          const current = getAgent(conn.agentId);
+          const heldOffline = current?.status === "offline" && isRecord(current.meta?.terminalProviderExit);
+          if (!heldOffline) {
+            const runtime = runtimeFromMeta(frame.payload.meta);
+            heartbeat(conn.agentId, { instanceId: conn.instanceId, epoch: conn.epoch }, runtime);
+            if (frame.payload.status) setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
+            emitAgentStatusEvent(conn.agentId);
+          }
         }
         if (frame.id) send(ws, { type: "ack", payload: { frameId: frame.id } });
       });
@@ -180,6 +190,10 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
+        // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
+        // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
+        // terminal event + #636 diagnosis (and clears the hold on a genuine resume).
+        reconcileTerminalProviderExit(conn.agentId, before, after);
       });
       return;
     case "ack":

package/src/db/agents.ts

@@ -331,6 +331,36 @@ export function mergeAgentMeta(id: string, meta: Record<string, unknown>, guard?
   return result.changes > 0;
 }
 
+/** #633/#634 — persist a durable "this child became ready" marker. Death classification
+ *  (`notifyAgentOffline`) keys `agent.exited` vs `agent.spawn_failed` off readiness, but the live
+ *  signal is an in-memory set that a relay restart wipes — so a long-ready child's later clean exit
+ *  would mis-fire `spawn_failed`. This stamp survives the restart in SQLite, so the offline edge
+ *  still classifies as `agent.exited`. Idempotent: only stamped once (first ready). */
+export function markAgentReadyNotified(id: string, at: number = Date.now()): boolean {
+  const agent = getAgent(id);
+  if (!agent) return false;
+  if (typeof agent.meta?.readyNotifiedAt === "number") return false;
+  const merged = { ...(agent.meta ?? {}), readyNotifiedAt: at };
+  return getDb().query("UPDATE agents SET meta = ? WHERE id = ?").run(JSON.stringify(merged), id).changes > 0;
+}
+
+/** Delete specific keys from an agent's meta blob. Returns true if anything changed. Used to clear
+ *  the #633 `terminalProviderExit` hold when a dead provider genuinely resumes. */
+export function clearAgentMetaKeys(id: string, keys: string[]): boolean {
+  const agent = getAgent(id);
+  if (!agent?.meta) return false;
+  const meta = { ...agent.meta };
+  let changed = false;
+  for (const key of keys) {
+    if (key in meta) {
+      delete meta[key];
+      changed = true;
+    }
+  }
+  if (!changed) return false;
+  return getDb().query("UPDATE agents SET meta = ? WHERE id = ?").run(JSON.stringify(meta), id).changes > 0;
+}
+
 export function recordAgentExitDiagnostics(id: string, diagnostics: ManagedSessionExitDiagnostics): AgentCard | null {
   const agent = getAgent(id);
   if (!agent) return null;
@@ -341,9 +371,12 @@ export function recordAgentExitDiagnostics(id: string, diagnostics: ManagedSessi
     lastExit: diagnostics,
     lastExitAt: diagnostics.detectedAt || now,
   };
+  // #636 — do NOT clobber last_seen with `now`: it is the agent's genuine last heartbeat, and the
+  // death diagnosis derives the real heartbeat gap from it (the orchestrator exit path diagnoses
+  // off the row returned here). "When we detected the exit" lives in meta.lastExitAt instead.
   const result = getDb()
-    .query("UPDATE agents SET status = 'offline', ready = 0, meta = ?, last_seen = ? WHERE id = ?")
-    .run(JSON.stringify(merged), now, id);
+    .query("UPDATE agents SET status = 'offline', ready = 0, meta = ? WHERE id = ?")
+    .run(JSON.stringify(merged), id);
   if (result.changes <= 0) return null;
   closeOpenPairsForAgent(id, now);
   return getAgent(id);

package/src/db/auth-identities.ts

@@ -0,0 +1,119 @@
+// Pluggable authentication identities (#389 auth & sessions). Maps an external login —
+// a (provider, provider_subject) pair such as ("password", "admin") or ("github", "12345") —
+// onto a relational `users.id`. The login flow authenticates a provider_subject, looks it up
+// here, and mints a session token for the resolved user. Provider-agnostic by construction:
+// `secret_hash` is nullable so an OAuth/magic-link identity is just a row with no stored secret —
+// a new provider needs ZERO schema change (the #389 pluggability guarantee).
+//
+// DDL home (single owner; the barrel re-exports, never inlines DDL). Wired into applyMigrations
+// right after seedDefaultUser(), mirroring the idempotent ensureUsersSchema() pattern.
+import { randomUUID } from "node:crypto";
+import { getDb } from "./connection.ts";
+
+export interface AuthIdentity {
+  id: string;
+  userId: string;
+  provider: string;
+  providerSubject: string;
+  /** Opaque provider-managed secret material (e.g. a scrypt password hash). Null for secretless
+   * providers (OAuth, magic-link) whose proof lives with the upstream provider, not here. */
+  secretHash: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+}
+
+interface AuthIdentityRow {
+  id: string;
+  user_id: string;
+  provider: string;
+  provider_subject: string;
+  secret_hash: string | null;
+  metadata: string | null;
+  created_at: number;
+}
+
+/**
+ * Single DDL home for `auth_identities` (#389). Idempotent (CREATE TABLE IF NOT EXISTS), so it is
+ * safe on every boot/migration — an old single-user DB gains the table on upgrade, with zero rows,
+ * and the god-token break-glass keeps working without any identity present. `UNIQUE(provider,
+ * provider_subject)` makes a login subject resolve to exactly one identity; `user_id` cascades on
+ * user delete so removing a human drops their logins.
+ */
+export function ensureAuthIdentitiesSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS auth_identities (
+      id TEXT PRIMARY KEY,
+      user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      provider TEXT NOT NULL,
+      provider_subject TEXT NOT NULL,
+      secret_hash TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      UNIQUE(provider, provider_subject)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_auth_identities_user ON auth_identities(user_id)");
+}
+
+function rowToIdentity(row: AuthIdentityRow): AuthIdentity {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    provider: row.provider,
+    providerSubject: row.provider_subject,
+    secretHash: row.secret_hash,
+    metadata: row.metadata ? (JSON.parse(row.metadata) as Record<string, unknown>) : {},
+    createdAt: row.created_at,
+  };
+}
+
+/** Resolve a login subject to its identity, or undefined if no such (provider, subject) exists. */
+export function getAuthIdentity(provider: string, providerSubject: string): AuthIdentity | undefined {
+  const row = getDb()
+    .query("SELECT * FROM auth_identities WHERE provider = ? AND provider_subject = ?")
+    .get(provider, providerSubject) as AuthIdentityRow | null;
+  return row ? rowToIdentity(row) : undefined;
+}
+
+/** All identities linked to a user — used by account UIs and "unlink provider" flows. */
+export function listAuthIdentitiesForUser(userId: string): AuthIdentity[] {
+  const rows = getDb()
+    .query("SELECT * FROM auth_identities WHERE user_id = ? ORDER BY created_at")
+    .all(userId) as AuthIdentityRow[];
+  return rows.map(rowToIdentity);
+}
+
+/**
+ * Link a login to a user. `secretHash` is null for secretless providers. Throws on a duplicate
+ * (provider, provider_subject) — the caller surfaces it as a 409/validation error.
+ */
+export function createAuthIdentity(input: {
+  userId: string;
+  provider: string;
+  providerSubject: string;
+  secretHash?: string | null;
+  metadata?: Record<string, unknown>;
+}): AuthIdentity {
+  const id = randomUUID();
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO auth_identities (id, user_id, provider, provider_subject, secret_hash, metadata, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      id,
+      input.userId,
+      input.provider,
+      input.providerSubject,
+      input.secretHash ?? null,
+      JSON.stringify(input.metadata ?? {}),
+      now,
+    );
+  return getAuthIdentity(input.provider, input.providerSubject)!;
+}
+
+/** Remove an identity by id. Returns true if a row was deleted. */
+export function deleteAuthIdentity(id: string): boolean {
+  return getDb().query("DELETE FROM auth_identities WHERE id = ?").run(id).changes > 0;
+}

package/src/db/crash-reports.ts

@@ -0,0 +1,115 @@
+// #636 — persisted crash post-mortems. Stored in their own table (no FK to agents) so a death
+// verdict survives `pruneOfflineAgents` / `deleteAgent` and stays retrievable by agentId after the
+// worktree/session reaper has cleaned up. One row per (agentId, createdAt); the latest wins on read.
+import { getDb } from "./connection.ts";
+import { parseJson } from "../utils";
+import type { AgentDeathDiagnosis, CrashReport } from "../types";
+
+interface CrashReportRow {
+  agent_id: string;
+  parent_id: string | null;
+  team_id: string | null;
+  spawn_request_id: string | null;
+  provider: string | null;
+  label: string | null;
+  cause: string;
+  reason: string;
+  diagnosis: string;
+  created_at: number;
+}
+
+export function ensureCrashReportsSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS crash_reports (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL,
+      parent_id TEXT,
+      team_id TEXT,
+      spawn_request_id TEXT,
+      provider TEXT,
+      label TEXT,
+      cause TEXT NOT NULL,
+      reason TEXT NOT NULL,
+      diagnosis TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_crash_reports_agent ON crash_reports(agent_id, created_at DESC)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_crash_reports_parent ON crash_reports(parent_id, created_at DESC)");
+}
+
+function rowToCrashReport(row: CrashReportRow): CrashReport {
+  return {
+    agentId: row.agent_id,
+    ...(row.parent_id ? { parentId: row.parent_id } : {}),
+    ...(row.team_id ? { teamId: row.team_id } : {}),
+    ...(row.spawn_request_id ? { spawnRequestId: row.spawn_request_id } : {}),
+    ...(row.provider ? { provider: row.provider } : {}),
+    ...(row.label ? { label: row.label } : {}),
+    reason: row.reason,
+    diagnosis: parseJson<AgentDeathDiagnosis>(row.diagnosis, {
+      cause: "unknown",
+      confidence: "low",
+      summary: "Cause undetermined",
+      evidence: [],
+      detectedAt: row.created_at,
+    }),
+    createdAt: row.created_at,
+  };
+}
+
+export function recordCrashReport(report: CrashReport): void {
+  getDb()
+    .query(
+      `INSERT INTO crash_reports (agent_id, parent_id, team_id, spawn_request_id, provider, label, cause, reason, diagnosis, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      report.agentId,
+      report.parentId ?? null,
+      report.teamId ?? null,
+      report.spawnRequestId ?? null,
+      report.provider ?? null,
+      report.label ?? null,
+      report.diagnosis.cause,
+      report.reason,
+      JSON.stringify(report.diagnosis),
+      report.createdAt,
+    );
+}
+
+/** The most recent crash report for an agent, or null if none was ever recorded. */
+export function getCrashReport(agentId: string): CrashReport | null {
+  const row = getDb()
+    .query("SELECT * FROM crash_reports WHERE agent_id = ? ORDER BY created_at DESC, id DESC LIMIT 1")
+    .get(agentId) as CrashReportRow | undefined;
+  return row ? rowToCrashReport(row) : null;
+}
+
+export interface ListCrashReportsFilter {
+  /** Restrict to children of this spawn-parent (the parent/self scope for the MCP tool). */
+  parentId?: string;
+  /** Restrict to a single agent. */
+  agentId?: string;
+  limit?: number;
+}
+
+export function listCrashReports(filter: ListCrashReportsFilter = {}): CrashReport[] {
+  const where: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.parentId) {
+    where.push("parent_id = ?");
+    params.push(filter.parentId);
+  }
+  if (filter.agentId) {
+    where.push("agent_id = ?");
+    params.push(filter.agentId);
+  }
+  const limit = Math.max(1, Math.min(filter.limit ?? 50, 200));
+  const rows = getDb()
+    .query(
+      `SELECT * FROM crash_reports ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY created_at DESC, id DESC LIMIT ?`,
+    )
+    .all(...params, limit) as CrashReportRow[];
+  return rows.map(rowToCrashReport);
+}

package/src/db/index.ts

@@ -17,6 +17,7 @@ export * from "./delivery.ts";
 export * from "./message-reads.ts";
 export * from "./inbox.ts";
 export * from "./users.ts";
+export * from "./auth-identities.ts";
 export * from "./agent-ownership.ts";
 export * from "./drive-leases.ts";
 export * from "./activity.ts";
@@ -26,6 +27,7 @@ export * from "./workspaces.ts";
 export * from "./merge-lease.ts";
 export * from "./continuations.ts";
 export * from "./continuation-archives.ts";
+export * from "./crash-reports.ts";
 export * from "./plans.ts";
 export * from "./teams.ts";
 export * from "./blackboard.ts";

package/src/db/migrations.ts

@@ -16,9 +16,11 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import { ensureUsersSchema, seedDefaultUser } from "./users.ts";
+import { ensureAuthIdentitiesSchema } from "./auth-identities.ts";
 import { ensureAgentOwnershipSchema, seedDefaultAgentOwnership } from "./agent-ownership.ts";
 import { ensureDriveLeaseSchema } from "./drive-leases.ts";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
+import { ensureCrashReportsSchema } from "./crash-reports.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
 import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
 import { projectRootsMissingIssueRepo, setProjectIssueRepo } from "./projects.ts";
@@ -794,12 +796,21 @@ export function applyMigrations(): void {
     )
   `);
 
+  // #636 — persisted crash post-mortems. Own table, no FK to agents, so a death verdict outlives
+  // the offline-prune/reaper and stays retrievable by agentId.
+  ensureCrashReportsSchema();
+
   // First-class human users (#388 keystone #393): ensure the table (single DDL home in users.ts)
   // and seed the admin-level default user mapped to the existing single human. P0 + idempotent —
   // bare 'user' == user:default resolve to users.id='default' via the SDK resolver; no bytes move.
   ensureUsersSchema();
   seedDefaultUser();
 
+  // Pluggable login identities (#389): the (provider, provider_subject) → users.id map behind real
+  // login + sessions. Ensured right after the user seed (FK → users) and idempotent — an old
+  // single-user DB gains it empty, and the god-token break-glass keeps working with zero rows.
+  ensureAuthIdentitiesSchema();
+
   // Agent ownership/visibility table (#392). FK-references both agents and users, so it ensures
   // AFTER both exist. The backfill (seedDefaultAgentOwnership) runs below, once the built-in
   // agents are in, so they can be excluded from ownership.

package/src/index.ts

@@ -268,7 +268,12 @@ export function createFetchHandler(
     const matched = matchRoute(req.method, url.pathname);
     if (matched) {
       const publicPaths = ["/api/spec", "/api/docs", "/api/health"];
-      if (!publicPaths.includes(url.pathname)) {
+      // Pre-auth allowlist (#389): the auth endpoints must be reachable unauthenticated — they ARE
+      // the way a session is obtained. Each handler self-authenticates (login verifies credentials,
+      // refresh validates the refresh token, logout revokes the presented token). Everything else
+      // still flows through the component-token gate below.
+      const publicAuthPaths = ["/api/auth/providers", "/api/auth/login", "/api/auth/refresh", "/api/auth/logout"];
+      if (!publicPaths.includes(url.pathname) && !publicAuthPaths.includes(url.pathname)) {
         const integrationAuth = getIntegrationAuth(req);
         const componentAuth = getComponentAuth(req);
         const handlerOwnsScopedAuth = url.pathname === "/api/tokens/me" ||