@gotcos/glasses-server 6.94.4 → 6.98.0

package/server/lib/speaker-shadow-timeline.ts

@@ -0,0 +1,210 @@
+// Speaker shadow mode (6.95.0): the whole-call timeline and the production segments.
+//
+// A port of round3/propose.py `build_timeline` and its segment loop. READ ONLY: it reads
+// the finalized sidecar and the retained chunk WAVs and returns buffers; it never writes.
+//
+// Placement policy (the canary's): each original chunk starts at floor(elapsed_ms*16+.5),
+// rows sort by (start, raw index), an original's tail that runs into the next one's start
+// is trimmed, and gaps stay zero. Every original with an `audioSha256` must still match
+// it, and each file is read twice with the second read required to hash the same as the
+// first, which is what the tool's "rebuild twice, same PCM SHA" check proves.
+
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { hasMacSpeakerProtectedRows } from './mac-speaker-protection.js'
+import { SHADOW_SAMPLE_RATE, isShadowVoiceLabel, type ShadowSegment, type ShadowSegmentSource } from './speaker-shadow-decide.js'
+import { PY_SPACE_CLASS, pyRoundInt } from './speaker-shadow-numeric.js'
+
+/** A meeting longer than this is not reconstructed (the timeline buffer is 115 MB per hour). */
+export const SHADOW_MAX_TIMELINE_SECONDS = 4 * 60 * 60
+
+export class ShadowInputError extends Error {
+  constructor(readonly reason: 'bad_sidecar' | 'audio_missing' | 'audio_format' | 'audio_drift' | 'too_long', message: string) {
+    super(message)
+    this.name = 'ShadowInputError'
+  }
+}
+
+export interface ShadowChunkEntry { chunkIndex: number; chunk: Record<string, unknown> }
+export interface ShadowTimelineRow { rawChunkIndex: number; startSample: number; sampleCount: number; usedSampleCount: number }
+export interface ShadowTimeline {
+  rows: ShadowTimelineRow[]
+  pcm: Buffer
+  total: number
+  verified: number
+  unhashed: number
+  unhashedWithText: number[]
+  pcmSHA256: string
+}
+
+const sha256 = (data: Buffer) => createHash('sha256').update(data).digest('hex')
+const PY_STRIP = new RegExp(`^${PY_SPACE_CLASS}+|${PY_SPACE_CLASS}+$`, 'gu')
+
+/** Validated entries in sidecar order, or a bad_sidecar error. */
+export function shadowEntries(sidecar: Record<string, unknown>): ShadowChunkEntry[] {
+  const raw = sidecar.chunkEntries
+  if (!Array.isArray(raw) || !raw.length) throw new ShadowInputError('bad_sidecar', 'the sidecar has no chunkEntries')
+  const seen = new Set<number>()
+  return raw.map(item => {
+    const e = item as { chunkIndex?: unknown; chunk?: unknown }
+    if (!e || typeof e !== 'object' || !Number.isInteger(e.chunkIndex) || (e.chunkIndex as number) < 0 || (e.chunkIndex as number) > 99_999) throw new ShadowInputError('bad_sidecar', 'a chunk entry has no valid chunkIndex')
+    if (!e.chunk || typeof e.chunk !== 'object' || Array.isArray(e.chunk)) throw new ShadowInputError('bad_sidecar', 'a chunk entry has no chunk')
+    const chunk = e.chunk as Record<string, unknown>
+    if (typeof chunk.elapsed !== 'number' || !Number.isFinite(chunk.elapsed)) throw new ShadowInputError('bad_sidecar', 'a chunk has no elapsed clock')
+    if (chunk.segments !== undefined && !Array.isArray(chunk.segments)) throw new ShadowInputError('bad_sidecar', 'a chunk has malformed segments')
+    if (seen.has(e.chunkIndex as number)) throw new ShadowInputError('bad_sidecar', 'duplicate chunkIndex')
+    seen.add(e.chunkIndex as number)
+    return { chunkIndex: e.chunkIndex as number, chunk }
+  })
+}
+
+/** propose.py labels_of: what a later correction would change. Hashed, so a run can refuse labels that moved after finalize. */
+export function shadowLabelsHash(entries: readonly ShadowChunkEntry[]): string {
+  const projection = entries.map(e => [
+    e.chunkIndex,
+    e.chunk.speaker ?? null,
+    ((e.chunk.segments as unknown[] | undefined) ?? []).map(s => {
+      const seg = (s ?? {}) as Record<string, unknown>
+      return [seg.speaker ?? null, seg.startSec ?? null, seg.endSec ?? null]
+    }),
+  ])
+  return createHash('sha256').update(JSON.stringify(projection)).digest('hex')
+}
+
+/** Python `wave` read of a 16 kHz mono 16-bit PCM file: the declared frames and their bytes. */
+export function readPcm16Wav(wav: Buffer): { sampleCount: number; pcm: Buffer } {
+  if (wav.length < 12 || wav.toString('ascii', 0, 4) !== 'RIFF' || wav.toString('ascii', 8, 12) !== 'WAVE') throw new ShadowInputError('audio_format', 'not a RIFF/WAVE file')
+  let offset = 12, fmtOk = false
+  while (offset + 8 <= wav.length) {
+    const id = wav.toString('ascii', offset, offset + 4)
+    const size = wav.readUInt32LE(offset + 4)
+    const body = offset + 8
+    if (id === 'fmt ') {
+      if (body + 16 > wav.length) throw new ShadowInputError('audio_format', 'truncated fmt chunk')
+      const format = wav.readUInt16LE(body), channels = wav.readUInt16LE(body + 2), rate = wav.readUInt32LE(body + 4), bits = wav.readUInt16LE(body + 14)
+      if (format !== 1 || channels !== 1 || rate !== SHADOW_SAMPLE_RATE || bits !== 16) throw new ShadowInputError('audio_format', `expected 16 kHz mono PCM16, got format ${format}, ${channels} ch, ${rate} Hz, ${bits} bit`)
+      fmtOk = true
+    } else if (id === 'data') {
+      if (!fmtOk) throw new ShadowInputError('audio_format', 'data before fmt')
+      const sampleCount = Math.floor(size / 2)
+      if (body + sampleCount * 2 > wav.length) throw new ShadowInputError('audio_format', 'truncated data chunk')
+      return { sampleCount, pcm: wav.subarray(body, body + sampleCount * 2) }
+    }
+    offset = body + size + (size % 2)
+  }
+  throw new ShadowInputError('audio_format', 'no data chunk')
+}
+
+/** The 44-byte header Python's wave writer emits, then the PCM. */
+export function pcm16WavFile(pcm: Buffer): Buffer {
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0); header.writeUInt32LE(36 + pcm.length, 4); header.write('WAVE', 8); header.write('fmt ', 12)
+  header.writeUInt32LE(16, 16); header.writeUInt16LE(1, 20); header.writeUInt16LE(1, 22); header.writeUInt32LE(SHADOW_SAMPLE_RATE, 24)
+  header.writeUInt32LE(SHADOW_SAMPLE_RATE * 2, 28); header.writeUInt16LE(2, 32); header.writeUInt16LE(16, 34); header.write('data', 36); header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+async function readOriginal(path: string): Promise<Buffer> {
+  try { return await readFile(path) } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code
+    throw new ShadowInputError(code === 'ENOENT' ? 'audio_missing' : 'audio_format', `original ${path.split('/').pop()}: ${code ?? 'unreadable'}`)
+  }
+}
+
+/** Every original verified, placed and copied into one PCM buffer. Async reads, one file at a time. */
+export async function buildShadowTimeline(entries: readonly ShadowChunkEntry[], originalPath: (chunkIndex: number) => string): Promise<ShadowTimeline> {
+  const SR = SHADOW_SAMPLE_RATE
+  let verified = 0
+  const unhashed: number[] = [], unhashedWithText: number[] = []
+  const firstHash = new Map<number, string>()
+  const rows: Array<ShadowTimelineRow & { path: string }> = []
+  for (const e of entries) {
+    const path = originalPath(e.chunkIndex)
+    const bytes = await readOriginal(path)
+    const digest = sha256(bytes)
+    const want = e.chunk.audioSha256
+    if (typeof want === 'string' && want) {
+      if (digest !== want) throw new ShadowInputError('audio_drift', `original ${e.chunkIndex} no longer matches the sidecar audioSha256`)
+      verified++
+    } else {
+      unhashed.push(e.chunkIndex)
+      const text = typeof e.chunk.text === 'string' ? e.chunk.text : ''
+      if (text.replace(PY_STRIP, '')) unhashedWithText.push(e.chunkIndex)
+    }
+    const { sampleCount } = readPcm16Wav(bytes)
+    firstHash.set(e.chunkIndex, digest)
+    rows.push({ rawChunkIndex: e.chunkIndex, startSample: Math.floor((e.chunk.elapsed as number) * 16 + 0.5), sampleCount, usedSampleCount: 0, path })
+  }
+  rows.sort((a, b) => (a.startSample - b.startSample) || (a.rawChunkIndex - b.rawChunkIndex))
+  if (rows[0].startSample < 0) throw new ShadowInputError('bad_sidecar', 'a chunk starts before the recording')
+  const total = Math.max(...rows.map(x => x.startSample + x.sampleCount))
+  if (total > SHADOW_MAX_TIMELINE_SECONDS * SR) throw new ShadowInputError('too_long', `the meeting is longer than ${SHADOW_MAX_TIMELINE_SECONDS / 3600} h`)
+  const pcm = Buffer.alloc(total * 2)
+  for (let i = 0; i < rows.length; i++) {
+    const x = rows[i]
+    const bytes = await readOriginal(x.path)
+    if (sha256(bytes) !== firstHash.get(x.rawChunkIndex)) throw new ShadowInputError('audio_drift', `original ${x.rawChunkIndex} changed while the timeline was built`)
+    const raw = readPcm16Wav(bytes).pcm
+    const use = i + 1 < rows.length ? Math.min(x.sampleCount, Math.max(0, rows[i + 1].startSample - x.startSample)) : x.sampleCount
+    if (!(use > 0)) throw new ShadowInputError('bad_sidecar', `original ${x.rawChunkIndex} is fully shadowed by the next one`)
+    x.usedSampleCount = use
+    raw.copy(pcm, x.startSample * 2, 0, use * 2)
+  }
+  return {
+    rows: rows.map(({ path: _path, ...row }) => row),
+    pcm, total, verified, unhashed: unhashed.length, unhashedWithText, pcmSHA256: sha256(pcm),
+  }
+}
+
+/** propose.py's segment loop: production labels on the timeline, plus where each came from. */
+export function shadowProductionSegments(entries: readonly ShadowChunkEntry[], rows: readonly ShadowTimelineRow[], total: number): { segs: ShadowSegment[]; sources: ShadowSegmentSource[] } {
+  const SR = SHADOW_SAMPLE_RATE
+  const placed = new Map(rows.map(x => [x.rawChunkIndex, x]))
+  // Python's isinstance(x, (int, float)) is true for a JSON boolean, which counts as 0 or 1.
+  const num = (x: unknown): number | null => typeof x === 'number' ? x : typeof x === 'boolean' ? Number(x) : null
+  const segs: ShadowSegment[] = [], sources: ShadowSegmentSource[] = []
+  for (const e of entries) {
+    const x = placed.get(e.chunkIndex)!
+    const off = x.startSample, end = Math.min(total, off + x.usedSampleCount)
+    for (const raw of (e.chunk.segments as unknown[] | undefined) ?? []) {
+      const s = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+      const a = num(s.startSec), b = num(s.endSec), label = s.speaker
+      if (a === null || b === null || !label) continue
+      if (typeof label !== 'string') throw new ShadowInputError('bad_sidecar', 'a segment speaker is not a string')
+      const lo = off + pyRoundInt(a * SR), hi = Math.min(end, off + pyRoundInt(b * SR))
+      if (lo < hi) {
+        segs.push([lo, hi, label])
+        sources.push({ chunkIndex: e.chunkIndex, start: a, end: Math.min(b, x.usedSampleCount / SR), abs: lo / SR })
+      }
+    }
+  }
+  return { segs, sources }
+}
+
+/** Voice labels that appear on any chunk a human touched. A hint in the record; it never changes a gate. */
+export function shadowHumanProtectedVoices(entries: readonly ShadowChunkEntry[]): string[] {
+  const out = new Set<string>()
+  for (const e of entries) {
+    if (!hasMacSpeakerProtectedRows(e.chunk)) continue
+    const labels = [e.chunk.speaker, ...((e.chunk.segments as unknown[] | undefined) ?? []).map(s => (s as Record<string, unknown> | null)?.speaker)]
+    for (const label of labels) if (typeof label === 'string' && isShadowVoiceLabel(label)) out.add(label)
+  }
+  return [...out].sort()
+}
+
+/** The meeting's title (the saved markdown's `# ` line), else the sidecar's file name. Read only. */
+export async function readShadowMeetingTitle(sidecarPath: string): Promise<string> {
+  const fallback = basename(sidecarPath).replace(/\.g2-chunks\.json$/, '')
+  try {
+    const text = await readFile(sidecarPath.replace(/\.g2-chunks\.json$/, '.md'), 'utf8')
+    const line = text.split('\n', 40).find(l => l.startsWith('# '))
+    const title = line?.slice(2).trim()
+    return title ? title.slice(0, 160) : fallback
+  } catch { return fallback }
+}
+
+/** The meeting day for the report folder: the sidecar name's YYYY-MM-DD prefix, else null. */
+export function shadowMeetingDay(sidecarPath: string): string | null {
+  return /^(\d{4}-\d{2}-\d{2})/.exec(basename(sidecarPath))?.[1] ?? null
+}

