thinkpool-pair 0.7.190 → 0.7.192

package/account.mjs

@@ -102,6 +102,10 @@ export async function runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) {
   const poll = async () => {
     if (Date.now() - started > 5 * 60 * 1000) { process.stderr.write('\n  ◇ link timed out — run `npx thinkpool-pair login` again.\n'); process.exit(1) }
     try {
+      // A discarded `error` costs one tick — the loop retries in a second, and a
+      // permanent failure still lands on the "link timed out" branch above rather than
+      // hanging. Nothing is persisted here, so nothing can be silently lost.
+      // fail-open-ok: read-only poll; a lost tick retries, and permanent failure times out loudly
       const { data: r } = await sb.rpc('claim_device_code', { p_device_code: device_code })
       if (r?.status === 'approved' && r.session?.refresh_token) {
         saveAuth(r.session)
@@ -1086,6 +1090,12 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     for (const { channel } of pairChannels.values()) { try { sb.removeChannel(channel) } catch { /* noop */ } }   // tear down pair buses (Tier 2/3)
     // Flush the presence LEAVE before exiting so the dashboard flips to
     // "not connected" in realtime (don't fire-and-forget the untrack).
+    //
+    // Shutdown teardown; the process is already exiting. A lost `release_bridge` leaves
+    // the claim to expire on its own TTL — degraded (the dashboard shows "connected"
+    // until it lapses), never lost data. No caller remains to surface an error to, and a
+    // throw here would skip process.exit.
+    // fail-open-ok: exit-path teardown; a lost release_bridge expires on its own TTL
     ;(async () => { try { if (claimHeld) await sb.rpc('release_bridge', { p_bridge_id: BRIDGE_ID }) } catch { /* noop */ } try { await acct.untrack() } catch { /* noop */ } try { await sb.removeChannel(acct) } catch { /* noop */ } process.exit(code) })()
     setTimeout(() => process.exit(code), 1500)   // hard backstop if the flush hangs
   }

package/bridge.mjs

@@ -50,6 +50,7 @@ import { validateProviderSwitch, providerSwitchPlan, BUILTIN_PROVIDER } from './
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
+import { startCodexSession, readCodexDefaultModel, readCodexModels } from './codex-session.mjs'
 import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, buildConductorEnv, assembleCrossWaveContext, buildLanePrompt } from './flow-conductor.mjs'
 import { normalizePlanOutput, laneModelFor } from './flow-task-graph.mjs'   // FL-B1 — validate the conductor's submit_flow_plan task-graph; laneModelFor — per-slice model tier (2026-07-03-flow-lane-model-tiers)
 // S1 (context-offload) — durable digest store. mark_flow_done digests a closed slice in;
@@ -456,7 +457,11 @@ const STRUCTURED = process.env.TP_STRUCTURED === '1' || argv.includes('--structu
 // Claude Code runs as a STRUCTURED Agent-SDK session by default now (the picked
 // design — structured reader, risk-tiered permissions). Other CLIs keep the PTY
 // relay. TP_PTY=1 forces claude back to the raw PTY if ever needed.
-const wantStructured = (cmd) => /(^|[/\\])claude$/.test(cmd || '') && process.env.TP_PTY !== '1'
+const structuredRuntime = (cmd) => {
+  const bin = path.basename(String(cmd || '')).toLowerCase()
+  return bin === 'codex' ? 'codex' : bin === 'claude' ? 'claude' : null
+}
+const wantStructured = (cmd) => !!structuredRuntime(cmd) && process.env.TP_PTY !== '1'
 const installedAgents = KNOWN_AGENTS.filter(a => onPath(a.cmd))
 const dashIdx = argv.indexOf('--')
 // Own flags are only read from BEFORE `--`; after it, every token belongs
@@ -1065,7 +1070,7 @@ const announce = () => {
       // turnActive). Authoritative — the bridge owns the turn — so the /code
       // dashboard reads "N agents working" off the roster instead of sniffing
       // the live code-event stream (which a passive dashboard channel misses).
-      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', alive: true, busy: s.session?.turnActive ?? false, commands: s.commands, mode: s.mode || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
+      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, busy: s.session?.turnActive ?? false, commands: s.commands, mode: s.mode || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: 'never', models: s.models || [] } : {}), ...(s.archiveOldestSeq != null ? { oldestSeq: s.archiveOldestSeq } : {}), ...(s.spawnedBy ? { spawned: true, spawnedBy: s.spawnedBy } : {}), ...(s.flowSessionId ? { flowId: s.flowSessionId, flowRole: s.flowTaskKey ? 'lane' : 'conductor' } : {}),
         // provider: the registered LLM-provider this lane runs on, NAME-ONLY {id,name}
         // (NEVER the key or baseUrl). Additive; older clients ignore it. Omitted for the
         // built-in/default Claude path (no badge). Makes the lane's provider badge +
@@ -1558,8 +1563,10 @@ function worktreeSnapshot(cwd) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
+function openStructured({ id, runtime = 'claude', model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage }) {
   if (sessions.has(id)) return
+  runtime = runtime === 'codex' ? 'codex' : 'claude'
+  if (runtime === 'codex') mode = 'bypassPermissions'
   // The lane's EFFECTIVE model — computed ONCE and used for BOTH the truthful display
   // label (entry.model) and the SDK's `model` option below. These used to be computed
   // separately: the label resolved the provider's configured model while the SDK got the
@@ -1567,11 +1574,13 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
   // lane opened while focused on Fable therefore showed `glm-4.6` and sent
   // `claude-fable-5` → 400 [1211][Unknown Model]. One value, one truth.
   // undefined → omit the SDK option entirely and let the provider env/endpoint default.
-  const laneModel = effectiveLaneModel({ provider, model, configuredModel: resolveProviderEnv(provider)?.ANTHROPIC_MODEL })
+  const laneModel = runtime === 'codex'
+    ? (model || readCodexDefaultModel() || undefined)
+    : effectiveLaneModel({ provider, model, configuredModel: resolveProviderEnv(provider)?.ANTHROPIC_MODEL })
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
-  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode,
+  const entry = { cmd: runtime, runtime, kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, models: runtime === 'codex' ? readCodexModels() : undefined,
     // model: truthful active-model label — now the SAME `laneModel` the SDK is given, so the
     // chip cannot disagree with the wire. When this lane runs on a custom (non-anthropic)
     // registered provider the SDK id is impersonated (see the onEvent guard below), so
@@ -1579,7 +1588,9 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     // No configured model → the provider's NAME, never a false Claude id (an inherited
     // claudeish id was dropped upstream by effectiveLaneModel; it must not sneak back in as a
     // label fallback here). Built-in Anthropic keeps the passed model.
-    model: (!provider || provider === 'anthropic')
+    model: runtime === 'codex'
+      ? (laneModel || null)
+      : (!provider || provider === 'anthropic')
       ? (laneModel || null)
       : (laneModel || providerNameMap()[provider] || provider),
     provider: provider || null, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null,
@@ -1773,7 +1784,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
   // restart. Without this, sessionData omitted it → on restart the resumed session
   // re-launched on the host default (Opus) regardless of the last switch, and the
   // switch looked like it "never changed the model" (Max 2026-07-02). Restored below.
-  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null })
+  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, runtime: entry.runtime, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null, lastUsage: entry.lastUsage || null })
   const persist = () => saveSession(room, id, sessionData())
   // Synchronous flush of this session's record. Used on open (so a brand-new session
   // has a file under its id BEFORE its first event — surviving a restart inside the
