@gotcos/glasses-server 6.18.3 → 6.18.4

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 6.18.4
+
+- **Meeting sync progress on `/api/health`.** Post-meeting HQ polish writes
+  `_batch_progress.json` under `pending-batch/<meetingId>/` and publishes
+  `meeting_sync` on health (`active`, `percent`, `label`, `blocksRestart`,
+  per-meeting rows). COS Control 0.3.0+ shows this as a status row so Update /
+  Restart drain is no longer a black box during long Whisper batch jobs.
+
 ## 6.18.3
 
 > Ships as 6.18.3. There is no published 6.18.2 — that version number was bumped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.18.3",
+  "version": "6.18.4",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/lib/meeting-batch-progress.ts

@@ -0,0 +1,221 @@
+// Meeting HQ polish progress for COS Control / health.
+// Written next to pending-batch audio so a draining Update can show % complete
+// instead of a silent "degraded" row while Whisper chews through a long save.
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { dataPath } from './data-dir.js'
+
+export const BATCH_PROGRESS_FILENAME = '_batch_progress.json'
+export const BATCH_PENDING_MARKER = '_batch_pending.marker'
+
+export type MeetingBatchPhase =
+  | 'queued'
+  | 'hq_polish'
+  | 'quality_check'
+  | 'persisting'
+  | 'done'
+
+export interface MeetingBatchProgress {
+  schemaVersion: 1
+  meetingId: string
+  phase: MeetingBatchPhase
+  segmentsDone: number
+  segmentsTotal: number
+  chunkFiles?: number
+  updatedAt: string
+  startedAt: string
+}
+
+export interface MeetingSyncMeeting {
+  meetingId: string
+  phase: MeetingBatchPhase | 'pending'
+  percent: number | null
+  segmentsDone: number | null
+  segmentsTotal: number | null
+  chunkFiles: number
+  label: string
+  updatedAt: string | null
+}
+
+export interface MeetingSyncSnapshot {
+  active: boolean
+  percent: number | null
+  label: string
+  blocksRestart: boolean
+  meetings: MeetingSyncMeeting[]
+}
+
+function pendingBatchRoot(): string {
+  return dataPath('pending-batch')
+}
+
+function clampPercent(done: number, total: number): number {
+  if (total <= 0) return 0
+  return Math.max(0, Math.min(100, Math.round((done / total) * 100)))
+}
+
+function labelFor(meeting: Omit<MeetingSyncMeeting, 'label'>): string {
+  if (meeting.percent != null && meeting.segmentsTotal != null && meeting.segmentsTotal > 0) {
+    return `HQ polish ${meeting.percent}% (${meeting.segmentsDone}/${meeting.segmentsTotal})`
+  }
+  if (meeting.chunkFiles > 0) {
+    return `HQ polish · ${meeting.chunkFiles} chunk${meeting.chunkFiles === 1 ? '' : 's'}`
+  }
+  return 'HQ polish · pending'
+}
+
+export function writeMeetingBatchProgress(
+  audioDir: string,
+  input: {
+    phase: MeetingBatchPhase
+    segmentsDone: number
+    segmentsTotal: number
+    meetingId?: string
+    startedAt?: string
+  },
+): void {
+  const meetingId = input.meetingId ?? basename(audioDir)
+  const path = join(audioDir, BATCH_PROGRESS_FILENAME)
+  let startedAt = input.startedAt
+  if (!startedAt && existsSync(path)) {
+    try {
+      const prior = JSON.parse(readFileSync(path, 'utf8')) as MeetingBatchProgress
+      if (typeof prior.startedAt === 'string') startedAt = prior.startedAt
+    } catch { /* replace */ }
+  }
+  const payload: MeetingBatchProgress = {
+    schemaVersion: 1,
+    meetingId,
+    phase: input.phase,
+    segmentsDone: Math.max(0, input.segmentsDone),
+    segmentsTotal: Math.max(0, input.segmentsTotal),
+    updatedAt: new Date().toISOString(),
+    startedAt: startedAt ?? new Date().toISOString(),
+  }
+  try {
+    const wavs = readdirSync(audioDir).filter(name => name.endsWith('.wav')).length
+    payload.chunkFiles = wavs
+  } catch { /* optional */ }
+  try {
+    writeFileSync(path, `${JSON.stringify(payload)}\n`, { encoding: 'utf8', mode: 0o600 })
+  } catch {
+    // Progress is observability only — never fail HQ polish for a status write.
+  }
+}
+
+export function clearMeetingBatchProgress(audioDir: string): void {
+  const path = join(audioDir, BATCH_PROGRESS_FILENAME)
+  try {
+    if (existsSync(path)) unlinkSync(path)
+  } catch { /* ignore */ }
+}
+
+function readProgressFile(dir: string): MeetingBatchProgress | null {
+  const path = join(dir, BATCH_PROGRESS_FILENAME)
+  if (!existsSync(path)) return null
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as MeetingBatchProgress
+    if (raw?.schemaVersion !== 1) return null
+    if (typeof raw.meetingId !== 'string') return null
+    if (typeof raw.segmentsTotal !== 'number' || typeof raw.segmentsDone !== 'number') return null
+    return raw
+  } catch {
+    return null
+  }
+}
+
+function markerFresh(dir: string, maxAgeMs = 15 * 60_000): boolean {
+  const marker = join(dir, BATCH_PENDING_MARKER)
+  if (!existsSync(marker)) return false
+  try {
+    return Date.now() - statSync(marker).mtimeMs <= maxAgeMs
+  } catch {
+    return false
+  }
+}
+
+/** Snapshot of pending HQ polish work for /api/health and COS Control. */
+export function getMeetingSyncSnapshot(
+  root: string = pendingBatchRoot(),
+): MeetingSyncSnapshot {
+  const meetings: MeetingSyncMeeting[] = []
+  if (!existsSync(root)) {
+    return { active: false, percent: null, label: 'Idle', blocksRestart: false, meetings }
+  }
+
+  let dirs: string[] = []
+  try {
+    dirs = readdirSync(root).filter(name => {
+      try {
+        return statSync(join(root, name)).isDirectory()
+      } catch {
+        return false
+      }
+    })
+  } catch {
+    return { active: false, percent: null, label: 'Idle', blocksRestart: false, meetings }
+  }
+
+  for (const name of dirs) {
+    const dir = join(root, name)
+    const progress = readProgressFile(dir)
+    let chunkFiles = 0
+    try {
+      chunkFiles = readdirSync(dir).filter(f => f.endsWith('.wav')).length
+    } catch { /* ignore */ }
+
+    const active = markerFresh(dir) || progress != null
+    if (!active && chunkFiles === 0) continue
+
+    if (progress) {
+      const percent = progress.segmentsTotal > 0
+        ? clampPercent(progress.segmentsDone, progress.segmentsTotal)
+        : null
+      const row: Omit<MeetingSyncMeeting, 'label'> = {
+        meetingId: progress.meetingId || name,
+        phase: progress.phase,
+        percent,
+        segmentsDone: progress.segmentsTotal > 0 ? progress.segmentsDone : null,
+        segmentsTotal: progress.segmentsTotal > 0 ? progress.segmentsTotal : null,
+        chunkFiles: progress.chunkFiles ?? chunkFiles,
+        updatedAt: progress.updatedAt,
+      }
+      meetings.push({ ...row, label: labelFor(row) })
+      continue
+    }
+
+    if (!markerFresh(dir) && chunkFiles === 0) continue
+    const row: Omit<MeetingSyncMeeting, 'label'> = {
+      meetingId: name,
+      phase: 'pending',
+      percent: null,
+      segmentsDone: null,
+      segmentsTotal: null,
+      chunkFiles,
+      updatedAt: null,
+    }
+    meetings.push({ ...row, label: labelFor(row) })
+  }
+
+  if (meetings.length === 0) {
+    return { active: false, percent: null, label: 'Idle', blocksRestart: false, meetings }
+  }
+
+  const withPercent = meetings.filter(m => m.percent != null)
+  const percent = withPercent.length === meetings.length
+    ? Math.round(withPercent.reduce((sum, m) => sum + (m.percent ?? 0), 0) / meetings.length)
+    : null
+
+  const label = meetings.length === 1
+    ? meetings[0]!.label
+    : `${meetings.length} meetings syncing` + (percent != null ? ` · ${percent}%` : '')
+
+  return {
+    active: true,
+    percent,
+    label,
+    blocksRestart: true,
+    meetings,
+  }
+}

