@gotcos/glasses-server 6.74.0 → 6.75.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 6.75.0 - Live cues v2 MVP: Jev gate, rank-fusion memory, one writer (candidate, default off)
+
+- New live cues pipeline behind `COS_LIVE_CUES_V2=1` (default off; independent of the v1 `COS_LIVE_CUES` flag, so switching v2 off never re-enables the v1 Composer path): a Jev gate decides whether a moment deserves a cue (P(cue) >= `COS_LIVE_CUES_V2_GATE`, default 0.8), `cue_memory.py` in COS scripts ranks past meetings by rank fusion (BM25 first, then Qdrant dense inside a 3 s budget; no LLM), a Jev judge keeps at most two notes about the same client or project (P >= 0.8), and ONE tools-off Claude call writes the cue (`COS_LIVE_CUES_V2_MODEL`, default Sonnet 5.5; writer rules v3, `COS_LIVE_CUES_V2_PROMPT=v2` restores v2). Prompt strings are generated from the replay sources (`cue_rrf_replay/generate_server_prompts.py`) and pinned by sha256 in the tests.
+- Evidence, and the configuration it was measured in: held-out replay (112 windows, labels frozen before outputs) at gate 0.6 with writer v2: useful on required moments 26/29, unwanted 6/44, p50 7.2 s. The shipped defaults differ: gate 0.8 (pooled dev + held-out: 110/113 silent windows kept silent, 51/59 required admitted) and writer v3 (on the held-out windows after the fact, so development data: unsupported claims 18 to 11). Real-path latency through the server (Jev, `cue_memory.py`, Sonnet): 8.4 to 17.5 s per cue, the first call cold.
+- New SSE event `coaching_nudge_v2` (`shared/live-cues-v2.ts`: cueId, headline <= 64, detail <= 220, kind, sources with stable meeting ids, gate, model), emitted before its v1 `coaching_nudge` twin (headline only) for old companions; every v2 cue is checked against the shared validator before it is emitted. Ticketless subscribers receive neither.
+- Routes: `GET /api/live-cues/status?sessionId=` (per-meeting `state` active, paused, ended or stopped with a `reason`), `POST /api/live-cues/pause` (sequenced: an older `seq` never wins), `POST /api/live-cues/feedback`. `capabilities.liveCuesV2` on `/api/health` and `/api/models` (and `v2` on the status route) only while v2 is switched on, so with v2 off a companion treats the server as v1; reasons when unavailable include `budget_exhausted`, `jev_cap_reached` and `jev_breaker_open`. v2 needs companion 6.10.643 or later (6.10.640 reads only the v1 capability).
+- How it stops: 10 cues and 20 writer calls per meeting (persisted, so a restart does not reset them), 300 writer calls per local week (`COS_LIVE_CUES_V2_WEEKLY`; zone stored at first use; checked before the gate and charged before the writer, never refunded; an unreadable ledger fails closed for the week), Jev daily cap `COS_LIVE_CUES_JEV_DAILY_TOKENS` (default 1.5M, about 7 meeting hours) on its own ledger `jev-cues-usage.json`, a breaker after 3 failures (writer, Jev gate or judge errors, or the 45 s wall) without a successful writer call in between (cancel, pause, stale and maintenance are not failures; a writer quota error opens it at once), a 45 s wall per evaluation, single flight, 20 s cadence, 45 s cooldown, and no evaluation while the user's own query runs. Refuses to run with `ANTHROPIC_API_KEY` in the environment unless `COS_ALLOW_API_FALLBACK=1`. A caller's abort of a Jev request no longer counts toward the Jev client's breaker.
+- Stop and save tombstone the meeting (7 days) so trailing chunks never re-arm it; a chunk whose session closed during ASR no longer feeds cues (v1 included).
+- Logs without transcript text: `live-cues-trace.jsonl`, one row per evaluation (gate probability, kept memory, memory errors and index age, timings, cost, outcome), one `skip` row per reason per meeting at most every 5 minutes (paused, breaker, meeting cap, weekly budget, busy), and feedback rows (cueId, vote, and the user's own optional reason). The number guard is traced, not enforced, unless `COS_LIVE_CUES_V2_NUMBER_GUARD=withhold`.
+- Tests: `live-cues-v2.test.ts` (39) and `live-cues-v2-route.test.ts` (2); 32 guards mutation-tested, each mutation killed. COS `tests/test_cue_memory.py` (6; 4 guards mutation-tested).
+- Includes 6.74.0. Pair with companion 6.10.643 for the v2 lens and phone surfaces. Switched on only by `COS_LIVE_CUES_V2=1` in the managed server environment; with it off this server behaves as 6.74.0 for live cues.
+
 ## 6.74.0 - Mac dictation works for every user, and Parakeet installs from COS Control (local candidate)
 
 - Mac dictation has its own engine setting, `dictation`: `auto` (default), `parakeet-ultra` or `whisper`, saved with the other speech settings (`PUT /api/stt-settings {"dictation":"whisper"}`; GET adds `dictation.desktop` with `selected`, `effective`, `reason`, `reasonCode`, `options` and `note`). It no longer follows the Preview model. Every settings file written before 6.74.0 has no key and reads as `auto`, so a Mac that chose Parakeet keeps it.

package/managed-runtime-contract.json

@@ -20,6 +20,13 @@
     "COS_LIVE_CUES_GRAPH",
     "COS_LIVE_CUES_LIGHTRAG_RESERVE",
     "COS_LIVE_CUES_AUTO",
+    "COS_LIVE_CUES_V2",
+    "COS_LIVE_CUES_V2_GATE",
+    "COS_LIVE_CUES_V2_MODEL",
+    "COS_LIVE_CUES_V2_PROMPT",
+    "COS_LIVE_CUES_V2_WEEKLY",
+    "COS_LIVE_CUES_V2_NUMBER_GUARD",
+    "COS_LIVE_CUES_JEV_DAILY_TOKENS",
     "COS_BATCH_HQ_METAL",
     "COS_BATCH_HQ_FORCE_CPU",
     "COS_BATCH_HQ_TIMESTAMPS",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.74.0",
+  "version": "6.75.0",
   "description": "COS Glasses: self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -120,6 +120,7 @@ import { memoryRouter } from './routes/memory.js'
 import { threadsRouter } from './routes/threads.js'
 import { skillsRouter } from './routes/skills.js'
 import { shutdownLiveCues } from './lib/live-cues-engine.js'
+import { shutdownLiveCuesV2 } from './lib/live-cues-v2.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { sweepStaleTurnRequests } from './lib/turn-request.js'
@@ -1176,6 +1177,7 @@ async function gracefulShutdown(): Promise<void> {
   // explicitly inside the 8s force-exit budget. Single-flight guarantees at
   // most one tree per session, which fits.
   try {
+    try { shutdownLiveCuesV2() } catch (err) { console.error('[shutdown] live cues v2:', err) }
     await shutdownLiveCues()
   } catch (error) {
     console.error('[live-cues] shutdown termination failed:', error)

package/server/lib/display-bus.ts

@@ -8,7 +8,7 @@ const bus = new EventEmitter()
 bus.setMaxListeners(20) // Multiple glasses clients
 
 export interface DisplayEvent {
-  type: 'chunk' | 'done' | 'error' | 'tool_status' | 'start' | 'session_restore' | 'transcript_chunk' | 'prompt_transcript' | 'recording_start' | 'recording_stop' | 'coaching_nudge'
+  type: 'chunk' | 'done' | 'error' | 'tool_status' | 'start' | 'session_restore' | 'transcript_chunk' | 'prompt_transcript' | 'recording_start' | 'recording_stop' | 'coaching_nudge' | 'coaching_nudge_v2'
   data: Record<string, unknown>
 }
 

package/server/lib/jev.ts

@@ -138,12 +138,19 @@ export class JevClient {
       res = await this.fetchImpl(`${JEV_ENDPOINT}/systemone`, { method: 'POST', signal: AbortSignal.any([AbortSignal.timeout(JEV_LIMITS.timeoutMs), ...(options?.signal ? [options.signal] : [])]),
         headers: { Authorization: `Bearer ${key.key}`, 'Content-Type': 'application/json' },
         body: JSON.stringify({ state, model: JEV_MODEL, questions }) })
-    } catch { return this.fail('jev_unavailable', true) }
+    } catch {
+      // A caller's own cancel (pause, stop, shutdown) is not a Jev failure: it must not grow the breaker.
+      if (options?.signal?.aborted) throw jevCancelled()
+      return this.fail('jev_unavailable', true)
+    }
     if (res.status === 401 || res.status === 403 || res.status === 402) return this.fail('jev_key_rejected', true)
     if (res.status === 400 || res.status === 413 || res.status === 422) return this.fail('jev_request_rejected', false)
     if (!res.ok) return this.fail('jev_unavailable', true)
     let body: { answers?: JevAnswers['answers']; model?: string; usage?: { input_tokens?: number } }
-    try { body = await res.json() } catch { return this.fail('jev_bad_answer', true) }
+    try { body = await res.json() } catch {
+      if (options?.signal?.aborted) throw jevCancelled()
+      return this.fail('jev_bad_answer', true)
+    }
     const used = Number(body.usage?.input_tokens) || estimate  // count something even if usage is missing
     this.record(used)
     if (!body.answers || typeof body.answers !== 'object') return this.fail('jev_bad_answer', true)
@@ -152,6 +159,9 @@ export class JevClient {
   }
 }
 
+/** Thrown only when the caller's signal aborted; never counted toward the breaker. */
+export function jevCancelled(): Error { const e = new Error('cancelled'); e.name = 'AbortError'; return e }
+
 let shared: JevClient | null = null
 export function sharedJevClient(): JevClient { return shared ??= new JevClient() }
 /** Jev bills by input size; about 2.6 characters per token, measured on COS meeting and task text. */

package/server/lib/live-cues-engine.ts

@@ -37,6 +37,7 @@ import {
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
 import { atomicWriteFileSync } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
+import { liveCuesV2, liveCuesV2Enabled } from './live-cues-v2.js'
 
 // ── Gates ────────────────────────────────────────────────────────────────────
 const MIN_BUFFER_WORDS = 40
@@ -244,6 +245,8 @@ export async function feedLiveCueTranscript(
   text: string,
   asrDegraded = false,
 ): Promise<void> {
+  // v2 (COS_LIVE_CUES_V2=1) owns the feed when enabled; the Composer v1 path below is unchanged otherwise.
+  if (liveCuesV2Enabled()) return liveCuesV2().feed(sessionId, text, asrDegraded)
   let session = sessions.get(sessionId)
   if (!session) {
     if (process.env.COS_LIVE_CUES_AUTO === '1' && liveCuesEnabled()) {

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

@@ -0,0 +1,41 @@
+// GENERATED from operations/personal/wk42_2026/cue_rrf_replay (prompts.py, jev_gate.py, run_v42.py) on 2026-10-17.
+// These strings are the exact ones the dev replay (120 windows) and the held-out replay (112 windows) measured.
+// Do not hand-edit: change the replay source, re-run the replay, then regenerate.
+
+export const CUE_GATE_QUESTIONS = {
+  "act": {
+    "type": "choice",
+    "instructions": "Should the wearer's smart glasses show a live cue about the last part of the conversation in `window`?",
+    "criteria": {
+      "cue": "Live work is on the table right now: a decision being made or weighed (work or life), a commitment, a missing owner or deadline, a contradiction, a number or date that matters, or a plan being set.",
+      "silent": "Small talk, catching up, family or social conversation with no decision, storytelling, TV, video, podcast or news commentary, bedtime or household chatter, logistics with nothing to decide, or speech too garbled to tell."
+    }
+  },
+  "lookup": {
+    "type": "choice",
+    "instructions": "What extra information would most improve a cue about the last part of `window`?",
+    "criteria": {
+      "none": "Nothing extra; the conversation itself has what is needed, or no cue is needed.",
+      "past_meetings": "The wearer's own past meetings or notes about the same client, project, brand or person.",
+      "public_fact": "A public fact to check: a price, statistic, law, news event or published number."
+    }
+  },
+  "kind": {
+    "type": "choice",
+    "instructions": "If a cue were shown about the last part of `window`, which kind would help the wearer most?",
+    "criteria": {
+      "reinforce": "They are on the right track; name the evidence and the next step.",
+      "challenge": "There is a flaw, a missing piece, or a contradiction to raise."
+    }
+  }
+} as const
+
+export const CUE_JUDGE_INSTRUCTIONS = "Which past meeting note is about the same client, project, brand or decision as the last part of `window`? Choose none if no note is."
+export const CUE_JUDGE_NONE = "None of these notes is about the same client, project, brand or decision as the conversation."
+
+/** Writer v2: measured on dev (A9) and held-out (useful on required 26/29). */
+export const CUE_WRITER_SYSTEM_V2 = "You write one live cue for the wearer of smart glasses during a conversation. You work for the wearer.\nWrite ONE cue the wearer can act on in the next minute.\n1. One or two sentences, at most 200 characters, built around one specific taken from the window or memory: a number, name, date, or concrete next step.\n2. Every name, number, date, owner and target in the cue must appear in the window or memory. Never invent a deadline, owner, number, cap or test date.\n   If one is missing, say that it is missing (for example: no owner or date was set for X) instead of choosing one.\n3. Two kinds. reinforce: they are on track; name the evidence and the next step. challenge: the flaw, the missing piece, or the contradiction.\n   Check previousCues: do not only criticize, and never repeat a previous cue. No empty praise.\n4. Add something the room has not said: the missing owner, deadline or criterion, a risk, a contradiction, or a past decision from memory.\n   If the cue would only restate what was just said, output null.\n5. Use a memory note only when it is about the same client, project, brand or person as the window. Otherwise ignore memory completely.\n   Memory notes are past claims written at a point in time, not facts. Cite the date, keep their numbers exact, and never stretch what they say.\n6. Never make the wearer serve you. Never ask them to clarify or confirm what was said. Never mention the transcript, audio, hearing, or speakers.\n   A question is allowed only as the decision the room must settle, phrased as advice.\n7. Speech-to-text is noisy. Never build a cue on a word that looks misheard. When someone corrects themselves, the last version wins.\n   Do not reopen something the room already settled.\n8. Name a person only if the window or memory names them. Plain text: no markdown, no em dashes. Output null for small talk, noise, entertainment, or repeats.\nSchema: {\"cue\":\"<=200 chars\",\"kind\":\"reinforce|challenge\",\"memoryIds\":[\"M1\"],\"specific\":\"the specific fact used, copied\"} or the literal null.\nOutput one line of minified JSON only."
+
+/** Writer v3: v2 plus the volunteered-owner and attribution rules, measured on the held-out windows after the fact (development data). */
+export const CUE_WRITER_SYSTEM_V3 = "You write one live cue for the wearer of smart glasses during a conversation. You work for the wearer.\nWrite ONE cue the wearer can act on in the next minute.\n1. One or two sentences, at most 200 characters, built around one specific taken from the window or memory: a number, name, date, or concrete next step.\n2. Every name, number, date, owner and target in the cue must appear in the window or memory. Never invent a deadline, owner, number, cap or test date.\n   If one is missing, say that it is missing instead of choosing one. It is missing only when nobody took it on: if anyone said they will do it (I'll fix it, we'll send it), it is not missing and you must not claim it is.\n   Do not say who promised or said something unless that window line names them; write the room or you two. Keep numbers exactly as spoken; never round, sum or compare numbers the window did not.\n3. Two kinds. reinforce: they are on track; name the evidence and the next step. challenge: the flaw, the missing piece, or the contradiction.\n   Check previousCues: do not only criticize, and never repeat a previous cue. No empty praise.\n4. Add something the room has not said: the missing owner, deadline or criterion, a risk, a contradiction, or a past decision from memory.\n   If the cue would only restate what was just said, output null.\n5. Use a memory note only when it is about the same client, project, brand or person as the window. Otherwise ignore memory completely.\n   Memory notes are past claims written at a point in time, not facts. Cite the date, keep their numbers exact, and never stretch what they say.\n6. Never make the wearer serve you. Never ask them to clarify or confirm what was said. Never mention the transcript, audio, hearing, or speakers.\n   A question is allowed only as the decision the room must settle, phrased as advice.\n7. Speech-to-text is noisy. Never build a cue on a word that looks misheard. When someone corrects themselves, the last version wins.\n   Do not reopen something the room already settled.\n8. Name a person only if the window or memory names them. Plain text: no markdown, no em dashes. Output null for small talk, noise, entertainment, or repeats.\nSchema: {\"cue\":\"<=200 chars\",\"kind\":\"reinforce|challenge\",\"memoryIds\":[\"M1\"],\"specific\":\"the specific fact used, copied\"} or the literal null.\nOutput one line of minified JSON only."
+

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

@@ -0,0 +1,639 @@
+// Live cues v2 (MVP, default off): Jev gate -> rank-fusion memory -> Jev relevance judge -> ONE tools-off Claude writer.
+//
+// Evidence and thresholds: docs/PLAN-live-cues-v2-mvp.md. Every recurring model caller must answer how it stops; here:
+// the master switch COS_LIVE_CUES_V2=1 (default off; independent of the v1 COS_LIVE_CUES flag, so turning v2 off can never
+// re-enable the v1 Composer path), a per-meeting cap (10 cues, 20 writer calls; persisted, so a restart does not reset
+// it), a weekly writer ceiling checked BEFORE the gate and charged before the call, never refunded (local week in the zone
+// stored at first use), the Jev client's own daily token cap and breaker, a 3-failure breaker per meeting (cancel, pause,
+// end, stale and maintenance are NOT failures), single flight per meeting, a 20 s cadence floor, a 45 s cooldown after a
+// cue, a 45 s wall per evaluation, and no evaluation while a user's own query runs. Each evaluation writes one trace row
+// without transcript text; a skip (paused, breaker, meeting cap, weekly budget, busy) writes one `skip` row per reason
+// per meeting at most every 5 minutes, so the trace can tell those apart from silence.
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { dirname, resolve } from 'node:path'
+import { emitDisplay, onDisplay } from './display-bus.js'
+import { acquireMaintenanceWork, MaintenanceLifecycleError, maintenanceLifecycle, type MaintenanceWorkLease } from './maintenance-lifecycle.js'
+import { JevClient, JevError, estimateJevTokens, resolveJevKey, type JevAnswers } from './jev.js'
+import { LensGistLimitError, runLensGistEngine } from './lens-gist-engines.js'
+import { resolveProviderBinary } from './provider-binary.js'
+import { COS_SCRIPTS_DIR, PYTHON_BIN } from './python-bridge.js'
+import { dataPath } from './data-dir.js'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import { CUE_GATE_QUESTIONS, CUE_JUDGE_INSTRUCTIONS, CUE_JUDGE_NONE, CUE_WRITER_SYSTEM_V2, CUE_WRITER_SYSTEM_V3 } from './live-cues-v2-prompts.js'
+import {
+  CUE_DETAIL_MAX, CUE_FEEDBACK_REASON_MAX, CUE_HEADLINE_MAX, LIVE_CUES_V2_PROTOCOL, isLiveCueV2,
+  type CueKind, type CueSourceRef, type LiveCueV1Compat, type LiveCueV2, type LiveCuesV2Capability,
+  type LiveCuesV2SessionStatus, type LiveCuesV2StatusResponse, type LiveCuesV2StopReason,
+} from '../../shared/live-cues-v2.js'
+
+// ── Limits ──────────────────────────────────────────────────────────────────
+export const LIVE_CUES_V2_LIMITS = {
+  minNewWords: 40,
+  minIntervalMs: 20_000,
+  cooldownAfterCueMs: 45_000,
+  /** A cue is stale when the room moved on while it was being written: more than ~24 s of speech at ~2.5 words/s,
+   *  or more than 30 s of wall time (the pipeline's worst case is ~28 s: 20 s writer, 6 s memory, two Jev calls). */
+  staleWords: 60,
+  staleMs: 30_000,
+  windowWords: 400,
+  windowChars: 2_200,
+  maxCuesPerMeeting: 10,
+  maxWriterCallsPerMeeting: 20,
+  defaultWeeklyWriterCalls: 300,
+  breakerFailures: 3,
+  judgeKeep: 0.8,
+  judgeMaxNotes: 2,
+  defaultGate: 0.8,
+  memoryTimeoutMs: 6_000,
+  /** Hard wall for one evaluation, far under Control's 90 s drain (a held live_cue_pipeline lease past it fails Update). */
+  pipelineWallMs: 45_000,
+  /** A skip reason is traced at most once per meeting per window of this length. */
+  skipTraceEveryMs: 5 * 60_000,
+  writerTimeoutMs: 20_000,
+  writerMaxOutputTokens: 600,
+  sessionTtlMs: 4 * 60 * 60_000,
+  tombstoneTtlMs: 7 * 24 * 60 * 60_000,
+  counterTtlMs: 24 * 60 * 60_000,
+  /** ~1.2k gate tokens per evaluation, at most 3 a minute: ~216k an hour, so 1.5M covers ~7 meeting hours (~$0.06). */
+  defaultJevDailyTokens: 1_500_000,
+} as const
+
+export function liveCuesV2Enabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_LIVE_CUES_V2 === '1'
+}
+export function liveCuesV2Gate(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env.COS_LIVE_CUES_V2_GATE)
+  return Number.isFinite(raw) && raw >= 0.3 && raw <= 0.99 ? raw : LIVE_CUES_V2_LIMITS.defaultGate
+}
+export function liveCuesV2Model(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = (env.COS_LIVE_CUES_V2_MODEL ?? '').trim().toLowerCase()
+  if (raw === 'haiku') return 'claude-haiku-5-5'
+  if (raw === 'sonnet' || raw === '') return 'claude-sonnet-5-5'
+  return /^claude-[a-z0-9.-]{3,40}$/.test(raw) ? raw : 'claude-sonnet-5-5'
+}
+export function liveCuesV2WriterSystem(env: NodeJS.ProcessEnv = process.env): { version: 'v2' | 'v3'; system: string } {
+  return (env.COS_LIVE_CUES_V2_PROMPT ?? '').trim() === 'v2' ? { version: 'v2', system: CUE_WRITER_SYSTEM_V2 } : { version: 'v3', system: CUE_WRITER_SYSTEM_V3 }
+}
+export function liveCuesV2WeeklyCap(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env.COS_LIVE_CUES_V2_WEEKLY)
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : LIVE_CUES_V2_LIMITS.defaultWeeklyWriterCalls
+}
+function jevDailyCap(): number {
+  const raw = Number(process.env.COS_LIVE_CUES_JEV_DAILY_TOKENS)
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : LIVE_CUES_V2_LIMITS.defaultJevDailyTokens
+}
+
+// ── Python-style JSON (the replay built every prompt with json.dumps; keep byte parity) ──
+export function pyJson(value: unknown): string {
+  if (value === null || value === undefined) return 'null'
+  if (typeof value === 'string') return JSON.stringify(value).replace(/[\u007f-￿]/g, ch => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'))
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null'
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (Array.isArray(value)) return '[' + value.map(pyJson).join(', ') + ']'
+  return '{' + Object.entries(value as Record<string, unknown>).filter(([, v]) => v !== undefined).map(([k, v]) => `${pyJson(k)}: ${pyJson(v)}`).join(', ') + '}'
+}
+
+// ── Pure helpers (exported for tests) ───────────────────────────────────────
+/** A note as the writer sees it ({id, date, title, notes}; the same keys the replay sent). `key` is the stable meeting
+ *  identity from cue_memory.py; it never reaches the prompt. */
+export interface MemoryNote { id: string; date: string; title: string; notes: string; key?: string }
+
+/** A cue's headline: the first sentence when it fits, otherwise cut at a word with an ellipsis. Never empty. */
+export function cueHeadline(detail: string): string {
+  const clean = detail.replace(/\s+/g, ' ').trim()
+  const first = (clean.split(/(?<=[.!?])\s/)[0] ?? '').replace(/[.]$/, '').trim()
+  if (first && first.length <= CUE_HEADLINE_MAX) return first
+  const cut = clean.slice(0, CUE_HEADLINE_MAX - 1)
+  const space = cut.lastIndexOf(' ')
+  const head = (space > 30 ? cut.slice(0, space) : cut).replace(/[,;:.\s]+$/, '')
+  return head ? head + '…' : clean.slice(0, CUE_HEADLINE_MAX)
+}
+
+const NUMBER = /\$?\d[\d,]*(?:\.\d+)?%?k?/gi
+/** Every multi-digit number (or any dollar amount) in the cue must appear in the window or the memory notes, dates included.
+ *  A substring check: it catches invented figures and dates, not a number that happens to sit inside a longer one. */
+export function unsupportedNumbers(cue: string, window: string, memory: MemoryNote[]): string[] {
+  const hay = (window + ' ' + memory.map(m => `${m.notes} ${m.date}`).join(' ')).toLowerCase().replace(/[$,%]/g, '')
+  const bad: string[] = []
+  for (const n of cue.match(NUMBER) ?? []) {
+    const digits = n.toLowerCase().replace(/[$,%]/g, '').replace(/k$/, '')
+    if (digits.length < 2 && !n.startsWith('$')) continue
+    if (digits && !hay.includes(digits)) bad.push(n)
+  }
+  return bad
+}
+
+export interface ParsedCue { detail: string; kind: CueKind; memoryIds: string[]; numberFlags: string[] }
+export type CueRejection = 'null' | 'unparseable' | 'empty' | 'too_long' | 'unsupported_number'
+/** `enforceNumbers` withholds a cue whose numbers are not in the source. Off by default: on the held-out replay the
+ *  guard fired on 3 v3 cues and only 1 was unsupported (ASR writes "300 000" and "a hundred"), so it is traced, not enforced. */
+export function parseWriterCue(raw: string, fallbackKind: CueKind, window: string, kept: MemoryNote[], enforceNumbers = false): ParsedCue | CueRejection {
+  const text = raw.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim()
+  if (!text || text === 'null') return 'null'
+  const start = text.indexOf('{'), end = text.lastIndexOf('}')
+  if (start < 0 || end < start) return 'unparseable'
+  let value: Record<string, unknown>
+  try { value = JSON.parse(text.slice(start, end + 1)) as Record<string, unknown> } catch { return 'unparseable' }
+  const cue = typeof value.cue === 'string' ? value.cue.replace(/[—–]/g, '-').replace(/\s+/g, ' ').trim() : ''
+  if (!cue) return 'empty'
+  if (cue.length > CUE_DETAIL_MAX) return 'too_long'
+  const numberFlags = unsupportedNumbers(cue, window, kept)
+  if (enforceNumbers && numberFlags.length) return 'unsupported_number'
+  const kind: CueKind = value.kind === 'reinforce' || value.kind === 'challenge' ? value.kind : fallbackKind
+  const ids = new Set(kept.map(m => m.id))
+  const memoryIds = Array.isArray(value.memoryIds) ? [...new Set(value.memoryIds.filter((x): x is string => typeof x === 'string' && ids.has(x)))] : []
+  return { detail: cue, kind, memoryIds, numberFlags }
+}
+
+/** A stable, opaque id for a past meeting (the same meeting gets the same id in every cue). */
+export function sourceId(note: MemoryNote): string {
+  return 'mtg_' + createHash('sha256').update(note.key || `${note.date}|${note.title}`).digest('hex').slice(0, 12)
+}
+
+/** Local Monday (YYYY-MM-DD) in `zone`. Intl, never toISOString: a UTC key flips the week at 19:00 Central. */
+export function localWeekStart(now: Date, zone: string): string {
+  const parts = new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit', weekday: 'short' }).formatToParts(now)
+  const get = (t: string) => parts.find(p => p.type === t)?.value ?? ''
+  const dow = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].indexOf(get('weekday'))
+  const local = new Date(Date.UTC(Number(get('year')), Number(get('month')) - 1, Number(get('day'))))
+  local.setUTCDate(local.getUTCDate() - Math.max(0, dow))
+  return local.toISOString().slice(0, 10)
+}
+
+// ── Durable state: weekly ceiling, tombstones, pauses, per-meeting counters ─────
+interface MeetingCounters { cues: number; writerCalls: number; at: number }
+interface DurableState {
+  zone: string; weekStart: string; writerCalls: number
+  ended: Record<string, number>; paused: Record<string, boolean>; pauseSeq: Record<string, number>
+  meetings: Record<string, MeetingCounters>
+}
+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 }
+}
+export class LiveCuesV2Store {
+  constructor(private readonly file: string, private readonly now: () => Date) {}
+  read(): DurableState {
+    const nowMs = this.now().getTime()
+    try {
+      let raw: unknown = {}
+      if (existsSync(this.file)) raw = JSON.parse(readFileSync(this.file, 'utf8'))
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('not an object')
+      const s = raw as Partial<DurableState>
+      const zone = validZone(s.zone) ?? (s.zone === undefined ? (validZone(Intl.DateTimeFormat().resolvedOptions().timeZone) ?? 'UTC') : null)
+      if (!zone) throw new Error('invalid zone')
+      const week = localWeekStart(this.now(), zone)
+      const keep = <T>(m: unknown, ok: (v: T) => boolean): Record<string, T> =>
+        Object.fromEntries(Object.entries(m && typeof m === 'object' ? m as Record<string, T> : {}).filter(([, v]) => ok(v)))
+      const ended = keep<number>(s.ended, at => typeof at === 'number' && at >= nowMs - LIVE_CUES_V2_LIMITS.tombstoneTtlMs)
+      const meetings = keep<MeetingCounters>(s.meetings, c => !!c && typeof c.at === 'number' && c.at >= nowMs - LIVE_CUES_V2_LIMITS.counterTtlMs)
+      const live = (id: string) => id in meetings || !(id in ended)
+      const paused = keep<boolean>(s.paused, v => v === true)
+      const pauseSeq = keep<number>(s.pauseSeq, v => typeof v === 'number' && Number.isFinite(v))
+      for (const id of Object.keys(paused)) if (!live(id) && !(id in meetings)) delete paused[id]
+      const sameWeek = s.weekStart === week
+      const futureWeek = typeof s.weekStart === 'string' && s.weekStart > week
+      const calls = Number(s.writerCalls ?? 0)
+      // A future week key or a negative/non-numeric count fails toward NOT spending: the week is saturated.
+      const saturated = futureWeek || (sameWeek && !(calls >= 0))
+      return { zone, weekStart: week, writerCalls: saturated ? Number.MAX_SAFE_INTEGER : sameWeek ? calls : 0, ended, paused, pauseSeq, meetings }
+    } catch {
+      // An unreadable file fails closed for this week (no spending) but keeps cues off nothing else.
+      const zone = validZone(Intl.DateTimeFormat().resolvedOptions().timeZone) ?? 'UTC'
+      return { zone, weekStart: localWeekStart(this.now(), zone), writerCalls: Number.MAX_SAFE_INTEGER, ended: {}, paused: {}, pauseSeq: {}, meetings: {} }
+    }
+  }
+  private write(s: DurableState): void {
+    mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
+    durableAtomicWriteFileSync(this.file, JSON.stringify(s) + '\n', { mode: 0o600 })
+  }
+  /** Charge one writer call BEFORE the call. Never refunded. False when the week is spent. */
+  charge(cap: number, sessionId: string): boolean {
+    const s = this.read()
+    if (s.writerCalls >= cap) return false
+    s.writerCalls += 1
+    const m = s.meetings[sessionId] ?? { cues: 0, writerCalls: 0, at: 0 }
+    s.meetings[sessionId] = { ...m, writerCalls: m.writerCalls + 1, at: this.now().getTime() }
+    this.write(s)
+    return true
+  }
+  recordCue(sessionId: string): void {
+    const s = this.read()
+    const m = s.meetings[sessionId] ?? { cues: 0, writerCalls: 0, at: 0 }
+    s.meetings[sessionId] = { ...m, cues: m.cues + 1, at: this.now().getTime() }
+    this.write(s)
+  }
+  counters(sessionId: string): { cues: number; writerCalls: number } {
+    const m = this.read().meetings[sessionId]
+    return { cues: m?.cues ?? 0, writerCalls: m?.writerCalls ?? 0 }
+  }
+  weeklyUsed(): number { return this.read().writerCalls }
+  end(sessionId: string): void { const s = this.read(); s.ended[sessionId] = this.now().getTime(); delete s.paused[sessionId]; this.write(s) }
+  isEnded(sessionId: string): boolean { return sessionId in this.read().ended }
+  /** Applies only when `seq` is absent or newer than the last applied one. */
+  setPaused(sessionId: string, paused: boolean, seq?: number): { applied: boolean; paused: boolean; pauseSeq: number } {
+    const s = this.read()
+    const last = s.pauseSeq[sessionId] ?? 0
+    if (seq !== undefined && seq <= last) return { applied: false, paused: s.paused[sessionId] === true, pauseSeq: last }
+    if (paused) s.paused[sessionId] = true; else delete s.paused[sessionId]
+    if (seq !== undefined) s.pauseSeq[sessionId] = seq
+    this.write(s)
+    return { applied: true, paused, pauseSeq: seq ?? last }
+  }
+  isPaused(sessionId: string): boolean { return this.read().paused[sessionId] === true }
+  pauseSeq(sessionId: string): number { return this.read().pauseSeq[sessionId] ?? 0 }
+}
+
+// ── Dependencies (real by default, faked in tests) ──────────────────────────
+export interface GateResult { pCue: number; kind: CueKind; lookup: Record<string, number> | null; tokens: number }
+export interface MemoryResult { notes: MemoryNote[]; denseError?: string; indexAgeH?: number }
+export interface LiveCuesV2Deps {
+  gate(title: string, window: string, signal: AbortSignal): Promise<GateResult>
+  memory(window: string, before: string, signal: AbortSignal): Promise<MemoryResult>
+  judge(title: string, window: string, notes: MemoryNote[], signal: AbortSignal): Promise<{ probs: Record<string, number>; tokens: number }>
+  writer(model: string, system: string, prompt: string, signal: AbortSignal): Promise<{ text: string; costUsd?: number; inputTokens?: number; outputTokens?: number; model?: string }>
+  emit(type: 'coaching_nudge' | 'coaching_nudge_v2', data: Record<string, unknown>): void
+  lease(): MaintenanceWorkLease | null
+  /** True while the user's own query runs (Ask, a durable query): cues wait rather than compete for the provider. */
+  busy(): boolean
+  /** The cue Jev client's own state, for an honest capability. */
+  jevState(): { breakerOpen: boolean; capReached: boolean }
+  warmMemory(): void
+  now(): Date
+  store: LiveCuesV2Store
+  trace(row: Record<string, unknown>): void
+  env: NodeJS.ProcessEnv
+}
+
+function cleanWindow(text: string): string {
+  return text.replace(/^\[\d+\]\s*/gm, '').replace(/\*\*?Speaker \d+:?\*\*?:?|Speaker \d+:/g, '')
+}
+
+function realDeps(): LiveCuesV2Deps {
+  const jev = new JevClient(fetch, () => new Date(), dataPath('jev-cues-usage.json'), jevDailyCap)
+  const traceFile = dataPath('live-cues-trace.jsonl')
+  return {
+    async gate(title, window, signal) {
+      const state = { meetingTitle: title, window: window.slice(-LIVE_CUES_V2_LIMITS.windowChars) }
+      const res: JevAnswers = await jev.ask(state, CUE_GATE_QUESTIONS as unknown as Record<string, unknown>, estimateJevTokens({ state, CUE_GATE_QUESTIONS }), { signal })
+      const a = res.answers ?? {}
+      const kind = a.kind?.choice === 'reinforce' ? 'reinforce' : 'challenge'
+      return { pCue: Number(a.act?.probabilities?.cue ?? 0), kind, lookup: a.lookup?.probabilities ?? null, tokens: res.inputTokens }
+    },
+    memory: (window, before, signal) => cueMemory(window, before, signal),
+    async judge(title, window, notes, signal) {
+      const criteria: Record<string, string> = Object.fromEntries(notes.map(m => [m.id, `${m.date} ${m.title}: ${m.notes.slice(0, 300)}`]))
+      criteria.none = CUE_JUDGE_NONE
+      const state = { meetingTitle: title, window: window.slice(-LIVE_CUES_V2_LIMITS.windowChars) }
+      const questions = { same: { type: 'choice', instructions: CUE_JUDGE_INSTRUCTIONS, criteria } }
+      const res = await jev.ask(state, questions, estimateJevTokens({ state, questions }), { signal })
+      return { probs: res.answers?.same?.probabilities ?? {}, tokens: res.inputTokens }
+    },
+    async writer(model, system, prompt, signal) {
+      const run = await runLensGistEngine('claude', model, prompt, { system, timeoutMs: LIVE_CUES_V2_LIMITS.writerTimeoutMs, source: 'live-cues-v2', maxOutputTokens: LIVE_CUES_V2_LIMITS.writerMaxOutputTokens, signal })
+      return { text: run.text, costUsd: run.usage?.costUsd, inputTokens: run.usage?.inputTokens, outputTokens: run.usage?.outputTokens, model: run.model }
+    },
+    emit: (type, data) => emitDisplay({ type, data }),
+    lease: () => acquireMaintenanceWork('live_cue_pipeline'),
+    busy() {
+      const active = maintenanceLifecycle.snapshot().activeByKind as Record<string, number>
+      return ['durable_query', 'legacy_query', 'openai_query', 'meeting_ask'].some(kind => (active[kind] ?? 0) > 0)
+    },
+    jevState() {
+      const st = jev.status()
+      return { breakerOpen: !!st.breakerOpenUntil, capReached: st.usedToday >= st.dailyCap }
+    },
+    warmMemory: () => warmCueMemory(),
+    now: () => new Date(),
+    store: new LiveCuesV2Store(dataPath('live-cues-v2-state.json'), () => new Date()),
+    trace(row) {
+      try { mkdirSync(dirname(traceFile), { recursive: true, mode: 0o700 }); appendFileSync(traceFile, JSON.stringify(row) + '\n', { mode: 0o600 }) } catch { /* trace is best effort */ }
+    },
+    env: process.env,
+  }
+}
+
+export interface CueMemoryPaths { python: string; script: string; cwd: string }
+function cueMemoryPaths(): CueMemoryPaths | null {
+  const python = PYTHON_BIN, scriptsDir = COS_SCRIPTS_DIR
+  if (!python || !scriptsDir) return null
+  const script = resolve(scriptsDir, 'cue_memory.py')
+  return existsSync(script) && existsSync(python) ? { python, script, cwd: scriptsDir } : null
+}
+
+/** Starts a background index refresh when the cache is stale (non-blocking; the script locks and skips if fresh). */
+export function warmCueMemory(): void {
+  const p = cueMemoryPaths()
+  if (!p) return
+  try {
+    const proc = spawn(p.python, [p.script, '--warm'], { cwd: p.cwd, detached: true, stdio: 'ignore' })
+    proc.on('error', () => { /* warm is best effort */ })
+    proc.unref()
+  } catch { /* warm is best effort */ }
+}
+
+/** Rank-fusion retrieval through COS scripts/cue_memory.py. Transcript text goes over stdin, never argv. Non-fatal. */
+export function cueMemory(window: string, before: string, signal: AbortSignal, p: CueMemoryPaths | null = cueMemoryPaths(), timeoutMs: number = LIVE_CUES_V2_LIMITS.memoryTimeoutMs): Promise<MemoryResult> {
+  if (!p) return Promise.resolve({ notes: [], denseError: 'no_cue_memory_script' })
+  const paths = p
+  return new Promise(resolveNotes => {
+    let proc: ChildProcess, out = '', settled = false
+    const done = (r: MemoryResult) => { if (settled) return; settled = true; clearTimeout(timer); signal.removeEventListener('abort', onAbort); resolveNotes(r) }
+    const kill = () => { if (proc) void terminateProviderProcess(proc).catch(() => {}) }
+    const onAbort = () => { kill(); done({ notes: [] }) }
+    const timer = setTimeout(() => { kill(); done({ notes: [], denseError: 'memory_timeout' }) }, timeoutMs)
+    try {
+      proc = spawn(paths.python, [paths.script, '--stdin'], { cwd: paths.cwd, detached: true, stdio: ['pipe', 'pipe', 'ignore'] })
+    } catch { done({ notes: [], denseError: 'spawn_failed' }); return }
+    signal.addEventListener('abort', onAbort, { once: true })
+    proc.stdout?.on('data', b => { out += String(b); if (out.length > 200_000) { kill(); done({ notes: [], denseError: 'output_limit' }) } })
+    proc.on('error', () => done({ notes: [], denseError: 'spawn_failed' }))
+    proc.on('close', () => {
+      try {
+        const res = JSON.parse(out) as { notes?: MemoryNote[]; timing?: { dense_error?: string }; index?: { ageHours?: number } }
+        const notes = (res.notes ?? []).filter(n => n && typeof n.id === 'string' && typeof n.notes === 'string').slice(0, 4)
+        done({ notes, denseError: res.timing?.dense_error, indexAgeH: res.index?.ageHours })
+      } catch { done({ notes: [], denseError: 'bad_output' }) }
+    })
+    proc.stdin?.on('error', () => { /* child exited early */ })
+    proc.stdin?.end(JSON.stringify({ queries: [window.slice(-600)], keywordText: window, before, top: 4 }))
+  })
+}
+
+// ── Engine ──────────────────────────────────────────────────────────────────
+interface Session {
+  sessionId: string
+  title: string
+  armedAt: number
+  lastSeenAt: number
+  chunks: string[]
+  wordsSinceEval: number
+  lastEvalAt: number
+  lastCueAt: number
+  inFlight: AbortController | null
+  cues: LiveCueV2[]
+  evaluations: number
+  failures: number
+  breaker: boolean
+  /** The last reason cues were not produced, cleared by the next evaluation that runs the writer. */
+  stopReason: LiveCuesV2StopReason | null
+  skipTracedAt: Record<string, number>
+}
+
+export class LiveCuesV2ArmError extends Error {
+  constructor(readonly code: string, readonly status: number, message: string) { super(message); this.name = 'LiveCuesV2ArmError' }
+}
+
+function isCancel(error: unknown, signal: AbortSignal): boolean {
+  return signal.aborted || (error instanceof Error && error.name === 'AbortError')
+}
+
+export class LiveCuesV2Engine {
+  private readonly sessions = new Map<string, Session>()
+  constructor(private readonly deps: LiveCuesV2Deps) {}
+
+  capability(): LiveCuesV2Capability {
+    const model = liveCuesV2Model(this.deps.env)
+    const off = (reason: string): LiveCuesV2Capability => ({ available: false, reason, protocol: LIVE_CUES_V2_PROTOCOL, model })
+    try {
+      if (!liveCuesV2Enabled(this.deps.env)) return off('master_flag_off')
+      if (this.deps.env.ANTHROPIC_API_KEY && this.deps.env.COS_ALLOW_API_FALLBACK !== '1') return off('api_key_in_env')
+      if (!resolveJevKey()) return off('jev_not_configured')
+      if (!resolveProviderBinary('claude').ok) return off('claude_not_found')
+      if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return off('budget_exhausted')
+      const jev = this.deps.jevState()
+      if (jev.capReached) return off('jev_cap_reached')
+      if (jev.breakerOpen) return off('jev_breaker_open')
+      return { available: true, protocol: LIVE_CUES_V2_PROTOCOL, model }
+    } catch {
+      return off('unavailable')
+    }
+  }
+
+  /** Idempotent. A repeat start for an armed meeting keeps its counters; an ended meeting cannot be re-armed. */
+  arm(sessionId: string): { armed: true; sessionId: string; protocol: 2; cuesGenerated: number; paused: boolean; pauseSeq: number } {
+    this.reap()
+    const cap = this.capability()
+    if (!cap.available) throw new LiveCuesV2ArmError(cap.reason ?? 'unavailable', cap.reason === 'master_flag_off' ? 403 : 503, `Live cues v2 unavailable: ${cap.reason}.`)
+    if (this.deps.store.isEnded(sessionId)) throw new LiveCuesV2ArmError('meeting_ended', 409, 'This meeting has ended; live cues cannot be re-armed for it.')
+    const existing = this.sessions.get(sessionId)
+    const nowMs = this.deps.now().getTime()
+    const answer = (cues: number) => ({ armed: true as const, sessionId, protocol: 2 as const, cuesGenerated: cues, paused: this.deps.store.isPaused(sessionId), pauseSeq: this.deps.store.pauseSeq(sessionId) })
+    if (existing) { existing.lastSeenAt = nowMs; return answer(existing.cues.length) }
+    const d = this.deps.now()
+    const title = `G2 Recording ${d.toLocaleDateString('en-CA')} ${String(d.getHours()).padStart(2, '0')}${String(d.getMinutes()).padStart(2, '0')}`
+    this.sessions.set(sessionId, { sessionId, title, armedAt: nowMs, lastSeenAt: nowMs, chunks: [], wordsSinceEval: 0, lastEvalAt: 0, lastCueAt: 0,
+      inFlight: null, cues: [], evaluations: 0, failures: 0, breaker: false, stopReason: null, skipTracedAt: {} })
+    this.deps.warmMemory()
+    return answer(this.deps.store.counters(sessionId).cues)
+  }
+
+  /** Stop or save: tombstone FIRST (so trailing chunks cannot revive it), then abort any evaluation in flight. */
+  end(sessionId: string): { nudgesGenerated: number; nudges: Array<Record<string, unknown>>; protocol: 2; cues: LiveCueV2[] } {
+    this.deps.store.end(sessionId)
+    const s = this.sessions.get(sessionId)
+    s?.inFlight?.abort()
+    const cues = s ? [...s.cues] : []
+    return { nudgesGenerated: cues.length, protocol: 2, cues,
+      nudges: cues.map(c => ({ nudge: c.headline, type: c.kind, priority: 2, timestamp: c.createdAt, cueId: c.cueId })) }
+  }
+
+  setPaused(sessionId: string, paused: boolean, seq?: number): { ok: true; paused: boolean; applied: boolean; pauseSeq: number } {
+    const r = this.deps.store.setPaused(sessionId, paused, seq)
+    if (r.applied && paused) this.sessions.get(sessionId)?.inFlight?.abort()
+    return { ok: true, ...r }
+  }
+
+  status(sessionId: string): LiveCuesV2StatusResponse {
+    const s = this.sessions.get(sessionId)
+    const ended = this.deps.store.isEnded(sessionId)
+    const paused = this.deps.store.isPaused(sessionId)
+    if (!s && !ended) return { protocol: 2, enabled: liveCuesV2Enabled(this.deps.env), session: null }
+    const counters = this.deps.store.counters(sessionId)
+    const reason = s ? this.stopReasonOf(s, counters) : null
+    const session: LiveCuesV2SessionStatus = {
+      sessionId, state: ended ? 'ended' : paused ? 'paused' : reason ? 'stopped' : 'active', ...(reason && !ended && !paused ? { reason } : {}),
+      paused, ended, pauseSeq: this.deps.store.pauseSeq(sessionId), cues: s ? [...s.cues] : [], evaluations: s?.evaluations ?? 0, writerCalls: counters.writerCalls,
+    }
+    return { protocol: 2, enabled: liveCuesV2Enabled(this.deps.env), session }
+  }
+
+  private stopReasonOf(s: Session, counters: { cues: number; writerCalls: number }): LiveCuesV2StopReason | null {
+    const L = LIVE_CUES_V2_LIMITS
+    if (s.breaker) return 'breaker_open'
+    if (counters.cues >= L.maxCuesPerMeeting || counters.writerCalls >= L.maxWriterCallsPerMeeting) return 'meeting_cap'
+    if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return 'budget_exhausted'
+    return s.stopReason
+  }
+
+  recordFeedback(input: { sessionId: string; cueId: string; vote: 'up' | 'down'; reason?: string }): { ok: true; knownCue: boolean } {
+    const knownCue = !!this.sessions.get(input.sessionId)?.cues.some(c => c.cueId === input.cueId)
+    const reason = (input.reason ?? '').replace(/\s+/g, ' ').trim().slice(0, CUE_FEEDBACK_REASON_MAX)
+    this.deps.trace({ kind: 'feedback', at: this.deps.now().toISOString(), sessionId: input.sessionId, cueId: input.cueId, vote: input.vote, knownCue, ...(reason ? { reason } : {}) })
+    return { ok: true, knownCue }
+  }
+
+  /** From the ASR path: fire-and-forget, never awaited. All gates live here. */
+  async feed(sessionId: string, text: string, asrDegraded = false): Promise<void> {
+    if (!liveCuesV2Enabled(this.deps.env)) return
+    if (this.deps.store.isEnded(sessionId)) return                    // tombstone before any auto-arm
+    let s = this.sessions.get(sessionId)
+    if (!s) {
+      if (this.deps.env.COS_LIVE_CUES_AUTO !== '1') return
+      try { this.arm(sessionId) } catch { return }
+      s = this.sessions.get(sessionId)
+      if (!s) return
+    }
+    const nowMs = this.deps.now().getTime()
+    s.lastSeenAt = nowMs
+    const words = text.trim().split(/\s+/).filter(Boolean)
+    if (words.length) {
+      s.chunks.push(text.trim())
+      s.wordsSinceEval += words.length
+      let total = s.chunks.reduce((n, c) => n + c.split(/\s+/).length, 0)
+      while (s.chunks.length > 1 && total > LIVE_CUES_V2_LIMITS.windowWords) { total -= s.chunks[0].split(/\s+/).length; s.chunks.shift() }
+    }
+    const L = LIVE_CUES_V2_LIMITS
+    if (s.inFlight || asrDegraded) return
+    if (s.breaker) return this.traceSkip(s, 'breaker_open', nowMs)
+    if (this.deps.store.isPaused(sessionId)) return this.traceSkip(s, 'paused', nowMs)
+    if (s.wordsSinceEval < L.minNewWords) return
+    if (nowMs - s.lastEvalAt < L.minIntervalMs || nowMs - s.lastCueAt < L.cooldownAfterCueMs) return
+    const counters = this.deps.store.counters(sessionId)
+    if (counters.cues >= L.maxCuesPerMeeting || counters.writerCalls >= L.maxWriterCallsPerMeeting) return this.traceSkip(s, 'meeting_cap', nowMs)
+    if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return this.traceSkip(s, 'budget_exhausted', nowMs)  // before the gate
+    if (this.deps.busy()) return this.traceSkip(s, 'busy', nowMs)
+    await this.evaluate(s)
+  }
+
+  private traceSkip(s: Session, reason: string, nowMs: number): void {
+    if (nowMs - (s.skipTracedAt[reason] ?? 0) < LIVE_CUES_V2_LIMITS.skipTraceEveryMs) return
+    s.skipTracedAt[reason] = nowMs
+    this.deps.trace({ kind: 'skip', at: new Date(nowMs).toISOString(), sessionId: s.sessionId, reason })
+  }
+
+  private async evaluate(s: Session): Promise<void> {
+    const L = LIVE_CUES_V2_LIMITS
+    const started = this.deps.now().getTime()
+    const abort = new AbortController()
+    s.inFlight = abort
+    s.evaluations += 1
+    s.lastEvalAt = started
+    s.wordsSinceEval = 0
+    const window = cleanWindow(s.chunks.join('\n')).slice(-L.windowChars)
+    const trace: Record<string, unknown> = { kind: 'evaluation', at: new Date(started).toISOString(), sessionId: s.sessionId, n: s.evaluations }
+    let lease: MaintenanceWorkLease | null = null
+    let wallHit = false
+    const wall = setTimeout(() => { wallHit = true; abort.abort() }, L.pipelineWallMs)
+    wall.unref?.()
+    try {
+      try { lease = this.deps.lease() } catch (e) { if (e instanceof MaintenanceLifecycleError) { trace.outcome = 'maintenance'; return } throw e }
+      const t0 = Date.now()
+      const gate = await this.deps.gate(s.title, window, abort.signal)
+      const pCue = Number.isFinite(gate.pCue) ? gate.pCue : 0
+      Object.assign(trace, { gateMs: Date.now() - t0, pCue: round(pCue), cueKind: gate.kind, lookup: gate.lookup, gateTokens: gate.tokens })
+      if (pCue < liveCuesV2Gate(this.deps.env)) { trace.outcome = 'gate_silent'; s.stopReason = null; return }
+      if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
+
+      const t1 = Date.now()
+      const before = new Date(started + 86_400_000).toLocaleDateString('en-CA')
+      const mem: MemoryResult = await this.deps.memory(window, before, abort.signal).catch((): MemoryResult => ({ notes: [], denseError: 'memory_threw' }))
+      Object.assign(trace, { memoryMs: Date.now() - t1, candidates: mem.notes.length, ...(mem.denseError ? { memoryError: mem.denseError } : {}), ...(mem.indexAgeH !== undefined ? { indexAgeH: mem.indexAgeH } : {}) })
+      let kept: MemoryNote[] = []
+      if (mem.notes.length && !abort.signal.aborted) {
+        const t2 = Date.now()
+        const judged = await this.deps.judge(s.title, window, mem.notes, abort.signal)
+        Object.assign(trace, { judgeMs: Date.now() - t2, judgeTokens: judged.tokens })
+        kept = mem.notes.filter(m => (judged.probs[m.id] ?? 0) >= L.judgeKeep).slice(0, L.judgeMaxNotes).map((m, i) => ({ ...m, id: `M${i + 1}` }))
+      }
+      trace.kept = kept.length
+      if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
+
+      if (!this.deps.store.charge(liveCuesV2WeeklyCap(this.deps.env), s.sessionId)) { trace.outcome = 'budget_exhausted'; s.stopReason = 'budget_exhausted'; return }
+      const { version, system } = liveCuesV2WriterSystem(this.deps.env)
+      const model = liveCuesV2Model(this.deps.env)
+      const previous = s.cues.slice(-3).map(c => c.detail)
+      const promptMemory = kept.map(m => ({ id: m.id, date: m.date, title: m.title, notes: m.notes }))  // the replay's exact keys
+      const prompt = pyJson({ meetingTitle: s.title, liveIssue: '', suggestedKind: gate.kind, previousCues: previous, memory: promptMemory, window })
+      const t3 = Date.now()
+      const out = await this.deps.writer(model, system, prompt, abort.signal)
+      Object.assign(trace, { writerMs: Date.now() - t3, prompt: version, model: out.model ?? model, writerUsd: out.costUsd, writerIn: out.inputTokens, writerOut: out.outputTokens })
+      if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
+      s.failures = 0
+      s.stopReason = null
+
+      const parsed = parseWriterCue(out.text, gate.kind, window, kept, this.deps.env.COS_LIVE_CUES_V2_NUMBER_GUARD === 'withhold')
+      if (typeof parsed === 'string') { trace.outcome = parsed === 'null' ? 'writer_null' : `withheld_${parsed}`; return }
+      const elapsed = this.deps.now().getTime() - started
+      if (s.wordsSinceEval > L.staleWords || elapsed > L.staleMs) { trace.outcome = 'stale'; return }
+      if (this.deps.store.isEnded(s.sessionId) || this.deps.store.isPaused(s.sessionId)) { trace.outcome = 'cancelled'; return }
+
+      const sources: CueSourceRef[] = parsed.memoryIds.map(id => kept.find(m => m.id === id)).filter((m): m is MemoryNote => !!m)
+        .map(m => ({ id: sourceId(m), date: m.date, title: m.title }))
+      const cue: LiveCueV2 = { protocol: 2, cueId: randomUUID(), sessionId: s.sessionId, headline: cueHeadline(parsed.detail), detail: parsed.detail,
+        kind: parsed.kind, sources, gate: round(pCue), createdAt: this.deps.now().getTime(), model: out.model ?? model }
+      if (!isLiveCueV2(cue)) { trace.outcome = 'withheld_invalid'; return }       // never emit what the companion would drop
+      s.cues.push(cue)
+      s.lastCueAt = cue.createdAt
+      this.deps.store.recordCue(s.sessionId)
+      this.deps.emit('coaching_nudge_v2', cue as unknown as Record<string, unknown>)
+      const v1: LiveCueV1Compat = { nudge: cue.headline, type: cue.kind, priority: 2, cueId: cue.cueId, sessionId: s.sessionId, protocol: 2 }
+      this.deps.emit('coaching_nudge', v1 as unknown as Record<string, unknown>)
+      Object.assign(trace, { outcome: 'cue', cueId: cue.cueId, cueChars: cue.detail.length, sources: sources.length, ...(parsed.numberFlags.length ? { numberFlags: parsed.numberFlags.length } : {}) })
+    } catch (error) {
+      if (wallHit) { trace.outcome = 'failure'; trace.error = 'wall_timeout'; s.failures += 1; if (s.failures >= L.breakerFailures) s.breaker = true; return }
+      if (isCancel(error, abort.signal)) { trace.outcome = 'cancelled'; return }
+      if (error instanceof JevError && ['jev_cap_reached', 'jev_breaker_open', 'jev_not_configured'].includes(error.code)) {
+        trace.outcome = error.code
+        s.stopReason = error.code as LiveCuesV2StopReason
+        return
+      }
+      trace.outcome = 'failure'
+      trace.error = error instanceof JevError ? error.code : error instanceof LensGistLimitError ? 'writer_quota' : 'writer_error'
+      s.failures += 1
+      if (error instanceof LensGistLimitError || s.failures >= L.breakerFailures) s.breaker = true
+    } finally {
+      clearTimeout(wall)
+      if (wallHit && trace.outcome === 'cancelled') { trace.outcome = 'failure'; trace.error = 'wall_timeout'; s.failures += 1; if (s.failures >= L.breakerFailures) s.breaker = true }
+      s.inFlight = null
+      try { lease?.release() } catch { /* released */ }
+      trace.totalMs = this.deps.now().getTime() - started
+      this.deps.trace(trace)
+    }
+  }
+
+  private reap(): void {
+    const nowMs = this.deps.now().getTime()
+    for (const [id, s] of this.sessions) if (!s.inFlight && nowMs - s.lastSeenAt > LIVE_CUES_V2_LIMITS.sessionTtlMs) this.sessions.delete(id)
+  }
+
+  shutdown(): void { for (const s of this.sessions.values()) s.inFlight?.abort(); this.sessions.clear() }
+}
+
+function round(n: number): number { return Math.round(n * 1000) / 1000 }
+
+// ── Singleton wiring ────────────────────────────────────────────────────────
+let engine: LiveCuesV2Engine | null = null
+let unsubscribe: (() => void) | null = null
+export function liveCuesV2(): LiveCuesV2Engine {
+  if (!engine) {
+    engine = new LiveCuesV2Engine(realDeps())
+    // A saved meeting ends its cues even when the phone never sent Stop (orphan recovery, Control save).
+    unsubscribe = onDisplay(event => {
+      const sid = event.type === 'recording_stop' ? event.data?.sessionId : null
+      if (typeof sid === 'string' && sid && liveCuesV2Enabled()) engine?.end(sid)
+    })
+  }
+  return engine
+}
+export function liveCuesV2Capability(): LiveCuesV2Capability { return liveCuesV2().capability() }
+/** What /api/health, /api/models and the status route advertise: NOTHING while v2 is switched off, so a 6.10.642
+ *  companion treats the server exactly like a v1 server (v1 cues keep their own capability and indicator). */
+export function liveCuesV2Advertised(env: NodeJS.ProcessEnv = process.env): LiveCuesV2Capability | undefined {
+  return liveCuesV2Enabled(env) ? liveCuesV2Capability() : undefined
+}
+export function shutdownLiveCuesV2(): void { engine?.shutdown(); unsubscribe?.(); unsubscribe = null; engine = null }