package/server/lib/speaker-shadow-worker.ts

@@ -0,0 +1,312 @@
+// Speaker shadow mode (6.95.0): one meeting's proposal run, in its own child process.
+//
+// The server never runs this on its event loop. speaker-shadow.ts starts it as a niced
+// child (`node --import tsx/esm speaker-shadow-worker.ts`), sends one job on stdin, and
+// reads exactly one JSON outcome line from stdout. The parent owns the wall clock and the
+// RSS cap and kills the whole process group; this side also stops the CLI on its own
+// deadline and exits if its parent goes away.
+//
+// Shadow remains READ ONLY, LOG ONLY: its temporary native outputs are removed.
+// A separately default-off reviewed closed-call consumer may retain the SAME verified
+// execution exports in its own data directory. It never edits BASE, names, profiles or
+// corrections here; later derived-view publication has an independent queue/admission.
+//
+// The CLI is FluidAudio 0.17.4 `process --mode offline --overlapping-segments
+// --export-embeddings`, the exact invocation of round3/propose.py, run through
+// sandbox-exec with network denied (the Parakeet profile: writes only to the temp dir,
+// the private HOME and the per-user temp dir NSTemporaryDirectory uses).
+
+import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { createReadStream, existsSync, mkdtempSync, readdirSync, realpathSync, rmSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { Transform } from 'node:stream'
+import { fileURLToPath } from 'node:url'
+import { darwinUserTempDir, parakeetChildEnv, parakeetSandboxProfile } from './parakeet.js'
+import {
+  SHADOW_GATES, SHADOW_SAMPLE_RATE, buildShadowProposals, decide, nativeTurns,
+  type ShadowEmbeddingRow, type ShadowProposals,
+} from './speaker-shadow-decide.js'
+import { SHADOW_MODEL_REPO, SHADOW_MODEL_REVISION, prepareShadowHome, verifyShadowModels, type ShadowModelCheck } from './speaker-shadow-models.js'
+import {
+  ShadowInputError, buildShadowTimeline, pcm16WavFile, readShadowMeetingTitle, shadowEntries, shadowHumanProtectedVoices,
+  shadowLabelsHash, shadowProductionSegments,
+} from './speaker-shadow-timeline.js'
+import { renderShadowReport } from './speaker-shadow-report.js'
+import { pyRound } from './speaker-shadow-numeric.js'
+import { findShadowPairSource } from './speaker-shadow-pair-source.js'
+import { evaluatePairedSpeakerShadow, renderPairedSpeakerShadow, type PairedShadowReport } from './speaker-shadow-paired.js'
+import { beginMacSpeakerCallNative,retainMacSpeakerCallNative,type MacSpeakerCallProducerRequest,type MacSpeakerCallNativeRef } from './mac-speaker-call-producer-worker.js'
+
+export const SHADOW_TMP_PREFIX = 'cos-speaker-shadow-'
+/** The CLI's flags, verbatim from round3/propose.py (via scripts/guard.py). */
+export const SHADOW_CLI_FLAGS = ['--mode', 'offline', '--overlapping-segments'] as const
+
+export interface ShadowJob {
+  sessionId: string
+  sidecarPath: string
+  /** The retained chunk WAV directory (`<data>/meeting-audio/<session>`). */
+  audioDir: string
+  /** The labels hash recorded when the meeting finalized; a different one now means a person edited it. */
+  expectedLabelsHash: string | null
+  cliPath: string
+  /** SHA-256 the parent verified for cliPath; re-checked here before the run. */
+  cliSha256: string
+  sandboxExec: string
+  modelsDir: string
+  homeDir: string
+  tmpRoot: string
+  cliTimeoutMs: number
+  /** Separate default-off consumer, admitted independently from log-only shadow. */
+  callProducer?: MacSpeakerCallProducerRequest
+  shadowLogRequested?: boolean
+  callProducerSwapStart?:number
+}
+
+export type ShadowSkipReason =
+  | 'not_finalized' | 'labels_changed' | 'no_voices' | 'audio_missing' | 'audio_drift' | 'audio_format'
+  | 'bad_sidecar' | 'too_long' | 'models_missing' | 'models_mismatch' | 'cli_changed' | 'cli_lacks_flags'
+export type ShadowFailReason = 'cli_timeout' | 'cli_failed' | 'cli_unsupported' | 'bad_cli_output' | 'sandbox_unavailable' | 'internal'
+
+export interface ShadowRunFacts {
+  minutes: number
+  originals: number
+  verifiedAgainstSidecar: number
+  unhashedOriginals: number
+  unhashedWithText: number[]
+  timelinePCMSHA256: string
+  timelineWAVSHA256: string
+  labelsHash: string
+  clippedTurns: number
+  humanProtectedVoices: string[]
+  /**
+   * Empty `NSIRD_fluidaudiocli_*` OS temp dirs that appeared during the run and are still
+   * there. A cold CoreML cache leaves up to four (MPSGraph staging); warm runs leave none.
+   * Counted, never removed: the server cannot prove a dir in the shared temp folder is its own.
+   */
+  osTempDirsLeft: number
+  timing: { rebuildMs: number; nativeMs: number; totalMs: number }
+  tool: { cliSha256: string; flags: string[]; modelRepo: string; modelRevision: string; modelBytes: number }
+}
+
+export type ShadowJobOutcome =
+  | { status: 'proposed'; facts: ShadowRunFacts; proposals: ShadowProposals; paired?: PairedShadowReport & { pairSessionId?: string; pairSourceSha256?: string; discoveryReason: string }; report: { title: string; markdown: string };callProducerExport?:MacSpeakerCallNativeRef; callProducerFailure?:{stage:'retain';reason:string} }
+  | { status: 'skipped'; reason: ShadowSkipReason; detail: string }
+  | { status: 'failed'; reason: ShadowFailReason; detail: string }
+
+type SpawnLike = (command: string, args: string[], options: SpawnOptions) => ChildProcess
+
+export interface ShadowWorkerDeps {
+  spawn?: SpawnLike
+  now?: () => number
+  /** Aborts the CLI (the parent went away). */
+  signal?: AbortSignal
+  /** Tests only (the fake-CLI integration worker): real model bytes cannot be faked. */
+  verifyModels?: (dir: string) => Promise<ShadowModelCheck>
+}
+
+async function sha256File(path: string): Promise<string> {
+  const hash = createHash('sha256')
+  await pipeline(createReadStream(path), new Transform({ transform(chunk, _e, cb) { hash.update(chunk); cb(null) } }))
+  return hash.digest('hex')
+}
+
+/** The CLI flags shadow mode passes that are not in the binary's own strings. Read only. */
+export async function cliMissingFlags(cliPath: string, flags: readonly string[] = ['--export-embeddings', '--overlapping-segments']): Promise<string[]> {
+  const bytes = await readFile(cliPath)
+  return flags.filter(flag => bytes.indexOf(flag) < 0)
+}
+
+/** Foundation's item-replacement dirs for this CLI, in the per-user temp folder. Read only. */
+function nsirdDirs(): Set<string> {
+  const root = darwinUserTempDir()
+  if (!root) return new Set()
+  try { return new Set(readdirSync(join(root, 'TemporaryItems')).filter(name => name.startsWith('NSIRD_fluidaudiocli_'))) } catch { return new Set() }
+}
+
+const skip = (reason: ShadowSkipReason, detail: string): ShadowJobOutcome => ({ status: 'skipped', reason, detail })
+const fail = (reason: ShadowFailReason, detail: string): ShadowJobOutcome => ({ status: 'failed', reason, detail: detail.slice(0, 300) })
+
+function runCli(job: ShadowJob, wavPath: string, nativePath: string, embPath: string, work: string, deps: ShadowWorkerDeps): Promise<{ code: number | null; signal: NodeJS.Signals | null; stderr: string; timedOut: boolean;closed:boolean; error?: string }> {
+  const args = ['-p', parakeetSandboxProfile(work, job.homeDir), job.cliPath, 'process', wavPath, '--mode', 'offline', '--output', nativePath, '--overlapping-segments', '--export-embeddings', embPath]
+  return new Promise(resolvePromise => {
+    if(deps.signal?.aborted){resolvePromise({code:null,signal:null,stderr:'',timedOut:false,closed:false,error:'cancelled before native admission'});return}
+    const deadline=Date.now()+job.cliTimeoutMs
+    let child: ChildProcess
+    try {
+      child = (deps.spawn ?? (spawn as unknown as SpawnLike))(job.sandboxExec, args, { stdio: ['ignore', 'ignore', 'pipe'], env: {...parakeetChildEnv(job.homeDir, work),...(job.callProducer?{OMP_NUM_THREADS:'1',VECLIB_MAXIMUM_THREADS:'1',OPENBLAS_NUM_THREADS:'1'}:{})} })
+    } catch (error) {
+      resolvePromise({ code: null, signal: null, stderr: '', timedOut: false,closed:false, error: error instanceof Error ? error.message : String(error) })
+      return
+    }
+    let stderr = '', timedOut = false, settled = false, childError:string|undefined
+    const done = (value: Parameters<typeof resolvePromise>[0]) => { if (settled) return; settled = true; clearTimeout(timer); deps.signal?.removeEventListener('abort', onAbort); resolvePromise(value) }
+    const kill = () => { try { child.kill('SIGKILL') } catch { /* gone */ } }
+    // SIGKILL: CoreML work does not stop for TERM.
+    const timer = setTimeout(() => { timedOut = true; kill() }, job.cliTimeoutMs)
+    const onAbort = () => kill()
+    deps.signal?.addEventListener('abort', onAbort, { once: true })
+    child.stderr?.on('data', (d: Buffer) => { if (stderr.length < 65_536) stderr += d.toString() })
+    child.on('error', error => {childError=error.message;if(!child.pid)done({ code: null, signal: null, stderr, timedOut,closed:false, error: error.message });else kill()})
+    child.on('close', (code, signal) => done({ code, signal, stderr, timedOut:timedOut||Date.now()>deadline,closed:true,error:childError }))
+  })
+}
+
+/** One meeting. Never throws: every path ends in an outcome, and the temp dir is always removed. */
+export async function runShadowJob(job: ShadowJob, deps: ShadowWorkerDeps = {}): Promise<ShadowJobOutcome> {
+  const now = deps.now ?? Date.now
+  const started = now()
+  let work: string | null = null
+  try {
+    // 1. The finalized meeting, unchanged since it finalized.
+    let sidecar: Record<string, unknown>,sourceJSON:string
+    try { sourceJSON=await readFile(job.sidecarPath, 'utf8');sidecar = JSON.parse(sourceJSON) } catch { return skip('bad_sidecar', 'the sidecar is missing or unreadable') }
+    if (sidecar.sessionId !== job.sessionId) return skip('bad_sidecar', 'the sidecar belongs to another session')
+    if (sidecar.finalizationState !== 'complete') return skip('not_finalized', `finalizationState=${String(sidecar.finalizationState)}`)
+    const entries = shadowEntries(sidecar)
+    const labelsHash = shadowLabelsHash(entries)
+    if (job.expectedLabelsHash && labelsHash !== job.expectedLabelsHash) return skip('labels_changed', 'labels changed after the meeting finalized (a correction landed first)')
+    const missing = entries.filter(e => !existsSync(join(job.audioDir, `chunk_${String(e.chunkIndex).padStart(4, '0')}.wav`))).length
+    if (missing) return skip('audio_missing', `${missing} original chunk WAVs missing`)
+
+    // 2. Models and CLI, verified now rather than trusted from the scheduler's look.
+    const models = await (deps.verifyModels ?? verifyShadowModels)(job.modelsDir)
+    if (!models.ok) return skip(models.reason, models.detail)
+    if (!existsSync(job.cliPath) || await sha256File(job.cliPath) !== job.cliSha256) return skip('cli_changed', 'the FluidAudio CLI changed since it was verified')
+    // A build without these would fail every run and open the breaker; say so once instead.
+    const missingFlags = await cliMissingFlags(job.cliPath)
+    if (missingFlags.length) return skip('cli_lacks_flags', `the installed fluidaudiocli has no ${missingFlags.join(' or ')} (COS Control's signed helper has both)`)
+    if (!existsSync(job.sandboxExec)) return fail('sandbox_unavailable', 'sandbox-exec is missing, so the CLI cannot be proven offline and does not run')
+
+    // 3. The timeline, then the production segments on it.
+    const timeline = await buildShadowTimeline(entries, idx => join(job.audioDir, `chunk_${String(idx).padStart(4, '0')}.wav`))
+    const { segs, sources } = shadowProductionSegments(entries, timeline.rows, timeline.total)
+    if (!segs.length) return skip('no_voices', 'no production segments to compare')
+    const wav = pcm16WavFile(timeline.pcm)
+    const rebuildMs = now() - started
+
+    // The platform temp root may spell /private/var as /var. Pin the owned
+    // directory itself; retained-output readers keep their strict canonical path fence.
+    work = mkdtempSync(join(job.tmpRoot, SHADOW_TMP_PREFIX))
+    work = realpathSync(work)
+    const wavPath = join(work, 'timeline.wav'), nativePath = join(work, 'native.json'), embPath = join(work, 'embeddings.json')
+    await writeFile(wavPath, wav, { mode: 0o600, flag: 'wx' })
+    const timelineWAVSHA256 = createHash('sha256').update(wav).digest('hex')
+    prepareShadowHome(job.homeDir, models.dir)
+    let producerContext:ReturnType<typeof beginMacSpeakerCallNative>|null=null
+    if(job.callProducer){
+      try{producerContext=beginMacSpeakerCallNative(job.callProducer,{sourceJSON,audioDir:job.audioDir,cliPath:job.cliPath,modelsDir:models.dir,timeline:{rows:timeline.rows,total:timeline.total,pcmSHA256:timeline.pcmSHA256}})}
+      catch(error){if(job.shadowLogRequested===false)return skip('bad_sidecar',`independent consumer withheld: ${error instanceof Error?error.message:String(error)}`)}
+    }
+
+    // 4. One offline diarization.
+    const nativeStarted = now()
+    const nsirdBefore = nsirdDirs()
+    const run = await runCli(job, wavPath, nativePath, embPath, work, deps)
+    const nativeMs = now() - nativeStarted
+    const osTempDirsLeft = [...nsirdDirs()].filter(name => !nsirdBefore.has(name)).length
+    if (run.timedOut) return fail('cli_timeout', `no result within ${job.cliTimeoutMs} ms`)
+    if (run.error) return fail('cli_failed', `spawn: ${run.error}`)
+    const tail = run.stderr.trim().split('\n').slice(-2).join(' | ')
+    if (/Unknown option|unexpected argument|Unrecognized/i.test(run.stderr)) return fail('cli_unsupported', `the CLI rejected an option: ${tail}`)
+    if (run.code !== 0) return fail('cli_failed', `exit ${run.code ?? run.signal}: ${tail}`)
+
+    let native: { segments?: unknown }, emb: unknown
+    try {
+      native = JSON.parse(await readFile(nativePath, 'utf8'))
+      emb = JSON.parse(await readFile(embPath, 'utf8'))
+    } catch (error) { return fail('bad_cli_output', `unreadable output: ${error instanceof Error ? error.message : String(error)}`) }
+    if (!Array.isArray(native.segments) || !Array.isArray(emb)) return fail('bad_cli_output', 'the CLI output has no segments or embeddings')
+
+    // 5. The gates, exactly as the research tool applies them.
+    let proposals: ShadowProposals, clipped: number
+    let paired: Extract<ShadowJobOutcome, { status: 'proposed' }>['paired']
+    try {
+      const turns = nativeTurns(native.segments as Array<{ speakerId: unknown; startTimeSeconds: unknown; endTimeSeconds: unknown }>, timeline.total / SHADOW_SAMPLE_RATE)
+      clipped = turns.clipped
+      for (const row of emb as ShadowEmbeddingRow[]) {
+        if (!row || typeof row.startTime !== 'number' || typeof row.endTime !== 'number' || !Array.isArray(row.embedding256) || row.embedding256.length !== 256) throw new Error('bad embedding row')
+      }
+      const D = decide(segs, timeline.total, turns.turns, emb as ShadowEmbeddingRow[], SHADOW_GATES.floorSeconds, SHADOW_GATES.majority)
+      proposals = buildShadowProposals(D, segs, sources, turns.turns)
+      // Pair scoring is advisory; an unavailable G2 must not suppress the acoustic report.
+      try {
+        const source = await findShadowPairSource(job.sidecarPath, sidecar, timeline.total / SHADOW_SAMPLE_RATE * 1000)
+        paired = { ...evaluatePairedSpeakerShadow({ macStartTime: sidecar.startTime as number, totalSamples: timeline.total,
+          segments: segs, regularTurns: turns.turns, acceptedGroups: proposals.accepted,
+          voiceEvidence: [...proposals.accepted.flatMap(group => group.voices), ...proposals.rejected],
+          g2: source.g2, alignment: { status: source.status } }),
+          pairSessionId: source.sessionId, pairSourceSha256: source.sourceSha256, discoveryReason: source.reason }
+      } catch {
+        paired = { ...evaluatePairedSpeakerShadow({ macStartTime: sidecar.startTime as number, totalSamples: timeline.total,
+          segments: segs, regularTurns: turns.turns, acceptedGroups: proposals.accepted, voiceEvidence: [],
+          alignment: { status: 'unpaired' } }), discoveryReason: 'pair discovery or scoring unavailable' }
+      }
+    } catch (error) { return fail('bad_cli_output', error instanceof Error ? error.message : String(error)) }
+
+    const humanProtectedVoices = shadowHumanProtectedVoices(entries)
+    const facts: ShadowRunFacts = {
+      minutes: pyRound(timeline.total / SHADOW_SAMPLE_RATE / 60, 1),
+      originals: entries.length,
+      verifiedAgainstSidecar: timeline.verified,
+      unhashedOriginals: timeline.unhashed,
+      unhashedWithText: timeline.unhashedWithText,
+      timelinePCMSHA256: timeline.pcmSHA256,
+      timelineWAVSHA256,
+      labelsHash,
+      clippedTurns: clipped,
+      humanProtectedVoices,
+      osTempDirsLeft,
+      timing: { rebuildMs, nativeMs, totalMs: now() - started },
+      tool: { cliSha256: job.cliSha256, flags: [...SHADOW_CLI_FLAGS, '--export-embeddings'], modelRepo: SHADOW_MODEL_REPO, modelRevision: SHADOW_MODEL_REVISION, modelBytes: models.bytes },
+    }
+    const title = await readShadowMeetingTitle(job.sidecarPath)
+    const chunkText = new Map(entries.map(e => [e.chunkIndex, typeof e.chunk.text === 'string' ? e.chunk.text : '']))
+    let markdown = renderShadowReport({ title, sessionId: job.sessionId, proposals, facts, audioDir: job.audioDir, chunkText })
+    if (paired) markdown += `\n${renderPairedSpeakerShadow(paired)}\nDiscovery: ${paired.discoveryReason}\n`
+    let callProducerExport:MacSpeakerCallNativeRef|undefined
+    let callProducerFailure:Extract<ShadowJobOutcome,{status:'proposed'}>['callProducerFailure']
+    if(producerContext){try{callProducerExport=retainMacSpeakerCallNative(producerContext,{nativePath,embeddingPath:embPath,exitCode:run.code,closed:run.closed,networkDenied:true})}catch(error){callProducerFailure={stage:'retain',reason:(error instanceof Error?error.message:'native export retention failed').slice(0,200)}}}
+    return { status: 'proposed', proposals, paired, facts, report: { title, markdown },...(callProducerExport?{callProducerExport}:{}),...(callProducerFailure?{callProducerFailure}:{}) }
+  } catch (error) {
+    if (error instanceof ShadowInputError) return skip(error.reason, error.message)
+    return fail('internal', error instanceof Error ? error.message : String(error))
+  } finally {
+    if (work) { try { rmSync(work, { recursive: true, force: true }) } catch { /* best effort; swept at boot */ } }
+  }
+}
+
+// ── Child process entry ──────────────────────────────────────────────────────
+
+async function readStdin(limit = 64 * 1024): Promise<string> {
+  let text = ''
+  for await (const chunk of process.stdin) {
+    text += chunk.toString()
+    if (text.length > limit) throw new Error('job too large')
+  }
+  return text
+}
+
+/** The child's whole life: one job in on stdin, one outcome line out on stdout. */
+export async function workerMain(deps: Omit<ShadowWorkerDeps, 'signal'> = {}): Promise<void> {
+  const controller = new AbortController()
+  const parent = process.ppid
+  // A parent that died (or was SIGKILLed with its group spared) must not leave this running.
+  const watch = setInterval(() => { if (process.ppid !== parent) { controller.abort(); process.exit(3) } }, 1_000)
+  watch.unref()
+  let outcome: ShadowJobOutcome
+  try {
+    const job = JSON.parse(await readStdin()) as ShadowJob
+    outcome = await runShadowJob(job, { ...deps, signal: controller.signal })
+  } catch (error) {
+    outcome = fail('internal', error instanceof Error ? error.message : String(error))
+  }
+  process.stdout.write(`${JSON.stringify(outcome)}\n`, () => process.exit(0))
+}
+
+function isEntry(): boolean {
+  try { return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)) } catch { return false }
+}
+if (isEntry()) void workerMain()