@gotcos/glasses-server 6.21.2 → 6.21.4

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 6.21.4
+
+- Preserve validated phone-photo references on Claude and Codex conversation
+  exchanges so Recent Glasses and message-history clients can recover the
+  original visual context instead of receiving a text-only marker.
+- Recover validated refs at read time from the durable media association index,
+  keyed by exact session ID, global message number, and message era. Pre-6.21.4
+  unversioned refs are recovered only for the active era when both creation and
+  association occurred after its boundary; ambiguous historical refs fail
+  closed rather than risking the wrong photo.
+
+## 6.21.3
+
+- Route Max-tier provisional dictation preview through the resident Turbo
+  preview sidecar while keeping authoritative live commit and saved-work
+  polish on Large-v3. This corrects the 6.21.0 behavior that made cosmetic
+  preview pay Large-v3 latency.
+- Give canonical transcription strict GPU priority. A cosmetic preview is
+  dropped or aborted when canonical/HQ Metal work begins, and preview failures
+  remain outside the Whisper circuit breaker and all persistence paths.
+- Report the effective Max lanes truthfully as Turbo preview, Large-v3 commit,
+  and Large-v3 polish. Balanced remains Small.en preview, Turbo commit, and
+  Large-v3 polish.
+
 ## 6.21.2
 
 - Cache Python, Claude, Codex, and Cursor process probes for 30 seconds so the

package/README.md

@@ -112,6 +112,10 @@ range is the exact Tailscale/CGNAT allocation (`100.64.0.0/10`), not all of
   authenticated query that requested it
 - Message History + cross-day "reference message N" — your chats are archived by day
   and every message keeps a permanent number you can recall (`/api/archive`, `/api/message/:num`)
+- Recent/history responses preserve validated photo references. Recovery uses
+  exact session + global-message + message-era identity without exposing storage
+  paths. Ambiguous pre-version historical refs fail closed; unversioned refs are
+  recovered only inside the active era when created and associated after its boundary.
 - Send phone photos with queued prompts, and review assistant-selected generated,
   research, or explicitly used email images in Messages and on the G2 lens
 - Recover long voice prompts after phone, network, or server interruptions. Audio
