@gotcos/glasses-server 6.73.5 → 6.74.0

package/server/routes/meetings.ts

@@ -18,6 +18,7 @@ import { meetingListLimit } from '../lib/meeting-store.js'
 import { searchMeetingLibrary } from '../lib/meeting-library-search.js'
 import { meetingContextFields, meetingContextKeys, readOnlyContext } from '../lib/meeting-context-keys.js'
 import { g2RecordingsReachOperations } from '../lib/g2-ops-handoff.js'
+import { MAC_CAPTURE_ID } from '../lib/mac-recording.js'
 import {
   type ImportedMeetingLibrary,
   IMPORTED_DOMAIN,
@@ -67,11 +68,36 @@ function withStandaloneIdentity(meeting: MeetingMeta): MeetingMeta {
 export function withMeetingContext<T extends MeetingMeta>(meeting: T, source: MeetingMeta['librarySource'] = meeting.librarySource): T {
   if (meeting.contextKeys !== undefined) return meeting
   if (source === 'standalone_recordings') {
-    return { ...meeting, ...meetingContextFields(meetingContextKeys({ g2SessionId: meeting.sessionId })) }
+    return { ...meeting, ...meetingContextFields(meetingContextKeys({ g2SessionId: meeting.sessionId, sourceType: meeting.sourceType })) }
   }
   return { ...meeting, ...readOnlyContext() }
 }
 
+/** A Mac capture's session id, as routes/meeting.ts keys the pipeline skip. */
+export function isMacCaptureId(sessionId: string | undefined): boolean {
+  return typeof sessionId === 'string' && MAC_CAPTURE_ID.test(sessionId)
+}
+
+/**
+ * Operations rows plus the store's Mac recordings (6.73.14), newest first by date and time, capped at `limit`. Only Mac
+ * rows are added: a G2 store row is the pipeline's to file, and its operations copy is the row. A Mac row is left out
+ * when an operations row holds its session, or when `held` does (the sessions merged scribes declare), the same rule
+ * the day count applies (imported-library-rows macStoreDayCounts). Operations rows are never deduplicated against each
+ * other or reordered among themselves, but a newer Mac row can push the oldest of them past `limit`.
+ */
+export function withMacStoreRows(operations: MeetingMeta[], storeRows: MeetingMeta[], limit: number, held: ReadonlySet<string> = new Set()): MeetingMeta[] {
+  const sessions = new Set(operations.map(row => row.sessionId).filter(Boolean))
+  const mac = storeRows
+    // Keyed on the sidecar's session, as the save route keys the pipeline skip (MAC_CAPTURE_ID). The row's sourceType
+    // comes from the markdown's Capture source line instead, which an edited or older record can lack.
+    .filter(row => isMacCaptureId(row.sessionId) && !sessions.has(row.sessionId) && !held.has(row.sessionId!))
+    .map(withStandaloneIdentity)
+  if (mac.length === 0) return operations
+  return [...operations, ...mac]
+    .sort((a, b) => `${b.date}T${b.time || '00:00'}`.localeCompare(`${a.date}T${a.time || '00:00'}`) || b.filename.localeCompare(a.filename))
+    .slice(0, Math.max(limit, 1))
+}
+
 function mergeMeetingSources(groups: MeetingMeta[][], limit: number, max = 50): MeetingMeta[] {
   const seenSessions = new Set<string>()
   const seenExact = new Set<string>()
@@ -213,7 +239,7 @@ function savedMeetingDetailWithContext(
   const source = detail.librarySource ?? (detail.recordId?.startsWith('standalone:') ? 'standalone_recordings' : undefined)
   if (source === 'standalone_recordings' && detail.contextKeys === undefined) {
     const sessionId = detail.sessionId || store.storedSessionId(descriptor.month, detail.filename || descriptor.filename)
-    return { ...detail, ...meetingContextFields(meetingContextKeys({ g2SessionId: sessionId })) }
+    return { ...detail, ...meetingContextFields(meetingContextKeys({ g2SessionId: sessionId, sourceType: detail.sourceType })) }
   }
   return withMeetingContext(detail, source)
 }
@@ -312,7 +338,11 @@ export function createMeetingsRouter(
             day: filters.day,
           })
           const declaredSessions = supersededFromRows(rows).g2Sessions
-          const meetings = dropSupersededRows(rows, { g2Sessions: declaredSessions, importRecordIds: new Set<string>(), isEmpty: declaredSessions.size === 0 })
+          const operationsMeetings = dropSupersededRows(rows, { g2Sessions: declaredSessions, importRecordIds: new Set<string>(), isEmpty: declaredSessions.size === 0 })
+          // 6.73.14 (Miles 2026-10-15): routes/meeting.ts never hands a Mac recording to the pipeline (MAC_CAPTURE_ID),
+          // so on a pipeline Mac it lives only in this store and never appeared in Meetings; Control's hand-off read
+          // "Saved meeting not found yet" forever. The store's Mac rows join the operations rows here.
+          const meetings = withMacStoreRows(operationsMeetings, store.list({ ...listOptions, sessionMatch: isMacCaptureId }), limit, declaredSessions)
           // ONLY WHEN THE LIST SAW THE WHOLE MONTH. The row list is capped, and a capped
           // list knows about fewer merged scribes than the month holds, so handing its
           // sessions to an UNCAPPED day count would subtract too little and put the dot
@@ -320,7 +350,15 @@ export function createMeetingsRouter(
           const listSawWholeMonth = rows.length < limit
           res.json({
             meetings: meetings.map(meeting => withMeetingContext(meeting)),
-            months: listCosOperationsMeetingMonths(domain),
+            // 6.73.14: a month holding only Mac recordings still reaches the calendar pager. Only store months the
+            // operations tree lacks are read, so a usual request reads nothing extra.
+            months: (() => {
+              const operationsMonths = listCosOperationsMeetingMonths(domain)
+              const known = new Set(operationsMonths)
+              const macOnly = store.listMonths().filter(month => !known.has(month)
+                && store.list({ month, domain, limit: 1, sessionMatch: isMacCaptureId }).length > 0)
+              return macOnly.length ? uniqueSortedMonths([operationsMonths, macOnly]) : operationsMonths
+            })(),
             // The rows above already read every scribe in this month and told us which
             // sessions the merged ones hold. Handing that over is the difference between
             // one read per file and two on every month request.

package/server/routes/stt-settings.ts

@@ -4,14 +4,20 @@
 //   PUT  /api/stt-settings                    partial body: {"hq":"parakeet-ultra"}, {"resolver":false}, ...
 //   POST /api/stt-settings/parakeet/install   install the pinned Parakeet CLI and models (202; poll GET)
 //        body {} | {"localSource":"/abs/path"} | {"localSource":"...","allowDownload":true}
+//        6.74.0: {"cliPath":"/Applications/COS Control.app/Contents/Helpers/fluidaudiocli","allowDownload":true}
+//        507 insufficient_disk, 422 cli_untrusted. allowDownload:false without localSource never downloads.
 //   DELETE /api/stt-settings/parakeet/install cancel a running install (nothing partial is kept)
+//   POST /api/stt-settings/parakeet/cli       6.74.0: COS Control registers its signed CLI and gets the verdict
 //
 // Clients find the route with GET: a 404 means an older server, so they hide the switcher.
 // The contract is shared with COS Control and the phone (see README "Speech-to-text settings").
 
 import { Router } from 'express'
 import { errMsg } from '../lib/utils.js'
-import { cancelParakeetInstall, installParakeet, parakeetInstalled, parakeetInstallRunning, type InstallOptions } from '../lib/parakeet.js'
+import {
+  cancelParakeetInstall, findPinnedCli, installParakeet, parakeetDiskCheck, parakeetInstalled, parakeetInstallRunning, type InstallOptions,
+} from '../lib/parakeet.js'
+import { isCliPathShape, offerControlCli, trustCli, type CliTrust } from '../lib/parakeet-cli-trust.js'
 import { currentSttCapabilities, ensurePreviewWarm, parakeetStatus } from '../lib/stt-runtime.js'
 import {
   applySettingsPatch, readLastSttJob, readSttSettings, settingsView, SttSettingsError, writeSttSettings,
@@ -23,12 +29,22 @@ export interface SttSettingsRouterDeps {
   capabilities?: () => SttCapabilities
   install?: (options: InstallOptions) => Promise<void>
   onChanged?: () => void
+  /** 6.74.0, tests: the disk precheck and the CLI verdict. */
+  diskCheck?: () => { ok: boolean; freeBytes: number | null; requiredBytes: number }
+  trust?: (path: string) => Promise<CliTrust>
+  pinned?: (path: string) => Promise<boolean>
 }
 
 export function createSttSettingsRouter(deps: SttSettingsRouterDeps): Router {
   const router = Router()
   const caps = deps.capabilities ?? currentSttCapabilities
   const install = deps.install ?? installParakeet
+  const diskCheck = deps.diskCheck ?? (() => parakeetDiskCheck())
+  const trust = deps.trust ?? (path => trustCli(path))
+  const pinned = deps.pinned ?? (async (path: string) => (await findPinnedCli([path])) !== null)
+  const cliVerdict = (t: CliTrust) => t.trusted
+    ? { trusted: true, trust: t.trust, teamId: t.teamId, version: t.version, versionSource: t.versionSource }
+    : { trusted: false, reason: t.reason, detail: t.detail }
   const view = () => settingsView(readSttSettings(), caps(), parakeetStatus(deps.recordingLive()), readLastSttJob())
 
   router.get('/stt-settings', (_req, res) => {
@@ -48,19 +64,54 @@ export function createSttSettingsRouter(deps: SttSettingsRouterDeps): Router {
     }
   })
 
-  router.post('/stt-settings/parakeet/install', (req, res) => {
+  // 6.74.0: COS Control says where its signed CLI is. The verdict is the same check the
+  // install makes; a trusted path also makes GET report Parakeet as installable.
+  router.post('/stt-settings/parakeet/cli', async (req, res) => {
+    try {
+      const cliPath = (req.body ?? {}).cliPath
+      if (!isCliPathShape(cliPath)) return void res.status(400).json({ error: 'cliPath must be an absolute path to fluidaudiocli.' })
+      const t = await trust(cliPath)
+      if (t.trusted) offerControlCli(cliPath)
+      res.status(t.trusted ? 200 : 422).json(cliVerdict(t))
+    } catch (err) {
+      res.status(500).json({ error: errMsg(err) })
+    }
+  })
+
+  router.post('/stt-settings/parakeet/install', async (req, res) => {
     try {
       if (deps.recordingLive()) return void res.status(409).json({ error: 'A recording is live. Install Parakeet after it is saved.' })
       if (parakeetInstalled().installed && !parakeetInstallRunning()) return void res.status(200).json({ started: false, ...view() })
-      const body = (req.body ?? {}) as { localSource?: unknown; allowDownload?: unknown }
+      const body = (req.body ?? {}) as { localSource?: unknown; allowDownload?: unknown; cliPath?: unknown }
       const raw = body.localSource
       if (raw !== undefined && (typeof raw !== 'string' || !raw.startsWith('/') || raw.length > 1024)) {
         return void res.status(400).json({ error: 'localSource must be an absolute path.' })
       }
       if (body.allowDownload !== undefined && typeof body.allowDownload !== 'boolean') return void res.status(400).json({ error: 'allowDownload must be true or false.' })
+      if (body.cliPath !== undefined && !isCliPathShape(body.cliPath)) return void res.status(400).json({ error: 'cliPath must be an absolute path to fluidaudiocli.' })
+      if (!parakeetInstallRunning()) {
+        const disk = diskCheck()
+        if (!disk.ok) {
+          return void res.status(507).json({
+            error: `Parakeet needs ${(disk.requiredBytes / 1e9).toFixed(1)} GB free on this Mac. Free some space, then install again. Whisper keeps working.`,
+            reason: 'insufficient_disk', freeBytes: disk.freeBytes, requiredBytes: disk.requiredBytes,
+          })
+        }
+        if (typeof body.cliPath === 'string' && !(await pinned(body.cliPath))) {
+          const t = await trust(body.cliPath)
+          if (!t.trusted) {
+            return void res.status(422).json({ error: 'The speech tool in COS Control did not pass its check. Reinstall COS Control, then install again.', reason: 'cli_untrusted', cli: cliVerdict(t) })
+          }
+          offerControlCli(body.cliPath)
+        }
+      }
       // Only bytes whose SHA-256 matches the pinned manifest are ever copied from it.
       // A named localSource that lacks a file fails plainly unless allowDownload is true.
-      const options: InstallOptions = raw ? { localSources: [raw], requireLocal: body.allowDownload !== true } : {}
+      // 6.74.0: allowDownload:false with no localSource also never downloads.
+      const options: InstallOptions = {
+        ...(raw ? { localSources: [raw], requireLocal: body.allowDownload !== true } : body.allowDownload === false ? { requireLocal: true } : {}),
+        ...(typeof body.cliPath === 'string' ? { cliCandidates: [body.cliPath] } : {}),
+      }
       if (!parakeetInstallRunning()) {
         void install(options).then(() => { ensurePreviewWarm(); deps.onChanged?.() }).catch(error => {
           console.warn(`[stt] Parakeet install failed: ${errMsg(error)}`)

package/server/routes/subq-key.ts

@@ -0,0 +1,27 @@
+/** Same authenticated push-only key workflow as Jev. No key values or upstream bodies are returned. */
+import { Router } from 'express'
+import { existsSync, unlinkSync } from 'node:fs'
+import { resetSubqDecisionClients } from '../lib/decision-provider.js'
+import { saveSubqKey, subqKeyStatus, SUBQ_KEY_FILE, validateSubqKey } from '../lib/subq-key.js'
+import { secureExistingPrivateFile } from '../lib/secure-user-config.js'
+interface SubqKeyRouteDeps { status: typeof subqKeyStatus; save: (key:string)=>void; validate: typeof validateSubqKey; remove:()=>void; reset:()=>void }
+export function createSubqKeyRouter(overrides: Partial<SubqKeyRouteDeps> = {}): Router {
+  const deps:SubqKeyRouteDeps={status:()=>subqKeyStatus(),save:key=>saveSubqKey(key),validate:validateSubqKey,remove:()=>{secureExistingPrivateFile(SUBQ_KEY_FILE);if(existsSync(SUBQ_KEY_FILE))unlinkSync(SUBQ_KEY_FILE)},reset:resetSubqDecisionClients,...overrides}
+  const router=Router();router.use('/subq-key',(_req,res,next)=>{res.set('Cache-Control','private, no-store');next()})
+  router.get('/subq-key/status',(_req,res)=>res.json(deps.status()))
+  router.post('/subq-key/set',async(req,res)=>{
+    const raw=req.body?.key
+    if (!req.body||typeof req.body!=='object'||Object.keys(req.body).some(k=>k!=='key')||typeof raw!=='string') return void res.status(400).json({error:{code:'invalid_subq_key',message:'Paste a SubQ API key.'}})
+    const key=raw.trim()
+    if(key.length<16||key.length>512||/[\s\x00-\x1f\x7f]/.test(key)) return void res.status(400).json({error:{code:'invalid_subq_key',message:'That does not look like a SubQ API key.'}})
+    const check=await deps.validate(key)
+    if(!check.ok)return void res.status(400).json({error:{code:'subq_key_not_accepted',message:check.reason,upstreamStatus:check.status}})
+    try{deps.save(key);deps.reset()}catch{return void res.status(500).json({error:{code:'subq_key_not_saved',message:'The key could not be saved. Check the server data folder.'}})}
+    res.json({ok:true,...deps.status()})
+  })
+  router.delete('/subq-key',(_req,res)=>{
+    try{deps.remove();deps.reset()}catch{return void res.status(500).json({error:{code:'subq_key_not_removed',message:'The saved key could not be removed.'}})}
+    res.json({ok:true,...deps.status()})
+  })
+  return router
+}

package/server/routes/transcribe-stream.ts

@@ -1,3 +1,6 @@
+import { MacParakeetUnavailableError, transcribeMacParakeet } from '../lib/mac-recording-asr.js'
+import { getMeetingStore } from '../lib/meeting-store.js'
+import { MAC_AUDIO, MAC_CAPTURE_ID, persistMacChunkReceipt, macError, registerMacRecording, requireMacRecording, readMacRecording, validateMacWav } from '../lib/mac-recording.js'
 import { AUTO_ENROLL_THRESHOLD } from '../lib/voiceprint-floor.js'
 import { readSpeakerPolicy, policyLabel, type SpeakerMode } from '../lib/meeting-speaker-policy.js'
 // POST /api/transcribe-stream — Streaming transcription for continuous meeting capture
@@ -19,6 +22,7 @@ import {
   clearStrandedDraft,
   listStrandedDrafts,
   releaseStrandedState,
+  restoresAtBoot,
   shouldCloseAfterFailedPromote,
   sweepStrandedSessions,
   promoteStrandedSession,
@@ -277,7 +281,7 @@ export interface TranscriptChunk {
   /** Capture-time policy survives batch and final passes; absent means legacy Standard. */
   speakerPolicy?: SpeakerMode
   words?: WhisperWord[] // word-level timestamps from DTW alignment
-  asrProvider?: 'server-whisper' | 'iphone-whisperkit-beta'
+  asrProvider?: 'server-whisper' | 'server-parakeet' | 'iphone-whisperkit-beta'
   backend?: string
   model?: string
   mode?: string
@@ -286,6 +290,7 @@ export interface TranscriptChunk {
   audioSha256?: string
   canonical?: boolean
   evenHubSpeakerRole?: EvenSpeakerRoleHistogram
+  audioDurationMs?: number
   /** 6.61.0: who spoke when inside this chunk, in time order. Present when
    *  Nemotron separated the chunk's voices; `speaker` is then the dominant name. */
   segments?: ChunkSpeakerSegment[]
@@ -365,6 +370,8 @@ interface EmptyTranscriptCompletion {
   elapsed: number
   backend?: string
   asrProvider?: string
+  model?: string
+  latencyMs?: number
   fallbackReason?: string
   audioSha256?: string
   canonical: false
@@ -381,6 +388,8 @@ interface StreamChunkCompletionResponse {
   canonical: boolean
   backend?: string
   asrProvider?: string
+  model?: string
+  latencyMs?: number
   fallbackReason?: string
   /** 6.61.0, additive: the chunk's speaker turns in time order. Their texts
    *  joined with one space equal `text`; `speaker` stays the dominant name. */
@@ -820,7 +829,7 @@ function recoverSessions(): void {
         if (data.sessionId && (hasChunks || Array.isArray(data.receivedIndices) || Number.isFinite(lastActivityAt))) {
           // Active retention is idle-based. Long meetings are not purged merely
           // because their original start time is old.
-          if (Date.now() - lastActivityAt < LOCAL_FIRST_MEETING_IDLE_RETENTION_MS) {
+          if (restoresAtBoot(data.sessionId, Date.now() - lastActivityAt, LOCAL_FIRST_MEETING_IDLE_RETENTION_MS)) {
             const chunks: TranscriptChunk[] = []
             if (indexed) {
               for (const e of indexed) {
@@ -1520,7 +1529,11 @@ export function getSessionChunkEntries(sessionId: string): IndexedTranscriptChun
           elapsed: empty.elapsed,
           similarity: 0,
           backend: empty.backend,
-          asrProvider: empty.asrProvider === 'iphone-whisperkit-beta'
+          ...(empty.model ? { model: empty.model } : {}),
+          ...(empty.latencyMs !== undefined ? { latencyMs: empty.latencyMs } : {}),
+          asrProvider: empty.asrProvider === 'server-parakeet'
+            ? 'server-parakeet'
+            : empty.asrProvider === 'iphone-whisperkit-beta'
             ? 'iphone-whisperkit-beta'
             : empty.asrProvider === 'server-whisper'
               ? 'server-whisper'
@@ -1547,6 +1560,9 @@ export function getSessionAsrCompletedIndices(sessionId: string): number[] {
 }
 
 function scheduleSessionProgressiveHq(sessionId: string): void {
+  // Progressive checkpoints are Whisper-only and may not bypass a Mac's
+  // explicit Parakeet choice, even if the separate HQ canary is enabled.
+  if (MAC_CAPTURE_ID.test(sessionId) && readSttSettings().hq === 'parakeet-ultra') return
   // Preserve the default-off contract at the route boundary. In addition to
   // avoiding any cache work, this keeps legacy/local-first transcription
   // independent of the progressive HQ capability surface when the canary is
@@ -2016,6 +2032,8 @@ function canonicalChunkResponse(
     canonical: true,
     backend: existing.backend,
     asrProvider: existing.asrProvider,
+    ...(existing.model ? { model: existing.model } : {}),
+    ...(existing.latencyMs !== undefined ? { latencyMs: existing.latencyMs } : {}),
     fallbackReason: existing.fallbackReason,
     ...(existing.segments?.length ? { segments: existing.segments } : {}),
   }
@@ -2072,7 +2090,7 @@ function identifyChunkSpeaker(audioBuffer: Buffer, sessionId: string, chunkIndex
   if (!isEmbeddingAvailable() || audioDurationSec < VOICEPRINT_MIN_AUDIO_SEC) return policyLabel({ speaker: clientSpeaker, similarity: 0 }, policy)
 
   const tEmb = performance.now()
-  const embeddingResult = identifySpeaker(audioBuffer, expectedSpeakers, { minSimilarity: policy === 'high-confidence' ? AUTO_ENROLL_THRESHOLD : undefined })
+  const embeddingResult = identifySpeaker(audioBuffer, expectedSpeakers, { minSimilarity: policy === 'high-confidence' ? AUTO_ENROLL_THRESHOLD : undefined, ...(MAC_CAPTURE_ID.test(sessionId) ? { prioritizeOwner: false, event: 'mac-system-audio' } : {}) })
   console.log(`[perf] identifySpeaker: ${(performance.now() - tEmb).toFixed(1)}ms`)
   if (!embeddingResult) return policyLabel({ speaker: clientSpeaker, similarity: 0 }, policy)
 
@@ -2080,8 +2098,9 @@ function identifyChunkSpeaker(audioBuffer: Buffer, sessionId: string, chunkIndex
   // it exists: identifySpeaker computes it per chunk and nothing else keeps it,
   // so a correction made later has no acoustic evidence without this write.
   // Deliberately includes 'Ext' — an unidentified voice is the case with no
-  // other way to be trained.
-  if (embeddingResult.embedding) {
+  // other way to be trained. Mac playback is recognition-only: never bank
+  // its voiceprints or create auxiliary training-audio copies.
+  if (embeddingResult.embedding && !MAC_CAPTURE_ID.test(sessionId)) {
     appendChunkEmbedding(sessionId, {
       i: chunkIndex,
       speaker: policyLabel(embeddingResult, policy).speaker,
@@ -2117,7 +2136,7 @@ function identifyChunkSpeaker(audioBuffer: Buffer, sessionId: string, chunkIndex
     }
   }
 
-  if (speaker === 'Ext' && audioBuffer.length >= 16000) {
+  if (speaker === 'Ext' && audioBuffer.length >= 16000 && !MAC_CAPTURE_ID.test(sessionId)) {
     const extSessionDir = resolve(EXT_AUDIO_DIR, sessionId)
     ensurePrivateDirectory(extSessionDir)
     const extCount = extAudioCounts.get(sessionId) ?? 0
@@ -2154,6 +2173,7 @@ async function processStreamChunk(opts: {
   clientElapsed?: number
   /** Original client recording start, applied only before canonical chunks. */
   startTimeOverride?: number
+  audioDurationMs?: number
   evenHubSpeakerRole?: EvenSpeakerRoleHistogram
 }): Promise<StreamChunkCompletionResponse> {
   const { sessionId, chunkIndex, clientSpeaker, audioBuffer, candidate } = opts
@@ -2215,7 +2235,7 @@ async function processStreamChunk(opts: {
 
   // Pin identity policy at acceptance, before persistence, ASR or diarization
   // yields. A later loosening applies to the next chunk, never this audio.
-  const capturePolicy = readSpeakerPolicy(sessionId).mode
+  const capturePolicy = MAC_CAPTURE_ID.test(sessionId) ? (requireMacRecording(sessionId), 'high-confidence' as const) : readSpeakerPolicy(sessionId).mode
   await persistRawSessionAudioChunk(sessionId, chunkIndex, audioBuffer)
   // Commit the received-index ledger only after the canonical raw WAV is
   // durable. A failure is typed non-2xx and a retry remains safe.
@@ -2250,7 +2270,7 @@ async function processStreamChunk(opts: {
   let rawText = ''
   let words: WhisperWord[] | undefined
   let backend = 'candidate'
-  let asrProvider: 'server-whisper' | 'iphone-whisperkit-beta' = 'server-whisper'
+  let asrProvider: 'server-whisper' | 'server-parakeet' | 'iphone-whisperkit-beta' = 'server-whisper'
   let model: string | undefined
   let mode: string | undefined
   let latencyMs: number | undefined
@@ -2263,6 +2283,16 @@ async function processStreamChunk(opts: {
     model = candidate.model
     mode = candidate.mode
     latencyMs = candidate.latencyMs
+  } else if (MAC_CAPTURE_ID.test(sessionId) && stt.hq === 'parakeet-ultra') {
+    // Use the stored choice directly. effectiveStt/preview intentionally fall
+    // back when unavailable, which is not an acceptable canonical Mac commit.
+    const result = await transcribeMacParakeet(whisperAudio, quiet.speechSec)
+    rawText = result.text
+    words = result.words
+    backend = result.backend
+    asrProvider = result.asrProvider
+    model = result.model
+    latencyMs = result.latencyMs
   } else {
     const t0 = performance.now()
     const result = await transcribeWithServerWhisper(audioBuffer, whisperAudio, whisperContext, isQuiet)
@@ -2343,6 +2373,8 @@ async function processStreamChunk(opts: {
       elapsed,
       backend,
       asrProvider,
+      ...(model ? { model } : {}),
+      ...(latencyMs !== undefined ? { latencyMs } : {}),
       fallbackReason: sanitized.fallbackReason || fallbackReason,
       audioSha256,
       canonical: false,
@@ -2358,6 +2390,7 @@ async function processStreamChunk(opts: {
   const chunk: TranscriptChunk = {
     text: trimmedText,
     speakerPolicy: capturePolicy,
+    ...(opts.audioDurationMs !== undefined ? { audioDurationMs: opts.audioDurationMs } : {}),
     speaker,
     elapsed,
     similarity,
@@ -2417,6 +2450,9 @@ async function processStreamChunk(opts: {
 }
 
 function sendStreamError(res: { status: (code: number) => { json: (body: unknown) => unknown } }, err: unknown): unknown {
+  if (err instanceof MacParakeetUnavailableError) {
+    return res.status(err.status).json({ error: err.message, reason: err.reason, retryable: true, model: err.model })
+  }
   if (err instanceof TranscriptionUnavailableError) {
     console.warn(`[transcribe-stream] ${err.message}`)
     return res.status(err.status).json({
@@ -2507,12 +2543,82 @@ transcribeStreamRouter.post('/transcribe-stream/preview', async (req, res) => {
   }
 })
 
+/** Unlike the received ledger, only these canonical completions acknowledge ASR.
+ * A native stop supplies the total captured chunks, including its last tail. */
+export function assertMacCaptureComplete(sessionId: string, expectedChunkCount: unknown): void {
+  if (!Number.isInteger(expectedChunkCount) || Number(expectedChunkCount) < 1 || Number(expectedChunkCount) > 10000) {
+    throw macError(400, 'mac_chunk_count_required', 'Mac save requires the total captured chunk count')
+  }
+  const session = sessions.get(sessionId)
+  const expected = Number(expectedChunkCount)
+  const missingIndices: number[] = []
+  for (let index = 0; index < expected; index++) {
+    if (!session?.chunks[index] && !session?.emptyCompletions?.[String(index)]) missingIndices.push(index)
+  }
+  if (missingIndices.length || (session?.maxChunkIndex ?? -1) >= expected) {
+    throw Object.assign(macError(409, 'mac_capture_incomplete', 'Mac audio is not fully acknowledged; retry pending chunks before saving'), { missingIndices })
+  }
+}
+
+// Manual Mac pilot: independent from iPhone candidate and cue rollout gates.
+transcribeStreamRouter.get('/mac-recording/capabilities', (_req, res) => {
+  res.set('Cache-Control', 'private, no-store').json({ available: true, ...MAC_AUDIO, serverInstanceId: getServerInstanceId() })
+})
+function requireMacPin(req: { get(name: string): string | undefined }): string {
+  const pin = req.get('X-COS-Server-Instance')?.trim()
+  if (!pin) throw macError(400, 'server_identity_pin_required', 'Server identity pin required')
+  return assertPinnedServerIdentity(pin, undefined)
+}
+transcribeStreamRouter.post('/mac-recording/start', (req, res) => {
+  let lease: MaintenanceWorkLease | undefined
+  try {
+    const serverInstanceId = requireMacPin(req)
+    if (typeof req.body?.captureId !== 'string' || !MAC_CAPTURE_ID.test(req.body.captureId)) throw macError(400, 'invalid_capture_id', 'Invalid Mac capture ID')
+    if (isSessionDeleted(req.body.captureId) || getMeetingStore().findBySessionId(req.body.captureId)) throw macError(410, 'session_closed', 'Capture is closed')
+    // An existing non-Mac session may not acquire new source metadata.
+    if (sessions.has(req.body.captureId) && !readMacRecording(req.body.captureId)) throw macError(409, 'mac_capture_conflict', 'Capture ID already exists')
+    lease = acquireRecordingChunkLease({ allowDuringDrain: sessions.has(req.body.captureId) })
+    const { recording, replayed } = registerMacRecording(req.body)
+    const session = getSession(recording.sessionId)
+    if (!session.chunks.some(Boolean)) session.startTime = recording.startTime
+    persistSessionRequired(recording.sessionId)
+    res.json({ ...MAC_AUDIO, ...recording, replayed, serverInstanceId })
+  } catch (error) { sendStreamError(res, error) } finally { lease?.release() }
+})
+const macChunkLocks = new Set<string>()
+transcribeStreamRouter.post('/mac-recording/:captureId/chunks', async (req, res) => {
+  let lease: MaintenanceWorkLease | undefined
+  let locked = false
+  const id = String(req.params.captureId ?? '')
+  try {
+    requireMacPin(req)
+    const recording = requireMacRecording(id)
+    if (isSessionDeleted(id)) throw macError(410, 'session_closed', 'Capture is closed')
+    const chunkIndex = Number(req.query.chunkIndex)
+    validateChunkIndex(chunkIndex)
+    const elapsed = Number(req.query.elapsed)
+    if (!Number.isFinite(elapsed) || elapsed < 0 || elapsed > 24 * 60 * 60 * 1000) throw macError(400, 'invalid_elapsed', 'Valid capture elapsed time required')
+    if (macChunkLocks.has(id)) throw macError(409, 'mac_chunk_in_progress', 'Another chunk is processing; retry the same chunk after its receipt')
+    macChunkLocks.add(id); locked = true
+    lease = acquireRecordingChunkLease({ allowDuringDrain: sessions.has(id) })
+    const audio = await readBoundedRawBody(req, MAC_AUDIO.maxChunkBytes)
+    const duration = validateMacWav(audio)
+    if (elapsed < duration) throw macError(400, 'invalid_elapsed', 'Chunk end precedes its duration')
+    const session = getSession(id)
+    persistMacChunkReceipt(id, { chunkIndex, endElapsed: elapsed, durationMs: duration, audioSha256: sha256Hex(audio) })
+    const prior = session.chunks[chunkIndex] ?? session.emptyCompletions?.[String(chunkIndex)]
+    if (prior?.audioSha256 && prior.audioSha256 !== sha256Hex(audio)) throw macError(409, 'mac_chunk_conflict', 'Chunk index already holds different audio')
+    res.json(await processStreamChunk({ sessionId: id, chunkIndex, clientSpeaker: 'Ext', audioBuffer: audio, clientElapsed: elapsed - duration, audioDurationMs: duration, startTimeOverride: recording.startTime }))
+  } catch (error) { sendStreamError(res, error) } finally { if (locked) macChunkLocks.delete(id); lease?.release() }
+})
+
 transcribeStreamRouter.post('/transcribe-stream', async (req, res) => {
   let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     // Reject a wrong Mac before consuming or persisting any upload bytes.
     assertPinnedServerIdentity(req.get('X-COS-Server-Instance'), req.query.serverInstanceId)
     const sessionId = (req.query.sessionId as string) || `g2_${Date.now()}`
+    if (sessionId.startsWith('mac_')) throw macError(400, 'mac_transport_required', 'Use the Mac recording transport for Mac captures')
     maintenanceLease = acquireRecordingChunkLease({
       allowDuringDrain: sessions.has(sessionId),
     })

package/server/routes/transcribe.ts

@@ -1,5 +1,7 @@
 // POST /api/transcribe: one-shot transcription (message-query path). 6.73.0: the engine
 // follows the STT settings (docs/dictation-stt-contract.md); Whisper is the fallback.
+// 6.74.0: Mac dictation (requiredEngine=local) follows its own dictation setting and
+// never leaves this Mac; POST /api/transcribe/benchmark is the onboarding check.
 //
 // The actual Whisper + cleanup pipeline lives in server/lib/transcribe-audio.ts so
 // prompt-draft recovery and the legacy one-shot path share exactly the same behavior.
@@ -12,6 +14,9 @@ import {
   OpenAIWhisperBudgetExhaustedError,
   TranscriptionUnavailableError,
 } from '../lib/transcribe-audio.js'
+import {
+  BENCHMARK_MAX_BYTES, BenchmarkRefusedError, parseBenchmarkEngines, runDictationBenchmark,
+} from '../lib/dictation-benchmark.js'
 import {
   acquireMaintenanceWork,
   MaintenanceLifecycleError,
@@ -20,6 +25,58 @@ import {
 } from '../lib/maintenance-lifecycle.js'
 
 export const transcribeRouter = Router()
+// A Mac client checks this before transferring microphone audio. Older servers must not
+// silently ignore the requested engine and use a configured cloud fallback.
+// 6.74.0: desktopDictationVersion stays 1, because COS Control 0.5.316 and earlier accept
+// exactly 1. desktopDictationVersions lists 2: requiredEngine=local (the dictation setting).
+transcribeRouter.get('/transcribe/capabilities', (_req, res) => {
+  res.json({
+    desktopDictationVersion: 1,
+    desktopDictationVersions: [1, 2],
+    requiredEngines: ['parakeet-ultra', 'local'],
+    localOnly: true,
+    dictionary: 'cos',
+    benchmark: 1,
+  })
+})
+
+const REQUIRED_ENGINES = new Set(['parakeet-ultra', 'local'])
+
+async function readCapped(req: AsyncIterable<unknown>, cap: number): Promise<Buffer | null> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array)
+    size += part.length
+    if (size > cap) return null
+    chunks.push(part)
+  }
+  return Buffer.concat(chunks)
+}
+
+// POST /api/transcribe/benchmark?engines=whisper,parakeet-ultra: raw 16 kHz WAV body.
+// Bounded in dictation-benchmark.ts (one at a time, never while recording, timeouts).
+transcribeRouter.post('/transcribe/benchmark', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
+  try {
+    const engines = parseBenchmarkEngines(req.query.engines)
+    if (!engines) return res.status(400).json({ error: 'engines must list whisper and/or parakeet-ultra.', reason: 'invalid_engine' })
+    maintenanceLease = acquireMaintenanceWork('one_shot_transcription')
+    const audio = await readCapped(req, BENCHMARK_MAX_BYTES)
+    if (!audio) return res.status(413).json({ error: 'The sample is longer than two minutes.', reason: 'audio_too_large' })
+    const result = await runDictationBenchmark(audio, engines)
+    res.json(result)
+  } catch (err: any) {
+    if (err instanceof MaintenanceLifecycleError) {
+      if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+      return res.status(err.status).json(maintenanceErrorPayload(err))
+    }
+    if (err instanceof BenchmarkRefusedError) return res.status(err.status).json({ error: err.message, reason: err.reason })
+    res.status(500).json({ error: err.message })
+  } finally {
+    maintenanceLease?.release()
+  }
+})
 
 function resolveMode(req: { body?: { mode?: string }; query?: { mode?: string | string[] } }) {
   return resolveTranscribeMode(
@@ -33,17 +90,22 @@ transcribeRouter.post('/transcribe', async (req, res) => {
   let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     maintenanceLease = acquireMaintenanceWork('one_shot_transcription')
-    const chunks: Buffer[] = []
-    for await (const chunk of req) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+    const rawEngine = req.query.requiredEngine
+    if (rawEngine !== undefined && (typeof rawEngine !== 'string' || !REQUIRED_ENGINES.has(rawEngine))) {
+      return res.status(400).json({ error: 'invalid_required_engine' })
     }
-    const audioBuffer = Buffer.concat(chunks)
+    const requiredEngine = rawEngine as 'parakeet-ultra' | 'local' | undefined
+    const audioBuffer = await readCapped(req, requiredEngine ? 3_840_044 : 25 * 1024 * 1024)
+    if (!audioBuffer) return res.status(413).json({ error: 'audio_too_large' })
 
     if (audioBuffer.length < 100) {
       return res.status(400).json({ error: 'audio too short' })
     }
 
-    const result = await transcribeAudioBuffer(audioBuffer, { mode: resolveMode(req) })
+    const result = await transcribeAudioBuffer(audioBuffer, {
+      mode: resolveMode(req),
+      ...(requiredEngine ? { requiredEngine, policy: 'local-only' as const, affectsCircuit: false } : {}),
+    })
     console.log(`[perf] /transcribe: ${result.elapsedMs.toFixed(1)}ms | mode=${result.mode} | ${result.backend}${result.engineReason ? ` (${result.engineReason})` : ''} | ${result.audioBytes}b | ${result.text.length} chars`)
     res.json({
       text: result.text,
@@ -56,6 +118,9 @@ transcribeRouter.post('/transcribe', async (req, res) => {
       // 6.73.0, additive: which engine decoded it and, when the selection could not run, why.
       engine: result.engine,
       ...(result.engineReason ? { engineReason: result.engineReason } : {}),
+      // 6.74.0, Mac dictation only.
+      ...(result.dictationSetting ? { dictationSetting: result.dictationSetting } : {}),
+      ...(result.fallbackReason ? { fallbackReason: result.fallbackReason } : {}),
     })
   } catch (err: any) {
     if (err instanceof MaintenanceLifecycleError) {
@@ -77,10 +142,13 @@ transcribeRouter.post('/transcribe', async (req, res) => {
     }
     if (err instanceof TranscriptionUnavailableError) {
       console.warn(`[transcribe] ${err.message}`)
+      // The 6.73.x body for every caller; Mac dictation on requiredEngine=local adds
+      // the one action it offers, and says when a retry cannot succeed.
       return res.status(err.status).json({
         error: err.message,
         reason: err.reason,
-        retryable: true,
+        retryable: err.hint ? err.hint.retryable : true,
+        ...(err.hint ? { action: err.hint.action, detail: err.hint.detail } : {}),
       })
     }
     res.status(500).json({ error: err.message })

package/server/routes/work-chat.ts

@@ -1,11 +1,14 @@
 import { Router } from 'express'
-import { parseWorkChatInput, parseWorkChatAnswer, WORK_CHAT_SYSTEM } from '../lib/work-chat.js'
+import { parseWorkChatInput, parseWorkChatAnswer, WORK_CHAT_SYSTEM, WORK_CHAT_PLANNERS, WORK_CHAT_EFFORTS, WORK_CHAT_DEFAULT_EFFORT,
+  WORK_CHAT_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS, WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS, WORK_CHAT_MAX_ITEMS, WORK_CHAT_MAX_REFERENCES } from '../lib/work-chat.js'
 import { runMeetingAskModel } from '../lib/meeting-ask-runner.js'
 import { acquireMaintenanceWork, maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
 export function createWorkChatRouter(deps = {run:runMeetingAskModel, admissions:maintenanceAdmissionsOpen, lease:()=>acquireMaintenanceWork('work_chat')}) {
   const router=Router(); let running=false
   router.use('/work/chat', (_req,res,next)=>{res.set('Cache-Control','private, no-store');next()})
-  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',automaticProviders:['claude','codex'],maxAssignments:3}))
+  // 6.73.15: queueRounds means sessions may carry openWork, and the planner routes around sessions with earlier work open.
+  // references means the input may carry read-only reference sessions (never targets).
+  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',planners:WORK_CHAT_PLANNERS,effort:WORK_CHAT_DEFAULT_EFFORT,efforts:WORK_CHAT_EFFORTS,automaticProviders:['claude','codex'],maxAssignments:WORK_CHAT_MAX_ASSIGNMENTS,contextItems:true,maxContextItems:WORK_CHAT_MAX_ITEMS,queueRounds:true,references:true,maxReferences:WORK_CHAT_MAX_REFERENCES}))
   router.post('/work/chat',async(req,res)=>{
     let input
     try { if (Buffer.byteLength(JSON.stringify(req.body))>100000) throw new Error(); input=parseWorkChatInput(req.body) }
@@ -17,9 +20,12 @@ export function createWorkChatRouter(deps = {run:runMeetingAskModel, admissions:
     res.on('close',abort)
     try {
       lease=deps.lease()
-      const out=await deps.run({engine:'claude',model:'sonnet'},JSON.stringify(input),WORK_CHAT_SYSTEM,controller.signal,undefined,{caller:'work_chat_'+input.mode})
+      // Planner and effort select how the model runs; they are not evidence, so they never reach the prompt.
+      const {planner='sonnet',effort=WORK_CHAT_DEFAULT_EFFORT,...prompt}=input
+      const out=await deps.run({engine:'claude',model:planner},JSON.stringify(prompt),WORK_CHAT_SYSTEM,controller.signal,undefined,{caller:'work_chat_'+input.mode},
+        {effort,maxOutputTokens:WORK_CHAT_OUTPUT_TOKENS,maxThinkingTokens:WORK_CHAT_THINKING_TOKENS[effort],deadlineMs:WORK_CHAT_DEADLINE_MS})
       const answer=parseWorkChatAnswer(out.text,input)
-      if (!res.destroyed) return res.json({protocolVersion:1,...answer,model:out.model??'claude:sonnet (requested)'})
+      if (!res.destroyed) return res.json({protocolVersion:1,...answer,model:out.model??`claude:${planner} (requested)`,effort})
     } catch {if(!res.destroyed) return res.status(503).json({error:'work_chat_unavailable',message:'No assignment was dispatched. Your saved request can be retried.'})}
     finally {res.off('close',abort);lease?.release();running=false}
   })