@gotcos/glasses-server 6.21.10 → 6.21.13

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+## 6.21.13
+
+- Carry each meeting's `sessionId` on the meetings list, so a Control row can
+  open the per-meeting speaker review. The review is keyed on the session
+  because that is what lets the store's own hardened lookup find the chunk
+  sidecar again; without this field the two surfaces could not be joined.
+- Read only the head of a sidecar to lift that one field. Sidecars run to
+  megabytes, and reading them whole would make listing cost scale with total
+  transcript size — and silently drop the id on any sidecar above the
+  whole-file size cap.
+- Omit the field rather than invent one when a sidecar is absent, corrupt,
+  symlinked outside its month directory, or carries an implausible id. A
+  meeting with no readable sidecar is still listed.
+
+## 6.21.12
+
+- Add `GET /api/meeting/:sessionId/speakers`, the read surface behind COS
+  Control's speaker-naming panel. Read-only: it reports what a saved meeting's
+  chunk sidecar already holds and never writes. Naming, merging, and rebuilding
+  stay on the `/api/voice/*` routes, each with its own confirmation.
+- Return two to three representative verbatim lines per voice, spread across the
+  meeting and timestamped. These are the primary output: a similarity score
+  cannot tell you who someone is, and a remembered sentence can.
+- Report per-voice reliability from run length rather than similarity alone. Two
+  labels that swap every few segments are the identifier oscillating mid-turn,
+  which means those profiles cannot be told apart and any name applied to either
+  would be a guess. A high similarity score does not override that verdict.
+- Restrict the run-length comparison to each pair of speakers, so a third person
+  interjecting cannot make two others look like they are swapping.
+- Report a recovered meeting as unattributed rather than as a meeting with no
+  speakers, and still return phrases for it — on those meetings the phrases are
+  the only way in.
+
+## 6.21.11
+
+- Add `POST /api/voice/merge-profiles` for the case where one person holds two
+  profiles. The sherpa manager registers one centroid per name, so a split
+  identity has both halves competing on every search and each capped at twenty
+  samples independently — a weaker representation than either half deserves.
+- Refuse a merge whose centroid similarity falls below the search-accept
+  threshold, since two profiles further apart than the value at which
+  identification would match them are not one voice. `force` overrides and is
+  recorded in the response.
+- Preserve provenance through a merge and select the surviving samples for
+  acoustic diversity, so capping the union keeps both profiles represented
+  rather than silently discarding the absorbed one.
+- Relabel the absorbed name's calibration history instead of deleting it: after
+  a merge it is one person's history, and it is the only evidence for whether
+  the merge improved identification.
+- Refuse to absorb the owner label, which the live identification path checks
+  first on every chunk.
+
 ## 6.21.10
 
 - Make the voice profile store durable. `voice-profiles.json` is written

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.10",
+  "version": "6.21.13",
   "description": "COS Glasses — 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-speaker-review.ts