@@ -257,12 +261,14 @@ update the server remain on Turbo until Guided Setup opts them into Small.en.
 npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier max
 ```
 
-Max reuses the existing Large-v3 worker for preview and authoritative commit;
-saved work still receives Large-v3 HQ polish. It does not start a third model
-process. If Large-v3 is missing, health reports the downgrade and the server
-falls back to Turbo rather than making transcription unavailable. COS Control
-is the supported owner of the machine-wide tier; the per-lane environment
-variables remain advanced overrides.
+Max keeps Turbo resident in the isolated preview sidecar for low-latency
+provisional words, while Large-v3 remains authoritative for live commit and
+saved-work polish. Canonical transcription has strict GPU priority: a cosmetic
+preview is dropped or aborted instead of competing with a committed decode.
+If Large-v3 is missing, health reports the downgrade and the server falls back
+to Turbo rather than making transcription unavailable. COS Control is the
+supported owner of the machine-wide tier; the per-lane environment variables
+remain advanced overrides.
 
 The first server start downloads the real-time turbo model. True HQ additionally
 requires the full `ggml-large-v3.bin` model (about 3.1 GB):

package/bin/cli.cjs

@@ -379,7 +379,7 @@ if (SETUP_TRANSCRIPTION) {
   process.env.COS_WHISPER_PREVIEW_MODEL = previewModel
   process.env.COS_WHISPER_COMMIT_MODEL = commitModel
   const laneSummary = TRANSCRIPTION_TIER === 'max'
-    ? 'Large-v3 preview + commit · Large-v3 HQ'
+    ? 'Turbo preview · Large-v3 commit · Large-v3 HQ'
     : 'Small.en preview · Turbo commit · Large-v3 HQ'
   console.log(green('  ✓') + ` ${TRANSCRIPTION_TIER === 'max' ? 'Max' : 'Balanced'} transcription selected ` + dim(`— ${laneSummary}`))
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.2",
+  "version": "6.21.4",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/lib/claude-bridge.ts

@@ -428,6 +428,7 @@ export async function callClaudeStreaming(
       outputImagePublisher = createRunOutputImagePublisher({
         sessionId: sid,
         globalMsgNum,
+        messageEra: options?.messageEra,
         maxImages: outputImageBudget,
       })
     } catch (err) {
@@ -473,6 +474,7 @@ export async function callClaudeStreaming(
   // Record user message (with [Photo]/[N Photos] prefix for vision queries)
   const photoPrefix = imagePaths.length === 1 ? '[Photo]' : imagePaths.length > 1 ? `[${imagePaths.length} Photos]` : ''
   const historyQuery = photoPrefix ? `${photoPrefix} ${query || 'What do you see?'}` : query
+  const inboundAttachments = imageInputs.length > 0 ? imageInputs.map(input => input.attachment) : undefined
   const exchangeProvenance = {
     clientJobId: options?.clientJobId,
     generation: options?.generation,
@@ -482,7 +484,7 @@ export async function callClaudeStreaming(
     'user',
     historyQuery,
     globalMsgNum,
-    undefined,
+    inboundAttachments,
     exchangeProvenance,
     resolvedModel,
   )

package/server/lib/codex-bridge.ts

@@ -321,6 +321,7 @@ export async function callCodexStreaming(
         sessionId: sid,
         globalMsgNum,
         runId: run.runId,
+        messageEra: options?.messageEra,
         maxImages: outputImageBudget,
       })
     } catch (err) {
@@ -363,6 +364,7 @@ export async function callCodexStreaming(
   const isFirstQuery = isNewSession(sid)
   const photoPrefix = imagePaths.length === 1 ? '[Photo]' : imagePaths.length > 1 ? `[${imagePaths.length} Photos]` : ''
   const historyQuery = photoPrefix ? `${photoPrefix} ${query || 'What do you see?'}` : query
+  const inboundAttachments = imageInputs.length > 0 ? imageInputs.map(input => input.attachment) : undefined
   const exchangeProvenance = {
     clientJobId: options?.clientJobId,
     generation: options?.generation,
@@ -372,7 +374,7 @@ export async function callCodexStreaming(
     'user',
     historyQuery,
     globalMsgNum,
-    undefined,
+    inboundAttachments,
     exchangeProvenance,
     model,
   )

package/server/lib/cursor-bridge.ts

@@ -262,6 +262,7 @@ export async function callCursorStreaming(
         sessionId: sid,
         globalMsgNum,
         runId: run.runId,
+        messageEra: options?.messageEra,
         maxImages: outputImageBudget,
       })
     } catch (err) {

package/server/lib/media-store.ts

@@ -33,6 +33,7 @@ import { atomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
 import {
   isValidMediaId,
+  mergeMediaAttachmentRefs,
   parseMediaAttachmentRef,
   type MediaAttachmentRef,
   type MediaKind,
@@ -131,6 +132,7 @@ export interface MediaRecord {
   clientQueueItemId?: string
   runId?: string
   globalMsgNum?: number
+  messageEra?: string
   createdAtMs: number
   updatedAtMs: number
   reservedAtMs?: number
@@ -197,6 +199,9 @@ function sanitizeRecord(raw: unknown): MediaRecord | null {
     ...(typeof r.clientQueueItemId === 'string' ? { clientQueueItemId: r.clientQueueItemId } : {}),
     ...(typeof r.runId === 'string' ? { runId: r.runId } : {}),
     ...(typeof r.globalMsgNum === 'number' ? { globalMsgNum: r.globalMsgNum } : {}),
+    ...(typeof r.messageEra === 'string' && /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(r.messageEra)
+      ? { messageEra: r.messageEra }
+      : {}),
     createdAtMs: typeof r.createdAtMs === 'number' ? r.createdAtMs : Date.now(),
     updatedAtMs: typeof r.updatedAtMs === 'number' ? r.updatedAtMs : Date.now(),
     ...(typeof r.reservedAtMs === 'number' ? { reservedAtMs: r.reservedAtMs } : {}),
@@ -464,6 +469,51 @@ export class MediaStore {
     return this.getRecord(id)?.ref ?? null
   }
 
+  /** Recover the public refs associated with one exact conversation turn.
+   *
+   * The media index is already the durable lifecycle authority for uploaded
+   * and generated images. Older/legacy query paths associated the media here
+   * but failed to copy the refs onto the conversation exchange. Readers may
+   * use this exact session + message key to repair that projection without
+   * exposing storage paths or inventing a second attachment database.
+   */
+  getAssociatedRefs(target: {
+    sessionId: string
+    globalMsgNum: number
+    messageEra?: string
+    activeMessageEra: string
+    activeEraStartedAt: number
+  }): MediaAttachmentRef[] {
+    if (!target.sessionId || !Number.isSafeInteger(target.globalMsgNum) || target.globalMsgNum < 1) return []
+    const validEra = (value: unknown): value is string =>
+      typeof value === 'string' && /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(value)
+    if (!validEra(target.activeMessageEra) || !Number.isFinite(target.activeEraStartedAt)) return []
+    const targetEra = validEra(target.messageEra) ? target.messageEra : undefined
+    const eraMatches = (rec: MediaRecord): boolean => {
+      if (rec.messageEra) return targetEra != null && rec.messageEra === targetEra
+
+      // Pre-6.21.4 associations did not persist an era. Recover them only for
+      // the active era when both creation and association are on/after its
+      // boundary. Requiring both closes the race where a pre-reset upload was
+      // associated only after the reset. Anything older may belong to legacy
+      // or any prior named era and fails closed.
+      const associatedAt = rec.associatedAtMs ?? rec.createdAtMs
+      if (target.activeMessageEra === 'legacy') return targetEra == null || targetEra === 'legacy'
+      if (targetEra === target.activeMessageEra) {
+        return rec.createdAtMs >= target.activeEraStartedAt && associatedAt >= target.activeEraStartedAt
+      }
+      return false
+    }
+    const matching = [...this.records.values()]
+      .filter(rec => rec.lifecycle === 'associated'
+        && rec.sessionId === target.sessionId
+        && rec.globalMsgNum === target.globalMsgNum
+        && eraMatches(rec))
+      .sort((a, b) => a.createdAtMs - b.createdAtMs)
+      .map(rec => rec.ref)
+    return mergeMediaAttachmentRefs(matching)
+  }
+
   /** Resolve content for serving/model input, honoring lifecycle + TTLs. */
   getContent(id: string, variant: 'phone' | 'thumb' | 'g2' = 'phone'): MediaContentResult {
     const rec = this.getRecord(id)
@@ -667,7 +717,7 @@ export class MediaStore {
 
   /** Bind media to its final run/message. Safe to replay; wins over a
    *  delayed release. */
-  associate(ids: string[], target: { sessionId?: string; runId?: string; globalMsgNum?: number }): Promise<void> {
+  associate(ids: string[], target: { sessionId?: string; runId?: string; globalMsgNum?: number; messageEra?: string }): Promise<void> {
     return this.withLock(() => {
       const now = Date.now()
       let dirty = false
@@ -684,6 +734,8 @@ export class MediaStore {
         if (target.sessionId && rec.sessionId !== target.sessionId) { rec.sessionId = target.sessionId; recDirty = true }
         if (target.runId && rec.runId !== target.runId) { rec.runId = target.runId; recDirty = true }
         if (target.globalMsgNum != null && rec.globalMsgNum !== target.globalMsgNum) { rec.globalMsgNum = target.globalMsgNum; recDirty = true }
+        if (target.messageEra && /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(target.messageEra)
+            && rec.messageEra !== target.messageEra) { rec.messageEra = target.messageEra; recDirty = true }
         if (recDirty) {
           rec.updatedAtMs = now
           dirty = true

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

@@ -227,6 +227,7 @@ const runner: QueryJobRunner = async ({ jobId, turnId, request, signal, callback
             await getMediaStore().associate(resolvedAttachments.ids, {
               sessionId: request.sessionId,
               ...(request.globalMsgNum ? { globalMsgNum: request.globalMsgNum } : {}),
+              messageEra: request.messageEra,
             }).catch(error => console.error('[query-jobs] attachment association failed:', error))
           }
           const { outputAttachments: _outputAttachments, ...runMetadata } = metadata ?? {}

package/server/lib/run-output-images.ts

@@ -41,6 +41,7 @@ export interface RunOutputImageTarget {
   sessionId: string
   globalMsgNum?: number
   runId?: string
+  messageEra?: string
 }
 
 export interface CreateRunOutputImagePublisherOptions extends RunOutputImageTarget {
@@ -223,7 +224,15 @@ function safeTarget(options: CreateRunOutputImagePublisherOptions): RunOutputIma
   const runId = typeof options.runId === 'string' && options.runId.trim()
     ? options.runId.trim().slice(0, 120)
     : undefined
-  return { sessionId, ...(globalMsgNum ? { globalMsgNum } : {}), ...(runId ? { runId } : {}) }
+  const messageEra = typeof options.messageEra === 'string' && /^[a-z0-9][a-z0-9._-]{0,79}$/i.test(options.messageEra)
+    ? options.messageEra
+    : undefined
+  return {
+    sessionId,
+    ...(globalMsgNum ? { globalMsgNum } : {}),
+    ...(runId ? { runId } : {}),
+    ...(messageEra ? { messageEra } : {}),
+  }
 }
 
 function assertTempRoot(rawRoot: string): string {

package/server/lib/whisper-local.ts

@@ -16,9 +16,12 @@ import { getVocabulary, getOwnerName, getWhisperCorrections } from './profile.js
 import { stripBrandUrls } from './hallucination-filter.js'
 import {
   batchHqMetalEnabled,
+  beginCanonicalMetal,
   chooseBatchDevice,
   MetalBatchPreemptedError,
+  MetalPreviewContendedError,
   registerMetalBatchChild,
+  tryAcquireMetalPreview,
   unregisterMetalBatchChild,
 } from './whisper-metal-gate.js'
 
@@ -1026,6 +1029,7 @@ async function transcribeViaServer(
   context?: string,
   isQuiet?: boolean,
   promptPolicy: 'full-vocabulary' | 'none' = 'full-vocabulary',
+  signal?: AbortSignal,
 ): Promise<{ text: string; words?: WhisperWord[] }> {
   const formData = new FormData()
   // Convert Buffer to Uint8Array to satisfy Blob's BlobPart type constraint
@@ -1043,10 +1047,11 @@ async function transcribeViaServer(
   // legitimate speech from quiet sources (laptop speakers through G2 mic).
   formData.append('suppress_non_speech', 'true')  // Suppress special/non-speech tokens (benign)
 
+  const timeoutSignal = AbortSignal.timeout(10_000)
   const response = await fetch(`${WHISPER_SERVER_URL}/inference`, {
     method: 'POST',
     body: formData,
-    signal: AbortSignal.timeout(10_000),
+    signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
   })
 
   if (!response.ok) {
@@ -1183,6 +1188,7 @@ export async function transcribeLocal(
   opts?: {
     affectsCircuit?: boolean
     promptPolicy?: 'full-vocabulary' | 'none'
+    metalPriority?: 'canonical' | 'preview'
   },
 ): Promise<{ text: string; backend: 'server' | 'cli'; words?: WhisperWord[] }> {
   const start = Date.now()
@@ -1198,8 +1204,21 @@ export async function transcribeLocal(
 
   // Try whisper-server first (fastest: ~50-100ms, includes DTW word timestamps)
   if (serverAvailable) {
+    const previewLease = opts?.metalPriority === 'preview' ? tryAcquireMetalPreview() : null
+    if (opts?.metalPriority === 'preview' && !previewLease) {
+      throw new MetalPreviewContendedError()
+    }
+    const releaseCanonical = opts?.metalPriority === 'preview'
+      ? null
+      : beginCanonicalMetal('whisper_server')
     try {
-      const result = await transcribeViaServer(audioBuffer, context, isQuiet, opts?.promptPolicy)
+      const result = await transcribeViaServer(
+        audioBuffer,
+        context,
+        isQuiet,
+        opts?.promptPolicy,
+        previewLease?.signal,
+      )
       const text = applyCorrections(result.text)
       const words = result.words?.map(w => ({ ...w, word: applyCorrections(w.word) }))
       const elapsed = Date.now() - start
@@ -1211,6 +1230,7 @@ export async function transcribeLocal(
       console.log(`[whisper-local] Server transcribed in ${elapsed}ms (${words?.length ?? 0} words): "${text.slice(0, 80)}${text.length > 80 ? '...' : ''}"`)
       return { text, backend: 'server', words }
     } catch (err: any) {
+      if (previewLease?.signal.aborted) throw new MetalPreviewContendedError()
       if (affectsCircuit) {
         serverConsecutiveFailures++
         const isTimeout = err.message.includes('timeout') || err.message.includes('aborted')
@@ -1239,6 +1259,9 @@ export async function transcribeLocal(
 
       // Throw to let caller fall to OpenAI cloud (1-3s) — much faster than CLI cold-start (11s)
       throw new Error(`whisper-server unavailable: ${err.message}`)
+    } finally {
+      previewLease?.release()
+      releaseCanonical?.()
     }
   }
 

package/server/lib/whisper-metal-gate.ts

@@ -39,6 +39,7 @@ export type ContentionReason =
   | 'prompt_draft_warm'
   | 'prompt_draft_finalize'
   | 'metal_batch_in_flight'
+  | 'canonical_in_flight'
 
 export type DeviceReason =
   | 'force_cpu'
@@ -72,6 +73,8 @@ export function batchHqMetalEnabled(): boolean {
 type LiveActivityProbe = () => number | null
 
 let liveActivityProbe: LiveActivityProbe | null = null
+let canonicalMetalRequests = 0
+const previewMetalRequests = new Set<AbortController>()
 
 /** transcribe-stream calls this at module load. Returns the most recent
  *  lastActivityAt across in-memory sessions, or null when there are none. */
@@ -83,6 +86,9 @@ export function registerLiveActivityProbe(probe: LiveActivityProbe): void {
 export function resetMetalGateForTests(): void {
   liveActivityProbe = null
   metalChildren.clear()
+  canonicalMetalRequests = 0
+  for (const controller of previewMetalRequests) controller.abort('test_reset')
+  previewMetalRequests.clear()
 }
 
 function recentSessionActivity(now: number): boolean {
@@ -115,6 +121,7 @@ function activeMetalFamilyWork(): ContentionReason | null {
 
 /** Is something live currently entitled to Metal? */
 export function isLiveMetalContended(now: number = Date.now()): { contended: boolean; reason: ContentionReason | null } {
+  if (canonicalMetalRequests > 0) return { contended: true, reason: 'canonical_in_flight' }
   const work = activeMetalFamilyWork()
   if (work) return { contended: true, reason: work }
   if (recentSessionActivity(now)) return { contended: true, reason: 'session_recent' }
@@ -122,6 +129,52 @@ export function isLiveMetalContended(now: number = Date.now()): { contended: boo
   return { contended: false, reason: null }
 }
 
+export interface MetalPreviewLease {
+  signal: AbortSignal
+  release: () => void
+}
+
+/** Cosmetic preview receives Metal only while canonical work is idle. The
+ * registration is synchronous, so a canonical request that begins afterward
+ * can abort this request before starting its own inference. */
+export function tryAcquireMetalPreview(): MetalPreviewLease | null {
+  // Recent session activity is not itself GPU work. Allow preview between
+  // canonical chunks, but never alongside an active canonical or HQ Metal job.
+  if (canonicalMetalRequests > 0 || metalChildren.size > 0) return null
+  const controller = new AbortController()
+  previewMetalRequests.add(controller)
+  let released = false
+  return {
+    signal: controller.signal,
+    release: () => {
+      if (released) return
+      released = true
+      previewMetalRequests.delete(controller)
+    },
+  }
+}
+
+/** Canonical live transcription always wins. Abort any cosmetic preview first,
+ * then hold a synchronous counter so no new preview can enter until release. */
+export function beginCanonicalMetal(reason: string): () => void {
+  canonicalMetalRequests++
+  for (const controller of previewMetalRequests) controller.abort(reason)
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    canonicalMetalRequests = Math.max(0, canonicalMetalRequests - 1)
+  }
+}
+
+export class MetalPreviewContendedError extends Error {
+  readonly contended = true
+  constructor() {
+    super('Whisper preview yielded to canonical transcription')
+    this.name = 'MetalPreviewContendedError'
+  }
+}
+
 /** Device for the NEXT batch segment. Re-evaluated per segment so a meeting
  *  that starts mid-batch moves subsequent segments to CPU without a preempt. */
 export function chooseBatchDevice(now: number = Date.now()): BatchDeviceDecision {

package/server/lib/whisper-preview.ts

@@ -1,6 +1,6 @@
 // Adaptive provisional transcription:
 //   Balanced -> isolated Small.en cosmetic preview + Turbo live commit
-//   Max      -> resident Large-v3 worker reused for preview + live commit
+//   Max      -> isolated Turbo cosmetic preview + Large-v3 live commit
 //   polish   -> Large-v3 save pass (unchanged)
 
 import { execFile, spawn } from 'node:child_process'
@@ -16,9 +16,11 @@ import {
   type WhisperCommitModel,
   type WhisperTranscriptionTier,
 } from './whisper-local.js'
+import { MetalPreviewContendedError, tryAcquireMetalPreview } from './whisper-metal-gate.js'
 
 export type WhisperPreviewRequest = 'auto' | 'small.en' | 'turbo' | 'off'
 export type WhisperPreviewModel = 'small.en' | WhisperCommitModel | null
+type WhisperPreviewSidecarModel = 'small.en' | 'large-v3-turbo'
 export type WhisperPreviewReason =
   | 'disabled'
   | 'small_model_missing'
@@ -50,6 +52,7 @@ export interface WhisperPreviewCapability {
 
 const MODEL_DIR = join(process.env.HOME ?? homedir(), '.local/share/whisper-models')
 export const WHISPER_SMALL_EN_MODEL_PATH = join(MODEL_DIR, 'ggml-small.en.bin')
+const WHISPER_TURBO_MODEL_PATH = join(MODEL_DIR, 'ggml-large-v3-turbo.bin')
 const VAD_MODEL_PATH = join(MODEL_DIR, 'ggml-silero-v5.1.2.bin')
 const VAD_ENABLED = process.env.COS_WHISPER_VAD !== '0'
 const WHISPER_SERVER = ['/opt/homebrew/bin/whisper-server', '/usr/local/bin/whisper-server']
@@ -63,6 +66,7 @@ let previewProcess: ChildProcess | null = null
 let previewAvailable = false
 let previewStarting = false
 let previewFailure: WhisperPreviewReason = null
+let previewWorkerModel: WhisperPreviewSidecarModel | null = null
 let warnedInvalidChoice = false
 
 interface ProcessEntry {
@@ -103,10 +107,11 @@ function isCosPreviewCommand(command: string): boolean {
   const executablePath = firstToken?.[1] ?? firstToken?.[2] ?? firstToken?.[3] ?? ''
   return basename(executablePath) === 'whisper-server'
     && new RegExp(`(?:^|\\s)--port(?:=|\\s+)${PREVIEW_PORT}(?:\\s|$)`).test(command)
-    && command.includes(WHISPER_SMALL_EN_MODEL_PATH)
+    && [WHISPER_SMALL_EN_MODEL_PATH, WHISPER_TURBO_MODEL_PATH]
+      .some(modelPath => command.includes(modelPath))
 }
 
-/** Reap only a listener proven to be our exact Small.en/8177 command. An
+/** Reap only a listener proven to be our exact COS preview/8177 command. An
  * unrelated local service is never contacted with audio or terminated. */
 async function reclaimPreviewPort(): Promise<'clear' | 'reaped' | 'foreign'> {
   const listeners = await previewListeningPids()
@@ -135,7 +140,7 @@ async function reclaimPreviewPort(): Promise<'clear' | 'reaped' | 'foreign'> {
     if ((await previewListeningPids()).length === 0) return 'reaped'
     await new Promise(resolve => setTimeout(resolve, 100))
   }
-  throw new Error(`verified Small.en worker still owns port ${PREVIEW_PORT}`)
+  throw new Error(`verified COS preview worker still owns port ${PREVIEW_PORT}`)
 }
 
 export function normalizeWhisperPreviewRequest(raw?: string): WhisperPreviewRequest {
@@ -169,11 +174,21 @@ function requestedPreviewModel(): WhisperPreviewRequest {
 function selectedPreviewModel(requested = requestedPreviewModel()): WhisperPreviewModel {
   if (requested === 'off') return null
   const primary = getWhisperCommitCapability().effectiveModel
-  if (requested === 'turbo') return primary
+  if (requested === 'turbo') {
+    return existsSync(WHISPER_TURBO_MODEL_PATH) ? 'large-v3-turbo' : primary
+  }
   if (requested === 'small.en') return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : primary
   return existsSync(WHISPER_SMALL_EN_MODEL_PATH) ? 'small.en' : primary
 }
 
+function sidecarModelPath(model: WhisperPreviewSidecarModel): string {
+  return model === 'small.en' ? WHISPER_SMALL_EN_MODEL_PATH : WHISPER_TURBO_MODEL_PATH
+}
+
+function needsPreviewSidecar(model: WhisperPreviewModel): model is WhisperPreviewSidecarModel {
+  return model !== null && model !== getWhisperCommitCapability().effectiveModel
+}
+
 export function getWhisperPreviewCapability(): WhisperPreviewCapability {
   const commit = getWhisperCommitCapability()
   const requested = requestedPreviewModel()
@@ -189,12 +204,12 @@ export function getWhisperPreviewCapability(): WhisperPreviewCapability {
     }
   }
 
-  const smallPresent = existsSync(WHISPER_SMALL_EN_MODEL_PATH)
   const selected = selectedPreviewModel(requested)
-  const turboReady = getWhisperHealth().server
-  if (selected === 'small.en' && previewAvailable) {
+  const primaryReady = getWhisperHealth().server
+  const sidecarExpected = needsPreviewSidecar(selected)
+  if (sidecarExpected && previewAvailable && previewWorkerModel === selected) {
     return {
-      requested, effectiveModel: 'small.en', ready: true,
+      requested, effectiveModel: selected, ready: true,
       backend: 'whisper-preview-server', degraded: commit.degraded, reason: commit.reason,
       previewDegraded: false, commitDegraded: commit.degraded, commitReason: commit.reason,
       committedModel: commit.effectiveModel,
@@ -204,20 +219,24 @@ export function getWhisperPreviewCapability(): WhisperPreviewCapability {
     }
   }
 
-  const smallWasExpected = requested === 'small.en' || (requested === 'auto' && smallPresent)
-  const previewDegraded = smallWasExpected
+  const selectedModelMissing = requested === 'small.en' && !existsSync(WHISPER_SMALL_EN_MODEL_PATH)
+    ? 'small_model_missing'
+    : requested === 'turbo' && !existsSync(WHISPER_TURBO_MODEL_PATH)
+      ? 'turbo_model_missing'
+      : null
+  const previewDegraded = sidecarExpected || selectedModelMissing !== null
   const reason: WhisperPreviewReason = commit.reason
     ? commit.reason
-    : requested === 'small.en' && !smallPresent
-    ? 'small_model_missing'
-    : smallWasExpected
+    : selectedModelMissing
+      ? selectedModelMissing
+      : sidecarExpected
       ? (previewFailure ?? (previewStarting ? null : 'preview_sidecar_unavailable'))
-      : turboReady ? null : 'turbo_unavailable'
+      : primaryReady ? null : 'turbo_unavailable'
   return {
     requested,
-    effectiveModel: turboReady ? commit.effectiveModel : selected,
-    ready: turboReady,
-    backend: turboReady ? 'whisper-server' : null,
+    effectiveModel: primaryReady ? commit.effectiveModel : selected,
+    ready: primaryReady,
+    backend: primaryReady ? 'whisper-server' : null,
     degraded: previewDegraded || commit.degraded,
     reason,
     previewDegraded,
@@ -232,16 +251,21 @@ export function getWhisperPreviewCapability(): WhisperPreviewCapability {
 }
 
 async function endpointReady(path: '/health' | '/inference', init?: RequestInit, timeoutMs = 1_000): Promise<Response> {
-  return fetch(`${PREVIEW_URL}${path}`, { ...init, signal: AbortSignal.timeout(timeoutMs) })
+  const timeoutSignal = AbortSignal.timeout(timeoutMs)
+  const signal = init?.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal
+  return fetch(`${PREVIEW_URL}${path}`, { ...init, signal })
 }
 
-/** Start the optional small.en preview worker. Failure is cosmetic: committed
- * Turbo and every recovery/finalization path stay untouched. */
+/** Start the optional isolated preview worker. Balanced uses Small.en; Max
+ * uses Turbo while its canonical live worker remains Large-v3. Failure is
+ * cosmetic: every recovery/finalization path stays untouched. */
 export async function startWhisperPreviewServer(): Promise<void> {
   const requested = requestedPreviewModel()
-  if (selectedPreviewModel(requested) !== 'small.en' || previewProcess || previewAvailable || previewStarting) return
-  if (!existsSync(WHISPER_SMALL_EN_MODEL_PATH)) {
-    previewFailure = 'small_model_missing'
+  const selected = selectedPreviewModel(requested)
+  if (!needsPreviewSidecar(selected) || previewProcess || previewAvailable || previewStarting) return
+  const modelPath = sidecarModelPath(selected)
+  if (!existsSync(modelPath)) {
+    previewFailure = selected === 'small.en' ? 'small_model_missing' : 'turbo_model_missing'
     return
   }
   if (!existsSync(WHISPER_SERVER)) {
@@ -259,7 +283,7 @@ export async function startWhisperPreviewServer(): Promise<void> {
         return
       }
       if (portState === 'reaped') {
-        console.log('[whisper-preview] reaped a stale Small.en worker before restart')
+        console.log('[whisper-preview] reaped a stale COS preview worker before restart')
       }
     } catch (error) {
       previewFailure = 'preview_start_failed'
@@ -268,7 +292,7 @@ export async function startWhisperPreviewServer(): Promise<void> {
     }
 
     const args = [
-      '-m', WHISPER_SMALL_EN_MODEL_PATH,
+      '-m', modelPath,
       '-t', '16',
       '-l', 'en',
       '-fa',
@@ -281,10 +305,12 @@ export async function startWhisperPreviewServer(): Promise<void> {
     }
     const child = spawn(WHISPER_SERVER, args, { stdio: 'ignore', detached: false })
     previewProcess = child
+    previewWorkerModel = selected
     child.once('close', code => {
       if (previewProcess !== child) return
       previewProcess = null
       previewAvailable = false
+      previewWorkerModel = null
       previewFailure = code === 0 ? 'preview_sidecar_unavailable' : 'preview_start_failed'
     })
     child.once('error', () => {
@@ -300,7 +326,8 @@ export async function startWhisperPreviewServer(): Promise<void> {
         if (response.ok) {
           previewAvailable = true
           previewFailure = null
-          console.log('[whisper-preview] small.en ready for provisional text; committed text remains Turbo')
+          const committed = getWhisperCommitCapability().effectiveModel
+          console.log(`[whisper-preview] ${selected} ready for provisional text; committed text remains ${committed}`)
           return
         }
       } catch { /* model still loading */ }
@@ -308,6 +335,7 @@ export async function startWhisperPreviewServer(): Promise<void> {
     }
     try { child.kill('SIGKILL') } catch { /* already exited */ }
     if (previewProcess === child) previewProcess = null
+    previewWorkerModel = null
     previewFailure = 'preview_start_failed'
   } finally {
     previewStarting = false
@@ -336,6 +364,7 @@ export async function stopWhisperPreviewServer(): Promise<void> {
   previewProcess = null
   previewAvailable = false
   previewStarting = false
+  previewWorkerModel = null
   if (child) {
     try { child.kill('SIGTERM') } catch { /* already exited */ }
     if (!await waitForPreviewClose(child, 2_000)) {
@@ -345,40 +374,63 @@ export async function stopWhisperPreviewServer(): Promise<void> {
   }
 }
 
-async function transcribeViaPreviewServer(audioBuffer: Buffer): Promise<string> {
+async function transcribeViaPreviewServer(audioBuffer: Buffer, signal: AbortSignal): Promise<string> {
   const formData = new FormData()
   formData.append('file', new Blob([new Uint8Array(audioBuffer)], { type: 'audio/wav' }), 'recording.wav')
   formData.append('response_format', 'json')
   // Preview text is cosmetic and the same audio is authoritatively decoded by
-  // the commit lane. Small.en is disproportionately suggestible on short
-  // windows, so never bias this provisional decode with profile vocabulary.
+  // the commit lane. Never bias this provisional decode with profile vocabulary.
   formData.append('suppress_non_speech', 'true')
-  const response = await endpointReady('/inference', { method: 'POST', body: formData }, 5_000)
+  const response = await endpointReady('/inference', { method: 'POST', body: formData, signal }, 5_000)
   if (!response.ok) throw new Error(`preview server ${response.status}`)
   const result = await response.json() as { text?: unknown }
   if (typeof result.text !== 'string') throw new Error('preview server returned invalid text')
   return applyCorrections(result.text.trim())
 }
 
-/** Cosmetic preview only. A small-worker failure falls through to the existing
- * non-circuit Turbo decode and can never write committed transcript state. */
+/** Cosmetic preview only. A sidecar failure falls through to the existing
+ * non-circuit canonical decode and can never write committed transcript state. */
 export async function transcribeWhisperPreview(audioBuffer: Buffer): Promise<{
   text: string
   model: 'small.en' | WhisperCommitModel
   backend: 'whisper-preview-server' | 'whisper-server'
-}> {
-  if (previewAvailable) {
+  }> {
+  if (previewAvailable && previewWorkerModel) {
+    const workerModel = previewWorkerModel
+    const previewLease = tryAcquireMetalPreview()
+    if (!previewLease) {
+      return { text: '', model: workerModel, backend: 'whisper-preview-server' }
+    }
     try {
-      return { text: await transcribeViaPreviewServer(audioBuffer), model: 'small.en', backend: 'whisper-preview-server' }
+      return {
+        text: await transcribeViaPreviewServer(audioBuffer, previewLease.signal),
+        model: workerModel,
+        backend: 'whisper-preview-server',
+      }
     } catch (error) {
+      if (previewLease.signal.aborted) {
+        return { text: '', model: workerModel, backend: 'whisper-preview-server' }
+      }
+      const failedModel = previewWorkerModel
       previewAvailable = false
+      previewWorkerModel = null
       previewFailure = 'preview_sidecar_unavailable'
-      console.warn(`[whisper-preview] small.en preview failed; falling back to Turbo: ${error instanceof Error ? error.message : error}`)
+      console.warn(`[whisper-preview] ${failedModel} preview failed; falling back to canonical worker: ${error instanceof Error ? error.message : error}`)
+    } finally {
+      previewLease.release()
     }
   }
-  const result = await transcribeLocal(audioBuffer, undefined, undefined, {
-    affectsCircuit: false,
-    promptPolicy: 'none',
-  })
-  return { text: result.text, model: getWhisperCommitCapability().effectiveModel, backend: 'whisper-server' }
+  try {
+    const result = await transcribeLocal(audioBuffer, undefined, undefined, {
+      affectsCircuit: false,
+      promptPolicy: 'none',
+      metalPriority: 'preview',
+    })
+    return { text: result.text, model: getWhisperCommitCapability().effectiveModel, backend: 'whisper-server' }
+  } catch (error) {
+    if (error instanceof MetalPreviewContendedError) {
+      return { text: '', model: getWhisperCommitCapability().effectiveModel, backend: 'whisper-server' }
+    }
+    throw error
+  }
 }

package/server/routes/media.ts

@@ -28,6 +28,7 @@ import {
   getMediaStore,
   MediaStoreError,
 } from '../lib/media-store.js'
+import { currentMessageEra } from '../lib/message-era.js'
 import {
   ImageSafetyError,
   MAX_BATCH_BYTES,
@@ -175,6 +176,9 @@ mediaRouter.post('/media/associate', async (req: Request, res: Response) => {
       sessionId: safeString(req.body?.sessionId, 64),
       runId: safeString(req.body?.runId, 120),
       globalMsgNum,
+      // Association always belongs to the server's active message era. Never
+      // trust a client-supplied era to make media visible in historical turns.
+      messageEra: currentMessageEra(),
     })
     res.json({ ok: true })
   } catch (err) {

package/server/routes/query.ts

@@ -160,6 +160,7 @@ queryRouter.post('/query', async (req, res) => {
             await getMediaStore().associate(resolvedAttachments.ids, {
               sessionId: sid,
               ...(validGlobalMsgNum ? { globalMsgNum: validGlobalMsgNum } : {}),
+              messageEra: activeMessageEra,
             }).catch((err) => console.error('[query] attachment association failed:', err))
           }
           if (!done) {
@@ -199,6 +200,7 @@ queryRouter.post('/query', async (req, res) => {
       {
         abortSignal: abortController.signal,
         effort: validEffort,
+        messageEra: activeMessageEra,
         ...(validModel && isCursorModel(validModel) ? { cursorExecutionMode } : {}),
       },
     )

package/server/routes/sessions.ts

@@ -8,9 +8,46 @@ import { getArchiveDayMessages } from '../lib/archive.js'
 import { localDay } from '../lib/local-day.js'
 import { clearCodexEngineSession } from '../lib/codex-engine-sessions.js'
 import { mergeMediaAttachmentRefs, type MediaAttachmentRef } from '../../shared/media-attachment.js'
-import { currentMessageEra, exchangeBelongsToEra } from '../lib/message-era.js'
+import { currentMessageEraState, exchangeBelongsToEra, type MessageEraState } from '../lib/message-era.js'
+import { getMediaStore } from '../lib/media-store.js'
 
 export const sessionsRouter = Router()
+let mediaAssociationLookupWarned = false
+
+/** Conversation exchanges are the normal attachment projection. The media
+ * store fallback repairs turns created by the legacy query path, which did
+ * durably associate media to session + message but did not stamp the refs on
+ * the exchange. Both sources contain public refs only and remain capped by the
+ * shared merge validator. */
+function turnAttachments(
+  sessionId: string,
+  globalMsgNum: number | undefined,
+  messageEra: string | undefined,
+  activeEra: MessageEraState,
+  ...sources: unknown[]
+): MediaAttachmentRef[] {
+  let associated: MediaAttachmentRef[] = []
+  if (globalMsgNum != null) {
+    try {
+      associated = getMediaStore().getAssociatedRefs({
+        sessionId,
+        globalMsgNum,
+        messageEra,
+        activeMessageEra: activeEra.era,
+        activeEraStartedAt: activeEra.startedAt,
+      })
+    } catch (error) {
+      // Conversation history remains useful when optional media recovery is
+      // unavailable. Warn once per process instead of turning a text endpoint
+      // into a 500 or flooding logs once per turn.
+      if (!mediaAssociationLookupWarned) {
+        mediaAssociationLookupWarned = true
+        console.warn(`[sessions] media association lookup unavailable; serving text-only history: ${String(error)}`)
+      }
+    }
+  }
+  return mergeMediaAttachmentRefs(...sources, associated)
+}
 
 sessionsRouter.get('/sessions/recent', (_req, res) => {
   const sessions = getRecentSessions(24 * 60 * 60_000)
@@ -62,19 +99,22 @@ sessionsRouter.get('/sessions/:id/messages', (req, res) => {
     attachments?: MediaAttachmentRef[]
   }> = []
   const session = getSessionRaw(req.params.id)
+  const activeEra = currentMessageEraState()
   for (let i = 0; i < exchanges.length; i++) {
     const ex = exchanges[i]
     if (ex.role === 'user') {
       const next = exchanges[i + 1]
       if (next && next.role === 'assistant') {
-        const attachments = mergeMediaAttachmentRefs(ex.attachments, next.attachments)
+        const globalMsgNum = ex.globalMsgNum ?? next.globalMsgNum
+        const messageEra = ex.messageEra ?? next.messageEra
+        const attachments = turnAttachments(req.params.id, globalMsgNum, messageEra, activeEra, ex.attachments, next.attachments)
         const modelPreference = resolveExchangePairModel(ex, next, session?.modelPreference)
         messages.push({
           query: ex.content,
           text: next.content,
           timestamp: next.timestamp,
           sessionId: req.params.id,
-          ...((ex.globalMsgNum ?? next.globalMsgNum) != null ? { no: ex.globalMsgNum ?? next.globalMsgNum } : {}),
+          ...(globalMsgNum != null ? { no: globalMsgNum } : {}),
           ...(modelPreference ? { modelPreference } : {}),
           ...(attachments.length > 0 ? { attachments } : {}),
         })
@@ -246,14 +286,23 @@ sessionsRouter.get('/sessions/today/live-chats', (_req, res) => {
 // back to the archived chat's sessionId via getArchiveDayMessages.
 sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
   const todayDate = localDay()
-  const era = currentMessageEra()
+  const activeEra = currentMessageEraState()
+  const era = activeEra.era
 
   const archivedMessages = getArchiveDayMessages(todayDate)
     .filter(m => exchangeBelongsToEra(m, era))
-    .map(m => ({
-      ...m,
-      source: 'archive' as const,
-    }))
+    .map(m => {
+      const globalMsgNum = m.globalMsgNum ?? m.no
+      const attachments = turnAttachments(m.sessionId, globalMsgNum, m.messageEra, activeEra, m.attachments)
+      // Never pass an unvalidated archive attachment array through the object
+      // spread when the merge rejects it.
+      const { attachments: _rawAttachments, ...message } = m
+      return {
+        ...message,
+        source: 'archive' as const,
+        ...(attachments.length > 0 ? { attachments } : {}),
+      }
+    })
 
   const liveMessages: Array<{
     query: string
@@ -278,9 +327,9 @@ sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
         if (!exchangeBelongsToEra(ex, era)) continue
         const next = session.exchanges[i + 1]
         if (next && next.role === 'assistant') {
-          const attachments = mergeMediaAttachmentRefs(ex.attachments, next.attachments)
           const globalMsgNum = ex.globalMsgNum ?? next.globalMsgNum
           const messageEra = ex.messageEra ?? next.messageEra
+          const attachments = turnAttachments(session.id, globalMsgNum, messageEra, activeEra, ex.attachments, next.attachments)
           const modelPreference = resolveExchangePairModel(ex, next, session.modelPreference)
           liveMessages.push({
             query: ex.content,