package/server/lib/meeting-batch-transcribe.ts

@@ -3,10 +3,14 @@
 // The candidate is never canonical until batch-transcript-quality accepts it.
 
 import { existsSync, readFileSync, readdirSync, utimesSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { enhanceAudio } from './audio-enhance.js'
 import { transcribeHighQuality, type WhisperWord } from './whisper-local.js'
 import { isMetalBatchPreempted } from './whisper-metal-gate.js'
+import {
+  clearMeetingBatchProgress,
+  writeMeetingBatchProgress,
+} from './meeting-batch-progress.js'
 import type { IndexedTranscriptChunk } from '../routes/transcribe-stream.js'
 import {
   evaluateBatchQuality,
@@ -167,6 +171,13 @@ async function transcribeSegments(
   entries: IndexedTranscriptChunk[],
 ): Promise<BatchResult[]> {
   const results: BatchResult[] = []
+  const meetingId = basename(audioDir)
+  writeMeetingBatchProgress(audioDir, {
+    phase: 'hq_polish',
+    segmentsDone: 0,
+    segmentsTotal: segments.length,
+    meetingId,
+  })
   for (const segment of segments) {
     try {
       refreshPendingLease(audioDir)
@@ -202,11 +213,23 @@ async function transcribeSegments(
         speakerWords: mapWordsToSpeakers(words, segment, entries),
       })
       refreshPendingLease(audioDir)
+      writeMeetingBatchProgress(audioDir, {
+        phase: 'hq_polish',
+        segmentsDone: results.length,
+        segmentsTotal: segments.length,
+        meetingId,
+      })
     } catch (error) {
       console.error(
         `[meeting-batch] Segment ${segment.startChunkIdx}-${segment.endChunkIdx} failed: `
         + `${error instanceof Error ? error.message : String(error)}`,
       )
+      writeMeetingBatchProgress(audioDir, {
+        phase: 'hq_polish',
+        segmentsDone: results.length,
+        segmentsTotal: segments.length,
+        meetingId,
+      })
     }
   }
   return results
@@ -223,13 +246,22 @@ export function runMeetingBatchPipeline(
   // Lease immediately, including time spent behind another HQ decoder. Without
   // this, the two-hour cleanup could delete a queued meeting before it starts.
   refreshPendingLease(audioDir)
+  writeMeetingBatchProgress(audioDir, {
+    phase: 'queued',
+    segmentsDone: 0,
+    segmentsTotal: 0,
+    meetingId: basename(audioDir),
+  })
   const lease = setInterval(() => refreshPendingLease(audioDir), 60_000)
   lease.unref()
   const job = batchQueueTail.then(() => runMeetingBatchPipelineNow(
     audioDir,
     entries,
     streamingWordCount,
-  )).finally(() => clearInterval(lease))
+  )).finally(() => {
+    clearInterval(lease)
+    clearMeetingBatchProgress(audioDir)
+  })
   batchQueueTail = job.then(() => undefined, () => undefined)
   return job
 }