@@ -1940,11 +1951,14 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
           task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
           model: z.string().optional().describe('optional model for the lane, e.g. opus / sonnet / haiku'),
+          runtime: z.enum(['claude', 'codex']).optional().describe('agent runtime for the new lane; defaults to inheriting this lane'),
           provider: z.string().optional().describe('optional registered LLM provider id to run this lane on (from the account\'s provider registry); omit for the default Claude/Anthropic path'),
           mode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).optional().describe('permission mode for the new lane; defaults to inheriting YOUR current mode. Raising a lane to bypassPermissions from a non-bypass lane asks the room to confirm once.'),
         },
         async (args) => {
           const okText = (t) => ({ content: [{ type: 'text', text: t }] })
+          const childRuntime = args?.runtime || entry.runtime || 'claude'
+          if (childRuntime === 'codex' && args?.provider) return okText('A Codex lane uses its Codex/OpenAI login in v1; custom bridge providers are not wired to Codex yet. Omit provider or spawn a Claude lane for that provider.')
           const now = Date.now()
           const gate = spawnDecision({
             hop: entry.hop || 0,
@@ -1979,7 +1993,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           // plan-mode lane would stall on ExitPlanMode cards. An explicit args.mode still wins;
           // otherwise inherit, but fall plan → default (an autonomous worker doesn't plan-gate).
           const childMode = args?.mode || (entry.mode === 'plan' ? 'default' : entry.mode)
-          openStructured({ id: newId, model: args?.model, provider: args?.provider, mode: childMode })
+          openStructured({ id: newId, runtime: childRuntime, model: args?.model, provider: args?.provider, mode: childMode })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.spawnedBy = id   // ownership: only the spawner may close_terminal it
@@ -2113,7 +2127,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
   // on the init `system` event (see onEvent) — a sendTurn before the input stream is consumed
   // is silently lost (the 2026-07-02 auto-resume bug). Empty string → nothing to carry.
   entry.pendingRecap = (typeof carryRecap === 'string' && carryRecap.trim()) ? carryRecap : null
-  entry.session = startClaudeSession({
+  entry.session = (runtime === 'codex' ? startCodexSession : startClaudeSession)({
     // laneModel, NOT the raw `model` param: the SDK's `model` option OVERRIDES the
     // ANTHROPIC_MODEL supplied by resolveProviderEnv() in `env` below, so an inherited
     // Claude id here defeats the whole per-provider env. undefined → option omitted.
@@ -2195,7 +2209,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
         try { entry.session?.end() } catch { /* noop */ }
         try { entry.mockupWatcher?.close() } catch { /* noop */ }
         sessions.delete(id)
-        openStructured({ id, model, log: entry.log, commands: entry.commands, mode: entry.mode })
+        openStructured({ id, runtime: entry.runtime, model, log: entry.log, commands: entry.commands, mode: entry.mode })
         return
       }
       // Stamp a wall-clock ts AND a stable cid on every transcript event before
@@ -2510,7 +2524,7 @@ function respawnStructured(id, provider) {
   // openStructured seed from the TARGET provider's configured model, which is the
   // only model this lane was ever asked for. A same-env model change never reaches
   // here — that path is an in-place setModel (see provider-switch).
-  const { log, commands, mode, spawnedBy, flowSessionId, flowTaskKey, cwd, rolePrompt, reviewSliceRoots, openedAt } = s
+  const { runtime, log, commands, mode, spawnedBy, flowSessionId, flowTaskKey, cwd, rolePrompt, reviewSliceRoots, openedAt } = s
   // Context-carry (2026-07-08): a provider switch is not an SDK resume — the new backend
   // starts blank mid-conversation. Synthesize a plain-text recap from the VISIBLE log NOW
   // (before teardown) and hand it to the fresh session as its first turn so the agent
@@ -2528,7 +2542,7 @@ function respawnStructured(id, provider) {
   // sessionData() (provider included) synchronously on open, so a bridge restart
   // restores the lane on its CURRENT provider, not the original — and its next
   // announce carries the new provider badge (additive {id,name} projection).
-  openStructured({ id, provider, log, commands, mode, spawnedBy, flowSessionId, flowTaskKey, cwd, rolePrompt, reviewSliceRoots, openedAt, carryRecap })
+  openStructured({ id, runtime, provider, log, commands, mode, spawnedBy, flowSessionId, flowTaskKey, cwd, rolePrompt, reviewSliceRoots, openedAt, carryRecap })
   return true
 }
 
@@ -2686,7 +2700,8 @@ channel
       // previous terminal's model (and the first uses the provider default). Falls
       // through to the SDK default when absent. Stamped on the entry so the announce
       // carries it at open (chip shows the model immediately, not the branch).
-      openStructured({ id: payload.id, mode: payload.mode, model: payload.model || undefined, provider: payload.provider || undefined })
+      const runtime = structuredRuntime(payload.cmd)
+      openStructured({ id: payload.id, runtime, mode: payload.mode, model: payload.model || undefined, provider: runtime === 'codex' ? undefined : payload.provider || undefined })
       process.stderr.write(`\n  ◆ web opened a structured "${payload.cmd}" session (${payload.mode || 'default'}${payload.model ? `, model ${payload.model}` : ''}).\n`)
       return
     }
@@ -2822,7 +2837,7 @@ channel
   // ── structured-session control (Phase 2) ──
   .on('broadcast', { event: 'code-open' }, ({ payload }) => {
     if (payload?.host && payload.host !== name) return
-    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, provider: payload?.provider, resume: payload?.resume, mode: payload?.mode })
+    openStructured({ id: payload?.id || randomUUID(), runtime: payload?.runtime, model: payload?.model, provider: payload?.runtime === 'codex' ? undefined : payload?.provider, resume: payload?.resume, mode: payload?.mode })
   })
   .on('broadcast', { event: 'code-turn' }, async ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
@@ -2864,7 +2879,10 @@ channel
     const mm = text.match(/^\/model\b\s*(\S+)?/)
     if (mm) {
       if (mm[1]) {
-        s.session.setModel(mm[1])
+        if (s.session.setModel(mm[1]) === false) {
+          ctlLine(s.runtime === 'codex' ? 'finish or stop the current Codex turn before switching models' : 'model switch unavailable right now')
+          return
+        }
         // Reflect the switch in the announce IMMEDIATELY (before any turn). The SDK
         // only echoes the resolved full id on the next turn, and meta/ctx model go
         // stale until then, so without this the chip snapped back to the old model
@@ -2885,7 +2903,8 @@ channel
     }
     if (/^\/clear\s*$/.test(text)) {
       s.pendingRecap = null   // /clear means forget context — drop any un-fired carry recap
-      s.session.sendTurn(text)
+      if (s.runtime === 'codex') s.session.clearContext?.()
+      else s.session.sendTurn(text)
       // The seq reset is load-bearing on BOTH ends: the client's clear handler sets
       // seqHi = 0 (room.jsx), so the counter must restart with it. The durable archive
       // is append-only and keeps the pre-clear era under colliding seqs — session-store's
@@ -2903,6 +2922,10 @@ channel
     // track so onEvent clears it + attributes the recap card when the SDK turn finishes.
     // No persisted ctl line — the live indicator + the CompactionCard are the record.
     if (/^\/compact\b/.test(text)) {
+      if (s.runtime === 'codex') {
+        ctlLine('Codex manages context compaction automatically')
+        return
+      }
       s.compacting = true
       s.compactBy = payload.by
       bcast('code-event', { term: payload.term, evt: { kind: 'compact', status: 'start', ts: Date.now() } })
@@ -2961,6 +2984,11 @@ channel
   .on('broadcast', { event: 'code-mode' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
     if (s) {
+      if (s.runtime === 'codex') {
+        s.mode = 'bypassPermissions'
+        announce()
+        return
+      }
       s.mode = payload.mode; s.session.setMode(payload.mode)  // track for persist/restore
       // Flipping to bypass = "stop asking, including the cards this turn already raised."
       if (payload.mode === 'bypassPermissions') allowPending(s)
@@ -3127,7 +3155,7 @@ channel
             // FL-M6 — restore the flow context (id/role/cwd) so an in-flight flow survives a
             // bridge restart: the conductor keeps its subagent-block + plan interception, and
             // lanes keep their worktree cwd + the ability to mark done.
-            openStructured({ id: rec.id, model: rec.model || undefined, provider: rec.provider || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt, lastUsage: rec.lastUsage,
+            openStructured({ id: rec.id, runtime: rec.runtime || 'claude', model: rec.model || undefined, provider: rec.runtime === 'codex' ? undefined : rec.provider || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt, lastUsage: rec.lastUsage,
               // Lazy-boot restored terminals that were IDLE + not part of a flow: their transcript
               // shows immediately; the query boots on first turn. Mid-turn + flow terminals boot now
               // (mid-turn needs auto-resume; flow needs its lane live).
@@ -3174,7 +3202,7 @@ channel
           // fresh random id, so openStructured's id-dedup couldn't catch it. The
           // saved-session restore above still runs unconditionally, so a bridge
           // restart resumes backgrounded sessions regardless of this guard.
-          else if (attachedCmd) openStructured({ id: randomUUID() })
+          else if (attachedCmd) openStructured({ id: randomUUID(), runtime: structuredRuntime(attachedCmd) })
           // Background-warm the lazily-restored idle terminals shortly after restore, so
           // they're ready before the user clicks them (no first-turn penalty). Delayed so the
           // eagerly-booted (mid-turn / auto-resumed) sessions get the machine to themselves first.

package/codex-event-mapper.mjs

@@ -0,0 +1,145 @@
+// codex-event-mapper.mjs — maps a Codex `codex exec --json` event stream into
+// the ThinkPool bridge's runtime-agnostic room-event contract (the SAME kinds
+// claude-session.mjs emits). Pure logic over a sequential event stream: the
+// driver (codex-session.mjs) feeds it parsed JSONL events, it calls onEvent
+// with normalized events. Spec: docs/specs/2026-07-12-codex-driver.md.
+//
+// WHY A SEPARATE RUNTIME, NOT A TRANSLATOR (see spec §Why): Codex is itself an
+// openai-native agent loop (tools + sandbox); we map its OUTPUT, we do not
+// re-implement the loop or translate APIs. This keeps each runtime on its
+// maker-tuned loop with no tool_use↔function-call loss.
+//
+// Codex item taxonomy (live capture: bridge/fixtures/codex-read-write.jsonl):
+//   agent_message            → assistant { blocks:[{type:'text',text}] }
+//   reasoning                → assistant { blocks:[{type:'thinking',text}] }
+//   command_execution start  → assistant { blocks:[{type:'tool_use',name:'Bash',input:{command}}] }
+//   command_execution done   → tool_result { toolUseId, content, isError, durationMs }
+//   file_change start        → assistant { blocks:[{type:'tool_use',name:'Write'|'Edit',input:{path}}] }
+//   file_change done         → tool_result
+//   turn.completed (usage)   → result { subtype:'success', usage, model }
+//   turn.failed / error      → error { recoverable:true } (+ result on turn.failed)
+//
+// G1 (spike): agent_message is burst-on-completion (no per-token deltas). Tool
+// activity DOES stream (item.started→item.completed), so an active turn still
+// shows live progress; only the final prose pops in. The driver adds a
+// "composing" indicator to cover the gap (see codex-session.mjs).
+//
+// Risk: this module emits tool_use blocks with names ('Bash'/'Write'/'Edit') so
+// the existing risk classifier (claude-session.classifyRisk) and room rendering
+// apply unchanged. Codex v1 is observe-only (no per-tool card) — classification
+// is for display accent + future gating, not blocking (spec §tradeoff).
+
+export class CodexEventMapper {
+  /**
+   * @param {{onEvent:(evt)=>void, model?:string|null, sessionId?:string|null}} opts
+   */
+  constructor({ onEvent, model = null, sessionId = null }) {
+    this._onEvent = onEvent
+    this._model = model || null
+    this._sessionId = sessionId || null
+    this._starts = new Map() // item.id → startMs (for durationMs)
+    this._systemSent = false
+  }
+
+  /** Emit a room-event; never let a consumer throw into the stream. */
+  _emit(evt) { try { this._onEvent?.(evt) } catch { /* noop */ } }
+
+  setModel(model) { this._model = model || null }
+
+  /** Process one parsed Codex JSONL event. */
+  push(ev) {
+    if (!ev || typeof ev !== 'object') return
+    switch (ev.type) {
+      case 'thread.started': {
+        this._sessionId = this._sessionId || ev.thread_id || null
+        if (!this._systemSent) {
+          this._systemSent = true
+          this._emit({ kind: 'system', sessionId: this._sessionId, model: this._model, commands: [] })
+        }
+        return
+      }
+      case 'turn.started':
+        return
+
+      case 'item.started': {
+        const it = ev.item
+        if (!it) return
+        this._starts.set(it.id, Date.now())
+        if (it.type === 'command_execution') {
+          this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: it.id, name: 'Bash', input: { command: it.command || '' } }], parentToolUseId: null })
+        } else if (it.type === 'file_change') {
+          const c = (it.changes && it.changes[0]) || {}
+          this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: it.id, name: c.kind === 'add' ? 'Write' : 'Edit', input: { path: c.path || '' } }], parentToolUseId: null })
+        } else if (it.type === 'web_search') {
+          this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: it.id, name: 'WebSearch', input: { query: it.query || '' } }], parentToolUseId: null })
+        }
+        // agent_message / reasoning have no item.started (burst on completion).
+        return
+      }
+
+      case 'item.completed': {
+        const it = ev.item
+        if (!it) return
+        const start = this._starts.get(it.id)
+        const durationMs = start != null ? Date.now() - start : undefined
+        this._starts.delete(it.id)
+
+        if (it.type === 'agent_message') {
+          this._emit({ kind: 'assistant', blocks: [{ type: 'text', text: it.text || '' }], parentToolUseId: null })
+        } else if (it.type === 'reasoning') {
+          this._emit({ kind: 'assistant', blocks: [{ type: 'thinking', text: it.text || '' }], parentToolUseId: null })
+        } else if (it.type === 'command_execution') {
+          const bad = it.exit_code != null ? it.exit_code !== 0 : false
+          this._emit({ kind: 'tool_result', toolUseId: it.id, content: [{ type: 'text', text: it.aggregated_output || '' }], isError: bad, durationMs, parentToolUseId: null })
+        } else if (it.type === 'file_change') {
+          const c = (it.changes && it.changes[0]) || {}
+          const verb = c.kind === 'add' ? 'wrote' : 'edited'
+          this._emit({ kind: 'tool_result', toolUseId: it.id, content: [{ type: 'text', text: `${verb} ${c.path || ''}` }], isError: false, durationMs, parentToolUseId: null })
+        } else if (it.type === 'web_search') {
+          this._emit({ kind: 'tool_result', toolUseId: it.id, content: [{ type: 'text', text: it.query || 'search completed' }], isError: false, durationMs, parentToolUseId: null })
+        }
+        // mcp_tool_call / plan_update remain additive future event shapes. Unknown
+        // items are ignored rather than risking a malformed transcript row.
+        return
+      }
+
+      case 'turn.completed': {
+        const u = ev.usage || {}
+        // Map Codex usage → Claude-shape usage (what event-id.mjs folds into cost).
+        // reasoning_output_tokens are billed as output → fold in (conservative).
+        const out = (u.output_tokens || 0) + (u.reasoning_output_tokens || 0)
+        this._emit({
+          kind: 'result',
+          subtype: 'success',
+          sessionId: this._sessionId,
+          model: this._model,
+          costUsd: null,
+          usage: {
+            input_tokens: u.input_tokens || 0,
+            cache_read_input_tokens: u.cached_input_tokens || 0,
+            cache_creation_input_tokens: 0,
+            output_tokens: out,
+          },
+          numTurns: 1,
+          durationMs: undefined,
+          denials: 0,
+          resultText: null,
+        })
+        return
+      }
+
+      case 'turn.failed': {
+        this._emit({ kind: 'error', message: ev.message || ev.error || 'codex turn failed', recoverable: true })
+        this._emit({ kind: 'result', subtype: 'error_during_execution', sessionId: this._sessionId, model: this._model, costUsd: null, usage: null, numTurns: 1, durationMs: undefined, denials: 0, resultText: null })
+        return
+      }
+
+      case 'error':
+        this._emit({ kind: 'error', message: ev.message || ev.error || 'codex error', recoverable: true })
+        return
+
+      default:
+        return
+    }
+  }
+}

package/codex-session.mjs

@@ -0,0 +1,228 @@
+// codex-session.mjs — a structured Codex CLI session for the ThinkPool bridge.
+// Sibling to claude-session.mjs: SAME interface (startCodexSession →
+// { sendTurn, abort, end, sessionId }) and SAME room-event contract, so the
+// bridge can spawn either runtime per lane (spec §"the seam"). Wraps
+// `codex exec --json` (OpenAI's openai-native agent loop) instead of the
+// Anthropic Agent SDK. Spec: docs/specs/2026-07-12-codex-driver.md.
+//
+// WHY NOT a translator: Codex IS the agent loop (tools + sandbox); we spawn it
+// and map its --json event stream (codex-event-mapper.mjs). No API translation,
+// no tool_use↔function-call loss. Auth = the HOST's `codex login` (ChatGPT,
+// flat sub) by default; BYOK via env CODEX_API_KEY works too (exec-only).
+//
+// v1 TRADEOFF (spec §tradeoff, G3): `codex exec` is non-interactive — fixed
+// --sandbox, NO per-tool human gate. The room OBSERVES each command/file-change
+// live (item.started→item.completed) but cannot approve/deny mid-run. Codex's
+// own sandbox governs safety. Default sandbox: workspace-write.
+//
+// ONE-SHOT-PER-TURN model: unlike Claude's long-lived query(), `codex exec` is
+// one prompt → run → exit. sendTurn spawns an exec; continuity across turns uses
+// the exact thread id captured for this lane. Turns are serialized (one exec at
+// a time per lane).
+//
+// GOTCHA (spike): `codex exec` blocks reading stdin when backgrounded
+// ("Reading additional input from stdin…"). Spawn with stdin set to /dev/null.
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline'
+import { CodexEventMapper } from './codex-event-mapper.mjs'
+
+const DEFAULT_SANDBOX = 'workspace-write'
+const SAFE_SANDBOXES = new Set(['read-only', 'workspace-write'])
+
+export function readCodexDefaultModel({ home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), fsImpl = fs } = {}) {
+  try {
+    const text = fsImpl.readFileSync(path.join(home, 'config.toml'), 'utf8')
+    // Only the top-level model controls the default runtime. Stop at the first
+    // table so a profile/provider's nested `model` cannot impersonate it.
+    const top = text.split(/^\s*\[/m, 1)[0]
+    const m = top.match(/^\s*model\s*=\s*["']([^"']+)["']\s*(?:#.*)?$/m)
+    return m?.[1]?.trim() || null
+  } catch { return null }
+}
+
+export function readCodexModels({ home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), fsImpl = fs } = {}) {
+  try {
+    const data = JSON.parse(fsImpl.readFileSync(path.join(home, 'models_cache.json'), 'utf8'))
+    return (Array.isArray(data?.models) ? data.models : [])
+      .filter((m) => m?.slug && m.visibility !== 'hide')
+      .sort((a, b) => (Number(a.priority) || 999) - (Number(b.priority) || 999))
+      .map((m) => ({ value: m.slug, displayName: m.display_name || m.slug, description: m.description || '' }))
+  } catch { return [] }
+}
+
+export function normalizeCodexSandbox(value) {
+  return SAFE_SANDBOXES.has(value) ? value : DEFAULT_SANDBOX
+}
+
+export function buildCodexPrompt({ text, rolePrompt, roomContext }) {
+  const context = typeof roomContext === 'function' ? roomContext() : roomContext
+  const additions = [rolePrompt, context].map((v) => String(v || '').trim()).filter(Boolean)
+  if (!additions.length) return String(text ?? '')
+  return `<thinkpool-context>\n${additions.join('\n\n')}\n</thinkpool-context>\n\n${String(text ?? '')}`
+}
+
+export function buildCodexExecArgs({ sessionId, model, sandbox, providerConfig, prompt }) {
+  const safeSandbox = normalizeCodexSandbox(sandbox)
+  const args = sessionId
+    // `codex exec resume` deliberately has no --sandbox option. The resumed
+    // rollout retains the sandbox selected on its fresh first turn. Passing the
+    // fresh-only flag here makes current Codex exit 2 before doing any work.
+    ? ['exec', 'resume', '--json', '--skip-git-repo-check']
+    : ['exec', '--json', '--sandbox', safeSandbox, '--skip-git-repo-check']
+  if (model) args.push('-m', model)
+  if (providerConfig) args.push('-c', providerConfig)
+  if (sessionId) args.push(sessionId)
+  args.push(String(prompt ?? ''))
+  return args
+}
+
+/**
+ * Start a structured Codex session. Mirrors startClaudeSession's contract.
+ * @param {object} o
+ * @param {string} o.cwd           work directory for the codex exec (a git repo)
+ * @param {string} [o.model]       model id (e.g. 'gpt-5.6-sol'); passed via -m
+ * @param {string} [o.resume]      captured Codex thread id to resume after bridge restart
+ * @param {object} [o.env]         env for the child (e.g. CODEX_API_KEY for BYOK)
+ * @param {string} [o.sandbox]     'read-only' | 'workspace-write' | 'danger-full-access' (default workspace-write)
+ * @param {(evt)=>void} o.onEvent  receives normalized room-events
+ * @param {string} [o.providerConfig] optional -c overrides / provider block (M2: from the provider registry)
+ * @returns {{ sendTurn(text), abort(), end(), readonly sessionId }}
+ */
+export function startCodexSession({ cwd, model, resume, env, sandbox = DEFAULT_SANDBOX, onEvent, providerConfig, rolePrompt, roomContext }) {
+  sandbox = normalizeCodexSandbox(sandbox)
+  const childEnv = { ...process.env, ...(env || {}) }
+  let sessionId = resume || null
+  let turnNo = resume ? 1 : 0
+  let child = null
+  let aborted = false
+  let ended = false
+  let turnActive = false
+  let activeModel = model || null
+  // serialize turns: one exec at a time
+  let chain = Promise.resolve()
+  const queue = []
+
+  const mapper = new CodexEventMapper({ onEvent, model: model || null })
+
+  function runExec(prompt) {
+    // First turn: fresh exec. Later turns: resume THIS lane's captured thread.
+    // `--last` is process-global and can cross-wire two concurrently-active Codex
+    // lanes, so it is never safe in a multi-lane bridge.
+    const args = buildCodexExecArgs({
+      sessionId: turnNo === 0 ? null : sessionId,
+      model: activeModel,
+      sandbox,
+      providerConfig,
+      prompt,
+    })
+
+    return new Promise((resolve) => {
+      // stdin: /dev/null (spike gotcha — codex blocks on stdin otherwise)
+      let stdinFd
+      try { stdinFd = fs.openSync('/dev/null', 'r') } catch { /* will inherit; best effort */ }
+      const opts = { cwd, env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] }
+      if (stdinFd != null) opts.stdio = [stdinFd, 'pipe', 'pipe']
+
+      aborted = false
+      turnActive = true
+      child = spawn('codex', args, opts)
+      if (stdinFd != null) { try { fs.closeSync(stdinFd) } catch { /* child owns its duplicated fd */ } }
+
+      const rl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity })
+      rl.on('line', (line) => {
+        if (!line.trim()) return
+        let ev
+        try { ev = JSON.parse(line) } catch { return /* non-JSON progress line */
+        }
+        if (ev.type === 'thread.started' && ev.thread_id) sessionId = sessionId || ev.thread_id
+        if (ev.type === 'turn.completed' || ev.type === 'turn.failed') sawTerminalResult = true
+        mapper.push(ev)
+      })
+      // stderr is codex's human progress channel; surface tail on failure only.
+      let stderrTail = ''
+      let sawTerminalResult = false
+      let settled = false
+      child.stderr.on('data', (d) => { stderrTail += d.toString(); if (stderrTail.length > 800) stderrTail = stderrTail.slice(-800) })
+
+      const finish = (code) => {
+        if (settled) return
+        settled = true
+        child = null
+        turnActive = false
+        if (aborted && !sawTerminalResult) {
+          try { onEvent?.({ kind: 'result', subtype: 'aborted', sessionId, model: activeModel, costUsd: null, usage: null, numTurns: 1, durationMs: undefined, denials: 0, resultText: null }) } catch { /* noop */ }
+        } else if (!aborted && !sawTerminalResult && code !== 0 && code != null) {
+          try { onEvent?.({ kind: 'error', message: `codex exec exited ${code}${stderrTail ? ': ' + stderrTail.trim().slice(-300) : ''}`, recoverable: true }) } catch { /* noop */ }
+        }
+        resolve()
+      }
+      child.on('error', (e) => {
+        if (settled) return
+        settled = true
+        try { onEvent?.({ kind: 'error', message: `codex failed to start: ${e.message}`, recoverable: true }) } catch { /* noop */ }
+        child = null
+        turnActive = false
+        resolve()
+      })
+      child.on('close', finish)
+    })
+  }
+
+  function pump() {
+    if (ended) return
+    const next = queue.shift()
+    if (!next) return
+    chain = chain.then(async () => {
+      // runExec sees turnNo===0 on the FIRST turn (fresh exec); increment only
+      // after, so subsequent turns resume this lane's captured thread id.
+      // Claude receives these through the Agent SDK's system-reminder path.
+      // Codex is one-shot per turn, so give it the same lane identity and live
+      // room awareness in a compact envelope before the person's text.
+      await runExec(buildCodexPrompt({ text: next, rolePrompt, roomContext }))
+      turnNo++
+      pump()
+    })
+  }
+
+  return {
+    get sessionId() { return sessionId },
+    get turnActive() { return turnActive },
+    get started() { return turnNo > 0 || turnActive },
+    sendTurn(text) {
+      if (ended) return false
+      queue.push(text)
+      // start the pump if idle
+      if (queue.length === 1) pump()
+      return true
+    },
+    abort() {
+      aborted = true
+      queue.length = 0
+      if (child) { try { child.kill('SIGTERM') } catch { /* noop */ } ; setTimeout(() => { try { child?.kill('SIGKILL') } catch { /* noop */ } }, 1500) }
+    },
+    end() {
+      ended = true
+      queue.length = 0
+      if (child) { try { child.kill() } catch { /* noop */ } }
+    },
+    setModel(nextModel) {
+      if (!nextModel || turnActive) return false
+      activeModel = String(nextModel)
+      mapper.setModel(activeModel)
+      return true
+    },
+    // Codex v1 has a fixed sandbox for the lifetime of the lane. The bridge may
+    // still call setMode from shared chrome; report unsupported rather than
+    // pretending the Claude permission mode changed Codex's sandbox.
+    setMode() { return false },
+    clearContext() {
+      if (turnActive) return false
+      sessionId = null
+      turnNo = 0
+      return true
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.190",
+  "version": "0.7.192",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -13,6 +13,8 @@
     "byok-detect.mjs",
     "context-windows.mjs",
     "claude-session.mjs",
+    "codex-session.mjs",
+    "codex-event-mapper.mjs",
     "turn-stall.mjs",
     "update-gate.mjs",
     "agent-notify.mjs",