thinkpool-pair 0.7.354 → 0.7.356

package/bridge.mjs

@@ -55,6 +55,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'
@@ -2263,6 +2264,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 /

package/claude-session.mjs

@@ -22,6 +22,7 @@ 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'
 
@@ -244,7 +245,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 }) {
   // 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
@@ -297,7 +298,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 +349,9 @@ 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 */ } }
   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
@@ -428,7 +432,7 @@ 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') { observeRecovery('stall_replay', { quietMs: quiet }); forceStopped = true; 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
@@ -949,7 +953,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
           case 'assistant':
             // 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
@@ -964,7 +968,8 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
               if (b?.type === 'tool_result') {
                 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
@@ -1092,6 +1097,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

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') })
+}

package/design-edit.mjs

@@ -2,13 +2,24 @@ import crypto from 'node:crypto'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import {
+  DESIGN_SOURCE_MAP_RELATIVE,
+  DESIGN_SOURCE_MAP_VERSION,
+  MAX_DESIGN_SOURCE_ENTRIES,
+  MAX_DESIGN_SOURCE_MAP_BYTES,
+} from './design-source-contract.mjs'
 
 const MAX_SOURCE_BYTES = 2 * 1024 * 1024
 const MAX_INTENT = 2_000
 const MAX_TEXT = 4_000
 const MAX_BATCH_EDITS = 8
+const GENERATED_SOURCE_PARTS = new Set(['dist', 'build', '.next', '.git', 'coverage', 'node_modules'])
 
 const clean = (value, max) => String(value ?? '').replace(/\0/g, '').trim().slice(0, max)
