@gotcos/glasses-server 6.47.0 → 6.48.0

package/server/lib/session-hooks-runtime.ts

@@ -0,0 +1,229 @@
+// The composition root for session hooks: the one signal store, the ledger, the spool
+// ingester, and the per-session facts the routes read.
+//
+// `COS_SESSION_HOOKS` (default: on whenever `COS_CLAUDE_SESSIONS_ENABLED=1`) gates the
+// APPLY, never the drain: with the flag off the spool is still ledgered, unlinked and
+// stamped, and nothing reaches a row. Control's env allowlist carries the flag across
+// Update Server (main.swift `providerEnvironmentKeys`).
+
+import { execFileSync } from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import { cosSpawnedPids } from './agent-session-ownership-store.js'
+import { dataPath } from './data-dir.js'
+import { SessionHookLedger } from './session-hook-ledger.js'
+import { startSpoolIngester, type SpoolIngester, type SpoolStats } from './session-hook-spool.js'
+import { SessionSignalStore, type SessionSignal } from './session-signal-store.js'
+import { deriveSessionState, type DerivedSessionState, type RegistryFacts, type TranscriptFacts } from './session-state-derive.js'
+import { ensureHookRuntimeFiles, ensureStableHookScript, hookSpoolDir, hookStatus, type HookStatus } from './claude-hooks-installer.js'
+
+export function sessionHooksEnabled(): boolean {
+  const raw = process.env.COS_SESSION_HOOKS
+  if (raw === '0' || raw === 'false' || raw === 'off') return false
+  if (raw === '1' || raw === 'true' || raw === 'on') return true
+  return process.env.COS_CLAUDE_SESSIONS_ENABLED === '1'
+}
+
+export function spoolDir(): string {
+  return hookSpoolDir()
+}
+
+export function deskIdleSeconds(): number {
+  const raw = Number(process.env.COS_PERMISSION_BROKER_DESK_IDLE_S)
+  return Number.isFinite(raw) && raw >= 0 ? Math.trunc(raw) : 90
+}
+
+/** Replay this much ledger history into the store at boot. */
+export const LEDGER_REPLAY_WINDOW_MS = 6 * 60 * 60_000
+
+// A hook's ppid is the claude process itself: macOS `sh -c '<script> <Event>'` execs the
+// single command, and every recorded session (fixtures, 2026-09-15) shows one ppid across all
+// of its events. The `ps` parent lookup below is the fallback for a shell that does not exec;
+// it runs once per pid and is remembered for a minute.
+const parentCache = new Map<number, { parent: number | null; at: number }>()
+const PARENT_CACHE_MS = 60_000
+
+function parentPid(pid: number): number | null {
+  const cached = parentCache.get(pid)
+  if (cached && Date.now() - cached.at < PARENT_CACHE_MS) return cached.parent
+  let parent: number | null = null
+  try {
+    const out = execFileSync('/bin/ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf-8', timeout: 1_000 })
+    const n = Number(out.trim())
+    parent = Number.isInteger(n) && n > 0 ? n : null
+  } catch { parent = null }
+  if (parentCache.size > 512) parentCache.clear()
+  parentCache.set(pid, { parent, at: Date.now() })
+  return parent
+}
+
+// A child's synchronous SessionEnd is spooled ~150 ms before the child exits, and the spawn
+// ledger forgets the pid the moment it does; the sweep that reads the file can run after.
+// So every pid the ledger ever vouched for is remembered here for a grace window.
+const recentCosPids = new Map<number, number>()
+export const COS_PID_TOMBSTONE_MS = 60_000
+
+export function isCosSpawnedPid(pid: number | null, nowMs = Date.now()): boolean {
+  if (pid === null) return false
+  const spawned = cosSpawnedPids()
+  for (const p of spawned.keys()) recentCosPids.set(p, nowMs)
+  if (recentCosPids.size > 256) {
+    for (const [p, at] of recentCosPids) if (nowMs - at > COS_PID_TOMBSTONE_MS) recentCosPids.delete(p)
+  }
+  const remembered = (p: number) => { const at = recentCosPids.get(p); return at !== undefined && nowMs - at <= COS_PID_TOMBSTONE_MS }
+  if (spawned.has(pid) || remembered(pid)) return true
+  if (spawned.size === 0 && recentCosPids.size === 0) return false
+  const parent = parentPid(pid)
+  return parent !== null && (spawned.has(parent) || remembered(parent))
+}
+
+export const sessionSignalStore = new SessionSignalStore({ isCosSpawnedPid })
+
+let ledger: SessionHookLedger | null = null
+let ingester: SpoolIngester | null = null
+let replayed: { rows: number; applied: number } | null = null
+/** The two-scan memory: consecutive dead observations and when the first one was. */
+const deadById = new Map<string, { scans: number; since: number | null; at: number }>()
+const DEAD_MEMORY_MS = 60 * 60_000
+
+export interface SessionHooksRuntime {
+  store: SessionSignalStore
+  stop(): void
+}
+
+export function startSessionHooksRuntime(options: { port: number }): SessionHooksRuntime {
+  const dir = spoolDir()
+  try { mkdirSync(dir, { recursive: true, mode: 0o700 }) } catch { /* the ingester reports it */ }
+  ledger = new SessionHookLedger(dataPath('session-hook-events.jsonl'))
+  const enabled = sessionHooksEnabled()
+  const since = Date.now() - LEDGER_REPLAY_WINDOW_MS
+  const replay = ledger.replay(since, (env, _key, child) => { if (enabled) sessionSignalStore.apply(env, child) })
+  replayed = { rows: replay.rows, applied: replay.applied }
+  ingester = startSpoolIngester({
+    dir,
+    ledger,
+    seenKeys: replay.keys,
+    isChild: env => isCosSpawnedPid(env.ppid),
+    apply: enabled ? (env, child) => { sessionSignalStore.apply(env, child) } : undefined,
+  })
+  // Runtime files the script reads. The port can change per install; the token never does.
+  // The script is copied only when MISSING here: a boot must never downgrade what a newer
+  // `--hooks install` put at the stable path.
+  try {
+    ensureHookRuntimeFiles(options.port, deskIdleSeconds())
+    ensureStableHookScript(undefined, undefined, true)
+  } catch (error) {
+    console.error(`[session-hooks] runtime files: ${error instanceof Error ? error.message : error}`)
+  }
+  const pruneTimer = setInterval(() => { sessionSignalStore.prune() }, 10 * 60_000)
+  pruneTimer.unref()
+  return {
+    store: sessionSignalStore,
+    stop() {
+      clearInterval(pruneTimer)
+      ingester?.stop()
+    },
+  }
+}
+
+export interface SessionHooksHealth {
+  enabled: boolean
+  /** The install state word; `installed` below is its boolean. */
+  state: HookStatus['state']
+  installed: boolean
+  scriptSha: string | null
+  tokenPresent: boolean
+  lastEventAt: string | null
+  spoolBacklog: number
+  spoolStuck: number
+  applyErrors: number
+  ledgerBytes: number
+  /** Error CODES only (ENOSPC, EACCES); a message would carry the home path onto public health. */
+  ledgerError: string | null
+  spoolError: string | null
+  signals: number
+  replayed: { rows: number; applied: number } | null
+  spool: SpoolStats | null
+}
+
+// Health is polled by three clients every few seconds; the status read (settings parse,
+// two hashes) is cheap but not free, and it cannot change faster than this.
+let statusCache: { at: number; value: HookStatus } | null = null
+const STATUS_CACHE_MS = 5_000
+
+export function cachedHookStatus(nowMs = Date.now()): HookStatus {
+  if (statusCache && nowMs - statusCache.at < STATUS_CACHE_MS) return statusCache.value
+  const value = hookStatus()
+  statusCache = { at: nowMs, value }
+  return value
+}
+
+export function invalidateHookStatus(): void {
+  statusCache = null
+}
+
+export function sessionHooksHealthFields(): { sessionHooks: SessionHooksHealth } {
+  const status = cachedHookStatus()
+  const spool = ingester?.stats() ?? null
+  const ledgerStats = ledger?.stats() ?? null
+  const newest = sessionSignalStore.newestEventAt()
+  return {
+    sessionHooks: {
+      enabled: sessionHooksEnabled(),
+      state: status.state,
+      installed: status.installed,
+      scriptSha: status.scriptSha,
+      tokenPresent: status.tokenPresent,
+      lastEventAt: newest ? new Date(newest).toISOString() : null,
+      spoolBacklog: spool?.backlog ?? 0,
+      spoolStuck: spool?.stuck ?? 0,
+      applyErrors: spool?.applyErrors ?? 0,
+      ledgerBytes: ledgerStats?.bytes ?? 0,
+      ledgerError: ledgerStats?.lastError ?? null,
+      spoolError: spool?.lastError ?? null,
+      signals: sessionSignalStore.size(),
+      replayed,
+      spool,
+    },
+  }
+}
+
+/** Signal for a row id that may be the registry's eight-character form. */
+export function signalFor(sessionId: string): SessionSignal | undefined {
+  if (!sessionHooksEnabled()) return undefined
+  return sessionId.length >= 36 ? sessionSignalStore.get(sessionId) : sessionSignalStore.getByPrefix(sessionId)
+}
+
+/**
+ * Derive with the two-scan memory kept here, keyed by full id when known. Rows the
+ * caller has no facts for at all get nothing, so an older payload stays byte-identical.
+ */
+export function deriveForRow(input: { sessionId: string; registry?: RegistryFacts; transcript?: TranscriptFacts; now?: number }): DerivedSessionState | undefined {
+  // Off means off: with the feature disabled every row is byte-identical to 6.47.0.
+  if (!sessionHooksEnabled()) return undefined
+  const signal = signalFor(input.sessionId)
+  if (!signal && !input.registry && !input.transcript) return undefined
+  const now = input.now ?? Date.now()
+  const key = signal?.sessionId ?? input.sessionId.toLowerCase()
+  const prev = deadById.get(key)
+  const derived = deriveSessionState({
+    signal,
+    registry: input.registry,
+    transcript: input.transcript,
+    now,
+    prevDeadScans: prev?.scans ?? 0,
+    prevDeadSince: prev?.since ?? null,
+  })
+  if (deadById.size > 2_048) {
+    for (const [k, v] of deadById) if (now - v.at > DEAD_MEMORY_MS) deadById.delete(k)
+  }
+  deadById.set(key, { scans: derived.deadScans, since: derived.deadSince, at: now })
+  return derived
+}
+
+export function __resetSessionHooksForTests(): void {
+  sessionSignalStore.__resetForTests()
+  deadById.clear()
+  parentCache.clear()
+  recentCosPids.clear()
+  statusCache = null
+}

