@gotcos/glasses-server 6.46.0 → 6.47.0

package/server/lib/meeting-engine/split.ts

@@ -0,0 +1,242 @@
+/**
+ * Splitting one long recording into the meetings it actually holds (6.47.0, WS3).
+ *
+ * PURE. No filesystem, no network, no clock.
+ *
+ * A recorder left running across a morning produces one three-hour "meeting" that is
+ * really three. The boundaries come from CONTENT: where each separate capture's shared
+ * phrases begin and end inside the long recording, snapped outward to a real silence.
+ * Measured against Miles's own manual split of the Aug 20 recording, the four boundaries
+ * land 27, 25, 42 and 42 s from where he put them.
+ *
+ * Calendar events and silence alone were measured and rejected: the calendar flagged 40 of
+ * 42 long recordings as spanning, which is noise, not a signal. Those cases stay
+ * suggestions in this release.
+ */
+
+import {
+  type AnchorSample,
+  type FirefliesMeetingInput,
+  type G2RecordingInput,
+  anchorsInBand,
+  contentEvidence,
+  g2TimedWords,
+  speechGaps,
+} from './evidence.js'
+
+/** Two hours. Below this, a recording holding two meetings is rare enough to leave alone. */
+export const LONG_RECORDING_S = 7200
+
+/** Shared phrases a capture needs before its span may cut the recording. */
+export const SPLIT_MIN_ANCHORS = 30
+
+/** One capture inside a long recording is a partial capture, not a split. */
+export const SPLIT_MIN_INSIDE_RECORDINGS = 2
+
+/** A silence this long is a real gap between meetings, not a pause for breath. */
+export const SPLIT_GAP_S = 90
+
+/** How far a span edge may be moved to land on that silence. */
+export const SPLIT_SNAP_S = 90
+
+/** A piece shorter than this is an artefact; it joins its neighbour. */
+export const MIN_PIECE_S = 120
+
+/** When one capture covers this much of the recording, they are one meeting: pair, do not split. */
+export const SPLIT_PAIRING_COVERAGE = 0.8
+
+/** Span edges are percentiles, so one stray early or late anchor cannot stretch a piece. */
+export const SPAN_LOW_PERCENTILE = 0.01
+export const SPAN_HIGH_PERCENTILE = 0.99
+
+export interface ContentSpan {
+  sessionId: string
+  /** Seconds from the recording start, after snapping to silence. */
+  startS: number
+  endS: number
+  /** Before snapping, for the report and the tests. */
+  rawStartS: number
+  rawEndS: number
+  anchors: number
+  offsetMs: number
+  /** The capture's extent on the recording's timeline, as a fraction of the recording. */
+  coverage: number
+}
+
+export type PieceKind = 'matched' | 'unmatched'
+
+export interface SplitPiece {
+  index: number
+  startS: number
+  endS: number
+  kind: PieceKind
+  /** The captures whose content defines this piece, in span order. */
+  sessionIds: string[]
+}
+
+export type SplitRefusal =
+  | 'not_long_enough'
+  | 'too_few_inside'
+  | 'one_capture_covers_recording'
+
+export interface SplitPlan {
+  firefliesId: string
+  split: boolean
+  refusal?: SplitRefusal
+  spans: ContentSpan[]
+  pieces: SplitPiece[]
+}
+
+function percentileAt(sorted: readonly number[], fraction: number): number {
+  return sorted[Math.trunc(fraction * (sorted.length - 1))]
+}
+
+/**
+ * Move a span edge onto the near side of a nearby silence.
+ *
+ * A start moves to where speech RESUMES and an end to where it STOPS, so the silence
+ * between two meetings belongs to neither piece's content and the boundary sits where a
+ * person would put it.
+ */
+export function snapToGap(
+  timeS: number,
+  gaps: readonly { startS: number; endS: number }[],
+  edge: 'start' | 'end',
+  withinS: number = SPLIT_SNAP_S,
+): number {
+  let best: number | null = null
+  let bestDistance = Infinity
+  for (const gap of gaps) {
+    const candidate = edge === 'start' ? gap.endS : gap.startS
+    const distance = Math.abs(candidate - timeS)
+    if (distance <= withinS && distance < bestDistance) {
+      best = candidate
+      bestDistance = distance
+    }
+  }
+  return best ?? timeS
+}
+
+/** Where one capture's content sits inside one recording. */
+export function contentSpanFor(
+  recording: G2RecordingInput,
+  meeting: FirefliesMeetingInput,
+  minAnchors: number = SPLIT_MIN_ANCHORS,
+): ContentSpan | null {
+  const { words } = g2TimedWords(recording)
+  const evidence = contentEvidence(words, meeting.sentences)
+  if (evidence.offsetMs === null) return null
+  const cluster: AnchorSample[] = anchorsInBand(evidence.samples, evidence.offsetMs)
+  if (cluster.length < minAnchors) return null
+  const times = cluster.map(sample => sample.firefliesMs)
+  const rawStartS = percentileAt(times, SPAN_LOW_PERCENTILE) / 1000
+  const rawEndS = percentileAt(times, SPAN_HIGH_PERCENTILE) / 1000
+  const gaps = speechGaps(meeting.sentences, SPLIT_GAP_S)
+  const offsetS = evidence.offsetMs / 1000
+  const captureEndS = offsetS + recording.durationMs / 1000
+  const covered = Math.max(0, Math.min(meeting.durationS, captureEndS) - Math.max(0, offsetS))
+  return {
+    sessionId: recording.sessionId,
+    startS: snapToGap(rawStartS, gaps, 'start'),
+    endS: snapToGap(rawEndS, gaps, 'end'),
+    rawStartS,
+    rawEndS,
+    anchors: cluster.length,
+    offsetMs: evidence.offsetMs,
+    coverage: meeting.durationS > 0 ? covered / meeting.durationS : 0,
+  }
+}
+
+/**
+ * Resolve two spans that claim the same seconds.
+ *
+ * A silence inside the contested stretch is the honest boundary. Without one, the midpoint
+ * at least keeps every second in exactly one piece, which is the property the pieces must
+ * have.
+ */
+export function resolveOverlap(
+  endOfEarlier: number,
+  startOfLater: number,
+  gaps: readonly { startS: number; endS: number }[],
+): number {
+  const low = Math.min(startOfLater, endOfEarlier)
+  const high = Math.max(startOfLater, endOfEarlier)
+  for (const gap of gaps) {
+    if (gap.startS >= low && gap.endS <= high) return gap.startS
+  }
+  return (low + high) / 2
+}
+
+/** Merge pieces under the minimum into the earlier neighbour, or the later one when first. */
+export function mergeShortPieces(pieces: readonly SplitPiece[], minPieceS: number = MIN_PIECE_S): SplitPiece[] {
+  const working = pieces.map(piece => ({ ...piece, sessionIds: [...piece.sessionIds] }))
+  for (;;) {
+    if (working.length <= 1) break
+    const index = working.findIndex(piece => piece.endS - piece.startS < minPieceS)
+    if (index === -1) break
+    const short = working[index]
+    const intoIndex = index > 0 ? index - 1 : 1
+    const into = working[intoIndex]
+    into.startS = Math.min(into.startS, short.startS)
+    into.endS = Math.max(into.endS, short.endS)
+    for (const sessionId of short.sessionIds) {
+      if (!into.sessionIds.includes(sessionId)) into.sessionIds.push(sessionId)
+    }
+    if (into.sessionIds.length > 0) into.kind = 'matched'
+    working.splice(index, 1)
+  }
+  return working.map((piece, index) => ({ ...piece, index }))
+}
+
+/**
+ * The pieces of one long recording.
+ *
+ * Every second of the recording lands in exactly one piece, including the stretches no
+ * capture matched: dropping them would lose content, which this release never does.
+ */
+export function splitPlanFor(
+  meeting: FirefliesMeetingInput,
+  recordings: readonly G2RecordingInput[],
+  options: { minInside?: number; longRecordingS?: number } = {},
+): SplitPlan {
+  const longRecordingS = options.longRecordingS ?? LONG_RECORDING_S
+  const minInside = options.minInside ?? SPLIT_MIN_INSIDE_RECORDINGS
+  const spans = recordings
+    .map(recording => contentSpanFor(recording, meeting))
+    .filter((span): span is ContentSpan => span !== null)
+    .sort((a, b) => (a.startS - b.startS) || (a.sessionId < b.sessionId ? -1 : 1))
+
+  if (meeting.durationS < longRecordingS) return { firefliesId: meeting.id, split: false, refusal: 'not_long_enough', spans, pieces: [] }
+  if (spans.length < minInside) return { firefliesId: meeting.id, split: false, refusal: 'too_few_inside', spans, pieces: [] }
+  if (spans.some(span => span.coverage >= SPLIT_PAIRING_COVERAGE)) {
+    return { firefliesId: meeting.id, split: false, refusal: 'one_capture_covers_recording', spans, pieces: [] }
+  }
+
+  const gaps = speechGaps(meeting.sentences, SPLIT_GAP_S)
+  const bounded = spans.map(span => ({
+    ...span,
+    startS: Math.max(0, Math.min(meeting.durationS, span.startS)),
+    endS: Math.max(0, Math.min(meeting.durationS, span.endS)),
+  }))
+  for (let i = 0; i + 1 < bounded.length; i++) {
+    if (bounded[i].endS > bounded[i + 1].startS) {
+      const boundary = resolveOverlap(bounded[i].endS, bounded[i + 1].startS, gaps)
+      bounded[i].endS = boundary
+      bounded[i + 1].startS = boundary
+    }
+  }
+
+  const pieces: SplitPiece[] = []
+  let cursor = 0
+  for (const span of bounded) {
+    const start = Math.max(cursor, span.startS)
+    if (start > cursor) pieces.push({ index: pieces.length, startS: cursor, endS: start, kind: 'unmatched', sessionIds: [] })
+    const end = Math.max(start, span.endS)
+    pieces.push({ index: pieces.length, startS: start, endS: end, kind: 'matched', sessionIds: [span.sessionId] })
+    cursor = end
+  }
+  if (cursor < meeting.durationS) {
+    pieces.push({ index: pieces.length, startS: cursor, endS: meeting.durationS, kind: 'unmatched', sessionIds: [] })
+  }
+  return { firefliesId: meeting.id, split: true, spans: bounded, pieces: mergeShortPieces(pieces) }
+}

