@gotcos/glasses-server 6.79.1 → 6.80.0

package/server/lib/codex-bridge.ts

@@ -86,6 +86,24 @@ import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
 import { teeJobTrail } from './job-trail.js'
 import { applyTurnRequestEnv, createTurnRequestBinding, spawnWithTurnRequest } from './turn-request.js'
+// Key lanes K1 P4 (plan v4 8): Lane B Codex. Every use below sits behind `options.keyProfile`;
+// without one, argv, env, the catalog read and the resume binding are the 963fe25 ones.
+import { randomUUID } from 'node:crypto'
+import { profilePreference } from '../../shared/key-preference.js'
+import type { AnswerKeyFields, KeyKind, KeyProfile, RelayTurnHandle } from './key-relay-contract.js'
+import { getSharedKeyMeter } from './key-relay-meter.js'
+import {
+  CODEX_LANE_B_COPY,
+  CODEX_RELAY_PROVIDER_ID,
+  applyCodexLaneBEnv,
+  codexKeyRelay,
+  codexProfilePreflight,
+  recordKeyedCodexThread,
+  renderCodexProfileHome,
+  writeCodexProfileHome,
+  type CodexKeyLaneCallOptions,
+  type RenderedCodexProfileHome,
+} from './codex-profile-home.js'
 
 const INACTIVITY_MS = 180_000
 const WALL_MAX_MS = 900_000
