@gotcos/glasses-server 6.53.4 → 6.54.0

package/.env.example

@@ -252,6 +252,21 @@ BIND_HOST=0.0.0.0
 # tier for the rest of the day. Default 40.
 # COS_MEETING_SUMMARY_DAILY_CAP=40
 
+# ── LENS GIST: the summary behind the G2 prompt box (6.54.0) ────────────
+# Outcome / So what / You asked for a finished session or message, written by the
+# engine you pick: claude (default, when the Claude CLI is installed), codex, cursor,
+# ollama, or off. A mistyped engine is off. PUT /api/lens-gist/config saves the same
+# choice in the data dir; this setting wins over it.
+# COS_LENS_GIST_ENGINE=claude
+# COS_LENS_GIST_MODEL=sonnet
+#
+# Or a chain, asked in order when one fails, cools down or reports a usage limit.
+# Each engine in it sees the reply. COS_LENS_GIST_MODEL does not apply to a chain.
+# COS_LENS_GIST_ENGINE=claude:sonnet,codex:gpt-5.6-terra
+#
+# Answers per local day (attempts stop at twice this). Default 150.
+# COS_LENS_GIST_DAILY_CAP=150
+
 
 # ── RETAINED MEETING-AUDIO PLAYBACK CLEANUP (6.21.32 canary) ────────────
 # Default OFF. When enabled, the first authenticated Play of a retained raw

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 6.54.0
+
+### The summary behind the G2 prompt box, from the engine you choose
+
+COS Glasses 6.9.545 floats your words over a dimmed card of the session or message you are replying to. The server now writes that card: `Outcome` (`Answer` for a message), `So what` and `You asked`, from a reply the phone already holds. The engine is swappable the way the COS indexer's is: Claude, Codex, Cursor or a local Ollama model.
+
+- **`POST /api/lens-gist`** `{kind, ask, reply}` answers `ready` with the three lines, or `off`, `unavailable` (`cap`, `breaker`, `busy`, `retry-later`, `maintenance`) or `failed`, always as a 200 with a status; only a malformed request is a 400. **`GET /api/lens-gist/config`** lists the engines, whether each is installed, and the models it can run; **`PUT`** saves `{engine, model, dailyCap}` to `<data>/lens-gist.json`, which survives Update Server.
+- **The engine:** `COS_LENS_GIST_ENGINE` and `COS_LENS_GIST_MODEL`, then the saved choice, then Claude Sonnet when the Claude CLI is installed (off otherwise). One engine never falls back to another; a mistyped one, or a saved file that cannot be read, is off.
+- **A chain, for resilience:** `claude:sonnet,codex:gpt-5.6-terra` (env, or `PUT {"chain": ...}`) asks the next engine when one fails, is cooling down, or reports a spent session or usage limit, which opens that engine's breaker at once. A limit is read only from the provider's own error (the same pattern as the provider proof, including Claude Code's "You've hit your session limit", which it prints on stdout), never from the words of an answer. The chain shares one 70 s budget, and no engine starts on its last 3 s. A refusal from every engine reads as `breaker` only when every engine's breaker is open, so one engine's hiccup never pauses the phone. Opt-in only: a chain sends the reply to every provider in it; `PUT` takes either `engine` or `chain`, and a saved `off` wins. An answer any engine wrote is reused for the whole chain. Tested live: with Claude failing fast (a model it does not have), Codex Terra answered in 4.9 s end to end.
+- **Measured with the shipped prompt** on real replies: Claude Sonnet 2 to 5 s on about 1.2k tokens; Codex `gpt-5.6-terra` (the Codex default, the peer of Sonnet) 3.2 to 3.7 s on about 11.4k, `gpt-6-luna` and `gpt-6-sol` about 3 s on about 12k (Codex's own harness); Cursor `grok-4.7-low-fast` and `composer-2.5-fast` 11 to 13 s on about 11k to 17k; Ollama `qwen3.8:27b` 14 s cold. Claude Haiku timed out at 30 s twice.
+- **The reply is untrusted text.** Claude runs with no tools and every hook disabled; Codex with its shell, exec, image, agent, browser, computer, app and plugin tools disabled, web search off, no user config and no rules files; Cursor in ask mode (read-only tools) in an empty workspace; Ollama as a bare completion. Each call gets a private empty workspace, removed after it, and no server token in its environment. Text inside the exchange cannot close its own tag. Keys and tokens (OpenAI, GitHub, Slack, AWS, HubSpot, JWT, private keys and the server's own token) are redacted from cards, logs and the ledger.
+- **How it stops:** answers cached on disk per reply, engine and model; a daily cap of 150 answers (`COS_LENS_GIST_DAILY_CAP` or the saved `dailyCap`, kept when a save does not mention it) and twice that in attempts; a failed reply refused for 10 minutes, then 6 hours (a spent provider limit does not count against it); a breaker per engine (3 failures in a row or one limit answer, 30 minutes, then one trial call); at most 2 running and 4 waiting, with the cap, breaker and drain checked again before each engine. The route sits outside the request lease, so a slow model never holds up Update Server, and it answers `maintenance` during a drain.
+- **Visible:** a `g2-lens-gist` row in the token audit for every call, `<data>/lens-gist-runs.jsonl` (with `fallbackFrom` and `limit` when they apply), and `lens_gist` on `/api/health` (engine, model, calls today, cap, open breakers; no error text and no chain on the unauthenticated slice). Error text is redacted before it is cut, so a cut cannot split a token past the redaction.
+- Stated limits: a session reply reaches the phone cut to its first 4,000 characters, so a long reply's ending is not summarized. Cursor's ask mode keeps read-only tools; the CLI has no switch to remove them. COS Control 0.5.239 drops a `COS_LENS_GIST_*` value set only in the plist; use `~/.cos-glasses/.env` or `PUT /api/lens-gist/config`.
+- Checks: three /qa rounds (four reviewers; one per repo on the fixes; two on the chain before release). The limit reading is tested against real processes printing Claude Code's own failure shapes. 50 mutation cases, all killed from a green baseline. Full suite 5,214 passed, 2 skipped (343 files); typecheck clean; `npm audit --omit=dev` 0 vulnerabilities.
+
 ## 6.53.4
 
 ### The fixes from 6.53.3's review

package/README.md

@@ -300,6 +300,60 @@ reads `missing` and the phone stops asking to save it. Saving a known meeting th
 transcript answers **404 `nothing_to_save`** (with its state); only an unknown id answers
 `session_not_found`.
 
+## The summary behind the prompt box (6.54.0)
+
+When you hold the ring on a finished session or message, COS Glasses 6.9.545 floats your
+live words over a dimmed card of what you are replying to. From 6.54.0 the server writes
+that card: `Outcome` (`Answer` for a message), `So what` and `You asked`, one lens row
+each, instead of the reply's first lines. Older phones and older servers keep the
+6.9.544 card.
+
+**Pick the engine** the way the COS indexer does: `COS_LENS_GIST_ENGINE` wins, then the
+choice saved with `PUT /api/lens-gist/config`, then the default. One engine never falls back
+to another; `off` turns the summary off.
+
+**Or chain them, for resilience.** `claude:sonnet,codex:gpt-5.6-terra` asks Claude first and
+Codex when Claude fails, is cooling down, or says its session or usage limit is spent (a
+limit, read from the provider's own error and never from an answer, skips that engine for 30
+minutes at once). Running low on one plan no longer turns the summary off. A chain gets 70
+seconds in all, shared in order. It is opted into, never the default: it sends a session's
+reply to every provider in it, and an installed CLI is not consent (ChatGPT.app ships
+`codex`). `PUT` takes either `engine` or `chain`, never both, and a saved `off` wins.
+
+| Engine | Default model | Measured (2026-09-25, one call) | Tools it keeps |
+|---|---|---|---|
+| `claude` (default) | `sonnet` | 2 to 5 s, about 1.2k tokens | none (`--tools ""`, hooks off) |
+| `codex` | `gpt-5.6-terra` (`gpt-6-luna`, `gpt-6-sol` work as well) | 3.2 to 3.7 s, about 11.4k tokens | shell, browser, image, agent, app and plugin tools off; web search off |
+| `cursor` | `grok-4.7-low-fast` | 11 to 13 s, about 11k to 17k tokens | ask mode: read-only tools in an empty workspace |
+| `ollama` | the local model lens queries use | 2.5 s warm, 14 s cold | none |
+
+With nothing chosen and no Claude CLI installed, the summary is off rather than sent to a
+provider nobody picked. Claude `haiku` timed out at 30 s in testing and is not a default.
+
+```bash
+curl -s -X PUT -H "X-COS-Token: $COS_API_TOKEN" -H 'content-type: application/json' \
+  -d '{"chain":"claude:sonnet,codex:gpt-5.6-terra","dailyCap":150}' http://127.0.0.1:3141/api/lens-gist/config
+curl -s -X PUT -H "X-COS-Token: $COS_API_TOKEN" -H 'content-type: application/json' \
+  -d '{"engine":"codex","model":"gpt-6-sol"}' http://127.0.0.1:3141/api/lens-gist/config
+curl -s -H "X-COS-Token: $COS_API_TOKEN" http://127.0.0.1:3141/api/lens-gist/config
+```
+
+`GET /api/lens-gist/config` lists every engine, whether it is installed, and the models it
+can run here. The saved choice lives in `<data>/lens-gist.json` and survives Update
+Server; a file that cannot be read turns the summary off until it is saved again.
+
+**How it stops.** The phone asks once per finished reply it has open (a session that is
+still running or waiting on an approval asks for nothing). Answers are cached on disk per
+engine and model. A daily cap (`COS_LENS_GIST_DAILY_CAP` or the saved `dailyCap`, default
+150) counts answers, and attempts stop at twice that. A reply that failed is refused for 10
+minutes, then 6 hours (a spent provider limit does not count against the reply). Three
+failures in a row, or one limit answer, pause that engine for 30 minutes, then one trial call
+runs. At most 2 calls run at once with 4 waiting. A drain for Update Server stops queued
+calls before each engine. Every call writes a `g2-lens-gist` row to the token audit and a line
+to `<data>/lens-gist-runs.jsonl` (with `fallbackFrom` when a later engine answered).
+`/api/health` shows `lens_gist` (engine, model, calls today, cap, open breakers; no error text
+and no chain); `GET /api/lens-gist/config` shows the chain.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/managed-runtime-contract.json

@@ -34,7 +34,10 @@
     "COS_SESSION_HOOK_SSE",
     "COS_PERMISSION_BROKER",
     "COS_PERMISSION_BROKER_DESK_IDLE_S",
-    "COS_PERMISSION_BROKER_TIMEOUT_S"
+    "COS_PERMISSION_BROKER_TIMEOUT_S",
+    "COS_LENS_GIST_ENGINE",
+    "COS_LENS_GIST_MODEL",
+    "COS_LENS_GIST_DAILY_CAP"
   ],
   "maintenance": {
     "scope": "cross_boot",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.53.4",
+  "version": "6.54.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -92,6 +92,7 @@ import { glossaryRouter } from './routes/glossary.js'
 import { handoffsRouter } from './routes/handoffs.js'
 import { recoveryRouter } from './routes/recovery.js'
 import { promptEditRouter } from './routes/prompt-edit.js'
+import { lensGistRouter } from './routes/lens-gist.js'
 import { bookmarksRouter } from './routes/bookmarks.js'
 import { welcomeContextRouter } from './routes/welcome-context.js'
 import { liveCuesRouter } from './routes/live-cues.js'
@@ -311,6 +312,11 @@ app.use('/api', (req, res, next) => {
     || req.path.startsWith('/meeting-actions/')
     || req.path === '/meeting-engine/mode'
     || req.path.startsWith('/prompt-drafts')
+    // 6.54.0: a gist can wait behind two others and then run a chain for up to 70 s
+    // (LENS_GIST_CHAIN_BUDGET_MS), which could keep Control's 90 s drain waiting if it held
+    // the request lease. It refuses on its own while admissions are closed, and a queued
+    // chain checks again before each engine (routes/lens-gist.ts, lib/lens-gist.ts).
+    || req.path === '/lens-gist'
     || req.path.startsWith('/maintenance/drain')
   if (lifecycleOwned) return next()
 
@@ -889,6 +895,7 @@ app.use('/api', glossaryRouter)
 app.use('/api', handoffsRouter)
 app.use('/api', recoveryRouter)
 app.use('/api', promptEditRouter)
+app.use('/api', lensGistRouter)
 app.use('/api', bookmarksRouter)
 app.use('/api', welcomeContextRouter)
 app.use('/api', liveCuesRouter)

package/server/lib/lens-gist-engines.ts

@@ -0,0 +1,416 @@
+// The engines behind the lens gist (lens-gist.ts): one text-in, text-out call each, with no
+// session, no history and no MCP servers, in an empty workspace made for the call and
+// removed after it. Every runner rejects on any failure so the caller can count it against
+// that engine's breaker; the next engine of a chain answers, or the phone keeps its
+// verbatim card. A provider that says its limit is spent rejects with LensGistLimitError.
+//
+// WHAT EACH ENGINE CAN STILL DO (the reply is untrusted text: a web page an agent quoted
+// can carry instructions, /qa round 1 B1):
+//   claude  no tools at all (`--tools ""`), no hooks (`disableAllHooks`).
+//   codex   its shell, browser, computer-use, app and plugin tools disabled, web search
+//           off, no user config and no rules files.
+//   cursor  ask mode, which is read-only but keeps its read tools; the CLI has no switch to
+//           remove them. It reads an empty workspace, and what it answers is redacted.
+//   ollama  a bare completion: no tools.
+//
+// Measured 2026-09-25 (operations/personal/wk39_2026 in the COS repo): Claude Sonnet with the
+// tools off answered in 2 to 5 s on about 1.2k tokens; Claude Haiku with the flags the
+// dictation cleaner ships (no `--tools ""`) wrote a 26.5k-token cache of tool definitions.
+// Codex and Cursor carry 11 to 17k tokens of their own harness on every call.
+
+import { spawn } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { resolveProviderBinary } from './provider-binary.js'
+import { getOllamaCatalog, ollamaFetch, resolveOllamaOrigin } from './ollama-catalog.js'
+import { PROVIDER_QUOTA_RE } from './provider-proof.js'
+import { logTokenAudit } from './token-audit.js'
+
+/**
+ * The provider itself said its plan, session, rate or capacity limit is spent. Raised only
+ * from the provider's OWN output (its exit text, its JSON error, its failed-turn event),
+ * never from the words of an answer: /qa round 3 found a reply that mentioned "429s" or a
+ * "daily quota" opening a breaker. The caller opens that engine's breaker at once.
+ */
+export class LensGistLimitError extends Error {
+  readonly limit = true
+}
+
+/** An error for this failure: a limit when the provider's raw words say so. */
+export function engineFailure(message: string, providerText: string): Error {
+  return PROVIDER_QUOTA_RE.test(providerText) ? new LensGistLimitError(message) : new Error(message)
+}
+
+export type LensGistEngineName = 'claude' | 'codex' | 'cursor' | 'ollama'
+
+export interface LensGistUsage {
+  inputTokens?: number
+  outputTokens?: number
+  cachedInputTokens?: number
+  costUsd?: number
+}
+
+export interface LensGistEngineRun {
+  text: string
+  usage?: LensGistUsage
+  /** The model the engine reports it ran, when it says. */
+  model?: string
+}
+
+export interface LensGistRunOptions {
+  timeoutMs: number
+  system: string
+}
+
+/** Replaces Claude Code's own system prompt, so the call carries none of it. */
+export const LENS_GIST_SYSTEM_PROMPT = 'You write three-line summaries for a smart-glasses card. Output only the lines asked for.'
+
+const SECRET_PATTERNS: Array<[RegExp, string]> = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, '[private key]'],
+  [/\bsk-[A-Za-z0-9_*.-]{6,}/g, 'sk-REDACTED'],
+  [/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi, '$1REDACTED'],
+  [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, 'gh-REDACTED'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'gh-REDACTED'],
+  [/\bxox[abposr]-[A-Za-z0-9-]{10,}\b/g, 'xox-REDACTED'],
+  [/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, 'AWS-REDACTED'],
+  [/\bpat-(?:na|eu|ap)\d-[0-9a-f-]{20,}\b/gi, 'pat-REDACTED'],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, 'jwt-REDACTED'],
+]
+
+/** A key or token never reaches a log, the cache or the lens, whichever side echoed it. */
+export function redactSecrets(text: string): string {
+  let out = text
+  for (const [re, to] of SECRET_PATTERNS) out = out.replace(re, to)
+  const own = process.env.COS_API_TOKEN
+  if (own && own.length >= 12) out = out.split(own).join('COS-TOKEN-REDACTED')
+  return out
+}
+
+/** A fresh, private, empty directory for one call: nothing planted in it, nothing to read. */
+function withScratchWorkspace<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), 'cos-lens-gist-'))
+  return fn(dir).finally(() => {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* best effort */ }
+  })
+}
+
+/** Nothing the server itself holds reaches a model's process. */
+const STRIPPED_ENV = ['CLAUDECODE', 'COS_API_TOKEN']
+
+export function lensGistChildEnv(binary: string): NodeJS.ProcessEnv {
+  const env = { ...process.env }
+  for (const key of STRIPPED_ENV) delete env[key]
+  // A launchd- or Finder-spawned server has a minimal PATH, and `claude` is a node script:
+  // resolving the binary is not enough, its interpreter must be findable too.
+  const dirs = [dirname(binary), '/opt/homebrew/bin', '/usr/local/bin']
+  const path = env.PATH ?? ''
+  env.PATH = [...dirs.filter(dir => !path.split(':').includes(dir)), path].filter(Boolean).join(':')
+  return env
+}
+
+interface ProcessResult {
+  code: number | null
+  stdout: string
+  stderr: string
+}
+
+/** Spawn, write the prompt to stdin, collect both streams; SIGTERM then SIGKILL on timeout. */
+export function runProcess(
+  binary: string,
+  args: string[],
+  opts: { stdin: string; cwd: string; timeoutMs: number; label: string },
+): Promise<ProcessResult> {
+  return new Promise((resolve, reject) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let killTimer: NodeJS.Timeout | null = null
+    const proc = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'], env: lensGistChildEnv(binary), cwd: opts.cwd })
+    const finish = (fn: () => void) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn()
+    }
+    const terminate = () => {
+      try { proc.kill('SIGTERM') } catch { /* already gone */ }
+      killTimer = setTimeout(() => { try { proc.kill('SIGKILL') } catch { /* already gone */ } }, 2_000)
+      killTimer.unref?.()
+    }
+    const timer = setTimeout(() => finish(() => {
+      terminate()
+      reject(new Error(`${opts.label} timed out after ${opts.timeoutMs} ms${stderr ? `: ${redactSecrets(stderr).slice(-200)}` : ''}`))
+    }), opts.timeoutMs)
+    proc.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+    proc.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+    proc.on('error', err => finish(() => reject(err)))
+    proc.on('close', code => {
+      if (killTimer) clearTimeout(killTimer)
+      finish(() => resolve({ code, stdout, stderr }))
+    })
+    proc.stdin.on('error', err => finish(() => { terminate(); reject(err) }))
+    try {
+      proc.stdin.end(opts.stdin)
+    } catch (err) {
+      finish(() => { terminate(); reject(err instanceof Error ? err : new Error(String(err))) })
+    }
+  })
+}
+
+function binaryFor(provider: 'claude' | 'codex' | 'cursor'): string {
+  const resolved = resolveProviderBinary(provider)
+  if (!resolved.ok) throw new Error(`${provider} binary not found (${resolved.detail})`)
+  return resolved.path
+}
+
+function num(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function lastJsonObject(stdout: string): any {
+  const lines = stdout.trim().split('\n').reverse()
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('{')) continue
+    try { return JSON.parse(trimmed) } catch { /* keep looking */ }
+  }
+  throw new Error('no JSON result in the output')
+}
+
+// --- Claude ---------------------------------------------------------------------------
+
+export function buildClaudeGistArgs(model: string, system: string): string[] {
+  return [
+    '-p', '--model', model, '--effort', 'low',
+    // No tools: nothing to act on an instruction hidden in the reply, and ~1.2k tokens a
+    // call instead of a cache of tool definitions. claude-permissions.ts records an empty
+    // --tools causing a spurious compaction and a synthetic 400 on the 2026-08-26 CLI, in
+    // long bridge sessions; this one-shot call was measured clean on the 2026-09-25 CLI, and
+    // a regression lands on this engine's breaker, not on the lens.
+    '--tools', '',
+    '--output-format', 'json', '--no-session-persistence',
+    '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
+    // The user's own hooks (session trackers, prompt loggers) would otherwise spool every
+    // reply this summarizes. Proven 2026-09-25: a hook set in the same call did not fire.
+    '--settings', '{"disableAllHooks":true}',
+    '--system-prompt', system,
+  ]
+}
+
+/** `claude -p --output-format json`: one result object. */
+export function parseClaudeGistOutput(stdout: string): LensGistEngineRun {
+  const result = lastJsonObject(stdout)
+  if (result?.is_error || (result?.subtype && result.subtype !== 'success')) {
+    throw new Error(`claude: ${redactSecrets(String(result?.result ?? result?.subtype ?? 'error')).slice(0, 200)}`)
+  }
+  const text = typeof result?.result === 'string' ? result.result : ''
+  const usage = result?.usage ?? {}
+  const cacheIn = (num(usage.cache_creation_input_tokens) ?? 0) + (num(usage.cache_read_input_tokens) ?? 0)
+  // `sonnet` is an alias; modelUsage names what it resolved to.
+  const resolved = result?.modelUsage && typeof result.modelUsage === 'object' ? Object.keys(result.modelUsage)[0] : undefined
+  return {
+    text,
+    ...(resolved ? { model: resolved } : {}),
+    usage: {
+      inputTokens: (num(usage.input_tokens) ?? 0) + cacheIn,
+      cachedInputTokens: num(usage.cache_read_input_tokens),
+      outputTokens: num(usage.output_tokens),
+      costUsd: num(result?.total_cost_usd),
+    },
+  }
+}
+
+// --- Codex ----------------------------------------------------------------------------
+
+/**
+ * Codex tools switched off for a gist (`codex features list`, CLI 0.155; /qa round 2 found
+ * view_image, multi_agent, image_generation, unified_exec and hooks still on after round 1).
+ * An unknown name is an error on this CLI, so a renamed feature fails loudly on the breaker.
+ */
+export const CODEX_GIST_DISABLED_FEATURES = [
+  'shell_tool', 'unified_exec', 'view_image', 'multi_agent', 'image_generation', 'hooks',
+  'browser_use', 'browser_use_external', 'computer_use', 'in_app_browser', 'apps', 'plugins',
+] as const
+
+export function buildCodexGistArgs(model: string, workspace: string): string[] {
+  return [
+    'exec',
+    // No config.toml (its MCP servers, profiles, model settings) and no rules files. Auth
+    // still comes from CODEX_HOME, and AGENTS.md discovery starts at the empty workspace.
+    '--ignore-user-config',
+    '--ignore-rules',
+    // A read-only sandbox still lets the shell read the whole disk; the shell is off.
+    ...CODEX_GIST_DISABLED_FEATURES.flatMap(feature => ['--disable', feature]),
+    '-c', 'web_search="disabled"',
+    '--sandbox', 'read-only',
+    '--skip-git-repo-check',
+    '--ephemeral',
+    '--json',
+    '--cd', workspace,
+    '--model', model,
+    '-c', 'model_reasoning_effort="low"',
+    '-',
+  ]
+}
+
+/** `codex exec --json`: JSON lines; the answer is the last agent message. */
+export function parseCodexGistOutput(stdout: string): LensGistEngineRun {
+  let text = ''
+  let usage: LensGistUsage | undefined
+  let failure = ''
+  for (const line of stdout.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('{')) continue
+    let event: any
+    try { event = JSON.parse(trimmed) } catch { continue }
+    const item = event?.item
+    if (event?.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string') text = item.text
+    if (event?.type === 'turn.completed') {
+      const u = event.usage ?? {}
+      usage = { inputTokens: num(u.input_tokens), cachedInputTokens: num(u.cached_input_tokens), outputTokens: num(u.output_tokens) }
+    }
+    if (event?.type === 'turn.failed') failure = String(event?.error?.message ?? 'turn failed')
+  }
+  if (failure) throw new Error(`codex: ${redactSecrets(failure).slice(0, 200)}`)
+  return { text, usage }
+}
+
+// --- Cursor ---------------------------------------------------------------------------
+
+export function buildCursorGistArgs(model: string, workspace: string): string[] {
+  // Ask mode is read-only; the workspace is an empty directory, so there is nothing to read.
+  return ['-p', '--mode', 'ask', '--model', model, '--output-format', 'json', '--trust', '--workspace', workspace]
+}
+
+/** `agent -p --output-format json`: one result object. */
+export function parseCursorGistOutput(stdout: string): LensGistEngineRun {
+  const result = lastJsonObject(stdout)
+  if (result?.is_error || (result?.subtype && result.subtype !== 'success')) {
+    throw new Error(`cursor: ${redactSecrets(String(result?.result ?? result?.subtype ?? 'error')).slice(0, 200)}`)
+  }
+  const usage = result?.usage ?? {}
+  return {
+    text: typeof result?.result === 'string' ? result.result : '',
+    usage: {
+      inputTokens: num(usage.inputTokens) ?? num(usage.input_tokens),
+      outputTokens: num(usage.outputTokens) ?? num(usage.output_tokens),
+      cachedInputTokens: num(usage.cacheReadTokens) ?? num(usage.cache_read_input_tokens),
+    },
+  }
+}
+
+// --- Dispatch -------------------------------------------------------------------------
+
+/** The failure text of a non-zero exit, redacted BEFORE it is cut (a cut token escapes). */
+function failedExitMessage(label: string, result: ProcessResult): string {
+  // Claude Code prints a spent limit on STDOUT and exits 1; stderr may carry other noise.
+  const text = redactSecrets([result.stderr.trim(), result.stdout.trim()].filter(Boolean).join('\n'))
+  const detail = text.split('\n').slice(-3).join(' ').slice(0, 240)
+  return `${label} exited ${result.code ?? 'by signal'}${detail ? `: ${detail}` : ''}`
+}
+
+async function runCli(
+  provider: 'claude' | 'codex' | 'cursor',
+  args: (workspace: string) => string[],
+  prompt: string,
+  opts: LensGistRunOptions,
+  parse: (stdout: string) => LensGistEngineRun,
+): Promise<LensGistEngineRun> {
+  const binary = binaryFor(provider)
+  const result = await withScratchWorkspace(workspace =>
+    runProcess(binary, args(workspace), { stdin: prompt, cwd: workspace, timeoutMs: opts.timeoutMs, label: provider }))
+  const providerText = `${result.stdout}\n${result.stderr}`
+  if (result.code !== 0) {
+    // Codex reports its failure as a JSON event AND a non-zero exit; the event says why.
+    if (provider === 'codex') {
+      try { parse(result.stdout) } catch (err) { throw engineFailure(err instanceof Error ? err.message : String(err), providerText) }
+    }
+    throw engineFailure(failedExitMessage(provider, result), providerText)
+  }
+  let run: LensGistEngineRun
+  try {
+    run = parse(result.stdout)
+  } catch (err) {
+    // A JSON result marked as an error (Claude, Cursor) can be a limit too.
+    throw engineFailure(err instanceof Error ? err.message : String(err), providerText)
+  }
+  if (!run.text.trim()) throw new Error(`${provider} returned no text`)
+  return run
+}
+
+async function runOllama(model: string, prompt: string, opts: LensGistRunOptions): Promise<LensGistEngineRun> {
+  const origin = resolveOllamaOrigin()
+  if (!origin.ok) throw new Error(`ollama: ${origin.error}`)
+  const chosen = model || (await getOllamaCatalog()).model
+  if (!chosen) throw new Error('ollama: no local model installed')
+  const abort = new AbortController()
+  const timer = setTimeout(() => abort.abort(), opts.timeoutMs)
+  try {
+    const response = await ollamaFetch(`${origin.origin}/api/generate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model: chosen,
+        system: opts.system,
+        prompt,
+        stream: false,
+        think: false,
+        // Loading a 27B model cold took 14 s of a 16.5 s call; kept warm it answered in 2.5 s.
+        keep_alive: '30m',
+        options: { temperature: 0.2, num_predict: 200 },
+      }),
+      signal: abort.signal,
+    })
+    if (!response.ok) throw new Error(`ollama answered ${response.status}`)
+    const body = await response.json() as any
+    const text = typeof body?.response === 'string' ? body.response : ''
+    if (!text.trim()) throw new Error('ollama returned no text')
+    return { text, model: chosen, usage: { inputTokens: num(body?.prompt_eval_count), outputTokens: num(body?.eval_count) } }
+  } catch (err) {
+    if (abort.signal.aborted) throw new Error(`ollama timed out after ${opts.timeoutMs} ms`)
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function dispatch(engine: LensGistEngineName, model: string, prompt: string, opts: LensGistRunOptions): Promise<LensGistEngineRun> {
+  switch (engine) {
+    case 'claude':
+      return runCli('claude', () => buildClaudeGistArgs(model, opts.system), prompt, opts, parseClaudeGistOutput)
+    case 'codex':
+      return runCli('codex', workspace => buildCodexGistArgs(model, workspace), prompt, opts, parseCodexGistOutput)
+    case 'cursor':
+      return runCli('cursor', workspace => buildCursorGistArgs(model, workspace), prompt, opts, parseCursorGistOutput)
+    case 'ollama':
+      return runOllama(model, prompt, opts)
+  }
+}
+
+/** One engine call, and one row in the shared token audit either way (source g2-lens-gist). */
+export async function runLensGistEngine(
+  engine: LensGistEngineName,
+  model: string,
+  prompt: string,
+  opts: LensGistRunOptions,
+): Promise<LensGistEngineRun> {
+  const started = Date.now()
+  let outputChars = 0
+  let resolvedModel = model
+  try {
+    const run = await dispatch(engine, model, prompt, opts)
+    outputChars = run.text.length
+    resolvedModel = run.model || model
+    return run
+  } finally {
+    logTokenAudit({
+      source: 'g2-lens-gist',
+      caller: 'lens_gist',
+      model: `${engine}:${resolvedModel || 'default'}`,
+      inputChars: prompt.length + opts.system.length,
+      outputChars,
+      durationMs: Date.now() - started,
+    })
+  }
+}