@gotcos/glasses-server 6.15.3 → 6.16.0

package/.env.example

@@ -70,11 +70,15 @@ BIND_HOST=0.0.0.0
 
 # ── VOICE (optional) ────────────────────────────────────────────────────
 # Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the
-# model auto-downloads on first run). Voice is local-only by default. Merely
+# real-time turbo model auto-downloads on first run). Full HQ dictation also
+# needs ggml-large-v3.bin as documented in README. Voice is local-only by default. Merely
 # configuring a key never uploads audio. To allow OpenAI Whisper only after a
 # local failure, set BOTH the exact opt-in and a key:
 # COS_OPENAI_WHISPER_FALLBACK=1
 # OPENAI_API_KEY=sk-...
+# COS_HQ_SPECULATIVE_WARM=0        # disable background HQ warm
+# COS_BATCH_LARGE_V3=0             # explicitly use turbo instead of full HQ
+# COS_HQ_BEAM_INTERACTIVE=2        # interactive only; meetings stay at beam 5
 
 # Spoken reply playback defaults to local Kokoro on Apple silicon Macs. The
 # first run creates a private venv and downloads the model. Local mode fails

package/CHANGELOG.md

@@ -1,3 +1,60 @@
+## 6.16.0
+
+- **Truthful HQ results.** An HQ request is reported as HQ only when the full
+  local large-v3 decoder actually ran. Turbo, real-time server, long-audio, and
+  decode-error fallbacks now retain the requested mode while returning their
+  actual quality, backend, degradation flag, and bounded reason code.
+- **HQ capability health.** `/api/health` and `/api/models` add a path-free
+  `capabilities.transcription.hq` block with availability, model, backend, and
+  a user-safe missing-prerequisite reason. Generic Whisper liveness no longer
+  implies that large-v3 HQ is installed.
+- **Phone-visible fallback telemetry.** One-shot transcription and prompt-draft
+  finalize responses expose the same additive quality fields. Draft finalize
+  aggregates the records it actually used and reuses a successful degraded
+  warm result instead of paying for an identical second turbo decode.
+- **Default unchanged.** Absent an explicit Fast request, prompt dictation still
+  requests HQ. `COS_HQ_SPECULATIVE_WARM=0` remains the immediate warm-path
+  rollback, and meeting batch beam/isolation behavior is unchanged.
+
+## 6.15.5
+
+- **Speculative HQ warm (no EHPK).** While a prompt-draft chunk is acknowledged,
+  Fast warm still paints the HUD and, when Settings HQ is active (default), a
+  background large-v3 warm overwrites `warmTranscripts` with `actualQuality=hq`
+  under `local-only` (never OpenAI mid-speak). Finalize reuses that cache so
+  Render is dominated by the last unfinished chunk, not a cold full re-decode.
+  Killswitch: `COS_HQ_SPECULATIVE_WARM=0`.
+- **Finalize dedupe.** In-flight HQ warm and finalize share one decode via a
+  purpose-agnostic job key so Render cannot start a second large-v3 while warm
+  is still running.
+- **Interactive HQ latency knobs.** Interactive beam defaults to 2 (meetings
+  keep beam 5); short clips (<15s) use light ffmpeg enhance (highpass only).
+  Env: `COS_HQ_BEAM_INTERACTIVE`, `COS_HQ_ENHANCE_LIGHT_MAX_SEC`.
+
+## 6.15.4
+
+- Start Whisper, Kokoro, model discovery, and local audio prerequisites while
+  a managed successor remains behind the authenticated maintenance gate. Start
+  durable recovery, session warming, snapshots, and media GC exactly once after
+  the controller releases admissions, so routine restarts cannot strand local
+  services or prematurely mutate durable state.
+- Bound Whisper process and port inspection to two seconds per probe, move it
+  off the Node event loop, expose startup phase/error diagnostics, and only reap
+  processes whose executable is actually `whisper-server` with the COS model
+  and port signature.
+- Migrate legacy bare MCP server selectors to `mcp__server__*` and warn once for
+  rejected local/invalid selectors without relaxing the safe tool boundary.
+- Terminate abandoned, timed-out, start-failed, and ownership-lost provider
+  runs without orphaning tool subprocesses. Termination targets the detached
+  process group, escalates from SIGTERM to SIGKILL, and releases lifecycle
+  ownership only after Node observes process close. Control's provider proof
+  uses the same process-owned cancellation boundary.
+- Expose persistent Whisper prerequisite state separately from batch-only CLI
+  availability, plus an additive readiness summary so HTTP-200 liveness cannot
+  hide a configured local subsystem failure.
+- Keep the stable `unauthorized` error code while adding non-secret guidance to
+  copy and paste the complete pairing token from COS Control.
+
 ## 6.15.3
 
 - Make `COS_WORKDIR` the authoritative Claude, Codex, and Cursor workspace.

