thinkpool-pair 0.7.354 → 0.7.357

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-compact.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,50 @@
+// Strict, runtime-neutral EvidenceEnvelopeV1 parsing. Only an actual
+// project-context evidence tool result can create room evidence in S1.
+import { createHash } from 'node:crypto'
+import { EVIDENCE_CAP, compactEvidenceEnvelope } from './evidence-compact.mjs'
+
+export { EVIDENCE_CAP, compactEvidenceEnvelope }
+
+export const EVIDENCE_START = '<<<TP_EVIDENCE_V1>>>'
+export const EVIDENCE_END = '<<<END_TP_EVIDENCE_V1>>>'
+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 }

package/evidence-compact.mjs

@@ -0,0 +1,11 @@
+// Browser-safe evidence bounding shared by the bridge and replay client.
+// Parsing and digest verification stay in evidence-citations.mjs (Node-only).
+export const EVIDENCE_CAP = 8
+
+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,

package/lane-continuation.mjs

@@ -0,0 +1,83 @@
+// A continuation is a durable-safe control projection, never a provider
+// transcript or a command to start a new native turn.
+
+import { isSecretFreeRoomPayload, runtimeSupportsCapability } from './runtime-contract.mjs'
+
+const STATES = new Set(['waiting_for_human', 'resumable', 'canceled', 'terminal'])
+const RESUME_KINDS = new Set(['human_response', 'approval', 'redispatch', 'reconnect'])
+const EXECUTION = new Set(['Working', 'Done', 'Failed', 'Canceled'])
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/
+const dispatchers = new WeakSet()
+
+const canonical = (value) => {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]))
+  return value
+}
+const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b))
+const safeId = (value) => typeof value === 'string' && SAFE_ID.test(value)
+const denied = (code) => Object.freeze({ ok: false, code })
+const clone = (value) => {
+  const freeze = (node) => {
+    if (node && typeof node === 'object') {
+      for (const child of Object.values(node)) freeze(child)
+      Object.freeze(node)
+    }
+    return node
+  }
+  return freeze(canonical(value))
+}
+
+export function isSafeContinuationProjection (record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record) || record.version !== 1 || !safeId(record.id) || !safeId(record.laneRef) || !safeId(record.roomCode) || !safeId(record.authorityRef)) return false
+  if (!runtimeSupportsCapability(record.runtime, record.capabilityId) || !STATES.has(record.state) || record.verification !== 'unverified') return false
+  if (record.resumeKind != null && !RESUME_KINDS.has(record.resumeKind)) return false
+  if (record.resumeRef != null && (!record.resumeRef || typeof record.resumeRef !== 'object' || !safeId(record.resumeRef.type) || !safeId(record.resumeRef.id))) return false
+  if (!['canceled', 'terminal'].includes(record.state) && (!record.resumeKind || !record.resumeRef)) return false
+  if (!record.executionBoundary || !EXECUTION.has(record.executionBoundary.state) || !record.executionBoundary.eventRef || !isSecretFreeRoomPayload(record.executionBoundary.eventRef, 2048)) return false
+  if (record.expiresAt != null && (!Number.isSafeInteger(record.expiresAt) || record.expiresAt <= 0)) return false
+  return isSecretFreeRoomPayload(record, 8192)
+}
+
+export function createContinuationDispatcher ({ roomCode, authorityRef, now = () => Date.now() } = {}) {
+  if (!safeId(roomCode) || !safeId(authorityRef) || typeof now !== 'function') throw new TypeError('Invalid continuation dispatcher authority')
+  const records = new Map()
+  const dispatcher = {
+    create (record) {
+      const next = { ...record, version: 1, roomCode, authorityRef, verification: 'unverified' }
+      if (!isSafeContinuationProjection(next)) return denied('invalid_continuation')
+      const prior = records.get(next.id)
+      if (prior) return same(prior, next) ? Object.freeze({ ok: true, code: 'idempotent', record: prior }) : denied('continuation_conflict')
+      const frozen = clone(next)
+      records.set(frozen.id, frozen)
+      return Object.freeze({ ok: true, code: 'created', record: frozen })
+    },
+    consume ({ id, roomCode: consumeRoom, authorityRef: consumeAuthority, control } = {}) {
+      const record = records.get(id)
+      if (!record) return denied('unknown_continuation')
+      if (consumeRoom !== roomCode || consumeAuthority !== authorityRef) return denied('continuation_authority_mismatch')
+      if (record.state === 'canceled') return denied('continuation_canceled')
+      if (record.state === 'terminal') return denied('continuation_terminal')
+      if (record.expiresAt != null && now() > record.expiresAt) return denied('continuation_stale')
+      if (!control || control.authorized !== true || control.roomCode !== roomCode || control.authorityRef !== authorityRef || !same(control.resumeRef, record.resumeRef)) return denied('continuation_control_unverified')
+      // The adapter must explicitly act on this intent. Returning it is not an
+      // auto-resume and cannot fabricate an execution or verification result.
+      return Object.freeze({ ok: true, code: 'resume_intent', record, resumeIntent: Object.freeze({ runtime: record.runtime, laneRef: record.laneRef, resumeKind: record.resumeKind, resumeRef: record.resumeRef }) })
+    },
+    cancel ({ id, roomCode: cancelRoom, authorityRef: cancelAuthority, reason = 'interrupt' } = {}) {
+      const record = records.get(id)
+      if (!record) return denied('unknown_continuation')
+      if (cancelRoom !== roomCode || cancelAuthority !== authorityRef) return denied('continuation_authority_mismatch')
+      if (record.state === 'canceled') return Object.freeze({ ok: true, code: 'idempotent_cancel', record })
+      // Do not preserve an arbitrary reason string: it might be provider prose.
+      // The canceled execution boundary is the safe observable fact.
+      const canceled = clone({ ...record, state: 'canceled', resumeKind: null, resumeRef: null, executionBoundary: { ...record.executionBoundary, state: 'Canceled' }, verification: 'unverified' })
+      records.set(id, canceled)
+      return Object.freeze({ ok: true, code: 'canceled', record: canceled })
+    },
+  }
+  dispatchers.add(dispatcher)
+  return Object.freeze(dispatcher)
+}
+
+export const isBridgeContinuationDispatcher = (value) => dispatchers.has(value)