@@ -0,0 +1,268 @@
+// Per-meeting speaker review — the data behind COS Control's naming panel.
+//
+// The panel's job is to let a human name voices from what they REMEMBER, so the
+// primary output here is verbatim phrases, not similarity scores. A score cannot
+// tell you who someone is; "I'll follow up with both Andrews on music targeting"
+// can.
+//
+// It also carries the diagnostic that actually catches a broken profile.
+// Similarity between profile centroids does NOT distinguish "two people who
+// sound alike" from "one voice split across two labels" — measured on the live
+// store, Chris Krubeck and Luke Henry sat at 0.85 while genuinely being
+// separate rows. What discriminates is RUN LENGTH within a single meeting:
+//
+//   MU + Chris Krubeck (known two people) : flip rate 0.069, mean run 30.0
+//   Luke H + Luke Henry                   : flip rate 0.361, mean run 2.79
+//   Chris Krubeck + Luke Henry            : flip rate 0.381, mean run 3.47
+//   Scott Taylor + Dylan Jackson          : flip rate 0.344, mean run 2.80
+//
+// Real conversation holds the floor for ~30 consecutive segments. A pair that
+// swaps every ~3 is the identifier oscillating mid-turn, which means those two
+// profiles cannot be told apart and any name applied to either is a guess.
+//
+// Everything here is pure over a chunk array so it can be tested by execution.
+
+/** One transcript chunk as stored in the `.g2-chunks.json` sidecar. */
+export interface ReviewChunk {
+  text?: string
+  speaker?: string
+  /** MILLISECONDS from meeting start. Confirmed against the writer:
+   *  meeting.ts accumulates `elapsed += row.durationMs`. Treating this as
+   *  seconds reports a 32-minute meeting as 30,936 minutes. */
+  elapsed?: number
+  similarity?: number
+}
+
+/** Labels that mean "nobody was identified", not a person. */
+export const UNATTRIBUTED = new Set(['Unknown', 'Ext', '', 'Speaker 1', 'Speaker 2', 'Speaker 3'])
+
+/** Calibrated from the control pair above. A pair must be BOTH flip-happy and
+ *  short-run to be called unreliable — either alone has honest explanations
+ *  (a rapid-fire exchange is flip-happy; a brief interjection is short-run). */
+export const THRASH_FLIP_RATE = 0.20
+export const THRASH_MEAN_RUN = 8
+/** Below the search-accept threshold a name was never asserted with confidence. */
+export const CONFIDENT_SIMILARITY = 0.65
+
+export type Reliability = 'confident' | 'weak' | 'unreliable' | 'unattributed'
+
+export interface ThrashPair {
+  speaker: string
+  flipRate: number
+  meanRun: number
+  sharedSegments: number
+}
+
+export interface Phrase {
+  text: string
+  /** Milliseconds from meeting start, matching the sidecar. */
+  atMs: number
+  similarity: number | null
+}
+
+export interface VoiceReview {
+  label: string
+  segments: number
+  meanSimilarity: number | null
+  /** Mean consecutive-run length across the WHOLE meeting. Not comparable to
+   *  the pair-scoped run in `thrashesWith`: in a 13-voice meeting every
+   *  speaker's whole-sequence run is short (measured: 3.36 for the owner), so
+   *  this is a talkativeness texture, never a reliability signal. */
+  meanRun: number
+  longestRun: number
+  isOwner: boolean
+  reliability: Reliability
+  thrashesWith: ThrashPair[]
+  phrases: Phrase[]
+}
+
+export interface MeetingSpeakerReview {
+  segments: number
+  /** False when no chunk carries a real speaker — a recovered capture. */
+  attributed: boolean
+  durationMs: number
+  voices: VoiceReview[]
+}
+
+function mean(xs: number[]): number {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0
+}
+
+/** Consecutive-run lengths for one speaker across the whole meeting. */
+export function speakerRuns(sequence: string[], speaker: string): number[] {
+  const runs: number[] = []
+  let cur = 0
+  for (const s of sequence) {
+    if (s === speaker) cur++
+    else if (cur > 0) { runs.push(cur); cur = 0 }
+  }
+  if (cur > 0) runs.push(cur)
+  return runs
+}
+
+/**
+ * How often the label flips between exactly two speakers, ignoring everyone
+ * else. Restricting to the pair is the point: a third person interjecting
+ * should not make two other speakers look like they are thrashing.
+ */
+export function pairFlipRate(
+  sequence: string[],
+  a: string,
+  b: string,
+): { flipRate: number; meanRun: number; sharedSegments: number } | null {
+  const pair = sequence.filter(s => s === a || s === b)
+  if (pair.length < 6) return null            // too little to characterise
+  if (!pair.includes(a) || !pair.includes(b)) return null
+
+  let flips = 0
+  const runs: number[] = []
+  let cur = 1
+  for (let i = 1; i < pair.length; i++) {
+    if (pair[i] === pair[i - 1]) cur++
+    else { flips++; runs.push(cur); cur = 1 }
+  }
+  runs.push(cur)
+  return {
+    flipRate: flips / (pair.length - 1),
+    meanRun: mean(runs),
+    sharedSegments: pair.length,
+  }
+}
+
+/** Words that carry no identifying information. */
+const FILLER = /^(?:yeah|yep|okay|ok|right|sure|mm+|uh+|um+|hmm+|got it|exactly|thanks?|no|yes)[.!?]?$/i
+
+/**
+ * Score a line by how much it would help a human recognise the speaker.
+ *
+ * Length matters (a longer line carries more voice), but so does specificity:
+ * a proper noun, a number, or a domain term is what makes someone say "that's
+ * Graham." A long line of pleasantries scores lower than a short line naming a
+ * brand and a figure.
+ */
+export function phraseScore(text: string): number {
+  const trimmed = text.trim()
+  if (!trimmed || FILLER.test(trimmed)) return 0
+  const words = trimmed.split(/\s+/)
+  if (words.length < 6) return 0
+
+  let score = Math.min(words.length, 28)
+  // Mid-sentence capitals — names, brands, products.
+  const propers = words.slice(1).filter(w => /^[A-Z][a-zA-Z]{2,}/.test(w)).length
+  score += Math.min(propers, 4) * 6
+  // Figures, percentages, money — highly memorable.
+  if (/\d/.test(trimmed)) score += 5
+  // Penalise a line that is mostly filler even if long.
+  const fillerWords = words.filter(w => FILLER.test(w)).length
+  score -= fillerWords * 3
+  return Math.max(score, 0)
+}
+
+/**
+ * Pick up to `limit` representative lines, spread across the meeting.
+ *
+ * Spread is enforced deliberately: the three best-scoring lines often sit
+ * seconds apart in one monologue, which tells you far less about a speaker than
+ * three lines from the beginning, middle, and end. Every phrase carries its
+ * timestamp so a reviewer can place it against their memory of the meeting.
+ */
+export function selectPhrases(
+  chunks: ReviewChunk[],
+  speaker: string,
+  limit = 3,
+  durationMs = 0,
+): Phrase[] {
+  const owned = chunks
+    .map((c, i) => ({ c, i }))
+    .filter(({ c }) => (c.speaker ?? '') === speaker)
+    .map(({ c }) => ({
+      text: (c.text ?? '').trim(),
+      atMs: typeof c.elapsed === 'number' ? c.elapsed : 0,
+      similarity: typeof c.similarity === 'number' ? c.similarity : null,
+      score: phraseScore(c.text ?? ''),
+    }))
+    .filter(p => p.score > 0)
+
+  if (owned.length === 0) return []
+
+  const span = durationMs > 0 ? durationMs : Math.max(...owned.map(p => p.atMs), 1)
+  const minGap = span / (limit * 2)   // no two picks from the same stretch
+
+  const picked: typeof owned = []
+  for (const cand of [...owned].sort((a, b) => b.score - a.score)) {
+    if (picked.length >= limit) break
+    if (picked.some(p => Math.abs(p.atMs - cand.atMs) < minGap)) continue
+    picked.push(cand)
+  }
+  // Backfill on a short meeting where the gap rule excluded everything.
+  if (picked.length < limit) {
+    for (const cand of [...owned].sort((a, b) => b.score - a.score)) {
+      if (picked.length >= limit) break
+      if (!picked.includes(cand)) picked.push(cand)
+    }
+  }
+  return picked
+    .sort((a, b) => a.atMs - b.atMs)
+    .map(({ text, atMs, similarity }) => ({ text, atMs, similarity }))
+}
+
+/** Build the whole review for one meeting's chunks. */
+export function reviewMeetingSpeakers(
+  chunks: ReviewChunk[],
+  options: { owner?: string; phrasesPerVoice?: number } = {},
+): MeetingSpeakerReview {
+  const owner = options.owner ?? 'Me'
+  const limit = options.phrasesPerVoice ?? 3
+  const sequence = chunks.map(c => c.speaker ?? '')
+  const durationMs = chunks.reduce((max, c) => Math.max(max, typeof c.elapsed === 'number' ? c.elapsed : 0), 0)
+
+  const labels = [...new Set(sequence)].filter(s => s.length > 0)
+  const named = labels.filter(l => !UNATTRIBUTED.has(l))
+
+  const voices: VoiceReview[] = labels.map(label => {
+    const own = chunks.filter(c => (c.speaker ?? '') === label)
+    const sims = own.map(c => c.similarity).filter((s): s is number => typeof s === 'number' && s > 0)
+    const runs = speakerRuns(sequence, label)
+    const unattributed = UNATTRIBUTED.has(label)
+
+    const thrashesWith: ThrashPair[] = []
+    if (!unattributed) {
+      for (const other of named) {
+        if (other === label) continue
+        const p = pairFlipRate(sequence, label, other)
+        if (!p) continue
+        if (p.flipRate > THRASH_FLIP_RATE && p.meanRun < THRASH_MEAN_RUN) {
+          thrashesWith.push({
+            speaker: other,
+            flipRate: Math.round(p.flipRate * 1000) / 1000,
+            meanRun: Math.round(p.meanRun * 100) / 100,
+            sharedSegments: p.sharedSegments,
+          })
+        }
+      }
+      thrashesWith.sort((a, b) => b.flipRate - a.flipRate)
+    }
+
+    const meanSim = sims.length ? Math.round(mean(sims) * 1000) / 1000 : null
+    const reliability: Reliability = unattributed
+      ? 'unattributed'
+      : thrashesWith.length > 0
+        ? 'unreliable'
+        : (meanSim ?? 0) >= CONFIDENT_SIMILARITY ? 'confident' : 'weak'
+
+    return {
+      label,
+      segments: own.length,
+      meanSimilarity: meanSim,
+      meanRun: Math.round(mean(runs) * 100) / 100,
+      longestRun: runs.length ? Math.max(...runs) : 0,
+      isOwner: label === owner,
+      reliability,
+      thrashesWith,
+      phrases: selectPhrases(chunks, label, limit, durationMs),
+    }
+  })
+
+  voices.sort((a, b) => b.segments - a.segments)
+  return { segments: chunks.length, attributed: named.length > 0, durationMs, voices }
+}