package/server/routes/display.ts

@@ -28,9 +28,9 @@ export const displayRouter = Router()
  * The projection is the contract: whatever the emitter grows later, only the fields
  * named here can ever leave.
  *
- * The other ten members of the union all carry user content: `transcript_chunk` and
+ * The other eleven members of the union all carry user content: `transcript_chunk` and
  * `prompt_transcript` carry meeting speech with speaker labels, `chunk`/`done` carry
- * answer text, `session_restore` carries conversation state, `coaching_nudge` carries
+ * answer text, `session_restore` carries conversation state, `coaching_nudge` and `coaching_nudge_v2` carry
  * derived guidance, `start` carries session metadata, `tool_status` carries a message,
  * `error` carries error text, and `recording_start` is covered by its own note below.
  *

package/server/routes/health.ts

@@ -68,6 +68,7 @@ import { getServerGenerationId } from '../lib/managed-runtime.js'
 import { maintenanceLifecycle } from '../lib/maintenance-lifecycle.js'
 import { getLocalTtsHealth, refreshLocalTtsHealth } from '../lib/tts-local.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
+import { liveCuesV2Advertised } from '../lib/live-cues-v2.js'
 import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
 import { getStrandedCaptures } from './transcribe-stream.js'
@@ -495,6 +496,7 @@ healthRouter.get('/health', async (_req, res) => {
       },
       cliDebug: CLI_DEBUG_CAPABILITY,
       liveCues,
+      ...(liveCuesV2Advertised() ? { liveCuesV2: liveCuesV2Advertised() } : {}),
       richMedia: {
         text: true,
         pdf: richMedia.pdf,
@@ -668,6 +670,7 @@ healthRouter.get('/models', async (req, res) => {
       // THIS surface, so a value present only on /api/health leaves the
       // live-cues indicator blind.
       liveCues: liveCuesCapability(),
+      ...(liveCuesV2Advertised() ? { liveCuesV2: liveCuesV2Advertised() } : {}),
       richMedia: {
         video: richMedia.video,
         maxPromptVisuals: MAX_MODEL_IMAGE_INPUTS,

package/server/routes/live-cues.ts

@@ -14,6 +14,14 @@ import {
   LiveCuesArmError,
 } from '../lib/live-cues-engine.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
+import { LiveCuesV2ArmError, liveCuesV2, liveCuesV2Advertised, liveCuesV2Enabled } from '../lib/live-cues-v2.js'
+
+const SESSION_ID = /^[A-Za-z0-9:_-]{3,96}$/
+const CUE_ID = /^[A-Za-z0-9-]{8,64}$/
+function bodySessionId(body: unknown): string {
+  const raw = (body as { sessionId?: unknown })?.sessionId
+  return typeof raw === 'string' ? raw.trim() : ''
+}
 
 export const liveCuesRouter = Router()
 
@@ -23,13 +31,17 @@ liveCuesRouter.post('/live-cues/start', async (req, res) => {
     : ''
   // A start with no sessionId is refused, never silently armed on a global
   // counter — the per-meeting cap is only real when it is session-scoped.
-  if (!sessionId || !/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) {
+  if (!sessionId || !SESSION_ID.test(sessionId)) {
     return res.status(400).json({ error: 'sessionId required', reason: 'missing_session_id' })
   }
   try {
+    if (liveCuesV2Enabled()) return res.json(liveCuesV2().arm(sessionId))
     const result = await armLiveCues(sessionId)
     return res.json(result)
   } catch (error) {
+    if (error instanceof LiveCuesV2ArmError) {
+      return res.status(error.status).json({ error: error.message, reason: error.code, protocol: 2 })
+    }
     if (error instanceof LiveCuesArmError) {
       return res.status(error.status).json({ error: error.message, reason: error.code })
     }
@@ -41,18 +53,51 @@ liveCuesRouter.post('/live-cues/stop', (req, res) => {
   const sessionId = typeof (req.body as { sessionId?: unknown })?.sessionId === 'string'
     ? String((req.body as { sessionId: string }).sessionId).trim()
     : ''
-  if (!sessionId) {
+  if (!sessionId || (liveCuesV2Enabled() && !SESSION_ID.test(sessionId))) {
     return res.status(400).json({ error: 'sessionId required', reason: 'missing_session_id' })
   }
   // Shape matches the existing client stop handler: it reads nudgesGenerated
   // for its log line and hydrates meetingNudgeHistory from nudges when SSE
   // missed events (the 200-event replay buffer is flooded by transcript_chunk).
+  if (liveCuesV2Enabled()) return res.json(liveCuesV2().end(sessionId))
   return res.json(disarmLiveCues(sessionId))
 })
 
-liveCuesRouter.get('/live-cues/status', (_req, res) => {
+liveCuesRouter.get('/live-cues/status', (req, res) => {
+  const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId.trim() : ''
+  // v2 with a sessionId answers the per-meeting shape; without one the v1 shape is unchanged (plus v2 capability).
+  if (sessionId && liveCuesV2Enabled()) {
+    if (!SESSION_ID.test(sessionId)) return res.status(400).json({ error: 'invalid sessionId', reason: 'invalid_session_id' })
+    return res.json(liveCuesV2().status(sessionId))
+  }
   res.json({
     capability: liveCuesCapability(),
     sessions: getLiveCuesStatus(),
+    ...(liveCuesV2Advertised() ? { v2: liveCuesV2Advertised() } : {}),
   })
 })
+
+// POST /live-cues/pause { sessionId, paused, seq? } -> { ok, paused, applied, pauseSeq }  (v2 only; the phone keeps its own local pause)
+liveCuesRouter.post('/live-cues/pause', (req, res) => {
+  const sessionId = bodySessionId(req.body)
+  const paused = (req.body as { paused?: unknown })?.paused
+  const seq = (req.body as { seq?: unknown })?.seq
+  if (!SESSION_ID.test(sessionId) || typeof paused !== 'boolean' || (seq !== undefined && !(typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0))) {
+    return res.status(400).json({ error: 'sessionId and boolean paused required', reason: 'invalid_request' })
+  }
+  if (!liveCuesV2Enabled()) return res.status(404).json({ error: 'live cues v2 is off', reason: 'v2_disabled' })
+  return res.json(liveCuesV2().setPaused(sessionId, paused, seq as number | undefined))
+})
+
+// POST /live-cues/feedback { sessionId, cueId, vote: 'up'|'down', reason? } -> { ok, knownCue }
+liveCuesRouter.post('/live-cues/feedback', (req, res) => {
+  const body = (req.body ?? {}) as { cueId?: unknown; vote?: unknown; reason?: unknown }
+  const sessionId = bodySessionId(req.body)
+  const cueId = typeof body.cueId === 'string' ? body.cueId.trim() : ''
+  if (!SESSION_ID.test(sessionId) || !CUE_ID.test(cueId) || (body.vote !== 'up' && body.vote !== 'down')
+      || (body.reason !== undefined && typeof body.reason !== 'string')) {
+    return res.status(400).json({ error: 'sessionId, cueId and vote (up|down) required', reason: 'invalid_request' })
+  }
+  if (!liveCuesV2Enabled()) return res.status(404).json({ error: 'live cues v2 is off', reason: 'v2_disabled' })
+  return res.json(liveCuesV2().recordFeedback({ sessionId, cueId, vote: body.vote, reason: body.reason as string | undefined }))
+})

package/server/routes/transcribe-stream.ts

@@ -2443,7 +2443,8 @@ async function processStreamChunk(opts: {
   // block on a cue, and no LLM runs on this path. .catch() is required — a
   // bare `void` on a rejecting promise is an unhandled rejection, which Node
   // throws on by default. All gates live inside the feed.
-  void feedLiveCueTranscript(sessionId, trimmedText, Boolean(fallbackReason)).catch(() => {})
+  // The ASR await above lets a late chunk land after Stop or save; a closed session never feeds cues.
+  if (!isSessionDeleted(sessionId)) void feedLiveCueTranscript(sessionId, trimmedText, Boolean(fallbackReason)).catch(() => {})
 
   console.log(`[perf] TOTAL request: ${(performance.now() - tReq).toFixed(1)}ms | chunk #${chunkIndex} | ${audioBuffer.length}b | rms=${Math.round(rms)} q=${isQuiet ? 1 : 0} gate=${quiet.gate}${quiet.speechSec === null ? '' : ` speech=${quiet.speechSec.toFixed(2)}s`} fe=${stt.frontEnd} | ${asrProvider} | "${trimmedText.slice(0, 50)}"`)
   return canonicalChunkResponse(chunk, sessionId, chunkIndex)

package/shared/live-cues-v2.ts

@@ -0,0 +1,77 @@
+/**
+ * Live cues v2 wire contract (server 6.75 candidate, companion 6.10.641 candidate).
+ * Additive to v1: old clients keep receiving `coaching_nudge` and ignore the new named event.
+ * The companion keeps a byte-identical copy at src/lib/live-cues-v2-contract.ts.
+ */
+export const LIVE_CUES_V2_PROTOCOL = 2 as const
+export const CUE_HEADLINE_MAX = 64
+export const CUE_DETAIL_MAX = 220
+export const CUE_FEEDBACK_REASON_MAX = 200
+
+export type CueKind = 'reinforce' | 'challenge'
+
+/** A past meeting the cue drew on (0 to 2 per cue). */
+export interface CueSourceRef { id: string; date: string; title: string }
+
+/** SSE named event `coaching_nudge_v2` (emitted BEFORE its v1 `coaching_nudge` twin), and the rows of GET /api/live-cues/status?sessionId=. */
+export interface LiveCueV2 {
+  protocol: 2
+  cueId: string
+  sessionId: string
+  /** <= 64 chars: the lens footer line. */
+  headline: string
+  /** <= 220 chars: the full cue, shown on tap and in the phone Cues sheet. */
+  detail: string
+  kind: CueKind
+  sources: CueSourceRef[]
+  /** Admission probability from the gate, 0 to 1. */
+  gate: number
+  createdAt: number
+  model: string
+}
+
+/** v1 `coaching_nudge` as the v2 engine emits it for old clients (headline only). */
+export interface LiveCueV1Compat { nudge: string; type: CueKind; priority: 2; cueId: string; sessionId: string; protocol: 2 }
+
+/** `reason` when unavailable: master_flag_off, api_key_in_env, jev_not_configured, claude_not_found, budget_exhausted,
+ *  jev_cap_reached, jev_breaker_open. */
+export interface LiveCuesV2Capability { available: boolean; reason?: string; protocol: 2; model: string }
+
+/** Why cues are not coming for this meeting. `active` means evaluations are running normally (silence is a choice). */
+export type LiveCuesV2SessionState = 'active' | 'paused' | 'ended' | 'stopped'
+export type LiveCuesV2StopReason = 'breaker_open' | 'meeting_cap' | 'budget_exhausted' | 'jev_cap_reached' | 'jev_breaker_open' | 'jev_not_configured'
+
+export interface LiveCuesV2SessionStatus {
+  sessionId: string
+  state: LiveCuesV2SessionState
+  /** Present when state is `stopped`. */
+  reason?: LiveCuesV2StopReason
+  paused: boolean
+  ended: boolean
+  /** The pause request sequence the server last applied (0 when none). */
+  pauseSeq: number
+  cues: LiveCueV2[]
+  evaluations: number
+  writerCalls: number
+}
+
+/** GET /api/live-cues/status?sessionId=X (v2 server). Without sessionId the v1 array shape is unchanged. */
+export interface LiveCuesV2StatusResponse { protocol: 2; enabled: boolean; session: LiveCuesV2SessionStatus | null }
+
+/** POST /api/live-cues/pause -> { ok, paused, applied, pauseSeq }. `seq` is a per-meeting counter from the phone; the server
+ *  ignores a request whose seq is not newer than the last applied one (applied: false) so out-of-order posts cannot win. */
+export interface LiveCuesPauseRequest { sessionId: string; paused: boolean; seq?: number }
+/** POST /api/live-cues/feedback */
+export interface LiveCuesFeedbackRequest { sessionId: string; cueId: string; vote: 'up' | 'down'; reason?: string }
+
+export function isLiveCueV2(value: unknown): value is LiveCueV2 {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return v.protocol === 2 && typeof v.cueId === 'string' && v.cueId.length > 0 && typeof v.sessionId === 'string'
+    && typeof v.headline === 'string' && v.headline.length > 0 && v.headline.length <= CUE_HEADLINE_MAX
+    && typeof v.detail === 'string' && v.detail.length > 0 && v.detail.length <= CUE_DETAIL_MAX
+    && (v.kind === 'reinforce' || v.kind === 'challenge')
+    && Array.isArray(v.sources) && v.sources.length <= 2
+    && v.sources.every(s => !!s && typeof (s as CueSourceRef).id === 'string' && typeof (s as CueSourceRef).date === 'string' && typeof (s as CueSourceRef).title === 'string')
+    && typeof v.gate === 'number' && typeof v.createdAt === 'number' && typeof v.model === 'string'
+}