@humwick/server 0.130.0 → 0.130.2

package/src/db/agents-write-ops.ts

@@ -19,6 +19,8 @@ import { applyIdleSelfCare } from "./idle-self-care";
 // write (none of these are) would need `idempotent: false` plus a caller-supplied key.
 
 import {
+  applyAgentLifecycleUpdateInternal,
+  type AgentLifecycleWriteArgs,
   clearAgentMetaKeys,
   deleteAgentInternal,
   heartbeat,
@@ -41,6 +43,7 @@ import {
 import { pruneOfflineAgentsWithFinality, type AgentsPruneOfflineOpArgs } from "./agents-prune-write-op.ts";
 import { setAgentKeepState } from "./agent-keep.ts";
 import type { AgentCard, AgentKeep, AgentSessionGuard, ContextState, ManagedSessionExitDiagnostics, ProviderCapabilities, QuotaState, RegisterAgentInput } from "../types";
+import type { OrphanedTokenPage } from "./agents.ts";
 import type { LineageRevokeReason } from "./token-standing.ts";
 import type { LifecycleWriteOutcome } from "./lifecycle-seq.ts";
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
@@ -69,31 +72,36 @@ export interface AgentsHeartbeatOpArgs {
 export interface AgentsRecordContextSnapshotOpArgs { agentId: string; context: ContextState }
 export interface AgentsReapStaleOpArgs { ttlMs: number; lagGraceMs: number; protectedIds?: string[]; seq: number }
 export interface AgentsDeleteOpArgs { id: string }
-export interface AgentsRevokeOrphanedTokensOpArgs { graceMs: number; lagGraceMs: number }
+export interface AgentsRevokeOrphanedTokensOpArgs { graceMs: number; lagGraceMs: number; afterId?: string; limit?: number }
 export interface AgentsRevokeTokensForAgentOpArgs { agentId: string; reason?: LineageRevokeReason }
 
 export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
-  "agents.pruneIdentityArchive": { idempotent: true, fn: (_args: Record<string, never>, ctx: WriterOpContext) => pruneAgentIdentityArchive(ctx.now) },
-  "agents.idleSelfCare": { idempotent: false, fn: (args: { id: string; epoch: number }, ctx: WriterOpContext) => applyIdleSelfCare(args, ctx.now) },
+  "agents.pruneIdentityArchive": { offLoop: true, idempotent: true, fn: (_args: Record<string, never>, ctx: WriterOpContext) => pruneAgentIdentityArchive(ctx.now) },
+  "agents.idleSelfCare": { offLoop: true, idempotent: false, fn: (args: { id: string; epoch: number }, ctx: WriterOpContext) => applyIdleSelfCare(args, ctx.now) },
   "agents.upsert": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsUpsertOpArgs, ctx: WriterOpContext): UpsertAgentTxResult =>
       upsertAgentInternal(args.input, args.opts, ctx.now, args.seq),
   },
   "agents.setLabel": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsSetLabelOpArgs): boolean => setLabel(args.id, args.label),
   },
   "agents.setKeep": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: string; keep: AgentKeep | null }): boolean => setAgentKeepState(args.id, args.keep),
   },
   "agents.setTeam": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsSetTeamOpArgs, ctx: WriterOpContext): AgentCard | null =>
       setAgentTeam(args.agentId, args.teamId, ctx.now),
   },
   "agents.setTags": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsSetTagsOpArgs, ctx: WriterOpContext): AgentCard | null =>
       setTags(args.id, args.tags, ctx.now),
@@ -102,6 +110,12 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
   // coalescing window buffered them) and return a tri-state: `superseded` means a later-submitted
   // lifecycle write already landed, which is a SUCCESS for the caller and must not be mistaken for a
   // missing agent. See lifecycle-seq.ts.