@@ -248,7 +280,19 @@ async function runMeetingBatchPipelineNow(
     const segments = segmentTranscriptChunks(entries)
     if (segments.length === 0) return { transcriptionQuality: 'streaming' }
 
+    writeMeetingBatchProgress(audioDir, {
+      phase: 'hq_polish',
+      segmentsDone: 0,
+      segmentsTotal: segments.length,
+      meetingId: basename(audioDir),
+    })
     const batchSegments = await transcribeSegments(audioDir, segments, entries)
+    writeMeetingBatchProgress(audioDir, {
+      phase: 'quality_check',
+      segmentsDone: segments.length,
+      segmentsTotal: segments.length,
+      meetingId: basename(audioDir),
+    })
     const batchTranscript = batchSegments.map(result => result.text).join(' ')
     const qualityReport = evaluateBatchQuality(batchSegments, streamingWordCount)
     if (!qualityReport.accepted) {

package/server/routes/health.ts

@@ -37,6 +37,7 @@ import { getServerGenerationId } from '../lib/managed-runtime.js'
 import { maintenanceLifecycle } from '../lib/maintenance-lifecycle.js'
 import { getLocalTtsHealth, refreshLocalTtsHealth } from '../lib/tts-local.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
+import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 
 export const healthRouter = Router()
 
@@ -259,6 +260,7 @@ healthRouter.get('/health', async (_req, res) => {
   // agent binary paths stay on the authenticated /api/models surface.
   const cursorSnapshot = getCursorModelCatalogSnapshot()
   const { agentBinary: _cursorAgentBinary, ...cursor_models } = cursorSnapshot
+  const meeting_sync = getMeetingSyncSnapshot()
   res.json({
     ...checks,
     server_version: managedServerVersion(),
@@ -273,6 +275,7 @@ healthRouter.get('/health', async (_req, res) => {
     tts_local,
     codex_models,
     cursor_models,
+    meeting_sync,
     capabilities: {
       transcription: { ...transcription, hq: transcriptionHq },
       recovery,