@humwick/server 0.0.0-stage → 0.130.1

package/src/lifecycle-signal-registry.ts

@@ -0,0 +1,87 @@
+// #1032b — cross-subsystem "a first-class lifecycle event already told this spawner about this
+// subject" registry. A spawned child's state reaches its spawner through TWO independent lanes:
+//   1. First-class lifecycle notifications — agent.ready, the lineage report-up (turn-final
+//      response), agent.exited, branch.landed/merge.
+//   2. "Task status pulse" digests emitted from task transitions (working / committed-on-branch /
+//      landed-on-main / done / …).
+// When lane 1 has just conveyed the state, the lane-2 pulse is redundant noise that wakes the
+// spawner a second time for the same fact. This registry is the shared memory: lane-1 emitters
+// STAMP `(recipient, subjectKey)`; the pulse enqueue/flush path CHECKS it and suppresses.
+//
+// In-memory + short-TTL by design: it only needs to catch the near-simultaneous double-notify
+// (both lanes fire within seconds of the same underlying event). A relay restart wiping it merely
+// means a pulse that would have been suppressed is delivered once — never a lost signal.
+
+const DEFAULT_LIFECYCLE_SIGNAL_TTL_MS = 60_000;
+
+interface SignalEntry {
+  at: number;
+}
+
+const signals = new Map<string, SignalEntry>();
+
+// Delimiter between recipient and subject key. A pipe can't occur in an agent id or a subject key
+// (subject keys are `task:<n>` / `child:<id>` and ids are dot/dash/colon-only), so the composite is
+// unambiguous. Kept a plain visible character so the source stays grep-friendly.
+const KEY_DELIMITER = " || ";
+
+function compositeKey(recipient: string, subjectKey: string): string {
+  return `${recipient}${KEY_DELIMITER}${subjectKey}`;
+}
+
+// #1038 — the semantic state a child-progress lifecycle signal (a report-up / agent.ready) conveys:
+// "the child is actively working this task". Suppression is state-keyed on this, so a progress
+// signal supersedes only a redundant `working` pulse — a later DISTINCT milestone pulse (committed /
+// landed / done) for the same task still reaches the spawner within the TTL instead of being dropped.
+export const LIFECYCLE_STATE_WORKING = "working";
+
+/** Subject key for a task-scoped lifecycle signal, keyed by semantic state so a signal about one
+ * state cannot suppress a pulse for a distinct state (#1038). The stamp and the check MUST pass the
+ * same `state` (the pulse's transition) to line up; omitting it keeps the legacy subject-only key. */
+export function taskSignalKey(taskId: number | string, state?: string, sha?: string): string {
+  return state ? `task:${taskId}::${state}${sha ? `::${sha}` : ""}` : `task:${taskId}`;
+}
+
+/** Subject key for a child-agent-scoped lifecycle signal (report-up / ready / exit about a child). */
+export function childSignalKey(childId: string): string {
+  return `child:${childId}`;
+}
+
+/** Record that a first-class lifecycle event just conveyed `subjectKey`'s state to `recipient`. */
+export function stampLifecycleSignal(recipient: string, subjectKey: string, now: number = Date.now()): void {
+  const rec = recipient.trim();
+  if (!rec || !subjectKey) return;
+  signals.set(compositeKey(rec, subjectKey), { at: now });
+  pruneExpired(now);
+}
+
+/** True when a lifecycle event stamped `subjectKey` for `recipient` within the TTL window. */
+export function hasRecentLifecycleSignal(
+  recipient: string,
+  subjectKey: string,
+  now: number = Date.now(),
+  ttlMs: number = DEFAULT_LIFECYCLE_SIGNAL_TTL_MS,
+): boolean {
+  const rec = recipient.trim();
+  if (!rec || !subjectKey) return false;
+  const key = compositeKey(rec, subjectKey);
+  const entry = signals.get(key);
+  if (!entry) return false;
+  if (now - entry.at > ttlMs) {
+    signals.delete(key);
+    return false;
+  }
+  return true;
+}
+
+function pruneExpired(now: number, ttlMs: number = DEFAULT_LIFECYCLE_SIGNAL_TTL_MS): void {
+  if (signals.size < 512) return; // amortized cleanup only when the map grows
+  for (const [key, entry] of signals) {
+    if (now - entry.at > ttlMs) signals.delete(key);
+  }
+}
+
+/** Reset seam: clear all recorded lifecycle signals (per-test / on a fresh relay DB). */
+export function __resetLifecycleSignals(): void {
+  signals.clear();
+}

