@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/key-secrets-guard.ts

@@ -0,0 +1,52 @@
+// Key lanes K1, QA B1 (main session decision, 2026-10-19): while key lanes are ENABLED and a key
+// is saved, every Claude spawn that can use tools gets deny rules for the key secrets directory,
+// as one `--settings` layer (deny rules from every layer apply; a flag layer cannot be turned off
+// by a user or project settings file).
+//
+//   Read, Edit, Write   the directory and everything under it, by its path and its real path
+//   Bash                any command line naming the directory or the key file
+//
+// This narrows, it does not wall off: a process running on this Mac as the same user can still
+// read a file the server can read (a Bash line that builds the path, another app, Codex, whose
+// sandbox has no read exclusion). That residual risk is stated plainly in key-notices.ts
+// (KEY_LANE_SAME_MAC_COPY) and the CHANGELOG; the provider's own spending limit is the real stop.
+//
+// HARD RULE: with key lanes off this returns [] before touching the disk, so every spawn's argv is
+// byte-identical to 6.79.1. Enabled with no key saved, there is nothing to protect: [] too.
+import { existsSync, realpathSync } from 'node:fs'
+import { keyLanesEnabled } from './key-lanes.js'
+import { KEY_SECRETS_DIR, KEY_STORE_FILE, keySecretsDir, keyStorePath } from './key-store.js'
+
+/** The deny rules for the secrets directory (exported for the tests and the real-CLI canary). */
+export function keySecretsDenyRules(dir: string = keySecretsDir()): string[] {
+  const dirs = new Set([dir])
+  try { dirs.add(realpathSync(dir)) } catch { /* not created yet: the plain path still applies */ }
+  const rules: string[] = []
+  for (const d of dirs) {
+    // `//abs/path` is Claude Code's absolute-path form for Read, Edit and Write rules.
+    for (const tool of ['Read', 'Edit', 'Write']) rules.push(`${tool}(/${d}/**)`)
+  }
+  rules.push(`Bash(*${KEY_SECRETS_DIR}*)`, `Bash(*${KEY_STORE_FILE}*)`)
+  return rules
+}
+
+/**
+ * Canary R12: settings `env` names a keyed (Lane B) run forces, whatever a user or project settings
+ * file says. A flag `--settings` layer outranks both (MU's project file turns agent teams on).
+ */
+export const LANE_B_FORCED_SETTINGS_ENV: Readonly<Record<string, string>> = {
+  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '0',
+}
+
+/**
+ * `['--settings', <JSON>]` while lanes are enabled and a key is saved, else []. A keyed run
+ * (`laneB`) also gets LANE_B_FORCED_SETTINGS_ENV in the same layer (one `--settings` per spawn).
+ */
+export function claudeKeySecretsGuardArgs(opts: { laneB?: boolean } = {}): string[] {
+  if (!keyLanesEnabled()) return []
+  if (!existsSync(keyStorePath())) return []
+  return ['--settings', JSON.stringify({
+    permissions: { deny: keySecretsDenyRules() },
+    ...(opts.laneB ? { env: { ...LANE_B_FORCED_SETTINGS_ENV } } : {}),
+  })]
+}

package/server/lib/key-store.ts