+  "agents.applyLifecycleUpdate": {
+    // #1870 S7: bus status frame and heartbeat bypass; a replay of the same `seq` is a no-op on the fenced columns.
+    offLoop: true,
+    idempotent: true,
+    fn: (args: AgentLifecycleWriteArgs) => applyAgentLifecycleUpdateInternal(args),
+  },
   "agents.setStatus": {
     offLoop: true,
     idempotent: true,
@@ -115,16 +129,19 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
       markReady(args.id, args.ready, args.guard, ctx.now, args.seq),
   },
   "agents.mergeMeta": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsMergeMetaOpArgs, ctx: WriterOpContext): boolean =>
       mergeAgentMeta(args.id, args.meta, args.guard, ctx.now),
   },
   "agents.markReadyNotified": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsMarkReadyNotifiedOpArgs, ctx: WriterOpContext): boolean =>
       markAgentReadyNotified(args.id, ctx.now),
   },
   "agents.clearMetaKeys": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsClearMetaKeysOpArgs): boolean => clearAgentMetaKeys(args.id, args.keys),
   },
@@ -135,11 +152,13 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
       recordAgentExitDiagnosticsInternal(args.id, args.diagnostics, ctx.now, args.seq),
   },
   "agents.heartbeat": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsHeartbeatOpArgs, ctx: WriterOpContext): boolean =>
       heartbeat(args.id, args.guard, args.runtime, ctx.now),
   },
   "agents.recordContextSnapshot": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsRecordContextSnapshotOpArgs, ctx: WriterOpContext): null => {
       recordContextSnapshot(args.agentId, args.context, ctx.now);
@@ -147,26 +166,30 @@ export const AGENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.f
     },
   },
   "agents.reapStale": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsReapStaleOpArgs, ctx: WriterOpContext): string[] =>
       reapStaleAgentsInternal(args.ttlMs, args.lagGraceMs, ctx.now, args.protectedIds, args.seq),
   },
   "agents.pruneOffline": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsPruneOfflineOpArgs, ctx: WriterOpContext) =>
       pruneOfflineAgentsWithFinality(args, ctx.now),
   },
   "agents.delete": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsDeleteOpArgs, ctx: WriterOpContext): boolean => deleteAgentInternal(args.id, ctx.now),
   },
   "agents.revokeOrphanedTokens": {
     offLoop: true,
     idempotent: true,
-    fn: (args: AgentsRevokeOrphanedTokensOpArgs, ctx: WriterOpContext): Array<{ agentId: string; jtis: string[] }> =>
-      revokeOrphanedRuntimeTokens(args.graceMs, args.lagGraceMs, ctx.now),
+    fn: (args: AgentsRevokeOrphanedTokensOpArgs, ctx: WriterOpContext): OrphanedTokenPage =>
+      revokeOrphanedRuntimeTokens(args.graceMs, args.lagGraceMs, ctx.now, { afterId: args.afterId, limit: args.limit }),
   },
   "agents.revokeTokensForAgent": {
+    offLoop: true,
     idempotent: true,
     fn: (args: AgentsRevokeTokensForAgentOpArgs, ctx: WriterOpContext): string[] =>
       revokeRuntimeTokensForAgent(args.agentId, ctx.now, args.reason),

package/src/db/agents.ts

@@ -479,28 +479,51 @@ export function applyAgentLifecycleUpdate(
   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 seq = nextLifecycleSeq();
+  const before = prepareAgentLifecycleUpdate(id, update, guard);
+  if (!before) return { ok: false, changed: false, metaWriteBytes: 0, before: null, after: null };
+  return { ok: true, before, ...inWriteTransaction(() => applyAgentLifecycleUpdateInternal(agentLifecycleWriteArgs(before, update, seq, now))) };
+}
 
+/** The writer-op args for one lifecycle delta (#1870 S7). `seq` is taken at the caller's entry (lifecycle-seq.ts
+ *  rule 1); `expectedEpoch` fences the write to the instance `before` was read from across the writer hop. */
+export interface AgentLifecycleWriteArgs {
+  id: string;
+  update: AgentLifecycleUpdate;
+  seq: number;
+  now: number;
+  expectedEpoch: number;
+  before: { instanceId?: string; spawnRequestId: string; terminalProviderExit?: unknown };
+}
+
+export function agentLifecycleWriteArgs(before: AgentCard, update: AgentLifecycleUpdate, seq: number, now: number): AgentLifecycleWriteArgs {
+  return { id: before.id, update, seq, now, expectedEpoch: before.epoch, before: { instanceId: before.instanceId, spawnRequestId: String(before.meta?.spawnRequestId ?? ""), terminalProviderExit: before.meta?.terminalProviderExit } };
+}
+
+/** The main-thread half of a lifecycle delta: guard, `before` snapshot, transition handlers and presence
+ *  eviction (main-thread state), all before the write is submitted. Null when the guard rejects. */
+export function prepareAgentLifecycleUpdate(id: string, update: AgentLifecycleUpdate, guard?: AgentSessionGuard): AgentCard | null {
+  const before = getPersistedAgentRuntimeCard(id);
+  if (!before || !agentSessionGuardResult(before, guard).ok) return null;
   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.
+  // Pre-transition handlers 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);
+  return before;
+}
 
-  // #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();
+/** Op body (`agents.applyLifecycleUpdate`): the fenced UPDATE, its effects, and the offline post-commit, in the
+ *  caller's transaction. #2111 review BLOCKER 1 — each written column's ordinal is raised, so a lifecycle write
+ *  the coalescing window deferred cannot commit afterwards and undo it. */
+export function applyAgentLifecycleUpdateInternal(args: AgentLifecycleWriteArgs): Omit<AgentLifecycleUpdateResult, "ok" | "before"> {
+  const { id, update, seq, now, before } = args;
+  const nextStatus = update.status;
   // 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 };
+  const params: Record<string, unknown> = { $now: now, $seq: seq, $id: id, $epoch: args.expectedEpoch };
   let metaWriteBytes = 0;
   if (nextStatus !== undefined) {
     sets.push(fencedColumnSql("status", "$status", "$seq"));
@@ -558,16 +581,10 @@ export function applyAgentLifecycleUpdate(
     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;
-  });
-
+  const changed = getDb().query(`UPDATE agents SET ${sets.join(", ")} WHERE id = $id AND epoch = $epoch`).run(params as never).changes > 0;
+  const terminalLaunch = terminalProviderLaunchId(update.meta?.terminalProviderExit ?? before.terminalProviderExit);
+  if (changed && nextStatus === "offline" && terminalLaunch) revokeVaultTokens(id, now, "provider_terminal_exit", before.instanceId, before.spawnRequestId, terminalLaunch);
+  if (changed && contextState) recordContextSnapshot(id, contextState, now);
   // 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.
@@ -575,7 +592,7 @@ export function applyAgentLifecycleUpdate(
     closeOpenPairsForAgent(id, now);
     electWorkspaceStewards();
   }
-  return { ok: true, changed, metaWriteBytes, before, after: getPersistedAgentRuntimeCard(id) };
+  return { changed, metaWriteBytes, after: getPersistedAgentRuntimeCard(id) };
 }
 
 export function mergeAgentMeta(id: string, meta: Record<string, unknown>, guard?: AgentSessionGuard, now: number = Date.now()): boolean {
@@ -828,21 +845,27 @@ export function heartbeat(
 // 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).
 
+/** Heartbeat: buffers the steady-state liveness advance (flushed by `flushPresence`), writes presence-critical
+ * transitions at once. False if the session guard rejects or the agent is gone. Sync twin for tests; the
+ * transports use `recordHeartbeatAsync`, which writes the bypass on the writer thread (#1870 S7). */
+export function recordHeartbeat(id: string, opts: HeartbeatInput = {}): boolean {
+  const beat = bufferOrBypassHeartbeat(id, opts);
+  return typeof beat === "boolean" ? beat : applyAgentLifecycleUpdate(id, beat, opts.guard, opts.now ?? Date.now()).changed;
+}
+
+export interface HeartbeatInput {
+  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;
+}
+
 /**
- * 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.
+ * The shared decision of `recordHeartbeat` and `recordHeartbeatAsync`: buffer a steady-state beat (returns
+ * the result) or hand back the lifecycle delta a presence-critical beat must write now.
  */
-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 {
+export function bufferOrBypassHeartbeat(id: string, opts: HeartbeatInput): boolean | AgentLifecycleUpdate {
   if (!validateAgentSession(id, opts.guard).ok) return false;
   const current = getAgent(id);
   if (!current) return false;
@@ -861,9 +884,9 @@ export function recordHeartbeat(
     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.
+    // Merge any buffered-but-unflushed runtime cols into this 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,
@@ -871,16 +894,10 @@ export function recordHeartbeat(
           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;
+    pendingPresence.delete(id); // this write supersedes any buffered advance
+    // #2111 — one consolidated update carries both the beat and the explicit status, which overrides
+    // the resurrection CASE.
+    return { status: statusChanged ? opts.status : undefined, resurrectOnBeat: true, runtime };
   }
 
   // Steady state: buffer. Merge context advisory markers now (matches heartbeat()'s per-beat merge),
@@ -1192,6 +1209,10 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
   return deleted ? { ok: true } : { ok: false, error: "agent not found" };
 }
 
+export type OrphanedTokenRevocation = { agentId: string; jtis: string[] };
+/** One page of the orphan sweep: agents after `afterId` in id order, up to `limit` (#3776: one short write each). */
+export type OrphanedTokenPage = { revoked: OrphanedTokenRevocation[]; nextAfterId: string | null };
+
 // #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
@@ -1204,12 +1225,18 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
 // `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[] }> {
+export function revokeOrphanedRuntimeTokens(
+  graceMs: number = STALE_TTL_MS,
+  lagGraceMs = 0,
+  now = Date.now(),
+  page: { afterId?: string; limit?: number } = {},
+): OrphanedTokenPage {
   const cutoff = now - graceMs - Math.max(0, lagGraceMs);
+  const limit = page.limit ?? -1;
   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[] }> = [];
+    .query(`SELECT id, meta, last_seen FROM agents WHERE status = 'offline' AND meta LIKE '%lastExitReceivedAt%' AND NOT ${reservedAgentIdSql()} AND id > ? ORDER BY id LIMIT ?`)
+    .all(page.afterId ?? "", limit) as Array<{ id: string; meta: string | null; last_seen: number }>;
+  const revoked: OrphanedTokenRevocation[] = [];
   for (const row of rows) {
     const meta = parseJson<Record<string, unknown>>(row.meta ?? "{}", {});
     const receivedAt = typeof meta.lastExitReceivedAt === "number" ? meta.lastExitReceivedAt : undefined;
@@ -1218,7 +1245,7 @@ export function revokeOrphanedRuntimeTokens(graceMs: number = STALE_TTL_MS, lagG
     const jtis = revokeProviderRuntimeTokensByJti(runtimeTokenJtisFromMeta(meta), "stale", now);
     if (jtis.length > 0) revoked.push({ agentId: row.id, jtis });
   }
-  return revoked;
+  return { revoked, nextAfterId: limit > 0 && rows.length === limit ? rows[rows.length - 1]!.id : null };
 }
 
 // #484: `reason` is stamped on each revocation so a stale-on-restart revocation

package/src/db/artifacts-write-ops.ts

@@ -13,6 +13,7 @@ import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const ARTIFACTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "artifacts.upsertBlob": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof upsertArtifactBlob>[0] }, ctx: WriterOpContext) =>
       upsertArtifactBlob({ ...args.input, createdAt: args.input.createdAt ?? ctx.now }),
@@ -22,23 +23,27 @@ export const ARTIFACTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Objec
     idempotent: false,
     fn: (args: { input: Parameters<typeof createArtifact>[0] }, ctx: WriterOpContext) => createArtifact(args.input, ctx.now),
   },
-  "artifacts.pin": { idempotent: true, fn: (args: { id: string; pinned: boolean; readScope?: import("./artifacts").ArtifactReadScope }) => setArtifactPinned(args.id, args.pinned, args.readScope) },
-  "artifacts.delete": { idempotent: true, fn: (args: { id: string }) => deleteArtifact(args.id, false) },
-  "artifacts.deleteBlob": { idempotent: true, fn: (args: { digest: string }) => deleteArtifactBlob(args.digest) },
+  "artifacts.pin": { offLoop: true, idempotent: true, fn: (args: { id: string; pinned: boolean; readScope?: import("./artifacts").ArtifactReadScope }) => setArtifactPinned(args.id, args.pinned, args.readScope) },
+  "artifacts.delete": { offLoop: true, idempotent: true, fn: (args: { id: string }) => deleteArtifact(args.id, false) },
+  "artifacts.deleteBlob": { offLoop: true, idempotent: true, fn: (args: { digest: string }) => deleteArtifactBlob(args.digest) },
   "artifacts.link": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof linkArtifact>[0] }, ctx: WriterOpContext) => linkArtifact(args.input, ctx.now),
   },
   "artifacts.linkExistingEntity": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof linkArtifactToExistingEntity>[0] }, ctx: WriterOpContext) => linkArtifactToExistingEntity(args.input, ctx.now),
   },
   "artifacts.deleteLinksForEntity": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { entityType: Parameters<typeof deleteArtifactLinksForEntity>[0]; entityId: string | number }) =>
       deleteArtifactLinksForEntity(args.entityType, args.entityId),
   },
   "artifacts.sweep": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input?: Parameters<typeof sweepArtifacts>[0] }, ctx: WriterOpContext) =>
       sweepArtifacts({ ...args.input, now: args.input?.now ?? ctx.now }, false),

