@gotcos/glasses-server 6.12.0 → 6.12.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 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/package.json

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

@@ -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'
@@ -163,6 +164,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

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/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,