package/src/live-runs-section.ts

@@ -0,0 +1,38 @@
+import { listScheduledTimers, type ScheduledTimer } from "./db";
+
+// #2882 — a clear/compact wipes the agent's memory of its own background `relay_run` runs and command
+// timers, so it concludes they died and starts duplicates. They are durable rows that outlive the
+// boundary and still wake the agent on completion; the continuation names them so nobody has to guess.
+const MAX_LISTED_RUNS = 10;
+const COMMAND_HEAD_CHARS = 80;
+
+function isLiveCommandTimer(timer: ScheduledTimer): boolean {
+  const status = timer.command?.status;
+  return timer.enabled && (status === "pending" || status === "running");
+}
+
+function commandHead(command: string): string {
+  const firstLine = command.trim().split("\n")[0]!.trim();
+  return firstLine.length > COMMAND_HEAD_CHARS ? `${firstLine.slice(0, COMMAND_HEAD_CHARS)}…` : firstLine;
+}
+
+function renderLiveRun(timer: ScheduledTimer): string {
+  const command = timer.command!;
+  const kind = command.via === "relay_run" ? "run" : "timer";
+  const started = command.startedAt ? `started ${new Date(command.startedAt).toISOString()}` : "queued";
+  const deadlineAt = command.startedAt && command.runTimeoutMs ? command.startedAt + command.runTimeoutMs : timer.nextRunAt;
+  return `- ${kind} ${timer.id} (${command.status}): \`${commandHead(command.command)}\` — ${started}, deadline ${new Date(deadlineAt).toISOString()}`;
+}
+
+/** The agent's still-live background commands, as a continuation section; "" when there are none. */
+export function renderLiveRunsSection(agentId: string): string {
+  const live = listScheduledTimers({ createdBy: agentId, limit: 500 }).filter(isLiveCommandTimer);
+  if (!live.length) return "";
+  const listed = live.slice(0, MAX_LISTED_RUNS).map(renderLiveRun);
+  const more = live.length - listed.length;
+  return [
+    "Your live background runs (relay_run / command timers). They survived the clear/compact and are still executing — do NOT restart them. Their completion still wakes you.",
+    ...listed,
+    ...(more > 0 ? [`- …and ${more} more (relay_list_timers)`] : []),
+  ].join("\n");
+}

package/src/loop-block-attribution.ts

