@agent-native/core 0.87.0 → 0.90.1

package/corpus/templates/clips/desktop/src-tauri/src/whisper_speech.rs

@@ -9,7 +9,7 @@
 //!
 //! Capture is reused from the existing modules:
 //!   - mic    → `native_speech::macos::start_raw_mic_capture` (AVAudioEngine +
-//!              VoiceProcessingIO AEC, other-audio ducking off)
+//!              optional VoiceProcessingIO AEC, other-audio ducking off)
 //!   - system → `system_audio::macos::start_raw_system_capture` (ScreenCaptureKit)
 //!
 use tauri::AppHandle;
@@ -21,6 +21,8 @@ pub async fn whisper_transcription_start(
     mic_device_id: Option<String>,
     mic_device_label: Option<String>,
     capture_system: bool,
+    voice_processing: bool,
+    owner: Option<String>,
 ) -> Result<(), String> {
     if !crate::config::feature_config(&app).whisper_model_enabled {
         return Err("whisper-model-disabled".into());
@@ -33,6 +35,8 @@ pub async fn whisper_transcription_start(
             mic_device_id,
             mic_device_label,
             capture_system,
+            voice_processing,
+            macos::SessionOwner::from_param(owner),
         )
         .await
     }
@@ -44,6 +48,8 @@ pub async fn whisper_transcription_start(
             mic_device_id,
             mic_device_label,
             capture_system,
+            voice_processing,
+            owner,
         );
         Err("Whisper transcription is only supported on macOS.".into())
     }
@@ -82,6 +88,15 @@ pub async fn whisper_transcription_stop(app: AppHandle) -> Result<(), String> {
     }
 }
 
