@gotcos/glasses-server 6.76.1 → 6.78.0

package/server/lib/env-switch.ts

@@ -0,0 +1,17 @@
+/**
+ * 6.78.0: the ONE reader for every 6.78.0 switch (P7 S3). Before it, the Sessions switches
+ * took only an exact `1` or `0` while the Messages and crash-loop switches also took
+ * `true`/`false`/`on`/`off`, so `COS_QUEUE_RECONCILE=false` read ON.
+ *
+ * `1`, `true` or `on` force a switch on; `0`, `false` or `off` force it off; case and
+ * surrounding space are ignored. Anything else (unset or empty included) is the switch's
+ * DEFAULT. Callers read it at call time, so a restart applies a change.
+ *
+ * Pure, no imports: the Pi Durable canaries load modules that use it.
+ */
+export function readSwitch(raw: string | undefined, fallback: boolean): boolean {
+  const value = (raw ?? '').trim().toLowerCase()
+  if (value === '1' || value === 'true' || value === 'on') return true
+  if (value === '0' || value === 'false' || value === 'off') return false
+  return fallback
+}

package/server/lib/fuzzy-correct.ts

@@ -4,7 +4,11 @@
 //
 // Used by:
 //   - /api/transcribe       (short-form dictation / messaging)
-//   - /api/meeting/save     (batch post-processing, Phase 3.5 — via meeting.ts)
+//   - prompt drafts         (routes/prompt-drafts.ts)
+//   - the post-save transcript cleanup (6.77.0, transcript-cleanup.ts), one word at
+//     a time through fuzzyReplacementFor, with the meeting's own screen and file
+//     terms as extra targets. Not otherwise on the meeting save path: the Phase 3.5
+//     LLM pass this file once fed was deleted with the app's server fork.
 //
 // Zero LLM cost, ~5ms on typical dictation length.
 //
@@ -191,6 +195,72 @@ const COMMON_ENGLISH_WORDS = new Set<string>([
   'willie', 'zachary',
 ])
 
