@gotcos/glasses-server 6.94.4 → 6.98.0

package/server/lib/token-audit.ts

@@ -8,12 +8,17 @@ import { homedir } from 'node:os'
 
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
 import type { TokenAuditKeyFields } from './key-relay-contract.js'
+import { cleanProviderId, normalizeRealUsage, type RealUsage } from './provider-usage.js'
 
 // Shared JSONL file — same path as Python's llm_client.py uses
 // Uses COS_SCRIPTS_DIR when available (server mode), falls back to user home
-const AUDIT_FILE = COS_SCRIPTS_DIR
-  ? resolve(COS_SCRIPTS_DIR, '.cos_token_audit.jsonl')
-  : resolve(homedir(), '.cos-glasses', 'token-audit.jsonl')
+// 6.97.0: COS_TOKEN_AUDIT_FILE is set only by the test config, so no test writes a made-up row to a
+// real ledger now that a row can claim to be measured.
+const AUDIT_FILE = process.env.COS_TOKEN_AUDIT_FILE
+  ? resolve(process.env.COS_TOKEN_AUDIT_FILE)
+  : COS_SCRIPTS_DIR
+    ? resolve(COS_SCRIPTS_DIR, '.cos_token_audit.jsonl')
+    : resolve(homedir(), '.cos-glasses', 'token-audit.jsonl')
 
 // Rough char-to-token ratio (1 token ~ 4 chars for English)
 const CHARS_PER_TOKEN = 4
