@gotcos/glasses-server 6.16.9 → 6.18.0

package/.env.example

@@ -116,3 +116,24 @@ BIND_HOST=0.0.0.0
 # Telegram session/activity notifications remain OFF even if the COS scripts
 # directory contains .telegram_config.json. Enable export explicitly:
 # COS_TELEGRAM_NOTIFICATIONS=1
+
+# ── LIVE CUES (optional — requires the FULL COS PIPELINE above) ──────────
+# Live meeting coaching cues on the lens: transcript window -> Composer
+# planner -> Qdrant -> LightRAG -> Composer insight -> coaching_nudge.
+# Requires COS_SCRIPTS_DIR (memory hops) plus the Cursor Agent CLI.
+# Set these in ~/.cos-glasses/.env — NOT the LaunchAgent plist: COS Control
+# refuses unknown env keys and rebuilds plist env from its manifest, so a
+# hand-edited plist value is dropped by the next Update Server.
+# COS_LIVE_CUES=1                      # master switch (kill switch: set 0 + restart)
+# COS_LIVE_CUES_MODEL=cursor-composer  # only supported value; others fail closed
+# COS_LIVE_CUES_LIGHTRAG_RESERVE=120   # leave >=N of the shared 200/day query pool
+# COS_LIVE_CUES_AUTO=0                 # debug only: arm without the phone toggle
+#
+# COS_LIVE_CUES_GRAPH=1 — LightRAG entity hop. OFF by default; measure before
+# enabling. On a 31k-entity / 66k-relationship graph we measured p50 73.5s and
+# max 117s across 5 real explores, so only 1 in 5 finished inside the 40s hop
+# budget. The rest would spend 40s of the 60s pipeline wall AND two calls from
+# the shared 200/day query pool only to end up degraded. Time your own graph:
+#   time <scripts>/venv/bin/python3 <scripts>/lightrag_search.py --explore "Some Entity"
+# Consistently under ~30s, turn it on. Otherwise leave it off — cues still get
+# memory grounding from Qdrant, which returns in ~1.5s.

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+## 6.18.0
+
+- **G2 save → operations sync restored on the managed public server.** After
+  `meeting/save` (+ HQ batch when present), the server stages the durable
+  recording into `operations/personal/meetings/` with pipeline markers and runs
+  `sync_meetings.py --g2-only --g2-file` (same enrichment runner as the private
+  app). Without this, Control installs finished HQ locally but never wrote
+  `(G2)` scribes into COS — Jul 27 regression after the 6.17.0 managed cutover.
+  Pending-batch TTL raised to 12h and skips purge while a batch lease is held.
+- **Live Cues (opt-in): live meeting coaching on the lens.** With
+  `COS_LIVE_CUES=1` and the companion's Live cues toggle On, a live meeting
+  runs transcript window → Composer planner → Qdrant → Composer insight → a
+  `coaching_nudge` flash on the glasses. Requires the full COS pipeline
+  (`COS_SCRIPTS_DIR`) plus the Cursor Agent CLI; Composer 2.5 is the only
+  supported cue model and anything else fails closed.
+- **The LightRAG graph hop ships OFF, on measured evidence.** Across 5 real
+  `--explore` calls against a 31k-entity / 66k-relationship graph: p50
+  **73.5s**, max 117.2s, min 14.8s — only 1 of 5 finished inside the 40s hop
+  budget. Left on by default it would spend 40s of the 60s pipeline wall plus
+  two calls from the shared 200/day query pool to produce a degraded cue about
+  80% of the time. `COS_LIVE_CUES_GRAPH=1` opts in after you time your own
+  graph. Graph-off is a configured normal, not a degradation, so it renders no
+  mark; cues still get memory grounding from Qdrant in ~1.5s.
+- **Cost containment is structural, not advisory.** Per-meeting cap (8
+  pipelines), single-flight, 60s floor, 30s cooldown, a 60s pipeline wall
+  (deliberately under COS Control's 90s drain window), a consecutive-failure
+  breaker, a persisted weekly Composer ceiling, and a LightRAG reserve that
+  stops graph hops while fewer than `COS_LIVE_CUES_LIGHTRAG_RESERVE` calls
+  remain in the shared 200/day query pool. Every skipped pipeline logs its
+  reason — a silent cap is treated as a defect.
+- **Zero side effects on existing paths.** Cue asks use a dedicated Composer
+  spawn: no conversation history, no Cursor run-ledger entries, no Telegram
+  notifications, and token audit under its own `live-cues` source so `g2-query`
+  keeps measuring only real user queries. Transcription never awaits the
+  pipeline. Cues degrade honestly: a cue produced without graph grounding
+  carries `degraded` + a reason, and Cursor's exit-0 auth failure output is
+  detected rather than rendered as a cue.
+- **Health truthfulness.** `features.liveCues` plus `capabilities.liveCues`
+  (`{ available, reason }`) publish from one helper on BOTH `/api/health` and
+  `/api/models`, with user-safe reasons only. Config lives in
+  `~/.cos-glasses/.env` — never the LaunchAgent plist, which COS Control
+  rebuilds from its manifest. Kill switch: `COS_LIVE_CUES=0` + restart.
+
+## 6.17.0
+
+- **Speaker diarization is now a bolt-on any install can enable.** The ~26 MB
+  voiceprint model stays out of the npm package, but the loader no longer looks
+  only inside the package (where a managed install has no copy, and where a
+  hand-placed one is destroyed by the next update). Resolution order:
+  `COS_SPEAKER_MODEL_PATH` → `~/.cos-glasses/models/` → bundled `server/models/`
+  (source checkouts). Put the model in `~/.cos-glasses/models/` and restart.
+- **A bad model file can no longer take the server down.** onnxruntime aborts
+  the process on a malformed or mismatched model rather than throwing, which
+  under a KeepAlive LaunchAgent became a permanent restart loop that killed
+  queries, meetings, and transcription over an optional feature. The file is now
+  screened structurally and loaded in a throwaway child process first, so a
+  truncated download or an HTML error page saved as `.onnx` disables diarization
+  and nothing else.
+- **`/api/health` reports `speaker_id`** as `active` / `unavailable` / `error`,
+  so a server running without voiceprints is no longer indistinguishable from
+  one doing real diarization. `error` means a model is installed but the runtime
+  rejected it.
+- **Profile config is read from the data home.** `.cos-profile.json` is now
+  loaded from `~/.cos-glasses/` when present, ahead of the package-root copy.
+  Managed installs previously resolved it inside the generation directory, where
+  no profile exists and every field silently took its default — losing
+  transcription vocabulary, whisper corrections, and the wearer label.
+- **`/api/voice/enroll` and `/api/voice/status` no longer hardcode `MU`.** Both
+  use `owner_speaker_label` (default `Me`), matching what identification already
+  used. **Upgrade note:** an install that enrolled under the old default holds a
+  profile named `MU`; `/api/voice/status` will report `enrolled: false` until you
+  set `owner_speaker_label` to `MU`. Do that rather than re-enrolling, which
+  splits one voice across two profiles.
+
 ## 6.16.9
 
 - **Message-era reset visible to a running server.** `currentMessageEraState`

package/README.md

@@ -163,6 +163,55 @@ Telegram activity export is disabled by default even when a private COS
 pipeline contains `.telegram_config.json`; enable it only with the explicit
 `COS_TELEGRAM_NOTIFICATIONS=1` opt-in.
 
+## Speaker diarization (opt-in)
+
+Without a voiceprint model this server does not classify speakers at all — it
+passes through whatever label the client sends (`Unknown` when the client sends
+nothing; the COS companion sends its own wearer/`Ext` labels). Named
+per-speaker diarization needs a ~26 MB voiceprint model that is deliberately
+**not** shipped in the npm package, so it is a bolt-on:
+
+```bash
+mkdir -p ~/.cos-glasses/models
+# put 3dspeaker_speech_eres2net_sv_en_voxceleb_16k.onnx there, then restart
+```
+
+The server searches, in order: `COS_SPEAKER_MODEL_PATH` (explicit full path to
+the `.onnx`), `~/.cos-glasses/models/`, then a bundled `server/models/` copy
+(source checkouts only). **Use the data home, not the installed package** —
+anything inside the package is destroyed by the next update, while
+`~/.cos-glasses/` survives.
+
+Use an **absolute** path if you set `COS_SPEAKER_MODEL_PATH` — a relative one
+resolves against the working directory, which under the managed LaunchAgent is
+the installed package.
+
+Verify with `/api/health` → `speaker_id`:
+
+| Value | Meaning |
+|---|---|
+| `active` | model loaded, diarization running |
+| `unavailable` | no model found — labels come from the client |
+| `error` | a model is present but the runtime rejected it (see the startup log) |
+
+The model is read once at startup, so restart after adding it. A corrupt or
+mismatched `.onnx` is screened and probed in a child process first, so a bad
+download disables diarization instead of taking the server down — but it does
+mean a wrong file fails silently apart from that log line.
+
+The wearer's label comes from `owner_speaker_label` in
+`~/.cos-glasses/.cos-profile.json` (default `Me`); set it to match the profile
+name you enrol under. Train voices via `/api/voice/enroll?name=…` (the default
+name is `owner_speaker_label`); profiles persist in
+`~/.cos-glasses/data/voice-profiles.json`.
+
+**Upgrading from an older server:** before this release the enrollment default
+was hardcoded to `MU`, so an existing install may hold a profile under that name
+while `owner_speaker_label` resolves to `Me`. `/api/voice/status` will then
+report `enrolled: false`. Set `owner_speaker_label` to `MU` to keep the existing
+voiceprints rather than re-enrolling, which would split the same voice across two
+profiles.
+
 ## HQ dictation
 
 Prompt dictation defaults to HQ. The phone owns the preference: **Fast mode

package/managed-runtime-contract.json

@@ -13,7 +13,12 @@
     "PORT",
     "HTTPS_PORT",
     "BIND_HOST",
-    "COS_DURABLE_QUERY_JOBS"
+    "COS_DURABLE_QUERY_JOBS",
+    "COS_LIVE_CUES",
+    "COS_LIVE_CUES_MODEL",
+    "COS_LIVE_CUES_GRAPH",
+    "COS_LIVE_CUES_LIGHTRAG_RESERVE",
+    "COS_LIVE_CUES_AUTO"
   ],
   "maintenance": {
     "scope": "cross_boot",

package/package.json

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

package/server/index.ts

@@ -38,6 +38,8 @@ import { recoveryRouter } from './routes/recovery.js'
 import { promptEditRouter } from './routes/prompt-edit.js'
 import { bookmarksRouter } from './routes/bookmarks.js'
 import { welcomeContextRouter } from './routes/welcome-context.js'
+import { liveCuesRouter } from './routes/live-cues.js'
+import { shutdownLiveCues } from './lib/live-cues-engine.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { getCodexRunConfig } from './lib/codex-run-ledger.js'
@@ -247,6 +249,7 @@ app.use('/api', recoveryRouter)
 app.use('/api', promptEditRouter)
 app.use('/api', bookmarksRouter)
 app.use('/api', welcomeContextRouter)
+app.use('/api', liveCuesRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -281,6 +284,15 @@ async function gracefulShutdown(): Promise<void> {
   } catch (error) {
     console.error('[query-jobs] graceful interruption failed:', error)
   }
+  // Live Cues spawns detached trees (Cursor CLI, python with claude -p
+  // grandchildren) that would survive this process's death — kill them
+  // explicitly inside the 8s force-exit budget. Single-flight guarantees at
+  // most one tree per session, which fits.
+  try {
+    await shutdownLiveCues()
+  } catch (error) {
+    console.error('[live-cues] shutdown termination failed:', error)
+  }
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
   stopCodexModelCatalogRefresh()
   stopWhisperServer()

package/server/lib/g2-enrichment-runner.ts

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+
+export const G2_RESULT_PREFIX = 'COS_G2_RESULT='
+
+export interface G2EnrichmentOutcome {
+  status: 'enriched' | 'already-enriched' | 'blended'
+  path: string
+  title: string
+}
+
+export interface G2EnrichmentAttempt {
+  code: number | null
+  stdout: string
+  stderr: string
+  error?: string
+}
+
+export interface G2EnrichmentRunResult {
+  ok: boolean
+  attempts: number
+  outcome?: G2EnrichmentOutcome
+  error?: string
+}
+
+export interface G2EnrichmentOptions {
+  pythonBin: string
+  syncScript: string
+  scriptsDir: string
+  meetingFile: string
+  env: NodeJS.ProcessEnv
+  retryDelaysMs?: readonly number[]
+  timeoutMs?: number
+  killGraceMs?: number
+  onAttempt?: (message: string) => void
+}
+
+export interface G2EnrichmentDependencies {
+  runAttempt?: (options: G2EnrichmentOptions) => Promise<G2EnrichmentAttempt>
+  sleep?: (ms: number) => Promise<void>
+  fileExists?: (path: string) => boolean
+}
+
+const MAX_CAPTURE_CHARS = 64 * 1024
+
+function appendBounded(current: string, chunk: Buffer | string): string {
+  const next = current + chunk.toString()
+  return next.length <= MAX_CAPTURE_CHARS ? next : next.slice(-MAX_CAPTURE_CHARS)
+}
+
+export function parseG2EnrichmentOutcome(stdout: string): G2EnrichmentOutcome | null {
+  const lines = stdout.split(/\r?\n/)
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = lines[index].trim()
+    if (!line.startsWith(G2_RESULT_PREFIX)) continue
+    try {
+      const parsed = JSON.parse(line.slice(G2_RESULT_PREFIX.length)) as Partial<G2EnrichmentOutcome>
+      if (
+        (parsed.status === 'enriched' || parsed.status === 'already-enriched' || parsed.status === 'blended')
+        && typeof parsed.path === 'string'
+        && parsed.path.length > 0
+        && typeof parsed.title === 'string'
+        && parsed.title.length > 0
+      ) {
+        return parsed as G2EnrichmentOutcome
+      }
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+export function buildExactG2SyncArgs(syncScript: string, meetingFile: string): string[] {
+  return [syncScript, '--g2-only', '--g2-file', meetingFile, '--quiet']
+}
+
+function signalChildTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals): boolean {
+  if (!child.pid) return false
+  try {
+    if (process.platform !== 'win32') {
+      process.kill(-child.pid, signal)
+      return true
+    }
+  } catch { /* fall back to the direct child */ }
+  return child.kill(signal)
+}
+
+export async function spawnG2SyncAttempt(options: G2EnrichmentOptions): Promise<G2EnrichmentAttempt> {
+  return await new Promise(resolve => {
+    const child = spawn(
+      options.pythonBin,
+      buildExactG2SyncArgs(options.syncScript, options.meetingFile),
+      {
+        cwd: options.scriptsDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: options.env,
+        detached: process.platform !== 'win32',
+      },
+    )
+
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let timedOut = false
+    let timeout: ReturnType<typeof setTimeout> | null = null
+    let killTimer: ReturnType<typeof setTimeout> | null = null
+    const finish = (attempt: G2EnrichmentAttempt): void => {
+      if (settled) return
+      settled = true
+      if (timeout) clearTimeout(timeout)
+      if (killTimer) clearTimeout(killTimer)
+      resolve(attempt)
+    }
+
+    child.stdout?.on('data', (chunk: Buffer) => { stdout = appendBounded(stdout, chunk) })
+    child.stderr?.on('data', (chunk: Buffer) => { stderr = appendBounded(stderr, chunk) })
+    child.on('error', error => finish({ code: null, stdout, stderr, error: error.message }))
+    child.on('close', code => finish(timedOut
+      ? { code, stdout, stderr, error: `exact G2 sync timed out after ${options.timeoutMs ?? 600_000}ms` }
+      : { code, stdout, stderr }))
+
+    timeout = setTimeout(() => {
+      timedOut = true
+      signalChildTree(child, 'SIGTERM')
+      killTimer = setTimeout(() => {
+        signalChildTree(child, 'SIGKILL')
+      }, Math.max(25, options.killGraceMs ?? 2_000))
+    }, options.timeoutMs ?? 600_000)
+  })
+}
+
+function attemptError(attempt: G2EnrichmentAttempt): string {
+  if (attempt.error) return attempt.error
+  const detail = attempt.stderr.trim() || attempt.stdout.trim()
+  if (attempt.code !== 0) return `exit ${attempt.code}${detail ? `: ${detail.slice(-500)}` : ''}`
+  return `exit 0 without verified ${G2_RESULT_PREFIX} outcome${detail ? `: ${detail.slice(-500)}` : ''}`
+}
+
+/**
+ * Run one exact-file enrichment job with bounded retries. This executes in the
+ * Mac server process, not the Even Hub WebView, so it cannot touch SDK timers
+ * or the proven meeting-capture path.
+ */
+export async function runG2EnrichmentWithRetry(
+  options: G2EnrichmentOptions,
+  dependencies: G2EnrichmentDependencies = {},
+): Promise<G2EnrichmentRunResult> {
+  const retryDelaysMs = options.retryDelaysMs?.length
+    ? [...options.retryDelaysMs]
+    : [0, 15_000, 60_000]
+  const runAttempt = dependencies.runAttempt ?? spawnG2SyncAttempt
+  const sleep = dependencies.sleep ?? (async (ms: number) => await new Promise<void>(resolve => setTimeout(resolve, ms)))
+  const fileExists = dependencies.fileExists ?? existsSync
+  let lastError = 'exact G2 sync did not run'
+
+  for (let index = 0; index < retryDelaysMs.length; index++) {
+    const delayMs = Math.max(0, retryDelaysMs[index] ?? 0)
+    if (delayMs > 0) {
+      options.onAttempt?.(`retry ${index + 1}/${retryDelaysMs.length} in ${Math.round(delayMs / 1000)}s`)
+      await sleep(delayMs)
+    }
+
+    options.onAttempt?.(`attempt ${index + 1}/${retryDelaysMs.length}`)
+    const attempt = await runAttempt(options)
+    const outcome = attempt.code === 0 ? parseG2EnrichmentOutcome(attempt.stdout) : null
+    if (outcome && isAbsolute(outcome.path) && fileExists(outcome.path)) {
+      return { ok: true, attempts: index + 1, outcome }
+    }
+    lastError = outcome
+      ? `verified sentinel points to missing or non-absolute path: ${outcome.path}`
+      : attemptError(attempt)
+    options.onAttempt?.(`attempt ${index + 1} failed: ${lastError.slice(0, 500)}`)
+  }
+
+  return { ok: false, attempts: retryDelaysMs.length, error: lastError }
+}
+

package/server/lib/g2-ops-handoff.ts

@@ -0,0 +1,136 @@
+// Hand off a durable local G2 recording into COS operations/ and run exact
+// enrichment. Private cos-glasses-app did this inline in meeting/save; the
+// public managed package only wrote ~/.cos-glasses/data/recordings until
+// 2026-07-27 — so HQ could finish while operations/ never got a (G2) scribe.
+//
+// Contract:
+//   1. Keep the local recording as the glasses MeetingStore source of truth.
+//   2. When COS_OPERATIONS_DIR / COS_SCRIPTS_DIR is set, stage a pipeline-ready
+//      copy under operations/personal/meetings/YYYY-MM/ (domain review marker
+//      lets sync_meetings reclassify).
+//   3. Run sync_meetings.py --g2-only --g2-file with the private-app retry helper.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { resolveCosOperationsDir } from './cos-operations-meetings.js'
+import { runG2EnrichmentWithRetry } from './g2-enrichment-runner.js'
+import { COS_SCRIPTS_DIR, PYTHON_BIN } from './python-bridge.js'
+
+const PENDING_SUMMARY = '*G2 recording — summary pending pipeline processing.*'
+const DOMAIN_REVIEW_MARKER = '<!-- g2-needs-domain-review -->'
+
+export function patchRecordingForG2Pipeline(markdown: string): string {
+  let text = markdown.replace(/\r\n?/g, '\n')
+  if (!/\|\s*\*\*Source\*\*\s*\|\s*G2 Glasses\s*\|/i.test(text) && !text.includes('| G2 Glasses')) {
+    text = text.replace(
+      /(\|\s*\*\*Source\*\*\s*\|)([^|\n]*)\|/,
+      '| **Source** | G2 Glasses |',
+    )
+  }
+  text = text.replace(
+    /\*Standalone recording[^*]*\*/i,
+    PENDING_SUMMARY,
+  )
+  if (!/summary pending pipeline processing/i.test(text)) {
+    if (/## Summary\n\n/.test(text)) {
+      text = text.replace(/## Summary\n\n/, `## Summary\n\n${PENDING_SUMMARY}\n\n`)
+    } else {
+      text = `${text.trimEnd()}\n\n## Summary\n\n${PENDING_SUMMARY}\n`
+    }
+  }
+  if (!text.includes('g2-needs-domain-review')) {
+    if (text.includes('## Summary')) {
+      text = text.replace('## Summary', `${DOMAIN_REVIEW_MARKER}\n\n## Summary`)
+    } else {
+      text = `${text.trimEnd()}\n\n${DOMAIN_REVIEW_MARKER}\n`
+    }
+  }
+  return text
+}
+
+/** Stage local recording into operations/personal for exact enrichment. */
+export function stageRecordingIntoOperations(localMeetingPath: string): string | null {
+  const operationsDir = resolveCosOperationsDir()
+  if (!operationsDir) return null
+  if (!existsSync(localMeetingPath)) {
+    console.warn(`[g2-ops-handoff] Local meeting missing: ${localMeetingPath}`)
+    return null
+  }
+
+  const month = basename(dirname(localMeetingPath))
+  if (!/^\d{4}-\d{2}$/.test(month)) {
+    console.warn(`[g2-ops-handoff] Unexpected meeting month folder for ${localMeetingPath}`)
+    return null
+  }
+
+  const destDir = join(operationsDir, 'personal', 'meetings', month)
+  mkdirSync(destDir, { recursive: true })
+  const destPath = join(destDir, basename(localMeetingPath))
+  const patched = patchRecordingForG2Pipeline(readFileSync(localMeetingPath, 'utf8'))
+  writeFileSync(destPath, patched, { encoding: 'utf8', mode: 0o600 })
+
+  const stem = basename(localMeetingPath, '.md')
+  const localDir = dirname(localMeetingPath)
+  for (const companionName of [`${stem}.g2-chunks.json`, `${stem}.json`]) {
+    const companion = join(localDir, companionName)
+    if (existsSync(companion)) {
+      try {
+        copyFileSync(companion, join(destDir, companionName))
+      } catch (error) {
+        console.warn(
+          `[g2-ops-handoff] Sidecar copy failed for ${companionName}: `
+          + `${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+    }
+  }
+  return destPath
+}
+
+export async function handoffMeetingToOperations(localMeetingPath: string): Promise<void> {
+  if (!COS_SCRIPTS_DIR || !PYTHON_BIN) {
+    console.log('[meeting/save] Standalone mode — skipping G2 sync pipeline')
+    return
+  }
+  if (!existsSync(PYTHON_BIN)) {
+    console.warn(`[meeting/save] COS python missing at ${PYTHON_BIN} — skipping G2 sync`)
+    return
+  }
+
+  const staged = stageRecordingIntoOperations(localMeetingPath)
+  if (!staged) {
+    console.warn('[meeting/save] COS operations dir unset/unavailable — G2 sync skipped')
+    return
+  }
+
+  const syncScript = join(COS_SCRIPTS_DIR, 'sync_meetings.py')
+  if (!existsSync(syncScript)) {
+    console.warn(`[meeting/save] sync_meetings.py missing at ${syncScript}`)
+    return
+  }
+
+  const spawnPath = process.env.PATH?.includes('/opt/homebrew/bin')
+    ? process.env.PATH
+    : `/opt/homebrew/bin:${process.env.PATH || ''}`
+
+  const enrichment = await runG2EnrichmentWithRetry({
+    pythonBin: PYTHON_BIN,
+    syncScript,
+    scriptsDir: COS_SCRIPTS_DIR,
+    meetingFile: staged,
+    env: { ...process.env, PYTHONUNBUFFERED: '1', PATH: spawnPath },
+    onAttempt: message => console.log(`[meeting/save] G2 exact sync: ${message}`),
+  })
+
+  if (enrichment.ok && enrichment.outcome) {
+    console.log(
+      `[meeting/save] G2 pipeline verified after ${enrichment.attempts} attempt(s): `
+      + `${enrichment.outcome.title} → ${enrichment.outcome.path}`,
+    )
+  } else {
+    console.error(
+      `[meeting/save] G2 pipeline FAILED after ${enrichment.attempts} attempt(s): `
+      + `${enrichment.error ?? 'unknown exact-file enrichment failure'}`,
+    )
+  }
+}

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

@@ -0,0 +1,83 @@
+// Live Cues capability — ONE truth source for both health surfaces.
+//
+// Called from routes/health.ts at BOTH assembly sites (/api/health at :271 and
+// /api/models at :314). Duplicated literals at two sites is exactly how the
+// "patched one site" bug class recurs; the companion polls /api/models, so a
+// value present only on /api/health leaves the indicator blind.
+//
+// /api/health is unauthenticated: `reason` stays a user-safe enum — no paths,
+// no usernames, no counts.
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { COS_SCRIPTS_DIR, PYTHON_BIN } from './python-bridge.js'
+import { resolveAgentBinary, resolveCursorModelOption } from './cursor-model-catalog.js'
+import { CURSOR_COMPOSER_MODEL } from '../../shared/model-preference.js'
+
+export type LiveCuesReason =
+  | 'master_flag_off'
+  | 'no_composer'
+  | 'no_cos_pipeline'
+  | 'no_memory_scripts'
+  | 'budget_exhausted'
+  | 'legacy_runtime'
+  | 'maintenance_drain_active'
+
+export interface LiveCuesCapability {
+  available: boolean
+  reason?: LiveCuesReason
+}
+
+export function liveCuesEnabled(): boolean {
+  return process.env.COS_LIVE_CUES === '1'
+}
+
+/** Composer is the only supported v1 model. Anything else fails closed. */
+export function liveCuesModelSupported(): boolean {
+  const requested = process.env.COS_LIVE_CUES_MODEL?.trim()
+  return !requested || requested === CURSOR_COMPOSER_MODEL
+}
+
+/** The graph hop is OPT-IN, not opt-out. Measured against a live 31k-entity /
+ *  66k-relationship LightRAG graph (2026-07-27, n=5 real explores): p50 73.5s,
+ *  max 117.2s, and only 1 of 5 finished inside the 40s hop budget. Defaulting
+ *  it ON would burn 40s of the 60s wall plus two calls from the shared 200/day
+ *  pool to produce a DEGRADED cue roughly 80% of the time. Users with a
+ *  smaller/faster graph opt in with COS_LIVE_CUES_GRAPH=1. */
+export function liveCuesGraphEnabled(): boolean {
+  return process.env.COS_LIVE_CUES_GRAPH === '1'
+}
+
+export const LIVE_CUES_MEMORY_SCRIPTS = ['semantic_search.py', 'lightrag_search.py'] as const
+
+export function memoryScriptsPresent(): boolean {
+  const scriptsDir = COS_SCRIPTS_DIR
+  const pythonBin = PYTHON_BIN
+  if (!scriptsDir || !pythonBin) return false
+  if (!existsSync(pythonBin)) return false
+  return LIVE_CUES_MEMORY_SCRIPTS.every(script => existsSync(resolve(scriptsDir, script)))
+}
+
+/** Injected by the engine so capability can reflect an exhausted weekly budget
+ *  without a circular import. Absent hook = budget not exhausted. */
+let budgetExhaustedProbe: (() => boolean) | null = null
+export function registerLiveCuesBudgetProbe(probe: () => boolean): void {
+  budgetExhaustedProbe = probe
+}
+
+export function liveCuesCapability(): LiveCuesCapability {
+  if (!liveCuesEnabled()) return { available: false, reason: 'master_flag_off' }
+  // An unsupported model is a misconfiguration, not a missing Composer, but
+  // the public reason vocabulary maps it to no_composer: the actionable fact
+  // for the user is the same — the cue brain has no usable model.
+  if (!liveCuesModelSupported()) return { available: false, reason: 'no_composer' }
+  if (!COS_SCRIPTS_DIR) return { available: false, reason: 'no_cos_pipeline' }
+  if (!memoryScriptsPresent()) return { available: false, reason: 'no_memory_scripts' }
+  const option = resolveCursorModelOption(CURSOR_COMPOSER_MODEL)
+  // resolveCursorModelOption returns a TRUTHY object with id '' when the
+  // catalog is unavailable — the test must be !option?.id, never !option.
+  // isCursorProviderReady() is wrong here: it requires BOTH cursor slots.
+  if (!resolveAgentBinary() || !option?.id) return { available: false, reason: 'no_composer' }
+  if (budgetExhaustedProbe?.()) return { available: false, reason: 'budget_exhausted' }
+  return { available: true }
+}