@gotcos/glasses-server 6.21.31 → 6.21.32

package/.env.example

@@ -167,6 +167,14 @@ BIND_HOST=0.0.0.0
 # deliberately independent from the progressive-HQ compute switch.
 # COS_MEETING_EARLY_SYNC=1
 
+# ── RETAINED MEETING-AUDIO PLAYBACK CLEANUP (6.21.32 canary) ────────────
+# Default OFF. When enabled, the first authenticated Play of a retained raw
+# meeting chunk creates a cached, adaptive cleanup copy. Raw WAV evidence stays
+# byte-identical; capture, live preview, canonical transcription, HQ, and sync
+# are untouched. Any FFmpeg/analyzer failure serves raw. Use `?raw=1` on the
+# playback URL for a per-request A/B comparison.
+# COS_MEETING_AUDIO_ADAPTIVE_PLAYBACK=1
+
 # ── UNSAVED-CAPTURE QUARANTINE (6.19.0) ─────────────────────────────────
 # Meeting audio whose save never landed is QUARANTINED, never deleted. It
 # surfaces on /api/health (unsaved_captures) and, with COS Control 0.3.1+,

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 6.21.32
+
+- **Adaptive meeting-audio cleanup is a default-off, replay-only canary.** When
+  `COS_MEETING_AUDIO_ADAPTIVE_PLAYBACK=1`, the authenticated retained-audio
+  playback route profiles each PCM chunk as hot/clipped, hot, quiet,
+  wind/noisy, or clean indoor, then generates a bounded cleaned WAV on first
+  play. Later plays use the cached copy.
+- **Raw evidence is immutable and remains the fallback.** Derived files live
+  beside retained raw chunks under a versioned name, count against the existing
+  8 GB archive cap, and cannot extend the seven-day retention clock. Unsupported
+  WAVs, missing FFmpeg, timeouts, and invalid output all serve the original raw
+  file. Cache-orphan cleanup deletes only directories proven to contain derived
+  playback files alone; unknown entries or failed stats retain the directory.
+  `?raw=1` provides an authenticated per-request A/B escape hatch.
+- **A live recording always wins.** Play requests made while any meeting is
+  actively recording bypass cleanup and serve raw. If recording starts after
+  cleanup was admitted, the one global cleanup worker is preempted within
+  100 ms; requests for other chunks while it is busy immediately serve raw.
+  FFmpeg falls back inside eight seconds, ahead of Control's media deadline.
+- **No live or canonical path changed.** Capture, Turbo preview, Large-v3
+  canonical transcription, speaker attribution, meeting save, HQ polish, and
+  meeting sync do not import or call the cleanup module. Health reports the
+  active policy, generated/cache/fallback counters, and raw-preservation
+  contract for COS Control and field diagnostics.
+
 ## 6.21.31
 
 Domains belong to the user. Four places in this codebase hardcoded ONE user's

package/README.md

@@ -279,6 +279,19 @@ available CPUs. `COS_MEETING_EARLY_SYNC=1` separately gives the Operations sync
 pipeline a stable meeting identity before HQ completes. Either switch can be
 disabled without changing canonical live transcription or raw meeting audio.
 
+Server 6.21.32 adds a separate default-off cleanup canary for retained review
+audio. Set `COS_MEETING_AUDIO_ADAPTIVE_PLAYBACK=1` (or use COS Control 0.5.11+)
+to profile a retained PCM chunk and create a cached playback-only copy when a
+reviewer presses Play. The raw WAV remains byte-identical, still owns the
+seven-day retention clock, and is served on every analyzer/FFmpeg failure.
+Capture, live preview, canonical transcription, speaker attribution, save, HQ,
+and meeting sync are unchanged. Append `?raw=1` to an authenticated playback
+URL for an immediate raw-versus-cleaned A/B check.
+While a meeting is actively recording, playback automatically stays raw so the
+optional cleanup process cannot contend with live transcription. Cleanup uses
+one global worker, serves raw while that worker is busy, and preempts within
+100 ms if a meeting starts after a replay request was admitted.
+
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.31",
+  "version": "6.21.32",
   "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/adaptive-playback-audio.ts

