@gotcos/glasses-server 6.15.0 → 6.15.2

package/.env.example

@@ -61,6 +61,12 @@ BIND_HOST=0.0.0.0
 # Claude to COS's explicit per-query tool allowlist. Undeclared tools fail
 # closed without an interactive prompt:
 # COS_CLAUDE_TRUST_MODE=allowlist
+# Optional comma-separated MCP tool selectors made available to BOTH full and
+# lightweight glasses queries. Only mcp__server__tool / mcp__server__* entries
+# are accepted; built-in Bash/Write access cannot be enabled here.
+# COS_EXTRA_TOOLS=mcp__calendar__*,mcp__gmail__search
+# Optional absolute MCP config when the managed CLI cwd does not contain it.
+# COS_CLAUDE_MCP_CONFIG=/absolute/path/to/.mcp.json
 
 # ── VOICE (optional) ────────────────────────────────────────────────────
 # Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 6.15.2
+
+- Validate the inherited Kokoro Python runtime before skipping bootstrap, so a
+  stale Python 3.13 or partial venv is repaired during a normal managed update.
+- Retry failed Kokoro cold starts with bounded exponential backoff instead of
+  latching local speech unavailable until the whole server restarts.
+- Add explicit MCP selector/config support to both Claude query paths and tell
+  the model the exact permission selectors without fabricating connector
+  health, authentication, or handshake machinery.
+- Add an authenticated, boot-cached transactional provider proof for COS
+  Control. It performs a real no-tool model turn and exposes no provider output
+  or credentials.
+
+## 6.15.1
+
+- Fix prepared TTS playback for native audio clients by allowing only
+  `GET`/`HEAD /api/tts/play/<UUID>` through the global API-token boundary. The
+  authenticated prepare route mints a random, audio-scoped capability that
+  expires after 60 seconds; all other TTS routes remain token-protected.
+- Fix Kokoro first-run provisioning by selecting only Python 3.11 or 3.12,
+  the actual compatibility intersection of the pinned `numpy` and `misaki`
+  dependencies. Python 3.13 is no longer advertised or selected.
+- Reject an incompatible `COS_TTS_BOOTSTRAP_PYTHON` before installation and
+  automatically rebuild stale or partial TTS virtual environments instead of
+  repeatedly failing inside pip.
+
 ## 6.15.0
 
 - Add local-first spoken reply playback through a Mac-owned Kokoro sidecar on

package/README.md

@@ -45,8 +45,8 @@ without silently losing completed replies.
   _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
 - `brew install whisper-cpp` for free local voice (the launcher can download the model)
-- _Optional:_ `brew install python@3.13 ffmpeg espeak-ng` for local Kokoro
-  spoken replies on Apple silicon (Python 3.11-3.13 is supported). `ffmpeg`
+- _Optional:_ `brew install python@3.12 ffmpeg espeak-ng` for local Kokoro
+  spoken replies on Apple silicon (Python 3.11-3.12 is supported). `ffmpeg`
   also enables phone/output image attachments; text chat remains available
   without these optional dependencies.
 - _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
@@ -125,6 +125,10 @@ optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
 `COS_TTS_KOKORO_VOICE` (local voice id),
 `COS_TTS_LOCAL_DISABLE=1` (disable the sidecar), and
 `COS_TTS_PRONUNCIATIONS_JSON` (optional local/cloud pronunciation overrides),
