@gotcos/glasses-server 6.46.1 → 6.48.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 6.48.0
+
+Session state now comes from Claude Code itself. A hook script spools every session event (session start and end, prompt submitted, turn stopped, permission wanted) and every session row carries one derived state with its provenance. No client change is required: Control 0.5.230 and glasses 6.9.478 ignore the new keys; Control 0.5.231 and the next EHPK read them.
+
+- `--hooks install|status|uninstall [--dry-run] [--port N]` writes fifteen hook subscriptions into `~/.claude/settings.json` (user level, so Desktop tabs, the CLI and `claude -p` jobs all report), preserving every existing hook block and every other key, with a backup of the file and an atomic 0600 write. The script is copied to the stable path `~/.cos-glasses/bin/cos-session-hook` so a server update never breaks it; `status` reports `script_outdated` when the package copy moved on and `install` re-copies. The same actions are on `POST /api/session-hooks/install` and `/uninstall` for COS Control. `status` also reports `disabled_by_settings` (the file carries `disableAllHooks`) and `settings_unreadable`, and `serverApplies` says whether the running server would read the spool into rows at all. A hooks install changes sessions started after it; tabs already open keep their startup snapshot until restarted. Removing the package does not remove the hooks: run `--hooks uninstall` first.
+- The hook is a POSIX sh script that writes one file per event into `~/.cos-glasses/data/hook-spool` and exits 0 on every path; it never talks to the server, so a session is never delayed by a server restart. It stops spooling when the spool holds 2,000 files or the server has not drained for a day, except permission requests. Only `PermissionRequest` may contact the server, and only after the desk has been idle (`ioreg` HIDIdleTime, default 90 s), for the broker that ships in 6.48.2; on 6.48.0 that call is refused (401) and the hook prints nothing, so the native dialog shows as before. An unreadable idle time never contacts the server.
+- The server ingests the spool (2 s sweep, `fs.watch` as a wake-up, bounded batches), keeps a projected ledger at `~/.cos-glasses/data/session-hook-events.jsonl` (10 MB rotation, replayed for the last 6 hours at boot), and reduces the events into one record per session. A pending permission clears only on evidence for that request (its own PostToolUse by fingerprint, a PermissionDenied naming the tool, Stop, a new prompt, SessionEnd; a parallel auto-allowed tool of the same name ending does not clear it); a Continue child that shares the tab's session id never changes the tab's state; a dead registry pid on two consecutive scans ends the row.
+- Rows on `/api/agent-sessions` (list and detail) and peers on `/api/claude-sessions` gain `agent_state` (running, waiting, idle, failed, ended), `state_source` (hook, registry, transcript), `state_since`, and when known `waiting_kind` (permission, question, plan, mcp_input), `waiting_detail` (the tool and its target), `failure`, and `last_reply` (the turn's last assistant message, 400 chars; the ledger keeps the same 400 chars of each prompt). `pending_permission_id` is reserved for the 6.48.2 broker and never set here. `state` keeps its old meaning and values. Older clients ignore the new keys.
+- `/api/health` gains `sessionHooks` (enabled, state, installed, scriptSha, tokenPresent, lastEventAt, spoolBacklog, spoolStuck, applyErrors, ledgerBytes, ledgerError and spoolError as codes, signals). A pending wait is also cleared by evidence the hooks cannot see: the registry moving on after it, the transcript moving on well after it, or nothing alive standing behind it for 30 minutes; an interrupted turn (no Stop fires) follows the registry to idle at once. `GET /api/session-hooks/runs?since=<ms>` lists the sessions the hooks saw start and end, for Control's scheduled-job ledger.
+- Flags: `COS_SESSION_HOOKS` (default on whenever `COS_CLAUDE_SESSIONS_ENABLED=1`; off still drains and stamps the spool and every row is exactly as 6.47.0), `COS_SESSION_HOOKS_SPOOL_DIR` (baked into the installed hook command together with the token directory, so the script and the server always agree; reinstall after changing it, `status` reports `drift` until then), `managed-runtime-contract.json` lists all six, and the reserved `COS_SESSION_HOOK_SSE`, `COS_PERMISSION_BROKER`, `COS_PERMISSION_BROKER_DESK_IDLE_S`, `COS_PERMISSION_BROKER_TIMEOUT_S` for the next releases. The next Control (0.5.231) adds all six to its runtime environment allowlist; until then a hand-set flag is dropped by Control's next Update Server, which is the fail-safe direction.
+- Fixtures under `server/lib/__fixtures__/session-hooks-6.48.0/` are real 2.1.272 recordings (paths redacted) and are excluded from the npm tarball. Recorded there: `SessionStart.source`, `SessionEnd.reason`, a `Stop` with no stop reason, a `PermissionRequest` with no `tool_use_id`, two permission hooks in one turn running one after the other, and a hook deny whose message reaches Claude with no `PermissionDenied` afterwards. Measured limit: an asynchronous hook that fires right before a print-mode process exits can be dropped by Claude (a `PostToolUse` in one recording, a `Stop` in another), so SessionStart, UserPromptSubmit, Stop and SessionEnd (the four events a row's state turns on) are installed synchronously with a 5 s timeout and were never dropped that way. The script itself is behaviour-tested under its own restricted PATH: spool naming, the 1 MiB cap, both B8 guards, the empty-token and closed-port paths, and a PermissionRequest round trip against a local listener.
+
+## 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/README.md

@@ -165,6 +165,30 @@ range is the exact Tailscale/CGNAT allocation (`100.64.0.0/10`), not all of
   `COS_WEATHER_DEFAULT_*`, otherwise omits weather. Optional `nextEvent`
   appears when `COS_SCRIPTS_DIR` calendar data is available.
 
+## Session hooks (6.48.0)
+
+Claude Code can tell the server what each session is doing (started, prompt submitted,
+waiting on a permission, turn stopped, ended) through its own hooks. Install them once:
+
+```bash
+npx --yes @gotcos/glasses-server@latest --hooks install --dry-run   # shows the merge, writes nothing
+npx --yes @gotcos/glasses-server@latest --hooks install             # merges into ~/.claude/settings.json
+npx --yes @gotcos/glasses-server@latest --hooks status
+npx --yes @gotcos/glasses-server@latest --hooks uninstall
+```
+
+The install keeps every hook you already had, backs the file up, and copies a small
+POSIX sh script to `~/.cos-glasses/bin/cos-session-hook`. The script writes one file per
+event into `~/.cos-glasses/data/hook-spool` and never contacts the server (a permission
+request may, only after the desk has been idle for 90 s, for the approval feature that ships
+next). Sessions started after the install report `state_source: hook` on
+`/api/agent-sessions` and `/api/claude-sessions`; tabs already open keep their startup
+hook snapshot until restarted, and may show Claude's "hooks modified externally" notice once (expected: the user-level file changed under them). The next COS Control (0.5.231) offers the same install from
+its Sessions tab. Rows change only while the server runs with `COS_CLAUDE_SESSIONS_ENABLED=1`
+(`--hooks status` prints `serverApplies`). Turn the ingestion off with `COS_SESSION_HOOKS=0`
+(the spool is still drained and stamped, rows are exactly as before). Removing the package
+does not remove the hooks: run `--hooks uninstall` first.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/bin/cli.cjs

@@ -27,6 +27,7 @@ const CONFIG_DIR = join(homedir(), '.cos-glasses')
 const PREPARE_ONLY = process.argv.includes('--prepare-only')
 const SETUP_TRANSCRIPTION = process.argv.includes('--setup-transcription')
 const SETUP_SPEAKER_MODEL = process.argv.includes('--setup-speaker-model')
+const HOOKS_ACTION = process.argv.includes('--hooks') ? process.argv[process.argv.indexOf('--hooks') + 1] : undefined
 function optionValue(name) {
   const index = process.argv.indexOf(name)
   return index >= 0 ? process.argv[index + 1] : undefined
@@ -145,6 +146,26 @@ function setupSpeakerModel() {
   return 0
 }
 
+// --hooks install|status|uninstall: the Claude Code session hook (6.48.0). Runs before the
+// banner and the runtime checks, resolving tsx itself; the managed runtime never comes
+// through here (Control uses POST /api/session-hooks/install on the running server).
+if (process.argv.includes('--hooks')) {
+  if (!['install', 'status', 'uninstall'].includes(HOOKS_ACTION)) {
+    console.error('Usage: --hooks install|status|uninstall [--dry-run] [--port N]')
+    process.exit(64)
+  }
+  let hooksTsx
+  try {
+    hooksTsx = require.resolve('tsx/esm', { paths: [PKG_ROOT] })
+  } catch {
+    console.error('COS package dependencies are incomplete; run npm install in the package first.')
+    process.exit(2)
+  }
+  const rest = process.argv.slice(process.argv.indexOf('--hooks') + 1)
+  const child = require('child_process').spawnSync(process.execPath, ['--import', hooksTsx, join(PKG_ROOT, 'server', 'scripts', 'hooks-cli.ts'), ...rest], { cwd: PKG_ROOT, stdio: 'inherit' })
+  process.exit(child.status ?? 1)
+}
+
 if (SETUP_SPEAKER_MODEL) {
   console.log('')
   console.log(bold('  COS Glasses - voiceprint model'))
@@ -162,6 +183,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('    npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier balanced|max')
   console.log('    npx --yes @gotcos/glasses-server@latest --setup-speaker-model')
   console.log('    npx --yes @gotcos/glasses-server@latest --prepare-only')
+  console.log('    npx --yes @gotcos/glasses-server@latest --hooks install|status|uninstall [--dry-run] [--port N]')
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')

package/bin/hooks/cos-session-hook

@@ -0,0 +1,43 @@
+#!/bin/sh
+# COS session hook (glasses-server 6.48.0). Installed into ~/.claude/settings.json by
+# `--hooks install`; Claude Code runs it with the hook event name as $1 and the event
+# payload on stdin. It spools one JSON file per event into the hook spool and exits 0
+# on every path. Only PermissionRequest ever talks to the server, and only when the
+# desk has been idle. Everything else is a file write, so the server being down or
+# restarting never delays a Claude session.
+#
+# The installer bakes COS_GLASSES_HOME and COS_HOOK_SPOOL into the command, so this
+# script and the server can never disagree about where the token or the spool is.
+PATH=/usr/bin:/bin:/usr/sbin; umask 077; trap '' PIPE
+HOME=${HOME:-$(cd ~ 2>/dev/null && pwd)}; [ -n "$HOME" ] || exit 0
+GH=${COS_GLASSES_HOME:-$HOME/.cos-glasses}
+SPOOL=${COS_HOOK_SPOOL:-$GH/data/hook-spool}; EVENT="$1"
+mkdir -p "$SPOOL/rejected" 2>/dev/null || exit 0
+TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null || date +%s000)
+# B8 guard: a full spool or a stale drain stamp means nobody is reading; keep only permissions.
+if [ "$EVENT" != PermissionRequest ]; then
+  N=$(ls "$SPOOL" 2>/dev/null | wc -l | tr -d ' '); [ "${N:-0}" -lt 2000 ] || exit 0
+  STAMP="$SPOOL/.last-drain"; [ ! -f "$STAMP" ] || [ -z "$(find "$STAMP" -mmin +1440 2>/dev/null)" ] || exit 0   # -mtime +1 would mean two days
+fi
+T="$SPOOL/.tmp.$$.$TS"; head -c 1048576 > "$T.in"                    # stdin to disk, 1 MiB cap
+case "$(head -c 1 "$T.in")" in '{') ;; *) EVENT=rejected ;; esac
+{ printf '{"ts":%s,"ppid":%s,"event":"%s","payload":' "$TS" "$PPID" "$EVENT"; cat "$T.in"; printf '}\n'; } > "$T"
+rm -f "$T.in"
+if [ "$EVENT" != PermissionRequest ]; then mv "$T" "$SPOOL/$TS-$$-$EVENT.json"; exit 0; fi   # rename = publish
+# A permission request keeps its own copy: the server unlinks the published file within
+# milliseconds of the rename, and the request body below must outlive that.
+cp "$T" "$T.req" 2>/dev/null; mv "$T" "$SPOOL/$TS-$$-$EVENT.json"
+cleanup() { rm -f "$T.req"; }
+# Desk-active fast path decided HERE (about 30 ms): no HTTP at all when someone is at the
+# keyboard. An unreadable idle time fails the same way: nothing is contacted, the native
+# dialog shows.
+IDLE_NS=$(ioreg -c IOHIDSystem 2>/dev/null | awk -F'= ' '/HIDIdleTime/{print $2; exit}')
+DESK_S=$(cat "$GH/hook-desk-idle-s" 2>/dev/null || echo 90)
+{ [ -n "$IDLE_NS" ] && [ "$(( ${IDLE_NS%.*} / 1000000000 ))" -ge "$DESK_S" ]; } || { cleanup; exit 0; }
+TOK=$(cat "$GH/hook-token" 2>/dev/null); [ -n "$TOK" ] || { cleanup; exit 0; }   # no token, no request
+PORT=$(cat "$GH/hook-port" 2>/dev/null || echo 3141)
+OUT=$(curl -s --connect-timeout 2 --max-time 125 -H "X-Cos-Hook-Token: $TOK" -H 'content-type: application/json' \
+  --data-binary @"$T.req" "http://127.0.0.1:$PORT/api/permission-requests/ask") || { cleanup; exit 0; }
+cleanup
+case "$OUT" in '{"hookSpecificOutput"'*) printf '%s' "$OUT" ;; esac
+exit 0