package/server/lib/meeting-engine/worker.ts

@@ -0,0 +1,238 @@
+/**
+ * The merge engine's worker-thread entry, and the in-process orchestration it runs
+ * (6.47.0, WS3).
+ *
+ * PURE ABOVE THE THREAD BOUNDARY. `runEngine` touches no filesystem, no network and no
+ * clock: the runner (WS4) snapshots the inputs, posts them here, and writes the results.
+ *
+ * WHY A WORKER. Scoring a backlog is CPU-bound — trigrams over every capture against every
+ * candidate transcript. On the main thread that competes with live capture: chunk writes,
+ * transcription and the display bus all wait behind it. The engine never blocks a meeting.
+ *
+ * LOADING A `.ts` WORKER. Node 24 strips types natively but does NOT map a `./x.js`
+ * specifier to `x.ts`, so a bare `new Worker(url)` fails on the engine's own imports, and
+ * `execArgv: ['--import', 'tsx/esm']` does not fix it (measured: all three of bare,
+ * resolved and inherited execArgv fail to resolve the sibling import). Registering tsx's
+ * hooks INSIDE the worker before importing this file does work, with or without a loader
+ * in the parent, so the worker starts from a small bootstrap that does exactly that.
+ */
+
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import { Worker, isMainThread, parentPort } from 'node:worker_threads'
+import type { FirefliesMeetingInput, G2RecordingInput } from './evidence.js'
+import {
+  type MergeGroup,
+  type MergeTier,
+  type PairingResult,
+  groupAutoMerges,
+  scoreRecording,
+} from './pairing.js'
+import {
+  type SplitPlan,
+  LONG_RECORDING_S,
+  splitPlanFor,
+} from './split.js'
+import type { AttributeMode } from './attribute.js'
+import {
+  type DeriveResult,
+  type MergeDeriveInput,
+  type PieceDeriveInput,
+  renderMergedRecord,
+  renderSplitPiece,
+} from './render.js'
+
+/** How long one engine job may run before the caller stops waiting on the thread. */
+export const ENGINE_WORKER_TIMEOUT_MS = 300_000
+
+export interface EngineSuggestion {
+  kind: 'merge' | 'split'
+  sessionIds: string[]
+  firefliesIds: string[]
+  evidence: { K1: number; K2: number }
+}
+
+export interface EngineScoreRequest {
+  kind: 'score'
+  g2: G2RecordingInput[]
+  fireflies: FirefliesMeetingInput[]
+  options?: { attributeMode?: AttributeMode }
+}
+
+export interface EngineDeriveMergeRequest {
+  kind: 'derive_merge'
+  input: MergeDeriveInput
+}
+
+export interface EngineDerivePieceRequest {
+  kind: 'derive_piece'
+  input: PieceDeriveInput
+}
+
+export type EngineRequest = EngineScoreRequest | EngineDeriveMergeRequest | EngineDerivePieceRequest
+
+export interface EngineScoreResult {
+  kind: 'score'
+  pairings: PairingResult[]
+  /** One merged record per meeting, holding every capture of it. */
+  groups: MergeGroup[]
+  /** Long recordings that hold more than one meeting. */
+  splits: SplitPlan[]
+  suggestions: EngineSuggestion[]
+  tierCounts: Record<MergeTier, number>
+}
+
+export interface EngineDeriveResult {
+  kind: 'derive'
+  result: DeriveResult
+}
+
+export type EngineResult = EngineScoreResult | EngineDeriveResult
+
+/**
+ * Score every capture, group the automatic merges, and plan the splits.
+ *
+ * Split beats merge on a long recording: when a recorder ran across three meetings, merging
+ * a capture into the whole three hours would file that meeting under the wrong title and
+ * bury it. The exception is a capture that covers the recording, which means they are the
+ * same meeting after all.
+ */
+export function runEngine(request: EngineRequest): EngineResult {
+  if (request.kind === 'derive_merge') return { kind: 'derive', result: renderMergedRecord(request.input) }
+  if (request.kind === 'derive_piece') return { kind: 'derive', result: renderSplitPiece(request.input) }
+  if (request.kind !== 'score') throw new Error(`unknown engine request kind: ${String((request as { kind?: unknown }).kind)}`)
+
+  const pairings = request.g2.map(recording => scoreRecording(recording, request.fireflies))
+  const splits: SplitPlan[] = []
+  for (const meeting of request.fireflies) {
+    if (meeting.durationS < LONG_RECORDING_S) continue
+    const meetingStart = meeting.startMs
+    const meetingEnd = meeting.startMs + meeting.durationS * 1000
+    const inside = request.g2.filter(recording =>
+      recording.startMs + recording.durationMs > meetingStart && recording.startMs < meetingEnd)
+    if (inside.length === 0) continue
+    const plan = splitPlanFor(meeting, inside)
+    if (plan.split) splits.push(plan)
+  }
+  const splitIds = new Set(splits.map(plan => plan.firefliesId))
+  const groups = groupAutoMerges(pairings, request.g2).filter(group => !splitIds.has(group.primaryFirefliesId))
+
+  const suggestions: EngineSuggestion[] = []
+  for (const pairing of pairings) {
+    if (pairing.tier !== 'suggest' || !pairing.primaryFirefliesId) continue
+    suggestions.push({
+      kind: 'merge',
+      sessionIds: [pairing.sessionId],
+      firefliesIds: [pairing.primaryFirefliesId],
+      evidence: { K1: pairing.k1, K2: pairing.k2 },
+    })
+  }
+  const tierCounts: Record<MergeTier, number> = { auto_merge: 0, suggest: 0, none: 0 }
+  for (const pairing of pairings) tierCounts[pairing.tier] += 1
+
+  return { kind: 'score', pairings, groups, splits, suggestions, tierCounts }
+}
+
+interface WorkerEnvelope {
+  id: number
+  request: EngineRequest
+}
+
+interface WorkerReply {
+  id: number
+  ok: boolean
+  result?: EngineResult
+  error?: string
+}
+
+if (!isMainThread && parentPort) {
+  const port = parentPort
+  port.on('message', (envelope: WorkerEnvelope) => {
+    try {
+      port.postMessage({ id: envelope.id, ok: true, result: runEngine(envelope.request) } satisfies WorkerReply)
+    } catch (error) {
+      port.postMessage({ id: envelope.id, ok: false, error: error instanceof Error ? error.message : String(error) } satisfies WorkerReply)
+    }
+  })
+}
+
+/**
+ * Where tsx's loader API lives, as an absolute URL.
+ *
+ * Two ways, because neither works everywhere: `import.meta.resolve` is absent under the
+ * test runner's transform, and `createRequire` is the one that survives it. A `.js` worker
+ * (a future build step) needs no loader at all.
+ */
+function tsxRegistrationUrl(workerUrl: URL): string | null {
+  if (!workerUrl.pathname.endsWith('.ts')) return null
+  try {
+    if (typeof import.meta.resolve === 'function') return import.meta.resolve('tsx/esm/api')
+  } catch {
+    // fall through to require resolution
+  }
+  try {
+    return pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm/api')).href
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Start the engine worker.
+ *
+ * The bootstrap runs as CommonJS (`eval`), so it uses dynamic import rather than top-level
+ * await, and both URLs are absolute: a bare specifier would resolve against the process
+ * working directory, which for an installed server is wherever the user started it.
+ */
+export function createEngineWorker(): Worker {
+  const workerUrl = new URL(import.meta.url)
+  const tsxUrl = tsxRegistrationUrl(workerUrl)
+  const bootstrap = `
+    const workerUrl = ${JSON.stringify(workerUrl.href)}
+    const tsxUrl = ${JSON.stringify(tsxUrl)}
+    ;(async () => {
+      if (tsxUrl) {
+        const tsx = await import(tsxUrl)
+        tsx.register()
+      }
+      await import(workerUrl)
+    })().catch(error => { throw error })
+  `
+  return new Worker(bootstrap, { eval: true })
+}
+
+/** Run one engine job on a worker thread and shut the thread down. */
+export function runEngineInWorker(
+  request: EngineRequest,
+  options: { timeoutMs?: number } = {},
+): Promise<EngineResult> {
+  const timeoutMs = options.timeoutMs ?? ENGINE_WORKER_TIMEOUT_MS
+  return new Promise((resolve, reject) => {
+    let worker: Worker
+    try {
+      worker = createEngineWorker()
+    } catch (error) {
+      reject(error instanceof Error ? error : new Error(String(error)))
+      return
+    }
+    const timer = setTimeout(() => {
+      void worker.terminate()
+      reject(new Error('meeting engine worker timed out'))
+    }, timeoutMs)
+    timer.unref?.()
+    const done = (action: () => void) => {
+      clearTimeout(timer)
+      void worker.terminate()
+      action()
+    }
+    worker.on('message', (reply: WorkerReply) => {
+      if (reply.ok && reply.result) done(() => resolve(reply.result as EngineResult))
+      else done(() => reject(new Error(reply.error ?? 'meeting engine worker failed')))
+    })
+    worker.on('error', error => done(() => reject(error)))
+    worker.on('exit', code => {
+      if (code !== 0) done(() => reject(new Error(`meeting engine worker exited with ${code}`)))
+    })
+    worker.postMessage({ id: 1, request } satisfies WorkerEnvelope)
+  })
+}

package/server/lib/meeting-engine-mode.ts

@@ -0,0 +1,197 @@
+// One predicate, read by every surface that behaves differently on a Mac with
+// the COS pipeline than on a Mac without it.
+//
+// `imports` means nothing else here brings meetings in, so the server does: it
+// imports Fireflies meetings and writes derived records under the imports root.
+//
+// On a Mac whose own pipeline already files Fireflies meetings into operations/,
+// the server must not import them a second time — two writers producing
+// near-identical records is how one meeting becomes two rows that each look
+// canonical. Such a Mac is in one of two modes:
+//
+//   `advise`  the engine reads and shows what it WOULD do. It writes nothing
+//             outside the imports root. This is the starting mode everywhere.
+//   `apply`   the engine decides and the pipeline applies each decision into
+//             operations/, additively and revertibly.
+//
+// WHY A FILE AND NOT AN ENVIRONMENT FLAG (v3 blocker 7). Four processes have to
+// agree: this server, the hourly meeting sync, the meeting watcher and COS
+// Control. An env flag is read per process from whatever launched it, so a
+// LaunchAgent updated for one of them silently disagrees with the other three.
+// One file at the shared default data path is read the same way by all of them.
+//
+// THE SERVER IS THE ONLY WRITER. The pipeline reads the file and never writes
+// it; Control changes it through POST /api/meeting-engine/mode.
+//
+// ABSENT OR UNREADABLE MEANS ADVISE. The safe mode is the one that writes
+// nothing into a person's meeting tree, so every failure to read the file lands
+// there rather than on `apply`.
+//
+// The pipeline check is the STRICTER of the two available:
+// `g2RecordingsReachOperations` requires both the venv Python and
+// sync_meetings.py to exist, which is the same condition the save path uses to
+// decide whether a recording can reach operations at all. Reading env live
+// (rather than caching) matters because COS Control can change COS_SCRIPTS_DIR
+// under a running server.
+
+import { readFileSync } from 'node:fs'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { g2RecordingsReachOperations } from './g2-ops-handoff.js'
+
+export type MeetingEngineMode = 'advise' | 'imports' | 'apply'
+
+/** The modes a pipeline Mac can be switched between. `imports` is not a choice. */
+export type MeetingEnginePipelineMode = 'advise' | 'apply'
+
+export const MERGE_MODE_FILENAME = 'merge-engine.json'
+export const MERGE_MODE_SCHEMA = 1
+
+/**
+ * What kind of Mac this install has been observed to be.
+ *
+ * WHY IT IS REMEMBERED. `g2RecordingsReachOperations()` is a LIVE probe: it stats the COS
+ * venv's python and `sync_meetings.py`. Those two go missing for reasons that have nothing
+ * to do with this Mac's identity — iCloud evicting the checkout, a `pip` rebuild, COS
+ * Control changing `COS_SCRIPTS_DIR` between two reads. Every one of those made the predicate
+ * answer `imports`, and `imports` is the one mode that lets the server IMPORT Fireflies
+ * meetings the pipeline already files, which is how one meeting becomes two rows that each
+ * look canonical.
+ *
+ * A Mac that has once been seen with a pipeline is remembered as one. A transient negative
+ * then keeps the recorded mode (advise, the safe default) rather than flipping to imports,
+ * and the disagreement is reported in engine status as an alarm instead of acted on.
+ */
+export type MeetingEngineMacClass = 'pipeline' | 'standalone'
+
+export interface MergeModeFile {
+  schema: number
+  mode: MeetingEnginePipelineMode
+  changedAt: string
+  changedBy: 'control' | 'server'
+  /** The Mac class this install has been observed to be. Absent on a pre-QA1 file. */
+  macClass?: MeetingEngineMacClass
+}
+
+export function mergeModeFilePath(): string {
+  return dataPath(MERGE_MODE_FILENAME)
+}
+
+/**
+ * The mode recorded in the file, for a Mac that has a pipeline.
+ *
+ * Every failure — missing file, unreadable file, bad JSON, an unknown schema, an
+ * unknown mode — answers `advise`. A file that cannot be understood must never
+ * be read as permission to write into operations/.
+ */
+/** The whole file, or null when it cannot be understood. */
+export function readMergeModeRecord(path: string = mergeModeFilePath()): MergeModeFile | null {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<MergeModeFile>
+    if (parsed?.schema !== MERGE_MODE_SCHEMA) return null
+    return {
+      schema: MERGE_MODE_SCHEMA,
+      mode: parsed.mode === 'apply' ? 'apply' : 'advise',
+      changedAt: typeof parsed.changedAt === 'string' ? parsed.changedAt : new Date(0).toISOString(),
+      changedBy: parsed.changedBy === 'server' ? 'server' : 'control',
+      ...(parsed.macClass === 'pipeline' || parsed.macClass === 'standalone' ? { macClass: parsed.macClass } : {}),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function readMergeModeFile(path: string = mergeModeFilePath()): MeetingEnginePipelineMode {
+  return readMergeModeRecord(path)?.mode ?? 'advise'
+}
+
+/** Write the mode file atomically. The server is the only caller. */
+export function writeMergeModeFile(
+  mode: MeetingEnginePipelineMode,
+  options: { path?: string; now?: () => number; macClass?: MeetingEngineMacClass; changedBy?: 'control' | 'server' } = {},
+): MergeModeFile {
+  const path = options.path ?? mergeModeFilePath()
+  const macClass = options.macClass ?? readMergeModeRecord(path)?.macClass
+  const record: MergeModeFile = {
+    schema: MERGE_MODE_SCHEMA,
+    mode,
+    changedAt: new Date((options.now ?? Date.now)()).toISOString(),
+    changedBy: options.changedBy ?? 'control',
+    ...(macClass ? { macClass } : {}),
+  }
+  durableAtomicWriteFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
+  return record
+}
+
+/**
+ * Remember the Mac class, at most once per process per class.
+ *
+ * Bounded on purpose: `meetingEngineMode()` is called on every list, every detail, every
+ * status poll and every import refusal, and a write per call would be a write per request.
+ * The class only ever changes when a person installs or removes the COS pipeline, so once
+ * per process is enough to notice it.
+ */
+let rememberedMacClass: MeetingEngineMacClass | null = null
+
+/** Test seam: forget what this process has already written. */
+export function resetRememberedMacClass(): void {
+  rememberedMacClass = null
+}
+
+function rememberMacClass(macClass: MeetingEngineMacClass, current: MergeModeFile | null): void {
+  if (rememberedMacClass === macClass) return
+  rememberedMacClass = macClass
+  try {
+    writeMergeModeFile(current?.mode ?? 'advise', { macClass, changedBy: 'server' })
+  } catch {
+    // The data home is not writable. The predicate still answers; only the memory is lost.
+  }
+}
+
+/**
+ * The mode, and what it was decided from.
+ *
+ * A LIVE POSITIVE ALWAYS WINS: a Mac that can reach operations right now is a pipeline Mac,
+ * whatever the file says. A live NEGATIVE only wins when the file has never seen a pipeline
+ * here. That asymmetry is deliberate — being wrong towards `advise` writes nothing, and being
+ * wrong towards `imports` imports meetings the pipeline already owns.
+ */
+export function meetingEngineModeDetail(): {
+  mode: MeetingEngineMode
+  observedMacClass: MeetingEngineMacClass
+  recordedMacClass?: MeetingEngineMacClass
+  /** True when the recorded class and the live probe disagree. Reported, never acted on. */
+  macClassChanged: boolean
+} {
+  const reaches = g2RecordingsReachOperations()
+  const record = readMergeModeRecord()
+  const observedMacClass: MeetingEngineMacClass = reaches ? 'pipeline' : 'standalone'
+  const recordedMacClass = record?.macClass
+
+  if (reaches) {
+    rememberMacClass('pipeline', record)
+    return { mode: record?.mode ?? 'advise', observedMacClass, ...(recordedMacClass ? { recordedMacClass } : {}), macClassChanged: recordedMacClass === 'standalone' }
+  }
+  if (recordedMacClass === 'pipeline') {
+    // A transient negative. Keep the recorded mode and raise the alarm instead of importing
+    // meetings a pipeline that is merely unreadable right now still owns.
+    return { mode: record?.mode ?? 'advise', observedMacClass, recordedMacClass, macClassChanged: true }
+  }
+  rememberMacClass('standalone', record)
+  return { mode: 'imports', observedMacClass, ...(recordedMacClass ? { recordedMacClass } : {}), macClassChanged: false }
+}
+
+export function meetingEngineMode(): MeetingEngineMode {
+  return meetingEngineModeDetail().mode
+}
+
+/** Whether this Mac may be switched between advise and apply at all. */
+export function meetingEngineIsPipelineMac(): boolean {
+  return meetingEngineModeDetail().mode !== 'imports'
+}