@gotcos/glasses-server 6.15.1 → 6.15.3

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,23 @@
+## 6.15.3
+
+- Make `COS_WORKDIR` the authoritative Claude, Codex, and Cursor workspace.
+  Legacy provider-specific and `COS_SCRIPTS_DIR` paths remain compatibility
+  fallbacks, so pipeline scripts can stay separate from the agent workspace.
+- Add workspace-precedence coverage for migrated LaunchAgent environments.
+
+## 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

package/README.md

@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.15.1",
+  "version": "6.15.3",
   "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'
@@ -70,6 +71,7 @@ import { requireApiToken } from './lib/api-auth.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
 import {
   acquireMaintenanceWork,
+  maintenanceOperationCredentialsValid,
   MaintenanceLifecycleError,
   maintenanceAdmissionsOpen,
   maintenanceErrorPayload,
@@ -158,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
@@ -196,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/claude-bridge.ts

@@ -11,7 +11,7 @@ import { writeFileSync, readFileSync, unlinkSync, existsSync } from 'node:fs'
 import { appendFileSync } from 'node:fs'
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
 import { cleanupModelImageInputs, type ModelImageInput } from './model-image-input.js'
-import { cosBrainDir } from './launch-dir.js'
+import { resolveProviderWorkDir } from './launch-dir.js'
 import { logTokenAudit } from './token-audit.js'
 import { buildSystemPrompt, buildLightweightSystemPrompt, buildPrewarmSystemPrompt, getCachedContextInstant } from './context-builder.js'
 import { getHistory, addExchange, setExchangeAttachments, removeExchange, formatHistoryForPrompt, getOrCreateSession, isNewSession, markSessionNotified, getSessionModel, getSessionRaw, replaceLastExchangeWithSummary, type ModelPreference, type PromptReference } from './conversation.js'
@@ -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'
 
@@ -220,7 +225,7 @@ export async function preWarmCLI(): Promise<void> {
     ], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
-      cwd: COS_SCRIPTS_DIR ?? cosBrainDir() ?? process.cwd(),
+      cwd: resolveProviderWorkDir({ scriptsDir: COS_SCRIPTS_DIR }),
     })
 
     let buffer = ''
@@ -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')
   }
@@ -518,7 +528,7 @@ export async function callClaudeStreaming(
   const env = { ...process.env }
   delete env.CLAUDECODE
   if (outputImagePublisher) Object.assign(env, outputImagePublisher.env)
-  const cliCwd = COS_SCRIPTS_DIR ?? cosBrainDir() ?? process.cwd()
+  const cliCwd = resolveProviderWorkDir({ scriptsDir: COS_SCRIPTS_DIR })
   const inactivityMs = INACTIVITY_BY_MODEL[resolvedModel]
   const defaultWallMax = WALL_MAX_BY_MODEL[resolvedModel]
   const effortWallMax = resolvedEffort === 'max' || resolvedEffort === 'ultracode'

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/codex-run-ledger.ts

@@ -2,7 +2,7 @@ import crypto from 'node:crypto'
 import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
-import { cosBrainDir } from './launch-dir.js'
+import { resolveProviderWorkDir } from './launch-dir.js'
 import { CODEX_ENGINE_SESSION_TTL_MS, type CodexTrustMode } from './codex-engine-sessions.js'
 import {
   CODEX_FRONTIER_MODEL,
@@ -84,16 +84,10 @@ export function areCodexContentPreviewsEnabled(): boolean {
 }
 
 export function getCodexExecutionCwd(): string {
-  const configured = process.env.CODEX_GLASSES_WORKDIR?.trim()
-  if (configured) return resolve(configured)
-  if (COS_SCRIPTS_DIR) return resolve(COS_SCRIPTS_DIR, '..', '..')
-  // A Starter-Kit COS in the directory the user launched npx from — Codex
-  // loads its AGENTS.md brain natively when run there.
-  const brain = cosBrainDir()
-  if (brain) return brain
-  // Last resort when neither CODEX_GLASSES_WORKDIR nor COS_SCRIPTS_DIR is set:
-  // the server's own working dir (codex glasses is an optional, env-configured feature).
-  return process.cwd()
+  return resolveProviderWorkDir({
+    legacyProviderDir: process.env.CODEX_GLASSES_WORKDIR,
+    scriptsDir: COS_SCRIPTS_DIR,
+  })
 }
 
 export function getCodexTrustMode(): CodexTrustMode {

package/server/lib/launch-dir.ts

@@ -7,8 +7,9 @@
 // spawns of claude/codex use IT as their working directory — so the CLIs load
 // the user's brain exactly as they would in a terminal session in that folder.
 //
-// Precedence stays: COS_SCRIPTS_DIR (full COS pipeline) > detected brain dir >
-// process.cwd(). Explicit config always wins.
+// Provider precedence is: selected COS_WORKDIR > legacy provider override >
+// COS_SCRIPTS_DIR repository root > process.cwd(). Pipeline data still uses
+// COS_SCRIPTS_DIR independently.
 import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
@@ -33,3 +34,28 @@ export function cosBrainDir(): string | null {
   cached = resolveCosBrainDir(process.env.COS_WORKDIR ?? process.env.COS_LAUNCH_DIR)
   return cached
 }
+
+/**
+ * Resolve the provider working directory from one authoritative contract.
+ * COS_WORKDIR (via cosBrainDir) is the user-selected agent workspace and must
+ * outrank legacy provider-specific and pipeline locations. COS_SCRIPTS_DIR is
+ * still used by the Python pipeline; it is only a cwd fallback here.
+ */
+export function resolveProviderWorkDir(options: {
+  legacyProviderDir?: string | null
+  scriptsDir?: string | null
+  fallback?: string
+} = {}): string {
+  const brain = cosBrainDir()
+  if (brain) return brain
+  const legacy = options.legacyProviderDir?.trim()
+  if (legacy) return resolve(legacy)
+  const scripts = options.scriptsDir?.trim()
+  if (scripts) return resolve(scripts, '..', '..')
+  return resolve(options.fallback ?? process.cwd())
+}
+
+/** Test-only cache reset for environment-precedence coverage. */
+export function resetCosBrainDirCacheForTests(): void {
+  cached = undefined
+}

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