@gotcos/glasses-server 6.12.0 → 6.12.2

package/.env.example

@@ -38,7 +38,7 @@ BIND_HOST=0.0.0.0
 
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
-#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
+#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://docs.anthropic.com/en/docs/claude-code/getting-started, then `claude auth login`)
 #   GPT Frontier/Balanced  ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
 # Install at least one. Pick the default model the glasses use:
 # COS_G2_DEFAULT_MODEL=sonnet     # opus | fable | sonnet | codex-frontier | codex-balanced

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 6.12.2
+
+First-install hardening for public `npx` users.
+
+- **No nested install inside npm's cache.** The launcher resolves the declared
+  `tsx` dependency from npm's existing `npx` dependency tree and never runs a
+  second `npm install` from the ephemeral package directory.
+- **Permission failures do not spread.** A broken or incomplete package fails
+  closed with a user-owned isolated-cache recovery command. COS never suggests
+  `sudo npm`, broad ownership changes, or writing through a root-owned cache.
+- **Claude Desktop is no longer mistaken for Claude Code.** First-run guidance
+  explicitly requires the terminal CLI, keeps the scoped npm command on one
+  copyable line, forbids `sudo`, and explains the interactive sign-in step.
+- **Known signed-out agents fail before startup.** Installed Claude/Codex
+  binaries are checked before first-query readiness. Older CLI versions whose
+  authentication state cannot be proven show a warning instead of a false
+  signed-in claim.
+- **Local credentials are private.** `~/.cos-glasses` is repaired to `0700`;
+  the token and profile files are repaired to `0600`; symlinked credential
+  paths fail closed; auto-generated tokens are persisted with an atomic write.
+- **Runtime behavior is unchanged.** Query, prompt recovery, meetings, media,
+  diagnostics, transcription, display, and server data contracts are untouched.
+
+## 6.12.1
+
+Public-safe CLI diagnostics for the COS Glasses Recovery Center.
+
+- **Both local agents are visible.** Authenticated clients can inspect a
+  versioned Claude Code and Codex status summary at `/api/cli/debug`, including
+  provider support, persistence readiness, workspace configuration, and the
+  latest run's safe status metadata.
+- **False success is fenced.** Claude Code or Codex output that reports a
+  machine-shaped authentication failure while the CLI exits `0` is finalized
+  as a typed `auth_error`, never projected as a completed assistant reply.
+- **Build 210 stays compatible.** Sanitized `/api/cli/runs` and
+  `/api/codex/runs` projections preserve the fields older Recovery Centers can
+  render while newer clients adopt the combined contract.
+- **Diagnostics do not become an exfiltration path.** Responses use explicit
+  allowlists and omit commands, filesystem paths, trust modes, prompts,
+  answers, tool payloads, content previews, raw run/session/thread IDs,
+  resumable handles, environment values, and tokens. Legacy display IDs are
+  omitted and workspace state is a fixed label only.
+- **Authentication is mandatory.** All three diagnostic routes remain behind
+  the existing `/api` token boundary. Preview-enabled ledger fixtures are
+  covered by recursive forbidden-field and private-value tests.
+- **Unauthenticated health is capability-only.** `/api/health` and
+  `/api/models` advertise `capabilities.cliDebug`; health exposes only a CLI
+  session-availability boolean rather than the resumable session ID.
+- **Backward compatible.** Query, prompt, meeting, media, display, model, and
+  recovery behavior is unchanged. Older clients and servers continue to use
+  their existing paths; a missing CLI Debug capability remains an unsupported
+  feature rather than a connection failure.
+
 ## 6.12.0
 
 Local-first transcription policy and capability-safe recovery diagnostics for

package/README.md

@@ -8,7 +8,7 @@ API key is pasted into the phone for chat.
 ## Quick start
 
 ```bash
-npx @gotcos/glasses-server
+npx --yes @gotcos/glasses-server@latest
 ```
 
 The launcher checks Node, finds your CLI, checks voice and image processing,
@@ -24,7 +24,10 @@ without silently losing completed replies.
 ## Requirements
 
 - **Node.js 20.11+** — https://nodejs.org
-- **Claude Code CLI** (Opus/Fable/Sonnet) — https://claude.ai/download, then `claude login`
+- **Claude Code CLI** (Opus/Fable/Sonnet). Claude Desktop alone does not install
+  the terminal command. Install it on one line with
+  `npm install -g @anthropic-ai/claude-code` (**never with `sudo`**), then run
+  `claude` and finish the browser sign-in
   _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)
@@ -106,9 +109,20 @@ BIND_HOST=0.0.0.0 npm run start:server
 
 ## Troubleshooting
 
+- *Claude Desktop is installed but COS says Claude Code is missing* — Desktop
+  and the terminal CLI are separate. Run
+  `npm install -g @anthropic-ai/claude-code` on one line without `sudo`, then
+  run `claude` and complete sign-in. Verify with `claude --version` before
+  starting COS again.
+- *npm reports EACCES or a root-owned cache* — never run COS or npm with
+  `sudo`, and do not recursively change system ownership. Use a private COS
+  cache instead:
+  `npm_config_cache="$HOME/.cos-glasses/npm-cache" npx --yes @gotcos/glasses-server@latest`.
+  Version 6.12.2+ never runs a second install from inside npm's temporary cache.
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
-- *Safari connects but the app does not* — confirm `npx @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
-- *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
+- *Safari connects but the app does not* — confirm `npx --yes @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
+- *AI queries fail* — run `claude auth status` / `codex login status`, then
+  `claude auth login` / `codex login` when the provider reports signed out.
 - *Voice getting billed?* — voice is local-only by default in 6.12.0+. Confirm
   `/api/health` reports `capabilities.transcription.mode: "local-only"`. Remove
   `COS_OPENAI_WHISPER_FALLBACK` (or set it to `0`) to disable an earlier opt-in.
