@gotcos/glasses-server 6.21.0 → 6.21.2

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 6.21.2
+
+- Cache Python, Claude, Codex, and Cursor process probes for 30 seconds so the
+  public health endpoint remains cheap under frequent phone diagnostics. Stale
+  static versions are served while one background refresh runs; live recovery,
+  transcription, TTS, maintenance, and request fields remain fresh.
+- Parse Cursor's actual `CLI Version` line instead of reporting the About
+  heading. Authenticated model discovery continues to be the authoritative
+  Cursor readiness signal.
+
+## 6.21.1
+
+- Make the transactional Claude readiness proof explicitly use Haiku instead
+  of inheriting a user's heavyweight default model. The no-tool proof now has
+  a 45-second bound, while normal COS queries keep their selected models.
+- Preserve timeout and cancellation reasons across the provider-process close
+  race. A timed-out proof now reports `provider proof timed out` instead of the
+  misleading `provider process exited before launch`.
+
 ## 6.21.0
 
 Transcription quality is now a machine-owned, observable two-tier policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.0",
+  "version": "6.21.2",
   "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/lib/health-static-probes.ts

@@ -0,0 +1,177 @@
+import { execFile } from 'node:child_process'
+import { PYTHON_BIN } from './python-bridge.js'
+import {
+  getCursorModelCatalog,
+  isCursorProviderReady,
+  resolveAgentBinary,
+} from './cursor-model-catalog.js'
+
+const DEFAULT_CACHE_TTL_MS = 30_000
+const PROBE_TIMEOUT_MS = 5_000
+
+export interface HealthStaticProbeSnapshot {
+  python: string
+  claude: string
+  codex: string
+  cursor: string
+  claudeAvailable: boolean
+  codexAvailable: boolean
+  cursorAvailable: boolean
+}
+
+interface CachedProbe<T> {
+  value: T
+  refreshedAt: number
+}
+
+/**
+ * Small stale-while-revalidate cache used for process-level health probes.
+ * Runtime fields (recordings, recovery leases, Whisper, TTS, request counts)
+ * remain fresh on every /api/health request.
+ */
+export function createStaticProbeCache<T>(
+  load: () => Promise<T>,
+  ttlMs: () => number,
+  now: () => number = Date.now,
+): { get: () => Promise<T>; reset: () => void } {
+  let cached: CachedProbe<T> | null = null
+  let inFlight: Promise<T> | null = null
+
+  const refresh = (): Promise<T> => {
+    if (inFlight) return inFlight
+    inFlight = load().then((value) => {
+      cached = { value, refreshedAt: now() }
+      return value
+    }).finally(() => {
+      inFlight = null
+    })
+    return inFlight
+  }
+
+  return {
+    get: async () => {
+      if (!cached) return refresh()
+      if (now() - cached.refreshedAt < ttlMs()) return cached.value
+      // A stale static version string is safer than making liveness wait for
+      // four child processes. Refresh it for the next request in background.
+      void refresh().catch(() => {})
+      return cached.value
+    },
+    reset: () => {
+      cached = null
+      inFlight = null
+    },
+  }
+}
+
+function cacheTtlMs(): number {
+  const raw = Number(process.env.COS_HEALTH_STATIC_PROBE_TTL_MS ?? DEFAULT_CACHE_TTL_MS)
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_CACHE_TTL_MS
+}
+
+function execute(file: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      encoding: 'utf8',
+      timeout: PROBE_TIMEOUT_MS,
+      maxBuffer: 256 * 1024,
+      killSignal: 'SIGKILL',
+    }, (error, stdout, stderr) => {
+      if (error) return reject(error)
+      resolve({ stdout: String(stdout), stderr: String(stderr) })
+    })
+  })
+}
+
+export function parseCursorAboutVersion(output: string): string | undefined {
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    const match = /^CLI Version\s*:?\s*(\d{4}(?:\.\d+){1,3}(?:[-+][a-z0-9.-]+)?)$/i.exec(line)
+    if (match) return match[1]
+  }
+  return undefined
+}
+
+function firstNonemptyLine(output: string): string | undefined {
+  return output.split(/\r?\n/).map(line => line.trim()).find(Boolean)
+}
+
+async function probePython(): Promise<string> {
+  if (!PYTHON_BIN) return 'standalone'
+  try {
+    return firstNonemptyLine((await execute(PYTHON_BIN, ['--version'])).stdout) ?? 'available'
+  } catch {
+    return 'error'
+  }
+}
+
+async function probeClaude(): Promise<{ value: string; available: boolean }> {
+  try {
+    const result = await execute('claude', ['--version'])
+    return { value: firstNonemptyLine(result.stdout) ?? 'available', available: true }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function probeCodex(): Promise<{ value: string; available: boolean }> {
+  try {
+    const result = await execute('codex', ['--version'])
+    const combined = `${result.stdout}\n${result.stderr}`.trim()
+    const versionLine = combined.split(/\r?\n/).map(line => line.trim())
+      .find(line => /^codex(?:-cli)?\s+/i.test(line))
+    return { value: versionLine ?? firstNonemptyLine(combined) ?? 'available', available: true }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function probeCursor(): Promise<{ value: string; available: boolean }> {
+  const agentBinary = resolveAgentBinary()
+  if (!agentBinary) return { value: 'error', available: false }
+  try {
+    const result = await execute(agentBinary, ['about'])
+    const combined = `${result.stdout}\n${result.stderr}`.trim()
+    const version = parseCursorAboutVersion(combined)
+    // Catalog discovery is authenticated downstream truth and can take up to
+    // seven seconds. Warm it without putting that latency on public health.
+    void getCursorModelCatalog().catch(() => {})
+    const available = isCursorProviderReady()
+    const value = version ?? 'available'
+    return {
+      value: available ? value : `${value} (models unresolved)`,
+      available,
+    }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function loadStaticHealthProbes(): Promise<HealthStaticProbeSnapshot> {
+  const [python, claude, codex, cursor] = await Promise.all([
+    probePython(),
+    probeClaude(),
+    probeCodex(),
+    probeCursor(),
+  ])
+  return {
+    python,
+    claude: claude.value,
+    codex: codex.value,
+    cursor: cursor.value,
+    claudeAvailable: claude.available,
+    codexAvailable: codex.available,
+    cursorAvailable: cursor.available,
+  }
+}
+
+const staticProbeCache = createStaticProbeCache(loadStaticHealthProbes, cacheTtlMs)
+
+export function getHealthStaticProbes(): Promise<HealthStaticProbeSnapshot> {
+  return staticProbeCache.get()
+}
+
+/** Test hook. */
+export function _resetHealthStaticProbeCache(): void {
+  staticProbeCache.reset()
+}

package/server/lib/provider-proof.ts

@@ -17,7 +17,7 @@ const PROOF_PROMPT = `This is an automated local readiness check. Do not use too
 const successCache = new Map<ProofProvider, ProviderProofResult>()
 const inFlight = new Map<ProofProvider, Promise<ProviderProofResult>>()
 
-interface ProcessResult {
+export interface ProcessResult {
   code: number | null
   stdout: string
   stderr: string
@@ -25,7 +25,9 @@ interface ProcessResult {
   aborted: boolean
 }
 
-function runBounded(
+type TerminationReason = 'timeout' | 'abort' | null
+
+export function runBounded(
   command: string,
   args: string[],
   input: string,
@@ -48,6 +50,11 @@ function runBounded(
     let stdout = ''
     let stderr = ''
     let settled = false
+    // The child `close` event normally wins the race against the async
+    // terminateProviderProcess() result. Record WHY termination began before
+    // sending a signal so that close cannot misreport a timeout as
+    // "exited before launch" (Control 0.3.5 field failure, 2026-08-03).
+    let terminationReason: TerminationReason = null
     const cap = (value: string) => value.slice(-256_000)
     child.stdout.on('data', chunk => { stdout = cap(stdout + chunk.toString()) })
     child.stderr.on('data', chunk => { stderr = cap(stderr + chunk.toString()) })
@@ -58,27 +65,57 @@ function runBounded(
       signal?.removeEventListener('abort', abort)
       resolvePromise(result)
     }
+    const terminatedResult = (code: number | null): ProcessResult => ({
+      code,
+      stdout,
+      stderr,
+      timedOut: terminationReason === 'timeout',
+      aborted: terminationReason === 'abort',
+    })
     const timer = setTimeout(() => {
+      if (settled || terminationReason) return
+      terminationReason = 'timeout'
       void terminateProviderProcess(child, { termGraceMs: 50 }).then(result => {
-        if (result.closed) finish({ code: result.code, stdout, stderr, timedOut: true, aborted: false })
+        if (result.closed) finish(terminatedResult(result.code))
         else console.error('[provider-proof] timed-out provider did not close after SIGKILL; retaining request ownership')
       })
     }, timeoutMs)
     timer.unref?.()
     const abort = () => {
+      if (settled || terminationReason) return
+      terminationReason = 'abort'
       void terminateProviderProcess(child).then(result => {
-        if (result.closed) finish({ code: result.code, stdout, stderr, timedOut: false, aborted: true })
+        if (result.closed) finish(terminatedResult(result.code))
         else console.error('[provider-proof] canceled provider did not close after SIGKILL; retaining request ownership')
       })
     }
-    child.once('error', err => finish({ code: null, stdout, stderr: err.message, timedOut: false, aborted: false }))
-    child.once('close', code => finish({ code, stdout, stderr, timedOut: false, aborted: false }))
+    child.once('error', err => {
+      stderr = cap(stderr + err.message)
+      finish(terminatedResult(null))
+    })
+    child.once('close', code => finish(terminatedResult(code)))
     signal?.addEventListener('abort', abort, { once: true })
     child.stdin.on('error', () => { /* close/error is authoritative */ })
     child.stdin.end(input)
   })
 }
 
+export const CLAUDE_PROOF_MODEL = 'haiku'
+export const CLAUDE_PROOF_TIMEOUT_MS = 45_000
+
+export function claudeProofArgs(): string[] {
+  return [
+    '-p',
+    '--model', CLAUDE_PROOF_MODEL,
+    '--output-format', 'json',
+    '--permission-mode', 'dontAsk',
+    '--tools', '',
+    '--allowedTools', '',
+    '--system-prompt', PROOF_PROMPT,
+    PROOF_PROMPT,
+  ]
+}
+
 export function claudeProofText(stdout: string): string {
   try {
     const parsed = JSON.parse(stdout) as { result?: unknown }
@@ -120,15 +157,7 @@ function safeProofError(result: ProcessResult): string {
 async function executeProof(provider: ProofProvider, signal?: AbortSignal): Promise<ProviderProofResult> {
   const started = Date.now()
   const result = provider === 'claude'
-    ? await runBounded('claude', [
-      '-p',
-      '--output-format', 'json',
-      '--permission-mode', 'dontAsk',
-      '--tools', '',
-      '--allowedTools', '',
-      '--system-prompt', PROOF_PROMPT,
-      PROOF_PROMPT,
-    ], '', 120_000, signal)
+    ? await runBounded('claude', claudeProofArgs(), '', CLAUDE_PROOF_TIMEOUT_MS, signal)
     : await runBounded('codex', [
       'exec',
       '--sandbox', 'read-only',

package/server/routes/health.ts

@@ -1,8 +1,7 @@
 import { Router } from 'express'
-import { execFile } from 'node:child_process'
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { COS_SCRIPTS_DIR, COS_MODE, PYTHON_BIN } from '../lib/python-bridge.js'
+import { COS_SCRIPTS_DIR, COS_MODE } from '../lib/python-bridge.js'
 import { serverMetrics } from '../lib/server-metrics.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
 import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contract.js'
@@ -24,7 +23,6 @@ import {
   getCursorModelCatalog,
   getCursorModelCatalogSnapshot,
   isCursorProviderReady,
-  resolveAgentBinary,
 } from '../lib/cursor-model-catalog.js'
 import { isMediaProcessingReady } from '../lib/image-safety.js'
 import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
@@ -41,6 +39,7 @@ import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
 import { getWhisperPreviewCapability } from '../lib/whisper-preview.js'
 import { getTranscriptionProfileStatus } from '../lib/profile.js'
+import { getHealthStaticProbes } from '../lib/health-static-probes.js'
 
 export const healthRouter = Router()
 
@@ -74,101 +73,26 @@ function durableQueryJobStatus() {
 }
 
 healthRouter.get('/health', async (_req, res) => {
-  await refreshLocalTtsHealth()
+  const [, staticProbes] = await Promise.all([
+    refreshLocalTtsHealth(),
+    getHealthStaticProbes(),
+  ])
   const checks: Record<string, string | number | boolean> = {
     status: 'ok',
     mode: COS_MODE ? 'cos' : 'standalone',
     server: 'ok',
-    python: 'unknown',
-    claude: 'unknown',
-    codex: 'unknown',
-    cursor: 'unknown',
+    python: staticProbes.python,
+    claude: staticProbes.claude,
+    codex: staticProbes.codex,
+    cursor: staticProbes.cursor,
     uptime_seconds: Math.floor((Date.now() - serverMetrics.startedAt) / 1000),
     request_count: serverMetrics.requestCount,
   }
 
   // Feature detection flags
-  let claudeAvailable = false
-  let codexAvailable = false
-  let cursorAvailable = false
-
-  // Check Python venv (COS mode only)
-  if (PYTHON_BIN) {
-    try {
-      await new Promise<void>((resolve, reject) => {
-        execFile(PYTHON_BIN!, ['--version'], { timeout: 5000 }, (err, stdout) => {
-          if (err) return reject(err)
-          checks.python = stdout.trim()
-          resolve()
-        })
-      })
-    } catch {
-      checks.python = 'error'
-    }
-  } else {
-    checks.python = 'standalone'
-  }
-
-  // Check claude CLI
-  try {
-    await new Promise<void>((resolve, reject) => {
-      execFile('claude', ['--version'], { timeout: 5000 }, (err, stdout) => {
-        if (err) return reject(err)
-        checks.claude = stdout.trim()
-        claudeAvailable = true
-        resolve()
-      })
-    })
-  } catch {
-    checks.claude = 'error'
-  }
-
-  // Check Codex CLI. The desktop CLI can print benign PATH warnings to stderr,
-  // so version extraction uses stdout + stderr and looks for the codex-cli line.
-  try {
-    await new Promise<void>((resolve, reject) => {
-      execFile('codex', ['--version'], { timeout: 5000 }, (err, stdout, stderr) => {
-        if (err) return reject(err)
-        const combined = `${stdout}\n${stderr}`.trim()
-        const versionLine = combined.split('\n').map(line => line.trim()).find(line => /^codex(?:-cli)?\s+/i.test(line))
-        checks.codex = versionLine ?? combined.split('\n')[0] ?? 'available'
-        codexAvailable = true
-        resolve()
-      })
-    })
-  } catch {
-    checks.codex = 'error'
-  }
-
-  // Cursor Agent CLI — probe via `agent about` only (≤5s). Never use
-  // `agent status` (can hang on login UX while logged out).
-  try {
-    const agentBinary = resolveAgentBinary()
-    if (!agentBinary) {
-      checks.cursor = 'error'
-    } else {
-      await new Promise<void>((resolveCheck, reject) => {
-        execFile(agentBinary, ['about'], { timeout: 5000 }, (err, stdout, stderr) => {
-          if (err) return reject(err)
-          const combined = `${stdout}\n${stderr}`.trim()
-          const versionLine = combined.split('\n').map(line => line.trim()).find(line =>
-            /CLI Version|cursor|agent/i.test(line),
-          )
-          checks.cursor = versionLine ?? combined.split('\n')[0] ?? 'available'
-          resolveCheck()
-        })
-      })
-      await getCursorModelCatalog()
-      cursorAvailable = isCursorProviderReady()
-      if (!cursorAvailable) {
-        checks.cursor = typeof checks.cursor === 'string' && checks.cursor !== 'error'
-          ? `${checks.cursor} (models unresolved)`
-          : 'error'
-      }
-    }
-  } catch {
-    checks.cursor = 'error'
-  }
+  const claudeAvailable = staticProbes.claudeAvailable
+  const codexAvailable = staticProbes.codexAvailable
+  const cursorAvailable = staticProbes.cursorAvailable
 
   // Check session cache freshness (COS mode only)
   if (COS_SCRIPTS_DIR) {