package/src/db/bus-outbox-write-ops.ts

@@ -49,6 +49,7 @@ export const BUS_OUTBOX_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Obje
   // the same end state (no rows older than the threshold), so it is idempotent and needs no key. `ctx.now`
   // is the submission-time wall-clock (H6).
   "bus.prune": {
+    offLoop: true,
     idempotent: true,
     fn: (args: BusPruneOpArgs, ctx: WriterOpContext): { changes: number } => ({
       changes: pruneOutbox(args.retentionMs, ctx.now),

package/src/db/channels-write-ops.ts

@@ -14,15 +14,18 @@ import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const CHANNELS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "channels.deleteBinding": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { id: string; fence: ChannelBindingSessionFence }) => deleteChannelBindingBody(args.id, args.fence),
   },
   "channels.upsertBinding": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: UpsertChannelBindingInput; presence?: PresenceSnapshot; fence?: ChannelBindingSessionFence }, ctx: WriterOpContext) =>
       upsertChannelBindingBody(args.input, ctx.now, args.presence, args.fence),
   },
   "channels.registerAgent": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { agentId: string; expectedEpoch: number; presence?: PresenceSnapshot }, ctx: WriterOpContext) => {
       // Re-read under this operation's BEGIN IMMEDIATE. A card captured before an await may now be
@@ -36,6 +39,7 @@ export const CHANNELS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object
     },
   },
   "channels.evaluatePoolBindings": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { presence?: PresenceSnapshot }, ctx: WriterOpContext) => evaluatePoolBindingsBody(ctx.now, args.presence),
   },

