thinkpool-pair 0.7.354 → 0.7.357

package/bridge.mjs

@@ -47,7 +47,8 @@ import { createPermNotifier, shouldNotifyTurnDone, shouldRecordTurnDone, permiss
 // resolveProviderEnv(id) → {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL} for a
 // registered custom provider, or null for the built-in/unknown (leave the default env intact).
 // Multi-provider BYOK slice 1: a lane spawned with a `provider` id runs on that endpoint.
-import { resolveProviderEnv, resolveProviderRef, providerNameMap, publicKeyB64, bridgeHostId, announceProviders, listProviders, effectiveLaneModel, sameProviderEnv, providerModel } from './providers.mjs'
+import { resolveProviderEnv, resolveProviderRef, resolveProviderResiliencePolicy, providerNameMap, publicKeyB64, bridgeHostId, announceProviders, listProviders, effectiveLaneModel, sameProviderEnv, providerModel } from './providers.mjs'
+import { createMemoryCircuit, providerResilienceCapAdmission } from './provider-resilience.mjs'
 import { validateProviderSwitch, providerSwitchPlan, BUILTIN_PROVIDER } from './switch-provider.mjs'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
@@ -55,6 +56,7 @@ import { readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThread
 import { codexAccountUsageLine, codexCreditsReportLine, codexLimitReportLine } from './codex-commands.mjs'
 import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 import { startStructuredSession } from './runtime-session.mjs'
+import { admitRuntimeCapability } from './runtime-contract.mjs'
 import { cleanTerminalName, modelTerminalNameInput } from './terminal-name.mjs'
 import { defaultStructuredMode, normalizeStructuredEffort, shouldDeferStructuredRuntime, structuredModeForSlice, structuredModeLocked, structuredModesForLane, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
 import { commandCatalogForRuntime, commandHelpLine, reconcileCommandCatalog } from './command-catalog.mjs'
@@ -671,6 +673,10 @@ const BRIDGE_STARTED_AT = Date.now()
 // top-level only (one bridge per announce); older clients ignore the unknown key.
 const host = (os.hostname() || 'host').split('.')[0].slice(0, 24)
 const hostId = bridgeHostId()
+// Phase 1 circuit state is deliberately memory-only. Its primitive keys state
+// by bridge/provider/exact-model; a process restart clears it and no credential,
+// endpoint, prompt, or raw error ever enters the map.
+const providerResilienceCircuit = createMemoryCircuit()
 
 // Repo awareness — the room shows which project this machine is sharing.
 // Cheap reads, no subprocess: directory name + .git/HEAD.
@@ -2263,6 +2269,10 @@ function worktreeSnapshot(cwd) {
 function openStructured({ id, runtime = 'claude', model, models, effort, resume, log, commands, mode, spawnedBy, spawnDepth, cascadeRole, hop, sideParent, sideTask, pendingSideContexts, pendingWorkerCompletions, workerCompletionsInFlight, rolePrompt, sliceType, flowSessionId, flowTaskKey, flowRole, flowReviewTarget, flowReviewTargets, flowReviewSnapshots, flowReviewRound, dispatchBaseSha, revertTarget, cwd, managedWorktree, reviewSliceRoots, openedAt, defer, provider, carryRecap, lastUsage, receivedTurnCids }) {
   if (sessions.has(id)) return
   runtime = structuredRuntimeMetadata(runtime) ? runtime : 'claude'
+  // Fail closed before exposing a native lane if its bridge semantic contract
+  // was removed or mismatched. This does not replace native tool transports.
+  const runtimeContract = admitRuntimeCapability({ runtime, capabilityId: 'terminal_interrupt', input: {} })
+  if (!runtimeContract.ok) throw new TypeError(`Structured runtime contract rejected: ${runtimeContract.code}`)
   mode = structuredModeForSlice(runtime, { mode, sliceType, flowRole })
   // No explicit mode → a sensible default per runtime (see defaultModeForRuntime):
   // codex → bypassPermissions, so a freshly-opened codex terminal can fetch /
@@ -3249,6 +3259,33 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     flowRole: entry.flowRole,
     sideParent: entry.sideParent,
   }), canSpawnWorkers ? HERMES_VISIBLE_WORKER_FALLBACK_RULE : ''].filter(Boolean).join('\n\n')
+  const resolvedProviderResilience = runtime === 'claude'
+    ? resolveProviderResiliencePolicy(provider)
+    : null
+  let resilienceCapAbsenceLogged = false
+  const providerResilience = resolvedProviderResilience?.policy?.enabled === true
+    ? {
+        policy: resolvedProviderResilience.policy,
+        providers: listProviders(),
+        providerId: resolvedProviderResilience.target.providerId,
+        model: resolvedProviderResilience.target.actualConfiguredModel,
+        requestedModel: laneModel || resolvedProviderResilience.target.actualConfiguredModel,
+        bridgeHostId: hostId,
+        circuit: providerResilienceCircuit,
+        // sendTurn creates the controller immediately before the bridge advances
+        // its public turn revision, so project the revision that admission owns.
+        turnRev: () => (Number(entry._turnRev) || 0) + 1,
+        capGate: () => {
+          const budget = entry.flowSessionId ? flowBudgets.get(entry.flowSessionId) : null
+          const admission = providerResilienceCapAdmission(budget)
+          if (!admission.configured && !resilienceCapAbsenceLogged) {
+            resilienceCapAbsenceLogged = true
+            process.stderr.write(`\n  ${A.dim}◇ provider resilience cap_not_configured (${String(id).slice(0, 8)})${A.rst}\n`)
+          }
+          return admission
+        },
+      }
+    : null
   entry.session = startStructuredSession(runtime, {
     // laneModel, NOT the raw `model` param: the SDK's `model` option OVERRIDES the
     // ANTHROPIC_MODEL supplied by resolveProviderEnv() in `env` below, so an inherited
@@ -3355,6 +3392,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // per-machine default (provider.mjs/applyProviderEnv). null for built-in/unknown → the
     // default Claude env is left exactly as-is (unchanged path).
     env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), ...(resolveProviderEnv(provider) || {}), TP_MOCKUP_OUTBOX: mockupOutbox },
+    // Same-target custom-provider resilience is a host-local dark-launch
+    // primitive. Missing/disabled policy, built-in Anthropic, Codex, and Hermes
+    // receive null and preserve their established transport behavior exactly.
+    resilience: providerResilience,
     onTurnStart: (options = {}) => {
       // Hermes promotes /queue items internally, without a second code-turn.
       // Advance the lifecycle before its first output and publish the deferred

package/claude-session.mjs

@@ -22,8 +22,10 @@ import { reviewGatePreToolDecision } from './flow-review-gate.mjs'
 import { crossPostNeedsCard } from './cross-terminal.mjs'
 import { correctContext } from './context-windows.mjs'
 import { normalizeClaudeCommandCatalog } from './claude-command-catalog.mjs'
+import { evidenceForToolResult } from './evidence-citations.mjs'
 import { THINKPOOL_CASCADE_RULE, THINKPOOL_REMOTE_DELIVERY_RULES, THINKPOOL_RUNTIME_AUTHORITY_RULE, THINKPOOL_RUNTIME_TURN_REMINDER, buildThinkPoolTurnGuidance, createRoomContextSelector, usesFullThinkPoolReminder } from './thinkpool-room-prompt.mjs'
 import { stallDecision, stallEvent, isCompactTurn } from './turn-stall.mjs'
+import { createSameTargetResilienceController, formatResilienceTrace } from './provider-resilience.mjs'
 
 // The caret-pulled SDK's real version (^0.3.x auto-upgrades on restart). Resolved
 // once at import by walking up from the package entry to its own package.json.
@@ -244,7 +246,7 @@ const TP_ROOM_REMINDER = [
   'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans worker slices into visible spawn_terminal lanes and verifies them. Worker/leaf/Side/managed Flow roles do not fan out. A person-requested new or separate terminal uses open_main_terminal. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
 ].join(' ')
 
-export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null, admitStart = null }) {
+export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null, admitStart = null, resilienceObserver = null, resilience = null }) {
   // Per-turn reminder + live ROOM NOW tail. roomContext (bridge-supplied) returns the
   // room's CURRENT state — sibling lanes, active git worktrees — or null. The static
   // rules keep the agent aware of the room's FEATURES; the live tail keeps it aware of
@@ -271,6 +273,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   let persistedSessionId = resume || null
   let lastTurnText = null   // the most recent turn text, so a bad-resume recovery can re-deliver it
   let lastTurnReminder = null
+  let lastTurnBlocks = null // exact current prompt blocks; same-target retry must replay byte-for-byte
   let closed = false
   // Lazy boot (2026-07-02): a RESTORED-IDLE terminal returns a full session object but
   // defers the expensive query() cold-start (MCP + settingSources, ~50s each) until its
@@ -297,7 +300,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   // never throws an ExitPlanMode card. Falls back to 'default' for unknown values.
   let mode = MODES.has(initialMode) ? initialMode : 'default'  // mirrors ⇧⇥ cycle
   const alwaysAllow = new Set()  // tool:risk signatures the user chose "don't ask again" for
-  const toolStart = new Map()     // tool_use id → start time, for the duration badge
+  const toolStart = new Map()     // tool_use id → source metadata for duration/evidence
   const effortLevels = new Set(['low', 'medium', 'high', 'xhigh', 'max'])
   let effort = effortLevels.has(initialEffort) ? initialEffort : 'high'
   // Live token count for the thinking indicator — mirrors Claude Code's
@@ -348,6 +351,17 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   const RESTART_MAX = 3
   const RECOVERABLE = /connection closed|connection reset|econnreset|etimedout|socket hang up|fetch failed|network error|socket destroyed/i
   let restartCount = 0
+  // Phase 0 measurement seam. The observer receives only a coarse recovery
+  // reason/count; it cannot alter this session's existing retry behavior.
+  const observeRecovery = (reason, detail = {}) => { try { resilienceObserver?.({ reason, restartCount, ...detail }) } catch { /* observer is strictly read-only */ } }
+  // Phase 1 is opt-in and applies only to a named non-Anthropic custom target. Keep
+  // disabled/built-in sessions on the established RESTART_MAX recovery path exactly.
+  const resilienceEnabled = !!(resilience?.policy?.enabled && resilience?.providerId && resilience.providerId !== 'anthropic')
+  let turnResilience = null
+  let resilienceDeadlineTimer = null
+  let resilienceRetryPending = false
+  let resilienceTurnRevision = 0
+  let abortPending = false
   let restartTimer = null   // the pending auto-restart backoff — cancelled by end()
   // Force-stop a true wedge (item 3): no result, no error, just silence past
   // FORCE_STOP_MS. As of the 2026-07-08 hardening we no longer just surface an error
@@ -396,6 +410,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   // cleared on the next result — "all teardown has arrived" isn't observable. `success`
   // results are never swallowed, so the flushed steer's completion always surfaces.
   let interrupting = false
+  let interruptingRevision = null
   let interruptTimer = null
   const INTERRUPT_SWALLOW_MS = 6000
   // ── Haiku suggestion fallback ──
@@ -419,6 +434,59 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   // (`result`/`error` — covers a no-op "Not enough messages to compact" and a Stop). After
   // that the normal wedge timeline applies again.
   const emit = (evt) => { lastEvtTs = Date.now(); if (evt && evt.kind !== 'stalled') stalledSent = false; if (evt && (evt.kind === 'compaction' || evt.kind === 'result' || evt.kind === 'error')) compacting = false; emitRaw(evt) }
+  // The controller only receives its own allowlisted records. Room notes are likewise
+  // rendered from that projection, never from an SDK error, URL, credential, or prompt.
+  const resilienceRecord = (record) => {
+    try { resilience?.onRecord?.(record) } catch { /* observer is never control flow */ }
+    if (record?.outcome === 'retrying' || record?.outcome === 'cap_blocked' || record?.outcome === 'circuit_open') {
+      emit({ kind: 'note', text: formatResilienceTrace(record) })
+    }
+  }
+  const clearResilienceDeadline = () => {
+    if (resilienceDeadlineTimer == null) return
+    try { (resilience?.clearTimer || clearTimeout)(resilienceDeadlineTimer) } catch { /* deadline cleanup is best-effort */ }
+    resilienceDeadlineTimer = null
+  }
+  const armResilienceDeadline = () => {
+    clearResilienceDeadline()
+    if (!turnResilience) return
+    const timeoutMs = Number(resilience?.policy?.timeoutMs)
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return
+    const schedule = resilience?.setTimer || setTimeout
+    resilienceDeadlineTimer = schedule(() => {
+      resilienceDeadlineTimer = null
+      if (closed || !turnResilience || !turnActive) return
+      // This is a bridge-authored timeout classification, never a raw provider
+      // error. Abort the wedged iterator, then reuse the same controller budget.
+      turnResilience.failure({ message: 'timeout' })
+      turnActive = false
+      try { qAc?.abort() } catch { /* the disposal wait below still fails closed */ }
+      retryResilientTurn()
+    }, timeoutMs)
+  }
+  const createTurnResilience = () => {
+    if (!resilienceEnabled) return null
+    try {
+      const controller = createSameTargetResilienceController({
+        runtime: 'claude', providers: resilience.providers || [], providerId: resilience.providerId,
+        model: resilience.model || opts.model || model,
+        requestedModel: resilience.requestedModel || resilience.model || opts.model || model,
+        policy: resilience.policy, bridgeHostId: resilience.bridgeHostId,
+        circuit: resilience.circuit, capGate: resilience.capGate,
+        traceId: resilience.traceId,
+        turnRev: typeof resilience.turnRev === 'function' ? resilience.turnRev() : resilience.turnRev,
+        onRecord: resilienceRecord,
+      })
+      controller.start()
+      return controller
+    } catch { return null }
+  }
+  const admitResilientSubmission = async () => {
+    if (!turnResilience) return true
+    let admission = null
+    try { admission = await turnResilience.preflight() } catch { return false }
+    return admission?.admitted === true
+  }
   const stallTimer = setInterval(() => {
     const quiet = Date.now() - lastEvtTs
     const action = stallDecision({ turnActive, awaitingUser, quietMs: quiet, stallMs: STALL_MS, forceStopMs: FORCE_STOP_MS, stalledSent, stallRetried, compacting, compactForceStopMs: COMPACT_FORCE_STOP_MS })
@@ -428,7 +496,23 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     const ev = stallEvent(action, quiet)
     if (ev) emitRaw(ev)
     if (action === 'status') { stalledSent = true; return }
-    if (action === 'retry') { forceStopped = true; retryStalledTurn(quiet); return }
+    if (action === 'retry') {
+      forceStopped = true
+      if (turnResilience) {
+        // The legacy watchdog must never create a second retry ledger. Route
+        // its terminal timeout through the same controller; visible output or
+        // an exhausted attempt budget makes the following preflight fail closed.
+        observeRecovery('resilience_stall', { quietMs: quiet })
+        turnResilience.failure({ message: 'timeout' })
+        turnActive = false
+        try { qAc?.abort() } catch { /* disposal is awaited by the shared retry path */ }
+        retryResilientTurn()
+        return
+      }
+      observeRecovery('stall_replay', { quietMs: quiet })
+      retryStalledTurn(quiet)
+      return
+    }
     // 'giveup' — the one auto-retry ALSO stalled past FORCE_STOP_MS. Fall back to the
     // pre-2026-07-08 behavior: force-stop the turn so between-turns updates unblock, and
     // let the human resend. The wedged loop is left in place; if it later throws, the
@@ -682,6 +766,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     // On deny, permissionDecisionReason IS what the model receives as the
     // tool error — make it a real instruction, not an opaque tag.
     const denied = decision === 'deny'
+    if (denied && turnResilience) turnResilience.failure({ permissionDenied: true })
     return {
       continue: true,
       hookSpecificOutput: {
@@ -947,9 +1032,13 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             }
             break
           case 'assistant':
+            clearResilienceDeadline()
+            // Any assistant block (including a tool_use) has crossed the replay
+            // boundary. A same-target retry is only safe before visible output.
+            turnResilience?.visibleOutput()
             // Stamp tool-call start times so tool_result can report a duration.
             for (const b of (m.message?.content || [])) {
-              if (b?.type === 'tool_use' && b.id) toolStart.set(b.id, Date.now())
+              if (b?.type === 'tool_use' && b.id) toolStart.set(b.id, { at: Date.now(), name: b.name, input: b.input })
             }
             // parentToolUseId: non-null when this assistant message comes from a
             // sub-agent (Task tool) — the universal nesting spine. Thread it so the
@@ -962,9 +1051,12 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             // tool_result blocks arrive on the user-role echo
             for (const b of (m.message?.content || [])) {
               if (b?.type === 'tool_result') {
+                clearResilienceDeadline()
+                turnResilience?.visibleOutput({ tool: true })
                 const start = toolStart.get(b.tool_use_id)
                 if (start != null) toolStart.delete(b.tool_use_id)
-                emit({ kind: 'tool_result', toolUseId: b.tool_use_id, content: b.content, isError: !!b.is_error, durationMs: start != null ? Date.now() - start : undefined, parentToolUseId: m.parent_tool_use_id || null })
+                const evidence = evidenceForToolResult(start?.name, b.content)
+                emit({ kind: 'tool_result', toolUseId: b.tool_use_id, content: b.content, ...(evidence ? { evidence } : {}), isError: !!b.is_error, durationMs: start?.at != null ? Date.now() - start.at : undefined, parentToolUseId: m.parent_tool_use_id || null })
               }
             }
             break
@@ -985,6 +1077,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             break
           }
           case 'result':
+            clearResilienceDeadline()
             if (m.session_id) sessionId = m.session_id
             // Bad resume target: the CLI can't find the session we tried to resume — a forked
             // id that was never persisted, or a pruned transcript. It surfaces as an is_error
@@ -1014,7 +1107,26 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             // abort() already emitted the one canonical aborted boundary. `success` (and any
             // non-teardown subtype) always emits; only the aborted/error_during_execution pair
             // the interrupt churns out is dropped, and only inside the timer-bounded window.
-            if (interrupting && (m.subtype === 'aborted' || m.subtype === 'error_during_execution')) { turnActive = false; break }
+            // This guard MUST precede resilient `is_error` handling: the second teardown echo
+            // is itself an is_error result and may arrive after the next turn has installed a
+            // new controller. Letting it reach that controller would retry the wrong prompt.
+            if (interrupting && (m.subtype === 'aborted' || m.subtype === 'error_during_execution')) {
+              // A late teardown echo from the stopped turn may arrive after the
+              // next turn is accepted. Swallow the echo, but only mutate liveness
+              // while the stopped revision still owns the lane.
+              if (resilienceTurnRevision === interruptingRevision) turnActive = false
+              break
+            }
+            // Some SDK transport failures arrive as an error result instead of a
+            // thrown iterator error. Treat them identically, without serializing
+            // `m.errors` or `m.result` into the room event stream.
+            if (m.is_error && turnResilience) {
+              if (resilienceRetryPending) break
+              turnResilience.failure({ message: Array.isArray(m.errors) ? m.errors.join(' ') : m.result, status: m.status ?? m.statusCode, code: m.code })
+              turnActive = false
+              retryResilientTurn()
+              break
+            }
             turnBaseOut = 0; curMsgOut = 0   // reset the live token count for the next turn
             turnActive = false               // turn settled → stall watchdog stands down
             // A model switch requested mid-turn was deferred — apply it now the turn is done.
@@ -1022,6 +1134,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
             // doesn't await itself; the setTimeout runs after this iterator yields.
             if (pendingSwitch) { pendingSwitch = false; setTimeout(() => { if (!closed) recreateForSwitch() }, 0) }
             if (m.subtype === 'success') { restartCount = 0; if (sessionId) persistedSessionId = sessionId }   // ONLY a real success refills the
+            if (m.subtype === 'success') { turnResilience?.success(); turnResilience = null }
             // auto-restart budget (else a flapping connection that lands one aborted turn between
             // drops refills every cycle past RESTART_MAX) — and marks this session id durably
             // persisted so a later model-switch re-create can safely resume it.
@@ -1075,11 +1188,22 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
         }
       }
     } catch (e) {
+      clearResilienceDeadline()
       if (closed) return
       // This query was intentionally aborted (a model switch superseded it, or the
       // session is ending) — not a real error. Stay silent; the re-create owns what's next.
       if (myAc.signal.aborted) return
       const msg = e?.message || String(e)
+      // Enabled custom-provider turns have a strict, per-turn controller. It
+      // classifies the raw transport error locally, then either admits one exact
+      // replay before any output or terminates without putting provider details in
+      // the room. The legacy path below is intentionally untouched when disabled.
+      if (turnResilience && turnActive) {
+        turnResilience.failure({ message: msg, status: e?.status ?? e?.statusCode, code: e?.code })
+        turnActive = false
+        retryResilientTurn()
+        return
+      }
       // onEvent is also the bridge's synchronous busy-edge sampling point. The
       // query has already ended here, so publish the failure only after clearing
       // the turn. Otherwise a non-recoverable SDK error leaves the roster on its
@@ -1092,6 +1216,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       // fresh input stream is needed because the throw killed the old iterator.
       if (RECOVERABLE.test(msg) && restartCount < RESTART_MAX) {
         restartCount++
+        observeRecovery('stream_reconnect', { failureClass: 'network' })
         emit({ kind: 'note', text: `connection dropped — reconnecting (${restartCount}/${RESTART_MAX})` })
         // End the OLD input stream before swapping — else its generator leaks
         // (suspended forever) and a turn pushed into it after the throw is silently
@@ -1186,12 +1311,63 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       emitRaw({ kind: 'note', text: 'retrying the stalled turn on a fresh connection' })
     }
   }
