@gotcos/glasses-server 6.26.0 → 6.27.1

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## 6.27.1
+
+### The 16-frame video from 6.27.0 now actually works end to end
+
+6.27.0 raised video stills from 1-3 to 8-16 entirely inside the extractor. Four
+consumers were never checked, and each one silently rejected what the extractor
+had started writing. Every failure was invisible: three dropped an optional field
+with no error, and the fourth threw only when the user asked a question.
+
+- **A video of 75 seconds or longer 400'd when you asked about it.**
+  `query-attachments.ts` capped model image inputs at 12 and threw a hard
+  `too_many_attachment_frames` rather than trimming, while `round(75/6) = 13`
+  frames. The video uploaded, stored its frames, and failed at ask time. The
+  ceiling is now `VIDEO_SUMMARY_FRAMES_MAX`, expressed as the symbol so the two
+  cannot drift again, and a test walks every duration to 30 minutes. Nothing in
+  the suite had ever asserted `too_many_attachment_frames`.
+- **A 16-frame video became an 8-frame video after any restart.**
+  `sanitizeRecord` ran `derivativePaths.slice(0, 8)` on index load, so the record
+  kept 16 frames in memory and 8 on reload - and Update Server restarts the
+  server. The other 8 files stayed on disk orphaned: unreferenced, never served,
+  never swept. PDFs are unaffected; their producer caps itself at 8.
+- **`frameCount` above 8 was dropped by the parser.** `parseMediaAttachmentRef`
+  is a whitelist and the field is optional, so the count vanished with no error
+  for every video past ~90 seconds.
+- **`bytes` above 64 MiB was dropped by the parser** - so the 100 MiB and chunked
+  2 GiB videos shipped in 6.26.0 lost their byte count too. Raised to the chunked
+  ceiling and pinned to it.
+- `durationMs` above 1 hour was likewise dropped. Unreachable today behind the
+  20-minute ingest cap, fixed now because it is the same one-line class and would
+  have been the next invisible ceiling.
+
+The parser bounds are now named constants documented as sanity bounds rather than
+policy, mirrored from the server ceilings and pinned by test - `shared/` cannot
+import `server/`, and an unpinned copy is what allowed all of this to drift.
+
+Known limitation, unchanged: attaching three or more videos to one prompt still
+returns 400, because 3 x the 8-frame floor exceeds the 16-input ceiling. Frames
+are a video's only visual representation, so refusing is honest where silently
+dropping half of one would not be.
+
+New tests: 8 parser round-trip, 4 restart round-trip, 5 frame-budget. Every one
+round-trips through the real reader - asserting on the writer is what missed all
+four defects, since the writer was correct in every case. 8 mutations, all caught.
+
+## 6.27.0
+
+### Video review frames: 8-16 stills instead of 1-3
+
+A video attachment is summarized from stills. The old rule was one still per 15
+seconds, floored at 1 and capped at 8, which gave a 12 second clip **one** frame
+and a 44 second clip **three** - not enough to tell what a video contains. Miles,
+on a fridge sweep: "it only selects three chunks from the video."
+
+- Frame count is now `clamp(round(seconds / 6), 8, 16)`. A 12s clip and a 44s
+  clip both get 8; a 72s clip gets 12; anything past 96s gets 16.
+- Each frame is the **sharpest** of 5 candidates sampled around its position,
+  ranked by encoded JPEG size at fixed quality. Measured on real footage the
+  spread within one second was 1.45x, and the large frame read product label
+  text that the small one rendered as smear.
+- Candidate count is `frames * 5`, so a 20 minute recording costs the same temp
+  I/O as a 12 second one - the sampling rate adapts, the work does not grow.
+- Fixed an upscale: `scale=1280:-2` was enlarging a 480x360 source to 1280x960,
+  paying roughly 7x the image tokens for detail that was never captured. Now
+  `scale='min(1280,iw)':-2`, so small sources pass through at native size.
+- `MAX_DERIVATIVE_IMAGES` (8) is untouched, so PDF page extraction is unchanged.
+  Video no longer shares that constant.
+
 ## 6.26.0
 
 Chunked, resumable upload: video is no longer limited by what fits in one request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.26.0",
+  "version": "6.27.1",
   "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/media-store.ts

