@gotcos/glasses-server 7.0.7 → 7.0.27

package/server/lib/session-cache-writer.ts

@@ -188,9 +188,16 @@ function loadArchivedSessions(): SessionCacheEntry[] {
   return entries
 }
 
+// S1 (2026-11-09): said once per process. COS Control's generated .env has no COS_SCRIPTS_DIR, so
+// on a new install this ran after every exchange (5 s debounce) and printed each time.
+let scriptsDirMissingNoted = false
+
 export function updateGlassesSessionCache(): void {
   if (!SCRIPTS_DIR) {
-    console.warn('[session-cache] COS_SCRIPTS_DIR not set — skipping cache write')
+    if (!scriptsDirMissingNoted) {
+      scriptsDirMissingNoted = true
+      console.warn('[session-cache] COS_SCRIPTS_DIR not set — skipping cache writes (said once)')
+    }
     return
   }
 

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

@@ -13,6 +13,8 @@
 // interactive-only events (Notification, StopFailure, sub-agents, compaction, model switch)
 // whose shapes are still the documented ones until a Desktop recording lands.
 
+import { questionRowText, waitingQuestionWordsEnabled } from './full-hold.js'
+import { captureTurnAsk, turnEndAsksEnabled, WRAP_UP_TOOL } from './turn-end-ask.js'
 import { createHash } from 'node:crypto'
 import { profileIdForCodexPath } from './codex-homes.js'
 import { isKeyProfileId } from '../../shared/key-preference.js'
@@ -208,12 +210,31 @@ function canonicalJson(value: unknown): string {
 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]
+  // X1: an AskUserQuestion carries only `questions`. With COS_WAITING_QUESTION_WORDS on (default ON, Miles
+  // 22:10) its target is its first question's text, control and format characters out, cut at `max` (80)
+  // below, so a row waiting on a question says what it asks. Never an option, a description or an answer.
+  // `0`: a question's target is '' exactly as in 7.0.13, and the words reach neither the ledger nor a row.
+  const firstQuestion = waitingQuestionWordsEnabled(process.env) && Array.isArray(i.questions) && i.questions.length > 0 && i.questions[0] && typeof i.questions[0] === 'object'
+    ? questionRowText((i.questions[0] as Record<string, unknown>).question)
+    : undefined
+  const candidate = [i.command, i.file_path, i.path, i.url, i.pattern, i.query, i.prompt, i.description, firstQuestion]
     .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
 }
 
+/**
+ * 7.0.18 (X1): a turn-end ask (lib/turn-end-ask.ts) kept in the ledger so a restart replays it. Only on a
+ * PostToolUse of `mcp__ccd_turn__wrap_up`, only with COS_TURN_END_ASKS on, and only the bounded capture:
+ * the ask (80), at most 2 reply labels (40) and `blocked`. Never `recap`, never `tool_response`. An
+ * additive key, so 7.0.17 replays the row and ignores it. `tool_target` stays as 7.0.17 computes it.
+ */
+function turnAskProjection(event: HookEventName, toolName: string, toolInput: unknown): Record<string, unknown> {
+  if (event !== 'PostToolUse' || toolName !== WRAP_UP_TOOL || !turnEndAsksEnabled()) return {}
+  const capture = captureTurnAsk(toolInput, waitingQuestionWordsEnabled(process.env))
+  return capture ? { turn_ask: capture } : {}
+}
+
 /** Text fields kept from a payload. Everything else is dropped before the ledger sees it. */
 export const HOOK_TEXT_MAX = 400
 
@@ -272,6 +293,7 @@ export function projectHookPayload(event: HookEventName, payload: Record<string,
         ...(event === 'PermissionRequest' && Array.isArray(payload.permission_suggestions)
           ? { permission_suggestions: payload.permission_suggestions.slice(0, 4) }
           : {}),
+        ...turnAskProjection(event, toolName, payload.tool_input),
       }
     }
     case 'Notification':

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

