@gotcos/glasses-server 6.21.7 → 6.21.9

package/server/lib/meeting-finalization-jobs.ts

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+const JOB_NAME = /^[A-Za-z0-9:_-]{3,96}\.json$/
+
+export interface MeetingFinalizationJob {
+  schemaVersion: 1
+  sessionId: string
+  meetingPath: string
+  sidecarPath: string
+  audioDir: string | null
+  streamingWordCount: number
+  phase: 'capture_pending' | 'batch_pending' | 'ops_pending'
+  claimPending: boolean
+  createdAt: string
+  updatedAt: string
+  lastError?: string
+}
+
+function contained(parent: string, child: string): boolean {
+  return child === parent || child.startsWith(`${parent}${sep}`)
+}
+
+function validJob(raw: unknown): raw is MeetingFinalizationJob {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false
+  const job = raw as Partial<MeetingFinalizationJob>
+  return job.schemaVersion === 1
+    && typeof job.sessionId === 'string'
+    && /^[A-Za-z0-9:_-]{3,96}$/.test(job.sessionId)
+    && typeof job.meetingPath === 'string'
+    && typeof job.sidecarPath === 'string'
+    && (job.audioDir === null || typeof job.audioDir === 'string')
+    && typeof job.streamingWordCount === 'number'
+    && Number.isFinite(job.streamingWordCount)
+    && (job.phase === 'capture_pending' || job.phase === 'batch_pending' || job.phase === 'ops_pending')
+    && (job.claimPending === undefined || typeof job.claimPending === 'boolean')
+    && typeof job.createdAt === 'string'
+    && typeof job.updatedAt === 'string'
+}
+
+/** Durable replay ledger for the post-response HQ + operations handoff.
+ * The meeting and sidecar remain the canonical data; this store contains only
+ * bounded pointers and phase state so a server restart can resume safely. */
+export class MeetingFinalizationJobStore {
+  readonly root: string
+
+  constructor(root = dataPath('meeting-finalization-jobs')) {
+    this.root = resolve(root)
+  }
+
+  private ensureRoot(): void {
+    mkdirSync(this.root, { recursive: true, mode: 0o700 })
+  }
+
+  private pathFor(sessionId: string): string {
+    if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) throw new Error('Invalid finalization sessionId')
+    const path = resolve(this.root, `${sessionId}.json`)
+    if (!contained(this.root, path)) throw new Error('Unsafe finalization job path')
+    return path
+  }
+
+  private assertSafePointers(input: Pick<MeetingFinalizationJob, 'meetingPath' | 'sidecarPath' | 'audioDir'>): void {
+    const dataRoot = dirname(this.root)
+    const recordingsRoot = resolve(dataRoot, 'recordings')
+    const pendingRoot = resolve(dataRoot, 'pending-batch')
+    if (!contained(recordingsRoot, resolve(input.meetingPath))) throw new Error('Unsafe finalization meeting path')
+    if (!contained(recordingsRoot, resolve(input.sidecarPath))) throw new Error('Unsafe finalization sidecar path')
+    if (input.audioDir && !contained(pendingRoot, resolve(input.audioDir))) {
+      throw new Error('Unsafe finalization audio path')
+    }
+  }
+
+  save(input: Omit<MeetingFinalizationJob, 'schemaVersion' | 'createdAt' | 'updatedAt'>): MeetingFinalizationJob {
+    this.assertSafePointers(input)
+    this.ensureRoot()
+    const prior = this.get(input.sessionId)
+    const now = new Date().toISOString()
+    const job: MeetingFinalizationJob = {
+      schemaVersion: 1,
+      ...input,
+      createdAt: prior?.createdAt ?? now,
+      updatedAt: now,
+    }
+    durableAtomicWriteFileSync(this.pathFor(input.sessionId), `${JSON.stringify(job, null, 2)}\n`, { mode: 0o600 })
+    return job
+  }
+
+  get(sessionId: string): MeetingFinalizationJob | null {
+    const path = this.pathFor(sessionId)
+    if (!existsSync(path)) return null
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+      if (!validJob(parsed)) return null
+      const normalized = { ...parsed, claimPending: parsed.claimPending === true }
+      this.assertSafePointers(normalized)
+      return normalized
+    } catch {
+      return null
+    }
+  }
+
+  list(): MeetingFinalizationJob[] {
+    if (!existsSync(this.root)) return []
+    let names: string[] = []
+    try { names = readdirSync(this.root).filter(name => JOB_NAME.test(name)) } catch { return [] }
+    return names.flatMap(name => {
+      const sessionId = basename(name, '.json')
+      const job = this.get(sessionId)
+      return job ? [job] : []
+    })
+  }
+
+  malformedCount(): number {
+    if (!existsSync(this.root)) return 0
+    try {
+      return readdirSync(this.root)
+        .filter(name => JOB_NAME.test(name))
+        .filter(name => this.get(basename(name, '.json')) === null)
+        .length
+    } catch {
+      return 0
+    }
+  }
+
+  remove(sessionId: string): void {
+    try { unlinkSync(this.pathFor(sessionId)) } catch { /* already absent */ }
+  }
+
+  /** Find a previously moved audio directory without trusting a stored path. */
+  findPendingAudioDir(sessionId: string): string | null {
+    const pendingRoot = resolve(dirname(this.root), 'pending-batch')
+    if (!existsSync(pendingRoot)) return null
+    try {
+      const candidates = readdirSync(pendingRoot)
+        .filter(name => name === sessionId || name.startsWith(`${sessionId}_`))
+        .map(name => resolve(pendingRoot, name))
+        .filter(path => contained(pendingRoot, path) && statSync(path).isDirectory())
+        .sort()
+      return candidates[0] ?? null
+    } catch {
+      return null
+    }
+  }
+
+  /** Rebuild missing replay jobs from the canonical sidecar intent marker. */
+  reconcileCanonicalSidecars(): MeetingFinalizationJob[] {
+    const recordingsRoot = resolve(dirname(this.root), 'recordings')
+    if (!existsSync(recordingsRoot)) return []
+    const rebuilt: MeetingFinalizationJob[] = []
+    let months: string[] = []
+    try { months = readdirSync(recordingsRoot).filter(name => /^\d{4}-\d{2}$/.test(name)) } catch { return [] }
+    for (const month of months) {
+      const monthDir = resolve(recordingsRoot, month)
+      let names: string[] = []
+      try { names = readdirSync(monthDir).filter(name => name.endsWith('.g2-chunks.json')) } catch { continue }
+      for (const name of names) {
+        const sidecarPath = resolve(monthDir, name)
+        try {
+          const sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8')) as Record<string, unknown>
+          const sessionId = typeof sidecar.sessionId === 'string' ? sidecar.sessionId : ''
+          if (sidecar.finalizationState === 'complete' || !sidecar.finalizationState || this.get(sessionId)) continue
+          const meetingPath = sidecarPath.replace(/\.g2-chunks\.json$/, '.md')
+          if (!existsSync(meetingPath)) continue
+          const audioDir = this.findPendingAudioDir(sessionId)
+          rebuilt.push(this.save({
+            sessionId,
+            meetingPath,
+            sidecarPath,
+            audioDir,
+            streamingWordCount: Number(sidecar.streamingWordCount ?? 0),
+            phase: audioDir ? 'batch_pending' : 'capture_pending',
+            claimPending: sidecar.claimPending === true,
+          }))
+        } catch { /* malformed canonical sidecars are not executable */ }
+      }
+    }
+    return rebuilt
+  }
+}
+
+export function readFinalizationChunkEntries(job: MeetingFinalizationJob): unknown[] | null {
+  if (!existsSync(job.meetingPath) || !existsSync(job.sidecarPath)) return null
+  try {
+    const sidecar = JSON.parse(readFileSync(job.sidecarPath, 'utf8')) as Record<string, unknown>
+    if (sidecar.sessionId !== job.sessionId || !Array.isArray(sidecar.chunkEntries)) return null
+    return sidecar.chunkEntries
+  } catch {
+    return null
+  }
+}
+
+export function canonicalFinalizationIsComplete(job: MeetingFinalizationJob): boolean {
+  try {
+    const sidecar = JSON.parse(readFileSync(job.sidecarPath, 'utf8')) as Record<string, unknown>
+    return sidecar.sessionId === job.sessionId && sidecar.finalizationState === 'complete'
+  } catch {
+    return false
+  }
+}
+
+export function markCanonicalFinalizationState(
+  sidecarPath: string,
+  state: MeetingFinalizationJob['phase'] | 'complete',
+  claimPending: boolean,
+): void {
+  if (!existsSync(sidecarPath)) return
+  const parsed = JSON.parse(readFileSync(sidecarPath, 'utf8')) as Record<string, unknown>
+  parsed.finalizationState = state
+  parsed.claimPending = claimPending
+  parsed.finalizationUpdatedAt = new Date().toISOString()
+  if (state === 'complete') delete parsed.finalizationError
+  durableAtomicWriteFileSync(sidecarPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 })
+}
+
+export function getMeetingFinalizationSnapshot(): {
+  pending: number
+  failed: number
+  oldestUpdatedAt: string | null
+  lastError: string | null
+  malformed: number
+} {
+  const jobs = new MeetingFinalizationJobStore().list()
+  const failed = jobs.filter(job => Boolean(job.lastError))
+  const oldest = jobs.map(job => job.updatedAt).sort()[0] ?? null
+  const mostRecentFailure = failed.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0]
+  return {
+    pending: jobs.length,
+    failed: failed.length,
+    oldestUpdatedAt: oldest,
+    lastError: mostRecentFailure?.lastError?.slice(0, 200) ?? null,
+    malformed: new MeetingFinalizationJobStore().malformedCount(),
+  }
+}

