@gotcos/glasses-server 6.76.1 → 6.77.0

package/server/routes/meeting.ts

@@ -182,6 +182,12 @@ import {
 } from '../lib/meeting-finalization-jobs.js'
 import { enrichStandaloneMeeting } from '../lib/meeting-summary-persistence.js'
 import { recordFinalPassSkip, runNemotronFinalPass, type FinalPassOptions, type FinalPassOutcome } from '../lib/nemotron-final.js'
+import { runTranscriptCleanup, type CleanupOutcome } from '../lib/transcript-cleanup.js'
+import { sweepTranscriptCleanupData } from '../lib/transcript-cleanup-screen.js'
+import type { TranscriptCleanupRouteDeps } from './transcript-cleanup.js'
+
+/** 6.77.0: the post-save transcript cleanup. Injectable so tests never reach a model. */
+export type TranscriptCleanupRunner = (input: { sessionId: string; meetingPath: string; sidecarPath: string }) => Promise<CleanupOutcome>
 
 /** 6.61.0: the save-time Nemotron pass. Injectable so tests never spawn the CLI. */
 export type FinalDiarize = (options: Pick<FinalPassOptions, 'meetingPath' | 'sidecarPath' | 'audioDir'>) => Promise<FinalPassOutcome>
@@ -243,6 +249,8 @@ export interface MeetingRouteDependencies {
   finalDiarize?: FinalDiarize
   /** Control's stop requests for live G2 meetings (lib/meeting-stop-requests.ts). */
   stopRequests?: StopRequestStore
+  /** 6.77.0: the post-save transcript cleanup (lib/transcript-cleanup.ts). */
+  transcriptCleanup?: TranscriptCleanupRunner
 }
 
 const activeFinalizationJobs = new Set<string>()
@@ -254,6 +262,21 @@ interface FinalizationRuntime {
   scheduleBackground: (task: Promise<void>) => void
   sessions?: MeetingSessionSource
   finalDiarize?: FinalDiarize
+  transcriptCleanup?: TranscriptCleanupRunner
+}
+
+/**
+ * The cleanup as finalization runs it: a meeting whose session is somehow live again is
+ * skipped, and nothing it does can fail the finalization (it never throws; this catch is
+ * the last line of defence should that ever change).
+ */
+async function runCleanupStage(runner: TranscriptCleanupRunner | undefined, input: { sessionId: string; meetingPath: string; sidecarPath: string }, sessions?: MeetingSessionSource): Promise<void> {
+  const run = runner ?? (cleanupInput => runTranscriptCleanup(cleanupInput, { sessionLive: id => (sessions?.getState ?? defaultSessionState)(id) === 'active' }))
+  try {
+    await run(input)
+  } catch (error) {
+    console.warn(`[meeting/save] transcript cleanup threw; the saved transcript is unchanged: ${error instanceof Error ? error.name : 'error'}`)
+  }
 }
 
 function validReplayEntries(raw: unknown[]): IndexedTranscriptChunk[] | null {
@@ -372,6 +395,11 @@ function scheduleFinalizationJob(job: MeetingFinalizationJob, runtime: Finalizat
       markCanonicalFinalizationState(current.sidecarPath, 'ops_pending', current.claimPending)
     }
 
+    // 6.77.0: the transcript is final here (HQ text and the Nemotron relabel are written),
+    // and nothing downstream has read it yet: COS operations imports, and the standalone
+    // summary describes, the cleaned text. Off unless Miles turns it on.
+    await runCleanupStage(runtime.transcriptCleanup, { sessionId: current.sessionId, meetingPath: current.meetingPath, sidecarPath: current.sidecarPath }, runtime.sessions)
+
     if (cosOpsPipelineConfigured() && !MAC_CAPTURE_ID.test(current.sessionId)) {
       await handoffMeetingToOperations(current.meetingPath)
     } else {
@@ -558,6 +586,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
   const emit = deps.emit ?? emitDisplay
   const finalizationJobs = deps.finalizationJobs ?? new MeetingFinalizationJobStore()
   const finalDiarize = deps.finalDiarize ?? runNemotronFinalPass
+  const transcriptCleanup = deps.transcriptCleanup
   const router = Router()
   const savingSessions = new Set<string>()
   const stopRequests = deps.stopRequests ?? createStopRequestStore()
@@ -780,6 +809,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
         finalizationJobs.reconcileCanonicalSidecars()
         const pendingJob = finalizationJobs.get(sessionId)
         if (pendingJob) scheduleFinalizationJob(pendingJob, {
+          transcriptCleanup,
           finalizationJobs,
           runBatch,
           scheduleBackground,
@@ -956,6 +986,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
           scheduleBackground,
           sessions,
           finalDiarize,
+          transcriptCleanup,
         })
       }
     } catch (error) {
@@ -2438,6 +2469,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
           },
         })
       } catch { /* display is best-effort */ }