@@ -54,6 +54,7 @@ import {
   validateSourceImage,
 } from './image-safety.js'
 import {
+  VIDEO_SUMMARY_FRAMES_MAX,
   prepareRichMediaFromFile,
   type MediaTransferMode,
   type PreparedRichMediaFile,
@@ -278,8 +279,16 @@ function sanitizeRecord(raw: unknown): MediaRecord | null {
     && resolve(sep, value).startsWith(`${expectedAbsolute}${sep}`)
   if (!isOwnedPath(r.storagePath) || !isOwnedPath(r.thumbPath)) return null
   const textPath = isOwnedPath(r.textPath) ? r.textPath : undefined
+  // Was slice(0, 8). sanitizeRecord runs on INDEX LOAD, so a 16-frame video kept all
+  // 16 frames in memory and dropped to 8 after any restart — and COS Control's Update
+  // Server restarts the server. The other 8 files stayed on disk orphaned:
+  // unreferenced, never served, never swept. The model therefore saw the whole video
+  // before a restart and the first half after one, which is invisible in every status
+  // surface. This is a sanity bound on untrusted index data, so it tracks the largest
+  // count any producer can emit; PDFs are unaffected, their producer caps itself at
+  // MAX_DERIVATIVE_IMAGES.
   const derivativePaths = Array.isArray(r.derivativePaths)
-    ? r.derivativePaths.filter(isOwnedPath).slice(0, 8)
+    ? r.derivativePaths.filter(isOwnedPath).slice(0, VIDEO_SUMMARY_FRAMES_MAX)
     : undefined
   const videoCompression = sanitizeVideoCompression(r.videoCompression)
   return {

package/server/lib/query-attachments.ts

@@ -20,6 +20,7 @@ import {
   type MediaAttachmentRef,
 } from '../../shared/media-attachment.js'
 import { getMediaStore, MediaStoreError } from './media-store.js'
+import { VIDEO_SUMMARY_FRAMES_MAX } from './rich-media-safety.js'
 import { strictBase64Decode, ImageSafetyError } from './image-safety.js'
 import type { ModelImageInput } from './model-image-input.js'
 import { formatAttachmentSourceData, type AttachmentSourceData } from './prompt-reference-boundary.js'
@@ -34,7 +35,22 @@ export interface ResolvedQueryAttachments {
   promptBlock?: string
 }
 
-const MAX_MODEL_IMAGE_INPUTS = 12
+/**
+ * Image inputs one prompt may carry.
+ *
+ * This MUST be at least VIDEO_SUMMARY_FRAMES_MAX, because a video contributes one
+ * input per extracted frame with no clamp (see the video branch below) and exceeding
+ * this throws a hard 400. It sat at 12 while frames went to 16 in 6.27.0, so every
+ * video of 75 seconds or longer uploaded successfully, stored its frames, and then
+ * failed the instant the user asked a question about it:
+ *
+ *   Math.round(75 / 6) = 13 frames > 12  ->  400 too_many_attachment_frames
+ *
+ * Frames are a video's ONLY visual representation, unlike PDF page images which are
+ * an optional aid over canonical text — so this ceiling cannot be treated as a
+ * budget to trim silently. It has to fit a whole video.
+ */
+const MAX_MODEL_IMAGE_INPUTS = VIDEO_SUMMARY_FRAMES_MAX
 const MAX_ATTACHMENT_PROMPT_CHARS = 60_000
 
 export class QueryAttachmentError extends Error {

package/server/lib/rich-media-safety.ts

@@ -14,6 +14,7 @@ import {
   readSync,
   readdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -44,6 +45,76 @@ export const MEDIA_SNIFF_BYTES = 12
 export const MAX_DOCUMENT_TEXT_CHARS = 100_000
 export const MAX_VIDEO_DURATION_MS = 20 * 60_000
 export const MAX_DERIVATIVE_IMAGES = 8
+
+// ── Video summary frames ────────────────────────────────────────────────────────
+// DELIBERATELY SEPARATE from MAX_DERIVATIVE_IMAGES, which the PDF path also uses
+// (pdftoppm -l): raising that shared constant would silently give every PDF 16 pages.
+//
+// What was here: min(8, max(1, ceil(durationMs / 15_000))) — one frame per 15 seconds,
+// capped at 8. Measured against real assets that produced:
+//   11.7s 4K clip     ->  1 frame
+//   43.6s fridge sweep ->  3 frames   (Msg 796: "I only got 3 samples")
+//   20 min (the cap)  ->  8 frames, one per 2.5 MINUTES
+// A 12-second video summarised by a single still is not a summary, and 3 frames missed
+// the entire contents of a refrigerator the user was asking about.
+export const VIDEO_SUMMARY_FRAMES_MIN = 8
+export const VIDEO_SUMMARY_FRAMES_MAX = 16
+/** One frame per ~6s of footage, between the floor and the ceiling. */
+const VIDEO_SUMMARY_SECONDS_PER_FRAME = 6
+/** Candidates sampled per window; the sharpest one is kept. More candidates cost
+ *  only temp I/O, but the search is pointless beyond a handful per window. */
+export const VIDEO_SUMMARY_CANDIDATES_PER_FRAME = 5
+
+/**
+ * How many stills represent a video.
+ *
+ * Uniform intervals, not random: random sampling clusters and leaves gaps, while a
+ * uniform grid provably covers start to finish and is reproducible across runs — which
+ * matters when the same video is asked about twice.
+ *
+ * 12 frames is the target for a typical clip: roughly one per 8% of the runtime, about
+ * 15K tokens at 1280px wide, leaving room for a transcript and the question in one turn.
+ * Below the floor of 8 whole segments go unseen; above the ceiling of 16 the marginal
+ * still adds little to a SUMMARY and that budget is better spent on a targeted
+ * native-resolution pass over a named time window.
+ */
+export function videoSummaryFrameCount(durationMs: number): number {
+  const seconds = Number.isFinite(durationMs) ? Math.max(0, durationMs) / 1000 : 0
+  const scaled = Math.round(seconds / VIDEO_SUMMARY_SECONDS_PER_FRAME)
+  return Math.min(VIDEO_SUMMARY_FRAMES_MAX, Math.max(VIDEO_SUMMARY_FRAMES_MIN, scaled))
+}
+
+/**
+ * Pick the sharpest candidate in each window, by encoded JPEG size.
+ *
+ * At a FIXED quality setting, a sharper frame carries more high-frequency detail and
+ * therefore encodes larger; a motion-blurred one compresses down. Measured on the real
+ * 480x360 fridge sweep: within one second the spread was 1.45x (27,311 vs 18,852 bytes),
+ * and inspecting both ends confirmed it — the largest frame reads "Mootopia WHOLE / 13g /
+ * LACTOSE FREE" and the smallest is unreadable smear. Those are the exact labels that
+ * previously required a manual frame-by-frame pass to recover.
+ *
+ * This is a proxy, not a Laplacian: it needs no image library, no new dependency, and one
+ * ffmpeg pass. It can be fooled by a window where the sharp frames are also the emptiest,
+ * which costs a slightly worse still rather than a wrong answer.
+ */
+export function pickSharpestPerWindow(
+  candidates: readonly { name: string; bytes: number }[],
+  windows: number,
+): string[] {
+  if (candidates.length === 0 || windows <= 0) return []
+  const ordered = [...candidates].sort((a, b) => a.name.localeCompare(b.name))
+  const perWindow = Math.max(1, Math.floor(ordered.length / windows))
+  const picked: string[] = []
+  for (let w = 0; w < windows; w++) {
+    const start = w * perWindow
+    // The final window absorbs any remainder, so no candidate is silently dropped.
+    const slice = w === windows - 1 ? ordered.slice(start) : ordered.slice(start, start + perWindow)
+    if (slice.length === 0) continue
+    picked.push(slice.reduce((best, c) => (c.bytes > best.bytes ? c : best), slice[0]).name)
+  }
+  return picked
+}
 const PROCESS_STDERR_MAX = 8_192
 const PROCESS_TIMEOUT_MS = 30_000
 
@@ -364,15 +435,25 @@ async function processVideo(
     if (durationMs > MAX_VIDEO_DURATION_MS) {
       throw new RichMediaSafetyError('video_too_long', `video exceeds ${MAX_VIDEO_DURATION_MS / 60_000} minute limit`)
     }
-    const frameCount = Math.min(MAX_DERIVATIVE_IMAGES, Math.max(1, Math.ceil(durationMs / 15_000)))
-    const fps = Math.max(0.001, frameCount / (durationMs / 1000))
+    // Uniform windows across the whole runtime, then the SHARPEST candidate in each.
+    // Sampling candidates at a duration-derived rate keeps the total constant no matter
+    // how long the video is: a 20-minute recording costs the same temp I/O as a 12-second
+    // one, in ONE ffmpeg pass.
+    const frameCount = videoSummaryFrameCount(durationMs)
+    const candidateCount = frameCount * VIDEO_SUMMARY_CANDIDATES_PER_FRAME
+    const fps = Math.max(0.001, candidateCount / (durationMs / 1000))
     await runProcess('ffmpeg', [
       '-nostdin', '-v', 'error', '-i', input,
-      '-vf', `fps=${fps.toFixed(6)},scale=1280:-2:force_original_aspect_ratio=decrease`,
-      '-frames:v', String(frameCount), '-q:v', '3', join(work, 'frame-%02d.jpg'),
+      // min(1280,iw) rather than a bare 1280: the old filter UPSCALED a 480x360 source to
+      // 1280x960, paying ~7x the image tokens for detail that was never captured. It only
+      // ever downscales now.
+      '-vf', `fps=${fps.toFixed(6)},scale='min(1280,iw)':-2`,
+      '-frames:v', String(candidateCount), '-q:v', '3', join(work, 'cand-%04d.jpg'),
     ])
-    const frames = readdirSync(work)
-      .filter(name => /^frame-\d+\.jpg$/i.test(name)).sort().slice(0, MAX_DERIVATIVE_IMAGES)
+    const candidates = readdirSync(work)
+      .filter(name => /^cand-\d+\.jpg$/i.test(name))
+      .map(name => ({ name, bytes: statSync(join(work, name)).size }))
+    const frames = pickSharpestPerWindow(candidates, frameCount)
       .map(name => readFileSync(join(work, name)))
     if (frames.length === 0) throw new RichMediaSafetyError('corrupt_attachment', 'video produced no review frames')
     const mime: PreparedVideoFile['mime'] = declaredMime === 'video/quicktime' || ext === '.mov'

package/server/lib/voice-directory.ts

@@ -0,0 +1,418 @@
+/**
+ * Cross-meeting voice directory.
+ *
+ * Profiles answer WHO is enrolled. Meeting sidecars answer WHERE a profile was
+ * observed and how strong those occurrence-level matches were. Keeping those
+ * jobs separate matters: an embedding count is training coverage, never a
+ * confidence score, and Ext/Unidentified clusters are meeting-local—not people.
+ *
+ * The scan is asynchronous, bounded, single-flight, and cached. It never runs a
+ * client-side N+1 fan-out and it never exposes filesystem paths.
+ */
+
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises'
+import { dataPath } from './data-dir.js'
+import { confirmedLabels } from './meeting-corrections.js'
+import { resolveCosOperationsDir, resolveMeetingLibrary } from './cos-operations-meetings.js'
+import {
+  isUnattributed,
+  reviewMeetingSpeakers,
+  type Reliability,
+  type ReviewChunk,
+  type SpeakerWordSegment,
+} from './meeting-speaker-review.js'
+import { getOwnerSpeakerLabel } from './profile.js'
+import { readVoiceProfiles, type VoiceProfile } from './speaker-embeddings.js'
+
+const MONTH = /^\d{4}-(0[1-9]|1[0-2])$/
+const SIDECAR = /\.g2-chunks\.json$/
+const SESSION = /^[A-Za-z0-9:_-]{3,96}$/
+const MAX_EVIDENCE_FILES = 1_200
+const MAX_SIDECAR_BYTES = 12 * 1024 * 1024
+const MAX_TOTAL_BYTES = 512 * 1024 * 1024
+const MAX_APPEARANCES_PER_VOICE = 24
+const CACHE_MS = 5 * 60_000
+
+type EvidenceSource = 'cos_operations' | 'direct_library' | 'standalone_recordings'
+
+interface EvidenceCandidate {
+  sidecarPath: string
+  markdownPath: string
+  source: EvidenceSource
+  mutable: boolean
+  date: string
+}
+
+export interface VoiceAppearance {
+  sessionId: string
+  title: string
+  date: string
+  source: EvidenceSource
+  mutable: boolean
+  segments: number
+  speakingMs: number
+  speakingTimeSource: 'words' | 'chunks'
+  observedMatch: number | null
+  reliability: Reliability
+  confirmedByHuman: boolean
+  needsReview: boolean
+}
+
+export interface VoiceDirectoryProfile {
+  name: string
+  isOwner: boolean
+  embeddings: number
+  sources: Record<string, number>
+  sourcesAligned: boolean
+  assertedSegments: number
+  candidateSegments: number
+  assertedSpeakingMs: number
+  candidateSpeakingMs: number
+  speakingTimeSources: Record<'words' | 'chunks', number>
+  meetingCount: number
+  reviewMeetingCount: number
+  observedMatch: number | null
+  observedMatchSegments: number
+  reliabilityCounts: Record<Reliability, number>
+  firstSeen: string | null
+  lastSeen: string | null
+  appearances: VoiceAppearance[]
+}
+
+export interface VoiceDirectorySnapshot {
+  schemaVersion: 1
+  generatedAt: string
+  owner: string
+  profileCount: number
+  totalEmbeddings: number
+  meetingsScanned: number
+  sidecarsSkipped: number
+  truncated: boolean
+  unresolvedMeetings: number
+  unresolvedSegments: number
+  profiles: VoiceDirectoryProfile[]
+}
+
+interface AppearanceAccumulator {
+  assertedSegments: number
+  candidateSegments: number
+  assertedSpeakingMs: number
+  candidateSpeakingMs: number
+  speakingTimeSources: Record<'words' | 'chunks', number>
+  observedWeighted: number
+  observedSegments: number
+  reliabilityCounts: Record<Reliability, number>
+  assertedMeetings: Set<string>
+  reviewMeetings: Set<string>
+  firstSeen: string | null
+  lastSeen: string | null
+  appearances: VoiceAppearance[]
+}
+
+let cached: { at: number; snapshot: VoiceDirectorySnapshot } | null = null
+let building: Promise<VoiceDirectorySnapshot> | null = null
+
+function sourceCounts(profile: VoiceProfile): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const source of profile.sources ?? []) {
+    const key = source.startsWith('auto:') ? 'auto' : source
+    counts[key] = (counts[key] ?? 0) + 1
+  }
+  return counts
+}
+
+function cleanTitle(markdown: string, fallback: string): string {
+  const heading = markdown.match(/^#\s+(.+)$/m)?.[1]?.trim()
+  if (heading) return heading.slice(0, 180)
+  return fallback
+    .replace(/\.g2-chunks\.json$/, '')
+    .replace(/^\d{4}-\d{2}-\d{2}_/, '')
+    .replace(/_/g, ' ')
+    .slice(0, 180) || 'Untitled meeting'
+}
+
+async function safeDirectory(path: string): Promise<string | null> {
+  try {
+    const info = await lstat(path)
+    if (!info.isDirectory() || info.isSymbolicLink()) return null
+    return await realpath(path)
+  } catch { return null }
+}
+
+async function childDirectory(parentReal: string, name: string): Promise<string | null> {
+  const child = await safeDirectory(join(parentReal, name))
+  return child && dirname(child) === parentReal ? child : null
+}
+
+async function collectMonths(
+  base: string,
+  source: EvidenceSource,
+  mutable: boolean,
+): Promise<EvidenceCandidate[]> {
+  const root = await safeDirectory(base)
+  if (!root) return []
+  const candidates: EvidenceCandidate[] = []
+  const months = (await readdir(root)).filter(name => MONTH.test(name)).sort().reverse()
+  for (const month of months) {
+    const monthDir = await childDirectory(root, month)
+    if (!monthDir) continue
+    const files = (await readdir(monthDir)).filter(name => SIDECAR.test(name)).sort().reverse()
+    for (const file of files) {
+      candidates.push({
+        sidecarPath: join(monthDir, file),
+        markdownPath: join(monthDir, file.replace(SIDECAR, '.md')),
+        source,
+        mutable,
+        date: file.match(/^\d{4}-\d{2}-\d{2}/)?.[0] ?? month,
+      })
+      if (candidates.length >= MAX_EVIDENCE_FILES) return candidates
+    }
+  }
+  return candidates
+}
+
+async function boundedMarkdownTitle(path: string, fallback: string): Promise<string> {
+  try {
+    const link = await lstat(path)
+    if (!link.isFile() || link.isSymbolicLink() || link.size > 10 * 1024 * 1024) return fallback
+    const real = await realpath(path)
+    if (dirname(real) !== dirname(path)) return fallback
+    return cleanTitle((await readFile(real, 'utf8')).slice(0, 8_192), fallback)
+  } catch {
+    return fallback
+  }
+}
+
+async function collectCandidates(): Promise<{ rows: EvidenceCandidate[]; truncated: boolean }> {
+  const groups: EvidenceCandidate[][] = []
+  const canonicalRoots = new Set<string>()
+  const operations = resolveCosOperationsDir()
+  if (operations) {
+    const operationsReal = await safeDirectory(operations)
+    if (operationsReal) {
+      canonicalRoots.add(operationsReal)
+      const domains = (await readdir(operationsReal)).sort()
+      const rows: EvidenceCandidate[] = []
+      for (const domain of domains) {
+        const domainDir = await childDirectory(operationsReal, domain)
+        if (!domainDir) continue
+        rows.push(...await collectMonths(join(domainDir, 'meetings'), 'cos_operations', true))
+        if (rows.length >= MAX_EVIDENCE_FILES) break
+      }
+      groups.push(rows)
+    }
+  }
+
+  const library = resolveMeetingLibrary()
+  if (library.layout === 'direct' && library.root) {
+    const directReal = await safeDirectory(library.root)
+    if (directReal && !canonicalRoots.has(directReal)) {
+      canonicalRoots.add(directReal)
+      groups.push(await collectMonths(directReal, 'direct_library', false))
+    }
+  }
+
+  const standalone = await safeDirectory(dataPath('recordings'))
+  if (standalone && !canonicalRoots.has(standalone)) {
+    groups.push(await collectMonths(standalone, 'standalone_recordings', true))
+  }
+
+  const total = groups.reduce((sum, rows) => sum + rows.length, 0)
+  // Source order is precedence order. Duplicates are removed after parsing by
+  // session id, so the titled operations copy wins over direct/raw copies.
+  return { rows: groups.flat().slice(0, MAX_EVIDENCE_FILES), truncated: total > MAX_EVIDENCE_FILES }
+}
+
+function emptyAccumulator(): AppearanceAccumulator {
+  return {
+    assertedSegments: 0,
+    candidateSegments: 0,
+    assertedSpeakingMs: 0,
+    candidateSpeakingMs: 0,
+    speakingTimeSources: { words: 0, chunks: 0 },
+    observedWeighted: 0,
+    observedSegments: 0,
+    reliabilityCounts: { confident: 0, weak: 0, unreliable: 0, unattributed: 0 },
+    assertedMeetings: new Set(),
+    reviewMeetings: new Set(),
+    firstSeen: null,
+    lastSeen: null,
+    appearances: [],
+  }
+}
+
+export async function buildVoiceDirectorySnapshot(): Promise<VoiceDirectorySnapshot> {
+  const owner = getOwnerSpeakerLabel()
+  const { profiles } = readVoiceProfiles()
+  const byName = new Map(profiles.map(profile => [profile.name, emptyAccumulator()]))
+  const known = new Set(profiles.map(profile => profile.name))
+  const candidates = await collectCandidates()
+  const seenSessions = new Set<string>()
+  let totalBytes = 0
+  let meetingsScanned = 0
+  let sidecarsSkipped = 0
+  let truncated = candidates.truncated
+  let unresolvedSegments = 0
+  const unresolvedMeetings = new Set<string>()
+
+  for (let i = 0; i < candidates.rows.length; i++) {
+    if (i > 0 && i % 8 === 0) await yieldToEventLoop()
+    const candidate = candidates.rows[i]
+    try {
+      const link = await lstat(candidate.sidecarPath)
+      if (!link.isFile() || link.isSymbolicLink() || link.size <= 0 || link.size > MAX_SIDECAR_BYTES) {
+        sidecarsSkipped++
+        continue
+      }
+      if (totalBytes + link.size > MAX_TOTAL_BYTES) {
+        truncated = true
+        break
+      }
+      const real = await realpath(candidate.sidecarPath)
+      if (dirname(real) !== dirname(candidate.sidecarPath)) {
+        sidecarsSkipped++
+        continue
+      }
+      totalBytes += link.size
+      const raw = JSON.parse(await readFile(real, 'utf8')) as Record<string, unknown> | ReviewChunk[]
+      const chunks = Array.isArray(raw) ? raw : raw.chunks
+      const sessionId = Array.isArray(raw) ? '' : String(raw.sessionId ?? '')
+      if (!Array.isArray(chunks) || !SESSION.test(sessionId) || seenSessions.has(sessionId)) {
+        sidecarsSkipped++
+        continue
+      }
+      seenSessions.add(sessionId)
+
+      const record = Array.isArray(raw) ? {} : raw
+      const storedTitle = typeof record.title === 'string' && record.title.trim()
+        ? record.title.trim().slice(0, 180)
+        : cleanTitle('', basename(candidate.sidecarPath))
+      const title = await boundedMarkdownTitle(
+        candidate.markdownPath,
+        storedTitle,
+      )
+
+      const review = reviewMeetingSpeakers(chunks as ReviewChunk[], {
+        owner,
+        phrasesPerVoice: 1,
+        confirmed: confirmedLabels(sessionId),
+        durationMs: typeof record.durationMs === 'number' ? record.durationMs : undefined,
+        batchSegments: Array.isArray(record.batchSegments)
+          ? record.batchSegments as SpeakerWordSegment[]
+          : undefined,
+      })
+      meetingsScanned++
+
+      for (const voice of review.voices) {
+        if (isUnattributed(voice.label)) {
+          unresolvedSegments += voice.segments
+          unresolvedMeetings.add(sessionId)
+          continue
+        }
+        if (!known.has(voice.label)) continue
+        const acc = byName.get(voice.label)!
+        const needsReview = !voice.nameAsserted
+        if (needsReview) {
+          acc.candidateSegments += voice.segments
+          acc.candidateSpeakingMs += voice.speakingMs
+          acc.reviewMeetings.add(sessionId)
+        } else {
+          acc.assertedSegments += voice.segments
+          acc.assertedSpeakingMs += voice.speakingMs
+          acc.assertedMeetings.add(sessionId)
+        }
+        acc.speakingTimeSources[review.speakingTimeSource] += voice.speakingMs
+        acc.reliabilityCounts[voice.reliability] += voice.segments
+        if (!acc.firstSeen || candidate.date < acc.firstSeen) acc.firstSeen = candidate.date
+        if (!acc.lastSeen || candidate.date > acc.lastSeen) acc.lastSeen = candidate.date
+        if (voice.meanSimilarity != null) {
+          acc.observedWeighted += voice.meanSimilarity * voice.segments
+          acc.observedSegments += voice.segments
+        }
+        acc.appearances.push({
+          sessionId,
+          title,
+          date: candidate.date,
+          source: candidate.source,
+          mutable: candidate.mutable,
+          segments: voice.segments,
+          speakingMs: voice.speakingMs,
+          speakingTimeSource: review.speakingTimeSource,
+          observedMatch: voice.meanSimilarity,
+          reliability: voice.reliability,
+          confirmedByHuman: voice.confirmedByHuman,
+          needsReview,
+        })
+      }
+    } catch {
+      sidecarsSkipped++
+    }
+  }
+
+  const directory = profiles.map(profile => {
+    const acc = byName.get(profile.name) ?? emptyAccumulator()
+    const appearances = acc.appearances
+      .sort((a, b) => b.date.localeCompare(a.date) || b.segments - a.segments)
+      .slice(0, MAX_APPEARANCES_PER_VOICE)
+    return {
+      name: profile.name,
+      isOwner: profile.name === owner,
+      embeddings: profile.embeddings.length,
+      sources: sourceCounts(profile),
+      sourcesAligned: (profile.sources?.length ?? 0) === profile.embeddings.length,
+      assertedSegments: acc.assertedSegments,
+      candidateSegments: acc.candidateSegments,
+      assertedSpeakingMs: acc.assertedSpeakingMs,
+      candidateSpeakingMs: acc.candidateSpeakingMs,
+      speakingTimeSources: acc.speakingTimeSources,
+      meetingCount: acc.assertedMeetings.size,
+      reviewMeetingCount: acc.reviewMeetings.size,
+      observedMatch: acc.observedSegments > 0
+        ? Math.round((acc.observedWeighted / acc.observedSegments) * 1_000) / 1_000
+        : null,
+      observedMatchSegments: acc.observedSegments,
+      reliabilityCounts: acc.reliabilityCounts,
+      firstSeen: acc.firstSeen,
+      lastSeen: acc.lastSeen,
+      appearances,
+    }
+  }).sort((a, b) => {
+    const attentionA = a.reviewMeetingCount > 0 || !a.sourcesAligned ? 1 : 0
+    const attentionB = b.reviewMeetingCount > 0 || !b.sourcesAligned ? 1 : 0
+    return attentionB - attentionA || b.meetingCount - a.meetingCount || a.name.localeCompare(b.name)
+  })
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    owner,
+    profileCount: profiles.length,
+    totalEmbeddings: profiles.reduce((sum, profile) => sum + profile.embeddings.length, 0),
+    meetingsScanned,
+    sidecarsSkipped,
+    truncated,
+    unresolvedMeetings: unresolvedMeetings.size,
+    unresolvedSegments,
+    profiles: directory,
+  }
+}
+
+export async function getVoiceDirectorySnapshot(force = false): Promise<VoiceDirectorySnapshot> {
+  if (!force && cached && Date.now() - cached.at < CACHE_MS) return cached.snapshot
+  if (!building) {
+    building = buildVoiceDirectorySnapshot()
+      .then(snapshot => {
+        cached = { at: Date.now(), snapshot }
+        return snapshot
+      })
+      .finally(() => { building = null })
+  }
+  return building
+}
+
+/** Test and post-mutation hook. */
+export function invalidateVoiceDirectory(): void {
+  cached = null
+}

package/server/routes/voice.ts

@@ -12,6 +12,7 @@ import { dataPath } from '../lib/data-dir.js'
 import { purgeSpeakerCalibrationRows, relabelSpeakerCalibrationRows } from '../lib/speaker-calibration-log.js'
 import { trainingSourceFor } from '../lib/training-audio-provenance.js'
 import { sendAudioFile } from '../lib/send-audio.js'
+import { getVoiceDirectorySnapshot, invalidateVoiceDirectory } from '../lib/voice-directory.js'
 
 // These MUST match the writer in transcribe-stream.ts, which saves under
 // dataPath(). They previously resolved relative to __dirname — i.e. inside the
@@ -56,6 +57,7 @@ voiceRouter.post('/voice/enroll', async (req, res) => {
     }
 
     const result = enrollSpeaker(name, audioBuffer)
+    invalidateVoiceDirectory()
     res.json(result)
   } catch (err: unknown) {
     res.status(500).json({ success: false, error: errMsg(err) })
@@ -532,6 +534,35 @@ voiceRouter.get('/voice/profiles', (_req, res) => {
   }
 })
 
+// GET /api/voice/directory — enrolled identities plus bounded cross-meeting
+// evidence. Confidence belongs to an observed match, not to a person, so the
+// contract deliberately calls the aggregate `observedMatch` and includes its
+// segment basis. Ext/Unidentified clusters stay in corpus totals rather than
+// being promoted into fictional global people.
+voiceRouter.get('/voice/directory', async (req, res) => {
+  res.set('Cache-Control', 'private, no-store')
+  try {
+    const requestedLimit = Number.parseInt(String(req.query.limit ?? '100'), 10)
+    const requestedOffset = Number.parseInt(String(req.query.offset ?? '0'), 10)
+    const limit = Math.min(Math.max(Number.isFinite(requestedLimit) ? requestedLimit : 100, 1), 100)
+    const offset = Math.max(Number.isFinite(requestedOffset) ? requestedOffset : 0, 0)
+    const snapshot = await getVoiceDirectorySnapshot(req.query.refresh === '1')
+    res.json({
+      ...snapshot,
+      profiles: snapshot.profiles.slice(offset, offset + limit),
+      offset,
+      limit,
+      hasMore: offset + limit < snapshot.profiles.length,
+    })
+  } catch (err: unknown) {
+    res.status(503).json({
+      error: 'Voice directory is temporarily unavailable',
+      reason: 'voice_directory_unavailable',
+      detail: errMsg(err).slice(0, 240),
+    })
+  }
+})
+
 // POST /api/voice/merge-profiles — fold two names for one person together.
 // Body: { into, from: string[]|string, confirm: true, dryRun?, force? }
 //
@@ -605,6 +636,7 @@ voiceRouter.post('/voice/merge-profiles', (req, res) => {
       }
     }
 
+    if (!dryRun) invalidateVoiceDirectory()
     res.json({ ...report, dryRun, forced: force, calibrationRowsRelabeled: calibration })
   } catch (err: unknown) {
     res.status(500).json({ error: errMsg(err) })
@@ -683,6 +715,7 @@ voiceRouter.post('/voice/delete-person', (req, res) => {
 
     // 3. Calibration rows (the name appears in every row).
     const calibration = purgeSpeakerCalibrationRows(CALIBRATION_LOG, target)
+    invalidateVoiceDirectory()
 
     res.json({
       name: target,

package/shared/media-attachment.ts

@@ -44,6 +44,33 @@ export interface MediaAttachmentRef {
  *  query resolution, and the phone composer. */
 export const MAX_ATTACHMENTS_PER_PROMPT = 5
 
+/**
+ * Sanity bounds for the PARSER, not policy.
+ *
+ * `parseMediaAttachmentRef` is a whitelist that drops any field failing its
+ * bound, and every field here is optional — so a value the writer sets correctly
+ * and the parser rejects vanishes with no error anywhere. That is not theoretical:
+ * both of these were live defects found 2026-08-11.
+ *
+ *   - `bytes` was hardcoded `64 * 1024 * 1024` while the server had already moved
+ *     the video ceiling to 100 MiB and chunked uploads to 2 GiB, so every video
+ *     over 64 MiB silently lost its byte count.
+ *   - `frameCount` was hardcoded `8` while VIDEO_SUMMARY_FRAMES_MAX went to 16, so
+ *     every video over ~90 seconds silently lost its frame count.
+ *
+ * These are deliberately GENEROUS: their job is to reject garbage from outside,
+ * while the real limits are enforced at ingest (rich-media-safety.ts) and
+ * advertised on /api/health. A parser bound that doubles as policy is how the
+ * policy ends up in two places and drifts.
+ *
+ * `shared/` must not import from `server/`, so these mirror the server ceilings
+ * and are pinned to them by media-attachment-bounds.test.ts — the same pattern as
+ * ADVERTISED_VIDEO_COMPRESSION_LABEL. Change one, the test fails.
+ */
+export const MAX_PLAUSIBLE_MEDIA_BYTES = 2 * 1024 * 1024 * 1024  // mirrors MAX_CHUNKED_MEDIA_BYTES
+export const MAX_PARSED_VIDEO_FRAMES = 16                        // mirrors VIDEO_SUMMARY_FRAMES_MAX
+export const MAX_PARSED_DURATION_MS = 24 * 60 * 60_000           // a day; ingest enforces the real cap
+
 // ── Media IDs ────────────────────────────────────────────────────────────────
 // One strict generated format, one strict validator. The id builds filesystem
 // paths on the server, so the validator rejects anything that isn't exactly
@@ -108,13 +135,13 @@ export function parseMediaAttachmentRef(raw: unknown): MediaAttachmentRef | null
   // Do not add category to legacy image refs that never carried it. Their
   // canonical JSON is part of persisted durable-query fingerprints.
   if (r.category === inferredCategory) ref.category = inferredCategory
-  if (typeof r.bytes === 'number' && Number.isSafeInteger(r.bytes) && r.bytes >= 0 && r.bytes <= 64 * 1024 * 1024) {
+  if (typeof r.bytes === 'number' && Number.isSafeInteger(r.bytes) && r.bytes >= 0 && r.bytes <= MAX_PLAUSIBLE_MEDIA_BYTES) {
     ref.bytes = r.bytes
   }
-  if (typeof r.durationMs === 'number' && Number.isSafeInteger(r.durationMs) && r.durationMs >= 0 && r.durationMs <= 60 * 60_000) {
+  if (typeof r.durationMs === 'number' && Number.isSafeInteger(r.durationMs) && r.durationMs >= 0 && r.durationMs <= MAX_PARSED_DURATION_MS) {
     ref.durationMs = r.durationMs
   }
-  if (typeof r.frameCount === 'number' && Number.isSafeInteger(r.frameCount) && r.frameCount >= 0 && r.frameCount <= 8) {
+  if (typeof r.frameCount === 'number' && Number.isSafeInteger(r.frameCount) && r.frameCount >= 0 && r.frameCount <= MAX_PARSED_VIDEO_FRAMES) {
     ref.frameCount = r.frameCount
   }
   if (typeof r.textChars === 'number' && Number.isSafeInteger(r.textChars) && r.textChars >= 0 && r.textChars <= 100_000) {