package/server/lib/meeting-store.ts

@@ -89,6 +89,10 @@ export interface SaveMeetingInput {
   chunkEntries?: IndexedTranscriptChunk[]
   providerCandidates?: Record<string, ProviderCandidateRecord>
   transferIntegrity?: TranscriptGapReport | null
+  /** Durable intent used to reconstruct post-save work if the process exits
+   * between the canonical commit and creation of the replay job. */
+  finalizationRequired?: boolean
+  claimPending?: boolean
 }
 
 export interface SavedMeeting {
@@ -444,6 +448,11 @@ export class MeetingStore {
       transcriptionQuality: 'streaming',
       batchApplied: false,
       streamingWordCount: wordCount(transcript),
+      ...(input.finalizationRequired ? {
+        finalizationState: 'capture_pending',
+        claimPending: input.claimPending === true,
+        finalizationUpdatedAt: new Date().toISOString(),
+      } : {}),
     }
 
     // Sidecar first, markdown second: the markdown is the visible commit marker.

package/server/lib/whisper-local.ts

@@ -8,7 +8,7 @@
 
 import { spawn, execFile } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
-import { writeFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs'
+import { writeFileSync, unlinkSync, existsSync, readFileSync, statSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
@@ -74,6 +74,37 @@ export interface HighQualityTranscriptionResult {
   degradationReason?: HighQualityUnavailableReason
 }
 
+let highQualityCheckpointFingerprint: string | null = null
+
+/** Stable, path-free cache identity for progressive meeting HQ checkpoints.
+ * Model/configuration is immutable for the lifetime of one server process, so
+ * cache this instead of stat'ing multi-GB model files on every health poll. */
+export function getHighQualityCheckpointFingerprint(): string {
+  if (highQualityCheckpointFingerprint) return highQualityCheckpointFingerprint
+  const identity = (path: string): Record<string, number | boolean> => {
+    try {
+      const stat = statSync(path)
+      return { present: true, size: stat.size, mtimeMs: Math.floor(stat.mtimeMs) }
+    } catch {
+      return { present: false, size: 0, mtimeMs: 0 }
+    }
+  }
+  highQualityCheckpointFingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    schema: 2,
+    serverVersion: process.env.COS_SERVER_VERSION?.trim() || 'development',
+    whisperCli: identity(WHISPER_CLI),
+    model: identity(resolveBatchModel()),
+    vad: identity(VAD_MODEL_PATH),
+    beam: 5,
+    bestOf: 5,
+    vadEnabled: hqCliVadEnabled('batch'),
+    enhancement: 'audio-enhance-v1',
+    prompt: buildWhisperPrompt(),
+    corrections: getWhisperCorrections(),
+  })).digest('hex')
+  return highQualityCheckpointFingerprint
+}
+
 export function classifyHighQualityTranscriptionCapability(input: {
   enabled: boolean
   cliPresent: boolean
@@ -806,7 +837,14 @@ export async function transcribeHighQuality(
   /** forceCpu: the batch pipeline's one CPU retry after a Metal preempt. It
    *  bypasses the gate entirely so the retry cannot itself be preempted into
    *  an infinite loop. */
-  opts: { priority?: 'interactive' | 'batch'; forceCpu?: boolean } = {},
+  opts: {
+    priority?: 'interactive' | 'batch'
+    forceCpu?: boolean
+    forceCpuReason?: string
+    threads?: number
+    backgroundCpu?: boolean
+    signal?: AbortSignal
+  } = {},
 ): Promise<HighQualityTranscriptionResult> {
   if (!cliAvailable) {
     // Fall back to server (no beam search available via HTTP API)
@@ -844,7 +882,7 @@ export async function transcribeHighQuality(
     const useVad = hqCliVadEnabled(opts.priority)
     const decision: { device: 'metal' | 'cpu'; reason: string; metalEnabled: boolean } = isBatch
       ? (opts.forceCpu
-          ? { device: 'cpu', reason: 'preempt_retry', metalEnabled: batchHqMetalEnabled() }
+          ? { device: 'cpu', reason: opts.forceCpuReason || 'preempt_retry', metalEnabled: batchHqMetalEnabled() }
           : chooseBatchDevice())
       : { device: 'metal', reason: 'interactive', metalEnabled: batchHqMetalEnabled() }
     const useMetal = decision.device === 'metal'
@@ -858,11 +896,14 @@ export async function transcribeHighQuality(
         : 2
       const beam = isBatch ? 5 : interactiveBeam
       const bestOf = beam
+      const requestedThreads = Number.isFinite(opts.threads)
+        ? Math.max(1, Math.min(16, Math.floor(opts.threads!)))
+        : 8
       const args = [
         '-m', modelPath,
         '-f', tmpWav,
         // CPU batch stays at 8 threads so it cannot starve live work of cores.
-        '-t', (isBatch && !useMetal) ? '8' : '16',
+        '-t', (isBatch && !useMetal) ? String(requestedThreads) : '16',
         '-l', 'en',
         ...(useMetal ? ['-fa'] : ['-ng']),
         '-bs', String(beam),
@@ -879,9 +920,18 @@ export async function transcribeHighQuality(
         // omits this — VAD was measured dropping real leading speech on compose.
         args.push('--vad', '--vad-model', VAD_MODEL_PATH)
       }
-      const proc = spawn(WHISPER_CLI, args, {
+      const useBackgroundTaskPolicy = Boolean(
+        isBatch && !useMetal && opts.backgroundCpu
+        && process.platform === 'darwin'
+        && existsSync('/usr/sbin/taskpolicy'),
+      )
+      const proc = spawn(
+        useBackgroundTaskPolicy ? '/usr/sbin/taskpolicy' : WHISPER_CLI,
+        useBackgroundTaskPolicy ? ['-b', WHISPER_CLI, ...args] : args,
+        {
         stdio: ['ignore', 'pipe', 'pipe'],
-      })
+        },
+      )
       ownedHqChildren.add(proc)
 
       // BLOCKER contract: a preempted Metal child is a HARD FAIL. Its stdout
@@ -896,6 +946,17 @@ export async function transcribeHighQuality(
 
       let stdout = ''
       let stderr = ''
+      let aborted = false
+      let abortForceKill: ReturnType<typeof setTimeout> | null = null
+      const onAbort = (): void => {
+        aborted = true
+        try { proc.kill('SIGTERM') } catch { /* already exited */ }
+        abortForceKill = setTimeout(() => {
+          try { proc.kill('SIGKILL') } catch { /* already exited */ }
+        }, 2_000)
+      }
+      if (opts.signal?.aborted) onAbort()
+      else opts.signal?.addEventListener('abort', onAbort, { once: true })
       proc.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
       proc.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
 
@@ -915,9 +976,11 @@ export async function transcribeHighQuality(
       }, timeoutMs)
 
       proc.on('close', (code) => {
+        opts.signal?.removeEventListener('abort', onAbort)
         ownedHqChildren.delete(proc)
         unregisterMetalBatchChild(proc)
         clearTimeout(timeout)
+        if (abortForceKill) clearTimeout(abortForceKill)
         if (forceKill) clearTimeout(forceKill)
         // Preempt is checked FIRST and ignores the exit code: SIGTERM often
         // yields a non-zero code, but a race could also let the child exit 0
@@ -926,6 +989,12 @@ export async function transcribeHighQuality(
           reject(new MetalBatchPreemptedError(preemptedReason))
           return
         }
+        if (aborted) {
+          const error = new Error('Progressive HQ checkpoint aborted')
+          error.name = 'AbortError'
+          reject(error)
+          return
+        }
         if (timedOut) {
           reject(new Error(`whisper-cli HQ timeout (${timeoutMs / 1000}s, model=${useLargeV3 ? 'large-v3' : 'turbo'})`))
           return
@@ -938,9 +1007,11 @@ export async function transcribeHighQuality(
       })
 
       proc.on('error', (err) => {
+        opts.signal?.removeEventListener('abort', onAbort)
         ownedHqChildren.delete(proc)
         unregisterMetalBatchChild(proc)
         clearTimeout(timeout)
+        if (abortForceKill) clearTimeout(abortForceKill)
         if (forceKill) clearTimeout(forceKill)
         reject(new Error(`whisper-cli HQ spawn error: ${err.message}`))
       })

package/server/routes/health.ts

@@ -40,6 +40,9 @@ import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
 import { getWhisperPreviewCapability } from '../lib/whisper-preview.js'
 import { getTranscriptionProfileStatus } from '../lib/profile.js'
 import { getHealthStaticProbes } from '../lib/health-static-probes.js'
+import { getEarlyMeetingSyncSnapshot } from '../lib/g2-ops-handoff.js'
+import { getProgressiveHqSnapshot } from '../lib/meeting-batch-transcribe.js'
+import { getMeetingFinalizationSnapshot } from '../lib/meeting-finalization-jobs.js'
 
 export const healthRouter = Router()
 
@@ -190,6 +193,7 @@ healthRouter.get('/health', async (_req, res) => {
   const cursorSnapshot = getCursorModelCatalogSnapshot()
   const { agentBinary: _cursorAgentBinary, ...cursor_models } = cursorSnapshot
   const meeting_sync = getMeetingSyncSnapshot()
+  const progressiveHq = getProgressiveHqSnapshot()
   // Quarantined unsaved captures (6.19.0). Compact on this unauthenticated
   // surface — same exposure level as meeting_sync's meetingIds. Full detail
   // plus the recover action live on the authenticated /api/meeting/orphans.
@@ -235,6 +239,11 @@ healthRouter.get('/health', async (_req, res) => {
       },
       cliDebug: CLI_DEBUG_CAPABILITY,
       liveCues,
+      meetingLifecycle: {
+        earlySyncClaim: getEarlyMeetingSyncSnapshot(),
+        progressiveHq,
+        finalization: getMeetingFinalizationSnapshot(),
+      },
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
     // /api/health is intentionally unauthenticated for setup diagnostics.
@@ -261,6 +270,7 @@ healthRouter.get('/models', async (req, res) => {
   const transcriptionHq = getHighQualityTranscriptionCapability()
   const transcriptionLive = getWhisperPreviewCapability()
   const transcriptionProfile = getTranscriptionProfileStatus()
+  const progressiveHq = getProgressiveHqSnapshot()
   const cursorOptions = cursorCatalog.options.filter(option => !!option.id)
   res.json({
     ...catalog,
@@ -282,6 +292,11 @@ healthRouter.get('/models', async (req, res) => {
         hq: transcriptionHq,
         profile: transcriptionProfile,
       },
+      meetingLifecycle: {
+        earlySyncClaim: getEarlyMeetingSyncSnapshot(),
+        progressiveHq,
+        finalization: getMeetingFinalizationSnapshot(),
+      },
       cliDebug: CLI_DEBUG_CAPABILITY,
       recovery: managedRuntimeCapability(),
       // Same helper as /api/health — the companion's 15s liveness poll reads