@gotcos/glasses-server 6.12.5 → 6.12.6

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 6.12.6
+
+Pairs with COS Glasses build 222 to harden local-first meeting recovery and
+local Whisper supervision while preserving the existing public API surface.
+
+- **Meeting work stays on its admitting Mac.** Capability-aware clients pin
+  upload, status, and save requests to one `serverInstanceId`; a mismatch fails
+  before audio is consumed. Legacy unpinned clients continue to work.
+- **Receipt is not transcription.** Durable ledgers distinguish raw audio
+  receipt, completed ASR, and canonical transcript text. Silent chunks persist
+  as terminal empty completions, so replay does not rerun ASR or invent text.
+- **Whisper recovery is single-owner.** Concurrent start/restart requests are
+  serialized and coalesced. COS reaps only a process tree proven to own the
+  configured model and port 8178, verifies the port is clear, and launches one
+  replacement. An unrelated Whisper process is never killed; uncertain
+  ownership fails closed.
+- **Backward compatible.** Existing query, prompt recovery, media, display,
+  diagnostics, transcription, and legacy meeting contracts retain their prior
+  behavior. The new capability flags are additive.
+
 ## 6.12.5
 
 Extends the file-permission hardening to the remaining append-only logs that

package/package.json

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

package/server/lib/local-first-meetings-contract.ts

@@ -6,6 +6,10 @@ export interface LocalFirstMeetingsCapability {
   serverInstanceId: string
   idempotentSave: true
   sessionStatus: true
+  /** Capability-admitted clients pin every upload/status/save to one Mac. */
+  pinnedServerIdentity: true
+  /** Status and upload receipts distinguish raw receive, ASR completion, and canonical text. */
+  asrCompletionStatus: true
   retentionMs: number
 }
 
@@ -19,6 +23,8 @@ export function localFirstMeetingsCapability(serverInstanceId: string | null): L
     serverInstanceId,
     idempotentSave: true,
     sessionStatus: true,
+    pinnedServerIdentity: true,
+    asrCompletionStatus: true,
     retentionMs: LOCAL_FIRST_MEETING_IDLE_RETENTION_MS,
   }
 }

package/server/lib/whisper-local.ts

@@ -6,7 +6,8 @@
 //   2. whisper-cli (spawned per request, model loaded from disk) → ~500-700ms
 //   3. OpenAI API (cloud, handled by transcribe.ts) → ~1000-3000ms
 