package/src/db/ci-incidents-async.ts

@@ -35,15 +35,15 @@ const write = <T>(op: string, args: unknown, idempotencyKey?: string): Promise<T
 export function upsertWatchStateAsync(input: Parameters<typeof upsertWatchState>[0]): Promise<ReturnType<typeof upsertWatchState>> {
   return write("ciIncidents.watch.upsert", input);
 }
-/** One gateway writer transaction for the complete watch + incident lifecycle decision. */
-export function ingestCiObservationTransitionAsync(input: CiObservationTransitionInput): Promise<CiObservationTransitionResult> {
-  return write("ciIncidents.observation.ingest", input);
+/** One gateway writer transaction for the complete watch + incident lifecycle decision. `now` pins a test clock. */
+export function ingestCiObservationTransitionAsync(input: CiObservationTransitionInput, now?: number): Promise<CiObservationTransitionResult> {
+  return write("ciIncidents.observation.ingest", now === undefined ? input : { ...input, now });
 }
 export function markCiWatchNeverMatchedNotifiedAsync(watchKey: string): Promise<ReturnType<typeof markCiWatchNeverMatchedNotified>> {
   return write("ciIncidents.watch.markNeverMatched", { watchKey });
 }
-export function markCiRootMissingNotifiedAsync(repository: string): Promise<ReturnType<typeof markCiRootMissingNotified>> {
-  return write("ciIncidents.root.markMissing", { repository });
+export function markCiRootMissingNotifiedAsync(repository: string, now?: number): Promise<ReturnType<typeof markCiRootMissingNotified>> {
+  return write("ciIncidents.root.markMissing", now === undefined ? { repository } : { repository, now });
 }
 export function openOrDedupeIncidentAsync(input: Parameters<typeof openOrDedupeIncident>[0]): Promise<ReturnType<typeof openOrDedupeIncident>> {
   return write("ciIncidents.openOrDedupe", input);

package/src/db/ci-incidents-write-ops.ts

@@ -27,7 +27,7 @@ export const CI_INCIDENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Ob
   "ciIncidents.observation.ingest": {
     offLoop: true,
     idempotent: true,
-    fn: (a: Parameters<typeof applyCiObservationTransitionInternal>[0], ctx) => applyCiObservationTransitionInternal(a, ctx.now),
+    fn: (a: Parameters<typeof applyCiObservationTransitionInternal>[0] & { now?: number }, ctx) => applyCiObservationTransitionInternal(a, a.now ?? ctx.now),
   },
   "ciIncidents.gateRun.record": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof recordCiGateRuns>[0]) => recordCiGateRuns(a) },
   "ciIncidents.gateBackfill.start": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof startCiGateBackfill>[0]) => startCiGateBackfill(a) },