+      await runCleanupStage(transcriptCleanup, { sessionId, meetingPath: saved.filepath, sidecarPath: saved.sidecarPath }, sessions)
       if (cosOpsPipelineConfigured() && !macCapture) {
         await handoffMeetingToOperations(saved.filepath)
       } else {
@@ -2620,3 +2652,36 @@ async function finalizeBatch(options: {
 }
 
 export const meetingRouter = createMeetingRouter()
+
+/** 6.77.0: what the transcript cleanup routes need from the meeting layer. */
+export function transcriptCleanupRouteDeps(store: MeetingStore = getMeetingStore()): TranscriptCleanupRouteDeps {
+  return {
+    sessionState: id => defaultSessionState(id),
+    sessionStartedAt: id => getSessionStartTime(id),
+    findMeeting: id => {
+      const meeting = store.findBySessionId(id)
+      return meeting ? { meetingPath: meeting.filepath, sidecarPath: meeting.sidecarPath } : null
+    },
+  }
+}
+
+/**
+ * Boot: delete cleanup data (screen context and ledgers) whose meeting is gone, and screen
+ * text past its retention. Deferred and unref'd, so it never delays startup or a restart.
+ */
+export function scheduleTranscriptCleanupSweep(delayMs = 90_000): void {
+  const timer = setTimeout(() => {
+    try {
+      const store = getMeetingStore()
+      const jobs = new MeetingFinalizationJobStore()
+      const result = sweepTranscriptCleanupData({
+        now: Date.now(),
+        known: id => defaultSessionState(id) !== 'missing' || Boolean(jobs.get(id)) || store.findBySessionId(id) !== null,
+      })
+      if (result.screenDeleted || result.ledgersDeleted) {
+        console.log(`[transcript-cleanup] swept ${result.screenDeleted} screen and ${result.ledgersDeleted} ledger files`)
+      }
+    } catch { /* the next boot sweeps again */ }
+  }, delayMs)
+  timer.unref()
+}

package/server/routes/transcribe.ts

@@ -37,6 +37,9 @@ transcribeRouter.get('/transcribe/capabilities', (_req, res) => {
     localOnly: true,
     dictionary: 'cos',
     benchmark: 1,
+    // 6.77.0: post-save transcript cleanup. suggestions = /api/transcript-cleanup/suggestions,
+    // screenContext = POST /api/meeting/:sessionId/screen-context.
+    transcriptCleanup: { protocol: 1, suggestions: 1, screenContext: 1 },
   })
 })
 

package/server/routes/transcript-cleanup.ts

