@gotcos/glasses-server 6.73.5 → 6.74.0

package/server/lib/meeting-ask-runner.ts

@@ -4,9 +4,28 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { resolveProviderBinary } from './provider-binary.js';
-import { buildClaudeGistArgs, buildCodexGistArgs, parseClaudeGistOutput, parseCodexGistOutput, lensGistChildEnv } from './lens-gist-engines.js';
+import { buildClaudeGistArgs, buildCodexGistArgs, parseClaudeGistOutput, parseCodexGistOutput, lensGistChildEnv, type ClaudeGistEffort } from './lens-gist-engines.js';
 import { logTokenAudit } from './token-audit.js';
 import type { MeetingAskModel } from '../../shared/meeting-ask.js';
+/** 6.73.12: how one caller's run is bounded. Omitted fields keep Meeting Ask's budget, unchanged since before 6.73.12. */
+export interface MeetingAskRunBudget {
+    /** Claude `--effort`. Omitted keeps the builder's low. */
+    effort?: ClaudeGistEffort;
+    /** Answer tokens, excluding thinking. The child's CLAUDE_CODE_MAX_OUTPUT_TOKENS is this plus maxThinkingTokens,
+     *  because the model's max_tokens counts thinking too. */
+    maxOutputTokens?: number;
+    /** MAX_THINKING_TOKENS for the child. 0 turns thinking off. */
+    maxThinkingTokens?: number;
+    /** Wall-clock limit before the child is stopped with provider_timeout. */
+    deadlineMs?: number;
+}
+export const MEETING_ASK_DEFAULT_BUDGET = { maxOutputTokens: 1400, maxThinkingTokens: 0, deadlineMs: 45000 } as const;
+/** The child environment's token limits for a budget; the default is exactly '1400' and '0'. */
+export function meetingAskTokenEnv(budget?: MeetingAskRunBudget): { CLAUDE_CODE_MAX_OUTPUT_TOKENS: string; MAX_THINKING_TOKENS: string } {
+    const output = budget?.maxOutputTokens ?? MEETING_ASK_DEFAULT_BUDGET.maxOutputTokens;
+    const thinking = budget?.maxThinkingTokens ?? MEETING_ASK_DEFAULT_BUDGET.maxThinkingTokens;
+    return { CLAUDE_CODE_MAX_OUTPUT_TOKENS: String(output + thinking), MAX_THINKING_TOKENS: String(thinking) };
+}
 export class AskProcessError extends Error {
     constructor(message: string, readonly terminationUnconfirmed = false) { super(message); }
 }
