@gotcos/glasses-server 6.95.0 → 6.98.1

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/decision-provider.ts

@@ -3,6 +3,7 @@ import { Router } from 'express'
 import { JEV_MODEL, resolveJevKey } from '../lib/jev.js'
 import { resolveSubqKey, subqKeyStatus } from '../lib/subq-key.js'
 import { SUBQ_MODEL } from '../lib/decision-provider.js'
+import { sessionFindAvailable } from '../lib/session-find.js'
 import { decisionSettingsView, DecisionSettingsError, patchDecisionSettings, readDecisionSettings, writeDecisionSettings, type DecisionProvider, type DecisionSettings } from '../lib/decision-settings.js'
 export interface DecisionProviderRouteDeps {
   read: () => DecisionSettings
@@ -15,7 +16,9 @@ export function createDecisionProviderRouter(overrides: Partial<DecisionProvider
   const deps: DecisionProviderRouteDeps = { read: readDecisionSettings, write: writeDecisionSettings, configured: () => ({ jev: !!resolveJevKey(), subq: !!resolveSubqKey() }), env: process.env, keyStatus: () => { const jev = resolveJevKey(); return { jev: { configured:!!jev, source:jev?.source ?? 'none' }, subq:subqKeyStatus() } }, ...overrides }
   const router = Router()
   const view = (settings: DecisionSettings) => ({ ...decisionSettingsView(settings, deps.configured(), deps.env), models: { jev: JEV_MODEL, subq: SUBQ_MODEL }, keyStatus: deps.keyStatus(),
-    capabilities: { choices: ['jev','subq'], workflows: ['session','completion','search'], hotReload: true, fallback: false, subqImages: true, subqKeySource: 'config-or-env' } })
+    capabilities: { choices: ['jev','subq'], workflows: ['session','completion','search'], hotReload: true, fallback: false, subqImages: true, subqKeySource: 'config-or-env',
+    // Present only while POST /api/agent-sessions/find can answer. Absent means no meaning search here, and Control does not ask (never keyed on version).
+    ...(sessionFindAvailable(deps.env) ? { sessionFind: true } : {}) } })
   router.use('/decision-provider', (_req,res,next) => { res.set('Cache-Control','private, no-store'); next() })
   router.get('/decision-provider', (_req,res) => {
     try { res.json(view(deps.read())) } catch { res.status(503).json({ error: { code: 'decision_settings_unavailable', message: 'Decision provider settings could not be read.' } }) }

package/server/routes/jev.ts

@@ -14,6 +14,7 @@ import { CompletionChecker, readRepliesSince } from '../lib/work-completion.js'
 import { isSafeSessionId, type AgentProvider } from '../lib/agent-session-store.js'
 import { listBoard } from '../lib/task-store.js'
 import { sharedWorkSearchJevClient } from '../lib/work-search.js'
+import { sharedSessionFindJevClient } from '../lib/session-find.js'
 import { isSafeDomainName } from '../lib/domains.js'
 
 /** What the route reads from a meeting review (6.57.1): the server's own record, never client text. */
@@ -34,6 +35,8 @@ export interface JevRouteDependencies {
   replies: (provider: AgentProvider, sessionId: string, afterMs: number | null) => Promise<string | null>
   /** 6.65.0: Work search keeps its own client and breaker; a newly saved key clears that breaker too. */
   searchJev: Pick<JevClient, 'resetForNewKey'>
+  /** Session find (Control 0.5.363) keeps its own client and breaker too. */
+  findJev: Pick<JevClient, 'resetForNewKey'>
 }
 
 /** Work identity first: it survives a rename, while a new card's id could equal an old identity's text hash. */
@@ -45,7 +48,7 @@ export function createJevRouter(overrides: Partial<JevRouteDependencies> = {}):
   const jev = overrides.jev ?? sharedJevClient()
   const deps: JevRouteDependencies = { jev, recommender: new SessionRecommender(createDecisionClient('session', jev)), list: listBoard, validate: validateJevKey, save: saveJevKey,
     completion: new CompletionChecker(createDecisionClient('completion', jev)), replies: (provider, sessionId, afterMs) => readRepliesSince(provider, sessionId, afterMs),
-    searchJev: sharedWorkSearchJevClient(), ...overrides }
+    searchJev: sharedWorkSearchJevClient(), findJev: sharedSessionFindJevClient(), ...overrides }
   const router = Router()
   router.use(['/jev-key', '/work-board/session-recommendation', '/work-board/completion-check'], (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
 
@@ -67,6 +70,7 @@ export function createJevRouter(overrides: Partial<JevRouteDependencies> = {}):
     }
     deps.jev.resetForNewKey()
     deps.searchJev.resetForNewKey()
+    deps.findJev.resetForNewKey()
     return res.json({ ok: true, ...deps.jev.status() })
   })
 

package/server/routes/live-cues.ts

