@gotcos/glasses-server 6.46.1 → 6.48.0

package/server/lib/session-hook-events.ts

@@ -0,0 +1,200 @@
+// The hook envelope: what `bin/hooks/cos-session-hook` writes, and the only shape the
+// ingester, the ledger and the signal store ever read.
+//
+// One file per Claude Code hook event, spooled by a POSIX sh script that never talks to
+// this server (PermissionRequest excepted). The script wraps the payload Claude piped to
+// it: `{"ts":<ms>,"ppid":<pid>,"event":"<name>","payload":<stdin>}`.
+//
+// FIELD NAMES COME FROM RECORDED 2.1.272 PAYLOADS WHERE ONE EXISTS, never from the docs
+// alone. The docs said `start_reason`, `end_reason`, `stop_reason` and a `tool_use_id` on
+// PermissionRequest; the recordings (2026-09-15) carry `source`, `reason`, no stop reason
+// at all, and no tool_use_id on PermissionRequest. Fixtures under
+// `__fixtures__/session-hooks-6.48.0/` are those recordings; their README lists the
+// interactive-only events (Notification, StopFailure, sub-agents, compaction, model switch)
+// whose shapes are still the documented ones until a Desktop recording lands.
+
+import { createHash } from 'node:crypto'
+
+/** Events the installer subscribes and the reducer understands. Anything else is dropped. */
+export const HOOK_EVENT_NAMES = [
+  'SessionStart',
+  'SessionEnd',
+  'UserPromptSubmit',
+  'Stop',
+  'StopFailure',
+  'PermissionRequest',
+  'PermissionDenied',
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'SubagentStart',
+  'SubagentStop',
+  'PostCompact',
+  'PostModelSwitch',
+] as const
+
+export type HookEventName = typeof HOOK_EVENT_NAMES[number]
+
+const EVENT_SET: ReadonlySet<string> = new Set(HOOK_EVENT_NAMES)
+
+export function isHookEventName(value: unknown): value is HookEventName {
+  return typeof value === 'string' && EVENT_SET.has(value)
+}
+
+/** A full Claude session id: the transcript basename and the registry `sessionId`. */
+export const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** The spool file is capped by the script at 1 MiB of stdin; the envelope adds a few bytes. */
+export const HOOK_ENVELOPE_MAX_BYTES = 1_048_576 + 256
+
+export interface HookEnvelope {
+  /** Milliseconds, stamped by the script when the hook ran. */
+  ts: number
+  /** The hook process's parent pid: the claude process, or the `sh -c` wrapper. */
+  ppid: number | null
+  event: HookEventName
+  sessionId: string
+  payload: Record<string, unknown>
+}
+
+/**
+ * What a regex can still read off the head of a file that did not parse: enough for the
+ * store to apply a payload-less event so a cut Stop still turns a row idle, never enough
+ * to trust any other field.
+ */
+export interface SalvagedHookHead {
+  sessionId: string
+  event: HookEventName
+  ts: number
+}
+
+export type ParsedHookEnvelope =
+  | { ok: true; envelope: HookEnvelope }
+  | { ok: false; reason: 'too_large' | 'not_json' | 'not_envelope' | 'unknown_event' | 'no_session'; salvaged: SalvagedHookHead | null }
+
+const SALVAGE_SESSION_RE = /"session_id"\s*:\s*"([0-9a-f-]{36})"/i
+const SALVAGE_EVENT_RE = /"event"\s*:\s*"([A-Za-z]+)"/
+const SALVAGE_TS_RE = /"ts"\s*:\s*(\d{10,16})/
+
+function salvage(text: string): SalvagedHookHead | null {
+  const head = text.slice(0, 4096)
+  const session = SALVAGE_SESSION_RE.exec(head)?.[1]
+  const event = SALVAGE_EVENT_RE.exec(head)?.[1]
+  const ts = Number(SALVAGE_TS_RE.exec(head)?.[1])
+  if (!session || !SESSION_ID_RE.test(session) || !isHookEventName(event) || !Number.isFinite(ts)) return null
+  return { sessionId: session.toLowerCase(), event, ts }
+}
+
+export function parseHookEnvelope(text: string): ParsedHookEnvelope {
+  if (text.length > HOOK_ENVELOPE_MAX_BYTES) return { ok: false, reason: 'too_large', salvaged: salvage(text) }
+  let raw: unknown
+  try { raw = JSON.parse(text) } catch { return { ok: false, reason: 'not_json', salvaged: salvage(text) } }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'not_envelope', salvaged: null }
+  const r = raw as Record<string, unknown>
+  const ts = Number(r.ts)
+  const payload = r.payload
+  if (!Number.isFinite(ts) || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { ok: false, reason: 'not_envelope', salvaged: salvage(text) }
+  }
+  if (!isHookEventName(r.event)) return { ok: false, reason: 'unknown_event', salvaged: null }
+  const p = payload as Record<string, unknown>
+  const sessionId = typeof p.session_id === 'string' && SESSION_ID_RE.test(p.session_id) ? p.session_id.toLowerCase() : null
+  if (!sessionId) return { ok: false, reason: 'no_session', salvaged: null }
+  const ppid = Number(r.ppid)
+  return {
+    ok: true,
+    envelope: {
+      ts,
+      ppid: Number.isInteger(ppid) && ppid > 0 ? ppid : null,
+      event: r.event,
+      sessionId,
+      payload: p,
+    },
+  }
+}
+
+/** Pin the fingerprint the broker and the reducer share: tool name + canonical input. */
+export function toolFingerprint(toolName: string, toolInput: unknown): string {
+  return createHash('sha256').update(toolName).update('\0').update(canonicalJson(toolInput)).digest('hex')
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null)
+  if (Array.isArray(value)) return '[' + value.map(canonicalJson).join(',') + ']'
+  const o = value as Record<string, unknown>
+  return '{' + Object.keys(o).sort().map(k => JSON.stringify(k) + ':' + canonicalJson(o[k])).join(',') + '}'
+}
+
+/** The 80-char target a waiting line shows: the command, path or URL the tool was called with. */
+export function toolTarget(toolInput: unknown, max = 80): string {
+  if (!toolInput || typeof toolInput !== 'object') return ''
+  const i = toolInput as Record<string, unknown>
+  const candidate = [i.command, i.file_path, i.path, i.url, i.pattern, i.query, i.prompt, i.description]
+    .find(v => typeof v === 'string' && v.trim().length > 0)
+  const text = typeof candidate === 'string' ? candidate.replace(/\s+/g, ' ').trim() : ''
+  return text.length > max ? text.slice(0, max - 1) + '…' : text
+}
+
+/** Text fields kept from a payload. Everything else is dropped before the ledger sees it. */
+export const HOOK_TEXT_MAX = 400
+
+export function clipText(value: unknown, max = HOOK_TEXT_MAX): string {
+  if (typeof value !== 'string') return ''
+  const text = value.trim()
+  return text.length > max ? text.slice(0, max - 1) + '…' : text
+}
+
+/**
+ * What the ledger keeps of a payload. A PostToolUse carries the whole tool_response (a
+ * Read can exceed 100 KB) and a Stop the whole reply; neither belongs in a durable
+ * 10 MB ring. The reducer needs exactly these.
+ */
+export function projectHookPayload(event: HookEventName, payload: Record<string, unknown>): Record<string, unknown> {
+  const str = (k: string) => (typeof payload[k] === 'string' ? payload[k] as string : undefined)
+  const base: Record<string, unknown> = {
+    session_id: str('session_id'),
+    ...(str('transcript_path') ? { transcript_path: str('transcript_path') } : {}),
+    ...(str('cwd') ? { cwd: str('cwd') } : {}),
+    ...(str('permission_mode') ? { permission_mode: str('permission_mode') } : {}),
+    ...(str('prompt_id') ? { prompt_id: str('prompt_id') } : {}),
+  }
+  switch (event) {
+    case 'SessionStart':
+      return { ...base, source: str('source'), ...(str('model') ? { model: str('model') } : {}) }
+    case 'SessionEnd':
+      return { ...base, reason: str('reason') }
+    case 'UserPromptSubmit':
+      return { ...base, prompt: clipText(payload.prompt) }
+    case 'Stop':
+      return { ...base, last_assistant_message: clipText(payload.last_assistant_message), stop_hook_active: payload.stop_hook_active === true }
+    case 'StopFailure':
+      return { ...base, error: clipText(payload.error ?? payload.error_type ?? payload.message, 120), matcher: str('matcher') ?? str('error_type') }
+    case 'PermissionRequest':
+    case 'PermissionDenied':
+    case 'PreToolUse':
+    case 'PostToolUse':
+    case 'PostToolUseFailure': {
+      const toolName = str('tool_name') ?? ''
+      return {
+        ...base,
+        tool_name: toolName,
+        tool_target: toolTarget(payload.tool_input),
+        tool_fingerprint: toolFingerprint(toolName, payload.tool_input ?? null),
+        ...(str('tool_use_id') ? { tool_use_id: str('tool_use_id') } : {}),
+        ...(event === 'PermissionRequest' && Array.isArray(payload.permission_suggestions)
+          ? { permission_suggestions: payload.permission_suggestions.slice(0, 4) }
+          : {}),
+      }
+    }
+    case 'Notification':
+      return { ...base, notification_type: str('notification_type'), message: clipText(payload.message, 160) }
+    case 'SubagentStart':
+    case 'SubagentStop':
+      return { ...base, agent_id: str('agent_id'), agent_type: str('agent_type') }
+    case 'PostModelSwitch':
+      return { ...base, from_model: str('from_model'), to_model: str('to_model') }
+    case 'PostCompact':
+      return base
+  }
+}

