@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/query-job-store.ts

@@ -39,6 +39,7 @@ import {
   type QueryJobSteerState,
   type QueryJobTrailEntry,
 } from './query-job-types.js'
+import { keyAnswerJobFields, type QueryJobKeyAnswerFields } from './key-answer-fields.js'
 import {
   jobTrailTextChars,
   parseJobTrailEventData,
@@ -868,6 +869,7 @@ export class QueryJobStore {
       const outputImageStats = parseQueryJobOutputImageStats(patch.outputImageStats)
       if (outputImageStats) snapshot.outputImageStats = outputImageStats
       else delete snapshot.outputImageStats
+      Object.assign(snapshot, keyAnswerJobFields(patch))
       this.applyLinkage(snapshot, patch)
       delete snapshot.error
     } else if (record.type === 'failed' || record.type === 'canceled' || record.type === 'interrupted') {
@@ -1466,13 +1468,15 @@ export class QueryJobStore {
 
   async complete(
     jobId: string,
-    input: { text: string; attachments?: unknown; outputImageStats?: unknown } & QueryJobProviderLinkage,
+    input: { text: string; attachments?: unknown; outputImageStats?: unknown } & QueryJobProviderLinkage & QueryJobKeyAnswerFields,
   ): Promise<QueryJobMutationResult> {
     const response = boundedText(input.text, QUERY_JOB_LIMITS.terminalResponseChars)
     const partial = boundedText(input.text, QUERY_JOB_LIMITS.partialChars)
     const linkage = this.safeLinkage(input)
     const attachments = parseMediaAttachmentRefs(input.attachments)
     const outputImageStats = parseQueryJobOutputImageStats(input.outputImageStats)
+    // Key lanes (P11): {} unless a key profile answered, so a subscription record is unchanged.
+    const keyAnswer = keyAnswerJobFields(input)
     const completedAt = this.now().toISOString()
     return this.transition(jobId, 'completed', 'completed', {
       ...linkage,
@@ -1483,12 +1487,14 @@ export class QueryJobStore {
       partialTruncated: partial.truncated,
       attachments,
       ...(outputImageStats ? { outputImageStats } : {}),
+      ...keyAnswer,
     }, {
       ...linkage,
       response: response.text,
       responseTruncated: response.truncated,
       attachments,
       ...(outputImageStats ? { outputImageStats } : {}),
+      ...keyAnswer,
     })
   }
 

package/server/lib/query-job-types.ts

@@ -1,5 +1,7 @@
 import { providerFailureCode } from './provider-failure-text.js'
 import { createHash } from 'node:crypto'
+import type { QueryJobKeyAnswerFields } from './key-answer-fields.js'
+import { isProfilePreference } from '../../shared/key-preference.js'
 import {
   parseMediaAttachmentRefs,
   parseMediaIdList,
@@ -132,6 +134,12 @@ export interface QueryJobRequest {
    * it names the session, it does not change what is asked.
    */
   sessionName?: string
+  /**
+   * Key lanes (QA U9 / C10): run THIS turn on the key profile it names without binding the
+   * session to it (the plan-limit "run this one on your key" offer). Kept only with a
+   * `profile:<id>` model; in the fingerprint, since it changes what the turn does.
+   */
+  keyTurnOnly?: true
   /**
    * 6.78.0: the client can steer this run (it read `durableQueryJobs.steer`). Only `true` is
    * kept. Excluded from the fingerprint: it says how the answer may be guided, not what is
@@ -437,6 +445,11 @@ export interface QueryJobSnapshot extends QueryJobProviderLinkage {
   response?: string
   responseTruncated?: boolean
   outputImageStats?: QueryJobOutputImageStats
+  /** Key lanes (P11, plan 3.1): present only on a job a key profile answered; omitted, never null. */
+  lane?: QueryJobKeyAnswerFields['lane']
+  credential?: QueryJobKeyAnswerFields['credential']
+  profile?: string
+  usd?: number
   error?: QueryJobError
   /** 6.78.0: what a restart cut off (see QueryJobInterruption). Only on a job a restart ended. */
   interruption?: QueryJobInterruption
@@ -657,6 +670,7 @@ export function parseQueryJobRequest(raw: unknown, options: ParseQueryJobRequest
     ...(input.handoffLatest === true ? { handoffLatest: true } : {}),
     ...(clientQueueItemId ? { clientQueueItemId } : {}),
     ...(sessionName ? { sessionName } : {}),
+    ...(input.keyTurnOnly === true && isProfilePreference(model) ? { keyTurnOnly: true as const } : {}),
     ...(input.steerable === true ? { steerable: true as const } : {}),
     attachmentIds,
     attachmentRefs,
@@ -721,7 +735,7 @@ export const FINGERPRINT_KEYS = [
   'clientJobId', 'generation', 'query', 'sessionId', 'model', 'effort',
   'cursorExecutionMode', 'messageEra', 'globalMsgNum', 'reference', 'handoffCode',
   'handoffLatest', 'clientQueueItemId', 'attachmentIds', 'attachmentRefs',
-  'activityToolMode',
+  'activityToolMode', 'keyTurnOnly',
 ] as const satisfies readonly (keyof QueryJobRequest)[]
 
 /** The request keys deliberately OUTSIDE the identity. Every key of

package/server/lib/session-hook-events.ts

@@ -14,6 +14,10 @@
 // whose shapes are still the documented ones until a Desktop recording lands.
 
 import { createHash } from 'node:crypto'
+import { profileIdForCodexPath } from './codex-homes.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
+import { keyLanesEnabled } from './key-lanes.js'
+import { keyedSessionProfile } from './keyed-sessions.js'
 
 /** Events the installer subscribes and the reducer understands. Anything else is dropped. */
 export const HOOK_EVENT_NAMES = [
@@ -71,9 +75,29 @@ export function inferHookProvider(stamped: unknown, payload: Record<string, unkn
   if (isHookProvider(stamped)) return stamped
   if ('cursor_version' in payload) return 'cursor'
   if (typeof payload.transcript_path === 'string' && payload.transcript_path.includes('/.codex/sessions/')) return 'codex'
+  // Key lanes K1 (plan v4 8.2): a keyed Codex profile home keeps its rollouts under
+  // `data/codex-homes/<id>/sessions/`, which never contains `/.codex/`.
+  if (profileIdForCodexPath(payload.transcript_path) !== undefined) return 'codex'
   return 'claude'
 }
 
+/**
+ * Key lanes K1 (plan v4 7.3): the key profile a hook event ran under, or undefined. Read from
+ * the envelope's own `keyProfile` stamp (a hook script that forwards `COS_KEY_PROFILE`), else
+ * from a transcript inside a keyed Codex profile home, else (canary R7: the installed hook script
+ * does not stamp it, and changing the script would mark every install outdated) from the
+ * keyed-session record the bridge wrote for that CLI session id. Lanes off: never looked up.
+ * Undefined for every Lane A event.
+ */
+export function hookKeyProfile(stamped: unknown, payload: Record<string, unknown>, sessionId?: string | null): string | undefined {
+  if (isKeyProfileId(stamped)) return stamped
+  const codex = profileIdForCodexPath(payload.transcript_path)
+  if (codex) return codex
+  if (!sessionId || !keyLanesEnabled()) return undefined
+  const recorded = keyedSessionProfile(sessionId)
+  return isKeyProfileId(recorded) ? recorded : undefined
+}
+
 /** 6.62.0: the cap on an agent thought kept in memory and sent on the live feed. */
 export const AGENT_THOUGHT_MAX = 280
 
@@ -99,6 +123,8 @@ export interface HookEnvelope {
   payload: Record<string, unknown>
   /** 6.62.0: set by `parseHookEnvelope` and a 6.62 ledger row; absent on older rows and hand-built envelopes. */
   provider?: HookProvider
+  /** Key lanes K1 (plan v4 7.3): the key profile this event ran under. Absent on every Lane A envelope. */
+  keyProfile?: string
   /**
    * 6.62.0 (QA W2): the envelope itself named the provider: a 6.62 hook script (from the Codex
    * command, or from a Codex payload) or the Cursor observer wrote it. Inferred is not stamped.
@@ -150,6 +176,7 @@ export function parseHookEnvelope(text: string): ParsedHookEnvelope {
   const sessionId = typeof p.session_id === 'string' && SESSION_ID_RE.test(p.session_id) ? p.session_id.toLowerCase() : null
   if (!sessionId) return { ok: false, reason: 'no_session', salvaged: null }
   const ppid = Number(r.ppid)
+  const keyProfile = hookKeyProfile(r.keyProfile, p, sessionId)
   return {
     ok: true,
     envelope: {
@@ -160,6 +187,7 @@ export function parseHookEnvelope(text: string): ParsedHookEnvelope {
       payload: p,
       provider: inferHookProvider(r.provider, p),
       ...(isHookProvider(r.provider) ? { stamped: true as const } : {}),
+      ...(keyProfile ? { keyProfile } : {}),
     },
   }
 }

package/server/lib/session-hook-ledger.ts

@@ -9,6 +9,8 @@
 import { appendFileSync, existsSync, readFileSync, renameSync, statSync } from 'node:fs'
 import type { HookEnvelope, HookEventName, HookProvider } from './session-hook-events.js'
 import { projectHookPayload, isHookEventName, isHookProvider, SESSION_ID_RE } from './session-hook-events.js'
+import { keyLanesEnabled } from './key-lanes.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
 
 export const LEDGER_ROTATE_BYTES = 10 * 1024 * 1024
 
@@ -30,6 +32,12 @@ export interface LedgerRow {
   provider?: HookProvider
   /** 6.62.0 (QA W2): the envelope carried the provider stamp; a replay keeps the evidence. */
   stamped?: true
+  /**
+   * Key lanes K1 (canary rerun R8): the key profile the event ran under, as `hookKeyProfile`
+   * resolved it at ingest (for a Codex thread, from the keyed-thread record the bridge wrote).
+   * Written only while lanes are on, so a row with lanes off is byte-identical to before.
+   */
+  keyProfile?: string
   payload: Record<string, unknown>
 }
 
@@ -77,6 +85,7 @@ export class SessionHookLedger {
         ...(entrypoint ? { entrypoint } : {}),
         ...(env.provider ? { provider: env.provider } : {}),
         ...(env.stamped ? { stamped: true as const } : {}),
+        ...(env.keyProfile && keyLanesEnabled() ? { keyProfile: env.keyProfile } : {}),
         payload: projectHookPayload(env.event, env.payload),
       }
     } catch (error) {
@@ -137,6 +146,7 @@ export class SessionHookLedger {
         payload: { session_id: r.session_id, ...payload },
         ...(isHookProvider(r.provider) ? { provider: r.provider } : {}),
         ...(r.stamped === true && isHookProvider(r.provider) ? { stamped: true as const } : {}),
+        ...(isKeyProfileId(r.keyProfile) ? { keyProfile: r.keyProfile } : {}),
       }, r.key, r.child === true, entrypoint)
       applied++
     }

package/server/lib/thread-occupancy.ts

@@ -543,11 +543,32 @@ export function codexOwners(
   return { owners, doubt }
 }
 
+/**
+ * Key lanes K1 (plan v4 8.2): the server home's writer locks, then each keyed profile home's.
+ * A keyed home that is absent adds nothing (its detector was never the server's to lose); with
+ * no profile home this is exactly `codexOwners` on the server home.
+ */
+export function codexOwnersAcrossHomes(threadId: string, probes: OccupancyProbes, dirs: OccupancyDirs): ScanResult {
+  const base = codexOwners(threadId, probes, dirs.codexLocksDir)
+  if (!dirs.codexProfileLocksDirs) return base
+  const owners = [...base.owners]
+  let doubt = base.doubt
+  for (const dir of dirs.codexProfileLocksDirs) {
+    if (!probes.dirExists(dir)) continue
+    const keyed = codexOwners(threadId, probes, dir)
+    owners.push(...keyed.owners)
+    if (keyed.doubt !== null && keyed.doubt !== 'detector_unavailable') doubt ??= keyed.doubt
+  }
+  return { ...base, owners, doubt }
+}
+
 export interface OccupancyDirs {
   /** `<CLAUDE_CONFIG_DIR|~/.claude>/sessions` */
   claudeSessionsDir: string
   /** `<CODEX_HOME|~/.codex>/thread-writer-locks` */
   codexLocksDir: string
+  /** Key lanes K1 (plan v4 8.2): each keyed profile home's `thread-writer-locks`. Absent with no profile home. */
+  codexProfileLocksDirs?: string[]
   /** `<COS_AGENT_SESSIONS_HOME|~>/.cursor/chats` */
   cursorChatsDir: string
 }
@@ -698,7 +719,7 @@ export function threadOccupancy(
   try {
     result = provider === 'claude'
       ? claudeOwners(threadId, probes, dirs.claudeSessionsDir)
-      : codexOwners(threadId, probes, dirs.codexLocksDir)
+      : codexOwnersAcrossHomes(threadId, probes, dirs)
   } catch {
     return { attachable: false, owners: [], reason: 'probe_failed' }
   }

package/server/lib/token-audit.ts

@@ -7,6 +7,7 @@ import { resolve } from 'node:path'
 import { homedir } from 'node:os'
 
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
+import type { TokenAuditKeyFields } from './key-relay-contract.js'
 
 // Shared JSONL file — same path as Python's llm_client.py uses
 // Uses COS_SCRIPTS_DIR when available (server mode), falls back to user home
@@ -21,7 +22,7 @@ function estimateTokens(chars: number): number {
   return Math.max(1, Math.floor(chars / CHARS_PER_TOKEN))
 }
 
-export interface TokenAuditEntry {
+export interface TokenAuditEntry extends TokenAuditKeyFields {
   source: string       // "g2-voice", "g2-prewarm", "g2-archive", "g2-query"
   model: string        // "opus", "sonnet", "haiku", "cursor-composer", ...
   inputChars: number
@@ -35,9 +36,14 @@ export interface TokenAuditEntry {
   usageKind?: 'provider_final' | 'estimated'
 }
 
-export function logTokenAudit(entry: TokenAuditEntry): void {
-  const record = {
-    ts: new Date().toISOString(),
+/**
+ * The JSONL record. Key-lane fields (plan v4 3.1: `profile`, `lane`, `credentialKind`, `usd`) are
+ * conditional spreads AFTER every 6.79.0 key, written only when the caller sets them, so a Lane A
+ * (subscription) row is byte-identical to 6.79.0. Callers set them only on keyed turns.
+ */
+export function buildTokenAuditRecord(entry: TokenAuditEntry, now: Date = new Date()): Record<string, unknown> {
+  return {
+    ts: now.toISOString(),
     source: entry.source,
     model: entry.model,
     input_chars: entry.inputChars,
@@ -51,7 +57,15 @@ export function logTokenAudit(entry: TokenAuditEntry): void {
     ...(entry.runId ? { run_id: entry.runId } : {}),
     ...(entry.sessionId ? { session_id: entry.sessionId } : {}),
     ...(entry.clientJobId ? { client_job_id: entry.clientJobId } : {}),
+    ...(entry.profile ? { profile: entry.profile } : {}),
+    ...(entry.lane ? { lane: entry.lane } : {}),
+    ...(entry.credentialKind ? { credentialKind: entry.credentialKind } : {}),
+    ...(typeof entry.usd === 'number' && Number.isFinite(entry.usd) ? { usd: entry.usd } : {}),
   }
+}
+
+export function logTokenAudit(entry: TokenAuditEntry): void {
+  const record = buildTokenAuditRecord(entry)
   try {
     appendFileSync(AUDIT_FILE, JSON.stringify(record) + '\n', { encoding: 'utf8', mode: 0o600 })
     chmodSync(AUDIT_FILE, 0o600)

package/server/lib/work-handoff-requests.ts

@@ -23,6 +23,7 @@ import { isSafeDomainName } from './domains.js'
 import { acquireServerInstanceLock, type ServerInstanceLock } from './server-instance-lock.js'
 import { parseWorkSessionId, modelProvider, UUID_V4, FORK_PROVIDERS } from './work-activity.js'
 import { normalizeModelPreference } from '../../shared/model-preference.js'
+import { KEY_PROFILE_REJECT_CODE, KEY_PROFILE_WORK_REJECT, keyProfileRejectApplies } from './key-profile-rejects.js'
 
 export class WorkHandoffRequestError extends Error {
   /** `extra` goes into the error body next to the code (the daily cap's `resetsAt`). */
@@ -136,6 +137,8 @@ export function parseHandoffRequest(body: unknown, defaultModel: string): { inpu
   let model: string | undefined
   if (given(body.model)) {
     model = normalizeModelPreference(body.model)
+    // Key lanes K1 (plan 5.2): Reject, and say why. Work hands off subscription sessions only.
+    if (!model && keyProfileRejectApplies(body.model)) throw new WorkHandoffRequestError(KEY_PROFILE_REJECT_CODE, 400, KEY_PROFILE_WORK_REJECT)
     if (!model) throw invalid('Choose a model slot this server knows.')
   }
   let note: string | undefined

package/server/routes/agent-session-bindings.ts

@@ -131,6 +131,7 @@ import { isValidNativeThreadId } from '../lib/native-thread-id.js'
 import { FORK_PROVIDER_FAILURES, type ForkProviderFailure } from '../lib/fork-thread.js'
 import { CLIENT_FORK_ID_RE, ForkJobLedger, type ForkJobRow } from '../lib/fork-job-ledger.js'
 import { PEER_VERIFY_TIMEOUT_MS } from '../lib/session-peer-inbox.js'
+import { KEYED_SESSION_REFUSAL } from '../lib/keyed-sessions.js'
 import {
   CANCEL_QUEUE_HOLD_MS,
   CLIENT_CANCEL_ID_RE,
@@ -652,6 +653,9 @@ export type WriteRefusal =
   // person said stop. Deliberately NOT a fence (plan validation B2): the next Continue
   // must work, and it re-reads the head.
   | 'turn_cancelled'
+  // Key lanes (P3, wired by P11): the thread ran on a key profile. Refused before any spawn, with
+  // the same 409 body every other keyed entry point answers (keyed-sessions.ts).
+  | 'keyed_session'
   // ------------------------------------------------------------------- fork
   //
   // Fork gets its OWN members rather than reusing the ones above, and the reason
@@ -739,6 +743,7 @@ export const WRITE_REASON_COPY: Record<Exclude<WriteRefusal, OccupancyReason>, s
     'COS could not run this turn. Nothing was sent. You can try again.',
   turn_cancelled:
     'Run cancelled.',
+  keyed_session: KEYED_SESSION_REFUSAL.message,
 
   // Fork copy. No sentence here may end with "Fork it instead" — this IS the fork,
   // and pointing a failed fork back at itself is a dead end rather than an action.
@@ -2698,6 +2703,10 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         return refuseFork('fork_orphan_possible', { orphanPossible: true })
       }
 
+      // Key lanes: fork-thread refused a keyed source before any spawn (P3). The exact keyed 409.
+      if (raw && typeof raw === 'object' && (raw as { ok?: unknown }).ok === false && (raw as { reason?: unknown }).reason === 'keyed_session') {
+        return refuseFork('keyed_session', { ...KEYED_SESSION_REFUSAL, retryable: false })
+      }
       const outcome = classifyFork(raw, threadIdParam)
       {
         // 6.62.1: one line per attempt. On 2026-10-05 a fork's real cause existed only
@@ -3458,6 +3467,12 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         return refuseTurn('turn_cancelled', { retryable: false, deliveryState: 'cancelled' })
       }
 
+      // Key lanes: the adapter refused a keyed thread before any spawn (P3). The exact keyed 409.
+      if (adapterEvidence.adapterReason === 'keyed_session') {
+        spawnMay = false // refused before any spawn
+        return refuseTurn('keyed_session', { ...KEYED_SESSION_REFUSAL, retryable: false })
+      }
+
       if (delivery.kind === 'aborted') {
         // The adapter's own proof that the child never opened the session.
         spawnMay = false

package/server/routes/agent-sessions.ts

@@ -1,5 +1,14 @@
 import { workObservationFields } from '../lib/session-work-observation.js'
-import { readCodexSubagents } from '../lib/codex-subagent-activity.js'
+import { readCodexSubagentsAcross } from '../lib/codex-subagent-activity.js'
+import { listKeyedSessions } from '../lib/keyed-sessions.js'
+import { codexProfileHome } from '../lib/codex-homes.js'
+import { join as joinPath } from 'node:path'
+
+/** Key lanes (P11): a keyed Codex thread's own sessions root (P3's keyed-session record). */
+function keyedCodexRootOf(): (id: string) => string | undefined {
+  const byId = new Map(listKeyedSessions().filter(r => r.engine === 'codex').map(r => [r.id.toLowerCase(), joinPath(codexProfileHome(r.profileId), 'sessions')]))
+  return id => byId.get(id.toLowerCase())
+}
 // GET /api/agent-sessions
 // GET /api/agent-sessions/search?q=
 // GET /api/agent-sessions/:provider/:sessionId
@@ -31,7 +40,8 @@ import {
   emptySessionListDropped,
   loadClaudeDesktopAliases,
   loadCursorComposerNames,
-  loadCodexThreadNames,
+  codexSessionRootsOf,
+  loadCodexThreadNamesAll,
   idFromCodexFilename,
   parseAgentSession,
   type AgentProvider,
@@ -518,7 +528,8 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
       derivedById.set(row.session_id, deriveCodexRow(row.session_id, running.occupied.has(row.session_id), facts, now))
     }
     const queuedOf = await allQueuedWaitingLookup(now)
-    const subagents = await readCodexSubagents(sessions.filter(row => row.provider === 'codex').map(row => row.session_id), roots.codexSessions, now)
+    const codexRoots = codexSessionRootsOf(roots)
+    const subagents = await readCodexSubagentsAcross(sessions.filter(row => row.provider === 'codex').map(row => row.session_id), codexRoots, now, codexRoots.length > 1 ? keyedCodexRootOf() : undefined)
     res.json({
       sessions: sessions.map((row, index) => {
         const derived = derivedById.get(row.session_id)
@@ -624,7 +635,7 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     // parent's id (see `listCodexSessions`), and the parent's name would be the wrong one.
     let codexThreadName: string | undefined
     if (provider === 'codex') {
-      const names = await loadCodexThreadNames(agentSessionRoots().codexSessions)
+      const names = await loadCodexThreadNamesAll(agentSessionRoots())
       const fileId = idFromCodexFilename(found.split('/').pop() || '')
       codexThreadName = (fileId ? names.get(fileId) : undefined) || names.get(sessionId) || undefined
     }
@@ -649,7 +660,8 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     const now = Date.now()
     const rollout = provider === 'codex' ? codexRolloutFacts(found, now) : null
     const observed = provider === 'codex' ? codexCompactionFields(workObservationFor(parsed.session_id), rollout, now) : workObservationFields(workObservationFor(parsed.session_id))
-    const subagents = provider === 'codex' ? (await readCodexSubagents([sessionId], agentSessionRoots().codexSessions)).get(sessionId.toLowerCase()) : observed.subagent_activity
+    const detailRoots = provider === 'codex' ? codexSessionRootsOf(agentSessionRoots()) : []
+    const subagents = provider === 'codex' ? (await readCodexSubagentsAcross([sessionId], detailRoots, undefined, detailRoots.length > 1 ? keyedCodexRootOf() : undefined)).get(sessionId.toLowerCase()) : observed.subagent_activity
     const modified = st.mtime.toISOString()
     const activity = await readSessionActivity(provider, found)
     const running = runningForThread(provider, parsed.session_id, activityClockMs(st.mtimeMs, activity))

package/server/routes/handoffs.ts

@@ -10,6 +10,7 @@ import {
 import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
 import { getCodexExecutionCwd, getCodexTrustMode } from '../lib/codex-run-ledger.js'
 import { normalizeHandoffCode } from '../../shared/handoff-intent.js'
+import { anyKeyedSessions, isKeyedCosSession, isKeyedSession, KEYED_SESSION_REFUSAL } from '../lib/keyed-sessions.js'
 
 export const handoffsRouter = Router()
 
@@ -17,6 +18,20 @@ function runtimeExpiresAt(): string {
   return new Date(Date.now() + 2 * 60 * 60_000).toISOString()
 }
 
+/**
+ * Key lanes K1 (plan v4 7.1, 7.3): a handoff carries a CLI session id that another surface
+ * resumes, on the subscription. One that ran on a key is refused in K1. With no keyed session
+ * ever recorded this is one failed stat and the route is the b7c620e one.
+ */
+function keyedHandoff(body: Record<string, any> | null | undefined, resolvedCliSessionId?: string): boolean {
+  if (!anyKeyedSessions()) return false
+  const runtime = body?.runtime && typeof body.runtime === 'object' ? body.runtime : {}
+  return isKeyedCosSession(body?.sessionId)
+    || isKeyedSession(runtime.claude?.cliSessionId)
+    || isKeyedSession(runtime.codex?.codexThreadId)
+    || isKeyedSession(resolvedCliSessionId)
+}
+
 function enrichRuntime(body: Record<string, any>): HandoffCreateInput {
   const input: HandoffCreateInput = { ...body }
   const runtime = body.runtime && typeof body.runtime === 'object' ? { ...body.runtime } : {}
@@ -53,7 +68,9 @@ function enrichRuntime(body: Record<string, any>): HandoffCreateInput {
 handoffsRouter.post('/handoffs', async (req, res) => {
   try {
     const body = req.body && typeof req.body === 'object' ? req.body : {}
-    const handoff = await createHandoff(enrichRuntime(body))
+    const input = enrichRuntime(body)
+    if (keyedHandoff(body, (input.runtime as any)?.claude?.cliSessionId)) return res.status(409).json(KEYED_SESSION_REFUSAL)
+    const handoff = await createHandoff(input)
     res.status(201).json({ handoff, context: buildHandoffPromptContext(handoff) })
   } catch (err: any) {
     res.status(500).json({ error: err?.message ?? 'handoff create failed' })
@@ -92,6 +109,10 @@ handoffsRouter.post('/handoffs/:code/claim', async (req, res) => {
   if (!code) return res.status(404).json({ error: 'handoff not found' })
   try {
     const claimedBy = typeof req.body?.claimedBy === 'string' ? req.body.claimedBy : 'unknown'
+    // Key lanes: a handoff saved before its session was known to be keyed is not claimed either.
+    if (anyKeyedSessions() && keyedHandoff((await getHandoff(code)) as Record<string, any> | null)) {
+      return res.status(409).json(KEYED_SESSION_REFUSAL)
+    }
     const handoff = await claimHandoff(code, claimedBy)
     if (!handoff) return res.status(404).json({ error: 'handoff not found' })
     res.json({ handoff, context: buildHandoffPromptContext(handoff) })

package/server/routes/health.ts

@@ -32,6 +32,7 @@ import { meetingAskCapabilities } from '../lib/meeting-ask-runtime.js'
 import { lensGistPublicHealth } from '../lib/lens-gist.js'
 import { meetingSummaryLLMEnabled } from '../lib/meeting-summary.js'
 import { getKeyStatus } from '../lib/openai-key.js'
+import { keyLanesHealthFields, keyProfilesModelsField } from '../lib/key-lanes.js'
 import {
   getCodexModelCatalog,
   getCodexModelCatalogSnapshot,
@@ -550,6 +551,8 @@ healthRouter.get('/health', async (_req, res) => {
     // count only (health is public); the items and their Retry are behind the token at
     // GET /api/maintenance/status.
     crash_loop_parking: crashLoopParkingHealth(),
+    // Key lanes (plan v4 3.1): `details.keyLanes` only while enabled. Absent, never null, when off.
+    ...keyLanesHealthFields(),
   })
 })
 
@@ -616,6 +619,8 @@ healthRouter.get('/models', async (req, res) => {
       refreshedAt: ollamaCatalog.refreshedAt,
     },
     ollamaReady: isOllamaProviderReady(),
+    // Key lanes (plan v4 3.1): `keyProfiles` only while a profile is active. Absent when off.
+    ...keyProfilesModelsField(),
     serverInstanceId: getServerInstanceId(),
     // Minted here rather than on a route of its own: this response is already
     // authenticated, and the mint is stateless, so it costs nothing and stores