@preventive/triage 1.0.0-alpha.1 → 1.0.0-alpha.3

package/server/hub.ts

@@ -102,12 +102,11 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   }
 
   function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
-    // Snapshot before iterating — `send`'s try/catch swallows
-    // socket.send errors, but a socket transitioning to CLOSED
+    // Snapshot before iterating — a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
-    // which mutates `set` while we're walking it. The snapshot keeps a
-    // future refactor (different collection, async send) from silently
-    // skipping subscribers. Audit M4 round-3.
+    // mutating `set` while we walk it. The snapshot also keeps a future
+    // refactor (different collection, async send) from silently skipping
+    // subscribers. Audit M4 round-3.
     for (const s of [...set]) {
       if (s === except) continue
       sendRaw(s, payload)

package/server/index.ts

@@ -97,8 +97,8 @@ import {
 import { createBusReceiver } from './bus-receiver.ts'
 
 // All external inputs (env vars + optional config.json) are parsed
-// and validated in ./config.ts. Destructure into the existing
-// uppercase names so the rest of this module reads unchanged.
+// and validated in ./config.ts; destructure into the uppercase names
+// the rest of this module uses.
 const config = loadConfig()
 const {
   port: PORT, host: HOST, dbPath: DB_PATH, objstoreDir: OBJSTORE_DIR,
@@ -109,8 +109,8 @@ const {
 } = config
 
 // Same-origin gate for the WS upgrade and REST data plane (see
-// ./origin.ts). `TRUST_PROXY_ENV` (from config) also feeds the
-// boot-time misconfiguration fail-fast below.
+// ./origin.ts). `TRUST_PROXY_ENV` also feeds the boot-time
+// misconfiguration fail-fast below.
 const { trustProxy: TRUST_PROXY, isOriginAllowed } = createOriginGate(HOST, TRUST_PROXY_ENV)
 
 // Per-socket buffered-bytes cap. `socket.send` returns synchronously
@@ -131,10 +131,9 @@ const MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 
 // Per-connection state registry. One `Peer` per accepted socket holds
 // the challenge nonce, auth flag, heartbeat liveness, in-flight count,
-// and subscribed tags (see ./peer.ts) — replacing what were five
-// parallel per-socket WeakMaps. The connection handler holds the Peer
-// in a closure for the hot paths; cross-function call sites resolve it
-// via `peers.get(socket)`.
+// and subscribed tags (see ./peer.ts). The connection handler holds
+// the Peer in a closure for the hot paths; cross-function call sites
+// resolve it via `peers.get(socket)`.
 const peers: PeerRegistry = new WeakMap()
 
 // REST PUT idle-body timeout. A slow-loris client trickling bytes
@@ -163,8 +162,8 @@ const REST_PUT_IDLE_TIMEOUT_MS = 30_000
 const HEARTBEAT_INTERVAL_MS = 30_000
 
 // Backend selection. Both planes (workspace_revision DB + the
-// v1.objstore byte store) are picked from config at boot. Two supported
-// pairings:
+// v1.objstore byte store) are picked from config at boot. Two
+// supported pairings:
 //   1. DATABASE_URL set → Neon (workspace_revision + objstore
 //      tables) + Vercel Blob Private Storage (bytes). Requires
 //      BLOB_READ_WRITE_TOKEN — fail fast at boot if missing, since
@@ -174,11 +173,10 @@ const HEARTBEAT_INTERVAL_MS = 30_000
 //      process; the only pairing the SQLite plane supports.
 // The Neon / Vercel files import their peer deps lazily inside the
 // open functions, so static imports here are safe even on a SQLite-
-// only install where the optional peer deps aren't present. Branch
-// out explicitly (rather than via a ternary) so the SQLite path
-// keeps its `SqliteHandle` narrowing — `sqliteHandle.db` is typed
-// as a non-optional `DatabaseSync` and `openObjstore` accepts it
-// without a non-null assertion.
+// only install where the optional peer deps aren't present. Explicit
+// branch (not a ternary) so the SQLite path keeps its `SqliteHandle`
+// narrowing — `sqliteHandle.db` is a non-optional `DatabaseSync` that
+// `openObjstore` accepts without a non-null assertion.
 let handle: Handle
 let objstoreHandle: ObjstoreHandle
 let objstoreBanner: string
@@ -238,8 +236,7 @@ async function workspaceExists(tag: string): Promise<boolean> {
 }
 
 // WS fan-out hub: subscriber registry + backpressure-aware send /
-// broadcast (see ./hub.ts). Destructure into the existing names so the
-// handlers / dispatcher / objstore wiring below read unchanged.
+// broadcast (see ./hub.ts).
 const hub = createHub({ peers, maxBufferedBytes: MAX_BUFFERED_BYTES, debug: DEBUG })
 const { send, broadcast, subscribe, unsubscribeAll, broadcastLocalRaw } = hub
 
@@ -276,7 +273,7 @@ if (NEON_URL) {
 }
 
 // Password gate (see ./auth.ts) — HMAC derivation + the `authenticate`
-// handshake. Destructure into the existing names for the wiring below.
+// handshake.
 const auth = createAuth({ peers, password: CONFIG_PASSWORD, send, debug: DEBUG })
 const { requiresAuth, handleAuthenticate, sendUnauthorized } = auth
 
@@ -320,8 +317,8 @@ const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper
   sendUnauthorized,
   // `tokenSecret` is set only when OBJSTORE_TOKEN_SECRET was
   // provided in env (see TOKEN_SECRET resolution above). Omitted
-  // → initObjstore mints a fresh per-process secret (the pre-PR
-  // behaviour, fine for single-replica).
+  // → initObjstore mints a fresh per-process secret (fine for
+  // single-replica).
   ...(TOKEN_SECRET ? { tokenSecret: TOKEN_SECRET } : {}),
 })
 
@@ -452,11 +449,29 @@ installLifecycle({
 
 // Bind only after the startup orphan sweep finishes — otherwise a
 // fresh boot could serve traffic against tags whose on-disk state
-// still has residue from a prior crash. Top-level await is fine
-// for an entry-point ESM module (no other module imports this for
-// its exports — the side effect IS the program). `startupReap`
-// already resolves on any error (the reaper's own catch logs the
-// failure unconditionally and returns void), so no outer `.catch`
-// is needed here.
+// still has residue from a prior crash. `startupReap` already
+// resolves on any error (the reaper's own catch logs the failure
+// unconditionally and returns void), so no outer `.catch` is
+// needed here.
 await startupReap
-httpServer.listen(PORT, HOST)
+
+// Bind the HTTP/WS plane on the configured PORT/HOST. Exported so a
+// launcher (server/cli.js — the triage-server bin) or any `import`er can
+// start serving. The top-level `await startupReap` above means the server
+// is fully ready — DB open, DDL bootstrapped, objstore reaper swept — by
+// the time the import resolves.
+export function start(): void {
+  httpServer.listen(PORT, HOST)
+}
+
+export { httpServer, wss }
+
+// Library mode: when this module is `import`ed (rather than run as the
+// entry script) skip the auto-start so consumers can own the bind — e.g.
+// wrap CF Access / framework-preset shims around the assembled
+// `httpServer`, or just call `start()` when ready. Direct invocation via
+// `node server/index.ts` (or the `triage-server` bin) still listens.
+if (import.meta.main) {
+  start()
+}
+

package/server/lifecycle.ts

@@ -46,7 +46,12 @@ export function createLifecycle(): Lifecycle {
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    promise.finally(() => inFlight.delete(promise))
+    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
+    // propagates through its returned promise — without it, a tracked
+    // handler that rejects (or whose caller's catch handler itself
+    // throws) trips the `unhandledRejection` catchall below and crashes
+    // the process via `fireShutdown(1)`.
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
   // Live exit code the in-progress shutdown will pass to `process.exit`.

package/server/objstore/blob-fs.ts

@@ -90,12 +90,10 @@ export function openFsBlobBackend(dir: string): BlobBackend {
         // closed by Node's stream machinery on 'finish'.
         finalize: async () => {},
         // `destroy(err)` synchronously starts tearing the stream
-        // down; the WriteStream emits 'close' on the next tick.
-        // For the FS backend there's no remote upload to wait for,
-        // so we resolve immediately — the REST layer awaits but
-        // doesn't block on anything real here. eslint-disable for
-        // the no-await-in-async — the function signature is
-        // dictated by the BlobBackend contract.
+        // down; the WriteStream emits 'close' on the next tick. No
+        // remote upload to wait for on FS, so we resolve immediately
+        // — the REST layer awaits but doesn't block on anything real.
+        // Async signature is dictated by the BlobBackend contract.
         // eslint-disable-next-line require-await
         abort: async (err) => { writable.destroy(err as Error) },
       }

package/server/objstore/blob-vercel.ts

@@ -119,21 +119,19 @@ type VercelBlobSdk = {
 
 // Recognise "blob is gone" errors uniformly across read/write/delete
 // paths so callers can treat them as success (delete) or
-// not-found (read). The SDK exposes BlobNotFoundError as a class
-// with `.name === 'BlobNotFoundError'`; checking the name string
-// avoids importing the class at the top level (which would force
-// the optional peer dep to resolve).
+// not-found (read). The SDK exposes BlobNotFoundError as a class with
+// `.name === 'BlobNotFoundError'`; checking the name string avoids
+// importing the class at the top level (which would force the optional
+// peer dep to resolve).
 //
-// Class-name check ONLY. The SDK's internal mapper translates every
-// API `not_found` code into BlobNotFoundError-by-name; a bare-404
-// transport leak doesn't reach here. A prior version of this
-// function had a `/does not exist|\b404\b/` fallback that
-// DANGEROUSLY matched BlobStoreNotFoundError's message "This store
-// does not exist." — a config fault (revoked token, deleted store)
-// would silently surface as every-blob-missing across reads and
-// unlinks, masking the fatal misconfiguration. The tight name check
-// lets BlobStoreNotFoundError / other classes propagate as real
-// exceptions.
+// Class-name check ONLY — the SDK's internal mapper turns every API
+// `not_found` into BlobNotFoundError-by-name, so a bare-404 transport
+// leak doesn't reach here. A broader `/does not exist|\b404\b/` match
+// is DANGEROUS: it also matches BlobStoreNotFoundError's "This store
+// does not exist.", so a config fault (revoked token, deleted store)
+// would silently surface as every-blob-missing across reads/unlinks,
+// masking the fatal misconfiguration. The tight name check lets
+// BlobStoreNotFoundError / other classes propagate as real exceptions.
 function isNotFound(err: unknown): boolean {
   if (err == null || typeof err !== 'object') return false
   const name = (err as { name?: unknown }).name
@@ -242,20 +240,17 @@ function buildOpenStagingWriter(sdk: VercelBlobSdk, token: string): BlobBackend[
       abortSignal: ac.signal,
     })
     // Defuse a possible unhandled-rejection if abort() is called
-    // BEFORE finalize() (the REST layer's error path). Attach a
-    // detached `.catch` on the original promise so an early
-    // rejection has a handler; finalize() awaits `putPromise`
-    // directly, which still re-throws the original rejection
-    // (the .catch returns a separate chain that doesn't replace
-    // putPromise's state).
+    // BEFORE finalize() (the REST error path). The detached `.catch`
+    // gives an early rejection a handler; finalize() still awaits
+    // `putPromise` directly and re-throws the original rejection (the
+    // .catch is a separate chain, not a replacement of putPromise).
     putPromise.catch(() => {})
     return {
       writable: pt,
       // Await the upload's completion. After pipeline(req, counter,
-      // pt) resolves, pt has emitted 'end' on the read side and
-      // `put` is finalising the last multipart part. Awaiting here
-      // gives us the same "bytes durable" guarantee that
-      // pipeline-to-WriteStream gives the FS backend.
+      // pt) resolves, pt has emitted 'end' and `put` is finalising the
+      // last multipart part. Awaiting here gives the same "bytes
+      // durable" guarantee pipeline-to-WriteStream gives the FS backend.
       finalize: async () => { await putPromise },
       // Await the SDK's put-promise settlement (rejected via the
       // AbortController). Without this await, a slow upload that
@@ -315,11 +310,11 @@ function buildPromoteStagingToLive(sdk: VercelBlobSdk, token: string): BlobBacke
       //
       // `allowOverwrite: true` because the content-addressed live
       // pathname `${tag}/${contentHash}.bin` can be (re)written by a
-      // retried or racing promote of the same blob. The destination
-      // bytes are identical by construction (the path IS the hash), so
-      // the overwrite is idempotent — never a clobber of DIFFERENT
-      // bytes. Without the flag, the SDK sends `x-allow-overwrite: 0`
-      // and Vercel rejects any such re-promote with BlobAccessError.
+      // retried or racing promote of the same blob. Destination bytes
+      // are identical by construction (the path IS the hash), so the
+      // overwrite is idempotent — never a clobber of DIFFERENT bytes.
+      // Without the flag the SDK sends `x-allow-overwrite: 0` and
+      // Vercel rejects the re-promote with BlobAccessError.
       await sdk.copy(from, to, {
         access: 'private',
         allowOverwrite: true,
@@ -356,17 +351,55 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
     // origin truth. Origin fetch is the right default for a store
     // where freshness > latency.
     try { res = await sdk.get(path, { access: 'private', useCache: false, token }) } catch (err) {
-      if (isNotFound(err)) return { ok: false, reason: 'not-found' }
+      // A missing blob HERE is never "the resource doesn't exist" — the
+      // REST layer (rest.ts openLiveSnapshot) already confirmed a live row
+      // whose (version, incarnation) matches the GET token before calling
+      // us. So BlobNotFoundError means the bytes for a still-live row are
+      // momentarily gone: the reaper GC'd a hash a racing version-bump just
+      // unreferenced, or Vercel's read-after-write / edge propagation hasn't
+      // caught up to a freshly-promoted private blob. That is the documented
+      // `unavailable` (HTTP 503) transient — reconciled by reaper /
+      // propagation, retried by the client — NOT a 404. Returning
+      // `not-found` would emit a 404 the FS backend never emits for the
+      // same condition (blob-fs.ts maps ENOENT → `unavailable`), telling
+      // the client the resource is gone for good when it should refetch.
+      // See server/README.md's GET status table.
+      if (isNotFound(err)) return { ok: false, reason: 'unavailable' }
       throw err
     }
-    if (res == null) return { ok: false, reason: 'not-found' }
+    // SDK returned null (no blob) — same "bytes missing for a live row"
+    // transient as the BlobNotFoundError branch above → `unavailable`, not
+    // `not-found`.
+    if (res == null) return { ok: false, reason: 'unavailable' }
     // statusCode 304 doesn't reach here in practice — the REST
     // GET layer doesn't pass If-None-Match — but a future call
     // site could. Treat as unavailable rather than streaming a
     // null body.
-    if (res.statusCode !== 200 || res.stream == null || res.blob.size == null) {
+    if (res.statusCode !== 200 || res.stream == null) {
       return { ok: false, reason: 'unavailable' }
     }
+    // `@vercel/blob@2.x`'s streaming `get()` for private blobs returns
+    // the body but does NOT populate `blob.size` nor pass a
+    // `content-length` header (verified empirically: get.size=0,
+    // content-length-hdr=null, while head.size reports the true count).
+    // The REST layer needs a size to set `content-length` and for the
+    // integrity check against the DB row, so on 0/null we fall back to
+    // head(). Two round-trips per private read until the SDK is fixed —
+    // small price vs. 503ing every read.
+    let size: number | null | undefined = res.blob?.size
+    if (size == null || size === 0) {
+      try {
+        const h = await sdk.head(path, { token })
+        size = (h as { size?: number })?.size
+      } catch (headErr) {
+        // Blob vanished between get() and the head() size fallback (a
+        // racing reaper GC) — still the "live row present, bytes gone"
+        // transient, so `unavailable` (503), matching the get() path above.
+        if (isNotFound(headErr)) return { ok: false, reason: 'unavailable' }
+        throw headErr
+      }
+    }
+    if (size == null) return { ok: false, reason: 'unavailable' }
     // SDK returns a web ReadableStream<Uint8Array>; the REST layer
     // expects a Node Readable for pipeline(). Convert via
     // Readable.fromWeb — built-in and zero-copy where possible.
@@ -376,7 +409,7 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
       ok: true,
       reader: {
         stream: nodeStream,
-        size: res.blob.size,
+        size,
         // eslint-disable-next-line require-await
         close: async () => {
           // Destroying the Node wrapper also cancels the underlying

package/server/objstore/blob.ts

@@ -83,13 +83,20 @@ export type LiveReader = {
   close(): Promise<void>
 }
 
-// `not-found` maps to HTTP 404 (the live blob is gone or never
-// existed); `unavailable` maps to HTTP 503 (transient backend issue
-// the reaper will eventually sort out). The REST layer uses this
-// discrimination to set the right status code.
+// A missing blob is always `unavailable` (→ HTTP 503), never a 404. The
+// byte plane has NO view of the metadata row, so it can't decide whether
+// a resource "doesn't exist" — only whether specific bytes are present
+// right now. The authoritative "this resource/version is gone" 404 is the
+// REST layer's call, made from the live row BEFORE it opens a reader
+// (rest.ts openLiveSnapshot). By the time `openLiveReader` runs the row is
+// already confirmed, so an absent blob means a transient bytes/metadata
+// desync the reaper (or store propagation) reconciles — exactly the
+// `unavailable`/503 contract, which the client retries. Both backends MUST
+// map a missing blob to `unavailable` (FS: ENOENT; Vercel: BlobNotFoundError
+// / null get()). No 404-mapping variant exists here so that bug can't recur.
 export type OpenLiveResult =
   | { ok: true; reader: LiveReader }
-  | { ok: false; reason: 'not-found' | 'unavailable' }
+  | { ok: false; reason: 'unavailable' }
 
 export type BlobBackend = {
   // Per-workspace setup. FS creates the on-disk staging directory;
@@ -128,9 +135,10 @@ export type BlobBackend = {
   promoteStagingToLive(tag: string, stagingId: string, contentHash: string): Promise<boolean>
 
   // Open a streaming reader for the content-addressed live blob.
-  // `not-found` lets the REST layer return 404; `unavailable` returns
-  // 503 for a transient state (file/blob missing while the row still
-  // exists — reaper will reconcile on the next sweep).
+  // Called only after the REST layer has confirmed the live row, so a
+  // missing blob is the transient "row present, bytes gone" state →
+  // `unavailable` (HTTP 503), which the reaper reconciles and the client
+  // retries. Never a 404 from here — see OpenLiveResult above.
   openLiveReader(tag: string, contentHash: string): Promise<OpenLiveResult>
 
   // Idempotent deletes. Backends MUST tolerate "already gone" as

package/server/objstore/handlers.ts

@@ -68,11 +68,11 @@ function urlPathFor(tag: string, resourceTag: string): string {
 // Shared gate every objstore handler runs after its message-specific
 // field checks: fetch the socket's challenge nonce, verify the signed
 // message against it, then re-confirm the socket is still OPEN — the
-// close handler may have fired during the verify await, and attaching
-// to / replying on a closed socket is the half-handshake leak case
-// (PR #4 review F4). Returns true when the caller may proceed.
-// Centralising the post-await readyState recheck keeps that
-// easy-to-forget invariant in one auditable place.
+// close handler may have fired during the verify await, and replying
+// on a closed socket is the half-handshake leak case (PR #4 review
+// F4). Centralising the post-await readyState recheck keeps that
+// invariant in one auditable place. Returns true when the caller may
+// proceed.
 async function verified<M extends { workspaceTag?: unknown }>(
   deps: ObjstoreDeps, socket: WebSocket, msg: M, label: string,
   verify: (m: M, nonce: string) => Promise<boolean>,
@@ -96,12 +96,10 @@ async function handlePutBegin(deps: ObjstoreDeps, socket: WebSocket, msg: Objsto
   // signature to fail. Cheaper to reject up-front, and consistent
   // with `verifyObjstorePutSig`'s `isSafeNonNegativeInt` gate.
   if (!Number.isSafeInteger(msg.expectedLength) || (msg.expectedLength as number) < 0 || (msg.expectedLength as number) > MAX_CONTENT_LENGTH) return
-  // Symmetric with `handleDelete`'s prevVersion gate (line 116) and
-  // `verifyObjstorePutSig`'s `isSafeIntOrNull` (sign.ts:119). Without
-  // this, a non-safe-integer `prevVersion` (NaN, 2^53+1, ...) would
-  // pass the typeof check below and reach sig verify, burning a
-  // hash + Ed25519 round-trip on a guaranteed-fail input. Input-
-  // validation audit `server/objstore/handlers.ts:76`.
+  // Same up-front reject for `prevVersion` (symmetric with handleDelete
+  // and `verifyObjstorePutSig`'s `isSafeIntOrNull`): a non-safe-integer
+  // (NaN, 2^53+1, ...) would pass the typeof check below and reach sig
+  // verify, burning a hash + Ed25519 round-trip on a guaranteed fail.
   if (msg.prevVersion != null && (typeof msg.prevVersion !== 'number' || !Number.isSafeInteger(msg.prevVersion))) return
   if (!await verified(deps, socket, msg, 'put-begin', verifyObjstorePutSig)) return
   const tag = msg.workspaceTag
@@ -110,8 +108,8 @@ async function handlePutBegin(deps: ObjstoreDeps, socket: WebSocket, msg: Objsto
   // workspace tag (no rows in workspace_revision AND none in
   // workspace_object). Mirrors handleSave in server/index.ts; runs
   // AFTER sig verify so `unauthorized` only reaches a legitimate
-  // signer. The gate is config-driven (server/config.json
-  // `password`) and is a no-op when no password is configured.
+  // signer. Config-driven (server/config.json `password`), no-op when
+  // unconfigured.
   if (deps.authGate && deps.sendUnauthorized && await deps.authGate(socket, tag)) {
     if (socket.readyState !== socket.OPEN) return
     if (deps.debug) console.warn(`reject objstore-put-begin: unauthorized (new workspace ${debugTag(tag)})`)

package/server/objstore/init.ts

@@ -56,6 +56,16 @@ export type ObjstoreInit = {
 }
 
 export function initObjstore(deps: ObjstoreInitDeps): ObjstoreInit {
+  // Fail loud on a lopsided auth config. The put-begin gate in
+  // handlers.ts only fires when BOTH authGate and sendUnauthorized are
+  // present (it needs the reporter to emit the `unauthorized` frame),
+  // so wiring authGate WITHOUT sendUnauthorized silently fails OPEN —
+  // unauthenticated first-writes to unknown workspaces would be accepted
+  // despite the operator's intent to gate them. Reject at boot rather
+  // than regress access control silently.
+  if (deps.authGate && !deps.sendUnauthorized) {
+    throw new Error('initObjstore: authGate requires sendUnauthorized (the put-begin gate needs it to emit the unauthorized frame)')
+  }
   const handle = deps.handle
   const secret = deps.tokenSecret ?? newTokenSecret()
   const handlers = createObjstoreHandlers({
@@ -93,15 +103,14 @@ export function initObjstore(deps: ObjstoreInitDeps): ObjstoreInit {
   // on-disk state still has stranded files from a prior crash.
   const startupReap = enqueueSweep()
   // Jittered start of the periodic timer. Multi-replica deploys
-  // (Neon + Vercel Blob) commonly boot N replicas in tight lock-
-  // step (deploy rollout, cluster restart) and would otherwise
-  // sync every replica's reaper at the same wall-clock tick,
-  // hammering the DB + blob store with N×readdir+lock-acquire
-  // bursts. A random first-interval delay deconcurrencies the
-  // cluster without changing the long-term sweep cadence.
-  // Jitter range is 0…1× reapIntervalMs (i.e., the next sweep
-  // happens at [interval, 2×interval] after boot); subsequent
-  // sweeps stay at exactly `reapIntervalMs` apart.
+  // (Neon + Vercel Blob) commonly boot N replicas in tight lock-step
+  // (deploy rollout, cluster restart), which would otherwise sync every
+  // replica's reaper to the same wall-clock tick and hammer the DB +
+  // blob store with N×readdir+lock-acquire bursts. A random
+  // first-interval delay spreads the cluster out without changing the
+  // long-term cadence. Jitter is 0…1× reapIntervalMs (first sweep at
+  // [interval, 2×interval] after boot); subsequent sweeps stay exactly
+  // `reapIntervalMs` apart.
   let reapTimer: ReturnType<typeof setInterval> | null = null
   const jitterMs = Math.floor(Math.random() * deps.reapIntervalMs)
   const firstTimer = setTimeout(() => {