@@ -33,7 +38,12 @@ export interface TokenAuditEntry extends TokenAuditKeyFields {
   runId?: string
   sessionId?: string
   clientJobId?: string
-  usageKind?: 'provider_final' | 'estimated'
+  /** The provider's own session id: Claude's session, Codex's thread, Cursor's chat. `sessionId` is COS's. */
+  cliSessionId?: string
+  /** 6.97.0: what the provider reported. The row says `provider_final` only when these are real numbers. */
+  realUsage?: RealUsage
+  /** 6.97.0, dictation polish only: what the model is sent, system prompt included. `inputChars` stays the words dictated. */
+  promptChars?: number
   /** 6.85.0, dictation polish only: whether the user's polish instructions were in the prompt, and their hash. */
   polishInstructions?: { on: boolean; hash: string }
   /** 6.91.0, dictation polish only: whether the learned style was in the prompt, and its hash. */
@@ -56,6 +66,8 @@ export interface TokenAuditEntry extends TokenAuditKeyFields {
  * (subscription) row is byte-identical to 6.79.0. Callers set them only on keyed turns.
  */
 export function buildTokenAuditRecord(entry: TokenAuditEntry, now: Date = new Date()): Record<string, unknown> {
+  const real = normalizeRealUsage(entry.realUsage)
+  const cliSessionId = cleanProviderId(entry.cliSessionId)
   return {
     ts: now.toISOString(),
     source: entry.source,
@@ -66,7 +78,7 @@ export function buildTokenAuditRecord(entry: TokenAuditEntry, now: Date = new Da
     est_output_tokens: estimateTokens(entry.outputChars),
     duration_ms: entry.durationMs,
     caller: entry.caller,
-    usage_kind: entry.usageKind ?? 'estimated',
+    usage_kind: real ? 'provider_final' : 'estimated',
     ...(entry.turnId ? { turn_id: entry.turnId } : {}),
     ...(entry.runId ? { run_id: entry.runId } : {}),
     ...(entry.sessionId ? { session_id: entry.sessionId } : {}),
@@ -91,12 +103,30 @@ export function buildTokenAuditRecord(entry: TokenAuditEntry, now: Date = new Da
     ...(entry.polishGuard ? { polish_guard: entry.polishGuard } : {}),
     // 6.92.0: set only by the prompt-edit caller.
     ...(entry.promptEditOutcome ? { prompt_edit_outcome: entry.promptEditOutcome } : {}),
+    // 6.97.0: last, and only when set, so a row without them is byte-identical to 6.96.4. Numbers and
+    // ids only. COS Control reads these names. All four counts are always written. input_tokens never
+    // includes cache reads; it excludes cache writes only on Claude, the one provider that reports
+    // them, so on Codex and direct cache_write_tokens is 0 and any write stays in input_tokens.
+    // resolved_model is the CLI's word on Claude, and what COS asked for elsewhere. provider-usage.ts
+    // says exactly what each means. cache_write_1h_tokens is part of cache_write_tokens; it and cost_usd
+    // appear only when stated.
+    ...(typeof entry.promptChars === 'number' ? { prompt_chars: entry.promptChars } : {}),
+    ...(cliSessionId ? { cli_session_id: cliSessionId } : {}),
+    ...(real ? {
+      input_tokens: real.inputTokens,
+      output_tokens: real.outputTokens,
+      cache_read_tokens: real.cacheReadTokens ?? 0,
+      cache_write_tokens: real.cacheWriteTokens ?? 0,
+      ...(real.cacheWrite1hTokens !== undefined ? { cache_write_1h_tokens: real.cacheWrite1hTokens } : {}),
+      ...(real.costUsd !== undefined ? { cost_usd: real.costUsd } : {}),
+      ...(real.resolvedModel ? { resolved_model: real.resolvedModel } : {}),
+    } : {}),
   }
 }
 
 export function logTokenAudit(entry: TokenAuditEntry): void {
-  const record = buildTokenAuditRecord(entry)
   try {
+    const record = buildTokenAuditRecord(entry)
     appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', { encoding: 'utf8', mode: 0o600 })
     chmodSync(AUDIT_FILE, 0o600)
   } catch {

package/server/lib/transcript-cleanup.ts

@@ -169,8 +169,9 @@ const notesSearchDefault: CleanupDeps['searchNotes'] = async (queries, sessionId
 
 const filesDefault: CleanupDeps['files'] = async sessionId => {
   try {
-    const { MeetingAskStore } = await import('./meeting-ask-store.js')
-    return new MeetingAskStore().files(sessionId).filter(f => f.status === 'ready' && typeof f.text === 'string' && f.text.trim()).map(f => ({ name: f.name, text: f.text }))
+    const { MeetingAskStore, isPastedFileId } = await import('./meeting-ask-store.js')
+    // Pasted text and read pages (paste_, web_) are article words, not the room's vocabulary: they must not rewrite the saved transcript.
+    return new MeetingAskStore().files(sessionId).filter(f => !isPastedFileId(f.id) && f.status === 'ready' && typeof f.text === 'string' && f.text.trim()).map(f => ({ name: f.name, text: f.text }))
   } catch { return [] }
 }
 

package/server/lib/voice-directory.ts

@@ -14,6 +14,7 @@ import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
 import { readMacSpeakerMachineEvidence } from './mac-speaker-machine-evidence.js'
+import { readMacSpeakerCallView } from './mac-speaker-call-view.js'
 import { dataPath } from './data-dir.js'
 import { confirmedLabels, confirmedChunks } from './meeting-corrections.js'
 import { resolveCosOperationsDir, resolveMeetingLibrary } from './cos-operations-meetings.js'
@@ -278,7 +279,8 @@ export async function buildVoiceDirectorySnapshot(): Promise<VoiceDirectorySnaps
         continue
       }
       totalBytes += link.size
-      const raw = JSON.parse(await readFile(real, 'utf8')) as Record<string, unknown> | ReviewChunk[]
+      const baseJSON = await readFile(real, 'utf8')
+      const raw = JSON.parse(baseJSON) as Record<string, unknown> | ReviewChunk[]
       const chunks = Array.isArray(raw) ? raw : raw.chunks
       const sessionId = Array.isArray(raw) ? '' : String(raw.sessionId ?? '')
       if (!Array.isArray(chunks) || !SESSION.test(sessionId) || seenSessions.has(sessionId)) {
@@ -297,7 +299,9 @@ export async function buildVoiceDirectorySnapshot(): Promise<VoiceDirectorySnaps
       )
 
       const machineEvidence = readMacSpeakerMachineEvidence(record)
-      const review = reviewMeetingSpeakers(chunks as ReviewChunk[], {
+      const callView = readMacSpeakerCallView(real, baseJSON, candidate.markdownPath)
+      const review = reviewMeetingSpeakers((callView.doc.chunks ?? chunks) as ReviewChunk[], {
+        callViewAnonymousLabels: callView.metadata.groups.map(g => g.label),
         owner,
         phrasesPerVoice: 1,
         confirmed: confirmedLabels(sessionId),
@@ -305,8 +309,8 @@ export async function buildVoiceDirectorySnapshot(): Promise<VoiceDirectorySnaps
         machineQualifiedPositions: machineEvidence.positions,
         machineEvidenceStatus: machineEvidence.status,
         durationMs: typeof record.durationMs === 'number' ? record.durationMs : undefined,
-        batchSegments: Array.isArray(record.batchSegments)
-          ? record.batchSegments as SpeakerWordSegment[]
+        batchSegments: Array.isArray(callView.doc.batchSegments)
+          ? callView.doc.batchSegments as SpeakerWordSegment[]
           : undefined,
       })
       meetingsScanned++

package/server/lib/web-lookup-ledger.ts

@@ -0,0 +1,151 @@
+// An honest daily count of every public web lookup COS makes, by feature, and of every lookup it held back and why.
+//
+// WHY. The settings line "Today: N topic checks, N web searches" counts only the general cues. The meeting assistant and the
+// fact check also search and read pages, and nothing counted them, so the number read as the whole story when it was a part.
+// This ledger is written where each lookup actually happens (searchMeetingWeb for a search, the page reader for a page, the
+// gate that refuses for a withheld one), never inferred from a result or a log.
+//
+// It is a LEDGER, not a gate. No code path waits on it or is refused by it, and recording never throws: a lookup that cannot
+// be counted still runs. The file is local-day keyed like the general cue state (same zone and rollover rule): a new local day
+// starts from zero, a day in the future (a clock set back) is not trusted. A file that cannot be read says so in the view
+// (`readable: false`) instead of reading as zero, and a corrupt one is moved aside so counting resumes the next time.
+import { readFileSync, mkdirSync, renameSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+export type WebFeature = 'cues' | 'ask' | 'factCheck'
+export const WEB_FEATURES: readonly WebFeature[] = ['cues', 'ask', 'factCheck']
+/** Distinct withheld reasons kept per feature; the rest count under 'other' so a bad caller cannot grow the file. */
+export const WEB_LEDGER_MAX_REASONS = 40
+
+/** `pagesRead` is pages whose text was used; `pagesFailed` is page fetches that were attempted and returned nothing (blocked, too big, not an article, too slow). */
+export interface WebFeatureToday { searches: number; pagesRead: number; pagesFailed: number }
+export interface WebTodayView {
+  day: string
+  /** False when the file could not be read: the counts below are then zero and do not describe today. */
+  readable: boolean
+  cues: WebFeatureToday
+  ask: WebFeatureToday
+  factCheck: WebFeatureToday
+  withheld: { total: number; byReason: Record<string, number>; byFeature: Record<WebFeature, number> }
+}
+
+interface FeatureState { searches: number; pagesRead: number; pagesFailed: number; withheld: Record<string, number> }
+interface LedgerState { v: 1; zone: string; day: string; features: Record<WebFeature, FeatureState> }
+type LedgerRead = { ok: true; state: LedgerState } | { ok: false; future: boolean }
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+const whole = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0
+function validZone(zone: unknown): string | null {
+  if (typeof zone !== 'string' || !zone) return null
+  try { new Intl.DateTimeFormat('en-CA', { timeZone: zone }); return zone } catch { return null }
+}
+/** Local calendar day in `zone`. Intl, never toISOString: a UTC key flips the day at 19:00 Central (the rule live-cues-general.ts follows). */
+function localDay(ms: number, zone: string): string {
+  return new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date(ms))
+}
+const emptyFeature = (): FeatureState => ({ searches: 0, pagesRead: 0, pagesFailed: 0, withheld: {} })
+const REASON = /^[a-z0-9][a-z0-9_:.-]{0,47}$/
+
+export class WebLookupLedger {
+  constructor(private readonly file: string, private readonly now: () => number = Date.now) {}
+  private systemZone(): string { return validZone(Intl.DateTimeFormat().resolvedOptions().timeZone) ?? 'UTC' }
+  private fresh(nowMs: number): LedgerState {
+    const zone = this.systemZone()
+    return { v: 1, zone, day: localDay(nowMs, zone), features: { cues: emptyFeature(), ask: emptyFeature(), factCheck: emptyFeature() } }
+  }
+  private read(): LedgerRead {
+    const nowMs = this.now()
+    let raw: unknown
+    try { raw = JSON.parse(readFileSync(this.file, 'utf8')) } catch (e) {
+      if ((e as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: true, state: this.fresh(nowMs) }
+      return { ok: false, future: false }
+    }
+    if (!isRecord(raw) || raw.v !== 1 || !isRecord(raw.features)) return { ok: false, future: false }
+    const zone = validZone(raw.zone), today = zone ? localDay(nowMs, zone) : ''
+    if (!zone || typeof raw.day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw.day)) return { ok: false, future: false }
+    if (raw.day > today) return { ok: false, future: true }
+    const rolled = raw.day < today
+    const features = {} as Record<WebFeature, FeatureState>
+    for (const f of WEB_FEATURES) {
+      const s = raw.features[f]
+      // pagesFailed arrived after the first files were written: a file without it reads as zero.
+      if (!isRecord(s) || !whole(s.searches) || !whole(s.pagesRead) || !(s.pagesFailed === undefined || whole(s.pagesFailed)) || !isRecord(s.withheld)) return { ok: false, future: false }
+      const withheld: Record<string, number> = {}
+      for (const [reason, n] of Object.entries(s.withheld)) {
+        if (!whole(n) || !REASON.test(reason)) return { ok: false, future: false }
+        withheld[reason] = n
+      }
+      features[f] = rolled ? emptyFeature() : { searches: s.searches, pagesRead: s.pagesRead, pagesFailed: (s.pagesFailed as number | undefined) ?? 0, withheld }
+    }
+    return { ok: true, state: { v: 1, zone, day: today, features } }
+  }
+  private write(s: LedgerState): boolean {
+    try {
+      mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
+      durableAtomicWriteFileSync(this.file, JSON.stringify(s) + '\n', { mode: 0o600 })
+      return true
+    } catch { return false }
+  }
+  /** One read-modify-write. A file that cannot be parsed is moved aside once so counting resumes; a future day is left alone
+   *  (the day catches up) and nothing is counted until then. Never throws. */
+  private update(change: (s: LedgerState) => void): boolean {
+    try {
+      let r = this.read()
+      if (!r.ok && !r.future) {
+        try { renameSync(this.file, `${this.file}.unreadable`) } catch { return false }
+        r = this.read()
+      }
+      if (!r.ok) return false
+      change(r.state)
+      return this.write(r.state)
+    } catch { return false }
+  }
+  /** One web search is starting now. */
+  search(feature: WebFeature): boolean { return this.update(s => { s.features[feature].searches += 1 }) }
+  /** `count` result or pasted pages were read. */
+  pagesRead(feature: WebFeature, count = 1): boolean {
+    if (!whole(count) || count === 0) return false
+    return this.update(s => { s.features[feature].pagesRead += count })
+  }
+  /** `count` page fetches were attempted and returned nothing. */
+  pagesFailed(feature: WebFeature, count = 1): boolean {
+    if (!whole(count) || count === 0) return false
+    return this.update(s => { s.features[feature].pagesFailed += count })
+  }
+  /** One lookup was proposed and refused, for `reason` (a gate reason code such as no_public_intent). */
+  withheld(feature: WebFeature, reason: string): boolean {
+    const key = REASON.test(reason) ? reason : 'other'
+    return this.update(s => {
+      const w = s.features[feature].withheld
+      const name = key in w || Object.keys(w).length < WEB_LEDGER_MAX_REASONS ? key : 'other'
+      w[name] = (w[name] ?? 0) + 1
+    })
+  }
+  today(): WebTodayView {
+    const r = this.read()
+    const zeros = (): WebTodayView => ({ day: localDay(this.now(), this.systemZone()), readable: false, cues: { searches: 0, pagesRead: 0, pagesFailed: 0 }, ask: { searches: 0, pagesRead: 0, pagesFailed: 0 }, factCheck: { searches: 0, pagesRead: 0, pagesFailed: 0 },
+      withheld: { total: 0, byReason: {}, byFeature: { cues: 0, ask: 0, factCheck: 0 } } })
+    if (!r.ok) return zeros()
+    const f = r.state.features
+    const byReason: Record<string, number> = {}
+    const byFeature = {} as Record<WebFeature, number>
+    for (const name of WEB_FEATURES) {
+      byFeature[name] = Object.values(f[name].withheld).reduce((a, b) => a + b, 0)
+      for (const [reason, n] of Object.entries(f[name].withheld)) byReason[reason] = (byReason[reason] ?? 0) + n
+    }
+    const view = (s: FeatureState): WebFeatureToday => ({ searches: s.searches, pagesRead: s.pagesRead, pagesFailed: s.pagesFailed })
+    return { day: r.state.day, readable: true, cues: view(f.cues), ask: view(f.ask), factCheck: view(f.factCheck),
+      withheld: { total: WEB_FEATURES.reduce((n, name) => n + byFeature[name], 0), byReason, byFeature } }
+  }
+}
+
+let shared: WebLookupLedger | null = null
+/** The server's one ledger, in the data dir. Created on first use so importing this file touches nothing. */
+export function webLedger(): WebLookupLedger {
+  if (!shared) shared = new WebLookupLedger(dataPath('web-lookup-ledger.json'))
+  return shared
+}
+/** Tests only: replace (or clear, with null) the shared ledger. */
+export function setWebLedgerForTests(ledger: WebLookupLedger | null): void { shared = ledger }

package/server/lib/work-review-runtime.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto'
+import { noteWorkReviewJob } from './job-audit-caller.js'
 import type { MeetingDetail } from './meeting-store.js'
 import type { QueryJobSnapshot } from './query-job-types.js'
 import { WorkReviewError, WorkReviewStore, parseMeetingDescriptor, publicReview, reviewHash,
@@ -143,6 +144,7 @@ export class WorkReviewRuntime {
         const request = { clientJobId: row.clientJobId, generation: 1, query: row.prompt, model: row.model,
           messageEra: row.messageEra, activityToolMode: 'status', cursorExecutionMode: 'ask',
           ...(row.provider === 'claude' ? { dispatch: { restricted: true, tools: ['Read','Grep','Glob'] } } : {}) }
+        noteWorkReviewJob(row.clientJobId)
         job = (await this.deps.jobs.submit(request)).job
       }
       if (!job) {

package/server/lib/work-search.ts

@@ -131,9 +131,11 @@ export function searchOptionText(text: string): string {
  * drain for an update or restart would wait up to 20 s (the Jev timeout) for a search, and a drain would answer every
  * search 503. Outside it, a restart mid-search loses at most that search's token count.
  * Live COS Ask is also read-only and cancellable, with no durable tasks or conversation writes.
+ * Voice suggestions (6.96.3) write nothing, answer at once and run detached. The route checks admissions itself so a
+ * drain answers its own `refused` state rather than a 503, and a running job stops at its next unit when a drain starts.
  */
 export function isReadOnlyApiPost(method: string, path: string): boolean {
-  return method === 'POST' && (path === '/work/search' || path === '/meetings/live-ask')
+  return method === 'POST' && (path === '/work/search' || path === '/meetings/live-ask' || /^\/meeting\/[A-Za-z0-9:_-]{3,96}\/voice-suggestions$/.test(path))
 }
 
 /** A query's length as people count it: code points, not UTF-16 units, so 150 emoji are 150 (Control counts characters). */

package/server/lib/xlsx-text.ts

@@ -0,0 +1,277 @@
+// Plain text from an .xlsx workbook, for meeting context. No dependency: an .xlsx is a zip of XML parts, read here with
+// node:zlib and a small bounded zip reader.
+//
+// What comes out. For each sheet, in workbook order: a "Sheet: <name>" line, then each non-empty row as tab-separated cell
+// values. Shared strings are resolved. NO FORMULA IS EVALUATED: a formula cell shows the value Excel last saved with it, and
+// numbers and dates are shown exactly as stored (a date is its serial number). Charts, images, comments and macros are not read.
+//
+// Limits, all enforced while reading, never after:
+//   XLSX_LIMITS.maxBytes         10 MB workbook
+//   XLSX_LIMITS.maxSheets        12 sheets (later sheets are named in a notice, not read)
+//   XLSX_LIMITS.maxRowsPerSheet  200 non-empty rows per sheet
+//   XLSX_LIMITS.maxColumns       50 columns per row
+//   XLSX_LIMITS.maxCellChars     200 characters per cell
+//   XLSX_LIMITS.maxChars         100,000 characters of text in all (the same cap as the other document types)
+//   inflate caps                 8 MB for shared strings, 16 MB per sheet, 4 MB for the other parts: a zip bomb stops at the cap
+//   total inflated               48 MB across all parts of one workbook
+//   work bound                   2 s of scanning in all (checked as the scanners advance); then XlsxError 'too_complex'
+// Every scanner below is a linear indexOf pass that stops at a missing close tag. Nothing here uses a lazy [\s\S]*? regex over
+// untrusted XML: with unclosed tags those go quadratic and an 8 to 16 MB part would hold the server for hours.
+// Anything past a cap is cut and said so in a bracketed line in the text.
+import { inflateRawSync } from 'node:zlib';
+
+export const XLSX_LIMITS = {
+  maxBytes: 10_000_000,
+  maxSheets: 12,
+  maxRowsPerSheet: 200,
+  maxColumns: 50,
+  maxCellChars: 200,
+  maxChars: 100_000,
+  maxSharedStringsBytes: 8_000_000,
+  maxSheetBytes: 16_000_000,
+  maxPartBytes: 4_000_000,
+  maxTotalInflatedBytes: 48_000_000,
+  maxWorkMs: 2_000,
+} as const
+
+export type XlsxErrorCode = 'too_large' | 'not_a_workbook' | 'encrypted' | 'unsupported_zip' | 'corrupt' | 'too_complex'
+export class XlsxError extends Error {
+  constructor(readonly code: XlsxErrorCode, message: string) {
+    super(message)
+    this.name = 'XlsxError'
+  }
+}
+
+interface ZipEntry { name: string; method: number; compressedSize: number; size: number; offset: number }
+
+function readEntries(zip: Buffer): Map<string, ZipEntry> {
+  if (zip.length < 22 || zip.readUInt32LE(0) !== 0x04034b50) throw new XlsxError('not_a_workbook', 'not a zip file')
+  let eocd = -1
+  for (let i = zip.length - 22; i >= Math.max(0, zip.length - 22 - 65_535); i--) {
+    if (zip.readUInt32LE(i) === 0x06054b50) { eocd = i; break }
+  }
+  if (eocd < 0) throw new XlsxError('corrupt', 'no end of central directory')
+  const count = zip.readUInt16LE(eocd + 10)
+  const cdSize = zip.readUInt32LE(eocd + 12)
+  const cdOffset = zip.readUInt32LE(eocd + 16)
+  if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) throw new XlsxError('unsupported_zip', 'zip64 is not supported')
+  if (cdOffset + cdSize > zip.length || count > 5_000) throw new XlsxError('corrupt', 'central directory out of range')
+  const entries = new Map<string, ZipEntry>()
+  let p = cdOffset
+  for (let n = 0; n < count; n++) {
+    if (p + 46 > zip.length || zip.readUInt32LE(p) !== 0x02014b50) throw new XlsxError('corrupt', 'bad central directory entry')
+    const flags = zip.readUInt16LE(p + 8)
+    if (flags & 1) throw new XlsxError('encrypted', 'the workbook is encrypted')
+    const nameLength = zip.readUInt16LE(p + 28), extraLength = zip.readUInt16LE(p + 30), commentLength = zip.readUInt16LE(p + 32)
+    if (p + 46 + nameLength > zip.length) throw new XlsxError('corrupt', 'entry name out of range')
+    const name = zip.toString('utf8', p + 46, p + 46 + nameLength)
+    entries.set(name, { name, method: zip.readUInt16LE(p + 10), compressedSize: zip.readUInt32LE(p + 20), size: zip.readUInt32LE(p + 24), offset: zip.readUInt32LE(p + 42) })
+    p += 46 + nameLength + extraLength + commentLength
+  }
+  return entries
+}
+
+/** One part, inflated with a hard output cap. Returns null past the cap or when the part is damaged. */
+function readPart(zip: Buffer, entry: ZipEntry, cap: number): string | null {
+  const at = entry.offset
+  if (at + 30 > zip.length || zip.readUInt32LE(at) !== 0x04034b50) return null
+  const start = at + 30 + zip.readUInt16LE(at + 26) + zip.readUInt16LE(at + 28)
+  if (start + entry.compressedSize > zip.length || entry.size > cap) return null
+  const raw = zip.subarray(start, start + entry.compressedSize)
+  try {
+    const bytes = entry.method === 0 ? raw : entry.method === 8 ? inflateRawSync(raw, { maxOutputLength: cap }) : null
+    return bytes ? bytes.toString('utf8') : null
+  } catch { return null }
+}
+
+/** The work bound: scanners call it as they advance; it reads the clock every 4,096 calls and throws once the deadline has passed. */
+class Work {
+  private n = 0
+  private readonly deadline: number
+  constructor(private readonly now: () => number) { this.deadline = now() + XLSX_LIMITS.maxWorkMs }
+  tick(): void {
+    if ((++this.n & 4095) === 0 && this.now() > this.deadline) throw new XlsxError('too_complex', `workbook took longer than ${XLSX_LIMITS.maxWorkMs} ms to scan`)
+  }
+}
+interface Block { attrs: string; body: string | null }
+/**
+ * The <tag ...>body</tag> and <tag .../> elements of `xml`, in order, found with indexOf only. A tag without its closing tag ends the
+ * scan (nothing after it is trusted), so every position is passed over at most a constant number of times. Nested elements of the same
+ * name are not supported (none of the parts read here nest them).
+ */
+function* blocks(xml: string, tag: string, work: Work): Generator<Block> {
+  const open = `<${tag}`, close = `</${tag}>`
+  let at = 0
+  for (;;) {
+    const start = xml.indexOf(open, at)
+    if (start < 0) return
+    const after = start + open.length
+    const c = xml.charCodeAt(after)
+    // <row but not <rowBreaks: the name must end here.
+    if (!(c === 62 || c === 47 || c === 32 || c === 9 || c === 10 || c === 13)) { at = after; continue }
+    const gt = xml.indexOf('>', after)
+    if (gt < 0) return
+    work.tick()
+    if (xml.charCodeAt(gt - 1) === 47) {
+      yield { attrs: xml.slice(after, gt - 1), body: null }
+      at = gt + 1
+      continue
+    }
+    const end = xml.indexOf(close, gt + 1)
+    if (end < 0) return
+    yield { attrs: xml.slice(after, gt), body: xml.slice(gt + 1, end) }
+    at = end + close.length
+  }
+}
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }
+function unescapeXml(s: string): string {
+  return s.replace(/&(?:#x([0-9a-f]+)|#(\d+)|(amp|lt|gt|quot|apos));/gi, (_, hex: string | undefined, dec: string | undefined, name: string | undefined) => {
+    if (name) return ENTITIES[name.toLowerCase()]
+    const code = hex ? parseInt(hex, 16) : Number(dec)
+    return code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : ''
+  })
+}
+/** `fragment` without its <rPh>...</rPh> phonetic guides; an unclosed <rPh> drops the rest. */
+function withoutGuides(fragment: string): string {
+  let out = '', at = 0
+  for (;;) {
+    const start = fragment.indexOf('<rPh', at)
+    if (start < 0) return out + fragment.slice(at)
+    out += fragment.slice(at, start)
+    const end = fragment.indexOf('</rPh>', start)
+    if (end < 0) return out
+    at = end + 6
+  }
+}
+/** The text of every <t> in a fragment, phonetic guides left out. */
+function textOf(fragment: string, work: Work): string {
+  let out = ''
+  for (const t of blocks(withoutGuides(fragment), 't', work)) if (t.body) out += unescapeXml(t.body)
+  return out
+}
+const ATTR_PATTERNS = new Map<string, RegExp>()
+function attr(tag: string, name: string): string | undefined {
+  let pattern = ATTR_PATTERNS.get(name)
+  if (!pattern) ATTR_PATTERNS.set(name, pattern = new RegExp(`\\b${name}="([^"]*)"`))
+  const m = pattern.exec(tag)
+  return m ? unescapeXml(m[1]) : undefined
+}
+/** Column letters to a zero-based index: A is 0, AA is 26. */
+function columnIndex(ref: string): number {
+  const letters = /^[A-Z]+/i.exec(ref)?.[0].toUpperCase() ?? ''
+  let n = 0
+  for (const ch of letters.slice(0, 4)) n = n * 26 + (ch.charCodeAt(0) - 64)
+  return n - 1
+}
+const clean = (value: string): string => value.replace(/[\t\r\n]+/g, ' ').trim().slice(0, XLSX_LIMITS.maxCellChars)
+
+function sharedStrings(xml: string | null, work: Work): string[] {
+  if (!xml) return []
+  const out: string[] = []
+  for (const si of blocks(xml, 'si', work)) out.push(si.body ? textOf(si.body, work) : '')
+  return out
+}
+
+function firstBody(xml: string, tag: string, work: Work): string | undefined {
+  for (const b of blocks(xml, tag, work)) return b.body ?? undefined
+  return undefined
+}
+function cellValue(attrs: string, body: string, strings: readonly string[], work: Work): string {
+  const type = attr(attrs, 't')
+  if (type === 'inlineStr') return textOf(firstBody(body, 'is', work) ?? '', work)
+  const v = firstBody(body, 'v', work)
+  if (v === undefined) return ''
+  const value = unescapeXml(v)
+  if (type === 's') return strings[Number(value)] ?? ''
+  if (type === 'b') return value === '1' ? 'TRUE' : 'FALSE'
+  return value
+}
+
+/** Rows of one sheet as tab-separated text, at most maxRowsPerSheet non-empty rows. */
+function sheetRows(xml: string, strings: readonly string[], work: Work): { lines: string[]; cut: boolean } {
+  const lines: string[] = []
+  for (const row of blocks(xml, 'row', work)) {
+    if (!row.body) continue
+    const cells: string[] = []
+    let next = 0
+    for (const c of blocks(row.body, 'c', work)) {
+      const ref = attr(c.attrs, 'r')
+      const at = ref ? columnIndex(ref) : next
+      if (at >= XLSX_LIMITS.maxColumns) break
+      const value = clean(cellValue(c.attrs, c.body ?? '', strings, work))
+      while (cells.length < at) cells.push('')
+      cells[at] = value
+      next = at + 1
+    }
+    while (cells.length && !cells[cells.length - 1]) cells.pop()
+    if (!cells.length) continue
+    if (lines.length >= XLSX_LIMITS.maxRowsPerSheet) return { lines, cut: true }
+    lines.push(cells.join('\t'))
+  }
+  return { lines, cut: false }
+}
+
+const CUT_NOTE = `[Text cut at ${XLSX_LIMITS.maxChars} characters.]`
+export interface XlsxText { text: string; truncated: boolean; sheets: number }
+
+/** The text of an .xlsx workbook. Throws XlsxError for anything that is not a readable, unencrypted workbook within the limits. */
+export function extractXlsxText(bytes: Buffer, options: { now?: () => number } = {}): XlsxText {
+  if (bytes.length > XLSX_LIMITS.maxBytes) throw new XlsxError('too_large', `workbook exceeds ${XLSX_LIMITS.maxBytes} bytes`)
+  const work = new Work(options.now ?? Date.now)
+  const entries = readEntries(bytes)
+  let inflated = 0
+  const part = (name: string, cap: number): string | null => {
+    const entry = entries.get(name)
+    const text = entry ? readPart(bytes, entry, cap) : null
+    inflated += text?.length ?? 0
+    if (inflated > XLSX_LIMITS.maxTotalInflatedBytes) throw new XlsxError('too_complex', `workbook inflates past ${XLSX_LIMITS.maxTotalInflatedBytes} bytes`)
+    return text
+  }
+  const workbook = part('xl/workbook.xml', XLSX_LIMITS.maxPartBytes)
+  if (!workbook) throw new XlsxError('not_a_workbook', 'no workbook part')
+  const rels = new Map<string, string>()
+  for (const m of blocks(part('xl/_rels/workbook.xml.rels', XLSX_LIMITS.maxPartBytes) ?? '', 'Relationship', work)) {
+    const id = attr(m.attrs, 'Id'), target = attr(m.attrs, 'Target')
+    if (id && target) rels.set(id, target.startsWith('/') ? target.slice(1) : `xl/${target.replace(/^\.\//, '')}`)
+  }
+  const sheets: Array<{ name: string; path: string }> = []
+  let ordinal = 0
+  for (const m of blocks(workbook, 'sheet', work)) {
+    ordinal += 1
+    const rid = /\br:id="([^"]*)"/.exec(m.attrs)?.[1]
+    sheets.push({ name: clean(attr(m.attrs, 'name') ?? `Sheet${ordinal}`) || `Sheet${ordinal}`, path: (rid && rels.get(rid)) || `xl/worksheets/sheet${ordinal}.xml` })
+  }
+  if (!sheets.length) throw new XlsxError('not_a_workbook', 'no sheets')
+  const strings = sharedStrings(part('xl/sharedStrings.xml', XLSX_LIMITS.maxSharedStringsBytes), work)
+  const texts: string[] = []
+  let truncated = false, used = 0
+  // The cut marker is added after the cap is reached, so the budget leaves room for it and the whole text stays within maxChars.
+  const budget = XLSX_LIMITS.maxChars - CUT_NOTE.length - 2
+  let capped = false
+  const push = (block: string): boolean => {
+    if (used + block.length + 2 > budget) {
+      capped = true
+      const room = budget - used - 2
+      if (room > 0) texts.push(block.slice(0, room))
+      truncated = true
+      return false
+    }
+    texts.push(block)
+    used += block.length + 2
+    return true
+  }
+  for (const [i, sheet] of sheets.entries()) {
+    if (i >= XLSX_LIMITS.maxSheets) {
+      push(`[${sheets.length - XLSX_LIMITS.maxSheets} more sheet${sheets.length - XLSX_LIMITS.maxSheets === 1 ? '' : 's'} not read: ${sheets.slice(XLSX_LIMITS.maxSheets).map(s => s.name).join(', ')}.]`)
+      truncated = true
+      break
+    }
+    const xml = part(sheet.path, XLSX_LIMITS.maxSheetBytes)
+    if (xml === null) { if (!push(`Sheet: ${sheet.name}\n[This sheet could not be read.]`)) break; continue }
+    const { lines, cut } = sheetRows(xml, strings, work)
+    if (cut) truncated = true
+    if (!push([`Sheet: ${sheet.name}`, ...lines, ...(cut ? [`[Only the first ${XLSX_LIMITS.maxRowsPerSheet} rows of this sheet are read.]`] : [])].join('\n'))) break
+  }
+  const text = texts.join('\n\n').trim()
+  return { text: capped ? `${text}\n\n${CUT_NOTE}` : text, truncated, sheets: sheets.length }
+}

package/server/routes/health.ts

@@ -16,6 +16,7 @@ import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contra
 import { isSileroAvailable } from '../lib/vad-silero.js'
 import { profileProvenanceSummary, speakerModelState, speakerReadiness } from '../lib/speaker-embeddings.js'
 import { nemotronLive } from '../lib/nemotron-live.js'
+import { speakerShadowHealthFields } from '../lib/speaker-shadow.js'
 import { finalPassSnapshot } from '../lib/nemotron-final.js'
 import { chunkEmbeddingStoreStats } from '../lib/chunk-embedding-store.js'
 import { mintDisplayTicket, DISPLAY_TICKET_TTL_SECONDS } from '../lib/display-ticket.js'
@@ -579,6 +580,10 @@ healthRouter.get('/health', async (_req, res) => {
     // count only (health is public); the items and their Retry are behind the token at
     // GET /api/maintenance/status.
     crash_loop_parking: crashLoopParkingHealth(),
+    // 6.95.0: speaker merge shadow mode, only while it is on (absent when off). Codes and counts
+    // only (health is public): the proposals and the last error's text are behind the token at
+    // /api/speaker-shadow/*.
+    ...speakerShadowHealthFields(),
     // Key lanes (plan v4 3.1): `details.keyLanes` only while enabled. Absent, never null, when off.
     ...keyLanesHealthFields(),
   })