package/server/lib/meeting-store.ts

@@ -8,6 +8,7 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  readSync,
   readdirSync,
   realpathSync,
   unlinkSync,
@@ -43,6 +44,11 @@ export class MeetingStoreError extends Error {
 
 export interface MeetingMeta {
   filename: string
+  /** From the chunk sidecar, absent on meetings saved without one. Carried so a
+   *  list row can open the per-meeting speaker review, which is keyed on the
+   *  session rather than the filename — the session is what lets the store's
+   *  own hardened lookup find the sidecar again. */
+  sessionId?: string
   title: string
   date: string
   domain: string
@@ -314,7 +320,7 @@ export function boundedMeetingSource(content: string): { sourceContent: string;
   return { sourceContent: bytes.subarray(0, end).toString('utf8'), sourceTruncated: true }
 }
 
-function toMeta(detail: MeetingDetail): MeetingMeta {
+function toMeta(detail: MeetingDetail, sessionId?: string): MeetingMeta {
   const detailCharEstimate = [
     detail.title,
     detail.date,
@@ -327,6 +333,7 @@ function toMeta(detail: MeetingDetail): MeetingMeta {
   ].join('\n\n').trim().length
   return {
     filename: detail.filename,
+    ...(sessionId ? { sessionId } : {}),
     title: detail.title,
     date: detail.date,
     domain: detail.domain,
@@ -344,6 +351,9 @@ function toMeta(detail: MeetingDetail): MeetingMeta {
   }
 }
 
+/** Enough to clear the sidecar's leading metadata keys whatever their order. */
+const SIDECAR_HEAD_BYTES = 4096
+
 function isContained(parent: string, child: string): boolean {
   return child === parent || child.startsWith(`${parent}${sep}`)
 }
@@ -542,7 +552,7 @@ export class MeetingStore {
           if (content === null) continue
           const detail = parseMeeting(content, filename, month)
           if (domain !== 'all' && detail.domain !== domain) continue
-          meetings.push(toMeta(detail))
+          meetings.push(toMeta(detail, this.sidecarSessionId(monthDir, monthReal, filename)))
         } catch {
           // One unreadable/corrupt entry must not hide the rest of the store.
         }
@@ -601,6 +611,51 @@ export class MeetingStore {
     return this.safeReadFile(monthDir, monthReal, filename)
   }
 
+  /** Read only the first `bytes` of a file, with the same symlink,
+   *  containment, and O_NOFOLLOW guards as safeReadFile.
+   *
+   *  Exists so `list()` can lift one field out of a chunk sidecar without
+   *  reading it whole: sidecars run to megabytes (1.3 MB for a 32-minute
+   *  meeting) and would also trip safeReadFile's MAX_MEETING_BYTES cap, which
+   *  is sized for markdown. */
+  private safeReadFileHead(monthDir: string, monthReal: string, filename: string, bytes: number): string | null {
+    const filepath = join(monthDir, filename)
+    let fd: number | null = null
+    try {
+      const linkStat = lstatSync(filepath)
+      if (linkStat.isSymbolicLink() || !linkStat.isFile()) return null
+      const real = realpathSync(filepath)
+      if (!isContained(monthReal, real) || dirname(real) !== monthReal) return null
+      fd = openSync(filepath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+      const stat = fstatSync(fd)
+      if (!stat.isFile()) return null
+      const buffer = Buffer.alloc(Math.min(bytes, stat.size))
+      if (buffer.length === 0) return ''
+      const read = readSync(fd, buffer, 0, buffer.length, 0)
+      return buffer.subarray(0, read).toString('utf8')
+    } catch {
+      return null
+    } finally {
+      if (fd !== null) {
+        try { closeSync(fd) } catch { /* already closed */ }
+      }
+    }
+  }
+
+  /** The sessionId recorded in a meeting's chunk sidecar, if it has one.
+   *
+   *  Matched with a regex over the file's head rather than JSON.parse: the goal
+   *  is one small field, and parsing a megabyte of chunks per list row to reach
+   *  it would make listing cost scale with total transcript size. */
+  private sidecarSessionId(monthDir: string, monthReal: string, meetingFilename: string): string | undefined {
+    const sidecarName = meetingFilename.replace(/\.md$/, '.g2-chunks.json')
+    if (sidecarName === meetingFilename) return undefined
+    const head = this.safeReadFileHead(monthDir, monthReal, sidecarName, SIDECAR_HEAD_BYTES)
+    if (!head) return undefined
+    const match = head.match(/"sessionId"\s*:\s*"([A-Za-z0-9:_-]{3,96})"/)
+    return match ? match[1] : undefined
+  }
+
   private safeReadFile(monthDir: string, monthReal: string, filename: string): string | null {
     const filepath = join(monthDir, filename)
     let fd: number | null = null

package/server/lib/speaker-calibration-log.ts

@@ -62,6 +62,66 @@ export function filterCalibrationRows(
   return { text: kept.length > 0 ? kept.join('\n') + '\n' : '', result }
 }
 
+/**
+ * Rename a speaker across the log, for a profile merge.
+ *
+ * Relabel rather than delete: a merge means the two names were always one
+ * person, so their calibration history is one history. Dropping the absorbed
+ * name's rows would silently discard exactly the evidence needed to tell
+ * whether the merge improved identification.
+ */
+export function relabelCalibrationRows(
+  raw: string,
+  fromName: string,
+  toName: string,
+): { text: string; relabeled: number; retained: number; unparsable: number } {
+  const out: string[] = []
+  let relabeled = 0, retained = 0, unparsable = 0
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    let row: Record<string, unknown>
+    try {
+      row = JSON.parse(line) as Record<string, unknown>
+    } catch {
+      unparsable++; retained++; out.push(line); continue
+    }
+    // `retained` counts every row that survives, relabeled or not, so
+    // `retained === total input rows` is the invariant a caller can assert: a
+    // merge must never lose history. (Contrast filterCalibrationRows, where
+    // removed + retained = total.)
+    retained++
+    if (row.speaker === fromName) {
+      row.speaker = toName
+      relabeled++
+      out.push(JSON.stringify(row))
+    } else {
+      out.push(line)
+    }
+  }
+  return { text: out.length > 0 ? out.join('\n') + '\n' : '', relabeled, retained, unparsable }
+}
+
+/** Apply a merge relabel to the log on disk. */
+export function relabelSpeakerCalibrationRows(
+  logPath: string,
+  fromName: string,
+  toName: string,
+  options: { dryRun?: boolean } = {},
+): { relabeled: number; retained: number; unparsable: number } {
+  if (!existsSync(logPath)) return { relabeled: 0, retained: 0, unparsable: 0 }
+  let raw: string
+  try {
+    raw = readFileSync(logPath, 'utf-8')
+  } catch {
+    return { relabeled: 0, retained: 0, unparsable: 0 }
+  }
+  const { text, relabeled, retained, unparsable } = relabelCalibrationRows(raw, fromName, toName)
+  if (relabeled > 0 && !options.dryRun) {
+    durableAtomicWriteFileSync(logPath, text, { mode: 0o600 })
+  }
+  return { relabeled, retained, unparsable }
+}
+
 /** Rewrite the log without a given speaker's rows. */
 export function purgeSpeakerCalibrationRows(
   logPath: string,

package/server/lib/speaker-embeddings.ts

@@ -12,6 +12,8 @@ import { existsSync, appendFileSync, mkdirSync, statSync, openSync, readSync, cl
 import {
   appendEmbedding,
   deleteProfileFromStore,
+  mergeProfilesInStore,
+  profileSimilarity,
   describeRepairs,
   dropOldestEmbedding,
   hasRepairs,
@@ -463,6 +465,108 @@ export function clearSpeakerEmbeddings(name: string): boolean {
   return writeProfileStore(store)
 }
 
+/** The floor a merge must clear on centroid cosine.
+ *
+ *  Set at the search-accept threshold on purpose: if two profiles are further
+ *  apart than the value at which identification would accept a match between
+ *  them, they are not the same voice and merging them would poison both. */
+export const MERGE_SIMILARITY_FLOOR = SEARCH_THRESHOLD
+
+export interface MergeReport {
+  into: string
+  merged: string[]
+  missing: string[]
+  similarity: Record<string, number>
+  samplesBefore: number
+  samplesAfter: number
+  droppedToCap: number
+  refused?: { name: string; similarity: number; floor: number }[]
+}
+
+/**
+ * Fold profiles together — two names for one person, e.g. "Luke H" and
+ * "Luke Henry" at 0.843.
+ *
+ * Fails closed below MERGE_SIMILARITY_FLOOR unless `force`. That guard is the
+ * whole safety story: a wrong merge destroys BOTH identities at once, and the
+ * only evidence that two names are one person is acoustic, never the names
+ * themselves.
+ */
+export function mergeSpeakerProfiles(
+  into: string,
+  from: string[],
+  options: { force?: boolean; dryRun?: boolean } = {},
+): MergeReport {
+  const store = loadProfileStore()
+  const target = store.profiles.find(p => p.name === into)
+  const report: MergeReport = {
+    into,
+    merged: [],
+    missing: [],
+    similarity: {},
+    samplesBefore: target?.embeddings.length ?? 0,
+    samplesAfter: target?.embeddings.length ?? 0,
+    droppedToCap: 0,
+  }
+  if (!target) {
+    report.missing = [into]
+    return report
+  }
+
+  // Score every candidate first so a dry run and a refusal report the same
+  // numbers the real merge would act on.
+  const eligible: string[] = []
+  const refused: { name: string; similarity: number; floor: number }[] = []
+  for (const name of from) {
+    if (name === into) continue
+    const source = store.profiles.find(p => p.name === name)
+    if (!source) { report.missing.push(name); continue }
+    const similarity = profileSimilarity(target, source)
+    report.similarity[name] = Math.round(similarity * 1000) / 1000
+    if (similarity < MERGE_SIMILARITY_FLOOR && !options.force) {
+      refused.push({ name, similarity: report.similarity[name], floor: MERGE_SIMILARITY_FLOOR })
+      continue
+    }
+    eligible.push(name)
+  }
+  if (refused.length > 0) report.refused = refused
+  if (eligible.length === 0) return report
+
+  if (options.dryRun) {
+    // Report on a throwaway copy so nothing is mutated by a preview.
+    const preview = JSON.parse(JSON.stringify(store)) as ProfileStore
+    const outcome = mergeProfilesInStore(preview, into, eligible, { cap: MAX_EMBEDDINGS_PER_SPEAKER })
+    report.merged = outcome.mergedFrom
+    report.samplesAfter = outcome.samplesAfter
+    report.droppedToCap = outcome.droppedToCap
+    return report
+  }
+
+  const outcome = mergeProfilesInStore(store, into, eligible, { cap: MAX_EMBEDDINGS_PER_SPEAKER })
+  report.merged = outcome.mergedFrom
+  report.samplesAfter = outcome.samplesAfter
+  report.droppedToCap = outcome.droppedToCap
+
+  // Manager first: drop the absorbed names so a stale centroid cannot keep
+  // winning searches after its profile is gone, then re-register the target
+  // from its new combined sample set.
+  //
+  // Routed through rebuildSpeakerInManager rather than an inline
+  // contains()/remove() pair: that helper already removes-then-returns on an
+  // empty sample list, so this is the one manager-mutation path in the file
+  // instead of a second one that could drift. NOTE: the manager is absent in
+  // tests (no 26 MB model), so this side effect has no test seam — the reason
+  // it is expressed as a single reused call rather than bespoke logic.
+  for (const name of outcome.mergedFrom) rebuildSpeakerInManager(name, [])
+  rebuildSpeakerInManager(into, target.embeddings)
+  writeProfileStore(store)
+  console.log(
+    `[speaker] Merged ${outcome.mergedFrom.join(', ')} into "${into}"`,
+    `(${report.samplesBefore} + absorbed → ${report.samplesAfter}, ${report.droppedToCap} dropped to cap)`,
+  )
+  return report
+}
+
 /** Remove a person entirely: profile, embeddings, and manager registration.
  *  Returns counts so a caller can report what was actually removed. */
 export function removeSpeakerProfile(name: string): { removedProfiles: number; removedEmbeddings: number } {

package/server/lib/voice-profile-store.ts

@@ -347,6 +347,148 @@ export function removeEmbeddingsBySource(
   return removed
 }
 
+/** Cosine similarity between two raw rows. Local so this module stays free of
+ *  the sherpa runtime and can be unit-tested without a 26 MB model. */
+export function rowCosine(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0
+  let dot = 0, na = 0, nb = 0
+  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i] }
+  const denom = Math.sqrt(na) * Math.sqrt(nb)
+  return denom > 0 ? dot / denom : 0
+}
+
+/** L2-normalized mean of the rows that share the modal dimension. */
+export function profileCentroid(embeddings: number[][]): number[] {
+  const dim = modalDimension(embeddings)
+  if (dim === 0) return []
+  const usable = embeddings.filter(row => row.length === dim)
+  if (usable.length === 0) return []
+  const c = new Array<number>(dim).fill(0)
+  for (const row of usable) for (let i = 0; i < dim; i++) c[i] += row[i]
+  for (let i = 0; i < dim; i++) c[i] /= usable.length
+  const norm = Math.sqrt(c.reduce((sum, v) => sum + v * v, 0))
+  return norm > 0 ? c.map(v => v / norm) : c
+}
+
+/** How close two profiles' centroids are. This is the number a merge must be
+ *  justified by: names are not evidence, and `Miles Mallard` / `Manoj Kumar`
+ *  are different humans who would merge happily on a name heuristic. */
+export function profileSimilarity(a: VoiceProfile, b: VoiceProfile): number {
+  return rowCosine(profileCentroid(a.embeddings), profileCentroid(b.embeddings))
+}
+
+/** Pick the N most acoustically diverse samples, carrying provenance along.
+ *
+ *  A merge routinely produces more samples than the per-speaker cap (two
+ *  capped profiles make 40 against a cap of 20), and which 20 survive matters:
+ *  taking the first N would keep one profile's acoustic conditions and discard
+ *  the other's, which is the opposite of what merging is for. Greedy
+ *  max-min-distance keeps the spread.
+ *
+ *  Returns indices so the caller can slice embeddings and sources together. */
+export function selectDiverseIndices(embeddings: number[][], maxN: number): number[] {
+  if (embeddings.length <= maxN) return embeddings.map((_, i) => i)
+
+  // Seed with the two most dissimilar rows.
+  let worstPair = Number.POSITIVE_INFINITY, seedA = 0, seedB = 1
+  for (let i = 0; i < embeddings.length; i++) {
+    for (let j = i + 1; j < embeddings.length; j++) {
+      const sim = rowCosine(embeddings[i], embeddings[j])
+      if (sim < worstPair) { worstPair = sim; seedA = i; seedB = j }
+    }
+  }
+  const chosen = [seedA, seedB]
+  const taken = new Set(chosen)
+  while (chosen.length < maxN) {
+    let best = -1, bestMinDist = -Infinity
+    for (let i = 0; i < embeddings.length; i++) {
+      if (taken.has(i)) continue
+      let minDist = Infinity
+      for (const c of chosen) {
+        const dist = 1 - rowCosine(embeddings[i], embeddings[c])
+        if (dist < minDist) minDist = dist
+      }
+      if (minDist > bestMinDist) { bestMinDist = minDist; best = i }
+    }
+    if (best === -1) break
+    chosen.push(best)
+    taken.add(best)
+  }
+  // Ascending so the surviving order still reflects enrollment order.
+  return chosen.sort((x, y) => x - y)
+}
+
+export interface MergeOutcome {
+  /** Centroid cosine between the target and each source, before merging. */
+  similarity: Record<string, number>
+  samplesBefore: number
+  samplesAfter: number
+  /** Samples discarded by the cap, not by the merge itself. */
+  droppedToCap: number
+  mergedFrom: string[]
+  missing: string[]
+}
+
+/**
+ * Fold one or more profiles into another.
+ *
+ * Provenance is deliberately PRESERVED rather than restamped `merged:*`: the
+ * per-source retraction path is what makes a poisoned `auto:<sessionId>` sample
+ * removable later, and overwriting it to record a bookkeeping event would trade
+ * a useful fact for a useless one.
+ */
+export function mergeProfilesInStore(
+  store: ProfileStore,
+  into: string,
+  from: string[],
+  options: { cap?: number } = {},
+): MergeOutcome {
+  const cap = options.cap ?? 20
+  const target = store.profiles.find(p => p.name === into)
+  const outcome: MergeOutcome = {
+    similarity: {},
+    samplesBefore: target?.embeddings.length ?? 0,
+    samplesAfter: target?.embeddings.length ?? 0,
+    droppedToCap: 0,
+    mergedFrom: [],
+    missing: [],
+  }
+  if (!target) {
+    outcome.missing = [into, ...from]
+    return outcome
+  }
+
+  const embeddings = [...target.embeddings]
+  const sources = [...(target.sources ?? [])]
+  while (sources.length < embeddings.length) sources.push(UNKNOWN_SOURCE)
+
+  for (const name of from) {
+    if (name === into) continue
+    const source = store.profiles.find(p => p.name === name)
+    if (!source) { outcome.missing.push(name); continue }
+    outcome.similarity[name] = profileSimilarity(target, source)
+    const sourceSources = [...(source.sources ?? [])]
+    while (sourceSources.length < source.embeddings.length) sourceSources.push(UNKNOWN_SOURCE)
+    for (let i = 0; i < source.embeddings.length; i++) {
+      embeddings.push(source.embeddings[i])
+      sources.push(sourceSources[i] ?? UNKNOWN_SOURCE)
+    }
+    outcome.mergedFrom.push(name)
+  }
+
+  if (outcome.mergedFrom.length === 0) return outcome
+
+  const keep = selectDiverseIndices(embeddings, cap)
+  outcome.droppedToCap = embeddings.length - keep.length
+  target.embeddings = keep.map(i => embeddings[i])
+  target.sources = keep.map(i => sources[i])
+  outcome.samplesAfter = target.embeddings.length
+
+  const removed = new Set(outcome.mergedFrom)
+  store.profiles = store.profiles.filter(p => !removed.has(p.name))
+  return outcome
+}
+
 /** Delete a person's profile outright. Returns what was removed so the caller
  *  can report a per-store count instead of a bare success. */
 export function deleteProfileFromStore(

package/server/routes/meeting.ts

@@ -2,7 +2,7 @@
 // the standalone public meeting store. The live transcript and chunk metadata
 // are durable before the session is closed; batch improvement runs afterward.
 
-import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { Router } from 'express'
 import { emitDisplay } from '../lib/display-bus.js'
@@ -64,6 +64,8 @@ import {
   type TranscriptGapReport,
 } from './transcribe-stream.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
+import { getOwnerSpeakerLabel } from '../lib/profile.js'
+import { reviewMeetingSpeakers, type ReviewChunk } from '../lib/meeting-speaker-review.js'
 import {
   acquireMaintenanceWork,
   maintenanceAdmissionsOpen,
@@ -613,6 +615,59 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
     }
   })
 
+  // ── Speaker review (6.21.12) ──────────────────────────────────────────
+  // Backs COS Control's naming panel. Read-only: it reports what a saved
+  // meeting's sidecar already contains and never writes. Naming, merging, and
+  // rebuilding are the /api/voice/* routes, each with its own confirmation.
+  //
+  // Keyed on sessionId so it can reuse the store's traversal-hardened readers
+  // (safeDirectoryRealpath / safeReadFile) instead of reassembling a path from
+  // client-supplied domain and filename components.
+  router.get('/meeting/:sessionId/speakers', (req, res) => {
+    const sessionId = String(req.params.sessionId ?? '')
+    if (!/^[A-Za-z0-9:_-]{3,96}$/.test(sessionId)) {
+      res.status(400).json({ error: 'Invalid sessionId', reason: 'invalid_session_id' })
+      return
+    }
+    const saved = store.findBySessionId(sessionId)
+    if (!saved) {
+      res.status(404).json({ error: 'No saved meeting for this session', reason: 'meeting_not_found' })
+      return
+    }
+
+    let chunks: unknown
+    try {
+      const raw = JSON.parse(readFileSync(saved.sidecarPath, 'utf-8')) as Record<string, unknown>
+      chunks = Array.isArray(raw) ? raw : raw.chunks
+    } catch {
+      // Defensive: findBySessionId already parsed this sidecar to match the
+      // session, so a corrupt file 404s above and never reaches here. This
+      // covers the narrow race where it becomes unreadable in between. Either
+      // way the answer is never 200-with-no-voices, which would read as
+      // "nobody spoke" and invite naming voices that were never analysed.
+      res.status(422).json({ error: 'Chunk sidecar is missing or unreadable', reason: 'sidecar_unreadable' })
+      return
+    }
+    if (!Array.isArray(chunks)) {
+      res.status(422).json({ error: 'Chunk sidecar holds no chunk array', reason: 'sidecar_empty' })
+      return
+    }
+
+    const review = reviewMeetingSpeakers(chunks as ReviewChunk[], {
+      owner: getOwnerSpeakerLabel(),
+      phrasesPerVoice: Math.max(1, Math.min(6, Number(req.query.phrases) || 3)),
+    })
+    res.set('Cache-Control', 'private, no-store')
+    res.json({
+      sessionId,
+      title: saved.title,
+      domain: saved.domain,
+      filename: saved.filename,
+      durationMin: saved.durationMin,
+      ...review,
+    })
+  })
+
   // ── Unsaved-capture recovery (6.19.0) ─────────────────────────────────
   // Surface-only by decision (Miles, 2026-08-02): the server NEVER drives
   // recovery on its own. It lists what the quarantine holds, and one

package/server/routes/voice.ts

@@ -4,12 +4,12 @@ import { Router } from 'express'
 import { errMsg } from '../lib/utils.js'
 import { readdirSync, readFileSync, unlinkSync, existsSync, rmdirSync, rmSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { enrollSpeaker, isEnrolled, getAllSpeakerNames, identifySpeaker, extractEmbedding, enrollEmbedding, rawCosineSimilarity, getEmbeddingCount, removeSpeakerProfile, readVoiceProfiles } from '../lib/speaker-embeddings.js'
+import { enrollSpeaker, isEnrolled, getAllSpeakerNames, identifySpeaker, extractEmbedding, enrollEmbedding, rawCosineSimilarity, getEmbeddingCount, removeSpeakerProfile, readVoiceProfiles, mergeSpeakerProfiles } from '../lib/speaker-embeddings.js'
 import { statSync } from 'node:fs'
 import { trainFromFireflies, getTrainingStatus } from '../lib/speaker-trainer.js'
 import { getOwnerSpeakerLabel } from '../lib/profile.js'
 import { dataPath } from '../lib/data-dir.js'
-import { purgeSpeakerCalibrationRows } from '../lib/speaker-calibration-log.js'
+import { purgeSpeakerCalibrationRows, relabelSpeakerCalibrationRows } from '../lib/speaker-calibration-log.js'
 
 // These MUST match the writer in transcribe-stream.ts, which saves under
 // dataPath(). They previously resolved relative to __dirname — i.e. inside the
@@ -444,6 +444,85 @@ voiceRouter.get('/voice/profiles', (_req, res) => {
   }
 })
 
+// POST /api/voice/merge-profiles — fold two names for one person together.
+// Body: { into, from: string[]|string, confirm: true, dryRun?, force? }
+//
+// Two profiles for one voice is worse than it looks: the sherpa manager holds
+// one centroid per NAME, so both compete on every search and each is capped at
+// 20 samples independently — 40 samples of one person, split, each half a
+// weaker representation of them than the union would be.
+//
+// Fails closed below the search-accept threshold. A wrong merge destroys BOTH
+// identities at once and cannot be undone from the store alone, so the only
+// acceptable evidence is acoustic. `force` exists for the case where Miles
+// knows something the audio does not, and it is logged.
+voiceRouter.post('/voice/merge-profiles', (req, res) => {
+  try {
+    const into = typeof req.body?.into === 'string' ? req.body.into.trim() : ''
+    const rawFrom = req.body?.from
+    const from = (Array.isArray(rawFrom) ? rawFrom : [rawFrom])
+      .filter((n: unknown): n is string => typeof n === 'string' && n.trim().length > 0)
+      .map((n: string) => n.trim())
+
+    if (!into || from.length === 0) {
+      return res.status(400).json({ error: 'into (string) and from (string or string[]) are required' })
+    }
+    if (from.includes(into)) {
+      return res.status(400).json({ error: 'into and from must differ' })
+    }
+
+    const owner = getOwnerSpeakerLabel()
+    if (from.includes(owner)) {
+      // Absorbing the owner label would delete the profile the live
+      // identification path checks FIRST, on every chunk.
+      return res.status(400).json({
+        error: `refusing to absorb the owner label "${owner}" — merge INTO it instead`,
+      })
+    }
+
+    const dryRun = req.body?.dryRun === true
+    const force = req.body?.force === true
+
+    if (req.body?.confirm !== true && !dryRun) {
+      const preview = mergeSpeakerProfiles(into, from, { force, dryRun: true })
+      return res.status(400).json({
+        error: 'confirmation required',
+        message: `Merging is not reversible from the store alone. Review the similarity scores, then pass { confirm: true }.`,
+        preview,
+      })
+    }
+
+    const report = mergeSpeakerProfiles(into, from, { force, dryRun })
+
+    if (report.missing.length > 0 && report.merged.length === 0) {
+      return res.status(404).json({ error: 'no such profile(s)', missing: report.missing, report })
+    }
+    if (report.refused && report.merged.length === 0) {
+      return res.status(409).json({
+        error: 'similarity below the merge floor',
+        message: 'These centroids are further apart than the threshold at which identification would '
+          + 'accept a match between them, so they are probably different people. Pass { force: true } '
+          + 'only if you know they are the same person.',
+        report,
+      })
+    }
+
+    // Relabel rather than drop the absorbed name's calibration history: after a
+    // merge it is one person's history, and it is the only evidence for whether
+    // the merge improved identification.
+    const calibration: Record<string, number> = {}
+    if (!dryRun) {
+      for (const name of report.merged) {
+        calibration[name] = relabelSpeakerCalibrationRows(CALIBRATION_LOG, name, into).relabeled
+      }
+    }
+
+    res.json({ ...report, dryRun, forced: force, calibrationRowsRelabeled: calibration })
+  } catch (err: unknown) {
+    res.status(500).json({ error: errMsg(err) })
+  }
+})
+
 // POST /api/voice/delete-person — remove one person from every store that
 // carries their name. Body: { name, confirm: true, dryRun? }
 //