@@ -36,7 +36,7 @@ export const CI_INCIDENTS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Ob
   "ciIncidents.sha.prune": { offLoop: true, idempotent: true, fn: (_a: { now: number }, ctx) => pruneCiShaObservations(ctx.now) },
   "ciIncidents.watch.upsert": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof upsertWatchState>[0], ctx) => upsertWatchState(a, ctx.now) },
   "ciIncidents.watch.markNeverMatched": { offLoop: true, idempotent: true, fn: (a: { watchKey: string }, ctx) => markCiWatchNeverMatchedNotified(a.watchKey, ctx.now) },
-  "ciIncidents.root.markMissing": { offLoop: true, idempotent: true, fn: (a: { repository: string }, ctx) => markCiRootMissingNotified(a.repository, ctx.now) },
+  "ciIncidents.root.markMissing": { offLoop: true, idempotent: true, fn: (a: { repository: string; now?: number }, ctx) => markCiRootMissingNotified(a.repository, a.now ?? ctx.now) },
   "ciIncidents.openOrDedupe": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof openOrDedupeIncidentInternal>[0], ctx) => openOrDedupeIncidentInternal(a, ctx.now, false) },
   // Guarded transitions throw after they have advanced; use the durable retry ledger rather than
   // misclassifying that as safe replay. Distinct steward attempts carry distinct request ids.

