@gotcos/glasses-server 6.79.1 → 6.80.0

package/server/lib/live-cues-v2-settings.ts

@@ -5,6 +5,12 @@
 //   3. off (source 'default').
 // Only the exact value '1' forces. Any other env value (unset, '0', 'true') defers to the setting, as it always read as off.
 // An unreadable or malformed settings file reads as no setting, so it fails toward off, never toward spending.
+//
+// 6.79.2: the same file holds COS Control's spend limits (gate, cues per meeting, cooldown, writer calls per local day).
+// Each saved value is validated on read; one out of bounds reads as unset (the default), never as a looser limit. An env
+// var for a limit wins over the saved value and locks it. A file holding only `enabled` is still written as schema 1, so
+// a 6.79.1 server reads it exactly as before; any limit makes it schema 2, which 6.79.1 also reads (it looks only at
+// `enabled`).
 
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname } from 'node:path'
@@ -13,34 +19,66 @@ import { dataPath } from './data-dir.js'
 
 export type LiveCuesV2SettingSource = 'env' | 'setting' | 'default'
 
-/** What the engine and the routes need from the store: the saved choice, or null when there is none. */
-export interface LiveCuesV2SettingReader { stored(): boolean | null }
+/** COS Control's live-cue spend limits (6.79.2). Bounds are inclusive; integer fields take whole numbers only. */
+export const LIVE_CUES_V2_LIMIT_BOUNDS = {
+  gate: { min: 0.5, max: 0.95, default: 0.8, integer: false, env: 'COS_LIVE_CUES_V2_GATE' },
+  maxCuesPerMeeting: { min: 1, max: 25, default: 25, integer: true, env: 'COS_LIVE_CUES_V2_MAX_PER_MEETING' },
+  cooldownSeconds: { min: 20, max: 900, default: 45, integer: true, env: 'COS_LIVE_CUES_V2_COOLDOWN_S' },
+  dailyWriterCalls: { min: 1, max: 500, default: 150, integer: true, env: 'COS_LIVE_CUES_V2_DAILY_WRITER_CALLS' },
+} as const
+export type LiveCuesV2LimitName = keyof typeof LIVE_CUES_V2_LIMIT_BOUNDS
+export const LIVE_CUES_V2_LIMIT_NAMES = Object.keys(LIVE_CUES_V2_LIMIT_BOUNDS) as LiveCuesV2LimitName[]
+export type LiveCuesV2StoredLimits = Partial<Record<LiveCuesV2LimitName, number>>
+
+/** Inside the bounds, and whole where the field is whole. */
+export function limitInBounds(name: LiveCuesV2LimitName, value: unknown): value is number {
+  const b = LIVE_CUES_V2_LIMIT_BOUNDS[name]
+  return typeof value === 'number' && Number.isFinite(value) && value >= b.min && value <= b.max && (!b.integer || Number.isInteger(value))
+}
+
+/** What the engine and the routes need from the store: the saved choice, or null when there is none, and (6.79.2) the
+ *  saved limits. `limits` is optional so a reader without it means "no saved limits". */
+export interface LiveCuesV2SettingReader { stored(): boolean | null; limits?(): LiveCuesV2StoredLimits }
 
 export class LiveCuesV2Settings implements LiveCuesV2SettingReader {
-  /** Loaded once; only this server writes the file, and every write goes through save(). */
-  private cache: { value: boolean | null } | null = null
+  /** Loaded once; only this server writes the file, and every write goes through update(). */
+  private cache: { value: boolean | null; limits: LiveCuesV2StoredLimits } | null = null
   constructor(readonly file: string) {}
 
-  stored(): boolean | null {
-    if (this.cache) return this.cache.value
+  private load(): { value: boolean | null; limits: LiveCuesV2StoredLimits } {
+    if (this.cache) return this.cache
     let value: boolean | null = null
+    const limits: LiveCuesV2StoredLimits = {}
     try {
       if (existsSync(this.file)) {
         const raw = JSON.parse(readFileSync(this.file, 'utf8')) as unknown
-        if (raw && typeof raw === 'object' && !Array.isArray(raw) && typeof (raw as { enabled?: unknown }).enabled === 'boolean') {
-          value = (raw as { enabled: boolean }).enabled
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+          const r = raw as Record<string, unknown>
+          if (typeof r.enabled === 'boolean') value = r.enabled
+          for (const name of LIVE_CUES_V2_LIMIT_NAMES) if (limitInBounds(name, r[name])) limits[name] = r[name] as number
         }
       }
     } catch { value = null }
-    this.cache = { value }
-    return value
+    this.cache = { value, limits }
+    return this.cache
   }
 
+  stored(): boolean | null { return this.load().value }
+  limits(): LiveCuesV2StoredLimits { return { ...this.load().limits } }
+
   /** Atomic and durable. The in-memory value changes only after the file is written, so a failed write changes nothing. */
-  save(enabled: boolean, now: Date = new Date()): void {
+  save(enabled: boolean, now: Date = new Date()): void { this.update({ enabled }, now) }
+
+  /** One write for any mix of the switch and the limits; unnamed fields keep their saved values. */
+  update(patch: { enabled?: boolean; limits?: LiveCuesV2StoredLimits }, now: Date = new Date()): void {
+    const current = this.load()
+    const value = patch.enabled ?? current.value
+    const limits = { ...current.limits, ...patch.limits }
+    const hasLimits = Object.keys(limits).length > 0
+    const body = { schema: hasLimits ? 2 : 1, ...(value === null ? {} : { enabled: value }), ...limits, updatedAt: now.toISOString() }
     mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
-    durableAtomicWriteFileSync(this.file, JSON.stringify({ schema: 1, enabled, updatedAt: now.toISOString() }) + '\n', { mode: 0o600 })
-    this.cache = { value: enabled }
+    durableAtomicWriteFileSync(this.file, JSON.stringify(body) + '\n', { mode: 0o600 })
+    this.cache = { value, limits }
   }
 }
 

package/server/lib/live-cues-v2.ts

@@ -26,7 +26,10 @@ import { JevClient, JevError, estimateJevTokens, resolveJevKey, type JevAnswers
 import { DecisionProviderError, SubqDecisionClient, trackSubqDecisionClient, type DecisionClient } from './decision-provider.js'
 import type { DecisionProvider } from './decision-settings.js'
 import { resolveSubqKey } from './subq-key.js'
-import { liveCuesV2EnvForced, liveCuesV2Settings, resolveLiveCuesV2, type LiveCuesV2SettingReader, type LiveCuesV2SettingSource } from './live-cues-v2-settings.js'
+import {
+  LIVE_CUES_V2_LIMIT_BOUNDS, LIVE_CUES_V2_LIMIT_NAMES, liveCuesV2EnvForced, liveCuesV2Settings, resolveLiveCuesV2,
+  type LiveCuesV2LimitName, type LiveCuesV2SettingReader, type LiveCuesV2SettingSource, type LiveCuesV2StoredLimits,
+} from './live-cues-v2-settings.js'
 import { notesMemory } from './live-cues-v2-notes.js'
 import { meetingLibraryConfigured } from './cos-operations-meetings.js'
 import { getMeetingStore } from './meeting-store.js'
@@ -87,9 +90,13 @@ export const LIVE_CUES_V2_LIMITS = {
 export function liveCuesV2Enabled(env: NodeJS.ProcessEnv = process.env, settings: LiveCuesV2SettingReader | null = liveCuesV2Settings()): boolean {
   return resolveLiveCuesV2(env, settings).enabled
 }
-export function liveCuesV2Gate(env: NodeJS.ProcessEnv = process.env): number {
+/** The gate from env alone, or null when env does not set a usable one (unchanged acceptance: 0.3 to 0.99). */
+function envGate(env: NodeJS.ProcessEnv): number | null {
   const raw = Number(env.COS_LIVE_CUES_V2_GATE)
-  return Number.isFinite(raw) && raw >= 0.3 && raw <= 0.99 ? raw : LIVE_CUES_V2_LIMITS.defaultGate
+  return env.COS_LIVE_CUES_V2_GATE !== undefined && env.COS_LIVE_CUES_V2_GATE.trim() !== '' && Number.isFinite(raw) && raw >= 0.3 && raw <= 0.99 ? raw : null
+}
+export function liveCuesV2Gate(env: NodeJS.ProcessEnv = process.env): number {
+  return envGate(env) ?? LIVE_CUES_V2_LIMITS.defaultGate
 }
 /** 6.79.0 tuning knobs for Friday's rated-cue review. Unset (or empty, which a managed env may pass for an unset optional
  *  variable) is the calibrated default with no log. Anything else outside the accepted form falls back to the default with
@@ -102,12 +109,49 @@ function knobFallback<T>(name: string, raw: string, fallback: T, accepted: strin
   }
   return fallback
 }
-export function liveCuesV2CooldownMs(env: NodeJS.ProcessEnv = process.env): number {
+/** A whole-number env knob (6.79.2 limits): null when unset or empty, the value when inside [min, max], else null with
+ *  one log line per value (the saved setting or the default then applies). */
+function envWhole(env: NodeJS.ProcessEnv, name: string, min: number, max: number): number | null {
+  const raw = env[name]
+  if (raw === undefined || raw.trim() === '') return null
+  const n = /^\d{1,4}$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN
+  return n >= min && n <= max ? n : knobFallback<number | null>(name, raw, null, `a whole number from ${min} to ${max}`)
+}
+/** The cooldown from env alone (whole seconds 20..900), or null when unset, empty or invalid (one log line per value). */
+function envCooldownSeconds(env: NodeJS.ProcessEnv): number | null {
   const raw = env.COS_LIVE_CUES_V2_COOLDOWN_S
-  if (raw === undefined || raw.trim() === '') return LIVE_CUES_V2_LIMITS.cooldownAfterCueMs
+  if (raw === undefined || raw.trim() === '') return null
   const seconds = /^\d{1,3}$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN     // whole seconds only
-  return seconds >= 20 && seconds <= 900 ? seconds * 1000
-    : knobFallback('COS_LIVE_CUES_V2_COOLDOWN_S', raw, LIVE_CUES_V2_LIMITS.cooldownAfterCueMs, 'whole seconds from 20 to 900')
+  return seconds >= 20 && seconds <= 900 ? seconds : knobFallback<number | null>('COS_LIVE_CUES_V2_COOLDOWN_S', raw, null, 'whole seconds from 20 to 900')
+}
+export function liveCuesV2CooldownMs(env: NodeJS.ProcessEnv = process.env): number {
+  const seconds = envCooldownSeconds(env)
+  return seconds === null ? LIVE_CUES_V2_LIMITS.cooldownAfterCueMs : seconds * 1000
+}
+
+/** One resolved limit: where its value came from, and whether COS Control may change it (an env var locks it). */
+export interface LiveCuesV2Limit { value: number; source: LiveCuesV2SettingSource; locked: boolean; min: number; max: number; default: number }
+export type LiveCuesV2Limits = Record<LiveCuesV2LimitName, LiveCuesV2Limit>
+/** 6.79.2: env wins and locks; else the saved setting; else the default. Read on every evaluation, so a saved change
+ *  applies from the next one with no restart. */
+export function resolveLiveCuesV2Limits(env: NodeJS.ProcessEnv = process.env, settings: LiveCuesV2SettingReader | null = liveCuesV2Settings()): LiveCuesV2Limits {
+  let saved: LiveCuesV2StoredLimits = {}
+  try { saved = settings?.limits?.() ?? {} } catch { saved = {} }
+  const fromEnv: Record<LiveCuesV2LimitName, number | null> = {
+    gate: envGate(env),
+    maxCuesPerMeeting: envWhole(env, LIVE_CUES_V2_LIMIT_BOUNDS.maxCuesPerMeeting.env, 1, 25),
+    cooldownSeconds: envCooldownSeconds(env),
+    dailyWriterCalls: envWhole(env, LIVE_CUES_V2_LIMIT_BOUNDS.dailyWriterCalls.env, 1, 500),
+  }
+  const out = {} as LiveCuesV2Limits
+  for (const name of LIVE_CUES_V2_LIMIT_NAMES) {
+    const b = LIVE_CUES_V2_LIMIT_BOUNDS[name]
+    const e = fromEnv[name], v = saved[name]
+    out[name] = e !== null ? { value: e, source: 'env', locked: true, min: b.min, max: b.max, default: b.default }
+      : v !== undefined ? { value: v, source: 'setting', locked: false, min: b.min, max: b.max, default: b.default }
+        : { value: b.default, source: 'default', locked: false, min: b.min, max: b.max, default: b.default }
+  }
+  return out
 }
 export function liveCuesV2JudgeKeep(env: NodeJS.ProcessEnv = process.env): number {
   const raw = env.COS_LIVE_CUES_V2_JUDGE_KEEP
@@ -244,11 +288,22 @@ export function localWeekStart(now: Date, zone: string): string {
 
 // ── Durable state: weekly ceiling, tombstones, pauses, per-meeting counters ─────
 interface MeetingCounters { cues: number; writerCalls: number; at: number }
+/** 6.79.2: usage on the local calendar day (in the stored zone), for the daily writer ceiling and COS Control's readout. */
+export interface LiveCuesV2DayUsage { writerCalls: number; writerTokensIn: number; writerTokensOut: number; cues: number; jevTokens: number }
+const DAY_FIELDS = ['writerCalls', 'writerTokensIn', 'writerTokensOut', 'cues', 'jevTokens'] as const
 interface DurableState {
   zone: string; weekStart: string; writerCalls: number
   ended: Record<string, number>; paused: Record<string, boolean>; pauseSeq: Record<string, number>
   meetings: Record<string, MeetingCounters>
+  day: string; today: LiveCuesV2DayUsage
 }
+/** Local calendar day (YYYY-MM-DD) in `zone`. Intl, never toISOString: a UTC key flips the day at 19:00 Central. */
+export function localDay(now: Date, zone: string): string {
+  return new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now)
+}
+const zeroDay = (): LiveCuesV2DayUsage => ({ writerCalls: 0, writerTokensIn: 0, writerTokensOut: 0, cues: 0, jevTokens: 0 })
+/** Saturated writer calls: an unreadable, future-dated or malformed day fails toward NOT spending, like the week. */
+const spentDay = (): LiveCuesV2DayUsage => ({ ...zeroDay(), writerCalls: Number.MAX_SAFE_INTEGER })
 function validZone(zone: unknown): string | null {
   if (typeof zone !== 'string' || !zone) return null
   try { new Intl.DateTimeFormat('en-CA', { timeZone: zone }); return zone } catch { return null }
@@ -278,11 +333,20 @@ export class LiveCuesV2Store {
       const calls = Number(s.writerCalls ?? 0)
       // A future week key or a negative/non-numeric count fails toward NOT spending: the week is saturated.
       const saturated = futureWeek || (sameWeek && !(calls >= 0))
-      return { zone, weekStart: week, writerCalls: saturated ? Number.MAX_SAFE_INTEGER : sameWeek ? calls : 0, ended, paused, pauseSeq, meetings }
+      const day = localDay(this.now(), zone)
+      const t = (s.today ?? {}) as Partial<Record<string, unknown>>
+      let today: LiveCuesV2DayUsage
+      if (s.day === undefined || (typeof s.day === 'string' && s.day < day)) today = zeroDay()
+      else if (s.day !== day) today = spentDay()                                   // a future or malformed day
+      else today = DAY_FIELDS.every(f => t[f] === undefined || Number(t[f]) >= 0)
+        ? Object.fromEntries(DAY_FIELDS.map(f => [f, Number(t[f] ?? 0)])) as unknown as LiveCuesV2DayUsage
+        : spentDay()
+      return { zone, weekStart: week, writerCalls: saturated ? Number.MAX_SAFE_INTEGER : sameWeek ? calls : 0, ended, paused, pauseSeq, meetings, day, today }
     } catch {
-      // An unreadable file fails closed for this week (no spending) but keeps cues off nothing else.
+      // An unreadable file fails closed for this week and this day (no spending) but keeps cues off nothing else.
       const zone = validZone(Intl.DateTimeFormat().resolvedOptions().timeZone) ?? 'UTC'
-      return { zone, weekStart: localWeekStart(this.now(), zone), writerCalls: Number.MAX_SAFE_INTEGER, ended: {}, paused: {}, pauseSeq: {}, meetings: {} }
+      return { zone, weekStart: localWeekStart(this.now(), zone), writerCalls: Number.MAX_SAFE_INTEGER, ended: {}, paused: {}, pauseSeq: {}, meetings: {},
+        day: localDay(this.now(), zone), today: spentDay() }
     }
   }
   private write(s: DurableState): void {
@@ -294,6 +358,7 @@ export class LiveCuesV2Store {
     const s = this.read()
     if (s.writerCalls >= cap) return false
     s.writerCalls += 1
+    s.today.writerCalls += 1
     const m = s.meetings[sessionId] ?? { cues: 0, writerCalls: 0, at: 0 }
     s.meetings[sessionId] = { ...m, writerCalls: m.writerCalls + 1, at: this.now().getTime() }
     this.write(s)
@@ -303,8 +368,21 @@ export class LiveCuesV2Store {
     const s = this.read()
     const m = s.meetings[sessionId] ?? { cues: 0, writerCalls: 0, at: 0 }
     s.meetings[sessionId] = { ...m, cues: m.cues + 1, at: this.now().getTime() }
+    s.today.cues += 1
+    this.write(s)
+  }
+  /** Tokens one evaluation spent (writer in and out, the decision provider's gate and judge). One write; nothing when zero. */
+  recordUsage(u: { writerTokensIn?: number; writerTokensOut?: number; jevTokens?: number }): void {
+    const add = (n: number | undefined) => (typeof n === 'number' && Number.isFinite(n) && n > 0 ? Math.round(n) : 0)
+    const inc = { writerTokensIn: add(u.writerTokensIn), writerTokensOut: add(u.writerTokensOut), jevTokens: add(u.jevTokens) }
+    if (!inc.writerTokensIn && !inc.writerTokensOut && !inc.jevTokens) return
+    const s = this.read()
+    s.today.writerTokensIn += inc.writerTokensIn; s.today.writerTokensOut += inc.writerTokensOut; s.today.jevTokens += inc.jevTokens
     this.write(s)
   }
+  /** Today's usage (local day in the stored zone). A saturated (fail-closed) day reads its writer calls as the sentinel. */
+  today(): { day: string } & LiveCuesV2DayUsage { const s = this.read(); return { day: s.day, ...s.today } }
+  dailyWriterCalls(): number { return this.read().today.writerCalls }
   counters(sessionId: string): { cues: number; writerCalls: number } {
     const m = this.read().meetings[sessionId]
     return { cues: m?.cues ?? 0, writerCalls: m?.writerCalls ?? 0 }
@@ -544,6 +622,15 @@ export class LiveCuesV2Engine {
   constructor(private readonly deps: LiveCuesV2Deps) {}
 
   private enabled(): boolean { return liveCuesV2Enabled(this.deps.env, this.deps.settings) }
+  /** 6.79.2: the spend limits as they stand now (env, else COS Control's saved values, else the defaults). The writer
+   *  cap per meeting stays twice the cue cap. */
+  private limits(): { gate: number; maxCues: number; writerCap: number; cooldownMs: number; dailyWriterCalls: number } {
+    const r = resolveLiveCuesV2Limits(this.deps.env, this.deps.settings)
+    return { gate: r.gate.value, maxCues: r.maxCuesPerMeeting.value, writerCap: 2 * r.maxCuesPerMeeting.value,
+      cooldownMs: r.cooldownSeconds.value * 1000, dailyWriterCalls: r.dailyWriterCalls.value }
+  }
+  /** Today's usage for COS Control (local day in the stored zone). */
+  today(): { day: string } & LiveCuesV2DayUsage { return this.deps.store.today() }
 
   capability(): LiveCuesV2Capability {
     const model = liveCuesV2Model(this.deps.env)
@@ -620,10 +707,12 @@ export class LiveCuesV2Engine {
   }
 
   private stopReasonOf(s: Session, counters: { cues: number; writerCalls: number }): LiveCuesV2StopReason | null {
-    const L = LIVE_CUES_V2_LIMITS
+    const lim = this.limits()
     if (s.breaker) return 'breaker_open'
-    if (counters.cues >= L.maxCuesPerMeeting || counters.writerCalls >= L.maxWriterCallsPerMeeting) return 'meeting_cap'
-    if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return 'budget_exhausted'
+    if (counters.cues >= lim.maxCues || counters.writerCalls >= lim.writerCap) return 'meeting_cap'
+    // The daily ceiling reads as budget_exhausted on the wire: the shared stop-reason union (pinned with the companion's
+    // copy) has no daily_cap. The trace says daily_cap.
+    if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env) || this.deps.store.dailyWriterCalls() >= lim.dailyWriterCalls) return 'budget_exhausted'
     return s.stopReason
   }
 
@@ -665,10 +754,12 @@ export class LiveCuesV2Engine {
     if (s.breaker) return this.traceSkip(s, 'breaker_open', nowMs)
     if (this.deps.store.isPaused(sessionId)) return this.traceSkip(s, 'paused', nowMs)
     if (s.wordsSinceEval < L.minNewWords) return
-    if (nowMs - s.lastEvalAt < L.minIntervalMs || nowMs - s.lastCueAt < liveCuesV2CooldownMs(this.deps.env)) return
+    const lim = this.limits()
+    if (nowMs - s.lastEvalAt < L.minIntervalMs || nowMs - s.lastCueAt < lim.cooldownMs) return
     const counters = this.deps.store.counters(sessionId)
-    if (counters.cues >= L.maxCuesPerMeeting || counters.writerCalls >= L.maxWriterCallsPerMeeting) return this.traceSkip(s, 'meeting_cap', nowMs)
+    if (counters.cues >= lim.maxCues || counters.writerCalls >= lim.writerCap) return this.traceSkip(s, 'meeting_cap', nowMs)
     if (this.deps.store.weeklyUsed() >= liveCuesV2WeeklyCap(this.deps.env)) return this.traceSkip(s, 'budget_exhausted', nowMs)  // before the gate
+    if (this.deps.store.dailyWriterCalls() >= lim.dailyWriterCalls) return this.traceSkip(s, 'daily_cap', nowMs)              // before the gate
     if (this.deps.busy()) return this.traceSkip(s, 'busy', nowMs)
     await this.evaluate(s)
   }
@@ -704,7 +795,7 @@ export class LiveCuesV2Engine {
       const gate = await this.deps.gate(s.title, window, abort.signal, provider)
       const pCue = Number.isFinite(gate.pCue) ? gate.pCue : 0
       Object.assign(trace, { gateMs: Date.now() - t0, pCue: round(pCue), cueKind: gate.kind, lookup: gate.lookup, gateTokens: gate.tokens })
-      if (pCue < liveCuesV2Gate(this.deps.env)) { trace.outcome = 'gate_silent'; s.stopReason = null; return }
+      if (pCue < this.limits().gate) { trace.outcome = 'gate_silent'; s.stopReason = null; return }
       if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
 
       const t1 = Date.now()
@@ -731,6 +822,10 @@ export class LiveCuesV2Engine {
       trace.kept = kept.length
       if (abort.signal.aborted) { trace.outcome = 'cancelled'; return }
 
+      // 6.79.2: limits lowered while this evaluation ran apply before the writer is charged.
+      const lim = this.limits(), counters = this.deps.store.counters(s.sessionId)
+      if (counters.cues >= lim.maxCues || counters.writerCalls >= lim.writerCap) { trace.outcome = 'meeting_cap'; return }
+      if (this.deps.store.dailyWriterCalls() >= lim.dailyWriterCalls) { trace.outcome = 'daily_cap'; s.stopReason = 'budget_exhausted'; return }
       if (!this.deps.store.charge(liveCuesV2WeeklyCap(this.deps.env), s.sessionId)) { trace.outcome = 'budget_exhausted'; s.stopReason = 'budget_exhausted'; return }
       const { version, system } = liveCuesV2WriterSystem(this.deps.env)
       const model = liveCuesV2Model(this.deps.env)
@@ -791,6 +886,11 @@ export class LiveCuesV2Engine {
       if (error instanceof LensGistLimitError || s.failures >= L.breakerFailures) s.breaker = true
     } finally {
       clearTimeout(wall)
+      // 6.79.2: today's spend for COS Control, from the numbers this evaluation traced. One write; best effort.
+      try {
+        this.deps.store.recordUsage({ writerTokensIn: trace.writerIn as number | undefined, writerTokensOut: trace.writerOut as number | undefined,
+          jevTokens: (Number(trace.gateTokens) || 0) + (Number(trace.judgeTokens) || 0) })
+      } catch { /* the readout is best effort; the trace row still has the numbers */ }
       if (wallHit && trace.outcome === 'cancelled') { trace.outcome = 'failure'; trace.error = 'wall_timeout'; s.failures += 1; if (s.failures >= L.breakerFailures) s.breaker = true }
       if (trace.outcome === 'cancelled' && abort.signal.reason === V2_OFF) trace.cancelReason = V2_OFF
       s.inFlight = null
@@ -850,16 +950,44 @@ export function liveCuesV2SettingsView(env: NodeJS.ProcessEnv = process.env): Li
 /** Save the switch. Off while env forces it on is refused and changes nothing. Turning it off ends cue evaluation for running
  *  meetings at once; turning it on applies from each meeting's next evaluation. */
 export function setLiveCuesV2Enabled(enabled: boolean, env: NodeJS.ProcessEnv = process.env): { ok: true; view: LiveCuesV2SettingsResponse } | { ok: false; error: 'env_forced' } {
-  if (!enabled && liveCuesV2EnvForced(env)) return { ok: false, error: 'env_forced' }
+  const r = applyLiveCuesV2Settings({ enabled, limits: {} }, env)
+  if (!r.ok) return { ok: false, error: 'env_forced' }
+  return { ok: true, view: liveCuesV2SettingsView(env) }
+}
+
+/** GET /api/live-cues/v2/settings?v=2 and POST {v: 2, ...} (6.79.2): the v1 body plus the spend limits and today's usage.
+ *  Without v=2 the routes answer exactly the v1 body, so an older COS Control is unaffected. */
+export interface LiveCuesV2SettingsResponseV2 extends LiveCuesV2SettingsResponse {
+  v: 2
+  limits: LiveCuesV2Limits
+  /** Always twice the cue cap. */
+  writerCallsPerMeeting: number
+  today: { day: string } & LiveCuesV2DayUsage
+}
+export function liveCuesV2SettingsViewV2(env: NodeJS.ProcessEnv = process.env): LiveCuesV2SettingsResponseV2 {
+  const limits = resolveLiveCuesV2Limits(env, liveCuesV2Settings())
+  return { ...liveCuesV2SettingsView(env), v: 2, limits, writerCallsPerMeeting: 2 * limits.maxCuesPerMeeting.value, today: liveCuesV2().today() }
+}
+
+/** Save the switch and any limits in ONE write, after every check passed: nothing is saved when any part is refused.
+ *  Turning v2 off stops evaluations in flight; limits apply from each meeting's next evaluation. */
+export function applyLiveCuesV2Settings(patch: { enabled?: boolean; limits: LiveCuesV2StoredLimits }, env: NodeJS.ProcessEnv = process.env):
+  { ok: true } | { ok: false; error: 'env_forced' } | { ok: false; error: 'env_locked'; fields: LiveCuesV2LimitName[] } {
+  if (patch.enabled === false && liveCuesV2EnvForced(env)) return { ok: false, error: 'env_forced' }
+  const current = resolveLiveCuesV2Limits(env, liveCuesV2Settings())
+  const locked = (Object.keys(patch.limits) as LiveCuesV2LimitName[]).filter(name => current[name].locked)
+  if (locked.length) return { ok: false, error: 'env_locked', fields: locked }
   const wasOn = liveCuesV2Enabled(env)
-  liveCuesV2Settings().save(enabled)
+  liveCuesV2Settings().update(patch)
   if (wasOn && !liveCuesV2Enabled(env)) {
     const aborted = engine?.suspend() ?? 0
     console.log(`[live-cues-v2] switched off by setting; ${aborted} evaluation(s) stopped`)
   } else if (!wasOn && liveCuesV2Enabled(env)) {
     console.log('[live-cues-v2] switched on by setting')
   }
-  return { ok: true, view: liveCuesV2SettingsView(env) }
+  const changed = Object.entries(patch.limits).map(([k, v]) => `${k}=${v}`).join(' ')
+  if (changed) console.log(`[live-cues-v2] limits saved: ${changed}`)
+  return { ok: true }
 }
 /** What /api/health, /api/models and the status route advertise: NOTHING while v2 is switched off, so a 6.10.642
  *  companion treats the server exactly like a v1 server (v1 cues keep their own capability and indicator). */

package/server/lib/model-router.ts

@@ -4,10 +4,12 @@ import { callCursorStreaming } from './cursor-bridge.js'
 import { callOllamaStreaming } from './ollama-bridge.js'
 import {
   getOrCreateSession,
+  getSessionBinding,
   getSessionModel,
   setSessionModel,
   type ModelPreference,
   type PromptReference,
+  type SessionModelBinding,
 } from './conversation.js'
 import {
   DEFAULT_MODEL,
@@ -15,7 +17,6 @@ import {
   isClaudeModel,
   isCursorModel,
   isOllamaModel,
-  normalizeModelPreference,
 } from '../../shared/model-preference.js'
 import {
   getCursorModelCatalog,
@@ -27,6 +28,14 @@ import {
   isOllamaProviderReady,
 } from './ollama-catalog.js'
 import type { ModelImageInput } from './model-image-input.js'
+import { parsePreference } from '../../shared/key-preference.js'
+import {
+  closedEnvDefaultModel,
+  keyProfileEngineRunner,
+  keyProfileUnavailableLine,
+  resolveKeyProfileTurn,
+  type KeyProfileTurnCallbacks,
+} from './key-profile-routing.js'
 
 // Bridges return as soon as their subprocess is spawned, while completion is
 // delivered later through callbacks. This keyed tail queue therefore releases
@@ -57,8 +66,8 @@ export async function acquireModelSessionRunLock(sessionId: string): Promise<()
 export async function callModelStreaming(
   query: string,
   sessionId: string | undefined,
-  callbacks: StreamCallbacks,
-  model?: ModelPreference,
+  callbacks: StreamCallbacks & KeyProfileTurnCallbacks,
+  model?: SessionModelBinding,
   images?: ModelImageInput[],
   reference?: PromptReference,
   globalMsgNum?: number,
@@ -71,12 +80,21 @@ export async function callModelStreaming(
     throw new Error('model-router: request aborted before the model run started.')
   }
 
+  // Key lanes K1 (plan 5.2): the request model is ACCEPTED here. parsePreference returns exactly
+  // normalizeModelPreference for every model slot; only a well formed `profile:<id>` is new.
+  const requested = parsePreference(model)
   const sessionModel = getSessionModel(sid)
+  // A session bound to a profile reads null from the closed getSessionModel. It is looked up
+  // only when nothing else names the model, so every 6.79.0 path stays exactly as it was.
+  const bound = requested ?? (sessionModel === null ? parsePreference(getSessionBinding(sid)) : undefined)
+  const profileId = bound?.kind === 'profile' ? bound.id : undefined
+  if (profileId !== undefined) return await runKeyProfileRoute(query, sid, callbacks, profileId, release, images, reference, globalMsgNum, options)
+
   // COS_G2_DEFAULT_MODEL is the documented default-model switch (CHANGELOG 6.1.0);
   // it must win over the hardcoded DEFAULT_MODEL on this primary query path, not
-  // just the OpenAI-compat surface.
-  const envDefault = normalizeModelPreference(process.env.COS_G2_DEFAULT_MODEL)
-  const resolvedModel = normalizeModelPreference(model) ?? sessionModel ?? envDefault ?? DEFAULT_MODEL
+  // just the OpenAI-compat surface. A profile id there is ignored (plan 5.2: closed).
+  const envDefault = closedEnvDefaultModel(process.env.COS_G2_DEFAULT_MODEL)
+  const resolvedModel = (requested?.kind === 'model' ? requested.value : undefined) ?? sessionModel ?? envDefault ?? DEFAULT_MODEL
 
   setSessionModel(sid, resolvedModel)
 
@@ -86,8 +104,9 @@ export async function callModelStreaming(
     terminal = true
     release()
   }
+  const { onKeyProfileTurn: _onKeyProfileTurn, ...streamCallbacks } = callbacks
   const lockedCallbacks: StreamCallbacks = {
-    ...callbacks,
+    ...streamCallbacks,
     onDone: async (fullText, completedModel, cliSessionId, metadata) => {
       try {
         return await callbacks.onDone(fullText, completedModel, cliSessionId, metadata)
@@ -142,3 +161,73 @@ export async function callModelStreaming(
     throw err
   }
 }
+
+/**
+ * Key lanes K1 (plan 5.2): a turn bound to `profile:<id>`. Refused with a lens line, never
+ * answered on the subscription, when lanes are off, the profile is unknown, disabled or keyless,
+ * no runner is registered for its engine, or it is a scheduled dispatch.
+ */
+async function runKeyProfileRoute(
+  query: string,
+  sid: string,
+  callbacks: StreamCallbacks & KeyProfileTurnCallbacks,
+  profileId: string,
+  release: () => void,
+  images?: ModelImageInput[],
+  reference?: PromptReference,
+  globalMsgNum?: number,
+  options?: CallOptions,
+): Promise<string> {
+  let terminal = false
+  const releaseTerminal = () => {
+    if (terminal) return
+    terminal = true
+    release()
+  }
+  const { onKeyProfileTurn, ...streamCallbacks } = callbacks
+  const lockedCallbacks: StreamCallbacks = {
+    ...streamCallbacks,
+    onDone: async (fullText, completedModel, cliSessionId, metadata) => {
+      try {
+        return await callbacks.onDone(fullText, completedModel, cliSessionId, metadata)
+      } finally {
+        releaseTerminal()
+      }
+    },
+    onError: async (error) => {
+      try {
+        await callbacks.onError(error)
+      } finally {
+        releaseTerminal()
+      }
+    },
+  }
+  try {
+    if (options?.dispatch) {
+      console.info(`[key-lanes] refused kind=dispatch profile=${profileId}`)
+      await lockedCallbacks.onError('dispatch_requires_claude')
+      return sid
+    }
+    const resolved = resolveKeyProfileTurn(profileId)
+    if (!resolved.ok) {
+      // QA G4: one line per refusal kind.
+      console.info(`[key-lanes] refused kind=${resolved.code} profile=${profileId}`)
+      await lockedCallbacks.onError(resolved.message)
+      return sid
+    }
+    const runner = keyProfileEngineRunner(resolved.turn.profile.engine)
+    if (!runner) {
+      console.info(`[key-lanes] refused kind=no_runner engine=${resolved.turn.profile.engine}`)
+      await lockedCallbacks.onError(keyProfileUnavailableLine(resolved.turn.profile.label))
+      return sid
+    }
+    // Persisted by syntax (conversation.ts) so the next turn of this session stays on the key,
+    // unless this is the one-turn plan-limit offer (QA U9): then the session keeps its model.
+    if (!options?.keyTurnOnly) setSessionModel(sid, resolved.turn.binding)
+    onKeyProfileTurn?.(resolved.turn)
+    return await runner(query, sid, lockedCallbacks, resolved.turn, images, reference, globalMsgNum, options)
+  } catch (err) {
+    releaseTerminal()
+    throw err
+  }
+}

package/server/lib/morning-brief-config.ts

@@ -19,6 +19,7 @@ import { chmodSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
+import { KEY_PROFILE_REJECT_CODE, KEY_PROFILE_SCHEDULED_REJECT, keyProfileRejectApplies } from './key-profile-rejects.js'
 import {
   normalizeEffortPreference,
   normalizeModelPreference,
@@ -410,6 +411,8 @@ export function applyMorningBriefPatch(current: MorningBriefConfig, raw: unknown
       delete next.model
     } else {
       const model = normalizeModelPreference(patch.model)
+      // Key lanes K1 (plan 5.2): Reject, and say why. A brief always runs on the subscription.
+      if (!model && keyProfileRejectApplies(patch.model)) throw new MorningBriefConfigError(KEY_PROFILE_REJECT_CODE, KEY_PROFILE_SCHEDULED_REJECT)
       if (!model) throw new MorningBriefConfigError('invalid_model', 'Unknown model preference.')
       next.model = model
     }

package/server/lib/native-head.ts

@@ -195,6 +195,8 @@ export interface NativeHeadDirs {
   claudeProjectsDir: string
   /** `<COS_AGENT_SESSIONS_HOME|~>/.codex/sessions` */
   codexSessionsDir: string
+  /** Key lanes (plan v4 8.2): each keyed profile home's `sessions`, searched after the server's. Absent with no profile home. */
+  codexProfileSessionsDirs?: string[]
   /** `<COS_AGENT_SESSIONS_HOME|~>/.cursor/projects` */
   cursorProjectsDir: string
 }
@@ -495,7 +497,16 @@ function claudeTranscriptPath(threadId: string, deps: NativeHeadDeps): string |
  * certified.
  */
 function codexRolloutPath(threadId: string, deps: NativeHeadDeps): string | null {
-  const root = deps.dirs.codexSessionsDir
+  const found = codexRolloutPathIn(deps.dirs.codexSessionsDir, threadId, deps)
+  if (found !== null || !deps.dirs.codexProfileSessionsDirs) return found
+  for (const root of deps.dirs.codexProfileSessionsDirs) {
+    const keyed = codexRolloutPathIn(root, threadId, deps)
+    if (keyed !== null) return keyed
+  }
+  return null
+}
+
+function codexRolloutPathIn(root: string, threadId: string, deps: NativeHeadDeps): string | null {
   if (!deps.dirExists(root)) return null
 
   let scanned = 0
@@ -626,6 +637,7 @@ export function realNativeHeadDirs(): NativeHeadDirs {
     claudeProjectsDir: roots.claudeProjects,
     codexSessionsDir: roots.codexSessions,
     cursorProjectsDir: roots.cursorProjects,
+    ...(roots.codexProfileSessions ? { codexProfileSessionsDirs: roots.codexProfileSessions } : {}),
   }
 }
 

package/server/lib/occupancy-probes.ts

@@ -63,6 +63,7 @@ import { activeSqliteReaderPids, cliChatLastWriteMs } from './cursor-session-mod
 // about which directory "empty" was observed in.
 export { claudeSessionsDir } from '../routes/claude-sessions.js'
 import { claudeSessionsDir } from '../routes/claude-sessions.js'
+import { profileCodexHomeSubdirs } from './codex-homes.js'
 
 /**
  * `<CODEX_HOME|~/.codex>/thread-writer-locks`.
@@ -78,10 +79,13 @@ export function codexLocksDir(): string {
 
 export function realOccupancyDirs(): OccupancyDirs {
   const home = process.env.COS_AGENT_SESSIONS_HOME?.trim() || homedir()
+  const profileLocks = profileCodexHomeSubdirs('thread-writer-locks')
   return {
     claudeSessionsDir: claudeSessionsDir(),
     codexLocksDir: codexLocksDir(),
     cursorChatsDir: join(home, '.cursor', 'chats'),
+    // Key lanes K1 (plan v4 8.2): absent with no keyed profile home, so the dirs are 963fe25's.
+    ...(profileLocks.length ? { codexProfileLocksDirs: profileLocks } : {}),
   }
 }