@gotcos/glasses-server 6.79.1 → 6.80.0

package/server/lib/conversation.ts

@@ -13,6 +13,8 @@ import { logSessionEnd, buildSessionLogEntry, writeSessionLog } from './session-
 import { atomicWriteFileSync, durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
 import { localDay } from './local-day.js'
 import { normalizeModelPreference, type ModelPreference } from '../../shared/model-preference.js'
+import { parsePreference, profilePreference } from '../../shared/key-preference.js'
+import { onKeyLanesInactive } from './key-lanes.js'
 import { parseMediaAttachmentRefs, type MediaAttachmentRef } from '../../shared/media-attachment.js'
 import { secureExistingPrivateFile } from './secure-user-config.js'
 import { currentMessageEra } from './message-era.js'
@@ -20,6 +22,38 @@ import { formatReferencedSourceData } from './prompt-reference-boundary.js'
 
 export type { ModelPreference }
 
+/**
+ * Key lanes K1 (plan v4 5.2, W2): what a session or an exchange may be bound to. A model slot,
+ * exactly as before, or a key profile as `profile:<id>`. Persistence accepts a profile by SYNTAX
+ * only: whether that profile still exists, is enabled and has a key is decided at resolve time
+ * (model-router), which refuses with a lens line. Dropping the binding here would make the next
+ * turn run on the subscription without a word, which is the bug this type exists to prevent.
+ */
+export type KeyProfileBinding = `profile:${string}`
+export type SessionModelBinding = ModelPreference | KeyProfileBinding
+
+/**
+ * The persistence normalizer (plan 5.2 Accept by syntax). For every input that is not a well
+ * formed `profile:<id>` this returns exactly what normalizeModelPreference returns, so a store
+ * with no profile in it reads and writes byte for byte as 6.79.0 did.
+ */
+export function normalizeSessionBinding(value: unknown): SessionModelBinding | undefined {
+  const parsed = parsePreference(value)
+  if (!parsed) return undefined
+  return parsed.kind === 'model' ? parsed.value : profilePreference(parsed.id) as KeyProfileBinding
+}
+
+/** The profile id of a `profile:<id>` binding, else undefined. */
+export function bindingProfileId(value: unknown): string | undefined {
+  const parsed = parsePreference(value)
+  return parsed?.kind === 'profile' ? parsed.id : undefined
+}
+
+/** The closed view of a binding: the model slot, or null for a profile (or nothing). */
+function closedSessionModel(value: SessionModelBinding | null | undefined): ModelPreference | null {
+  return normalizeModelPreference(value) ?? null
+}
+
 export interface Exchange {
   role: 'user' | 'assistant'
   content: string
@@ -31,8 +65,9 @@ export interface Exchange {
   /** Short-number namespace. Missing means the original legacy era. */
   messageEra?: string
   /** Per-exchange model badge. Prefer this over session.modelPreference when
-   * rendering history so Cursor/Codex turns do not inherit an Opus default. */
-  modelPreference?: ModelPreference
+   * rendering history so Cursor/Codex turns do not inherit an Opus default.
+   * K1: a keyed turn is stamped `profile:<id>` (accepted by syntax). */
+  modelPreference?: SessionModelBinding
   /** Public attachment refs may live on either half of a Q&A pair: request
    * photos on the user exchange, model-published images on the assistant
    * exchange. Bytes, filesystem paths, and capabilities never persist here. */
@@ -75,7 +110,7 @@ interface Session {
   exchanges: Exchange[]
   lastActivity: number
   createdAt: number
-  modelPreference: ModelPreference | null
+  modelPreference: SessionModelBinding | null
   contextBreaks: number[]  // timestamps where user said "new chat" — prompt history only sees exchanges after last break
 }
 
@@ -160,12 +195,12 @@ function loadFromDisk(): void {
   let loaded = 0
   for (const [id, session] of Object.entries(result.data.sessions)) {
     if (!session.contextBreaks) session.contextBreaks = []
-    session.modelPreference = normalizeModelPreference(session.modelPreference) ?? null
+    session.modelPreference = normalizeSessionBinding(session.modelPreference) ?? null
     // Persistence boundary: malformed refs are dropped without sacrificing
     // the surrounding exchange or the rest of the recovered session.
     for (const exchange of session.exchanges) {
       validateLoadedExchangeProvenance(exchange)
-      const exchangeModel = normalizeModelPreference(exchange.modelPreference)
+      const exchangeModel = normalizeSessionBinding(exchange.modelPreference)
       if (exchangeModel) exchange.modelPreference = exchangeModel
       else delete exchange.modelPreference
       if ('attachments' in exchange && exchange.attachments !== undefined) {
@@ -479,7 +514,7 @@ export function addExchange(
   globalMsgNum?: number,
   attachments?: MediaAttachmentRef[],
   provenance?: ExchangeJobProvenance,
-  modelPreference?: ModelPreference | null,
+  modelPreference?: SessionModelBinding | null,
 ): Exchange {
   let session = sessions.get(sessionId)
   if (!session) {
@@ -487,7 +522,7 @@ export function addExchange(
     sessions.set(sessionId, session)
   }
 
-  const stampedModel = normalizeModelPreference(modelPreference)
+  const stampedModel = normalizeSessionBinding(modelPreference)
   const exchange: Exchange = {
     role,
     content,
@@ -593,7 +628,7 @@ export function reconcileExchangeByJobIdentity(
   globalMsgNum?: number,
   attachments?: MediaAttachmentRef[],
   messageEra?: string,
-  modelPreference?: ModelPreference | null,
+  modelPreference?: SessionModelBinding | null,
   origin?: ExchangeOriginStamp,
 ): ReconciledExchange {
   if (!validClientJobId(identity.clientJobId) || !validGeneration(identity.generation)) {
@@ -625,7 +660,7 @@ export function reconcileExchangeByJobIdentity(
     && /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(messageEra)
     ? messageEra
     : currentMessageEra()
-  const stampedModel = normalizeModelPreference(modelPreference)
+  const stampedModel = normalizeSessionBinding(modelPreference)
   let exchange: Exchange
   const created = matchingIndexes.length === 0
   if (created) {
@@ -709,17 +744,57 @@ export async function clearSession(sessionId: string): Promise<void> {
   scheduleCacheUpdate()
 }
 
+/**
+ * The session's model slot. CLOSED (plan 5): a session bound to a key profile reads null here,
+ * so no caller that predates key lanes can ever mistake `profile:<id>` for a model and fall
+ * through to Claude. Routing reads getSessionBinding instead.
+ */
 export function getSessionModel(sessionId: string): ModelPreference | null {
+  return closedSessionModel(sessions.get(sessionId)?.modelPreference)
+}
+
+/** The session's binding, a model slot or `profile:<id>`. Only model-router and the job runtime read it. */
+export function getSessionBinding(sessionId: string): SessionModelBinding | null {
   return sessions.get(sessionId)?.modelPreference ?? null
 }
 
+/**
+ * Plan 12 (Remove all keys): every session bound to a profile (or only to `profileIds`) loses the
+ * binding and gets a context break, so a later subscription turn starts a fresh CLI session and
+ * never resumes a keyed transcript. Exchange stamps stay: history still says which answers ran
+ * on a key. Returns the session ids it changed.
+ */
+export function clearProfileBindings(profileIds?: readonly string[]): string[] {
+  const only = profileIds ? new Set(profileIds) : null
+  const changed: string[] = []
+  const now = Date.now()
+  for (const session of sessions.values()) {
+    const id = bindingProfileId(session.modelPreference)
+    if (id === undefined || (only && !only.has(id))) continue
+    session.modelPreference = null
+    session.contextBreaks.push(now)
+    changed.push(session.id)
+  }
+  if (changed.length > 0) {
+    scheduleSave()
+    scheduleCacheUpdate()
+  }
+  return changed
+}
+
+// Plan 12: Remove all keys clears every profile binding. A named Map entry; nothing runs until
+// the remove-all route fires it.
+onKeyLanesInactive('p6-session-bindings', reason => {
+  if (reason === 'remove_all') clearProfileBindings()
+})
+
 /** Prefer per-exchange stamps; fall back to session model for pre-stamp rows. */
 export function resolveExchangePairModel(
   user: Pick<Exchange, 'modelPreference'> | undefined,
   assistant: Pick<Exchange, 'modelPreference'> | undefined,
-  sessionModel: ModelPreference | null | undefined,
-): ModelPreference | undefined {
-  return normalizeModelPreference(
+  sessionModel: SessionModelBinding | null | undefined,
+): SessionModelBinding | undefined {
+  return normalizeSessionBinding(
     assistant?.modelPreference
       ?? user?.modelPreference
       ?? sessionModel
@@ -727,7 +802,7 @@ export function resolveExchangePairModel(
   )
 }
 
-export function setSessionModel(sessionId: string, model: ModelPreference | null): void {
+export function setSessionModel(sessionId: string, model: SessionModelBinding | null): void {
   const session = sessions.get(sessionId)
   if (session) {
     session.modelPreference = model
@@ -809,7 +884,7 @@ export interface SessionSummary {
   exchangeCount: number
   lastActivity: number
   createdAt: number
-  modelPreference: ModelPreference | null
+  modelPreference: SessionModelBinding | null
   lastQuery: string | null
 }
 
@@ -948,7 +1023,9 @@ export function getActiveSessions(): SessionToArchive[] {
       contextBreaks: session.contextBreaks,
       createdAt: session.createdAt,
       lastActivity: session.lastActivity,
-      modelPreference: session.modelPreference,
+      // Archive rows carry their own stamps (a keyed answer is stamped profile:<id>); the
+      // session-level fallback stays a closed model slot, as archive.ts types it.
+      modelPreference: closedSessionModel(session.modelPreference),
     })
   }
   return result

package/server/lib/dictation-clean.ts

@@ -83,6 +83,18 @@ export function dictationChildEnv(binary: string): NodeJS.ProcessEnv {
   return env
 }
 
+/** The Claude polish process: no tools, MCP, hooks or session file. `stream` keeps stdin open
+ * for exactly one stream-json user message (the 6.79.2 prewarm); `text` reads the prompt from stdin. */
+export function claudePolishArgs(model: string, version: DictationPolishPromptVersion, io: 'text' | 'stream'): string[] {
+  return [
+    '-p', '--model', model, '--effort', 'low',
+    ...(io === 'text' ? ['--output-format', 'text'] : ['--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose']),
+    '--no-session-persistence', '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
+    '--tools', '', '--settings', '{"disableAllHooks":true}', '--permission-mode', 'dontAsk',
+    '--system-prompt', DICTATION_POLISH_SYSTEM_PROMPTS[version],
+  ]
+}
+
 /** A fresh workspace and no MCP. Claude has no tools or hooks; Cursor's ask
  * mode retains read tools. Neither runner is given the COS working directory.
  * Failure rejects so callers preserve the deterministic transcript. */
@@ -128,12 +140,7 @@ export async function autoCleanDictation(
     const args = cursor ? [
       '-p', '--mode', 'ask', '--model', LUNA_DICTATION_CLI_MODEL,
       '--output-format', 'json', '--trust', '--workspace', workspace,
-    ] : [
-      '-p', '--model', model, '--effort', 'low', '--output-format', 'text',
-      '--no-session-persistence', '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
-      '--tools', '', '--settings', '{"disableAllHooks":true}', '--permission-mode', 'dontAsk',
-      '--system-prompt', DICTATION_POLISH_SYSTEM_PROMPTS[version],
-    ]
+    ] : claudePolishArgs(model, version, 'text')
     return await new Promise<string>((resolve, reject) => {
       const proc = spawn(binary.path, args, { stdio: ['pipe', 'pipe', 'pipe'], env, cwd: workspace, detached: true })
       let stdout = ''

package/server/lib/dictation-fillers.ts

@@ -16,7 +16,8 @@
  *   ellipsis follows it ("I think, Um, we"). An abbreviation's period ("Mr.", "e.g.", "5 p.m.",
  *   "U.S.", an initial) and an ellipsis are not sentence ends, so they neither start a sentence
  *   nor trigger the capital hand-off.
- * - any token right after a title ("Mr. Ah", "Dr. Er") and any quoted mention ('"um"').
+ * - a Titlecase token right after a title or abbreviation ("Mr. Ah", "Dr. Er"; "Mr. uh Jones"
+ *   still loses "uh"), and any quoted mention ('"um"').
  * - "uh huh", "uh oh" and "mm hmm" written without a hyphen: answers, not hesitations.
  * - "like", "you know", "I mean": filler only sometimes, so the model decides, not a regex.
  * A filler inside a longer quote ("um, no") is removed like any other.
@@ -30,23 +31,28 @@ const TRAILING_PAUSE = /^[ \t]*(?:,|\.{2,}|…|--|—|–)?[ \t]*/
 const OWN_SENTENCE_END = /^[ \t]*[.?!]+[ \t]*/
 const CLOSES_CLAUSE = /^(?:[.?!;:)\]}"”’]|$|\n)/
 
-/** A period that ends an abbreviation, not a sentence: "Mr.", "e.g.", "5 p.m.", "U.S.", "J.". */
-const ABBREVIATION = /(?:^|[\s(“"‘'])(?:mrs?|ms|dr|prof|st|vs|etc|e\.g|i\.e|a\.m|p\.m|u\.s)\.["”’)]*$/i
+/** A period that ends an abbreviation, not a sentence: "Mr.", "Jr.", "e.g.", "5 p.m.", "U.S.", "J.". */
+const ABBREVIATION = /(?:^|[\s(“"‘'])(?:mrs?|ms|dr|prof|st|jr|sr|vs|etc|e\.g|i\.e|a\.m|p\.m|u\.s)\.["”’)]*$/i
 const INITIAL = /(?:^|[\s(“"‘'])[A-Z]\.["”’)]*$/
-/** A title right before a token makes the token a name ("Mr. Ah", "Dr. Er"). */
-const TITLE = /(?:^|[\s(“"‘'])(?:mrs?|ms|dr|prof|st)\.[ \t]*$/i
 const QUOTE_OPEN = /["“”'‘’]$/
 const QUOTE_CLOSE = /^["“”'‘’]/
 /** A pause mark right after the token: a Titlecase filler set off this way is a hesitation. */
 const PAUSE_AFTER = /^[ \t]*(?:,|\.{2,}|…)/
 
+function afterAbbreviation(before: string): boolean {
+  const trimmed = before.replace(/[ \t]+$/, '')
+  return ABBREVIATION.test(trimmed) || INITIAL.test(trimmed)
+}
+
 function sentenceStart(before: string): boolean {
   const trimmed = before.replace(/[ \t]+$/, '')
   if (trimmed === '' || trimmed.endsWith('\n')) return true
   if (!/[.?!]["”’)]*$/.test(trimmed)) return false
-  // An ellipsis is a pause, and an abbreviation's period is not a sentence end.
-  if (/(?:\.{2,}|…)["”’)]*$/.test(trimmed)) return false
-  return !(ABBREVIATION.test(trimmed) || INITIAL.test(trimmed))
+  // An ellipsis is a pause, not a sentence end. An abbreviation's period needs no case here:
+  // the only thing a sentence start changes is the capital hand-off from a Titlecase filler,
+  // and a Titlecase token after an abbreviation is kept as a name before this is consulted
+  // (the 6.79.1 mutation gate showed a check here was unreachable).
+  return !/(?:\.{2,}|…)["”’)]*$/.test(trimmed)
 }
 
 export function fillerPassEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
@@ -70,8 +76,9 @@ export function stripDisfluencies(text: string): string {
       // A capital away from a sentence start is a name ("Ask Ah Kow"), unless a pause mark
       // sets it off as a hesitation ("I think, Um, we should").
       || (!atStart && /^[A-Z]/.test(token) && !PAUSE_AFTER.test(after))
-      // Right after a title it is a name ("Mr. Ah", "Dr. Er").
-      || TITLE.test(out + before)
+      // Titlecase right after a title or abbreviation is a name ("Mr. Ah", "Dr. Er, the surgeon").
+      // A lowercase filler there still goes ("Mr. uh Jones").
+      || (/^[A-Z]/.test(token) && afterAbbreviation(out + before))
       // A quoted mention is the word itself ('"um" is a filler word').
       || (QUOTE_OPEN.test(out + before) && QUOTE_CLOSE.test(after))
       // Two-word answers said without a hyphen: "uh huh", "uh oh", "mm hmm".

package/server/lib/dictation-polish-need.ts

@@ -0,0 +1,48 @@
+/**
+ * Skip the polish model when the text has nothing for it to fix.
+ *
+ * Runs after the deterministic filler pass. The model is called only when one of these
+ * is present; anything else goes out as the filler-passed text with polishSkipped "clean":
+ * - a backtrack or self-correction marker ("actually", "no wait", "I mean", "scratch that", "sorry")
+ * - a repeated word or stutter ("the the", "I I"), or a clause restarted on its first word
+ *   ("we should, we need to")
+ * - a filler-like the deterministic pass leaves to the model ("like", "you know", "kind of"),
+ *   or a sentence that opens on a tic ("So", "Well", "Okay")
+ * - a filler sound still present (a meeting line, or one the pass kept)
+ * - spoken formatting or punctuation ("new line", "bullet point", "comma", "question mark")
+ * - text that does not read as finished: no capital at the start or no closing punctuation
+ * - more than MAX_WORDS words
+ * Each check errs toward calling the model: a false "needed" costs a model call, a false
+ * "clean" costs a fix. What it cannot see is a mis-heard name ("ask preeya" for Priya): the
+ * 6.79.2 eval found those are the fixes skipping loses, so the switch defaults OFF.
+ */
+export const MAX_WORDS = 40
+
+export type PolishNeed =
+  | 'backtrack' | 'repeat' | 'false_start' | 'filler_like' | 'filler' | 'formatting' | 'unfinished' | 'long'
+
+const BACKTRACK = /\b(actually|no,? wait|wait,? no|i mean|scratch that|sorry|or rather|correction|let me rephrase|i meant|no no)\b|,\s*no\s*,/i
+const REPEAT = /(?<![\p{L}\p{N}'])([\p{L}\p{N}']+)[\s,]+\1(?![\p{L}\p{N}'])/iu
+/** A clause restarted on the same word: "we should, we need to". */
+const FALSE_START = /(?<![\p{L}\p{N}'])([\p{L}']+)\s+[\p{L}']+(?:\s+[\p{L}']+)?,\s+\1(?![\p{L}\p{N}'])/iu
+const FILLER_LIKE = /\b(like|you know|kind of|kinda|sort of|sorta|basically|literally|i guess)\b|^["“(]?(so|well|okay|ok|alright|anyway)\b/i
+const FILLER = /(?<![\p{L}\p{N}'’-])(um+|uhm|uh+|erm?|ah+|hm+|mm+|mhm)(?![\p{L}\p{N}'’-])/iu
+const FORMATTING = /\b(new ?line|new paragraph|next line|bullet( point)?|numbered|number (one|two|three|1|2|3)|comma|period|full stop|question mark|exclamation (point|mark)|colon|semicolon|open (quote|paren)|close (quote|paren)|dash)\b/i
+
+export function polishNeed(text: string): PolishNeed | null {
+  const trimmed = text.trim()
+  if (BACKTRACK.test(trimmed)) return 'backtrack'
+  if (REPEAT.test(trimmed)) return 'repeat'
+  if (FALSE_START.test(trimmed)) return 'false_start'
+  if (FILLER_LIKE.test(trimmed)) return 'filler_like'
+  if (FILLER.test(trimmed)) return 'filler'
+  if (FORMATTING.test(trimmed)) return 'formatting'
+  if (!/^["“'‘(]?[\p{Lu}\p{N}]/u.test(trimmed) || !/[.?!]["”’)]*$/.test(trimmed)) return 'unfinished'
+  if (trimmed.split(/\s+/).length > MAX_WORDS) return 'long'
+  return null
+}
+
+/** Off unless COS_DICTATION_POLISH_SKIP_CLEAN is 1, true or on. */
+export function skipCleanEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return ['1', 'true', 'on'].includes((env.COS_DICTATION_POLISH_SKIP_CLEAN ?? '').trim().toLowerCase())
+}

package/server/lib/dictation-prewarm.ts

@@ -0,0 +1,209 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { resolveProviderBinary } from './provider-binary.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import {
+  buildDictationPolishPrompt, claudePolishArgs, dictationChildEnv, dictationPolishPromptVersion,
+  type DictationPolishPromptVersion,
+} from './dictation-clean.js'
+
+/**
+ * 6.79.2: start the polish Claude process when dictation starts, not when it ends.
+ *
+ * About 70% of a polish is the CLI's own start (measured on Miles's Mac: cold polish 1.8 to
+ * 1.9 s; the same process started 3 s earlier answered 1.0 to 1.3 s after the text arrived).
+ * A warm process is the exact polish process (same args, no tools, MCP, hooks or session
+ * file, its own empty workspace) in stream-json input mode, waiting for ONE user message.
+ * It gets that message, answers, and its stdin is closed at once, so it exits: no history
+ * ever carries into another dictation.
+ *
+ * Bounded: at most PREWARM_MAX live (a new one evicts the oldest), each killed after
+ * PREWARM_TTL_MS unused, killed when finalize decides not to call the model, and killed
+ * with the server. A warm process costs no model call until a message is written, so the
+ * daily polish budget is spent only when it is used.
+ */
+export const PREWARM_TTL_MS = 150_000
+export const PREWARM_MAX = 2
+export const PREWARM_MODELS = ['haiku', 'sonnet'] as const
+export type PrewarmModel = typeof PREWARM_MODELS[number]
+
+export class PrewarmUnavailableError extends Error {}
+
+interface WarmPolish {
+  token: string
+  model: PrewarmModel
+  version: DictationPolishPromptVersion
+  proc: ChildProcess
+  scratch: string
+  exited: boolean
+  timer: NodeJS.Timeout
+  onResult: ((event: any) => void) | null
+  onExit: (() => void) | null
+}
+
+/** Unclaimed warm processes, by token. */
+const warm = new Map<string, WarmPolish>()
+/** Every process not yet exited, claimed or not: what the server kills on its way out. */
+const alive = new Set<WarmPolish>()
+
+export function prewarmEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return !['0', 'false', 'off'].includes((env.COS_DICTATION_PREWARM ?? '').trim().toLowerCase())
+}
+
+export function isPrewarmModel(model: unknown): model is PrewarmModel {
+  return typeof model === 'string' && (PREWARM_MODELS as readonly string[]).includes(model)
+}
+
+export function livePrewarmCount(): number {
+  return warm.size
+}
+
+function retire(entry: WarmPolish): void {
+  warm.delete(entry.token)
+  clearTimeout(entry.timer)
+  if (!entry.exited) void terminateProviderProcess(entry.proc).catch(() => {})
+}
+
+export function startPolishPrewarm(model: PrewarmModel): { token: string; expiresMs: number } {
+  const binary = resolveProviderBinary('claude')
+  if (!binary.ok) throw new PrewarmUnavailableError('Dictation cleanup Claude CLI unavailable')
+  while (warm.size >= PREWARM_MAX) retire(warm.values().next().value!)
+  const version = dictationPolishPromptVersion()
+  const scratch = mkdtempSync(join(tmpdir(), 'cos-dictation-prewarm-'))
+  const workspace = join(scratch, 'workspace')
+  mkdirSync(workspace, { mode: 0o700 })
+  const proc = spawn(binary.path, claudePolishArgs(model, version, 'stream'), {
+    stdio: ['pipe', 'pipe', 'pipe'], env: dictationChildEnv(binary.path), cwd: workspace, detached: true,
+  })
+  const token = randomUUID()
+  const entry: WarmPolish = {
+    token, model, version, proc, scratch, exited: false, onResult: null, onExit: null,
+    timer: setTimeout(() => retire(entry), PREWARM_TTL_MS),
+  }
+  entry.timer.unref?.()
+  let buffer = ''
+  proc.stdout?.on('data', (chunk: Buffer) => {
+    buffer += chunk.toString()
+    if (buffer.length > 256_000) { retire(entry); return }
+    let newline: number
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline).trim()
+      buffer = buffer.slice(newline + 1)
+      if (!line) continue
+      let event: any
+      try { event = JSON.parse(line) } catch { continue }
+      if (event?.type === 'result') entry.onResult?.(event)
+    }
+  })
+  // Do not log provider stderr: it can contain login or dictation data.
+  proc.stderr?.resume()
+  proc.stdin?.on('error', () => {})
+  const exited = () => {
+    if (entry.exited) return
+    entry.exited = true
+    warm.delete(token)
+    alive.delete(entry)
+    clearTimeout(entry.timer)
+    rmSync(scratch, { recursive: true, force: true })
+    entry.onExit?.()
+  }
+  proc.on('error', exited)
+  proc.on('close', exited)
+  warm.set(token, entry)
+  alive.add(entry)
+  return { token, expiresMs: PREWARM_TTL_MS }
+}
+
+/** Kill a warm process nobody will use (finalize skipped the model, or the press was cancelled). */
+export function discardPolishPrewarm(token: string | undefined): boolean {
+  const entry = token ? warm.get(token) : undefined
+  if (!entry) return false
+  retire(entry)
+  return true
+}
+
+/** One use: the entry leaves the pool whether or not it matches. A model mismatch kills it. */
+export function takePolishPrewarm(token: string | undefined, model: string): WarmPolish | null {
+  const entry = token ? warm.get(token) : undefined
+  if (!entry) return null
+  warm.delete(entry.token)
+  if (entry.model !== model || entry.exited) { retire(entry); return null }
+  return entry
+}
+
+/**
+ * Write the one message and read the one result. PrewarmUnavailableError means nothing was
+ * sent (the process had already gone), so the caller may spawn cold. Any later failure means
+ * the model may have run, so it is a real polish failure.
+ */
+export async function runWarmPolish(
+  entry: WarmPolish,
+  text: string,
+  terms: string[],
+  opts: { signal?: AbortSignal } = {},
+): Promise<string> {
+  if (entry.exited || !entry.proc.stdin || entry.proc.stdin.destroyed) {
+    retire(entry)
+    throw new PrewarmUnavailableError('Warm polish process already exited')
+  }
+  if (opts.signal?.aborted) { retire(entry); throw new Error('Auto-clean aborted') }
+  clearTimeout(entry.timer)
+  const configuredTimeout = Number.parseInt(process.env.COS_DICTATION_AUTOCLEAN_TIMEOUT_MS || '20000', 10)
+  const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : 20_000
+  return await new Promise<string>((resolve, reject) => {
+    let settled = false
+    const finish = (error?: Error, output?: string) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      opts.signal?.removeEventListener('abort', abort)
+      entry.onResult = null
+      entry.onExit = null
+      // Exactly one message: once it is answered (or abandoned) the process must go.
+      retire(entry)
+      if (error) reject(error); else resolve(output!)
+    }
+    const abort = () => finish(new Error('Auto-clean aborted'))
+    const timer = setTimeout(() => finish(new Error(`Auto-clean timed out (${timeoutMs}ms)`)), timeoutMs)
+    entry.onResult = (event) => {
+      if (event.subtype !== 'success' || event.is_error || typeof event.result !== 'string') {
+        return finish(new Error('Warm polish returned an unsuccessful result'))
+      }
+      const output = event.result.trim()
+      if (!output) return finish(new Error('Auto-clean returned empty text'))
+      finish(undefined, output)
+    }
+    entry.onExit = () => finish(new Error('Warm polish process exited without a result'))
+    opts.signal?.addEventListener('abort', abort, { once: true })
+    const message = JSON.stringify({
+      type: 'user',
+      message: { role: 'user', content: buildDictationPolishPrompt(text, terms, entry.version) },
+    })
+    try {
+      entry.proc.stdin!.write(message + '\n')
+      entry.proc.stdin!.end()
+    } catch {
+      finish(new Error('Auto-clean input failed'))
+    }
+  })
+}
+
+/** The server is going away: a detached warm process would outlive it. */
+export function killAllPrewarmsSync(): void {
+  for (const entry of alive) {
+    try { if (entry.proc.pid) process.kill(-entry.proc.pid, 'SIGTERM') } catch {}
+    // No close event will run before the server is gone, so its workspace goes now.
+    try { rmSync(entry.scratch, { recursive: true, force: true }) } catch {}
+  }
+  warm.clear()
+  alive.clear()
+}
+process.once('exit', killAllPrewarmsSync)
+
+export function _resetPrewarmsForTest(): void {
+  for (const entry of [...alive]) retire(entry)
+  warm.clear()
+}