-import { spawn, execSync } from 'node:child_process'
+import { spawn, execFileSync } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
 import { writeFileSync, unlinkSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
@@ -142,14 +143,171 @@ const WHISPER_SERVER_URL = `http://127.0.0.1:${WHISPER_SERVER_PORT}`
 let cliAvailable = false
 let serverAvailable = false
 let serverProcess: ReturnType<typeof spawn> | null = null
+const ownedServerChildren = new Set<ChildProcess>()
 
 // Circuit breaker: track consecutive server failures to detect hung process
 let serverConsecutiveFailures = 0
 const SERVER_FAILURE_THRESHOLD = 3   // After 3 consecutive failures, auto-restart
-let serverRestarting = false          // Prevents concurrent restart attempts
+let serverRestarting = false          // Exposed in the existing health shape
 let serverStarting = false            // Initial model load is not a circuit failure
+let serverStartPromise: Promise<void> | null = null
+let serverRestartPromise: Promise<WhisperRestartResult> | null = null
 let serverHealthProbe: Promise<boolean> | null = null
 
+interface ProcessEntry {
+  pid: number
+  ppid: number
+  command: string
+}
+
+export interface WhisperRestartResult {
+  status: 'recovered' | 'failed'
+  error?: string
+}
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+
+function listProcesses(): ProcessEntry[] {
+  // `command=` includes arguments, which lets us distinguish this COS-owned
+  // port/model signature from unrelated whisper-server instances.
+  const output = execFileSync('ps', ['-axww', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' })
+  return output.split('\n').flatMap(line => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/)
+    if (!match) return []
+    return [{ pid: Number(match[1]), ppid: Number(match[2]), command: match[3] }]
+  })
+}
+
+function listeningPids(): number[] {
+  try {
+    const output = execFileSync(
+      'lsof',
+      ['-nP', `-iTCP:${WHISPER_SERVER_PORT}`, '-sTCP:LISTEN', '-t'],
+      { encoding: 'utf8' },
+    )
+    return output.split(/\s+/).map(Number).filter(pid => Number.isInteger(pid) && pid > 0)
+  } catch (err: any) {
+    // lsof uses exit 1 for "no matches". Anything else means we could not
+    // prove the port state, so startup must fail closed.
+    if (err?.status === 1) return []
+    throw new Error(`unable to inspect whisper-server port ${WHISPER_SERVER_PORT}: ${err?.message ?? err}`)
+  }
+}
+
+function isCosWhisperServerCommand(command: string): boolean {
+  const executable = /(?:^|\s)(?:\S*\/)?whisper-server(?:\s|$)/.test(command)
+  const configuredPort = new RegExp(`(?:^|\\s)--port(?:=|\\s+)${WHISPER_SERVER_PORT}(?:\\s|$)`).test(command)
+  return executable && configuredPort && command.includes(MODEL_PATH)
+}
+
+function collectDescendants(processes: ProcessEntry[], roots: Iterable<number>): Set<number> {
+  const descendants = new Set<number>(roots)
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const entry of processes) {
+      if (!descendants.has(entry.pid) && descendants.has(entry.ppid)) {
+        descendants.add(entry.pid)
+        changed = true
+      }
+    }
+  }
+  return descendants
+}
+
+function signalPid(pid: number): void {
+  try {
+    process.kill(pid, 'SIGKILL')
+  } catch (err: any) {
+    if (err?.code !== 'ESRCH') throw err
+  }
+}
+
+async function waitForOwnedChildClose(child: ChildProcess, timeoutMs = 2_000): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return true
+  return new Promise(resolve => {
+    let settled = false
+    const finish = (closed: boolean) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeout)
+      child.off('close', onClose)
+      resolve(closed)
+    }
+    const onClose = () => finish(true)
+    const timeout = setTimeout(() => finish(false), timeoutMs)
+    child.once('close', onClose)
+  })
+}
+
+/**
+ * Kill every whisper-server we own or can identify as stale, plus all of its
+ * descendants. Direct children are awaited so Node reaps them before another
+ * model process is allowed to bind the port.
+ */
+async function killAndReapWhisperProcesses(): Promise<void> {
+  serverAvailable = false
+
+  for (let round = 0; round < 3; round++) {
+    const processes = listProcesses()
+    const ownedPids = [...ownedServerChildren]
+      .map(child => child.pid)
+      .filter((pid): pid is number => typeof pid === 'number')
+    const staleWhisperPids = processes
+      .filter(entry => isCosWhisperServerCommand(entry.command))
+      .map(entry => entry.pid)
+    const targets = collectDescendants(processes, [...ownedPids, ...staleWhisperPids])
+
+    if (targets.size === 0 && ownedServerChildren.size === 0) break
+
+    // Descendants first prevents a model worker from surviving its supervisor.
+    const depth = new Map<number, number>()
+    const byPid = new Map(processes.map(entry => [entry.pid, entry]))
+    const getDepth = (pid: number): number => {
+      if (depth.has(pid)) return depth.get(pid)!
+      const parent = byPid.get(pid)?.ppid
+      const value = parent && targets.has(parent) ? getDepth(parent) + 1 : 0
+      depth.set(pid, value)
+      return value
+    }
+    const orderedTargets = [...targets].sort((a, b) => getDepth(b) - getDepth(a))
+
+    for (const pid of orderedTargets) {
+      const ownedChild = [...ownedServerChildren].find(child => child.pid === pid)
+      if (ownedChild) {
+        try { ownedChild.kill('SIGKILL') } catch { /* already exited */ }
+      } else {
+        signalPid(pid)
+      }
+    }
+
+    const closeResults = await Promise.all([...ownedServerChildren].map(child => waitForOwnedChildClose(child)))
+    if (closeResults.some(closed => !closed)) {
+      throw new Error('owned whisper-server child did not exit after SIGKILL')
+    }
+    await sleep(50)
+  }
+
+  const remaining = listProcesses().filter(entry => isCosWhisperServerCommand(entry.command))
+  if (remaining.length > 0) {
+    throw new Error(`stale whisper-server process(es) remain: ${remaining.map(entry => entry.pid).join(', ')}`)
+  }
+
+  serverProcess = null
+}
+
+async function proveWhisperPortClear(): Promise<void> {
+  for (let attempt = 0; attempt < 20; attempt++) {
+    const pids = listeningPids()
+    if (pids.length === 0) return
+    if (attempt < 19) await sleep(250)
+  }
+  const pids = listeningPids()
+  throw new Error(
+    `whisper-server port ${WHISPER_SERVER_PORT} remains occupied${pids.length ? ` by PID(s) ${pids.join(', ')}` : ''}`,
+  )
+}
+
 // Check CLI availability at import time
 try {
   cliAvailable = existsSync(WHISPER_CLI) && existsSync(MODEL_PATH)
@@ -165,45 +323,38 @@ try {
  * Called from index.ts at server boot. Non-blocking.
  */
 export async function startWhisperServer(): Promise<void> {
-  if (serverStarting) return
+  if (serverRestartPromise) {
+    const result = await serverRestartPromise
+    if (result.status === 'failed') {
+      throw new Error(result.error ?? 'whisper-server restart failed')
+    }
+    return
+  }
+  if (serverStartPromise) return serverStartPromise
+  if (serverAvailable && serverProcess) return
+
   serverStarting = true
+  const operation = startWhisperServerAttempt()
+  serverStartPromise = operation
   try {
-    await startWhisperServerAttempt()
+    await operation
   } finally {
+    if (serverStartPromise === operation) serverStartPromise = null
     serverStarting = false
   }
 }
 
-async function startWhisperServerAttempt(): Promise<void> {
+async function startWhisperServerAttempt(preflightCompleted = false): Promise<void> {
   if (!existsSync(WHISPER_SERVER) || !existsSync(MODEL_PATH)) {
     console.log('[whisper-local] whisper-server or model not found — using CLI fallback')
     return
   }
 
-  // Check if already running
-  try {
-    const res = await fetch(`${WHISPER_SERVER_URL}/health`, { signal: AbortSignal.timeout(1000) })
-    if (res.ok) {
-      serverAvailable = true
-      console.log('[whisper-local] whisper-server already running on port', WHISPER_SERVER_PORT)
-      return
-    }
-  } catch {
-    // Not running — kill any zombie processes before starting fresh
-    try {
-      execSync('pkill -9 -f "whisper-server"', { stdio: 'ignore' })
-      console.log('[whisper-local] Killed stale whisper-server processes')
-    } catch { /* none running */ }
-
-    // Wait for port to actually clear (up to 5s)
-    for (let i = 0; i < 10; i++) {
-      try {
-        execSync('lsof -i :8178 -t', { stdio: 'ignore' })
-        await new Promise(r => setTimeout(r, 500))
-      } catch {
-        break // Port clear
-      }
-    }
+  // The API process is the sole Whisper owner. Never adopt an untracked daemon:
+  // reap stale trees, then prove the fixed local port is free before spawning.
+  if (!preflightCompleted) {
+    await killAndReapWhisperProcesses()
+    await proveWhisperPortClear()
   }
 
   // Assemble startup args. VAD only attaches if the ggml model is actually on
@@ -237,51 +388,61 @@ async function startWhisperServerAttempt(): Promise<void> {
 
   console.log('[whisper-local] Starting whisper-server...')
 
-  serverProcess = spawn(WHISPER_SERVER, serverArgs, {
+  const child = spawn(WHISPER_SERVER, serverArgs, {
     stdio: ['ignore', 'pipe', 'pipe'],
     detached: false,  // Dies with parent
   })
+  serverProcess = child
+  ownedServerChildren.add(child)
 
-  // Wait for server to be ready — poll /health every 2s (large models take ~20s to load)
-  return new Promise<void>((resolve) => {
-    const maxWaitMs = 45_000
-    const pollIntervalMs = 2_000
-    const startTime = Date.now()
-
-    const pollTimer = setInterval(async () => {
-      try {
-        const res = await fetch(`${WHISPER_SERVER_URL}/health`, { signal: AbortSignal.timeout(1000) })
-        if (res.ok) {
-          clearInterval(pollTimer)
-          serverAvailable = true
-          const loadTime = ((Date.now() - startTime) / 1000).toFixed(1)
-          console.log(`[whisper-local] whisper-server ready on port ${WHISPER_SERVER_PORT} (loaded in ${loadTime}s)`)
-          resolve()
-        }
-      } catch {
-        // Not ready yet — keep polling
-        if (Date.now() - startTime > maxWaitMs) {
-          clearInterval(pollTimer)
-          console.warn(`[whisper-local] whisper-server startup timeout (${maxWaitMs / 1000}s) — using CLI fallback`)
-          resolve()
-        }
-      }
-    }, pollIntervalMs)
-
-    serverProcess!.on('error', (err) => {
-      clearInterval(pollTimer)
-      console.error('[whisper-local] whisper-server failed to start:', err.message)
-      resolve()
-    })
+  child.once('close', (code) => {
+    ownedServerChildren.delete(child)
+    if (serverProcess !== child) return
+    serverAvailable = false
+    serverProcess = null
+    if (code !== null && code !== 0) {
+      console.warn(`[whisper-local] whisper-server exited with code ${code}`)
+    }
+  })
 
-    serverProcess!.on('close', (code) => {
-      serverAvailable = false
-      serverProcess = null
-      if (code !== null && code !== 0) {
-        console.warn(`[whisper-local] whisper-server exited with code ${code}`)
+  // Wait for server to be ready — poll /health every 2s (large models take ~20s to load).
+  // Polls are sequential, so a slow health request cannot overlap the next one.
+  const maxWaitMs = 45_000
+  const pollIntervalMs = 2_000
+  const startTime = Date.now()
+  let spawnError: Error | null = null
+  let childClosed = false
+  child.once('error', err => { spawnError = err })
+  child.once('close', () => { childClosed = true })
+
+  while (Date.now() - startTime <= maxWaitMs && !spawnError && !childClosed) {
+    try {
+      const res = await fetch(`${WHISPER_SERVER_URL}/health`, { signal: AbortSignal.timeout(1000) })
+      if (res.ok) {
+        serverAvailable = true
+        const loadTime = ((Date.now() - startTime) / 1000).toFixed(1)
+        console.log(`[whisper-local] whisper-server ready on port ${WHISPER_SERVER_PORT} (loaded in ${loadTime}s)`)
+        return
       }
-    })
-  })
+    } catch {
+      // Model is still loading.
+    }
+    if (!spawnError && !childClosed && Date.now() - startTime <= maxWaitMs) {
+      await sleep(pollIntervalMs)
+    }
+  }
+
+  // Event-listener assignment is opaque to TypeScript's control-flow analysis.
+  const caughtSpawnError = spawnError as Error | null
+  const failure = caughtSpawnError
+    ? `whisper-server failed to start: ${caughtSpawnError.message}`
+    : childClosed
+      ? 'whisper-server exited before becoming healthy'
+      : `whisper-server startup timeout (${maxWaitMs / 1000}s)`
+  console.error(`[whisper-local] ${failure} — reaping child and keeping local backend unavailable`)
+  await killAndReapWhisperProcesses()
+  await proveWhisperPortClear()
+  throw new Error(failure)
 }
 
 /**
@@ -671,7 +832,7 @@ export async function transcribeLocal(audioBuffer: Buffer, context?: string, isQ
       if (serverConsecutiveFailures >= SERVER_FAILURE_THRESHOLD && !serverRestarting) {
         console.error(`[whisper-local] ⚠ CIRCUIT BREAKER OPEN — ${serverConsecutiveFailures} consecutive failures. Auto-restarting server...`)
         // Non-blocking restart in background
-        restartWhisperServer()
+        void restartWhisperServer()
       } else if (serverConsecutiveFailures < SERVER_FAILURE_THRESHOLD) {
         console.warn(`[whisper-local] Server failed (${serverConsecutiveFailures}/${SERVER_FAILURE_THRESHOLD} before restart): ${err.message}`)
       }
@@ -687,7 +848,7 @@ export async function transcribeLocal(audioBuffer: Buffer, context?: string, isQ
   serverConsecutiveFailures++
   if (serverConsecutiveFailures >= SERVER_FAILURE_THRESHOLD && !serverRestarting) {
     console.error(`[whisper-local] CIRCUIT BREAKER OPEN — ${serverConsecutiveFailures} consecutive failures (server unavailable). Auto-restarting...`)
-    restartWhisperServer()
+    void restartWhisperServer()
   }
 
   // Throw so the caller applies the configured recovery policy. CLI is
@@ -700,48 +861,46 @@ export async function transcribeLocal(audioBuffer: Buffer, context?: string, isQ
  * Non-blocking — runs in background while callers preserve audio or apply the
  * explicitly configured fallback policy.
  */
-async function restartWhisperServer(): Promise<void> {
-  if (serverRestarting) return
-  serverRestarting = true
+export async function restartWhisperServer(): Promise<WhisperRestartResult> {
+  if (serverRestartPromise) return serverRestartPromise
 
-  try {
-    // Kill any existing server process
-    if (serverProcess) {
-      try { serverProcess.kill('SIGKILL') } catch {}
-      serverProcess = null
-    }
-    // Also kill any zombie processes
+  serverRestarting = true
+  const priorStart = serverStartPromise
+  const operation = (async (): Promise<WhisperRestartResult> => {
     try {
-      execSync('pkill -9 -f "whisper-server"', { stdio: 'ignore' })
-    } catch { /* none running */ }
-
-    // Wait for port to clear
-    for (let i = 0; i < 6; i++) {
-      try {
-        execSync('lsof -i :8178 -t', { stdio: 'ignore' })
-        await new Promise(r => setTimeout(r, 500))
-      } catch {
-        break
+      // A restart requested during model load runs immediately after that single
+      // start attempt completes, then owns the lifecycle until recovery finishes.
+      if (priorStart) {
+        try { await priorStart } catch { /* restart performs its own clean recovery */ }
       }
-    }
 
-    console.log('[whisper-local] Restarting whisper-server (model load ~20s)...')
-    await startWhisperServer()
+      await killAndReapWhisperProcesses()
+      await proveWhisperPortClear()
 
-    if (serverAvailable) {
+      console.log('[whisper-local] Restarting whisper-server (model load ~20s)...')
+      await startWhisperServerAttempt(true)
+      if (!serverAvailable) {
+        throw new Error('whisper-server did not become healthy')
+      }
       serverConsecutiveFailures = 0
       console.log('[whisper-local] Server restarted successfully — circuit breaker CLOSED')
-    } else {
-      // Reset counter so the next N failures can trigger another restart attempt
-      // Without this, the counter stays >= threshold but serverRestarting is false,
-      // so every subsequent call would re-trigger restart in a tight loop
+      return { status: 'recovered' }
+    } catch (err: any) {
+      serverAvailable = false
+      // Preserve the existing retry cadence: one failed recovery consumes this
+      // breaker cycle, and the next three failed calls may request one new cycle.
       serverConsecutiveFailures = 0
-      console.error('[whisper-local] Server restart failed — reset counter, will retry after next 3 failures. Caller recovery policy remains active.')
+      const message = err?.message ?? String(err)
+      console.error(`[whisper-local] Server restart error: ${message} — will retry after next 3 failures`)
+      return { status: 'failed', error: message }
     }
-  } catch (err: any) {
-    serverConsecutiveFailures = 0  // Same reset — allow future retry cycle
-    console.error(`[whisper-local] Server restart error: ${err.message} — will retry after next 3 failures`)
+  })()
+
+  serverRestartPromise = operation
+  try {
+    return await operation
   } finally {
+    if (serverRestartPromise === operation) serverRestartPromise = null
     serverRestarting = false
   }
 }

package/server/routes/meeting.ts

@@ -120,6 +120,16 @@ function publicSaveResponse(saved: SavedMeeting, replayed = false): Record<strin
   }
 }
 
+function suppliedServerPin(
+  req: { get: (name: string) => string | undefined },
+  fallback: unknown,
+): string | null {
+  const header = req.get('X-COS-Server-Instance')?.trim() ?? ''
+  const secondary = typeof fallback === 'string' ? fallback.trim() : ''
+  if (header && secondary && header !== secondary) return '__conflict__'
+  return header || secondary || null
+}
+
 export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router {
   const store = deps.store ?? getMeetingStore()
   const sessions = deps.sessions ?? defaultSessionSource
@@ -140,6 +150,11 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       res.status(503).json({ error: 'Server identity unavailable', reason: 'server_identity_unavailable' })
       return
     }
+    const pin = suppliedServerPin(req, req.query.serverInstanceId)
+    if (pin && pin !== serverInstanceId) {
+      res.status(409).json({ error: 'Server identity mismatch', reason: 'server_instance_mismatch' })
+      return
+    }
     const saved = store.findBySessionId(sessionId)
     const live = getMeetingSessionStatus(sessionId)
     res.set('Cache-Control', 'private, no-store')
@@ -149,6 +164,10 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       serverInstanceId,
       receivedRanges: live.receivedRanges,
       receivedCount: live.receivedCount,
+      asrCompletedRanges: live.asrCompletedRanges,
+      asrCompletedCount: live.asrCompletedCount,
+      canonicalRanges: live.canonicalRanges,
+      canonicalCount: live.canonicalCount,
       maxChunkIndex: live.maxChunkIndex,
       lastActivityAt: live.lastActivityAt,
       retainedUntil: saved ? null : live.retainedUntil,
@@ -177,6 +196,16 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
         res.status(400).json({ error: 'Invalid domain', reason: 'invalid_domain' })
         return
       }
+      const serverInstanceId = getServerInstanceId()
+      if (!serverInstanceId) {
+        res.status(503).json({ error: 'Server identity unavailable', reason: 'server_identity_unavailable' })
+        return
+      }
+      const pin = suppliedServerPin(req, body?.serverInstanceId)
+      if (pin && pin !== serverInstanceId) {
+        res.status(409).json({ error: 'Server identity mismatch', reason: 'server_instance_mismatch' })
+        return
+      }
 
       // A response can be lost after both durable files were committed. Find
       // the sidecar by session ID so client retry/restart is idempotent.

package/server/routes/transcribe-stream.ts

@@ -42,6 +42,7 @@ import {
   retainedUntilIso,
   type IndexRange,
 } from '../lib/local-first-meetings-contract.js'
+import { getServerInstanceId } from '../lib/server-instance-id.js'
 
 function ensurePrivateDirectory(path: string): void {
   if (!existsSync(path)) mkdirSync(path, { recursive: true, mode: 0o700 })
@@ -209,6 +210,10 @@ interface TranscriptSession {
   // never arrived = a chunk lost in transit) is the only thing flagged as a gap.
   // Sorted, de-duplicated. See computeGapReport()/analyzeTranscriptGaps().
   receivedIndices?: number[]
+  /** Durable ASR terminal outcomes. Raw receive alone never implies completion. */
+  asrCompletedIndices?: number[]
+  /** Exact replay records for silent/filtered ASR completions. */
+  emptyCompletions?: Record<string, EmptyTranscriptCompletion>
   maxChunkIndex?: number
   /** Persisted idle-retention clock. Meeting date/duration still use startTime. */
   lastActivityAt: number
@@ -226,10 +231,37 @@ interface ClosedTranscriptSession {
   closedAt: number
   lastActivityAt: number
   receivedIndices: number[]
+  asrCompletedIndices: number[]
+  canonicalIndices: number[]
   maxChunkIndex: number
   reason: 'saved' | 'expired' | 'closed'
 }
 
+interface EmptyTranscriptCompletion {
+  text: ''
+  speaker: string
+  elapsed: number
+  backend?: string
+  asrProvider?: string
+  fallbackReason?: string
+  audioSha256?: string
+  canonical: false
+}
+
+interface StreamChunkCompletionResponse {
+  text: string
+  speaker: string
+  chunkIndex: number
+  elapsed: number
+  sessionId: string
+  serverInstanceId: string
+  asrCompleted: true
+  canonical: boolean
+  backend?: string
+  asrProvider?: string
+  fallbackReason?: string
+}
+
 const closedSessionRecords = new Map<string, ClosedTranscriptSession>()
 
 // Incremental chunk persistence — survive server restarts
@@ -249,6 +281,8 @@ function readClosedSessions(): Record<string, ClosedTranscriptSession> {
           closedAt: value,
           lastActivityAt: value,
           receivedIndices: [],
+          asrCompletedIndices: [],
+          canonicalIndices: [],
           maxChunkIndex: -1,
           reason: 'closed',
         }
@@ -269,8 +303,26 @@ function readClosedSessions(): Record<string, ClosedTranscriptSession> {
       const maxChunkIndex = typeof raw.maxChunkIndex === 'number' && Number.isInteger(raw.maxChunkIndex)
         ? raw.maxChunkIndex
         : (receivedIndices.at(-1) ?? -1)
+      const asrCompletedIndices = Array.isArray(raw.asrCompletedIndices)
+        ? Array.from(new Set(raw.asrCompletedIndices.filter(
+          (entry): entry is number => Number.isInteger(entry) && (entry as number) >= 0,
+        ))).sort((a, b) => a - b)
+        : []
+      const canonicalIndices = Array.isArray(raw.canonicalIndices)
+        ? Array.from(new Set(raw.canonicalIndices.filter(
+          (entry): entry is number => Number.isInteger(entry) && (entry as number) >= 0,
+        ))).sort((a, b) => a - b)
+        : []
       const reason = raw.reason === 'saved' || raw.reason === 'expired' ? raw.reason : 'closed'
-      normalized[id] = { closedAt, lastActivityAt, receivedIndices, maxChunkIndex, reason }
+      normalized[id] = {
+        closedAt,
+        lastActivityAt,
+        receivedIndices,
+        asrCompletedIndices,
+        canonicalIndices,
+        maxChunkIndex,
+        reason,
+      }
     }
     return normalized
   } catch {
@@ -289,6 +341,8 @@ function persistClosedSessions(): void {
       closedAt: now,
       lastActivityAt: now,
       receivedIndices: [],
+      asrCompletedIndices: [],
+      canonicalIndices: [],
       maxChunkIndex: -1,
       reason: 'closed',
     }
@@ -345,6 +399,8 @@ function persistSessionRequired(sessionId: string): void {
       chunks: chunksIndexed.map(e => e.c),
       chunksIndexed,
       receivedIndices: session.receivedIndices ?? [],
+      asrCompletedIndices: session.asrCompletedIndices ?? [],
+      emptyCompletions: session.emptyCompletions ?? {},
       maxChunkIndex: session.maxChunkIndex ?? -1,
       providerCandidates: session.providerCandidates ?? {},
     })
@@ -387,10 +443,10 @@ function recoverSessions(): void {
             const chunks: TranscriptChunk[] = []
             if (indexed) {
               for (const e of indexed) {
-                if (e && Number.isInteger(e.i) && e.i >= 0 && e.c) chunks[e.i] = e.c
+                if (e && Number.isInteger(e.i) && e.i >= 0 && e.c) chunks[e.i] = { ...e.c, canonical: true }
               }
             } else if (legacy) {
-              for (let k = 0; k < legacy.length; k++) if (legacy[k]) chunks[k] = legacy[k]
+              for (let k = 0; k < legacy.length; k++) if (legacy[k]) chunks[k] = { ...legacy[k], canonical: true }
             }
             // Restore the received-index ledger. A legacy file (pre-feature)
             // has no ledger and no way to know whether a chunk was truly lost,
@@ -415,12 +471,36 @@ function recoverSessions(): void {
               for (let k = 0; k <= maxStored; k++) receivedIndices.push(k)
               maxChunkIndex = maxStored
             }
+            const emptyCompletions: Record<string, EmptyTranscriptCompletion> = {}
+            if (data.emptyCompletions && typeof data.emptyCompletions === 'object') {
+              for (const [key, value] of Object.entries(data.emptyCompletions as Record<string, unknown>)) {
+                if (!/^\d+$/.test(key) || !value || typeof value !== 'object') continue
+                const item = value as Partial<EmptyTranscriptCompletion>
+                if (item.text !== '' || typeof item.speaker !== 'string' || typeof item.elapsed !== 'number') continue
+                emptyCompletions[key] = { ...item, text: '', canonical: false } as EmptyTranscriptCompletion
+              }
+            }
+            const canonical: number[] = []
+            for (let k = 0; k < chunks.length; k++) if (chunks[k]?.text) canonical.push(k)
+            const asrCompletedIndices = Array.isArray(data.asrCompletedIndices)
+              ? Array.from(new Set(
+                (data.asrCompletedIndices as unknown[]).filter(
+                  (n): n is number => Number.isInteger(n) && (n as number) >= 0,
+                ),
+              )).sort((a, b) => a - b)
+              : []
+            // Canonical chunks and durable empty completion records are always
+            // terminal ASR outcomes. Never infer completion from raw receive.
+            for (const index of canonical) insertSortedUnique(asrCompletedIndices, index)
+            for (const key of Object.keys(emptyCompletions)) insertSortedUnique(asrCompletedIndices, Number(key))
             const session: TranscriptSession = {
               chunks,
               startTime: data.startTime,
               title: data.title || '',
               lastActivityAt,
               receivedIndices,
+              asrCompletedIndices,
+              emptyCompletions,
               maxChunkIndex,
               providerCandidates: data.providerCandidates && typeof data.providerCandidates === 'object'
                 ? data.providerCandidates
@@ -464,10 +544,23 @@ function recoverSessions(): void {
             const maxChunkIndex = typeof data.maxChunkIndex === 'number' && Number.isInteger(data.maxChunkIndex)
               ? data.maxChunkIndex
               : (receivedIndices.at(-1) ?? -1)
+            const canonicalIndices = Array.isArray(data.chunksIndexed)
+              ? (data.chunksIndexed as Array<{ i?: unknown; c?: TranscriptChunk }>)
+                .filter(entry => Number.isInteger(entry?.i) && (entry.i as number) >= 0 && entry.c?.text)
+                .map(entry => entry.i as number)
+              : []
+            const asrCompletedIndices = Array.isArray(data.asrCompletedIndices)
+              ? Array.from(new Set((data.asrCompletedIndices as unknown[]).filter(
+                (value): value is number => Number.isInteger(value) && (value as number) >= 0,
+              ))).sort((left, right) => left - right)
+              : [...canonicalIndices]
+            for (const index of canonicalIndices) insertSortedUnique(asrCompletedIndices, index)
             closedSessionRecords.set(data.sessionId, {
               closedAt: Date.now(),
               lastActivityAt,
               receivedIndices,
+              asrCompletedIndices,
+              canonicalIndices,
               maxChunkIndex,
               reason: 'expired',
             })
@@ -580,10 +673,22 @@ export function getSession(sessionId: string): TranscriptSession {
   let session = sessions.get(sessionId)
   if (!session) {
     const now = Date.now()
-    session = { chunks: [], startTime: now, lastActivityAt: now, title: '', providerCandidates: {} }
+    session = {
+      chunks: [],
+      startTime: now,
+      lastActivityAt: now,
+      title: '',
+      providerCandidates: {},
+      receivedIndices: [],
+      asrCompletedIndices: [],
+      emptyCompletions: {},
+    }
     sessions.set(sessionId, session)
   }
   if (!session.providerCandidates) session.providerCandidates = {}
+  if (!session.receivedIndices) session.receivedIndices = []
+  if (!session.asrCompletedIndices) session.asrCompletedIndices = []
+  if (!session.emptyCompletions) session.emptyCompletions = {}
   return session
 }
 
@@ -616,6 +721,20 @@ function recordReceivedChunk(session: TranscriptSession, chunkIndex: number): vo
   }
 }
 
+function recordAsrCompleted(session: TranscriptSession, chunkIndex: number): void {
+  if (!Number.isInteger(chunkIndex) || chunkIndex < 0) return
+  if (!session.asrCompletedIndices) session.asrCompletedIndices = []
+  insertSortedUnique(session.asrCompletedIndices, chunkIndex)
+}
+
+function canonicalIndices(session: TranscriptSession): number[] {
+  const result: number[] = []
+  for (let index = 0; index < session.chunks.length; index++) {
+    if (session.chunks[index]?.text) result.push(index)
+  }
+  return result
+}
+
 export interface TranscriptGapReport {
   received: number          // distinct chunk indices the server got
   stored: number            // chunks that survived filtering (have text)
@@ -768,6 +887,10 @@ export interface MeetingSessionStatusSnapshot {
   state: 'active' | 'closed' | 'missing'
   receivedRanges: IndexRange[]
   receivedCount: number
+  asrCompletedRanges: IndexRange[]
+  asrCompletedCount: number
+  canonicalRanges: IndexRange[]
+  canonicalCount: number
   maxChunkIndex: number
   lastActivityAt: string | null
   retainedUntil: string | null
@@ -777,10 +900,16 @@ export function getMeetingSessionStatus(sessionId: string): MeetingSessionStatus
   const active = sessions.get(sessionId)
   if (active) {
     const received = active.receivedIndices ?? []
+    const asrCompleted = active.asrCompletedIndices ?? []
+    const canonical = canonicalIndices(active)
     return {
       state: 'active',
       receivedRanges: compressIndexRanges(received),
       receivedCount: received.length,
+      asrCompletedRanges: compressIndexRanges(asrCompleted),
+      asrCompletedCount: asrCompleted.length,
+      canonicalRanges: compressIndexRanges(canonical),
+      canonicalCount: canonical.length,
       maxChunkIndex: active.maxChunkIndex ?? (received.at(-1) ?? -1),
       lastActivityAt: new Date(active.lastActivityAt).toISOString(),
       retainedUntil: retainedUntilIso(active.lastActivityAt),
@@ -792,6 +921,10 @@ export function getMeetingSessionStatus(sessionId: string): MeetingSessionStatus
       state: 'closed',
       receivedRanges: compressIndexRanges(closed.receivedIndices),
       receivedCount: closed.receivedIndices.length,
+      asrCompletedRanges: compressIndexRanges(closed.asrCompletedIndices),
+      asrCompletedCount: closed.asrCompletedIndices.length,
+      canonicalRanges: compressIndexRanges(closed.canonicalIndices),
+      canonicalCount: closed.canonicalIndices.length,
       maxChunkIndex: closed.maxChunkIndex,
       lastActivityAt: new Date(closed.lastActivityAt).toISOString(),
       retainedUntil: new Date(closed.closedAt + CLOSED_SESSION_TTL_MS).toISOString(),
@@ -801,6 +934,10 @@ export function getMeetingSessionStatus(sessionId: string): MeetingSessionStatus
     state: 'missing',
     receivedRanges: [],
     receivedCount: 0,
+    asrCompletedRanges: [],
+    asrCompletedCount: 0,
+    canonicalRanges: [],
+    canonicalCount: 0,
     maxChunkIndex: -1,
     lastActivityAt: null,
     retainedUntil: null,
@@ -815,11 +952,15 @@ function closeTranscriptSession(
   const session = sessions.get(sessionId)
   const now = Date.now()
   const receivedIndices = [...(session?.receivedIndices ?? [])]
+  const asrCompletedIndices = [...(session?.asrCompletedIndices ?? [])]
+  const canonical = session ? canonicalIndices(session) : []
   const maxChunkIndex = session?.maxChunkIndex ?? (receivedIndices.at(-1) ?? -1)
   closedSessionRecords.set(sessionId, {
     closedAt: now,
     lastActivityAt: session?.lastActivityAt ?? now,
     receivedIndices,
+    asrCompletedIndices,
+    canonicalIndices: canonical,
     maxChunkIndex,
     reason,
   })
@@ -866,6 +1007,23 @@ function makeHttpError(status: number, message: string, reason?: string): Error
   return err
 }
 
+function assertPinnedServerIdentity(headerValue: unknown, queryValue: unknown): string {
+  const headerPin = typeof headerValue === 'string' ? headerValue.trim() : ''
+  const queryPin = typeof queryValue === 'string' ? queryValue.trim() : ''
+  if (headerPin && queryPin && headerPin !== queryPin) {
+    throw makeHttpError(409, 'conflicting server identity pins', 'server_instance_mismatch')
+  }
+  const supplied = headerPin || queryPin
+  const serverInstanceId = getServerInstanceId()
+  // Omission is the legacy route contract. Capability-admitted clients pin.
+  if (!supplied) return serverInstanceId ?? ''
+  if (!serverInstanceId) throw makeHttpError(503, 'server identity unavailable', 'server_identity_unavailable')
+  if (supplied !== serverInstanceId) {
+    throw makeHttpError(409, 'server identity mismatch', 'server_instance_mismatch')
+  }
+  return serverInstanceId
+}
+
 function validateSessionId(sessionId: string): void {
   if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) {
     throw makeHttpError(400, 'invalid sessionId', 'invalid_session_id')
@@ -1033,19 +1191,39 @@ function canonicalChunkResponse(
   existing: TranscriptChunk,
   sessionId: string,
   chunkIndex: number,
-): { text: string; speaker: string; chunkIndex: number; elapsed: number; sessionId: string; backend?: string; asrProvider?: string; fallbackReason?: string } {
+): StreamChunkCompletionResponse {
+  const serverInstanceId = getServerInstanceId() ?? ''
   return {
     text: existing.text,
     speaker: existing.speaker,
     chunkIndex,
     elapsed: existing.elapsed,
     sessionId,
+    serverInstanceId,
+    asrCompleted: true,
+    canonical: true,
     backend: existing.backend,
     asrProvider: existing.asrProvider,
     fallbackReason: existing.fallbackReason,
   }
 }
 
+function emptyChunkResponse(
+  existing: EmptyTranscriptCompletion,
+  sessionId: string,
+  chunkIndex: number,
+): StreamChunkCompletionResponse {
+  const serverInstanceId = getServerInstanceId() ?? ''
+  return {
+    ...existing,
+    chunkIndex,
+    sessionId,
+    serverInstanceId,
+    asrCompleted: true,
+    canonical: false,
+  }
+}
+
 async function transcribeWithServerWhisper(audioBuffer: Buffer, whisperAudio: Buffer, whisperContext: string, isQuiet: boolean): Promise<{ text: string; words?: WhisperWord[]; backend: string }> {
   // The worker owns reconciliation of stale health. Always attempt local ASR
   // once; an availability snapshot must not divert meeting audio to cloud.
@@ -1152,7 +1330,7 @@ async function processStreamChunk(opts: {
   clientElapsed?: number
   /** Original client recording start, applied only before canonical chunks. */
   startTimeOverride?: number
-}): Promise<{ text: string; speaker: string; chunkIndex: number; elapsed: number; sessionId: string; backend?: string; asrProvider?: string; fallbackReason?: string }> {
+}): Promise<StreamChunkCompletionResponse> {
   const { sessionId, chunkIndex, clientSpeaker, audioBuffer, candidate } = opts
   const tReq = performance.now()
   validateSessionId(sessionId)
@@ -1166,6 +1344,7 @@ async function processStreamChunk(opts: {
     session.startTime = opts.startTimeOverride
   }
   const alreadyCanonical = session.chunks[chunkIndex]
+  const alreadyEmpty = session.emptyCompletions?.[String(chunkIndex)]
 
   let candidateRecordKey: string | undefined
   if (candidate) {
@@ -1186,9 +1365,10 @@ async function processStreamChunk(opts: {
 
   // Do not let late duplicate/replayed candidates replace canonical raw audio.
   // Batch re-transcription relies on chunk_000N.wav matching the accepted chunk.
-  if (alreadyCanonical?.canonical) {
+  if (alreadyCanonical?.text) {
     session.lastActivityAt = Date.now()
     recordReceivedChunk(session, chunkIndex)
+    recordAsrCompleted(session, chunkIndex)
     if (candidate && candidateRecordKey) {
       session.providerCandidates![candidateRecordKey].accepted =
         alreadyCanonical.asrProvider === 'iphone-whisperkit-beta' && alreadyCanonical.audioSha256 === audioSha256
@@ -1198,6 +1378,13 @@ async function processStreamChunk(opts: {
     persistSessionRequired(sessionId)
     return canonicalChunkResponse(alreadyCanonical, sessionId, chunkIndex)
   }
+  if (alreadyEmpty) {
+    session.lastActivityAt = Date.now()
+    recordReceivedChunk(session, chunkIndex)
+    recordAsrCompleted(session, chunkIndex)
+    persistSessionRequired(sessionId)
+    return emptyChunkResponse(alreadyEmpty, sessionId, chunkIndex)
+  }
 
   await persistRawSessionAudioChunk(sessionId, chunkIndex, audioBuffer)
   // Commit the received-index ledger only after the canonical raw WAV is
@@ -1276,8 +1463,21 @@ async function processStreamChunk(opts: {
       session.providerCandidates[candidateRecordKey].accepted = false
       session.providerCandidates[candidateRecordKey].fallbackReason = sanitized.fallbackReason || fallbackReason || 'empty'
     }
+    const emptyCompletion: EmptyTranscriptCompletion = {
+      text: '',
+      speaker: clientSpeaker,
+      elapsed,
+      backend,
+      asrProvider,
+      fallbackReason: sanitized.fallbackReason || fallbackReason,
+      audioSha256,
+      canonical: false,
+    }
+    session.emptyCompletions ??= {}
+    session.emptyCompletions[String(chunkIndex)] = emptyCompletion
+    recordAsrCompleted(session, chunkIndex)
     persistSessionRequired(sessionId)
-    return { text: '', speaker: clientSpeaker, chunkIndex, elapsed, sessionId, backend, asrProvider, fallbackReason: sanitized.fallbackReason || fallbackReason }
+    return emptyChunkResponse(emptyCompletion, sessionId, chunkIndex)
   }
 
   const chunk: TranscriptChunk = {
@@ -1296,7 +1496,7 @@ async function processStreamChunk(opts: {
     canonical: true,
   }
   const finalExisting = session.chunks[chunkIndex]
-  if (finalExisting?.canonical) {
+  if (finalExisting?.text) {
     if (candidate && candidateRecordKey && session.providerCandidates?.[candidateRecordKey]) {
       session.providerCandidates[candidateRecordKey].accepted =
         finalExisting.asrProvider === 'iphone-whisperkit-beta' && finalExisting.audioSha256 === audioSha256
@@ -1304,10 +1504,12 @@ async function processStreamChunk(opts: {
         session.providerCandidates[candidateRecordKey].accepted ? undefined : 'canonical_exists'
     }
     session.lastActivityAt = Date.now()
+    recordAsrCompleted(session, chunkIndex)
     persistSessionRequired(sessionId)
     return canonicalChunkResponse(finalExisting, sessionId, chunkIndex)
   }
   session.chunks[chunkIndex] = chunk
+  recordAsrCompleted(session, chunkIndex)
   if (candidate && candidateRecordKey) {
     if (session.providerCandidates?.[candidateRecordKey]) {
       session.providerCandidates[candidateRecordKey].accepted = asrProvider === 'iphone-whisperkit-beta'
@@ -1322,7 +1524,7 @@ async function processStreamChunk(opts: {
   emitDisplay({ type: 'transcript_chunk', data: { text: trimmedText, speaker, chunkIndex, elapsed, sessionId } })
 
   console.log(`[perf] TOTAL request: ${(performance.now() - tReq).toFixed(1)}ms | chunk #${chunkIndex} | ${audioBuffer.length}b | rms=${Math.round(rms)} q=${isQuiet ? 1 : 0} | ${asrProvider} | "${trimmedText.slice(0, 50)}"`)
-  return { text: trimmedText, speaker, chunkIndex, elapsed, sessionId, backend, asrProvider, fallbackReason }
+  return canonicalChunkResponse(chunk, sessionId, chunkIndex)
 }
 
 function sendStreamError(res: { status: (code: number) => { json: (body: unknown) => unknown } }, err: unknown): unknown {
@@ -1349,6 +1551,8 @@ function sendStreamError(res: { status: (code: number) => { json: (body: unknown
 
 transcribeStreamRouter.post('/transcribe-stream', async (req, res) => {
   try {
+    // Reject a wrong Mac before consuming or persisting any upload bytes.
+    assertPinnedServerIdentity(req.get('X-COS-Server-Instance'), req.query.serverInstanceId)
     const sessionId = (req.query.sessionId as string) || `g2_${Date.now()}`
     const chunkIndex = parseInt((req.query.chunkIndex as string) || '0', 10)
     const clientSpeaker = (req.query.speaker as string) || 'Unknown'