@gotcos/glasses-server 6.21.31 → 6.21.33

package/.env.example

@@ -124,12 +124,15 @@ BIND_HOST=0.0.0.0
 # pipeline to inherit live tasks/calendar/people context. Omit for standalone.
 # COS_SCRIPTS_DIR=/path/to/your/cos/operations/scripts
 #
-# G2 "Review Meetings" reads COS meeting markdown from an operations tree:
-#   {COS_OPERATIONS_DIR}/{quilt|personal|…}/meetings/YYYY-MM/*.md
-# Prefer an explicit ops root (each COS layout can differ). If unset, the
-# server falls back to COS_SCRIPTS_DIR/.. then to local G2 recordings only.
+# G2 "Review Meetings" accepts either layout:
+#   {COS_MEETINGS_ROOT}/YYYY-MM/*.md                      # one read-only library
+#   {COS_OPERATIONS_DIR}/{domain}/meetings/YYYY-MM/*.md  # multi-domain pipeline
+# Keep COS_OPERATIONS_DIR for enrichment and writes. COS_MEETINGS_ROOT is a
+# browse override; legacy values that contain a multi-domain operations tree
+# retain their old alias behavior. If both are unset, the server tries
+# COS_SCRIPTS_DIR/.. and then local G2 recordings.
 # COS_OPERATIONS_DIR=/path/to/your/cos/operations
-# COS_MEETINGS_ROOT=/path/to/your/cos/operations   # alias for COS_OPERATIONS_DIR
+# COS_MEETINGS_ROOT=/path/to/your/existing/meetings
 
 # Telegram session/activity notifications remain OFF even if the COS scripts
 # directory contains .telegram_config.json. Enable export explicitly:
@@ -167,6 +170,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,43 @@
+## 6.21.33
+
+- **Existing meeting libraries can be selected directly.** `COS_MEETINGS_ROOT`
+  now accepts `meetings/YYYY-MM/*.md` as a read-only library, while
+  `COS_OPERATIONS_DIR` continues to own multi-domain enrichment and writes.
+- **Mixed libraries stay coherent.** Review Meetings merges direct, enriched
+  operations, and standalone G2 records, dedupes by session identity, and
+  prefers the writable enriched copy when one exists.
+- **Upgrades remain compatible.** A legacy multi-domain
+  `COS_MEETINGS_ROOT` keeps its prior operations-root meaning. Invalid explicit
+  roots report a degraded state instead of silently switching libraries.
+- **Read-only means read-only.** Direct-library speaker mutations return a
+  typed conflict, paths and symlinks are contained, scans are bounded, and
+  public health never exposes the selected filesystem path.
+
+## 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,28 @@ 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.
+
+Server 6.21.33 lets Review Meetings browse an existing single-library tree such
+as `meetings/YYYY-MM/*.md`. Set `COS_MEETINGS_ROOT` to the folder that directly
+contains the month folders. It is intentionally read-only. For the full COS
+sync and enrichment pipeline, keep using `COS_OPERATIONS_DIR` with
+`<domain>/meetings/YYYY-MM/*.md`; arbitrary domain names are supported. When a
+direct library and an operations root are both configured, the server merges
+them with standalone G2 recordings and prefers the enriched writable record
+for the same session.
+
 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.33",
   "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 },
+  }
+}