@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/meeting-autonomous-finalize.ts

@@ -0,0 +1,267 @@
+// The server finishes a stopped G2 meeting on its own (6.81.0).
+//
+// Miles, 2026-10-20: "if the application isn't in the foreground, it can fail to save the
+// meetings". Once the phone has told the server its meeting stopped (lib/meeting-stop-
+// intents.ts) and the server holds every chunk it captured, nothing is left that needs the
+// phone, so the server runs the same save the phone would have run. The phone, when it
+// comes back on screen, finds a saved meeting and adopts the receipt.
+//
+// THE ONE RULE: NEVER SAVE A CAPTURE THAT IS NOT COMPLETE. The server saves on its own only
+// when its ledger holds every index 0..N (N = the phone's last captured index) and every one
+// of them has finished ASR. A gap means audio exists only on the phone, so the server waits
+// and the session stays live: the phone's late upload lands in the SAME session (the merge)
+// and the next check saves. There is no shorter timeout that saves with the gap, because a
+// save closes the session, and a chunk that arrives after the close is refused (410) and the
+// phone reads "server closed, local audio pending" as a collision it cannot resolve: the
+// meeting splits or the tail is lost. A gap that never fills is handed to the existing
+// stranded sweeper at its existing 4 h horizon, exactly as before this release. Waiting
+// costs only time; saving early costs audio.
+//
+// Why a settle delay as well: a phone that is on screen saves within a few seconds of Stop.
+// The server stands back for AUTONOMOUS_FINALIZE_SETTLE_MS after the Stop and after the last
+// chunk arrived, so a healthy phone's own save is the normal path and the server's is the
+// fallback. Both racing is safe anyway (one save lock, an idempotent save route), but not
+// racing is quieter.
+
+import type { StopIntent } from './meeting-stop-intents.js'
+
+/** Quiet time after the Stop and after the last chunk before the server saves on its own. */
+export const AUTONOMOUS_FINALIZE_SETTLE_MS = 45_000
+/** How often a waiting Stop is checked again. Cheap: an in-memory ledger read. */
+export const AUTONOMOUS_FINALIZE_POLL_MS = 15_000
+/** Missing indices kept in a log line. */
+const MISSING_SAMPLE = 8
+
+export interface SessionLedger {
+  state: 'active' | 'closed' | 'missing'
+  received: readonly number[]
+  asrCompleted: readonly number[]
+  maxChunkIndex: number
+  /** ms since epoch of the last chunk arrival, or null. */
+  lastActivityAt: number | null
+}
+
+export type AutonomousWaitReason = 'settling' | 'missing_chunks' | 'asr_pending' | 'session_unknown' | 'saving' | 'not_ready'
+export type AutonomousStandDownReason = 'already_saved' | 'closed_unsaved' | 'nothing_captured' | 'server_instance_mismatch'
+
+export type AutonomousDecision =
+  | { action: 'finalize'; chunks: number }
+  | { action: 'wait'; reason: AutonomousWaitReason; missing: number[]; missingCount: number; retryInMs: number }
+  | { action: 'revoke'; reason: 'chunk_beyond_final'; maxChunkIndex: number }
+  | { action: 'stand_down'; reason: AutonomousStandDownReason }
+
+function missingFrom(finalIndex: number, have: readonly number[]): { sample: number[]; count: number } {
+  const present = new Set(have)
+  const sample: number[] = []
+  let count = 0
+  for (let index = 0; index <= finalIndex; index++) {
+    if (present.has(index)) continue
+    count++
+    if (sample.length < MISSING_SAMPLE) sample.push(index)
+  }
+  return { sample, count }
+}
+
+/**
+ * What to do with a waiting Stop right now. Pure: every input is passed in.
+ *
+ * Order matters and each step is pinned by a test: a saved meeting is never saved again, a
+ * chunk past the Stop means the meeting is still recording (revoke, never save), and only a
+ * complete, fully transcribed, quiet capture is saved.
+ */
+export function decideAutonomousFinalize(input: {
+  intent: Pick<StopIntent, 'finalChunkIndex' | 'receivedAt'>
+  ledger: SessionLedger
+  now: number
+  alreadySaved: boolean
+  saving: boolean
+}): AutonomousDecision {
+  const { intent, ledger, now } = input
+  if (input.alreadySaved) return { action: 'stand_down', reason: 'already_saved' }
+  if (input.saving) return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  // A session closed WITHOUT a save receipt (expired, quarantined) is the stranded and
+  // quarantine paths' to finish. Saving here would race them.
+  if (ledger.state === 'closed') return { action: 'stand_down', reason: 'closed_unsaved' }
+  if (intent.finalChunkIndex < 0) return { action: 'stand_down', reason: 'nothing_captured' }
+  // The server holds audio the phone says it never captured: the phone resumed after this
+  // Stop, or the Stop is stale. Either way the meeting may still be recording.
+  if (ledger.maxChunkIndex > intent.finalChunkIndex) {
+    return { action: 'revoke', reason: 'chunk_beyond_final', maxChunkIndex: ledger.maxChunkIndex }
+  }
+  // An offline capture: the Stop arrived before any chunk did. Wait for the upload.
+  if (ledger.state === 'missing') {
+    return { action: 'wait', reason: 'session_unknown', missing: [], missingCount: intent.finalChunkIndex + 1, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const absent = missingFrom(intent.finalChunkIndex, ledger.received)
+  if (absent.count > 0) {
+    return { action: 'wait', reason: 'missing_chunks', missing: absent.sample, missingCount: absent.count, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const pending = missingFrom(intent.finalChunkIndex, ledger.asrCompleted)
+  if (pending.count > 0) {
+    return { action: 'wait', reason: 'asr_pending', missing: pending.sample, missingCount: pending.count, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const quietSince = Math.max(intent.receivedAt, ledger.lastActivityAt ?? 0)
+  const settleLeft = quietSince + AUTONOMOUS_FINALIZE_SETTLE_MS - now
+  if (settleLeft > 0) {
+    return { action: 'wait', reason: 'settling', missing: [], missingCount: 0, retryInMs: Math.min(settleLeft, AUTONOMOUS_FINALIZE_POLL_MS) }
+  }
+  return { action: 'finalize', chunks: intent.finalChunkIndex + 1 }
+}
+
+/** Expand `[start, end]` ranges (the status route's shape) into indices. */
+export function indicesFromRanges(ranges: ReadonlyArray<readonly [number, number]>): number[] {
+  const out: number[] = []
+  for (const [start, end] of ranges) for (let index = start; index <= end; index++) out.push(index)
+  return out
+}
+
+export type AutonomousSaveOutcome =
+  | { ok: true; filename: string; sidecarPath: string; chunkCount: number; canonicalCount: number; missingIndices: number[] }
+  | { ok: false; status: number; reason: string }
+
+export interface AutonomousFinalizerDeps {
+  waiting(): StopIntent[]
+  get(sessionId: string): StopIntent | null
+  update(sessionId: string, patch: Partial<StopIntent>): void
+  ledger(sessionId: string): SessionLedger
+  alreadySaved(sessionId: string): boolean
+  saving(sessionId: string): boolean
+  save(intent: StopIntent): Promise<AutonomousSaveOutcome>
+  /** Maintenance admissions open AND durable session recovery has run. */
+  ready(): boolean
+  now(): number
+  /** Returns a cancel function. Production timers are unref'd so they never hold the process. */
+  schedule(fn: () => void, ms: number): () => void
+  log(event: string, fields: Record<string, unknown>): void
+}
+
+export interface AutonomousFinalizer {
+  /** Check one session now (a Stop arrived, a boot). Never throws. */
+  check(sessionId: string, trigger: string): Promise<AutonomousDecision | null>
+  /** Check every waiting Stop, then re-arm while any remain. */
+  tick(trigger?: string): Promise<void>
+  /** Make sure a tick is scheduled. */
+  arm(ms?: number): void
+}
+
+export function createAutonomousFinalizer(deps: AutonomousFinalizerDeps): AutonomousFinalizer {
+  const inFlight = new Set<string>()
+  let cancel: (() => void) | null = null
+  let armedFor = Infinity
+
+  const arm = (ms = AUTONOMOUS_FINALIZE_POLL_MS) => {
+    const due = deps.now() + Math.max(0, ms)
+    if (cancel && armedFor <= due) return
+    cancel?.()
+    armedFor = due
+    cancel = deps.schedule(() => {
+      cancel = null
+      armedFor = Infinity
+      void finalizer.tick('poll')
+    }, Math.max(0, ms))
+  }
+
+  const check = async (sessionId: string, trigger: string): Promise<AutonomousDecision | null> => {
+    if (inFlight.has(sessionId)) return null
+    const intent = deps.get(sessionId)
+    if (!intent || intent.state !== 'waiting') return null
+    // A boot behind a closed maintenance gate has not adopted the persisted sessions yet,
+    // so "the server holds no chunks" is not evidence of anything. Wait, never decide.
+    if (!deps.ready()) {
+      return { action: 'wait', reason: 'not_ready', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+    }
+    inFlight.add(sessionId)
+    try {
+      const now = deps.now()
+      const decision = decideAutonomousFinalize({
+        intent,
+        ledger: deps.ledger(sessionId),
+        now,
+        alreadySaved: deps.alreadySaved(sessionId),
+        saving: deps.saving(sessionId),
+      })
+      if (decision.action === 'stand_down') {
+        // A save the phone (or anyone) already made is the phone's save, not ours.
+        deps.update(sessionId, decision.reason === 'already_saved'
+          ? { state: 'saved', savedBy: intent.savedBy ?? 'phone', savedAt: intent.savedAt ?? now }
+          : { state: 'stood_down', reason: decision.reason })
+        deps.log('stood_down', { sessionId, reason: decision.reason, trigger, waitedMs: now - intent.receivedAt })
+        return decision
+      }
+      if (decision.action === 'revoke') {
+        deps.update(sessionId, { state: 'revoked', reason: decision.reason })
+        deps.log('revoked', { sessionId, reason: decision.reason, finalChunkIndex: intent.finalChunkIndex, maxChunkIndex: decision.maxChunkIndex, trigger })
+        return decision
+      }
+      if (decision.action === 'wait') {
+        const last = intent.lastWait
+        // One line per change of state, not one per poll.
+        if (!last || last.reason !== decision.reason || last.missingCount !== decision.missingCount) {
+          deps.update(sessionId, { lastWait: { reason: decision.reason, missingCount: decision.missingCount, missingSample: decision.missing, at: now } })
+          deps.log('waiting', { sessionId, reason: decision.reason, missingCount: decision.missingCount, missingSample: decision.missing, finalChunkIndex: intent.finalChunkIndex, trigger })
+        }
+        return decision
+      }
+      const outcome = await deps.save(intent)
+      const at = deps.now()
+      if (outcome.ok) {
+        deps.update(sessionId, {
+          state: 'saved', savedBy: 'server', savedAt: at,
+          filename: outcome.filename, sidecarPath: outcome.sidecarPath,
+          chunkCount: outcome.chunkCount, canonicalCount: outcome.canonicalCount, lastWait: null,
+        })
+        deps.log('finalized', {
+          sessionId, reason: 'stop_received_complete', trigger,
+          finalChunkIndex: intent.finalChunkIndex, chunks: outcome.chunkCount, canonical: outcome.canonicalCount,
+          gaps: outcome.missingIndices.length, filename: outcome.filename,
+          waitedMs: at - intent.receivedAt, phoneConfirmed: false,
+        })
+        return decision
+      }
+      // The phone saved between the decision and the lock: its save, not ours.
+      if (outcome.reason === 'already_saved') {
+        deps.update(sessionId, { state: 'saved', savedBy: 'phone', savedAt: at, lastWait: null })
+        deps.log('stood_down', { sessionId, reason: 'already_saved', trigger, waitedMs: at - intent.receivedAt })
+        return { action: 'stand_down', reason: 'already_saved' }
+      }
+      // The phone pinned another server instance: this Mac is not where it meant to save.
+      if (outcome.reason === 'server_instance_mismatch') {
+        deps.update(sessionId, { state: 'stood_down', reason: outcome.reason })
+        deps.log('stood_down', { sessionId, reason: outcome.reason, trigger })
+        return { action: 'stand_down', reason: 'server_instance_mismatch' }
+      }
+      // The phone's own save holds the lock: it wins, and the next check reads its receipt.
+      if (outcome.status === 409 && outcome.reason === 'save_in_progress') {
+        return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+      }
+      // Nothing to save (every chunk was silence): the phone's own Stop says so on the lens.
+      if (outcome.status === 404) {
+        deps.update(sessionId, { state: 'stood_down', reason: outcome.reason })
+        deps.log('stood_down', { sessionId, reason: outcome.reason, trigger })
+        return { action: 'stand_down', reason: 'nothing_captured' }
+      }
+      deps.log('finalize_failed', { sessionId, status: outcome.status, reason: outcome.reason, trigger })
+      return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+    } catch (error) {
+      deps.log('finalize_failed', { sessionId, status: 500, reason: error instanceof Error ? error.message.slice(0, 200) : 'error', trigger })
+      return null
+    } finally {
+      inFlight.delete(sessionId)
+    }
+  }
+
+  const finalizer: AutonomousFinalizer = {
+    check,
+    async tick(trigger = 'poll') {
+      let soonest = Infinity
+      for (const intent of deps.waiting()) {
+        const decision = await check(intent.sessionId, trigger)
+        if (decision?.action === 'wait') soonest = Math.min(soonest, decision.retryInMs)
+        else if (decision === null && deps.get(intent.sessionId)?.state === 'waiting') soonest = Math.min(soonest, AUTONOMOUS_FINALIZE_POLL_MS)
+      }
+      if (Number.isFinite(soonest)) arm(soonest)
+    },
+    arm,
+  }
+  return finalizer
+}

package/server/lib/meeting-stop-intents.ts

@@ -0,0 +1,277 @@
+// The phone's Stop, as the server hears it (6.81.0).
+//
+// WHY THIS EXISTS. Until 6.81.0 the server learned that a G2 meeting had ended only from
+// POST /api/meeting/save, and the phone sends that save only after its own finalize has
+// read IndexedDB, reconciled the server's ledger and drained every chunk. iOS suspends
+// IndexedDB while the companion is off screen, so a Stop pressed with the phone in a pocket
+// sat unsaved until the app came back on screen (2026-10-20: 11:19 meeting qbbgyq, Stop at
+// 12:43, `stop_blocked` and `foreground_reconcile_failed` "Load failed", saved only by a new
+// WebView at 12:47; 14:07 meeting mip9qb, Stop at 15:13:50, saved at 15:14:37 only once
+// the phone was visible). A fetch works while hidden; IndexedDB does not.
+//
+// WHAT A STOP INTENT IS. One small POST the phone can send the moment Stop is pressed,
+// before any IndexedDB work: "this meeting has ended, and the last chunk I captured is
+// index N". The server records it durably and from then on can finish the save itself
+// once it holds every chunk 0..N (lib/meeting-autonomous-finalize.ts decides when).
+//
+// WHAT IT IS NOT. It never closes the session, never refuses a chunk, and never saves by
+// itself. Chunks keep arriving into the same live session after it (that is the merge),
+// and a chunk past N cancels it, because a meeting that is still recording must never be
+// finalized.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { LOCAL_FIRST_MEETING_IDLE_RETENTION_MS } from './local-first-meetings-contract.js'
+
+export const STOP_INTENTS_FILE_NAME = 'meeting-stop-intents.json'
+export const AUTONOMOUS_SAVE_LOG_NAME = 'meeting-autonomous-save.jsonl'
+
+/** A finished intent stays readable this long, so a late phone can still be answered and logged. */
+export const STOP_INTENT_TERMINAL_RETAIN_MS = 24 * 60 * 60_000
+/**
+ * A waiting intent outlives the session it describes by one retention horizon. By then the
+ * stranded sweeper (4 h idle) has promoted or quarantined the session and owns it.
+ */
+export const STOP_INTENT_WAITING_RETAIN_MS = 2 * LOCAL_FIRST_MEETING_IDLE_RETENTION_MS
+
+export type StopIntentState = 'waiting' | 'saved' | 'revoked' | 'stood_down'
+/** `other`: an unpinned save (the stranded sweep's own POST, a manual curl). */
+export type StopIntentSavedBy = 'server' | 'phone' | 'other'
+
+export interface StopIntentWait {
+  reason: string
+  missingCount: number
+  /** The first few missing indices, for the log. Never the whole list. */
+  missingSample: number[]
+  at: number
+}
+
+export interface StopIntent {
+  sessionId: string
+  /** The highest chunk index the phone captured. -1 = it captured nothing. */
+  finalChunkIndex: number
+  source: string
+  title?: string
+  domain?: string
+  serverInstanceId: string
+  /** Server clock, first receipt. The phone's clock is never read. */
+  receivedAt: number
+  updatedAt: number
+  /** How many times the phone sent it (a hidden phone retries). */
+  posts: number
+  state: StopIntentState
+  /** Why it is revoked or stood down. */
+  reason?: string
+  savedBy?: StopIntentSavedBy
+  savedAt?: number
+  filename?: string
+  sidecarPath?: string
+  chunkCount?: number
+  canonicalCount?: number
+  lastWait?: StopIntentWait | null
+  /** Set when the phone first reports back after the server saved on its own. */
+  phoneConfirmedAt?: number
+  phoneConfirmedBy?: string
+  /** Chunks the phone re-sent after the save that the saved meeting already held. */
+  lateReplays?: number
+  /** Chunks the phone sent after the save that the saved meeting did NOT hold. Should stay 0. */
+  lateRefused?: number
+  /** The state of an earlier Stop for this session that this one replaced. */
+  replaced?: StopIntentState
+}
+
+export type RecordStopIntentResult =
+  | { ok: true; intent: StopIntent; created: boolean; raised: boolean }
+  | { ok: false; reason: 'terminal'; intent: StopIntent }
+
+export interface StopIntentStore {
+  readonly path: string
+  get(sessionId: string): StopIntent | null
+  /** Waiting intents, oldest first. */
+  waiting(): StopIntent[]
+  /**
+   * Record or refresh the phone's Stop. Re-posting is idempotent; a higher final index
+   * raises it (never lowers it: the server must never finalize before the highest index the
+   * phone ever claimed has arrived).
+   */
+  record(input: { sessionId: string; finalChunkIndex: number; source: string; title?: string; domain?: string; serverInstanceId: string }): RecordStopIntentResult
+  update(sessionId: string, patch: Partial<StopIntent>): StopIntent | null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function readIntents(path: string): Record<string, StopIntent> {
+  if (!existsSync(path)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown
+    if (!isRecord(parsed) || !isRecord(parsed.intents)) return {}
+    const out: Record<string, StopIntent> = {}
+    for (const [id, raw] of Object.entries(parsed.intents)) {
+      if (!/^[A-Za-z0-9:_-]{3,96}$/.test(id) || !isRecord(raw)) continue
+      const intent = raw as unknown as StopIntent
+      if (intent.sessionId !== id) continue
+      if (!Number.isInteger(intent.finalChunkIndex) || intent.finalChunkIndex < -1) continue
+      if (!Number.isFinite(intent.receivedAt) || !Number.isFinite(intent.updatedAt)) continue
+      if (!['waiting', 'saved', 'revoked', 'stood_down'].includes(intent.state)) continue
+      out[id] = intent
+    }
+    return out
+  } catch {
+    // A corrupt ledger is set aside, never silently trusted or deleted.
+    try { renameSync(path, `${path}.corrupt.${Date.now()}`) } catch {}
+    return {}
+  }
+}
+
+export function createStopIntentStore(options: { path?: string; now?: () => number } = {}): StopIntentStore {
+  const path = options.path ?? dataPath(STOP_INTENTS_FILE_NAME)
+  const now = options.now ?? Date.now
+  let cache: Record<string, StopIntent> | null = null
+
+  const load = (): Record<string, StopIntent> => {
+    if (!cache) cache = readIntents(path)
+    return cache
+  }
+  const prune = (intents: Record<string, StopIntent>, at: number) => {
+    for (const [id, intent] of Object.entries(intents)) {
+      const retain = intent.state === 'waiting' ? STOP_INTENT_WAITING_RETAIN_MS : STOP_INTENT_TERMINAL_RETAIN_MS
+      if (at - intent.updatedAt > retain) delete intents[id]
+    }
+  }
+  // Persisted before the caller answers, so a 2xx means a restart still knows the Stop.
+  const persist = (intents: Record<string, StopIntent>) => {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    durableAtomicWriteFileSync(path, JSON.stringify({ schemaVersion: 1, intents }, null, 2), { mode: 0o600 })
+  }
+
+  return {
+    path,
+    get(sessionId) {
+      const intent = load()[sessionId]
+      return intent ? { ...intent } : null
+    },
+    waiting() {
+      return Object.values(load())
+        .filter(intent => intent.state === 'waiting')
+        .sort((a, b) => a.receivedAt - b.receivedAt)
+        .map(intent => ({ ...intent }))
+    },
+    record(input) {
+      const at = now()
+      const intents = load()
+      prune(intents, at)
+      const prior = intents[input.sessionId]
+      // A saved Stop is final. A revoked or stood-down one is history: the phone resumed and
+      // stopped again, so this is a new Stop and replaces it.
+      if (prior && prior.state === 'saved') return { ok: false, reason: 'terminal', intent: { ...prior } }
+      const existing = prior?.state === 'waiting' ? prior : undefined
+      if (existing) {
+        const raised = input.finalChunkIndex > existing.finalChunkIndex
+        const next: StopIntent = {
+          ...existing,
+          finalChunkIndex: Math.max(existing.finalChunkIndex, input.finalChunkIndex),
+          title: input.title ?? existing.title,
+          domain: input.domain ?? existing.domain,
+          updatedAt: at,
+          posts: existing.posts + 1,
+        }
+        intents[input.sessionId] = next
+        persist(intents)
+        return { ok: true, intent: { ...next }, created: false, raised }
+      }
+      const intent: StopIntent = {
+        sessionId: input.sessionId,
+        finalChunkIndex: input.finalChunkIndex,
+        source: input.source,
+        ...(input.title ? { title: input.title } : {}),
+        ...(input.domain ? { domain: input.domain } : {}),
+        serverInstanceId: input.serverInstanceId,
+        receivedAt: at,
+        updatedAt: at,
+        posts: 1,
+        state: 'waiting',
+        lastWait: null,
+        ...(prior ? { replaced: prior.state } : {}),
+      }
+      intents[input.sessionId] = intent
+      persist(intents)
+      return { ok: true, intent: { ...intent }, created: true, raised: false }
+    },
+    update(sessionId, patch) {
+      const intents = load()
+      const existing = intents[sessionId]
+      if (!existing) return null
+      const next: StopIntent = { ...existing, ...patch, sessionId, updatedAt: now() }
+      intents[sessionId] = next
+      try { persist(intents) } catch (error) {
+        console.error(`[meeting/auto-save] Could not persist the stop intent for ${sessionId}: ${error instanceof Error ? error.message : error}`)
+      }
+      return { ...next }
+    },
+  }
+}
+
+let defaultStore: StopIntentStore | null = null
+/** The process-wide store, created on first use (never at import: tests import this module). */
+export function getStopIntentStore(): StopIntentStore {
+  if (!defaultStore) defaultStore = createStopIntentStore()
+  return defaultStore
+}
+
+/** One JSON line per autonomous-save event, beside the server log line that says the same. */
+export function appendAutonomousSaveLog(event: string, fields: Record<string, unknown>, path = dataPath(AUTONOMOUS_SAVE_LOG_NAME)): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    appendFileSync(path, `${JSON.stringify({ at: new Date().toISOString(), event, ...fields })}\n`, { mode: 0o600 })
+  } catch { /* the console line is the fallback record */ }
+}
+
+export interface SavedChunkText {
+  text: string
+  speaker: string
+  elapsed: number
+  [key: string]: unknown
+}
+export type SavedChunkReplay = { kind: 'canonical'; chunk: SavedChunkText } | { kind: 'empty' } | null
+
+let sidecarCache: { path: string; mtimeMs: number; entries: Map<number, SavedChunkText> } | null = null
+
+/**
+ * What a meeting the server saved on its own holds at one chunk index, for answering a
+ * phone that re-sends that chunk after the save (its upload response was lost while it was
+ * hidden). `canonical`: the saved text. `empty`: the chunk arrived and was silence. `null`:
+ * the saved meeting never held this index, so the replay is refused as before (410).
+ *
+ * Read from the saved sidecar, not from memory, so it survives a restart. One sidecar is
+ * cached at a time: replays arrive in a burst for one meeting.
+ */
+export function savedChunkReplay(sidecarPath: string, chunkIndex: number, asrCompleted: readonly number[]): SavedChunkReplay {
+  let entries: Map<number, SavedChunkText>
+  try {
+    const mtimeMs = statSync(sidecarPath).mtimeMs
+    if (sidecarCache && sidecarCache.path === sidecarPath && sidecarCache.mtimeMs === mtimeMs) {
+      entries = sidecarCache.entries
+    } else {
+      const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf-8')) as { chunkEntries?: unknown }
+      entries = new Map()
+      for (const entry of Array.isArray(sidecar.chunkEntries) ? sidecar.chunkEntries : []) {
+        const candidate = entry as { chunkIndex?: unknown; chunk?: unknown }
+        const chunk = candidate?.chunk as Partial<SavedChunkText> | undefined
+        if (!Number.isInteger(candidate?.chunkIndex) || !chunk) continue
+        if (typeof chunk.text !== 'string' || !chunk.text || typeof chunk.speaker !== 'string') continue
+        if (typeof chunk.elapsed !== 'number' || !Number.isFinite(chunk.elapsed)) continue
+        entries.set(candidate.chunkIndex as number, chunk as SavedChunkText)
+      }
+      sidecarCache = { path: sidecarPath, mtimeMs, entries }
+    }
+  } catch {
+    return null
+  }
+  const chunk = entries.get(chunkIndex)
+  if (chunk) return { kind: 'canonical', chunk }
+  return asrCompleted.includes(chunkIndex) ? { kind: 'empty' } : null
+}