package/lane-lifecycle.mjs

@@ -1,4 +1,5 @@
 import { classifyCodeEvent } from './code-event-contract.mjs'
+import { isSafeContinuationProjection } from './lane-continuation.mjs'
 
 // This file ships in the standalone thinkpool-pair tarball. Keep the canonical
 // vocabulary here rather than importing from ../src (which is not packaged).
@@ -84,7 +85,7 @@ const base = (state, reason = null, extra = {}) => ({ state, reason, phase: null
 export function projectLaneLifecycle ({
   events = [], busy = false, pendingCount = 0, pendingReason = null,
   stalled = false, offline = false, stale = false, failed = false, canceled = false,
-  rawStatus = null,
+  rawStatus = null, continuation = null,
 } = {}) {
   let out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.NEEDS_INPUT, { rawStatus })
   const replay = normalizeReplayEvents(events)
@@ -120,6 +121,11 @@ export function projectLaneLifecycle ({
   else if (failed) out = base(LIFECYCLE_STATE.FAILED, null, { rawStatus })
   else if (canceled) out = base(LIFECYCLE_STATE.CANCELED, null, { rawStatus })
   else if (pendingCount > 0) out = base(LIFECYCLE_STATE.BLOCKED, pendingReason || BLOCKED_REASON.NEEDS_DECISION, { rawStatus })
+  // This is explanation only. A continuation cannot certify verification or
+  // resurrect an interrupted/canceled execution boundary.
+  else if (isSafeContinuationProjection(continuation) && !TERMINAL.has(out.state) && continuation.state !== 'terminal') {
+    out = base(LIFECYCLE_STATE.BLOCKED, continuation.state === 'waiting_for_human' ? BLOCKED_REASON.NEEDS_INPUT : BLOCKED_REASON.NEEDS_DECISION, { rawStatus, phase: 'continuation' })
+  }
   else if (stalled) out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.STALLED, { rawStatus, phase: 'stalled' })
   else if (busy && !TERMINAL.has(out.state)) out = base(LIFECYCLE_STATE.WORKING, null, { rawStatus, phase: out.phase || 'active' })
   else if (offline && !TERMINAL.has(out.state)) out = base(LIFECYCLE_STATE.BLOCKED, BLOCKED_REASON.OFFLINE, { rawStatus })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.354",
+  "version": "0.7.357",
   "description": "Connect Claude Code, Codex, or Hermes on your computer to a Thinkpool Code room.",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "privacy-report.mjs",
     "agent-visibility.mjs",
     "byok-detect.mjs",
+    "context-contract.mjs",
     "context-windows.mjs",
     "claude-session.mjs",
     "terminal-name.mjs",
@@ -48,6 +49,7 @@
     "hermes-isolation.mjs",
     "hermes-delegation-guard.mjs",
     "runtime-registry.mjs",
+    "runtime-contract.mjs",
     "command-catalog.mjs",
     "repo-search.mjs",
     "git-diff-report.mjs",
@@ -57,6 +59,9 @@
     "agent-notify.mjs",
     "agent-detect.mjs",
     "code-event-contract.mjs",
+    "evidence-compact.mjs",
+    "evidence-citations.mjs",
+    "error-recovery.mjs",
     "pair-control-authority.mjs",
     "event-id.mjs",
     "event-bounds.mjs",
@@ -71,6 +76,7 @@
     "pair-bus.mjs",
     "direct-pair-room.mjs",
     "lane-lifecycle.mjs",
+    "lane-continuation.mjs",
     "interrupted-resume.mjs",
     "dispatch-lease.mjs",
     "dispatch-permission-cleanup.mjs",
@@ -83,6 +89,7 @@
     "mockup-delivery.mjs",
     "viewport.mjs",
     "design-edit.mjs",
+    "design-source-contract.mjs",
     "flow-review.mjs",
     "review-check.mjs",
     "flow-review-gate.mjs",
@@ -106,6 +113,7 @@
     "supabase-key.mjs",
     "provider.mjs",
     "providers.mjs",
+    "provider-resilience.mjs",
     "model-prices.mjs",
     "README.md"
   ],