@gotcos/glasses-server 6.16.9 → 6.18.0

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

@@ -0,0 +1,202 @@
+// Live Cues memory hops.
+//
+// callPython() cannot be used here: it shells exactly one script,
+// cos_api_bridge.py, whose dispatch has no semantic_search or lightrag_search
+// verb — an unknown verb returns nothing useful, indistinguishable from an
+// empty result. Both hops spawn python directly against the exported
+// PYTHON_BIN / COS_SCRIPTS_DIR with their own preflight, timeout, and parse.
+
+import { execFile, spawn, type ChildProcess } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { COS_SCRIPTS_DIR, PYTHON_BIN } from './python-bridge.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import { logTokenAudit } from './token-audit.js'
+
+export interface SemanticHit {
+  title: string
+  date: string
+  domain: string
+  score: number
+  summary: string
+}
+
+export interface Hop1Result {
+  ok: boolean
+  snippets: string[]
+  reason?: string
+}
+
+export interface Hop2Result {
+  ok: boolean
+  text: string | null
+  reason?: string
+  /** False when the python tree (which may hold claude -p grandchildren)
+   *  could not be proven dead after a timeout kill. */
+  treeClosed: boolean
+}
+
+const HOP1_TIMEOUT_MS = 15_000
+const HOP2_TIMEOUT_MS = 40_000
+
+// The LightRAG query pool is 200/day SHARED with /why, --explore, and prep,
+// and it increments per LLM call (~2 per query), not per invocation. The
+// reserve leaves headroom for interactive queries; it does NOT give cues an
+// isolated pool (that would need a third pool in lightrag_adapter.py).
+const LIGHTRAG_DAILY_CAP = 200
+
+function lightragReserve(): number {
+  const raw = Number(process.env.COS_LIVE_CUES_LIGHTRAG_RESERVE ?? 120)
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 120
+}
+
+export function lightragBudgetAllows(): boolean {
+  if (!COS_SCRIPTS_DIR) return false
+  try {
+    const counterPath = resolve(COS_SCRIPTS_DIR, '.lightrag_daily_calls.json')
+    if (!existsSync(counterPath)) return true
+    const parsed = JSON.parse(readFileSync(counterPath, 'utf-8')) as { date?: string; query?: number }
+    const today = new Date().toISOString().slice(0, 10)
+    if (parsed.date !== today) return true
+    const spent = Number.isFinite(parsed.query) ? Number(parsed.query) : 0
+    return (LIGHTRAG_DAILY_CAP - spent) > lightragReserve()
+  } catch {
+    // An unreadable counter fails toward NOT spending: the reserve exists to
+    // protect the interactive pool, and blind spending defeats it.
+    return false
+  }
+}
+
+/** hop1 — Qdrant semantic search. No LLM spend; plain execFile timeout is fine. */
+export function semanticSearchHop(query: string): Promise<Hop1Result> {
+  const pythonBin = PYTHON_BIN
+  const scriptsDir = COS_SCRIPTS_DIR
+  if (!pythonBin || !scriptsDir) {
+    return Promise.resolve({ ok: false, snippets: [], reason: 'no_cos_pipeline' })
+  }
+  const script = resolve(scriptsDir, 'semantic_search.py')
+  if (!existsSync(script)) {
+    return Promise.resolve({ ok: false, snippets: [], reason: 'no_memory_scripts' })
+  }
+  return new Promise(resolveHop => {
+    execFile(
+      pythonBin,
+      // --min-score pinned explicitly: the CLI default is 0.25 but the
+      // programmatic default is 0.35, and inheriting the wrong one silently
+      // cuts recall.
+      [script, query, '--json', '--limit', '5', '--min-score', '0.25'],
+      { cwd: scriptsDir, timeout: HOP1_TIMEOUT_MS, maxBuffer: 1024 * 1024 },
+      (error: Error | null, stdout: string | Buffer) => {
+        if (error) {
+          resolveHop({ ok: false, snippets: [], reason: 'qdrant_unreachable' })
+          return
+        }
+        try {
+          const hits = JSON.parse(String(stdout)) as SemanticHit[]
+          const snippets = (Array.isArray(hits) ? hits : [])
+            .slice(0, 5)
+            .map(hit => `${hit.date ?? '?'} ${hit.title ?? 'Untitled'}: ${String(hit.summary ?? '').slice(0, 220)}`)
+          resolveHop({ ok: true, snippets })
+        } catch {
+          resolveHop({ ok: false, snippets: [], reason: 'qdrant_parse_error' })
+        }
+      },
+    )
+  })
+}
+
+/** Strip the human chrome lightrag_search.py --explore prints around the
+ *  answer. --explore returns before the --json branch — it can NEVER emit
+ *  JSON, so this is a plain-text contract by construction. */
+export function parseExploreOutput(raw: string): string {
+  return raw
+    .split('\n')
+    .filter(line => {
+      const trimmed = line.trim()
+      if (/^Exploring entity:/i.test(trimmed)) return false
+      if (/^-{10,}$/.test(trimmed)) return false
+      if (/^\[\d+(?:\.\d+)?s \| mode: /.test(trimmed)) return false
+      if (/^(Query|Mode):/i.test(trimmed)) return false
+      return true
+    })
+    .join('\n')
+    .trim()
+}
+
+/** hop2 — LightRAG entity exploration. Spends claude -p from the shared query
+ *  pool; spawned detached because the python child holds claude grandchildren
+ *  a plain timeout kill would orphan. */
+export function lightragExploreHop(
+  entity: string,
+  onProcess?: (proc: ChildProcess) => void,
+): Promise<Hop2Result> {
+  const pythonBin = PYTHON_BIN
+  const scriptsDir = COS_SCRIPTS_DIR
+  if (!pythonBin || !scriptsDir) {
+    return Promise.resolve({ ok: false, text: null, reason: 'no_cos_pipeline', treeClosed: true })
+  }
+  const script = resolve(scriptsDir, 'lightrag_search.py')
+  if (!existsSync(script)) {
+    return Promise.resolve({ ok: false, text: null, reason: 'no_memory_scripts', treeClosed: true })
+  }
+  if (!lightragBudgetAllows()) {
+    return Promise.resolve({ ok: false, text: null, reason: 'daily_graph_cap', treeClosed: true })
+  }
+  const startedAt = Date.now()
+  return new Promise(resolveHop => {
+    let settled = false
+    let stdout = ''
+    let timedOut = false
+
+    const proc = spawn(pythonBin, [script, '--explore', entity], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: scriptsDir,
+      env: { ...process.env },
+      detached: true,
+    })
+    onProcess?.(proc)
+
+    const finish = (result: Hop2Result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolveHop(result)
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      void terminateProviderProcess(proc).then(termination => {
+        finish({ ok: false, text: null, reason: 'graph_timeout', treeClosed: termination.closed })
+      })
+    }, HOP2_TIMEOUT_MS)
+
+    proc.on('error', () => finish({ ok: false, text: null, reason: 'graph_spawn_failed', treeClosed: !proc.pid }))
+    proc.stdout?.on('data', chunk => {
+      stdout += String(chunk)
+      if (stdout.length > 1024 * 1024) stdout = stdout.slice(-1024 * 1024)
+    })
+
+    proc.on('close', code => {
+      if (timedOut) return
+      const durationMs = Date.now() - startedAt
+      if (code !== 0) {
+        finish({ ok: false, text: null, reason: 'graph_failed', treeClosed: true })
+        return
+      }
+      const text = parseExploreOutput(stdout)
+      if (!text || /^LightRAG query failed/im.test(stdout)) {
+        finish({ ok: false, text: null, reason: 'graph_empty', treeClosed: true })
+        return
+      }
+      logTokenAudit({
+        source: 'live-cues',
+        model: 'lightrag',
+        inputChars: entity.length,
+        outputChars: text.length,
+        durationMs,
+        caller: 'live-cues-lightrag',
+      })
+      finish({ ok: true, text: text.slice(0, 4_000), treeClosed: true })
+    })
+  })
+}

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