@@ -3,11 +3,13 @@
 //
 // POST /live-cues/start { sessionId, kinds? }  -> { armed, sessionId, pipelinesUsed } (v1) or the v2 arm answer
 //   kinds (6.86.0, v2 only): 'legacy' (reinforce, challenge) or 'extended' (plus decision, promise, followUp). Absent: a
-//   Mac recording (mac_ id) gets extended, every other meeting legacy, so an older companion never sees a kind it drops.
+//   Mac recording (mac_ id) gets extended, every other meeting legacy, so an older companion never sees a kind it drops. A G2 meeting armed 'extended' (6.97.9) gets the five kinds and
+//   nothing else of the Mac's: no general (web) cues, no cue mode `general` switching its focused cues off, no open-items fold.
 // POST /live-cues/stop  { sessionId }  -> { nudgesGenerated, nudges }
 // GET  /live-cues/status               -> engine snapshot + capability
 // GET  /live-cues/v2/settings           -> { enabled, source: env|setting|default, capability }       (6.76.2)
 // POST /live-cues/v2/settings { enabled } -> same shape; 409 { error: 'env_forced' } when env forces v2 on
+//   ?v=2 / {v: 2}: the spend limits (6.79.2). ?v=3 / {v: 3}: the cue mode, grounded cues and the general-cue limits (live cues v3).
 // POST /live-cues/feedback { sessionId, cueId, verdict, note? } -> { ok, cueId, verdict, vote }                 (6.79.0)
 // GET  /live-cues/history?days=7&sessionId=a,b&unrated=1&limit=200 -> { v: 1, cues, counts, truncated, skipped, maxCuesPerMeeting, meetings? } (6.79.0)
 
@@ -20,8 +22,11 @@ import {
   LiveCuesArmError,
 } from '../lib/live-cues-engine.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
-import { applyLiveCuesV2Settings, liveCuesV2SettingsViewV2 } from '../lib/live-cues-v2.js'
-import { LIVE_CUES_V2_LIMIT_BOUNDS, LIVE_CUES_V2_LIMIT_NAMES, limitInBounds, type LiveCuesV2StoredLimits } from '../lib/live-cues-v2-settings.js'
+import { applyLiveCuesV2Settings, liveCuesV2SettingsViewV2, liveCuesV2SettingsViewV3 } from '../lib/live-cues-v2.js'
+import {
+  LIVE_CUES_GENERAL_LIMIT_BOUNDS, LIVE_CUES_GENERAL_LIMIT_NAMES, LIVE_CUES_V2_LIMIT_BOUNDS, LIVE_CUES_V2_LIMIT_NAMES, generalLimitInBounds, isCueMode, isGrounding, limitInBounds,
+  type LiveCuesGeneralStoredLimits, type LiveCuesV2StoredLimits,
+} from '../lib/live-cues-v2-settings.js'
 import { LIVE_CUES_V2_LIMITS, LiveCuesV2ArmError, liveCuesV2, liveCuesV2Advertised, liveCuesV2Enabled, liveCuesV2MeetingCounters, liveCuesV2SettingsView, peekLiveCuesV2, setLiveCuesV2Enabled } from '../lib/live-cues-v2.js'
 import { LIVE_CUE_VERDICTS_PROTOCOL, LIVE_CUE_VERDICT_LIMITS, VerdictsUnreadableError, isCueVerdict, liveCueVerdicts } from '../lib/live-cue-verdicts.js'
 
