thinkpool-pair 0.7.212 → 0.7.214

package/README.md

@@ -51,6 +51,23 @@ Structured Claude sessions persist their scrollback + session id to
 `~/.thinkpool-pair/<ROOM>/` and **resume on restart** (live context if recent),
 so none of the above loses your place.
 
+### Codex App Server driver
+
+Structured Codex lanes use the long-lived App Server transport (streaming prose,
+mid-turn steering, shared approval and question cards, and native image inputs)
+when the installed Codex CLI is in the bridge's tested protocol range. To force
+the stable `codex exec --json` fallback, set the kill switch before starting the
+bridge:
+
+```bash
+export TP_CODEX_APP_SERVER=0
+```
+
+The bridge performs the initialize handshake before creating a thread and falls
+back to `codex exec` when App Server is disabled, outside the tested version
+range, or cannot initialize before a turn. It never retries a prompt via the
+fallback after `turn/start` has been accepted, preventing duplicate work.
+
 Your first agent runs **attached** — use it exactly like your normal terminal,
 every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
 **headless** terminals here (same directory, same env), driven entirely from

package/bridge.mjs

@@ -51,6 +51,7 @@ import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
 import { startCodexSession, readCodexDefaultModel, readCodexModels, codexConfigForMode, defaultModeForRuntime } from './codex-session.mjs'
+import { canonicalRoomFilePath, waitForNativeImages } from './codex-images.mjs'
 import { createManagedLaneWorktree, removeManagedLaneWorktree } from './lane-worktree.mjs'
 import { commandOnPath } from './agent-detect.mjs'
 