@@ -0,0 +1,384 @@
+// Adaptive cleanup for RETAINED meeting-audio playback only.
+//
+// This module deliberately does not sit on the live capture, preview, canonical
+// transcription, speaker-attribution, save, HQ, or sync paths. A reviewer asks
+// to hear a retained raw chunk; on first play we derive a bounded cleaned WAV,
+// cache it beside the raw evidence, and serve that copy. Raw is never rewritten.
+// Any unsupported input, missing ffmpeg, timeout, or invalid output falls back
+// to the exact raw path the route would have served before this feature existed.
+
+import { spawn } from 'node:child_process'
+import {
+  chmodSync,
+  existsSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+} from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { invalidateMeetingAudioStats } from './meeting-audio-archive.js'
+
+const FILTER_VERSION = 1
+// Control's bounded media request is 12s. Cleanup must fail back to raw before
+// that client deadline, with margin for the response body to transfer.
+const FFMPEG_TIMEOUT_MS = 8_000
+const LIVE_PREEMPT_POLL_MS = 100
+// Capture chunks are seconds long (~200 KB). Four MiB still tolerates a wildly
+// oversized chunk while bounding synchronous profiling on the server event loop.
+const MAX_INPUT_BYTES = 4 * 1024 * 1024
+const MAX_STDERR_BYTES = 4_096
+
+export type AdaptivePlaybackProfile =
+  | 'hot_clipped'
+  | 'hot'
+  | 'quiet'
+  | 'wind_noisy'
+  | 'clean_indoor'
+
+export interface AudioSignalProfile {
+  profile: AdaptivePlaybackProfile
+  sampleRate: number
+  channels: number
+  samples: number
+  peakDbfs: number
+  rmsDbfs: number
+  clippedSampleRatio: number
+  lowFrequencyEnergyRatio: number
+}
+
+export interface AdaptivePlaybackResult {
+  path: string
+  mode: 'raw' | 'adaptive'
+  profile: AdaptivePlaybackProfile | null
+  reason?: string
+}
+
+export interface AdaptivePlaybackOptions {
+  /** Fail-safe admission/preemption hook supplied by the meeting route. */
+  shouldAbort?: () => boolean
+}
+
+const FILTERS: Record<AdaptivePlaybackProfile, string> = {
+  hot_clipped: 'adeclip,highpass=f=100,afftdn=nt=w,volume=-8dB,alimiter=limit=0.794,loudnorm=I=-17:LRA=9:TP=-2',
+  hot: 'highpass=f=80,volume=-6dB,alimiter=limit=0.794,loudnorm=I=-17:LRA=9:TP=-2',
+  quiet: 'highpass=f=80,afftdn=nt=w,volume=6dB,alimiter=limit=0.891',
+  wind_noisy: 'highpass=f=140,afftdn=nt=w,loudnorm=I=-18:LRA=9:TP=-2',
+  clean_indoor: 'highpass=f=80,alimiter=limit=0.891',
+}
+
+type Pcm16 = {
+  sampleRate: number
+  channels: number
+  dataOffset: number
+  dataBytes: number
+}
+
+function pcm16Wav(buffer: Buffer): Pcm16 | null {
+  if (buffer.length < 44 || buffer.toString('ascii', 0, 4) !== 'RIFF' || buffer.toString('ascii', 8, 12) !== 'WAVE') return null
+  let offset = 12
+  let audioFormat = 0
+  let channels = 0
+  let sampleRate = 0
+  let bitsPerSample = 0
+  let dataOffset = -1
+  let dataBytes = 0
+  while (offset + 8 <= buffer.length) {
+    const id = buffer.toString('ascii', offset, offset + 4)
+    const size = buffer.readUInt32LE(offset + 4)
+    const start = offset + 8
+    const end = start + size
+    if (end > buffer.length) return null
+    if (id === 'fmt ' && size >= 16) {
+      audioFormat = buffer.readUInt16LE(start)
+      channels = buffer.readUInt16LE(start + 2)
+      sampleRate = buffer.readUInt32LE(start + 4)
+      bitsPerSample = buffer.readUInt16LE(start + 14)
+    } else if (id === 'data') {
+      dataOffset = start
+      dataBytes = size
+    }
+    offset = end + (size % 2)
+  }
+  if (audioFormat !== 1 || channels !== 1 || bitsPerSample !== 16 || sampleRate < 8_000 || sampleRate > 96_000) return null
+  if (dataOffset < 0 || dataBytes < 2 || dataOffset + dataBytes > buffer.length || dataBytes % 2 !== 0) return null
+  return { sampleRate, channels, dataOffset, dataBytes }
+}
+
+function dbfs(value: number): number {
+  if (!(value > 0)) return -120
+  return Math.round(20 * Math.log10(Math.min(1, value)) * 10) / 10
+}
+
+/** Pure, deterministic profiler. It never shells out and never mutates audio. */
+export function analyzePlaybackWav(buffer: Buffer): AudioSignalProfile | null {
+  const wav = pcm16Wav(buffer)
+  if (!wav) return null
+  const count = wav.dataBytes / 2
+  let peak = 0
+  let energy = 0
+  let lowEnergy = 0
+  let clipped = 0
+  let low = 0
+  // One-pole 120 Hz low-pass. This is only a conservative wind/noise proxy;
+  // it selects a stronger high-pass profile and never changes canonical text.
+  const alpha = 1 - Math.exp((-2 * Math.PI * 120) / wav.sampleRate)
+  for (let i = 0; i < count; i++) {
+    const raw = wav.dataOffset + i * 2
+    const sample = buffer.readInt16LE(raw) / 32768
+    const magnitude = Math.abs(sample)
+    peak = Math.max(peak, magnitude)
+    energy += sample * sample
+    low += alpha * (sample - low)
+    lowEnergy += low * low
+    if (Math.abs(buffer.readInt16LE(raw)) >= 32_760) clipped++
+  }
+  const rms = Math.sqrt(energy / count)
+  const clippedSampleRatio = clipped / count
+  const lowFrequencyEnergyRatio = energy > 0 ? Math.min(1, lowEnergy / energy) : 0
+  const rmsDbfs = dbfs(rms)
+  const peakDbfs = dbfs(peak)
+  let profile: AdaptivePlaybackProfile
+  if (clippedSampleRatio >= 0.0005 || rmsDbfs >= -12 || peakDbfs >= -0.3) profile = 'hot_clipped'
+  else if (lowFrequencyEnergyRatio >= 0.38 && rmsDbfs > -35) profile = 'wind_noisy'
+  else if (rmsDbfs >= -18) profile = 'hot'
+  else if (rmsDbfs <= -32) profile = 'quiet'
+  else profile = 'clean_indoor'
+  return {
+    profile,
+    sampleRate: wav.sampleRate,
+    channels: wav.channels,
+    samples: count,
+    peakDbfs,
+    rmsDbfs,
+    clippedSampleRatio: Math.round(clippedSampleRatio * 1_000_000) / 1_000_000,
+    lowFrequencyEnergyRatio: Math.round(lowFrequencyEnergyRatio * 1_000) / 1_000,
+  }
+}
+
+export function adaptivePlaybackEnabled(): boolean {
+  // Private canary: explicit opt-in, explicit 0 rollback through COS Control.
+  return process.env.COS_MEETING_AUDIO_ADAPTIVE_PLAYBACK === '1'
+}
+
+function outputPathFor(rawPath: string): string | null {
+  const rawName = basename(rawPath)
+  const match = /^chunk_(\d+)\.wav$/.exec(rawName)
+  if (!match) return null
+  const dir = dirname(rawPath)
+  const output = resolve(dir, `playback_v${FILTER_VERSION}_${match[1]}.wav`)
+  return output.startsWith(resolve(dir) + '/') ? output : null
+}
+
+function cachedOutput(rawPath: string, outputPath: string): boolean {
+  try {
+    const raw = statSync(rawPath)
+    const output = statSync(outputPath)
+    return output.isFile()
+      && output.size > 44
+      && output.mtimeMs >= raw.mtimeMs
+      && analyzePlaybackWav(readFileSync(outputPath)) !== null
+  } catch {
+    return false
+  }
+}
+
+function abortRequested(check?: () => boolean): boolean {
+  if (!check) return false
+  try { return check() }
+  catch { return true }
+}
+
+async function runFfmpeg(
+  inputPath: string,
+  outputPath: string,
+  filter: string,
+  shouldAbort?: () => boolean,
+): Promise<void> {
+  await new Promise<void>((resolvePromise, rejectPromise) => {
+    const proc = spawn('ffmpeg', [
+      '-nostdin',
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-i', inputPath,
+      '-af', filter,
+      '-ar', '16000',
+      '-ac', '1',
+      '-c:a', 'pcm_s16le',
+      '-f', 'wav',
+      '-y',
+      outputPath,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] })
+    let settled = false
+    let stderr = ''
+    let terminalError: Error | null = null
+    let killSettle: NodeJS.Timeout | null = null
+    let livePoll: NodeJS.Timeout | null = null
+    const finish = (error?: Error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      if (killSettle) clearTimeout(killSettle)
+      if (livePoll) clearInterval(livePoll)
+      error ? rejectPromise(error) : resolvePromise()
+    }
+    const stop = (error: Error) => {
+      if (settled || terminalError) return
+      terminalError = error
+      if (!proc.kill('SIGKILL')) { finish(error); return }
+      // SIGKILL should close the direct ffmpeg child immediately. Keep a bounded
+      // settle fallback so a broken process handle cannot strand the request.
+      killSettle = setTimeout(() => finish(error), 1_000)
+      killSettle.unref()
+    }
+    proc.stderr?.on('data', (chunk: Buffer) => {
+      stderr = (stderr + chunk.toString()).slice(-MAX_STDERR_BYTES)
+    })
+    const timeout = setTimeout(() => {
+      stop(new Error(`ffmpeg timeout (${FFMPEG_TIMEOUT_MS / 1000}s)`))
+    }, FFMPEG_TIMEOUT_MS)
+    timeout.unref()
+    if (shouldAbort) {
+      livePoll = setInterval(() => {
+        if (abortRequested(shouldAbort)) stop(new Error('live_recording_started'))
+      }, LIVE_PREEMPT_POLL_MS)
+      livePoll.unref()
+    }
+    proc.on('error', error => finish(error))
+    proc.on('close', code => {
+      if (terminalError) finish(terminalError)
+      else if (code !== 0) finish(new Error(`ffmpeg exit ${code}: ${stderr.trim().slice(-300)}`))
+      else finish()
+    })
+  })
+}
+
+const inFlight = new Map<string, Promise<AdaptivePlaybackResult>>()
+// One cleanup worker for the whole server. Different retained chunks never fan
+// out into competing ffmpeg children; busy requests immediately hear raw.
+let activeGenerationPath: string | null = null
+const counters = {
+  generated: 0,
+  cacheHits: 0,
+  fallbacks: 0,
+  busyBypasses: 0,
+  liveBypasses: 0,
+  profiles: {} as Record<AdaptivePlaybackProfile, number>,
+}
+
+async function prepare(rawPath: string, options: AdaptivePlaybackOptions): Promise<AdaptivePlaybackResult> {
+  if (!adaptivePlaybackEnabled()) return { path: rawPath, mode: 'raw', profile: null, reason: 'disabled' }
+  if (abortRequested(options.shouldAbort)) {
+    counters.liveBypasses++
+    return { path: rawPath, mode: 'raw', profile: null, reason: 'live_recording' }
+  }
+  if (activeGenerationPath && activeGenerationPath !== rawPath) {
+    counters.busyBypasses++
+    return { path: rawPath, mode: 'raw', profile: null, reason: 'cleanup_busy' }
+  }
+  const outputPath = outputPathFor(rawPath)
+  if (!outputPath) {
+    counters.fallbacks++
+    return { path: rawPath, mode: 'raw', profile: null, reason: 'unsupported_source' }
+  }
+  let input: Buffer
+  try {
+    const stat = statSync(rawPath)
+    if (!stat.isFile() || stat.size > MAX_INPUT_BYTES) throw new Error('input is not a bounded regular file')
+    input = readFileSync(rawPath)
+  } catch (error: unknown) {
+    counters.fallbacks++
+    return { path: rawPath, mode: 'raw', profile: null, reason: error instanceof Error ? error.message : String(error) }
+  }
+  const signal = analyzePlaybackWav(input)
+  if (!signal) {
+    counters.fallbacks++
+    return { path: rawPath, mode: 'raw', profile: null, reason: 'unsupported_wav' }
+  }
+  counters.profiles[signal.profile] = (counters.profiles[signal.profile] ?? 0) + 1
+  if (cachedOutput(rawPath, outputPath)) {
+    counters.cacheHits++
+    return { path: outputPath, mode: 'adaptive', profile: signal.profile }
+  }
+
+  // Re-check after bounded synchronous profiling. A recording that started
+  // during that work must win before any child process is launched.
+  if (abortRequested(options.shouldAbort)) {
+    counters.liveBypasses++
+    return { path: rawPath, mode: 'raw', profile: signal.profile, reason: 'live_recording' }
+  }
+  if (activeGenerationPath && activeGenerationPath !== rawPath) {
+    counters.busyBypasses++
+    return { path: rawPath, mode: 'raw', profile: signal.profile, reason: 'cleanup_busy' }
+  }
+
+  const tempPath = join(dirname(outputPath), `.${basename(outputPath)}.${randomUUID()}.tmp.wav`)
+  activeGenerationPath = rawPath
+  try {
+    await runFfmpeg(rawPath, tempPath, FILTERS[signal.profile], options.shouldAbort)
+    if (abortRequested(options.shouldAbort)) throw new Error('live_recording_started')
+    if (!existsSync(tempPath) || !analyzePlaybackWav(readFileSync(tempPath))) {
+      throw new Error('ffmpeg produced an invalid PCM WAV')
+    }
+    chmodSync(tempPath, 0o600)
+    renameSync(tempPath, outputPath)
+    counters.generated++
+    invalidateMeetingAudioStats()
+    return { path: outputPath, mode: 'adaptive', profile: signal.profile }
+  } catch (error: unknown) {
+    counters.fallbacks++
+    const message = error instanceof Error ? error.message : String(error)
+    const reason = message === 'live_recording_started' ? 'live_recording' : message
+    if (reason === 'live_recording') counters.liveBypasses++
+    console.warn(`[adaptive-playback] cleanup failed (${signal.profile}); serving raw: ${reason}`)
+    return { path: rawPath, mode: 'raw', profile: signal.profile, reason }
+  } finally {
+    if (activeGenerationPath === rawPath) activeGenerationPath = null
+    try { unlinkSync(tempPath) } catch { /* already renamed or never created */ }
+  }
+}
+
+/** Single-flight per raw chunk so simultaneous Play requests run ffmpeg once. */
+export async function adaptivePlaybackAudio(
+  rawPath: string,
+  options: AdaptivePlaybackOptions = {},
+): Promise<AdaptivePlaybackResult> {
+  const current = inFlight.get(rawPath)
+  if (current) return current
+  const pending = prepare(rawPath, options).finally(() => inFlight.delete(rawPath))
+  inFlight.set(rawPath, pending)
+  return pending
+}
+
+export function adaptivePlaybackStatus(): {
+  supported: true
+  enabled: boolean
+  mode: 'retained_replay_only'
+  rawPreserved: true
+  liveRecordingProtected: true
+  generatedThisBoot: number
+  cacheHitsThisBoot: number
+  fallbacksThisBoot: number
+  busyBypassesThisBoot: number
+  liveBypassesThisBoot: number
+  inFlight: number
+  globalWorkerBusy: boolean
+  profilesThisBoot: Partial<Record<AdaptivePlaybackProfile, number>>
+} {
+  return {
+    supported: true,
+    enabled: adaptivePlaybackEnabled(),
+    mode: 'retained_replay_only',
+    rawPreserved: true,
+    liveRecordingProtected: true,
+    generatedThisBoot: counters.generated,
+    cacheHitsThisBoot: counters.cacheHits,
+    fallbacksThisBoot: counters.fallbacks,
+    busyBypassesThisBoot: counters.busyBypasses,
+    liveBypassesThisBoot: counters.liveBypasses,
+    inFlight: inFlight.size,
+    globalWorkerBusy: activeGenerationPath !== null,
+    profilesThisBoot: { ...counters.profiles },
+  }
+}