+const isInside = (parent, child) => {
+  const rel = path.relative(parent, child)
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
 
 // supabase-js does not copy the Auth session into an already-created Realtime
 // client. Private tpdesign:* joins therefore need the bridge owner's JWT pinned
@@ -28,6 +39,52 @@ export function sourceRevision(source) {
   return crypto.createHash('sha256').update(String(source)).digest('hex').slice(0, 24)
 }
 
+export function resolveDesignSourceMap(file, previewRoot, workspaceRoot) {
+  if (!file || !previewRoot || !workspaceRoot) return null
+  let sourceMapPath, expectedSourceMapPath, builtRoot, root, raw, parsed
+  try {
+    sourceMapPath = fs.realpathSync(file)
+    builtRoot = fs.realpathSync(previewRoot)
+    expectedSourceMapPath = fs.realpathSync(path.join(builtRoot, DESIGN_SOURCE_MAP_RELATIVE))
+    root = fs.realpathSync(workspaceRoot)
+    const stat = fs.statSync(sourceMapPath)
+    if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_DESIGN_SOURCE_MAP_BYTES) return null
+    if (sourceMapPath !== expectedSourceMapPath || !isInside(root, builtRoot) || !isInside(builtRoot, sourceMapPath)) return null
+    raw = fs.readFileSync(sourceMapPath, 'utf8')
+    parsed = JSON.parse(raw)
+  } catch { return null }
+  if (parsed?.version !== DESIGN_SOURCE_MAP_VERSION || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) return null
+  const rows = Object.entries(parsed.entries)
+  if (rows.length > MAX_DESIGN_SOURCE_ENTRIES) return null
+
+  const files = new Map()
+  const entries = new Map()
+  for (const [sourceId, value] of rows) {
+    if (!/^[A-Za-z0-9_-]{8,80}$/.test(sourceId) || !value || typeof value !== 'object') return null
+    const relative = clean(value.file, 700)
+    if (!relative || path.isAbsolute(relative) || relative.split(/[\\/]/).some((part) => part === '..' || GENERATED_SOURCE_PARTS.has(part))) return null
+    let sourcePath = files.get(relative)
+    if (!sourcePath) {
+      try {
+        sourcePath = fs.realpathSync(path.resolve(root, relative))
+        const stat = fs.statSync(sourcePath)
+        if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES || !isInside(root, sourcePath)) return null
+      } catch { return null }
+      files.set(relative, sourcePath)
+    }
+    const start = Number(value.start)
+    const end = Number(value.end)
+    const line = Number(value.line)
+    const column = Number(value.column)
+    const tag = clean(value.tag, 40).toLowerCase()
+    const fileHash = clean(value.fileHash, 64).toLowerCase()
+    if (![start, end, line, column].every(Number.isSafeInteger) || start < 0 || end <= start || line < 1 || column < 0) return null
+    if (!/^[a-z][a-z0-9:-]*$/.test(tag) || !/^[a-f0-9]{24}$/.test(fileHash)) return null
+    entries.set(sourceId, { sourceId, file: relative.split(path.sep).join('/'), sourcePath, start, end, line, column, tag, fileHash })
+  }
+  return { path: sourceMapPath, revision: sourceRevision(raw), buildId: clean(parsed.buildId, 80), entries }
+}
+
 export function resolveDesignSource(file, workspaceRoot) {
   if (!file || !workspaceRoot) return null
   let sourcePath, root
@@ -67,11 +124,21 @@ export function resolvePreviewDesignSource(manifest, workspaceRoot, box) {
   const captureKey = clean(manifest.captureKey, 1000)
   if (!route.startsWith('/') || !captureKey || captureKey !== JSON.stringify([previewRoot, route])) return null
   const source = fs.readFileSync(sourcePath, 'utf8')
-  const revision = sourceRevision(source)
+  let builtRoot = null
+  try {
+    builtRoot = fs.realpathSync(path.resolve(root, previewRoot))
+    if (!isInside(root, builtRoot)) return null
+  } catch { return null }
+  const sourceMap = manifest.sourceMap ? resolveDesignSourceMap(manifest.sourceMap, builtRoot, root) : null
+  const revision = sourceRevision(sourceMap ? `${source}\0${sourceMap.revision}` : source)
   const previewId = crypto.createHash('sha256')
     .update(`${root}\0${captureKey}\0${revision}`)
     .digest('base64url').slice(0, 32)
-  return { sourceKind: 'preview', previewId, revision, sourcePath, workspaceRoot: root, source, outbox, route, previewRoot, captureKey }
+  return {
+    sourceKind: 'preview', previewId, revision, sourcePath, workspaceRoot: root, source, outbox,
+    route, previewRoot, captureKey, sourceMap, sourceMapPath: sourceMap?.path || null,
+    sourceMapDeclared: !!manifest.sourceMap,
+  }
 }
 
 // Older lane worktrees predate the explicit `source` manifest field and emit the
@@ -108,7 +175,7 @@ export function refreshDesignSource(record) {
   if (record.sourceKind !== 'preview') return resolveDesignSource(record.sourcePath, record.workspaceRoot)
   return resolvePreviewDesignSource({
     sourceKind: 'preview', snapshot: record.sourcePath, route: record.route,
-    previewRoot: record.previewRoot, captureKey: record.captureKey,
+    previewRoot: record.previewRoot, captureKey: record.captureKey, sourceMap: record.sourceMapPath,
   }, record.workspaceRoot, record.outbox)
 }
 
@@ -168,10 +235,35 @@ function safeTarget(value) {
     canReplaceImage: value.canReplaceImage === true,
     nodeKey: clean(value.nodeKey, 80),
     parentNodeKey: clean(value.parentNodeKey, 80),
+    sourceId: clean(value.sourceId, 80),
+    parentSourceId: clean(value.parentSourceId, 80),
     rect,
   }
 }
 