@@ -202,15 +207,15 @@ liveCuesRouter.get('/live-cues/history', (req, res) => {
 liveCuesRouter.get('/live-cues/v2/settings', (req, res) => {
   res.set('Cache-Control', 'private, no-store')
   const v = req.query.v
-  if (v !== undefined && v !== '2') return res.status(400).json({ error: 'invalid_request', reason: 'unsupported_version' })
-  try { return res.json(v === '2' ? liveCuesV2SettingsViewV2() : liveCuesV2SettingsView()) } catch { return res.status(503).json({ error: 'settings_unavailable' }) }
+  if (v !== undefined && v !== '2' && v !== '3') return res.status(400).json({ error: 'invalid_request', reason: 'unsupported_version' })
+  try { return res.json(v === '3' ? liveCuesV2SettingsViewV3() : v === '2' ? liveCuesV2SettingsViewV2() : liveCuesV2SettingsView()) } catch { return res.status(503).json({ error: 'settings_unavailable' }) }
 })
 
 const V2_SETTINGS_KEYS = new Set<string>(['v', 'enabled', ...LIVE_CUES_V2_LIMIT_NAMES])
 liveCuesRouter.post('/live-cues/v2/settings', (req, res) => {
   res.set('Cache-Control', 'private, no-store')
   const body = req.body as { enabled?: unknown; v?: unknown } | undefined
-  if (body && typeof body === 'object' && !Array.isArray(body) && body.v !== undefined) return postSettingsV2(body as Record<string, unknown>, res)
+  if (body && typeof body === 'object' && !Array.isArray(body) && body.v !== undefined) return postSettingsVersioned(body as Record<string, unknown>, res)
   if (!body || typeof body !== 'object' || Array.isArray(body) || typeof body.enabled !== 'boolean') {
     return res.status(400).json({ error: 'invalid_request' })
   }
@@ -223,12 +228,19 @@ liveCuesRouter.post('/live-cues/v2/settings', (req, res) => {
   }
 })
 
-/** POST {v: 2, ...}: every field is checked before anything is saved, so a refused request changes nothing. */
-function postSettingsV2(body: Record<string, unknown>, res: import('express').Response) {
-  if (body.v !== 2) return res.status(400).json({ error: 'invalid_request', reason: 'unsupported_version' })
-  const unknown = Object.keys(body).find(k => !V2_SETTINGS_KEYS.has(k))
+const V3_SETTINGS_KEYS = new Set<string>([...V2_SETTINGS_KEYS, 'cueMode', 'grounding', ...LIVE_CUES_GENERAL_LIMIT_NAMES.map(name => LIVE_CUES_GENERAL_LIMIT_BOUNDS[name].field)])
+
+/** POST {v: 2, ...} (the spend limits, 6.79.2) and POST {v: 3, ...} (live cues v3: the same plus cueMode, grounding and the six
+ *  general limits). Every field is checked before anything is saved, so a refused request changes nothing. v=2 takes none of
+ *  the v3 fields (unknown_field), exactly as before. A bad enum is invalid_value; a number out of bounds names the wire field. */
+function postSettingsVersioned(body: Record<string, unknown>, res: import('express').Response) {
+  if (body.v !== 2 && body.v !== 3) return res.status(400).json({ error: 'invalid_request', reason: 'unsupported_version' })
+  const v3 = body.v === 3
+  const unknown = Object.keys(body).find(k => !(v3 ? V3_SETTINGS_KEYS : V2_SETTINGS_KEYS).has(k))
   if (unknown) return res.status(400).json({ error: 'invalid_request', reason: 'unknown_field', field: unknown })
   if (body.enabled !== undefined && typeof body.enabled !== 'boolean') return res.status(400).json({ error: 'invalid_request', reason: 'invalid_enabled', field: 'enabled' })
+  if (v3 && body.cueMode !== undefined && !isCueMode(body.cueMode)) return res.status(400).json({ error: 'invalid_request', reason: 'invalid_value', field: 'cueMode' })
+  if (v3 && body.grounding !== undefined && !isGrounding(body.grounding)) return res.status(400).json({ error: 'invalid_request', reason: 'invalid_value', field: 'grounding' })
   const limits: LiveCuesV2StoredLimits = {}
   for (const name of LIVE_CUES_V2_LIMIT_NAMES) {
     if (body[name] === undefined) continue
@@ -238,11 +250,21 @@ function postSettingsV2(body: Record<string, unknown>, res: import('express').Re
     }
     limits[name] = body[name] as number
   }
-  if (body.enabled === undefined && Object.keys(limits).length === 0) return res.status(400).json({ error: 'invalid_request', reason: 'empty' })
+  const general: LiveCuesGeneralStoredLimits = {}
+  for (const name of LIVE_CUES_GENERAL_LIMIT_NAMES) {
+    const b = LIVE_CUES_GENERAL_LIMIT_BOUNDS[name]
+    if (body[b.field] === undefined) continue
+    if (!generalLimitInBounds(name, body[b.field])) return res.status(400).json({ error: 'invalid_request', reason: 'out_of_bounds', field: b.field, min: b.min, max: b.max, integer: b.integer })
+    general[name] = body[b.field] as number
+  }
+  const v3Fields = body.cueMode !== undefined || body.grounding !== undefined || Object.keys(general).length > 0
+  if (body.enabled === undefined && Object.keys(limits).length === 0 && !v3Fields) return res.status(400).json({ error: 'invalid_request', reason: 'empty' })
   try {
-    const result = applyLiveCuesV2Settings({ ...(typeof body.enabled === 'boolean' ? { enabled: body.enabled } : {}), limits })
-    if (!result.ok) return res.status(409).json(result.error === 'env_locked' ? { error: 'env_locked', fields: result.fields } : { error: result.error })
-    return res.json(liveCuesV2SettingsViewV2())
+    const result = applyLiveCuesV2Settings({ ...(typeof body.enabled === 'boolean' ? { enabled: body.enabled } : {}), limits,
+      ...(isCueMode(body.cueMode) ? { cueMode: body.cueMode } : {}), ...(isGrounding(body.grounding) ? { grounding: body.grounding } : {}),
+      ...(Object.keys(general).length ? { general } : {}) })
+    if (!result.ok) return res.status(409).json(result.error === 'env_locked' ? { error: 'env_locked', fields: result.fields } : result.fields ? { error: 'env_forced', fields: result.fields } : { error: result.error })
+    return res.json(v3 ? liveCuesV2SettingsViewV3() : liveCuesV2SettingsViewV2())
   } catch {
     return res.status(500).json({ error: 'settings_write_failed' })
   }