package/server/lib/meeting-audio-archive.ts

@@ -60,6 +60,11 @@ function isChunkWav(name: string): boolean {
   return /^chunk_\d+\.wav$/.test(name)
 }
 
+/** Derived playback copies count against the cap but never define retention age. */
+function isDerivedPlaybackWav(name: string): boolean {
+  return /^playback_v\d+_\d+\.wav$/.test(name)
+}
+
 export interface ArchiveResult {
   linked: number
   /** Files that had to be copied because the link failed (e.g. cross-device). */
@@ -110,19 +115,40 @@ export function archiveSessionAudio(sessionId: string, sourceDir: string): Archi
 }
 
 /** Bytes and age for one archived session. */
-function sessionSize(dir: string): { bytes: number; mtimeMs: number; files: number } {
-  let bytes = 0, mtimeMs = 0, files = 0
+function sessionSize(dir: string): {
+  bytes: number
+  mtimeMs: number
+  files: number
+  derivedFiles: number
+  otherEntries: number
+  statFailures: number
+  readable: boolean
+} {
+  let bytes = 0, mtimeMs = 0, files = 0, derivedFiles = 0
+  let otherEntries = 0, statFailures = 0, readable = false
   try {
-    for (const name of readdirSync(dir).filter(isChunkWav)) {
+    const names = readdirSync(dir)
+    readable = true
+    for (const name of names) {
+      if (!isChunkWav(name) && !isDerivedPlaybackWav(name)) {
+        otherEntries++
+        continue
+      }
       try {
         const st = statSync(join(dir, name))
         bytes += st.size
-        files++
-        mtimeMs = Math.max(mtimeMs, st.mtimeMs)
-      } catch { /* skip unreadable */ }
+        // A replay created six days after capture must not buy the raw evidence
+        // another seven days. Only immutable raw chunks determine session age.
+        if (isChunkWav(name)) {
+          files++
+          mtimeMs = Math.max(mtimeMs, st.mtimeMs)
+        } else {
+          derivedFiles++
+        }
+      } catch { statFailures++ }
     }
   } catch { /* unreadable dir reports zero */ }
-  return { bytes, mtimeMs, files }
+  return { bytes, mtimeMs, files, derivedFiles, otherEntries, statFailures, readable }
 }
 
 export interface SweepResult {
@@ -145,7 +171,14 @@ export function sweepMeetingAudio(nowMs: number, ttlMs = meetingAudioTtlMs()): S
   try { names = readdirSync(root) } catch { return out }
   for (const name of names) {
     const dir = join(root, name)
-    const { bytes, mtimeMs } = sessionSize(dir)
+    const { bytes, mtimeMs, files, derivedFiles, otherEntries, statFailures, readable } = sessionSize(dir)
+    // Delete only a provably cache-only directory. Any unknown entry or failed
+    // stat may be retained evidence, so ambiguity fails closed to preservation.
+    if (readable && files === 0 && derivedFiles > 0 && otherEntries === 0 && statFailures === 0) {
+      try { rmSync(dir, { recursive: true, force: true }); out.removed.push(name); out.bytesFreed += bytes }
+      catch { out.retained.push(name) }
+      continue
+    }
     if (mtimeMs <= 0) { out.retained.push(name); continue }
     if (nowMs - mtimeMs > ttlMs) {
       try { rmSync(dir, { recursive: true, force: true }); out.removed.push(name); out.bytesFreed += bytes }

package/server/routes/health.ts

@@ -10,6 +10,7 @@ import { profileProvenanceSummary, speakerModelState, speakerReadiness } from '.
 import { chunkEmbeddingStoreStats } from '../lib/chunk-embedding-store.js'
 import { correctionStoreStats } from '../lib/meeting-corrections.js'
 import { meetingAudioStats } from '../lib/meeting-audio-archive.js'
+import { adaptivePlaybackStatus } from '../lib/adaptive-playback-audio.js'
 import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
 import {
   isWhisperLocalAvailable,
@@ -125,7 +126,10 @@ healthRouter.get('/health', async (_req, res) => {
   // `pending` is the number that matters here: an intent that never closed means
   // some meeting's files may be half-rewritten.
   const speakerCorrections = correctionStoreStats()
-  const reviewAudio = meetingAudioStats()
+  const reviewAudio = {
+    ...meetingAudioStats(),
+    adaptivePlayback: adaptivePlaybackStatus(),
+  }
   // `noHumanSample` is the one to read: a profile with no human-verified sample
   // is trained entirely on labels the system chose for itself.
   const voiceProvenance = speakerId.state === 'active' ? profileProvenanceSummary() : null

package/server/routes/meeting.ts

@@ -11,6 +11,7 @@ import { durableAtomicWriteFileSync } from '../lib/atomic-fs.js'
 import { appendCorrection, appliedCorrections, pendingCorrections } from '../lib/meeting-corrections.js'
 import { isSampleFromSession, untraceableSampleCount } from '../lib/training-audio-provenance.js'
 import { sendAudioFile } from '../lib/send-audio.js'
+import { adaptivePlaybackAudio } from '../lib/adaptive-playback-audio.js'
 import { chunkDiagnostics } from '../lib/chunk-embedding-diagnostics.js'
 import { errMsg } from '../lib/utils.js'
 import { confirmedLabels } from '../lib/meeting-corrections.js'
@@ -100,6 +101,7 @@ import {
   getSessionStartTime,
   getSessionTranscript,
   getMeetingSessionStatus,
+  getTranscriptionSessionLiveness,
   hasSessionAudio,
   moveSessionAudioToPending,
   type IndexedTranscriptChunk,
@@ -1423,7 +1425,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
   // voice. Retention is 7 days (see meeting-audio-archive), so this answers with
   // 404 + a reason once the window has passed rather than pretending the audio
   // was never there.
-  router.get('/meeting/:sessionId/audio/:chunkIndex', (req, res) => {
+  router.get('/meeting/:sessionId/audio/:chunkIndex', async (req, res) => {
     res.set('Cache-Control', 'private, no-store')
     const sessionId = String(req.params.sessionId ?? '')
     if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) {
@@ -1440,8 +1442,8 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
     // fallback there is nothing to play on any meeting predating 6.21.18 — while
     // 72 hours of unidentified-voice audio is sitting right there, and an
     // unidentified voice is exactly what a reviewer needs to hear.
-    const path = meetingAudioChunkPath(sessionId, chunkIndex)
-      ?? extAudioChunkPath(sessionId, chunkIndex)
+    const archivedPath = meetingAudioChunkPath(sessionId, chunkIndex)
+    const path = archivedPath ?? extAudioChunkPath(sessionId, chunkIndex)
     if (!path) {
       const retained = [...new Set([
         ...listMeetingAudioChunks(sessionId),
@@ -1460,7 +1462,30 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       })
       return
     }
-    sendAudioFile(res, path)
+    // Canary scope is intentionally narrow: only the week-retained immutable
+    // archive gets a derived playback copy. Legacy ext-audio remains byte-for-
+    // byte raw. `?raw=1` is the authenticated A/B and emergency per-request
+    // escape hatch; the COS Control toggle is the machine-wide rollback.
+    const liveRecording = getTranscriptionSessionLiveness().live > 0
+    const playback = archivedPath && req.query.raw !== '1' && !liveRecording
+      ? await adaptivePlaybackAudio(archivedPath, {
+          // Admission is not enough: if a meeting starts while FFmpeg is
+          // working, the replay job is preempted and this request hears raw.
+          shouldAbort: () => getTranscriptionSessionLiveness().live > 0,
+        })
+      : { path, mode: 'raw' as const, profile: null }
+    res.set('X-COS-Audio-Playback', playback.mode)
+    const bypassReason = 'reason' in playback ? playback.reason : undefined
+    const bypass = liveRecording
+      ? 'live_recording'
+      : bypassReason === 'live_recording'
+        ? 'live_recording'
+        : bypassReason === 'cleanup_busy'
+          ? 'cleanup_busy'
+          : null
+    if (bypass) res.set('X-COS-Audio-Bypass', bypass)
+    if (playback.profile) res.set('X-COS-Audio-Profile', playback.profile)
+    sendAudioFile(res, playback.path)
   })
 
   /**