package/managed-runtime-contract.json

@@ -26,7 +26,13 @@
     "COS_UNSAVED_AUDIO_RETENTION_HOURS",
     "COS_CLAUDE_TRUST_MODE",
     "COS_CODEX_SANDBOX",
-    "COS_SCRIPTS_DIR"
+    "COS_SCRIPTS_DIR",
+    "COS_SESSION_HOOKS",
+    "COS_SESSION_HOOKS_SPOOL_DIR",
+    "COS_SESSION_HOOK_SSE",
+    "COS_PERMISSION_BROKER",
+    "COS_PERMISSION_BROKER_DESK_IDLE_S",
+    "COS_PERMISSION_BROKER_TIMEOUT_S"
   ],
   "maintenance": {
     "scope": "cross_boot",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.46.1",
+  "version": "6.48.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",
@@ -28,6 +29,7 @@
   "files": [
     "bin/cli.cjs",
     "bin/managed-server.cjs",
+    "bin/hooks/cos-session-hook",
     "managed-runtime-contract.json",
     "server",
     "!server/data/**",
@@ -36,6 +38,10 @@
     "server/models/silero_vad.onnx",
     "shared",
     "!server/**/*.test.ts",
+    "!server/scripts/engine-canary.ts",
+    "!server/scripts/mutation-gate.mjs",
+    "!server/lib/meeting-engine/__fixtures__/**",
+    "!server/lib/__fixtures__/**",
     "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",

package/server/index.ts

@@ -22,6 +22,8 @@ import { agentSessionsRouter } from './routes/agent-sessions.js'
 import { agentSessionStreamRouter } from './routes/agent-session-stream.js'
 import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
+import { createSessionHooksRouter } from './routes/session-hooks.js'
+import { startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
 import {
   createAgentSessionBindingsRouter,
   TargetGuard,
@@ -43,6 +45,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 +236,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()
@@ -356,6 +384,11 @@ const attachedWorkspaceDeps = realAttachedWorkspaceDeps(nativeHeadDeps)
  */
 const occupancyProbes = buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled())
 
+// 6.48.0: the hook spool ingester and the one signal store every session row reads. Starts
+// before any router is registered so the first list request already sees the replayed
+// ledger. With COS_SESSION_HOOKS off it still drains and stamps the spool (see the module).
+const sessionHooksRuntime = startSessionHooksRuntime({ port: PORT })
+
 /**
  * The shim between the route's request shape and the adapter's.
  *
@@ -511,6 +544,7 @@ app.use('/api', agentSessionStreamRouter)
 // Presence view of Claude Code sessions on this Mac. Dark unless
 // COS_CLAUDE_SESSIONS_ENABLED=1 — it projects another product's 0700 state dir.
 app.use('/api', claudeSessionsRouter)
+app.use('/api', createSessionHooksRouter({ port: PORT }))
 // Phase 0 of Continue Original Agent Thread: can COS write into a desktop thread
 // without colliding with a live writer? Read-only — it answers, it never attaches.
 // Registered AFTER agentSessionsRouter deliberately: its paths are 2 and 4 segments
@@ -675,6 +709,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 +766,9 @@ async function gracefulShutdown(): Promise<void> {
   const forceExit = setTimeout(() => process.exit(1), 8_000)
   forceExit.unref?.()
   stopMorningBriefScheduler()
+  stopMeetingImportScheduler()
+  stopMeetingMergeScheduler()
+  sessionHooksRuntime.stop()
   try {
     await shutdownQueryJobRuntime('server_shutdown')
   } catch (error) {
@@ -915,6 +959,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`)