@@ -240,6 +258,50 @@ export function buildCodexExecArgs(input: {
   return args
 }
 
+/**
+ * Key lanes (plan v4 8.1): argv for a keyed Codex turn. The user's COS_CODEX_EXTRA_ARGS, the
+ * ChatGPT model catalog and its effort and service-tier settings never reach it: the profile's
+ * slug goes on `--model` and the generated home's relay is selected as the provider. Sandbox,
+ * publisher directory, resume and image handling are the subscription ones.
+ */
+export function buildCodexProfileExecArgs(input: {
+  codexCwd: string
+  imagePaths?: string[]
+  persistentCodexSession: boolean
+  codexThreadId?: string
+  profileModel: string
+  publisherWritableDirectory?: string
+}): string[] {
+  const imagePaths = input.imagePaths ?? []
+  const args = ['exec', ...codexSandboxArgs()]
+  if (input.publisherWritableDirectory) {
+    args.push('--add-dir', input.publisherWritableDirectory)
+  }
+  // A trusted project's own config could name another provider; argv wins over every layer.
+  args.push('-c', `model_provider="${CODEX_RELAY_PROVIDER_ID}"`)
+  if (input.codexThreadId) {
+    args.push('resume', '--json', '--all', '--model', input.profileModel)
+    for (const p of imagePaths) args.push('--image', p)
+    args.push(input.codexThreadId, '-')
+    return args
+  }
+  args.push('--json', '--cd', input.codexCwd, '--model', input.profileModel)
+  if (!input.persistentCodexSession) args.push('--ephemeral')
+  for (const p of imagePaths) args.push('--image', p)
+  args.push('-')
+  return args
+}
+
+/** Key lanes: a spawn that throws synchronously revokes the turn's nonce. Without one it is the call itself. */
+function withKeyTurnRevokedOnThrow<T>(keyTurn: RelayTurnHandle | null, run: () => T): T {
+  try {
+    return run()
+  } catch (err) {
+    keyTurn?.revoke('cancel')
+    throw err
+  }
+}
+
 function buildCodexPrompt(systemPrompt: string, fullQuery: string): string {
   return [
     'SYSTEM INSTRUCTIONS',
@@ -300,6 +362,23 @@ function toolStatus(event: any): string | undefined {
   return undefined
 }
 
+/**
+ * Key lanes: the Codex runner in P6's engine-seam shape (`registerKeyProfileEngine('codex', ...)`
+ * in key-profile-routing.ts; P11 wires it). The turn's profile rides `options.keyProfile`.
+ */
+export function runCodexKeyProfileTurn(
+  query: string,
+  sessionId: string,
+  callbacks: StreamCallbacks,
+  turn: { profile: KeyProfile },
+  images?: ModelImageInput[],
+  reference?: PromptReference,
+  globalMsgNum?: number,
+  options?: CallOptions,
+): Promise<string> {
+  return callCodexStreaming(query, sessionId, callbacks, undefined, images, reference, globalMsgNum, { ...options, keyProfile: turn.profile })
+}
+
 function safeCodexUserError(message: string): string {
   const code = classifyCodexError(message)
   if (code === 'codex.cli_unavailable') return 'Codex CLI unavailable. Check server Settings.'
@@ -317,27 +396,55 @@ export async function callCodexStreaming(
   images?: ModelImageInput[],
   reference?: PromptReference,
   globalMsgNum?: number,
-  options?: CallOptions,
+  options?: CallOptions & CodexKeyLaneCallOptions,
 ): Promise<string> {
   const sid = getOrCreateSession(sessionId)
-  // Refresh is TTL-cached and coalesced, so every run sees the newest known
-  // catalog without creating duplicate app-server discovery processes.
-  await getCodexModelCatalog()
+  // Key lanes: a keyed turn passes every check before history, the run ledger or a process, and
+  // never reads the ChatGPT catalog or COS_CODEX_EXTRA_ARGS. A refusal ends the turn with its lens
+  // line; the subscription is never the fallback.
+  const keyProfile = options?.keyProfile
+  let keyKind: KeyKind | null = null
+  let profileHome: RenderedCodexProfileHome | null = null
+  if (keyProfile) {
+    const preflight = codexProfilePreflight({ profile: keyProfile, dispatch: !!options?.dispatch, cwd: getCodexExecutionCwd() })
+    if (!preflight.ok) {
+      await callbacks.onError(preflight.message)
+      return sid
+    }
+    keyKind = preflight.keyKind
+    try {
+      profileHome = renderCodexProfileHome(keyProfile)
+    } catch (err) {
+      console.error(`[codex-bridge] key profile home render failed: ${err instanceof Error ? err.message.slice(0, 200) : 'unknown'}`)
+      await callbacks.onError(CODEX_LANE_B_COPY.relayUnavailable)
+      return sid
+    }
+  } else {
+    // Refresh is TTL-cached and coalesced, so every run sees the newest known
+    // catalog without creating duplicate app-server discovery processes.
+    await getCodexModelCatalog()
+  }
   if (options?.abortSignal?.aborted) {
     throw new Error('codex-bridge: client disconnected before Codex started.')
   }
   let extra: string[]
-  try {
-    extra = parseCodexExtraArgs(process.env.COS_CODEX_EXTRA_ARGS)
-    assertSafeCodexExtraArgs(extra)
-  } catch (error) {
-    if (error instanceof CodexExtraArgsError) {
-      await callbacks.onError(error.message)
-      return sid
+  if (keyProfile) {
+    extra = []
+  } else {
+    try {
+      extra = parseCodexExtraArgs(process.env.COS_CODEX_EXTRA_ARGS)
+      assertSafeCodexExtraArgs(extra)
+    } catch (error) {
+      if (error instanceof CodexExtraArgsError) {
+        await callbacks.onError(error.message)
+        return sid
+      }
+      throw error
     }
-    throw error
   }
-  const extraFingerprint = codexEngineFingerprint(extra)
+  // Plan 8.1 resume binding: a keyed thread resumes only under its own profile and generated
+  // config, and a subscription turn never resumes it (nor a keyed turn a subscription thread).
+  const extraFingerprint = profileHome ? profileHome.engineFingerprint : codexEngineFingerprint(extra)
   const history = getHistory(sid)
   const session = getSessionRaw(sid)
   const contextBreaks = session?.contextBreaks ?? []
@@ -346,8 +453,11 @@ export async function callCodexStreaming(
   const persistentCodexSession = isCodexPersistenceEnabled()
   const codexCwd = getCodexExecutionCwd()
   const codexTrustMode = getCodexTrustMode()
-  const resolvedCodexModel = resolveCodexModelOption(model)
-  const resolvedCodexEffort = resolveCodexEffortForModel(resolvedCodexModel, options?.effort)
+  // A keyed turn's model is the profile slug; the catalog is never consulted for it.
+  const resolvedCodexModel = keyProfile ? null : resolveCodexModelOption(model)
+  const resolvedCodexEffort = resolvedCodexModel ? resolveCodexEffortForModel(resolvedCodexModel, options?.effort) : 'provider-default'
+  // A keyed exchange is stamped with its profile (P6 persists it by syntax), never with the slot.
+  const exchangeModel = keyProfile ? profilePreference(keyProfile.id) as unknown as CodexModelPreference : model
   const engineSession = persistentCodexSession
     ? getCodexEngineSession({
       cosSessionId: sid,
@@ -355,6 +465,7 @@ export async function callCodexStreaming(
       cwd: codexCwd,
       trustMode: codexTrustMode,
       engineFingerprint: extraFingerprint,
+      ...(keyProfile ? { profileId: keyProfile.id } : {}),
     })
     : null
   const imageInputs: ModelImageInput[] = images ?? []
@@ -370,7 +481,7 @@ export async function callCodexStreaming(
     trustMode: codexTrustMode,
     codexThreadId: engineSession?.codexThreadId,
     expiresAt: engineSession?.expiresAt,
-    cliModel: resolvedCodexModel.id || 'codex-cli-default',
+    cliModel: keyProfile ? keyProfile.model : (resolvedCodexModel?.id || 'codex-cli-default'),
     reasoningEffort: resolvedCodexEffort,
     query,
   })
@@ -438,7 +549,7 @@ export async function callCodexStreaming(
     globalMsgNum,
     inboundAttachments,
     exchangeProvenance,
-    model,
+    exchangeModel,
   )
 
   const hasNonImageAttachment = requestRefs.some(ref => mediaCategoryOf(ref) !== 'image')
@@ -455,17 +566,26 @@ export async function callCodexStreaming(
   if (options?.attachmentPromptBlock) fullQuery = `${fullQuery}\n\n${options.attachmentPromptBlock}`
 
   const prompt = buildCodexPrompt(systemPrompt, fullQuery)
-  const args = buildCodexExecArgs({
-    codexCwd,
-    imagePaths,
-    persistentCodexSession,
-    codexThreadId: engineSession?.codexThreadId,
-    model,
-    resolvedModel: resolvedCodexModel,
-    effort: options?.effort,
-    publisherWritableDirectory: outputImagePublisher?.writableDirectory,
-    extra,
-  })
+  const args = keyProfile
+    ? buildCodexProfileExecArgs({
+      codexCwd,
+      imagePaths,
+      persistentCodexSession,
+      codexThreadId: engineSession?.codexThreadId,
+      profileModel: keyProfile.model,
+      publisherWritableDirectory: outputImagePublisher?.writableDirectory,
+    })
+    : buildCodexExecArgs({
+      codexCwd,
+      imagePaths,
+      persistentCodexSession,
+      codexThreadId: engineSession?.codexThreadId,
+      model,
+      resolvedModel: resolvedCodexModel!,
+      effort: options?.effort,
+      publisherWritableDirectory: outputImagePublisher?.writableDirectory,
+      extra,
+    })
 
   const env = { ...process.env }
   delete env.CLAUDECODE
@@ -482,6 +602,43 @@ export async function callCodexStreaming(
     )
   }
 
+  // Key lanes: one nonce per turn from the relay (P2 contract), the generated home written with
+  // its origin, then the child env points at both. Only the child's copy is written. A relay
+  // that cannot issue, or a home that cannot be written, ends the turn before spawn.
+  let keyTurn: RelayTurnHandle | null = null
+  const keyTurnId = keyProfile && profileHome ? options?.turnId ?? randomUUID() : null
+  if (keyProfile && profileHome) {
+    try {
+      const relay = await codexKeyRelay()
+      keyTurn = await relay.issueTurn({
+        keyRef: keyProfile.keyRef,
+        profileId: keyProfile.id,
+        turnId: keyTurnId!,
+        sessionId: sid,
+        engine: 'codex',
+        allowedModel: keyProfile.model,
+      }, { wallMaxMs: WALL_MAX_MS })
+      writeCodexProfileHome(profileHome, keyTurn.origin)
+      applyCodexLaneBEnv(env, { home: profileHome.home, nonce: keyTurn.nonce, profileId: keyProfile.id })
+    } catch (err) {
+      keyTurn?.revoke('cancel')
+      outputImagePublisher?.cleanup()
+      cleanupModelImageInputs(imageInputs)
+      removeExchange(sid, pendingUserExchange)
+      try {
+        finishCodexRun(run.runId, { status: 'failed', startedAtMs: startTime, error: 'codex-bridge: key relay refused the turn.', exitCode: null })
+      } catch { /* the ledger is best effort here */ }
+      console.error(`[codex-bridge] key relay refused the turn: ${err instanceof Error ? err.message.slice(0, 200) : 'unknown'}`)
+      await callbacks.onError(CODEX_LANE_B_COPY.relayUnavailable)
+      return sid
+    }
+  }
+  const keyAuditFields = keyProfile && keyKind ? { profile: keyProfile.id, lane: 'key' as const, credentialKind: keyKind } : {}
+  // Key lanes (P11, plan 3.1): `lane` and `credential` on a keyed answer, omitted otherwise.
+  const keyLane: AnswerKeyFields | null = keyProfile && keyKind
+    ? { lane: 'key', credential: { kind: keyKind, ref: keyProfile.keyRef, profileId: keyProfile.id } }
+    : null
+
   // The COS UserPromptSubmit hook sees `prompt`, which is SYSTEM INSTRUCTIONS plus USER
   // REQUEST in one text, on a fresh thread and on resume alike. This private file hands it
   // the user's own words, bound by the hash of exactly what goes on stdin; the file dies
@@ -489,12 +646,12 @@ export async function callCodexStreaming(
   const turnRequest = createTurnRequestBinding({ userText: query, prompt, turnId: options?.turnId })
   applyTurnRequestEnv(env, turnRequest)
 
-  const proc = spawnWithTurnRequest(turnRequest, () => spawn(resolvedCodex.path, args, {
+  const proc = withKeyTurnRevokedOnThrow(keyTurn, () => spawnWithTurnRequest(turnRequest, () => spawn(resolvedCodex.path, args, {
     stdio: ['pipe', 'pipe', 'pipe'],
     env,
     cwd: codexCwd,
     detached: true,
-  }))
+  })))
 
   let fullText = ''
   let stderr = ''
@@ -519,7 +676,7 @@ export async function callCodexStreaming(
   function clearEngineSessionBestEffort(reason: string) {
     if (!engineSession) return
     try {
-      clearCodexEngineSession(sid, model)
+      clearCodexEngineSession(sid, model, keyProfile?.id)
     } catch (error) {
       console.error(`[codex-bridge] engine session clear failed (${reason}):`, error)
     }
@@ -535,6 +692,7 @@ export async function callCodexStreaming(
         cwd: codexCwd,
         trustMode: codexTrustMode,
         engineFingerprint: extraFingerprint,
+        ...(keyProfile ? { profileId: keyProfile.id } : {}),
       })
       updateCodexRun(run.runId, { codexThreadId, expiresAt: saved.expiresAt })
     } catch (error) {
@@ -570,6 +728,8 @@ export async function callCodexStreaming(
       return
     }
     finalized = true
+    // Canary R14: the turn is over the moment the bridge says so; the child gets no more calls on the key.
+    keyTurn?.revoke('child_close')
     cleanup()
     cleanupImages()
 
@@ -615,7 +775,7 @@ export async function callCodexStreaming(
       globalMsgNum,
       undefined,
       exchangeProvenance,
-      model,
+      exchangeModel,
     )
     if (imagePaths.length > 0) {
       replaceLastExchangeWithSummary(sid, query, text, imagePaths.length)
@@ -649,6 +809,8 @@ export async function callCodexStreaming(
     }
 
     const totalMs = Date.now() - startTime
+    // Key lanes (P11): this turn's settled spend on the key. Keyed turns only.
+    const keyUsdFields = keyTurnId ? { usd: Math.round(getSharedKeyMeter().turnSettledUsd(keyTurnId) * 1e6) / 1e6 } : {}
     logTokenAudit({
       source: options?.lightweight ? 'g2-voice' : 'g2-query',
       model,
@@ -656,6 +818,8 @@ export async function callCodexStreaming(
       outputChars: text.length,
       durationMs: totalMs,
       caller: options?.lightweight ? 'voice_query' : 'full_query',
+      ...keyAuditFields,
+      ...keyUsdFields,
     })
     saveEngineSessionBestEffort()
 
@@ -673,6 +837,7 @@ export async function callCodexStreaming(
         generation: options?.generation,
         ...(outputAttachments.length > 0 ? { outputAttachments } : {}),
         ...(outputImageStats && outputImageStats.published > 0 ? { outputImageStats } : {}),
+        ...(keyLane ? { keyLane, ...keyUsdFields } : {}),
       })
       if (terminalOwned === false) return
     } catch (error) {
@@ -689,6 +854,8 @@ export async function callCodexStreaming(
   async function finalizeError(msg: string, exitCode?: number | null, status: Exclude<CodexRunStatus, 'running'> = 'failed') {
     if (finalized) return
     finalized = true
+    // Canary R14: a Codex child keeps retrying after the bridge ends the turn; its nonce dies now.
+    keyTurn?.revoke('cancel')
     cleanup()
     cleanupImages()
     outputImagePublisher?.cleanup()
@@ -739,6 +906,7 @@ export async function callCodexStreaming(
   }
 
   function handleAbort() {
+    keyTurn?.revoke('cancel')
     void terminateForTerminal('client disconnect', result => finalizeError(
         'codex-bridge: client disconnected before Codex completed.',
         result.code,
@@ -784,6 +952,9 @@ export async function callCodexStreaming(
     if (nextThreadId && nextThreadId !== codexThreadId) {
       codexThreadId = nextThreadId
       updateCodexRun(run.runId, { codexThreadId })
+      // Key lanes (plan 7.3): recorded before any answer text, so Continue, Fork, attach and
+      // handoff refuse this thread from the moment it exists.
+      if (keyProfile) recordKeyedCodexThread({ id: nextThreadId, engine: 'codex', profileId: keyProfile.id, cosSessionId: sid })
     }
     // 6.62.0 (plan 3.9): the job links to its native thread at the first event naming it,
     // not only at completion.
@@ -860,6 +1031,7 @@ export async function callCodexStreaming(
   })
 
   proc.on('close', (code) => {
+    keyTurn?.childClosed()
     if (terminationRequested) return
     if (buffer.trim()) {
       try { handleEvent(JSON.parse(buffer.trim())) } catch { /* ignore */ }
@@ -880,6 +1052,7 @@ export async function callCodexStreaming(
   })
 
   proc.on('error', (err) => {
+    keyTurn?.revoke('cancel')
     if (terminationRequested) return
     finalizeError(`codex-bridge: ${err.message}`)
   })

package/server/lib/codex-engine-sessions.ts

@@ -5,6 +5,7 @@ import {
   normalizeModelPreference,
   type CodexModelPreference,
 } from '../../shared/model-preference.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
 
 export const CODEX_ENGINE_SESSION_TTL_MS = 2 * 60 * 60_000
 
@@ -21,6 +22,12 @@ export interface CodexEngineSession {
   lastUsedAt: number
   expiresAt: string
   engineFingerprint: string
+  /**
+   * Key lanes (P11): the key profile this thread runs under. Its own slot, so a keyed turn and a
+   * subscription turn of one COS session never overwrite each other's resume. Absent on every
+   * subscription row, which keeps its 6.79.0 key and bytes.
+   */
+  profileId?: string
 }
 
 interface CodexEngineSessionFile {
@@ -28,8 +35,12 @@ interface CodexEngineSessionFile {
   savedAt: string
 }
 
-function sessionKey(cosSessionId: string, model: CodexModelPreference): string {
-  return `${cosSessionId}:${model}`
+function sessionKey(cosSessionId: string, model: CodexModelPreference, profileId?: string): string {
+  return profileId ? `${cosSessionId}:${model}:profile:${profileId}` : `${cosSessionId}:${model}`
+}
+
+function slotProfile(raw: unknown): string | undefined {
+  return isKeyProfileId(raw) ? raw : undefined
 }
 
 export function getCodexEngineSessionPath(): string {
@@ -58,7 +69,8 @@ function readStore(): CodexEngineSessionFile {
         typeof raw?.lastUsedAt !== 'number' ||
         typeof raw?.expiresAt !== 'string'
       ) continue
-      const key = sessionKey(raw.cosSessionId, model)
+      if (raw.profileId !== undefined && !slotProfile(raw.profileId)) continue
+      const key = sessionKey(raw.cosSessionId, model, slotProfile(raw.profileId))
       const normalized = { ...raw, key, model } as CodexEngineSession
       const prior = sessions[key]
       if (!prior || normalized.lastUsedAt > prior.lastUsedAt) sessions[key] = normalized
@@ -95,12 +107,13 @@ export function getCodexEngineSession(input: {
   cwd: string
   trustMode: CodexTrustMode
   engineFingerprint?: string
+  profileId?: string
 }): CodexEngineSession | null {
   const { engineFingerprint = '', ...rest } = input
   const store = readStore()
   const now = Date.now()
   const sessions = pruneExpired(store.sessions, now)
-  const existing = sessions[sessionKey(rest.cosSessionId, rest.model)]
+  const existing = sessions[sessionKey(rest.cosSessionId, rest.model, slotProfile(rest.profileId))]
   if (!existing) {
     if (Object.keys(sessions).length !== Object.keys(store.sessions).length) {
       writeStore({ sessions, savedAt: new Date().toISOString() })
@@ -120,11 +133,13 @@ export function saveCodexEngineSession(input: {
   trustMode: CodexTrustMode
   now?: number
   engineFingerprint?: string
+  profileId?: string
 }): CodexEngineSession {
   const now = input.now ?? Date.now()
   const store = readStore()
   const sessions = pruneExpired(store.sessions, now)
-  const key = sessionKey(input.cosSessionId, input.model)
+  const profileId = slotProfile(input.profileId)
+  const key = sessionKey(input.cosSessionId, input.model, profileId)
   const previous = sessions[key]
   const session: CodexEngineSession = {
     key,
@@ -137,13 +152,18 @@ export function saveCodexEngineSession(input: {
     lastUsedAt: now,
     expiresAt: expiresAtFrom(now),
     engineFingerprint: input.engineFingerprint ?? '',
+    ...(profileId ? { profileId } : {}),
   }
   sessions[key] = session
   writeStore({ sessions, savedAt: new Date().toISOString() })
   return session
 }
 
-export function clearCodexEngineSession(cosSessionId: string, model?: CodexModelPreference): number {
+/**
+ * With a model, clears that model's slot of one lane only: the subscription slot, or with
+ * `profileId` that profile's slot. Without a model (deleting the COS session), every slot.
+ */
+export function clearCodexEngineSession(cosSessionId: string, model?: CodexModelPreference, profileId?: string): number {
   const store = readStore()
   const sessions = pruneExpired(store.sessions)
   let removed = 0
@@ -151,6 +171,7 @@ export function clearCodexEngineSession(cosSessionId: string, model?: CodexModel
     const session = sessions[key]
     if (session.cosSessionId !== cosSessionId) continue
     if (model && session.model !== model) continue
+    if (model && (session.profileId ?? undefined) !== slotProfile(profileId)) continue
     delete sessions[key]
     removed += 1
   }

package/server/lib/codex-homes.ts

@@ -0,0 +1,134 @@
+// Key lanes K1 P4 (plan v4 8.2): every Codex home a reader must look in.
+//
+// A keyed (Lane B) Codex turn runs in its own home, `data/codex-homes/<profileId>/`, so its
+// rollouts, writer locks and queue database never land in the user's `~/.codex`. Readers that
+// FIND threads (the session list, the native head, the queue counts, occupancy, hook events)
+// look in every home; readers of config, catalog or models stay on the server home.
+//
+//   codexHomes(serverHome)   the server home FIRST, then each profile home. With key lanes off
+//                            or no profile home on disk it is exactly `[serverHome]`, so every
+//                            reader built on it is identical to 963fe25.
+//
+// HARD RULE (zero impact without a key): nothing here creates a file or a directory. A profile
+// home is listed only while key lanes are enabled AND `data/codex-homes/` exists. Importing this
+// module reads nothing.
+import { lstatSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { dataPath } from './data-dir.js'
+import { keyLanesEnabled } from './key-lanes.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
+
+/** The directory under the data dir. P1's Remove all keys deletes it (`routes/key-lanes.ts`). */
+export const CODEX_PROFILE_HOMES_DIR = 'codex-homes'
+/** A bound on how many profile homes one read lists (the profile store caps at 20). */
+export const MAX_CODEX_PROFILE_HOMES = 64
+
+/** The server's own Codex home: `CODEX_HOME`, else `~/.codex` (as the hooks installer reads it). */
+export function serverCodexHome(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.CODEX_HOME?.trim()
+  return raw ? resolve(raw) : join(homedir(), '.codex')
+}
+
+export function codexProfileHomesRoot(): string {
+  return dataPath(CODEX_PROFILE_HOMES_DIR)
+}
+
+/** `data/codex-homes/<id>`. Throws on a malformed id (a caller bug, never user input). */
+export function codexProfileHome(profileId: string): string {
+  if (!isKeyProfileId(profileId)) throw new Error('invalid key profile id')
+  return join(codexProfileHomesRoot(), profileId)
+}
+
+export interface CodexProfileHomeEntry {
+  profileId: string
+  home: string
+}
+
+/**
+ * Profile homes on disk, sorted by id. Empty unless key lanes are enabled and the root exists.
+ * A symlink, a file or a badly named entry is skipped, never followed.
+ */
+export function profileCodexHomes(env: NodeJS.ProcessEnv = process.env): CodexProfileHomeEntry[] {
+  if (!keyLanesEnabled(env)) return []
+  const root = codexProfileHomesRoot()
+  let names: string[]
+  try {
+    if (!lstatSync(root).isDirectory()) return []
+    names = readdirSync(root)
+  } catch {
+    return []
+  }
+  const out: CodexProfileHomeEntry[] = []
+  for (const name of names.sort()) {
+    if (!isKeyProfileId(name)) continue
+    const home = join(root, name)
+    try { if (!lstatSync(home).isDirectory()) continue } catch { continue }
+    out.push({ profileId: name, home })
+    if (out.length >= MAX_CODEX_PROFILE_HOMES) break
+  }
+  return out
+}
+
+/**
+ * Every Codex home, the server home first. A reader passes its own server home (some honour
+ * `COS_AGENT_SESSIONS_HOME`, some `CODEX_HOME`) so the first entry is exactly what it read before.
+ */
+export function codexHomes(serverHome: string = serverCodexHome(), env: NodeJS.ProcessEnv = process.env): string[] {
+  return [serverHome, ...profileCodexHomes(env).map(entry => entry.home)]
+}
+
+/** The profile homes only, joined with a subpath (`sessions`, `thread-writer-locks`). */
+export function profileCodexHomeSubdirs(sub: string, env: NodeJS.ProcessEnv = process.env): string[] {
+  return profileCodexHomes(env).map(entry => join(entry.home, sub))
+}
+
+/**
+ * The profile id a path lives under (`data/codex-homes/<id>/...`), or undefined. Prefix-exact on
+ * the real root, so a user folder that happens to be called `codex-homes` never matches.
+ */
+export function profileIdForCodexPath(path: unknown): string | undefined {
+  if (typeof path !== 'string' || !path) return undefined
+  const root = codexProfileHomesRoot() + sep
+  if (!path.startsWith(root)) return undefined
+  const id = path.slice(root.length).split(sep)[0]
+  return isKeyProfileId(id) ? id : undefined
+}
+
+const ROLLOUT_ID_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i
+const MAX_DIR_ENTRIES = 512
+const MAX_FILES = 20_000
+
+/**
+ * The profile whose home holds this Codex thread's rollout, or undefined. Walks
+ * `sessions/<yyyy>/<mm>/<dd>/rollout-*-<id>.jsonl` in each profile home, bounded like
+ * native-head's walk. With no profile home it returns at once without touching the disk.
+ */
+export function profileForCodexThread(threadId: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const homes = profileCodexHomes(env)
+  if (homes.length === 0) return undefined
+  const needle = typeof threadId === 'string' ? threadId.trim().toLowerCase() : ''
+  if (!/^[0-9a-f-]{36}$/.test(needle)) return undefined
+  const list = (dir: string): string[] => {
+    try {
+      const names = readdirSync(dir)
+      return names.length > MAX_DIR_ENTRIES ? [] : names
+    } catch { return [] }
+  }
+  for (const { profileId, home } of homes) {
+    let scanned = 0
+    const root = join(home, 'sessions')
+    for (const y of list(root)) for (const m of list(join(root, y))) for (const d of list(join(root, y, m))) {
+      for (const name of list(join(root, y, m, d))) {
+        if (++scanned > MAX_FILES) break
+        if (!name.startsWith('rollout-')) continue
+        if (ROLLOUT_ID_RE.exec(name)?.[1]?.toLowerCase() === needle) return profileId
+      }
+    }
+  }
+  return undefined
+}
+
+export function isProfileCodexThread(threadId: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return profileForCodexThread(threadId, env) !== undefined
+}

package/server/lib/codex-live-queue.ts

@@ -54,6 +54,7 @@
 // sentence into the thread twice. A clap usage error (exit 2) queued nothing.
 
 import { isValidNativeThreadId } from './native-thread-id.js'
+import { isProfileCodexThread } from './codex-homes.js'
 
 export type CodexLiveReason =
   /** The row is in the holder's queue. */
@@ -71,6 +72,11 @@ export type CodexLiveReason =
   | 'refused'
   /** Something may be queued. Hold; never retry, never spawn over it. */
   | 'unverified'
+  /**
+   * Key lanes K1 (plan v4 8.1): the thread lives in a keyed profile home, never the Codex app's
+   * queue. Nothing sent; the steer lands after the running turn (CODEX_KEYED_STEER_NOTICE).
+   */
+  | 'keyed_session'
 
 export interface CodexLiveResult {
   ok: boolean
@@ -100,8 +106,13 @@ export interface CodexLiveDeps {
   run: (binary: string, args: readonly string[], timeoutMs: number) => Promise<CodexQueueRun>
   now: () => number
   log?: (level: 'info' | 'warn', event: string, detail: Record<string, unknown>) => void
+  /** Key lanes: is this thread a keyed profile thread? Defaults to a look in the profile homes. */
+  isKeyedThread?: (threadId: string) => boolean
 }
 
+/** Plan 8.1 lens line for a steer into a keyed Codex session. */
+export const CODEX_KEYED_STEER_NOTICE = 'Steer lands after this turn.'
+
 export interface CodexLiveRequest {
   provider: string
   sessionId: string
@@ -182,6 +193,9 @@ export async function deliverOverCodexQueue(request: CodexLiveRequest, deps: Cod
   })
   if (!request.enabled) return done('disabled')
   if (request.provider !== 'codex' || request.foreignHolder !== true) return done('no_holder')
+  // Key lanes: a keyed profile thread is never the Codex app's, so it never joins its queue.
+  // With no profile home this is one predicate call that touches nothing.
+  if ((deps.isKeyedThread ?? isProfileCodexThread)(request.sessionId)) return done('keyed_session')
   let args: string[]
   try {
     args = buildCodexQueueArgs(request.sessionId, request.prompt)