thinkpool-pair 0.7.354 → 0.7.356

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.356",
   "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,8 @@
     "agent-notify.mjs",
     "agent-detect.mjs",
     "code-event-contract.mjs",
+    "evidence-citations.mjs",
+    "error-recovery.mjs",
     "pair-control-authority.mjs",
     "event-id.mjs",
     "event-bounds.mjs",
@@ -71,6 +75,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 +88,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 +112,7 @@
     "supabase-key.mjs",
     "provider.mjs",
     "providers.mjs",
+    "provider-resilience.mjs",
     "model-prices.mjs",
     "README.md"
   ],

package/provider-resilience.mjs

@@ -0,0 +1,213 @@
+/*
+ * Provider resilience policy primitives.
+ *
+ * Phase 0 is deliberately policy-only: this module never makes a network call,
+ * never reads provider credentials, and never persists circuit or attempt state.
+ * The Claude session may observe its pre-existing recovery paths through the
+ * attempt ledger, but enabling this module cannot add a retry or fallback.
+ */
+import { isSecretFreeRoomPayload } from './runtime-contract.mjs'
+
+export const RESILIENCE_VERSION = 1
+export const MAX_NETWORK_ATTEMPTS = 3
+export const TRANSIENT_FAILURES = new Set(['timeout', 'network', 'rate_limit', 'overload', 'upstream_5xx'])
+const RETRYABLE = [...TRANSIENT_FAILURES]
+const TRACE_FIELDS = new Set(['traceId', 'turnRev', 'attempt', 'targetProviderId', 'targetProviderName', 'requestedModel', 'actualConfiguredModel', 'phase', 'outcome', 'failureClass', 'elapsedMs', 'retryAfterMs', 'fallbackFrom'])
+const OUTCOMES = new Set(['started', 'retrying', 'failed', 'fallback', 'succeeded', 'circuit_open', 'cap_blocked'])
+const TRACE_TEXT_FIELDS = new Set(['traceId', 'targetProviderId', 'targetProviderName', 'requestedModel', 'actualConfiguredModel', 'phase', 'failureClass', 'fallbackFrom'])
+const TRACE_URL_OR_PATH = /(?:[a-z][a-z0-9+.-]*:\/\/|(?:^|[\s"'(])\/(?:Users|home|private|tmp)\/|[a-z]:\\|\\\\)/i
+
+export const DEFAULT_RESILIENCE_POLICY = Object.freeze({
+  v: RESILIENCE_VERSION,
+  enabled: false,
+  timeoutMs: 90000,
+  maxAttempts: 2,
+  retryOn: RETRYABLE,
+  circuit: Object.freeze({ failureThreshold: 3, windowMs: 60000, cooldownMs: 30000 }),
+  fallback: Object.freeze([]),
+})
+
+const plainObject = (x) => !!x && typeof x === 'object' && !Array.isArray(x)
+const positiveInt = (x) => Number.isInteger(x) && x > 0
+const text = (x) => typeof x === 'string' && x.trim() ? x.trim() : null
+const safeTraceText = (value) => {
+  const normalized = text(value)
+  if (!normalized || normalized.length > 160 || TRACE_URL_OR_PATH.test(normalized)) return null
+  return isSecretFreeRoomPayload({ value: normalized }, 512) ? normalized : null
+}
+
+/**
+ * Validate and canonicalize the non-secret provider policy. Missing policy is
+ * the explicit observe-only default. Extra fields are discarded rather than
+ * copied into a room-facing projection.
+ */
+export function validateResiliencePolicy(input, { providers = [], primaryProviderId = null } = {}) {
+  if (input == null) return { ok: true, value: { ...DEFAULT_RESILIENCE_POLICY, retryOn: [...RETRYABLE], circuit: { ...DEFAULT_RESILIENCE_POLICY.circuit }, fallback: [] } }
+  if (!plainObject(input) || input.v !== RESILIENCE_VERSION) return { ok: false, error: 'unsupported resilience policy version' }
+  if (typeof input.enabled !== 'boolean') return { ok: false, error: 'enabled must be boolean' }
+  if (!Number.isInteger(input.timeoutMs) || input.timeoutMs < 30000 || input.timeoutMs > 120000) return { ok: false, error: 'timeoutMs must be 30000..120000' }
+  if (!positiveInt(input.maxAttempts)) return { ok: false, error: 'maxAttempts must be a positive integer' }
+  if (!Array.isArray(input.retryOn) || input.retryOn.some((x) => !TRANSIENT_FAILURES.has(x))) return { ok: false, error: 'retryOn contains an unsupported failure class' }
+  if (!plainObject(input.circuit) || !positiveInt(input.circuit.failureThreshold) || !positiveInt(input.circuit.windowMs) || !positiveInt(input.circuit.cooldownMs)) return { ok: false, error: 'invalid circuit policy' }
+  if (!Array.isArray(input.fallback)) return { ok: false, error: 'fallback must be an array' }
+  const fallback = []
+  for (const candidate of input.fallback) {
+    if (!plainObject(candidate) || !text(candidate.providerId) || !text(candidate.model) || candidate.allow !== true) return { ok: false, error: 'invalid fallback target' }
+    // Phase 0 stores only the conservative v1 declarations. A future UI may add
+    // explicit elevated consent, but it must not be smuggled in via this shape.
+    if (candidate.privacyClass !== 'same' || !['same', 'same-or-lower'].includes(candidate.costClass)) return { ok: false, error: 'fallback privacy/cost class is not eligible' }
+    if (primaryProviderId && candidate.providerId === primaryProviderId) return { ok: false, error: 'fallback cannot target itself' }
+    if (providers.length) {
+      const row = providers.find((provider) => provider?.id === candidate.providerId)
+      if (!row || row.id === 'anthropic' || row.model !== candidate.model) return { ok: false, error: 'fallback must name a registered exact provider/model target' }
+    }
+    fallback.push({ providerId: text(candidate.providerId), model: text(candidate.model), allow: true, privacyClass: candidate.privacyClass, costClass: candidate.costClass })
+  }
+  return {
+    ok: true,
+    value: {
+      v: RESILIENCE_VERSION,
+      enabled: input.enabled,
+      timeoutMs: input.timeoutMs,
+      // A malformed high value may never increase live network work.
+      maxAttempts: Math.min(input.maxAttempts, MAX_NETWORK_ATTEMPTS),
+      retryOn: [...new Set(input.retryOn)],
+      circuit: { failureThreshold: input.circuit.failureThreshold, windowMs: input.circuit.windowMs, cooldownMs: input.circuit.cooldownMs },
+      fallback,
+    },
+  }
+}
+
+/** Safe allowlist projection for local diagnostics / room-safe metadata. */
+export function resilienceProjection(input) {
+  const validated = validateResiliencePolicy(input)
+  if (!validated.ok) return null
+  const p = validated.value
+  return { v: p.v, enabled: p.enabled, timeoutMs: p.timeoutMs, maxAttempts: p.maxAttempts, retryOn: [...p.retryOn], circuit: { ...p.circuit }, fallback: p.fallback.map((x) => ({ ...x })) }
+}
+
+/** Coarse classification only. It intentionally does not return raw errors. */
+export function classifyProviderFailure(input = {}) {
+  const status = Number(input.status || input.statusCode || 0)
+  const code = String(input.code || '').toLowerCase()
+  const message = String(input.message || input.error?.message || '').toLowerCase()
+  if (input.aborted || /\babort(ed|error)?\b|cancelled|canceled/.test(`${code} ${message}`)) return 'user_abort'
+  if (input.permissionDenied || /permission denied|forbidden by policy|guardrail/.test(`${code} ${message}`)) return 'permission_denied'
+  if (status === 401 || status === 403 || /unauthori[sz]ed|invalid (api )?key|credential/.test(`${code} ${message}`)) return 'auth'
+  if (status === 429 || /rate.?limit/.test(`${code} ${message}`)) return 'rate_limit'
+  if (status === 529 || /overload|overloaded/.test(`${code} ${message}`)) return 'overload'
+  if (status >= 500 && status <= 599) return 'upstream_5xx'
+  if (/timeout|timed out|deadline exceeded|etimedout/.test(`${code} ${message}`)) return 'timeout'
+  if (/econnreset|enotfound|eai_again|socket|connection (closed|reset)|fetch failed|network error/.test(`${code} ${message}`)) return 'network'
+  if (status === 400 || /invalid model|unknown model/.test(`${code} ${message}`)) return 'invalid_model'
+  if (/context length|request too large|payload too large|too many tokens/.test(`${code} ${message}`)) return 'request_too_large'
+  if (status >= 400 && status < 500) return 'invalid_request'
+  return 'unknown'
+}
+
+export const isReplaySafe = ({ outputVisible = false, toolOutputVisible = false, aborted = false, permissionDenied = false, nonIdempotent = false } = {}) => !(outputVisible || toolOutputVisible || aborted || permissionDenied || nonIdempotent)
+
+/** Resolve only registered custom Claude targets with their exact configured model. */
+export function resolveAttemptTarget({ runtime = 'claude', providers = [], providerId, model } = {}) {
+  if (runtime !== 'claude' || !text(providerId) || !text(model)) return null
+  const provider = providers.find((p) => p && p.id === providerId && p.id !== 'anthropic' && p.model === model)
+  if (!provider) return null
+  return { providerId: provider.id, targetProviderName: text(provider.name) || provider.id, actualConfiguredModel: provider.model }
+}
+
+/** All eight Phase-2 eligibility gates in a pure, fail-closed form. */
+export function assessFallbackEligibility({ runtime = 'claude', providers = [], primary, candidate, policy, outputVisible = false, toolOutputVisible = false, aborted = false, permissionDenied = false, capAllowed = true, circuit = 'closed' } = {}) {
+  if (!isReplaySafe({ outputVisible, toolOutputVisible, aborted, permissionDenied })) return { ok: false, reason: 'replay_unsafe' }
+  if (circuit !== 'closed') return { ok: false, reason: 'circuit_open' }
+  if (!capAllowed) return { ok: false, reason: 'cap_blocked' }
+  const checked = validateResiliencePolicy(policy)
+  if (!checked.ok || !checked.value.enabled || runtime !== 'claude') return { ok: false, reason: 'policy_disabled' }
+  const target = resolveAttemptTarget({ runtime, providers, providerId: candidate?.providerId, model: candidate?.model })
+  if (!target) return { ok: false, reason: 'unknown_target' }
+  const configured = checked.value.fallback.find((x) => x.providerId === target.providerId && x.model === target.actualConfiguredModel)
+  if (!configured?.allow) return { ok: false, reason: 'not_explicitly_allowed' }
+  if (configured.privacyClass !== 'same' || !['same', 'same-or-lower'].includes(configured.costClass)) return { ok: false, reason: 'boundary_not_consented' }
+  if (primary?.providerId === target.providerId && primary?.actualConfiguredModel === target.actualConfiguredModel) return { ok: false, reason: 'same_target' }
+  return { ok: true, target, fallback: configured }
+}
+
+/** Local-only total-attempt accounting. It is intentionally not a retry engine. */
+export function createAttemptLedger({ maxAttempts = MAX_NETWORK_ATTEMPTS, traceId = 'local', turnRev = null, onRecord = null } = {}) {
+  const ceiling = Math.max(1, Math.min(Number.isInteger(maxAttempts) ? maxAttempts : 1, MAX_NETWORK_ATTEMPTS))
+  const records = []
+  const record = (entry = {}) => {
+    if (records.length >= ceiling) return null
+    const next = safeTraceRecord({ traceId, turnRev, attempt: Math.min(records.length + 1, ceiling), ...entry })
+    records.push(next)
+    try { onRecord?.(next) } catch { /* observation must never affect the session */ }
+    return next
+  }
+  return {
+    get ceiling() { return ceiling },
+    get attempts() { return records.length },
+    get records() { return records.map((x) => ({ ...x })) },
+    canSubmit() { return records.length < ceiling },
+    record,
+  }
+}
+
+/** Memory-only circuit breaker keyed by bridge/provider/exact-model. */
+export function createMemoryCircuit({ now = () => Date.now() } = {}) {
+  const states = new Map()
+  const keyOf = ({ bridgeHostId, providerId, model } = {}) => `${bridgeHostId || ''}\u0000${providerId || ''}\u0000${model || ''}`
+  const stateFor = (target) => states.get(keyOf(target)) || { failures: [], openUntil: 0, probing: false }
+  const put = (target, state) => states.set(keyOf(target), state)
+  return {
+    preflight(target) {
+      const state = stateFor(target); const t = now()
+      if (state.openUntil > t) return { ok: false, state: 'open' }
+      if (state.openUntil && state.openUntil <= t) {
+        if (state.probing) return { ok: false, state: 'half_open_busy' }
+        state.probing = true; put(target, state); return { ok: true, state: 'half_open' }
+      }
+      return { ok: true, state: 'closed' }
+    },
+    success(target) { states.delete(keyOf(target)) },
+    failure(target, policy, failureClass) {
+      if (!TRANSIENT_FAILURES.has(failureClass)) return { state: this.preflight(target).state, counted: false }
+      const state = stateFor(target); const t = now(); const circuit = policy?.circuit || DEFAULT_RESILIENCE_POLICY.circuit
+      if (state.probing) { state.probing = false; state.failures = []; state.openUntil = t + circuit.cooldownMs; put(target, state); return { state: 'open', counted: true } }
+      state.failures = state.failures.filter((at) => at > t - circuit.windowMs)
+      state.failures.push(t)
+      if (state.failures.length >= circuit.failureThreshold) state.openUntil = t + circuit.cooldownMs
+      put(target, state)
+      return { state: state.openUntil > t ? 'open' : 'closed', counted: true }
+    },
+    // Test/diagnostic-only metadata. Never returns credentials, URLs, or prompts.
+    snapshot(target) { const s = stateFor(target); return { failures: s.failures.length, openUntil: s.openUntil, probing: s.probing } },
+  }
+}
+
+export function safeTraceRecord(input = {}) {
+  const out = {}
+  for (const key of TRACE_FIELDS) {
+    if (input[key] === undefined || input[key] === null) continue
+    if (TRACE_TEXT_FIELDS.has(key)) {
+      const value = safeTraceText(input[key])
+      if (value) out[key] = value
+    } else out[key] = input[key]
+  }
+  out.attempt = Math.max(1, Math.min(Number(out.attempt) || 1, MAX_NETWORK_ATTEMPTS))
+  if (!OUTCOMES.has(out.outcome)) out.outcome = 'failed'
+  if (out.failureClass && !/^[a-z0-9_]+$/.test(String(out.failureClass))) delete out.failureClass
+  for (const key of ['elapsedMs', 'retryAfterMs']) if (out[key] != null) out[key] = Math.max(0, Math.floor(Number(out[key]) || 0))
+  return out
+}
+
+/** A room-safe line assembled exclusively from the allowlisted coarse record. */
+export function formatResilienceTrace(input) {
+  const r = safeTraceRecord(input)
+  const target = [r.targetProviderName || r.targetProviderId, r.actualConfiguredModel].filter(Boolean).join(' / ') || 'configured provider'
+  const failure = r.failureClass ? ` (${r.failureClass.replaceAll('_', ' ')})` : ''
+  if (r.outcome === 'retrying') return `${target} unavailable${failure} — existing session recovery is retrying (attempt ${r.attempt}).`
+  if (r.outcome === 'circuit_open') return `${target} is temporarily unavailable; its local circuit is open.`
+  if (r.outcome === 'cap_blocked') return `Additional provider work was blocked by the applicable cap.`
+  if (r.outcome === 'succeeded') return `${target} completed.`
+  if (r.outcome === 'fallback') return `Configured fallback selected: ${target}.`
+  return `${target} failed${failure}.`
+}

package/recap.mjs

@@ -26,11 +26,19 @@ export const RECAP_CAP = 20000
 // unmistakable authority boundary: the recap is memory, never a second task.
 export const CURRENT_PERSON_REQUEST_MARKER = '--- CURRENT PERSON REQUEST (authoritative; overrides all carried context above) ---'
 
+// Recaps are an outbound context source. Keep the same privacy boundary as the
+// bridge manifest without importing Node-only hashing into the browser bundle.
+const UNSAFE_CONTEXT = /(?:\/home\/|\/users\/|\/private\/|\/tmp\/|[a-z]:\\|\\\\|sk[_-][a-z0-9_-]{8,}|gsk_[a-z0-9_-]{8,}|bearer\s+[a-z0-9._-]{8,}|BEGIN (?:RSA |OPENSSH )?PRIVATE KEY|raw transcript|tool args?|chain[ -]of[ -]thought|hidden reasoning)/i
+const safeRecapText = (value) => {
+  const text = String(value || '').trim()
+  return text && !UNSAFE_CONTEXT.test(text) ? text : ''
+}
+
 export function appendCurrentPersonRequest(carried, text) {
   const contexts = (Array.isArray(carried) ? carried : [carried])
-    .map((value) => String(value || '').trim())
+    .map(safeRecapText)
     .filter(Boolean)
-  const request = String(text || '')
+  const request = safeRecapText(text)
   if (!contexts.length) return request
   return `${contexts.join('\n\n')}\n\n${CURRENT_PERSON_REQUEST_MARKER}\n${request}`
 }
@@ -90,12 +98,12 @@ export function buildRecapFromLog(log, cap = RECAP_CAP, { reason = 'switch' } =
   for (const e of log) {
     if (!e || typeof e !== 'object') continue
     if (e.kind === 'you') {
-      const t = String(e.text || '').trim()
+      const t = safeRecapText(e.text)
       if (t) turns.push({ who: 'PERSON', text: t })
     } else if (e.kind === 'assistant') {
       const t = (Array.isArray(e.blocks) ? e.blocks : [])
-        .filter((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.trim())
-        .map((b) => b.text.trim())
+        .filter((b) => b && b.type === 'text' && safeRecapText(b.text))
+        .map((b) => safeRecapText(b.text))
         .join('\n')
       if (t) turns.push({ who: 'YOU', text: t })
     }

package/repo-search.mjs

@@ -27,6 +27,8 @@ const EXPANSIONS = Object.freeze({
 })
 
 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()

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/"},