@gotcos/glasses-server 6.45.2 → 6.45.4

package/server/lib/workspace-skills.ts

@@ -0,0 +1,209 @@
+// Catalog of skills the glasses agent can actually run: the selected COS
+// workspace plus the user's global Claude skills. Labels only — never paths.
+//
+// Walk matches skill_sync.py: `.agents/skills` is canonical (nested folders
+// flatten with `:`), `.claude/skills` is a one-level mirror, `source-command-*`
+// is excluded as a generated duplicate. User skills live in `~/.claude/skills`.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join, relative } from 'node:path'
+import { COS_SCRIPTS_DIR } from './python-bridge.js'
+import { resolveProviderWorkDir } from './launch-dir.js'
+
+export const SKILLS_CATALOG_SCHEMA = 1
+export const SKILLS_CATALOG_MAX = 200
+const SKILL_FILE_MAX_BYTES = 8_192
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/
+const EXCLUDE_PREFIXES = ['source-command-']
+
+export interface WorkspaceSkill {
+  name: string
+  slash: string
+  description: string
+  group: string
+  where: 'workspace' | 'user'
+}
+
+export interface WorkspaceSkillsCatalog {
+  schemaVersion: number
+  skills: WorkspaceSkill[]
+}
+
+export function parseSkillFrontmatter(text: string): Record<string, string> {
+  const src = text.replace(/^\uFEFF/, '')
+  if (!src.startsWith('---')) return {}
+  const end = src.indexOf('\n---', 3)
+  if (end < 0) return {}
+  const block = src.slice(3, end).replace(/^\r?\n/, '')
+  const out: Record<string, string> = {}
+  const lines = block.split(/\r?\n/)
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    const match = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line)
+    if (!match) { i += 1; continue }
+    const key = match[1]
+    let raw = match[2].trim()
+    if (raw === '>' || raw === '>-' || raw === '|' || raw === '|-') {
+      const parts: string[] = []
+      i += 1
+      while (i < lines.length && /^\s+\S/.test(lines[i]) && !/^[A-Za-z_][\w-]*:/.test(lines[i])) {
+        parts.push(lines[i].trim())
+        i += 1
+      }
+      out[key] = unquote(parts.join(' '))
+      continue
+    }
+    out[key] = unquote(raw)
+    i += 1
+  }
+  return out
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim()
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'").trim()
+  }
+  return trimmed
+}
+
+function excludedName(name: string): boolean {
+  return EXCLUDE_PREFIXES.some(prefix => name === prefix.slice(0, -1) || name.startsWith(prefix))
+}
+
+function skillNameFromRel(rel: string): string | null {
+  const parts = rel.split(/[/\\]/).filter(part => part && part !== '.')
+  if (parts.length === 0 || parts.some(part => part.startsWith('.') || excludedName(part))) return null
+  const name = parts.join(':')
+  return SKILL_NAME_RE.test(name) ? name : null
+}
+
+function readSkillFile(path: string): { name?: string; description: string } | null {
+  let stat
+  try { stat = statSync(path) } catch { return null }
+  if (!stat.isFile() || stat.size <= 0) return null
+  const bytes = Math.min(stat.size, SKILL_FILE_MAX_BYTES)
+  let text: string
+  try {
+    text = readFileSync(path, { encoding: 'utf8' }).slice(0, bytes)
+  } catch {
+    return null
+  }
+  const meta = parseSkillFrontmatter(text)
+  const description = (meta.description || '').replace(/\s+/g, ' ').trim().slice(0, 160)
+  const name = meta.name && SKILL_NAME_RE.test(meta.name) && !excludedName(meta.name) ? meta.name : undefined
+  return { name, description }
+}
+
+function walkImmediateSkills(root: string): Array<{ rel: string; path: string }> {
+  let entries
+  try { entries = readdirSync(root, { withFileTypes: true }) } catch { return [] }
+  const found: Array<{ rel: string; path: string }> = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const path = join(root, entry.name, 'SKILL.md')
+    if (existsSync(path)) found.push({ rel: entry.name, path })
+  }
+  return found
+}
+
+function walkNestedSkills(root: string): Array<{ rel: string; path: string }> {
+  const found: Array<{ rel: string; path: string }> = []
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()!
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { continue }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        stack.push(full)
+        continue
+      }
+      if (entry.isFile() && entry.name === 'SKILL.md') {
+        const rel = relative(root, dir)
+        if (rel && rel !== '.') found.push({ rel, path: full })
+      }
+    }
+  }
+  return found
+}
+
+function groupFor(name: string, where: WorkspaceSkill['where']): string {
+  const colon = name.indexOf(':')
+  if (colon > 0) return name.slice(0, colon).replace(/[-_]/g, ' ').toUpperCase()
+  return where === 'user' ? 'USER' : 'WORKSPACE'
+}
+
+function addSkill(
+  seen: Map<string, WorkspaceSkill>,
+  rel: string,
+  path: string,
+  where: WorkspaceSkill['where'],
+): void {
+  if (seen.size >= SKILLS_CATALOG_MAX) return
+  const fromDir = skillNameFromRel(rel)
+  if (!fromDir) return
+  const parsed = readSkillFile(path)
+  if (!parsed) return
+  // Directory name is the loader identity. Frontmatter `name` is a label; if it
+  // disagrees with the folder (common on generated mirrors), keep the folder.
+  const name = parsed.name && basename(rel) === parsed.name ? parsed.name : fromDir
+  if (seen.has(name) || excludedName(name)) return
+  seen.set(name, {
+    name,
+    slash: `/${name}`,
+    description: parsed.description,
+    group: groupFor(name, where),
+    where,
+  })
+}
+
+export function listWorkspaceSkills(options: {
+  workDir?: string
+  home?: string
+} = {}): WorkspaceSkill[] {
+  const workDir = options.workDir ?? resolveProviderWorkDir({ scriptsDir: COS_SCRIPTS_DIR })
+  const home = options.home ?? homedir()
+  const seen = new Map<string, WorkspaceSkill>()
+
+  if (workDir) {
+    const agents = join(workDir, '.agents', 'skills')
+    if (existsSync(agents)) {
+      for (const skill of walkNestedSkills(agents)) addSkill(seen, skill.rel, skill.path, 'workspace')
+    }
+    const claude = join(workDir, '.claude', 'skills')
+    if (existsSync(claude)) {
+      for (const skill of walkImmediateSkills(claude)) addSkill(seen, skill.rel, skill.path, 'workspace')
+    }
+  }
+
+  const userClaude = join(home, '.claude', 'skills')
+  if (existsSync(userClaude)) {
+    for (const skill of walkImmediateSkills(userClaude)) addSkill(seen, skill.rel, skill.path, 'user')
+  }
+
+  return [...seen.values()].sort((a, b) => {
+    if (a.group !== b.group) {
+      if (a.group === 'WORKSPACE') return -1
+      if (b.group === 'WORKSPACE') return 1
+      if (a.group === 'USER') return 1
+      if (b.group === 'USER') return -1
+      return a.group.localeCompare(b.group)
+    }
+    return a.name.localeCompare(b.name)
+  })
+}
+
+export function workspaceSkillsCatalog(options?: {
+  workDir?: string
+  home?: string
+}): WorkspaceSkillsCatalog {
+  return {
+    schemaVersion: SKILLS_CATALOG_SCHEMA,
+    skills: listWorkspaceSkills(options),
+  }
+}