package/src/db/claude-api-budget-ops.ts

@@ -7,9 +7,9 @@ export const CLAUDE_API_BUDGET_READ_OPS = {
   "apiBudget.status": (args: { now: number; budgetId?: ApiBudgetId }) => apiBudgetStatus(args.now, args.budgetId),
 };
 export const CLAUDE_API_BUDGET_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
-  "apiBudget.reconcile": { idempotent: true, fn: (args: { now: number }) => reconcileApiBudgetSessions(args.now) },
-  "apiBudget.pace": { idempotent: true, fn: (args: { leadTimeMs: number; now: number; budgetId?: ApiBudgetId }) => apiBudgetPace(args.leadTimeMs, args.now, args.budgetId) },
-  "apiBudget.configure": { idempotent: true, fn: (args: { input: ApiBudgetConfig; now: number }) => configureApiBudget(args.input, args.now) },
-  "apiBudget.reserve": { idempotent: true, fn: (args: { input: ApiBudgetReserve; now: number }) => reserveApiBudget(args.input, args.now) },
-  "apiBudget.report": { idempotent: true, fn: (args: { input: ApiBudgetReport; now: number }) => reportApiBudget(args.input, args.now) },
+  "apiBudget.reconcile": { offLoop: true, idempotent: true, fn: (args: { now: number }) => reconcileApiBudgetSessions(args.now) },
+  "apiBudget.pace": { offLoop: true, idempotent: true, fn: (args: { leadTimeMs: number; now: number; budgetId?: ApiBudgetId }) => apiBudgetPace(args.leadTimeMs, args.now, args.budgetId) },
+  "apiBudget.configure": { offLoop: true, idempotent: true, fn: (args: { input: ApiBudgetConfig; now: number }) => configureApiBudget(args.input, args.now) },
+  "apiBudget.reserve": { offLoop: true, idempotent: true, fn: (args: { input: ApiBudgetReserve; now: number }) => reserveApiBudget(args.input, args.now) },
+  "apiBudget.report": { offLoop: true, idempotent: true, fn: (args: { input: ApiBudgetReport; now: number }) => reportApiBudget(args.input, args.now) },
 };