package/server/lib/session-signal-store.ts

@@ -0,0 +1,361 @@
+// The signal store: what the hooks have said about each Claude session, reduced to
+// one record per full session id.
+//
+// POSITIVE SIGNALS ONLY. Before 6.48.0 every state on a session row was inferred: a
+// registry pid that answers signal 0, a transcript mtime inside a window, a tool_use
+// block with no result behind it. This store holds what the engine itself announced
+// through its hooks (session started, prompt submitted, permission wanted, turn stopped,
+// session ended), and `session-state-derive.ts` ranks it above every inference.
+//
+// The reducer is PURE (`applyHookEvent`), so a recorded sequence of envelopes replays
+// into a deterministic record and the fixtures under `__fixtures__/session-hooks-6.48.0`
+// are the specification. Three rules that came out of the validation rounds:
+//
+//  1. A `waiting` entry clears only on RESOLUTION EVIDENCE for that request: the
+//     matching PostToolUse/PostToolUseFailure/PermissionDenied (same tool name + input
+//     fingerprint), or a turn boundary (Stop, StopFailure, UserPromptSubmit, SessionEnd, a
+//     non-compact SessionStart), or the broker's own decision. A parallel auto-allowed
+//     Read or a sub-agent's tool must not clear a real prompt. The deriver adds two more
+//     clearers it can see and this store cannot: a registry status that moved after the
+//     wait, and transcript activity newer than the wait.
+//  2. A COS-spawned Continue child (`claude -p --resume <id>`) shares the Desktop tab's
+//     session id and fires its own SessionStart/Stop/SessionEnd. Events whose spooled
+//     ppid is a COS spawn are recorded as `child*` counters and never touch the phase.
+//  3. `ended` is recorded here but RANKED in the deriver, which also sees the registry:
+//     an ended signal with an alive registry record is a child that ended, not the tab.
+
+import type { HookEnvelope, HookEventName } from './session-hook-events.js'
+import { clipText, toolFingerprint, toolTarget } from './session-hook-events.js'
+import { isKeepWarmSessionTitle } from './agent-session-store.js'
+
+export type WaitingKind = 'permission' | 'question' | 'plan' | 'mcp_input'
+
+export interface WaitingSignal {
+  kind: WaitingKind
+  /** "Bash git push", "Use the API error text in the form?", "" */
+  detail: string
+  toolName: string
+  /** sha256(tool_name + canonical tool_input); '' when the event carried no tool. */
+  fingerprint: string
+  since: number
+  /** The broker's minted id when a permission request is pending there. */
+  requestId: string | null
+}
+
+export interface FailureSignal {
+  kind: string
+  at: number
+}
+
+export interface SessionSignal {
+  sessionId: string
+  firstSeenAt: number
+  lastEventAt: number
+  lastEvent: HookEventName
+  cwd: string | null
+  transcriptPath: string | null
+  permissionMode: string | null
+  model: string | null
+  /** A prompt was submitted and no Stop/StopFailure/SessionEnd has closed it. */
+  turnOpen: boolean
+  turnStartedAt: number | null
+  promptId: string | null
+  /** Stamped by the newest Stop: `state_since` for an idle row. (6.48.1's B6 occupancy clause will compare it to the transcript.) */
+  stopAt: number | null
+  waiting: WaitingSignal | null
+  failure: FailureSignal | null
+  lastReply: string
+  lastTool: string | null
+  lastToolAt: number | null
+  subagentsOpen: number
+  ended: { at: number; reason: string } | null
+  /** The prompt prefix Control already suppresses as a readiness check. */
+  keepWarm: boolean
+  compactions: number
+  /** Events from a COS-spawned child on this id, kept out of the phase. */
+  childEvents: number
+  /** Hooks have been seen for this session: the row may say `state_source: hook`. */
+  hooksSeen: true
+}
+
+export interface ReducerContext {
+  /** Is this pid (or its parent) a process COS spawned itself? Consulted only when the
+   *  envelope was not already classified at ingest (`child`). */
+  isCosSpawnedPid: (pid: number | null) => boolean
+}
+
+/** The tool fields the reducer reads: the live payload's, or the ledger's projection on replay. */
+function toolFacts(p: Record<string, unknown>): { name: string; target: string; fingerprint: string } {
+  const name = typeof p.tool_name === 'string' ? p.tool_name : ''
+  const projectedTarget = typeof p.tool_target === 'string' ? p.tool_target : null
+  const projectedFingerprint = typeof p.tool_fingerprint === 'string' ? p.tool_fingerprint : null
+  return {
+    name,
+    target: projectedTarget ?? toolTarget(p.tool_input),
+    fingerprint: projectedFingerprint ?? toolFingerprint(name, p.tool_input ?? null),
+  }
+}
+
+function fresh(env: HookEnvelope): SessionSignal {
+  return {
+    sessionId: env.sessionId,
+    firstSeenAt: env.ts,
+    lastEventAt: env.ts,
+    lastEvent: env.event,
+    cwd: null,
+    transcriptPath: null,
+    permissionMode: null,
+    model: null,
+    turnOpen: false,
+    turnStartedAt: null,
+    promptId: null,
+    stopAt: null,
+    waiting: null,
+    failure: null,
+    lastReply: '',
+    lastTool: null,
+    lastToolAt: null,
+    subagentsOpen: 0,
+    ended: null,
+    keepWarm: false,
+    compactions: 0,
+    childEvents: 0,
+    hooksSeen: true,
+  }
+}
+
+const str = (v: unknown): string | null => (typeof v === 'string' && v.length > 0 ? v : null)
+
+/** Waiting kinds a PostToolUse of the same tool resolves without a fingerprint match. */
+const TOOL_WAITING: Record<string, WaitingKind> = { AskUserQuestion: 'question', ExitPlanMode: 'plan' }
+
+function resolvesWaiting(waiting: WaitingSignal, event: HookEventName, toolName: string, fingerprint: string): boolean {
+  if (waiting.fingerprint && waiting.fingerprint === fingerprint) return true
+  // Question/plan tools carry no meaningful input to fingerprint; the tool name is the key.
+  if (waiting.kind !== 'permission') return waiting.toolName === toolName
+  // A permission dialog is one at a time (canary 11: hooks run serially), and only a
+  // denied PROMPT fires PermissionDenied, so a denial naming the waiting tool is that
+  // prompt's denial even when the dialog rewrote the input. PostToolUse of the same name
+  // is not: a parallel auto-allowed Bash must not clear a prompt that still stands.
+  return event === 'PermissionDenied' && waiting.toolName === toolName
+}
+
+/**
+ * Apply one envelope. Returns a NEW record; the previous one is never mutated, so a
+ * subscriber holding the old value sees a consistent snapshot.
+ */
+export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelope, ctx: ReducerContext, child?: boolean): SessionSignal {
+  const base = prev ? { ...prev } : fresh(env)
+  const p = env.payload
+  const common = {
+    cwd: str(p.cwd) ?? base.cwd,
+    transcriptPath: str(p.transcript_path) ?? base.transcriptPath,
+    permissionMode: str(p.permission_mode) ?? base.permissionMode,
+  }
+
+  // Rule 2: a COS-spawned child on this session id is counted, never applied. The verdict
+  // is taken at ingest (and remembered on the ledger row) because the spawn ledger forgets
+  // a pid the moment the child exits.
+  if (child ?? ctx.isCosSpawnedPid(env.ppid)) {
+    return { ...base, ...common, childEvents: base.childEvents + 1 }
+  }
+
+  const next: SessionSignal = { ...base, ...common, lastEventAt: Math.max(base.lastEventAt, env.ts), lastEvent: env.event }
+
+  switch (env.event) {
+    case 'SessionStart': {
+      const source = str(p.source) ?? 'startup'
+      next.model = str(p.model) ?? next.model
+      if (source === 'compact') { next.compactions += 1; return next }
+      // startup | resume | clear | fork: a fresh conversation surface, nothing in flight.
+      return { ...next, turnOpen: false, turnStartedAt: null, waiting: null, failure: null, ended: null, subagentsOpen: 0 }
+    }
+    case 'UserPromptSubmit': {
+      const prompt = clipText(p.prompt)
+      return {
+        ...next,
+        turnOpen: true,
+        turnStartedAt: env.ts,
+        promptId: str(p.prompt_id),
+        waiting: null,
+        failure: null,
+        // The same predicate the session list uses to hide readiness checks.
+        keepWarm: prompt.length > 0 && isKeepWarmSessionTitle(prompt),
+      }
+    }
+    case 'PreToolUse': {
+      const tool = toolFacts(p)
+      const kind = TOOL_WAITING[tool.name]
+      if (kind) {
+        return {
+          ...next,
+          turnOpen: true,
+          waiting: { kind, detail: tool.target, toolName: tool.name, fingerprint: tool.fingerprint, since: env.ts, requestId: null },
+        }
+      }
+      return { ...next, lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
+    }
+    case 'PermissionRequest': {
+      const tool = toolFacts(p)
+      return {
+        ...next,
+        turnOpen: true,
+        waiting: {
+          kind: 'permission',
+          detail: tool.target ? `${tool.name} ${tool.target}` : tool.name,
+          toolName: tool.name,
+          fingerprint: tool.fingerprint,
+          since: env.ts,
+          requestId: null,
+        },
+      }
+    }
+    case 'PermissionDenied':
+    case 'PostToolUse':
+    case 'PostToolUseFailure': {
+      const tool = toolFacts(p)
+      const waiting = next.waiting && resolvesWaiting(next.waiting, env.event, tool.name, tool.fingerprint) ? null : next.waiting
+      const ran = env.event !== 'PermissionDenied'
+      return { ...next, waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
+    }
+    case 'Notification': {
+      const type = str(p.notification_type) ?? ''
+      if (type === 'idle_prompt') return { ...next, turnOpen: false }
+      if (next.waiting) return next // a dialog already owns the attention; never downgrade its kind
+      const message = clipText(p.message, 120)
+      const kind: WaitingKind | null =
+        type === 'permission_prompt' ? 'permission'
+        : type === 'agent_needs_input' ? 'question'
+        : type === 'elicitation_dialog' ? 'mcp_input'
+        : null
+      if (!kind) return next
+      return { ...next, turnOpen: true, waiting: { kind, detail: message, toolName: '', fingerprint: '', since: env.ts, requestId: null } }
+    }
+    case 'Stop':
+      return {
+        ...next,
+        turnOpen: false,
+        stopAt: env.ts,
+        waiting: null,
+        lastReply: clipText(p.last_assistant_message) || next.lastReply,
+      }
+    case 'StopFailure':
+      return {
+        ...next,
+        turnOpen: false,
+        waiting: null,
+        failure: { kind: str(p.matcher) ?? str(p.error_type) ?? (clipText(p.error, 60) || 'unknown'), at: env.ts },
+      }
+    case 'SubagentStart':
+      return { ...next, subagentsOpen: next.subagentsOpen + 1 }
+    case 'SubagentStop':
+      return { ...next, subagentsOpen: Math.max(0, next.subagentsOpen - 1) }
+    case 'PostCompact':
+      return { ...next, compactions: next.compactions + 1 }
+    case 'PostModelSwitch':
+      return { ...next, model: str(p.to_model) ?? next.model }
+    case 'SessionEnd':
+      return { ...next, turnOpen: false, waiting: null, ended: { at: env.ts, reason: str(p.reason) ?? 'other' } }
+  }
+}
+
+export type SignalListener = (signal: SessionSignal, env: HookEnvelope) => void
+
+/** Records older than this after a SessionEnd are dropped; Control keeps its own ledger. */
+export const SIGNAL_PRUNE_AFTER_END_MS = 6 * 60 * 60_000
+/** A record with no event at all for this long is a tab that died without a SessionEnd. */
+export const SIGNAL_PRUNE_SILENT_MS = 24 * 60 * 60_000
+
+export class SessionSignalStore {
+  private readonly signals = new Map<string, SessionSignal>()
+  private readonly listeners = new Set<SignalListener>()
+  private readonly ctx: ReducerContext
+
+  constructor(ctx: ReducerContext) {
+    this.ctx = ctx
+  }
+
+  apply(env: HookEnvelope, child?: boolean): SessionSignal {
+    const next = applyHookEvent(this.signals.get(env.sessionId), env, this.ctx, child)
+    this.signals.set(env.sessionId, next)
+    for (const listener of this.listeners) {
+      try { listener(next, env) } catch (error) {
+        console.error(`[session-signals] listener failed: ${error instanceof Error ? error.message : error}`)
+      }
+    }
+    return next
+  }
+
+  /** RESERVED FOR 6.48.2 (the permission broker); no caller in 6.48.0. Attach the broker's
+   *  minted id so rows can carry `pending_permission_id`. */
+  attachPermissionRequestId(sessionId: string, requestId: string | null): void {
+    const current = this.signals.get(sessionId)
+    if (!current?.waiting || current.waiting.kind !== 'permission') return
+    this.signals.set(sessionId, { ...current, waiting: { ...current.waiting, requestId } })
+  }
+
+  /** RESERVED FOR 6.48.2 (the permission broker); no caller in 6.48.0. The broker decided
+   *  (allow or deny): that is resolution evidence. */
+  resolveWaiting(sessionId: string): void {
+    const current = this.signals.get(sessionId)
+    if (!current?.waiting) return
+    this.signals.set(sessionId, { ...current, waiting: null })
+  }
+
+  get(sessionId: string): SessionSignal | undefined {
+    return this.signals.get(sessionId.toLowerCase())
+  }
+
+  /** Eight-char prefix lookup for the registry's short ids. Two matches means no answer. */
+  getByPrefix(prefix: string): SessionSignal | undefined {
+    const needle = prefix.toLowerCase()
+    let found: SessionSignal | undefined
+    for (const [id, signal] of this.signals) {
+      if (!id.startsWith(needle)) continue
+      if (found) return undefined
+      found = signal
+    }
+    return found
+  }
+
+  subscribe(listener: SignalListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** Drop records that ended long ago, and records silent for a day (a tab that died with no SessionEnd). */
+  prune(nowMs = Date.now()): number {
+    let dropped = 0
+    for (const [id, signal] of this.signals) {
+      const endedLongAgo = !!signal.ended && !signal.turnOpen && nowMs - signal.ended.at > SIGNAL_PRUNE_AFTER_END_MS
+      const silentForADay = nowMs - signal.lastEventAt > SIGNAL_PRUNE_SILENT_MS
+      if (endedLongAgo || silentForADay) {
+        this.signals.delete(id)
+        dropped++
+      }
+    }
+    return dropped
+  }
+
+  size(): number {
+    return this.signals.size
+  }
+
+  /** Every record, newest event first. A copy: callers cannot reach the map. */
+  snapshot(): SessionSignal[] {
+    return [...this.signals.values()].sort((a, b) => b.lastEventAt - a.lastEventAt)
+  }
+
+  newestEventAt(): number | null {
+    let newest: number | null = null
+    for (const signal of this.signals.values()) {
+      if (newest === null || signal.lastEventAt > newest) newest = signal.lastEventAt
+    }
+    return newest
+  }
+
+  __resetForTests(): void {
+    this.signals.clear()
+    this.listeners.clear()
+  }
+}