thinkpool-pair 0.7.354 → 0.7.357

package/provider-resilience.mjs

@@ -0,0 +1,356 @@
+/*
+ * Provider resilience policy primitives.
+ *
+ * This module never makes a network call or reads provider credentials. Phase 1
+ * adds an injected same-target controller, but transport remains owned by the
+ * Claude session and fallback remains unavailable.
+ */
+import { isSecretFreeRoomPayload } from './runtime-contract.mjs'
+
+export const RESILIENCE_VERSION = 1
+export const MAX_NETWORK_ATTEMPTS = 3
+export const MAX_SAME_TARGET_ATTEMPTS = 2
+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 } },
+  }
+}
+
+/**
+ * Apply the only authoritative provider-work cap currently available at the
+ * bridge boundary. Ordinary/uncapped lanes remain admissible, but the result
+ * names that absence explicitly so the host can record `cap_not_configured`
+ * rather than pretending an approval occurred.
+ */
+export function providerResilienceCapAdmission(budget) {
+  if (!budget || budget.capTokens == null) {
+    return { allowed: true, configured: false, reason: 'cap_not_configured' }
+  }
+  const capTokens = Number(budget.capTokens)
+  const spentTokens = Number(budget.spentTokens)
+  const allowed = Number.isFinite(capTokens)
+    && capTokens >= 0
+    && Number.isFinite(spentTokens)
+    && spentTokens >= 0
+    && budget.killed !== true
+    && spentTokens < capTokens
+  return { allowed, configured: true, reason: allowed ? 'within_cap' : 'cap_blocked' }
+}
+
+/**
+ * Pure, injected Phase-1 controller for a single exact custom Claude target.
+ *
+ * The bridge/session integration owns transport and invokes this controller at
+ * turn start, before each submission, after visible output, and at terminal
+ * success/failure. It intentionally has no fallback path and cannot resolve a
+ * built-in Anthropic target. A caller must inject both the authoritative cap
+ * admission gate and the bridge-scoped memory circuit; missing or broken gates
+ * deny the submission rather than guessing that it is safe.
+ */
+export function createSameTargetResilienceController({
+  runtime = 'claude', providers = [], providerId, model, requestedModel = model,
+  policy, bridgeHostId = null, circuit, capGate, traceId = 'local', turnRev = null,
+  onRecord = null,
+} = {}) {
+  let checked
+  try { checked = validateResiliencePolicy(policy, { providers, primaryProviderId: providerId }) } catch { checked = { ok: false } }
+  let target = null
+  try { target = resolveAttemptTarget({ runtime, providers, providerId, model }) } catch { /* malformed registry is not retryable */ }
+  const configured = checked?.ok && checked.value.enabled && target && runtime === 'claude'
+  const circuitReady = !!circuit && typeof circuit.preflight === 'function' && typeof circuit.failure === 'function' && typeof circuit.success === 'function'
+  const ceiling = configured ? Math.min(checked.value.maxAttempts, MAX_SAME_TARGET_ATTEMPTS) : 0
+  const targetKey = target && { bridgeHostId, providerId: target.providerId, model: target.actualConfiguredModel }
+  const base = target && {
+    traceId,
+    turnRev,
+    targetProviderId: target.providerId,
+    targetProviderName: target.targetProviderName,
+    requestedModel,
+    actualConfiguredModel: target.actualConfiguredModel,
+    phase: 'same_target',
+  }
+  let started = false
+  let submissions = 0
+  let awaitingOutcome = false
+  let retryEligible = false
+  let outputVisible = false
+  let toolOutputVisible = false
+  let aborted = false
+  let permissionDenied = false
+  let finished = false
+
+  const makeRecord = (outcome, extra = {}, attempt = submissions) => safeTraceRecord({
+    ...base,
+    attempt: Math.max(1, attempt),
+    outcome,
+    ...extra,
+  })
+  const emit = (outcome, extra) => {
+    const record = makeRecord(outcome, extra)
+    try { onRecord?.(record) } catch { /* trace observers are never control flow */ }
+    return record
+  }
+  const blocked = (outcome = 'failed', extra) => ({ admitted: false, record: emit(outcome, extra) })
+  const replaySafe = () => isReplaySafe({ outputVisible, toolOutputVisible, aborted, permissionDenied })
+
+  return {
+    /** Mark the controller as belonging to this turn; no provider work occurs here. */
+    start() { started = true },
+
+    /** Once any assistant/tool output is visible, automatic replay is permanently disabled. */
+    visibleOutput({ tool = false } = {}) {
+      outputVisible = true
+      if (tool) toolOutputVisible = true
+      retryEligible = false
+    },
+
+    /**
+     * Admit exactly one upcoming submission. The cap gate is awaited before
+     * transport, and any false/unknown/throwing result denies the attempt.
+     */
+    async preflight() {
+      if (!started) started = true
+      if (!configured || !circuitReady || finished || awaitingOutcome || submissions >= ceiling) return blocked()
+      if (submissions > 0 && (!retryEligible || !replaySafe())) return blocked()
+      const pending = makeRecord(submissions === 0 ? 'started' : 'retrying', {}, submissions + 1)
+      let admitted = false
+      try {
+        const result = await capGate?.(pending)
+        admitted = result === true || result?.allowed === true
+      } catch { admitted = false }
+      if (!admitted) return blocked('cap_blocked')
+      let circuitState
+      try { circuitState = circuit.preflight(targetKey) } catch { return blocked() }
+      if (!circuitState?.ok) return blocked('circuit_open')
+      submissions += 1
+      awaitingOutcome = true
+      retryEligible = false
+      return { admitted: true, record: emit(submissions === 1 ? 'started' : 'retrying') }
+    },
+
+    /** Classify a raw transport failure locally and expose only a coarse trace. */
+    failure(input = {}) {
+      if (!awaitingOutcome || finished) return null
+      awaitingOutcome = false
+      const failureClass = classifyProviderFailure(input)
+      if (failureClass === 'user_abort') aborted = true
+      if (failureClass === 'permission_denied') permissionDenied = true
+      let circuitUsable = true
+      if (TRANSIENT_FAILURES.has(failureClass)) {
+        try {
+          const state = circuit.failure(targetKey, checked.value, failureClass)
+          if (state?.state === 'open') circuitUsable = false
+        } catch { circuitUsable = false }
+      }
+      retryEligible = circuitUsable && checked.value.retryOn.includes(failureClass) && replaySafe() && submissions < ceiling
+      return emit('failed', { failureClass })
+    },
+
+    /** Close/reset the injected circuit after a completed provider response. */
+    success() {
+      if (!awaitingOutcome || finished) return null
+      awaitingOutcome = false
+      finished = true
+      try { circuit.success(targetKey) } catch { /* a completed response is never replayed */ }
+      return emit('succeeded')
+    },
+  }
+}
+
+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 if (key === 'turnRev') {
+      if (Number.isSafeInteger(input[key]) && input[key] >= 0) out[key] = input[key]
+    } 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} — retrying once before output (attempt ${r.attempt} of ${MAX_SAME_TARGET_ATTEMPTS}).`
+  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/providers.mjs

@@ -43,6 +43,12 @@ import fs from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
 import { claudeish } from './event-id.mjs'
+import {
+  DEFAULT_RESILIENCE_POLICY,
+  resilienceProjection,
+  resolveAttemptTarget,
+  validateResiliencePolicy,
+} from './provider-resilience.mjs'
 
 const DIR       = path.join(os.homedir(), '.thinkpool-pair')
 const REG_FILE  = path.join(DIR, 'providers.json')
@@ -54,7 +60,7 @@ export const BUILTIN_ID = 'anthropic'
 function ensureDir() { try { fs.mkdirSync(DIR, { recursive: true, mode: 0o700 }) } catch { /* noop */ } }
 
 // ── registry load / save ───────────────────────────────────────────────
-/** @returns {Array<{id:string,name:string,baseUrl:string,model?:string,key:string,addedAt:number}>} */
+/** @returns {Array<{id:string,name:string,baseUrl:string,model?:string,key:string,addedAt:number,resilience?:object}>} */
 export function loadProviders() {
   try {
     const arr = JSON.parse(fs.readFileSync(REG_FILE, 'utf8'))
@@ -244,6 +250,9 @@ export function addProviderModel({ id, model, name } = {}) {
     baseUrl: src.baseUrl,   // copied host-side
     model: nextModel,
     key: src.key,           // copied host-side — never re-sent by the client
+    // A cloned credential is not consent to retry it. Each row needs its own
+    // explicit Phase-1 opt-in, even when both rows share the same endpoint/key.
+    resilience: { ...DEFAULT_RESILIENCE_POLICY, retryOn: [...DEFAULT_RESILIENCE_POLICY.retryOn], circuit: { ...DEFAULT_RESILIENCE_POLICY.circuit }, fallback: [] },
     addedAt: Date.now(),
   })
   saveProviders(arr)
@@ -322,6 +331,55 @@ export function providerModel(id) {
   return loadProviders().find((x) => x.id === id)?.model || null
 }
 
+/**
+ * Persist one custom provider row's Phase-1 same-target policy. This is a
+ * host-local primitive: account RPC/UI wiring deliberately lives elsewhere.
+ *
+ * `policy` may be a complete v1 policy, or a boolean for the conservative
+ * Phase-1 preset. Fallback declarations are rejected here: alternate targets
+ * require the later explicit-consent flow, so this API can never turn one on.
+ */
+export function setProviderResiliencePolicy(id, policy) {
+  if (!id || id === BUILTIN_ID) return { ok: false, error: 'the built-in Anthropic provider cannot use resilience policy' }
+  const arr = loadProviders()
+  const provider = arr.find((p) => p.id === id)
+  if (!provider) return { ok: false, error: 'no such provider' }
+
+  const input = typeof policy === 'boolean'
+    ? { ...DEFAULT_RESILIENCE_POLICY, enabled: policy, retryOn: [...DEFAULT_RESILIENCE_POLICY.retryOn], circuit: { ...DEFAULT_RESILIENCE_POLICY.circuit }, fallback: [] }
+    : policy
+  const checked = validateResiliencePolicy(input, { providers: arr, primaryProviderId: id })
+  if (!checked.ok) return { ok: false, error: checked.error }
+  if (checked.value.fallback.length) return { ok: false, error: 'fallback is not available in Phase 1' }
+  // An enabled controller must have a configured exact model for its safe
+  // target record. A disabled policy remains valid for legacy/no-model rows.
+  if (checked.value.enabled && !resolveAttemptTarget({ providers: arr, providerId: id, model: provider.model })) {
+    return { ok: false, error: 'an enabled resilience policy requires an exact configured model' }
+  }
+
+  const next = arr.map((p) => p.id === id ? { ...p, resilience: checked.value } : p)
+  saveProviders(next)
+  return { ok: true, resilience: resilienceProjection(checked.value) }
+}
+
+/**
+ * Resolve a custom provider's persisted policy for bridge wiring without ever
+ * returning host credentials or endpoint data. Missing policy is safely
+ * disabled; malformed stored policy, built-in, unknown, and model-less targets
+ * fail closed with null.
+ */
+export function resolveProviderResiliencePolicy(id) {
+  if (!id || id === BUILTIN_ID) return null
+  const providers = loadProviders()
+  const provider = providers.find((p) => p.id === id)
+  if (!provider) return null
+  const checked = validateResiliencePolicy(provider.resilience, { providers, primaryProviderId: id })
+  if (!checked.ok) return null
+  const target = resolveAttemptTarget({ providers, providerId: id, model: provider.model })
+  if (!target) return null
+  return { policy: resilienceProjection(checked.value), target }
+}
+
 // ── read-only projections (never expose the raw key) ────────────────────
 /** Masked list for the dashboard: keyHint = last 4 chars only. Built-in first. */
 export function listProviders() {
@@ -331,8 +389,9 @@ export function listProviders() {
     model: p.model || null,
     group: providerGroup(p),
     keyHint: keyHint(p.key),
+    resilience: resilienceProjection(p.resilience),
   }))
-  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null, group: BUILTIN_ID, keyHint: null }, ...custom]
+  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null, group: BUILTIN_ID, keyHint: null, resilience: null }, ...custom]
 }
 
 /** Name-only projection for the announce/presence payload — NO key, NO baseUrl. */

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