@gotcos/glasses-server 6.2.1 → 6.5.0

package/server/bin/cos-output-image-publisher.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+// Capability-scoped image publisher used by a single COS Glasses model run.
+// It copies one already-local supported image artifact into the run's private inbox and
+// appends only an opaque content id + generic provenance to the manifest.
+// Source paths, URLs, and bytes never enter the manifest or stdout.
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs'
+import { basename, isAbsolute, join, sep } from 'node:path'
+
+const RUN_DIR_PREFIX = 'cos-glasses-output-images-'
+const ABSOLUTE_MAX_IMAGES = 5
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024
+const MANIFEST_MAX_BYTES = 64 * 1024
+const PROVENANCE = new Set(['generated', 'research', 'email'])
+const OUTPUT_ID_RE = /^o_[a-f0-9]{32}$/
+const WAIT_ARRAY = new Int32Array(new SharedArrayBuffer(4))
+
+function configuredMaxImages() {
+  const parsed = Number(process.env.COS_OUTPUT_IMAGE_MAX)
+  if (!Number.isInteger(parsed)) return ABSOLUTE_MAX_IMAGES
+  return Math.max(0, Math.min(ABSOLUTE_MAX_IMAGES, parsed))
+}
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function sleep(ms) {
+  Atomics.wait(WAIT_ARRAY, 0, 0, ms)
+}
+
+function isSupportedMagic(bytes) {
+  const jpeg = bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff
+  const png = bytes.length >= 8 &&
+    bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
+    bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a
+  const webp = bytes.length >= 12 &&
+    bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP'
+  let isoImage = false
+  if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const declaredBoxSize = bytes.readUInt32BE(0)
+    const boxEnd = Math.min(bytes.length, declaredBoxSize >= 16 ? declaredBoxSize : 16, 256)
+    const brands = [bytes.toString('ascii', 8, 12)]
+    for (let offset = 16; offset + 4 <= boxEnd; offset += 4) brands.push(bytes.toString('ascii', offset, offset + 4))
+    isoImage = brands.some((brand) => [
+      'avif', 'avis',
+      'heic', 'heix', 'hevc', 'hevx', 'heim', 'heis',
+      'mif1', 'msf1',
+    ].includes(brand))
+  }
+  return jpeg || png || webp || isoImage
+}
+
+function outputId(bytes) {
+  // Provenance is presentation metadata, not identity. The first publication
+  // of identical bytes wins regardless of how that image was later reused.
+  const digest = createHash('sha256').update(bytes).digest('hex')
+  return `o_${digest.slice(0, 32)}`
+}
+
+function validateItemsDir(runDir, expected) {
+  const itemsDir = join(runDir, 'items')
+  let fd = -1
+  try {
+    const before = lstatSync(itemsDir)
+    if (!before.isDirectory() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o700) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (typeof process.getuid === 'function' && before.uid !== process.getuid()) {
+      fail('Publisher items directory is unavailable.')
+    }
+    const real = realpathSync(itemsDir)
+    if (real !== itemsDir || !real.startsWith(`${runDir}${sep}`)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    fd = openSync(itemsDir, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    const after = lstatSync(itemsDir)
+    if (!opened.isDirectory() || opened.dev !== before.dev || opened.ino !== before.ino ||
+        after.isSymbolicLink() || after.dev !== opened.dev || after.ino !== opened.ino ||
+        (opened.mode & 0o777) !== 0o700 ||
+        (typeof process.getuid === 'function' && opened.uid !== process.getuid())) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (expected && (opened.dev !== expected.dev || opened.ino !== expected.ino)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    return { path: itemsDir, dev: opened.dev, ino: opened.ino }
+  } catch (err) {
+    if (err instanceof Error && err.message === 'Publisher items directory is unavailable.') throw err
+    fail('Publisher items directory is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function readManifestIds(path) {
+  if (!existsSync(path)) return new Set()
+  let contents = ''
+  let fd = -1
+  try {
+    const stat = lstatSync(path)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MANIFEST_MAX_BYTES) {
+      fail('Publisher manifest is unavailable.')
+    }
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    contents = readFileSync(fd, 'utf8')
+  } catch {
+    fail('Publisher manifest is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+  const ids = new Set()
+  for (const line of contents.split('\n')) {
+    if (!line || line.length > 512) continue
+    try {
+      const item = JSON.parse(line)
+      if (item?.v === 1 && item?.type === 'publish' && OUTPUT_ID_RE.test(item.id) && PROVENANCE.has(item.provenance)) {
+        ids.add(item.id)
+      }
+    } catch {
+      // A process can die between append bytes. A malformed tail never makes
+      // a valid earlier publication disappear.
+    }
+  }
+  return ids
+}
+
+function acquireLock(runDir) {
+  const lockDir = join(runDir, '.publish.lock')
+  const deadline = Date.now() + 5_000
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(lockDir, { mode: 0o700 })
+      return lockDir
+    } catch (err) {
+      if (err?.code !== 'EEXIST') fail('Publisher lock is unavailable.')
+      try {
+        if (Date.now() - statSync(lockDir).mtimeMs > 30_000) {
+          rmSync(lockDir, { recursive: true, force: true })
+          continue
+        }
+      } catch {
+        // The owner may have released it between the failed mkdir and stat.
+      }
+      sleep(25)
+    }
+  }
+  fail('Publisher is busy; try once more.')
+}
+
+function readCapability(runDir, supplied) {
+  if (!supplied || Buffer.byteLength(supplied) > 256) fail('Publisher capability is unavailable.')
+  let expected = ''
+  try {
+    expected = readFileSync(join(runDir, '.capability'), 'utf8').trim()
+  } catch {
+    fail('Publisher capability is unavailable.')
+  }
+  const a = Buffer.from(supplied)
+  const b = Buffer.from(expected)
+  if (a.length !== b.length || !timingSafeEqual(a, b)) fail('Publisher capability is unavailable.')
+}
+
+function validateRunDir(rawDir) {
+  if (!rawDir || !isAbsolute(rawDir)) fail('Publisher directory is unavailable.')
+  let runDir
+  let tmpRoot
+  try {
+    runDir = realpathSync(rawDir)
+    tmpRoot = realpathSync('/tmp')
+    const stat = lstatSync(runDir)
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('Publisher directory is unavailable.')
+    if ((stat.mode & 0o777) !== 0o700) fail('Publisher directory is not private.')
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) fail('Publisher directory is unavailable.')
+  } catch {
+    fail('Publisher directory is unavailable.')
+  }
+  if (!runDir.startsWith(`${tmpRoot}${sep}`) || !basename(runDir).startsWith(RUN_DIR_PREFIX)) {
+    fail('Publisher directory is unavailable.')
+  }
+  return runDir
+}
+
+function readLocalImage(source) {
+  if (!source || !isAbsolute(source) || /^[a-z][a-z0-9+.-]*:/i.test(source) || source.startsWith('//')) {
+    fail('Publisher accepts an absolute local file, never a URL.')
+  }
+  let fd = -1
+  try {
+    const before = lstatSync(source)
+    if (!before.isFile() || before.isSymbolicLink() || before.size <= 0 || before.size > MAX_IMAGE_BYTES) {
+      fail('Source must be a supported local image no larger than 16 MiB.')
+    }
+    fd = openSync(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    if (!opened.isFile() || opened.size !== before.size || opened.ino !== before.ino || opened.dev !== before.dev) {
+      fail('Source image changed while publishing.')
+    }
+    const bytes = readFileSync(fd)
+    const after = fstatSync(fd)
+    if (after.size !== opened.size || after.ino !== opened.ino || after.dev !== opened.dev) {
+      fail('Source image changed while publishing.')
+    }
+    if (!isSupportedMagic(bytes)) fail('Only JPEG, PNG, WebP, HEIC, HEIF, or AVIF images can be published.')
+    return bytes
+  } catch (err) {
+    if (typeof err?.message === 'string' && err.message.startsWith('Source ')) throw err
+    fail('Source image is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function main() {
+  const [provenance, source, ...extra] = process.argv.slice(2)
+  if (!PROVENANCE.has(provenance) || !source || extra.length > 0) {
+    fail('Usage: publisher <generated|research|email> <absolute-local-image>')
+  }
+
+  const runDir = validateRunDir(process.env.COS_OUTPUT_IMAGE_DIR)
+  readCapability(runDir, process.env.COS_OUTPUT_IMAGE_TOKEN)
+  const bytes = readLocalImage(source)
+  const id = outputId(bytes)
+  const maxImages = configuredMaxImages()
+  const manifestPath = join(runDir, 'manifest.jsonl')
+  const items = validateItemsDir(runDir)
+  const itemsDir = items.path
+  const lockDir = acquireLock(runDir)
+
+  try {
+    const published = readManifestIds(manifestPath)
+    if (!published.has(id) && published.size >= maxImages) {
+      fail(maxImages === 0 ? 'This response cannot accept output images.' : `This response already has ${maxImages} published images.`)
+    }
+
+    const target = join(itemsDir, `${id}.img`)
+    if (!existsSync(target)) {
+      const tmp = join(itemsDir, `.${id}-${process.pid}.tmp`)
+      let fd = -1
+      try {
+        validateItemsDir(runDir, items)
+        fd = openSync(
+          tmp,
+          constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+          0o600,
+        )
+        const opened = fstatSync(fd)
+        if (!opened.isFile() || opened.nlink !== 1 || (opened.mode & 0o777) !== 0o600) {
+          fail('Publisher items directory is unavailable.')
+        }
+        // If the path was swapped between validation and open, detect that
+        // before writing any source bytes to the selected directory.
+        validateItemsDir(runDir, items)
+        writeSync(fd, bytes)
+        fsyncSync(fd)
+        closeSync(fd)
+        fd = -1
+        validateItemsDir(runDir, items)
+        renameSync(tmp, target)
+        validateItemsDir(runDir, items)
+      } finally {
+        if (fd >= 0) {
+          try { closeSync(fd) } catch { /* best effort */ }
+        }
+        try { rmSync(tmp, { force: true }) } catch { /* best effort */ }
+      }
+    }
+
+    if (!published.has(id)) {
+      const line = `${JSON.stringify({ v: 1, type: 'publish', id, provenance })}\n`
+      const fd = openSync(
+        manifestPath,
+        constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      )
+      try {
+        const stat = fstatSync(fd)
+        if (!stat.isFile()) fail('Publisher manifest is unavailable.')
+        writeSync(fd, line)
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+      chmodSync(manifestPath, 0o600)
+    }
+    process.stdout.write(`Published ${provenance} image.\n`)
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true })
+  }
+}
+
+try {
+  main()
+} catch (err) {
+  const message = err instanceof Error ? err.message : 'Image publication failed.'
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}

package/server/bootstrap.ts

@@ -0,0 +1,16 @@
+// Must remain the first import in server/index.ts. Claim the same machine-wide
+// slot used by the installed LaunchAgent before mutable routes or stores load.
+import './env.js'
+import { acquireServerInstanceLock, ServerInstanceActiveError } from './lib/server-instance-lock.js'
+
+try {
+  const instanceLock = acquireServerInstanceLock()
+  process.once('exit', instanceLock.release)
+} catch (error) {
+  if (error instanceof ServerInstanceActiveError) {
+    console.error(`[COS API] Startup refused: ${error.message}`)
+    process.exit(75)
+  }
+  console.error('[COS API] Startup refused: single-instance lock failed.', error)
+  process.exit(74)
+}

package/server/index.ts

@@ -1,12 +1,12 @@
-// Load .env FIRST — ESM evaluates this module before subsequent imports,
-// ensuring process.env is populated before python-bridge.ts reads COS_SCRIPTS_DIR.
-import './env.js'
+// Load env and claim the one server slot before any mutable module initializes.
+import './bootstrap.js'
 
 import express from 'express'
 import cors from 'cors'
 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 { networkInterfaces, homedir } from 'node:os'
 import { join } from 'node:path'
@@ -20,13 +20,24 @@ import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter } from './routes/transcribe-stream.js'
 import { openaiCompatRouter } from './routes/openai-compat.js'
 import { openaiKeyRouter } from './routes/openai-key.js'
+import { messageRefRouter } from './routes/message-ref.js'
+import { archiveRouter } from './routes/archive.js'
+import { sessionsRouter } from './routes/sessions.js'
+import { mediaRouter, mediaBodyParser } from './routes/media.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
+import { getCodexRunConfig } from './lib/codex-run-ledger.js'
+import {
+  startCodexModelCatalogRefresh,
+  stopCodexModelCatalogRefresh,
+} from './lib/codex-model-catalog.js'
 import { startWhisperServer, stopWhisperServer } from './lib/whisper-local.js'
 import { initSileroVAD } from './lib/vad-silero.js'
 import { initSessionCache } from './lib/session-cache-writer.js'
 import { initSpeakerEmbeddings } from './lib/speaker-embeddings.js'
 import { logActiveSessionsOnShutdown, startAutoSnapshot } from './lib/conversation.js'
+import { getMediaStore } from './lib/media-store.js'
+import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
 
 const app = express()
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -96,8 +107,6 @@ app.use(cors({
     cb(new Error('CORS blocked'))
   },
 }))
-app.use(express.json({ limit: '10mb' }))
-
 // Auth middleware — always active (token is auto-generated if not set)
 app.use('/api', (req, res, next) => {
   // Allow health checks, display stream, and client diagnostics without auth.
@@ -117,6 +126,11 @@ app.use('/api', (req, res, next) => {
   next()
 })
 
+// Authenticate before parsing large upload bodies. The 16 MB allowance stays
+// scoped to /api/media; every other route retains the 10 MB ceiling.
+app.use('/api/media', mediaBodyParser)
+app.use(express.json({ limit: '10mb' }))
+
 // Request counter — must be before route registrations
 app.use((_req, _res, next) => {
   serverMetrics.requestCount++
@@ -131,6 +145,12 @@ app.use('/api', transcribeRouter)
 app.use('/api', displayRouter)
 app.use('/api', transcribeStreamRouter)
 app.use('/api', openaiKeyRouter)
+// v6.3.0 — Message History, cross-day 'reference message N', and history
+// recovery for public npx users (previously full-COS-server only).
+app.use('/api', messageRefRouter)
+app.use('/api', archiveRouter)
+app.use('/api', sessionsRouter)
+app.use('/api', mediaRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -156,12 +176,19 @@ process.on('SIGTERM', () => {
   // Production stops (kill, service managers) send SIGTERM — flush session logs
   // exactly like SIGINT so active conversations aren't lost on shutdown.
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
+  stopCodexModelCatalogRefresh()
+  stopWhisperServer()
+  process.exit(0)
+})
+process.on('SIGINT', () => {
+  logActiveSessionsOnShutdown()
+  stopCodexModelCatalogRefresh()
   stopWhisperServer()
   process.exit(0)
 })
-process.on('SIGINT', () => { logActiveSessionsOnShutdown(); stopWhisperServer(); process.exit(0) })
 
-// Crash protection — log and survive instead of dying mid-meeting
+// Crash protection for runtime work. Listener failures are handled separately
+// and exit immediately so a supervisor can restart a clean, unified process.
 process.on('uncaughtException', (err) => {
   console.error('[CRASH GUARD] Uncaught exception (server stays alive):', err.message)
   console.error(err.stack)
@@ -176,19 +203,24 @@ process.on('unhandledRejection', (reason: any) => {
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const HTTPS_PORT = parseInt(process.env.HTTPS_PORT ?? '3143', 10)
 const certDir = path.join(__dirname, 'certs')
+const listeners: RequiredListener[] = []
 if (existsSync(path.join(certDir, 'cert.pem'))) {
   const httpsServer = createHttpsServer({
     cert: readFileSync(path.join(certDir, 'cert.pem')),
     key: readFileSync(path.join(certDir, 'key.pem')),
   }, app)
-  httpsServer.listen(HTTPS_PORT, BIND_HOST, () => {
-    console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
-  })
+  listeners.push({ server: httpsServer, port: HTTPS_PORT, host: BIND_HOST, label: 'HTTPS' })
 } else {
   console.log('[COS API] No certs found — HTTPS disabled (drop cert.pem/key.pem in server/certs to enable)')
 }
 
-app.listen(PORT, BIND_HOST, () => {
+const httpServer = createHttpServer(app)
+listeners.push({ server: httpServer, port: PORT, host: BIND_HOST, label: 'HTTP' })
+
+listenRequiredServers(listeners).then(() => {
+  if (listeners.some(listener => listener.label === 'HTTPS')) {
+    console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
+  }
   console.log(`[COS API] HTTP server running on http://${BIND_HOST}:${PORT}`)
   console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
 
@@ -220,15 +252,25 @@ app.listen(PORT, BIND_HOST, () => {
     console.log('')
   }
 
-  // Check Claude CLI availability — the chat backend
+  // Check Claude CLI availability. Codex-only installs remain fully valid.
+  let claudeAvailable = false
   try {
     execSync('claude --version', { timeout: 5000, stdio: 'pipe' })
+    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]   AI queries will not work without the Claude Code CLI')
+    console.warn('[COS API]   Claude models unavailable; Codex models still work when Codex CLI is installed')
   }
 
+  const codexConfig = getCodexRunConfig()
+  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.
+  startCodexModelCatalogRefresh()
+
   if (COS_MODE) {
     initSessionCache()
     // Pre-warm context cache so first query doesn't wait for the pipeline
@@ -243,9 +285,17 @@ app.listen(PORT, BIND_HOST, () => {
   const vadOk = initSileroVAD()
   console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
 
-  // Pre-warm the Claude CLI so the first query doesn't eat a 2-15s cold start
-  preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+  // Pre-warm Claude only when installed so Codex-only startup stays quiet.
+  if (claudeAvailable) {
+    preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+  }
 
   // Auto-snapshot active sessions every 5 min (survives restarts)
   startAutoSnapshot(5 * 60_000)
+
+  // Durable media GC (staged/reserved expiry + generated-image content TTL).
+  getMediaStore().startGC()
+}).catch((error: NodeJS.ErrnoException) => {
+  console.error(`[COS API] Fatal listener startup: ${error.message}`)
+  process.exit(error.code === 'EADDRINUSE' ? 75 : 74)
 })

package/server/lib/activity-preview.ts

@@ -0,0 +1,168 @@
+// Safe, bounded activity previews for the live job monitor. This module only
+// surfaces observable tool actions/results; it never exposes model reasoning.
+
+export interface ActivityPreviewLine {
+  kind: 'input' | 'output'
+  text: string
+}
+
+const ANSI_RE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))/g
+const PRIVATE_MATERIAL_BLOCK_RE = /-----BEGIN [A-Z0-9 ]*(?:PRIVATE KEY|CREDENTIALS?)-----[\s\S]*?(?:-----END [A-Z0-9 ]*(?:PRIVATE KEY|CREDENTIALS?)-----|$)/gi
+
+const SECRET_PATTERNS: Array<[RegExp, string]> = [
+  // Cookie headers are credential containers; partial parsing is unsafe.
+  [/\b((?:set-)?cookie\s*:\s*)[^\r\n]+/gi, '$1[redacted]'],
+  // Authorization and proxy-authorization headers, including Basic credentials.
+  [/\b((?:proxy-)?authorization\s*[:=]\s*)(?:bearer|basic|digest)\s+[^\s,;"']+/gi, '$1[redacted]'],
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [redacted]'],
+  // Structured assignments and JSON/env values. Key names are intentionally
+  // broad; a false-positive here is safer than putting a credential on a lens.
+  [/\b((?:[a-z0-9]+[_-])*(?:api[_-]?key|access[_-]?key(?:[_-]?id)?|access[_-]?token|refresh[_-]?token|session[_-]?token|token|credential|auth(?:orization)?|password|passwd|pwd|secret|client[_-]?secret|private[_-]?key|database[_-]?url|connection[_-]?string|dsn|session(?:[_-]?id)?|cookie|phpsessid|jsessionid|sid)(?:[_-][a-z0-9]+)*["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}&]+)/gi, '$1[redacted]'],
+  // Shell/env whitespace assignments such as `export TOKEN value`.
+  [/\b((?:export|set|env)\s+(?:[a-z0-9]+[_-])*(?:api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?token|token|credential|auth|password|passwd|pwd|secret|client[_-]?secret|private[_-]?key|database[_-]?url|connection[_-]?string|dsn|session(?:[_-]?id)?|cookie)\s+)(?:"[^"]*"|'[^']*'|\S+)/gi, '$1[redacted]'],
+  // Command-line flags commonly used for credentials.
+  [/(\s--?(?:api-key|token|access-token|refresh-token|password|passwd|secret|client-secret)(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/gi, '$1[redacted]'],
+  [/(\s(?:-u|--user)(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/gi, '$1[redacted]'],
+  // URL userinfo and secret-bearing query parameters.
+  [/([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]*:[^\s/@]+@/gi, '$1[redacted]@'],
+  [/([?&](?:api[_-]?key|access[_-]?token|token|auth|password|secret)=)[^&#\s]+/gi, '$1[redacted]'],
+  // Common provider token formats.
+  [/\b(?:sk-(?:proj-|live-|test-)?|sk_(?:live|test)_|sess-|pat-|gh[pousr]_|github_pat_|glpat-|npm_|pypi-|shpat_|xox[baprs]-)[A-Za-z0-9._-]{8,}\b/gi, '[redacted-token]'],
+  [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '[redacted-aws-key]'],
+  [/\bAIza[A-Za-z0-9_-]{30,}\b/g, '[redacted-google-key]'],
+  // JWTs and PEM material.
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '[redacted-jwt]'],
+  [/-----BEGIN [A-Z0-9 ]*(?:PRIVATE KEY|CREDENTIALS?)-----/gi, '[redacted-private-material]'],
+  [/-----END [A-Z0-9 ]*(?:PRIVATE KEY|CREDENTIALS?)-----/gi, '[redacted-private-material]'],
+]
+
+function looksOpaqueSecret(text: string): boolean {
+  const compact = text.replace(/\s/g, '')
+  if (compact.length < 40) return false
+  if (!/^[A-Za-z0-9+/=_:.-]+$/.test(compact)) return false
+
+  // PEM bodies are conventionally wrapped into 64-character base64 lines,
+  // but exporters commonly use widths from 40–72. Suppress every standalone
+  // base64/hex chunk in that range, including low-variety padding lines.
+  if (!/\s/.test(text) && /^(?:[A-Za-z0-9+/]{40,}={0,2}|[A-Fa-f0-9]{40,})$/.test(compact)) return true
+
+  // Ordinary prose rarely has this mix without spaces. Requiring several
+  // character classes avoids hiding long paths or repeated divider lines.
+  let classes = 0
+  if (/[a-z]/.test(compact)) classes++
+  if (/[A-Z]/.test(compact)) classes++
+  if (/\d/.test(compact)) classes++
+  if (/[+/=_:.-]/.test(compact)) classes++
+  return classes >= 3
+}
+
+export function sanitizeActivityPreview(raw: unknown, max = 180): string | null {
+  if (typeof raw !== 'string') return null
+  let text = raw.replace(ANSI_RE, '').replace(PRIVATE_MATERIAL_BLOCK_RE, '[private material hidden]')
+  for (const [pattern, replacement] of SECRET_PATTERNS) text = text.replace(pattern, replacement)
+  text = text.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim()
+  if (!text) return null
+  if (looksOpaqueSecret(text)) return '[opaque output hidden]'
+  const safeMax = Number.isFinite(max) && max >= 8 ? Math.floor(max) : 180
+  return text.length > safeMax ? `${text.slice(0, safeMax - 1)}…` : text
+}
+
+export function textPreviewLines(raw: unknown, maxLines = 3): string[] {
+  if (typeof raw !== 'string') return []
+  const safeMaxLines = Number.isFinite(maxLines) && maxLines > 0 ? Math.min(Math.floor(maxLines), 5) : 3
+  const lines = raw.replace(PRIVATE_MATERIAL_BLOCK_RE, '[private material hidden]').replace(/\r\n?/g, '\n').split('\n')
+    .map(line => sanitizeActivityPreview(line))
+    .filter((line): line is string => !!line)
+  return lines.slice(-safeMaxLines)
+}
+
+function resultText(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) {
+    const parts = value.flatMap((part) => {
+      if (typeof part === 'string') return [part]
+      if (typeof part?.text === 'string') return [part.text]
+      if (typeof part?.content === 'string') return [part.content]
+      return []
+    })
+    return parts.length ? parts.join('\n') : null
+  }
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    return resultText(record.content) ?? resultText(record.text) ?? resultText(record.output)
+  }
+  return null
+}
+
+/** Extract observable Codex tool activity from `codex exec --json` events. */
+export function codexActivityPreviewLines(event: any): ActivityPreviewLine[] {
+  const eventType = String(event?.type ?? '')
+  const item = event?.item ?? event?.payload ?? {}
+  const itemType = String(item?.type ?? '')
+  const lines: ActivityPreviewLine[] = []
+
+  if (/command_execution|command|shell|exec/i.test(itemType)) {
+    if (/started/i.test(eventType)) {
+      const command = sanitizeActivityPreview(item.command ?? item.input)
+      if (command) lines.push({ kind: 'input', text: `$ ${command}` })
+    }
+    const output = item.aggregated_output ?? item.output ?? item.stdout ?? item.stderr
+    for (const text of textPreviewLines(output)) lines.push({ kind: 'output', text })
+    if (/completed/i.test(eventType) && Number.isInteger(item.exit_code)) {
+      lines.push({ kind: 'output', text: `exit ${item.exit_code}` })
+    }
+    return lines
+  }
+
+  if (/file_change|patch/i.test(itemType)) {
+    const changes = Array.isArray(item.changes) ? item.changes : []
+    for (const change of changes.slice(-3)) {
+      const path = sanitizeActivityPreview(change?.path ?? change?.file)
+      if (path) lines.push({ kind: 'output', text: `${change?.kind ?? 'updated'} ${path}` })
+    }
+    return lines
+  }
+
+  if (/web_search/i.test(itemType)) {
+    const query = sanitizeActivityPreview(item.query)
+    if (query) lines.push({ kind: 'input', text: `Search: ${query}` })
+    return lines
+  }
+
+  if (/mcp_tool_call|tool_call|tool/i.test(itemType)) {
+    const name = sanitizeActivityPreview([item.server, item.tool ?? item.name].filter(Boolean).join('.'))
+    if (name && /started/i.test(eventType)) lines.push({ kind: 'input', text: name })
+    const text = resultText(item.result ?? item.output)
+    for (const preview of textPreviewLines(text)) lines.push({ kind: 'output', text: preview })
+  }
+
+  return lines
+}
+
+/** Extract text from Claude tool_result events, never assistant reasoning. */
+export function claudeToolResultPreviewLines(event: any): ActivityPreviewLine[] {
+  if (event?.type !== 'user') return []
+  const content = event?.message?.content ?? event?.content
+  if (!Array.isArray(content)) return []
+  const lines: ActivityPreviewLine[] = []
+  for (const block of content) {
+    if (block?.type !== 'tool_result') continue
+    const text = resultText(block.content)
+    for (const preview of textPreviewLines(text)) lines.push({ kind: 'output', text: preview })
+  }
+  return lines.slice(-3)
+}
+
+/** Turn completed Claude tool input JSON into one allowlisted useful line. */
+export function claudeToolInputPreview(name: string, rawJson: string): ActivityPreviewLine | null {
+  let input: Record<string, unknown> = {}
+  try { input = JSON.parse(rawJson || '{}') } catch { return null }
+  const candidate = input.query ?? input.url ?? input.file_path ?? input.path ?? input.command
+  const preview = sanitizeActivityPreview(candidate)
+  if (!preview) return null
+  const label = name === 'WebSearch' ? 'Search'
+    : name === 'WebFetch' ? 'Read'
+      : name === 'Read' ? 'File'
+        : name
+  return { kind: 'input', text: `${label}: ${preview}` }
+}