@humwick/server 0.0.0-stage → 0.130.0

package/src/db/agents.ts

@@ -0,0 +1,1284 @@
+import { mainThreadRegistry } from "./main-thread-state";
+import { spawnTreeParentIds } from "./spawn-tree";
+import { recordSpawnProcessExit } from "./spawn-process-evidence";
+import { revokeVaultTokens, terminalProviderLaunchId } from "./vault-tokens";
+import { isRecord, stringValue, isReservedAgentId, isHumanAgentId } from "@humwick/sdk";
+import { parseJson } from "../utils";
+import { STALE_TTL_MS, DAY_MS } from "../config";
+import { withoutAuthzMetaKeys } from "../authz-meta-keys";
+import {
+  jsonBytes,
+  splitAgentMetaForStorage,
+  splitAgentMetaPatchForStorage,
+  topLevelJsonPath,
+  warnIfAgentMetaOversized,
+} from "./agent-meta.ts";
+import { agentSessionGuardResult, reservedAgentIdSql } from "./agent-predicates.ts";
+import { ROSTER_AGENT_COLUMNS, getPersistedAgentCard, getPersistedAgentRuntimeCard, listPersistedAgentCards, type AgentCardFilter } from "./agent-card-read.ts";
+import { expectedChannelAgentId } from "./channel-identity.ts";
+import { evaluatePoolBindings, upsertChannelForAgent } from "./channels.ts";
+import { seedContinuationObjectiveFromSpawnPrompt } from "./continuations.ts";
+import { messageTaskClosed } from "./claim-sql.ts";
+import { ValidationError, getDb, inWriteTransaction, writeTransaction } from "./connection.ts";
+import { fencedColumnSql, lifecycleWriteOutcome, nextLifecycleSeq, type LifecycleWriteOutcome } from "./lifecycle-seq.ts";
+import { pendingPresence, evictPendingPresence, withBufferedPresence, snapshotPendingPresenceFlush, settlePendingPresenceFlush, type PresenceFlushPayload } from "./presence-buffer.ts";
+import { rowToAgent, rowToContextSnapshot, rowToQuotaSnapshot } from "./mappers.ts";
+import { closeOpenPairsForAgent } from "./pair-maintenance.ts";
+import { parseStringArray } from "./shared.ts";
+import { removeSubscriptionsForAgent } from "./notification-subscriptions.ts";
+import { clearAgentNotices } from "./terminal-events.ts";
+import { listAgentQuotaSnapshotsFromProviderStore } from "./provider-quotas.ts";
+import { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
+import { claimTaskWhere } from "./task-core.ts";
+import { withCanonicalSpawnRequestId } from "./spawn-request-id.ts";
+import { assertSpawnIntentActive } from "../spawn-intent";
+import { electWorkspaceStewards, electWorkspaceStewardsForAgent } from "./workspaces.ts";
+import { releaseWorkspaceClaimsForAgent } from "../steward-claim-release.ts";
+import { revokeTokenLineage, type LineageRevokeReason } from "./token-standing.ts";
+import type {
+  AgentCard,
+  AgentKind,
+  AgentSessionGuard,
+  ManagedSessionExitDiagnostics,
+  RegisterAgentInput,
+  ContextSnapshot,
+  ContextState,
+  ProviderCapabilities,
+  QuotaSnapshot,
+  QuotaState,
+} from "../types";
+
+type BeforeAgentStatusTransition = (agent: AgentCard, nextStatus: AgentCard["status"]) => void;
+const beforeAgentStatusTransitionHandlers = mainThreadRegistry("agents.ts:beforeAgentStatusTransitionHandlers", new Set<BeforeAgentStatusTransition>());
+
+/** Register synchronous work that must finish before a status transition is persisted. */
+export function onBeforeAgentStatusTransition(handler: BeforeAgentStatusTransition): () => void {
+  beforeAgentStatusTransitionHandlers.add(handler);
+  return () => beforeAgentStatusTransitionHandlers.delete(handler);
+}
+
+/** Fire the registered pre-transition handlers — the module-level Set only the MAIN thread's
+ *  `agents.ts` instance ever populates (registrations like `transient-agent-reaper.ts`'s never reach
+ *  a writer-worker's own instance), so this must only ever be invoked main-thread-side: from
+ *  `setStatus` directly, or from `setStatusAsync`'s pre-write orchestration. Never from the
+ *  `agents.setStatus` op body. */
+export function runBeforeAgentStatusTransitionHandlers(before: AgentCard, next: AgentCard["status"]): void {
+  for (const handler of beforeAgentStatusTransitionHandlers) handler(before, next);
+}
+
+const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
+
+export { parseStringArray } from "./shared.ts";
+
+export function normalizeTags(tags: string[] | undefined): string[] {
+  return [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
+}
+
+function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
+  if (input.kind) return input.kind;
+  if (isHumanAgentId(input.id)) return "user";
+  if (input.id === "system") return "system";
+  const metaKind = stringValue(input.meta?.kind);
+  if (metaKind === "channel" || metaKind === "communication-channel") return "channel";
+  if (metaKind === "orchestrator") return "orchestrator";
+  if ((input.tags ?? []).includes("channel") || (input.capabilities ?? []).includes("channel")) return "channel";
+  return "provider";
+}
+
+function inferProviderTag(input: RegisterAgentInput): "claude" | "codex" | undefined {
+  if (inferAgentKind(input) !== "provider") return undefined;
+  const meta = input.meta ?? {};
+  const values = [
+    input.id,
+    input.name,
+    input.rig,
+    ...(input.tags ?? []),
+    stringValue(meta.provider),
+    stringValue(meta.client),
+    stringValue(meta.runtime),
+    stringValue(meta.agentType),
+  ].filter((value): value is string => typeof value === "string");
+
+  if (values.some((value) => value.toLowerCase().includes("codex"))) return "codex";
+  if (values.some((value) => value.toLowerCase().includes("claude"))) return "claude";
+
+  // Older Claude hooks did not always send an explicit provider tag, but did
+  // send Claude-style approval metadata. Codex also sends approvalMode, so this
+  // fallback only runs after Codex signals have been ruled out.
+  if (Object.prototype.hasOwnProperty.call(meta, "approvalMode")) return "claude";
+  return undefined;
+}
+
+function tagsWithProvider(input: RegisterAgentInput): string[] {
+  const tags = normalizeTags(input.tags);
+  const provider = inferProviderTag(input);
+  if (!provider || tags.includes(provider)) return tags;
+  return [provider, ...tags];
+}
+
+
+export interface UpsertAgentTxResult {
+  agent: AgentCard;
+  contextState: ContextState | undefined;
+}
+
+export interface UpsertAgentOptions {
+  verifiedKeepJtis?: string[];
+  systemTags?: string[];
+  verifiedSpawnRequestId?: string;
+}
+
+/**
+ * The atomic op body for `agents.upsert` (S3 L10 #1895): the pre-#1057 comment below still applies
+ * unchanged, just relocated out of a `writeTransaction` closure so it can run either wrapped by the
+ * sync caller (`upsertAgent`) or by the writer executor when reached via the gateway. Folding
+ * `mergeRelayContextMarkers` (a read) in here — rather than leaving it computed before the
+ * transaction, as the pre-migration code did — closes a TOCTOU window that a real thread hop would
+ * otherwise open (ADR §3.4): the read and the write are now one atomic unit either way.
+ */
+export function upsertAgentInternal(
+  input: RegisterAgentInput,
+  opts: UpsertAgentOptions | undefined,
+  now: number,
+  /** #2111 — the registration's lifecycle ordinal, taken on the MAIN thread at submission.
+   *  Never defaulted inside this body: under a worker writer the module-global counter is a
+   *  different instance, and two counters could hand out the same ordinal. */
+  lifecycleSeq: number,
+): UpsertAgentTxResult {
+  const kind = inferAgentKind(input);
+  if (kind === "channel") {
+    const expectedId = expectedChannelAgentId(input);
+    if (input.id !== expectedId) {
+      throw new ValidationError(`channel agent id must be canonical: ${expectedId}`);
+    }
+  }
+  const tags = tagsWithProvider(input); const labelProvided = Object.prototype.hasOwnProperty.call(input, "label");
+  // Preserve the existing label across re-registrations unless the caller
+  // explicitly sends one (including null to clear).
+  const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
+  const lifecycleProvided = Object.prototype.hasOwnProperty.call(input, "lifecycle");
+  const instanceProvided = Boolean(input.instanceId);
+  const contextState = mergeRelayContextMarkers(input.id, input.context);
+  const storedMeta = splitAgentMetaForStorage(withCanonicalSpawnRequestId(input.meta));
+  const metaJson = JSON.stringify(storedMeta.meta);
+  const profileProjectionJson = storedMeta.profileProjection == null ? null : JSON.stringify(storedMeta.profileProjection);
+  warnIfAgentMetaOversized(input.id, metaJson, "stored meta");
+  const stmt = getDb().query(`
+    INSERT INTO agents (id, name, kind, label, tags, system_tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, quota_state, profile_projection, meta, lifecycle, spawned_by, team_id, status_seq, ready_seq, last_seen, created_at)
+    VALUES ($id, $name, $kind, $label, $tags, $systemTags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $providerCapabilities, $contextState, $quotaState, $profileProjection, $meta, $lifecycle, $spawnedBy, $teamId, $lifecycleSeq, $lifecycleSeq, $now, $now)
+    ON CONFLICT(id) DO UPDATE SET
+      name = $name,
+      kind = $kind,
+      label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
+      tags = $tags, system_tags = CASE WHEN $systemTagsProvided = 1 THEN $systemTags ELSE agents.system_tags END,
+      machine = coalesce($machine, agents.machine),
+      rig = coalesce($rig, agents.rig),
+      capabilities = $capabilities,
+      ${fencedColumnSql("ready", "CASE WHEN $readyProvided = 1 THEN $ready ELSE agents.ready END", "$lifecycleSeq", { qualifier: "agents." })},
+      ${fencedColumnSql("status", "$status", "$lifecycleSeq", { qualifier: "agents." })},
+      instance_id = CASE WHEN $instanceProvided = 1 THEN $instanceId ELSE agents.instance_id END,
+      epoch = CASE
+        WHEN $instanceProvided = 1 AND (agents.instance_id IS NULL OR agents.instance_id <> $instanceId) THEN agents.epoch + 1
+        ELSE agents.epoch
+      END,
+      provider_capabilities = coalesce($providerCapabilities, agents.provider_capabilities),
+      context_state = coalesce($contextState, agents.context_state),
+      quota_state = coalesce($quotaState, agents.quota_state),
+      profile_projection = CASE WHEN $profileProjectionProvided = 1 THEN $profileProjection ELSE agents.profile_projection END,
+      -- Re-registration replaces provider meta, but readiness is a server-owned lifetime stamp.
+      -- Keep it through a deploy restart even when the replacement has not become ready yet.
+      -- The server's idle self-care latch survives only within the same epoch.
+      meta = json_patch(CASE
+        WHEN json_type(agents.meta, '$.readyNotifiedAt') IN ('integer', 'real')
+          THEN json_set($meta, '$.readyNotifiedAt', json_extract(agents.meta, '$.readyNotifiedAt'))
+        ELSE $meta
+      END, json_object('idleSelfCare', CASE
+        WHEN ($instanceProvided = 0 OR agents.instance_id = $instanceId)
+          AND json_type(agents.meta, '$.idleSelfCare') = 'object'
+          AND json_extract(agents.meta, '$.idleSelfCare.epoch') = agents.epoch
+          THEN json_extract(agents.meta, '$.idleSelfCare')
+        ELSE NULL
+      END)),
+      lifecycle = CASE WHEN $lifecycleProvided = 1 THEN $lifecycle ELSE agents.lifecycle END,
+      spawned_by = coalesce($spawnedBy, agents.spawned_by),
+      team_id = coalesce($teamId, agents.team_id),
+      last_seen = $now
+  `);
+
+  // #1057(2) — the takeover revoke fires on the SAME predicate as the epoch bump, by observing
+  // the bump itself (prior.epoch !== next.epoch) rather than re-deriving the SQL's instance-
+  // transition condition. The old guard in registerAgent required a truthy prior instanceId, so a
+  // NULL→instanceId takeover bumped the epoch yet skipped the revoke, stranding the prior token
+  // until the 24h prune. Read→upsert upgrade (SELECT prior agent → INSERT…ON CONFLICT DO UPDATE) on
+  // the hot registration/re-registration path. #1057(4) — the write + superseded-token revoke share
+  // this op body: a revoke failure rolls the epoch bump back with it, atomically either way.
+  const prior = getAgent(input.id);
+  // Check under the same writer transaction as registration so cancellation cannot slip between.
+  assertSpawnIntentActive(storedMeta.meta.spawnRequestId ?? prior?.meta?.spawnRequestId);
+  assertSpawnIntentActive(opts?.verifiedSpawnRequestId);
+  stmt.run({
+    $lifecycleSeq: lifecycleSeq,
+    $id: input.id,
+    $name: input.name,
+    $kind: kind,
+    $label: input.label ?? null,
+    $labelProvided: labelProvided ? 1 : 0,
+    $tags: JSON.stringify(tags), $systemTags: JSON.stringify(normalizeTags(opts?.systemTags)),
+    $systemTagsProvided: opts?.systemTags !== undefined ? 1 : 0,
+    $machine: input.machine ?? null,
+    $rig: input.rig ?? null,
+    $capabilities: JSON.stringify(input.capabilities ?? []),
+    $ready: input.ready ? 1 : 0,
+    $readyProvided: readyProvided ? 1 : 0,
+    $status: input.status ?? "idle",
+    $instanceId: input.instanceId ?? null,
+    $instanceProvided: instanceProvided ? 1 : 0,
+    $initialEpoch: instanceProvided ? 1 : 0,
+    $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
+    $contextState: contextState ? JSON.stringify(contextState) : null,
+    $quotaState: input.quota ? JSON.stringify(input.quota) : null,
+    $profileProjection: profileProjectionJson,
+    $profileProjectionProvided: storedMeta.profileProjectionProvided ? 1 : 0,
+    $meta: metaJson, // #1456 round-10 — canonical spawnRequestId at ingress
+    $lifecycle: input.lifecycle ?? "persistent",
+    $lifecycleProvided: lifecycleProvided ? 1 : 0,
+    $spawnedBy: input.spawnedBy ?? null,
+    $teamId: input.teamId ?? null,
+    $now: now,
+  });
+  const next = getAgent(input.id)!;
+  if (prior && next.epoch !== prior.epoch) {
+    revokeSupersededRuntimeTokens(prior, opts?.verifiedKeepJtis ?? [], now);
+  }
+  return { agent: next, contextState };
+}
+
+/**
+ * BEGIN IMMEDIATE (#1428/#1431) so a concurrent writer waits on busy_timeout instead of an instant
+ * SQLITE_BUSY on the deferred upgrade. Orchestrates `upsertAgentInternal` (the atomic DB op, also
+ * reachable async via the `agents.upsert` writer op) with the cross-domain side effects that were
+ * already outside its transaction pre-migration (channel/pool/steward wiring, in-memory presence
+ * eviction) — kept outside here too, since several of them (workspaces.ts's steward election,
+ * presence-buffer.ts's `pendingPresence` map) rely on MAIN-THREAD-only state a writer-worker op body
+ * cannot see (the same class of bug the S3.1 L4 stale-read-on-async landmine surfaced).
+ */
+export function upsertAgent(input: RegisterAgentInput, opts?: UpsertAgentOptions): AgentCard {
+  const now = Date.now();
+  const lifecycleSeq = nextLifecycleSeq();
+  const { agent, contextState } = writeTransaction(() => upsertAgentInternal(input, opts, now, lifecycleSeq));
+  if (contextState) recordContextSnapshot(input.id, contextState, now);
+
+  // #1468 — a (re)registration writes the row authoritatively (fresh last_seen + a possibly bumped
+  // epoch on instance takeover), so any beat buffered against the PRIOR instance is stale and must
+  // not be flushed onto this successor. The flush's epoch guard also catches it; this evicts eagerly.
+  evictPendingPresence(agent.id);
+
+  seedContinuationObjectiveFromSpawnPrompt(agent.id, stringValue(agent.meta?.spawnRequestId), now);
+  if (agent.kind === "channel") upsertChannelForAgent(agent);
+  evaluatePoolBindings();
+  // A (re)joining agent may revive a dormant repo steward — re-elect for the
+  // repos it owns live workspaces in (issue #157, steward survives offline gap).
+  if (agent.status !== "offline") electWorkspaceStewardsForAgent(agent.id);
+  return agent;
+}
+
+export function validateAgentSession(id: string, guard?: AgentSessionGuard): { ok: boolean; error?: string } {
+  if (!guard || (!guard.instanceId && guard.epoch === undefined)) return { ok: true };
+  return agentSessionGuardResult(getAgent(id), guard);
+}
+
+export function setLabel(id: string, label: string | null): boolean {
+  const normalized = label && label.trim() ? label.trim() : null;
+  return (
+    getDb().query("UPDATE agents SET label = ? WHERE id = ?").run(normalized, id).changes > 0
+  );
+}
+
+export function setAgentTeam(agentId: string, teamId: string, now: number = Date.now()): AgentCard | null {
+  const result = getDb()
+    .query("UPDATE agents SET team_id = ?, last_seen = ? WHERE id = ?")
+    .run(teamId, now, agentId);
+  return result.changes > 0 ? getAgent(agentId) : null;
+}
+
+export function setTags(id: string, tags: string[], now: number = Date.now()): AgentCard | null {
+  const normalized = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+  const result = getDb().query("UPDATE agents SET tags = ?, last_seen = ? WHERE id = ?").run(JSON.stringify(normalized), now, id);
+  return result.changes > 0 ? getAgent(id) : null;
+}
+
+export function getAgent(id: string): AgentCard | null {
+  // #1468 — fold in any epoch-matched buffered beat so liveness/routing reads (isAgentOnline,
+  // resolveAgentRef, channel routing) never see a coalesced-but-live agent as gone.
+  const card = getPersistedAgentCard(id);
+  return card ? withBufferedPresence(card) : null;
+}
+
+export function listAgents(filter?: AgentCardFilter): AgentCard[] {
+  // #1468 — roster routing must include coalesced heartbeat advances.
+  return listPersistedAgentCards(filter).map(withBufferedPresence);
+}
+
+
+/**
+ * Raw (unbuffered) persisted rows for a parent's ready, non-terminal descendants — the reader-pool op
+ * body for `agents.spawnedChildren`. Deliberately does NOT fold `pendingPresence` (mirrors
+ * `agent-card-read.ts`'s split): a reader-pool worker has its own empty presence-buffer module
+ * instance, so folding here would silently make a coalesced-but-live child invisible to the
+ * caller (the same stale-read-on-async class the S3.1 L4 landmine warned about). Buffer folding
+ * belongs to the main-thread caller — see `countLiveSpawnedAgents` / `countLiveSpawnedAgentsAsync`.
+ */
+export function spawnedChildrenRows(parentId: string): AgentCard[] {
+  const rows = getDb().query(
+    // #2392 — roster columns only; a spawn-quota scan has no use for the cold launch projection.
+    `SELECT ${ROSTER_AGENT_COLUMNS} FROM agents WHERE spawned_by IN (SELECT value FROM json_each(?)) AND status NOT IN ('offline', 'stale') AND ready = 1`,
+  ).all(JSON.stringify(spawnTreeParentIds(parentId))) as any[];
+  return rows.map(rowToAgent);
+}
+
+export function countLiveSpawnedAgents(parentId: string, now: number = Date.now()): number {
+  // #1468 — buffer-aware liveness: load the (few) ready children and fold in any epoch-matched
+  // buffered beat before the recency test, so a coalesced-but-live child near the TTL boundary is
+  // not undercounted (which would wrongly free a spawn-quota slot).
+  const cutoff = now - STALE_TTL_MS;
+  return spawnedChildrenRows(parentId).map(withBufferedPresence).filter((agent) => agent.lastSeen > cutoff).length;
+}
+
+/**
+ * The bare `agents.setStatus` op body (S3 L10 #1895) — just the UPDATE, threaded on `now`. Handler
+ * firing (`beforeAgentStatusTransitionHandlers`, a main-thread-only module Set — registrations like
+ * `transient-agent-reaper.ts`'s never reach a writer-worker's own module instance) and the
+ * presence-buffer eviction stay OUT of the op body for the same reason the S3.1 L4 landmine did:
+ * calling them from a worker thread would silently no-op against empty worker-local state.
+ *
+ * `expectedEpoch` (review fix, #1895 cross-host review finding 2 — CONFIRMED HIGH): the sync
+ * `setStatus` reads `before` and writes back-to-back with no event-loop yield, so the row can never
+ * move out from under it. `setStatusAsync` has a REAL await gap between that read and this write
+ * landing, during which a fresh instance registration can bump the row's epoch (an instance
+ * takeover) — without a CAS guard, a stale connection's setStatus could then offline the SUCCESSOR
+ * it was supposed to be fenced from. When provided, the UPDATE only applies if the row's epoch still
+ * matches what the caller observed; a mismatch is a silent no-op (`changes = 0`), exactly like "agent
+ * not found" today. Always `undefined` for the sync path (no gap to fence against).
+ *
+ * `seq` (#2111 review BLOCKER 1) is the ORDERING fence `expectedEpoch` cannot be: the epoch only
+ * moves on an instance takeover, so it lets a same-instance write that the coalescing window deferred
+ * commit AFTER — and silently undo — a newer synchronous transition. See lifecycle-seq.ts.
+ */
+export function setStatusInternal(
+  id: string,
+  status: AgentCard["status"],
+  now: number,
+  expectedEpoch?: number,
+  seq: number = nextLifecycleSeq(),
+): LifecycleWriteOutcome {
+  const epochGuard = expectedEpoch !== undefined ? " AND epoch = ?" : "";
+  // `offline` also clears readiness, but through the READY fence rather than as part of this one:
+  // an independently newer markReady must survive, and losing that half must not make the status
+  // transition itself report superseded. `status` is this write's primary column.
+  const readySet = status === "offline" ? `, ${fencedColumnSql("ready", "0", "$seq")}` : "";
+  const sql = `UPDATE agents SET ${fencedColumnSql("status", "$status", "$seq")}${readySet}, last_seen = $now`
+    + ` WHERE id = $id${epochGuard.replace("?", "$epoch")} RETURNING status_seq AS seq`;
+  const params: Record<string, unknown> = { $status: status, $seq: seq, $now: now, $id: id };
+  if (expectedEpoch !== undefined) params.$epoch = expectedEpoch;
+  const row = getDb().query(sql).get(params as never) as { seq: number } | null;
+  return lifecycleWriteOutcome(row?.seq, seq);
+}
+
+export function setStatus(id: string, status: AgentCard["status"], guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const before = getAgent(id);
+  if (!before) return false;
+  if (before.status !== status) {
+    runBeforeAgentStatusTransitionHandlers(before, status);
+  }
+  // #1468 — a terminal transition (offline/stale) evicts any buffered beat, so a coalesced advance
+  // can't later resurrect a gone agent at flush. Covers busHandleClose / expireStaleBusAgents, which
+  // reach terminal via this one choke point.
+  if (status === "offline" || status === "stale") evictPendingPresence(id);
+  const now = Date.now();
+  // BEGIN IMMEDIATE (#1428/#1431), same pattern as the registration path above (#1549): this write
+  // is hit by every agent on a post-restart reconnect storm, so it needs busy_timeout to govern
+  // contention instead of an unwrapped statement risking SQLITE_BUSY under concurrent writers.
+  // #2111 — the ordinal is taken HERE, at the caller's intent, and inside the transaction the write
+  // applies only if no later-submitted lifecycle write already landed (see lifecycle-seq.ts).
+  const seq = nextLifecycleSeq();
+  const changed = writeTransaction(() => setStatusInternal(id, status, now, undefined, seq)) === "applied";
+  // NOTE: `offline` here is a LIVENESS observation (bus-grace expiry / heartbeat lapse — the process may
+  // still be alive after a relay stall or partition), NOT a confirmed death. So it re-elects stewards and
+  // closes pairs, but it must NOT release a steward's workspace claim (#1789 part 2, review F2): that
+  // fires only on a CONFIRMED process exit, in recordAgentExitDiagnostics below.
+  if (changed && status === "offline") { closeOpenPairsForAgent(id, now); electWorkspaceStewards(); }
+  return changed;
+}
+
+/**
+ * #2111 review BLOCKER 1 — readiness is fenced by `seq` for the same reason `setStatusInternal` is,
+ * and it needed it MORE: markReady's only guard was session identity, so a buffered `markReady(true)`
+ * committing after a synchronous `offline` (which clears `ready`) resurrected readiness on a dead
+ * agent. The ordinal makes the last SUBMITTED writer win regardless of who commits last.
+ */
+export function markReady(
+  id: string,
+  ready: boolean,
+  guard?: AgentSessionGuard,
+  now: number = Date.now(),
+  seq: number = nextLifecycleSeq(),
+): LifecycleWriteOutcome {
+  if (!validateAgentSession(id, guard).ok) return "missing";
+  const row = getDb()
+    .query(`UPDATE agents SET ${fencedColumnSql("ready", "$ready", "$seq")}, last_seen = $now`
+      + " WHERE id = $id RETURNING ready_seq AS seq")
+    .get({ $ready: ready ? 1 : 0, $seq: seq, $now: now, $id: id } as never) as { seq: number } | null;
+  return lifecycleWriteOutcome(row?.seq, seq);
+}
+
+/** One agent row's whole lifecycle delta for `applyAgentLifecycleUpdate`. Every field is optional;
+ *  only what is supplied reaches the SET list. */
+export interface AgentLifecycleUpdate {
+  status?: AgentCard["status"];
+  ready?: boolean;
+  /** Shallow-patched onto stored meta (authz keys stripped); null/undefined deletes a top-level key. */
+  meta?: Record<string, unknown>;
+  runtime?: { providerCapabilities?: ProviderCapabilities; context?: ContextState; quota?: QuotaState };
+  /** Apply `heartbeat()`'s offline/stale → idle resurrection CASE. Ignored when `status` is supplied
+   *  (an explicit status always wins, matching the old heartbeat()-then-setStatus() ordering). */
+  resurrectOnBeat?: boolean;
+}
+
+export interface AgentLifecycleUpdateResult {
+  /** The session guard passed AND the row exists. False maps to the callers' old "agent not found". */
+  ok: boolean;
+  /** The UPDATE touched a row — the boolean the superseded setStatus/markReady/mergeMeta returned. */
+  changed: boolean;
+  /** Bytes bound for the JSON meta update (zero when this lifecycle delta has no meta patch). */
+  metaWriteBytes: number;
+  before: AgentCard | null;
+  after: AgentCard | null;
+}
+
+/**
+ * #2111 — ONE read + ONE UPDATE + ONE transaction for a whole agent lifecycle delta.
+ *
+ * The hot bus seams used to spend a per-frame storm of on-loop DB work on a SINGLE row: the `status`
+ * frame ran `getAgent(before)` → `setStatus` (its own `validateAgentSession`+`getAgent`+`getAgent`, an
+ * UPDATE inside its own BEGIN IMMEDIATE) → `markReady` (another guard read + UPDATE) → `mergeAgentMeta`
+ * (two more reads + UPDATE) → `getAgent(after)`: ~7 row reads and 3 separate UPDATEs of the same row.
+ * `recordHeartbeat`'s presence-critical bypass did the same on a smaller scale (`heartbeat()` UPDATE
+ * then `setStatus()` UPDATE). Under a fleet reconnection storm that per-row multiplier is what
+ * saturated the loop (agents.setStatus 121 / agents.markReady 75 on-loop blocks in the bad window).
+ *
+ * This collapses the whole delta into one statement inside one transaction, so a storm costs one row
+ * write per event instead of three, and the guard/before/after reads are shared rather than repeated.
+ * Observable semantics are deliberately UNCHANGED — same guard rejection, same pre-transition handlers,
+ * same presence eviction, same offline post-commit (pair close + steward re-election), same
+ * `changed` boolean — so nothing here relaxes a terminal transition.
+ */
+export function applyAgentLifecycleUpdate(
+  id: string,
+  update: AgentLifecycleUpdate,
+  guard?: AgentSessionGuard,
+  now: number = Date.now(),
+): AgentLifecycleUpdateResult {
+  const miss: AgentLifecycleUpdateResult = { ok: false, changed: false, metaWriteBytes: 0, before: null, after: null };
+  const before = getPersistedAgentRuntimeCard(id);
+  if (!before) return miss;
+  if (!agentSessionGuardResult(before, guard).ok) return miss;
+
+  const nextStatus = update.status;
+  // Pre-transition handlers are main-thread-only state (see runBeforeAgentStatusTransitionHandlers)
+  // and must run BEFORE the write lands, exactly as `setStatus` does.
+  if (nextStatus !== undefined && nextStatus !== before.status) runBeforeAgentStatusTransitionHandlers(before, nextStatus);
+  // #1468 — a terminal transition evicts any buffered beat so a coalesced advance cannot later
+  // resurrect a gone agent at flush.
+  if (nextStatus === "offline" || nextStatus === "stale") evictPendingPresence(id);
+
+  // #2111 review BLOCKER 1 — raise each written column's ordinal so a lifecycle write the coalescing
+  // window deferred cannot commit afterwards and undo it. This path only ever WINS its own races (it
+  // commits synchronously, and any submission carrying a higher ordinal has not been allocated yet),
+  // but it is fenced anyway so every writer of these columns obeys one rule.
+  const seq = nextLifecycleSeq();
+  // Named params throughout: the fenced-column fragments repeat `$seq`, which positional `?` could
+  // only express by counting placeholders across a dynamically-built SET list.
+  const sets: string[] = ["last_seen = $now"];
+  const params: Record<string, unknown> = { $now: now, $seq: seq, $id: id };
+  let metaWriteBytes = 0;
+  if (nextStatus !== undefined) {
+    sets.push(fencedColumnSql("status", "$status", "$seq"));
+    params.$status = nextStatus;
+  } else if (update.resurrectOnBeat) {
+    // A beat that does not actually resurrect makes no status claim, so `when` keeps it from raising
+    // the fence — otherwise it would suppress an earlier-submitted, later-flushed real transition.
+    sets.push(fencedColumnSql("status", "'idle'", "$seq", { when: "status IN ('offline', 'stale')" }));
+  }
+  // An explicit `ready` wins over the offline-forced clear, preserving the old setStatus-then-markReady
+  // ordering (setStatus zeroed `ready` on offline; a following markReady overwrote it).
+  if (update.ready !== undefined) {
+    sets.push(fencedColumnSql("ready", "$ready", "$seq"));
+    params.$ready = update.ready ? 1 : 0;
+  } else if (nextStatus === "offline") {
+    sets.push(fencedColumnSql("ready", "0", "$seq"));
+  }
+  if (update.meta) {
+    // #2367 — bind only the incoming top-level patch. Removing its keys before json_patch preserves
+    // the old SHALLOW replacement contract for nested objects; null (and local undefined) deletes a
+    // key, which lets one-shot runner markers be consumed instead of latching forever. The static
+    // launch projection is split into its cold column and never rides this hot write.
+    const patch = splitAgentMetaPatchForStorage(withoutAuthzMetaKeys(update.meta));
+    const metaJson = JSON.stringify(patch.meta);
+    let base = "meta";
+    const keys = Object.keys(patch.meta);
+    metaWriteBytes = keys.length ? jsonBytes(metaJson) : 0;
+    if (keys.length) warnIfAgentMetaOversized(id, metaJson, "status meta patch");
+    for (let offset = 0; offset < keys.length; offset += 50) {
+      const pathParams = keys.slice(offset, offset + 50).map((key, index) => {
+        const name = `$metaPath${offset + index}`;
+        params[name] = topLevelJsonPath(key);
+        return name;
+      });
+      base = `json_remove(${base}, ${pathParams.join(", ")})`;
+    }
+    if (keys.length) {
+      sets.push(`meta = json_patch(${base}, $meta)`);
+      params.$meta = metaJson;
+    }
+    if (patch.profileProjectionProvided) {
+      sets.push("profile_projection = $profileProjection");
+      params.$profileProjection = patch.profileProjection == null ? null : JSON.stringify(patch.profileProjection);
+    }
+  }
+  const runtime = update.runtime;
+  const hasRuntime = Boolean(runtime?.providerCapabilities || runtime?.context || runtime?.quota);
+  const contextState = hasRuntime ? mergeRelayContextMarkers(id, runtime?.context) : undefined;
+  if (hasRuntime) {
+    sets.push("provider_capabilities = coalesce($pc, provider_capabilities)");
+    params.$pc = runtime?.providerCapabilities ? JSON.stringify(runtime.providerCapabilities) : null;
+    sets.push("context_state = coalesce($cx, context_state)");
+    params.$cx = contextState ? JSON.stringify(contextState) : null;
+    sets.push("quota_state = coalesce($qs, quota_state)");
+    params.$qs = runtime?.quota ? JSON.stringify(runtime.quota) : null;
+  }
+
+  // BEGIN IMMEDIATE (#1428/#1431) so busy_timeout governs contention, joining an ambient writer-op
+  // transaction rather than nesting when this body is reached through the gateway.
+  const changed = inWriteTransaction(() => {
+    const applied = getDb().query(`UPDATE agents SET ${sets.join(", ")} WHERE id = $id`).run(params as never).changes > 0;
+    const terminalLaunch = terminalProviderLaunchId(update.meta?.terminalProviderExit ?? before.meta?.terminalProviderExit);
+    if (applied && nextStatus === "offline" && terminalLaunch) revokeVaultTokens(id, now, "provider_terminal_exit", before.instanceId, String(before.meta?.spawnRequestId ?? ""), terminalLaunch);
+    if (applied && contextState) recordContextSnapshot(id, contextState, now);
+    return applied;
+  });
+
+  // NOTE (from setStatus): `offline` is a LIVENESS observation, not a confirmed death — it re-elects
+  // stewards and closes pairs but must NOT release a steward's workspace claim (#1789 part 2, F2).
+  // Gated on the requested status, not on a status CHANGE, matching setStatus's own condition.
+  if (changed && nextStatus === "offline") {
+    closeOpenPairsForAgent(id, now);
+    electWorkspaceStewards();
+  }
+  return { ok: true, changed, metaWriteBytes, before, after: getPersistedAgentRuntimeCard(id) };
+}
+
+export function mergeAgentMeta(id: string, meta: Record<string, unknown>, guard?: AgentSessionGuard, now: number = Date.now()): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  const agent = getAgent(id);
+  if (!agent) return false;
+  // #1797 (N1) — THE SECOND caller-controlled meta ingress. `bus.ts` merges an agent-supplied blob
+  // from a `status` frame straight through here, so this path bypassed the registration sanitizer
+  // completely: an agent with a bus socket could stamp another agent's `spawnRequestId` on its own
+  // row and inherit that Task's read + DISPATCH authority (`agentBoundTaskIds` in task-authz.ts;
+  // dispatch is spawn-class), and claim an unowned Task on its next ready flip. `policyName` /
+  // `spawnRequestId` are authorization ADDRESSING established once at registration from the signed
+  // grant — no relay-internal caller of this function writes either — so refuse them outright here
+  // and let the invariant hold on BOTH ingresses. See authz-meta-keys.ts.
+  // #1456 round-10 — canonicalize spawnRequestId here too, so a value already on the row (written by
+  // registration, from signed constraints) stays canonical through an unrelated merge.
+  const merged = withCanonicalSpawnRequestId({ ...(agent.meta ?? {}), ...withoutAuthzMetaKeys(meta) });
+  const stored = splitAgentMetaForStorage(merged);
+  const metaJson = JSON.stringify(stored.meta);
+  warnIfAgentMetaOversized(id, metaJson, "stored meta");
+  const result = getDb()
+    .query("UPDATE agents SET meta = ?, profile_projection = ?, last_seen = ? WHERE id = ?")
+    .run(metaJson, stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), now, id);
+  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 };
+  const stored = splitAgentMetaForStorage(merged);
+  return getDb().query("UPDATE agents SET meta = ?, profile_projection = ? WHERE id = ?")
+    .run(JSON.stringify(stored.meta), stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), 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;
+  const stored = splitAgentMetaForStorage(meta);
+  return getDb().query("UPDATE agents SET meta = ?, profile_projection = ? WHERE id = ?")
+    .run(JSON.stringify(stored.meta), stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection), id).changes > 0;
+}
+
+/**
+ * #1059 — decide whether a process-exit certificate belongs to an agent row's CURRENT
+ * instance. A late/duplicate orchestrator exit report for a SUPERSEDED session (the agent id
+ * re-registered as a fresh instance after the report was generated) carries the prior session's
+ * `spawnRequestId`; the live successor's meta carries the new one. When both are known and
+ * differ, the certificate is for a dead predecessor and must never mark the successor gone.
+ * Unknown on either side (legacy / unmanaged sessions that never carried a spawnRequestId) can't
+ * be disproven, so it is treated as matching — preserving the pre-#1059 fast-exit path.
+ *
+ * The single home for the death-certificate/instance identity check, shared by the stamp site
+ * (recordAgentExitDiagnostics, below) and the reaper's death predicate (isOwnerProcessConfirmedGone
+ * in workspace-merge.ts) so the two can't drift.
+ */
+export function exitCertificateMatchesInstance(
+  currentMeta: Record<string, unknown> | undefined,
+  certificate: { spawnRequestId?: unknown } | undefined,
+): boolean {
+  const current = currentMeta ? stringValue(currentMeta.spawnRequestId) : undefined;
+  const cert = certificate ? stringValue(certificate.spawnRequestId) : undefined;
+  if (current && cert && current !== cert) return false;
+  return true;
+}
+
+/**
+ * The `agents.recordExitDiagnostics` op body (S3 L10 #1895): agent lookup + cert-match check + the
+ * merged-meta UPDATE, folded into one unit (the read decides whether the write applies at all, so
+ * splitting it across a real thread hop would reopen the #1059 TOCTOU the pre-migration code closed
+ * by keeping them in one synchronous call). Returns the EPOCH the exit write stamped (or `null` when
+ * no row changed), so the async facade's separate post-commit cleanup jobs can fence on the exact
+ * instance identity this write validated — a same-id replacement that registers in the await gap
+ * bumps the epoch and its pairs/claims must never be clobbered (#1869 W0.2 race fix). The cross-domain
+ * post-write side effects (pair/steward cleanup, presence eviction) stay in the orchestration below —
+ * `evictPendingPresence` in particular MUST run main-thread (see `setStatusInternal`'s note).
+ */
+export function recordAgentExitDiagnosticsInternal(
+  id: string,
+  diagnostics: ManagedSessionExitDiagnostics,
+  now: number,
+  /** #2111 — taken on the MAIN thread at submission, for the same cross-thread reason as
+   *  `upsertAgentInternal`'s. */
+  lifecycleSeq: number,
+): number | null {
+  recordSpawnProcessExit(id, stringValue(diagnostics.spawnRequestId), now);
+  const agent = getAgent(id);
+  if (!agent) return null;
+  // #1059 — drop a stale/duplicate exit report for a SUPERSEDED instance. The agent id
+  // re-registered as a fresh session (new spawnRequestId) after this report was generated;
+  // stamping its predecessor's certificate here would poison the LIVE successor's row (false
+  // offline flip + false death notification via the caller + a certificate the dead-owner reaper
+  // would later act on — the #1054 reopener). Returning false makes the caller skip both the status
+  // emit and notifyAgentOffline, exactly as for an absent row.
+  if (!exitCertificateMatchesInstance(isRecord(agent.meta) ? agent.meta : undefined, diagnostics)) return null;
+  revokeVaultTokens(id, now, "confirmed_exit", agent.instanceId, String(agent.meta?.spawnRequestId ?? ""));
+  const merged: Record<string, unknown> = {
+    ...(agent.meta ?? {}),
+    lastError: diagnostics.lastError,
+    lastExit: diagnostics,
+    lastExitAt: diagnostics.detectedAt || now,
+    // #1057(1) — RELAY-clock receipt of the process-confirmed death. The orphan-token sweep
+    // (revokeOrphanedRuntimeTokens) compares this against last_seen (also relay clock); the
+    // orchestrator-clock detectedAt in lastExitAt is not comparable across hosts.
+    lastExitReceivedAt: now,
+  };
+  // #1746 RC-2 — a process-confirmed exit is terminal: drop any in-flight lifecycle pill
+  // (shutting-down / killing / kill-failed / restarting) so relay_my_agents and the dashboard don't
+  // show a dead agent stuck "shutting down" forever. The MCP surface now checks offline first too, but
+  // clearing the underlying meta keeps every consumer of agent.meta in agreement.
+  delete merged.lifecycleAction;
+  delete merged.lifecycleActionAt;
+  delete merged.lifecycleCommandId;
+  // #1746 fwd BLOCKER — also drop the watchdog's one-shot escalation marker on the confirmed exit, so
+  // a re-registered/reused agent row starts its next shutdown with a fresh shot instead of inheriting a
+  // stale stamp that would fast-path it to kill-failed.
+  delete merged.shutdownWatchdogEscalatedAt;
+  delete merged.lifecycleShutdownTimeoutMs;
+  const stored = splitAgentMetaForStorage(merged);
+  // #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.
+  // #2111 review BLOCKER 1 — this is the CONFIRMED-death certificate, the transition that must never
+  // be undone. Advancing the lifecycle fence here is what stops a `setStatus`/`markReady` still
+  // sitting in the coalescing window from committing afterwards and reviving the dead row.
+  const result = getDb()
+    .query(`UPDATE agents SET ${fencedColumnSql("status", "'offline'", "$seq")}, ${fencedColumnSql("ready", "0", "$seq")}`
+      + ", meta = $meta, profile_projection = $profileProjection WHERE id = $id")
+    .run({
+      $seq: lifecycleSeq,
+      $meta: JSON.stringify(stored.meta),
+      $profileProjection: stored.profileProjection == null ? null : JSON.stringify(stored.profileProjection),
+      $id: id,
+    } as never);
+  return result.changes > 0 ? agent.epoch : null;
+}
+
+export function recordAgentExitDiagnostics(id: string, diagnostics: ManagedSessionExitDiagnostics, now: number = Date.now()): AgentCard | null {
+  const lifecycleSeq = nextLifecycleSeq();
+  const stampedEpoch = writeTransaction(() => recordAgentExitDiagnosticsInternal(id, diagnostics, now, lifecycleSeq));
+  // Sync path has no event-loop yield between this write and the cleanup below, so no replacement can
+  // interleave — the epoch is threaded only for the async facade's fencing (#1869 W0.2). `=== null` not
+  // truthiness: epoch 0 is a valid instance (instance-less agents), see setStatusInternal.
+  if (stampedEpoch === null) return null;
+  // #1468 — this terminal write bypasses setStatus, so evict any buffered beat here too.
+  evictPendingPresence(id);
+  // #1789 part 2 (review F2) — THIS is the confirmed process-exit certificate (matched to the current
+  // instance above, so a superseded/re-registered id's stale report can never fire it). Release the
+  // gone steward's workspace claim here — not on setStatus(offline) — so a live-but-partitioned steward
+  // mid-land keeps its lease while a genuinely-dead one's stale lease no longer wedges its replacement.
+  closeOpenPairsForAgent(id, now); releaseWorkspaceClaimsForAgent(id, now);
+  return getAgent(id);
+}
+
+/**
+ * `seq` (#2111 review BLOCKER 1) fences the RESURRECTION CASE below. A beat that the coalescing window
+ * deferred would otherwise flip an `offline`/`stale` row back to `idle` after a newer synchronous
+ * transition put it there — the orchestrator-heartbeat variant of the lost-terminal-transition bug.
+ * Only the deferred caller (`orchestrators.heartbeat`) passes one; the immediate paths leave it
+ * undefined and the write behaves exactly as before, since a beat that is not deferred cannot lose an
+ * ordering race it never entered.
+ */
+export function heartbeat(
+  id: string,
+  guard?: AgentSessionGuard,
+  runtime?: { providerCapabilities?: ProviderCapabilities; context?: ContextState; quota?: QuotaState },
+  now: number = Date.now(),
+  seq?: number,
+): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
+  // The resurrection is the only lifecycle CLAIM a beat makes, so that is all the fence covers: with
+  // `seq` supplied it flips offline/stale → idle only while no later-submitted status write has landed,
+  // and raises `status_seq` ONLY in that case (a beat that resurrects nothing must not consume an
+  // ordinal other writers are ordered against). Without `seq` the write is exactly as it was — a beat
+  // that is not deferred cannot lose an ordering race it never entered.
+  const RESURRECT_WHEN = "status IN ('offline', 'stale')";
+  const statusSet = seq !== undefined
+    ? fencedColumnSql("status", "'idle'", "$seq", { when: RESURRECT_WHEN })
+    : `status = CASE WHEN ${RESURRECT_WHEN} THEN 'idle' ELSE status END`;
+  if (runtime?.providerCapabilities || runtime?.context || runtime?.quota) {
+    const contextState = mergeRelayContextMarkers(id, runtime.context);
+    const params: Record<string, unknown> = {
+      $now: now,
+      $pc: runtime.providerCapabilities ? JSON.stringify(runtime.providerCapabilities) : null,
+      $cx: contextState ? JSON.stringify(contextState) : null,
+      $qs: runtime.quota ? JSON.stringify(runtime.quota) : null,
+      $id: id,
+    };
+    if (seq !== undefined) params.$seq = seq;
+    const result = getDb()
+      .query(`
+        UPDATE agents SET
+          last_seen = $now,
+          ${statusSet},
+          provider_capabilities = coalesce($pc, provider_capabilities),
+          context_state = coalesce($cx, context_state),
+          quota_state = coalesce($qs, quota_state)
+        WHERE id = $id
+      `)
+      .run(params as never);
+    if (result.changes > 0 && contextState) recordContextSnapshot(id, contextState, now);
+    return result.changes > 0;
+  }
+  const params: Record<string, unknown> = { $now: now, $id: id };
+  if (seq !== undefined) params.$seq = seq;
+  const result = getDb()
+    .query(`UPDATE agents SET last_seen = $now, ${statusSet} WHERE id = $id`)
+    .run(params as never);
+  return result.changes > 0;
+}
+
+// #1468 — heartbeat presence write-coalescing buffer.
+//
+// PROBLEM: the SDK sends a heartbeat every ~30s per agent (bus.ts) carrying `status` (always) and
+// usually `context`/`providerCapabilities`. The bus path used to persist that with TWO synchronous
+// row writes per beat — `heartbeat()` (last_seen + runtime cols) AND `setStatus()` (which rewrites
+// the row even when status is unchanged). bun:sqlite is synchronous, so at fleet scale on the 2012
+// macmini2 that scattered write frequency is the top CONSTANT event-loop-lag source.
+//
+// FIX: hold each agent's latest presence in memory and persist the whole DIRTY set in ONE batched
+// `UPDATE ... FROM json_each` per flush (PRESENCE_FLUSH_MS, default 5s) — N scattered writes/period
+// collapse to a single statement. `recordHeartbeat` is the entry point for the hot bus/API heartbeat
+// paths; it BYPASSES the buffer and writes synchronously only for presence-critical transitions
+// (status change — e.g. busy→idle for #1465/#1466 — and offline/stale resurrection), so a genuinely
+// changed presence still flips promptly. Steady-state no-change beats are coalesced.
+//
+// SAFETY: `last_seen` advances monotonically on flush (MAX), so the #1465 transportLiveAt floor and
+// the isLive/routing reads never regress; the persisted value is at most PRESENCE_FLUSH_MS stale,
+// 24× under the 120s STALE_TTL. The stale reaper flushes the buffer synchronously first
+// (`reapStaleAgents`), so a coalesced-but-live agent is never mis-reaped. A crash loses ≤ one flush
+// interval of last_seen advance — harmless (the agent looks ≤5s staler, still ≪ 120s).
+// PendingPresence, the buffer Map, and the read-side accessors (evictPendingPresence /
+// withBufferedPresence / bufferedLiveAgentIds) live in the leaf module ./presence-buffer.ts so every
+// liveness reader can fold in the buffer without an import cycle (agents.ts imports channels.ts).
+
+/**
+ * Hot-path heartbeat entry point for the bus/API transports. Coalesces the steady-state liveness
+ * advance into the in-memory buffer (flushed by `flushPresence`), but writes synchronously for
+ * presence-critical transitions. Returns false if the session guard rejects or the agent is gone.
+ */
+export function recordHeartbeat(
+  id: string,
+  opts: {
+    guard?: AgentSessionGuard;
+    /** Semantic status reported by the beat (bus path); undefined for the runtime-less API path. */
+    status?: AgentCard["status"];
+    runtime?: { providerCapabilities?: ProviderCapabilities; context?: ContextState; quota?: QuotaState };
+    now?: number;
+  } = {},
+): boolean {
+  if (!validateAgentSession(id, opts.guard).ok) return false;
+  const current = getAgent(id);
+  if (!current) return false;
+  const now = opts.now ?? Date.now();
+
+  // Presence-critical transitions must persist NOW, not at the next flush: a status change
+  // (busy→idle etc. — the #1465/#1466 surface) and a resurrection of an offline/stale row both
+  // flip liveness/availability that downstream readers and message-flush logic act on immediately.
+  // A context lifecycleState transition is equally critical — isAgentUnavailable() (message-queue
+  // gating, #416) keys off lifecycleState (compacting / clearing-context) — so a CHANGE in it also
+  // bypasses the buffer; only benign same-lifecycle utilization drift is coalesced.
+  const resurrection = current.status === "offline" || current.status === "stale";
+  const statusChanged = opts.status !== undefined && opts.status !== current.status;
+  const lifecycleTransition =
+    opts.runtime?.context !== undefined &&
+    opts.runtime.context.lifecycleState !== current.context?.lifecycleState;
+  const prev = pendingPresence.get(id);
+  if (resurrection || statusChanged || lifecycleTransition) {
+    // Merge any buffered-but-unflushed runtime cols into this synchronous write so the bypass never
+    // DISCARDS a coalesced advance (a beat that carried context but was buffered, then a status
+    // change arrives carrying none). Per column: this beat wins, else the pending value.
+    const runtime = prev
+      ? {
+          providerCapabilities: opts.runtime?.providerCapabilities ?? prev.providerCapabilities,
+          context: opts.runtime?.context ?? prev.context,
+          quota: opts.runtime?.quota ?? prev.quota,
+        }
+      : opts.runtime;
+    pendingPresence.delete(id); // this synchronous write supersedes any buffered advance
+    // #2111 — was `heartbeat()` (one UPDATE) followed by `setStatus()` (a second UPDATE of the SAME
+    // row inside its own BEGIN IMMEDIATE). One consolidated update now carries both; the explicit
+    // status overrides the resurrection CASE exactly as the second write used to.
+    return applyAgentLifecycleUpdate(
+      id,
+      { status: statusChanged ? opts.status : undefined, resurrectOnBeat: true, runtime },
+      opts.guard,
+      now,
+    ).changed;
+  }
+
+  // Steady state: buffer. Merge context advisory markers now (matches heartbeat()'s per-beat merge),
+  // carrying forward the freshest of {this beat, an earlier un-flushed beat} for each column. The
+  // entry is epoch-bound so a flush can't apply it to a successor instance after a takeover.
+  const merged = opts.runtime?.context ? mergeRelayContextMarkers(id, opts.runtime.context) : undefined;
+  pendingPresence.set(id, {
+    epoch: current.epoch,
+    lastSeen: Math.max(now, prev?.lastSeen ?? current.lastSeen),
+    providerCapabilities: opts.runtime?.providerCapabilities ?? prev?.providerCapabilities,
+    context: merged ?? prev?.context,
+    quota: opts.runtime?.quota ?? prev?.quota,
+  });
+  return true;
+}
+
+/**
+ * Persist every buffered heartbeat in ONE batched statement (the #1468 win: N scattered per-agent
+ * writes/period → a single UPDATE). `last_seen` advances via MAX (monotonic — never regresses a
+ * concurrent fresher write); the resurrection CASE mirrors `heartbeat()` as a backstop; runtime
+ * columns COALESCE so an absent value keeps the stored one. Context snapshots are recorded (with
+ * their existing 60s debounce) only for agents the UPDATE actually touched, so a row pruned between
+ * buffering and flush can't trip the context_snapshots FK. Called on the flush loop, before the
+ * stale reaper, and on shutdown.
+ */
+/**
+ * Writer-op body for `presence.flush`. The executor already owns the transaction/savepoint, so this
+ * deliberately does not call writeTransaction. `now` was captured at gateway submission (H6).
+ */
+export function flushPresencePayloadInternal(payload: PresenceFlushPayload, now: number): string[] {
+  if (payload.length === 0) return [];
+  // NEVER resurrect: the flush leaves `status` untouched and only touches rows that are still live
+  // and still on the buffered beat's epoch. A row that went offline/stale (BLOCKER) or was taken
+  // over by a new instance (HIGH) after the beat was buffered is skipped — no reanimation, no
+  // predecessor-instance clobber. A genuinely live beat that needs resurrection took the synchronous
+  // bypass in recordHeartbeat, so the flush never has to flip status.
+  const updated = getDb()
+      .query(`
+        UPDATE agents AS a SET
+          last_seen = MAX(a.last_seen, CAST(j.value ->> 'ls' AS INTEGER)),
+          provider_capabilities = COALESCE(j.value ->> 'pc', a.provider_capabilities),
+          context_state = COALESCE(j.value ->> 'cx', a.context_state),
+          quota_state = COALESCE(j.value ->> 'qs', a.quota_state)
+        FROM json_each(?) AS j
+        WHERE a.id = j.value ->> 'id'
+          AND a.epoch = CAST(j.value ->> 'ep' AS INTEGER)
+          AND a.status NOT IN ('offline', 'stale')
+        RETURNING id
+      `)
+      .all(JSON.stringify(payload)) as Array<{ id: string }>;
+  const updatedIds = new Set(updated.map((row) => row.id));
+  for (const row of payload) {
+    const p = row.cx ? JSON.parse(row.cx) as ContextState : undefined;
+    if (p && updatedIds.has(row.id)) recordContextSnapshot(row.id, p, now);
+  }
+  return [...updatedIds];
+}
+
+/** Synchronous compatibility path for stale reaping and process teardown. Normal timer ticks use
+ * `flushPresenceAsync` from presence-write.ts, which routes this same body through the writer gateway. */
+export function flushPresence(now: number = Date.now()): { flushed: number } {
+  const flush = snapshotPendingPresenceFlush();
+  if (!flush) return { flushed: 0 };
+  const ids = writeTransaction(() => flushPresencePayloadInternal(flush.payload, now));
+  // Clear only after commit. `settle` is identity-aware so a future async caller cannot erase a beat
+  // that arrived while its earlier snapshot was in flight.
+  settlePendingPresenceFlush(flush);
+  return { flushed: ids.length };
+}
+
+export function listContextSnapshots(agentId: string, options: { since?: number; limit?: number } = {}): ContextSnapshot[] {
+  const limit = Math.max(1, Math.min(options.limit ?? 288, 1000));
+  const params: any[] = [agentId];
+  let sql = "SELECT * FROM context_snapshots WHERE agent_id = ?";
+  if (options.since !== undefined) {
+    sql += " AND captured_at >= ?";
+    params.push(options.since);
+  }
+  sql += " ORDER BY captured_at ASC, id ASC LIMIT ?";
+  params.push(limit);
+  return (getDb().query(sql).all(...params) as any[]).map(rowToContextSnapshot);
+}
+
+export function listQuotaSnapshots(agentId: string, options: { since?: number; limit?: number } = {}): QuotaSnapshot[] {
+  const agent = getAgent(agentId);
+  if (!agent) return [];
+  return listAgentQuotaSnapshotsFromProviderStore(agent, options);
+}
+
+/** Debounced snapshot insert; retention runs separately in snapshot-ledger-prune. */
+export function recordContextSnapshot(agentId: string, context: ContextState, now: number): void {
+  const latest = getDb()
+    .query("SELECT captured_at FROM context_snapshots WHERE agent_id = ? ORDER BY captured_at DESC LIMIT 1")
+    .get(agentId) as { captured_at: number } | undefined;
+  if (latest && latest.captured_at > now - CONTEXT_SNAPSHOT_DEBOUNCE_MS) return;
+
+  getDb().query(`
+    INSERT INTO context_snapshots (
+      agent_id,
+      utilization,
+      lifecycle_state,
+      tokens_used,
+      tokens_max,
+      source,
+      confidence,
+      context_state,
+      captured_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    agentId,
+    context.utilization,
+    context.lifecycleState,
+    context.tokensUsed ?? null,
+    context.tokensMax ?? null,
+    context.source,
+    context.confidence,
+    JSON.stringify(context),
+    now,
+  );
+}
+
+function mergeRelayContextMarkers(agentId: string, next: ContextState | undefined): ContextState | undefined {
+  if (!next) return undefined;
+  const row = getDb().query("SELECT context_state FROM agents WHERE id = ?").get(agentId) as { context_state?: string | null } | undefined;
+  const previous = row?.context_state ? parseJson<ContextState | undefined>(row.context_state, undefined) : undefined;
+  if (!previous) return next;
+  return {
+    ...next,
+    lastContextAdvisoryBand: next.lastContextAdvisoryBand ?? previous.lastContextAdvisoryBand,
+    lastContextAdvisoryAt: next.lastContextAdvisoryAt ?? previous.lastContextAdvisoryAt,
+  };
+}
+
+
+/**
+ * The `agents.reapStale` op body (S3 L10 #1895): the stale-marking sweep only — deliberately
+ * EXCLUDES the `flushPresence` pre-flush (see `reapStaleAgents`), which reads the main-thread-only
+ * `pendingPresence` buffer and would silently no-op on a writer-worker thread (the exact
+ * stale-read-on-async class the S3.1 L4 landmine warned about; caught during this migration).
+ *
+ * `protectedIds` (review fix, finding 1 — CONFIRMED HIGH): ids the ASYNC caller observed with a
+ * still-fresh buffered beat at submission time — see `reapStaleAgentsAsync`'s doc comment for the
+ * race this closes. Always `[]` for the sync `reapStaleAgents` path (no gap to close there).
+ */
+export function reapStaleAgentsInternal(
+  ttlMs: number,
+  lagGraceMs: number,
+  now: number,
+  protectedIds: string[] = [],
+  /** #2111 round-3 review — the ordering fence. This is a TERMINAL transition, so a lifecycle write
+   *  still sitting in the coalescing window (submitted before this sweep) must not commit afterwards
+   *  and revive a reaped agent. Allocated at the caller's synchronous submission point. */
+  seq: number = nextLifecycleSeq(),
+): string[] {
+  // #1048 — extend the stale cutoff by the relay's own recently-observed event-loop
+  // lag. A missed heartbeat while THIS process was stalled means "the relay couldn't
+  // read it", not "the agent died"; the caller passes the grace in (this module stays
+  // health-agnostic). lagGraceMs of 0 is the pre-#1048 behavior.
+  const cutoff = now - ttlMs - Math.max(0, lagGraceMs);
+  getDb().query(`UPDATE agents SET last_seen = ? WHERE ${reservedAgentIdSql()}`).run(now);
+  const guard = protectedIds.length > 0
+    ? ` AND id NOT IN (${protectedIds.map((_, i) => `$p${i}`).join(",")})`
+    : "";
+  const params: Record<string, unknown> = { $seq: seq, $cutoff: cutoff };
+  protectedIds.forEach((protectedId, i) => { params[`$p${i}`] = protectedId; });
+  // The status fence is a WHERE clause rather than a CASE because this sweep RETURNS the rows it
+  // reaped: a row a later-submitted write already claimed must not be reaped at all, and must not be
+  // announced as stale. `ready` is fenced separately (an independently newer markReady survives).
+  const rows = getDb()
+    .query(
+      `UPDATE agents SET status = 'stale', status_seq = $seq, ${fencedColumnSql("ready", "0", "$seq")}`
+        + ` WHERE status NOT IN ('offline', 'stale') AND last_seen < $cutoff AND NOT ${reservedAgentIdSql()}`
+        + ` AND status_seq < $seq${guard} RETURNING id`,
+    )
+    .all(params as never) as any[];
+  for (const row of rows) {
+    // #1051 — liveness ≠ credential validity. A lapsed heartbeat is a transient,
+    // recoverable observation (the relay may have stalled, or the network blipped);
+    // it marks status only and must NOT void a still-unexpired token. On reconnect the
+    // relay accepts the agent's EXISTING token and re-marks it live. The #484 restart-
+    // strand invariant (an orphaned prior-instance token must not stay usable) is now
+    // enforced on instance takeover instead — see revokeSupersededRuntimeTokens, fired
+    // from registerAgent when a fresh process re-registers under a new instanceId.
+    closeOpenPairsForAgent(row.id, now);
+  }
+  return rows.map((r: any) => r.id);
+}
+
+export function reapStaleAgents(ttlMs: number = STALE_TTL_MS, lagGraceMs = 0): string[] {
+  const now = Date.now();
+  // #1468 — persist buffered heartbeats BEFORE evaluating staleness, so a live agent whose
+  // last_seen advance was only coalesced in memory is never mis-reaped as stale. This is the one
+  // read path that needs a synchronous flush-before; the isLive/routing reads tolerate a ≤5s-stale
+  // persisted value (far under the 120s TTL) and stay lock-free.
+  flushPresence(now);
+  const seq = nextLifecycleSeq();
+  return writeTransaction(() => reapStaleAgentsInternal(ttlMs, lagGraceMs, now, [], seq));
+}
+
+export { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
+
+/**
+ * The `agents.pruneOffline` op body (S3 L10 #1895): everything the pre-migration `writeTransaction`
+ * closure did, MINUS `evictPendingPresence` (main-thread-only buffer, see `setStatusInternal`) and
+ * the `beforeDelete` callback (a JS closure — not structured-clone-safe across a real thread hop, so
+ * it cannot ride in op args; see `pruneOfflineAgents`). `revokeRuntimeTokensForAgent` /
+ * `closeOpenPairsForAgent` / `removeSubscriptionsForAgent` / `settleSingleTargetOnDemandTasks` are
+ * plain `getDb()`-based helpers with no main-thread state, so they run correctly on any thread.
+ */
+export function pruneOfflineAgentsInternal(cutoff: number, now: number, beforeDelete?: (agentId: string) => void): string[] {
+  const rows = getDb()
+    .query(
+      `SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND NOT ${reservedAgentIdSql()}`
+    )
+    .all(cutoff) as any[];
+  if (rows.length === 0) return [];
+
+  // Release claims held by pruned agents so unfinished work becomes claimable again — but
+  // never for a message whose task is already closed: nulling that claim resurrects completed
+  // work on the next restart (the task release below is already guarded the same way).
+  getDb()
+    .query(
+      `UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND NOT ${reservedAgentIdSql()}) AND NOT ${messageTaskClosed("messages.id")}`
+    )
+    .run(cutoff);
+
+  const offlineClaimCondition = `claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND NOT ${reservedAgentIdSql()})`;
+  settleSingleTargetOnDemandTasks(offlineClaimCondition, [cutoff], now, "agent-pruned");
+
+  getDb()
+    .query(
+      `UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE ${claimTaskWhere()} AND ${offlineClaimCondition} AND status IN ('claimed', 'in_progress', 'blocked')`
+    )
+    .run(now, cutoff);
+
+  for (const row of rows) {
+    // Offline past the prune horizon and being deleted — a hard kill, not recoverable.
+    beforeDelete?.(row.id);
+    revokeRuntimeTokensForAgent(row.id, now, "pruned");
+    closeOpenPairsForAgent(row.id, now);
+    removeSubscriptionsForAgent(row.id);
+    clearAgentNotices(row.id);
+  }
+
+  getDb()
+    .query(
+      `DELETE FROM agents WHERE status = 'offline' AND last_seen < ? AND NOT ${reservedAgentIdSql()}`
+    )
+    .run(cutoff);
+
+  return rows.map((r: any) => r.id);
+}
+
+export function pruneOfflineAgents(
+  maxOfflineMs: number = DAY_MS,
+  opts?: {
+    /**
+     * #1084 crash-final-loss fix-forward — defense-in-depth for a held work-final ring that
+     * somehow survived to prune time (the primary flush is `notifyAgentOffline`, fired when the
+     * agent first goes offline). Called per pruned agent id BEFORE its row is deleted, so a
+     * caller can flush any still-held final report while `getAgent(id)` can still resolve it —
+     * kept a plain callback (not a direct import) so this db-layer module stays free of
+     * service/SSE-layer dependencies.
+     */
+    beforeDelete?: (agentId: string) => void;
+  },
+): string[] {
+  const cutoff = Date.now() - maxOfflineMs;
+  // Lock-free candidate pre-check (#1432 review R2 — the releaseExpiredClaims pattern). This offline
+  // reaper runs periodically and almost always has nothing to prune. Entering BEGIN IMMEDIATE
+  // unconditionally would make that no-op path BLOCK on busy_timeout (~1s stall, then throw) whenever an
+  // unrelated writer holds the lock — strictly worse than the old deferred read's ~0ms. This EXISTS is a
+  // plain deferred read that takes NO write lock; only a real candidate pays for BEGIN IMMEDIATE below,
+  // which re-reads under the lock (TOCTOU-safe).
+  const hasCandidate = getDb()
+    .query(`SELECT EXISTS(SELECT 1 FROM agents WHERE status = 'offline' AND last_seen < ? AND NOT ${reservedAgentIdSql()}) AS n`)
+    .get(cutoff) as { n: number };
+  if (!hasCandidate.n) return [];
+  const now = Date.now();
+  const prunedIds = writeTransaction(() => pruneOfflineAgentsInternal(cutoff, now, opts?.beforeDelete));
+  for (const id of prunedIds) evictPendingPresence(id); // #1468 — no buffered beat should outlive a pruned row
+  return prunedIds;
+}
+
+/** The `agents.delete` op body (S3 L10 #1895): the pre-migration transaction closure minus
+ *  `evictPendingPresence` (main-thread-only buffer — see `setStatusInternal`'s note). */
+export function deleteAgentInternal(id: string, now: number): boolean {
+  // Release any claims held by this agent so the tasks become claimable again — except for
+  // messages whose task is already closed (releasing those resurrects finished work).
+  // from_agent is left intact as historical record.
+  getDb().query(`UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by = ? AND NOT ${messageTaskClosed("messages.id")}`).run(id);
+  settleSingleTargetOnDemandTasks("claimed_by = ?", [id], now, "agent-removed");
+  getDb().query(`UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE ${claimTaskWhere()} AND claimed_by = ? AND status IN ('claimed', 'in_progress', 'blocked')`).run(now, id);
+  revokeRuntimeTokensForAgent(id, now);
+  closeOpenPairsForAgent(id, now);
+  removeSubscriptionsForAgent(id);
+  clearAgentNotices(id);
+  return getDb().query("DELETE FROM agents WHERE id = ?").run(id).changes > 0;
+}
+
+export function deleteAgent(id: string): { ok: boolean; error?: string } {
+  if (isReservedAgentId(id)) {
+    return { ok: false, error: "built-in agent cannot be deleted" };
+  }
+  const now = Date.now();
+  const deleted = writeTransaction(() => deleteAgentInternal(id, now));
+  evictPendingPresence(id); // #1468 — no buffered beat should outlive the deleted row
+  return deleted ? { ok: true } : { ok: false, error: "agent not found" };
+}
+
+// #1057(1) — close the orphan-token window #1051 left open. A dead runner with no replacement
+// used to keep its token valid until the 24h offline prune (~720× the pre-#1051 ~2min horizon).
+// This sweep revokes ("stale", re-mintable — #484) the runtime tokens of agents whose process the
+// orchestrator CONFIRMED dead (meta.lastExit, the #1054 signal — never a liveness inference, so
+// the #1051 decouple holds) once a full grace has passed with no heartbeat since the relay
+// received the report. The two guards make a late exit report harmless to a live replacement:
+//   - a replacement registration replaces meta wholesale (no lastExitReceivedAt) → excluded;
+//   - a replacement that got the late report stamped ONTO its row keeps heartbeating, pushing
+//     last_seen past the receipt (heartbeat also flips it off 'offline') → excluded.
+// `lagGraceMs` mirrors the stale reaper's #1048/#1055 discipline: while the relay's own event
+// loop was stalled, a live claimant's heartbeats may not have been processed yet, so the window
+// widens by the observed lag rather than misreading the backlog as post-mortem silence.
+export function revokeOrphanedRuntimeTokens(graceMs: number = STALE_TTL_MS, lagGraceMs = 0, now = Date.now()): Array<{ agentId: string; jtis: string[] }> {
+  const cutoff = now - graceMs - Math.max(0, lagGraceMs);
+  const rows = getDb()
+    .query(`SELECT id, meta, last_seen FROM agents WHERE status = 'offline' AND meta LIKE '%lastExitReceivedAt%' AND NOT ${reservedAgentIdSql()}`)
+    .all() as Array<{ id: string; meta: string | null; last_seen: number }>;
+  const revoked: Array<{ agentId: string; jtis: string[] }> = [];
+  for (const row of rows) {
+    const meta = parseJson<Record<string, unknown>>(row.meta ?? "{}", {});
+    const receivedAt = typeof meta.lastExitReceivedAt === "number" ? meta.lastExitReceivedAt : undefined;
+    if (receivedAt === undefined || receivedAt > cutoff) continue;
+    if (row.last_seen > receivedAt) continue;
+    const jtis = revokeProviderRuntimeTokensByJti(runtimeTokenJtisFromMeta(meta), "stale", now);
+    if (jtis.length > 0) revoked.push({ agentId: row.id, jtis });
+  }
+  return revoked;
+}
+
+// #484: `reason` is stamped on each revocation so a stale-on-restart revocation
+// (recoverable via orchestrator re-mint for a still-live process) is distinguishable
+// from a hard kill. Default "agent-removed" (hard) — callers that revoke a possibly-
+// live process across a restart MUST pass "stale".
+export function revokeRuntimeTokensForAgent(agentId: string, now = Date.now(), reason: LineageRevokeReason = "agent-removed"): string[] {
+  revokeVaultTokens(agentId, now, reason);
+  const row = getDb().query("SELECT meta FROM agents WHERE id = ?").get(agentId) as { meta?: string } | undefined;
+  const jtis = runtimeTokenJtisFromMeta(parseJson(row?.meta ?? "{}", {}));
+  return revokeProviderRuntimeTokensByJti(jtis, reason, now);
+}
+
+// #1051 — the #484 restart-strand invariant, re-homed from heartbeat-lapse to instance
+// takeover. Staleness (a missed heartbeat) no longer revokes anything; instead, when a
+// FRESH runner process re-registers under an existing agent id — a new instanceId, which
+// bumps the agent epoch — the PRIOR instance's runtime tokens are revoked "stale" here,
+// atomically with the bump (fired from inside upsertAgent). "stale" (not a hard kill)
+// keeps them re-mintable via the orchestrator (#484), so a live process that merely
+// rotated instances still self-heals, while an orphaned prior-instance token can no
+// longer authenticate a request directly. A same-instance reconnect (relay-restart / lag
+// recovery) keeps its instanceId, does not bump the epoch, and so never reaches this
+// path — its token stays valid untouched.
+// #1057(3) — `keepJtis` must be SERVER-verified (the jti of the token that authenticated the
+// registration, resolved to this very agent — see registerAgent). It is never derived from the
+// incoming client meta: a takeover caller could otherwise list the prior jti in meta.auth.jtis
+// and spare it from revocation. The incoming instance's own token needs no keep entry — only
+// PRIOR jtis are ever revoked, so a fresh token is structurally never collateral.
+export function revokeSupersededRuntimeTokens(prior: AgentCard, keepJtis: string[] = [], now = Date.now()): string[] {
+  revokeVaultTokens(prior.id, now, "instance_replaced", prior.instanceId);
+  const priorJtis = runtimeTokenJtisFromMeta((prior.meta ?? {}) as Record<string, unknown>);
+  if (priorJtis.length === 0) return [];
+  const keep = new Set(keepJtis);
+  const superseded = priorJtis.filter((jti) => !keep.has(jti));
+  return revokeProviderRuntimeTokensByJti(superseded, "stale", now, keepJtis);
+}
+
+// #1245 — each listed provider token, retired or not, seeds its whole handoff lineage.
+function revokeProviderRuntimeTokensByJti(jtis: string[], reason: LineageRevokeReason, now: number, keep: string[] = []): string[] {
+  if (jtis.length === 0) return [];
+  const placeholders = jtis.map(() => "?").join(",");
+  const seeds = getDb().query(`
+    SELECT jti FROM tokens
+    WHERE role = 'provider'
+      AND profile_id IN ('provider-agent', 'provider-interactive', 'provider-child')
+      AND jti IN (${placeholders})
+  `).all(...jtis) as Array<{ jti: string }>;
+  return revokeTokenLineage(seeds.map((row) => row.jti), reason, Math.floor(now / 1000), keep);
+}
+
+function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[] {
+  const jtis = new Set<string>();
+  const auth = isRecord(meta.auth) ? meta.auth : undefined;
+  const direct = typeof auth?.jti === "string" ? auth.jti : typeof meta.runtimeTokenJti === "string" ? meta.runtimeTokenJti : undefined;
+  if (direct) jtis.add(direct);
+  const extra = Array.isArray(auth?.jtis) ? auth.jtis : Array.isArray(meta.runtimeTokenJtis) ? meta.runtimeTokenJtis : [];
+  for (const item of extra) {
+    if (typeof item === "string") jtis.add(item);
+  }
+  return [...jtis];
+}
+
+// --- Tasks ---