-  if (!lazy) runQuery()
+  // A resilience retry has to wait for the failed Query's disposal: otherwise the
+  // replay races its session-file lock. Admission is deliberately before runQuery(),
+  // so a refused cap/circuit sends no second provider submission.
+  const retryResilientTurn = () => {
+    if (closed || abortPending || resilienceRetryPending) return
+    const retryingTurn = turnResilience
+    const retryingRevision = resilienceTurnRevision
+    const retryingBlocks = lastTurnBlocks
+    resilienceRetryPending = true
+    const dying = qDone
+    const oldInput = input
+    input = makeInputStream()
+    try { oldInput.end() } catch { /* noop */ }
+    restartTimer = setTimeout(async () => {
+      restartTimer = null
+      try { await dying } catch { /* disposal failure still fails closed below */ }
+      if (closed || !resilienceRetryPending || turnResilience !== retryingTurn || resilienceTurnRevision !== retryingRevision) return
+      if (!(await admitResilientSubmission())) {
+        resilienceRetryPending = false
+        finishResilientFailure()
+        return
+      }
+      if (closed || !resilienceRetryPending || turnResilience !== retryingTurn || resilienceTurnRevision !== retryingRevision) return
+      resilienceRetryPending = false
+      turnActive = true
+      lastEvtTs = Date.now()
+      stalledSent = false
+      runQuery()
+      // This is the exact previously accepted prompt block array, not a rebuilt
+      // string/reminder. It is only reached before assistant or tool output.
+      if (retryingBlocks) input.push(retryingBlocks)
+      armResilienceDeadline()
+    }, 0)
+  }
+  const finishResilientFailure = () => {
+    clearResilienceDeadline()
+    turnActive = false
+    turnResilience = null
+    // The failed Query is gone, but the lane remains recoverable for a later
+    // human turn. `started=false` ensures that turn creates a fresh Query rather
+    // than pushing into the ended stream.
+    started = false
+    emit({
+      kind: 'error',
+      message: 'The configured provider could not complete this turn. Nothing else was sent.',
+      recoverable: true,
+    })
+  }
+  // A custom resilient session defers its otherwise-eager query creation until a
+  // turn clears the injected admission gate. Disabled and built-in sessions retain
+  // their existing eager start and RESTART_MAX behavior.
+  if (!lazy && !resilienceEnabled) runQuery()
 
   return {
     // A lazy (restored-idle) session cold-boots the query on its first turn. input.push
     // is queue-backed, so the pushed turn buffers and runs once the query is ready.
-    sendTurn(text) { if (!closed) { if (!started && !admitColdStart()) return false; if (!started && prepareCwd) { try { const next = prepareCwd(); if (next) { cwd = next; opts.cwd = next } } catch { /* keep original cwd */ } } if (!started) runQuery({ admitted: true }); turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false; stallRetried = false; forceStopped = false;
+    sendTurn(text) { if (closed || abortPending || resilienceRetryPending) return false; if (!started && !admitColdStart()) return false; if (!started && prepareCwd) { try { const next = prepareCwd(); if (next) { cwd = next; opts.cwd = next } } catch { /* keep original cwd */ } } turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false; stallRetried = false; forceStopped = false;
       const t = String(text)
       const promptIndex = userPromptNo++
       const thisTurnForceFull = forceFullReminder
@@ -1210,11 +1386,34 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       // recognized). So a slash command goes CLEAN; conversational turns keep the reminder.
       // Normal turns never start with "/" (composeAgentStdin prepends the preamble), and the
       // web already routes "/"-prefixed input as a command (pane.jsx), so this matches intent.
-      input.push(/^\s*\//.test(t) ? [{ type: 'text', text: t }] : [{ type: 'text', text: t }, { type: 'text', text: lastTurnReminder }])
-    } },
+      lastTurnBlocks = /^\s*\//.test(t) ? [{ type: 'text', text: t }] : [{ type: 'text', text: t }, { type: 'text', text: lastTurnReminder }]
+      resilienceTurnRevision++
+      turnResilience = createTurnResilience()
+      if (turnResilience) {
+        const submittingTurn = turnResilience
+        const submittingRevision = resilienceTurnRevision
+        const submittingBlocks = lastTurnBlocks
+        // Keep the public sendTurn edge synchronous. The prompt is held locally until
+        // the asynchronous bridge cap admits it; a rejection never reaches the SDK.
+        void admitResilientSubmission().then((admitted) => {
+          // Stop or a newer human turn can land while cap admission is pending.
+          // In either case this exact turn no longer owns the submission edge.
+          if (closed || !turnActive || turnResilience !== submittingTurn || resilienceTurnRevision !== submittingRevision) return
+          if (!admitted) { finishResilientFailure(); return }
+          if (!started) runQuery({ admitted: true })
+          input.push(submittingBlocks)
+          armResilienceDeadline()
+        }).catch(() => {
+          if (!closed && turnActive && turnResilience === submittingTurn && resilienceTurnRevision === submittingRevision) finishResilientFailure()
+        })
+      } else {
+        if (!started) runQuery({ admitted: true })
+        input.push(lastTurnBlocks)
+      }
+    },
     // Cold-boot the query WITHOUT sending a turn — the background warmer calls this on
     // lazily-restored idle terminals so they're ready before the user clicks them.
-    warm() { if (!started && !closed) runQuery() },
+    warm() { if (!resilienceEnabled && !started && !closed) runQuery() },
     get started() { return started },
     // Set the permission mode — Claude Code's ⇧⇥ cycle. setPermissionMode is a
     // streaming control request (drives plan-mode behaviour SDK-side); the local
@@ -1268,25 +1467,51 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     // Graceful interrupt (Esc / Stop) — stops the current turn but keeps the
     // session alive for the next one. ac.abort() is teardown only (end()).
     async abort() {
+      if (abortPending) return
+      abortPending = true
+      try {
       // Swallow the SDK's redundant interrupt teardown (aborted + error_during_execution +
       // re-init) — we emit the one canonical boundary below. Set BEFORE interrupt so the
       // teardown results, which arrive async on the query loop, are caught; the timer bounds
       // the window so a genuine later turn failure still surfaces.
-      if (turnActive) {
+      const retryWasPending = resilienceRetryPending
+      const retryDisposal = retryWasPending ? qDone : null
+      if (turnActive || retryWasPending) {
+        resilienceTurnRevision++
+        // Keep the retry-pending ingress guard armed while Stop awaits the old
+        // process. The revision invalidates the retry itself; the flag prevents
+        // a new human turn from entering its reader-less replacement stream.
+        if (!retryWasPending) resilienceRetryPending = false
+        clearResilienceDeadline()
+        turnResilience?.failure({ aborted: true })
+        if (retryWasPending) {
+          clearTimeout(restartTimer)
+          restartTimer = null
+          started = false
+        }
         interrupting = true
+        interruptingRevision = resilienceTurnRevision
         clearTimeout(interruptTimer)
-        interruptTimer = setTimeout(() => { interrupting = false }, INTERRUPT_SWALLOW_MS)
+        interruptTimer = setTimeout(() => { interrupting = false; interruptingRevision = null }, INTERRUPT_SWALLOW_MS)
       }
       try { await q?.interrupt?.() } catch { /* noop */ }
+      // A failed query may already be inside its bounded disposal while its
+      // retry owns no live SDK turn. Keep Stop's barrier open until that process
+      // is actually gone so a later human turn cannot race its session lock.
+      if (retryDisposal) { try { await retryDisposal } catch { /* already disposed */ } }
+      if (retryWasPending) resilienceRetryPending = false
       // interrupt() stops the turn but emits NO terminal message. Without one the
       // struct stream ends on a non-terminal event, so on resume the SDK treats the
       // turn as INCOMPLETE and auto-continues it — the 2026-06-22 "zombie turn that
       // resumes itself" storm. Emit a terminal result so the turn is marked DONE +
       // persists across refresh. Guarded on turnActive to avoid a double-emit if the
       // SDK already surfaced one for the interrupt. (restored from 0.7.49)
-      if (turnActive) { turnActive = false; emit({ kind: 'result', subtype: 'aborted', sessionId }) }
+      if (turnActive || retryWasPending) { turnActive = false; emit({ kind: 'result', subtype: 'aborted', sessionId }) }
+      } finally {
+        abortPending = false
+      }
     },
-    end() { closed = true; clearInterval(stallTimer); clearTimeout(interruptTimer); clearTimeout(restartTimer); if (sugTimer) clearTimeout(sugTimer); input.end(); try { ac.abort() } catch { /* noop */ } },
+    end() { closed = true; clearResilienceDeadline(); clearInterval(stallTimer); clearTimeout(interruptTimer); clearTimeout(restartTimer); if (sugTimer) clearTimeout(sugTimer); input.end(); try { ac.abort() } catch { /* noop */ } },
     get sessionId() { return sessionId },
     get mode() { return mode },
     get turnActive() { return turnActive },   // a turn is in flight (gates between-turns update restart — Slice 3 Contract #1)

package/code-event-contract.mjs

@@ -1,6 +1,8 @@
 /* Canonical ThinkPool Code event contract.
    Keep this module browser-safe: the bridge and src/pages/code both consume it. */
 
+import { recoveryCodeEvent } from './error-recovery.mjs'
+
 export const EVENT_CLASS = Object.freeze({
   VOLATILE_PRESENCE: 'volatile-presence',
   REPLAYABLE_PROGRESS: 'replayable-progress',
@@ -60,6 +62,7 @@ export const CODE_EVENT_REGISTRY = Object.freeze({
   image: E,
   'needs-input': E,
   'needs-resolved': E,
+  continuation: E,
   'turn-done': E,
 })
 
@@ -106,3 +109,9 @@ export function unknownCodeEventNotice (eventOrKind) {
 }
 
 export const isKnownCodeEventKind = (kind) => Object.hasOwn(CODE_EVENT_REGISTRY, kind)
+
+// Normalize recovery reporting before it enters the durable room log. This is a
+// projection only: adapters retain their existing retry and session behavior.
+export function boundedRecoveryCodeEvent(input) {
+  return recoveryCodeEvent(input)
+}

package/codex-event-mapper.mjs

@@ -31,6 +31,7 @@
 import fs from 'node:fs'
 import { CODEX_COMMAND_CATALOG } from './codex-commands.mjs'
 import { normalizeEditKind, summarizeTextDiff } from './edit-diff.mjs'
+import { evidenceForToolResult } from './evidence-citations.mjs'
 
 const safeMcpPart = (value) => String(value || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_')
 const mcpToolName = (item) => `mcp__${safeMcpPart(item?.server)}__${safeMcpPart(item?.tool)}`
@@ -165,7 +166,9 @@ export class CodexEventMapper {
           const query = webSearchQuery(it)
           this._emit({ kind: 'tool_result', toolUseId: it.id, toolInput: { query }, content: [{ type: 'text', text: query || 'search completed' }], isError: false, durationMs, parentToolUseId: null })
         } else if (it.type === 'mcp_tool_call') {
-          this._emit({ kind: 'tool_result', toolUseId: it.id, content: [{ type: 'text', text: it.error?.message || resultText(it.result) }], isError: it.status === 'failed' || !!it.error, durationMs, parentToolUseId: null })
+          const content = [{ type: 'text', text: it.error?.message || resultText(it.result) }]
+          const evidence = evidenceForToolResult(mcpToolName(it), content)
+          this._emit({ kind: 'tool_result', toolUseId: it.id, content, ...(evidence ? { evidence } : {}), isError: it.status === 'failed' || !!it.error, durationMs, parentToolUseId: null })
         }
         // plan_update remains an additive future event shape. Unknown
         // items are ignored rather than risking a malformed transcript row.

package/context-contract.mjs

@@ -0,0 +1,95 @@
+// Deterministic, local-only description of the safe context ThinkPool supplies
+// to a native runtime. This is deliberately not a transcript store.
+
+import { createHash } from 'node:crypto'
+
+export const CONTEXT_CONTRACT_VERSION = 1
+export const CONTEXT_OMISSIONS = Object.freeze(['raw_pty', 'credentials', 'absolute_paths', 'unapproved_cross_room'])
+export const CONTEXT_SOURCE_POLICY = Object.freeze([
+  Object.freeze({ kind: 'current_user_turn', maxBytes: 8192 }),
+  Object.freeze({ kind: 'room_now_delta', maxBytes: 4096 }),
+  Object.freeze({ kind: 'flow_slice_digest', maxBytes: 8192 }),
+  Object.freeze({ kind: 'approved_human_response', maxBytes: 4096 }),
+])
+
+const BY_KIND = new Map(CONTEXT_SOURCE_POLICY.map((source) => [source.kind, source]))
+const HOST_PATH = /(?:\/home\/|\/users\/|\/private\/|\/tmp\/|[a-z]:\\|\\\\|(?:^|[\\/])\.\.(?:[\\/]|$))/i
+const SECRET_KEY = /(secret|token|password|authorization|api.?key|private.?key)/i
+const SECRET_VALUE = /(?:sk-[a-z0-9_-]{8,}|gsk_[a-z0-9_-]{8,}|AIza[a-z0-9_-]{8,}|gh[pousr]_[a-z0-9]{20,}|github_pat_[a-z0-9_]{20,}|xox[baprs]-[a-z0-9-]{10,}|AKIA[0-9A-Z]{16}|sbp_[a-z0-9]{20,}|eyJ[a-z0-9_-]{16,}\.[a-z0-9_-]{16,}\.[a-z0-9_-]{8,}|bearer\s+[a-z0-9._-]{8,})/i
+const PROHIBITED = /(?:raw transcript|tool args?|chain[ -]of[ -]thought|hidden reasoning|system prompt|environment dump|provider key|BEGIN (?:RSA |OPENSSH )?PRIVATE KEY)/i
+const SAFE_REF = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/
+const bytes = (value) => {
+  try {
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value)
+    return new TextEncoder().encode(serialized ?? '').length
+  } catch {
+    return Infinity
+  }
+}
+const stable = (value) => Array.isArray(value)
+  ? value.map(stable)
+  : value && typeof value === 'object'
+    ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
+    : value
+
+export function isSafeContextValue(value, maxBytes = 8192) {
+  if (value == null || bytes(value) > maxBytes) return false
+  const visit = (node) => {
+    if (typeof node === 'string') return node.length <= 2048 && !HOST_PATH.test(node) && !SECRET_VALUE.test(node) && !PROHIBITED.test(node)
+    if (node == null || typeof node === 'number' || typeof node === 'boolean') return true
+    if (Array.isArray(node)) return node.length <= 64 && node.every(visit)
+    if (typeof node !== 'object') return false
+    return Object.entries(node).every(([key, child]) => !SECRET_KEY.test(key) && visit(child))
+  }
+  return visit(value)
+}
+
+function safeRef(ref) {
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref)) return null
+  if (!SAFE_REF.test(String(ref.type || '')) || !SAFE_REF.test(String(ref.id || ''))) return null
+  return { type: String(ref.type), id: String(ref.id) }
+}
+
+// The visible room receives only lane identity/status aggregates, never terminal
+// snippets or host worktree paths. This intentionally trades detail for privacy.
+export function projectRoomContext(roomNow) {
+  const lines = String(roomNow || '').split('\n')
+  const lanes = []
+  let worktrees = 0
+  for (const line of lines) {
+    const lane = line.match(/^\s*-\s*([A-Za-z0-9._:@-]{4,160})\s+·\s+"([^"\n]{1,160})"\s+·\s+[^·\n]+\s+·\s+([^·\n]+)/)
+    if (lane && isSafeContextValue(lane[2], 512) && isSafeContextValue(lane[3], 128)) {
+      lanes.push({ ref: lane[1], title: lane[2].trim(), state: lane[3].trim() })
+      continue
+    }
+    if (/^\s*-\s*\S+\s+[0-9a-f]{7,40}\s+\[/.test(line)) worktrees++
+  }
+  const projection = { lanes: lanes.slice(0, 32), worktreeCount: Math.min(worktrees, 999) }
+  return isSafeContextValue(projection, 4096) ? projection : { lanes: [], worktreeCount: 0 }
+}
+
+export function formatRoomContextProjection(roomNow) {
+  const projection = projectRoomContext(roomNow)
+  if (!projection.lanes.length && !projection.worktreeCount) return ''
+  const laneText = projection.lanes.map((lane) => `${lane.ref} · ${lane.title} · ${lane.state}`).join('\n')
+  return ['ROOM NOW (safe projection):', laneText, projection.worktreeCount ? `Active git worktrees: ${projection.worktreeCount}` : ''].filter(Boolean).join('\n')
+}
+
+export function buildContextManifest({ promptBundle = {}, sources = [] } = {}) {
+  const accepted = new Map()
+  for (const candidate of Array.isArray(sources) ? sources : []) {
+    const policy = BY_KIND.get(candidate?.kind)
+    if (!policy || accepted.has(policy.kind)) continue
+    const ref = candidate.ref == null ? null : safeRef(candidate.ref)
+    if (candidate.ref != null && !ref) continue
+    if (candidate.value != null && !isSafeContextValue(candidate.value, policy.maxBytes)) continue
+    accepted.set(policy.kind, ref ? { kind: policy.kind, ref, maxBytes: policy.maxBytes } : { kind: policy.kind, maxBytes: policy.maxBytes })
+  }
+  const manifest = {
+    version: CONTEXT_CONTRACT_VERSION,
+    promptBundle: { version: Number(promptBundle?.version) || 1, hash: /^[a-f0-9]{64}$/i.test(String(promptBundle?.hash || '')) ? String(promptBundle.hash).toLowerCase() : null },
+    sources: CONTEXT_SOURCE_POLICY.map((policy) => accepted.get(policy.kind)).filter(Boolean),
+    omissions: [...CONTEXT_OMISSIONS],
+  }
+  return Object.freeze({ ...manifest, hash: createHash('sha256').update(JSON.stringify(stable(manifest))).digest('hex') })
+}