@@ -17,7 +36,9 @@ export function runMeetingAskModel(model: MeetingAskModel, prompt: string, syste
 }, audit?: {
     /** Token-audit caller label (6.71.13), e.g. meeting_fact_check_planner_hedge. A failed call appends ":<reason>". */
     caller: string;
-}): Promise<{
+},
+/** 6.73.12: effort, token budget and deadline. Omitted keeps Meeting Ask's, so every older caller is unchanged. */
+budget?: MeetingAskRunBudget): Promise<{
     text: string;
     model?: string;
 }> {
@@ -30,11 +51,11 @@ export function runMeetingAskModel(model: MeetingAskModel, prompt: string, syste
     if (!binary.ok)
         return Promise.reject(new AskProcessError('provider_unavailable'));
     const workspace = adapter?.workspace ?? mkdtempSync(join(tmpdir(), 'cos-meeting-ask-'));
-    const args = adapter?.args ?? (provider === 'claude' ? buildClaudeGistArgs(model.model, system) : buildCodexGistArgs(model.model, workspace));
+    const args = adapter?.args ?? (provider === 'claude' ? buildClaudeGistArgs(model.model, system, budget?.effort) : buildCodexGistArgs(model.model, workspace));
     // Codex has no system-prompt flag here: trusted instruction is separate, then JSON evidence.
     const stdin = adapter?.stdin ?? (provider === 'claude' ? prompt : `${system}\n\n${prompt}`);
     return new Promise((resolve, reject) => {
-        const child = spawn(binary.path, args, { cwd: workspace, detached: true, stdio: ['pipe', 'pipe', 'pipe'], env: { ...lensGistChildEnv(binary.path), CLAUDE_CODE_MAX_OUTPUT_TOKENS: '1400', MAX_THINKING_TOKENS: '0' } });
+        const child = spawn(binary.path, args, { cwd: workspace, detached: true, stdio: ['pipe', 'pipe', 'pipe'], env: { ...lensGistChildEnv(binary.path), ...meetingAskTokenEnv(budget) } });
         let stdout = '', failure: string | null = null, done = false, closeSeen = false, code: number | null = null;
         let killTimer: NodeJS.Timeout | undefined, proofTimer: NodeJS.Timeout | undefined;
         const kill = (sig: NodeJS.Signals) => { if (child.pid)
@@ -115,7 +136,7 @@ export function runMeetingAskModel(model: MeetingAskModel, prompt: string, syste
                 finish(true); }, 50);
         };
         const abort = () => stop('cancelled');
-        const deadline = setTimeout(() => stop('provider_timeout'), 45000);
+        const deadline = setTimeout(() => stop('provider_timeout'), budget?.deadlineMs ?? MEETING_ASK_DEFAULT_BUDGET.deadlineMs);
         signal?.addEventListener('abort', abort, { once: true });
         if (signal?.aborted)
             abort();

package/server/lib/meeting-ask-store.ts

@@ -8,7 +8,8 @@ import { emptyOrientation } from './meeting-ask-orientation.js';
 import type { MeetingAskOrientation } from '../../shared/meeting-ask.js';
 import { AskError } from './live-cos-ask.js';
 export const ASK_ID = /^[A-Za-z0-9_-]{8,100}$/;
-export const ASK_SESSION = /^meeting_[A-Za-z0-9_-]{1,89}$/;
+export { ASK_SESSION } from './ask-session-id.js';
+import { ASK_SESSION } from './ask-session-id.js';
 export interface AskRecord {
     version: 2;
     fingerprint: string;

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

@@ -20,6 +20,8 @@ import { measureSpeechSeconds } from './vad-silero.js'
 import { batchTimestampsEnabled } from './whisper-batch-timing.js'
 import { readSttSettings, recordLastSttJob, type FrontEndId, type HqId, type SecondOpinionId } from './stt-settings.js'
 import { currentEffectiveStt } from './stt-runtime.js'
+import { MAC_CAPTURE_ID } from './mac-recording.js'
+import { MacParakeetUnavailableError } from './mac-recording-asr.js'
 import { transcribeParakeet, type ParakeetResult, type ParakeetRunOptions } from './parakeet.js'
 import { isDeletionProneEngine, resolveHypotheses, RESOLVER_VERSION, type Hypothesis } from './stt-resolver.js'
 import { getVocabulary } from './profile.js'
@@ -450,9 +452,15 @@ export interface HqJobPlan {
   secondOpinion: SecondOpinionId
   resolver: boolean
   frontEnd: FrontEndId
+  /** Mac canonical Parakeet must never silently substitute Whisper. */
+  strictPrimary?: true
 }
 
-export function currentHqJobPlan(): HqJobPlan {
+export function currentHqJobPlan(sessionId?: string): HqJobPlan {
+  const selected = readSttSettings()
+  if (sessionId && MAC_CAPTURE_ID.test(sessionId) && selected.hq === 'parakeet-ultra') {
+    return { engine: selected.hq, secondOpinion: selected.secondOpinion, resolver: selected.resolver, frontEnd: selected.frontEnd, strictPrimary: true }
+  }
   const eff = currentEffectiveStt()
   return { engine: eff.hq.engine, secondOpinion: eff.secondOpinion.engine, resolver: eff.resolver, frontEnd: eff.frontEnd }
 }
@@ -668,6 +676,7 @@ async function decodeHqWindow(
     try {
       primary = await parakeetGuarded(job, () => decodeParakeetWindow(deps, input, parakeetTimeout(job), 'parakeet-ultra', true))
     } catch (error) {
+      if (plan.strictPrimary) throw new MacParakeetUnavailableError(error)
       fallbackReason = `parakeet_failed: ${errorReason(error)}`
       console.warn(`[meeting-batch] Parakeet HQ failed for ${segment.startChunkIdx}-${segment.endChunkIdx}; using Large-v3: ${errorReason(error)}`)
       const w = await decodeWhisperWindow(deps, input, previousText, 'large-v3', segment, audioDir)
@@ -766,6 +775,7 @@ export async function transcribeSegments(
   plan: HqJobPlan,
   deps: HqDecodeDeps = defaultHqDeps,
 ): Promise<BatchResult[]> {
+  if (expectedSessionId && MAC_CAPTURE_ID.test(expectedSessionId) && plan.engine === 'parakeet-ultra') plan = { ...plan, strictPrimary: true }
   const results: BatchResult[] = []
   const meetingId = basename(audioDir)
   const job: JobState = { parakeetRan: false, parakeetFailures: 0, parakeetStopped: false }
@@ -809,6 +819,9 @@ export async function transcribeSegments(
         meetingId,
       })
     } catch (error) {
+      // One failed strict Mac window invalidates the HQ candidate; preserve the
+      // already canonical Parakeet chunks, rather than accepting partial text.
+      if (plan.strictPrimary) throw error
       console.error(
         `[meeting-batch] Segment ${segment.startChunkIdx}-${segment.endChunkIdx} failed: `
         + `${error instanceof Error ? error.message : String(error)}`,
@@ -831,9 +844,10 @@ export function recoveryHqJob(
   segments: BatchSegment[],
   entries: IndexedTranscriptChunk[],
   deps: HqDecodeDeps = defaultHqDeps,
+  sessionId?: string,
 ): { plan: HqJobPlan; run: () => Promise<BatchResult[]> } {
-  const plan = currentHqJobPlan()
-  return { plan, run: () => transcribeSegments(quarantineDir, segments, entries, undefined, plan, deps) }
+  const plan = currentHqJobPlan(sessionId)
+  return { plan, run: () => transcribeSegments(quarantineDir, segments, entries, sessionId, plan, deps) }
 }
 
 export function summarizeStt(plan: HqJobPlan, results: readonly BatchResult[], segmentsPlanned = results.length): BatchSttSummary {
@@ -1229,7 +1243,7 @@ export function runMeetingBatchPipeline(
   lease.unref()
   // Frozen at SAVE time: a settings change applies to the next saved meeting,
   // never to one already queued behind another HQ job.
-  const plan = currentHqJobPlan()
+  const plan = currentHqJobPlan(sessionId)
   const job = batchQueueTail.then(() => runMeetingBatchPipelineNow(
     audioDir,
     entries,
@@ -1304,6 +1318,7 @@ async function runMeetingBatchPipelineNow(
       outcome: 'failed',
       reason: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200),
     })
+    if (plan.strictPrimary) throw error
     return { transcriptionQuality: 'streaming' }
   }
 }

package/server/lib/meeting-context-keys.ts

@@ -1,3 +1,4 @@
+import { readMacRecording } from './mac-recording.js'
 /**
  * Meeting context keys (6.64.0): the ids COS Control files a meeting's dropped files under.
  *
@@ -10,6 +11,7 @@
  * decisions, Work review and speaker review depend on. So the key is read from the meeting's own source ids:
  *   - `g2:<sessionId>` from its `.g2-chunks.json` sidecar (the speaker system's key; moves with every G2 rename);
  *   - `ff:<id>` from its `.fireflies.json` sidecar;
+ *   - `mac:<captureId>` from an admitted Mac source and its saved sourceType;
  *   - `g2:<id>` for every `<!-- g2-session -->` the file declares, which is how a merged meeting also shows the files of
  *     the capture it absorbed.
  * Measured 2026-10-06: 649 of 656 meetings from August to October carry at least one.
@@ -23,7 +25,7 @@ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpat
 import { dirname, join } from 'node:path'
 
 /** A key as Control stores it. The id part is the server's own marker grammar (`G2_SESSION_MARKER`). */
-export const MEETING_CONTEXT_KEY = /^(?:g2|ff):[A-Za-z0-9:_-]{3,96}$/
+export const MEETING_CONTEXT_KEY = /^(?:g2|ff|mac):[A-Za-z0-9:_-]{3,96}$/
 const SOURCE_ID = /^[A-Za-z0-9:_-]{3,96}$/
 
 const SIDECAR_HEAD_BYTES = 4096
@@ -96,11 +98,12 @@ export function firefliesSidecarId(monthDir: string, meetingFilename: string): s
 
 /** The ordered, de-duplicated keys for one meeting. The first is primary: the capture's own sidecar, then Fireflies,
  *  then what the file declares. */
-export function meetingContextKeys(sources: { g2SessionId?: string; firefliesId?: string; declared?: readonly string[] }): string[] {
+export function meetingContextKeys(sources: { g2SessionId?: string; firefliesId?: string; declared?: readonly string[]; sourceType?: string }): string[] {
   const keys: string[] = []
-  const add = (prefix: 'g2' | 'ff', id: string | undefined) => {
+  const add = (prefix: 'g2' | 'ff' | 'mac', id: string | undefined) => {
     if (!id || !SOURCE_ID.test(id)) return
-    const key = `${prefix}:${id}`
+    const actualPrefix = prefix === 'g2' && (sources.sourceType === 'mac_system_audio' || readMacRecording(id)) ? 'mac' : prefix
+    const key = `${actualPrefix}:${id}`
     if (!keys.includes(key)) keys.push(key)
   }
   add('g2', sources.g2SessionId)

package/server/lib/meeting-parse.ts

@@ -134,6 +134,7 @@ export function parseMeeting(content: string, filename: string, month: string):
     // codebase, disagreeing with each other.
     domainAbbr: domainAbbreviation(domain),
     source: parseField(content, 'Source'),
+    ...(parseField(content, 'Capture source') === 'mac_system_audio' ? { sourceType: 'mac_system_audio' as const } : {}),
     duration,
     ...(parseDurationMinutes(duration) !== undefined ? { durationMinutes: parseDurationMinutes(duration) } : {}),
     month,
@@ -171,6 +172,7 @@ export function toMeta(detail: MeetingDetail, sessionId?: string): MeetingMeta {
     domain: detail.domain,
     domainAbbr: detail.domainAbbr,
     source: detail.source,
+    ...(detail.sourceType ? { sourceType: detail.sourceType } : {}),
     duration: detail.duration,
     ...(detail.durationMinutes !== undefined ? { durationMinutes: detail.durationMinutes } : {}),
     month: detail.month,

package/server/lib/meeting-store.ts

@@ -1,3 +1,4 @@
+import { MAC_SOURCE_TYPE, readMacRecording, closeMacRecording } from './mac-recording.js'
 import {
   chmodSync,
   existsSync,
@@ -33,6 +34,8 @@ const DAY_FILE_PREFIX = /^(\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))_/
 const DOMAIN_HEAD_BYTES = 4096
 const LIST_CAP = 50
 const LIST_CAP_SCOPED = 200
+/** The most rows a month- or day-scoped list returns. Exported so a caller that asks for "all of them" names the cap it gets. */
+export const MEETING_LIST_CAP_SCOPED = LIST_CAP_SCOPED
 
 export function meetingListLimit(limit: number | undefined, scoped: boolean): number {
   const raw = typeof limit === 'number' && Number.isFinite(limit) ? Math.trunc(limit) : 20
@@ -92,6 +95,7 @@ export interface MeetingMeta {
   domain: string
   domainAbbr: string
   source: string
+  sourceType?: 'mac_system_audio'
   duration: string
   durationMinutes?: number
   month: string
@@ -133,7 +137,7 @@ export interface MeetingMeta {
   /** 0-based position of a split piece inside its source recording. */
   pieceIndex?: number
   /** Inputs of a derived record, for the detail view's source links. */
-  sources?: Array<{ kind: 'g2' | 'fireflies'; id: string; recordId?: string }>
+  sources?: Array<{ kind: 'g2' | 'fireflies' | 'mac'; id: string; recordId?: string }>
   /** Present only when the server can state a truthful local record. */
   canonicalRecord?: string
   /** 6.64.0, additive and read-only. The keys COS Control files a meeting's dropped files under, from source ids the
@@ -192,6 +196,8 @@ export interface SaveMeetingInput {
 }
 
 export interface SavedMeeting {
+  captureId?: string
+  sourceType?: typeof MAC_SOURCE_TYPE
   filepath: string
   sidecarPath: string
   filename: string
@@ -255,6 +261,36 @@ function filenameStem(title: string, fallback: string): string {
   return safe || fallback
 }
 
+function clockTime(hourText: string, minuteText: string, meridiemText = ''): string | undefined {
+  let hour = Number(hourText)
+  const minute = Number(minuteText)
+  if (!Number.isInteger(hour) || !Number.isInteger(minute) || minute > 59) return undefined
+  const meridiem = meridiemText.toUpperCase()
+  if (meridiem) {
+    if (hour < 1 || hour > 12) return undefined
+    if (meridiem === 'AM' && hour === 12) hour = 0
+    if (meridiem === 'PM' && hour !== 12) hour += 12
+  } else if (hour > 23) {
+    return undefined
+  }
+  return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`
+}
+
+/**
+ * 6.73.14: a stored recording's start as "HH:MM" (24 h), the form operations rows carry (cos-operations-meetings
+ * extractMeetingDateTime), so a merged list orders a store row by its time and not at 00:00 of its day. Save writes
+ * `**Time** | 10:39 PM`; an older or hand-made record may put the time on the Date line instead; a fallback title
+ * leaves `_YYYY-MM-DD_HHMM` in the filename.
+ */
+export function storedMeetingTime(content: string, filename: string): string | undefined {
+  const field = parseField(content, 'Time').match(/^(\d{1,2}):(\d{2})(?:\s*([AP]M))?$/i)
+  if (field) return clockTime(field[1], field[2], field[3])
+  const dateLine = parseField(content, 'Date').match(/^\d{4}-\d{2}-\d{2}[ T]+(\d{1,2}):(\d{2})(?:\s*([AP]M))?$/i)
+  if (dateLine) return clockTime(dateLine[1], dateLine[2], dateLine[3])
+  const named = filename.match(/_\d{4}-\d{2}-\d{2}_(\d{2})(\d{2})(?:\D|$)/)
+  return named ? clockTime(named[1], named[2]) : undefined
+}
+
 function localParts(timestamp: number): {
   date: string
   month: string
@@ -312,10 +348,11 @@ export class MeetingStore {
       .trim()
     if (!transcript) throw new MeetingStoreError('Transcript is empty', 400, 'empty_transcript')
 
+    const mac = readMacRecording(sessionId)
     const parts = localParts(input.startTime)
-    const fallbackTitle = `G2 Recording ${parts.date} ${parts.hourMinute}`
+    const fallbackTitle = `${mac ? 'Mac' : 'G2'} Recording ${parts.date} ${parts.hourMinute}`
     const title = normalizeTitle(input.title, fallbackTitle)
-    const stem = filenameStem(title, `G2_Recording_${parts.hourMinute}`)
+    const stem = filenameStem(title, `${mac ? 'Mac' : 'G2'}_Recording_${parts.hourMinute}`)
     const durationMs = Number.isFinite(input.durationMs) ? Math.max(0, input.durationMs) : 0
     const durationMin = Math.round(durationMs / 60_000)
 
@@ -354,7 +391,8 @@ export class MeetingStore {
       `| **Date** | ${parts.date} |`,
       `| **Time** | ${parts.time} |`,
       `| **Duration** | ${durationMin} minutes |`,
-      '| **Source** | G2 Glasses |',
+      mac ? '| **Source** | Mac System Audio |' : '| **Source** | G2 Glasses |',
+      ...(mac ? ['| **Capture source** | mac_system_audio |', '| **Captured voices** | Other participants only |'] : []),
       `| **Domain** | ${escapeTableValue(domain)} |`,
       `| **Transfer integrity** | ${integrityValue} |`,
       '| **Transcription quality** | streaming |',
@@ -364,7 +402,7 @@ export class MeetingStore {
       // When COS ops is configured, use the private-app pipeline markers so
       // sync_meetings.py --g2-file will enrich (and reclassify domain). Plain
       // "Standalone recording" summaries are treated as already-final and skipped.
-      ...(process.env.COS_SCRIPTS_DIR
+      ...(process.env.COS_SCRIPTS_DIR && !mac
         ? [
             '<!-- g2-needs-domain-review -->',
             '',
@@ -381,6 +419,7 @@ export class MeetingStore {
     const providers = [...new Set(input.chunks.map(chunk => chunk.asrProvider || 'server-whisper'))]
     const sidecar = {
       schemaVersion: 2,
+      ...(mac ? { sourceType: MAC_SOURCE_TYPE, captureSource: mac } : {}),
       sessionId,
       startTime: input.startTime,
       durationMs,
@@ -416,7 +455,9 @@ export class MeetingStore {
       throw error
     }
 
+    if (mac) closeMacRecording(sessionId)
     return {
+      ...(mac ? { captureId: sessionId, sourceType: MAC_SOURCE_TYPE } : {}),
       filepath,
       sidecarPath,
       filename,
@@ -455,6 +496,7 @@ export class MeetingStore {
             ? Math.max(0, sidecar.durationMs)
             : 0
           return {
+            ...(sidecar.sourceType === MAC_SOURCE_TYPE ? { captureId: sessionId, sourceType: MAC_SOURCE_TYPE } : {}),
             filepath: join(monthDir, filename),
             sidecarPath: join(monthDir, sidecarName),
             filename,
@@ -472,7 +514,12 @@ export class MeetingStore {
     return null
   }
 
-  list(options: { limit?: number; domain?: string; month?: string; day?: string } = {}): MeetingMeta[] {
+  /**
+   * `sessionMatch` filters BEFORE the cap (6.73.14: Mac rows were cut by the 200-row cap of every store row), and before
+   * the markdown is read: the session comes from the sidecar's 4 KB head, so a list of Mac rows opens no G2 recording.
+   * A `day` with no `month` reads only that day's month folder; save files every recording under its own date's month.
+   */
+  list(options: { limit?: number; domain?: string; month?: string; day?: string; sessionMatch?: (sessionId: string | undefined) => boolean } = {}): MeetingMeta[] {
     const scoped = Boolean(options.month || options.day)
     const limit = meetingListLimit(options.limit, scoped)
     const domain = options.domain ?? 'all'
@@ -488,27 +535,33 @@ export class MeetingStore {
     const rootReal = this.rootRealpath()
     if (!rootReal) return []
     const meetings: MeetingMeta[] = []
+    const onlyMonth = options.month ?? options.day?.slice(0, 7)
 
     for (const month of readdirSync(this.root).filter(name => MONTH_PATTERN.test(name)).sort().reverse()) {
-      if (options.month && month !== options.month) continue
+      if (onlyMonth && month !== onlyMonth) continue
       const monthDir = join(this.root, month)
       const monthReal = safeDirectoryRealpath(monthDir, rootReal)
       if (!monthReal) continue
       for (const filename of readdirSync(monthDir).filter(name => SAFE_FILENAME_PATTERN.test(name)).sort().reverse()) {
         try {
+          // Matched first when asked: the sidecar head is the cheap read, the markdown the expensive one.
+          const matched = options.sessionMatch ? this.sidecarSessionId(monthDir, monthReal, filename) : undefined
+          if (options.sessionMatch && !options.sessionMatch(matched)) continue
           const content = safeReadFile(monthDir, monthReal, filename)
           if (content === null) continue
           const detail = parseMeeting(content, filename, month)
           if (domain !== 'all' && detail.domain !== domain) continue
           if (options.day && detail.date !== options.day) continue
-          meetings.push(toMeta(detail, this.sidecarSessionId(monthDir, monthReal, filename)))
+          const sessionId = options.sessionMatch ? matched : this.sidecarSessionId(monthDir, monthReal, filename)
+          const time = storedMeetingTime(content, filename)
+          meetings.push({ ...toMeta(detail, sessionId), ...(time ? { time } : {}) })
         } catch {
           // One unreadable/corrupt entry must not hide the rest of the store.
         }
       }
     }
     meetings.sort((left, right) => (
-      right.date.localeCompare(left.date) || right.filename.localeCompare(left.filename)
+      right.date.localeCompare(left.date) || (right.time ?? '').localeCompare(left.time ?? '') || right.filename.localeCompare(left.filename)
     ))
     return meetings.slice(0, limit)
   }

package/server/lib/parakeet-cli-trust.ts

@@ -0,0 +1,262 @@
+// 6.74.0: trust for a fluidaudiocli that COS Control ships signed (its Contents/Helpers).
+//
+// FluidAudio publishes no binary for v0.17.4, so COS Control builds it from the pinned
+// source tag and signs it with the COS Developer ID. That build cannot match the SHA-256
+// pin (parakeet-manifest.ts) because the signature is part of the bytes, so it is trusted
+// on three proofs instead, all required:
+//
+//   1. `codesign --verify --strict` passes, and passes again against the requirement
+//      that the leaf certificate chains to Apple and names the COS team (a self-signed
+//      certificate can claim any team name; `anchor apple generic` rules that out).
+//   2. The TeamIdentifier codesign reports is COS_TEAM_ID.
+//   3. The codesign Identifier, and the CFBundleIdentifier of the Info.plist embedded in
+//      the binary, are both CLI_IDENTIFIER.
+//   4. That embedded Info.plist is bound by the signature (`Info.plist entries=`) and its
+//      CFBundleShortVersionString is 0.17.4. The upstream 0.17.4 CLI has no version
+//      command, so the binary is never run to ask.
+//
+// The hand-placed SHA-256 pinned copy (parakeet.ts isPinnedCli) is unchanged.
+
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { constants as fsConstants, createReadStream, fstatSync, openSync, readSync, closeSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { Transform } from 'node:stream'
+import { PARAKEET_CLI } from './parakeet-manifest.js'
+
+/** The COS Developer ID team (read from /Applications/COS Control.app with codesign -dv, 2026-10-16). */
+export const COS_TEAM_ID = 'NV3X46LLCR'
+export const CODESIGN = '/usr/bin/codesign'
+export const TRUST_REQUIREMENT = `=anchor apple generic and certificate leaf[subject.OU] = "${COS_TEAM_ID}"`
+/** The codesign identifier and embedded CFBundleIdentifier of COS Control's build (agreed with Control). */
+export const CLI_IDENTIFIER = 'com.gotcos.control.fluidaudiocli'
+
+export type CliTrustReason = 'missing' | 'unsigned' | 'signature_invalid' | 'wrong_team' | 'wrong_identifier' | 'wrong_version'
+
+export type CliTrust =
+  | { trusted: true; trust: 'developer-id'; path: string; teamId: string; version: string; versionSource: 'info-plist'; sha256: string; size: number }
+  | { trusted: false; path: string; reason: CliTrustReason; detail: string }
+
+export interface CliTrustDeps {
+  /** codesign -dv: what it prints (stderr), and its exit code. */
+  display: (path: string) => Promise<{ code: number; output: string }>
+  /** codesign --verify --strict [-R requirement]. */
+  verify: (path: string, requirement?: string) => Promise<{ code: number; output: string }>
+  /** The Info.plist embedded in the Mach-O, or null. */
+  embeddedPlist: (path: string) => string | null
+  sha256: (path: string) => Promise<string>
+}
+
+function run(command: string, args: string[], timeoutMs: number): Promise<{ code: number; output: string }> {
+  return new Promise(resolve => {
+    execFile(command, args, { timeout: timeoutMs, maxBuffer: 256 * 1024, env: { PATH: '/usr/bin:/bin' } }, (error, stdout, stderr) => {
+      const code = error ? (typeof (error as { code?: unknown }).code === 'number' ? (error as { code: number }).code : 1) : 0
+      resolve({ code, output: `${stdout ?? ''}${stderr ?? ''}` })
+    })
+  })
+}
+
+async function sha256File(path: string): Promise<string> {
+  const hash = createHash('sha256')
+  await pipeline(createReadStream(path), new Transform({ transform(chunk, _e, cb) { hash.update(chunk); cb(null) } }))
+  return hash.digest('hex')
+}
+
+export const defaultCliTrustDeps: CliTrustDeps = {
+  display: path => run(CODESIGN, ['-dv', path], 10_000),
+  verify: (path, requirement) => run(CODESIGN, ['--verify', '--strict', ...(requirement ? ['-R', requirement] : []), path], 15_000),
+  embeddedPlist: path => readEmbeddedInfoPlist(path),
+  sha256: sha256File,
+}
+
+// ── Mach-O __TEXT,__info_plist ────────────────────────────────────────────────
+
+const MH_MAGIC_64 = 0xfeedfacf
+const FAT_MAGIC = 0xcafebabe
+const LC_SEGMENT_64 = 0x19
+const CPU_TYPE_ARM64 = 0x0100000c
+
+function readAt(fd: number, offset: number, length: number): Buffer {
+  const buf = Buffer.alloc(length)
+  const n = readSync(fd, buf, 0, length, offset)
+  return buf.subarray(0, n)
+}
+
+function cstr(buf: Buffer, start: number): string {
+  const raw = buf.subarray(start, start + 16)
+  const end = raw.indexOf(0)
+  return raw.subarray(0, end < 0 ? 16 : end).toString('ascii')
+}
+
+/** The __TEXT,__info_plist section of a thin 64-bit or fat Mach-O (arm64 slice), or null. */
+export function readEmbeddedInfoPlist(path: string): string | null {
+  let fd: number
+  // Non-blocking and no-follow: the path can come from a client, and a FIFO would
+  // block this synchronous open, and with it the whole server (hazard-invariants.test.ts).
+  try { fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW) } catch { return null }
+  try { if (!fstatSync(fd).isFile()) { closeSync(fd); return null } } catch { closeSync(fd); return null }
+  try {
+    let base = 0
+    const head = readAt(fd, 0, 8)
+    if (head.length < 8) return null
+    if (head.readUInt32BE(0) === FAT_MAGIC) {
+      const count = head.readUInt32BE(4)
+      if (count > 16) return null
+      const arches = readAt(fd, 8, count * 20)
+      base = -1
+      for (let i = 0; i < count; i++) {
+        if (arches.readUInt32BE(i * 20) === CPU_TYPE_ARM64) { base = arches.readUInt32BE(i * 20 + 8); break }
+      }
+      if (base < 0) return null
+    }
+    const header = readAt(fd, base, 32)
+    if (header.length < 32 || header.readUInt32LE(0) !== MH_MAGIC_64) return null
+    const ncmds = header.readUInt32LE(16)
+    const sizeofcmds = header.readUInt32LE(20)
+    if (sizeofcmds > 4 * 1024 * 1024) return null
+    const cmds = readAt(fd, base + 32, sizeofcmds)
+    let off = 0
+    for (let i = 0; i < ncmds && off + 8 <= cmds.length; i++) {
+      const cmd = cmds.readUInt32LE(off)
+      const cmdsize = cmds.readUInt32LE(off + 4)
+      if (cmdsize < 8) return null
+      if (cmd === LC_SEGMENT_64 && cstr(cmds, off + 8) === '__TEXT') {
+        const nsects = cmds.readUInt32LE(off + 64)
+        for (let s = 0; s < nsects; s++) {
+          const sec = off + 72 + s * 80
+          if (sec + 80 > cmds.length) return null
+          if (cstr(cmds, sec) !== '__info_plist') continue
+          const size = Number(cmds.readBigUInt64LE(sec + 40))
+          const offset = cmds.readUInt32LE(sec + 48)
+          if (size <= 0 || size > 64 * 1024) return null
+          return readAt(fd, base + offset, size).toString('utf8').replace(/\0+$/, '')
+        }
+      }
+      off += cmdsize
+    }
+    return null
+  } catch { return null } finally { closeSync(fd) }
+}
+
+function plistString(xml: string, key: string): string | null {
+  const m = new RegExp(`<key>${key}</key>\\s*<string>([^<]{1,128})</string>`).exec(xml)
+  return m ? m[1].trim() : null
+}
+/** CFBundleShortVersionString from an XML plist. */
+export function plistVersion(xml: string): string | null { return plistString(xml, 'CFBundleShortVersionString') }
+export function plistIdentifier(xml: string): string | null { return plistString(xml, 'CFBundleIdentifier') }
+
+/** 0.17.4 as a whole token, so 0.17.40 or 10.17.4 never pass. */
+export function versionMatches(text: string, want: string = PARAKEET_CLI.version): boolean {
+  const escaped = want.replace(/\./g, '\\.')
+  return new RegExp(`(^|[^0-9.])v?${escaped}(?![0-9]|\\.[0-9])`).test(text)
+}
+
+export function parseCodesignDisplay(output: string): { teamId: string | null; identifier: string | null; adhoc: boolean; unsigned: boolean; plistBound: boolean } {
+  const team = /^TeamIdentifier=(.+)$/m.exec(output)?.[1]?.trim() ?? null
+  return {
+    teamId: team && team !== 'not set' ? team : null,
+    identifier: /^Identifier=(.+)$/m.exec(output)?.[1]?.trim() ?? null,
+    adhoc: /^Signature=adhoc$/m.test(output) || /flags=0x[0-9a-f]*\([^)]*adhoc/.test(output),
+    unsigned: /code object is not signed at all/i.test(output),
+    plistBound: /^Info\.plist entries=\d+/m.test(output),
+  }
+}
+
+/** Every proof, in order; the first that fails names the reason. Never throws. */
+export async function checkDeveloperIdCli(path: string, deps: CliTrustDeps = defaultCliTrustDeps): Promise<CliTrust> {
+  const no = (reason: CliTrustReason, detail: string): CliTrust => ({ trusted: false, path, reason, detail })
+  let size: number
+  try { const st = statSync(path); if (!st.isFile()) return no('missing', 'not a file'); size = st.size } catch { return no('missing', 'not found') }
+  try {
+    const shown = await deps.display(path)
+    const d = parseCodesignDisplay(shown.output)
+    if (d.unsigned || shown.code !== 0) return no('unsigned', 'the speech tool is not signed')
+    if (d.adhoc || !d.teamId) return no('unsigned', 'the speech tool has no Developer ID signature')
+    const strict = await deps.verify(path)
+    if (strict.code !== 0) return no('signature_invalid', strict.output.trim().split('\n').slice(-1)[0]?.slice(0, 200) || 'the signature does not verify')
+    if (d.teamId !== COS_TEAM_ID) return no('wrong_team', `signed by team ${d.teamId}`)
+    const anchored = await deps.verify(path, TRUST_REQUIREMENT)
+    if (anchored.code !== 0) return no('wrong_team', 'the signature does not chain to Apple for the COS team')
+    if (d.identifier !== CLI_IDENTIFIER) return no('wrong_identifier', `signed as ${d.identifier ?? 'no identifier'}`)
+    // Only a plist the signature binds counts; the binary is never run to ask its version.
+    const plist = d.plistBound ? deps.embeddedPlist(path) : null
+    if (!plist) return no('wrong_version', 'no signed Info.plist in the speech tool')
+    const bundleId = plistIdentifier(plist)
+    if (bundleId !== CLI_IDENTIFIER) return no('wrong_identifier', `its Info.plist names ${bundleId ?? 'no identifier'}`)
+    const named = plistVersion(plist)
+    if (!named || !versionMatches(named) || named.replace(/^v/, '') !== PARAKEET_CLI.version) return no('wrong_version', `version ${named ?? 'unknown'}, not FluidAudio ${PARAKEET_CLI.version}`)
+    const sha256 = await deps.sha256(path)
+    // The bytes hashed must be the bytes checked.
+    if (statSync(path).size !== size) return no('signature_invalid', 'the file changed while it was checked')
+    return { trusted: true, trust: 'developer-id', path, teamId: COS_TEAM_ID, version: PARAKEET_CLI.version, versionSource: 'info-plist', sha256, size }
+  } catch (error) {
+    return no('signature_invalid', error instanceof Error ? error.message.slice(0, 200) : String(error))
+  }
+}
+
+// ── Where COS Control's copy is, and a per-process cache for GET ──────────────
+
+const HELPER_REL = join('COS Control.app', 'Contents', 'Helpers', 'fluidaudiocli')
+
+/** COS Control in /Applications or ~/Applications, plus any path Control registered. */
+export function controlCliCandidates(home: string = homedir()): string[] {
+  return [...offered, join(applicationsRoot, HELPER_REL), join(home, 'Applications', HELPER_REL)]
+}
+let applicationsRoot = '/Applications'
+/** Tests only: keep the real /Applications out of a test's view. */
+export function __setApplicationsRootForTests(root: string | null): void { applicationsRoot = root ?? '/Applications' }
+
+const offered: string[] = []
+/** An absolute path whose file name is fluidaudiocli. Anything else is never checked or run. */
+export function isCliPathShape(path: unknown): path is string {
+  return typeof path === 'string' && path.startsWith('/') && path.length <= 1024 && !path.includes('\0') && basename(path) === 'fluidaudiocli'
+}
+/** Control tells the server where its bundled CLI is (POST /api/stt-settings/parakeet/cli). */
+export function offerControlCli(path: string): void {
+  if (!isCliPathShape(path)) return
+  if (!offered.includes(path)) offered.unshift(path)
+  if (offered.length > 4) offered.length = 4
+}
+
+const cache = new Map<string, CliTrust>()
+const pending = new Map<string, Promise<CliTrust>>()
+function cacheKey(path: string): string | null {
+  try { const st = statSync(path); return st.isFile() ? `${path}\0${st.size}\0${st.mtimeMs}\0${st.ino}` : null } catch { return null }
+}
+
+/** Check (once per path, size, mtime and inode) and remember. */
+export function trustCli(path: string, deps: CliTrustDeps = defaultCliTrustDeps): Promise<CliTrust> {
+  const key = cacheKey(path)
+  if (!key) return Promise.resolve({ trusted: false, path, reason: 'missing', detail: 'not found' })
+  const known = cache.get(key)
+  if (known) return Promise.resolve(known)
+  const running = pending.get(key)
+  if (running) return running
+  const job = checkDeveloperIdCli(path, deps).then(r => { cache.set(key, r); return r }).finally(() => pending.delete(key))
+  pending.set(key, job)
+  return job
+}
+
+/** Synchronous, for GET: the known result for this file, null while unchecked (a check starts). */
+export function knownCliTrust(path: string): CliTrust | null {
+  const key = cacheKey(path)
+  if (!key) return { trusted: false, path, reason: 'missing', detail: 'not found' }
+  const known = cache.get(key)
+  if (known) return known
+  void trustCli(path)
+  return null
+}
+
+/** The first trusted candidate, or null. */
+export async function findTrustedCli(candidates: string[] = controlCliCandidates(), deps?: CliTrustDeps): Promise<Extract<CliTrust, { trusted: true }> | null> {
+  for (const c of candidates) {
+    const r = await trustCli(c, deps)
+    if (r.trusted) return r
+  }
+  return null
+}
+
+export function __resetCliTrustForTests(): void { cache.clear(); pending.clear(); offered.length = 0; applicationsRoot = '/Applications' }