package/server/lib/session-hook-ledger.ts

@@ -0,0 +1,129 @@
+// The durable trail of hook events: `session-hook-events.jsonl`, one projected row per
+// envelope, rotated once at 10 MB, replayed on boot to warm the signal store.
+//
+// The ledger keeps the PROJECTION (`projectHookPayload`), never the raw payload: a
+// PostToolUse response or a full reply would churn the ring in minutes. Each row carries
+// the spool filename as its key so a crash between append and unlink replays without
+// applying the same event twice.
+
+import { appendFileSync, existsSync, readFileSync, renameSync, statSync } from 'node:fs'
+import type { HookEnvelope, HookEventName } from './session-hook-events.js'
+import { projectHookPayload, isHookEventName, SESSION_ID_RE } from './session-hook-events.js'
+
+export const LEDGER_ROTATE_BYTES = 10 * 1024 * 1024
+
+export interface LedgerRow {
+  key: string
+  ts: number
+  ppid: number | null
+  event: HookEventName
+  session_id: string
+  /** Classified at ingest, while the pid was alive: a COS-spawned child's event. */
+  child?: boolean
+  payload: Record<string, unknown>
+}
+
+function codeOf(error: unknown): string {
+  const code = (error as { code?: unknown })?.code
+  return typeof code === 'string' && code ? code : (error instanceof Error ? error.name || 'Error' : 'error')
+}
+
+function readText(path: string): string {
+  if (!existsSync(path)) return ''
+  try { return readFileSync(path, 'utf-8') } catch { return '' }
+}
+
+function oldestTs(text: string): number | null {
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const ts = (JSON.parse(line) as { ts?: unknown }).ts
+      if (typeof ts === 'number') return ts
+    } catch { continue }
+  }
+  return null
+}
+
+export class SessionHookLedger {
+  readonly path: string
+  private lastError: string | null = null
+  private appended = 0
+
+  constructor(path: string) {
+    this.path = path
+  }
+
+  /** Append one row. Returns false (and remembers why) when the disk refused. */
+  append(key: string, env: HookEnvelope, child = false): boolean {
+    let row: LedgerRow
+    try {
+      row = {
+        key,
+        ts: env.ts,
+        ppid: env.ppid,
+        event: env.event,
+        session_id: env.sessionId,
+        ...(child ? { child: true } : {}),
+        payload: projectHookPayload(env.event, env.payload),
+      }
+    } catch (error) {
+      // A pathological payload must not escape into the sweep; the caller rejects the file.
+      this.lastError = codeOf(error)
+      return false
+    }
+    try {
+      this.rotateIfNeeded()
+      appendFileSync(this.path, JSON.stringify(row) + '\n', { mode: 0o600 })
+      this.appended++
+      this.lastError = null
+      return true
+    } catch (error) {
+      this.lastError = codeOf(error)
+      return false
+    }
+  }
+
+  private rotateIfNeeded(): void {
+    let size = 0
+    try { size = statSync(this.path).size } catch { return }
+    if (size < LEDGER_ROTATE_BYTES) return
+    try { renameSync(this.path, this.path + '.1') } catch { /* the next append tries again */ }
+  }
+
+  /**
+   * Replay rows newer than `sinceMs`. The rotated `.1` is read too whenever the current
+   * file does not reach back to `sinceMs` (a rotation inside the window would otherwise
+   * hide the rows that matter most, and forget their keys). Malformed lines are skipped;
+   * a boot must never fail on a torn last line.
+   */
+  replay(sinceMs: number, apply: (env: HookEnvelope, key: string, child: boolean) => void): { rows: number; applied: number; keys: Set<string> } {
+    const keys = new Set<string>()
+    let rows = 0
+    let applied = 0
+    const current = readText(this.path)
+    const oldest = oldestTs(current)
+    const texts = oldest !== null && oldest > sinceMs ? [readText(this.path + '.1'), current] : [current]
+    for (const line of texts.join('\n').split('\n')) {
+      if (!line.trim()) continue
+      let row: unknown
+      try { row = JSON.parse(line) } catch { continue }
+      if (!row || typeof row !== 'object') continue
+      const r = row as Partial<LedgerRow>
+      rows++
+      if (typeof r.key !== 'string' || typeof r.ts !== 'number' || !isHookEventName(r.event)) continue
+      if (typeof r.session_id !== 'string' || !SESSION_ID_RE.test(r.session_id)) continue
+      keys.add(r.key)
+      if (r.ts < sinceMs) continue
+      const payload = r.payload && typeof r.payload === 'object' ? r.payload as Record<string, unknown> : {}
+      apply({ ts: r.ts, ppid: typeof r.ppid === 'number' ? r.ppid : null, event: r.event, sessionId: r.session_id.toLowerCase(), payload: { session_id: r.session_id, ...payload } }, r.key, r.child === true)
+      applied++
+    }
+    return { rows, applied, keys }
+  }
+
+  stats(): { bytes: number; appended: number; lastError: string | null } {
+    let bytes = 0
+    try { bytes = statSync(this.path).size } catch { /* none yet */ }
+    return { bytes, appended: this.appended, lastError: this.lastError }
+  }
+}