@@ -0,0 +1,228 @@
+// Key lanes (K1, plan v4 sections 4, 10.3, 12): the saved provider keys, `data/key-secrets/provider-keys.json`
+// (QA B1: a dedicated 0700 directory, so the deny rules every Claude spawn gets name one place).
+//
+// The only file on the Mac that holds a real key. 0600, written atomically into the 0700 data
+// dir, never followed through a symlink. Nothing here logs a secret, and the only function that
+// returns one is readKeySecretForRelay (P2's relay and P5's in-process direct lane). Routes,
+// health, diagnostics and ledgers get PublicKeyRecord: ref, kind, last 4, cap, times.
+//
+// Reading never creates: a missing file is an empty store, a corrupt one reads as empty and is
+// left exactly where it is.
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmdirSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { DATA_DIR, dataPath } from './data-dir.js'
+import type { KeyKind, KeyRef, PublicKeyRecord } from './key-relay-contract.js'
+import { KEY_KINDS, KEY_REF_RE } from './key-relay-contract.js'
+
+export const KEY_STORE_FILE = 'provider-keys.json'
+/** QA B1: the secrets live alone in this 0700 directory under the data dir. */
+export const KEY_SECRETS_DIR = 'key-secrets'
+export const DEFAULT_KEY_CAP_USD = 1.0
+export const KEY_CAP_LIMITS = { minUsd: 0.01, maxUsd: 1000 } as const
+const MAX_SECRET_CHARS = 512
+
+interface StoredKey extends PublicKeyRecord {
+  secret: string
+}
+interface KeyStoreFile {
+  v: 1
+  keys: StoredKey[]
+}
+
+export function keySecretsDir(): string {
+  return dataPath(KEY_SECRETS_DIR)
+}
+
+export function keyStorePath(): string {
+  return join(keySecretsDir(), KEY_STORE_FILE)
+}
+
+/** Parse a private JSON state file without creating, repairing or moving anything. */
+export function readPrivateJsonFile(file: string): unknown {
+  if (!existsSync(file)) return undefined
+  const st = lstatSync(file)
+  if (st.isSymbolicLink() || !st.isFile()) return undefined
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return undefined }
+}
+
+/** Atomic 0600 write into its 0700 directory (the data dir, or the key secrets dir). */
+export function writePrivateJsonFile(file: string, value: unknown): void {
+  mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 })
+  const dir = dirname(file)
+  if (dir !== DATA_DIR) {
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error('refusing to write through a symlinked directory')
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    chmodSync(dir, 0o700)
+  }
+  if (existsSync(file) && lstatSync(file).isSymbolicLink()) throw new Error('refusing to write through a symlink')
+  durableAtomicWriteFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 })
+}
+
+function isStoredKey(v: unknown): v is StoredKey {
+  if (!v || typeof v !== 'object') return false
+  const k = v as Partial<StoredKey>
+  return typeof k.ref === 'string' && KEY_REF_RE.test(k.ref)
+    && typeof k.kind === 'string' && (KEY_KINDS as readonly string[]).includes(k.kind)
+    && typeof k.secret === 'string' && k.secret.length > 0
+    && typeof k.capUsd === 'number' && Number.isFinite(k.capUsd)
+    && typeof k.savedAt === 'string'
+}
+
+let cache: { stamp: string; keys: StoredKey[] } | null = null
+
+function readStore(): StoredKey[] {
+  const file = keyStorePath()
+  let stamp: string
+  try {
+    const st = statSync(file)
+    stamp = `${st.ino}:${st.size}:${st.mtimeMs}`
+  } catch {
+    cache = null
+    return []
+  }
+  if (cache?.stamp === stamp) return cache.keys
+  const parsed = readPrivateJsonFile(file) as Partial<KeyStoreFile> | undefined
+  const keys = parsed && Array.isArray(parsed.keys) ? parsed.keys.filter(isStoredKey) : []
+  cache = { stamp, keys }
+  return keys
+}
+
+function writeStore(keys: StoredKey[]): void {
+  const body: KeyStoreFile = { v: 1, keys }
+  writePrivateJsonFile(keyStorePath(), body)
+  cache = null
+}
+
+function toPublic(k: StoredKey): PublicKeyRecord {
+  return {
+    ref: k.ref,
+    kind: k.kind,
+    last4: k.last4,
+    capUsd: k.capUsd,
+    savedAt: k.savedAt,
+    ...(k.validatedAt ? { validatedAt: k.validatedAt } : {}),
+    ...(k.kind === 'openai-compatible' && k.baseUrl ? { baseUrl: k.baseUrl } : {}),
+  }
+}
+
+export function listPublicKeys(): PublicKeyRecord[] {
+  return readStore().map(toPublic)
+}
+
+export function getPublicKey(ref: string): PublicKeyRecord | undefined {
+  const k = readStore().find(x => x.ref === ref)
+  return k ? toPublic(k) : undefined
+}
+
+/** P2 relay and P5 direct lane ONLY. No route, health field, log or diagnostic may call this. */
+export function readKeySecretForRelay(ref: KeyRef): string | null {
+  return readStore().find(x => x.ref === ref)?.secret ?? null
+}
+
+// ── Validation (shape only; the provider check is in routes/key-lanes.ts) ──
+
+export function isKeyKind(v: unknown): v is KeyKind {
+  return typeof v === 'string' && (KEY_KINDS as readonly string[]).includes(v)
+}
+
+/** A plain-language refusal, or null when the secret has the right shape for its kind. */
+export function keyShapeProblem(kind: KeyKind, secret: unknown): string | null {
+  if (typeof secret !== 'string' || !secret.trim()) return 'Paste the key.'
+  const s = secret.trim()
+  if (s.length > MAX_SECRET_CHARS || /\s/.test(s) || !/^[\x21-\x7e]+$/.test(s)) return 'That does not look like a key. Paste it again.'
+  if (kind === 'openrouter' && !s.startsWith('sk-or-')) return 'That is not an OpenRouter key. It starts with sk-or-.'
+  if (kind === 'anthropic' && !s.startsWith('sk-ant-')) return 'That is not an Anthropic key. It starts with sk-ant-.'
+  if (kind === 'openai' && !s.startsWith('sk-')) return 'That is not an OpenAI key. It starts with sk-.'
+  if (s.length < 20) return 'That key is too short. Paste the whole key.'
+  return null
+}
+
+/** A cap in USD rounded to cents, or null when out of range. Absent means the default. */
+export function normalizeCapUsd(v: unknown): number | null {
+  if (v === undefined) return DEFAULT_KEY_CAP_USD
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null
+  const cents = Math.round(v * 100) / 100
+  return cents >= KEY_CAP_LIMITS.minUsd && cents <= KEY_CAP_LIMITS.maxUsd ? cents : null
+}
+
+/** A custom OpenAI-compatible base URL (Mac only), normalized without a trailing slash, or null. */
+/** 127.0.0.0/8, ::1 and localhost. */
+export function isLoopbackHost(hostname: string): boolean {
+  const h = hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  return h === 'localhost' || h === '::1' || /^127(?:\.\d{1,3}){3}$/.test(h)
+}
+
+export function normalizeCompatibleBaseUrl(v: unknown): string | null {
+  if (typeof v !== 'string' || v.length > 300) return null
+  try {
+    const u = new URL(v.trim())
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return null
+    // QA N5: plain http only to this Mac (a local model server); anything remote is https.
+    if (u.protocol === 'http:' && !isLoopbackHost(u.hostname)) return null
+    if (u.username || u.password || u.search || u.hash) return null
+    return u.toString().replace(/\/+$/, '')
+  } catch {
+    return null
+  }
+}
+
+export interface SaveKeyInput {
+  kind: KeyKind
+  secret: string
+  capUsd: number
+  validatedAt?: string
+  baseUrl?: string
+}
+
+/** Save a validated key. The same secret saved twice keeps its ref (cap and times refresh). */
+export function saveKey(input: SaveKeyInput, now: () => Date = () => new Date()): PublicKeyRecord {
+  const secret = input.secret.trim()
+  const keys = [...readStore()]
+  const at = now().toISOString()
+  const existing = keys.findIndex(k => k.kind === input.kind && k.secret === secret)
+  const record: StoredKey = {
+    ref: existing >= 0 ? keys[existing].ref : `key_${randomBytes(6).toString('hex')}`,
+    kind: input.kind,
+    secret,
+    last4: secret.slice(-4),
+    capUsd: input.capUsd,
+    savedAt: existing >= 0 ? keys[existing].savedAt : at,
+    ...(input.validatedAt ? { validatedAt: input.validatedAt } : {}),
+    ...(input.kind === 'openai-compatible' && input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+  }
+  if (existing >= 0) keys[existing] = record
+  else keys.push(record)
+  writeStore(keys)
+  return toPublic(record)
+}
+
+/** Change one key's daily cap (Control's last saved value is the one that counts, plan 4.5). */
+export function updateKeyCap(ref: string, capUsd: number): PublicKeyRecord | undefined {
+  const keys = [...readStore()]
+  const i = keys.findIndex(k => k.ref === ref)
+  if (i < 0) return undefined
+  keys[i] = { ...keys[i], capUsd }
+  writeStore(keys)
+  return toPublic(keys[i])
+}
+
+/** Remove one key (plan 17 item 3): the store is rewritten atomically without it. True when it existed. */
+export function deleteKey(ref: string): boolean {
+  const keys = readStore()
+  const next = keys.filter(k => k.ref !== ref)
+  if (next.length === keys.length) return false
+  writeStore(next)
+  return true
+}
+
+/** Remove all keys (plan 12). True when a file was deleted. */
+export function deleteKeyStore(): boolean {
+  cache = null
+  const file = keyStorePath()
+  if (!existsSync(file)) return false
+  unlinkSync(file)
+  try { rmdirSync(keySecretsDir()) } catch { /* not empty or already gone */ }
+  return true
+}

package/server/lib/keyed-sessions.ts

@@ -0,0 +1,154 @@
+// Key lanes K1 P3 (plan v4 7.3, W11): the CLI sessions that ran on a key, `data/keyed-sessions.json`.
+//
+// A Lane B Claude turn writes its transcript into the shared ~/.claude/projects, where COS
+// Control's Continue and Fork, a handoff pickup, and an attach would otherwise resume it on the
+// subscription. Every Claude CLI session id (and, from P4, Codex thread id) created under a
+// profile is recorded here with its profile id, and those entry points refuse it with 409
+// `keyed_session`.
+//
+// The file is written only by a keyed turn, so with key lanes never used it never exists and
+// every check below is one failed stat. Reading never creates. Remove all keys (plan 12) keeps
+// this file on purpose: a keyed transcript stays refused after the keys are gone. A manual
+// `claude --resume` in a terminal is documented, not blocked.
+import { statSync } from 'node:fs'
+import { dataPath } from './data-dir.js'
+import { readPrivateJsonFile, writePrivateJsonFile } from './key-store.js'
+import { registerKeyLanesStatusProvider } from './key-lanes.js'
+import type { RelayEngine } from './key-relay-contract.js'
+
+export const KEYED_SESSIONS_FILE = 'keyed-sessions.json'
+/** Far past any real use; the oldest entries go first past it. */
+export const MAX_KEYED_SESSIONS = 20_000
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+
+/** The 409 body every refusing entry point returns (plan 7.3, 11.3). */
+export const KEYED_SESSION_REFUSAL = {
+  error: 'keyed_session',
+  message: 'This session ran on your key. Continue it from COS.',
+} as const
+
+export interface KeyedSessionRecord {
+  /** The Claude CLI session id or Codex thread id. */
+  id: string
+  engine: RelayEngine
+  profileId: string
+  /** The COS conversation the turn belonged to, when known. */
+  cosSessionId?: string
+  recordedAt: string
+}
+
+interface KeyedSessionsFile {
+  v: 1
+  sessions: KeyedSessionRecord[]
+}
+
+export function keyedSessionsPath(): string {
+  return dataPath(KEYED_SESSIONS_FILE)
+}
+
+function isRecord(v: unknown): v is KeyedSessionRecord {
+  if (!v || typeof v !== 'object') return false
+  const r = v as Partial<KeyedSessionRecord>
+  return typeof r.id === 'string' && SESSION_ID_RE.test(r.id)
+    && (r.engine === 'claude' || r.engine === 'codex')
+    && typeof r.profileId === 'string'
+    && typeof r.recordedAt === 'string'
+}
+
+// Ids recorded this boot. A failed write still refuses for the rest of the boot.
+const memory = new Map<string, KeyedSessionRecord>()
+let cache: { stamp: string; records: KeyedSessionRecord[] } | null = null
+
+function fileRecords(): KeyedSessionRecord[] {
+  const file = keyedSessionsPath()
+  let stamp: string
+  try {
+    const st = statSync(file)
+    stamp = `${st.ino}:${st.size}:${st.mtimeMs}`
+  } catch {
+    cache = null
+    return []
+  }
+  if (cache?.stamp === stamp) return cache.records
+  const parsed = readPrivateJsonFile(file) as Partial<KeyedSessionsFile> | undefined
+  const records = parsed && Array.isArray(parsed.sessions) ? parsed.sessions.filter(isRecord) : []
+  cache = { stamp, records }
+  return records
+}
+
+export function listKeyedSessions(): KeyedSessionRecord[] {
+  const byId = new Map<string, KeyedSessionRecord>()
+  for (const r of fileRecords()) byId.set(r.id, r)
+  for (const r of memory.values()) if (!byId.has(r.id)) byId.set(r.id, r)
+  return [...byId.values()]
+}
+
+/** True once anything was ever recorded. The cheap short-circuit every refusing site starts with. */
+export function anyKeyedSessions(): boolean {
+  return memory.size > 0 || fileRecords().length > 0
+}
+
+export function isKeyedSession(id: unknown): boolean {
+  if (typeof id !== 'string' || !id) return false
+  if (memory.has(id)) return true
+  return fileRecords().some(r => r.id === id)
+}
+
+/** True when any keyed CLI session belongs to this COS conversation. */
+export function isKeyedCosSession(cosSessionId: unknown): boolean {
+  if (typeof cosSessionId !== 'string' || !cosSessionId) return false
+  return listKeyedSessions().some(r => r.cosSessionId === cosSessionId)
+}
+
+/** Canary R7: the key profile a recorded CLI session ran under, by session id (any case), or undefined. */
+export function keyedSessionProfile(id: unknown): string | undefined {
+  if (typeof id !== 'string' || !id) return undefined
+  const needle = id.toLowerCase()
+  for (const r of memory.values()) if (r.id.toLowerCase() === needle) return r.profileId
+  return fileRecords().find(r => r.id.toLowerCase() === needle)?.profileId
+}
+
+export function keyedSessionIds(): string[] {
+  return listKeyedSessions().map(r => r.id)
+}
+
+/**
+ * Record a session created under a profile. Idempotent per id. 0600, atomic. Called by the
+ * bridge the moment the CLI names its session, before any answer text.
+ */
+export function recordKeyedSession(input: {
+  id: string
+  engine: RelayEngine
+  profileId: string
+  cosSessionId?: string
+}, now: () => Date = () => new Date()): void {
+  if (!SESSION_ID_RE.test(input.id)) return
+  const record: KeyedSessionRecord = {
+    id: input.id,
+    engine: input.engine,
+    profileId: input.profileId,
+    ...(input.cosSessionId ? { cosSessionId: input.cosSessionId } : {}),
+    recordedAt: now().toISOString(),
+  }
+  if (!memory.has(input.id)) memory.set(input.id, record)
+  const records = fileRecords()
+  if (records.some(r => r.id === input.id)) return
+  const next = [...records, record].slice(-MAX_KEYED_SESSIONS)
+  try {
+    const body: KeyedSessionsFile = { v: 1, sessions: next }
+    writePrivateJsonFile(keyedSessionsPath(), body)
+    cache = null
+  } catch (err) {
+    // The id stays refused in memory for this boot; the next keyed turn retries the write.
+    console.error(`[keyed-sessions] could not persist a keyed session: ${err instanceof Error ? err.message : err}`)
+  }
+}
+
+/** Tests only. */
+export function __resetKeyedSessionsForTests(): void {
+  memory.clear()
+  cache = null
+}
+
+// P1's status route reads this while lanes are enabled. In-memory registration only.
+registerKeyLanesStatusProvider({ keyedSessionIds })

package/server/lib/lane-b-env.ts

@@ -0,0 +1,169 @@
+// Key lanes K1 P3 (plan v4 sections 4.4, 7.1, 7.2): the Lane B Claude child environment and the
+// checks a keyed Claude turn passes before anything is spawned.
+//
+// Lane B runs the user's Claude Code CLI with the full harness, but pointed at the loopback relay
+// (P2) instead of the subscription. The child never sees a real key: it gets a turn nonce that
+// works only on 127.0.0.1, only during the turn, only under the cap.
+//
+// HARD RULE (zero impact without a key): nothing here runs unless a caller passes a key profile.
+// Importing this module reads no file, opens no socket and starts no timer.
+import { keyLanesActive } from './key-lanes.js'
+import { KEY_LANE_REFUSAL_COPY } from './key-notices.js'
+import { getPublicKey } from './key-store.js'
+import { claudeSettingsRefusal, claudeSettingsWatched } from './claude-settings-guard.js'
+import { KEY_LANE_CHILD_ENV, RELAY_BASE_PATHS } from './key-relay-contract.js'
+import type { KeyKind, KeyProfile, KeyRelay } from './key-relay-contract.js'
+
+/**
+ * Provider-credential names a Lane B child never inherits (plan 7.2). Every other name (PATH,
+ * HOME, COS_API_TOKEN, MCP and hook settings) is kept, unlike dictationChildEnv, which strips
+ * every *API_KEY and rewrites PATH.
+ */
+export const LANE_B_STRIPPED_NAMES: readonly string[] = [
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_MODEL',
+  'ANTHROPIC_SMALL_FAST_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS',
+  'OPENAI_API_KEY',
+  'OPENAI_BASE_URL',
+  'OPENROUTER_API_KEY',
+  // QA W4: other ways a child authenticates to someone else.
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'ANTHROPIC_CUSTOM_HEADERS',
+  'AWS_BEARER_TOKEN_BEDROCK',
+]
+/** Plus every `ANTHROPIC_DEFAULT_<TIER>_MODEL`, whatever the tier is called. */
+export const LANE_B_STRIPPED_PATTERN = /^ANTHROPIC_DEFAULT_[A-Z0-9_]+_MODEL$/
+
+export function isLaneBStrippedName(name: string): boolean {
+  return LANE_B_STRIPPED_NAMES.includes(name) || LANE_B_STRIPPED_PATTERN.test(name)
+}
+
+/** Plan 4.4: every model name the CLI may read is the profile slug. ANTHROPIC_MODEL is never set: the slug goes on `--model`. */
+export const LANE_B_CLAUDE_MODEL_NAMES: readonly string[] = [
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_SMALL_FAST_MODEL',
+  'CLAUDE_CODE_SUBAGENT_MODEL',
+]
+/** Plan 4.6: the child retries a 429 or 5xx twice; the relay never retries itself. */
+export const LANE_B_CLAUDE_MAX_RETRIES = '2'
+
+/** The names applyLaneBClaudeEnv sets. With LANE_B_STRIPPED_NAMES this is the whole A-vs-B difference. */
+export const LANE_B_CLAUDE_ADDED_NAMES: readonly string[] = [
+  KEY_LANE_CHILD_ENV.claudeBaseUrl,
+  KEY_LANE_CHILD_ENV.claudeToken,
+  'ANTHROPIC_API_KEY',
+  'CLAUDE_CODE_MAX_RETRIES',
+  ...LANE_B_CLAUDE_MODEL_NAMES,
+  KEY_LANE_CHILD_ENV.profileMarker,
+]
+
+const LOOPBACK_ORIGIN_RE = /^http:\/\/127\.0\.0\.1:\d{1,5}$/
+
+/** A copy of `base` minus the provider-credential names. `base` is never written. */
+export function laneBBaseEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = { ...base }
+  for (const name of Object.keys(env)) {
+    if (isLaneBStrippedName(name)) delete env[name]
+  }
+  return env
+}
+
+export interface LaneBClaudeEnvSpec {
+  /** The relay's `http://127.0.0.1:<port>` for this boot. */
+  origin: string
+  nonce: string
+  /** The profile's model slug. */
+  slug: string
+  profileId: string
+}
+
+/**
+ * Point a child env object (a copy, never process.env) at the relay. Strips the credential
+ * names, then sets the relay base URL, the nonce as the Bearer, an empty API key, the retry
+ * count, every model name to the slug and the profile marker. Agent teams stay off (stripped,
+ * never re-added). Throws on a non-loopback origin: the relay only ever listens on 127.0.0.1.
+ */
+export function applyLaneBClaudeEnv(env: NodeJS.ProcessEnv, spec: LaneBClaudeEnvSpec): void {
+  if (env === process.env) throw new Error('lane-b-env: refusing to write process.env')
+  if (!LOOPBACK_ORIGIN_RE.test(spec.origin)) throw new Error('lane-b-env: the relay origin is not loopback')
+  if (!spec.nonce || !spec.slug || !spec.profileId) throw new Error('lane-b-env: incomplete spec')
+  for (const name of Object.keys(env)) {
+    if (isLaneBStrippedName(name)) delete env[name]
+  }
+  env[KEY_LANE_CHILD_ENV.claudeBaseUrl] = spec.origin + RELAY_BASE_PATHS.claude
+  env[KEY_LANE_CHILD_ENV.claudeToken] = spec.nonce
+  env.ANTHROPIC_API_KEY = ''
+  env.CLAUDE_CODE_MAX_RETRIES = LANE_B_CLAUDE_MAX_RETRIES
+  for (const name of LANE_B_CLAUDE_MODEL_NAMES) env[name] = spec.slug
+  env[KEY_LANE_CHILD_ENV.profileMarker] = spec.profileId
+}
+
+// ── The relay seam ──────────────────────────────────────────────────────────
+// P2 owns the relay; this package consumes only the KeyRelay contract. P11 wires the real one
+// in index.ts (`registerLaneBRelay(() => getKeyRelay())` or similar). Unregistered, every keyed
+// turn is refused before spawn: there is no fallback to the subscription.
+
+type RelayResolver = () => KeyRelay | Promise<KeyRelay>
+let relayResolver: RelayResolver | null = null
+
+export function registerLaneBRelay(resolver: RelayResolver | null): void {
+  relayResolver = resolver
+}
+
+export function laneBRelayRegistered(): boolean {
+  return relayResolver !== null
+}
+
+export async function laneBRelay(): Promise<KeyRelay> {
+  if (!relayResolver) throw new Error('lane-b-env: no key relay registered')
+  return await relayResolver()
+}
+
+// ── Lens copy ───────────────────────────────────────────────────────────────
+// P8's key-notices.ts is the single source of key-lane strings (P11 moved these lines there).
+export const LANE_B_COPY = {
+  lanesOff: KEY_LANE_REFUSAL_COPY.lanesOff,
+  profileOff: KEY_LANE_REFUSAL_COPY.profileOff,
+  wrongEngine: KEY_LANE_REFUSAL_COPY.wrongEngineClaude,
+  keyMissing: KEY_LANE_REFUSAL_COPY.keyMissing,
+  scheduled: KEY_LANE_REFUSAL_COPY.scheduled,
+  relayUnavailable: KEY_LANE_REFUSAL_COPY.relayUnavailable,
+} as const
+
+export type LaneBClaudePreflight = { ok: true; keyKind: KeyKind } | { ok: false; message: string }
+
+/**
+ * Everything a keyed Claude turn must pass before it touches history, the run ledger or a
+ * process (plan 7.1, 7.2). Fails closed: any refusal ends the turn with its lens line and the
+ * subscription is never used instead.
+ */
+export function laneBClaudePreflight(input: {
+  profile: KeyProfile
+  dispatch: boolean
+  cwd: string
+  home?: string
+}): LaneBClaudePreflight {
+  const { profile } = input
+  if (!keyLanesActive()) return { ok: false, message: LANE_B_COPY.lanesOff }
+  if (profile.engine !== 'claude') return { ok: false, message: LANE_B_COPY.wrongEngine(profile.label) }
+  if (!profile.enabled) return { ok: false, message: LANE_B_COPY.profileOff(profile.label) }
+  if (input.dispatch) return { ok: false, message: LANE_B_COPY.scheduled }
+  const key = getPublicKey(profile.keyRef)
+  if (!key) return { ok: false, message: LANE_B_COPY.keyMissing(profile.label) }
+  const settings = claudeSettingsRefusal({ cwd: input.cwd, home: input.home })
+  if (settings) return { ok: false, message: settings.message }
+  for (const w of claudeSettingsWatched({ cwd: input.cwd, home: input.home })) {
+    console.info(`[key-lanes] ${w.name} is set by a Claude settings file; this keyed run forces it off`)
+  }
+  if (!laneBRelayRegistered()) return { ok: false, message: LANE_B_COPY.relayUnavailable }
+  return { ok: true, keyKind: key.kind }
+}