@gotcos/glasses-server 6.17.0 → 6.18.1

package/.env.example

@@ -116,3 +116,42 @@ 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
+
+# ── POST-MEETING HQ TRANSCRIPTION DEVICE (optional) ──────────────────────
+# After a meeting saves, the server re-transcribes it with whisper-cli
+# large-v3 ("polish"). Since 6.14.1 that batch has run on CPU (-ng) so it can
+# never fight a live meeting's ASR for the GPU — going meeting-to-meeting, the
+# polish of meeting A overlaps the live capture of meeting B, and two Metal
+# workloads degrade each other. The tax is that idle polish is slow too.
+#
+# COS_BATCH_HQ_METAL=1 opts into GPU-when-idle: each segment picks Metal only
+# when nothing live is contending, and a meeting starting mid-batch preempts
+# the GPU immediately (the interrupted segment is discarded and retried on CPU
+# — a truncated transcript is never saved). Default is OFF; leave it unset
+# until you have run a meeting-to-meeting smoke on your own machine.
+# COS_BATCH_HQ_METAL=1
+#
+# COS_BATCH_HQ_FORCE_CPU=1 is the blunt rollback. It wins over everything and
+# keeps working if the default ever flips to Metal-on.
+# COS_BATCH_HQ_FORCE_CPU=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,74 @@
+## 6.18.1
+
+- **Post-meeting HQ polish can use the GPU when nothing live needs it — opt-in.**
+  6.14.1 stopped batch polish from fighting a live meeting for Metal by pinning
+  it to CPU forever, which also taxed every idle polish. The device is now
+  chosen per segment: Metal only when `COS_BATCH_HQ_METAL=1` **and** nothing
+  live is contending. **Default is unchanged (always CPU)** until a
+  meeting-to-meeting smoke passes on real hardware; `COS_BATCH_HQ_FORCE_CPU=1`
+  remains the blunt rollback and wins over everything.
+- **Live always wins the GPU, and a preempted segment is never half-saved.**
+  A meeting starting mid-batch preempts the Metal child two ways: on new
+  session creation (create only — an ordinary status read of a stale session
+  must not evict a healthy batch) and on `recording_chunk` lease acquire, which
+  covers recovery/reconnect paths that skip creation. The interrupted output is
+  **discarded unconditionally** — checked before the exit code, because SIGTERM
+  can race to a zero exit with partial stdout — and the same segment is retried
+  once on CPU, which cannot itself be preempted. A truncated transcript is
+  never written into a saved meeting; slow or failed beats silently wrong.
+- **Waiting is distinguished from wedging.** A session counts as live only if
+  it was active within 180s. A cold orphan cannot pin batch to CPU — an
+  `active-sessions` entry sat untouched for 3+ hours on 2026-07-27, and an
+  "any session in the map" rule would have disabled the GPU path permanently
+  and silently. Prompt ASR and one-shot transcription count as contending
+  (same Metal family), and a second Metal batch never starts while one is in
+  flight. A failing liveness probe fails safe to CPU.
+- Every batch segment logs `device`, `reason`, and `metalEnabled`, so "why was
+  polish slow today" is answerable after the fact.
+
+## 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

package/managed-runtime-contract.json

@@ -13,7 +13,14 @@
     "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",
+    "COS_BATCH_HQ_METAL",
+    "COS_BATCH_HQ_FORCE_CPU"
   ],
   "maintenance": {
     "scope": "cross_boot",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.17.0",
-  "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
+  "version": "6.18.1",
+  "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": {
     "glasses-server": "bin/cli.cjs",

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