package/README.md

@@ -106,6 +106,10 @@ range is the exact Tailscale/CGNAT allocation (`100.64.0.0/10`), not all of
   Whisper fallback is optional and requires both the exact
   `COS_OPENAI_WHISPER_FALLBACK=1` opt-in and a configured key; a key alone never
   uploads audio.
+- HQ prompt dictation is requested by default; the phone's **Fast mode** switch
+  opts into turbo. Server 6.16.0 reports whether full local large-v3 actually
+  ran, and compatible companions alert once if an HQ request used Fast or
+  Cloud instead of silently claiming HQ.
 - Local-first spoken reply playback through Kokoro on Apple silicon. The first
   use creates a private Python environment and downloads its model without
   blocking the API. Selecting Local fails closed; `local_first` can fall back
@@ -137,6 +141,32 @@ Telegram activity export is disabled by default even when a private COS
 pipeline contains `.telegram_config.json`; enable it only with the explicit
 `COS_TELEGRAM_NOTIFICATIONS=1` opt-in.
 
+## HQ dictation
+
+Prompt dictation defaults to HQ. The phone owns the preference: **Fast mode
+OFF** requests HQ, and **Fast mode ON** requests turbo. The Mac performs all
+decoding; the phone does not run Whisper.
+
+The first server start downloads the real-time turbo model. True HQ additionally
+requires the full `ggml-large-v3.bin` model (about 3.1 GB):
+
+```bash
+mkdir -p "$HOME/.local/share/whisper-models"
+curl -fL --progress-bar \
+  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin \
+  -o "$HOME/.local/share/whisper-models/ggml-large-v3.bin.partial"
+mv "$HOME/.local/share/whisper-models/ggml-large-v3.bin.partial" \
+  "$HOME/.local/share/whisper-models/ggml-large-v3.bin"
+```
+
+Restart the server, then confirm
+`capabilities.transcription.hq.hqAvailable: true` at `/api/health`. The response
+does not expose local paths. If the CLI or model is unavailable, dictation stays
+usable on Fast and reports the downgrade truthfully. Set
+`COS_HQ_SPECULATIVE_WARM=0` to disable background HQ warm immediately; set
+`COS_BATCH_LARGE_V3=0` to explicitly use turbo. Interactive HQ uses beam 2 by
+default (`COS_HQ_BEAM_INTERACTIVE`); meeting batch remains beam 5.
+
 ## Run from source
 
 ```bash

package/package.json

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

@@ -69,12 +69,14 @@ import {
 } from './lib/network-policy.js'
 import { requireApiToken } from './lib/api-auth.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
+import { reportClaudeExtraToolConfiguration } from './lib/claude-tool-access.js'
 import {
   acquireMaintenanceWork,
   maintenanceOperationCredentialsValid,
   MaintenanceLifecycleError,
   maintenanceAdmissionsOpen,
   maintenanceErrorPayload,
+  onMaintenanceAdmissionsOpen,
 } from './lib/maintenance-lifecycle.js'
 
 const app = express()
@@ -153,6 +155,7 @@ app.use('/api', (req, res, next) => {
   if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next()
   const lifecycleOwned = (req.path === '/query-jobs' && req.method === 'POST')
     || req.path === '/query'
+    || req.path === '/diagnostics/provider-proof'
     || req.path === '/transcribe'
     || req.path.startsWith('/transcribe-stream')
     || req.path === '/meeting/save'
@@ -326,20 +329,8 @@ listenRequiredServers(listeners).then(() => {
   console.log(`[COS API] Server instance: ${serverInstanceId}`)
   console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
 
-  if (startupAdmissionsOpen) {
-    void initQueryJobRuntime().then(health => {
-      if (process.env.COS_DURABLE_QUERY_JOBS === '1') {
-        console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)
-      } else {
-        console.log('[COS API] Durable query jobs: disabled (set COS_DURABLE_QUERY_JOBS=1 to enable)')
-      }
-    }).catch(error => {
-      // The store remains degraded and rejects admission. Legacy /api/query is
-      // still mounted, so disabling the feature flag is an immediate rollback.
-      console.error('[COS API] Durable query-job store unavailable:', error)
-    })
-  } else {
-    console.log('[COS API] Startup maintenance gate is closed — durable recovery waits for controller adoption')
+  if (!startupAdmissionsOpen) {
+    console.log('[COS API] Startup maintenance gate is closed — durable recovery waits for controller release')
   }
 
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
@@ -387,16 +378,20 @@ listenRequiredServers(listeners).then(() => {
   console.log(`[COS API] Codex mode: ${codexConfig.persistenceEnabled ? 'persistent' : 'ephemeral'} · ${codexConfig.reasoningEffort} · ${codexConfig.trustMode}`)
   console.log(`[COS API] Codex models (${codexConfig.catalogSource}): ${codexConfig.availableModels.map(item => `${item.displayName}=${item.model}`).join(' · ')}`)
   console.log(`[COS API] Codex workdir: ${codexConfig.cwd}`)
-  // Refresh immediately and then periodically. The catalog module retains the
-  // last-known-good snapshot if Codex is temporarily unavailable.
-  if (startupAdmissionsOpen) {
-    startCodexModelCatalogRefresh()
+  reportClaudeExtraToolConfiguration()
 
-    if (COS_MODE) {
-      initSessionCache()
-      // Pre-warm context cache so first query doesn't wait for the pipeline
-      prewarmContext()
-    }
+  // These services do not admit or mutate user work. They must start while a
+  // managed successor is still behind the cross-boot gate so COS Control can
+  // prove the candidate before opening admissions. Keeping this idempotent also
+  // prevents a release notification from creating duplicate sidecars.
+  let proofSafeServicesStarted = false
+  const startProofSafeServices = () => {
+    if (proofSafeServicesStarted) return
+    proofSafeServicesStarted = true
+
+    // Refresh immediately and then periodically. The catalog retains the last
+    // known-good snapshot if Codex is temporarily unavailable.
+    startCodexModelCatalogRefresh()
     // Start local whisper-server (model stays in RAM for ~50ms transcription)
     startWhisperServer().catch(err => console.error('[startup] Whisper server error:', err))
     startLocalTtsServer().catch(err => console.error('[startup] Local TTS server error:', err))
@@ -406,6 +401,33 @@ listenRequiredServers(listeners).then(() => {
     // Initialize Silero VAD (silence trimming before Whisper) — fails soft if model absent
     const vadOk = initSileroVAD()
     console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
+  }
+
+  // Durable recovery and state-mutating background work remain closed until an
+  // authenticated controller release. The lifecycle callback is delivered for
+  // both an already-open fresh boot and a later cross-boot release.
+  let admittedRuntimeStarted = false
+  const startAdmittedRuntime = () => {
+    if (admittedRuntimeStarted) return
+    admittedRuntimeStarted = true
+
+    void initQueryJobRuntime().then(health => {
+      if (process.env.COS_DURABLE_QUERY_JOBS === '1') {
+        console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)
+      } else {
+        console.log('[COS API] Durable query jobs: disabled (set COS_DURABLE_QUERY_JOBS=1 to enable)')
+      }
+    }).catch(error => {
+      // The store remains degraded and rejects admission. Legacy /api/query is
+      // still mounted, so disabling the feature flag is an immediate rollback.
+      console.error('[COS API] Durable query-job store unavailable:', error)
+    })
+
+    if (COS_MODE) {
+      initSessionCache()
+      // Pre-warm context cache so first query doesn't wait for the pipeline
+      prewarmContext()
+    }
 
     // Pre-warm Claude only when installed so Codex-only startup stays quiet.
     if (claudeAvailable) {
@@ -418,6 +440,9 @@ listenRequiredServers(listeners).then(() => {
     // Durable media GC (staged/reserved expiry + generated-image content TTL).
     getMediaStore().startGC()
   }
+
+  startProofSafeServices()
+  onMaintenanceAdmissionsOpen(startAdmittedRuntime)
 }).catch((error: NodeJS.ErrnoException) => {
   console.error(`[COS API] Fatal listener startup: ${error.message}`)
   process.exit(error.code === 'EADDRINUSE' ? 75 : 74)

package/server/lib/api-auth.ts

@@ -27,7 +27,11 @@ export function requireApiToken(apiToken: string): RequestHandler {
   return (req, res, next) => {
     if (isPublicApiRequest(req.method, req.path)) return next()
     if (!timingSafeTokenEqual(req.headers['x-cos-token'], apiToken)) {
-      return res.status(401).json({ error: 'unauthorized' })
+      return res.status(401).json({
+        error: 'unauthorized',
+        reason: 'pairing_token_rejected',
+        message: 'In COS Control choose Copy Pairing Token, then paste the complete value into COS Glasses.',
+      })
     }
     next()
   }

package/server/lib/audio-enhance.ts

@@ -2,10 +2,9 @@
 // Extracted so both batch (post-meeting) and one-shot (message query HQ) paths
 // can use the same filter chain.
 //
-// Filter chain:
-//   highpass=f=80  — kills low-freq rumble (HVAC, body noise, table thumps)
-//   afftdn=nt=w    — FFT-based denoiser (white noise, fan hum)
-//   loudnorm       — EBU R128 loudness normalization (fixes quiet speakers)
+// Filter chains:
+//   light — highpass=f=80 only (short interactive clips; lower latency)
+//   full  — highpass + afftdn + loudnorm (meetings / longer outdoor audio)
 //
 // Graceful: returns the original buffer if ffmpeg is missing, fails, or times out.
 // Callers should never crash a user request because enhancement couldn't run.
@@ -16,7 +15,10 @@ import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 
 const FFMPEG_TIMEOUT_MS = 30_000
-const FILTER_CHAIN = 'highpass=f=80,afftdn=nt=w,loudnorm=I=-16:LRA=11:TP=-1.5'
+const FILTER_FULL = 'highpass=f=80,afftdn=nt=w,loudnorm=I=-16:LRA=11:TP=-1.5'
+const FILTER_LIGHT = 'highpass=f=80'
+
+export type EnhanceProfile = 'light' | 'full'
 
 /**
  * Enhance raw audio (WAV/webm/etc) and return a 16kHz mono WAV buffer suitable
@@ -25,7 +27,12 @@ const FILTER_CHAIN = 'highpass=f=80,afftdn=nt=w,loudnorm=I=-16:LRA=11:TP=-1.5'
  *
  * Returns the ORIGINAL buffer unchanged on any failure. Logs the reason.
  */
-export async function enhanceAudio(audioBuffer: Buffer): Promise<Buffer> {
+export async function enhanceAudio(
+  audioBuffer: Buffer,
+  opts: { profile?: EnhanceProfile } = {},
+): Promise<Buffer> {
+  const profile: EnhanceProfile = opts.profile === 'light' ? 'light' : 'full'
+  const filterChain = profile === 'light' ? FILTER_LIGHT : FILTER_FULL
   const id = randomUUID().slice(0, 8)
   const inputPath = join('/tmp', `cos-enhance-in-${id}`)
   const outputPath = join('/tmp', `cos-enhance-out-${id}.wav`)
@@ -36,7 +43,7 @@ export async function enhanceAudio(audioBuffer: Buffer): Promise<Buffer> {
     const enhanced = await new Promise<Buffer>((resolve, reject) => {
       const proc = spawn('ffmpeg', [
         '-i', inputPath,
-        '-af', FILTER_CHAIN,
+        '-af', filterChain,
         '-ar', '16000',
         '-ac', '1',
         '-f', 'wav',
@@ -78,7 +85,7 @@ export async function enhanceAudio(audioBuffer: Buffer): Promise<Buffer> {
     return enhanced
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err)
-    console.warn(`[audio-enhance] ffmpeg failed, returning original buffer: ${msg}`)
+    console.warn(`[audio-enhance] ffmpeg failed (${profile}), returning original buffer: ${msg}`)
     return audioBuffer
   } finally {
     try { unlinkSync(inputPath) } catch { /* ignore */ }

package/server/lib/claude-bridge.ts

@@ -54,6 +54,7 @@ import {
 } from './claude-tool-access.js'
 import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 import { claudePermissionArgs, getClaudeTrustMode } from './claude-permissions.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
 
 // Inactivity = no stdout data for this long → kill (catches stalls)
 const INACTIVITY_BY_MODEL: Record<ClaudeModelPreference, number> = {
@@ -553,12 +554,14 @@ export async function callClaudeStreaming(
     stdio: ['pipe', 'pipe', 'pipe'],
     env,
     cwd: cliCwd,
+    detached: true,
   })
 
   let fullText = ''
   let stderr = ''
   let buffer = ''
   let finalized = false        // Guard against double onDone/onError
+  let terminationRequested = false // Forced terminal callbacks wait for confirmed process close
   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)
@@ -722,10 +725,27 @@ export async function callClaudeStreaming(
     await callbacks.onError(msg)
   }
 
+  async function terminateForTerminal(
+    reason: string,
+    onClosed: (result: Awaited<ReturnType<typeof terminateProviderProcess>>) => void | Promise<void>,
+  ) {
+    if (finalized || terminationRequested) return
+    terminationRequested = true
+    cleanup()
+    const result = await terminateProviderProcess(proc)
+    if (!result.closed) {
+      console.error(`[claude-bridge] provider did not close after SIGKILL (${reason}); retaining lifecycle ownership`)
+      return
+    }
+    await onClosed(result)
+  }
+
   function handleAbort() {
-    if (finalized) return
-    proc.kill('SIGTERM')
-    finalizeError('claude-bridge: client disconnected before Claude completed.', null, 'client_disconnected')
+    void terminateForTerminal('client disconnect', result => finalizeError(
+        'claude-bridge: client disconnected before Claude completed.',
+        result.code,
+        'client_disconnected',
+      ))
   }
 
   // ─── Heartbeat: emit phase status during silence ───
@@ -743,31 +763,35 @@ export async function callClaudeStreaming(
   // ─── Inactivity timeout: resets on any stdout data ───
 
   let inactivityTimer = setTimeout(() => {
-    proc.kill('SIGTERM')
     const elapsed = Math.round((Date.now() - startTime) / 1000)
-    finalizeError(`No output for ${inactivityMs / 1000}s (${elapsed}s total). Process killed.`)
+    void terminateForTerminal('inactivity timeout', result => finalizeError(
+      `No output for ${inactivityMs / 1000}s (${elapsed}s total). Process killed.`,
+      result.code,
+    ))
   }, inactivityMs)
 
   function resetInactivity() {
     lastActivity = Date.now()
     clearTimeout(inactivityTimer)
     inactivityTimer = setTimeout(() => {
-      proc.kill('SIGTERM')
       const elapsed = Math.round((Date.now() - startTime) / 1000)
-      finalizeError(`No output for ${inactivityMs / 1000}s (${elapsed}s total). Process killed.`)
+      void terminateForTerminal('inactivity timeout', result => finalizeError(
+        `No output for ${inactivityMs / 1000}s (${elapsed}s total). Process killed.`,
+        result.code,
+      ))
     }, inactivityMs)
   }
 
   // ─── Wall clock max: absolute cap ───
 
   const wallTimer = setTimeout(() => {
-    proc.kill('SIGTERM')
-    if (fullText) {
-      // Got partial output — deliver what we have
-      void finalize(fullText)
-    } else {
-      finalizeError(`Wall clock limit reached (${wallMax / 1000}s). Process killed.`)
-    }
+    void terminateForTerminal('wall timeout', result => {
+      if (fullText) {
+        // Got partial output — deliver only after the process tree is closed.
+        return finalize(fullText)
+      }
+      return finalizeError(`Wall clock limit reached (${wallMax / 1000}s). Process killed.`, result.code)
+    })
   }, wallMax)
 
   function cleanup() {
@@ -898,6 +922,7 @@ export async function callClaudeStreaming(
   })
 
   proc.on('close', (code) => {
+    if (terminationRequested) return
     // Process any remaining buffer
     if (buffer.trim()) {
       try {
@@ -931,9 +956,11 @@ export async function callClaudeStreaming(
   })
 
   proc.on('error', (err) => {
+    if (terminationRequested) return
     finalizeError(`claude-bridge: ${err.message}`, null)
   })
   proc.stdin.on('error', (err) => {
+    if (terminationRequested) return
     finalizeError(`claude-bridge: stdin failed — ${err.message}`, null)
   })
 
@@ -959,8 +986,9 @@ export async function callClaudeStreaming(
       generation: options?.generation,
     })
     if (providerOwned === false) {
-      proc.kill('SIGTERM')
-      abandonLostDurableOwnership('claude-bridge: durable provider ownership was lost.')
+      await terminateForTerminal('provider ownership lost', () => {
+        abandonLostDurableOwnership('claude-bridge: durable provider ownership was lost.')
+      })
       return sid
     }
     if (finalized) return sid
@@ -969,8 +997,10 @@ export async function callClaudeStreaming(
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     if (!finalized) {
-      proc.kill('SIGTERM')
-      await finalizeError(`claude-bridge: provider start failed — ${message}`, null)
+      await terminateForTerminal('provider start failure', result => finalizeError(
+        `claude-bridge: provider start failed — ${message}`,
+        result.code,
+      ))
     }
   }
 

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

@@ -5,20 +5,86 @@ import { resolve } from 'node:path'
 // 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_.*:@/-]*$/
+const LEGACY_MCP_SERVER_SELECTOR = /^mcp__(?!.*__)[A-Za-z0-9][A-Za-z0-9_.:@/-]*$/
 
-export function configuredClaudeExtraTools(
+export interface ClaudeExtraToolConfiguration {
+  accepted: string[]
+  rejected: string[]
+  migrated: Array<{ from: string; to: string }>
+}
+
+let reportedConfiguration: string | null = null
+
+export function parseClaudeExtraToolConfiguration(
   env: NodeJS.ProcessEnv = process.env,
-): string[] {
+): ClaudeExtraToolConfiguration {
   const raw = env.COS_EXTRA_TOOLS ?? ''
   const seen = new Set<string>()
-  const tools: string[] = []
+  const rejectedSeen = new Set<string>()
+  const accepted: string[] = []
+  const rejected: string[] = []
+  const migrated: Array<{ from: string; to: string }> = []
+
   for (const value of raw.split(',')) {
-    const tool = value.trim()
-    if (!tool || !MCP_SELECTOR.test(tool) || seen.has(tool)) continue
+    const original = value.trim()
+    if (!original) continue
+    const tool = LEGACY_MCP_SERVER_SELECTOR.test(original)
+      ? `${original}__*`
+      : original
+    if (!MCP_SELECTOR.test(tool)) {
+      if (!rejectedSeen.has(original)) {
+        rejectedSeen.add(original)
+        rejected.push(original)
+      }
+      continue
+    }
+    if (seen.has(tool)) continue
     seen.add(tool)
-    tools.push(tool)
+    accepted.push(tool)
+    if (tool !== original) migrated.push({ from: original, to: tool })
+  }
+
+  return { accepted, rejected, migrated }
+}
+
+export function configuredClaudeExtraTools(
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  return parseClaudeExtraToolConfiguration(env).accepted
+}
+
+function safeSelectorList(values: string[]): string {
+  const visible = values.slice(0, 8).map(value => {
+    const sanitized = value.replace(/[^A-Za-z0-9_.:@/*=>-]/g, '?')
+    return sanitized.length > 64 ? `${sanitized.slice(0, 61)}...` : sanitized
+  })
+  return `${visible.join(', ')}${values.length > visible.length ? ` (+${values.length - visible.length} more)` : ''}`
+}
+
+/** Log migration/rejection once per process configuration, never per query. */
+export function reportClaudeExtraToolConfiguration(
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeExtraToolConfiguration {
+  const raw = env.COS_EXTRA_TOOLS ?? ''
+  const parsed = parseClaudeExtraToolConfiguration(env)
+  if (!raw.trim() || reportedConfiguration === raw) return parsed
+  reportedConfiguration = raw
+
+  if (parsed.migrated.length > 0) {
+    console.warn(
+      '[claude-tools] Migrated legacy COS_EXTRA_TOOLS server selector(s): ' +
+      safeSelectorList(parsed.migrated.map(item => `${item.from}->${item.to}`)) +
+      '. Persist the full mcp__server__* form.',
+    )
+  }
+  if (parsed.rejected.length > 0) {
+    console.warn(
+      '[claude-tools] Ignored unsafe or invalid COS_EXTRA_TOOLS selector(s): ' +
+      safeSelectorList(parsed.rejected) +
+      '. Use mcp__server__tool or mcp__server__*. Read/Glob/Grep/Bash/Write cannot be enabled through this setting.',
+    )
   }
-  return tools
+  return parsed
 }
 
 export function buildClaudeToolList(input: {