thinkpool-pair 0.7.353 → 0.7.356

package/repo-search.mjs

@@ -0,0 +1,190 @@
+import { execFileSync } from 'node:child_process'
+
+const MAX_QUERY_CHARS = 160
+const DEFAULT_MAX_RESULTS = 8
+const MAX_FILES_BUFFER = 16 * 1024 * 1024
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'every', 'file', 'files', 'find', 'for', 'from', 'in',
+  'inside', 'is', 'locate', 'me', 'of', 'please', 'show', 'the', 'to', 'under',
+  'where', 'with',
+])
+
+const EXPANSIONS = Object.freeze({
+  api: ['endpoint', 'route', 'server'],
+  auth: ['login', 'session', 'oauth'],
+  component: ['card', 'panel', 'view', 'widget'],
+  config: ['configuration', 'settings'],
+  database: ['db', 'sql', 'schema'],
+  image: ['asset', 'gallery', 'media', 'photo', 'picture', 'thumbnail'],
+  library: ['catalog', 'collection', 'index', 'lib'],
+  login: ['auth', 'oauth', 'session'],
+  session: ['auth', 'login'],
+  style: ['css', 'theme'],
+  styles: ['css', 'theme'],
+  test: ['spec'],
+  tests: ['spec'],
+})
+
+const cleanQuery = (value) => String(value || '')
+  // Deliberately strip ASCII control characters from room-supplied queries.
+  // eslint-disable-next-line no-control-regex
+  .replace(/[\u0000-\u001f\u007f]/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim()
+
+const unique = (values) => [...new Set(values.filter(Boolean))]
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const normalizePath = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '')
+const wordish = (value) => String(value || '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()
+const pathContainsSegment = (path, segment) => `/${normalizePath(path).toLowerCase()}/`.includes(`/${segment.toLowerCase().replace(/^\/+|\/+$/g, '')}/`)
+
+function queryTokens(query) {
+  return unique((query.toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}_-]*/gu) || [])
+    .map((token) => token.replace(/^[-_]+|[-_]+$/g, ''))
+    .filter((token) => token && !STOP_WORDS.has(token)))
+}
+
+function locationHints(query) {
+  return unique([...query.toLowerCase().matchAll(/\b(?:from|in|inside|under)\s+([\p{L}\p{N}_.\/-]+)/gu)]
+    .map((match) => match[1].replace(/^\/+|\/+$/g, ''))
+    .filter(Boolean))
+}
+
+function defaultRun(command, args, cwd) {
+  return execFileSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: command === 'rg' ? 1400 : 3000,
+    maxBuffer: MAX_FILES_BUFFER,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+}
+
+function listedFiles(run, cwd) {
+  const raw = String(run('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], cwd) || '')
+  return unique(raw.split('\0').map(normalizePath).filter(Boolean))
+}
+
+function contentMatches(run, cwd, terms, knownFiles) {
+  const matches = new Map()
+  if (!terms.length) return matches
+  const pattern = terms.slice().sort((a, b) => b.length - a.length).map(escapeRegex).join('|')
+  let raw = ''
+  try {
+    raw = String(run('rg', [
+      '--json',
+      '--ignore-case',
+      '--max-count', '4',
+      '--no-messages',
+      '--regexp', pattern,
+      '.',
+    ], cwd) || '')
+  } catch {
+    // `rg` is the fast path. A host without it still gets filename/path search;
+    // repository search must never block the room or fall through to an LLM turn.
+    return matches
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue
+    let record
+    try { record = JSON.parse(line) } catch { continue }
+    if (record?.type !== 'match') continue
+    const path = normalizePath(record.data?.path?.text)
+    if (!knownFiles.has(path)) continue
+    const lineNumber = Number(record.data?.line_number)
+    const text = String(record.data?.lines?.text || '').toLowerCase()
+    const prior = matches.get(path)
+    if (!prior) matches.set(path, { line: Number.isFinite(lineNumber) ? lineNumber : null, text })
+    else prior.text += ` ${text}`
+  }
+  return matches
+}
+
+function candidateScore(path, original, expanded, content) {
+  const lowerPath = path.toLowerCase()
+  const base = lowerPath.split('/').at(-1) || lowerPath
+  const pathWords = ` ${wordish(lowerPath)} `
+  const contentText = content?.text || ''
+  let score = 0
+
+  const phrase = original.join(' ')
+  if (phrase && pathWords.includes(` ${phrase} `)) score += 100
+  for (const token of original) {
+    if (base.includes(token)) score += 30
+    if (lowerPath.includes(token)) score += 16
+    if (pathWords.includes(` ${token} `)) score += 8
+    if (contentText.includes(token)) score += 8
+  }
+  for (const token of expanded) {
+    if (base.includes(token)) score += 8
+    else if (lowerPath.includes(token)) score += 5
+    if (contentText.includes(token)) score += 2
+  }
+
+  const rootMatches = (haystack) => original.filter((token) =>
+    haystack.includes(token) || (EXPANSIONS[token] || []).some((alias) => haystack.includes(alias)))
+  const pathCoverage = rootMatches(lowerPath).length
+  const coverage = rootMatches(`${lowerPath} ${contentText}`).length
+  score += (coverage ** 2) * 18 + (pathCoverage ** 2) * 22
+
+  const ext = base.includes('.') ? base.slice(base.lastIndexOf('.')) : ''
+  const componentFile = ['.jsx', '.tsx', '.vue', '.svelte'].includes(ext)
+  if (original.includes('component') && componentFile) score += 60
+  if (original.some((token) => token === 'test' || token === 'tests') && /(?:^|\/)(?:test|tests|spec|specs)(?:\/|$)|\.(?:test|spec)\./.test(lowerPath)) score += 10
+  if (original.some((token) => token === 'asset' || token === 'assets') && /(?:^|\/)assets?(?:\/|$)/.test(lowerPath)) score += 10
+  const testPath = /(?:^|\/)(?:test|tests|spec|specs)(?:\/|$)|\.(?:test|spec)\./.test(lowerPath)
+  if (testPath && !original.some((token) => token === 'test' || token === 'tests')) score -= 25
+  if (/^(?:docs|marketing|archive|\.claude)\//.test(lowerPath)) score -= 35
+  if (/^(?:src|app|lib|api|bridge|server|client|components|packages)\//.test(lowerPath)) score += 12
+  return { score, coverage, pathCoverage, componentFile }
+}
+
+export function repoSearch({
+  cwd = process.cwd(),
+  query,
+  maxResults = DEFAULT_MAX_RESULTS,
+  run = defaultRun,
+  now = () => Date.now(),
+} = {}) {
+  const startedAt = now()
+  const cleaned = cleanQuery(query)
+  const finish = (result) => ({ ...result, durationMs: Math.max(0, Math.round(now() - startedAt)) })
+
+  if (!cleaned) return finish({ query: '', results: [], total: 0, truncated: false, error: 'Use /find followed by a filename, symbol, or code concept.' })
+  if (cleaned.length > MAX_QUERY_CHARS) return finish({ query: cleaned.slice(0, MAX_QUERY_CHARS), results: [], total: 0, truncated: false, error: `Keep /find queries under ${MAX_QUERY_CHARS} characters.` })
+
+  const original = queryTokens(cleaned)
+  if (!original.length) return finish({ query: cleaned, results: [], total: 0, truncated: false, error: 'Try a filename, symbol, or code concept.' })
+  const expanded = unique(original.flatMap((token) => EXPANSIONS[token] || []))
+
+  let files
+  try { files = listedFiles(run, cwd) } catch {
+    return finish({ query: cleaned, results: [], total: 0, truncated: false, error: 'Repository search is unavailable outside a readable Git checkout.' })
+  }
+  const activeLocations = locationHints(cleaned).filter((hint) => files.some((path) => pathContainsSegment(path, hint)))
+  const eligibleFiles = activeLocations.length
+    ? files.filter((path) => activeLocations.every((hint) => pathContainsSegment(path, hint)))
+    : files
+  const knownFiles = new Set(eligibleFiles)
+  const matches = contentMatches(run, cwd, unique([...original, ...expanded]), knownFiles)
+  const minimumCoverage = Math.max(1, Math.ceil(original.length * 0.6))
+  const ranked = eligibleFiles
+    .map((path) => {
+      const rank = candidateScore(path, original, expanded, matches.get(path))
+      return { path, line: matches.get(path)?.line || null, ...rank }
+    })
+    .filter((item) => item.score > 0 && (
+      item.coverage >= minimumCoverage
+      || (original.includes('component') && item.componentFile && item.coverage >= 2)
+    ))
+    .sort((a, b) => b.score - a.score || b.pathCoverage - a.pathCoverage || a.path.length - b.path.length || a.path.localeCompare(b.path))
+
+  const limit = Math.max(1, Math.min(20, Number(maxResults) || DEFAULT_MAX_RESULTS))
+  return finish({
+    query: cleaned,
+    results: ranked.slice(0, limit).map(({ path, line }) => ({ path, ...(line ? { line } : {}) })),
+    total: ranked.length,
+    truncated: ranked.length > limit,
+  })
+}

package/runtime-contract.mjs

@@ -0,0 +1,93 @@
+// Bridge-owned semantic capabilities. Native runtimes keep their own tool
+// transport; this module only admits the stable room-facing meaning.
+
+const RUNTIMES = Object.freeze(['claude', 'codex', 'hermes'])
+const SUPPORT = Object.freeze({ claude: 'native', codex: 'native', hermes: 'native' })
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/
+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_PROSE = /(?:raw transcript|tool args?|chain[ -]of[ -]thought|hidden reasoning|system prompt|environment dump|provider key|BEGIN (?:RSA |OPENSSH )?PRIVATE KEY)/i
+
+const schema = (required = [], properties = {}) => Object.freeze({
+  type: 'object', additionalProperties: false, required: Object.freeze(required), properties: Object.freeze(properties),
+})
+const text = (maxLength = 500) => Object.freeze({ type: 'string', minLength: 1, maxLength })
+const optionalText = (maxLength = 500) => Object.freeze({ type: 'string', maxLength })
+const bool = Object.freeze({ type: 'boolean' })
+const integer = (minimum, maximum) => Object.freeze({ type: 'integer', minimum, maximum })
+const id = Object.freeze({ type: 'string', minLength: 1, maxLength: 160, pattern: '^[A-Za-z0-9][A-Za-z0-9._:@-]*$' })
+const option = schema(['label', 'description'], { label: text(80), description: text(240) })
+const question = schema(['id', 'header', 'question', 'options'], {
+  id: Object.freeze({ type: 'string', minLength: 1, maxLength: 80, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*$' }),
+  header: text(12), question: text(500), options: Object.freeze({ type: 'array', minItems: 2, maxItems: 3, items: option }), multiSelect: bool,
+})
+const evidenceRef = schema(['type', 'id'], { type: id, id })
+
+export const RUNTIME_CAPABILITY_VERSION = 1
+export const RUNTIME_CAPABILITIES = Object.freeze([
+  Object.freeze({ id: 'request_user_input', version: 1, runtimeSupport: SUPPORT, inputSchema: schema(['questions'], { questions: Object.freeze({ type: 'array', minItems: 1, maxItems: 3, items: question }), autoResolutionMs: integer(60_000, 240_000) }), output: 'accepted | deferred | rejected | failed', authority: 'pair-control', persistence: 'durable-safe-ref', continuation: 'resumable', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'request_permission', version: 1, runtimeSupport: SUPPORT, inputSchema: schema(['action'], { action: text(160), reason: optionalText(280) }), output: 'accepted | deferred | rejected | failed', authority: 'pair-control', persistence: 'durable-safe-ref', continuation: 'resumable', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'submit_flow_plan', version: 1, runtimeSupport: SUPPORT, inputSchema: schema(['plan'], { plan: text(32_768) }), output: 'accepted | rejected | failed', authority: 'pair-control', persistence: 'durable-safe-ref', continuation: 'resumable', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'mark_flow_done', version: 1, runtimeSupport: SUPPORT, inputSchema: schema([], { evidenceRef }), output: 'accepted | rejected | failed', authority: 'bridge', persistence: 'durable-safe-ref', continuation: 'none', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'submit_flow_review', version: 1, runtimeSupport: SUPPORT, inputSchema: schema(['verdict'], { verdict: text(16_384) }), output: 'accepted | rejected | failed', authority: 'bridge', persistence: 'durable-safe-ref', continuation: 'none', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'terminal_interrupt', version: 1, runtimeSupport: SUPPORT, inputSchema: schema([], { reason: optionalText(280) }), output: 'accepted | rejected | failed', authority: 'bridge', persistence: 'ephemeral', continuation: 'none', secretFreeRoomPayload: true }),
+  Object.freeze({ id: 'lane_continuation', version: 1, runtimeSupport: SUPPORT, inputSchema: schema(['state'], { state: Object.freeze({ type: 'string', enum: Object.freeze(['waiting_for_human', 'resumable', 'canceled', 'terminal']) }), resumeKind: Object.freeze({ type: 'string', enum: Object.freeze(['human_response', 'approval', 'redispatch', 'reconnect']) }) }), output: 'accepted | deferred | rejected | failed', authority: 'bridge', persistence: 'durable-safe-ref', continuation: 'resumable', secretFreeRoomPayload: true }),
+])
+
+const CAPABILITIES = new Map(RUNTIME_CAPABILITIES.map((capability) => [capability.id, capability]))
+export const runtimeCapability = (id) => CAPABILITIES.get(id) || null
+export const runtimeSupportsCapability = (runtime, capabilityId) => RUNTIMES.includes(runtime) && runtimeCapability(capabilityId)?.runtimeSupport?.[runtime] === 'native'
+
+const jsonBytes = (value) => {
+  try { return new TextEncoder().encode(JSON.stringify(value)).length } catch { return Infinity }
+}
+
+// This deliberately mirrors the pair-control redaction boundary without pulling
+// browser source into the published bridge package.
+export function isSecretFreeRoomPayload (value, maxBytes = 8192) {
+  if (value == null || jsonBytes(value) > maxBytes) return false
+  const visit = (node) => {
+    if (typeof node === 'string') return node.length <= 2048 && !HOST_PATH.test(node) && !SECRET_VALUE.test(node) && !PROHIBITED_PROSE.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 validValue (value, definition) {
+  if (!definition) return true
+  if (definition.type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+    if (definition.additionalProperties === false && Object.keys(value).some((key) => !Object.hasOwn(definition.properties || {}, key))) return false
+    if ((definition.required || []).some((key) => !Object.hasOwn(value, key))) return false
+    return Object.entries(definition.properties || {}).every(([key, child]) => !Object.hasOwn(value, key) || validValue(value[key], child))
+  }
+  if (definition.type === 'array') return Array.isArray(value) && value.length >= (definition.minItems || 0) && value.length <= (definition.maxItems ?? Infinity) && (!definition.items || value.every((item) => validValue(item, definition.items)))
+  if (definition.type === 'string') return typeof value === 'string' && value.length >= (definition.minLength || 0) && value.length <= (definition.maxLength ?? Infinity) && (!definition.enum || definition.enum.includes(value)) && (!definition.pattern || new RegExp(definition.pattern).test(value))
+  if (definition.type === 'integer') return Number.isSafeInteger(value) && value >= (definition.minimum ?? -Infinity) && value <= (definition.maximum ?? Infinity)
+  if (definition.type === 'boolean') return typeof value === 'boolean'
+  return false
+}
+
+export function validateRuntimeCapabilityInput (capabilityId, input) {
+  const capability = runtimeCapability(capabilityId)
+  return !!capability && validValue(input, capability.inputSchema)
+}
+
+export function admitRuntimeCapability ({ runtime, capabilityId, input = {}, roomPayload = null } = {}) {
+  const capability = runtimeCapability(capabilityId)
+  if (!capability) return Object.freeze({ ok: false, code: 'unregistered_capability' })
+  if (!RUNTIMES.includes(runtime) || capability.runtimeSupport[runtime] !== 'native') return Object.freeze({ ok: false, code: 'runtime_capability_mismatch' })
+  if (!validateRuntimeCapabilityInput(capabilityId, input)) return Object.freeze({ ok: false, code: 'invalid_capability_input' })
+  if (capability.secretFreeRoomPayload && roomPayload != null && !isSecretFreeRoomPayload(roomPayload)) return Object.freeze({ ok: false, code: 'unsafe_room_payload' })
+  return Object.freeze({ ok: true, code: 'admitted', capability })
+}
+
+export function assertRuntimeCapability (request) {
+  const admitted = admitRuntimeCapability(request)
+  if (!admitted.ok) throw new TypeError(`Runtime capability rejected: ${admitted.code}`)
+  return admitted.capability
+}

package/runtime-registry.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { runtimeCapability, runtimeSupportsCapability } from './runtime-contract.mjs'
 
 const RUNTIMES = Object.freeze({
   claude: Object.freeze({
@@ -28,6 +29,11 @@ export const structuredRuntimeForCommand = (command) => {
 export const defaultStructuredMode = (runtime) => structuredRuntimeMetadata(runtime)?.defaultMode || 'default'
 export const structuredRuntimeSupportsMode = (runtime, mode) => structuredRuntimeMetadata(runtime)?.modes?.includes(mode) === true
 export const structuredRuntimeSupportsFlow = (runtime) => structuredRuntimeMetadata(runtime)?.flow === true
+// This is deliberately semantic rather than a list of native tool names. The
+// bridge may expose an MCP tool, an SDK hook, or ACP registration underneath.
+export const structuredRuntimeCapability = (runtime, capabilityId) => (
+  runtimeSupportsCapability(runtime, capabilityId) ? runtimeCapability(capabilityId) : null
+)
 export const structuredModeLocked = ({ flowRole, sliceType } = {}) => (
   flowRole === 'conductor' || flowRole === 'reviewer' || sliceType === 'review'
 )

package/runtime-session.mjs

@@ -1,6 +1,7 @@
 import { startClaudeSession } from './claude-session.mjs'
 import { startCodexSession } from './codex-session.mjs'
 import { startHermesSession } from './hermes-session.mjs'
+import { assertRuntimeCapability } from './runtime-contract.mjs'
 
 const FACTORIES = Object.freeze({
   claude: startClaudeSession,
@@ -11,5 +12,9 @@ const FACTORIES = Object.freeze({
 export function startStructuredSession(runtime, options) {
   const factory = FACTORIES[runtime]
   if (!factory) throw new Error(`Unsupported structured runtime: ${runtime}`)
+  // Every live adapter has a native interrupt boundary. Assert the semantic
+  // contract here so an accidental registry/runtime divergence fails at launch,
+  // rather than silently accepting a provider-specific fallback later.
+  assertRuntimeCapability({ runtime, capabilityId: 'terminal_interrupt', input: {} })
   return factory(options)
 }

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 17,
+  "bundleVersion": 18,
   "contracts": [
     {
       "id": "room-coordination",
@@ -88,13 +88,13 @@
     },
     {
       "id": "visual-proof",
-      "version": 4,
+      "version": 5,
       "routes": [
         {
           "id": "visual-proof",
           "tools": ["preview_start", "preview_capture", "preview_inspect", "preview_stop"],
           "trigger": "\\b(ui|ux|visual|design|frontend|html|css|page|route|mockup|screenshot|responsive|desktop|mobile|preview)\\b",
-          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, ordinary room broadcasts, and refresh-token access are blocked, while non-mutating roster/transcript snapshot requests are allowed. Surface PNG evidence only when no interactive source-backed Design card is displayed."
+          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. For an intentional application-preview Design card, use the project's source-aware Design build command when one exists (for example npm run build:design); otherwise build normally and keep selector-based source matching labeled as fallback. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, ordinary room broadcasts, and refresh-token access are blocked, while non-mutating roster/transcript snapshot requests are allowed. Surface PNG evidence only when no interactive source-backed Design card is displayed."
         }
       ],
       "impact": [
@@ -188,8 +188,8 @@
     },
     {
       "id": "design-workspace",
-      "version": 6,
-      "interactionPrompt": "DESIGN EDITING MODEL: every complete bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For authored HTML, the producing lane edits the canonical authored HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
+      "version": 7,
+      "interactionPrompt": "DESIGN EDITING MODEL: every complete bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For source-aware application previews, the bridge validates each opaque source identity against its contained host-only map and the current source-file hash before sharing an exact source location privately with the producing lane; uninstrumented elements keep the selector-based fallback, while stale or mismatched identities fail closed. For authored HTML, the producing lane edits the canonical authored HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
       "turnReminder": "DESIGN ROUTE: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. Cards are delivered after the final agent response so they remain the newest transcript item. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
       "impact": [
         {"path": "src/pages/code/design/"},

package/thinkpool-room-prompt.mjs

@@ -9,6 +9,7 @@
 // tells a fresh agent WHEN ThinkPool expects each capability without requiring
 // the people in the room to know a tool name or summon word.
 import { THINKPOOL_CAPABILITY_ROUTES, THINKPOOL_PROMPT_BUNDLE, thinkPoolCapabilityContract } from './thinkpool-prompt-contracts.mjs'
+import { buildContextManifest, formatRoomContextProjection } from './context-contract.mjs'
 
 export { THINKPOOL_CAPABILITY_ROUTES, THINKPOOL_PROMPT_BUNDLE }
 
@@ -113,7 +114,7 @@ export function createRoomContextSelector(roomContext) {
   return ({ force = false } = {}) => {
     let context = null
     try { context = typeof roomContext === 'function' ? roomContext() : roomContext } catch { context = null }
-    const value = String(context || '').trim()
+    const value = formatRoomContextProjection(context)
     if (!value) return ''
     const fingerprint = roomContextFingerprint(value)
     const changed = fingerprint !== previousFingerprint
@@ -122,6 +123,21 @@ export function createRoomContextSelector(roomContext) {
   }
 }
 
+// A caller can inspect the deterministic selection without retaining its raw
+// text. The manifest contains only allow-listed source kinds and safe refs.
+export function buildThinkPoolContextManifest({ currentUserTurn = '', roomNow = '', flowSliceDigest = null, approvedHumanResponse = null } = {}) {
+  const roomProjection = formatRoomContextProjection(roomNow)
+  return buildContextManifest({
+    promptBundle: THINKPOOL_PROMPT_BUNDLE,
+    sources: [
+      { kind: 'current_user_turn', value: currentUserTurn },
+      { kind: 'room_now_delta', value: roomProjection },
+      ...(flowSliceDigest ? [{ kind: 'flow_slice_digest', value: flowSliceDigest, ref: { type: 'flow_digest', id: 'local' } }] : []),
+      ...(approvedHumanResponse ? [{ kind: 'approved_human_response', value: approvedHumanResponse, ref: { type: 'control_item', id: 'approved' } }] : []),
+    ],
+  })
+}
+
 // One authoritative terminal-identity preamble for every structured runtime.
 // The bridge derives this from durable structural metadata — never from the text
 // of the task handed to the model. That distinction matters because a spawned

package/viewport.mjs

@@ -17,6 +17,10 @@ import os from 'node:os'
 import path from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { previews, startPreview } from './flow-preview.mjs'
+import {
+  DESIGN_SOURCE_MAP_RELATIVE,
+  MAX_DESIGN_SOURCE_MAP_BYTES,
+} from './design-source-contract.mjs'
 
 export const DEFAULT_VIEWPORTS = Object.freeze({
   desktop: Object.freeze({ width: 1440, height: 900 }),
@@ -51,6 +55,18 @@ export async function resolveContainedRoot(workspaceRoot, requested = 'dist') {
   return resolved
 }
 
+export async function resolvePreviewSourceMap(previewRoot) {
+  if (!previewRoot) return null
+  let root, sourceMap
+  try {
+    root = await fsp.realpath(previewRoot)
+    sourceMap = await fsp.realpath(path.join(root, DESIGN_SOURCE_MAP_RELATIVE))
+    const stat = await fsp.stat(sourceMap)
+    if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_DESIGN_SOURCE_MAP_BYTES) return null
+  } catch { return null }
+  return isInside(root, sourceMap) ? sourceMap : null
+}
+
 export function normalizeRoute(value = '/') {
   const route = String(value || '/').trim()
   if (!route.startsWith('/') || route.startsWith('//')) throw new Error('Preview path must start with one "/" and cannot be a URL.')
@@ -674,11 +690,13 @@ export class ViewportManager {
     if (snapshotPath) await fsp.writeFile(snapshotPath, snapshot)
     let manifestPath = null
     if (cardReady) {
+      const sourceMap = await resolvePreviewSourceMap(this.root)
       const manifest = {
         slug, title: String(title || 'Viewport capture').slice(0, 120),
         desktop: captures.desktop.file, mobile: captures.mobile.file, ts: Date.now(),
         sourceKind: 'preview', deliveryIntent: 'card', readinessValidated: true,
         snapshot: snapshotPath, previewRoot, route: normalizedRoute, captureKey,
+        ...(sourceMap ? { sourceMap } : {}),
         ...correlation,
       }
       manifestPath = path.join(this.outbox, `${slug}.json`)