@gotcos/glasses-server 7.0.7 → 7.0.18

package/server/lib/claude-hooks-installer.ts

@@ -24,6 +24,7 @@ import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { atomicWriteFileSync } from './atomic-fs.js'
+import { FULL_HOLD_HOOK_WAIT_S, NON_QUESTION_MATCHER, QUESTION_MATCHER, fullHoldSwitches } from './full-hold.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -187,6 +188,93 @@ function priorWaitBlock(scriptPath: string, sub: HookSubscription, paths: HookPa
   return canonicalBlock(scriptPath, { event: sub.event, async: sub.async, timeout: LEGACY_PERMISSION_HOOK_TIMEOUT_S }, paths)
 }
 
+/**
+ * X1 (2026-11-09): how the PermissionRequest hook is written. With `COS_QUESTION_FULL_HOLD` and
+ * `COS_APPROVAL_FULL_HOLD` both off (the default) it is the ONE block every release since 6.60.0
+ * writes, byte for byte (`split: false`). With either on it is TWO blocks of ours, split by matcher
+ * (canary C9, both engines): `AskUserQuestion` waits `questionWaitS`, everything else `otherWaitS`;
+ * a kind whose switch is on waits FULL_HOLD_HOOK_WAIT_S, the other keeps 630. Each block passes its
+ * own wait to the script, so the stamp a request carries is its own block's. Reinstall hooks is what
+ * writes it: until then the file reads `drift` (`priorWaitOnly`, still halt-ready).
+ */
+export interface PermissionHookPlan { split: boolean; questionWaitS: number; otherWaitS: number }
+
+export function permissionHookPlan(env: NodeJS.ProcessEnv = process.env): PermissionHookPlan {
+  const on = fullHoldSwitches(env)
+  if (!on.questions && !on.approvals) return { split: false, questionWaitS: PERMISSION_HOOK_TIMEOUT_S, otherWaitS: PERMISSION_HOOK_TIMEOUT_S }
+  return {
+    split: true,
+    questionWaitS: on.questions ? FULL_HOLD_HOOK_WAIT_S : PERMISSION_HOOK_TIMEOUT_S,
+    otherWaitS: on.approvals ? FULL_HOLD_HOOK_WAIT_S : PERMISSION_HOOK_TIMEOUT_S,
+  }
+}
+
+const UNSPLIT_PLAN: PermissionHookPlan = { split: false, questionWaitS: PERMISSION_HOOK_TIMEOUT_S, otherWaitS: PERMISSION_HOOK_TIMEOUT_S }
+
+/** The two blocks of a split PermissionRequest, question block first. */
+function splitPermissionBlocks(scriptPath: string, sub: HookSubscription, paths: HookPaths, questionWaitS: number, otherWaitS: number): Record<string, unknown>[] {
+  return [
+    canonicalBlock(scriptPath, { ...sub, matcher: QUESTION_MATCHER, timeout: questionWaitS }, paths),
+    canonicalBlock(scriptPath, { ...sub, matcher: NON_QUESTION_MATCHER, timeout: otherWaitS }, paths),
+  ]
+}
+
+/** Our blocks for one event under a plan. Every event but a split PermissionRequest: exactly `[canonicalBlock]`. */
+export function canonicalBlocks(scriptPath: string, sub: HookSubscription, paths: HookPaths, plan: PermissionHookPlan = UNSPLIT_PLAN): Record<string, unknown>[] {
+  if (sub.event === 'PermissionRequest' && plan.split) return splitPermissionBlocks(scriptPath, sub, paths, plan.questionWaitS, plan.otherWaitS)
+  return [canonicalBlock(scriptPath, sub, paths)]
+}
+
+/**
+ * Earlier shapes of our PermissionRequest blocks that differ from the plan only by the wait: the
+ * pre-6.60.0 block (`priorWaitBlock`); with a split plan, the one unsplit block; with an unsplit
+ * plan, every split pair this file can write (a flag turned off after Reinstall hooks).
+ */
+function priorWaitVariants(scriptPath: string, sub: HookSubscription, paths: HookPaths, plan: PermissionHookPlan): Record<string, unknown>[][] {
+  const prior = priorWaitBlock(scriptPath, sub, paths)
+  if (!prior) return []
+  const out: Record<string, unknown>[][] = [[prior]]
+  if (plan.split) out.push([canonicalBlock(scriptPath, sub, paths)])
+  const waits = [PERMISSION_HOOK_TIMEOUT_S, FULL_HOLD_HOOK_WAIT_S]
+  for (const q of waits) for (const o of waits) {
+    if (plan.split && q === plan.questionWaitS && o === plan.otherWaitS) continue
+    if (q === PERMISSION_HOOK_TIMEOUT_S && o === PERMISSION_HOOK_TIMEOUT_S) continue
+    out.push(splitPermissionBlocks(scriptPath, sub, paths, q, o))
+  }
+  return out
+}
+
+/** Whether a hook block's `matcher` selects this tool, as Claude Code reads it: no matcher, `*` or an empty one is every tool, else a regex. */
+function matcherSelects(matcher: unknown, toolName: string): boolean {
+  if (matcher === undefined || matcher === null || matcher === '' || matcher === '*') return true
+  if (typeof matcher !== 'string') return false
+  if (matcher === toolName) return true
+  try { return new RegExp(`^(?:${matcher})$`).test(toolName) } catch { return false }
+}
+
+/**
+ * X1: how long Claude Code waits on our PermissionRequest hook FOR THIS TOOL: the smallest timeout
+ * among our blocks whose matcher selects it. With the one unsplit block, the same number as
+ * `permissionHookTimeoutS`. Null when none of ours selects it or one has no usable number.
+ */
+export function permissionHookTimeoutForToolS(settings: unknown, toolName: string): number | null {
+  const hooks = settings && typeof settings === 'object' ? (settings as Record<string, unknown>).hooks : null
+  const blocks = hooks && typeof hooks === 'object' ? (hooks as Record<string, unknown>).PermissionRequest : null
+  if (!Array.isArray(blocks)) return null
+  let least: number | null = null
+  for (const block of blocks) {
+    if (!blockIsOurs(block)) continue
+    if (!matcherSelects((block as HookBlock).matcher, toolName)) continue
+    for (const h of (block as HookBlock).hooks as unknown[]) {
+      if (!hookIsOurs(h)) continue
+      const timeout = (h as { timeout?: unknown }).timeout
+      if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0) return null
+      least = least === null ? timeout : Math.min(least, timeout)
+    }
+  }
+  return least
+}
+
 /**
  * 6.60.0: how long Claude Code waits on OUR PermissionRequest hook, read from a settings
  * object: the smallest `timeout` among our entries (Claude runs each, so the first to give up
@@ -220,7 +308,7 @@ export type MergeResult =
  * `hooks` key that is not an object, or an event whose value is not an array, is refused
  * rather than replaced: "preserving every existing hook block" is the contract.
  */
