@gotcos/glasses-server 6.73.14 → 6.75.0

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/stt-settings.ts

@@ -4,14 +4,20 @@
 //   PUT  /api/stt-settings                    partial body: {"hq":"parakeet-ultra"}, {"resolver":false}, ...
 //   POST /api/stt-settings/parakeet/install   install the pinned Parakeet CLI and models (202; poll GET)
 //        body {} | {"localSource":"/abs/path"} | {"localSource":"...","allowDownload":true}
+//        6.74.0: {"cliPath":"/Applications/COS Control.app/Contents/Helpers/fluidaudiocli","allowDownload":true}
+//        507 insufficient_disk, 422 cli_untrusted. allowDownload:false without localSource never downloads.
 //   DELETE /api/stt-settings/parakeet/install cancel a running install (nothing partial is kept)
+//   POST /api/stt-settings/parakeet/cli       6.74.0: COS Control registers its signed CLI and gets the verdict
 //
 // Clients find the route with GET: a 404 means an older server, so they hide the switcher.
 // The contract is shared with COS Control and the phone (see README "Speech-to-text settings").
 
 import { Router } from 'express'
 import { errMsg } from '../lib/utils.js'
-import { cancelParakeetInstall, installParakeet, parakeetInstalled, parakeetInstallRunning, type InstallOptions } from '../lib/parakeet.js'
+import {
+  cancelParakeetInstall, findPinnedCli, installParakeet, parakeetDiskCheck, parakeetInstalled, parakeetInstallRunning, type InstallOptions,
+} from '../lib/parakeet.js'
+import { isCliPathShape, offerControlCli, trustCli, type CliTrust } from '../lib/parakeet-cli-trust.js'
 import { currentSttCapabilities, ensurePreviewWarm, parakeetStatus } from '../lib/stt-runtime.js'
 import {
   applySettingsPatch, readLastSttJob, readSttSettings, settingsView, SttSettingsError, writeSttSettings,
@@ -23,12 +29,22 @@ export interface SttSettingsRouterDeps {
   capabilities?: () => SttCapabilities
   install?: (options: InstallOptions) => Promise<void>
   onChanged?: () => void
+  /** 6.74.0, tests: the disk precheck and the CLI verdict. */
+  diskCheck?: () => { ok: boolean; freeBytes: number | null; requiredBytes: number }
+  trust?: (path: string) => Promise<CliTrust>
+  pinned?: (path: string) => Promise<boolean>
 }
 
 export function createSttSettingsRouter(deps: SttSettingsRouterDeps): Router {
   const router = Router()
   const caps = deps.capabilities ?? currentSttCapabilities
   const install = deps.install ?? installParakeet
+  const diskCheck = deps.diskCheck ?? (() => parakeetDiskCheck())
+  const trust = deps.trust ?? (path => trustCli(path))
+  const pinned = deps.pinned ?? (async (path: string) => (await findPinnedCli([path])) !== null)
+  const cliVerdict = (t: CliTrust) => t.trusted
+    ? { trusted: true, trust: t.trust, teamId: t.teamId, version: t.version, versionSource: t.versionSource }
+    : { trusted: false, reason: t.reason, detail: t.detail }
   const view = () => settingsView(readSttSettings(), caps(), parakeetStatus(deps.recordingLive()), readLastSttJob())
 
   router.get('/stt-settings', (_req, res) => {
@@ -48,19 +64,54 @@ export function createSttSettingsRouter(deps: SttSettingsRouterDeps): Router {
     }
   })
 
-  router.post('/stt-settings/parakeet/install', (req, res) => {
+  // 6.74.0: COS Control says where its signed CLI is. The verdict is the same check the
+  // install makes; a trusted path also makes GET report Parakeet as installable.
+  router.post('/stt-settings/parakeet/cli', async (req, res) => {
+    try {
+      const cliPath = (req.body ?? {}).cliPath
+      if (!isCliPathShape(cliPath)) return void res.status(400).json({ error: 'cliPath must be an absolute path to fluidaudiocli.' })
+      const t = await trust(cliPath)
+      if (t.trusted) offerControlCli(cliPath)
+      res.status(t.trusted ? 200 : 422).json(cliVerdict(t))
+    } catch (err) {
+      res.status(500).json({ error: errMsg(err) })
+    }
+  })
+
+  router.post('/stt-settings/parakeet/install', async (req, res) => {
     try {
       if (deps.recordingLive()) return void res.status(409).json({ error: 'A recording is live. Install Parakeet after it is saved.' })
       if (parakeetInstalled().installed && !parakeetInstallRunning()) return void res.status(200).json({ started: false, ...view() })
-      const body = (req.body ?? {}) as { localSource?: unknown; allowDownload?: unknown }
+      const body = (req.body ?? {}) as { localSource?: unknown; allowDownload?: unknown; cliPath?: unknown }
       const raw = body.localSource
       if (raw !== undefined && (typeof raw !== 'string' || !raw.startsWith('/') || raw.length > 1024)) {
         return void res.status(400).json({ error: 'localSource must be an absolute path.' })
       }
       if (body.allowDownload !== undefined && typeof body.allowDownload !== 'boolean') return void res.status(400).json({ error: 'allowDownload must be true or false.' })
+      if (body.cliPath !== undefined && !isCliPathShape(body.cliPath)) return void res.status(400).json({ error: 'cliPath must be an absolute path to fluidaudiocli.' })
+      if (!parakeetInstallRunning()) {
+        const disk = diskCheck()
+        if (!disk.ok) {
+          return void res.status(507).json({
+            error: `Parakeet needs ${(disk.requiredBytes / 1e9).toFixed(1)} GB free on this Mac. Free some space, then install again. Whisper keeps working.`,
+            reason: 'insufficient_disk', freeBytes: disk.freeBytes, requiredBytes: disk.requiredBytes,
+          })
+        }
+        if (typeof body.cliPath === 'string' && !(await pinned(body.cliPath))) {
+          const t = await trust(body.cliPath)
+          if (!t.trusted) {
+            return void res.status(422).json({ error: 'The speech tool in COS Control did not pass its check. Reinstall COS Control, then install again.', reason: 'cli_untrusted', cli: cliVerdict(t) })
+          }
+          offerControlCli(body.cliPath)
+        }
+      }
       // Only bytes whose SHA-256 matches the pinned manifest are ever copied from it.
       // A named localSource that lacks a file fails plainly unless allowDownload is true.
-      const options: InstallOptions = raw ? { localSources: [raw], requireLocal: body.allowDownload !== true } : {}
+      // 6.74.0: allowDownload:false with no localSource also never downloads.
+      const options: InstallOptions = {
+        ...(raw ? { localSources: [raw], requireLocal: body.allowDownload !== true } : body.allowDownload === false ? { requireLocal: true } : {}),
+        ...(typeof body.cliPath === 'string' ? { cliCandidates: [body.cliPath] } : {}),
+      }
       if (!parakeetInstallRunning()) {
         void install(options).then(() => { ensurePreviewWarm(); deps.onChanged?.() }).catch(error => {
           console.warn(`[stt] Parakeet install failed: ${errMsg(error)}`)

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/server/routes/transcribe.ts

@@ -1,5 +1,7 @@
 // POST /api/transcribe: one-shot transcription (message-query path). 6.73.0: the engine
 // follows the STT settings (docs/dictation-stt-contract.md); Whisper is the fallback.
+// 6.74.0: Mac dictation (requiredEngine=local) follows its own dictation setting and
+// never leaves this Mac; POST /api/transcribe/benchmark is the onboarding check.
 //
 // The actual Whisper + cleanup pipeline lives in server/lib/transcribe-audio.ts so
 // prompt-draft recovery and the legacy one-shot path share exactly the same behavior.
@@ -12,6 +14,9 @@ import {
   OpenAIWhisperBudgetExhaustedError,
   TranscriptionUnavailableError,
 } from '../lib/transcribe-audio.js'
+import {
+  BENCHMARK_MAX_BYTES, BenchmarkRefusedError, parseBenchmarkEngines, runDictationBenchmark,
+} from '../lib/dictation-benchmark.js'
 import {
   acquireMaintenanceWork,
   MaintenanceLifecycleError,
@@ -22,8 +27,55 @@ import {
 export const transcribeRouter = Router()
 // A Mac client checks this before transferring microphone audio. Older servers must not
 // silently ignore the requested engine and use a configured cloud fallback.
+// 6.74.0: desktopDictationVersion stays 1, because COS Control 0.5.316 and earlier accept
+// exactly 1. desktopDictationVersions lists 2: requiredEngine=local (the dictation setting).
 transcribeRouter.get('/transcribe/capabilities', (_req, res) => {
-  res.json({ desktopDictationVersion: 1, requiredEngines: ['parakeet-ultra'], localOnly: true, dictionary: 'cos' })
+  res.json({
+    desktopDictationVersion: 1,
+    desktopDictationVersions: [1, 2],
+    requiredEngines: ['parakeet-ultra', 'local'],
+    localOnly: true,
+    dictionary: 'cos',
+    benchmark: 1,
+  })
+})
+
+const REQUIRED_ENGINES = new Set(['parakeet-ultra', 'local'])
+
+async function readCapped(req: AsyncIterable<unknown>, cap: number): Promise<Buffer | null> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array)
+    size += part.length
+    if (size > cap) return null
+    chunks.push(part)
+  }
+  return Buffer.concat(chunks)
+}
+
+// POST /api/transcribe/benchmark?engines=whisper,parakeet-ultra: raw 16 kHz WAV body.
+// Bounded in dictation-benchmark.ts (one at a time, never while recording, timeouts).
+transcribeRouter.post('/transcribe/benchmark', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
+  try {
+    const engines = parseBenchmarkEngines(req.query.engines)
+    if (!engines) return res.status(400).json({ error: 'engines must list whisper and/or parakeet-ultra.', reason: 'invalid_engine' })
+    maintenanceLease = acquireMaintenanceWork('one_shot_transcription')
+    const audio = await readCapped(req, BENCHMARK_MAX_BYTES)
+    if (!audio) return res.status(413).json({ error: 'The sample is longer than two minutes.', reason: 'audio_too_large' })
+    const result = await runDictationBenchmark(audio, engines)
+    res.json(result)
+  } catch (err: any) {
+    if (err instanceof MaintenanceLifecycleError) {
+      if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+      return res.status(err.status).json(maintenanceErrorPayload(err))
+    }
+    if (err instanceof BenchmarkRefusedError) return res.status(err.status).json({ error: err.message, reason: err.reason })
+    res.status(500).json({ error: err.message })
+  } finally {
+    maintenanceLease?.release()
+  }
 })
 
 function resolveMode(req: { body?: { mode?: string }; query?: { mode?: string | string[] } }) {
@@ -38,21 +90,13 @@ transcribeRouter.post('/transcribe', async (req, res) => {
   let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     maintenanceLease = acquireMaintenanceWork('one_shot_transcription')
-    const chunks: Buffer[] = []
-    const requiredEngine = req.query.requiredEngine
-    if (requiredEngine !== undefined && requiredEngine !== 'parakeet-ultra') {
+    const rawEngine = req.query.requiredEngine
+    if (rawEngine !== undefined && (typeof rawEngine !== 'string' || !REQUIRED_ENGINES.has(rawEngine))) {
       return res.status(400).json({ error: 'invalid_required_engine' })
     }
-    let size = 0
-    for await (const chunk of req) {
-      const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
-      size += part.length
-      if (size > (requiredEngine ? 3_840_044 : 25 * 1024 * 1024)) {
-        return res.status(413).json({ error: 'audio_too_large' })
-      }
-      chunks.push(part)
-    }
-    const audioBuffer = Buffer.concat(chunks)
+    const requiredEngine = rawEngine as 'parakeet-ultra' | 'local' | undefined
+    const audioBuffer = await readCapped(req, requiredEngine ? 3_840_044 : 25 * 1024 * 1024)
+    if (!audioBuffer) return res.status(413).json({ error: 'audio_too_large' })
 
     if (audioBuffer.length < 100) {
       return res.status(400).json({ error: 'audio too short' })
@@ -74,6 +118,9 @@ transcribeRouter.post('/transcribe', async (req, res) => {
       // 6.73.0, additive: which engine decoded it and, when the selection could not run, why.
       engine: result.engine,
       ...(result.engineReason ? { engineReason: result.engineReason } : {}),
+      // 6.74.0, Mac dictation only.
+      ...(result.dictationSetting ? { dictationSetting: result.dictationSetting } : {}),
+      ...(result.fallbackReason ? { fallbackReason: result.fallbackReason } : {}),
     })
   } catch (err: any) {
     if (err instanceof MaintenanceLifecycleError) {
@@ -95,10 +142,13 @@ transcribeRouter.post('/transcribe', async (req, res) => {
     }
     if (err instanceof TranscriptionUnavailableError) {
       console.warn(`[transcribe] ${err.message}`)
+      // The 6.73.x body for every caller; Mac dictation on requiredEngine=local adds
+      // the one action it offers, and says when a retry cannot succeed.
       return res.status(err.status).json({
         error: err.message,
         reason: err.reason,
-        retryable: true,
+        retryable: err.hint ? err.hint.retryable : true,
+        ...(err.hint ? { action: err.hint.action, detail: err.hint.detail } : {}),
       })
     }
     res.status(500).json({ error: err.message })

package/server/routes/work-chat.ts

@@ -1,12 +1,14 @@
 import { Router } from 'express'
 import { parseWorkChatInput, parseWorkChatAnswer, WORK_CHAT_SYSTEM, WORK_CHAT_PLANNERS, WORK_CHAT_EFFORTS, WORK_CHAT_DEFAULT_EFFORT,
-  WORK_CHAT_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS, WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS, WORK_CHAT_MAX_ITEMS } from '../lib/work-chat.js'
+  WORK_CHAT_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS, WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS, WORK_CHAT_MAX_ITEMS, WORK_CHAT_MAX_REFERENCES } from '../lib/work-chat.js'
 import { runMeetingAskModel } from '../lib/meeting-ask-runner.js'
 import { acquireMaintenanceWork, maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
 export function createWorkChatRouter(deps = {run:runMeetingAskModel, admissions:maintenanceAdmissionsOpen, lease:()=>acquireMaintenanceWork('work_chat')}) {
   const router=Router(); let running=false
   router.use('/work/chat', (_req,res,next)=>{res.set('Cache-Control','private, no-store');next()})
-  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',planners:WORK_CHAT_PLANNERS,effort:WORK_CHAT_DEFAULT_EFFORT,efforts:WORK_CHAT_EFFORTS,automaticProviders:['claude','codex'],maxAssignments:WORK_CHAT_MAX_ASSIGNMENTS,contextItems:true,maxContextItems:WORK_CHAT_MAX_ITEMS}))
+  // 6.73.15: queueRounds means sessions may carry openWork, and the planner routes around sessions with earlier work open.
+  // references means the input may carry read-only reference sessions (never targets).
+  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',planners:WORK_CHAT_PLANNERS,effort:WORK_CHAT_DEFAULT_EFFORT,efforts:WORK_CHAT_EFFORTS,automaticProviders:['claude','codex'],maxAssignments:WORK_CHAT_MAX_ASSIGNMENTS,contextItems:true,maxContextItems:WORK_CHAT_MAX_ITEMS,queueRounds:true,references:true,maxReferences:WORK_CHAT_MAX_REFERENCES}))
   router.post('/work/chat',async(req,res)=>{
     let input
     try { if (Buffer.byteLength(JSON.stringify(req.body))>100000) throw new Error(); input=parseWorkChatInput(req.body) }

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'
+}