+#[tauri::command]
+pub async fn whisper_transcription_reset_timeline() -> Result<(), String> {
+    #[cfg(target_os = "macos")]
+    {
+        macos::reset_timeline();
+    }
+    Ok(())
+}
+
 #[cfg(target_os = "macos")]
 mod macos {
     use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
@@ -115,6 +130,11 @@ mod macos {
         segments: Vec<Segment>,
     }
 
+    struct StreamTimeline {
+        stream_start: Instant,
+        buffer_start: Instant,
+    }
+
     /// Process-wide whisper context, loaded once and reused across meetings.
     fn context(app: &AppHandle) -> Result<Arc<WhisperContext>, String> {
         // Route whisper.cpp + ggml's chatty stderr logs (model load dump,
@@ -192,11 +212,15 @@ mod macos {
         /// Capture start — t=0 of the meeting timeline. Mic and system streams
         /// start within a few ms of each other, so their segment timestamps
         /// share one timeline.
-        stream_start: Instant,
-        /// When the CURRENT buffer began (reset on each finalize/clear). Whisper
-        /// timestamps are relative to the buffer, so this is the offset onto the
-        /// meeting timeline.
-        buffer_start: Mutex<Instant>,
+        ///
+        /// Native recordings can warm this capture before the countdown ends;
+        /// they reset this timeline when ScreenCaptureKit actually attaches the
+        /// recording output so transcript timestamps stay video-relative.
+        timeline: Mutex<StreamTimeline>,
+        /// Incremented when the timeline and buffer are reset. The worker has
+        /// local counters that must be reset after the realtime callback clears
+        /// the shared sample buffer.
+        reset_generation: AtomicU32,
     }
 
     impl WhisperStream {
@@ -217,8 +241,11 @@ mod macos {
                 running: Arc::new(AtomicBool::new(true)),
                 done: done.clone(),
                 app,
-                stream_start,
-                buffer_start: Mutex::new(stream_start),
+                timeline: Mutex::new(StreamTimeline {
+                    stream_start,
+                    buffer_start: stream_start,
+                }),
+                reset_generation: AtomicU32::new(0),
             });
             let worker_stream = stream.clone();
             std::thread::spawn(move || {
@@ -248,9 +275,14 @@ mod macos {
 
         /// Offset (ms) of the current buffer onto the meeting timeline.
         fn offset_ms(&self) -> i64 {
-            self.buffer_start
+            self.timeline
                 .lock()
-                .map(|b| b.duration_since(self.stream_start).as_millis() as i64)
+                .map(|timeline| {
+                    timeline
+                        .buffer_start
+                        .saturating_duration_since(timeline.stream_start)
+                        .as_millis() as i64
+                })
                 .unwrap_or(0)
         }
 
@@ -258,9 +290,23 @@ mod macos {
         /// on finalize) so the next utterance's whisper timestamps offset
         /// correctly onto the meeting timeline.
         fn reset_buffer_start(&self) {
-            if let Ok(mut b) = self.buffer_start.lock() {
-                *b = Instant::now();
+            if let Ok(mut timeline) = self.timeline.lock() {
+                timeline.buffer_start = Instant::now();
+            }
+        }
+
+        /// Rebase timestamps to "now" and discard any audio captured while the
+        /// recorder was warming up/counting down.
+        fn reset_timeline(&self) {
+            if let Ok(mut buf) = self.buf.lock() {
+                buf.clear();
             }
+            let now = Instant::now();
+            if let Ok(mut timeline) = self.timeline.lock() {
+                timeline.stream_start = now;
+                timeline.buffer_start = now;
+            }
+            self.reset_generation.fetch_add(1, Ordering::SeqCst);
         }
 
         /// Clean an inference result and, if it survives, emit it on `event`
@@ -383,10 +429,21 @@ mod macos {
         // threshold. Whisper hallucinates filler ("you", "thank you") on
         // silent audio, so we NEVER run inference on a buffer with no voice.
         let mut had_voice = false;
+        let mut seen_reset_generation = stream.reset_generation.load(Ordering::SeqCst);
 
         while stream.running.load(Ordering::SeqCst) {
             std::thread::sleep(Duration::from_millis(250));
 
+            let reset_generation = stream.reset_generation.load(Ordering::SeqCst);
+            if reset_generation != seen_reset_generation {
+                seen_reset_generation = reset_generation;
+                last_len = 0;
+                last_voice = Instant::now();
+                last_infer = Instant::now() - Duration::from_secs(10);
+                had_voice = false;
+                continue;
+            }
+
             // Clone the raw buffer (cheap relative to inference), then resample
             // to 16 kHz here on the worker rather than on the audio thread.
             let raw = match stream.buf.lock() {
@@ -395,6 +452,9 @@ mod macos {
             };
             let src_rate = stream.src_rate.load(Ordering::SeqCst) as f64;
             let samples = resample_to_16k(&raw, src_rate);
+            if stream.reset_generation.load(Ordering::SeqCst) != seen_reset_generation {
+                continue;
+            }
             let len = samples.len();
 
             // Track voice activity over the newly-arrived region.
@@ -489,6 +549,28 @@ mod macos {
 
     // ---- session ----------------------------------------------------------
 
+    /// Who owns an in-flight whisper `Session`. Mirrors
+    /// `native_speech::macos::SessionOwner` — meeting beats dictation; all
+    /// other combinations (same owner replacing itself, or a meeting evicting
+    /// a dictation session) keep the original unconditional stop+replace
+    /// behavior.
+    #[derive(Clone, Copy, PartialEq, Eq, Debug)]
+    pub(crate) enum SessionOwner {
+        Dictation,
+        Meeting,
+    }
+
+    impl SessionOwner {
+        /// Parses the Tauri command's `owner` string param, defaulting to
+        /// `Dictation` for back-compat with callers that omit it.
+        pub(crate) fn from_param(owner: Option<String>) -> Self {
+            match owner.as_deref() {
+                Some("meeting") => SessionOwner::Meeting,
+                _ => SessionOwner::Dictation,
+            }
+        }
+    }
+
     struct Session {
         mic_cap: RawMicCapture,
         // System capture is optional — skipped when the user turns system
@@ -496,6 +578,8 @@ mod macos {
         sys_cap: Option<RawSystemCapture>,
         mic: Arc<WhisperStream>,
         sys: Option<Arc<WhisperStream>>,
+        /// Who started this session — see `SessionOwner`.
+        owner: SessionOwner,
     }
 
     // SAFETY: the capture handles hold refcounted ObjC objects (already
@@ -514,8 +598,25 @@ mod macos {
         mic_device_id: Option<String>,
         mic_device_label: Option<String>,
         capture_system: bool,
+        voice_processing: bool,
+        owner: SessionOwner,
     ) -> Result<(), String> {
-        // Tear down any prior session first.
+        // Priority rule (D10): a meeting-owned session must never be
+        // silently evicted by a dictation takeover. Check (without taking)
+        // BEFORE calling `stop()`, so a refused dictation start leaves the
+        // meeting's session completely untouched.
+        {
+            let slot = session_slot().lock().map_err(|e| e.to_string())?;
+            if let Some(prev) = slot.as_ref() {
+                if prev.owner == SessionOwner::Meeting && owner == SessionOwner::Dictation {
+                    return Err("speech-engine-busy-meeting".into());
+                }
+            }
+        }
+
+        // Tear down any prior session first. (Any other owner combination —
+        // same-owner replacement, or meeting evicting dictation — keeps this
+        // unconditional stop+replace behavior.)
         stop(&app);
 
         // Download (first run) + load the model before opening any capture so a
@@ -559,6 +660,7 @@ mod macos {
             app.clone(),
             mic_device_id,
             mic_device_label,
+            voice_processing,
             Arc::new(move |s: &[f32]| mic_for_cb.push(s)),
         )
         .map_err(|e| {
@@ -603,6 +705,7 @@ mod macos {
             sys_cap,
             mic: mic_stream,
             sys: sys_stream,
+            owner,
         });
         eprintln!(
             "[whisper] transcription started (mic{})",
@@ -611,6 +714,26 @@ mod macos {
         Ok(())
     }
 
+    pub fn reset_timeline() {
+        let session = match session_slot().lock() {
+            Ok(slot) => slot.as_ref().map(|session| {
+                (
+                    session.mic.clone(),
+                    session.sys.as_ref().map(|stream| stream.clone()),
+                )
+            }),
+            Err(_) => None,
+        };
+        let Some((mic, sys)) = session else {
+            return;
+        };
+        mic.reset_timeline();
+        if let Some(sys) = sys {
+            sys.reset_timeline();
+        }
+        eprintln!("[whisper] transcription timeline reset");
+    }
+
     pub fn stop(_app: &AppHandle) {
         let session = match session_slot().lock() {
             Ok(mut slot) => slot.take(),

package/corpus/templates/clips/desktop/vite.config.ts

@@ -85,6 +85,9 @@ export default defineConfig({
       resolveSentryEnvironment(),
     ),
     __CLIPS_DESKTOP_VERSION__: JSON.stringify(packageJson.version ?? "0.0.0"),
+    __CLIPS_DESKTOP_LOCAL_BUILD__: JSON.stringify(
+      process.env.CLIPS_DESKTOP_LOCAL_BUILD === "1",
+    ),
   },
   server: {
     port: 1420,

package/corpus/templates/clips/package.json

@@ -12,7 +12,7 @@
     "script": "agent-native script",
     "tauri": "cd desktop && pnpm tauri",
     "tauri:dev": "cd desktop && pnpm tauri dev",
-    "tauri:build": "cd desktop && pnpm tauri build",
+    "tauri:build": "cd desktop && pnpm run build:tauri",
     "chrome:dev": "cd chrome-extension && pnpm dev",
     "chrome:build": "cd chrome-extension && pnpm build",
     "chrome:package": "cd chrome-extension && pnpm package",

package/corpus/templates/clips/server/db/schema.ts

@@ -223,6 +223,12 @@ export const recordingTranscripts = table("recording_transcripts", {
     .notNull()
     .default("pending"),
   failureReason: text("failure_reason"),
+  // Count of automatic retries already attempted after a transient failure
+  // (ffmpeg timeout, transient provider/network error). Bounds the
+  // fire-and-forget auto-retry pass in request-transcript.ts so a repeatedly
+  // failing clip doesn't retry forever. Manual retries (force=true) don't
+  // consume this budget.
+  retryCount: integer("retry_count").notNull().default(0),
   createdAt: text("created_at").notNull().default(now()),
   updatedAt: text("updated_at").notNull().default(now()),
 });
@@ -344,6 +350,26 @@ export const recordingViewers = table("recording_viewers", {
     .default(false),
 });
 
+// Per-view records — one row per distinct counted view, so the owner can see
+// *who viewed and when* (not just an aggregate count or a single
+// first/last-seen row per viewer). Additive on top of `recording_viewers`:
+// that table still drives dedup/aggregation for the counting rule, this table
+// is an append-only log of the moments a view was actually counted.
+export const recordingViews = table("recording_views", {
+  id: text("id").primaryKey(),
+  recordingId: text("recording_id").notNull(),
+  // FK to recording_viewers.id — the viewer/session this view belongs to.
+  viewerId: text("viewer_id").notNull(),
+  // Stable key for this viewer (email or anonymous session key), used to
+  // collapse duplicate threshold posts for a single player-open session.
+  viewerKey: text("viewer_key"),
+  viewSessionId: text("view_session_id"),
+  // Denormalized for cheap reads without joining recording_viewers.
+  viewerEmail: text("viewer_email"), // null = anonymous
+  viewerName: text("viewer_name"),
+  viewedAt: text("viewed_at").notNull().default(now()),
+});
+
 // -----------------------------------------------------------------------------
 // Meetings (Granola-style) — recording + transcript + AI notes anchored to
 // a calendar event or an ad-hoc meeting block. Composes with the existing

package/corpus/templates/clips/server/jobs/builder-media-compression.ts

@@ -0,0 +1,41 @@
+/**
+ * builder-media-compression — recurring job (every 5 min).
+ *
+ * Clips upload completion intentionally skips Builder's inline video
+ * compression wait so recording saves do not inherit the upload API's timeout
+ * risk. This job finishes that work out of band: trigger Builder's existing
+ * compress-media endpoint, poll the deterministic `/compressed` object, and
+ * swap the recording row once it exists. The original media URL remains usable
+ * the whole time.
+ */
+
+import { runBuilderMediaCompressionSweepOnce } from "../lib/builder-media-compression.js";
+
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+let skippingLogged = false;
+
+export { runBuilderMediaCompressionSweepOnce };
+
+export default function registerBuilderMediaCompressionJob(): void {
+  const isProd = process.env.NODE_ENV === "production";
+  const flag = process.env.RUN_BACKGROUND_JOBS;
+  const enabled = flag === "1" || (isProd && flag !== "0");
+  if (!enabled) {
+    if (process.env.DEBUG && !skippingLogged) {
+      console.log(
+        "[builder-media-compression] Skipping background compression sweep (set RUN_BACKGROUND_JOBS=1 to enable in dev).",
+      );
+      skippingLogged = true;
+    }
+    return;
+  }
+
+  setInterval(() => {
+    runBuilderMediaCompressionSweepOnce().catch((err) =>
+      console.error("[builder-media-compression] interval failed:", err),
+    );
+  }, SWEEP_INTERVAL_MS);
+  console.log(
+    `[builder-media-compression] Recurring compression sweep every ${SWEEP_INTERVAL_MS / 1000}s.`,
+  );
+}

package/corpus/templates/clips/server/jobs/stale-meeting-sweeper.ts

@@ -0,0 +1,294 @@
+/**
+ * stale-meeting-sweeper — recurring job (every 5 min).
+ *
+ * Reconciles meetings stranded "live" forever by a desktop crash/force-quit
+ * (actualStart set, actualEnd never stamped — see lib.rs's RunEvent::Exit
+ * handler, which only kills the screencapture fallback child, never runs
+ * meeting teardown). Without this, such a row keeps a permanent Live badge,
+ * the detail page polls get-meeting every 2s forever, the linked recording
+ * stays "uploading", and notes never generate.
+ *
+ * Staleness definition (conservative — never end a genuinely live meeting):
+ *   - actualStart IS NOT NULL AND actualEnd IS NULL AND trashedAt IS NULL
+ *   - last transcript activity (recording_transcripts.updatedAt, or
+ *     meetings.updatedAt if no transcript row) is older than
+ *     STALE_THRESHOLD_MS — the desktop flushes the transcript at least every
+ *     1.5s while genuinely live, so this many minutes of silence is
+ *     decisive.
+ *   - scheduledEnd IS NULL OR scheduledEnd < now — if the scheduled window
+ *     is still in the future, skip: the user may have simply paused.
+ *
+ * Mirrors what `actions/stop-meeting-recording.ts` does when a user
+ * manually stops (kept as a small duplicated helper here rather than
+ * importing that action file, which is outside this slice's ownership):
+ * stamp actualEnd, flip transcriptStatus to 'ready'/'failed' based on
+ * whether transcript text exists, and flip the linked recording out of
+ * 'uploading'. Exported so `actions/delete-meeting.ts` can reuse the same
+ * close-out logic when trashing a meeting that's still live.
+ *
+ * A second, independent pass (`sweepStalePendingFinalizes`) reconciles
+ * meetings stranded in transcriptStatus='pending' by a server crash
+ * mid-finalize. This predicate deliberately does not require `actualEnd IS
+ * NULL`: a meeting reaching the finalize CAS already has `actualEnd` stamped,
+ * so gating on live-meeting shape would never match. Restoring to 'failed'
+ * unblocks both manual "Regenerate notes" and an ordinary finalize retry.
+ */
+
+import { runWithRequestContext } from "@agent-native/core/server/request-context";
+import { and, eq, isNotNull, isNull, lt, or } from "drizzle-orm";
+
+import finalizeMeeting from "../../actions/finalize-meeting.js";
+import { getDb, schema } from "../db/index.js";
+
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 min
+const STALE_THRESHOLD_MS = 60 * 60 * 1000; // 60 min of zero transcript activity
+// A finalize claim with no update in this long is presumed crashed, not merely
+// a slow Gemini call. Mirrors finalize-meeting.ts's force-takeover window.
+const PENDING_STALE_MS = 2 * 60 * 1000; // 2 min
+let skippingLogged = false;
+
+/**
+ * Close out a single stranded-live meeting row: stamp actualEnd, set
+ * transcriptStatus based on transcript presence, and flip a still-uploading
+ * linked recording to ready. Shared by the sweeper and by delete-meeting
+ * (trashing a live meeting should stop it the same way).
+ */
+export async function closeOutStaleMeeting(args: {
+  meetingId: string;
+  recordingId: string | null;
+  ownerEmail: string;
+  orgId: string | null;
+  /** Estimated end timestamp — pass the transcript's last updatedAt when
+   * available so actualEnd reflects when activity actually stopped, not
+   * "now" (which could be hours after the crash). */
+  endedAtIso?: string;
+}): Promise<{ hasTranscript: boolean }> {
+  const db = getDb();
+  const nowIso = new Date().toISOString();
+
+  let hasTranscript = false;
+  if (args.recordingId) {
+    const [transcript] = await db
+      .select({ fullText: schema.recordingTranscripts.fullText })
+      .from(schema.recordingTranscripts)
+      .where(eq(schema.recordingTranscripts.recordingId, args.recordingId))
+      .limit(1);
+    hasTranscript = Boolean(transcript?.fullText?.trim());
+  }
+
+  const meetingOwnershipScope = args.orgId
+    ? and(
+        eq(schema.meetings.ownerEmail, args.ownerEmail),
+        eq(schema.meetings.orgId, args.orgId),
+      )
+    : and(
+        eq(schema.meetings.ownerEmail, args.ownerEmail),
+        isNull(schema.meetings.orgId),
+      );
+
+  await db
+    .update(schema.meetings)
+    .set({
+      actualEnd: args.endedAtIso ?? nowIso,
+      updatedAt: nowIso,
+      transcriptStatus: hasTranscript ? "ready" : "failed",
+    })
+    .where(and(eq(schema.meetings.id, args.meetingId), meetingOwnershipScope));
+
+  if (args.recordingId) {
+    const recordingOwnershipScope = args.orgId
+      ? and(
+          eq(schema.recordings.ownerEmail, args.ownerEmail),
+          eq(schema.recordings.orgId, args.orgId),
+        )
+      : and(
+          eq(schema.recordings.ownerEmail, args.ownerEmail),
+          isNull(schema.recordings.orgId),
+        );
+
+    await db
+      .update(schema.recordings)
+      .set({ status: "ready", updatedAt: nowIso })
+      .where(
+        and(
+          eq(schema.recordings.id, args.recordingId),
+          eq(schema.recordings.status, "uploading"),
+          recordingOwnershipScope,
+        ),
+      );
+  }
+
+  return { hasTranscript };
+}
+
+/**
+ * Restore any meeting stuck in transcriptStatus='pending' for longer than
+ * PENDING_STALE_MS back to 'failed'. Deliberately independent of `actualEnd`
+ * because meetings reach the finalize CAS only after `actualEnd` is already
+ * stamped. CAS-guarded on transcriptStatus='pending' so this can't race a
+ * finalize call that completes concurrently.
+ */
+async function sweepStalePendingFinalizes(db: ReturnType<typeof getDb>) {
+  const staleBefore = new Date(Date.now() - PENDING_STALE_MS).toISOString();
+  // guard:allow-unscoped — background recovery scans all owners for crash-stranded finalize claims.
+  const stuck = await db
+    .select({ id: schema.meetings.id, updatedAt: schema.meetings.updatedAt })
+    .from(schema.meetings)
+    .where(
+      and(
+        eq(schema.meetings.transcriptStatus, "pending"),
+        lt(schema.meetings.updatedAt, staleBefore),
+      ),
+    );
+
+  for (const meeting of stuck) {
+    try {
+      const nowIso = new Date().toISOString();
+      const restored = await db
+        .update(schema.meetings)
+        .set({ transcriptStatus: "failed", updatedAt: nowIso })
+        .where(
+          and(
+            eq(schema.meetings.id, meeting.id),
+            eq(schema.meetings.transcriptStatus, "pending"),
+          ),
+        )
+        .returning({ id: schema.meetings.id });
+      if (restored.length) {
+        console.log(
+          `[stale-meeting-sweeper] restored crash-stranded pending finalize ${meeting.id} (stuck since ${meeting.updatedAt})`,
+        );
+      }
+    } catch (err: any) {
+      console.warn(
+        `[stale-meeting-sweeper] failed to restore stuck-pending ${meeting.id}:`,
+        err?.message ?? err,
+      );
+    }
+  }
+}
+
+export async function runStaleMeetingSweepOnce(): Promise<void> {
+  await runWithRequestContext({}, async () => {
+    const db = getDb();
+    const now = new Date();
+    const nowIso = now.toISOString();
+    const staleBefore = new Date(
+      now.getTime() - STALE_THRESHOLD_MS,
+    ).toISOString();
+
+    try {
+      const candidates = await db
+        .select({
+          id: schema.meetings.id,
+          recordingId: schema.meetings.recordingId,
+          ownerEmail: schema.meetings.ownerEmail,
+          orgId: schema.meetings.orgId,
+          updatedAt: schema.meetings.updatedAt,
+          scheduledEnd: schema.meetings.scheduledEnd,
+        })
+        .from(schema.meetings)
+        .where(
+          and(
+            isNotNull(schema.meetings.actualStart),
+            isNull(schema.meetings.actualEnd),
+            isNull(schema.meetings.trashedAt),
+            or(
+              isNull(schema.meetings.scheduledEnd),
+              lt(schema.meetings.scheduledEnd, nowIso),
+            ),
+          ),
+        );
+
+      for (const meeting of candidates) {
+        try {
+          let lastActivityIso = meeting.updatedAt;
+          if (meeting.recordingId) {
+            const [transcript] = await db
+              .select({ updatedAt: schema.recordingTranscripts.updatedAt })
+              .from(schema.recordingTranscripts)
+              .where(
+                eq(
+                  schema.recordingTranscripts.recordingId,
+                  meeting.recordingId,
+                ),
+              )
+              .limit(1);
+            if (transcript?.updatedAt) lastActivityIso = transcript.updatedAt;
+          }
+          if (!lastActivityIso || lastActivityIso > staleBefore) continue;
+
+          const closed = await closeOutStaleMeeting({
+            meetingId: meeting.id,
+            recordingId: meeting.recordingId,
+            ownerEmail: meeting.ownerEmail,
+            orgId: meeting.orgId,
+            endedAtIso: lastActivityIso,
+          });
+          if (closed.hasTranscript) {
+            try {
+              await runWithRequestContext(
+                {
+                  userEmail: meeting.ownerEmail,
+                  orgId: meeting.orgId ?? undefined,
+                },
+                async () => {
+                  await finalizeMeeting.run({ meetingId: meeting.id });
+                },
+              );
+            } catch (err: any) {
+              console.warn(
+                `[stale-meeting-sweeper] failed to finalize recovered meeting ${meeting.id}:`,
+                err?.message ?? err,
+              );
+            }
+          }
+          console.log(
+            `[stale-meeting-sweeper] closed out stranded-live meeting ${meeting.id} (last activity ${lastActivityIso})`,
+          );
+        } catch (err: any) {
+          console.warn(
+            `[stale-meeting-sweeper] failed to close out ${meeting.id}:`,
+            err?.message ?? err,
+          );
+        }
+      }
+    } catch (err: any) {
+      // Best-effort — must never crash the host process.
+      console.warn(`[stale-meeting-sweeper] tick failed:`, err?.message ?? err);
+    }
+
+    try {
+      await sweepStalePendingFinalizes(db);
+    } catch (err: any) {
+      // Best-effort — must never crash the host process.
+      console.warn(
+        `[stale-meeting-sweeper] pending-finalize sweep failed:`,
+        err?.message ?? err,
+      );
+    }
+  });
+}
+
+export default function registerStaleMeetingSweeperJob(): void {
+  const isProd = process.env.NODE_ENV === "production";
+  const flag = process.env.RUN_BACKGROUND_JOBS;
+  const enabled = flag === "1" || (isProd && flag !== "0");
+  if (!enabled) {
+    if (process.env.DEBUG && !skippingLogged) {
+      console.log(
+        "[stale-meeting-sweeper] Skipping background sweep (set RUN_BACKGROUND_JOBS=1 to enable in dev).",
+      );
+      skippingLogged = true;
+    }
+    return;
+  }
+  setInterval(() => {
+    runStaleMeetingSweepOnce().catch((err) =>
+      console.error("[stale-meeting-sweeper] interval failed:", err),
+    );
+  }, SWEEP_INTERVAL_MS);
+  console.log(
+    `[stale-meeting-sweeper] Recurring stale-meeting reconciliation every ${SWEEP_INTERVAL_MS / 1000}s.`,
+  );
+}