+export function resolveRequestSourceIdentity(record, target) {
+  if (!target?.sourceId) return { ok: true, identity: null }
+  const entry = record?.sourceMap?.entries?.get(target.sourceId)
+  if (!entry) return { ok: false, error: record?.sourceMapDeclared ? 'stale-source-identity' : 'source-identity-unavailable' }
+  if (target.tag && entry.tag !== target.tag) return { ok: false, error: 'source-identity-mismatch' }
+  let source
+  try { source = fs.readFileSync(entry.sourcePath, 'utf8') } catch { return { ok: false, error: 'stale-source-identity' } }
+  if (sourceRevision(source) !== entry.fileHash) return { ok: false, error: 'stale-source-identity' }
+  return {
+    ok: true,
+    identity: {
+      sourceId: entry.sourceId,
+      file: entry.file,
+      start: entry.start,
+      end: entry.end,
+      line: entry.line,
+      column: entry.column,
+      tag: entry.tag,
+      fileHash: entry.fileHash,
+    },
+  }
+}
+
 function safeMovement(value) {
   if (!value || typeof value !== 'object') return null
   const fromIndex = Number(value.fromIndex)
@@ -211,7 +303,16 @@ export function validateDesignRequest(payload, registry, room = '') {
   if (mode === 'move' && (!movement || movement.fromIndex === movement.toIndex)) return { ok: false, error: 'invalid-move' }
   const asset = mode === 'image' ? safeAsset(payload.asset, room) : null
   if (mode === 'image' && (!target.canReplaceImage || !asset)) return { ok: false, error: 'invalid-image' }
-  return { ok: true, record, request: { previewId, revision: record.revision, mode, intent, target, movement, asset, cid: clean(payload.cid, 80) } }
+  const source = resolveRequestSourceIdentity(record, target)
+  if (!source.ok) return source
+  return {
+    ok: true,
+    record,
+    request: {
+      previewId, revision: record.revision, mode, intent, target, movement, asset,
+      sourceIdentity: source.identity, cid: clean(payload.cid, 80),
+    },
+  }
 }
 
 export function validateDesignBatchRequest(payload, registry, room = '') {
@@ -226,7 +327,7 @@ export function validateDesignBatchRequest(payload, registry, room = '') {
   for (let index = 0; index < payload.edits.length; index++) {
     const verdict = validateDesignRequest({ ...payload.edits[index], previewId, revision, cid }, registry, room)
     if (!verdict.ok) return { ...verdict, editIndex: index }
-    const targetKey = verdict.request.target.nodeKey || verdict.request.target.selector || verdict.request.target.xpath
+    const targetKey = verdict.request.target.sourceId || verdict.request.target.nodeKey || verdict.request.target.selector || verdict.request.target.xpath
     if (targets.has(targetKey)) return { ok: false, error: 'duplicate-target', editIndex: index }
     targets.add(targetKey)
     record = verdict.record
@@ -276,6 +377,13 @@ function designAction(request) {
   return `Apply this visual change to only the selected element unless the instruction explicitly requires its immediate context:\n${request.intent}`
 }
 
+function selectedElementBlock(request) {
+  const identity = request.sourceIdentity
+    ? `\n\nBridge-verified application source:\n${JSON.stringify(request.sourceIdentity, null, 2)}`
+    : '\n\nApplication source identity: unavailable — selector/XPath fallback only.'
+  return `Selected element:\n${JSON.stringify(request.target, null, 2)}${identity}`
+}
+
 const designModeLabel = (mode) => ({ text: 'Text', prompt: 'Prompt', move: 'Move', image: 'Image' })[mode] || 'Edit'
 
 function visibleDesignAction(request) {
@@ -307,10 +415,10 @@ export function designPrompt({ record, request, by, restore = false, priorRecord
   const work = restore
     ? `Restore only the immediately previous Design Mode change by comparing the current artifact with this bridge-created verified backup: ${priorRecord?.backupPath || '(backup unavailable)'}. Do not overwrite unrelated changes.`
     : batch
-      ? batch.map((edit, index) => `Edit ${index + 1} of ${batch.length} · ${edit.mode}\nSelected element:\n${JSON.stringify(edit.target, null, 2)}\n\n${designAction(edit)}`).join('\n\n---\n\n')
-      : `Selected element:\n${JSON.stringify(request.target, null, 2)}\n\n${designAction(request)}`
+      ? batch.map((edit, index) => `Edit ${index + 1} of ${batch.length} · ${edit.mode}\n${selectedElementBlock(edit)}\n\n${designAction(edit)}`).join('\n\n---\n\n')
+      : `${selectedElementBlock(request)}\n\n${designAction(request)}`
   if (record.sourceKind === 'preview') {
-    return `A room member used ThinkPool Design Mode on a rendered application preview. This is an authorized source edit in your current workspace.\n\nRendered snapshot (read-only evidence): ${record.sourcePath}\nApplication workspace: ${record.workspaceRoot}\nPreview root: ${record.previewRoot}\nPreview route: ${record.route}\nExpected snapshot revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the rendered snapshot and confirm the selected element still matches before editing.\n- Do not edit the snapshot. Locate the represented element in the application source inside the workspace and make the smallest source change that produces the requested result.\n- If the selector, text, or surrounding structure does not identify one application source location unambiguously, stop without editing and explain that the person must reselect it.\n${batch ? '- Apply the queued edits in order in one source pass, then build and capture once after the full batch.' : '- Apply only the requested change, then build and capture once.'}\n- Preserve the product page faithfully: keep its real copy, structure, fonts, assets, spacing, responsive behavior, and unrelated source unchanged.\n- Run the project build, then use preview_start with root ${record.previewRoot} and preview_capture with path ${record.route}, both viewports, and title ${JSON.stringify(record.title || record.slug || 'Design preview')}. The bridge correlates that capture to this request.\n- Do not claim the edit is verified until the room receives the new desktop and mobile capture.\n- If the build or capture fails, report the failure instead of substituting a screenshot-only result.`
+    return `A room member used ThinkPool Design Mode on a rendered application preview. This is an authorized source edit in your current workspace.\n\nRendered snapshot (read-only evidence): ${record.sourcePath}\nApplication workspace: ${record.workspaceRoot}\nPreview root: ${record.previewRoot}\nPreview route: ${record.route}\nExpected snapshot revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the rendered snapshot and confirm the selected element still matches before editing.\n- Do not edit the snapshot. For an edit with bridge-verified application source, start at that exact relative file and range. For a selector/XPath fallback, locate the represented element in application source and do not call the match exact.\n- Before editing a bridge-verified target, confirm the current source still hashes to the supplied fileHash. If it does not, stop and request a fresh capture/reselection.\n- If fallback selector, text, or surrounding structure does not identify one application source location unambiguously, stop without editing and explain that the person must reselect it.\n${batch ? '- Apply the queued edits in order in one source pass, then build and capture once after the full batch.' : '- Apply only the requested change, then build and capture once.'}\n- Preserve the product page faithfully: keep its real copy, structure, fonts, assets, spacing, responsive behavior, and unrelated source unchanged.\n- Run the project build, then use preview_start with root ${record.previewRoot} and preview_capture with path ${record.route}, both viewports, and title ${JSON.stringify(record.title || record.slug || 'Design preview')}. The bridge correlates that capture to this request.\n- Do not claim the edit is verified until the room receives the new desktop and mobile capture.\n- If the build or capture fails, report the failure instead of substituting a screenshot-only result.`
   }
   return `A room member used ThinkPool Design Mode on the artifact below. This is an authorized source edit in your current workspace.\n\nArtifact source: ${record.sourcePath}\nWorkspace: ${record.workspaceRoot}\nExpected source revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${restore ? 'restore the immediately previous verified Design Mode revision' : batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the exact artifact source and confirm its revision/content still matches every selected element before editing.\n${batch ? '- Apply the queued edits in order in one source pass, then render once after the full batch.' : '- Apply only the requested change, then render the result once.'}\n- Edit the canonical source above; do not search for or edit a different plausible file.\n- Preserve the represented product page faithfully: keep its real copy, structure, fonts, assets, spacing, and responsive behavior except for the selected edits. Never replace it with generic mockup content.\n- Preserve unrelated content and styling.\n- Use the existing mockup render workflow to produce both desktop and mobile captures after the edit. Run it with TP_DESIGN_REQUEST_ID=${request.cid} and TP_DESIGN_PARENT_REVISION=${record.revision} in the command environment so the proof correlates to this request.\n- Do not claim this is live until both captures succeed and the room receives the manifest.\n- If any target is stale or ambiguous, stop without editing and explain that the person must reselect it.`
 }

package/design-source-contract.mjs

@@ -0,0 +1,4 @@
+export const DESIGN_SOURCE_MAP_VERSION = 1
+export const DESIGN_SOURCE_MAP_RELATIVE = '.thinkpool-design/source-map.json'
+export const MAX_DESIGN_SOURCE_MAP_BYTES = 2 * 1024 * 1024
+export const MAX_DESIGN_SOURCE_ENTRIES = 50_000

package/error-recovery.mjs

@@ -0,0 +1,50 @@
+// A safe recovery envelope. It records a bounded decision; it never performs a
+// retry and therefore cannot alter native adapter transport behavior.
+
+import { isSecretFreeRoomPayload, runtimeSupportsCapability } from './runtime-contract.mjs'
+
+export const ERROR_RECOVERY_VERSION = 1
+export const MAX_RECOVERY_ATTEMPTS = 3
+const CODE = /^[a-z][a-z0-9_-]{0,79}$/
+const SAFE_REF = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/
+
+const policyFor = ({ runtime, capabilityId }) => runtimeSupportsCapability(runtime, capabilityId)
+  ? Object.freeze({ maxAttempts: MAX_RECOVERY_ATTEMPTS })
+  : Object.freeze({ maxAttempts: 1 })
+
+export function normalizeErrorRecovery({ runtime, capabilityId, code = 'runtime_error', retryable = false, attempt = 1, evidenceRefs = [] } = {}) {
+  const policy = policyFor({ runtime, capabilityId })
+  const safeAttempt = Math.max(1, Math.min(policy.maxAttempts, Number.isSafeInteger(attempt) ? attempt : 1))
+  const safeRefs = (Array.isArray(evidenceRefs) ? evidenceRefs : []).slice(0, 16)
+    .filter((ref) => ref && SAFE_REF.test(String(ref.type || '')) && SAFE_REF.test(String(ref.id || '')))
+    .map((ref) => ({ type: String(ref.type), id: String(ref.id) }))
+  const admitted = runtimeSupportsCapability(runtime, capabilityId) && CODE.test(String(code))
+  const canRetry = admitted && retryable === true && safeAttempt < policy.maxAttempts
+  const envelope = {
+    version: ERROR_RECOVERY_VERSION,
+    capabilityId: admitted ? capabilityId : 'unknown',
+    code: admitted ? String(code) : 'invalid_recovery_input',
+    retryable: canRetry,
+    attempt: safeAttempt,
+    maxAttempts: policy.maxAttempts,
+    next: canRetry ? 'retry' : (admitted && retryable === true ? 'ask_human' : 'stop'),
+    evidenceRefs: safeRefs,
+  }
+  return Object.freeze(isSecretFreeRoomPayload(envelope, 4096) ? envelope : {
+    version: ERROR_RECOVERY_VERSION, capabilityId: 'unknown', code: 'invalid_recovery_input', retryable: false,
+    attempt: 1, maxAttempts: 1, next: 'stop', evidenceRefs: [],
+  })
+}
+
+export function recoveryCodeEvent(input) {
+  const recovery = normalizeErrorRecovery(input)
+  return Object.freeze({
+    kind: recovery.next === 'ask_human' ? 'needs-input' : 'error',
+    subtype: 'bounded_recovery',
+    message: recovery.next === 'ask_human'
+      ? `Recovery attempt ${recovery.attempt}/${recovery.maxAttempts} is exhausted; human input is required.`
+      : `Recovery stopped safely (${recovery.code}).`,
+    recovery,
+    verified: false,
+  })
+}

package/event-bounds.mjs

@@ -1,3 +1,5 @@
+import { compactEvidenceEnvelope } from './evidence-citations.mjs'
+
 /* Browser-safe structured-event bounding shared by the bridge broadcast path and
    the web client's persisted reload snapshot. Large Codex/Claude tool payloads
    must remain recognisable (tool name + a useful preview), but must never turn a
@@ -66,6 +68,7 @@ export function boundStructuredEvent(event, cap = STRUCTURED_EVENT_CAP) {
   if (!event || typeof event !== 'object' || sizeOf(event) <= cap) return event
 
   const out = { ...event, _bounded: true }
+  if (out.evidence) out.evidence = compactEvidenceEnvelope(out.evidence, 0)
   const stringBudget = Math.min(12000, Math.max(1000, Math.floor(cap / 4)))
   for (const key of ['text', 'output', 'stdout', 'stderr', 'input']) {
     if (typeof out[key] === 'string') out[key] = clipString(out[key], stringBudget)
@@ -89,6 +92,7 @@ export function boundStructuredEvent(event, cap = STRUCTURED_EVENT_CAP) {
   for (const key of ['kind', 'seq', 'cid', 'ts', 'term', 'toolUseId', 'isError', 'by', 'crosspost', 'relaySourceName']) {
     if (out[key] != null) identity[key] = out[key]
   }
+  if (out.evidence) identity.evidence = compactEvidenceEnvelope(out.evidence, 0)
   if (Array.isArray(out.blocks)) identity.blocks = out.blocks.slice(0, 4).map(block => compactBlock(block, 6000))
   else if (Array.isArray(out.content)) identity.content = out.content.slice(0, 4).map(block => compactBlock(block, 6000))
   else if (typeof out.content === 'string') identity.content = clipString(out.content, 12000)

package/evidence-citations.mjs

@@ -0,0 +1,56 @@
+// Strict, runtime-neutral EvidenceEnvelopeV1 parsing. Only an actual
+// project-context evidence tool result can create room evidence in S1.
+import { createHash } from 'node:crypto'
+
+export const EVIDENCE_START = '<<<TP_EVIDENCE_V1>>>'
+export const EVIDENCE_END = '<<<END_TP_EVIDENCE_V1>>>'
+export const EVIDENCE_CAP = 8
+const LEVELS = new Set(['exact', 'section', 'source', 'unavailable'])
+const WARNINGS = new Set(['NO_MATCH', 'LOW_LEXICAL_MATCH', 'UNCALIBRATED_RELEVANCE', 'SECTION_ONLY', 'SOURCE_ONLY', 'SOURCE_UNAVAILABLE', 'SPAN_ANCHOR_MISMATCH', 'TRANSCRIPT_BOUNDED'])
+const safeText = (value, max) => typeof value === 'string' && value.length <= max && !/(?:https?:\/\/|file:|bearer\s|token=|signature=|x-amz-|\.\.[\\/]|^\/|[A-Za-z]:[\\/])/i.test(value)
+const isProjectEvidenceTool = (name) => ['mcp__project_context__search_context_evidence', 'mcp__project-context__search_context_evidence'].includes(String(name || ''))
+const textContent = (content) => typeof content === 'string' ? content : Array.isArray(content) ? content.map((part) => typeof part === 'string' ? part : part?.text || '').join('\n') : ''
+const excerptDigest = (value) => createHash('sha256').update(value, 'utf8').digest('hex')
+
+function validCitation(raw) {
+  if (!raw || raw.v !== 1 || !/^ev1_[a-f0-9]{24,64}$/.test(raw.id || '')) return null
+  const source = raw.source || {}, locator = raw.locator || {}, revision = source.revision || {}, assessment = raw.assessment || {}, provenance = raw.provenance || {}
+  if (source.kind !== 'project_prose' || source.collection !== 'repo' || !safeText(source.label, 180) || !safeText(source.path, 500) || !/^[a-f0-9]{40,64}$/i.test(revision.value || '') || !['git', 'content_sha256'].includes(revision.kind)) return null
+  if (!LEVELS.has(locator.level) || !safeText(locator.heading || '', 180)) return null
+  if (!['high', 'medium', 'low', 'unscored'].includes(assessment.relevance) || !['direct', 'partial', 'source_only', 'unavailable'].includes(assessment.confidence) || !Array.isArray(assessment.warnings) || assessment.warnings.some((warning) => !WARNINGS.has(warning))) return null
+  if (provenance.capturedBy !== 'project-context' || provenance.method !== 'fts5_heading') return null
+  const citation = { v: 1, id: raw.id, source: { kind: source.kind, collection: source.collection, label: source.label, path: source.path, revision: { kind: revision.kind, value: revision.value, ...(safeText(revision.indexedAt || '', 80) ? { indexedAt: revision.indexedAt } : {}) } }, locator: { level: locator.level, ...(safeText(locator.heading || '', 180) ? { heading: locator.heading } : {}) }, provenance: { capturedBy: provenance.capturedBy, method: provenance.method, ...(safeText(provenance.retrievedAt || '', 80) ? { retrievedAt: provenance.retrievedAt } : {}), ...(safeText(provenance.query || '', 160) ? { query: provenance.query } : {}), ...(Number.isSafeInteger(provenance.rank) && provenance.rank > 0 ? { rank: provenance.rank } : {}) }, assessment: { relevance: assessment.relevance, confidence: assessment.confidence, warnings: [...new Set(assessment.warnings)].slice(0, 8) } }
+  if (locator.level === 'exact') {
+    if (![locator.charStart, locator.charEnd, locator.lineStart, locator.lineEnd].every(Number.isSafeInteger) || locator.charStart < 0 || locator.charEnd <= locator.charStart || locator.lineStart < 1 || locator.lineEnd < locator.lineStart || !safeText(locator.anchorBefore || '', 96) || !safeText(locator.anchorAfter || '', 96) || !safeText(raw.excerpt || '', 600) || !/^[a-f0-9]{64}$/i.test(raw.excerptSha256 || '') || excerptDigest(raw.excerpt) !== raw.excerptSha256) return null
+    citation.locator = { ...citation.locator, charStart: locator.charStart, charEnd: locator.charEnd, lineStart: locator.lineStart, lineEnd: locator.lineEnd, anchorBefore: locator.anchorBefore, anchorAfter: locator.anchorAfter }
+    citation.excerpt = raw.excerpt
+    citation.excerptSha256 = raw.excerptSha256
+  }
+  return citation
+}
+
+export function parseEvidenceEnvelope(toolName, content) {
+  if (!isProjectEvidenceTool(toolName)) return null
+  const text = textContent(content)
+  const start = text.indexOf(EVIDENCE_START), end = text.indexOf(EVIDENCE_END)
+  if (start < 0 || end < start || text.indexOf(EVIDENCE_START, start + EVIDENCE_START.length) >= 0 || text.indexOf(EVIDENCE_END, end + EVIDENCE_END.length) >= 0) return null
+  let raw
+  try { raw = JSON.parse(text.slice(start + EVIDENCE_START.length, end)) } catch { return null }
+  if (!raw || raw.v !== 1 || !Array.isArray(raw.citations) || raw.citations.length > EVIDENCE_CAP) return null
+  const citations = raw.citations.map(validCitation)
+  if (citations.some((citation) => !citation)) return null
+  const codes = Array.isArray(raw.summary?.warningCodes) ? raw.summary.warningCodes.filter((code) => WARNINGS.has(code)).slice(0, 8) : []
+  const status = ['evidence_found', 'weak_evidence', 'no_evidence'].includes(raw.summary?.status) ? raw.summary.status : null
+  if (!status || !Array.isArray(raw.summary?.searchedCollections) || raw.summary.searchedCollections.some((collection) => collection !== 'repo')) return null
+  return { v: 1, citations, summary: { searchedCollections: ['repo'], directCount: citations.filter((citation) => ['exact', 'section'].includes(citation.locator.level)).length, warningCodes: [...new Set(codes)], status } }
+}
+
+export function evidenceForToolResult(toolName, content) { return parseEvidenceEnvelope(toolName, content) || undefined }
+
+export function compactEvidenceEnvelope(envelope, maxExcerpt = 600) {
+  if (!envelope?.citations?.length) return envelope
+  return { ...envelope, citations: envelope.citations.slice(0, EVIDENCE_CAP).map((citation) => {
+    if (typeof citation.excerpt !== 'string' || citation.excerpt.length <= maxExcerpt) return citation
+    return { ...citation, excerpt: undefined, excerptSha256: undefined, locator: { ...citation.locator, level: 'unavailable' }, assessment: { ...citation.assessment, confidence: 'unavailable', warnings: [...new Set([...citation.assessment.warnings, 'TRANSCRIPT_BOUNDED', 'SOURCE_UNAVAILABLE'])].slice(0, 8) } }
+  }) }
+}

package/flow-preview.mjs

@@ -82,6 +82,10 @@ function makeHandler (dir) {
   return async (req, res) => {
     const resolved = resolveUnderRoot(dir, req.url || '/')
     if (resolved === null) return send(res, 403, 'text/plain; charset=utf-8', 'Forbidden')
+    const relative = path.relative(dir, resolved)
+    if (relative.split(path.sep)[0] === '.thinkpool-design') {
+      return send(res, 404, 'text/plain; charset=utf-8', 'Not found')
+    }
 
     // A concrete file hit (and still a real file, not a dir) → serve it.
     if (await isFile(resolved)) {

package/hermes-event-mapper.mjs

@@ -1,3 +1,5 @@
+import { evidenceForToolResult } from './evidence-citations.mjs'
+
 const textOf = (content) => {
   if (typeof content === 'string') return content
   if (content?.type === 'text') return String(content.text || '')
@@ -31,6 +33,9 @@ export function hermesToolFor(update = {}) {
   const kind = String(update.kind || '').toLowerCase()
   const title = String(update.title || '')
   const raw = update.rawInput && typeof update.rawInput === 'object' ? update.rawInput : {}
+  const server = String(update.server || raw.server || '')
+  const tool = String(update.tool || raw.tool || raw.name || '')
+  if (server === 'project-context' && tool === 'search_context_evidence') return { name: 'mcp__project-context__search_context_evidence', input: raw }
   const terminal = (update.content || []).find((part) => part?.type === 'terminal')
   const shellText = (update.content || []).map(textOf).find((text) => text.trim().startsWith('$ '))
   const location = update.locations?.[0]?.path
@@ -94,9 +99,11 @@ export class HermesEventMapper {
         this.tools.set(update.toolCallId, merged)
         if (!['completed', 'failed'].includes(update.status)) return
         const completedTool = hermesToolFor(merged)
+        const content = [{ type: 'text', text: outputText(merged) }]
+        const evidence = evidenceForToolResult(completedTool.name, content)
         this._emit({
           kind: 'tool_result', toolUseId: update.toolCallId,
-          content: [{ type: 'text', text: outputText(merged) }],
+          content, ...(evidence ? { evidence } : {}),
           toolInput: { ...(prior.input || {}), ...(completedTool.input || {}) },
           isError: update.status === 'failed',
           durationMs: prior.startedAt ? Date.now() - prior.startedAt : undefined,