-export function mergeHookSettings(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths()): MergeResult {
+export function mergeHookSettings(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths(), plan: PermissionHookPlan = permissionHookPlan()): MergeResult {
   const settings: Record<string, unknown> = current && typeof current === 'object' && !Array.isArray(current) ? { ...(current as Record<string, unknown>) } : {}
   const before = JSON.stringify(settings)
   if (settings.hooks !== undefined && (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks))) return { ok: false, reason: 'settings_hooks_invalid' }
@@ -231,7 +319,7 @@ export function mergeHookSettings(current: unknown, scriptPath: string, paths: H
     if (value !== undefined && !Array.isArray(value)) return { ok: false, reason: 'settings_hooks_invalid' }
     const existing = Array.isArray(value) ? value : []
     const foreign = existing.filter(b => !blockIsOurs(b))
-    hooks[sub.event] = [...foreign, canonicalBlock(scriptPath, sub, paths)]
+    hooks[sub.event] = [...foreign, ...canonicalBlocks(scriptPath, sub, paths, plan)]
   }
   settings.hooks = hooks
   return { ok: true, settings, changed: JSON.stringify(settings) !== before }
@@ -258,7 +346,7 @@ export function stripHookSettings(current: unknown): MergeResult {
  * (6.60.0) names the drifted events whose one block of ours is exactly the block an earlier
  * release wrote, differing only by the wait (`priorWaitBlock`).
  */
-export function subscribedEvents(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths()): { subscribed: string[]; missing: string[]; drifted: string[]; priorWait: string[] } {
+export function subscribedEvents(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths(), plan: PermissionHookPlan = permissionHookPlan()): { subscribed: string[]; missing: string[]; drifted: string[]; priorWait: string[] } {
   const hooks = current && typeof current === 'object' && (current as Record<string, unknown>).hooks
   const table = hooks && typeof hooks === 'object' ? hooks as Record<string, unknown> : {}
   const subscribed: string[] = []
@@ -269,11 +357,10 @@ export function subscribedEvents(current: unknown, scriptPath: string, paths: Ho
     const blocks = Array.isArray(table[sub.event]) ? table[sub.event] as unknown[] : []
     const ours = blocks.filter(blockIsOurs)
     if (ours.length === 0) { missing.push(sub.event); continue }
-    const canonical = JSON.stringify(canonicalBlock(scriptPath, sub, paths))
-    if (ours.length === 1 && JSON.stringify(ours[0]) === canonical) { subscribed.push(sub.event); continue }
+    const canonical = JSON.stringify(canonicalBlocks(scriptPath, sub, paths, plan))
+    if (JSON.stringify(ours) === canonical) { subscribed.push(sub.event); continue }
     drifted.push(sub.event)
-    const prior = priorWaitBlock(scriptPath, sub, paths)
-    if (prior && ours.length === 1 && JSON.stringify(ours[0]) === JSON.stringify(prior)) priorWait.push(sub.event)
+    if (priorWaitVariants(scriptPath, sub, paths, plan).some(variant => JSON.stringify(variant) === JSON.stringify(ours))) priorWait.push(sub.event)
   }
   return { subscribed, missing, drifted, priorWait }
 }
@@ -312,6 +399,11 @@ export interface HookStatus {
   observerOnlyDrift?: boolean
   /** 6.60.0: our PermissionRequest hook's `timeout` in the settings file, or null (`permissionHookTimeoutS`). */
   permissionHookTimeoutS: number | null
+  /**
+   * X1: the same, per kind (`permissionHookTimeoutForToolS` for AskUserQuestion and for any other
+   * tool). Equal to `permissionHookTimeoutS` while the block is not split.
+   */
+  permissionHookTimeouts?: { question: number | null; approval: number | null }
   tokenPresent: boolean
 }
 
@@ -343,7 +435,7 @@ function hooksDisabled(settings: unknown): boolean {
   return !!settings && typeof settings === 'object' && (settings as { disableAllHooks?: unknown }).disableAllHooks === true
 }
 
-export function hookStatus(paths: { settingsPath?: string; scriptPath?: string; packageScriptPath?: string; hookPaths?: HookPaths } = {}): HookStatus {
+export function hookStatus(paths: { settingsPath?: string; scriptPath?: string; packageScriptPath?: string; hookPaths?: HookPaths; plan?: PermissionHookPlan } = {}): HookStatus {
   const settingsPath = paths.settingsPath ?? claudeSettingsPath()
   const scriptPath = paths.scriptPath ?? stableHookScriptPath()
   const packageScriptPath = paths.packageScriptPath ?? packagedHookScriptPath()
@@ -355,8 +447,12 @@ export function hookStatus(paths: { settingsPath?: string; scriptPath?: string;
   if (!read.ok) {
     return { state: read.reason, installed: false, settingsPath, scriptPath, scriptSha, packageScriptSha, subscribed: [], missing: HOOK_SUBSCRIPTIONS.map(s => s.event), drifted: [], priorWait: [], priorWaitOnly: false, permissionHookTimeoutS: null, tokenPresent }
   }
-  const events = subscribedEvents(read.settings, scriptPath, hookPaths)
+  const events = subscribedEvents(read.settings, scriptPath, hookPaths, paths.plan ?? permissionHookPlan())
   const permissionWaitS = permissionHookTimeoutS(read.settings)
+  const permissionHookTimeouts = {
+    question: permissionHookTimeoutForToolS(read.settings, 'AskUserQuestion'),
+    approval: permissionHookTimeoutForToolS(read.settings, 'Bash'),
+  }
   let state: HookInstallState
   if (hooksDisabled(read.settings)) state = 'disabled_by_settings'
   else if (events.subscribed.length === 0 && events.drifted.length === 0) state = 'missing'
@@ -366,7 +462,7 @@ export function hookStatus(paths: { settingsPath?: string; scriptPath?: string;
   const priorWaitOnly = state === 'drift' && events.missing.length === 0 && events.drifted.length > 0
     && events.drifted.every(event => events.priorWait.includes(event))
   const observerOnlyDrift = state === 'drift' && events.missing.length > 0 && events.missing.every(event => event === 'PreCompact') && events.drifted.every(event => events.priorWait.includes(event))
-  return { observerOnlyDrift, state, installed: state === 'installed', settingsPath, scriptPath, scriptSha, packageScriptSha, ...events, priorWaitOnly, permissionHookTimeoutS: permissionWaitS, tokenPresent }
+  return { observerOnlyDrift, state, installed: state === 'installed', settingsPath, scriptPath, scriptSha, packageScriptSha, ...events, priorWaitOnly, permissionHookTimeoutS: permissionWaitS, ...(paths.plan?.split || permissionHookPlan().split || permissionHookTimeouts.question !== permissionHookTimeouts.approval ? { permissionHookTimeouts } : {}), tokenPresent }
 }
 
 /**
@@ -476,6 +572,8 @@ export interface InstallOptions {
   port?: number
   deskIdleSeconds?: number
   dryRun?: boolean
+  /** X1: how the PermissionRequest hook is written. Default: from the two full-hold switches (`permissionHookPlan`). */
+  plan?: PermissionHookPlan
 }
 
 export interface InstallResult {
@@ -548,10 +646,11 @@ export function installClaudeHooks(options: InstallOptions = {}): InstallResult
   const packageScriptPath = options.packageScriptPath ?? packagedHookScriptPath()
   const hookPaths = options.hookPaths ?? currentHookPaths()
   const read = readSettings(settingsPath)
-  const statusNow = () => hookStatus({ settingsPath, scriptPath, packageScriptPath, hookPaths })
+  const plan = options.plan ?? permissionHookPlan()
+  const statusNow = () => hookStatus({ settingsPath, scriptPath, packageScriptPath, hookPaths, plan })
   const refuse = (reason: string, scriptCopied = false): InstallResult => ({ ok: false, reason, changed: false, scriptCopied, backupPath: null, status: statusNow() })
   if (!read.ok) return refuse(read.reason)
-  const merged = mergeHookSettings(read.settings, scriptPath, hookPaths)
+  const merged = mergeHookSettings(read.settings, scriptPath, hookPaths, plan)
   if (!merged.ok) return refuse(merged.reason)
   if (options.dryRun) {
     return { ok: true, changed: merged.changed, scriptCopied: false, backupPath: null, status: statusNow(), merged: merged.settings }

package/server/lib/conversation.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { notifySessionStart, notifySessionEnd } from './telegram-notify.js'
 import { appendToArchive, type SessionToArchive } from './archive.js'
 import { updateGlassesSessionCache, scheduleCacheUpdate, setSessionProvider } from './session-cache-writer.js'
-import { logSessionEnd, buildSessionLogEntry, writeSessionLog } from './session-log.js'
+import { logSessionEnd, buildSessionLogEntry, writeSessionLogIfChanged, flushSessionLogState } from './session-log.js'
 import { atomicWriteFileSync, durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
 import { localDay } from './local-day.js'
 import { normalizeModelPreference, type ModelPreference } from '../../shared/model-preference.js'
@@ -966,11 +966,14 @@ export async function endSession(sessionId: string): Promise<{ logged: boolean;
   return { logged: exchangeCount > 0, exchangeCount, durationMin }
 }
 
-/** Log all active sessions on server shutdown — prevents data loss on restart */
-export function logActiveSessionsOnShutdown(): void {
+/** Log active sessions on server shutdown — prevents data loss on restart.
+ * S1 (2026-11-09): a session whose content was already written (by a snapshot or an
+ * earlier shutdown, in this boot or a previous one) is not appended again. */
+export function logActiveSessionsOnShutdown(): { written: number; unchanged: number; unconfigured: number; failed: number } {
+  const counts = { written: 0, unchanged: 0, unconfigured: 0, failed: 0 }
   for (const session of sessions.values()) {
     if (session.exchanges.length === 0) continue
-    logSessionEnd({
+    const entry = buildSessionLogEntry({
       id: session.id,
       exchanges: session.exchanges,
       createdAt: session.createdAt,
@@ -978,40 +981,65 @@ export function logActiveSessionsOnShutdown(): void {
       modelPreference: session.modelPreference,
       endReason: 'server_shutdown',
     })
+    counts[writeSessionLogIfChanged(entry, 'shutdown')]++
+  }
+  flushSessionLogState()
+  // No ledger configured (the new-install default): nothing to report.
+  if (counts.written || counts.unchanged || counts.failed) {
+    console.log(`[session-log] shutdown: ${counts.written} written, ${counts.unchanged} unchanged, ${counts.failed} failed`)
   }
+  return counts
 }
 
-// ── Auto-snapshot: periodically write active sessions to .glasses_sessions.jsonl ──
-// Runs every 5 minutes. No LLM calls, no network — just JSON serialize + file append.
-// Cost: ~0 CPU, ~0 RAM, ~50KB disk per snapshot.
+// ── Auto-snapshot: periodically write changed active sessions to .glasses_sessions.jsonl ──
+// Runs every 5 minutes. No LLM calls, no network. A session is appended only when its
+// content changed since the last write for it, and that memory survives restarts
+// (session-log.ts). Before 2026-11-09 the memory was this module's own map, empty after
+// every boot, so the first tick after a restart re-appended every session (about 300 entries,
+// roughly 5 MB, per boot on Miles's Mac; not the "~50KB per snapshot" once written here).
 let snapshotTimer: ReturnType<typeof setInterval> | null = null
-let lastSnapshotCounts: Record<string, number> = {} // track exchange counts to skip unchanged sessions
+let lastSnapshotCounts: Record<string, number> = {} // cheap in-process pre-check before hashing
+
+/** One auto-snapshot pass. Exported for tests. */
+export function runAutoSnapshotOnce(): { written: number; unchanged: number; unconfigured: number; failed: number } {
+  const counts = { written: 0, unchanged: 0, unconfigured: 0, failed: 0 }
+  for (const session of sessions.values()) {
+    if (session.exchanges.length === 0) continue
+    // Skip if exchange count hasn't changed since this process last looked
+    const prevCount = lastSnapshotCounts[session.id]
+    if (prevCount !== undefined && session.exchanges.length === prevCount) continue
+
+    const entry = buildSessionLogEntry({
+      id: session.id,
+      exchanges: session.exchanges,
+      createdAt: session.createdAt,
+      lastActivity: Date.now(), // Use NOW, not lastActivity — ensures lookup covers up to this moment
+      modelPreference: session.modelPreference,
+      endReason: 'explicit_end',
+      slug: `[LIVE] ${(session.exchanges.find(e => e.role === 'user')?.content ?? '').slice(0, 50)}`,
+    })
+    counts[writeSessionLogIfChanged(entry, 'snapshot')]++
+    // Recorded whatever the result, as before S1: a failed or unconfigured write is not retried
+    // every 5 minutes (Q1 review M2), only after the session changes again.
+    lastSnapshotCounts[session.id] = session.exchanges.length
+  }
+  if (counts.written) flushSessionLogState()
+  return counts
+}
 
 export function startAutoSnapshot(intervalMs = 5 * 60_000): void {
   if (snapshotTimer) return
-  snapshotTimer = setInterval(() => {
-    for (const session of sessions.values()) {
-      if (session.exchanges.length === 0) continue
-      // Skip if exchange count hasn't changed since last snapshot
-      const prevCount = lastSnapshotCounts[session.id] ?? 0
-      if (session.exchanges.length === prevCount) continue
-
-      const entry = buildSessionLogEntry({
-        id: session.id,
-        exchanges: session.exchanges,
-        createdAt: session.createdAt,
-        lastActivity: Date.now(), // Use NOW, not lastActivity — ensures lookup covers up to this moment
-        modelPreference: session.modelPreference,
-        endReason: 'explicit_end',
-        slug: `[LIVE] ${(session.exchanges.find(e => e.role === 'user')?.content ?? '').slice(0, 50)}`,
-      })
-      writeSessionLog(entry)
-      lastSnapshotCounts[session.id] = session.exchanges.length
-    }
-  }, intervalMs)
+  snapshotTimer = setInterval(() => { runAutoSnapshotOnce() }, intervalMs)
   console.log(`[conversation] Auto-snapshot started (every ${intervalMs / 1000}s)`)
 }
 
+/** Tests only. */
+export function __resetAutoSnapshotForTests(): void {
+  if (snapshotTimer) clearInterval(snapshotTimer)
+  snapshotTimer = null
+  lastSnapshotCounts = {}
+}
+
 /** Return all active sessions with exchanges, shaped for archiving */
 export function getActiveSessions(): SessionToArchive[] {
   const result: SessionToArchive[] = []

package/server/lib/cors-reject-log.ts

@@ -0,0 +1,51 @@
+/**
+ * Log a rejected CORS origin (S1, 2026-11-09).
+ *
+ * The scan of 10/26 to 11/09 found 22 "Error: CORS blocked" lines with nothing else, so no one
+ * could tell a COS client bug from a probe. This logs the ORIGIN only (an Origin header is a
+ * scheme, host and port; never a header dump, cookie or token), once per origin per hour, with a
+ * running count, and caps how many distinct origins it remembers so a scanner cannot grow it.
+ */
+const ONE_HOUR_MS = 60 * 60_000
+export const CORS_REJECT_ORIGIN_CAP = 200
+const seen = new Map<string, { count: number; lastLoggedAt: number }>()
+let overflow = 0
+
+/** An origin made safe for one log line: printable ASCII, no spaces, at most 200 characters. */
+export function sanitizeOrigin(origin: string): string {
+  const clean = origin.replace(/[^\x21-\x7e]/g, '?')
+  return clean.length > 200 ? `${clean.slice(0, 200)}…(${clean.length} chars)` : clean
+}
+
+export type CorsRejectReason = 'not_allowed' | 'check_failed'
+
+export function noteCorsRejection(
+  origin: string,
+  reason: CorsRejectReason,
+  now = Date.now(),
+  log: (line: string) => void = line => console.warn(line),
+): boolean {
+  const key = sanitizeOrigin(origin)
+  let entry = seen.get(key)
+  if (!entry) {
+    if (seen.size >= CORS_REJECT_ORIGIN_CAP) {
+      overflow++
+      if (overflow === 1 || overflow % 100 === 0) {
+        log(`[cors] blocked ${overflow} request(s) from origins beyond the first ${CORS_REJECT_ORIGIN_CAP} distinct ones (not listed)`)
+      }
+      return false
+    }
+    entry = { count: 0, lastLoggedAt: 0 }
+    seen.set(key, entry)
+  }
+  entry.count++
+  if (entry.lastLoggedAt && now - entry.lastLoggedAt < ONE_HOUR_MS) return false
+  entry.lastLoggedAt = now
+  log(`[cors] blocked origin=${key} reason=${reason} (${entry.count} from this origin since boot)`)
+  return true
+}
+
+export function __resetCorsRejectLogForTests(): void {
+  seen.clear()
+  overflow = 0
+}

package/server/lib/disk-io-meter.ts

@@ -0,0 +1,202 @@
+/**
+ * Opt-in per-path disk I/O meter (S1, 2026-11-09). COS_DISK_IO_METER=1 turns it on; default off.
+ *
+ * Why: macOS filed 12 "disk writes" resource reports against the server's node process
+ * (2.1 to 8.6 GB over 0.5 to 6 h) with JavaScript frames unsymbolicated, so no report could
+ * name a file. Measured from outside on 11/09 (proc_pid_rusage, idle, no meeting): 111.7 KB/s
+ * written and about 1.8 to 5 MB/s read. The largest writer (work-reviews/reviews.json) is fixed;
+ * the rest could not be attributed without root. With the meter on, the server logs once an
+ * hour which paths took the bytes:
+ *
+ *   [disk-io] 60 min: wrote 152.3 MB in 1,204 writes, read 3.1 GB in 9,880 reads; top writes: ...
+ *
+ * How: wraps the synchronous and promise write/read entry points of node:fs and
+ * node:fs/promises, then calls syncBuiltinESMExports() so modules that already imported
+ * named bindings see the wrappers. Each wrapper calls the original and only counts bytes;
+ * errors and return values pass through unchanged. Streams (createWriteStream) are not
+ * counted. Paths are folded so ids and temp suffixes group: "~/.cos-glasses/data/active-sessions/*.json".
+ */
+import fs from 'node:fs'
+import fsPromises from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { syncBuiltinESMExports } from 'node:module'
+
+interface Tally { bytes: number; ops: number }
+interface Window { startedAt: number; writes: Map<string, Tally>; reads: Map<string, Tally> }
+
+let windowState: Window | null = null
+let restore: (() => void) | null = null
+let reportTimer: ReturnType<typeof setInterval> | null = null
+const fdPaths = new Map<number, string>()
+/** Node's own fs functions call each other (appendFileSync calls writeFileSync, which calls
+ * openSync and writeSync). Only the outermost wrapped call counts. */
+let depth = 0
+function nested<T>(run: () => T): T {
+  depth++
+  try { return run() } finally { depth-- }
+}
+
+const HOME = homedir()
+
+/** Group a path: home as ~, temp suffixes dropped, id-like segments as *. */
+export function foldPath(path: string): string {
+  let p = path.startsWith(HOME) ? `~${path.slice(HOME.length)}` : path
+  p = p.replace(/(\.\d+\.[0-9a-f]+)?\.tmp$/i, '')           // atomic-write temp names
+  p = p.replace(/\.corrupt-\d+$/, '.corrupt-*')
+  p = p.replace(/(^|[/._-])[0-9a-f]{8,}(?=$|[/._-])/gi, '$1*') // hashes, uuids, hex ids
+  p = p.replace(/(^|[/._-])\d{6,}(?=$|[/._-])/g, '$1*')      // epoch ms, pids in names
+  p = p.replace(/meeting_\*_[a-z0-9]+/gi, 'meeting_*')
+  return p
+}
+
+function byteLength(data: unknown, encoding?: unknown): number {
+  if (typeof data === 'string') return Buffer.byteLength(data, typeof encoding === 'string' ? encoding as BufferEncoding : 'utf8')
+  if (data && typeof (data as ArrayBufferView).byteLength === 'number') return (data as ArrayBufferView).byteLength
+  return 0
+}
+
+function keyFor(target: unknown): string {
+  if (typeof target === 'number') return fdPaths.get(target) ?? `fd:${target}`
+  if (typeof target === 'string') return foldPath(target)
+  if (target instanceof URL) return foldPath(target.pathname)
+  if (Buffer.isBuffer(target)) return foldPath(target.toString())
+  if (target && typeof (target as { fd?: unknown }).fd === 'number') return fdPaths.get((target as { fd: number }).fd) ?? 'filehandle'
+  return 'unknown'
+}
+
+function count(kind: 'writes' | 'reads', target: unknown, bytes: number, outer: boolean): void {
+  if (!windowState || bytes <= 0 || !outer) return
+  const map = windowState[kind]
+  const key = keyFor(target)
+  const tally = map.get(key)
+  if (tally) { tally.bytes += bytes; tally.ops++ } else map.set(key, { bytes, ops: 1 })
+}
+
+export interface DiskIoReport {
+  windowMs: number
+  wroteBytes: number; writeOps: number
+  readBytes: number; readOps: number
+  topWrites: Array<{ path: string; bytes: number; ops: number }>
+  topReads: Array<{ path: string; bytes: number; ops: number }>
+}
+
+/** The current window's totals (diagnostics, tests). Null when the meter is off. */
+export function diskIoSnapshot(top = 10): DiskIoReport | null {
+  if (!windowState) return null
+  const sum = (m: Map<string, Tally>) => [...m.values()].reduce((a, t) => ({ bytes: a.bytes + t.bytes, ops: a.ops + t.ops }), { bytes: 0, ops: 0 })
+  const rank = (m: Map<string, Tally>) => [...m.entries()].sort((a, b) => b[1].bytes - a[1].bytes).slice(0, top)
+    .map(([path, t]) => ({ path, bytes: t.bytes, ops: t.ops }))
+  const w = sum(windowState.writes), r = sum(windowState.reads)
+  return {
+    windowMs: Date.now() - windowState.startedAt,
+    wroteBytes: w.bytes, writeOps: w.ops, readBytes: r.bytes, readOps: r.ops,
+    topWrites: rank(windowState.writes), topReads: rank(windowState.reads),
+  }
+}
+
+function mb(bytes: number): string {
+  return bytes >= 1e9 ? `${(bytes / 1e9).toFixed(2)} GB` : `${(bytes / 1e6).toFixed(1)} MB`
+}
+
+/** One log line for the window, then start a new window. */
+export function reportDiskIo(log: (line: string) => void = line => console.log(line)): DiskIoReport | null {
+  const report = diskIoSnapshot(8)
+  if (!report || !windowState) return null
+  const fmt = (rows: DiskIoReport['topWrites']) => rows.map(r => `${r.path} ${mb(r.bytes)} (${r.ops})`).join('; ') || 'none'
+  log(`[disk-io] ${Math.round(report.windowMs / 60_000)} min: wrote ${mb(report.wroteBytes)} in ${report.writeOps} writes, `
+    + `read ${mb(report.readBytes)} in ${report.readOps} reads; top writes: ${fmt(report.topWrites)}; top reads: ${fmt(report.topReads)}`)
+  windowState = { startedAt: Date.now(), writes: new Map(), reads: new Map() }
+  return report
+}
+
+export function diskIoMeterRequested(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_DISK_IO_METER === '1'
+}
+
+/** Install the wrappers. Idempotent. Returns false when already installed. */
+export function installDiskIoMeter(options: { reportEveryMs?: number } = {}): boolean {
+  if (restore) return false
+  windowState = { startedAt: Date.now(), writes: new Map(), reads: new Map() }
+  const f = fs as unknown as Record<string, any>
+  const p = fsPromises as unknown as Record<string, any>
+  const saved: Array<[Record<string, any>, string, unknown]> = []
+  const wrap = (obj: Record<string, any>, name: string, make: (orig: any) => any) => {
+    const orig = obj[name]
+    if (typeof orig !== 'function') return
+    saved.push([obj, name, orig])
+    obj[name] = make(orig)
+  }
+  wrap(f, 'openSync', orig => function (this: unknown, path: unknown, ...rest: unknown[]) {
+    const fd = nested(() => orig.call(this, path, ...rest))
+    if (typeof fd === 'number' && (typeof path === 'string' || path instanceof URL)) fdPaths.set(fd, keyFor(path))
+    return fd
+  })
+  wrap(f, 'closeSync', orig => function (this: unknown, fd: number, ...rest: unknown[]) {
+    fdPaths.delete(fd)
+    return orig.call(this, fd, ...rest)
+  })
+  wrap(f, 'writeFileSync', orig => function (this: unknown, target: unknown, data: unknown, options?: unknown) {
+    const outer = depth === 0
+    const result = nested(() => orig.call(this, target, data, options))
+    count('writes', target, byteLength(data, typeof options === 'string' ? options : (options as { encoding?: unknown } | undefined)?.encoding), outer)
+    return result
+  })
+  wrap(f, 'appendFileSync', orig => function (this: unknown, target: unknown, data: unknown, options?: unknown) {
+    const outer = depth === 0
+    const result = nested(() => orig.call(this, target, data, options))
+    count('writes', target, byteLength(data, typeof options === 'string' ? options : (options as { encoding?: unknown } | undefined)?.encoding), outer)
+    return result
+  })
+  wrap(f, 'writeSync', orig => function (this: unknown, fd: number, ...rest: unknown[]) {
+    const outer = depth === 0
+    const written = nested(() => orig.call(this, fd, ...rest))
+    count('writes', fd, typeof written === 'number' ? written : 0, outer)
+    return written
+  })
+  wrap(f, 'readFileSync', orig => function (this: unknown, target: unknown, ...rest: unknown[]) {
+    const outer = depth === 0
+    const result = nested(() => orig.call(this, target, ...rest))
+    count('reads', target, byteLength(result), outer)
+    return result
+  })
+  wrap(f, 'readSync', orig => function (this: unknown, fd: number, ...rest: unknown[]) {
+    const outer = depth === 0
+    const read = nested(() => orig.call(this, fd, ...rest))
+    count('reads', fd, typeof read === 'number' ? read : 0, outer)
+    return read
+  })
+  for (const name of ['writeFile', 'appendFile'] as const) {
+    wrap(p, name, orig => async function (this: unknown, target: unknown, data: unknown, options?: unknown) {
+      const result = await orig.call(this, target, data, options)
+      count('writes', target, byteLength(data, typeof options === 'string' ? options : (options as { encoding?: unknown } | undefined)?.encoding), true)
+      return result
+    })
+  }
+  wrap(p, 'readFile', orig => async function (this: unknown, target: unknown, ...rest: unknown[]) {
+    const result = await orig.call(this, target, ...rest)
+    count('reads', target, byteLength(result), true)
+    return result
+  })
+  syncBuiltinESMExports()
+  restore = () => {
+    for (const [obj, name, orig] of saved) obj[name] = orig
+    syncBuiltinESMExports()
+  }
+  const every = options.reportEveryMs ?? 60 * 60_000
+  if (every > 0) {
+    reportTimer = setInterval(() => { reportDiskIo() }, every)
+    reportTimer.unref?.()
+  }
+  console.log(`[disk-io] meter on (COS_DISK_IO_METER=1): ${every > 0 ? `one line every ${Math.round(every / 60_000)} min` : 'reports on request only'}`)
+  return true
+}
+
+/** Remove the wrappers (tests, and a clean shutdown). */
+export function uninstallDiskIoMeter(): void {
+  if (reportTimer) clearInterval(reportTimer)
+  reportTimer = null
+  restore?.()
+  restore = null
+  windowState = null
+  fdPaths.clear()
+}