package/server/lib/session-hook-spool.ts

@@ -0,0 +1,264 @@
+// The spool ingester: reads the one-file-per-event spool `bin/hooks/cos-session-hook`
+// writes, ledgers each event, applies it to the signal store, and unlinks the file.
+//
+// THE FILE IS THE BUS. The hook script never talks to this server, so a session's
+// hooks keep spooling while the managed runtime restarts or is stopped for a week; the
+// startup drain applies the backlog in filename order (millisecond timestamp, then pid)
+// and `state_since` comes from each file's own stamp, not its arrival.
+//
+// Same poll discipline as `session-transcript-watcher.ts`: a `fs.watch` on the directory
+// is only a wake-up, the 2 s readdir sweep is the guaranteed path, one sweep at a time
+// (`ticking`), timer unref'd so it never holds the process open. A sweep applies at most
+// BATCH files, so a 2,000-file backlog is drained in bounded slices of the event loop.
+//
+// Off is still a drain. With `COS_SESSION_HOOKS=0` the ingester runs with `apply` set to
+// nothing: it ledgers, unlinks and stamps `.last-drain`, because the script's own guard
+// stops spooling when that stamp goes stale, and a spool nobody reads must not grow.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, utimesSync, watch, writeFileSync, type FSWatcher } from 'node:fs'
+import { join } from 'node:path'
+import type { HookEnvelope } from './session-hook-events.js'
+import { parseHookEnvelope } from './session-hook-events.js'
+import type { SessionHookLedger } from './session-hook-ledger.js'
+
+export const SPOOL_SWEEP_MS = 2_000
+export const SPOOL_BATCH = 200
+export const REJECTED_KEEP = 1_000
+export const REJECTED_MAX_AGE_MS = 7 * 24 * 60 * 60_000
+export const LAST_DRAIN_STAMP = '.last-drain'
+
+const SPOOL_FILE_RE = /^(\d{10,16})-(\d+)-([A-Za-z]+)\.json$/
+
+/** A code, never a message: raw fs messages carry the home path and health is public. */
+export function errorCode(error: unknown): string {
+  const code = (error as { code?: unknown })?.code
+  if (typeof code === 'string' && code) return code
+  return error instanceof Error ? error.name || 'Error' : 'error'
+}
+
+/** A hook killed mid-write leaves `.tmp.*`; reap those older than this. */
+export const TMP_MAX_AGE_MS = 10 * 60_000
+/** The startup drain never loops more times than a full spool needs. */
+export const STARTUP_MAX_PASSES = Math.ceil(2_000 / SPOOL_BATCH) + 1
+
+export interface SpoolIngesterOptions {
+  dir: string
+  ledger: SessionHookLedger
+  /** Apply a parsed envelope to the store. Absent when the feature is off. */
+  apply?: (env: HookEnvelope, child: boolean) => void
+  /** Classify the envelope's ppid at INGEST time, while the pid is still alive. */
+  isChild?: (env: HookEnvelope) => boolean
+  /** Keys already in the ledger at boot, so a replayed file is not applied twice. */
+  seenKeys?: Set<string>
+  sweepMs?: number
+  batch?: number
+  now?: () => number
+}
+
+export interface SpoolStats {
+  ingested: number
+  rejected: number
+  salvaged: number
+  duplicates: number
+  /** Files a sweep visited and could not remove (ledger refused, unreadable). */
+  stuck: number
+  /** Non-`.json` names in the spool that are not ours; they count against the script's cap. */
+  foreign: number
+  applyErrors: number
+  backlog: number
+  lastSweepAt: number | null
+  lastEventAt: number | null
+  lastError: string | null
+}
+
+export interface SpoolIngester {
+  sweep(): number
+  stop(): void
+  stats(): SpoolStats
+}
+
+export function startSpoolIngester(options: SpoolIngesterOptions): SpoolIngester {
+  const { dir, ledger } = options
+  const now = options.now ?? (() => Date.now())
+  const sweepMs = options.sweepMs ?? SPOOL_SWEEP_MS
+  const batch = options.batch ?? SPOOL_BATCH
+  const seen = options.seenKeys ?? new Set<string>()
+  const rejectedDir = join(dir, 'rejected')
+  const stats: SpoolStats = { ingested: 0, rejected: 0, salvaged: 0, duplicates: 0, stuck: 0, foreign: 0, applyErrors: 0, backlog: 0, lastSweepAt: null, lastEventAt: null, lastError: null }
+  let ticking = false
+  let stopped = false
+  let watcher: FSWatcher | null = null
+  let pruneCounter = 0
+  let lastStampAt = 0
+  let loggedStuck = false
+
+  try { mkdirSync(rejectedDir, { recursive: true, mode: 0o700 }) } catch { /* the sweep reports it */ }
+
+  // The stamp is a metadata change inside the watched directory, so it would wake the
+  // watcher, which would sweep, which would stamp: touched at most once per sweep interval.
+  const stamp = () => {
+    const t = now()
+    if (t - lastStampAt < sweepMs) return
+    lastStampAt = t
+    const path = join(dir, LAST_DRAIN_STAMP)
+    try {
+      if (existsSync(path)) { const d = new Date(t); utimesSync(path, d, d) } else writeFileSync(path, '', { mode: 0o600 })
+    } catch { /* a missing stamp only makes the script cautious */ }
+  }
+
+  /** Spool order: the millisecond stamp, then the pid, both as numbers (a pid wrap must not reorder). */
+  const spoolOrder = (a: string, b: string): number => {
+    const ma = SPOOL_FILE_RE.exec(a)!, mb = SPOOL_FILE_RE.exec(b)!
+    return (Number(ma[1]) - Number(mb[1])) || (Number(ma[2]) - Number(mb[2])) || a.localeCompare(b)
+  }
+
+  const listSpool = (): string[] => {
+    let names: string[]
+    try { names = readdirSync(dir) } catch (error) {
+      stats.lastError = errorCode(error)
+      return []
+    }
+    // A `.json` whose name the script never writes (a partial rename) is moved aside so the
+    // count the script sees stays honest and `backlog` never hides it. Anything else that is
+    // not ours (a stray file someone dropped here) is left where it is and only counted.
+    let foreign = 0
+    for (const n of names) {
+      if (SPOOL_FILE_RE.test(n) || n === 'rejected' || n === LAST_DRAIN_STAMP) continue
+      if (n.startsWith('.tmp.')) {
+        try { if (now() - statSync(join(dir, n)).mtimeMs > TMP_MAX_AGE_MS) unlinkSync(join(dir, n)) } catch { /* fine */ }
+        continue
+      }
+      if (n.startsWith('.')) continue
+      if (!n.endsWith('.json')) { foreign++; continue }
+      try { renameSync(join(dir, n), join(rejectedDir, `${n}.unrecognized`)) ; stats.rejected++ } catch { /* fine */ }
+    }
+    stats.foreign = foreign
+    return names.filter(n => SPOOL_FILE_RE.test(n)).sort(spoolOrder)
+  }
+
+  const reject = (name: string, reason: string) => {
+    stats.rejected++
+    try { renameSync(join(dir, name), join(rejectedDir, `${name}.${reason}`)) } catch {
+      try { unlinkSync(join(dir, name)) } catch { /* gone already */ }
+    }
+  }
+
+  /** True when the file is gone afterwards (ingested, rejected or deduped); false when it stays. */
+  const ingestOne = (name: string): boolean => {
+    const path = join(dir, name)
+    let text: string
+    try { text = readFileSync(path, 'utf-8') } catch {
+      // Raced a rename, or unreadable: the next sweep sees it or not; it is not progress.
+      return !existsSync(path)
+    }
+    let parsed: ReturnType<typeof parseHookEnvelope>
+    try { parsed = parseHookEnvelope(text) } catch (error) {
+      stats.lastError = errorCode(error)
+      reject(name, 'parse_threw')
+      return true
+    }
+    let env: HookEnvelope | null = null
+    if (parsed.ok) {
+      env = parsed.envelope
+    } else if (parsed.salvaged) {
+      // A cut Stop still turns the row idle; nothing else in the file is trusted.
+      env = { ts: parsed.salvaged.ts, ppid: null, event: parsed.salvaged.event, sessionId: parsed.salvaged.sessionId, payload: { session_id: parsed.salvaged.sessionId } }
+      stats.salvaged++
+    }
+    if (!env) { reject(name, parsed.ok ? 'unknown' : parsed.reason); return true }
+    if (seen.has(name)) {
+      stats.duplicates++
+      try { unlinkSync(path) } catch { /* fine */ }
+      return true
+    }
+    // Classified NOW, while the child pid is alive; the ledger row remembers the verdict so a
+    // replay after a restart (when the spawn ledger is empty) applies the same rule.
+    let child = false
+    try { child = options.isChild?.(env) ?? false } catch { child = false }
+    let appended = false
+    try { appended = ledger.append(name, env, child) } catch (error) { stats.lastError = errorCode(error) }
+    if (!appended) {
+      // Keep the file: the ledger is the durable record and it refused. Health shows why.
+      stats.lastError = ledger.stats().lastError ?? stats.lastError
+      return false
+    }
+    seen.add(name)
+    try { options.apply?.(env, child) } catch (error) {
+      stats.applyErrors++
+      console.error(`[hook-spool] apply failed for ${name}: ${error instanceof Error ? error.message : error}`)
+    }
+    stats.ingested++
+    stats.lastEventAt = env.ts
+    try { unlinkSync(path) } catch { /* a re-read is deduped by `seen` */ }
+    return true
+  }
+
+  const pruneRejected = () => {
+    let names: string[]
+    try { names = readdirSync(rejectedDir).sort() } catch { return }
+    const cutoff = now() - REJECTED_MAX_AGE_MS
+    const excess = Math.max(0, names.length - REJECTED_KEEP)
+    names.forEach((n, index) => {
+      const path = join(rejectedDir, n)
+      let old = false
+      try { old = statSync(path).mtimeMs < cutoff } catch { return }
+      if (index < excess || old) { try { unlinkSync(path) } catch { /* fine */ } }
+    })
+  }
+
+  /** Returns the number of files REMOVED this pass; a stuck file is not progress. */
+  const sweep = (): number => {
+    if (ticking || stopped) return 0
+    ticking = true
+    let removed = 0
+    let stuck = 0
+    try {
+      const names = listSpool()
+      for (const name of names.slice(0, batch)) {
+        if (ingestOne(name)) removed++
+        else stuck++
+      }
+      stats.stuck = stuck
+      stats.backlog = Math.max(0, names.length - removed)
+      stats.lastSweepAt = now()
+      if (stuck > 0 && !loggedStuck) {
+        loggedStuck = true
+        console.error(`[hook-spool] ${stuck} file(s) could not be drained (${stats.lastError ?? 'unknown'}); they stay in ${dir}`)
+      }
+      if (stuck === 0) loggedStuck = false
+      stamp()
+      if (++pruneCounter % 30 === 0) pruneRejected()
+    } finally {
+      ticking = false
+    }
+    return removed
+  }
+
+  // Startup drain: the backlog, in bounded passes, before anyone asks. Bounded twice: a pass
+  // that removed nothing ends it (a refusing ledger must never spin the boot), and no
+  // backlog needs more passes than a full spool.
+  for (let pass = 0; pass < STARTUP_MAX_PASSES && !stopped; pass++) {
+    if (sweep() === 0) break
+  }
+
+  const timer = setInterval(sweep, sweepMs)
+  timer.unref()
+  try {
+    // Only a spool file is a wake-up. The stamp and the rejected dir change metadata here
+    // too, and reacting to them would be a self-sustaining loop.
+    watcher = watch(dir, { persistent: false }, (_event, filename) => {
+      if (typeof filename === 'string' && SPOOL_FILE_RE.test(filename)) sweep()
+    })
+    watcher.on('error', () => { /* the interval is the guaranteed path */ })
+  } catch { watcher = null }
+
+  return {
+    sweep,
+    stop() {
+      stopped = true
+      clearInterval(timer)
+      try { watcher?.close() } catch { /* fine */ }
+    },
+    stats: () => ({ ...stats }),
+  }
+}