@gotcos/glasses-server 6.46.1 → 6.47.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 6.47.0
+
+Meetings from Fireflies join the library, and recordings of the same meeting merge into one richer record. Paired Control build: 0.5.230. Glasses 6.9.474 adds Ref on the lens and needs no server change.
+
+- Fireflies import, on Macs without the COS pipeline. Paste a Fireflies API key in COS Control; the server checks it and reports a typed state (ok, invalid key, rate limited, vendor down, unreachable, no key). Imports arrive through the Fireflies API only, never from the desktop app's files, with a 7, 30 or 90 day backfill that resumes across the plan's daily limit, a 6 hour poll that uses at most half of the day's budget, and a ledger that reconciles what the vendor listed against what was written. Every failure has its own state; a run that imported nothing and failed reads as the failure. Imported meetings carry Fireflies' overview and action items.
+- A deterministic merge engine, on a worker thread. It pairs a G2 recording with the Fireflies meeting that shares the most unique three-word phrases at a consistent time offset, refuses a pairing whose clocks disagree by more than 15 minutes, collapses duplicate recordings of one meeting, and groups every G2 recording of a meeting into one merged record. No language model is involved anywhere in import, pairing, alignment, splitting or merging.
+- Merges are additive. A merged record holds the Fireflies transcript, the full G2 capture, any alternate transcript, the union of attendees, the vendor summary and action items, and a Sources table. Where the recordings align, G2 voice matches label generic Fireflies speakers, shown with their score, and the original label is kept. Source files are never modified.
+- Every automatic action can be undone. High confidence merges apply automatically with Undo; an undone merge is never repeated by automation. Lower confidence pairings become suggestions to confirm or dismiss. Recordings made before the engine was installed only ever become suggestions. Content-anchored splits of long recordings apply automatically with Revert on a Mac WITHOUT the COS pipeline, where a split writes new records; on a Mac with the pipeline a split is only ever a suggestion, because there is no additive, revertible way to turn one operations scribe into three, and accepting one in apply mode is refused with `split_not_supported_in_apply_mode`.
+- Macs with the COS pipeline start in advise mode: the engine shows would-merge items and suggestions and writes nothing into the operations tree. Switching to apply in Control hands each decision to sync_meetings.py, which archives the original to a unique verified path, splices the merge into the existing scribe (title, summary, decisions and action items survive), and can revert byte for byte. One mode file is read by every pipeline process; there is no environment flag.
+- Lists, detail, search, day counts and speaker review understand imported and merged records. A merged row replaces the rows it merged; its sources stay reachable from its detail. Imported and merged records are read only for speaker mutations, and never train voice profiles.
+- New routes: fireflies-key set, status, check and delete; meeting-import fireflies run, status and settings; meeting-suggestions list, accept, confirm and dismiss; meeting-actions list, one by id, revert, retry and revert-all; meeting-engine status and mode. A failed merge or undo is not terminal: retry puts it back in its own direction with a fresh attempt budget. Every suggestion carries both sides resolved server-side (title, start, length, source and the record that still holds each one), so a pipeline Mac can read them. The contract is in docs/meeting-merge-contract.md.
+- Compatibility: COS Control 0.5.229 and older show these features as unavailable and keep everything else. Glasses 6.9.473 lists merged meetings under an older source label. Older servers ignore the imports folder entirely. Rollback: run revert-all first if merged records should not remain, then set the mode back to advise before downgrading.
+
 ## 6.46.1
 
 G2 recordings show in a multi-folder Meetings library that has no COS pipeline to file them. No Control or glasses update is needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.46.1",