@@ -21,6 +21,9 @@ import { HALT_MARKER_TTL_MS, HALT_REARM_UNVERIFIED_MS, clearHaltMarkerOnSessionE
 import { cancelVoidsOpenTurn, threadCancel } from './session-cancel.js'
 import { ensureHookRuntimeFiles, ensureStableHookScript, hookSpoolDir, hookStatus, type HookStatus } from './claude-hooks-installer.js'
 import { codexHooksHealthField, cursorObserverHealthField, type CodexHooksHealth, type CursorObserverHealth } from './provider-observe.js'
+import { readHidIdleSeconds } from './permission-broker.js'
+import { waitingQuestionWordsEnabled } from './full-hold.js'
+import { TurnEndAskTracker, turnEndAsksEnabled, type TurnEndAskCounters } from './turn-end-ask.js'
 
 export function sessionHooksEnabled(): boolean {
   const raw = process.env.COS_SESSION_HOOKS
@@ -256,6 +259,8 @@ export function haltHandedOffTurn(sessionId: string, marker: HaltMarker, turn: {
 let ledger: SessionHookLedger | null = null
 let ingester: SpoolIngester | null = null
 let replayed: { rows: number; applied: number } | null = null
+/** 7.0.18 (X1): the turn-end ask tracker, only while COS_TURN_END_ASKS is on (read once at startup). */
+let turnEndAskTracker: TurnEndAskTracker | 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
@@ -271,6 +276,18 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
   ledger = new SessionHookLedger(dataPath('session-hook-events.jsonl'))
   const enabled = sessionHooksEnabled()
   const since = Date.now() - LEDGER_REPLAY_WINDOW_MS
+  // 7.0.18 (X1): subscribed BEFORE the replay, so an ask asked before a restart is still known after it.
+  // Off (COS_TURN_END_ASKS=0): no tracker, no subscription, no desk reads, every row 7.0.17's.
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = enabled && turnEndAsksEnabled() ? new TurnEndAskTracker({
+    now: () => Date.now(),
+    enabled: () => true,
+    words: () => waitingQuestionWordsEnabled(process.env),
+    readDeskIdleSeconds: readHidIdleSeconds,
+    deskIdleSeconds,
+  }) : null
+  const tracker = turnEndAskTracker
+  const unsubscribeTurnAsk = tracker ? sessionSignalStore.subscribe((signal, env, child) => tracker.observe(env, child, signal)) : () => {}
   const replay = ledger.replay(since, (env, _key, child, entrypoint) => {
     if (!enabled) return
     sessionSignalStore.apply(env, child)
@@ -321,6 +338,8 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
     stop() {
       clearInterval(pruneTimer)
       unsubscribeHalt()
+      unsubscribeTurnAsk()
+      tracker?.stop()
       ingester?.stop()
     },
   }
@@ -472,8 +491,10 @@ export function deriveForRow(input: { sessionId: string; registry?: RegistryFact
     prevDeadScans: prev?.scans ?? 0,
     prevDeadSince: prev?.since ?? null,
     attachedTurn: input.attachedTurn === true,
+    ...(turnEndAskTracker ? { turnEndAsk: turnEndAskTracker.visibleAsk(key, now) } : {}),
   })
   if (derived.agent_state === 'ended') {
+    turnEndAskTracker?.sessionRowEnded(key)
     for (const listener of rowEndedListeners) {
       try { listener(key) } catch { /* a listener never breaks a row */ }
     }
@@ -489,7 +510,20 @@ export function deriveForRow(input: { sessionId: string; registry?: RegistryFact
   return derived
 }
 
+/** 7.0.18 (X1): the turn-end ask counters for the authenticated stats, or null with the switch off. */
+export function turnEndAskStats(): (TurnEndAskCounters & { tracked: number }) | null {
+  return turnEndAskTracker ? turnEndAskTracker.stats() : null
+}
+
+/** Tests only: the tracker the runtime would build, installed directly. */
+export function __setTurnEndAskTrackerForTests(tracker: TurnEndAskTracker | null): void {
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = tracker
+}
+
 export function __resetSessionHooksForTests(): void {
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = null
   rowEndedListeners.clear()
   sessionSignalStore.__resetForTests()
   deadById.clear()

package/server/lib/session-log.ts

@@ -2,9 +2,12 @@
 // so COS can query Glasses sessions by original UUID, date, domain, or content.
 // Fires on: TTL expiry, explicit /api/sessions/:id/end, server shutdown.
 
-import { appendFileSync, chmodSync, mkdirSync } from 'node:fs'
+import { appendFileSync, chmodSync, closeSync, constants as fsConstants, createReadStream, fstatSync, mkdirSync, openSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { resolve, dirname } from 'node:path'
 import type { Exchange } from './conversation.js'
+import { atomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
 
 // Resolve COS_SCRIPTS_DIR independently (same pattern as session-cache-writer)
 let SCRIPTS_DIR: string | null = null
@@ -132,7 +135,13 @@ export function buildSessionLogEntry(input: EndSessionInput): SessionLogEntry {
   }
 }
 
-/** Append a session log entry to .glasses_sessions.jsonl */
+/** Where the ledger lives, or null when COS_SCRIPTS_DIR is not set. */
+export function sessionLogPath(): string | null {
+  return SCRIPTS_DIR ? resolve(SCRIPTS_DIR, LOG_FILE_NAME) : null
+}
+
+/** Append a session log entry to .glasses_sessions.jsonl. Unconditional: callers that may
+ * repeat an unchanged session go through writeSessionLogIfChanged instead. */
 export function writeSessionLog(entry: SessionLogEntry): boolean {
   if (!SCRIPTS_DIR) {
     console.warn('[session-log] COS_SCRIPTS_DIR not set — skipping session log')
@@ -153,11 +162,311 @@ export function writeSessionLog(entry: SessionLogEntry): boolean {
   }
 }
 
-/** End a session: build entry and write to JSONL */
+// ── Write-once-per-content ledger state (S1, 2026-11-09) ──────────────────────────────
+// Before this, every server shutdown appended EVERY session with exchanges (about 300 on
+// Miles's Mac, since sessions.json keeps all ages), and the first auto-snapshot after
+// each boot appended them all again, because its "unchanged" check lived only in memory.
+// 72 boots in 14 days grew the ledger to 1.94 GB: 118,221 entries for 588 sessions, one
+// session copied 1,254 times. The state below survives restarts, so an unchanged session
+// is never appended twice. It is keyed by the ledger path, so pointing COS_SCRIPTS_DIR
+// elsewhere starts a fresh state instead of suppressing writes to the new file.
+
+/** Why an entry is being written. A snapshot or a shutdown is a copy of a live session;
+ * an end (TTL, explicit end, clear) closes it. */
+export type SessionLogKind = 'snapshot' | 'shutdown' | 'end'
+
+interface LedgerStateRow { sig: string; kind: SessionLogKind; at: number }
+/** `ino`: the ledger file the rows describe. A different or missing file (compaction, a restore, a
+ * deletion) means the rows no longer describe what is on disk, so they are dropped (Q1 review S5). */
+interface LedgerState { version: 1; logPath: string; ino?: number; sessions: Record<string, LedgerStateRow> }
+
+function ledgerInode(logPath: string): number | null {
+  try { return statSync(logPath).ino } catch { return null }
+}
+
+/** Most sessions the state remembers; the oldest by last write are dropped past this. */
+export const SESSION_LOG_STATE_CAP = 5_000
+const STATE_FILE_NAME = 'session-log-state.json'
+
+let ledgerState: LedgerState | null = null
+let ledgerStateDirty = false
+let ledgerStateFlushTimer: ReturnType<typeof setTimeout> | null = null
+
+function stateFilePath(): string {
+  return dataPath(STATE_FILE_NAME)
+}
+
+function loadLedgerState(logPath: string): LedgerState {
+  if (ledgerState && ledgerState.logPath === logPath) return ledgerState
+  const fresh: LedgerState = { version: 1, logPath, sessions: {} }
+  try {
+    const result = loadJsonOrQuarantine<LedgerState>(stateFilePath())
+    const loaded = result.status === 'ok' ? result.data : null
+    if (loaded && loaded.version === 1 && loaded.logPath === logPath
+      && loaded.sessions && typeof loaded.sessions === 'object') {
+      ledgerState = loaded
+      return loaded
+    }
+  } catch { /* unreadable state: start fresh; the worst case is one more copy per session */ }
+  ledgerState = fresh
+  return fresh
+}
+
+/** What makes two entries for one session the same: its messages, counts and model.
+ * Timestamps the writer invents (a snapshot's ended_at is "now") are not part of it. */
+export function sessionLogSignature(entry: SessionLogEntry): string {
+  return createHash('sha256').update(JSON.stringify([
+    entry.total_message_count,
+    entry.user_message_count,
+    entry.assistant_message_count,
+    entry.model_preference,
+    entry.created_at,
+    entry.messages,
+  ])).digest('hex').slice(0, 32)
+}
+
+/** Persist the state now (atomic). Called at the end of a shutdown or snapshot pass. */
+export function flushSessionLogState(): void {
+  if (ledgerStateFlushTimer) { clearTimeout(ledgerStateFlushTimer); ledgerStateFlushTimer = null }
+  if (!ledgerState || !ledgerStateDirty) return
+  const rows = Object.entries(ledgerState.sessions)
+  if (rows.length > SESSION_LOG_STATE_CAP) {
+    rows.sort((a, b) => b[1].at - a[1].at)
+    ledgerState.sessions = Object.fromEntries(rows.slice(0, SESSION_LOG_STATE_CAP))
+  }
+  try {
+    mkdirSync(dirname(stateFilePath()), { recursive: true, mode: 0o700 })
+    atomicWriteFileSync(stateFilePath(), JSON.stringify(ledgerState), { mode: 0o600 })
+    ledgerStateDirty = false
+  } catch (err) {
+    console.error('[session-log] Failed to save ledger state:', err)
+  }
+}
+
+function scheduleStateFlush(): void {
+  if (ledgerStateFlushTimer) return
+  ledgerStateFlushTimer = setTimeout(() => { ledgerStateFlushTimer = null; flushSessionLogState() }, 1_000)
+  ledgerStateFlushTimer.unref?.()
+}
+
+/** 'unconfigured': COS_SCRIPTS_DIR is not set, so there is no ledger. That is the default for
+ * every new install (COS Control's generated .env does not set it), not a failure. */
+export type SessionLogWriteResult = 'written' | 'unchanged' | 'unconfigured' | 'failed'
+
+let unconfiguredNoted = false
+/** Say once per process that there is no ledger (Q1 review M2: the auto-snapshot printed it per
+ * session every 5 minutes on a new install). */
+function noteUnconfigured(): void {
+  if (unconfiguredNoted) return
+  unconfiguredNoted = true
+  console.log('[session-log] COS_SCRIPTS_DIR not set: no .glasses_sessions.jsonl ledger on this install (said once)')
+}
+
+/** Append the entry unless this session's content was already written.
+ *  - snapshot / shutdown: skipped when the last write for the session (any kind) had the same content.
+ *  - end: skipped only when the last write was itself an end with the same content, so a real end
+ *    always lands once even after a snapshot of the same content (its slug and end_reason differ). */
+export function writeSessionLogIfChanged(entry: SessionLogEntry, kind: SessionLogKind): SessionLogWriteResult {
+  const logPath = sessionLogPath()
+  if (!logPath) { noteUnconfigured(); return 'unconfigured' }
+  const state = loadLedgerState(logPath)
+  const ino = ledgerInode(logPath)
+  if (state.ino !== undefined && state.ino !== ino) {
+    state.sessions = {}
+    state.ino = undefined
+    ledgerStateDirty = true
+  }
+  const sig = sessionLogSignature(entry)
+  const prev = state.sessions[entry.session_id]
+  if (prev && prev.sig === sig && (kind !== 'end' || prev.kind === 'end')) return 'unchanged'
+  if (!writeSessionLog(entry)) return 'failed'
+  state.ino = ledgerInode(logPath) ?? undefined
+  state.sessions[entry.session_id] = { sig, kind, at: Date.now() }
+  ledgerStateDirty = true
+  scheduleStateFlush()
+  return 'written'
+}
+
+function kindForReason(reason: EndSessionInput['endReason']): SessionLogKind {
+  return reason === 'server_shutdown' ? 'shutdown' : 'end'
+}
+
+/** End a session: build entry and write to JSONL (once per content; see writeSessionLogIfChanged). */
 export function logSessionEnd(input: EndSessionInput): SessionLogEntry | null {
   if (input.exchanges.length === 0) return null
 
   const entry = buildSessionLogEntry(input)
-  writeSessionLog(entry)
+  writeSessionLogIfChanged(entry, kindForReason(input.endReason))
   return entry
 }
+
+// ── Reader (S1, 2026-11-09) ───────────────────────────────────────────────────────────
+// /api/sessions/lookup read the whole ledger with readFileSync(...).toString(). At 1.94 GB
+// that throws (the string is longer than V8 allows), the catch treated it as "no log
+// file", and every lookup silently answered from live sessions only, after blocking the
+// event loop for the read. This reader streams and reads only the bytes appended since the
+// last call. It keeps, per session, what the old loop kept: the FIRST line's range, plus the
+// latest end any line reported. Which of the two a lookup uses is the route's old rule
+// (lookupRangesFromHistory below), unchanged.
+
+export interface SessionLogRange {
+  /** created_at of the session's first line in the file. Never widened (the old loop never moved it). */
+  start: number
+  /** ended_at of that first line. */
+  firstEnd: number
+  /** The latest ended_at of any line for the session. */
+  end: number
+}
+
+interface RangeIndex { logPath: string; ino: number; offset: number; ranges: Map<string, SessionLogRange> }
+let rangeIndex: RangeIndex | null = null
+let rangeIndexBuild: Promise<Map<string, SessionLogRange>> | null = null
+
+const ENTRY_PREFIX = /^\{"session_id":"((?:[^"\\]|\\.)*)","device_id":"(?:[^"\\]|\\.)*","created_at":"([^"]*)","ended_at":"([^"]*)"/
+
+/** The identity and time range of one ledger line, or null for a line that is not an entry. */
+export function parseSessionLogLine(line: string): { sessionId: string; start: number; end: number } | null {
+  let sessionId: string | undefined
+  let createdAt: string | undefined
+  let endedAt: string | undefined
+  const prefix = ENTRY_PREFIX.exec(line.slice(0, 512))
+  if (prefix) {
+    try { sessionId = JSON.parse(`"${prefix[1]}"`) } catch { sessionId = undefined }
+    createdAt = prefix[2]
+    endedAt = prefix[3]
+  }
+  if (sessionId === undefined) {
+    try {
+      const d = JSON.parse(line)
+      if (d && typeof d.session_id === 'string') {
+        sessionId = d.session_id
+        createdAt = typeof d.created_at === 'string' ? d.created_at : undefined
+        endedAt = typeof d.ended_at === 'string' ? d.ended_at : undefined
+      }
+    } catch { return null }
+  }
+  if (!sessionId || !createdAt) return null
+  const start = new Date(createdAt).getTime()
+  if (!Number.isFinite(start)) return null
+  const endParsed = endedAt ? new Date(endedAt).getTime() : NaN
+  const end = Number.isFinite(endParsed) ? endParsed : start + 7_200_000
+  return { sessionId, start, end }
+}
+
+function mergeRange(ranges: Map<string, SessionLogRange>, id: string, start: number, end: number): void {
+  const existing = ranges.get(id)
+  if (!existing) { ranges.set(id, { start, firstEnd: end, end }); return }
+  if (end > existing.end) existing.end = end
+}
+
+/**
+ * The ranges /api/sessions/lookup matches against, in first-seen order: the route's rule from
+ * before S1, unchanged (Q1 review M1, 2026-11-09). A session's range starts at its first line.
+ * Its end may be widened by later lines ONLY when the session is not in memory. A session still
+ * in memory (restored from sessions.json, however old) keeps its first line's end, because every
+ * boot snapshot of it is stamped ended_at = now: widening would let an October session claim
+ * November timestamps, and the glasses companion stores the answer for good.
+ * Sessions in `live` are skipped (the route lists them first, extended to now).
+ */
+export function lookupRangesFromHistory(
+  history: ReadonlyMap<string, SessionLogRange>,
+  inMemory: (sessionId: string) => boolean,
+  live: ReadonlySet<string> = new Set(),
+): Array<{ sid: string; start: number; end: number }> {
+  const out: Array<{ sid: string; start: number; end: number }> = []
+  for (const [sid, range] of history) {
+    if (live.has(sid)) continue
+    out.push({ sid, start: range.start, end: inMemory(sid) ? range.firstEnd : Math.max(range.firstEnd, range.end) })
+  }
+  return out
+}
+
+/** Index lines in [from, to) of the file into `ranges`. Returns the offset just past the
+ * last complete line, so a half-written last line is read again next time. */
+async function indexBytes(fd: number, from: number, to: number, ranges: Map<string, SessionLogRange>): Promise<number> {
+  if (to <= from) return from
+  let offset = from
+  let carry: Buffer[] = []
+  let carryLen = 0
+  // Reads the descriptor readSessionLogRanges opened and checked (a regular file), never the path again.
+  const stream = createReadStream('', { fd, autoClose: false, start: from, end: to - 1, highWaterMark: 1 << 20 })
+  for await (const raw of stream) {
+    let chunk = raw as Buffer
+    let nl = chunk.indexOf(10)
+    while (nl !== -1) {
+      const piece = chunk.subarray(0, nl)
+      // Only the first 512 bytes are needed for the fast path; keep the whole line only
+      // while it is short or when the fast path fails (legacy key order).
+      const lineBuf = carryLen ? Buffer.concat([...carry, piece]) : piece
+      const lineLen = carryLen + piece.length
+      carry = []; carryLen = 0
+      const head = lineBuf.subarray(0, Math.min(lineBuf.length, 512)).toString('utf8')
+      let parsed = ENTRY_PREFIX.test(head) ? parseSessionLogLine(head) : null
+      if (!parsed && lineBuf.length <= 64 * 1024 * 1024) parsed = parseSessionLogLine(lineBuf.toString('utf8'))
+      if (parsed) mergeRange(ranges, parsed.sessionId, parsed.start, parsed.end)
+      offset += lineLen + 1
+      chunk = chunk.subarray(nl + 1)
+      nl = chunk.indexOf(10)
+    }
+    if (chunk.length) { carry.push(Buffer.from(chunk)); carryLen += chunk.length }
+  }
+  return offset
+}
+
+/** One time range per session from the ledger, read incrementally. A shrunk or replaced
+ * file (compaction) is re-read from the start. A missing file is an empty map. */
+export async function readSessionLogRanges(path: string | null = sessionLogPath()): Promise<Map<string, SessionLogRange>> {
+  if (!path) return new Map()
+  if (rangeIndexBuild) return rangeIndexBuild
+  rangeIndexBuild = (async () => {
+    // O_NONBLOCK (hazard-invariants ratchet): openSync on a FIFO with no writer never returns, and it runs on
+    // the server's only JS thread. Not O_NOFOLLOW: the append writer follows a symlinked ledger, and the reader
+    // must read what the writer writes. fstat follows the link, so a link to a FIFO or folder is refused below.
+    const nonBlock = typeof fsConstants.O_NONBLOCK === 'number' ? fsConstants.O_NONBLOCK : 0
+    let fd: number
+    try {
+      fd = openSync(path, fsConstants.O_RDONLY | nonBlock)
+    } catch {
+      rangeIndex = null
+      return new Map<string, SessionLogRange>()
+    }
+    try {
+      const st = fstatSync(fd)
+      if (!st.isFile()) {
+        rangeIndex = null
+        return new Map<string, SessionLogRange>()
+      }
+      if (!rangeIndex || rangeIndex.logPath !== path || rangeIndex.ino !== st.ino || rangeIndex.offset > st.size) {
+        rangeIndex = { logPath: path, ino: st.ino, offset: 0, ranges: new Map() }
+      }
+      const index = rangeIndex
+      index.offset = await indexBytes(fd, index.offset, st.size, index.ranges)
+      return index.ranges
+    } finally {
+      closeSync(fd)
+    }
+  })()
+  try {
+    return await rangeIndexBuild
+  } finally {
+    rangeIndexBuild = null
+  }
+}
+
+/** Size of the ledger in bytes, or null when it does not exist (diagnostics). */
+export function sessionLogSize(): number | null {
+  const path = sessionLogPath()
+  if (!path) return null
+  try { return statSync(path).size } catch { return null }
+}
+
+/** Tests only: forget the in-memory state and reader index. */
+export function __resetSessionLogForTests(): void {
+  if (ledgerStateFlushTimer) clearTimeout(ledgerStateFlushTimer)
+  ledgerStateFlushTimer = null
+  ledgerState = null
+  ledgerStateDirty = false
+  unconfiguredNoted = false
+  rangeIndex = null
+  rangeIndexBuild = null
+}