@@ -117,7 +131,7 @@ 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.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
-- *Prompt recovery unavailable?* — update with `npx @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
+- *Prompt recovery unavailable?* — update with `npx --yes @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
 - *Durable query recovery unavailable?* — build 204+ requires server 6.10.0+ and
   `COS_DURABLE_QUERY_JOBS=1`. Restart once, then confirm `/api/health` reports
   `features.durableQueryJobs: true`, protocol `1`, and state `ready`. To roll

package/bin/cli.cjs

@@ -5,7 +5,17 @@
 // package — there is no clone. Config persists at ~/.cos-glasses/.
 
 const { execSync, spawn } = require('child_process')
-const { existsSync, mkdirSync, statSync, readFileSync, copyFileSync, unlinkSync, renameSync } = require('fs')
+const {
+  existsSync,
+  mkdirSync,
+  statSync,
+  lstatSync,
+  readFileSync,
+  copyFileSync,
+  unlinkSync,
+  renameSync,
+  chmodSync,
+} = require('fs')
 const { join, resolve } = require('path')
 const { homedir } = require('os')
 
@@ -30,11 +40,11 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(bold('  COS Glasses Server'))
   console.log('')
   console.log('  Usage:')
-  console.log('    npx @gotcos/glasses-server')
+  console.log('    npx --yes @gotcos/glasses-server@latest')
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')
-  console.log('    - Claude Code CLI (Opus / Fable / Sonnet) or Codex CLI (GPT Frontier / Balanced)')
+  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('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
@@ -72,52 +82,142 @@ function normalizeCodexVersion(raw) {
   const line = raw.split('\n').map((s) => s.trim()).find((s) => /^codex(?:-cli)?\s+/i.test(s)) || raw.split('\n')[0].trim()
   return line.replace(/^codex(?:-cli)?\s*/i, '') || line
 }
+function commandResult(command) {
+  try {
+    return {
+      ok: true,
+      output: execSync(`${command} 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim(),
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      output: (err.stdout?.toString() || err.stderr?.toString() || '').trim(),
+    }
+  }
+}
+function claudeAuthState() {
+  const result = commandResult('claude auth status --json')
+  try {
+    const parsed = JSON.parse(result.output)
+    if (parsed.loggedIn === true) return 'ready'
+    if (parsed.loggedIn === false) return 'signed-out'
+  } catch { /* older CLIs may not support JSON status */ }
+  if (/not logged in|logged out|sign[ -]?in required/i.test(result.output)) return 'signed-out'
+  return 'unknown'
+}
+function codexAuthState() {
+  const result = commandResult('codex login status')
+  if (/logged in/i.test(result.output) && !/not logged in/i.test(result.output)) return 'ready'
+  if (/not logged in|logged out|sign[ -]?in required/i.test(result.output)) return 'signed-out'
+  return 'unknown'
+}
 const claudeVersion = getCliVersion('claude')
 const codexVersion = getCliVersion('codex')
+const claudeAuth = claudeVersion ? claudeAuthState() : null
+const codexAuth = codexVersion ? codexAuthState() : null
 if (claudeVersion) {
-  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
+  if (claudeAuth === 'signed-out') {
+    console.log(yellow('  ⚠') + ` Claude Code ${claudeVersion} installed — sign-in required`)
+    console.log('    Run: ' + bold('claude auth login'))
+  } else if (claudeAuth === 'unknown') {
+    console.log(yellow('  ⚠') + ` Claude Code ${claudeVersion} installed — sign-in status unavailable`)
+    console.log('    Verify: ' + bold('claude auth status'))
+  } else {
+    console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
+  }
 } else {
   console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Fable/Sonnet unavailable'))
-  console.log('    Install: ' + bold('https://claude.ai/download'))
+  console.log('    Claude Desktop does not install the terminal CLI.')
+  console.log('    Install (no sudo): ' + bold('npm install -g @anthropic-ai/claude-code'))
+  console.log('    Then run:          ' + bold('claude') + ' and finish sign-in')
 }
 if (codexVersion) {
-  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
+  if (codexAuth === 'signed-out') {
+    console.log(yellow('  ⚠') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} installed — sign-in required`)
+    console.log('    Run: ' + bold('codex login'))
+  } else if (codexAuth === 'unknown') {
+    console.log(yellow('  ⚠') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} installed — sign-in status unavailable`)
+    console.log('    Verify: ' + bold('codex login status'))
+  } else {
+    console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
+  }
 } else {
   console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— GPT Frontier/Balanced unavailable'))
 }
-if (!claudeVersion && !codexVersion) {
+const hasUsableAgent = (claudeVersion && claudeAuth !== 'signed-out') || (codexVersion && codexAuth !== 'signed-out')
+if (!hasUsableAgent) {
   console.log('')
-  console.log(red('  ✗ No supported agent CLI found'))
-  console.log('    Install Claude Code: ' + bold('https://claude.ai/download'))
+  console.log(red('  ✗ No signed-in agent CLI is ready'))
+  console.log('    Claude Desktop alone is not enough; COS needs a terminal CLI.')
+  console.log('    Install Claude Code (no sudo): ' + bold('npm install -g @anthropic-ai/claude-code'))
+  console.log('    Then run:                       ' + bold('claude auth login'))
   console.log('    or Codex CLI:        ' + bold('https://developers.openai.com/codex/') + ' then ' + bold('codex login'))
+  console.log('    Setup help:          ' + bold('https://www.gotcos.com/wizard/'))
   console.log('')
   process.exit(1)
 }
 
-// Step 3: dependencies — only when run from a git clone without node_modules.
-// `npx` already installed the package's deps alongside it.
-if (!existsSync(join(PKG_ROOT, 'node_modules'))) {
+// Step 3: resolve the dependency npm already installed. With `npx`, dependency
+// packages are siblings in npm's temporary node_modules tree rather than under
+// PKG_ROOT/node_modules. Running a second `npm install` from inside that cache
+// is both unnecessary and unsafe: a prior sudo-based npm install can make the
+// shared cache root-owned and turn an otherwise valid first launch into EACCES.
+let tsxImport
+try {
+  tsxImport = require.resolve('tsx/esm', { paths: [PKG_ROOT] })
+} catch {
   console.log('')
-  console.log(`  ${yellow('⟳')} Installing dependencies...`)
-  try {
-    execSync('npm install', { cwd: PKG_ROOT, stdio: 'pipe', timeout: 300000 })
-    console.log(green('  ✓') + ' Dependencies installed')
-  } catch (err) {
-    console.log(red('  ✗ npm install failed'))
-    console.log(`    ${err.stderr?.toString().slice(0, 200) || err.message}`)
-    process.exit(1)
-  }
+  console.log(red('  ✗ COS package dependencies are incomplete'))
+  console.log('    Do not use sudo. Retry with an isolated user-owned npm cache:')
+  console.log('    ' + bold('npm_config_cache="$HOME/.cos-glasses/npm-cache" npx --yes @gotcos/glasses-server@latest'))
+  console.log('    Source installs only: run ' + bold('npm install') + ' in the cloned repository.')
+  process.exit(1)
 }
 
 // Step 4: persistent config at ~/.cos-glasses/ (survives npx cache churn)
-mkdirSync(CONFIG_DIR, { recursive: true })
+function securePrivateDirectory(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stats = lstatSync(dir)
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`${dir} must be a private directory, not a symlink`)
+  }
+  chmodSync(dir, 0o700)
+}
+
+function securePrivateFile(file) {
+  if (!existsSync(file)) return
+  const stats = lstatSync(file)
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error(`${file} must be a regular file, not a symlink`)
+  }
+  chmodSync(file, 0o600)
+}
+
+try {
+  securePrivateDirectory(CONFIG_DIR)
+} catch (err) {
+  console.log('')
+  console.log(red('  ✗ COS config directory is unsafe'))
+  console.log(`    ${err.message}`)
+  console.log('    Move it aside and rerun COS; do not use sudo or broad ownership changes.')
+  process.exit(1)
+}
 const ENV_FILE = join(CONFIG_DIR, '.env')
 const ENV_EXAMPLE = join(PKG_ROOT, '.env.example')
 if (!existsSync(ENV_FILE) && existsSync(ENV_EXAMPLE)) {
   copyFileSync(ENV_EXAMPLE, ENV_FILE)
+  chmodSync(ENV_FILE, 0o600)
   console.log(green('  ✓') + ` Created config at ${dim(ENV_FILE)}`)
 }
 if (existsSync(ENV_FILE)) {
+  try {
+    securePrivateFile(ENV_FILE)
+  } catch (err) {
+    console.log('')
+    console.log(red('  ✗ COS config file is unsafe'))
+    console.log(`    ${err.message}`)
+    process.exit(1)
+  }
   try {
     for (const line of readFileSync(ENV_FILE, 'utf-8').split('\n')) {
       const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)=(.*)$/)
@@ -130,6 +230,15 @@ const PROFILE_FILE = join(CONFIG_DIR, '.cos-profile.json')
 const PROFILE_EXAMPLE = join(PKG_ROOT, '.cos-profile.example.json')
 if (!existsSync(PROFILE_FILE) && existsSync(PROFILE_EXAMPLE)) {
   copyFileSync(PROFILE_EXAMPLE, PROFILE_FILE)
+  chmodSync(PROFILE_FILE, 0o600)
+}
+try {
+  securePrivateFile(PROFILE_FILE)
+} catch (err) {
+  console.log('')
+  console.log(red('  ✗ COS profile is unsafe'))
+  console.log(`    ${err.message}`)
+  process.exit(1)
 }
 if (!process.env.COS_PROFILE_PATH) process.env.COS_PROFILE_PATH = PROFILE_FILE
 
@@ -156,14 +265,15 @@ function isValidWhisperModel(p) {
 }
 const whisperCliPath = findWhisperCli()
 const hasValidModel = isValidWhisperModel(WHISPER_MODEL_PATH)
+let localVoiceReady = Boolean(whisperCliPath && hasValidModel)
 if (whisperCliPath && hasValidModel) {
   console.log(green('  ✓') + ' whisper.cpp + model ready ' + dim('— voice = local (FREE)'))
 } else if (whisperCliPath && !hasValidModel) {
   if (existsSync(WHISPER_MODEL_PATH)) { try { unlinkSync(WHISPER_MODEL_PATH) } catch {} }
   if (existsSync(WHISPER_MODEL_PARTIAL)) { try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {} }
   console.log(yellow('  ⚠') + ' whisper.cpp installed but model missing')
-  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB). Ctrl-C to skip (voice remains unavailable by default).'))
-  console.log('    ' + dim('Skip permanently: SKIP_WHISPER_DOWNLOAD=1 npx @gotcos/glasses-server'))
+  console.log('    ' + dim('Downloading ggml-large-v3-turbo (~1.5 GB).'))
+  console.log('    ' + dim('Skip: SKIP_WHISPER_DOWNLOAD=1 npx --yes @gotcos/glasses-server@latest'))
   if (process.env.SKIP_WHISPER_DOWNLOAD === '1') {
     console.log(yellow('  ⚠') + ' SKIP_WHISPER_DOWNLOAD=1 — local voice unavailable')
   } else {
@@ -173,6 +283,7 @@ if (whisperCliPath && hasValidModel) {
       const stats = statSync(WHISPER_MODEL_PARTIAL)
       if (stats.size < WHISPER_MODEL_MIN_BYTES) throw new Error(`Downloaded file too small: ${stats.size} bytes`)
       renameSync(WHISPER_MODEL_PARTIAL, WHISPER_MODEL_PATH)
+      localVoiceReady = true
       console.log(green('  ✓') + ' Model downloaded ' + dim('— voice = local (FREE)'))
     } catch (err) {
       try { unlinkSync(WHISPER_MODEL_PARTIAL) } catch {}
@@ -215,17 +326,23 @@ try {
     console.log(green('  ✓') + ` COS detected in ${dim(ld)} — glasses chat will load its brain`)
   }
 } catch { /* detection is best-effort */ }
+if (!localVoiceReady) {
+  console.log('')
+  console.log(yellow('  ⚠ LOCAL VOICE NOT READY'))
+  console.log('    Text chat can start. Under the default local-only policy, voice prompts remain unavailable.')
+  console.log('    Install: ' + bold('brew install whisper-cpp'))
+  console.log('    Then stop COS with Ctrl-C and rerun: ' + bold('npx --yes @gotcos/glasses-server@latest'))
+}
 console.log('')
 console.log(dim('  Starting server...'))
 console.log('')
 const serverProc = spawn(
   process.execPath,
-  ['--import', 'tsx/esm', 'server/index.ts'],
+  ['--import', tsxImport, 'server/index.ts'],
   { cwd: PKG_ROOT, stdio: 'inherit', env: { ...process.env } }
 )
 serverProc.on('error', (err) => {
   console.error(red(`  Server failed to start: ${err.message}`))
-  if (err.message.includes('tsx')) console.error('  Try: cd ' + PKG_ROOT + ' && npm install')
   process.exit(1)
 })
 serverProc.on('exit', (code) => process.exit(code ?? 0))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.12.0",
+  "version": "6.12.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

@@ -7,7 +7,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createServer as createHttpsServer } from 'node:https'
 import { createServer as createHttpServer } from 'node:http'
-import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
 import { networkInterfaces, homedir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
@@ -27,6 +27,7 @@ import { archiveRouter } from './routes/archive.js'
 import { sessionsRouter } from './routes/sessions.js'
 import { mediaRouter, mediaBodyParser } from './routes/media.js'
 import { promptDraftsRouter } from './routes/prompt-drafts.js'
+import { cliDebugRouter } from './routes/cli-debug.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { getCodexRunConfig } from './lib/codex-run-ledger.js'
@@ -43,6 +44,7 @@ import { getMediaStore } from './lib/media-store.js'
 import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
 import { serverMetrics } from './lib/server-metrics.js'
 import { initializeServerInstanceId } from './lib/server-instance-id.js'
+import { appendPrivateEnvBlock, UnsafeUserConfigPathError } from './lib/secure-user-config.js'
 import { createQueryJobsRouter } from './routes/query-jobs.js'
 import {
   initQueryJobRuntime,
@@ -75,10 +77,16 @@ let API_TOKEN_PERSISTED = false
 if (API_TOKEN_AUTO) {
   try {
     const envDir = join(homedir(), '.cos-glasses')
-    mkdirSync(envDir, { recursive: true })
-    appendFileSync(join(envDir, '.env'), `\n# auto-generated by the server so the app token survives restarts\nCOS_API_TOKEN=${API_TOKEN}\n`)
+    appendPrivateEnvBlock(
+      join(envDir, '.env'),
+      `# auto-generated by the server so the app token survives restarts\nCOS_API_TOKEN=${API_TOKEN}\n`,
+    )
     API_TOKEN_PERSISTED = true
-  } catch { /* read-only home — token stays per-session */ }
+  } catch (error) {
+    // Read-only homes may continue with a per-session token, but an unsafe
+    // symlinked credential path must fail closed instead of being ignored.
+    if (error instanceof UnsafeUserConfigPathError) throw error
+  }
 }
 
 // IP allowlist — only accept connections from localhost, meshnet, and private networks.
@@ -163,6 +171,7 @@ app.use('/api', archiveRouter)
 app.use('/api', sessionsRouter)
 app.use('/api', mediaRouter)
 app.use('/api', promptDraftsRouter)
+app.use('/api', cliDebugRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -292,7 +301,7 @@ listenRequiredServers(listeners).then(() => {
     claudeAvailable = true
     console.log('[COS API] Claude Code CLI detected')
   } catch {
-    console.warn('[COS API] Claude Code CLI not found — install from https://claude.ai/download')
+    console.warn('[COS API] Claude Code CLI not found — install from https://docs.anthropic.com/en/docs/claude-code/getting-started')
     console.warn('[COS API]   Claude models unavailable; Codex models still work when Codex CLI is installed')
   }
 

package/server/lib/claude-bridge.ts

@@ -47,6 +47,7 @@ import {
   MAX_ATTACHMENTS_PER_PROMPT,
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
+import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 
 // Inactivity = no stdout data for this long → kill (catches stalls)
 const INACTIVITY_BY_MODEL: Record<ClaudeModelPreference, number> = {
@@ -325,12 +326,15 @@ export interface StreamCallbacks {
 /** Claude CLI can emit `subtype: success` with `is_error: true`; the boolean
  * is authoritative and must win before session ids or result text are saved. */
 export function claudeResultErrorMessage(event: any): string | null {
-  if (event?.type !== 'result' || (event?.is_error !== true && event?.subtype !== 'error')) return null
+  if (event?.type !== 'result') return null
   const raw = typeof event?.result === 'string' ? event.result
     : typeof event?.error === 'string' ? event.error
     : typeof event?.error?.message === 'string' ? event.error.message
       : typeof event?.message === 'string' ? event.message
         : ''
+  const authFailure = terminalProviderAuthFailure('claude', raw, event?.error)
+  if (authFailure) return authFailure
+  if (event?.is_error !== true && event?.subtype !== 'error') return null
   const detail = raw.replace(/\s+/g, ' ').trim().slice(0, 240)
   return detail ? `claude-bridge: ${detail}` : 'claude-bridge: Claude CLI returned an error result.'
 }
@@ -545,6 +549,7 @@ export async function callClaudeStreaming(
   let stderr = ''
   let buffer = ''
   let finalized = false        // Guard against double onDone/onError
+  let terminalTextError: string | null = null
   let lastActivity = Date.now() // Tracks last stdout data for inactivity timeout
   let receivedStreamEvents = false  // Track if CLI emits stream_event (vs older assistant-only format)
   const toolInputs = new Map<number, { name: string; json: string }>()
@@ -570,6 +575,13 @@ export async function callClaudeStreaming(
 
   async function finalize(text: string) {
     if (finalized) return
+    const responseAuthFailure = terminalProviderAuthFailure('claude', text)
+    const authFailure = responseAuthFailure
+      ?? (!text.trim() ? terminalTextError ?? terminalProviderAuthFailure('claude', stderr) : null)
+    if (authFailure) {
+      await finalizeError(authFailure, 0)
+      return
+    }
     finalized = true
     cleanup()
     cleanupImages()
@@ -831,9 +843,16 @@ export async function callClaudeStreaming(
               text = event.content
             }
             if (text) {
-              phase = 'generating'
-              fullText += text
-              callbacks.onChunk(text)
+              // Withhold only strongly machine-shaped provider auth output so
+              // credentials cannot flash through onChunk. Human sign-in
+              // instructions do not match the terminal classifier.
+              const authFailure = terminalProviderAuthFailure('claude', text)
+              if (authFailure) terminalTextError = authFailure
+              else {
+                phase = 'generating'
+                fullText += text
+                callbacks.onChunk(text)
+              }
             }
           }
         } else if (event.type === 'user') {
@@ -855,7 +874,9 @@ export async function callClaudeStreaming(
         }
         // tool_use/tool_result/other events still reset inactivity (we got stdout data)
       } catch {
-        // Not valid JSON — ignore partial lines
+        // Older CLI builds can emit a terminal auth error as plain text while
+        // still exiting 0. Remember only the canonical classification.
+        terminalTextError ??= terminalProviderAuthFailure('claude', trimmed)
       }
     }
   })
@@ -883,13 +904,19 @@ export async function callClaudeStreaming(
       } catch { /* ignore */ }
     }
 
-    if (code !== 0 && !fullText) {
-      finalizeError(`claude-bridge: exit ${code} — ${stderr.trim().slice(0, 200)}`, code)
-    } else if (fullText) {
-      // If we got text but no explicit result event, still finalize
+    if (fullText) {
+      // If we got text but no explicit result event, still finalize. A sole,
+      // machine-shaped auth response is classified inside finalize.
       void finalize(fullText)
     } else {
-      finalizeError('claude-bridge: Claude completed without a response.', code)
+      const authFailure = terminalTextError ?? terminalProviderAuthFailure('claude', stderr, buffer)
+      if (authFailure) {
+        finalizeError(authFailure, code)
+      } else if (code !== 0) {
+        finalizeError(`claude-bridge: exit ${code} — ${stderr.trim().slice(0, 200)}`, code)
+      } else {
+        finalizeError('claude-bridge: Claude completed without a response.', code)
+      }
     }
   })
 

package/server/lib/cli-debug-view.ts

@@ -0,0 +1,213 @@
+import type { ClaudeRunConfig, ClaudeRunRecord } from './claude-run-ledger.js'
+import type { CodexRunConfig, CodexRunRecord } from './codex-run-ledger.js'
+
+export const CLI_DEBUG_CAPABILITY = Object.freeze({
+  schemaVersion: 1,
+  providers: Object.freeze({ claude: true, codex: true }),
+  metadataOnly: true,
+})
+
+export type SafeCliRunStatus =
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'client_disconnected'
+
+export interface SafeCliDebugLatestRun {
+  status: SafeCliRunStatus
+  model: string
+  concreteModel?: string
+  effort?: string
+  resumed: boolean
+  durationMs?: number
+  updatedAt: string
+  errorCode?: string
+}
+
+export interface SafeCliDebugProvider {
+  supported: true
+  persistenceEnabled: boolean
+  workspaceConfigured: boolean
+  latestRun: SafeCliDebugLatestRun | null
+}
+
+export interface SafeCliDebugResponse {
+  schemaVersion: 1
+  providers: {
+    claude: SafeCliDebugProvider
+    codex: SafeCliDebugProvider
+  }
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function optionalFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined
+}
+
+function safeStatus(value: unknown): SafeCliRunStatus {
+  return value === 'running' || value === 'completed' || value === 'failed'
+    || value === 'cancelled' || value === 'client_disconnected'
+    ? value
+    : 'failed'
+}
+
+function safeModelLabel(value: unknown, provider: 'claude' | 'codex'): string | undefined {
+  const model = optionalString(value)
+  if (!model || model.length > 96) return undefined
+  const allowed = provider === 'claude'
+    ? /^(?:claude-|opus(?:\[1m\])?$|sonnet(?:\[1m\])?$|fable(?:\[1m\])?$|haiku(?:\[1m\])?$)[a-z0-9._\[\]-]*$/i
+    : /^(?:gpt-|codex-)[a-z0-9._\[\]-]*$/i
+  return allowed.test(model) ? model : undefined
+}
+
+function safeEffort(value: unknown): string | undefined {
+  const effort = optionalString(value)?.toLowerCase()
+  return effort && ['low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode'].includes(effort)
+    ? effort
+    : undefined
+}
+
+function safeTimestamp(value: unknown): string {
+  const timestamp = optionalString(value)
+  const parsed = timestamp ? Date.parse(timestamp) : Number.NaN
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : new Date(0).toISOString()
+}
+
+function safeErrorCode(provider: 'claude' | 'codex', value: unknown): string | undefined {
+  const candidate = optionalString(value)
+  if (!candidate) return undefined
+  const allowed = new Set([
+    `${provider}.cli_unavailable`,
+    `${provider}.permission_denied`,
+    `${provider}.auth_error`,
+    `${provider}.timeout`,
+    `${provider}.nonzero_exit`,
+    `${provider}.error`,
+    `${provider}.interrupted`,
+  ])
+  return allowed.has(candidate) ? candidate : `${provider}.error`
+}
+
+export function safeClaudeLatestRun(run?: ClaudeRunRecord): SafeCliDebugLatestRun | null {
+  if (!run) return null
+  const concreteModel = safeModelLabel(run.resolvedModelId ?? run.cliModelId, 'claude')
+  const effort = safeEffort(run.effortLevel)
+  const errorCode = safeErrorCode('claude', run.errorCode)
+  return {
+    status: safeStatus(run.status),
+    model: safeModelLabel(run.model, 'claude') ?? 'unknown',
+    ...(concreteModel ? { concreteModel } : {}),
+    ...(effort ? { effort } : {}),
+    resumed: run.resumed === true,
+    ...(optionalFiniteNumber(run.durationMs) !== undefined ? { durationMs: run.durationMs } : {}),
+    updatedAt: safeTimestamp(run.updatedAt),
+    ...(errorCode ? { errorCode } : {}),
+  }
+}
+
+export function safeCodexLatestRun(run?: CodexRunRecord): SafeCliDebugLatestRun | null {
+  if (!run) return null
+  const concreteModel = safeModelLabel(run.cliModel, 'codex')
+  const effort = safeEffort(run.reasoningEffort)
+  const errorCode = safeErrorCode('codex', run.errorCode)
+  return {
+    status: safeStatus(run.status),
+    model: safeModelLabel(run.model, 'codex') ?? 'unknown',
+    ...(concreteModel ? { concreteModel } : {}),
+    ...(effort ? { effort } : {}),
+    resumed: run.resumed === true,
+    ...(optionalFiniteNumber(run.durationMs) !== undefined ? { durationMs: run.durationMs } : {}),
+    updatedAt: safeTimestamp(run.updatedAt),
+    ...(errorCode ? { errorCode } : {}),
+  }
+}
+
+export function safeCliDebugResponse(
+  claudeConfig: ClaudeRunConfig,
+  claudeRun: ClaudeRunRecord | undefined,
+  codexConfig: CodexRunConfig,
+  codexRun: CodexRunRecord | undefined,
+): SafeCliDebugResponse {
+  return {
+    schemaVersion: 1,
+    providers: {
+      claude: {
+        supported: true,
+        persistenceEnabled: claudeConfig.persistenceEnabled === true,
+        workspaceConfigured: Boolean(claudeConfig.cwd),
+        latestRun: safeClaudeLatestRun(claudeRun),
+      },
+      codex: {
+        supported: true,
+        persistenceEnabled: codexConfig.persistenceEnabled === true,
+        workspaceConfigured: Boolean(codexConfig.cwd),
+        latestRun: safeCodexLatestRun(codexRun),
+      },
+    },
+  }
+}
+
+/** Compatibility projection for build 210 and earlier Settings panels.
+ * Every returned key is an explicit public-safe allowlist entry. */
+export function safeLegacyClaudeResponse(config: ClaudeRunConfig, runs: ClaudeRunRecord[]) {
+  return {
+    schemaVersion: 1,
+    config: {
+      persistenceEnabled: config.persistenceEnabled === true,
+      workspaceConfigured: Boolean(config.cwd),
+      cwd: config.cwd ? 'Configured workspace' : 'Not configured',
+      defaultEffortLevel: safeEffort(config.defaultEffortLevel) ?? 'high',
+      contentPreviewsEnabled: false,
+    },
+    runs: runs.map(run => {
+      const latest = safeClaudeLatestRun(run)!
+      return {
+        status: latest.status,
+        model: latest.model,
+        ...(latest.concreteModel ? {
+          cliModelId: latest.concreteModel,
+          resolvedModelId: latest.concreteModel,
+        } : {}),
+        ...(latest.effort ? { effortLevel: latest.effort } : {}),
+        ...(typeof latest.resumed === 'boolean' ? { resumed: latest.resumed } : {}),
+        ...(latest.durationMs !== undefined ? { durationMs: latest.durationMs } : {}),
+        ...(latest.updatedAt ? { updatedAt: latest.updatedAt } : {}),
+        ...(latest.errorCode ? { errorCode: latest.errorCode } : {}),
+      }
+    }),
+  }
+}
+
+/** Compatibility projection for build 210 and earlier Settings panels.
+ * Engine sessions are deliberately absent: their thread ids are resumable
+ * runtime handles, not display metadata. */
+export function safeLegacyCodexResponse(config: CodexRunConfig, runs: CodexRunRecord[]) {
+  return {
+    schemaVersion: 1,
+    config: {
+      persistenceEnabled: config.persistenceEnabled === true,
+      workspaceConfigured: Boolean(config.cwd),
+      cwd: config.cwd ? 'Configured workspace' : 'Not configured',
+      cliModel: safeModelLabel(config.cliModel, 'codex') ?? 'unknown',
+      reasoningEffort: safeEffort(config.reasoningEffort) ?? 'high',
+      contentPreviewsEnabled: false,
+    },
+    runs: runs.map(run => {
+      const latest = safeCodexLatestRun(run)!
+      return {
+        status: latest.status,
+        model: latest.model,
+        ...(latest.concreteModel ? { cliModel: latest.concreteModel } : {}),
+        ...(latest.effort ? { reasoningEffort: latest.effort } : {}),
+        ...(typeof latest.resumed === 'boolean' ? { resumed: latest.resumed } : {}),
+        ...(latest.durationMs !== undefined ? { durationMs: latest.durationMs } : {}),
+        ...(latest.updatedAt ? { updatedAt: latest.updatedAt } : {}),
+        ...(latest.errorCode ? { errorCode: latest.errorCode } : {}),
+      }
+    }),
+  }
+}

package/server/lib/codex-bridge.ts

@@ -60,6 +60,7 @@ import {
   MAX_ATTACHMENTS_PER_PROMPT,
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
+import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 
 const INACTIVITY_MS = 180_000
 const WALL_MAX_MS = 900_000
@@ -366,6 +367,7 @@ export async function callCodexStreaming(
   let stderr = ''
   let buffer = ''
   let finalized = false
+  let terminalTextError: string | null = null
   let lastActivity = Date.now()
   const emittedBlocks = new Set<string>()
 
@@ -425,6 +427,13 @@ export async function callCodexStreaming(
 
   async function finalize(text: string) {
     if (finalized) return
+    const responseAuthFailure = terminalProviderAuthFailure('codex', text)
+    const authFailure = responseAuthFailure
+      ?? (!text.trim() ? terminalTextError ?? terminalProviderAuthFailure('codex', stderr) : null)
+    if (authFailure) {
+      await finalizeError(authFailure, 0)
+      return
+    }
     finalized = true
     cleanup()
     cleanupImages()
@@ -614,13 +623,32 @@ export async function callCodexStreaming(
     }
 
     const text = extractCodexResponseText(event)
-    if (text) emitText(text)
+    if (text) {
+      // Withhold only strongly machine-shaped provider auth output so
+      // credentials cannot flash through onChunk. Human sign-in instructions
+      // do not match the terminal classifier.
+      const authFailure = terminalProviderAuthFailure('codex', text)
+      if (authFailure) terminalTextError = authFailure
+      else emitText(text)
+    }
 
     const type = String(event?.type ?? '')
     if (type === 'turn.completed') {
       void finalize(fullText)
     } else if (type === 'turn.failed' || type === 'error') {
-      finalizeError(`codex-bridge: ${event?.error ?? event?.message ?? 'unknown error'}`)
+      const rawProviderError = typeof event?.error === 'string' ? event.error
+        : typeof event?.error?.message === 'string' ? event.error.message
+          : typeof event?.message === 'string' ? event.message
+            : 'unknown error'
+      const structuredProviderError = event?.error && typeof event.error === 'object'
+        ? JSON.stringify(event.error)
+        : ''
+      const authenticationError = terminalProviderAuthFailure(
+        'codex',
+        rawProviderError,
+        structuredProviderError,
+      )
+      finalizeError(authenticationError ?? `codex-bridge: ${rawProviderError}`)
     }
   }
 
@@ -636,7 +664,9 @@ export async function callCodexStreaming(
       try {
         handleEvent(JSON.parse(trimmed))
       } catch {
-        // Ignore non-JSON status lines from older CLI builds.
+        // Older CLI builds can emit a terminal auth error as plain text while
+        // still exiting 0. Remember only the canonical classification.
+        terminalTextError ??= terminalProviderAuthFailure('codex', trimmed)
       }
     }
   })
@@ -651,10 +681,15 @@ export async function callCodexStreaming(
       try { handleEvent(JSON.parse(buffer.trim())) } catch { /* ignore */ }
     }
     if (finalized) return
-    if (code !== 0) {
-      finalizeError(`codex-bridge: exit ${code} — ${stderr.trim().slice(0, 240)}`, code)
-    } else if (fullText) {
+    if (fullText) {
       void finalize(fullText)
+      return
+    }
+    const authFailure = terminalTextError ?? terminalProviderAuthFailure('codex', stderr, buffer)
+    if (authFailure) {
+      finalizeError(authFailure, code)
+    } else if (code !== 0) {
+      finalizeError(`codex-bridge: exit ${code} — ${stderr.trim().slice(0, 240)}`, code)
     } else {
       finalizeError('codex-bridge: Codex completed without a response.')
     }

package/server/lib/provider-terminal-error.ts

@@ -0,0 +1,55 @@
+export type CliProvider = 'claude' | 'codex'
+
+const AUTH_CODE = /^(?:401|403|unauthori[sz]ed|forbidden|authentication_error|authorization_error|invalid_api_key|not_authenticated)$/i
+// Match whole, terminal-looking provider failures only. Natural assistant
+// answers such as "Please sign in to the customer portal, then..." must not
+// be reinterpreted as failures merely because their first words mention auth.
+const AUTH_FAILURE_PREFIX = /^(?:\s*(?:api\s+|http\s+|request\s+)?error(?:\[[^\]]+\])?\s*:\s*.{0,180}\b(?:401|403|unauthori[sz]ed|forbidden|authentication\s+(?:failed|required)|login\s+required|not\s+(?:logged|signed)\s+in)\b.*|\s*(?:http\s+)?(?:401|403)(?:\s+(?:unauthori[sz]ed|forbidden))?(?:\s*[:.\-]\s*.*)?|\s*(?:unauthori[sz]ed|forbidden)(?:\s*[:.\-]\s*.*)?|\s*(?:authentication|authorization)\s+(?:failed|required|error|missing|denied)(?:\s*[:.\-]\s*.*)?|\s*(?:login|sign[ -]?in)\s+(?:required|failed)(?:\s*[:.\-]\s*.*)?|\s*(?:you(?:'re| are)\s+)?not\s+(?:logged|signed)\s+in(?:\s*[:.\-]\s*.*)?|\s*please\s+run\s+(?:[`'"]?(?:claude|codex)[`'"]?\s+)?(?:[`'"]?\/?login[`'"]?|[`'"]?auth(?:enticate)?[`'"]?)\b.*)\s*$/i
+
+function stripAnsi(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+}
+
+function structuredAuthFailure(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  if (record.status === 401 || record.status === 403 || record.statusCode === 401 || record.statusCode === 403) return true
+  for (const key of ['code', 'type']) {
+    if (typeof record[key] === 'string' && AUTH_CODE.test(record[key])) return true
+  }
+  if (typeof record.error === 'string') {
+    return AUTH_CODE.test(record.error.trim()) || AUTH_FAILURE_PREFIX.test(record.error)
+  }
+  return structuredAuthFailure(record.error)
+}
+
+function looksLikeTerminalAuthFailure(value: unknown): boolean {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return structuredAuthFailure(value)
+  }
+  if (typeof value !== 'string') return false
+  const text = stripAnsi(value).trim()
+  if (!text || text.length > 2_000) return false
+  if (AUTH_FAILURE_PREFIX.test(text.replace(/\s+/g, ' '))) return true
+  if (!(text.startsWith('{') && text.endsWith('}'))) return false
+  try {
+    return structuredAuthFailure(JSON.parse(text))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Some CLI versions report authentication failures as successful process
+ * output and exit 0. Detect only terminal, machine-shaped auth messages and
+ * return a canonical error that cannot echo credentials or provider output.
+ */
+export function terminalProviderAuthFailure(
+  provider: CliProvider,
+  ...terminalValues: unknown[]
+): string | null {
+  return terminalValues.some(looksLikeTerminalAuthFailure)
+    ? `${provider}-bridge: authentication required.`
+    : null
+}

package/server/lib/secure-user-config.ts

@@ -0,0 +1,64 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+export class UnsafeUserConfigPathError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UnsafeUserConfigPathError'
+  }
+}
+
+export function securePrivateDirectory(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const stats = lstatSync(dir)
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new UnsafeUserConfigPathError(`${dir} must be a private directory, not a symlink`)
+  }
+  chmodSync(dir, 0o700)
+}
+
+export function secureExistingPrivateFile(file: string): void {
+  if (!existsSync(file)) return
+  const stats = lstatSync(file)
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new UnsafeUserConfigPathError(`${file} must be a regular file, not a symlink`)
+  }
+  chmodSync(file, 0o600)
+}
+
+/**
+ * Append an env block without ever following a symlink or exposing a partially
+ * written credential file. The replacement is created beside the destination
+ * at 0600 and atomically renamed into place.
+ */
+export function appendPrivateEnvBlock(file: string, block: string): void {
+  const dir = dirname(file)
+  securePrivateDirectory(dir)
+  secureExistingPrivateFile(file)
+
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const separator = current.length > 0 && !current.endsWith('\n') ? '\n' : ''
+  const temp = join(dir, `.${basename(file)}.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(temp, `${current}${separator}${block}`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600,
+    })
+    chmodSync(temp, 0o600)
+    renameSync(temp, file)
+    chmodSync(file, 0o600)
+  } catch (error) {
+    try { unlinkSync(temp) } catch { /* best-effort cleanup */ }
+    throw error
+  }
+}

package/server/routes/cli-debug.ts

@@ -0,0 +1,66 @@
+import { Router } from 'express'
+import { normalizeModelPreference, isClaudeModel } from '../../shared/model-preference.js'
+import {
+  getClaudeRunConfig,
+  listClaudeRuns,
+} from '../lib/claude-run-ledger.js'
+import {
+  getCodexRunConfig,
+  listCodexRuns,
+} from '../lib/codex-run-ledger.js'
+import {
+  safeCliDebugResponse,
+  safeLegacyClaudeResponse,
+  safeLegacyCodexResponse,
+} from '../lib/cli-debug-view.js'
+
+export const cliDebugRouter = Router()
+
+function boundedLimit(value: unknown): number {
+  const raw = Number(value ?? 20)
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.floor(raw), 50) : 20
+}
+
+function optionalSessionId(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function optionalClaudeModel(value: unknown) {
+  const raw = typeof value === 'string' ? normalizeModelPreference(value) : undefined
+  return raw && isClaudeModel(raw) ? raw : undefined
+}
+
+// Versioned public-safe view consumed by Recovery Center. Global /api auth
+// protects this route; it must never be added to the unauthenticated allowlist.
+cliDebugRouter.get('/cli/debug', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const model = optionalClaudeModel(req.query.model)
+  const claudeConfig = getClaudeRunConfig()
+  const codexConfig = getCodexRunConfig()
+  const claudeRuns = listClaudeRuns(limit, sessionId, model)
+  const codexRuns = listCodexRuns(limit, sessionId)
+  res.json(safeCliDebugResponse(
+    claudeConfig,
+    claudeRuns[0],
+    codexConfig,
+    codexRuns[0],
+  ))
+})
+
+// Build-210 compatibility. These legacy shapes retain only the fields the old
+// panel can render safely; they do not expose raw ledger records.
+cliDebugRouter.get('/cli/runs', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const model = optionalClaudeModel(req.query.model)
+  const config = getClaudeRunConfig()
+  res.json(safeLegacyClaudeResponse(config, listClaudeRuns(limit, sessionId, model)))
+})
+
+cliDebugRouter.get('/codex/runs', (req, res) => {
+  const limit = boundedLimit(req.query.limit)
+  const sessionId = optionalSessionId(req.query.sessionId)
+  const config = getCodexRunConfig()
+  res.json(safeLegacyCodexResponse(config, listCodexRuns(limit, sessionId)))
+})

package/server/routes/health.ts

@@ -20,6 +20,7 @@ import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
 import { durableQueryJobsCapability } from '../lib/query-job-feature.js'
 import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
 import { getTranscriptionPolicySnapshot } from '../lib/transcription-policy.js'
+import { CLI_DEBUG_CAPABILITY } from '../lib/cli-debug-view.js'
 
 export const healthRouter = Router()
 
@@ -53,7 +54,7 @@ function durableQueryJobStatus() {
 }
 
 healthRouter.get('/health', async (_req, res) => {
-  const checks: Record<string, string | number> = {
+  const checks: Record<string, string | number | boolean> = {
     status: 'ok',
     mode: COS_MODE ? 'cos' : 'standalone',
     server: 'ok',
@@ -128,9 +129,11 @@ healthRouter.get('/health', async (_req, res) => {
 
   checks.silero_vad = isSileroAvailable() ? 'active' : 'disabled'
 
-  // Include CLI session ID if available (pre-warmed or active)
+  // Health is unauthenticated. Publish only availability; the actual CLI
+  // session id is a resumable runtime handle and belongs on authenticated
+  // query/debug surfaces.
   const cliSid = getAvailableCliSessionId()
-  if (cliSid) checks.cli_session_id = cliSid
+  checks.cli_session_available = Boolean(cliSid)
 
   // Feature summary for client capability detection.
   // v5.9.5 — voice.hasKey reflects the centralized resolver (env > saved file >
@@ -185,6 +188,7 @@ healthRouter.get('/health', async (_req, res) => {
     capabilities: {
       transcription,
       recovery,
+      cliDebug: CLI_DEBUG_CAPABILITY,
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
     // /api/health is intentionally unauthenticated for setup diagnostics.
@@ -215,6 +219,7 @@ healthRouter.get('/models', async (req, res) => {
         protocolVersion: durableJobs.protocolVersion,
       },
       transcription,
+      cliDebug: CLI_DEBUG_CAPABILITY,
       recovery: {
         status: false,
         restartWhisper: false,