@gotcos/glasses-server 6.76.1 → 6.78.0

package/server/lib/claude-bridge.ts

@@ -62,6 +62,10 @@ import { terminateProviderProcess } from './provider-process-lifecycle.js'
 import { teeJobTrail, type JobTrailDraft } from './job-trail.js'
 import { claudeSupportsSessionName } from './claude-cli-support.js'
 import { applyTurnRequestEnv, createTurnRequestBinding, spawnWithTurnRequest } from './turn-request.js'
+import { STEER_REAPER_MS, STEER_SETTLE_MS, SteerTracker, composeFirstContent, encodeUserLine, steerClock, type SteerPort } from './claude-steer.js'
+import { randomUUID } from 'node:crypto'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 // Inactivity = no stdout data for this long → kill (catches stalls)
 const INACTIVITY_BY_MODEL: Record<ClaudeModelPreference, number> = {
@@ -407,6 +411,12 @@ export interface CallOptions {
   dispatch?: { restricted: true; tools: readonly string[] }
   /** 6.58.2: `claude --name` for a session this COS session starts fresh (QueryJobRequest.sessionName). */
   sessionName?: string
+  /**
+   * 6.78.0 Messages steer: the job's steer port. Present only when the coordinator decided the
+   * run is steerable (lib/claude-steer.ts). Absent, every argument and every stdin byte is the
+   * 6.77.0 one. A dispatch never steers.
+   */
+  steer?: SteerPort
 }
 
 export async function callClaudeStreaming(
@@ -599,6 +609,10 @@ export async function callClaudeStreaming(
   if (startsOwnCliSession && !options?.dispatch && options?.sessionName && await claudeSupportsSessionName()) {
     args.push(`--name=${options.sessionName}`)
   }
+  // 6.78.0 steer: the prompt becomes one stream-json line and stdin stays open for steers.
+  // These two flags and nothing else (plan P4); the CLI probe passed before the port existed.
+  const steerPort = options?.dispatch ? undefined : options?.steer
+  if (steerPort) args.push('--input-format', 'stream-json', '--replay-user-messages')
 
   // Strip CLAUDECODE env var so claude -p doesn't think it's nested
   const env = { ...process.env }
@@ -612,6 +626,9 @@ export async function callClaudeStreaming(
     : defaultWallMax
   const wallMax = isExtendedQuery(query) ? Math.max(WALL_MAX_EXTENDED_MS, effortWallMax) : effortWallMax
   const startTime = Date.now()
+  // 6.78.0 steer (P7 S7): the wall clock's start on the monotonic steer clock, next to the
+  // wall timer it describes, so the coordinator's cut-off reads the same clock after a sleep.
+  const steerStartedAt = steerClock()
   const run = startClaudeRun({
     cosSessionId: sid,
     model: resolvedModel,
@@ -627,9 +644,12 @@ export async function callClaudeStreaming(
 
   // Ultracode is a CLI-only orchestration keyword; history/chat keeps the
   // original user text so the keyword never appears on the lens.
-  const cliQuery = resolvedEffort === 'ultracode'
+  const promptText = resolvedEffort === 'ultracode'
     ? `${fullQuery}\n\n${ULTRACODE_KEYWORD}`
     : fullQuery
+  // 6.78.0 steer: steers that arrived before the first line ride in it (never in request.query
+  // or the fingerprint). They are journaled `included` once the line is written.
+  const cliQuery = steerPort ? composeFirstContent(promptText, steerPort.drainForCompose()) : promptText
   // The COS UserPromptSubmit hook sees `cliQuery` (image preamble, attachment block and
   // all). This private file hands it the user's own words, bound by the hash of exactly
   // what goes on stdin; the file dies with the child. See lib/turn-request.ts.
@@ -651,6 +671,57 @@ export async function callClaudeStreaming(
   let terminalTextError: string | null = null
   let lastActivity = Date.now() // Tracks last stdout data for inactivity timeout
   let receivedStreamEvents = false  // Track if CLI emits stream_event (vs older assistant-only format)
+  // 6.78.0 steer state (all inert without a port).
+  // The prompt line's uuid is the job's turn id when it is one (the plan's wire shape), so a
+  // result's user_message_uuids names the turn; anything else gets a fresh uuid.
+  const steerTracker = steerPort
+    ? new SteerTracker(typeof options?.turnId === 'string' && UUID_RE.test(options.turnId) ? options.turnId.toLowerCase() : randomUUID())
+    : null
+  let steerSettling = false            // a result left a steer uncovered: the settle window is open
+  let steerSettleTimer: ReturnType<typeof setTimeout> | null = null
+  let steerNeedsSeparator = false      // text after such a result is a second turn
+  let steerCheckpoint: string | null = null
+  let steerStdinEnded = false
+  let steerReaper: ReturnType<typeof setTimeout> | null = null
+  let steerKilled = false
+  let childClosed = false
+  function endSteerStdin() {
+    if (!steerPort || steerStdinEnded) return
+    steerStdinEnded = true
+    steerPort.close()
+    try { proc.stdin.end() } catch { /* the child is gone */ }
+  }
+  /**
+   * 6.78.0 (P7 S2): the run ended with steer lines written that no result covered. Ending
+   * stdin would let the CLI run those queued lines unwatched (up to the 15 s reaper), and a
+   * later --resume of its session would inherit them while the job reads them not_applied,
+   * so the client sends them again. Instead: the port closes, the child is killed, and the
+   * CLI session mapping is dropped so the next Ask starts a fresh session.
+   */
+  function abandonUncoveredSteers() {
+    steerStdinEnded = true
+    steerPort!.close()
+    if (cliSessionMap.delete(resolvedCliKey)) scheduleCliSessionSave()
+    if (childClosed || terminationRequested || steerKilled) return
+    steerKilled = true
+    void terminateProviderProcess(proc)
+  }
+  /** A finished steer-mode run whose child has not exited by now is terminated (stdin is closed). */
+  function armSteerReaper() {
+    if (!steerPort || steerReaper || childClosed || steerKilled) return
+    steerReaper = setTimeout(() => {
+      if (!childClosed && !terminationRequested) void terminateProviderProcess(proc)
+    }, STEER_REAPER_MS)
+    steerReaper.unref?.()
+  }
+  /** Second-turn text keeps the partial a prefix of the answer: one separator first. */
+  function steerSeparator() {
+    if (!steerNeedsSeparator) return
+    steerNeedsSeparator = false
+    if (!fullText) return
+    fullText += '\n\n'
+    callbacks.onChunk('\n\n')
+  }
   const toolInputs = new Map<number, { name: string; json: string }>()
 
   function cleanupImages() {
@@ -683,6 +754,7 @@ export async function callClaudeStreaming(
     }
     finalized = true
     cleanup()
+    armSteerReaper()
     cleanupImages()
 
     // The coordinator persists the final provider text before conversation
@@ -796,6 +868,7 @@ export async function callClaudeStreaming(
     if (finalized) return
     finalized = true
     cleanup()
+    armSteerReaper()
     cleanupImages()
     outputImagePublisher?.cleanup()
     removeExchange(sid, pendingUserExchange)
@@ -860,6 +933,11 @@ export async function callClaudeStreaming(
   function resetInactivity() {
     lastActivity = Date.now()
     clearTimeout(inactivityTimer)
+    // 6.78.0 steer: the inactivity timer pauses during the settle window; output resets the settle.
+    if (steerSettling) {
+      armSteerSettle()
+      return
+    }
     inactivityTimer = setTimeout(() => {
       const elapsed = Math.round((Date.now() - startTime) / 1000)
       void terminateForTerminal('inactivity timeout', result => finalizeError(
@@ -869,10 +947,33 @@ export async function callClaudeStreaming(
     }, inactivityMs)
   }
 
+  /**
+   * 6.78.0 steer: a result covered the prompt but not every steer. Wait for the next result,
+   * at most STEER_SETTLE_MS of quiet; then close stdin (the CLI runs anything queued and
+   * exits) and let the close finish the run with what it has.
+   */
+  function armSteerSettle() {
+    if (steerSettleTimer) clearTimeout(steerSettleTimer)
+    steerSettleTimer = setTimeout(() => {
+      steerSettleTimer = null
+      steerSettling = false
+      endSteerStdin()
+      if (!finalized) resetInactivity()
+    }, STEER_SETTLE_MS)
+    steerSettleTimer.unref?.()
+  }
+  function enterSteerSettle() {
+    steerSettling = true
+    clearTimeout(inactivityTimer)
+    armSteerSettle()
+  }
+
   // ─── Wall clock max: absolute cap ───
 
   const wallTimer = setTimeout(() => {
     void terminateForTerminal('wall timeout', result => {
+      // 6.78.0 steer: a steered run past its first whole answer completes with that answer.
+      if (steerCheckpoint !== null) return finalize(steerCheckpoint)
       if (fullText) {
         // Got partial output — deliver only after the process tree is closed.
         return finalize(fullText)
@@ -886,6 +987,15 @@ export async function callClaudeStreaming(
     clearTimeout(inactivityTimer)
     clearTimeout(wallTimer)
     options?.abortSignal?.removeEventListener('abort', handleAbort)
+    // 6.78.0 steer: every terminal path closes the port and stdin.
+    if (steerSettleTimer) clearTimeout(steerSettleTimer)
+    steerSettleTimer = null
+    steerSettling = false
+    if (steerTracker && steerTracker.uncovered().length > 0) {
+      abandonUncoveredSteers()
+      return
+    }
+    endSteerStdin()
   }
 
   // ─── Process stdout ───
@@ -924,6 +1034,7 @@ export async function callClaudeStreaming(
           const inner = event.event
           if (inner?.type === 'content_block_delta' && inner.delta?.type === 'text_delta' && inner.delta.text) {
             phase = 'generating'
+            steerSeparator()
             fullText += inner.delta.text
             callbacks.onChunk(inner.delta.text)
           } else if (inner?.type === 'content_block_start' && inner.content_block?.type === 'thinking') {
@@ -982,12 +1093,16 @@ export async function callClaudeStreaming(
               if (authFailure) terminalTextError = authFailure
               else {
                 phase = 'generating'
+                steerSeparator()
                 fullText += text
                 callbacks.onChunk(text)
               }
             }
           }
         } else if (event.type === 'user') {
+          // 6.78.0 steer: the CLI replaying a steer line means it has it.
+          const delivered = steerTracker?.onUserEvent(event)
+          if (delivered) steerPort!.events.onDelivered?.(delivered)
           for (const preview of claudeToolResultPreviewLines(event)) callbacks.onActivityLine?.(preview)
         } else if (event.type === 'result') {
           const resultError = claudeResultErrorMessage(event)
@@ -1001,6 +1116,25 @@ export async function callClaudeStreaming(
             scheduleCliSessionSave()
             updateClaudeRun(run.runId, { cliSessionId: event.session_id })
           }
+          // 6.78.0 steer: a result finishes the run only when it (with the ones before it)
+          // covers every line written. A result that leaves a steer uncovered checkpoints the
+          // answer the first time it covers the prompt, and the run waits.
+          if (steerTracker && !finalized) {
+            const verdict = steerTracker.onResult(event)
+            if (verdict.folded.length > 0) steerPort!.events.onFolded?.(verdict.folded)
+            if (verdict.action === 'wait') {
+              if (verdict.checkpoint) {
+                const checkpoint: string = fullText || event.result || ''
+                steerCheckpoint = checkpoint
+                steerPort!.events.onCheckpoint?.(checkpoint)
+              }
+              steerNeedsSeparator = true
+              enterSteerSettle()
+              continue
+            }
+            // finish, or finish with steering off (the CLI named no uuids): no more steers.
+            steerPort!.close()
+          }
           // Final result — use accumulated text (more reliable than result.result)
           void finalize(fullText || event.result || '')
         }
@@ -1025,6 +1159,9 @@ export async function callClaudeStreaming(
   })
 
   proc.on('close', (code) => {
+    childClosed = true
+    if (steerReaper) clearTimeout(steerReaper)
+    steerPort?.close()
     if (terminationRequested) return
     // Process any remaining buffer
     if (buffer.trim()) {
@@ -1090,8 +1227,20 @@ export async function callClaudeStreaming(
       return sid
     }
     if (finalized) return sid
-    proc.stdin.write(cliQuery)
-    proc.stdin.end()
+    if (steerPort && steerTracker) {
+      // 6.78.0 steer: the prompt is one stream-json line; stdin stays open. Steers offered
+      // after the compose are written right behind it, then every later one as it comes.
+      proc.stdin.write(encodeUserLine(steerTracker.promptUuid, cliQuery))
+      steerPort.open((line, steerId) => {
+        if (finalized || steerStdinEnded || !proc.stdin.writable) return false
+        proc.stdin.write(line)
+        steerTracker.noteWritten(steerId)
+        return true
+      }, { startedAt: steerStartedAt, wallMaxMs: wallMax })
+    } else {
+      proc.stdin.write(cliQuery)
+      proc.stdin.end()
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
     if (!finalized) {

package/server/lib/claude-cli-support.ts

@@ -32,6 +32,45 @@ export function helpListsNameOption(help: string): boolean {
   return /(^|[\s,])--name[\s=<[]/m.test(help)
 }
 
+/**
+ * 6.78.0 Messages steer: does the installed Claude CLI take `--input-format stream-json` and
+ * `--replay-user-messages` (probed on 2.1.302)? Asked once, like `--name`. Any failure is a no,
+ * and a run then streams exactly as before. `claudeSteerSupportKnown()` is the answer once it is
+ * in, for the synchronous /api/models capability (null until the first probe finishes).
+ */
+let steerSupport: Promise<boolean> | null = null
+let steerSupportKnown: boolean | null = null
+
+export function claudeSupportsSteer(): Promise<boolean> {
+  if (!steerSupport) {
+    steerSupport = new Promise<boolean>(resolve => {
+      try {
+        execFile('claude', ['--help'], { timeout: HELP_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+          const supported = !error && helpListsSteerOptions(`${stdout}\n${stderr}`)
+          if (!supported) console.warn('[claude-bridge] this Claude CLI does not list --input-format and --replay-user-messages; Messages steer is off')
+          steerSupportKnown = supported
+          resolve(supported)
+        })
+      } catch {
+        steerSupportKnown = false
+        resolve(false)
+      }
+    })
+  }
+  return steerSupport
+}
+
+export function claudeSteerSupportKnown(): boolean | null {
+  return steerSupportKnown
+}
+
+/** Both options, as Claude Code 2.1.302 prints them (`--input-format <format>`, `--replay-user-messages`). */
+export function helpListsSteerOptions(help: string): boolean {
+  return /(^|[\s,])--input-format[\s=<[]/m.test(help) && /(^|[\s,])--replay-user-messages([\s=<[]|$)/m.test(help)
+}
+
 export function resetClaudeCliSupportForTests(): void {
   sessionNameSupport = null
+  steerSupport = null
+  steerSupportKnown = null
 }

package/server/lib/claude-steer.ts

@@ -0,0 +1,259 @@
+// 6.78.0 Messages steer (plan v3.1 P4): everything about steering a running Claude answer that
+// can be decided without a process, a file or the network. The bridge holds thin wiring only;
+// the coordinator owns the journal. Imports nothing that reaches a provider, so tests and the
+// Pi Durable canaries load it directly.
+//
+// THE PROTOCOL (probed on Claude Code 2.1.302, pi_durable_build/probes). With
+// `-p --input-format stream-json --replay-user-messages`, the prompt is one stream-json user
+// line and stdin stays open. A later user line at the DEFAULT priority (never "now") folds into
+// the running turn at the next tool boundary: the CLI replays it (`type: user`, its own uuid,
+// `isReplay: true`), and the turn's one `result` lists every folded line in
+// `user_message_uuids`. A line that arrives after the turn's last step starts a second turn,
+// which ends in a second result. The run is finished only when the results cover every line
+// written; the CLI exits about 300 ms after stdin closes.
+//
+// WHAT THIS MODULE DECIDES:
+//   encodeUserLine        one stdin line
+//   composeFirstContent   the first prompt plus steers that arrived before it was written
+//                         (pending ones, and ones carried from an interrupted generation)
+//   SteerPort             one per job, created before the runner starts: a pending buffer the
+//                         first line drains, then direct writes, then closed (too late)
+//   SteerTracker          sent and covered uuids; what a result means (finish, wait, steering off)
+//   steerCutoffMs         how close to a deadline a steer is refused as too late
+//   resolveRunModel       the model a run will use, exactly as model-router resolves it
+import { DEFAULT_MODEL, isCodexModel, isCursorModel, isOllamaModel, normalizeModelPreference, type ModelPreference } from '../../shared/model-preference.js'
+
+/** Quiet after a result that left a steer uncovered, before stdin is closed (plan P4). */
+export const STEER_SETTLE_MS = 20_000
+/** After a steer-mode run is finalized, a child that has not exited by now is terminated. */
+export const STEER_REAPER_MS = 15_000
+const CUTOFF_FLOOR_MS = 10_000
+const CUTOFF_FRACTION = 0.2
+
+/**
+ * 6.78.0 (P7 S7): the clock every steer cut-off is measured on, the bridge's wall clock and the
+ * coordinator's deadline alike. Monotonic, like the timers that actually end the run
+ * (setTimeout runs on libuv's monotonic clock), so a Mac that slept does not make a steer read
+ * too late against a timer that did not advance. `Date.now()` jumps across a sleep.
+ */
+export function steerClock(): number {
+  return performance.now()
+}
+
+/** A steer arriving with less than this left on the wall clock or the deadline is too late. */
+export function steerCutoffMs(wallMaxMs: number): number {
+  return Math.max(CUTOFF_FLOOR_MS, Math.round(CUTOFF_FRACTION * Math.max(0, wallMaxMs)))
+}
+
+/** One stdin line of `--input-format stream-json`: a user message with its own uuid. */
+export function encodeUserLine(uuid: string, content: string): string {
+  return `${JSON.stringify({ type: 'user', uuid, parent_tool_use_id: null, message: { role: 'user', content } })}\n`
+}
+
+/**
+ * The first prompt, with the steers that are already known when it is written. Never part of
+ * `request.query` or the fingerprint (Resume and rollback hash the request): composed here, at
+ * execution time only. Pending steers (sent before the run started) and steers carried from an
+ * earlier generation read alike.
+ */
+export function composeFirstContent(prompt: string, steers: ReadonlyArray<{ text: string }>): string {
+  const lines = steers.map(steer => steer.text.trim()).filter(Boolean)
+  if (lines.length === 0) return prompt
+  return `${prompt}\n\nThe user added this while the answer was being prepared:\n${lines.map(line => `- ${line}`).join('\n')}`
+}
+
+export interface PendingSteer {
+  steerId: string
+  text: string
+  /** The generation it was first sent to, when it is carried into a later one. */
+  carriedFrom?: number
+}
+
+/** What the port tells its owner (the coordinator journals each). */
+export interface SteerPortEvents {
+  /** Composed into the first line (pending before the start, or carried). */
+  onIncluded?: (steers: PendingSteer[]) => void
+  /** The CLI replayed the line: it has it. */
+  onDelivered?: (steerId: string) => void
+  /** A result covered it: the answer includes it. */
+  onFolded?: (steerIds: string[]) => void
+  /** The first result covered the prompt while a steer was still uncovered: the answer so far. */
+  onCheckpoint?: (text: string) => void
+}
+
+export type SteerOffer = 'pending' | 'written' | 'closed' | 'duplicate'
+
+/**
+ * One per job, on the coordinator's ActiveRun BEFORE the runner starts, so no steer can fall
+ * between "accepted" and a sink that does not exist yet.
+ *
+ *   before the first line: `offer` buffers; the bridge drains the buffer into the first line
+ *   after `open(sink)`:    `offer` writes a line at once (the sink must say it is writable)
+ *   after `close()`:       `offer` is refused, and the caller journals too_late
+ */
+export class SteerPort {
+  readonly events: SteerPortEvents
+  private readonly pending: PendingSteer[] = []
+  private readonly known = new Set<string>()
+  private sink: ((line: string, steerId: string) => boolean) | null = null
+  private composed: PendingSteer[] = []
+  private closed = false
+  private wallDeadlineAt: number | null = null
+  private wallMaxMs: number | null = null
+  /** Every steer uuid written to stdin, in order (the tracker's `sent`, less the prompt). */
+  readonly written: string[] = []
+
+  constructor(events: SteerPortEvents = {}) {
+    this.events = events
+  }
+
+  get isClosed(): boolean { return this.closed }
+  get isOpen(): boolean { return this.sink !== null && !this.closed }
+
+  /** A steer to apply. Idempotent by id. */
+  offer(steer: PendingSteer): SteerOffer {
+    if (this.known.has(steer.steerId)) return 'duplicate'
+    if (this.closed) return 'closed'
+    this.known.add(steer.steerId)
+    if (!this.sink) {
+      this.pending.push(steer)
+      return 'pending'
+    }
+    if (!this.sink(encodeUserLine(steer.steerId, steer.text), steer.steerId)) {
+      this.closed = true
+      this.sink = null
+      return 'closed'
+    }
+    this.written.push(steer.steerId)
+    return 'written'
+  }
+
+  /** The bridge, composing the first line: every pending steer, in order, once. They are
+   * reported `onIncluded` when the line is actually written (`open`). */
+  drainForCompose(): PendingSteer[] {
+    this.composed = this.pending.splice(0)
+    return [...this.composed]
+  }
+
+  /**
+   * The first line is written: later steers go straight to stdin. Steers offered after the
+   * compose and before this call are written now, in order. Returns the ones written here.
+   */
+  open(sink: (line: string, steerId: string) => boolean, timing: { startedAt: number; wallMaxMs: number }): string[] {
+    if (this.closed) return []
+    this.wallMaxMs = timing.wallMaxMs
+    this.wallDeadlineAt = timing.startedAt + timing.wallMaxMs
+    const composed = this.composed.splice(0)
+    if (composed.length > 0) this.events.onIncluded?.(composed)
+    this.sink = sink
+    const late = this.pending.splice(0)
+    const out: string[] = []
+    for (const steer of late) {
+      if (!sink(encodeUserLine(steer.steerId, steer.text), steer.steerId)) {
+        this.closed = true
+        this.sink = null
+        break
+      }
+      this.written.push(steer.steerId)
+      out.push(steer.steerId)
+    }
+    return out
+  }
+
+  /** Steers that were offered and never written (they read not_applied when the run ends). */
+  unwritten(): PendingSteer[] {
+    return [...this.composed, ...this.pending]
+  }
+
+  /** No more writes: the run is finishing or finished. */
+  close(): void {
+    this.closed = true
+    this.sink = null
+  }
+
+  /** Time left on the bridge's wall clock, or null before the first line. */
+  wallRemainingMs(now: number): number | null {
+    return this.wallDeadlineAt === null ? null : this.wallDeadlineAt - now
+  }
+
+  wallMax(): number | null {
+    return this.wallMaxMs
+  }
+}
+
+export type ResultVerdict =
+  /** Every line written is covered: finish now with the whole answer. */
+  | { action: 'finish'; folded: string[] }
+  /** Some line is not covered yet: keep stdin open and wait (settle timer). */
+  | { action: 'wait'; folded: string[]; checkpoint: boolean }
+  /** The CLI did not say which lines a result covers: steering is off for this job, finish now. */
+  | { action: 'finish_steering_off'; folded: string[] }
+
+/**
+ * Sent and covered uuids for one run. The prompt's uuid is sent first; each steer written is
+ * sent after it. A replay echo marks a steer delivered; a result adds its `user_message_uuids`
+ * to `covered`.
+ */
+export class SteerTracker {
+  private readonly sent: string[]
+  private readonly covered = new Set<string>()
+  private readonly delivered = new Set<string>()
+  private promptCovered = false
+
+  constructor(readonly promptUuid: string) {
+    this.sent = [promptUuid]
+  }
+
+  noteWritten(uuid: string): void {
+    if (!this.sent.includes(uuid)) this.sent.push(uuid)
+  }
+
+  /** A `type: user` stream event. Returns a steer id the first time the CLI replays it. */
+  onUserEvent(event: { uuid?: unknown; isReplay?: unknown }): string | null {
+    const uuid = typeof event.uuid === 'string' ? event.uuid : null
+    if (!uuid || uuid === this.promptUuid || !this.sent.includes(uuid) || this.delivered.has(uuid)) return null
+    if (event.isReplay !== true) return null
+    this.delivered.add(uuid)
+    return uuid
+  }
+
+  /** A successful `result`. Errors are decided by the bridge before this is called. */
+  onResult(event: { user_message_uuids?: unknown }): ResultVerdict {
+    const uuids = event.user_message_uuids
+    if (!Array.isArray(uuids)) {
+      return { action: 'finish_steering_off', folded: [] }
+    }
+    const folded: string[] = []
+    for (const uuid of uuids) {
+      if (typeof uuid !== 'string' || this.covered.has(uuid)) continue
+      this.covered.add(uuid)
+      if (uuid !== this.promptUuid && this.sent.includes(uuid)) folded.push(uuid)
+    }
+    if (this.sent.every(uuid => this.covered.has(uuid))) return { action: 'finish', folded }
+    const firstCover = !this.promptCovered && this.covered.has(this.promptUuid)
+    if (firstCover) this.promptCovered = true
+    return { action: 'wait', folded, checkpoint: firstCover }
+  }
+
+  /** Steers written and not covered (they will read not_applied when the run ends). */
+  uncovered(): string[] {
+    return this.sent.filter(uuid => uuid !== this.promptUuid && !this.covered.has(uuid))
+  }
+}
+
+export type QueryProvider = 'claude' | 'codex' | 'cursor' | 'ollama'
+
+/**
+ * The model a run will use, EXACTLY as model-router.ts resolves it (a test pins the two):
+ * the request's model, else the session's, else COS_G2_DEFAULT_MODEL, else the default.
+ */
+export function resolveRunModel(model: unknown, sessionModel: ModelPreference | null | undefined, envDefault: unknown): ModelPreference {
+  return normalizeModelPreference(model) ?? sessionModel ?? normalizeModelPreference(envDefault) ?? DEFAULT_MODEL
+}
+
+/** The provider of a resolved model, with model-router's fall-through: anything else is Claude. */
+export function providerOfModel(model: ModelPreference): QueryProvider {
+  if (isOllamaModel(model)) return 'ollama'
+  if (isCursorModel(model)) return 'cursor'
+  return isCodexModel(model) ? 'codex' : 'claude'
+}

package/server/lib/cos-bridge-notes.ts

@@ -0,0 +1,73 @@
+// The owner's notes as the memory bridge lists them, searched by keyword, and reciprocal rank fusion (6.76.2). Shared by
+// the live cues notes fallback (live-cues-v2-notes.ts) and the Live COS Ask (searchAskHistory in live-cos-ask.ts).
+//
+// Why the listing: the public memory runtime 0.1.0 serves the owner's notes ONLY through `cos_api_bridge.py memory` (what
+// COS Control's Memory list shows). Its bot_memory.py has no `search` command, so searchMemories' meaning arm answers
+// memory_parse_error, and its keyword arm reads only markdown memory folders: on such a Mac, searchMemories finds none of
+// the owner's notes. Listing and scoring is local: no model call, no query leaves the Mac. Nothing here logs.
+
+import { callPython } from './python-bridge.js'
+import { scoreKeywordMatch, tokenizeMeetingQuery } from './meeting-library-search.js'
+
+export const BRIDGE_DAYS = 3650
+export const BRIDGE_LIMIT = 200
+/** The listing never takes longer than cue_memory.py's dense arm may (DENSE_BUDGET_S). */
+export const BRIDGE_TIMEOUT_MS = 3_000
+export const RRF_K = 60
+
+export interface BridgeMemory { id: string; content: string; summary?: string; created_at?: string; domain?: string }
+
+/** Rows the bridge listed: an id and some content, at most BRIDGE_LIMIT. Anything else (an error object) is no rows. */
+export function normalizeBridgeMemories(value: unknown): BridgeMemory[] {
+  if (!Array.isArray(value)) return []
+  const out: BridgeMemory[] = []
+  for (const row of value.slice(0, BRIDGE_LIMIT)) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) continue
+    const r = row as Record<string, unknown>
+    const id = typeof r.id === 'string' ? r.id.trim().slice(0, 170) : ''
+    const content = typeof r.content === 'string' ? r.content : ''
+    if (!id || !content.trim()) continue
+    out.push({ id, content,
+      ...(typeof r.summary === 'string' ? { summary: r.summary } : {}),
+      ...(typeof r.created_at === 'string' ? { created_at: r.created_at } : {}),
+      ...(typeof r.domain === 'string' && r.domain ? { domain: r.domain } : {}) })
+  }
+  return out
+}
+
+/** The bridge listing. Rejects when the bridge fails or the signal aborts; callers decide what that means. */
+export async function listBridgeMemories(signal?: AbortSignal, timeoutMs: number = BRIDGE_TIMEOUT_MS): Promise<BridgeMemory[]> {
+  return normalizeBridgeMemories(await callPython(['memory', '--days', String(BRIDGE_DAYS), '--limit', String(BRIDGE_LIMIT)], timeoutMs, undefined, signal))
+}
+
+/** Rows that match `query`, best first, scored by the library's own keyword scorer (score > 0 only). */
+export function scoreBridgeMemories(rows: BridgeMemory[], query: string): Array<{ row: BridgeMemory; score: number }> {
+  const tokens = tokenizeMeetingQuery(query)
+  return rows.map(row => ({ row, score: scoreKeywordMatch(tokens, row.summary || '', `${row.summary || ''}\n${row.content}`).score }))
+    .filter(x => x.score > 0).sort((a, b) => b.score - a.score)
+}
+
+/** A note's LOCAL calendar day: a date bound is a local day (live cues use "tomorrow"), and a memory written at 22:00 Central
+ *  carries a UTC timestamp dated the next day. A bare YYYY-MM-DD is already a local day. */
+export function localDateOf(v: unknown): string {
+  if (typeof v !== 'string') return ''
+  if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return v
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(v)) return ''
+  const ms = Date.parse(v)
+  return Number.isFinite(ms) ? new Date(ms).toLocaleDateString('en-CA') : ''
+}
+
+/** Reciprocal rank fusion over ranked lists (k=60, as cue_memory.py): an item in several lists, or high in one, ranks first.
+ *  The first item seen for a key is kept; ties keep the order items were first added. */
+export class RankFusion<T> {
+  private readonly items = new Map<string, { item: T; score: number; order: number }>()
+  add(list: ReadonlyArray<{ key: string; item: T }>): void {
+    list.forEach(({ key, item }, rank) => {
+      const prev = this.items.get(key)
+      this.items.set(key, { item: prev?.item ?? item, score: (prev?.score ?? 0) + 1 / (RRF_K + rank), order: prev?.order ?? this.items.size })
+    })
+  }
+  ranked(limit = Infinity): T[] {
+    return [...this.items.values()].sort((a, b) => b.score - a.score || a.order - b.order).slice(0, limit).map(x => x.item)
+  }
+}

package/server/lib/decision-provider.ts

@@ -82,6 +82,13 @@ export class SubqDecisionClient implements DecisionClient {
     private readonly cap = () => { const n = Number(process.env.COS_SUBQ_DAILY_TOKENS); return Number.isFinite(n) && n > 0 ? Math.floor(n) : SUBQ_LIMITS.dailyTokens },
     private readonly timeoutMs: number = SUBQ_LIMITS.timeoutMs) {}
   resetForNewKey(): void { this.failures = 0; this.breakerUntil = 0 }
+  /** For an honest capability (6.76.2, live cues). An unreadable ledger reads as the cap reached: it fails toward not spending. */
+  status(): { configured: boolean; usedToday: number; dailyCap: number; breakerOpenUntil: number | null } {
+    const dailyCap = this.cap()
+    let usedToday = dailyCap
+    try { usedToday = Number(this.ledger()[this.day()]) || 0 } catch { /* unreadable ledger: saturated */ }
+    return { configured: !!this.key(), usedToday, dailyCap, breakerOpenUntil: this.breakerUntil > this.now().getTime() ? this.breakerUntil : null }
+  }
   private ledger(): Record<string, number> {
     try {
       const stat = lstatSync(this.usageFile)
@@ -144,6 +151,8 @@ export class SubqDecisionClient implements DecisionClient {
 
 const configuredSubqClients = new Set<SubqDecisionClient>()
 export function resetSubqDecisionClients(): void { configuredSubqClients.forEach(client => client.resetForNewKey()) }
+/** A SubQ client built outside createDecisionClient (live cues, 6.76.2) still starts clean when a new key is saved. */
+export function trackSubqDecisionClient(client: SubqDecisionClient): SubqDecisionClient { configuredSubqClients.add(client); return client }
 /** Snapshot selection per workflow request. Separate clients and cache identities prevent stale cross-provider answers. */
 export function createDecisionClient(useCase: DecisionUseCase, jev: Pick<JevClient, 'ask'> = new JevClient(), env: NodeJS.ProcessEnv = process.env): DecisionClient {
   const clients: Partial<Record<DecisionProvider, DecisionClient>> = {}