+  "version": "6.47.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "start": "node bin/cli.cjs",
     "start:server": "node --import tsx/esm server/index.ts",
     "test": "vitest run --maxWorkers=1",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "mutation:gate": "node server/scripts/mutation-gate.mjs"
   },
   "keywords": [
     "even-g2",
@@ -36,6 +37,9 @@
     "server/models/silero_vad.onnx",
     "shared",
     "!server/**/*.test.ts",
+    "!server/scripts/engine-canary.ts",
+    "!server/scripts/mutation-gate.mjs",
+    "!server/lib/meeting-engine/__fixtures__/**",
     "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",

package/server/index.ts

@@ -43,6 +43,20 @@ import { meetingRouter, resumeMeetingFinalizationJobs } from './routes/meeting.j
 import { meetingsRouter } from './routes/meetings.js'
 import { openaiCompatRouter } from './routes/openai-compat.js'
 import { openaiKeyRouter } from './routes/openai-key.js'
+import { firefliesKeyRouter } from './routes/fireflies-key.js'
+import { meetingImportRouter } from './routes/meeting-import.js'
+import { startMeetingImportScheduler, stopMeetingImportScheduler } from './lib/meeting-import.js'
+import { meetingSuggestionsRouter } from './routes/meeting-suggestions.js'
+import { meetingActionsRouter } from './routes/meeting-actions.js'
+import { meetingEngineRouter } from './routes/meeting-engine.js'
+import {
+  redrivePendingMergeActions,
+  sweepOrphanDecisions,
+  startMeetingMergeScheduler,
+  stopMeetingMergeScheduler,
+} from './lib/meeting-actions.js'
+import { getImportedMeetingLibrary } from './lib/imported-meeting-library.js'
+import { maintenanceLifecycle } from './lib/maintenance-lifecycle.js'
 import { messageRefRouter } from './routes/message-ref.js'
 import { archiveRouter } from './routes/archive.js'
 import { sessionsRouter } from './routes/sessions.js'
@@ -220,6 +234,18 @@ app.use('/api', (req, res, next) => {
     || req.path === '/transcribe'
     || req.path.startsWith('/transcribe-stream')
     || req.path === '/meeting/save'
+    // The import run answers 202 and keeps working. It takes its own
+    // maintenance lease per page and checks admissions itself, so the global
+    // request lease would only double-own the same work.
+    || req.path === '/meeting-import/fireflies/run'
+    // The suggestion and action mutations queue onto the merge runner, which takes its
+    // own `meeting_merge` lease PER ACTION and catches a drain by deferring that action.
+    // The global request lease would double-own the same work, and in apply mode it
+    // would hold across a 75s pipeline spawn — past COS Control's 90s drain timeout.
+    // Each of these still refuses on its own when admissions are closed.
+    || req.path.startsWith('/meeting-suggestions/')
+    || req.path.startsWith('/meeting-actions/')
+    || req.path === '/meeting-engine/mode'
     || req.path.startsWith('/prompt-drafts')
     || req.path.startsWith('/maintenance/drain')
   if (lifecycleOwned) return next()
@@ -675,6 +701,13 @@ app.use('/api', memoryRouter)
 app.use('/api', threadsRouter)
 app.use('/api', skillsRouter)
 app.use('/api', openaiKeyRouter)
+// Fireflies: the key, and importing meetings this Mac did not record (6.47.0).
+app.use('/api', firefliesKeyRouter)
+app.use('/api', meetingImportRouter)
+// The merge engine: what it wants decided, what it did, and its own state (6.47.0).
+app.use('/api', meetingSuggestionsRouter)
+app.use('/api', meetingActionsRouter)
+app.use('/api', meetingEngineRouter)
 // v6.3.0 — Message History, cross-day 'reference message N', and history
 // recovery for public npx users (previously full-COS-server only).
 app.use('/api', messageRefRouter)
@@ -725,6 +758,8 @@ async function gracefulShutdown(): Promise<void> {
   const forceExit = setTimeout(() => process.exit(1), 8_000)
   forceExit.unref?.()
   stopMorningBriefScheduler()
+  stopMeetingImportScheduler()
+  stopMeetingMergeScheduler()
   try {
     await shutdownQueryJobRuntime('server_shutdown')
   } catch (error) {
@@ -915,6 +950,47 @@ listenRequiredServers(listeners).then(() => {
     // was interrupted by a prior server update or process exit.
     resumeMeetingFinalizationJobs()
 
+    // Debris from an import killed mid-write: a temp file, or a sidecar whose
+    // markdown never landed. Both are invisible to every reader, so nothing
+    // would ever surface them. Skipped while a writer holds the lease, because
+    // mid-write that sidecar is the correct intermediate state.
+    try {
+      const swept = getImportedMeetingLibrary().sweep({
+        isBusy: () => (maintenanceLifecycle.snapshot().activeByKind.meeting_import ?? 0) > 0,
+      })
+      if (swept.removedTemp > 0 || swept.removedSidecars > 0) {
+        console.log(`[imports] startup sweep: ${swept.removedTemp} temp file(s), ${swept.removedSidecars} orphan sidecar(s)`)
+      }
+    } catch (error) {
+      console.warn('[imports] startup sweep failed', error)
+    }
+
+    // The Fireflies poll. Its own tick refuses in advise mode, without a key,
+    // while admissions are closed, and past its share of the daily budget, so
+    // starting it here is safe in every configuration.
+    startMeetingImportScheduler()
+
+    // The merge engine's own 30s tick (a full pass every six hours), and the
+    // central speaker-correction hook that re-derives affected records. Both
+    // defer while a capture is live or admissions are closed.
+    startMeetingMergeScheduler()
+
+    // AFTER the imports sweep, not before: the sweep removes a killed write's
+    // debris, and re-driving a pending apply into a half-written decision is
+    // exactly what the sweep exists to prevent. A pending action is one a
+    // previous process wrote and did not finish; the pipeline steps are
+    // idempotent, so re-driving one that actually completed is a no-op.
+    void redrivePendingMergeActions()
+      .then(count => { if (count > 0) console.log(`[meeting-merge] re-drove ${count} waiting action(s)`) })
+      .then(() => {
+        // A decision file is written BEFORE its action row, so a crash in that window
+        // leaves transcript text nothing will ever read or delete. Runs after the
+        // re-drive, so an action being driven right now still owns its decision.
+        const removed = sweepOrphanDecisions()
+        if (removed > 0) console.log(`[meeting-merge] removed ${removed} orphan decision file(s)`)
+      })
+      .catch(error => console.warn('[meeting-merge] pending re-drive failed', error))
+
     void initQueryJobRuntime().then(health => {
       if (process.env.COS_DURABLE_QUERY_JOBS !== '0') {
         console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)

package/server/lib/cos-operations-meetings.ts

@@ -182,6 +182,37 @@ export function sidecarSessionId(monthDir: string, meetingFilename: string): str
   return sidecarListHints(monthDir, meetingFilename).sessionId
 }
 
+// ── Merged-scribe markers (6.47.0, apply mode) ───────────────────────────────
+//
+// On a Mac with the COS pipeline the merge is spliced INTO the existing Fireflies
+// scribe rather than written as a new record, so there is no `.derived.json` to
+// read and the scribe itself has to say what it holds. The pipeline writes four
+// markers (WS8 step 4); these two are the ones a row identity needs.
+//
+// WHY THE SCRIBE AND NOT A SIDECAR. A merged scribe replaced a Fireflies scribe,
+// which never had a `.g2-chunks.json`. Its G2 sidecar stays beside the retired
+// standalone capture, so the only place that says "this file holds session X" is
+// the file.
+
+/** `<!-- g2-session: <sessionId> -->`, once per G2 capture the scribe holds. */
+export const G2_SESSION_MARKER = /<!--\s*g2-session:\s*([A-Za-z0-9:_-]{3,96})\s*-->/g
+/** `<!-- merge-action: <actionId> -->`, so Control can offer the merge's Undo. */
+export const MERGE_ACTION_MARKER = /<!--\s*merge-action:\s*([A-Za-z0-9_-]{1,64})\s*-->/
+
+/** Every session a merged scribe declares, in the order it declares them. */
+export function mergedScribeSessions(content: string): string[] {
+  const sessions: string[] = []
+  for (const match of content.matchAll(G2_SESSION_MARKER)) {
+    if (!sessions.includes(match[1])) sessions.push(match[1])
+  }
+  return sessions
+}
+
+/** The action a merged scribe was written by, when it declares one. */
+export function mergedScribeActionId(content: string): string | undefined {
+  return content.match(MERGE_ACTION_MARKER)?.[1]
+}
+
 function envPath(name: string): string | null {
   const raw = process.env[name]?.trim()
   if (!raw) return null
@@ -439,6 +470,14 @@ function withMeetingListInsights(meta: CosOperationsMeetingMeta, content: string
  *
  * Scans sidecar heads rather than parsing them, so the cost is a 4 KB read per
  * candidate and not the transcript.
+ *
+ * A MERGED SCRIBE OUTRANKS AN ORPHAN SIDECAR (6.47.0). Applying a merge splices
+ * the capture into the Fireflies scribe and then RETIRES the G2 standalone
+ * scribe, leaving its `.g2-chunks.json` behind with no markdown beside it. The
+ * chunks are still the evidence — that sidecar is what the speaker review reads —
+ * but the readable meeting is now the merged scribe, so this returns the orphan's
+ * sidecar path with the merged scribe's path, filename and title. Without that,
+ * naming a voice on a merged meeting opened a file that no longer existed.
  */
 export function findCosOperationsMeetingBySessionId(sessionId: string): {
   sidecarPath: string
@@ -468,17 +507,29 @@ export function findCosOperationsMeetingBySessionId(sessionId: string): {
       for (const sidecarName of sidecars) {
         const meetingFilename = sidecarName.replace(/\.g2-chunks\.json$/, '.md')
         if (sidecarSessionId(monthDir, meetingFilename) !== sessionId) continue
-        const meetingPath = join(monthDir, meetingFilename)
-        let title = meetingFilename.replace(/\.md$/, '')
+        const sidecarPath = join(monthDir, sidecarName)
+        let meetingPath = join(monthDir, meetingFilename)
+        let resolvedFilename = meetingFilename
+        let content: string | null = null
         try {
-          const head = readFileSync(meetingPath, 'utf-8').slice(0, 4000)
-          const heading = head.match(/^#\s+(.+)$/m)?.[1]?.trim()
-          if (heading) title = heading
-        } catch { /* fall back to the filename stem */ }
+          content = readFileSync(meetingPath, 'utf-8')
+        } catch {
+          // The capture's own scribe is gone. Only now is it worth reading the
+          // month's other scribes to find the one that declares this session.
+          const merged = findMergedScribeForSession(monthDir, sessionId)
+          if (merged) {
+            resolvedFilename = merged.filename
+            meetingPath = join(monthDir, merged.filename)
+            content = merged.content
+          }
+        }
+        let title = resolvedFilename.replace(/\.md$/, '')
+        const heading = content?.slice(0, 4000).match(/^#\s+(.+)$/m)?.[1]?.trim()
+        if (heading) title = heading
         return {
-          sidecarPath: join(monthDir, sidecarName),
+          sidecarPath,
           meetingPath,
-          filename: meetingFilename,
+          filename: resolvedFilename,
           domain,
           month,
           title,
@@ -489,6 +540,32 @@ export function findCosOperationsMeetingBySessionId(sessionId: string): {
   return null
 }
 
+/**
+ * The scribe in this month that declares `sessionId` through `<!-- g2-session -->`.
+ *
+ * Only ever called when a capture's own scribe is missing, so the full-content
+ * read it costs lands on a path that was about to answer with a dead file.
+ */
+function findMergedScribeForSession(
+  monthDir: string,
+  sessionId: string,
+): { filename: string; content: string } | null {
+  let names: string[]
+  try {
+    names = readdirSync(monthDir).filter(name => name.endsWith('.md')).sort().reverse()
+  } catch {
+    return null
+  }
+  for (const filename of names.slice(0, MAX_LIST_CANDIDATES)) {
+    let content: string
+    try {
+      content = readFileSync(join(monthDir, filename), 'utf-8')
+    } catch { continue }
+    if (mergedScribeSessions(content).includes(sessionId)) return { filename, content }
+  }
+  return null
+}
+
 export type MeetingLibraryRecord = NonNullable<ReturnType<typeof findCosOperationsMeetingBySessionId>> & {
   recordId?: string
   librarySource?: 'direct_library' | 'cos_operations'
@@ -588,6 +665,20 @@ export function listCosOperationsMeetings(options: {
               if (hints.speakers.length > 0) {
                 meta.voiceReview = meetingVoiceReview(hints.speakers, hints.sessionId)
               }
+              // A scribe the pipeline merged says so in its own body: it holds
+              // captures whose standalone rows this list must then drop, and it
+              // names the action Control offers Undo for. The content is already
+              // in memory, so this costs no extra read. The sidecar wins for
+              // `sessionId` when both are present — the sidecar is the file the
+              // speaker system keys on.
+              const declared = mergedScribeSessions(content)
+              if (declared.length > 0) {
+                meta.derivedKind = 'merge'
+                meta.g2SessionIds = declared
+                if (!meta.sessionId) meta.sessionId = declared[0]
+                const actionId = mergedScribeActionId(content)
+                if (actionId) meta.actionId = actionId
+              }
               if (options.day && meta.date !== options.day) continue
               allMeetings.push(meta)
             } catch { /* skip unreadable files */ }