@@ -1044,7 +1045,7 @@ const announce = () => {
       // laneStatusOf: authoritative busy/idle + last-action timestamp/age +
       // STUCK/BLOCKED alert. The bridge owns the turn and permission state, so
       // every roster consumer reads one status instead of reconstructing it.
-      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, ...laneStatusOf(s), hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, 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' } : {}),
+      ...[...sessions.entries()].map(([id, s]) => ({ id, cmd: s.cmd, kind: 'structured', runtime: s.runtime || 'claude', alive: true, ...laneStatusOf(s), hasTranscript: s.log.length > 0, commands: s.commands, mode: s.mode || undefined, effort: s.effort || undefined, name: termNames[id] || undefined, model: s.model || undefined, ...(s.runtime === 'codex' ? { approvalPolicy: codexConfigForMode(s.mode).approvalPolicy, models: s.models || [], canSteer: s.session?.canSteer ?? false } : {}), ...(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 +
@@ -2243,6 +2244,11 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
         const busyChanged = busyNow !== entry._busyAnn
         if (busyChanged) { if (busyNow) entry._turnStart = Date.now(); entry._busyAnn = busyNow }
         if (busyChanged || stalledChanged) announce() }
+      // App Server steering is opt-in and can fall back to exec at runtime. Keep
+      // the roster capability authoritative so the browser never immediate-sends
+      // into an exec-only turn and loses its shared queue.
+      { const canSteerNow = entry.runtime === 'codex' && (entry.session?.canSteer ?? false)
+        if (canSteerNow !== entry._canSteerAnn) { entry._canSteerAnn = canSteerNow; announce() } }
       // Capture this session's current MODEL (resolved full id, with version — from
       // system/result `model` or usage `ctx.model`) and the SDK's supported-model
       // LIST (from the `models` event) so the announce carries them to EVERY device.
@@ -2346,7 +2352,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       // card) and is intentionally NOT chrome, so it persists + replays.
       // 'suggestion' is Claude Code's predicted-next-prompt ghost text — ephemeral
       // composer UI, broadcast to both clients but never logged/persisted/replayed.
-      const chrome = evt.kind === 'mode' || evt.kind === 'usage' || evt.kind === 'clear' || evt.kind === 'compact' || evt.kind === 'stalled' || evt.kind === 'suggestion'
+      const chrome = evt.kind === 'mode' || evt.kind === 'usage' || evt.kind === 'clear' || evt.kind === 'compact' || evt.kind === 'stalled' || evt.kind === 'suggestion' || evt.kind === 'assistant_stream'
       // The compact turn settled with `entry.compacting` STILL TRUE — which, because the
       // `compaction` branch above clears the flag the moment the milestone lands, means
       // exactly one thing: NO compaction happened. Three ways to get here, all of which
@@ -2387,7 +2393,12 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       if (evt.kind === 'result' || evt.kind === 'error') {
         const startedAt = entry._turnStart
         entry._turnStart = null
-        entry.permNotifier?.clearAll()
+        // A canceled/failed App Server request can settle the turn without the
+        // browser ever answering its permission card. Resolve those promises
+        // fail-closed and explicitly retract the stale cards on both clients.
+        const stalePermissionIds = [...entry.pending.keys()]
+        drainPending(entry)
+        for (const pendingId of stalePermissionIds) bcast('code-perm', { term: id, id: pendingId, decision: 'deny', name: 'agent' })
         if (shouldNotifyTurnDone({ entry, subtype: evt.subtype, startedAt, now: Date.now(), minTurnMs: MIN_TURN_MS })) {
           persistAgentEvent({
             kind: 'turn-done',
@@ -2429,8 +2440,9 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       }
       // Keep the broadcast payload with the resolver so a reconnect can re-send it
       // (replay-request handler) — pending cards never enter the replayed event log.
-      const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
-      entry.pending.set(req.id, { resolve, payload })
+      const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions, asker: req.asker, answerFormat: req.answerFormat, autoResolutionMs: req.autoResolutionMs }
+      const pending = { resolve, payload, timer: null }
+      entry.pending.set(req.id, pending)
       announce()
       bcast('code-perm-req', payload)
       // Slice 3 — arm the grace timer. Fires a "needs you" push only if the card is
@@ -2443,8 +2455,20 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
       process.stderr.write(req.risk === 'plan'
         ? `\n  ${A.mag}◆ plan ready — approve in the room.${A.rst}\n`
         : req.risk === 'ask'
-          ? `\n  ${A.cyan}● Claude is asking: ${(req.questions || []).map((q) => q.question).join(' / ').slice(0, 100)} — answer in the room.${A.rst}\n`
+          ? `\n  ${A.cyan}● ${req.asker || (runtime === 'codex' ? 'Codex' : 'Claude')} is asking: ${(req.questions || []).map((q) => q.question).join(' / ').slice(0, 100)} — answer in the room.${A.rst}\n`
           : `\n  ${A.yel}● permission: ${req.toolName}${argStr(req.input)} — approve in the room.${A.rst}\n`)
+      const autoResolutionMs = Number(req.autoResolutionMs)
+      if (req.risk === 'ask' && Number.isFinite(autoResolutionMs) && autoResolutionMs > 0) {
+        pending.timer = setTimeout(() => {
+          if (entry.pending.get(req.id) !== pending) return
+          entry.pending.delete(req.id)
+          entry.permNotifier?.resolve(req.id)
+          bcast('code-perm', { term: id, id: req.id, decision: 'timeout', name: req.asker || 'agent' })
+          try { resolve(pendingResolution(pending, { decision: 'timeout', answers: {} })) } catch { /* noop */ }
+          announce()
+        }, autoResolutionMs)
+        pending.timer.unref?.()
+      }
     }),
   })
   // A restored Codex lane may have a stale pre-0.7.206 meter persisted from the
@@ -2479,9 +2503,19 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
 // leaves the SDK's PreToolUse hook (claude-session.mjs) awaiting our promise
 // forever — the structured turn freezes mid-flight. 'deny' is the fail-safe the
 // hook already degrades to, so draining to deny is always safe.
+function pendingResolution(pending, payload = {}) {
+  const decision = payload.decision || 'deny'
+  return pending?.payload?.answerFormat === 'codex'
+    ? { decision, answers: payload.answers || {} }
+    : decision
+}
+
 function drainPending(s) {
   if (!s?.pending) return
-  for (const [, p] of s.pending) { try { p.resolve('deny') } catch { /* noop */ } }
+  for (const [, p] of s.pending) {
+    if (p?.timer) clearTimeout(p.timer)
+    try { p.resolve(pendingResolution(p, { decision: 'deny' })) } catch { /* noop */ }
+  }
   s.pending.clear()
   // Every card just died → retract any "needs you" banner they raised (Slice 3).
   s.permNotifier?.clearAll()
@@ -2502,6 +2536,7 @@ function allowPending(s) {
     // "run tools without asking", not "auto-approve my plan / answer my question" — leave
     // those for the human.
     if (p?.payload?.risk === 'plan' || p?.payload?.risk === 'ask') continue
+    if (p?.timer) clearTimeout(p.timer)
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
     s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
@@ -2521,6 +2556,7 @@ function acceptEditsPending(s) {
     const risk = p?.payload?.risk
     if (risk === 'plan' || risk === 'ask' || risk === 'high') continue
     if (!ACCEPT_EDIT_TOOLS.has(tn)) continue
+    if (p?.timer) clearTimeout(p.timer)
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
     s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
@@ -2868,12 +2904,13 @@ channel
     if (payload.host && payload.host !== name) return
     ;(async () => {
       try {
+        const fp = canonicalRoomFilePath(payload, { updir: UPDIR })
+        if (!fp) throw new Error('invalid attachment metadata')
         const r = await fetch(payload.url)
         if (!r.ok) throw new Error(`HTTP ${r.status}`)
         const buf = Buffer.from(await r.arrayBuffer())
         if (buf.length > FILE_MAX_BYTES) throw new Error('file too large')
         fs.mkdirSync(UPDIR, { recursive: true })
-        const fp = path.join(UPDIR, `${String(payload.id).slice(0, 8)}-${safeName(payload.name)}`)
         fs.writeFileSync(fp, buf)
         process.stderr.write(`\n  ◆ file from the room: ${fp}\n`)
         bcast('file-done', { id: payload.id, path: fp.split(path.sep).join('/'), host: name })
@@ -3033,7 +3070,14 @@ channel
     // no-ops. The visible `you` echo is unchanged; the recap is context for the agent only.
     let sendText = text
     if (s.pendingRecap) { sendText = `${s.pendingRecap}\n\n--- the person's next message ---\n${text}`; s.pendingRecap = null; s.flush?.() }
-    s.session.sendTurn(sendText)
+    // The browser's `hostPath` is display metadata, not host authority. Rebuild
+    // image paths from the bridge-owned UPDIR + deterministic attachment fields,
+    // then cover the separate file-put/code-turn download race with a bounded
+    // readiness wait. A late image remains available through its quoted text path.
+    const nativeImages = s.runtime === 'codex'
+      ? await waitForNativeImages(payload.files, { updir: UPDIR })
+      : []
+    s.session.sendTurn(sendText, nativeImages.length ? { images: nativeImages } : undefined)
     echoYou()
     // Pool-order fix (2026-07-02): emit the "dispatched to agent" marker HERE, right after
     // the @pool you-line, so it inherits the NEXT seq (seqable('pool') is true) and orders
@@ -3056,7 +3100,13 @@ channel
     // use run/accept/keep (claude-session interprets). Default deny on missing.
     // Answered from a device → retract the "needs you" banner on every OTHER device
     // (permNotifier.resolve is a no-op unless its grace timer already fired).
-    if (p) { s.pending.delete(payload.id); s.permNotifier?.resolve(payload.id); p.resolve(payload.decision || 'deny'); announce() }
+    if (p) {
+      if (p.timer) clearTimeout(p.timer)
+      s.pending.delete(payload.id)
+      s.permNotifier?.resolve(payload.id)
+      p.resolve(pendingResolution(p, payload))
+      announce()
+    }
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)

package/codex-app-server.mjs

@@ -0,0 +1,259 @@
+// codex-app-server.mjs — defensive JSONL/JSON-RPC transport for Codex App Server.
+//
+// App Server is still experimental, so the bridge enables it only for the exact
+// Codex version range whose protocol we have exercised. TP_CODEX_APP_SERVER=0 is
+// the kill switch; `codex exec --json` remains the safe fallback.
+import { execFileSync, spawn } from 'node:child_process'
+import readline from 'node:readline'
+
+export const CODEX_APP_SERVER_ENV = 'TP_CODEX_APP_SERVER'
+export const MIN_CODEX_APP_SERVER_VERSION = Object.freeze([0, 144, 1])
+export const MAX_CODEX_APP_SERVER_VERSION = Object.freeze([0, 145, 0])
+
+const parseVersion = (raw) => {
+  const m = String(raw || '').match(/(?:codex-cli\s+)?(\d+)\.(\d+)\.(\d+)/i)
+  return m ? m.slice(1, 4).map(Number) : null
+}
+
+const atLeast = (actual, minimum) => {
+  for (let i = 0; i < 3; i++) {
+    if (actual[i] > minimum[i]) return true
+    if (actual[i] < minimum[i]) return false
+  }
+  return true
+}
+
+const before = (actual, maximum) => !atLeast(actual, maximum)
+
+const transportError = (message, delivery = 'unknown') => {
+  const error = message instanceof Error ? message : new Error(String(message || 'Codex App Server transport failed'))
+  error.delivery = delivery
+  return error
+}
+
+export function codexAppServerGate({ env = process.env, execFile = execFileSync } = {}) {
+  const setting = String(env?.[CODEX_APP_SERVER_ENV] || '').trim().toLowerCase()
+  if (['0', 'false', 'off'].includes(setting)) {
+    return { enabled: false, reason: `${CODEX_APP_SERVER_ENV} disables App Server`, version: null }
+  }
+  if (setting && !['1', 'true', 'on'].includes(setting)) {
+    return { enabled: false, reason: `${CODEX_APP_SERVER_ENV} has an invalid value`, version: null }
+  }
+  try {
+    const raw = execFile('codex', ['--version'], { encoding: 'utf8', env })
+    const parsed = parseVersion(raw)
+    if (!parsed) return { enabled: false, reason: `unrecognized Codex version: ${String(raw).trim()}`, version: null }
+    const version = parsed.join('.')
+    if (!atLeast(parsed, MIN_CODEX_APP_SERVER_VERSION)) {
+      return { enabled: false, reason: `Codex ${version} is older than ${MIN_CODEX_APP_SERVER_VERSION.join('.')}`, version }
+    }
+    if (!before(parsed, MAX_CODEX_APP_SERVER_VERSION)) {
+      return { enabled: false, reason: `Codex ${version} is newer than the tested App Server protocol (<${MAX_CODEX_APP_SERVER_VERSION.join('.')})`, version }
+    }
+    return { enabled: true, reason: null, version }
+  } catch (error) {
+    return { enabled: false, reason: `could not read Codex version: ${error?.message || error}`, version: null }
+  }
+}
+
+export function buildCodexAppServerArgs({ providerConfig, mcpUrl, writableDirs = [] } = {}) {
+  const args = ['app-server', '--stdio']
+  if (providerConfig) args.push('-c', providerConfig)
+  if (mcpUrl) args.push('-c', `mcp_servers.thinkpool.url=${JSON.stringify(mcpUrl)}`)
+  if (writableDirs.length) args.push('-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(writableDirs)}`)
+  return args
+}
+
+const rpcError = (message, code = -32000) => ({ code, message: String(message || 'App Server request failed') })
+const turnInput = (text, images = []) => [
+  { type: 'text', text: String(text ?? '') },
+  ...images.filter(Boolean).map((imagePath) => ({ type: 'localImage', path: String(imagePath) })),
+]
+
+/**
+ * Minimal App Server client. It deliberately accepts unknown notifications and
+ * fields: protocol additions must not take down an otherwise usable lane.
+ */
+export class CodexAppServerClient {
+  constructor({ cwd, env, args = ['app-server', '--stdio'], spawnImpl = spawn, onNotification, onServerRequest, onClose, initializeTimeoutMs = 3000, threadTimeoutMs = 5000, turnStartTimeoutMs = 5000, controlTimeoutMs = 5000 } = {}) {
+    this.cwd = cwd
+    this.env = env
+    this.args = args
+    this.spawnImpl = spawnImpl
+    this.onNotification = onNotification
+    this.onServerRequest = onServerRequest
+    this.onClose = onClose
+    this.initializeTimeoutMs = initializeTimeoutMs
+    this.threadTimeoutMs = threadTimeoutMs
+    this.turnStartTimeoutMs = turnStartTimeoutMs
+    this.controlTimeoutMs = controlTimeoutMs
+    this.child = null
+    this.nextId = 1
+    this.pending = new Map()
+    this.turnWaiters = new Map()
+    this.completedTurns = new Map()
+    this.closedError = null
+    this.stderrTail = ''
+  }
+
+  get alive() { return !!this.child && !this.closedError }
+
+  async start() {
+    if (this.child) return
+    const child = this.spawnImpl('codex', this.args, { cwd: this.cwd, env: this.env, stdio: ['pipe', 'pipe', 'pipe'] })
+    this.child = child
+    const rl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity })
+    rl.on('line', (line) => this._onLine(line))
+    child.stderr?.on?.('data', (chunk) => {
+      this.stderrTail += String(chunk)
+      if (this.stderrTail.length > 1200) this.stderrTail = this.stderrTail.slice(-1200)
+    })
+    child.stdin?.on?.('error', (error) => this._close(error))
+    child.on('error', (error) => this._close(error))
+    child.on('close', (code) => this._close(new Error(`codex app-server exited ${code ?? 'unknown'}${this.stderrTail ? `: ${this.stderrTail.trim().slice(-300)}` : ''}`)))
+
+    await this.request('initialize', {
+      clientInfo: { name: 'thinkpool-pair', title: 'ThinkPool Code', version: '1' },
+      capabilities: { experimentalApi: true },
+    }, this.initializeTimeoutMs)
+    this.notify('initialized')
+  }
+
+  _write(message) {
+    if (!this.child?.stdin || this.closedError) throw this.closedError || new Error('codex app-server is not running')
+    this.child.stdin.write(`${JSON.stringify(message)}\n`)
+  }
+
+  request(method, params = {}, timeoutMs = 0) {
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      let timer = null
+      if (timeoutMs > 0) timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(transportError(`${method} timed out after ${timeoutMs}ms`, 'unknown'))
+      }, timeoutMs)
+      this.pending.set(id, { resolve, reject, timer, method })
+      try { this._write({ id, method, params }) }
+      catch (error) {
+        this.pending.delete(id)
+        if (timer) clearTimeout(timer)
+        reject(transportError(error, 'not_sent'))
+      }
+    })
+  }
+
+  notify(method, params) {
+    this._write(params === undefined ? { method } : { method, params })
+  }
+
+  respond(id, result) { this._write({ id, result }) }
+  respondError(id, error) { this._write({ id, error: rpcError(error?.message || error) }) }
+
+  _onLine(line) {
+    if (!String(line).trim()) return
+    let message
+    try { message = JSON.parse(line) } catch { return }
+    if (message.id != null && ('result' in message || 'error' in message) && !message.method) {
+      const pending = this.pending.get(message.id)
+      if (!pending) return
+      this.pending.delete(message.id)
+      if (pending.timer) clearTimeout(pending.timer)
+      if (message.error) {
+        const error = transportError(message.error.message || `${pending.method} failed`, 'rejected')
+        error.code = message.error.code
+        error.data = message.error.data
+        pending.reject(error)
+      }
+      else pending.resolve(message.result)
+      return
+    }
+    if (message.id != null && message.method) {
+      Promise.resolve().then(() => {
+        if (!this.onServerRequest) throw new Error(`Unsupported Codex App Server request: ${message.method}`)
+        return this.onServerRequest(message.method, message.params || {}, message.id)
+      })
+        .then((result) => { try { this.respond(message.id, result ?? {}) } catch { /* peer closed */ } })
+        .catch((error) => { try { this.respondError(message.id, error) } catch { /* peer closed */ } })
+      return
+    }
+    if (!message.method) return
+    if (message.method === 'turn/completed') {
+      const turn = message.params?.turn
+      const turnId = turn?.id
+      if (turnId) {
+        const waiter = this.turnWaiters.get(turnId)
+        if (waiter) { this.turnWaiters.delete(turnId); waiter.resolve(message.params) }
+        else {
+          this.completedTurns.set(turnId, message.params)
+          while (this.completedTurns.size > 32) this.completedTurns.delete(this.completedTurns.keys().next().value)
+        }
+      }
+    }
+    try { this.onNotification?.(message.method, message.params || {}) } catch { /* consumer isolation */ }
+  }
+
+  _close(error) {
+    if (this.closedError) return
+    this.closedError = transportError(error instanceof Error ? error : String(error || 'codex app-server closed'), 'unknown')
+    this.child = null
+    for (const { reject, timer } of this.pending.values()) { if (timer) clearTimeout(timer); reject(this.closedError) }
+    this.pending.clear()
+    for (const { reject } of this.turnWaiters.values()) reject(this.closedError)
+    this.turnWaiters.clear()
+    this.completedTurns.clear()
+    try { this.onClose?.(this.closedError) } catch { /* consumer isolation */ }
+  }
+
+  async startThread({ threadId, cwd, model, sandbox, approvalPolicy, config } = {}) {
+    const params = { cwd, model, sandbox, approvalPolicy, ...(config ? { config } : {}) }
+    const result = threadId
+      ? await this.request('thread/resume', { ...params, threadId }, this.threadTimeoutMs)
+      : await this.request('thread/start', params, this.threadTimeoutMs)
+    const id = result?.thread?.id || result?.threadId || threadId
+    if (!id) throw new Error('Codex App Server did not return a thread id')
+    return id
+  }
+
+  async startTurn({ threadId, input, images, model, effort, approvalPolicy } = {}) {
+    const result = await this.request('turn/start', {
+      threadId,
+      input: turnInput(input, images),
+      ...(model ? { model } : {}),
+      ...(effort ? { effort } : {}),
+      ...(approvalPolicy ? { approvalPolicy } : {}),
+    }, this.turnStartTimeoutMs)
+    const turnId = result?.turn?.id || result?.turnId
+    if (!turnId) throw new Error('Codex App Server did not return a turn id')
+    return turnId
+  }
+
+  waitForTurn(turnId) {
+    if (this.completedTurns.has(turnId)) {
+      const result = this.completedTurns.get(turnId)
+      this.completedTurns.delete(turnId)
+      return Promise.resolve(result)
+    }
+    if (this.turnWaiters.has(turnId)) return Promise.reject(new Error(`Already waiting for Codex turn ${turnId}`))
+    return new Promise((resolve, reject) => this.turnWaiters.set(turnId, { resolve, reject }))
+  }
+
+  async steer({ threadId, turnId, input, images } = {}) {
+    return this.request('turn/steer', {
+      threadId,
+      expectedTurnId: turnId,
+      input: turnInput(input, images),
+    }, this.controlTimeoutMs)
+  }
+
+  interrupt({ threadId, turnId } = {}) {
+    return this.request('turn/interrupt', { threadId, turnId }, this.controlTimeoutMs)
+  }
+
+  end() {
+    const child = this.child
+    this._close(new Error('codex app-server ended'))
+    if (child) { try { child.kill('SIGTERM') } catch { /* noop */ } }
+  }
+}
+
+export function createCodexAppServer(options) { return new CodexAppServerClient(options) }

package/codex-event-mapper.mjs

@@ -19,15 +19,15 @@
 //   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).
+// G1 (stable exec path): agent_message is burst-on-completion (no per-token
+// deltas). Tool activity DOES stream (item.started→item.completed). The opt-in
+// App Server adapter emits item/agentMessage/delta directly and suppresses the
+// completed-message duplicate before events reach this mapper.
 //
 // 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).
+// apply unchanged. The stable exec path is observe-only; the opt-in App Server
+// path routes command/file approval requests through the shared room cards.
 import fs from 'node:fs'
 
 const safeMcpPart = (value) => String(value || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_')
@@ -66,7 +66,10 @@ export class CodexEventMapper {
     if (!ev || typeof ev !== 'object') return
     switch (ev.type) {
       case 'thread.started': {
-        this._sessionId = this._sessionId || ev.thread_id || null
+        // /clear and permission-mode changes intentionally create a new native
+        // thread inside the same visible lane. Attribute subsequent usage and
+        // results to that new thread, never the previous one.
+        this._sessionId = ev.thread_id || this._sessionId || null
         if (!this._systemSent) {
           this._systemSent = true
           this._emit({ kind: 'system', sessionId: this._sessionId, model: this._model, commands: [] })

package/codex-images.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const IMAGE_MEDIA_TYPE = /^image\/[a-z0-9.+-]+$/i
+const SAFE_ID_PREFIX = /^[a-zA-Z0-9_-]{1,8}$/
+
+export const safeRoomFileName = (name) => String(name || 'file').replace(/[^a-zA-Z0-9._-]/g, '_').slice(-80)
+
+/**
+ * Rebuild the deterministic room-upload path from bridge-owned facts.
+ * `hostPath` is intentionally ignored: it is display metadata supplied by a
+ * browser and must never grant Codex access to an arbitrary host file.
+ */
+export function canonicalRoomFilePath(file, { updir } = {}) {
+  if (!file || !updir) return null
+  const idPrefix = String(file.id || '').slice(0, 8)
+  if (!SAFE_ID_PREFIX.test(idPrefix)) return null
+  const root = path.resolve(String(updir))
+  const candidate = path.resolve(root, `${idPrefix}-${safeRoomFileName(file.name)}`)
+  return candidate.startsWith(root + path.sep) ? candidate : null
+}
+
+export function nativeImageCandidates(files, { updir } = {}) {
+  if (!Array.isArray(files)) return []
+  const seen = new Set()
+  const candidates = []
+  for (const file of files) {
+    if (!IMAGE_MEDIA_TYPE.test(String(file?.mediaType || ''))) continue
+    const candidate = canonicalRoomFilePath(file, { updir })
+    if (!candidate || seen.has(candidate)) continue
+    seen.add(candidate)
+    candidates.push(candidate)
+  }
+  return candidates
+}
+
+const fileReady = async (filePath) => {
+  try { return (await fs.promises.stat(filePath)).isFile() }
+  catch { return false }
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * `file-put` and `code-turn` are separate realtime broadcasts, so the turn can
+ * arrive while the signed download is still in flight. Wait briefly for only
+ * canonical image paths; timed-out images stay in the text prompt as ordinary
+ * quoted paths instead of failing or delaying the turn indefinitely.
+ */
+export async function waitForNativeImages(files, {
+  updir,
+  timeoutMs = 2000,
+  pollMs = 40,
+  isReady = fileReady,
+  sleep = delay,
+  now = Date.now,
+} = {}) {
+  const candidates = nativeImageCandidates(files, { updir })
+  if (!candidates.length) return []
+  const ready = new Set()
+  const deadline = now() + Math.max(0, timeoutMs)
+  while (true) {
+    const checks = await Promise.all(candidates.map(async (candidate) => [candidate, await isReady(candidate)]))
+    for (const [candidate, exists] of checks) if (exists) ready.add(candidate)
+    if (ready.size === candidates.length || now() >= deadline) break
+    await sleep(Math.min(Math.max(1, pollMs), Math.max(1, deadline - now())))
+  }
+  return candidates.filter((candidate) => ready.has(candidate))
+}

package/codex-session.mjs

@@ -1,9 +1,9 @@
 // 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.
+// bridge can spawn either runtime per lane (spec §"the seam"). Uses
+// `codex exec --json` (OpenAI's openai-native agent loop) by default, with a
+// version-gated App Server path for streaming + interactive control.
 //
 // 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,
@@ -15,10 +15,10 @@
 // Codex thread so the new sandbox actually takes effect; the visible transcript
 // remains in ThinkPool.
 //
-// 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).
+// DEFAULT ONE-SHOT-PER-TURN model: unlike Claude's long-lived query(), `codex
+// exec` is one prompt → run → exit. Continuity uses the exact thread id captured
+// for this lane. Compatible CLIs use one long-lived process by default;
+// TP_CODEX_APP_SERVER=0 or initialization failure falls back to this path.
 //
 // GOTCHA (spike): `codex exec` blocks reading stdin when backgrounded
 // ("Reading additional input from stdin…"). Spawn with stdin set to /dev/null.
@@ -27,6 +27,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import readline from 'node:readline'
+import { buildCodexAppServerArgs, codexAppServerGate, createCodexAppServer } from './codex-app-server.mjs'
 import { CodexEventMapper } from './codex-event-mapper.mjs'
 import { startCodexMcpHttp } from './codex-mcp-http.mjs'
 import { CODEX_THINKPOOL_FIRST_TURN_PREAMBLE } from './thinkpool-room-prompt.mjs'
@@ -181,7 +182,7 @@ export function buildCodexPrompt({ text, rolePrompt, roomContext, firstTurn = fa
   return `<thinkpool-context>\n${additions.join('\n\n')}\n</thinkpool-context>\n\n${String(text ?? '')}`
 }
 
-export function buildCodexExecArgs({ sessionId, model, effort, sandbox, approvalPolicy = 'untrusted', providerConfig, mcpUrl, writableDirs = [], prompt }) {
+export function buildCodexExecArgs({ sessionId, model, effort, sandbox, approvalPolicy = 'untrusted', providerConfig, mcpUrl, writableDirs = [], images = [], prompt }) {
   const safeSandbox = normalizeCodexSandbox(sandbox)
   const args = sessionId
     // `codex exec resume` has no --sandbox option and does NOT retain the fresh
@@ -206,11 +207,119 @@ export function buildCodexExecArgs({ sessionId, model, effort, sandbox, approval
   if (!sessionId) for (const dir of writableDirs) args.push('--add-dir', dir)
   // Per-lane override only: never mutate the person's global Codex config.
   if (mcpUrl) args.push('-c', `mcp_servers.thinkpool.url=${JSON.stringify(mcpUrl)}`)
+  // Both fresh `exec` and `exec resume` accept repeatable --image flags. Only
+  // bridge-derived absolute paths reach this layer; relative values are ignored
+  // so a future caller cannot silently change the child's path interpretation.
+  for (const imagePath of images) if (path.isAbsolute(String(imagePath || ''))) args.push('--image', String(imagePath))
   if (sessionId) args.push(sessionId)
   args.push(String(prompt ?? ''))
   return args
 }
 
+const CODEX_DESTRUCTIVE = /\brm\s+\S|\brmdir\s+\S|\bgit\s+(push\s+(-f|--force)|reset\s+--hard|clean\s+-[a-z]*f)|\bdrop\s+(table|database)\b|\b(mkfs|dd)\b|\bsudo\b|>\s*\/dev\/|\bchmod\s+-R|\bchown\s+-R|\bkillall\b|\btruncate\b/i
+
+export function codexApprovalCard(method, params = {}, item = null) {
+  const id = String(params.approvalId || params.itemId || `${params.turnId || 'turn'}:${method}`)
+  if (method === 'item/tool/requestUserInput') {
+    const questions = Array.isArray(params.questions) ? params.questions : []
+    return {
+      id,
+      toolName: 'AskUserQuestion',
+      input: { questions },
+      risk: 'ask',
+      questions,
+      asker: 'Codex',
+      answerFormat: 'codex',
+      ...(Number.isFinite(params.autoResolutionMs) && params.autoResolutionMs > 0
+        ? { autoResolutionMs: params.autoResolutionMs }
+        : {}),
+    }
+  }
+  if (method === 'item/commandExecution/requestApproval') {
+    const command = params.command || item?.command || ''
+    return {
+      id,
+      toolName: 'Bash',
+      input: { command, cwd: params.cwd || item?.cwd || '', ...(params.reason ? { reason: params.reason } : {}) },
+      risk: CODEX_DESTRUCTIVE.test(command) ? 'high' : 'medium',
+    }
+  }
+  if (method === 'item/fileChange/requestApproval') {
+    const changes = Array.isArray(item?.changes) ? item.changes : []
+    const first = changes[0] || {}
+    const toolName = changes.length > 1 ? 'MultiEdit' : first.kind === 'add' ? 'Write' : 'Edit'
+    return {
+      id,
+      toolName,
+      input: changes.length > 1
+        ? { edits: changes.map((change) => ({ file_path: change.path || '', path: change.path || '', kind: change.kind || 'update' })), ...(params.reason ? { reason: params.reason } : {}) }
+        : { file_path: first.path || params.grantRoot || '', path: first.path || params.grantRoot || '', kind: first.kind || 'update', ...(params.reason ? { reason: params.reason } : {}) },
+      risk: 'medium',
+    }
+  }
+  return null
+}
+
+export function codexApprovalResponse(decision) {
+  return { decision: decision === 'always' ? 'acceptForSession' : decision === 'allow' ? 'accept' : 'decline' }
+}
+
+function legacyQuestionAnswers(decision, questions) {
+  if (typeof decision !== 'string' || !decision.startsWith('answer:')) return {}
+  const text = decision.slice(7).trim()
+  if (!text || !questions.length) return {}
+  if (questions.length === 1) {
+    const question = questions[0]
+    const prefix = `${question.header || 'Q1'}: `
+    const value = text.startsWith(prefix) ? text.slice(prefix.length) : text
+    return { [String(question.id || 0)]: { answers: [value] } }
+  }
+  const answers = {}
+  questions.forEach((question, index) => {
+    const id = String(question.id || index)
+    const marker = `${index ? '; ' : ''}${question.header || `Q${index + 1}`}: `
+    const start = text.indexOf(marker)
+    if (start < 0) return
+    const valueStart = start + marker.length
+    const nextQuestion = questions[index + 1]
+    const nextMarker = nextQuestion ? `; ${nextQuestion.header || `Q${index + 2}`}: ` : null
+    const end = nextMarker ? text.indexOf(nextMarker, valueStart) : -1
+    const value = text.slice(valueStart, end < 0 ? undefined : end).trim()
+    if (value) answers[id] = { answers: [value] }
+  })
+  return answers
+}
+
+export function codexUserInputResponse(result, questions = []) {
+  const supplied = result && typeof result === 'object' ? result.answers : null
+  const answers = {}
+  if (supplied && typeof supplied === 'object') {
+    const allowed = new Set(questions.map((question, index) => String(question?.id || index)))
+    for (const [id, value] of Object.entries(supplied)) {
+      if (!allowed.has(String(id)) || !Array.isArray(value?.answers)) continue
+      const values = value.answers.map((answer) => String(answer)).filter(Boolean)
+      if (values.length) answers[String(id)] = { answers: values }
+    }
+  }
+  if (Object.keys(answers).length) return { answers }
+  const decision = result && typeof result === 'object' ? result.decision : result
+  return { answers: legacyQuestionAnswers(decision, questions) }
+}
+
+function appServerItemForMapper(item) {
+  if (!item || typeof item !== 'object') return item
+  const common = { ...item }
+  switch (item.type) {
+    case 'agentMessage': return { ...common, type: 'agent_message' }
+    case 'commandExecution': return { ...common, type: 'command_execution', aggregated_output: item.aggregatedOutput || '', exit_code: item.exitCode }
+    case 'fileChange': return { ...common, type: 'file_change' }
+    case 'webSearch': return { ...common, type: 'web_search' }
+    case 'mcpToolCall': return { ...common, type: 'mcp_tool_call', arguments: item.arguments || {}, result: item.result, error: item.error }
+    case 'reasoning': return { ...common, type: 'reasoning', text: [...(item.summary || []), ...(item.content || [])].join('\n') }
+    default: return common
+  }
+}
+
 /**
  * Start a structured Codex session. Mirrors startClaudeSession's contract.
  * @param {object} o
@@ -220,10 +329,11 @@ export function buildCodexExecArgs({ sessionId, model, effort, sandbox, approval
  * @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 {(req)=>Promise<string>} [o.requestPermission] shared room permission-card callback
  * @param {string} [o.providerConfig] optional -c overrides / provider block (M2: from the provider registry)
- * @returns {{ sendTurn(text), abort(), end(), readonly sessionId }}
+ * @returns {{ sendTurn(text, options?), abort(), end(), readonly sessionId }}
  */
-export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, rolePrompt, roomContext, mcpServers, prepareCwd = null }) {
+export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, rolePrompt, roomContext, mcpServers, prepareCwd = null, requestPermission, appServerGate = codexAppServerGate, appServerFactory = createCodexAppServer, spawnImpl = spawn }) {
   let activeMode = CODEX_MODE_CONFIG[mode] ? mode : 'default'
   let modeConfig = codexConfigForMode(activeMode)
   sandbox = normalizeCodexSandbox(sandbox || modeConfig.sandbox)
@@ -239,6 +349,14 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
   let activeEffort = EFFORT_LEVELS.has(initialEffort) ? initialEffort : 'high'
   let latestUsageSnapshot = sessionId ? readCodexThreadUsage(sessionId) : null
   let mcpHttpPromise = null
+  const appServerGateResult = appServerGate({ env: childEnv })
+  let appServerDisabled = !appServerGateResult.enabled
+  let appServer = null
+  let appServerThreadReady = false
+  let activeTurnId = null
+  const appServerItems = new Map()
+  const streamedAgentItems = new Map() // item id → { cid, text }
+  let steerChain = Promise.resolve()
   // serialize turns: one exec at a time
   let chain = Promise.resolve()
   const queue = []
@@ -254,6 +372,9 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
   })
 
   const note = (text) => { try { onEvent?.({ kind: 'note', text }) } catch { /* noop */ } }
+  if (!['0', 'false', 'off'].includes(String(childEnv.TP_CODEX_APP_SERVER || '').trim().toLowerCase()) && !appServerGateResult.enabled) {
+    queueMicrotask(() => note(`Codex App Server disabled: ${appServerGateResult.reason}`))
+  }
 
   async function ensureMcpHttp() {
     const thinkpool = mcpServers?.thinkpool
@@ -262,7 +383,164 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
     return mcpHttpPromise
   }
 
-  async function runExec(prompt) {
+  function appServerNotification(method, params = {}) {
+    if (method === 'turn/started' && params.turn?.id) {
+      activeTurnId = activeTurnId || params.turn.id
+      return
+    }
+    if (method === 'turn/plan/updated') {
+      const todos = (Array.isArray(params.plan) ? params.plan : []).map(({ step, status }) => ({
+        content: step || '',
+        activeForm: step || '',
+        status: status === 'inProgress' ? 'in_progress' : status === 'completed' ? 'completed' : 'pending',
+      })).filter((todo) => todo.content)
+      try { onEvent?.({ kind: 'assistant', blocks: [{ type: 'tool_use', id: `codex-plan:${params.turnId || 'active'}`, name: 'TodoWrite', input: { todos } }], parentToolUseId: null }) } catch { /* noop */ }
+      return
+    }
+    if (method === 'item/agentMessage/delta') {
+      if (!params.delta) return
+      const itemId = params.itemId || `turn:${params.turnId || activeTurnId || 'active'}`
+      const state = streamedAgentItems.get(itemId) || { cid: `codex-stream:${sessionId || 'thread'}:${itemId}`, text: '' }
+      state.text += String(params.delta)
+      streamedAgentItems.set(itemId, state)
+      // Cumulative transient snapshot. The bridge broadcasts this chrome event
+      // without assigning transcript seq/archive rows; room.jsx replaces the
+      // stable cid in place. item/completed emits one durable assistant row.
+      try { onEvent?.({ kind: 'assistant_stream', cid: state.cid, text: state.text, itemId, streaming: true }) } catch { /* noop */ }
+      return
+    }
+    if (method === 'item/started' || method === 'item/completed') {
+      const raw = params.item
+      if (!raw) return
+      if (method === 'item/started') appServerItems.set(raw.id, raw)
+      if (method === 'item/completed') {
+        appServerItems.set(raw.id, raw)
+        if (raw.type === 'agentMessage' && streamedAgentItems.has(raw.id)) {
+          const state = streamedAgentItems.get(raw.id)
+          streamedAgentItems.delete(raw.id)
+          try { onEvent?.({ kind: 'assistant', blocks: [{ type: 'text', text: raw.text || state.text }], parentToolUseId: null, replacesCid: state.cid }) } catch { /* noop */ }
+          return
+        }
+      }
+      mapper.push({ type: method === 'item/started' ? 'item.started' : 'item.completed', item: appServerItemForMapper(raw) })
+      return
+    }
+    if (method === 'error') {
+      const message = params.error?.message || params.message || 'codex app-server error'
+      mapper.push({ type: 'error', message })
+    }
+  }
+
+  async function appServerRequest(method, params = {}) {
+    const card = codexApprovalCard(method, params, appServerItems.get(params.itemId))
+    if (!card) throw new Error(`Unsupported Codex App Server request: ${method}`)
+    // Missing/broken room permission plumbing denies safely. App Server expects
+    // an ordinary response even for denial; an RPC error can strand the turn.
+    let decision = 'deny'
+    try { decision = await requestPermission?.(card) } catch { /* deny */ }
+    if (method === 'item/tool/requestUserInput') return codexUserInputResponse(decision, card.questions)
+    return codexApprovalResponse(decision)
+  }
+
+  async function ensureAppServer() {
+    if (appServerDisabled) return false
+    if (appServer?.alive === false) {
+      appServerThreadReady = false
+      appServerDisabled = true
+      return false
+    }
+    if (appServer && appServerThreadReady) return true
+    let peer
+    try { peer = await ensureMcpHttp() }
+    catch (error) { note(`Thinkpool peer tools unavailable: ${error?.message || error}`) }
+    try {
+      if (!appServer) {
+        appServer = appServerFactory({
+          cwd,
+          env: childEnv,
+          args: buildCodexAppServerArgs({ providerConfig, mcpUrl: peer?.url, writableDirs: publishAccess.writableDirs }),
+          onNotification: appServerNotification,
+          onServerRequest: appServerRequest,
+          onClose: (error) => {
+            if (ended || appServerDisabled) return
+            appServerThreadReady = false
+            appServerDisabled = true
+            note(`Codex App Server closed; later turns will use codex exec: ${error?.message || error}`)
+          },
+        })
+        await appServer.start()
+      }
+      sessionId = await appServer.startThread({
+        threadId: turnNo > 0 ? sessionId : null,
+        cwd,
+        model: activeModel,
+        sandbox,
+        approvalPolicy: modeConfig.approvalPolicy,
+      })
+      appServerThreadReady = true
+      mapper.push({ type: 'thread.started', thread_id: sessionId })
+      return true
+    } catch (error) {
+      // Fallback is safe only here: no turn/start request has been accepted, so
+      // there is no possibility of running the same prompt twice.
+      appServerDisabled = true
+      try { appServer?.end() } catch { /* noop */ }
+      appServer = null
+      appServerThreadReady = false
+      note(`Codex App Server unavailable; using codex exec: ${error?.message || error}`)
+      return false
+    }
+  }
+
+  async function runAppServer(prompt, options = {}) {
+    if (!await ensureAppServer()) return false
+    mapper.setUsageBaseline(sessionId ? readCodexThreadUsage(sessionId) : null)
+    aborted = false
+    turnActive = true
+    try {
+      activeTurnId = await appServer.startTurn({
+        threadId: sessionId,
+        input: prompt,
+        images: Array.isArray(options.images) ? options.images : [],
+        model: activeModel,
+        effort: activeEffort,
+        approvalPolicy: modeConfig.approvalPolicy,
+      })
+      const completed = await appServer.waitForTurn(activeTurnId)
+      const status = completed?.turn?.status
+      if (aborted || status === 'interrupted') {
+        try { onEvent?.({ kind: 'result', subtype: 'aborted', sessionId, model: activeModel, costUsd: null, usage: null, numTurns: 1, durationMs: completed?.turn?.durationMs, denials: 0, resultText: null }) } catch { /* noop */ }
+      } else if (status === 'failed') {
+        mapper.push({ type: 'turn.failed', message: completed?.turn?.error?.message || 'codex turn failed' })
+      } else {
+        mapper.push({ type: 'turn.completed' })
+      }
+    } catch (error) {
+      // Once a started turn's transport fails we must not replay that prompt via
+      // exec (the model may already have acted). Disable App Server for later
+      // turns only; they can safely resume this thread through the stable driver.
+      appServerDisabled = true
+      appServerThreadReady = false
+      try { appServer?.end() } catch { /* noop */ }
+      appServer = null
+      if (!ended) mapper.push({ type: 'turn.failed', message: `codex app-server turn failed: ${error?.message || error}` })
+    } finally {
+      // A transport failure or interrupt can land after prose deltas but before
+      // item/completed. Preserve that partial prose as one durable row rather
+      // than leaving a replay-less streaming shell behind.
+      for (const state of streamedAgentItems.values()) {
+        if (!state.text) continue
+        try { onEvent?.({ kind: 'assistant', blocks: [{ type: 'text', text: state.text }], parentToolUseId: null, replacesCid: state.cid }) } catch { /* noop */ }
+      }
+      activeTurnId = null
+      turnActive = false
+      appServerItems.clear()
+      streamedAgentItems.clear()
+    }
+    return true
+  }
+
+  async function runExec(prompt, options = {}) {
     // 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.
@@ -278,6 +556,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       providerConfig,
       mcpUrl: peer?.url,
       writableDirs: publishAccess.writableDirs,
+      images: Array.isArray(options.images) ? options.images : [],
       prompt,
     })
 
@@ -294,7 +573,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
 
       aborted = false
       turnActive = true
-      child = spawn('codex', args, opts)
+      child = spawnImpl('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 })
@@ -347,7 +626,9 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       // 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, firstTurn: turnNo === 0 }))
+      const prompt = buildCodexPrompt({ text: next.text, rolePrompt, roomContext, firstTurn: turnNo === 0 })
+      const usedAppServer = await runAppServer(prompt, next.options)
+      if (!usedAppServer) await runExec(prompt, next.options)
       turnNo++
       pump()
     })
@@ -357,13 +638,32 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
     get sessionId() { return sessionId },
     get usageSnapshot() { return latestUsageSnapshot },
     get turnActive() { return turnActive },
+    get canSteer() { return !!(appServer && appServer.alive !== false && appServerThreadReady && !appServerDisabled) },
     get started() { return turnNo > 0 || turnActive },
-    sendTurn(text) {
+    sendTurn(text, options = {}) {
       if (ended) return false
       if (!turnActive && turnNo === 0 && prepareCwd) {
         try { cwd = prepareCwd() || cwd } catch { /* keep original cwd */ }
       }
-      queue.push(text)
+      if (turnActive && appServer && activeTurnId) {
+        const prompt = buildCodexPrompt({ text, rolePrompt, roomContext })
+        const targetTurnId = activeTurnId
+        // Serialize authored follow-ups: parallel RPCs can complete out of order.
+        steerChain = steerChain.then(() => appServer.steer({ threadId: sessionId, turnId: targetTurnId, input: prompt, images: Array.isArray(options.images) ? options.images : [] }))
+          .catch((error) => {
+            // Retry only after an explicit server rejection or a synchronous
+            // pre-write failure. Timeout/close after write is delivery-uncertain;
+            // replaying it as a new turn can execute the same instruction twice.
+            if (error?.delivery === 'rejected' || error?.delivery === 'not_sent') {
+              queue.push({ text, options })
+              if (!turnActive && queue.length === 1) pump()
+            } else {
+              try { onEvent?.({ kind: 'error', message: 'Codex steering delivery is uncertain; the message was not replayed automatically.', recoverable: true }) } catch { /* noop */ }
+            }
+          })
+        return true
+      }
+      queue.push({ text, options })
       // start the pump if idle
       if (queue.length === 1) pump()
       return true
@@ -371,12 +671,14 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
     abort() {
       aborted = true
       queue.length = 0
+      if (appServer && activeTurnId) { void appServer.interrupt({ threadId: sessionId, turnId: activeTurnId }).catch(() => {}) ; return }
       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 */ } }
+      try { appServer?.end() } catch { /* noop */ }
       void mcpHttpPromise?.then((h) => h.close()).catch(() => {})
     },
     setModel(nextModel) {
@@ -395,6 +697,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       sessionId = null
       turnNo = 0
       latestUsageSnapshot = null
+      appServerThreadReady = false
       return true
     },
     setEffort(nextEffort) {
@@ -408,6 +711,7 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
       sessionId = null
       turnNo = 0
       latestUsageSnapshot = null
+      appServerThreadReady = false
       return true
     },
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.212",
+  "version": "0.7.214",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -15,6 +15,8 @@
     "claude-session.mjs",
     "codex-session.mjs",
     "thinkpool-room-prompt.mjs",
+    "codex-app-server.mjs",
+    "codex-images.mjs",
     "codex-mcp-http.mjs",
     "lane-worktree.mjs",
     "codex-event-mapper.mjs",