@@ -0,0 +1,442 @@
+// Per-callsite on-loop-block attribution + the >50ms regression alarm — ADR 0001 §5 (Pillar 3),
+// S5 #1882. The other half of the event-loop-lag story: `event-loop-lag.ts` MEASURES a spike and
+// (via `setActivityAttributor`) names the maintenance JOB that overlapped it; this module names the
+// originating synchronous `file:line` / op — the STATEMENT half #1868/T1843 called "impossible to
+// debug".
+//
+// WHY THIS EXISTS NOW. Post-seam (S2/S3) the DB runs OFF the loop (writer thread + reader pool), so a
+// residual >50ms LOOP block is by construction NOT a DB call — a `db.read/write` is an `await` on an
+// off-thread result and never occupies the loop (ADR §5, H7). What CAN still block the loop is
+// synchronous CPU/fs BETWEEN awaits: a stray `*Sync` site that slipped the ratchet, or heavy in-loop
+// CPU. Such a block is anomalous, so it ALARMS as a regression (routed to the escalation sink), not a
+// passive `console.warn`. This is the runtime tripwire the S7 #1883 p99 loop-lag exit criterion needs.
+//
+// WHAT "async_hooks" MEANS HERE — and a Bun constraint that shaped the design. The natural mechanism
+// for automatic per-frame timing is `async_hooks.createHook`'s before/after. Bun (the server runtime)
+// does NOT implement those callbacks — verified on Bun 1.3.14: init/before/after never fire — so an
+// automatic per-frame monitor would be silent dead code in production. Bun DOES implement
+// `AsyncLocalStorage` (the reader pool already relies on it). So this module uses `async_hooks`
+// exactly where it works: `AsyncLocalStorage` to propagate the `{ callsite, op }` context through
+// `await`s, and it times the blocking frame EXPLICITLY at the instrumentation point
+// (`withLoopFrameCapture`) rather than via a global hook. General (uninstrumented) blocks are still
+// detected — by the existing loop-lag sampler — and alarm, just without a precise callsite until the
+// offending path is instrumented (the same incremental "build-time file:line on hot paths" model as
+// ADR §11.2).
+//
+// THE ATTRIBUTION MODEL — time-overlap, NOT a single "currently-executing op" register (ADR §5 H7
+// dropped that as mis-modeling async concurrency: many ops are in flight at once and none blocks the
+// caller). Each recorded synchronous frame carries a WALL interval; the lag attributor reports the
+// frames OVERLAPPING a spike's [gapStart, gapEnd) window — exactly the overlap approach
+// `event-loop-lag.ts` already uses for maintenance runs.
+//
+// SURVIVING THE GATEWAY HOP. The context is an `AsyncLocalStorage` payload, so it propagates through
+// `await`s and nests: a request that establishes `{ callsite }` at its boundary still has that context
+// in scope when it later calls the gateway, so `withLoopFrameCapture` falls back to the ORIGINATING
+// request callsite when the immediate op did not carry one — never attributing to the gateway boundary
+// (the task's explicit requirement).
+//
+// TWO CAPTURE / DETECTION SOURCES feed ONE alarm, deduped so one physical block pages once:
+//   1. `withLoopFrameCapture` (PRECISE) — times the SYNCHRONOUS portion of an instrumented call. The
+//      gateway facade wraps every op in it: for the in-process backend (today's default) the op body
+//      runs synchronously on the loop, so this captures it EXACTLY, tagged with the op name — the
+//      dominant current-world on-loop block. For the worker backend it captures only the negligible
+//      enqueue (below the record floor), so the off-thread wait is never mis-attributed. Fires the
+//      alarm at the exact frame boundary, with the precise callsite.
+//   2. `reportLagRegression` (BACKSTOP) — driven by the loop-lag sampler via a registered observer on
+//      `event-loop-lag.ts`. Catches ANY >50ms block, including uninstrumented ones the precise source
+//      never saw; attributes it from whatever recorded frames overlap the spike window (or reports it
+//      unattributed). Deduped against the precise source so a captured op is not double-alarmed.
+//
+// IMPORT DIRECTION (load-bearing, same rule as event-loop-lag.ts's own seams): `event-loop-lag.ts` is
+// a low-level primitive that must never import its callers, so THIS module registers its callsite view
+// and its regression observer ON it (via `setCallsiteAttributor` / `setLagRegressionObserver`).
+// `event-loop-lag.ts` imports nothing from here.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  ON_LOOP_BLOCK_RECORD_MS,
+  ON_LOOP_BLOCK_REGRESSION_MS,
+  ON_LOOP_BLOCK_RING_SIZE,
+} from "./config.ts";
+import { setCallsiteAttributor, setLagRegressionObserver, setOnLoopAttributor } from "./event-loop-lag.ts";
+import type { LoopGapDiagnosis } from "./main-thread-clock.ts";
+
+/**
+ * The attribution context propagated through `await`s. `callsite` is a build-time `file:line` (ADR
+ * §11.2 — per-op `Error().stack` is too costly at message rate, so a pre-computed string is the hot-
+ * path signal); `op` is the executing SQL / operation label. Either may be absent.
+ */
+export interface LoopCallsiteContext {
+  callsite?: string;
+  op?: string;
+}
+
+export const loopCallsiteStore = new AsyncLocalStorage<LoopCallsiteContext>();
+
+/**
+ * One recorded synchronous execution frame that occupied the loop for `durationMs`. `startAt`/`endAt`
+ * are WALL instants (`Date.now()`-based) so they overlap-compare against the lag sampler's own
+ * `Date.now()` gap window; `durationMs` is the MONOTONIC (`performance.now`) measured on-loop time —
+ * the value the record/regression thresholds are keyed on. `startAt` is derived as `endAt - durationMs`
+ * (the one disclosed clock-mixing assumption `event-loop-lag.ts` already documents: an NTP step or
+ * host suspend between the two reads could mis-size the window; no behaviour hinges on sub-ms accuracy).
+ */
+export interface LoopBlockFrame {
+  callsite?: string;
+  op?: string;
+  startAt: number;
+  endAt: number;
+  durationMs: number;
+}
+
+/** The >50ms regression signal handed to the alarm observer. `overlapping` carries the OTHER recorded
+ *  frames that overlap this block — so a sampler-backstop regression (which has no callsite of its own)
+ *  can still be attributed from the precise frames nested inside its window. `source` distinguishes the
+ *  exact frame capture from the sampler backstop.
+ *
+ *  #1975 — `attributedOnLoopMs` is the QUANTITATIVE half: how many of `durationMs` are actually measured
+ *  ON-LOOP JS, as opposed to WALL time the process spent frozen for a reason that executed no JS (host
+ *  swap, page fault, a multi-second GC pause). It is the same signal #1974 wired into the `/health` warn
+ *  (`sumLoopFrameMsOverlapping`, capped at the wall lag), carried on the event so the alarm POLICY can
+ *  tell a genuine on-loop block from a host stall. `durationMs` alone cannot: a `[sampler]` wall-gap
+ *  prints multi-second durations and borrows the label of whatever frame merely OVERLAPPED it. */
+export interface LoopBlockRegression extends LoopBlockFrame {
+  thresholdMs: number;
+  source: "frame" | "sampler";
+  attributedOnLoopMs: number;
+  overlapping: readonly LoopBlockFrame[];
+  /** #3037 — sampler source only: the main-thread clock verdict over the gap. */
+  diagnosis?: LoopGapDiagnosis;
+}
+
+/** The escalation seam (ADR §5 "wired to the same escalation sink the offload StrikeCounter feeds").
+ *  Registered in production wiring; unset in a plain unit context (then the alarm is inert). */
+export type LoopBlockRegressionObserver = (event: LoopBlockRegression) => void;
+
+// ── State ─────────────────────────────────────────────────────────────────────────────────────────
+
+const ring: LoopBlockFrame[] = [];
+let regressionObserver: LoopBlockRegressionObserver | undefined;
+// The last block that FIRED an alarm — its interval AND which source raised it. Used ONLY for
+// ACROSS-source dedup (see `maybeAlarm`): the precise frame source and the sampler backstop can both
+// detect the SAME physical block, so the second of the two is suppressed.
+let lastAlarm: { startAt: number; endAt: number; source: LoopBlockRegression["source"] } | undefined;
+
+export function setOnLoopBlockRegressionObserver(fn: LoopBlockRegressionObserver | undefined): void {
+  regressionObserver = fn;
+}
+
+function framesOverlap(aStart: number, aEnd: number, bStart: number, bEnd: number): boolean {
+  return aStart < bEnd && aEnd > bStart;
+}
+
+/** Record a synchronous frame into the overlap ring (dropping ones below the record floor) and, when it
+ *  crosses the regression threshold, fire the precise alarm. PURE w.r.t. clocks (all instants passed
+ *  in), so the record/overlap/dedup/alarm logic is unit-testable without real timers. */
+export function recordLoopFrame(frame: LoopBlockFrame): void {
+  if (!Number.isFinite(frame.durationMs) || frame.durationMs < ON_LOOP_BLOCK_RECORD_MS) return;
+  pushFrame(frame);
+  if (frame.durationMs >= ON_LOOP_BLOCK_REGRESSION_MS) {
+    maybeAlarm({
+      ...frame,
+      thresholdMs: ON_LOOP_BLOCK_REGRESSION_MS,
+      source: "frame",
+      // A precise frame IS measured on-loop time by construction (`captureSyncFrame` times the
+      // SYNCHRONOUS portion of an instrumented call), so all of it is attributed. #1975's host-stall
+      // gate therefore never suppresses a frame-source regression.
+      attributedOnLoopMs: frame.durationMs,
+      overlapping: [],
+    });
+  }
+}
+
+function pushFrame(frame: LoopBlockFrame): void {
+  ring.push(frame);
+  // Bounded ring: drop the oldest once over capacity. Residual blocks are rare post-seam, so this is a
+  // diagnostic overlap buffer, not a metrics store — old frames have no value once their window passes.
+  while (ring.length > ON_LOOP_BLOCK_RING_SIZE) ring.shift();
+}
+
+/**
+ * The sampler backstop (ADR §5). Called via `event-loop-lag.ts`'s regression observer when a lag sample
+ * crossed `ON_LOOP_BLOCK_REGRESSION_MS`. Dedupes against a precise frame that already alarmed for the
+ * same physical block, then fires — attributed from whatever recorded frames overlap [gapStartAt,
+ * gapEndAt). All instants passed in → clock-pure and unit-testable.
+ */
+export function reportLagRegression(gapStartAt: number, gapEndAt: number, lagMs: number, diagnosis?: LoopGapDiagnosis): void {
+  // ATTRIBUTION uses the WIDE diagnostic window [gapStartAt, gapEndAt] (the sampler builds it one tick
+  // spacing wider than the freeze, deliberately inclusive) so a frame anywhere in it is captured.
+  const overlapping = loopFramesOverlapping(gapStartAt, gapEndAt);
+  // The most-blocking overlapping frame lends its callsite to an otherwise-anonymous sampler spike.
+  const attributed = overlapping[0];
+  // DEDUP uses the TIGHT freeze window [gapEndAt - lagMs, gapEndAt] — the actual block interval, not the
+  // ~1s-wider diagnostic window — for the same reason the breaker actuator does (event-loop-lag.ts): a
+  // wide interval would over-suppress a genuinely SEPARATE precise block that happened elsewhere in the
+  // same sampler tick.
+  const freezeStartAt = gapEndAt - Math.max(0, lagMs);
+  // #1975 — the ON-LOOP portion of this wall gap: the SAME quantity `sumLoopFrameMsOverlapping` hands the
+  // #1974 health warn (sum of the overlapping frames, capped at the wall lag — on-loop work can never
+  // exceed the gap it was measured over), computed here from the overlap set already in hand. A pure host
+  // stall (swap/GC/page-fault) executes no JS, overlaps no frames, and correctly sums to 0.
+  const attributedOnLoopMs = Math.min(
+    Math.max(0, lagMs),
+    overlapping.reduce((total, frame) => total + frame.durationMs, 0),
+  );
+  maybeAlarm({
+    callsite: attributed?.callsite,
+    op: attributed?.op,
+    startAt: freezeStartAt,
+    endAt: gapEndAt,
+    durationMs: lagMs,
+    thresholdMs: ON_LOOP_BLOCK_REGRESSION_MS,
+    source: "sampler",
+    attributedOnLoopMs,
+    overlapping,
+    ...(diagnosis ? { diagnosis } : {}),
+  });
+}
+
+/**
+ * Fire the regression alarm, deduping ONLY across sources — never frame-vs-frame (nor sampler-vs-
+ * sampler). The precise frame source and the sampler backstop can both detect the SAME physical block
+ * (the frame fires at the block boundary; the sampler tick lands later and re-measures the same lag),
+ * so whichever arrives second and overlaps the first is suppressed.
+ *
+ * Frame-vs-frame is DELIBERATELY not deduped (r2-review MED): one precise frame IS one physical block by
+ * construction, so two frames are two blocks and BOTH must alarm/strike — exactly the convoy case S5
+ * exists to catch. The old frame-vs-frame overlap check silently swallowed a back-to-back block ~37/40
+ * runs because each frame's interval is DERIVED (`endAt - durationMs`, mixing `Date.now()` ms
+ * granularity with a `performance.now()` float), so consecutive frames overlapped by sub-ms clock slop.
+ * Keying dedup on source instead of a tightened interval removes that clock-slop dependency entirely.
+ *
+ * Nested capture sites (#3037: a route frame enclosing gateway frames) stay one-block-per-frame because
+ * `timeFrame` records each frame's EXCLUSIVE time: the outer frame never re-counts its children.
+ */
+function maybeAlarm(event: LoopBlockRegression): void {
+  const crossSourceDuplicate =
+    lastAlarm !== undefined &&
+    lastAlarm.source !== event.source &&
+    framesOverlap(event.startAt, event.endAt, lastAlarm.startAt, lastAlarm.endAt);
+  if (crossSourceDuplicate) {
+    // Same physical block via the other source — keep the FIRST source's identity (so a later same-
+    // source event still alarms) and widen the interval to the union so the whole block stays covered.
+    lastAlarm = {
+      startAt: Math.min(lastAlarm!.startAt, event.startAt),
+      endAt: Math.max(lastAlarm!.endAt, event.endAt),
+      source: lastAlarm!.source,
+    };
+    return;
+  }
+  lastAlarm = { startAt: event.startAt, endAt: event.endAt, source: event.source };
+  fireRegression(event);
+}
+
+function fireRegression(event: LoopBlockRegression): void {
+  if (!regressionObserver) return;
+  // A precise (frame-source) alarm computes its overlapping set lazily here so the common no-observer
+  // case pays nothing; the sampler source already carries its overlapping set.
+  const enriched =
+    event.source === "frame"
+      ? { ...event, overlapping: loopFramesOverlapping(event.startAt, event.endAt) }
+      : event;
+  // The observer does real work (write a strike, notify). It runs synchronously inside a capture-layer
+  // finally / the sampler timer callback, so a throw here would surface in unrelated code — guard it,
+  // for the same reason event-loop-lag.ts guards the breaker observer: the tripwire degrading is never
+  // worth breaking the code path it happened to fire under.
+  try {
+    regressionObserver(enriched);
+  } catch {
+    // Deliberately swallowed — a broken alarm sink must not break the request that tripped it.
+  }
+}
+
+// ── Attribution query (registered into event-loop-lag.ts) ──────────────────────────────────────────
+
+/** The recorded frames overlapping [gapStartAt, gapEndAt), most-blocking first. */
+export function loopFramesOverlapping(gapStartAt: number, gapEndAt: number): LoopBlockFrame[] {
+  return ring
+    .filter((frame) => framesOverlap(frame.startAt, frame.endAt, gapStartAt, gapEndAt))
+    .sort((a, b) => b.durationMs - a.durationMs);
+}
+
+/**
+ * #1974 — total ON-LOOP-JS milliseconds recorded over [gapStartAt, gapEndAt): the SUM of the
+ * overlapping frames' measured durations. This is the quantitative signal the event-loop-lag health
+ * warn gates on (registered via `setOnLoopAttributor`).
+ *
+ * SUM (not max single frame): a convoy of genuine sub-block frames that together occupied the loop for
+ * ≥250ms is a real on-loop block and MUST warn, so their durations add. Summing does not double-count —
+ * the loop runs frames strictly one at a time, and the capture sites do not nest (see `maybeAlarm`'s
+ * precondition), so within one spike window the frames are sequential and disjoint. The caller
+ * (`event-loop-lag.ts`) additionally CAPS the result at the wall lag, so even a frame that straddles the
+ * window edge can never attribute more on-loop time than the spike actually measured. A pure host stall
+ * (swap/GC/page-fault) executes no JS, records no frames, and correctly sums to 0.
+ */
+export function sumLoopFrameMsOverlapping(gapStartAt: number, gapEndAt: number): number {
+  let total = 0;
+  for (const frame of ring) {
+    if (framesOverlap(frame.startAt, frame.endAt, gapStartAt, gapEndAt)) total += frame.durationMs;
+  }
+  return total;
+}
+
+/** A frame's human label: `op@callsite`, or whichever of the two exists, else `unattributed`. */
+export function describeFrameLabel(frame: Pick<LoopBlockFrame, "callsite" | "op">): string {
+  if (frame.op && frame.callsite) return `${frame.op}@${frame.callsite}`;
+  return frame.op ?? frame.callsite ?? "unattributed";
+}
+
+// At most this many frames are named in the sampler's single-line spike clause; the rest are summarized
+// as a count so a convoy of small frames does not blow the log line.
+const MAX_NAMED_CALLSITES = 3;
+
+/**
+ * The clause `event-loop-lag.ts`'s spike log appends via `setCallsiteAttributor`. Returns undefined
+ * when nothing was recorded over the window (so the log line simply omits it), else e.g.
+ * `on-loop block ≥5ms: messages.send@src/db/messages.ts:755 (52ms), <cpu>@src/x.ts:9 (7ms)`.
+ */
+export function describeLoopCallsites(gapStartAt: number, gapEndAt: number): string | undefined {
+  const frames = loopFramesOverlapping(gapStartAt, gapEndAt);
+  if (frames.length === 0) return undefined;
+  const named = frames
+    .slice(0, MAX_NAMED_CALLSITES)
+    .map((frame) => `${describeFrameLabel(frame)} (${Math.round(frame.durationMs)}ms)`);
+  const overflow = frames.length - named.length;
+  const suffix = overflow > 0 ? `, +${overflow} more` : "";
+  return `on-loop block ≥${Math.round(ON_LOOP_BLOCK_RECORD_MS)}ms: ${named.join(", ")}${suffix}`;
+}
+
+// ── Capture: explicit synchronous frame timing ─────────────────────────────────────────────────────
+
+/** Merge a call's own context over the ambient one: the specific op/callsite wins, but a field the call
+ *  omits falls back to the ORIGINATING (ambient) context — so a gateway op called inside a request that
+ *  set a request-level callsite is attributed to the request, never dropped to "unattributed". */
+function mergeAmbient(ctx: LoopCallsiteContext): LoopCallsiteContext {
+  const ambient = loopCallsiteStore.getStore();
+  if (!ambient) return ctx;
+  return { op: ctx.op ?? ambient.op, callsite: ctx.callsite ?? ambient.callsite };
+}
+
+/**
+ * Time the SYNCHRONOUS portion of `fn` and, if it blocked at/above the record floor, record a frame
+ * tagged with `ctx` EXACTLY — no ambient merge. `fn`'s return value (a Promise, for the gateway) is
+ * passed straight through untouched; only its synchronous creation/execution is timed.
+ *
+ * This core deliberately does NOT read the callsite store, so it is safe to call from a place where the
+ * ambient context belongs to some OTHER caller — notably the writer drain microtask, which processes
+ * many callers' entries under whichever caller first kicked the drain. Callers that WANT the ambient
+ * (request-level) callsite folded in must resolve it into `ctx` first, in their own context — see
+ * `resolveLoopCallsite` (at submission time) and `withLoopFrameCapture` (inline).
+ */
+export function captureSyncFrame<T>(ctx: LoopCallsiteContext, fn: () => T): T {
+  return timeFrame(ctx, false, undefined, fn, undefined, NO_ARGS) as T;
+}
+
+// #3037 — frames nest (a route frame encloses its gateway and SQL frames). Each frame records only its
+// EXCLUSIVE time, so the overlap sum and the alarm count each loop ms once; a child below the record
+// floor leaves its time with the parent, so many small statements still add up to a named frame.
+let frameDepth = 0;
+let openFrameChildMs = 0;
+let openCtx: LoopCallsiteContext | undefined;
+let openFold = false;
+const NO_ARGS: ArrayLike<unknown> = [];
+
+type FrameCall = (...values: unknown[]) => unknown;
+
+function timeFrame(ctx: LoopCallsiteContext | undefined, foldAmbient: boolean, sqlOp: (() => string) | undefined, fn: FrameCall, self: unknown, args: ArrayLike<unknown>): unknown {
+  const parentChildMs = openFrameChildMs;
+  const parentCtx = openCtx;
+  const parentFold = openFold;
+  openFrameChildMs = 0;
+  openCtx = ctx;
+  openFold = foldAmbient;
+  frameDepth += 1;
+  const startPerf = performance.now();
+  try {
+    return fn.apply(self, args as unknown[]);
+  } finally {
+    const totalMs = performance.now() - startPerf;
+    const childMs = openFrameChildMs;
+    const selfMs = totalMs - childMs;
+    const recorded = selfMs >= ON_LOOP_BLOCK_RECORD_MS;
+    frameDepth -= 1;
+    openCtx = parentCtx;
+    openFold = parentFold;
+    openFrameChildMs = frameDepth === 0 ? 0 : parentChildMs + (recorded ? totalMs : childMs);
+    if (recorded) {
+      // Still synchronous in the caller's frame, so the ambient read here equals one taken at entry.
+      const label = sqlOp ? sqlFrameLabel(sqlOp(), frameDepth > 0 ? frameLabel(parentCtx, parentFold) : loopCallsiteStore.getStore())
+        : frameLabel(ctx, foldAmbient)!;
+      const endAt = Date.now();
+      recordLoopFrame({ callsite: label.callsite, op: label.op, startAt: endAt - totalMs, endAt, durationMs: selfMs });
+    }
+  }
+}
+
+function frameLabel(ctx: LoopCallsiteContext | undefined, foldAmbient: boolean): LoopCallsiteContext | undefined {
+  return ctx && foldAmbient ? mergeAmbient(ctx) : ctx;
+}
+
+/** A SQL frame is named by its statement head, and sits under whatever frame or request it ran in. */
+function sqlFrameLabel(op: string, parent: LoopCallsiteContext | undefined): LoopCallsiteContext {
+  return { op, callsite: parent && (parent.op || parent.callsite) ? describeFrameLabel(parent) : undefined };
+}
+
+/** #3037 — time one synchronous SQL call as a leaf frame; `op` is resolved only when the frame records.
+ *  Takes the call's `fn`/`self`/`args` so the per-statement hot path allocates nothing. */
+export function captureSqlFrame(op: () => string, fn: FrameCall, self: unknown, args: ArrayLike<unknown>): unknown {
+  return timeFrame(undefined, false, op, fn, self, args);
+}
+
+/**
+ * The effective loop callsite for a call: its explicit `file:line` if given, else the ambient
+ * request-level callsite the enclosing `runWithLoopCallsite` scope propagated across `await`s. Resolve
+ * this in the CALLER's context — synchronously, BEFORE any thread hop or microtask defer — so a later
+ * drain never captures a different caller's ambient. This is how write attribution survives the gateway
+ * hop: the write op body runs in a microtask (`kickDrain`), long after the caller's context is gone, so
+ * the callsite must be pinned onto the submission at submission time.
+ */
+export function resolveLoopCallsite(explicit?: string): string | undefined {
+  return explicit ?? loopCallsiteStore.getStore()?.callsite;
+}
+
+/**
+ * Inline timing for a call whose op body runs SYNCHRONOUSLY in the caller's own frame (the reader
+ * facade path). Folds the ambient request-level context in (via `mergeAmbient`, read here in the
+ * caller's context) then times + records. Deliberately does NOT open an `AsyncLocalStorage` scope —
+ * that would add a `run()` to the DB hot path for no gain.
+ */
+export function withLoopFrameCapture<T>(ctx: LoopCallsiteContext, fn: () => T): T {
+  return timeFrame(ctx, true, undefined, fn, undefined, NO_ARGS) as T;
+}
+
+/** Establish a loop-callsite context for a whole async scope (e.g. a request handler) so that
+ *  `withLoopFrameCapture` calls nested under it inherit the ORIGINATING callsite when they omit one —
+ *  the mechanism that makes attribution survive the gateway hop. This is the ONLY entry point that
+ *  opens an `AsyncLocalStorage` scope (once per request), so it does not belong on the per-op DB path.
+ *  Does not itself time a frame. */
+export function runWithLoopCallsite<T>(ctx: LoopCallsiteContext, fn: () => T): T {
+  return loopCallsiteStore.run(mergeAmbient(ctx), fn);
+}
+
+// #1882 — register the SECOND event-loop-lag attributor + the sampler regression observer at module
+// load (same unconditional-registration pattern as the maintenance run-registry's
+// `setActivityAttributor`): both only ever report what is ACTUALLY in the ring / the sample, so in a
+// mode where nothing blocked they correctly report nothing.
+setCallsiteAttributor((gapStartAt, gapEndAt) => describeLoopCallsites(gapStartAt, gapEndAt));
+setLagRegressionObserver((gapStartAt, gapEndAt, lagMs, diagnosis) => reportLagRegression(gapStartAt, gapEndAt, lagMs, diagnosis));
+// #1974 — the quantitative attributor the attribution-aware health warn reads (see `event-loop-lag.ts`).
+setOnLoopAttributor((gapStartAt, gapEndAt) => sumLoopFrameMsOverlapping(gapStartAt, gapEndAt));
+
+/** Test hook — clears the ring and the dedup latch so one test's recorded frames can't leak into
+ *  another's attribution (the same module-level-state hazard the event-loop-lag ring and the
+ *  maintenance run-registry both guard). The registrations stay in place; they read the (now-empty)
+ *  ring live. Does NOT clear the regression observer — a test that installs one owns clearing it. */
+export function resetLoopBlockAttributionForTests(): void {
+  ring.length = 0;
+  lastAlarm = undefined;
+  frameDepth = 0;
+  openFrameChildMs = 0;
+  openCtx = undefined;
+  openFold = false;
+}