@@ -0,0 +1,98 @@
+// Live Cues prompts — planner and insight, both Composer asks via the
+// dedicated spawn (live-cues-cursor.ts). The bridge's system prompt is gone,
+// so these prompts own EVERY constraint themselves, including the anti-markdown
+// rule (the old bridge prompt forbade structured output, which is why the
+// bridge cannot be used) and the attribution rule (with sparse voiceprints,
+// diarization collapses to owner/Ext and a model will invent named speakers).
+
+export interface PlannerResult {
+  query: string
+  entity: string | null
+}
+
+export interface InsightResult {
+  nudge: string
+  type: string
+  priority: number
+}
+
+const JSON_ONLY_RULES = [
+  'Output ONLY minified JSON on a single line. No markdown, no code fences, no prose before or after.',
+  'If you have nothing sharp to contribute, output the literal token null.',
+].join(' ')
+
+export function buildPlannerPrompt(transcriptWindow: string): string {
+  return [
+    'You plan memory lookups for a live-meeting coaching system.',
+    'Given the transcript window below, produce the single most valuable memory query.',
+    JSON_ONLY_RULES,
+    'Schema: {"query": string, "entity": string | null}',
+    '- "query": a semantic search phrase for past-meeting retrieval (topics, decisions, commitments). Under 12 words.',
+    '- "entity": ONE named person, company, or project from the transcript worth exploring in the knowledge graph, or null.',
+    'Output null when the window is small talk, logistics, or filler with no retrievable substance.',
+    '',
+    'TRANSCRIPT WINDOW:',
+    transcriptWindow,
+  ].join('\n')
+}
+
+export function buildInsightPrompt(input: {
+  transcriptWindow: string
+  memorySnippets: string[]
+  graphContext: string | null
+}): string {
+  const memory = input.memorySnippets.length
+    ? input.memorySnippets.map((snippet, index) => `${index + 1}. ${snippet}`).join('\n')
+    : '(no related past meetings found)'
+  return [
+    'You produce ONE live coaching cue for smart-glasses during a meeting.',
+    'The wearer sees at most 85 characters, so the cue must be a single sharp line.',
+    JSON_ONLY_RULES,
+    'Schema: {"nudge": string, "type": string, "priority": number}',
+    '- "nudge": max 85 characters, max 14 words. Plain text. No markdown, no asterisks, no em dashes.',
+    '- "type": a short snake_case category, e.g. commitment_check, past_context, open_question, risk_flag. NEVER the literal string coaching_nudge.',
+    '- "priority": 1 (glance-worthy) to 3 (say this now).',
+    'Rules:',
+    '- The cue must use the MEMORY or GRAPH context to surface an edge the room cannot see. Do not replay what was just said.',
+    '- Never attribute a statement to a named person unless the transcript line is labeled with that name. Prefer "someone raised X".',
+    '- A sharp question is a valid cue when context is thin.',
+    '- Output null unless the cue is genuinely worth interrupting a meeting for.',
+    '',
+    'TRANSCRIPT WINDOW:',
+    input.transcriptWindow,
+    '',
+    'MEMORY (related past meetings):',
+    memory,
+    '',
+    'GRAPH CONTEXT:',
+    input.graphContext ?? '(unavailable this cycle)',
+  ].join('\n')
+}
+
+/** Parse a Composer reply that was instructed to emit minified JSON or null.
+ *  Tolerates accidental code fences; anything else unparseable returns null. */
+export function parseJsonReply<T>(raw: string, validate: (value: unknown) => value is T): T | null {
+  const trimmed = raw.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim()
+  if (!trimmed || trimmed === 'null') return null
+  try {
+    const parsed: unknown = JSON.parse(trimmed)
+    return validate(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+export function isPlannerResult(value: unknown): value is PlannerResult {
+  if (!value || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return typeof record.query === 'string' && record.query.trim().length > 0
+    && (record.entity === null || typeof record.entity === 'string')
+}
+
+export function isInsightResult(value: unknown): value is InsightResult {
+  if (!value || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return typeof record.nudge === 'string' && record.nudge.trim().length > 0
+    && typeof record.type === 'string' && record.type.trim().length > 0
+    && typeof record.priority === 'number' && Number.isFinite(record.priority)
+}

package/server/lib/maintenance-lifecycle.ts

@@ -47,6 +47,12 @@ export type MaintenanceWorkKind =
   | 'prompt_draft_write'
   | 'prompt_draft_warm'
   | 'prompt_draft_finalize'
+  // Live Cues pipeline (planner + memory hops + insight). Held for the
+  // pipeline's in-flight duration so an Update Server drain cannot unload the
+  // server while a Cursor CLI or python child is live. The pipeline wall
+  // budget must stay under COS Control's 90s drain timeout (main.swift:1853)
+  // or every drain that catches a cue in flight hard-fails to Repair.
+  | 'live_cue_pipeline'
 
 export type MaintenanceWorkPhase = 'queued' | 'active'
 export type MaintenanceOperationScope = 'same_boot' | 'cross_boot'

package/server/lib/meeting-store.ts

@@ -409,7 +409,16 @@ export class MeetingStore {
       '',
       '## Summary',
       '',
-      '*Standalone recording — canonical transcript shown in meeting detail.*',
+      // When COS ops is configured, use the private-app pipeline markers so
+      // sync_meetings.py --g2-file will enrich (and reclassify domain). Plain
+      // "Standalone recording" summaries are treated as already-final and skipped.
+      ...(process.env.COS_SCRIPTS_DIR || process.env.COS_OPERATIONS_DIR || process.env.COS_MEETINGS_ROOT
+        ? [
+            '<!-- g2-needs-domain-review -->',
+            '',
+            '*G2 recording — summary pending pipeline processing.*',
+          ]
+        : ['*Standalone recording — canonical transcript shown in meeting detail.*']),
       '',
       '## Transcript',
       '',

package/server/lib/profile.ts

@@ -1,16 +1,38 @@
 // Profile loader — reads user identity from .cos-profile.json (gitignored)
 // Falls back to generic defaults for users who haven't configured a profile
 
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { resolve } from 'node:path'
 import { atomicWriteFileSync } from './atomic-fs.js'
 
 const APP_ROOT = resolve(import.meta.dirname, '../..')
+
+/** The profile in the data home. Survives updates; the APP_ROOT copy does not. */
+export function homeProfilePath(): string {
+  return resolve(homedir(), '.cos-glasses', '.cos-profile.json')
+}
+
 // Single canonical path — used by BOTH the reader and the writer so a glossary
 // PUT can never write to a different file than the cache reads from. Lazy +
 // env-overridable (COS_PROFILE_PATH) so tests can target a temp file.
+//
+// APP_ROOT is the INSTALLED PACKAGE root. For a managed install that is inside
+// the generation directory, which an update replaces wholesale — so a profile
+// there is destroyed on every upgrade, and a fresh managed install has no
+// profile at all (loadProfile() catches to {} and every field silently takes
+// its default). Relying on COS_PROFILE_PATH alone is not enough either: the
+// launcher rebuilds its environment from the release manifest rather than the
+// existing plist, so an operator-set value is dropped by the next
+// install/update/repair. Prefer the data home whenever a profile lives there.
+//
+// Order: explicit override → ~/.cos-glasses/.cos-profile.json → package root.
 function profilePath(): string {
-  return process.env.COS_PROFILE_PATH || resolve(APP_ROOT, '.cos-profile.json')
+  const override = process.env.COS_PROFILE_PATH?.trim()
+  if (override) return resolve(override)
+  const home = homeProfilePath()
+  if (existsSync(home)) return home
+  return resolve(APP_ROOT, '.cos-profile.json')
 }
 
 let profileCache: Record<string, unknown> | null = null

package/server/lib/speaker-embeddings.ts

@@ -8,18 +8,62 @@
 import { resolve } from 'node:path'
 import { errMsg } from './utils.js'
 import { getOwnerSpeakerLabel } from './profile.js'
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync, statSync, openSync, readSync, closeSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
+/** A real voiceprint model is ~26 MB; anything this small is a bad download. */
+const MIN_MODEL_BYTES = 1_000_000
+const PROBE_TIMEOUT_MS = 30_000
+
 // sherpa-onnx-node is CJS — use createRequire for ESM compat
 import { createRequire } from 'node:module'
 const require = createRequire(import.meta.url)
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 
-const MODEL_PATH = resolve(__dirname, '..', 'models',
-  '3dspeaker_speech_eres2net_sv_en_voxceleb_16k.onnx')
 import { DATA_DIR } from './data-dir.js'
+
+export const SPEAKER_MODEL_FILENAME = '3dspeaker_speech_eres2net_sv_en_voxceleb_16k.onnx'
+
+/** Where the voiceprint model may live, in priority order:
+ *
+ *  1. COS_SPEAKER_MODEL_PATH — explicit override (full path to the .onnx).
+ *  2. ~/.cos-glasses/models/ — the bolt-on location. The model is ~26 MB and is
+ *     deliberately NOT in the npm tarball, so a managed install has no bundled
+ *     copy. The data home survives generation swaps; anything inside the
+ *     installed package does not, and a model dropped there is destroyed by the
+ *     next update.
+ *  3. server/models/         — bundled, which only exists in a source checkout.
+ *
+ *  Anchored on homedir() rather than DATA_DIR/'..' on purpose: path.resolve is
+ *  purely lexical, so deriving a sibling of a relocated COS_DATA_DIR could point
+ *  the "durable" candidate at an unwritable root, or — if COS_DATA_DIR were ever
+ *  set inside the package — collapse it back onto the very directory an update
+ *  destroys, silently reintroducing the bug this ordering exists to fix.
+ *
+ *  Diarization is opt-in by design: with no model the system stays on amplitude
+ *  fallback (wearer vs Ext) rather than failing. speakerModelState() exists so
+ *  that choice is VISIBLE in /api/health instead of silently degrading.
+ */
+export function speakerModelCandidates(): string[] {
+  const override = process.env.COS_SPEAKER_MODEL_PATH?.trim()
+  return [
+    ...(override ? [resolve(override)] : []),
+    resolve(homedir(), '.cos-glasses', 'models', SPEAKER_MODEL_FILENAME),
+    resolve(__dirname, '..', 'models', SPEAKER_MODEL_FILENAME),
+  ]
+}
+
+function resolveSpeakerModelPath(): string | null {
+  // isFile, not existsSync: a directory passes an existence check and would be
+  // handed to the native loader as a model.
+  return speakerModelCandidates().find(p => {
+    try { return statSync(p).isFile() } catch { return false }
+  }) ?? null
+}
+
 const PROFILES_PATH = resolve(DATA_DIR, 'voice-profiles.json')
 const CALIBRATION_LOG = resolve(DATA_DIR, 'speaker-calibration.jsonl')
 
@@ -58,14 +102,109 @@ interface ProfileStore {
   profiles: VoiceProfile[]
 }
 
+/** Cheap structural screen for a downloaded model.
+ *
+ *  Catches the common bad downloads — an HTML error/redirect page saved as
+ *  .onnx, or a truncated transfer — before the file reaches the native runtime.
+ *  ONNX is protobuf: field 1 (ir_version, varint) encodes as a leading 0x08.
+ *  This is a screen, not validation; probeModelSafely() is the real gate. */
+function looksLikeOnnxModel(path: string): boolean {
+  try {
+    if (statSync(path).size < MIN_MODEL_BYTES) return false
+    const head = Buffer.alloc(1)
+    const fd = openSync(path, 'r')
+    try { readSync(fd, head, 0, 1, 0) } finally { closeSync(fd) }
+    return head[0] === 0x08
+  } catch { return false }
+}
+
+/** Load the model in a throwaway child process first.
+ *
+ *  onnxruntime does not throw on a malformed or mismatched model — it calls
+ *  std::terminate, so the process dies with SIGABRT (or SIGSEGV for a valid-but-
+ *  wrong model). No try/catch can intercept that. In a managed install the
+ *  LaunchAgent has KeepAlive, so the death becomes a permanent restart loop that
+ *  takes down queries, meetings, and transcription — the whole server, over an
+ *  optional feature.
+ *
+ *  Absorbing that crash in a child keeps a bad file a diarization problem
+ *  instead of an outage. Cost is one short-lived process, once, and only when a
+ *  model is actually present. */
+function probeModelSafely(modelPath: string): { ok: true } | { ok: false; reason: string } {
+  const script =
+    "const{SpeakerEmbeddingExtractor}=require('sherpa-onnx-node');" +
+    "new SpeakerEmbeddingExtractor({model:process.argv[1],numThreads:1,provider:'cpu'});"
+  const probe = spawnSync(process.execPath, ['-e', script, modelPath], {
+    cwd: resolve(__dirname, '..', '..'), // package root, so sherpa-onnx-node resolves
+    timeout: PROBE_TIMEOUT_MS,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  })
+  if (probe.signal) return { ok: false, reason: `native runtime aborted (${probe.signal})` }
+  if (probe.error) return { ok: false, reason: probe.error.message }
+  if (probe.status !== 0) {
+    const stderr = String(probe.stderr ?? '').trim().split('\n').pop() ?? ''
+    return { ok: false, reason: stderr || `probe exited ${probe.status}` }
+  }
+  return { ok: true }
+}
+
 /** Initialize speaker embedding system. Returns false if model missing (graceful degradation). */
 export function initSpeakerEmbeddings(): boolean {
   if (initialized) return extractor !== null
 
   initialized = true
 
-  if (!existsSync(MODEL_PATH)) {
-    console.log('[speaker] Model not found at', MODEL_PATH, '— embedding disabled, using amplitude fallback')
+  const override = process.env.COS_SPEAKER_MODEL_PATH?.trim()
+  if (override) {
+    const overridePath = resolve(override)
+    let usable = false
+    try { usable = statSync(overridePath).isFile() } catch { usable = false }
+    if (!usable) {
+      // Falling through silently would leave the operator believing an override
+      // they mistyped (or pointed at a directory) is in effect.
+      console.warn(
+        `[speaker] COS_SPEAKER_MODEL_PATH=${overridePath} is not a readable file — ignoring it`,
+        'and falling back to the remaining candidates.',
+      )
+    }
+    if (override !== overridePath) {
+      // Relative paths resolve against cwd, which under launchd is the installed
+      // package — a location the next update deletes.
+      console.warn(
+        `[speaker] COS_SPEAKER_MODEL_PATH is relative; resolved against the working directory to ${overridePath}.`,
+        'Use an absolute path so it cannot move with the process.',
+      )
+    }
+  }
+
+  const modelPath = resolveSpeakerModelPath()
+  if (!modelPath) {
+    const boltOn = resolve(homedir(), '.cos-glasses', 'models')
+    console.log(
+      '[speaker] Voiceprint model not found — embedding disabled, speaker labels come from the client.',
+      `Searched: ${speakerModelCandidates().join(', ')}.`,
+      // Name the durable directory outright. An ordinal ("the second path")
+      // shifts with the override and pointed users at the package copy, which
+      // the next update deletes.
+      `To enable diarization put ${SPEAKER_MODEL_FILENAME} in ${boltOn}/ and restart.`,
+    )
+    return false
+  }
+
+  if (!looksLikeOnnxModel(modelPath)) {
+    console.error(
+      `[speaker] ${modelPath} does not look like an ONNX model (too small, or not protobuf) —`,
+      'embedding disabled. A partial download or an HTML error page saved as .onnx does this.',
+    )
+    return false
+  }
+
+  const probe = probeModelSafely(modelPath)
+  if (!probe.ok) {
+    console.error(
+      `[speaker] ${modelPath} failed to load — embedding disabled. Reason: ${probe.reason}.`,
+      'The server is otherwise unaffected; replace the model file and restart.',
+    )
     return false
   }
 
@@ -73,7 +212,7 @@ export function initSpeakerEmbeddings(): boolean {
     sherpaOnnx = require('sherpa-onnx-node')
 
     extractor = new sherpaOnnx.SpeakerEmbeddingExtractor({
-      model: MODEL_PATH,
+      model: modelPath,
       numThreads: 2,
       provider: 'cpu',
     })
@@ -332,6 +471,30 @@ export function isEmbeddingAvailable(): boolean {
   return extractor !== null && manager !== null
 }
 
+/** Reported on /api/health so an amplitude fallback is never mistaken for real
+ *  diarization.
+ *
+ *  `state` is the RUNTIME truth (isEmbeddingAvailable), not "is a model file on
+ *  disk". Those diverge in both directions: a model deleted after a successful
+ *  load leaves diarization working from memory, and a model present alongside a
+ *  broken/ABI-mismatched sherpa-onnx never loads at all. `error` distinguishes
+ *  that second case — a model is installed but the runtime rejected it — from a
+ *  simply unconfigured install, which otherwise look identical to an operator.
+ *
+ *  Declared after the module state it reads: hoisting it above `extractor`
+ *  would make any import-time caller throw a ReferenceError on an
+ *  unauthenticated endpoint. */
+export function speakerModelState(): {
+  state: 'active' | 'unavailable' | 'error'
+  path: string | null
+  searched: string[]
+} {
+  const path = resolveSpeakerModelPath()
+  const running = isEmbeddingAvailable()
+  const state = running ? 'active' : (path && initialized ? 'error' : 'unavailable')
+  return { state, path, searched: speakerModelCandidates() }
+}
+
 /** Compute actual cosine similarity between two raw embedding vectors */
 export function rawCosineSimilarity(a: Float32Array, b: Float32Array): number {
   if (a.length !== b.length) return 0

package/server/routes/health.ts

@@ -7,6 +7,7 @@ import { serverMetrics } from '../lib/server-metrics.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
 import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contract.js'
 import { isSileroAvailable } from '../lib/vad-silero.js'
+import { speakerModelState } from '../lib/speaker-embeddings.js'
 import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
 import {
   isWhisperLocalAvailable,
@@ -35,6 +36,7 @@ import { managedRuntimeCapability, managedServerVersion } from '../lib/managed-r
 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'
 
 export const healthRouter = Router()
 
@@ -176,6 +178,12 @@ healthRouter.get('/health', async (_req, res) => {
 
   checks.silero_vad = isSileroAvailable() ? 'active' : 'disabled'
 
+  // Speaker diarization is opt-in (the ~26 MB voiceprint model ships outside the
+  // npm tarball), so publish its state rather than letting the amplitude
+  // fallback masquerade as working diarization. Availability only — the resolved
+  // path is a local filesystem detail and health is unauthenticated.
+  checks.speaker_id = speakerModelState().state
+
   // Health is unauthenticated. Publish only availability; the actual CLI
   // session id is a resumable runtime handle and belongs on authenticated
   // query/debug surfaces.
@@ -196,6 +204,9 @@ healthRouter.get('/health', async (_req, res) => {
   const recovery = managedRuntimeCapability()
   const maintenance = maintenanceLifecycle.snapshot()
   const tts_local = getLocalTtsHealth()
+  // Computed once per request; the same value feeds features.liveCues and
+  // capabilities.liveCues so the two surfaces can never disagree.
+  const liveCues = liveCuesCapability()
   const features = {
     claude: claudeAvailable,
     codex: codexAvailable,
@@ -212,6 +223,7 @@ healthRouter.get('/health', async (_req, res) => {
     durableQueryJobsProtocol: durableJobs.protocolVersion,
     localFirstMeetings: localFirstMeetings !== null,
     transcriptionPolicy: transcription.mode,
+    liveCues: liveCues.available,
   }
   const voice = {
     available: keyStatus.hasKey || tts_local.ready,
@@ -270,6 +282,7 @@ healthRouter.get('/health', async (_req, res) => {
         carriedAcrossBoot: maintenance.operation?.carriedAcrossBoot ?? false,
       },
       cliDebug: CLI_DEBUG_CAPABILITY,
+      liveCues,
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
     // /api/health is intentionally unauthenticated for setup diagnostics.
@@ -312,6 +325,10 @@ healthRouter.get('/models', async (req, res) => {
       transcription: { ...transcription, hq: transcriptionHq },
       cliDebug: CLI_DEBUG_CAPABILITY,
       recovery: managedRuntimeCapability(),
+      // Same helper as /api/health — the companion's 15s liveness poll reads
+      // THIS surface, so a value present only on /api/health leaves the
+      // live-cues indicator blind.
+      liveCues: liveCuesCapability(),
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
   })