+`COS_EXTRA_TOOLS` (comma-separated `mcp__server__tool` or
+`mcp__server__*` selectors shared by full and lightweight Claude paths),
+`COS_CLAUDE_MCP_CONFIG` (optional absolute config path when `.mcp.json` is not
+in the managed CLI working directory),
 `COS_SCRIPTS_DIR` (full pipeline), `COS_DURABLE_QUERY_JOBS=1` (build 204+
 server-owned query recovery), and `COS_MEDIA_ROOT` (optional image-store
 location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
@@ -166,9 +170,11 @@ BIND_HOST=0.0.0.0 npm run start:server
   keeps compatible prompt/meeting audio available for retry instead of silently
   sending it to OpenAI.
 - *Local spoken replies unavailable?* — on Apple silicon, install
-  `python@3.13 ffmpeg espeak-ng`, restart the server, and wait for the
+  `python@3.12 ffmpeg espeak-ng`, restart the server, and wait for the
   first-run Kokoro model download. Confirm `/api/health` reports
   `tts_local.ready: true`.
+  If Python lives outside the normal Homebrew paths, set its absolute 3.11 or
+  3.12 path as `COS_TTS_BOOTSTRAP_PYTHON` in `~/.cos-glasses/.env`.
   Selecting Local never falls back to cloud; set `COS_TTS_ENGINE=openai_primary`
   only when OpenAI playback is intentionally configured.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.

package/bin/cli.cjs

@@ -4,7 +4,7 @@
 // Runs the bundled server for Even G2 smart glasses. The server ships INSIDE this
 // package — there is no clone. Config persists at ~/.cos-glasses/.
 
-const { execSync, spawn } = require('child_process')
+const { execFileSync, execSync, spawn } = require('child_process')
 const {
   existsSync,
   mkdirSync,
@@ -47,7 +47,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('    - Node.js 20.11+')
   console.log('    - Claude Code CLI (not Claude Desktop) or Codex CLI')
   console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
-  console.log('    - Optional local Kokoro voice: Apple silicon + Python 3.11-3.13')
+  console.log('    - Optional local Kokoro voice: Apple silicon + Python 3.11 or 3.12')
   console.log('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
   console.log('  Config persists at ~/.cos-glasses/.env')
@@ -79,6 +79,21 @@ function getCliVersion(command, versionArg = '--version') {
     return null
   }
 }
+function compatibleKokoroPython() {
+  const configured = process.env.COS_TTS_BOOTSTRAP_PYTHON?.trim()
+  const candidates = configured ? [configured] : ['python3.12', 'python3.11', 'python3']
+  for (const command of candidates) {
+    let version = null
+    try {
+      version = execFileSync(command, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).trim()
+    } catch { /* try the next interpreter */ }
+    const match = version?.match(/^Python\s+(\d+)\.(\d+)/i)
+    if (match && Number(match[1]) === 3 && [11, 12].includes(Number(match[2]))) {
+      return { command, version }
+    }
+  }
+  return null
+}
 function normalizeCodexVersion(raw) {
   if (!raw) return 'available'
   const line = raw.split('\n').map((s) => s.trim()).find((s) => /^codex(?:-cli)?\s+/i.test(s)) || raw.split('\n')[0].trim()
@@ -182,14 +197,12 @@ try {
 // listener. An invoked agent CLI may still maintain its own user cache.
 if (process.argv.includes('--prepare-only')) {
   if (process.platform === 'darwin' && process.arch === 'arm64') {
-    const python = ['python3.13', 'python3.12', 'python3.11']
-      .map((command) => ({ command, version: getCliVersion(command, '--version') }))
-      .find((candidate) => candidate.version)
+    const python = compatibleKokoroPython()
     if (python) {
       console.log(green('  ✓') + ` Local voice Python ${python.version.replace(/^Python\s+/i, '')}`)
     } else {
-      console.log(yellow('  ⚠') + ' Local Kokoro voice needs Python 3.11-3.13')
-      console.log('    Install: ' + bold('brew install python@3.13 ffmpeg espeak-ng'))
+      console.log(yellow('  ⚠') + ' Local Kokoro voice needs Python 3.11 or 3.12')
+      console.log('    Install: ' + bold('brew install python@3.12 ffmpeg espeak-ng'))
     }
   }
   console.log('')

package/package.json

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

package/server/index.ts

@@ -15,6 +15,7 @@ import { randomBytes } from 'node:crypto'
 import { healthRouter } from './routes/health.js'
 import { diagRouter } from './routes/diag.js'
 import { queryRouter } from './routes/query.js'
+import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
 import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter } from './routes/transcribe-stream.js'
@@ -66,10 +67,11 @@ import {
   isAllowedNetworkOrigin,
   isTailscaleIpv4,
 } from './lib/network-policy.js'
-import { timingSafeTokenEqual } from './lib/token-auth.js'
+import { requireApiToken } from './lib/api-auth.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
 import {
   acquireMaintenanceWork,
+  maintenanceOperationCredentialsValid,
   MaintenanceLifecycleError,
   maintenanceAdmissionsOpen,
   maintenanceErrorPayload,
@@ -135,24 +137,12 @@ app.use(cors({
     cb(new Error('CORS blocked'))
   },
 }))
-// Auth middleware — always active (token is auto-generated if not set)
-app.use('/api', (req, res, next) => {
-  // Allow health checks, display stream, and client diagnostics without auth.
-  // Diagnostics are whitelisted because the client needs to report crashes
-  // that may happen before the wizard has supplied an API token, and
-  // enforcing auth on a debug telemetry endpoint adds risk during the exact
-  // boot window we're trying to observe.
-  if (
-    req.path === '/health' ||
-    req.path === '/display-stream' ||
-    req.path === '/diag/client' ||
-    req.path === '/diag/health'
-  ) return next()
-  if (!timingSafeTokenEqual(req.headers['x-cos-token'], API_TOKEN)) {
-    return res.status(401).json({ error: 'unauthorized' })
-  }
-  next()
-})
+// Auth middleware — always active (token is auto-generated if not set).
+// Mounted before body parsers so rejected uploads cannot consume parse memory.
+// The only capability-URL exception is a canonical /tts/play/<UUID> GET/HEAD;
+// authenticated /tts/prepare mints it for native audio players that cannot set
+// X-Cos-Token headers.
+app.use('/api', requireApiToken(API_TOKEN))
 
 // Fail-closed catch-all for mutation routes that do not own a more specific
 // lifecycle lease below. This closes the admission/drain race for secondary
@@ -170,8 +160,29 @@ app.use('/api', (req, res, next) => {
     || req.path.startsWith('/maintenance/drain')
   if (lifecycleOwned) return next()
 
+  // COS Control must prove the candidate while a committed cross-boot gate is
+  // still closed. Permit only its two bounded loopback proofs, and only with
+  // the controller-held operation receipt. Normal phone/LAN admissions stay
+  // closed throughout the update.
+  const address = req.socket.remoteAddress ?? ''
+  const loopback = address === '::1' || address === '127.0.0.1'
+    || address.startsWith('127.') || address.startsWith('::ffff:127.')
+  const controllerProofPath = req.path === '/diagnostics/provider-proof'
+    || req.path === '/tts/prepare'
+  const controllerProof = loopback && controllerProofPath
+    && maintenanceOperationCredentialsValid({
+      leaseId: typeof req.headers['x-cos-maintenance-lease'] === 'string'
+        ? req.headers['x-cos-maintenance-lease'] : undefined,
+      operationId: typeof req.headers['x-cos-maintenance-operation'] === 'string'
+        ? req.headers['x-cos-maintenance-operation'] : undefined,
+      nonce: typeof req.headers['x-cos-maintenance-nonce'] === 'string'
+        ? req.headers['x-cos-maintenance-nonce'] : undefined,
+    })
+
   try {
-    const lease = acquireMaintenanceWork('api_mutation')
+    const lease = acquireMaintenanceWork('api_mutation', {
+      allowDuringDrain: controllerProof,
+    })
     let released = false
     const release = () => {
       if (released) return
@@ -208,6 +219,7 @@ app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
   prepareAdmission: preparePublicDurableQueryAdmission,
 }))
 app.use('/api', queryRouter)
+app.use('/api', providerProofRouter)
 app.use('/api', transcribeRouter)
 app.use('/api', displayRouter)
 app.use('/api', transcribeStreamRouter)

package/server/lib/api-auth.ts

@@ -0,0 +1,34 @@
+import type { RequestHandler } from 'express'
+import { timingSafeTokenEqual } from './token-auth.js'
+
+// Recovery/setup clients need these availability surfaces before they have a
+// usable token. Keep private provider state and every mutation route out.
+const PUBLIC_API_PATHS = new Set([
+  '/health',
+  '/display-stream',
+  '/diag/client',
+  '/diag/health',
+])
+
+// Native HTML audio requests cannot attach X-Cos-Token. The UUID minted by
+// authenticated POST /tts/prepare is therefore a short-lived bearer
+// capability. Keep this exception exact: GET/HEAD only, one canonical v4 UUID
+// path segment, and no query-token fallback that could leak into URL logs.
+const TTS_PLAYBACK_CAPABILITY_PATH = /^\/tts\/play\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+export function isPublicApiRequest(method: string, path: string): boolean {
+  if (PUBLIC_API_PATHS.has(path)) return true
+  return (method === 'GET' || method === 'HEAD')
+    && TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+}
+
+/** Global /api authentication boundary. Mount before all body parsers. */
+export function requireApiToken(apiToken: string): RequestHandler {
+  return (req, res, next) => {
+    if (isPublicApiRequest(req.method, req.path)) return next()
+    if (!timingSafeTokenEqual(req.headers['x-cos-token'], apiToken)) {
+      return res.status(401).json({ error: 'unauthorized' })
+    }
+    next()
+  }
+}

package/server/lib/claude-bridge.ts

@@ -47,6 +47,11 @@ import {
   MAX_ATTACHMENTS_PER_PROMPT,
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
+import {
+  buildClaudeToolList,
+  claudeMcpConfigArgs,
+  claudeToolCapabilityPrompt,
+} from './claude-tool-access.js'
 import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 import { claudePermissionArgs, getClaudeTrustMode } from './claude-permissions.js'
 
@@ -430,6 +435,18 @@ export async function callClaudeStreaming(
     outputImagePublisher?.cleanup()
     throw err
   }
+  const allowedToolList = buildClaudeToolList({
+    includeRead: imagePaths.length > 0,
+    publisherTool: outputImagePublisher?.claudeAllowedTool,
+  })
+  let mcpConfigArgs: string[]
+  try {
+    mcpConfigArgs = claudeMcpConfigArgs()
+  } catch (err) {
+    outputImagePublisher?.cleanup()
+    throw err
+  }
+  systemPrompt = `${systemPrompt}\n\n${claudeToolCapabilityPrompt(allowedToolList)}`
   if (outputImagePublisher) systemPrompt = `${systemPrompt}\n\n${outputImagePublisher.promptInstructions}`
 
   // Phase: thinking (waiting for Claude to start)
@@ -456,10 +473,7 @@ export async function callClaudeStreaming(
   )
 
   // Vision queries need the Read tool to see the image files
-  const baseTools = imagePaths.length > 0 ? 'WebSearch,WebFetch,Read' : 'WebSearch,WebFetch'
-  const tools = outputImagePublisher
-    ? `${baseTools},${outputImagePublisher.claudeAllowedTool}`
-    : baseTools
+  const tools = allowedToolList.join(',')
 
   // Prepend image instruction when photos are attached
   let fullQuery: string
@@ -495,16 +509,12 @@ export async function callClaudeStreaming(
     '--output-format', 'stream-json',
     '--verbose',  // Required: stream-json requires --verbose
     '--system-prompt', systemPrompt,
+    ...mcpConfigArgs,
   ]
 
-  // Full COS path gets tools + partial messages; lightweight gets web search only
+  // Full and lightweight paths share the same explicit MCP selector contract.
   if (options?.lightweight) {
-    if (imagePaths.length > 0) {
-      args.push(...claudePermissionArgs(getClaudeTrustMode(), tools))
-    } else {
-      // Lightweight: web search for general questions, no Bash/Read/Write (saves 5-10s)
-      args.push(...claudePermissionArgs(getClaudeTrustMode(), 'WebSearch,WebFetch'))
-    }
+    args.push(...claudePermissionArgs(getClaudeTrustMode(), tools))
   } else {
     args.push(...claudePermissionArgs(getClaudeTrustMode(), tools), '--include-partial-messages')
   }

package/server/lib/claude-tool-access.ts

@@ -0,0 +1,56 @@
+import { existsSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+// COS_EXTRA_TOOLS is intentionally limited to Claude MCP selectors. The
+// server's built-in Web/Read tools remain code-owned, so a remotely reachable
+// glasses query cannot turn a local env typo into Bash/Write access.
+const MCP_SELECTOR = /^mcp__[A-Za-z0-9][A-Za-z0-9_.:@/-]*__[A-Za-z0-9*][A-Za-z0-9_.*:@/-]*$/
+
+export function configuredClaudeExtraTools(
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const raw = env.COS_EXTRA_TOOLS ?? ''
+  const seen = new Set<string>()
+  const tools: string[] = []
+  for (const value of raw.split(',')) {
+    const tool = value.trim()
+    if (!tool || !MCP_SELECTOR.test(tool) || seen.has(tool)) continue
+    seen.add(tool)
+    tools.push(tool)
+  }
+  return tools
+}
+
+export function buildClaudeToolList(input: {
+  includeRead?: boolean
+  publisherTool?: string
+  env?: NodeJS.ProcessEnv
+} = {}): string[] {
+  const tools = ['WebSearch', 'WebFetch']
+  if (input.includeRead) tools.push('Read')
+  tools.push(...configuredClaudeExtraTools(input.env))
+  if (input.publisherTool) tools.push(input.publisherTool)
+  return [...new Set(tools)]
+}
+
+export function claudeToolCapabilityPrompt(tools: string[]): string {
+  return `TOOL CAPABILITY CONTRACT:
+This request is configured with only these tool selectors: ${tools.join(', ') || '(none)'}.
+Selectors are permissions, not proof that a connector is online. Use a tool only when it is actually present in this session. If the user asks for a tool or connector that is absent, or a tool call fails, say that it is unavailable. Never invent connector health, sign-in handshakes, token loading, endpoints, or authentication state.`
+}
+
+/** Optional explicit MCP config for managed launches whose CLI cwd differs
+ * from the COS brain. Normal project-local `.mcp.json` discovery needs no flag. */
+export function claudeMcpConfigArgs(
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const configured = env.COS_CLAUDE_MCP_CONFIG?.trim()
+  if (!configured) return []
+  const path = resolve(configured)
+  let regular = false
+  try { regular = existsSync(path) && statSync(path).isFile() } catch { regular = false }
+  if (!regular) {
+    throw new Error(`claude-bridge: COS_CLAUDE_MCP_CONFIG is not a readable file: ${path}`)
+  }
+  return ['--mcp-config', path]
+}

package/server/lib/maintenance-lifecycle.ts

@@ -436,6 +436,16 @@ export class MaintenanceLifecycle {
     }
   }
 
+  /** Verify only the controller-held operation secret. This does not adopt or
+   * release a gate; it lets the loopback controller run bounded post-boot
+   * proofs while normal admissions remain closed. */
+  credentialsValid(credentials: MaintenanceOperationCredentials): boolean {
+    this.expireSameBootGateIfPermitted()
+    if (!this.gate || this.blockedGateReason) return false
+    const proof = this.credentialsMatch(credentials)
+    return proof.leaseMatches && proof.operationMatches && proof.nonceMatches
+  }
+
   beginDrain(request: MaintenanceDrainRequest): string {
     this.expireSameBootGateIfPermitted()
     if (!this.managed()) {
@@ -720,6 +730,12 @@ export function acquireMaintenanceWork(
   return maintenanceLifecycle.acquire(kind, options)
 }
 
+export function maintenanceOperationCredentialsValid(
+  credentials: MaintenanceOperationCredentials,
+): boolean {
+  return maintenanceLifecycle.credentialsValid(credentials)
+}
+
 /** Read-only boot/background-worker admission check. */
 export function maintenanceAdmissionsOpen(): boolean {
   return maintenanceLifecycle.snapshot().admissionsOpen

package/server/lib/provider-proof.ts

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process'
+import { cosBrainDir } from './launch-dir.js'
+
+export type ProofProvider = 'claude' | 'codex'
+
+export interface ProviderProofResult {
+  provider: ProofProvider
+  ok: boolean
+  durationMs: number
+  cached: boolean
+  error?: string
+}
+
+const PROOF_TOKEN = 'COS_CONTROL_OK'
+const PROOF_PROMPT = `This is an automated local readiness check. Do not use tools. Reply with exactly ${PROOF_TOKEN} and nothing else.`
+const successCache = new Map<ProofProvider, ProviderProofResult>()
+const inFlight = new Map<ProofProvider, Promise<ProviderProofResult>>()
+
+interface ProcessResult {
+  code: number | null
+  stdout: string
+  stderr: string
+  timedOut: boolean
+}
+
+function runBounded(
+  command: string,
+  args: string[],
+  input: string,
+  timeoutMs = 120_000,
+): Promise<ProcessResult> {
+  return new Promise((resolvePromise) => {
+    const env = { ...process.env }
+    delete env.CLAUDECODE
+    const child = spawn(command, args, {
+      cwd: cosBrainDir() ?? process.cwd(),
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: false,
+    })
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    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()) })
+    const finish = (result: ProcessResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(result)
+    }
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL') } catch { /* already exited */ }
+      finish({ code: null, stdout, stderr, timedOut: true })
+    }, timeoutMs)
+    timer.unref?.()
+    child.once('error', err => finish({ code: null, stdout, stderr: err.message, timedOut: false }))
+    child.once('close', code => finish({ code, stdout, stderr, timedOut: false }))
+    child.stdin.on('error', () => { /* close/error is authoritative */ })
+    child.stdin.end(input)
+  })
+}
+
+export function claudeProofText(stdout: string): string {
+  try {
+    const parsed = JSON.parse(stdout) as { result?: unknown }
+    return typeof parsed.result === 'string' ? parsed.result.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+export function codexProofText(stdout: string): string {
+  const parts: string[] = []
+  for (const line of stdout.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const event = JSON.parse(line) as any
+      const item = event?.item ?? event?.payload ?? event?.message ?? event
+      const eventType = String(event?.type ?? '').toLowerCase()
+      const itemType = String(item?.type ?? '').toLowerCase()
+      const assistant = /(?:^|[._-])(agent_message|assistant_message|output_text)(?:$|[._-])/.test(eventType)
+        || /^(?:agent_message|assistant_message|output_text)$/.test(itemType)
+      if (!assistant) continue
+      const text = typeof event?.text === 'string' ? event.text
+        : typeof event?.delta === 'string' ? event.delta
+          : typeof item?.text === 'string' ? item.text
+            : ''
+      if (text) parts.push(text)
+    } catch { /* ignore non-JSON CLI chatter */ }
+  }
+  return parts.join('').trim()
+}
+
+function safeProofError(result: ProcessResult): string {
+  if (result.timedOut) return 'provider proof timed out'
+  if (result.code !== 0) return `provider process exited ${result.code ?? 'before launch'}`
+  return 'provider returned no valid proof response'
+}
+
+async function executeProof(provider: ProofProvider): 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,
+    ], '')
+    : await runBounded('codex', [
+      'exec',
+      '--sandbox', 'read-only',
+      '--skip-git-repo-check',
+      '--json',
+      '--cd', cosBrainDir() ?? process.cwd(),
+      '--ephemeral',
+      '-',
+    ], PROOF_PROMPT)
+  const text = provider === 'claude'
+    ? claudeProofText(result.stdout)
+    : codexProofText(result.stdout)
+  const ok = result.code === 0 && text === PROOF_TOKEN
+  return {
+    provider,
+    ok,
+    durationMs: Date.now() - started,
+    cached: false,
+    ...(ok ? {} : { error: safeProofError(result) }),
+  }
+}
+
+/** Actual no-tool model turn, cached only after success for this server boot. */
+export async function runProviderProof(provider: ProofProvider): Promise<ProviderProofResult> {
+  const cached = successCache.get(provider)
+  if (cached) return { ...cached, cached: true }
+  const existing = inFlight.get(provider)
+  if (existing) return existing
+  const operation = executeProof(provider).then(result => {
+    if (result.ok) successCache.set(provider, result)
+    return result
+  }).finally(() => {
+    inFlight.delete(provider)
+  })
+  inFlight.set(provider, operation)
+  return operation
+}

package/server/lib/tts-cache.ts

@@ -495,9 +495,10 @@ function sweepStaleByAge(): void {
   }
 }
 
-/** Allocate a new session UUID pointing at a (hash, text, voice, format)
- *  bundle. The play route consumes the session; expired sessions are reaped
- *  by the periodic sweeper below. */
+/** Allocate a new random v4 session UUID pointing at one
+ *  (hash, text, voice, format) bundle. The play route may reread it for native
+ *  Range refills during the 60-second TTL; expired sessions are rejected and
+ *  reaped by the periodic sweeper below. */
 export function createSession(s: Omit<SessionEntry, 'expiresAt'>): string {
   const uuid = randomUUID()
   sessions.set(uuid, { ...s, expiresAt: Date.now() + SESSION_TTL_MS })

package/server/lib/tts-local.ts

@@ -35,6 +35,9 @@ let localVoice: string | null = null
 let lastFallbackToOpenAI: { at: string; reason: string } | null = null
 let lastHealthProbeAt = 0
 let healthProbeInFlight: Promise<boolean> | null = null
+let retryTimer: ReturnType<typeof setTimeout> | null = null
+let retryAttempt = 0
+let stopRequested = false
 
 const HEALTH_REFRESH_INTERVAL_MS = 2_000
 const HEALTH_REFRESH_TIMEOUT_MS = 400
@@ -84,13 +87,54 @@ function candidatePythons(): string[] {
   return out.filter((p) => p && existsSync(p))
 }
 
-function resolvePython(): string | null {
-  const hits = candidatePythons()
-  return hits[0] ?? null
+/** A path existing is not enough. Upgrades may inherit a Python 3.13 venv or
+ * a partial environment whose imports fail. Probe the exact sidecar runtime
+ * before bypassing bootstrap. */
+async function ttsPythonReady(path: string): Promise<boolean> {
+  const probe = [
+    'import sys',
+    'assert (sys.version_info.major, sys.version_info.minor) in ((3, 11), (3, 12))',
+    'import fastapi, mlx_audio, misaki, numpy, soundfile, uvicorn',
+  ].join('; ')
+  return await new Promise<boolean>((resolvePromise) => {
+    let settled = false
+    const child = spawn(path, ['-c', probe], {
+      stdio: 'ignore',
+      detached: false,
+      env: process.env,
+    })
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { child.kill('SIGKILL') } catch { /* already exited */ }
+      resolvePromise(false)
+    }, 15_000)
+    timer.unref?.()
+    child.once('error', () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(false)
+    })
+    child.once('exit', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(code === 0)
+    })
+  })
+}
+
+async function resolveReadyPython(): Promise<string | null> {
+  for (const path of candidatePythons()) {
+    if (await ttsPythonReady(path)) return path
+    console.warn(`[tts-local] existing Python runtime is incompatible or incomplete: ${path}`)
+  }
+  return null
 }
 
 async function ensureBootstrap(): Promise<string | null> {
-  let py = resolvePython()
+  let py = await resolveReadyPython()
   if (py) return py
   if (!existsSync(BOOTSTRAP)) {
     lastError = `TTS bootstrap missing at ${BOOTSTRAP}`
@@ -119,11 +163,36 @@ async function ensureBootstrap(): Promise<string | null> {
     console.error('[tts-local]', lastError)
     return null
   }
-  py = resolvePython()
-  if (!py) lastError = 'TTS bootstrap finished but python still missing'
+  py = await resolveReadyPython()
+  if (!py) lastError = 'TTS bootstrap finished but its Python runtime is incompatible or incomplete'
   return py
 }
 
+function clearRetryTimer(): void {
+  if (!retryTimer) return
+  clearTimeout(retryTimer)
+  retryTimer = null
+}
+
+function scheduleLocalTtsRetry(): void {
+  if (stopRequested || retryTimer || serverStarting || serverAvailable) return
+  // Retry forever but cap the quiet background cadence at five minutes. This
+  // recovers interrupted first-run model downloads and dependencies installed
+  // after boot without hot-looping a permanently unsupported setup.
+  const delayMs = Math.min(300_000, 10_000 * (2 ** Math.min(retryAttempt, 5)))
+  retryAttempt += 1
+  console.warn(`[tts-local] retrying Kokoro startup in ${Math.round(delayMs / 1000)}s`)
+  retryTimer = setTimeout(() => {
+    retryTimer = null
+    void startLocalTtsServer().catch((err) => {
+      lastError = err instanceof Error ? err.message : String(err)
+      console.error('[tts-local] retry failed:', lastError)
+      scheduleLocalTtsRetry()
+    })
+  }, delayMs)
+  retryTimer.unref?.()
+}
+
 async function probeHealth(timeoutMs = 1500): Promise<boolean> {
   try {
     const res = await fetch(`${TTS_BASE}/health`, {
@@ -227,6 +296,8 @@ export async function startLocalTtsServer(): Promise<void> {
     console.warn('[tts-local]', lastError)
     return
   }
+  stopRequested = false
+  clearRetryTimer()
   serverStarting = true
   try {
     if (await probeHealth(1500)) {
@@ -268,19 +339,24 @@ export async function startLocalTtsServer(): Promise<void> {
       },
     )
     serverProcess = child
+    let childExited = false
     child.on('exit', (code, signal) => {
+      childExited = true
       if (serverProcess === child) {
         serverProcess = null
         serverAvailable = false
         lastError = `sidecar exited code=${code} signal=${signal}`
         console.warn('[tts-local]', lastError)
+        scheduleLocalTtsRetry()
       }
     })
 
     const maxWaitMs = 120_000
     const started = Date.now()
-    while (Date.now() - started < maxWaitMs) {
+    while (Date.now() - started < maxWaitMs && !childExited) {
       if (await probeHealth(1500)) {
+        retryAttempt = 0
+        clearRetryTimer()
         console.log(
           `[tts-local] ready on ${TTS_PORT} engine=${engineVersion} voice=${localVoice} ` +
             `(${((Date.now() - started) / 1000).toFixed(1)}s)`,
@@ -289,17 +365,22 @@ export async function startLocalTtsServer(): Promise<void> {
       }
       await new Promise((r) => setTimeout(r, 1500))
     }
-    lastError = `sidecar startup timeout (${maxWaitMs / 1000}s)`
+    lastError = childExited
+      ? lastError || 'sidecar exited before becoming ready'
+      : `sidecar startup timeout (${maxWaitMs / 1000}s)`
     console.error('[tts-local]', lastError)
     try { child.kill('SIGKILL') } catch { /* ignore */ }
     serverProcess = null
     serverAvailable = false
   } finally {
     serverStarting = false
+    if (!serverAvailable) scheduleLocalTtsRetry()
   }
 }
 
 export function stopLocalTtsServer(): void {
+  stopRequested = true
+  clearRetryTimer()
   if (!serverProcess) return
   try {
     serverProcess.kill('SIGTERM')

package/server/routes/provider-proof.ts

@@ -0,0 +1,19 @@
+import { Router } from 'express'
+import { runProviderProof, type ProofProvider } from '../lib/provider-proof.js'
+
+export const providerProofRouter = Router()
+
+// Authenticated by the global /api token boundary. This performs one real,
+// no-tool model turn and exposes no provider output or credentials.
+providerProofRouter.post('/diagnostics/provider-proof', async (req, res) => {
+  const address = req.socket.remoteAddress ?? ''
+  const loopback = address === '::1' || address === '127.0.0.1'
+    || address.startsWith('127.') || address.startsWith('::ffff:127.')
+  if (!loopback) return res.status(403).json({ error: 'loopback_required' })
+  const provider = req.body?.provider
+  if (provider !== 'claude' && provider !== 'codex') {
+    return res.status(400).json({ error: 'provider must be claude or codex' })
+  }
+  const result = await runProviderProof(provider as ProofProvider)
+  return res.status(result.ok ? 200 : 503).json(result)
+})

package/server/routes/tts.ts

@@ -810,12 +810,14 @@ ttsRouter.post('/tts/stream', async (req, res) => {
 //   1. Client POSTs {text, voice, format} here. We strip+trim+budget-check,
 //      hash the (text, voice, format) tuple, and return a session URL.
 //   2. Client sets audio.src = `${apiBase}${sessionUrl}` and calls .play().
-//   3. The browser GETs /api/tts/play/:session, which consumes the session
-//      and either serves cached bytes (instant) or kicks off OpenAI fresh.
+//   3. The browser GETs /api/tts/play/:session using the session as a bearer
+//      capability. Range refills may reuse it during its 60-second lifetime;
+//      the route serves cached bytes or starts live generation on a cold miss.
 //
 // The two-step pattern is required because authentication on the play route
 // would force XHR (no Range support, no progressive decoding). The session
-// UUID IS the auth — short-lived (60s) and one-shot.
+// UUID IS the auth — cryptographically random, short-lived (60s), and scoped
+// to one prepared audio item. It is re-readable only for native Range refills.
 ttsRouter.post('/tts/prepare', async (req, res) => {
   try {
     const { text, format, instructions, fast } = req.body ?? {}

package/server/tts-sidecar/bootstrap.sh

@@ -5,25 +5,49 @@ ROOT="$(cd "$(dirname "$0")" && pwd)"
 MODEL_DIR="${COS_TTS_MODEL_DIR:-$HOME/.local/share/cos-tts-models}"
 VENV="$MODEL_DIR/.venv"
 PY="${COS_TTS_BOOTSTRAP_PYTHON:-}"
-if [[ -z "$PY" ]]; then
-  if command -v python3.13 >/dev/null 2>&1; then PY="$(command -v python3.13)"
-  elif command -v python3.12 >/dev/null 2>&1; then PY="$(command -v python3.12)"
-  elif command -v python3.11 >/dev/null 2>&1; then PY="$(command -v python3.11)"
-  elif command -v python3 >/dev/null 2>&1; then PY="$(command -v python3)"
-  else
-    echo "[cos-tts] Python 3.11-3.13 is required for local Kokoro" >&2
+
+# The pinned stack has one strict intersection: numpy 2.4.6 requires 3.11+ and
+# misaki 0.9.4 requires <3.13. Select by the interpreter's real version instead
+# of trusting its filename so a newer `python3` alias cannot poison bootstrap.
+python_minor() {
+  "$1" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null
+}
+
+python_is_compatible() {
+  local minor
+  minor="$(python_minor "$1")" || return 1
+  [[ "$minor" == "3.11" || "$minor" == "3.12" ]]
+}
+
+if [[ -n "$PY" ]]; then
+  if [[ ! -x "$PY" ]] || ! python_is_compatible "$PY"; then
+    PY_MINOR="$(python_minor "$PY" 2>/dev/null || echo unknown)"
+    echo "[cos-tts] COS_TTS_BOOTSTRAP_PYTHON is Python $PY_MINOR; pinned Kokoro requires Python 3.11 or 3.12" >&2
     exit 2
   fi
-fi
-PY_MINOR="$($PY -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
-case "$PY_MINOR" in
-  3.11|3.12|3.13) ;;
-  *)
-    echo "[cos-tts] unsupported Python $PY_MINOR; install Python 3.11, 3.12, or 3.13" >&2
+else
+  for candidate in python3.12 python3.11 python3; do
+    candidate_path="$(command -v "$candidate" 2>/dev/null || true)"
+    if [[ -n "$candidate_path" ]] && python_is_compatible "$candidate_path"; then
+      PY="$candidate_path"
+      break
+    fi
+  done
+  if [[ -z "$PY" ]]; then
+    echo "[cos-tts] compatible Python not found; install Python 3.12 with: brew install python@3.12" >&2
     exit 2
-    ;;
-esac
+  fi
+fi
+
 mkdir -p "$MODEL_DIR"
+if [[ -x "$VENV/bin/python" ]] && ! python_is_compatible "$VENV/bin/python"; then
+  VENV_MINOR="$(python_minor "$VENV/bin/python" 2>/dev/null || echo unknown)"
+  echo "[cos-tts] rebuilding incompatible Python $VENV_MINOR venv"
+  rm -rf -- "$VENV"
+elif [[ -d "$VENV" && ! -x "$VENV/bin/python" ]]; then
+  echo "[cos-tts] rebuilding incomplete venv"
+  rm -rf -- "$VENV"
+fi
 if [[ ! -x "$VENV/bin/python" ]]; then
   echo "[cos-tts] creating venv at $VENV with $PY"
   "$PY" -m venv "$VENV"