package/server/routes/archive.ts

@@ -2,6 +2,7 @@
 import { Router } from 'express'
 import { listArchiveDateStrings, archiveDir, archiveIndexPath, loadArchive, getArchiveChats, getArchiveDayMessages, appendToArchive } from '../lib/archive.js'
 import { getArchiveChatMessagesNumbered } from './message-ref.js'
+import { ensureArchiveMirrorForDay } from '../lib/conversation.js'
 import { searchArchive, MAX_LIMIT, DEFAULT_LIMIT } from '../lib/archive-search.js'
 import { refreshArchiveIndex } from '../lib/archive-index.js'
 import { getActiveSessions } from '../lib/conversation.js'
@@ -24,6 +25,8 @@ archiveRouter.param('date', (req, res, next, date) => {
 
 // GET /api/archive — list all archive dates with summaries
 archiveRouter.get('/archive', async (_req, res) => {
+  // 6.45.3 — the listing files yesterday's finished sessions before it answers.
+  await ensureArchiveMirrorForDay().catch(() => {})
   // Index-backed. The previous implementation parsed every day file to reach four
   // summary fields; see archive-index.ts for the measurements that killed it.
   const { entries, rebuilt, fromCache } = await refreshArchiveIndex(archiveDir(), archiveIndexPath())

package/server/routes/prompt-drafts.ts

@@ -16,6 +16,7 @@ import {
   transcriptQualityRank,
   type PromptDraftTranscriptRecord,
 } from '../lib/prompt-draft-store.js'
+import { SPEECH_UNKNOWN, guardPromptTail, speechWindowsFromWav } from '../lib/prompt-tail-guard.js'
 import {
   transcribeAudioBuffer,
   resolveTranscribeMode,
@@ -291,7 +292,15 @@ async function transcribeChunk(draftId: string, chunkIndex: number, audio: Buffe
       const policy = purpose === 'warm' ? 'local-only' as const : 'automatic' as const
       const result = await transcribeAudioBuffer(audio, { mode, policy })
       if (!isCurrentChunk(draftId, chunkIndex, audio)) return ''
-      const text = sanitizeTranscript(draftId, result.text)
+      // 6.45.4 — the sentence Whisper invents after the speaker stops. Never trims
+      // audio; drops a trailing sentence only on the junk lexicon or on silence
+      // plus the decoder's own low confidence (prompt-tail-guard.ts).
+      const guarded = guardPromptTail({ text: result.text, words: result.words, speech: speechWindowsFromWav(audio) })
+      for (const drop of guarded.dropped) {
+        console.warn(`[prompt-draft] tail_drop ${draftId}/${chunkIndex} ${purpose}/${mode} (${drop.reason}, start=${drop.startSec ?? '?'}s, lastSpeech=${guarded.lastSpeechEndSec ?? '?'}s, p=${drop.meanProbability?.toFixed(2) ?? '?'}): "${drop.text.slice(0, 100)}"`)
+      }
+      if (guarded.dropped.length > 0 && !guarded.text.trim()) throw new NoSpeechDetectedError(result.text)
+      const text = sanitizeTranscript(draftId, guarded.text)
       const record: PromptDraftTranscriptRecord = {
         text, hash, requestedMode: result.requestedMode, actualQuality: result.actualQuality,
         backend: result.backend, degraded: result.degraded,
@@ -497,7 +506,9 @@ promptDraftsRouter.post('/prompt-drafts/:draftId/peek', async (req, res) => {
       lease.setPhase('active')
       try {
         const result = await transcribeWhisperPreview(audio)
-        const text = sanitizeTranscript(draftId, result.text, false)
+        // 6.45.4: the same whole-sentence filler rule as the commit path, so an
+        // invented closing line never paints on the lens only to vanish later.
+        const text = sanitizeTranscript(draftId, guardPromptTail({ text: result.text, speech: SPEECH_UNKNOWN }).text, false)
         if (!text) return
         if (!loadPromptDraftMeta(draftId)) return
         emitDisplay({

package/server/routes/sessions.ts

@@ -2,9 +2,10 @@
 import { Router } from 'express'
 import { readFileSync } from 'fs'
 import { join } from 'path'
-import { getRecentSessions, getHistory, sessionExists, addContextBreak, endSession, getSessionRaw, getActiveSessions, resolveExchangePairModel } from '../lib/conversation.js'
+import { getRecentSessions, getHistory, sessionExists, addContextBreak, endSession, getSessionRaw, getActiveSessions, resolveExchangePairModel, ensureArchiveMirrorForDay } from '../lib/conversation.js'
 import { buildSessionLogEntry, writeSessionLog } from '../lib/session-log.js'
-import { getArchiveDayMessages } from '../lib/archive.js'
+import { getArchiveDayMessages, listArchiveDateStrings } from '../lib/archive.js'
+import { recentMessagesLimit, selectRecentMessages } from '../lib/recent-messages.js'
 import { localDay } from '../lib/local-day.js'
 import { clearCodexEngineSession } from '../lib/codex-engine-sessions.js'
 import { mergeMediaAttachmentRefs, type MediaAttachmentRef } from '../../shared/media-attachment.js'
@@ -282,16 +283,23 @@ sessionsRouter.get('/sessions/today/live-chats', (_req, res) => {
   res.json({ chats })
 })
 
-// GET /api/sessions/today/all-messages — merged view of today's archived + live session messages.
-// Dedup key is `sessionId|timestamp` (was bare timestamp, which collided on NTP skew or
-// same-ms adds). `sessionId` is always known for live exchanges; archive messages fall
-// back to the archived chat's sessionId via getArchiveDayMessages.
-sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
+// GET /api/sessions/today/all-messages — the newest messages, live + archived, one window.
+// 6.45.3 — the path keeps its name for the two clients that call it (COS Control's
+// Recent view, the phone's history recovery) but the view is a ROLLING WINDOW of the
+// newest `limit` (default 30, `?limit=` up to 100) across every live session and as many
+// archived days as it takes, not a calendar day. Dedup key is `sessionId|timestamp`
+// (was bare timestamp, which collided on NTP skew or same-ms adds); `sessionId` is
+// always known for live exchanges; archive messages fall back to the archived chat's
+// sessionId via getArchiveDayMessages. `date` stays in the response for compatibility.
+sessionsRouter.get('/sessions/today/all-messages', async (req, res) => {
+  // 6.45.3 — first read after midnight files yesterday before answering.
+  await ensureArchiveMirrorForDay().catch(() => {})
   const todayDate = localDay()
+  const limit = recentMessagesLimit(req.query.limit)
   const activeEra = currentMessageEraState()
   const era = activeEra.era
 
-  const archivedMessages = getArchiveDayMessages(todayDate)
+  const archivedDay = (date: string) => getArchiveDayMessages(date)
     .filter(m => exchangeBelongsToEra(m, era))
     .map(m => {
       const globalMsgNum = m.globalMsgNum ?? m.no
@@ -323,8 +331,7 @@ sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
   }> = []
   const liveSessions = getActiveSessions()
   for (const session of liveSessions) {
-    const sessionDay = localDay(session.lastActivity)
-    if (sessionDay !== todayDate) continue
+    // Every live session, whatever day it last spoke: the window decides, not the calendar.
     for (let i = 0; i < session.exchanges.length; i++) {
       const ex = session.exchanges[i]
       if (ex.role === 'user') {
@@ -358,17 +365,13 @@ sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
     }
   }
 
-  // Merge, dedup by (sessionId, timestamp), sort chronologically.
-  const seen = new Set<string>()
-  const keyOf = (m: { sessionId?: string; timestamp: number }) => `${m.sessionId ?? ''}|${m.timestamp}`
-  const merged = [...archivedMessages, ...liveMessages]
-    .filter(m => {
-      const k = keyOf(m as any)
-      if (seen.has(k)) return false
-      seen.add(k)
-      return true
-    })
-    .sort((a, b) => a.timestamp - b.timestamp)
+  // Newest `limit` across live sessions and archived days (newest day first, read
+  // only while the window is short), dedup by (sessionId, timestamp), chronological.
+  const merged = selectRecentMessages(
+    liveMessages as Array<(typeof liveMessages)[number] | ReturnType<typeof archivedDay>[number]>,
+    listArchiveDateStrings().map(date => () => archivedDay(date)),
+    limit,
+  )
 
-  res.json({ messages: merged, date: todayDate })
+  res.json({ messages: merged, date: todayDate, window: { kind: 'recent', limit } })
 })

package/server/routes/skills.ts

@@ -0,0 +1,13 @@
+// GET /api/skills — slash commands the glasses agent can run from this Mac.
+// Workspace `.agents/skills` (canonical) + `.claude/skills` + `~/.claude/skills`.
+// Authenticated by the /api token middleware. Paths never leave the box.
+
+import { Router } from 'express'
+import { workspaceSkillsCatalog } from '../lib/workspace-skills.js'
+
+export const skillsRouter = Router()
+
+skillsRouter.get('/skills', (_req, res) => {
+  res.set('Cache-Control', 'private, no-store')
+  res.json(workspaceSkillsCatalog())
+})

package/server/routes/transcribe-stream.ts

@@ -39,7 +39,7 @@ import { errMsg } from '../lib/utils.js'
 import { transcribeLocal, applyCorrections, type WhisperWord } from '../lib/whisper-local.js'
 import { enhanceAudio } from '../lib/audio-enhance.js'
 import { trimSilence, isSileroAvailable } from '../lib/vad-silero.js'
-import { identifySpeaker, isEmbeddingAvailable, autoEnroll, getEmbeddingCount } from '../lib/speaker-embeddings.js'
+import { identifySpeaker, isEmbeddingAvailable, autoEnroll, getEmbeddingCount, AUTO_ENROLL_CANDIDATE_SIMILARITY } from '../lib/speaker-embeddings.js'
 import {
   assertOpenAIWhisperBudget,
   recordOpenAIWhisperUsage,
@@ -1157,7 +1157,9 @@ setInterval(() => {
         const dirPath = resolve(EXT_AUDIO_DIR, dir)
         try {
           const files = readdirSync(dirPath)
-          if (files.length === 0) { rmSync(dirPath, { recursive: true, force: true }); continue }
+          // 6.45.4: an emptied session (every held sample named or discarded)
+          // frees its per-session cap too, so the next stranger can be held.
+          if (files.length === 0) { rmSync(dirPath, { recursive: true, force: true }); extAudioCounts.delete(dir); continue }
           const { mtimeMs } = statSync(resolve(dirPath, files[0]))
           if (Date.now() - mtimeMs > EXT_AUDIO_TTL_MS) {
             rmSync(dirPath, { recursive: true, force: true })
@@ -1897,7 +1899,7 @@ function identifyChunkSpeaker(audioBuffer: Buffer, sessionId: string, chunkIndex
     console.log(`[speaker] Embedding: ${speaker} vs Amplitude: ${clientSpeaker} (sim: ${embeddingResult.similarity.toFixed(2)})`)
   }
 
-  if (embeddingResult.similarity >= 0.72 && speaker !== 'Ext') {
+  if (embeddingResult.similarity >= AUTO_ENROLL_CANDIDATE_SIMILARITY && speaker !== 'Ext') {
     const enrollResult = autoEnroll(speaker, audioBuffer, embeddingResult.similarity, sessionId)
     if (enrollResult.enrolled) {
       console.log(`[speaker] Auto-enrolled ${speaker} from G2 mic (sim: ${embeddingResult.similarity.toFixed(3)})`)

package/server/routes/voice.ts

@@ -1,6 +1,6 @@
 // Voice enrollment, status, and multi-speaker training endpoints
 
-import { Router } from 'express'
+import express, { Router } from 'express'
 import { errMsg } from '../lib/utils.js'
 import { readdirSync, readFileSync, unlinkSync, existsSync, rmdirSync, rmSync } from 'node:fs'
 import { resolve } from 'node:path'
@@ -13,9 +13,11 @@ 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 { extAudioChunkPath, listExtAudioChunks } from '../lib/meeting-audio-archive.js'
 import { getVoiceDirectorySnapshot, invalidateVoiceDirectory } from '../lib/voice-directory.js'
 import { greedyDiversitySelect } from '../lib/voice-enrolment-selection.js'
 import { fanOutSpeakerRename, type SpeakerRenameFanOut } from '../lib/speaker-rename-fanout.js'
+import { HeldGroupError, discardHeldSamples, enrollHeldGroup, heldVoiceGroups, parseHeldMembers, previewDiscard } from '../lib/held-voice-groups.js'
 import { resolveCosOperationsDir } from '../lib/cos-operations-meetings.js'
 
 // These MUST match the writer in transcribe-stream.ts, which saves under
@@ -336,6 +338,10 @@ voiceRouter.get('/voice/ext-audio', (_req, res) => {
         chunks: wavFiles.length,
         ageHours: parseFloat(ageHours),
         expiresIn: `${Math.max(0, 72 - parseFloat(ageHours)).toFixed(1)}h`,
+        // 6.45.3 — the chunk indices a reviewer can ask to hear (`?chunk=` on
+        // the sample route). Queen, 2026-09-12: the Add-a-voice panel let her
+        // name a session but not listen to it; naming is a guess without this.
+        chunkIndices: listExtAudioChunks(d.name),
       }
     }).filter(s => s.chunks > 0)
 
@@ -496,6 +502,8 @@ voiceRouter.get('/voice/profiles/:name/sample', (req, res) => {
 })
 
 // GET /api/voice/ext-audio/:sessionId/sample — hear an unidentified voice.
+// 6.45.3 — `?chunk=<index>` picks one held chunk (indices come from the listing's
+// `chunkIndices`); without it the newest chunk is served, as before.
 voiceRouter.get('/voice/ext-audio/:sessionId/sample', (req, res) => {
   res.set('Cache-Control', 'private, no-store')
   const sessionId = String(req.params.sessionId ?? '')
@@ -504,6 +512,21 @@ voiceRouter.get('/voice/ext-audio/:sessionId/sample', (req, res) => {
     res.status(400).json({ error: 'Invalid sessionId', reason: 'invalid_session_id' })
     return
   }
+  const chunkRaw = req.query.chunk
+  if (chunkRaw !== undefined) {
+    const chunkIndex = Number.parseInt(String(chunkRaw), 10)
+    if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
+      res.status(400).json({ error: 'Invalid chunk', reason: 'invalid_chunk' })
+      return
+    }
+    const chunkWav = extAudioChunkPath(sessionId, chunkIndex)
+    if (!chunkWav) {
+      res.status(404).json({ error: 'No ext-audio retained for that chunk', reason: 'no_ext_audio_chunk' })
+      return
+    }
+    sendAudioFile(res, chunkWav)
+    return
+  }
   const wav = existsSync(dirPath) ? newestWav(dirPath) : null
   if (!wav) {
     res.status(404).json({
@@ -515,6 +538,121 @@ voiceRouter.get('/voice/ext-audio/:sessionId/sample', (req, res) => {
   sendAudioFile(res, wav)
 })
 
+// ── Held voices, grouped (6.45.4) ─────────────────────────────────────────
+//
+// The Add-a-voice panel listed held audio by SESSION. A session is not a voice:
+// one meeting holds several strangers, and one stranger recurs across meetings.
+// These three routes work at the grain a reviewer actually names — a GROUP of
+// samples that sound like one person, across the whole retention window — and
+// let the random artifacts be thrown out instead of named. See
+// lib/held-voice-groups.ts for the rule (mutually coherent at the identifier's
+// own floor) and for why the vectors cost no decode in the ordinary case.
+//
+// Both mutations fail closed like every sibling here: without `confirm: true`
+// they answer 400 `confirmation required` with a preview of exactly what would
+// change, and `dryRun: true` returns that preview as a 200. COS Control sends
+// `confirm` after its own two-click gate.
+
+// GET /api/voice/held-groups
+voiceRouter.get('/voice/held-groups', (_req, res) => {
+  try {
+    res.set('Cache-Control', 'private, no-store')
+    res.json(heldVoiceGroups())
+  } catch (err: unknown) {
+    res.status(500).json({ error: errMsg(err) })
+  }
+})
+
+function heldGroupFailure(res: express.Response, err: unknown): void {
+  if (err instanceof HeldGroupError) {
+    res.status(err.status).json({ success: false, error: err.message, reason: err.reason, ...err.details })
+    return
+  }
+  res.status(500).json({ success: false, error: errMsg(err) })
+}
+
+// POST /api/voice/held-groups/enroll — name a group (or any set of held
+// samples) as one person. Body: { name, members: [{ sessionId, chunkIndex }],
+// confirm?: true, dryRun?: true }. A name that already has a profile is
+// APPENDED to: "add more fidelity in samples to a given voice". Only the
+// coherent core is written and only its wavs are removed; samples that were
+// not this voice stay held.
+voiceRouter.post('/voice/held-groups/enroll', (req, res) => {
+  try {
+    const nameCheck = checkSpeakerName(req.body?.name, { ownerLabel: getOwnerSpeakerLabel() })
+    if (!nameCheck.ok) {
+      return res.status(400).json({ success: false, error: nameCheck.message, reason: nameCheck.reason })
+    }
+    const name = String(req.body.name).trim()
+    const members = parseHeldMembers(req.body?.members)
+    const dryRun = req.body?.dryRun === true
+    const confirm = req.body?.confirm === true
+    if (dryRun || !confirm) {
+      const plan = enrollHeldGroup(name, members, { dryRun: true })
+      const verb = plan.created ? 'create' : 'add to'
+      const summary = `Would ${verb} ${name} from ${plan.coherent} of ${plan.resolved} held sample${plan.resolved === 1 ? '' : 's'}`
+        + (plan.leftBehind.length > 0 ? `, leaving ${plan.leftBehind.length} that do not sound like the same person` : '')
+        + (plan.notReady.length > 0 ? `, with ${plan.notReady.length} still being read` : '')
+        + `, and delete the audio it used.`
+      if (dryRun) return res.json({ success: true, ...plan, message: summary })
+      return res.status(400).json({
+        success: false,
+        error: 'confirmation required',
+        reason: 'confirmation_required',
+        message: `${summary} Pass { confirm: true } to proceed.`,
+        preview: plan,
+      })
+    }
+    const result = enrollHeldGroup(name, members)
+    invalidateVoiceDirectory()
+    const verb = result.created ? 'Created' : 'Added to'
+    res.json({
+      success: true,
+      ...result,
+      message: result.leftBehind.length > 0
+        ? `${verb} ${name} from ${result.coherent} of ${result.resolved} samples; ${result.leftBehind.length} did not sound like the same person and stay held.`
+        : `${verb} ${name} from ${result.coherent} sample${result.coherent === 1 ? '' : 's'}.`
+          + (result.notReady.length > 0 ? ` ${result.notReady.length} still being read; they stay held.` : ''),
+    })
+  } catch (err: unknown) {
+    heldGroupFailure(res, err)
+  }
+})
+
+// POST /api/voice/held-groups/discard — throw held samples out without naming
+// them. Body: { members: [{ sessionId, chunkIndex }], confirm?: true, dryRun?: true }.
+// This is how the loose artifacts leave the panel.
+voiceRouter.post('/voice/held-groups/discard', (req, res) => {
+  try {
+    const members = parseHeldMembers(req.body?.members)
+    const dryRun = req.body?.dryRun === true
+    const confirm = req.body?.confirm === true
+    if (dryRun || !confirm) {
+      const preview = previewDiscard(members)
+      const summary = `Would discard ${preview.present.length} held sample${preview.present.length === 1 ? '' : 's'}`
+        + (preview.missing.length > 0 ? ` (${preview.missing.length} already gone)` : '') + '.'
+      if (dryRun) return res.json({ success: true, dryRun: true, wouldRemove: preview.present.length, missing: preview.missing, message: summary })
+      return res.status(400).json({
+        success: false,
+        error: 'confirmation required',
+        reason: 'confirmation_required',
+        message: `${summary} Pass { confirm: true } to proceed.`,
+        wouldRemove: preview.present.length,
+        missing: preview.missing,
+      })
+    }
+    const result = discardHeldSamples(members)
+    res.json({
+      success: true,
+      removed: result.removed.length,
+      missing: result.missing,
+      message: `Discarded ${result.removed.length} held sample${result.removed.length === 1 ? '' : 's'}.`,
+    })
+  } catch (err: unknown) {
+    heldGroupFailure(res, err)
+  }
+})
+
 // GET /api/voice/profiles — enrolled people with sample counts and provenance.
 // The review surfaces need to see the store; until now the only window into it
 // was a per-name count, so a misattributed profile was invisible.