@@ -0,0 +1,237 @@
+// Transcript cleanup routes (6.77.0). Token-authenticated by the global /api X-Cos-Token
+// middleware (index.ts) like every other /api route; nothing here is public.
+//
+// Settings (COS Control's toggle, later):
+//   GET  /transcript-cleanup/settings                  { enabled, source, model, modelSource, limits, today }
+//   POST /transcript-cleanup/settings { enabled?, model? }   same shape; 409 env_forced when env pins the value
+// Screen context (COS Control supplies on-screen text during a meeting, later):
+//   POST   /meeting/:sessionId/screen-context { lines: [{ at, text, app? }] }  counts of what was stored
+//   GET    /meeting/:sessionId/screen-context            counts only, never the text
+//   DELETE /meeting/:sessionId/screen-context            { deleted }
+// The cleanup ledger of one meeting:
+//   GET  /meeting/:sessionId/transcript-cleanup          { runs, edits }  (edits carry original and replacement words)
+//   POST /meeting/:sessionId/transcript-cleanup/undo { editId } | { runId }
+// Dictionary suggestions (COS Control's Dictionary tab, later):
+//   GET  /transcript-cleanup/suggestions?status=pending|all
+//   POST /transcript-cleanup/suggestions/:id/accept { correction? }
+//   POST /transcript-cleanup/suggestions/:id/dismiss
+
+import { Router } from 'express'
+import { appendScreenContext, deleteScreenContext, ScreenContextError, SESSION_ID, screenContextStats } from '../lib/transcript-cleanup-screen.js'
+import { alreadyCleaned, ledgerView, readLedger, readTranscriptSection, sha256, undoCleanupEdits } from '../lib/transcript-cleanup-ledger.js'
+import { cleanupLimits, resolveCleanupModel, resolveCleanupSwitch, transcriptCleanupBudget, transcriptCleanupSettings, type TranscriptCleanupBudget, type TranscriptCleanupSettings } from '../lib/transcript-cleanup-state.js'
+import { SUGGESTION_ID, suggestionStore, type DictionarySuggestion, type SuggestionStore } from '../lib/transcript-cleanup-suggestions.js'
+import { getVocabulary } from '../lib/profile.js'
+import { readFileSync } from 'node:fs'
+
+export const TRANSCRIPT_CLEANUP_PROTOCOL = 1
+
+type GlossaryOutcome = { status: number; body: unknown }
+
+export interface TranscriptCleanupRouteDeps {
+  env?: NodeJS.ProcessEnv
+  now?: () => Date
+  settings?: TranscriptCleanupSettings
+  budget?: TranscriptCleanupBudget
+  suggestions?: SuggestionStore
+  /** 'active' while the meeting is being recorded. */
+  sessionState?: (sessionId: string) => 'active' | 'closed' | 'missing'
+  sessionStartedAt?: (sessionId: string) => number | null
+  /** The saved meeting's files, or null. */
+  findMeeting?: (sessionId: string) => { meetingPath: string; sidecarPath: string } | null
+  addVocabulary?: (term: string) => Promise<GlossaryOutcome>
+  learnCorrection?: (body: { heard: string; written: string; source: 'meeting' }) => Promise<GlossaryOutcome>
+  vocabulary?: () => string[]
+}
+
+/** Health and capability shape. Codes only: /api/health is public. */
+export function transcriptCleanupAdvertised(env: NodeJS.ProcessEnv = process.env, settings: TranscriptCleanupSettings = transcriptCleanupSettings()): { protocol: number; enabled: boolean } {
+  let enabled = false
+  try { enabled = resolveCleanupSwitch(env, settings).enabled } catch { enabled = false }
+  return { protocol: TRANSCRIPT_CLEANUP_PROTOCOL, enabled }
+}
+
+function suggestionView(s: DictionarySuggestion, vocabulary: string[]): DictionarySuggestion & { inVocabulary: boolean } {
+  const lower = s.written.trim().toLowerCase()
+  return { ...s, inVocabulary: vocabulary.some(v => v.trim().toLowerCase() === lower) }
+}
+
+export function createTranscriptCleanupRouter(deps: TranscriptCleanupRouteDeps = {}): Router {
+  const env = deps.env ?? process.env
+  const now = deps.now ?? (() => new Date())
+  const settings = deps.settings ?? transcriptCleanupSettings()
+  const budget = deps.budget ?? transcriptCleanupBudget()
+  const suggestions = deps.suggestions ?? suggestionStore()
+  const sessionState = deps.sessionState ?? (() => 'missing' as const)
+  const sessionStartedAt = deps.sessionStartedAt ?? (() => null)
+  const findMeeting = deps.findMeeting ?? (() => null)
+  const vocabulary = deps.vocabulary ?? (() => { try { return getVocabulary() } catch { return [] } })
+  const addVocabulary = deps.addVocabulary ?? (async term => (await import('./glossary.js')).glossaryAddVocabulary(term))
+  const learnCorrection = deps.learnCorrection ?? (async body => (await import('./glossary.js')).glossaryLearnCorrection(body))
+  const router = Router()
+
+  const settingsView = () => {
+    const sw = resolveCleanupSwitch(env, settings)
+    const model = resolveCleanupModel(env, settings)
+    const limits = cleanupLimits(env)
+    const state = budget.read()
+    return {
+      protocol: TRANSCRIPT_CLEANUP_PROTOCOL,
+      enabled: sw.enabled,
+      source: sw.source,
+      model: model.choice,
+      modelId: model.id,
+      modelSource: model.source,
+      limits: { dailyCalls: limits.dailyCalls, dailyTokens: limits.dailyTokens, maxSpansPerMeeting: limits.maxSpans },
+      today: {
+        calls: Math.min(state.calls, Number.MAX_SAFE_INTEGER),
+        tokens: Math.min(state.tokens, Number.MAX_SAFE_INTEGER),
+        breakerOpenUntil: state.breakerOpenUntil !== null && state.breakerOpenUntil > now().getTime() ? new Date(state.breakerOpenUntil).toISOString() : null,
+      },
+    }
+  }
+
+  router.get('/transcript-cleanup/settings', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    try { return res.json(settingsView()) } catch { return res.status(503).json({ error: 'settings_unavailable' }) }
+  })
+
+  router.post('/transcript-cleanup/settings', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const body = req.body as { enabled?: unknown; model?: unknown } | undefined
+    if (!body || typeof body !== 'object' || Array.isArray(body)) return res.status(400).json({ error: 'invalid_request' })
+    const hasEnabled = body.enabled !== undefined, hasModel = body.model !== undefined
+    if ((!hasEnabled && !hasModel) || (hasEnabled && typeof body.enabled !== 'boolean') || (hasModel && body.model !== 'haiku' && body.model !== 'sonnet')) {
+      return res.status(400).json({ error: 'invalid_request' })
+    }
+    if (hasEnabled && (env.COS_TRANSCRIPT_CLEANUP === '1' || env.COS_TRANSCRIPT_CLEANUP === '0') && body.enabled !== (env.COS_TRANSCRIPT_CLEANUP === '1')) {
+      return res.status(409).json({ error: 'env_forced' })
+    }
+    if (hasModel && (env.COS_TRANSCRIPT_CLEANUP_MODEL === 'haiku' || env.COS_TRANSCRIPT_CLEANUP_MODEL === 'sonnet') && body.model !== env.COS_TRANSCRIPT_CLEANUP_MODEL) {
+      return res.status(409).json({ error: 'env_forced' })
+    }
+    try {
+      settings.save({ ...(hasEnabled ? { enabled: body.enabled as boolean } : {}), ...(hasModel ? { model: body.model as 'haiku' | 'sonnet' } : {}) }, now())
+      return res.json(settingsView())
+    } catch {
+      return res.status(500).json({ error: 'settings_write_failed' })
+    }
+  })
+
+  const sessionParam = (raw: string | undefined): string | null => (raw && SESSION_ID.test(raw) ? raw : null)
+
+  /** A late flush right after stop is welcome until the cleanup has run on the saved meeting. */
+  function screenAdmission(sessionId: string): { ok: true } | { ok: false; status: number; error: string } {
+    if (sessionState(sessionId) === 'active') return { ok: true }
+    const meeting = findMeeting(sessionId)
+    if (!meeting) return { ok: false, status: 404, error: 'unknown_session' }
+    const done = readLedger(sessionId).rows.some(r => r.kind === 'run' && (r.phase === 'done' || r.phase === 'skipped'))
+    return done ? { ok: false, status: 409, error: 'cleanup_done' } : { ok: true }
+  }
+
+  router.post('/meeting/:sessionId/screen-context', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const sessionId = sessionParam(req.params.sessionId)
+    if (!sessionId) return res.status(400).json({ error: 'invalid_session_id' })
+    const admission = screenAdmission(sessionId)
+    if (!admission.ok) return res.status(admission.status).json({ error: admission.error })
+    try {
+      const result = appendScreenContext(sessionId, req.body, { now: now().getTime(), sessionStartedAt: sessionStartedAt(sessionId) })
+      return res.json({ ok: true, protocol: TRANSCRIPT_CLEANUP_PROTOCOL, ...result })
+    } catch (error) {
+      if (error instanceof ScreenContextError) return res.status(error.status).json({ error: error.code })
+      return res.status(503).json({ error: 'screen_context_unavailable' })
+    }
+  })
+
+  router.get('/meeting/:sessionId/screen-context', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const sessionId = sessionParam(req.params.sessionId)
+    if (!sessionId) return res.status(400).json({ error: 'invalid_session_id' })
+    return res.json({ protocol: TRANSCRIPT_CLEANUP_PROTOCOL, ...screenContextStats(sessionId) })
+  })
+
+  router.delete('/meeting/:sessionId/screen-context', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const sessionId = sessionParam(req.params.sessionId)
+    if (!sessionId) return res.status(400).json({ error: 'invalid_session_id' })
+    try { return res.json({ deleted: deleteScreenContext(sessionId) }) } catch { return res.status(500).json({ error: 'delete_failed' }) }
+  })
+
+  router.get('/meeting/:sessionId/transcript-cleanup', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const sessionId = sessionParam(req.params.sessionId)
+    if (!sessionId) return res.status(400).json({ error: 'invalid_session_id' })
+    const view = ledgerView(sessionId)
+    let current: string | null = null
+    const meeting = findMeeting(sessionId)
+    if (meeting) {
+      try { const section = readTranscriptSection(readFileSync(meeting.meetingPath, 'utf8')); current = section === null ? null : sha256(section) } catch { current = null }
+    }
+    return res.json({ protocol: TRANSCRIPT_CLEANUP_PROTOCOL, ...view, cleanedCurrent: current !== null && alreadyCleaned(sessionId, current) })
+  })
+
+  router.post('/meeting/:sessionId/transcript-cleanup/undo', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const sessionId = sessionParam(req.params.sessionId)
+    if (!sessionId) return res.status(400).json({ error: 'invalid_session_id' })
+    const body = (req.body ?? {}) as { editId?: unknown; runId?: unknown }
+    const editId = typeof body.editId === 'string' && /^te_[0-9a-f]{16}$/.test(body.editId) ? body.editId : undefined
+    const runId = typeof body.runId === 'string' && /^tc_[0-9a-f]{16}$/.test(body.runId) ? body.runId : undefined
+    if (!editId === !runId) return res.status(400).json({ error: 'editId_or_runId_required' })
+    const meeting = findMeeting(sessionId)
+    if (!meeting) return res.status(404).json({ error: 'meeting_missing' })
+    const result = undoCleanupEdits({ sessionId, meetingPath: meeting.meetingPath, sidecarPath: meeting.sidecarPath, editId, runId, now })
+    if (!result.ok) return res.status(result.status).json({ error: result.error })
+    return res.json({ reverted: result.reverted })
+  })
+
+  router.get('/transcript-cleanup/suggestions', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const status = typeof req.query.status === 'string' ? req.query.status : 'pending'
+    if (status !== 'pending' && status !== 'all') return res.status(400).json({ error: 'invalid_status' })
+    const vocab = vocabulary()
+    const list = suggestions.list().filter(s => status === 'all' || s.status === 'pending')
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).map(s => suggestionView(s, vocab))
+    return res.json({ protocol: TRANSCRIPT_CLEANUP_PROTOCOL, suggestions: list })
+  })
+
+  router.post('/transcript-cleanup/suggestions/:id/accept', async (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const id = req.params.id
+    if (!SUGGESTION_ID.test(id)) return res.status(400).json({ error: 'invalid_suggestion_id' })
+    const body = (req.body ?? {}) as { correction?: unknown }
+    if (body.correction !== undefined && typeof body.correction !== 'boolean') return res.status(400).json({ error: 'invalid_request' })
+    const suggestion = suggestions.get(id)
+    if (!suggestion) return res.status(404).json({ error: 'suggestion_not_found' })
+    if (suggestion.status === 'dismissed') return res.status(409).json({ error: 'suggestion_dismissed' })
+    try {
+      const heard = suggestion.heard.find(h => h.trim().toLowerCase() !== suggestion.written.trim().toLowerCase())
+      const outcome = body.correction === true && heard
+        ? await learnCorrection({ heard, written: suggestion.written, source: 'meeting' })
+        : await addVocabulary(suggestion.written)
+      if (outcome.status !== 200) return res.status(outcome.status).json(outcome.body)
+      const accepted = suggestions.setStatus(id, 'accepted', now().toISOString()) ?? suggestion
+      const out = outcome.body as { unchanged?: boolean; glossary?: unknown; entry?: unknown }
+      return res.json({ suggestion: suggestionView(accepted, vocabulary()), unchanged: out.unchanged === true, glossary: out.glossary ?? null, entry: out.entry ?? null })
+    } catch {
+      return res.status(500).json({ error: 'accept_failed' })
+    }
+  })
+
+  router.post('/transcript-cleanup/suggestions/:id/dismiss', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const id = req.params.id
+    if (!SUGGESTION_ID.test(id)) return res.status(400).json({ error: 'invalid_suggestion_id' })
+    try {
+      const dismissed = suggestions.setStatus(id, 'dismissed', now().toISOString())
+      if (!dismissed) return res.status(404).json({ error: 'suggestion_not_found' })
+      return res.json({ suggestion: suggestionView(dismissed, vocabulary()) })
+    } catch {
+      return res.status(500).json({ error: 'dismiss_failed' })
+    }
+  })
+
+  return router
+}
+