+/** True for a word the stop list protects from ever being replaced (lowercase compare). */
+export function isCommonEnglishWord(word: string): boolean {
+  return COMMON_ENGLISH_WORDS.has(word.toLowerCase())
+}
+
+/**
+ * The proper-noun targets fuzzy correction may write, in first-seen order: speaker
+ * tokens (Ext, Unknown, the owner label) and entries that do not start uppercase or
+ * are shorter than 4 characters are dropped.
+ */
+export function canonicalFuzzyTargets(targets: string[]): string[] {
+  const owner = getOwnerSpeakerLabel()
+  return Array.from(new Set(
+    targets
+      .filter(t => {
+        if (!t || t.length < 4) return false
+        if (t === 'Ext' || t === 'Unknown' || t === owner) return false
+        return /^[A-Z]/.test(t.trim())
+      })
+      .map(t => t.trim()),
+  ))
+}
+
+/**
+ * The replacement fuzzy correction would write for ONE word, or null to leave it.
+ * `canonical` comes from canonicalFuzzyTargets. Same rules as applyFuzzyCorrections,
+ * which calls this for every candidate word.
+ */
+export function fuzzyReplacementFor(word: string, canonical: string[], targetLowerSet?: ReadonlySet<string>): string | null {
+  if (!/^[A-Za-z][A-Za-z'-]{4,}$/.test(word)) return null
+  const lower = word.toLowerCase()
+
+  // Skip common English words (primary false-positive defense)
+  if (COMMON_ENGLISH_WORDS.has(lower)) return null
+
+  // Skip exact matches (already correct)
+  const exact = targetLowerSet ?? new Set(canonical.map(t => t.toLowerCase()))
+  if (exact.has(lower)) return null
+
+  // Length-scaled distance threshold
+  const len = word.length
+  const maxDist = len <= 8 ? 1 : len <= 11 ? 2 : 3
+
+  let bestTarget: string | null = null
+  let bestDist = maxDist + 1
+
+  for (const target of canonical) {
+    // Split multi-word targets — match on individual tokens
+    const tokens = target.split(/\s+/)
+    for (const token of tokens) {
+      if (token.length < 4) continue
+      // Length difference must be small to prevent collapses
+      if (Math.abs(token.length - len) > 2) continue
+      const dist = levenshtein(lower, token.toLowerCase())
+      if (dist > 0 && dist < bestDist && dist <= maxDist) {
+        bestDist = dist
+        bestTarget = token
+      }
+    }
+  }
+
+  if (!bestTarget) return null
+  // Preserve original capitalization pattern
+  return /^[A-Z]/.test(word) ? bestTarget : bestTarget.toLowerCase()
+}
+
 /**
  * Fuzzy-match transcript words against a canonical list of proper nouns.
  *
@@ -218,16 +288,7 @@ export function applyFuzzyCorrections(
 
   // Keep only targets that look like proper nouns.
   // Drop speaker tokens and entries that don't start with uppercase.
-  const owner = getOwnerSpeakerLabel()
-  const canonical = Array.from(new Set(
-    targets
-      .filter(t => {
-        if (!t || t.length < 4) return false
-        if (t === 'Ext' || t === 'Unknown' || t === owner) return false
-        return /^[A-Z]/.test(t.trim())
-      })
-      .map(t => t.trim()),
-  ))
+  const canonical = canonicalFuzzyTargets(targets)
   if (canonical.length === 0) return { text, replacements: 0 }
 
   const targetLowerSet = new Set(canonical.map(t => t.toLowerCase()))
@@ -237,44 +298,11 @@ export function applyFuzzyCorrections(
   // Match any 5+ char word (case-insensitive). Stop-list + strict distance
   // thresholds are the primary defenses against false positives.
   const result = text.replace(/\b[A-Za-z][A-Za-z'-]{4,}\b/g, (word) => {
-    const lower = word.toLowerCase()
-
-    // Skip common English words (primary false-positive defense)
-    if (COMMON_ENGLISH_WORDS.has(lower)) return word
-
-    // Skip exact matches (already correct)
-    if (targetLowerSet.has(lower)) return word
-
-    // Length-scaled distance threshold
-    const len = word.length
-    const maxDist = len <= 8 ? 1 : len <= 11 ? 2 : 3
-
-    let bestTarget: string | null = null
-    let bestDist = maxDist + 1
-
-    for (const target of canonical) {
-      // Split multi-word targets — match on individual tokens
-      const tokens = target.split(/\s+/)
-      for (const token of tokens) {
-        if (token.length < 4) continue
-        // Length difference must be small to prevent collapses
-        if (Math.abs(token.length - len) > 2) continue
-        const dist = levenshtein(lower, token.toLowerCase())
-        if (dist > 0 && dist < bestDist && dist <= maxDist) {
-          bestDist = dist
-          bestTarget = token
-        }
-      }
-    }
-
-    if (bestTarget) {
-      replacements++
-      fuzzyLog.push({ from: word, to: bestTarget })
-      // Preserve original capitalization pattern
-      const wasCapitalized = /^[A-Z]/.test(word)
-      return wasCapitalized ? bestTarget : bestTarget.toLowerCase()
-    }
-    return word
+    const replacement = fuzzyReplacementFor(word, canonical, targetLowerSet)
+    if (replacement === null) return word
+    replacements++
+    fuzzyLog.push({ from: word, to: replacement })
+    return replacement
   })
 
   if (fuzzyLog.length > 0) {

package/server/lib/live-cos-ask.ts

@@ -11,6 +11,7 @@ import { createHash } from 'node:crypto'
 import { runLensGistEngine, redactSecrets } from './lens-gist-engines.js'
 import { AskProcessError } from './meeting-ask-runner.js'
 import { searchMemories } from './context-library-search.js'
+import { listBridgeMemories, localDateOf, RankFusion, scoreBridgeMemories, type BridgeMemory } from './cos-bridge-notes.js'
 import { searchMeetingLibrary } from './meeting-library-search.js'
 import { MEETING_ASK_LABELS, meetingAskAnswerMarkdown, meetingAskCitations, type MeetingAskSection, type MeetingAskPhaseTiming, type MeetingAskTimings } from '../../shared/meeting-ask.js'
 import { ABSENCE_CLAIM, matchOwnerName, ownerCardSource, personLookupQuery, personQuestion, searchedDisclosure, type OwnerCard } from './meeting-ask-owner.js'
@@ -240,18 +241,51 @@ export function sectionsFromAnswer(action: AskAction, answer: string, allowed: R
 }
 /** 'meaning' adds the embedding search (default); 'keyword' stays on local keyword matching, so no query is embedded. */
 export type CosSearchMode = 'meaning' | 'keyword'
-export async function searchAskHistory(query: string, excludeSessionId?: string, signal?: AbortSignal, mode: CosSearchMode = 'meaning', domain?: string): Promise<{ sources: AskSource[]; notices: string[] }> {
+/** The memory bridge listing searchAskHistory falls back to (cos-bridge-notes.ts); a parameter so tests can fake it. */
+export type AskBridgeList = (signal?: AbortSignal) => Promise<BridgeMemory[]>
+const ASK_HIT_MIN = 0.35
+export async function searchAskHistory(query: string, excludeSessionId?: string, signal?: AbortSignal, mode: CosSearchMode = 'meaning', domain?: string, bridge: AskBridgeList = s => listBridgeMemories(s)): Promise<{ sources: AskSource[]; notices: string[] }> {
   const semantic = mode !== 'keyword'
   const results = await Promise.allSettled([searchMemories({ query, limit: domain ? 50 : 3, semantic, ...(signal?{signal}:{}) }), searchMeetingLibrary({ query, limit: 3, semantic, ...(domain ? {domain} : {}), ...(signal?{signal}:{}) })])
   const sources: AskSource[] = [], notices: string[] = semantic ? [] : ['COS search used keywords only, as set in Meeting assistant settings.']
   if (domain) notices.push(`COS search focused on the confirmed ${domain.replace(/_/g, ' ')} domain.`)
-  results.forEach((result, i) => {
-    if (result.status === 'rejected') { if(result.reason instanceof AskProcessError)throw result.reason; notices.push(`${i === 0 ? 'COS memory' : 'Earlier meeting'} search is unavailable.`); return }
-    if (semantic && !result.value.semanticAvailable) notices.push(`${i === 0 ? 'COS memory' : 'Earlier meeting'} semantic search is unavailable; local keyword results are shown.`)
-    result.value.hits.filter(h => (!domain || h.domain === domain) && (!excludeSessionId || !('sessionId' in h) || h.sessionId !== excludeSessionId) && Math.max(h.keywordScore, h.semanticScore) >= 0.35).slice(0, 3).forEach(h => {
-      sources.push({ id: `H${sources.length + 1}`, kind: i === 0 ? 'memory' : 'meeting', title: redactSecrets(h.title + ('date' in h && h.date ? ' · ' + h.date : '')).slice(0, 180), text: redactSecrets(h.snippet).slice(0, 1500), ...('recordId' in h ? { recordId: h.recordId, sessionId: h.sessionId, domain: h.domain, month: h.month, filename: h.filename } : { memoryId: h.id, domain: h.domain }) })
+  for (const result of results) if (result.status === 'rejected' && result.reason instanceof AskProcessError) throw result.reason
+  const keep = (h: { domain?: string; keywordScore: number; semanticScore: number; sessionId?: string }) =>
+    (!domain || h.domain === domain) && (!excludeSessionId || !('sessionId' in h) || h.sessionId !== excludeSessionId) && Math.max(h.keywordScore, h.semanticScore) >= ASK_HIT_MIN
+  // id first: the same key order as before, so an unchanged search yields the same prompt bytes.
+  const source = (s: Omit<AskSource, 'id'>): AskSource => ({ id: `H${sources.length + 1}`, ...s })
+  // Memories. 6.76.2: when memory search did not answer (it failed, its meaning arm failed, or it found nothing), the
+  // owner's notes are also read from the memory bridge listing and matched by keyword (cos-bridge-notes.ts, shared with
+  // live cues). The public memory runtime keeps them only there. A memory search that answers is used exactly as before.
+  const memory = results[0]
+  if (memory.status === 'rejected') notices.push('COS memory search is unavailable.')
+  else if (semantic && !memory.value.semanticAvailable) notices.push('COS memory semantic search is unavailable; local keyword results are shown.')
+  const memoryRaw = memory.status === 'fulfilled' ? memory.value.hits : []
+  const memoryHits = memoryRaw.filter(keep)
+  const fused = new RankFusion<Omit<AskSource, 'id'> & { listed?: true }>()
+  fused.add(memoryHits.map(h => ({ key: `memory:${h.id}`, item: { kind: 'memory' as const, title: redactSecrets(h.title).slice(0, 180), text: redactSecrets(h.snippet).slice(0, 1500), memoryId: h.id, domain: h.domain } })))
+  const memoryDidNotAnswer = memoryRaw.length === 0 || (memory.status === 'fulfilled' && semantic && !memory.value.semanticAvailable)
+  if (memoryDidNotAnswer && !signal?.aborted) {
+    let listed: BridgeMemory[] = []
+    try { listed = await bridge(signal) } catch { /* no listing: the notices above stand */ }
+    fused.add(scoreBridgeMemories(listed, query).filter(x => x.score >= ASK_HIT_MIN && (!domain || x.row.domain === domain)).map(({ row }) => {
+      const date = localDateOf(row.created_at)
+      const title = row.summary || row.content.split('\n').find(l => l.trim()) || row.id
+      return { key: `memory:${row.id}`, item: { kind: 'memory' as const, title: redactSecrets(title.replace(/\s+/g, ' ').trim().slice(0, 140) + (date ? ' · ' + date : '')).slice(0, 180), text: redactSecrets(row.content).slice(0, 1500), memoryId: row.id, domain: row.domain, listed: true as const } }
+    }))
+  }
+  const memorySources = fused.ranked(3)
+  for (const { listed, ...s } of memorySources) sources.push(source(s))
+  if (memorySources.some(s => s.listed)) notices.push('COS also searched the notes in its memory list by keyword.')
+  // Earlier meetings: unchanged.
+  const meetings = results[1]
+  if (meetings.status === 'rejected') notices.push('Earlier meeting search is unavailable.')
+  else {
+    if (semantic && !meetings.value.semanticAvailable) notices.push('Earlier meeting semantic search is unavailable; local keyword results are shown.')
+    meetings.value.hits.filter(keep).slice(0, 3).forEach(h => {
+      sources.push(source({ kind: 'meeting', title: redactSecrets(h.title + (h.date ? ' · ' + h.date : '')).slice(0, 180), text: redactSecrets(h.snippet).slice(0, 1500), recordId: h.recordId, sessionId: h.sessionId, domain: h.domain, month: h.month, filename: h.filename }))
     })
-  })
+  }
   if (!sources.length) notices.push('No relevant COS history was found.')
   return { sources, notices }
 }

package/server/lib/live-cues-v2-notes.ts

@@ -0,0 +1,152 @@
+// Live cues v2 notes fallback (6.76.2). When cue_memory.py is missing, fails or times out (any Mac but Miles's has no such
+// script), the memory arm looks in the owner's own COS instead, with no model call and no query leaving the Mac:
+//   - searchMemories and searchMeetingLibrary, the search the Live COS Ask uses, in its keyword-only mode (semantic: false),
+//   - the memory bridge listing (`cos_api_bridge.py memory`, what COS Control's Memory list shows), where the public memory
+//     runtime 0.1.0 keeps the owner's notes (cos-bridge-notes.ts, shared with the Live COS Ask).
+// The window is never sent as a query. A few salient words are taken from it, and the candidates are ranked by
+// reciprocal rank fusion (k=60, as cue_memory.py does). The Jev or SubQ judge then decides relevance, exactly as for
+// cue_memory candidates. The whole arm is bounded by the 3 s dense budget of cue_memory.py. Nothing here logs.
+
+import { searchMemories, type ContextSearchHit } from './context-library-search.js'
+import { searchMeetingLibrary, type MeetingSearchHit } from './meeting-library-search.js'
+import { listBridgeMemories, localDateOf, RankFusion, scoreBridgeMemories, type BridgeMemory } from './cos-bridge-notes.js'
+export { localDateOf, normalizeBridgeMemories, type BridgeMemory } from './cos-bridge-notes.js'
+
+/** Mirrors cue_memory.py DENSE_BUDGET_S: the notes arm never takes longer than its dense arm may. */
+export const NOTES_BUDGET_MS = 3_000
+export const NOTES_TOP = 4
+const NOTE_CHARS = 520
+const TITLE_CHARS = 90
+
+export interface NoteCandidate { id: string; date: string; title: string; notes: string; key: string }
+export interface NotesResult { notes: NoteCandidate[]; error?: string }
+
+export interface NotesSearchers {
+  memories(query: string, signal: AbortSignal): Promise<ContextSearchHit[]>
+  meetings(query: string, signal: AbortSignal): Promise<MeetingSearchHit[]>
+  bridge(signal: AbortSignal, timeoutMs: number): Promise<BridgeMemory[]>
+}
+
+// cue_memory.py STOP, plus conversational filler that ASR produces and that would match every note.
+const STOP = new Set(`a an the and or but if then so of to in on at for with from by as is are was were be been being it its this that these those
+i you he she we they me him her us them my your our their what which who whom whose when where why how all any both each few more most other
+some such no nor not only own same than too very can will just don should now do does did doing have has had having would could might must
+shall may yeah yes okay ok like um uh gonna wanna kind sort really right know think going get got one two also there here about into over again
+further once out up down off say said says thing things lot gotta yep nope hmm mhm let lets thats theres dont didnt doesnt cant wont isnt im ive
+youre were theyre hes shes its okay alright actually basically literally maybe probably pretty much well good great cool sure thank thanks
+because cause want wanted need needs make made take took come came look looking see saw tell told talk talking mean means time today tomorrow
+yesterday week year day back still even something someone anything everything nothing way guess feel`.split(/\s+/).filter(Boolean))
+
+// Capitalised in every sentence position, so a capital says nothing about them being a name.
+const CALENDAR = new Set('monday tuesday wednesday thursday friday saturday sunday january february march april may june july august september october november december'.split(' '))
+
+/** The most salient words of the window, most salient first: frequency, a bonus for the last ~600 characters (what the
+ *  room is on now, the slice cue_memory.py embeds) and for a capitalised use mid-sentence (likely a name). Tokens use the
+ *  library tokenizer's alphabet ([a-z0-9]) so every term can match. */
+export function notesQueryTerms(window: string, max = 6): string[] {
+  const recentFrom = Math.max(0, window.length - 600)
+  const stats = new Map<string, { n: number; recent: boolean; proper: boolean; last: number }>()
+  for (const m of window.matchAll(/[A-Za-z0-9]+/g)) {
+    const raw = m[0], term = raw.toLowerCase(), at = m.index ?? 0
+    if (term.length < 3 || STOP.has(term) || /^\d{1,2}$/.test(term)) continue
+    const st = stats.get(term) ?? { n: 0, recent: false, proper: false, last: 0 }
+    st.n += 1
+    st.last = at
+    if (at >= recentFrom) st.recent = true
+    const before = window.slice(Math.max(0, at - 2), at)
+    if (/^[A-Z]/.test(raw) && !/[.!?\n]\s*$/.test(before) && at > 0) st.proper = true
+    stats.set(term, st)
+  }
+  return [...stats.entries()]
+    .map(([term, st]) => ({ term, score: st.n + (st.recent ? 0.5 : 0) + (st.proper && !CALENDAR.has(term) ? 1 : 0), last: st.last }))
+    .sort((a, b) => b.score - a.score || b.last - a.last)
+    .slice(0, max)
+    .map(x => x.term)
+}
+
+/** Two keyword queries: the top four terms (a note must share two of them, or one in its title, to match) and the top
+ *  two (either one matches). Distinct, in that order. */
+export function notesQueries(terms: string[]): string[] {
+  const qs = [terms.slice(0, 4).join(' '), terms.slice(0, 2).join(' ')].filter(q => q.trim())
+  return [...new Set(qs)]
+}
+
+const dateOf = localDateOf
+const flat = (v: unknown, max: number): string => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim().slice(0, max) : '')
+
+function memoryCandidate(hit: ContextSearchHit): NoteCandidate | null {
+  if (!hit.id) return null
+  return { id: '', date: dateOf(hit.created_at), title: flat(hit.title || hit.id, TITLE_CHARS), notes: flat(hit.snippet || hit.title, NOTE_CHARS), key: `memory:${hit.id}` }
+}
+function meetingCandidate(hit: MeetingSearchHit): NoteCandidate | null {
+  if (!hit.recordId) return null
+  return { id: '', date: dateOf(hit.date), title: flat(hit.title, TITLE_CHARS), notes: flat(hit.snippet || hit.title, NOTE_CHARS), key: `meeting:${hit.recordId}` }
+}
+function bridgeCandidate(row: BridgeMemory): NoteCandidate {
+  const firstLine = row.content.split('\n').find(l => l.trim()) ?? row.id
+  return { id: '', date: dateOf(row.created_at), title: flat(row.summary || firstLine, TITLE_CHARS), notes: flat(row.content, NOTE_CHARS), key: `memory:${row.id}` }
+}
+
+/** Bridge rows ranked for one query, best first (the shared scorer). */
+export function rankBridgeMemories(rows: BridgeMemory[], query: string): BridgeMemory[] {
+  return scoreBridgeMemories(rows, query).map(x => x.row)
+}
+
+export const realNotesSearchers: NotesSearchers = {
+  memories: async (query, signal) => (await searchMemories({ query, limit: 10, semantic: false, signal })).hits,
+  meetings: async (query, signal) => (await searchMeetingLibrary({ query, limit: 10, semantic: false, signal })).hits,
+  bridge: (signal, timeoutMs) => listBridgeMemories(signal, timeoutMs),
+}
+
+/**
+ * Candidates for the judge from the owner's own COS. `before` is exclusive (YYYY-MM-DD), like cue_memory.py; a note with
+ * no date is kept. `sessionId` drops the meeting being recorded if the library already holds a copy of it. Never throws:
+ * a source that fails is skipped, and running out of budget returns what was found so far with `error: notes_timeout`.
+ */
+export async function notesMemory(window: string, before: string, signal: AbortSignal,
+  opts: { sessionId?: string; budgetMs?: number; searchers?: NotesSearchers; top?: number } = {}): Promise<NotesResult> {
+  const budgetMs = opts.budgetMs ?? NOTES_BUDGET_MS
+  const searchers = opts.searchers ?? realNotesSearchers
+  const top = opts.top ?? NOTES_TOP
+  const terms = notesQueryTerms(window)
+  if (!terms.length) return { notes: [], error: 'notes_no_terms' }
+  const queries = notesQueries(terms)
+  const local = new AbortController()
+  const onAbort = () => local.abort()
+  signal.addEventListener('abort', onAbort, { once: true })
+  if (signal.aborted) local.abort()
+
+  const fused = new RankFusion<NoteCandidate>()
+  const failed: string[] = []
+  // The date bound applies before ranking, so a dropped note never takes a rank from one that stays.
+  const add = (list: Array<NoteCandidate | null>) => {
+    fused.add(list.filter((c): c is NoteCandidate => !!c && !(c.date && c.date >= before)).map(c => ({ key: c.key, item: c })))
+  }
+  const dropLive = (hits: MeetingSearchHit[]) => hits.filter(h => !(opts.sessionId && h.sessionId === opts.sessionId))
+
+  const work = (async () => {
+    const bridge = searchers.bridge(local.signal, budgetMs).catch(() => { failed.push('bridge'); return [] as BridgeMemory[] })
+    for (const q of queries) {
+      if (local.signal.aborted) return
+      try { add((await searchers.memories(q, local.signal)).map(memoryCandidate)) } catch { failed.push('memories') }
+      if (local.signal.aborted) return
+      try { add(dropLive(await searchers.meetings(q, local.signal)).map(meetingCandidate)) } catch { failed.push('meetings') }
+    }
+    const rows = await bridge
+    if (local.signal.aborted) return
+    for (const q of queries) add(rankBridgeMemories(rows, q).map(bridgeCandidate))
+  })()
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timedOut = await Promise.race([
+    work.then(() => false),
+    new Promise<boolean>(r => { timer = setTimeout(() => r(true), budgetMs) }),
+  ])
+  clearTimeout(timer)
+  local.abort()
+  signal.removeEventListener('abort', onAbort)
+  const notes = fused.ranked(top).map((c, i) => ({ ...c, id: `M${i + 1}` }))
+  if (signal.aborted) return { notes: [] }
+  if (timedOut) return { notes, error: 'notes_timeout' }
+  return failed.length ? { notes, error: `notes_${[...new Set(failed)].sort().join('_')}_failed` } : { notes }
+}

package/server/lib/live-cues-v2-settings.ts

@@ -0,0 +1,63 @@
+// Live cues v2 runtime switch (6.76.2). COS Control offers an on/off toggle; the choice is kept in this server's own data
+// dir and applies without a restart. Resolution order:
+//   1. env COS_LIVE_CUES_V2=1 forces v2 on (source 'env'); a request to turn it off is refused (409 env_forced).
+//   2. the saved setting (source 'setting').
+//   3. off (source 'default').
+// Only the exact value '1' forces. Any other env value (unset, '0', 'true') defers to the setting, as it always read as off.
+// An unreadable or malformed settings file reads as no setting, so it fails toward off, never toward spending.
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+export type LiveCuesV2SettingSource = 'env' | 'setting' | 'default'
+
+/** What the engine and the routes need from the store: the saved choice, or null when there is none. */
+export interface LiveCuesV2SettingReader { stored(): boolean | null }
+
+export class LiveCuesV2Settings implements LiveCuesV2SettingReader {
+  /** Loaded once; only this server writes the file, and every write goes through save(). */
+  private cache: { value: boolean | null } | null = null
+  constructor(readonly file: string) {}
+
+  stored(): boolean | null {
+    if (this.cache) return this.cache.value
+    let value: boolean | null = null
+    try {
+      if (existsSync(this.file)) {
+        const raw = JSON.parse(readFileSync(this.file, 'utf8')) as unknown
+        if (raw && typeof raw === 'object' && !Array.isArray(raw) && typeof (raw as { enabled?: unknown }).enabled === 'boolean') {
+          value = (raw as { enabled: boolean }).enabled
+        }
+      }
+    } catch { value = null }
+    this.cache = { value }
+    return value
+  }
+
+  /** Atomic and durable. The in-memory value changes only after the file is written, so a failed write changes nothing. */
+  save(enabled: boolean, now: Date = new Date()): void {
+    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
+    durableAtomicWriteFileSync(this.file, JSON.stringify({ schema: 1, enabled, updatedAt: now.toISOString() }) + '\n', { mode: 0o600 })
+    this.cache = { value: enabled }
+  }
+}
+
+export function liveCuesV2EnvForced(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_LIVE_CUES_V2 === '1'
+}
+
+export function resolveLiveCuesV2(env: NodeJS.ProcessEnv, settings: LiveCuesV2SettingReader | null): { enabled: boolean; source: LiveCuesV2SettingSource } {
+  if (liveCuesV2EnvForced(env)) return { enabled: true, source: 'env' }
+  let stored: boolean | null = null
+  try { stored = settings ? settings.stored() : null } catch { stored = null }
+  if (stored !== null) return { enabled: stored, source: 'setting' }
+  return { enabled: false, source: 'default' }
+}
+
+let singleton: LiveCuesV2Settings | null = null
+export function liveCuesV2Settings(): LiveCuesV2Settings {
+  if (!singleton) singleton = new LiveCuesV2Settings(dataPath('live-cues-v2-settings.json'))
+  return singleton
+}