package/src/db/claude-app-oauth.ts

@@ -44,13 +44,13 @@ function put(args: Put): boolean {
 
 export const CLAUDE_APP_OAUTH_READ_OPS = { "claudeAppOAuth.get": get };
 export const CLAUDE_APP_OAUTH_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
-  "claudeAppOAuth.put": { idempotent: false, fn: put },
-  "claudeAppOAuth.take": { idempotent: false, fn: (args: Key) => {
+  "claudeAppOAuth.put": { offLoop: true, idempotent: false, fn: put },
+  "claudeAppOAuth.take": { offLoop: true, idempotent: false, fn: (args: Key) => {
     const value = get(args);
     getDb().query("DELETE FROM claude_app_oauth WHERE resource=? AND kind=? AND key=?").run(args.resource, args.kind, args.key);
     return value;
   } },
-  "claudeAppOAuth.issue": { idempotent: false, fn: (args: Put & { refreshKey?: string; clientId: string }) => {
+  "claudeAppOAuth.issue": { offLoop: true, idempotent: false, fn: (args: Put & { refreshKey?: string; clientId: string }) => {
     // Consume and replace in the same writer transaction; concurrent refreshes cannot resurrect a revoked family.
     let old: { clientId: string; family: string; type: string; used?: boolean } | undefined;
     if (args.refreshKey) {
@@ -65,7 +65,7 @@ export const CLAUDE_APP_OAUTH_WRITE_OPS: Readonly<Record<string, WriterOpSpec>>
       .run(JSON.stringify({ ...old, used: true }), args.resource, args.kind, args.refreshKey!);
     return "ok";
   } },
-  "claudeAppOAuth.revoke": { idempotent: true, fn: (args: Key & { clientId: string }) => {
+  "claudeAppOAuth.revoke": { offLoop: true, idempotent: true, fn: (args: Key & { clientId: string }) => {
     const value = get(args);
     const credential = value ? JSON.parse(value) as { clientId: string; family: string } : null;
     if (credential?.clientId === args.clientId) removeFamily(args.resource, credential.family);

package/src/db/codex-reset-consumes-write-ops.ts

@@ -3,16 +3,19 @@ import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const CODEX_RESET_CONSUMES_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
   "codexResetConsumes.begin": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof beginCodexResetConsume>[0] }, ctx: WriterOpContext) =>
       beginCodexResetConsume({ ...args.input, now: args.input.now ?? ctx.now }),
   },
   "codexResetConsumes.complete": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { input: Parameters<typeof completeCodexResetConsume>[0] }, ctx: WriterOpContext) =>
       completeCodexResetConsume({ ...args.input, now: args.input.now ?? ctx.now }),
   },
   "codexResetConsumes.prune": {
+    offLoop: true,
     idempotent: true,
     fn: (args: { olderThan?: number }, ctx: WriterOpContext) => pruneCodexResetConsumes(args.olderThan ?? ctx.now),
   },

package/src/db/command-row.ts

@@ -41,13 +41,15 @@ export interface CommandRow {
 }
 
 
-export function rowToCommand(row: CommandRow): Command {
+/** `slim` (#3391): listings omit `params.agentProfile` (~0.5 MB per spawn row) instead of hydrating it;
+ *  `GET /api/commands/:id` returns the full row. */
+export function rowToCommand(row: CommandRow, options: { slim?: boolean } = {}): Command {
   return {
     id: row.id,
     type: row.type,
     source: row.source,
     target: row.target,
-    params: hydrateCommandAgentProfile(parseObject(row.params), row.agent_profile_hash),
+    params: options.slim ? withoutAgentProfile(parseObject(row.params)) : hydrateCommandAgentProfile(parseObject(row.params), row.agent_profile_hash),
     status: row.status,
     result: row.result ? parseObject(row.result) : undefined,
     error: row.error ?? undefined,
@@ -78,6 +80,12 @@ export function rowToCommand(row: CommandRow): Command {
   };
 }
 
+function withoutAgentProfile(params: Record<string, unknown>): Record<string, unknown> {
+  if (!("agentProfile" in params)) return params;
+  const { agentProfile: _omitted, ...rest } = params;
+  return rest;
+}
+
 function parseObject(raw: string): Record<string, unknown> {
   try {
     const parsed = JSON.parse(raw);

package/src/db/commands-list-query.ts

@@ -9,6 +9,8 @@ export interface CommandFilters {
   dispatchableOnly?: boolean;
   /** #2663 — oldest-first for the executor DISPATCH feed, whose window is capped. See `getCommands`. */
   oldestFirst?: boolean;
+  /** #3391 — omit `params.agentProfile` from rows (listing views; fetch the row by id for the profile). */
+  slim?: boolean;
 }
 
 export function buildListCommandsQuery(filters: CommandFilters = {}): { sql: string; params: unknown[] } {

package/src/db/commands-spawn-read.ts

@@ -29,5 +29,5 @@ export const IN_FLIGHT_SPAWNS_BY_PARENT_SQL = `SELECT * FROM commands INDEXED BY
 /** One parent's agent.spawn commands still in flight, newest first. */
 export function listInFlightSpawnCommands(parentId: string, limit = 500): Command[] {
   const rows = getDb().query(IN_FLIGHT_SPAWNS_BY_PARENT_SQL).all(...SPAWN_IN_FLIGHT_STATUSES, parentId, limit) as CommandRow[];
-  return rows.map(rowToCommand);
+  return rows.map((row) => rowToCommand(row));
 }