package/server/scripts/live-cues-v2-notes-mutation-gate.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// Live cues v2 6.76.2 mutation gate: the runtime switch, the notes fallback and the decision provider. Mutations run only
+// in a disposable copy of the checkout; the live checkout is never rewritten.
+//
+// What it proves, in order:
+//   0. The target suites are GREEN unmutated. A gate over a red suite reads every mutant as killed and proves nothing.
+//   1. Each target string appears EXACTLY ONCE in its file, so the mutation is unambiguous.
+//   2. The mutated file differs from the original, so the edit landed.
+//   3. A NAMED test fails ("FAIL  server/x.test.ts > name"); a build error or a harness failure is not a kill.
+//   4. The file is restored byte for byte (compared) before the next mutant.
+// Also the Live COS Ask's memory bridge fallback (searchAskHistory) and the helpers it shares with cues (cos-bridge-notes.ts).
+// Usage: node server/scripts/live-cues-v2-notes-mutation-gate.mjs [--list] [name…]
+import { mkdtempSync, cpSync, readFileSync, writeFileSync, symlinkSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { resolve, join, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+const CUES = ['server/lib/live-cues-v2.test.ts', 'server/lib/live-cues-v2-notes.test.ts', 'server/lib/live-cues-v2-notes-bridge.test.ts',
+  'server/lib/live-cues-v2-settings.test.ts', 'server/routes/live-cues-v2-settings-route.test.ts', 'server/routes/live-cues-v2-route.test.ts']
+const HEALTH = [...CUES, 'server/routes/health.test.ts']
+const ASK = ['server/lib/live-cos-ask-memory-fallback.test.ts', 'server/lib/live-cos-ask-queen-runtime.test.ts', 'server/lib/meeting-ask-cos-search.test.ts',
+  'server/lib/live-cos-ask.test.ts', 'server/lib/meeting-ask-owner.test.ts']
+const BOTH = [...CUES, ...ASK]
+const ALL = [...HEALTH, ...ASK]
+const ENGINE = 'server/lib/live-cues-v2.ts', NOTES = 'server/lib/live-cues-v2-notes.ts', SETTINGS = 'server/lib/live-cues-v2-settings.ts'
+const ROUTE = 'server/routes/live-cues.ts', DECISION = 'server/lib/decision-provider.ts'
+const SHARED = 'server/lib/cos-bridge-notes.ts', ASKLIB = 'server/lib/live-cos-ask.ts'
+const m = (name, file, edits, tests = CUES) => ({ name, file, edits: typeof edits[0] === 'string' ? [edits] : edits, tests })
+
+const mutations = [
+  // ── Runtime switch ──
+  m('env-forces-only-exact-1', SETTINGS, ["return env.COS_LIVE_CUES_V2 === '1'", 'return !!env.COS_LIVE_CUES_V2']),
+  m('env-forced-wins-over-setting', SETTINGS, ["if (liveCuesV2EnvForced(env)) return { enabled: true, source: 'env' }", 'if (false) return { enabled: true, source: \'env\' }']),
+  m('saved-setting-read', SETTINGS, ["if (stored !== null) return { enabled: stored, source: 'setting' }", "if (stored === true) return { enabled: stored, source: 'setting' }"]),
+  m('malformed-setting-is-none', SETTINGS, ["typeof (raw as { enabled?: unknown }).enabled === 'boolean'", '(raw as { enabled?: unknown }).enabled !== undefined']),
+  m('cache-follows-write', SETTINGS, ['    this.cache = { value: enabled }\n', '']),
+  m('failed-write-keeps-memory', SETTINGS, [
+    ['    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })\n', '    this.cache = { value: enabled }\n    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })\n'],
+    ["{ mode: 0o600 })\n    this.cache = { value: enabled }\n", '{ mode: 0o600 })\n']]),
+  m('settings-file-private', SETTINGS, ["+ '\\n', { mode: 0o600 })", "+ '\\n', { mode: 0o644 })"]),
+  m('engine-reads-setting', ENGINE, ['private enabled(): boolean { return liveCuesV2Enabled(this.deps.env, this.deps.settings) }', 'private enabled(): boolean { return liveCuesV2Enabled(this.deps.env, null) }']),
+  m('feed-stops-while-off', ENGINE, ['    if (!this.enabled()) return\n    if (this.deps.store.isEnded(sessionId)) return', '    if (this.deps.store.isEnded(sessionId)) return']),
+  m('last-check-before-emit', ENGINE, ['|| this.deps.store.isPaused(s.sessionId) || !this.enabled()) {', '|| this.deps.store.isPaused(s.sessionId)) {']),
+  m('suspend-aborts-in-flight', ENGINE, ['if (s.inFlight) { s.inFlight.abort(V2_OFF); aborted += 1 }', 'if (s.inFlight) { aborted += 1 }']),
+  m('cancel-reason-traced', ENGINE, ["      if (trace.outcome === 'cancelled' && abort.signal.reason === V2_OFF) trace.cancelReason = V2_OFF\n", '']),
+  m('env-forced-off-refused', ENGINE, ["if (!enabled && liveCuesV2EnvForced(env)) return { ok: false, error: 'env_forced' }", "if (false) return { ok: false, error: 'env_forced' }"]),
+  m('turning-off-suspends', ENGINE, ['const aborted = engine?.suspend() ?? 0', 'const aborted = 0']),
+  m('suspend-only-on-transition', ENGINE, ['if (wasOn && !liveCuesV2Enabled(env)) {', 'if (!liveCuesV2Enabled(env)) {']),
+  m('saved-meeting-ends-known-session', ENGINE, ['(liveCuesV2Enabled() || engine?.knows(sid))', 'liveCuesV2Enabled()']),
+  m('knows-armed-sessions', ENGINE, ['knows(sessionId: string): boolean { return this.sessions.has(sessionId) }', 'knows(sessionId: string): boolean { return false }']),
+  m('route-v2-owns-known-meeting', ROUTE, ['return liveCuesV2Enabled() || (peekLiveCuesV2()?.knows(sessionId) ?? false)', 'return liveCuesV2Enabled()']),
+  m('route-boolean-enabled-only', ROUTE, ["typeof body.enabled !== 'boolean'", 'body.enabled === undefined']),
+  m('route-409-body', ROUTE, ['if (!result.ok) return res.status(409).json({ error: result.error })', 'if (!result.ok) return res.status(200).json(liveCuesV2SettingsView())']),
+  m('advertised-follows-setting', ENGINE, ['return liveCuesV2Enabled(env) ? liveCuesV2Capability() : undefined', "return env.COS_LIVE_CUES_V2 === '1' ? liveCuesV2Capability() : undefined"], HEALTH),
+  // ── Notes fallback (engine) ──
+  m('fallback-runs-on-failure', ENGINE, ['if (cueMemoryFailed(mem) && !abort.signal.aborted) {', 'if (false) {']),
+  m('cue-memory-preferred', ENGINE, ['if (cueMemoryFailed(mem) && !abort.signal.aborted) {', 'if (!abort.signal.aborted) {']),
+  m('failure-codes-only', ENGINE, ['return !!mem.denseError && CUE_MEMORY_FAILURES.has(mem.denseError)', 'return !!mem.denseError']),
+  m('timeout-is-a-failure', ENGINE, ["'no_cue_memory_script', 'memory_timeout', 'spawn_failed'", "'no_cue_memory_script', 'spawn_failed'"]),
+  m('notes-candidates-to-judge', ENGINE, ['        mem = { notes: found.notes }\n', '        mem = { notes: [] }\n']),
+  m('notes-get-session-and-bound', ENGINE, ['this.deps.notes(window, before, abort.signal, s.sessionId)', "this.deps.notes(window, before, abort.signal, '')"]),
+  m('source-none-when-empty', ENGINE, ["cueMemorySource: mem.notes.length ? source : 'none'", 'cueMemorySource: source']),
+  m('capability-memory-source', ENGINE, [": notesAvailable() ? 'notes' : 'none'", ": 'none'"]),
+  // ── Notes fallback (search) ──
+  m('notes-date-bound', NOTES, ['!!c && !(c.date && c.date >= before)', '!!c']),
+  m('notes-local-day', SHARED, ["return Number.isFinite(ms) ? new Date(ms).toLocaleDateString('en-CA') : ''", "return Number.isFinite(ms) ? v.slice(0, 10) : ''"], BOTH),
+  m('notes-drop-live-meeting', NOTES, ['hits.filter(h => !(opts.sessionId && h.sessionId === opts.sessionId))', 'hits']),
+  m('notes-budget-race', NOTES, ['new Promise<boolean>(r => { timer = setTimeout(() => r(true), budgetMs) })', 'new Promise<boolean>(() => {})']),
+  m('notes-bridge-timeout', NOTES, ['searchers.bridge(local.signal, budgetMs)', 'searchers.bridge(local.signal, 30_000)']),
+  m('notes-abort-at-budget', NOTES, ['  clearTimeout(timer)\n  local.abort()\n', '  clearTimeout(timer)\n']),
+  m('notes-aborted-gets-nothing', NOTES, ['  if (signal.aborted) return { notes: [] }\n', '']),
+  m('notes-no-terms-no-search', NOTES, ["  if (!terms.length) return { notes: [], error: 'notes_no_terms' }\n", '']),
+  m('notes-queries-short', NOTES, ['terms.slice(0, 4).join', 'terms.join']),
+  m('notes-stopwords', NOTES, ['if (term.length < 3 || STOP.has(term) ||', 'if (term.length < 3 ||']),
+  m('shared-rank-fusion', SHARED, ['score: (prev?.score ?? 0) + 1 / (RRF_K + rank)', 'score: 1 / (RRF_K + rank)'], BOTH),
+  m('shared-fusion-keeps-order-on-ties', SHARED, ['b.score - a.score || a.order - b.order', 'b.score - a.score || b.order - a.order'], BOTH),
+  m('notes-top-four', NOTES, ['fused.ranked(top)', 'fused.ranked()']),
+  m('shared-bridge-scored', SHARED, ['    .filter(x => x.score > 0).sort(', '    .sort('], BOTH),
+  m('shared-bridge-needs-content', SHARED, ['if (!id || !content.trim()) continue', 'if (!id) continue'], BOTH),
+  m('shared-bridge-lists-memory', SHARED, ["callPython(['memory', '--days'", "callPython(['memory-overview', '--days'"], BOTH),
+  m('notes-bridge-searched', NOTES, ['    for (const q of queries) add(rankBridgeMemories(rows, q).map(bridgeCandidate))\n', '']),
+  m('notes-real-memories-keyword-only', NOTES, ['(await searchMemories({ query, limit: 10, semantic: false, signal })).hits', '[]']),
+  m('notes-real-meetings-keyword-only', NOTES, ['(await searchMeetingLibrary({ query, limit: 10, semantic: false, signal })).hits', '[]']),
+  // ── Decision provider ──
+  m('cue-override-read', ENGINE, ['  if (raw !== undefined) {\n', '  if (false) {\n']),
+  m('cue-override-validated', ENGINE, ["    if (v !== 'jev' && v !== 'subq') throw new DecisionProviderError('decision_invalid_provider')\n", '']),
+  m('only-key-subq', ENGINE, ["  if (!keys.jev() && keys.subq()) return { provider: 'subq', source: 'only_key' }\n", '']),
+  m('only-key-needs-no-jev', ENGINE, ['if (!keys.jev() && keys.subq()) return', 'if (keys.subq()) return']),
+  m('global-env-ignored', ENGINE, ['  const raw = env.COS_DECISION_PROVIDER_CUES\n', "  const raw = env.COS_DECISION_PROVIDER_CUES ?? env.COS_DECISION_PROVIDER\n"]),
+  m('global-setting-ignored', ENGINE, [
+    ["import type { DecisionProvider } from './decision-settings.js'", "import { readDecisionSettings, type DecisionProvider } from './decision-settings.js'"],
+    ['  const raw = env.COS_DECISION_PROVIDER_CUES\n', '  const raw = env.COS_DECISION_PROVIDER_CUES ?? readDecisionSettings().provider\n']]),
+  m('judge-uses-evaluation-provider', ENGINE, ['abort.signal, provider)\n        Object.assign(trace, { judgeMs', 'abort.signal, this.deps.decisionProvider())\n        Object.assign(trace, { judgeMs']),
+  m('gate-uses-provider', ENGINE, ['await this.deps.gate(s.title, window, abort.signal, provider)', "await this.deps.gate(s.title, window, abort.signal, 'jev')"]),
+  m('real-deps-route-subq', ENGINE, ["cueDecisionCalls(provider === 'subq' ? subq : jev)", 'cueDecisionCalls(jev)']),
+  m('capability-key-check', ENGINE, ["      if (!st.configured) return off(provider === 'jev' && this.deps.decisionState('subq').configured ? 'jev_not_configured' : 'decision_not_configured')\n", '']),
+  m('jev-alias-only-with-subq-key', ENGINE, ["provider === 'jev' && this.deps.decisionState('subq').configured ? 'jev_not_configured'", "provider === 'jev' ? 'jev_not_configured'"]),
+  m('decision-not-configured-reason', ENGINE, ["this.deps.decisionState('subq').configured ? 'jev_not_configured' : 'decision_not_configured'", "this.deps.decisionState('subq').configured ? 'jev_not_configured' : 'jev_not_configured'"]),
+  m('capability-selected-provider-state', ENGINE, ['      const st = this.deps.decisionState(provider)\n', "      const st = this.deps.decisionState('jev')\n"]),
+  m('subq-cap-reason', ENGINE, ["off(provider === 'jev' ? 'jev_cap_reached' : 'decision_cap_reached')", "off('jev_cap_reached')"]),
+  m('subq-breaker-reason', ENGINE, ["off(provider === 'jev' ? 'jev_breaker_open' : 'decision_breaker_open')", "off('jev_breaker_open')"]),
+  m('capability-names-provider', ENGINE, ['...(provider ? { decisionProvider: provider } : {})', '...({})']),
+  m('quiet-decision-stops', ENGINE, ["'decision_cap_reached', 'decision_breaker_open', 'decision_not_configured', 'decision_invalid_provider'])", "'decision_breaker_open', 'decision_not_configured', 'decision_invalid_provider'])"]),
+  m('quiet-sees-decision-errors', ENGINE, ['if ((error instanceof JevError || error instanceof DecisionProviderError) && QUIET_DECISION_STOPS.has(error.code)) {', 'if (error instanceof JevError && QUIET_DECISION_STOPS.has(error.code)) {']),
+  m('decision-error-code-traced', ENGINE, ["trace.error = error instanceof JevError || error instanceof DecisionProviderError ? error.code :", "trace.error = error instanceof JevError ? error.code :"]),
+  m('subq-cue-cap-env', ENGINE, ['Number(process.env.COS_LIVE_CUES_SUBQ_DAILY_TOKENS)', 'Number(process.env.COS_SUBQ_DAILY_TOKENS)']),
+  m('subq-cue-ledger', ENGINE, ["dataPath('subq-cues-usage.json')", "dataPath('subq-usage.json')"]),
+  m('subq-configured-honest', ENGINE, ['return { configured: st.configured, breakerOpen: st.breakerOpenUntil !== null', 'return { configured: true, breakerOpen: st.breakerOpenUntil !== null']),
+  m('subq-status-unreadable-is-spent', DECISION, ['    let usedToday = dailyCap\n', '    let usedToday = 0\n']),
+  m('subq-tracked-for-new-key', DECISION, ['{ configuredSubqClients.add(client); return client }', '{ return client }']),
+  // ── Live COS Ask: memory bridge fallback ──
+  m('ask-listing-only-when-memory-did-not-answer', ASKLIB, ['  const memoryDidNotAnswer = memoryRaw.length === 0 ||', '  const memoryDidNotAnswer = true ||'], ASK),
+  m('ask-listing-when-memory-empty', ASKLIB, ['  const memoryDidNotAnswer = memoryRaw.length === 0 ||', '  const memoryDidNotAnswer = false ||'], ASK),
+  m('ask-listing-when-meaning-failed', ASKLIB, ["|| (memory.status === 'fulfilled' && semantic && !memory.value.semanticAvailable)\n", '\n'], ASK),
+  m('ask-listing-meaning-only', ASKLIB, ["(memory.status === 'fulfilled' && semantic && !memory.value.semanticAvailable)", "(memory.status === 'fulfilled' && !memory.value.semanticAvailable)"], ASK),
+  m('ask-listing-threshold', ASKLIB, ['x.score >= ASK_HIT_MIN && (!domain', 'x.score > 0 && (!domain'], ASK),
+  m('ask-listing-domain', ASKLIB, ['x.score >= ASK_HIT_MIN && (!domain || x.row.domain === domain)', 'x.score >= ASK_HIT_MIN'], ASK),
+  m('ask-memory-cap-three', ASKLIB, ['const memorySources = fused.ranked(3)', 'const memorySources = fused.ranked()'], ASK),
+  m('ask-listing-notice', ASKLIB, ["  if (memorySources.some(s => s.listed)) notices.push('COS also searched the notes in its memory list by keyword.')\n", ''], ASK),
+  m('ask-abort-skips-listing', ASKLIB, ['if (memoryDidNotAnswer && !signal?.aborted) {', 'if (memoryDidNotAnswer) {'], ASK),
+  m('ask-listing-failure-tolerated', ASKLIB, ['try { listed = await bridge(signal) } catch { /* no listing: the notices above stand */ }', 'listed = await bridge(signal)'], ASK),
+  m('ask-source-id-first', ASKLIB, ["({ id: `H${sources.length + 1}`, ...s })", "({ ...s, id: `H${sources.length + 1}` })"], ASK),
+  m('ask-listing-cites-content', ASKLIB, ['text: redactSecrets(row.content).slice(0, 1500), memoryId: row.id', "text: '', memoryId: row.id"], ASK),
+  m('ask-default-listing-is-the-bridge', ASKLIB, ['bridge: AskBridgeList = s => listBridgeMemories(s)', 'bridge: AskBridgeList = async () => []'], ASK),
+]
+
+const args = process.argv.slice(2)
+if (args.includes('--list')) { for (const { name } of mutations) console.log(name); process.exit(0) }
+const selected = args.length ? mutations.filter(({ name }) => args.includes(name)) : mutations
+if (args.length && selected.length !== args.length) throw new Error('Unknown mutation name in: ' + args.join(' '))
+if (new Set(mutations.map(x => x.name)).size !== mutations.length) throw new Error('Duplicate mutation name')
+
+const scratch = mkdtempSync(join(tmpdir(), 'cues-notes-mutations-'))
+try {
+  const skip = new Set(['data', 'models', 'certs', 'node_modules'])
+  cpSync(join(root, 'server'), join(scratch, 'server'), { recursive: true, filter: src => !(skip.has(basename(src)) && dirname(src) === join(root, 'server')) })
+  for (const dir of ['shared', 'work-task-runtime', 'bin', 'docs', 'memory-runtime']) cpSync(join(root, dir), join(scratch, dir), { recursive: true })
+  for (const file of ['vitest.config.ts', 'package.json', 'managed-runtime-contract.json']) cpSync(join(root, file), join(scratch, file))
+  symlinkSync(join(root, 'node_modules'), join(scratch, 'node_modules'), 'dir')
+  const run = tests => spawnSync(process.execPath, [join(root, 'node_modules/vitest/vitest.mjs'), 'run', '--maxWorkers=1', ...tests], {
+    cwd: scratch, env: { PATH: process.env.PATH, HOME: scratch, TMPDIR: process.env.TMPDIR, COS_DATA_DIR: join(scratch, 'data'), COS_PROFILE_PATH: join(scratch, 'data', 'profile.json') },
+    encoding: 'utf8', timeout: 300000,
+  })
+  const baseline = run(ALL)
+  if (baseline.status !== 0) throw new Error('Baseline failed; a gate over a red suite proves nothing:\n' + baseline.stdout + '\n' + baseline.stderr)
+  const totals = /Tests\s+(\d+) passed/.exec(baseline.stdout)
+  console.log(`baseline PASS (${totals ? totals[1] : '?'} tests in ${ALL.length} files)`)
+  let killed = 0
+  for (const { name, file, edits, tests } of selected) {
+    const target = join(scratch, file), original = readFileSync(target, 'utf8')
+    let mutated = original
+    for (const [find, replacement] of edits) {
+      if (mutated.split(find).length !== 2) throw new Error(`Mutation ${name} does not match exactly once in ${file}: ${find.slice(0, 80)}`)
+      mutated = mutated.replace(find, () => replacement)
+    }
+    if (mutated === original) throw new Error(`Mutation ${name} did not change ${file}`)
+    writeFileSync(target, mutated)
+    let result
+    try { result = run(tests) } finally { writeFileSync(target, original) }
+    if (readFileSync(target, 'utf8') !== original) throw new Error(`Restore failed for ${file} after ${name}`)
+    const output = result.stdout + '\n' + result.stderr
+    const killers = [...new Set([...output.matchAll(/FAIL\s+(server\/\S+\.test\.ts > [^\n]+)/g)].map(x => x[1].trim()))]
+    if (result.status === 0 || result.error || !killers.length) { console.log(`${name} SURVIVED or harness failed\n${output.slice(-3000)}`); process.exitCode = 1; continue }
+    killed += 1
+    console.log(`${name} KILLED by ${killers.slice(0, 2).join(' | ')}${killers.length > 2 ? ` (+${killers.length - 2} more)` : ''}`)
+  }
+  console.log(`${killed} of ${selected.length} live cues and Ask 6.76.2 mutations killed`)
+} finally { rmSync(scratch, { recursive: true, force: true }) }