@agent-native/core 0.84.22 → 0.84.24

package/corpus/templates/analytics/server/lib/analytics-alerts.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 
-import { notify } from "@agent-native/core/notifications";
+import { notifyWithDelivery } from "@agent-native/core/notifications";
 import { recordChange } from "@agent-native/core/server";
-import { and, asc, desc, eq, gte, isNull, lte, sql } from "drizzle-orm";
+import { and, asc, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -21,7 +21,12 @@ export interface AnalyticsAlertFilter {
 
 export type AnalyticsAlertThresholdMode = "event_count" | "distinct_count";
 export type AnalyticsAlertSeverity = "warning" | "critical";
-export type AnalyticsAlertStatus = "ok" | "triggered" | "cooldown" | "error";
+export type AnalyticsAlertStatus =
+  | "ok"
+  | "triggered"
+  | "cooldown"
+  | "error"
+  | "running";
 
 export interface AnalyticsAlertRuleInput {
   id?: string;
@@ -108,6 +113,8 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+const ALERT_RULE_RUNNING_STALE_MS = 15 * 60 * 1000;
+
 function safeJsonParse<T>(raw: unknown, fallback: T): T {
   if (typeof raw !== "string" || !raw.trim()) return fallback;
   try {
@@ -372,6 +379,7 @@ export async function listEnabledAnalyticsAlertRules(options: {
       options.orgId ? eq(table.orgId, options.orgId) : isNull(table.orgId),
     );
   }
+  clauses.push(alertRuleNotRunningWhere(new Date()));
   const rows = await db
     .select()
     .from(table)
@@ -385,6 +393,52 @@ export async function listEnabledAnalyticsAlertRules(options: {
   return rows.map(rowToRule);
 }
 
+function alertRuleNotRunningWhere(now: Date) {
+  const table = schema.analyticsAlertRules;
+  const staleRunningBefore = new Date(
+    now.getTime() - ALERT_RULE_RUNNING_STALE_MS,
+  ).toISOString();
+  return or(
+    isNull(table.lastStatus),
+    sql`${table.lastStatus} <> 'running'`,
+    isNull(table.lastEvaluatedAt),
+    lte(table.lastEvaluatedAt, staleRunningBefore),
+  );
+}
+
+function alertRulePreviousEvaluationWhere(rule: AnalyticsAlertRule) {
+  const table = schema.analyticsAlertRules;
+  return rule.lastEvaluatedAt
+    ? eq(table.lastEvaluatedAt, rule.lastEvaluatedAt)
+    : isNull(table.lastEvaluatedAt);
+}
+
+export async function claimAnalyticsAlertRuleEvaluation(
+  rule: AnalyticsAlertRule,
+  now: Date = new Date(),
+): Promise<boolean> {
+  const db = getDb() as any;
+  const table = schema.analyticsAlertRules;
+  const claimedAt = now.toISOString();
+  const rows = await db
+    .update(table)
+    .set({
+      lastEvaluatedAt: claimedAt,
+      lastStatus: "running",
+      lastError: null,
+    })
+    .where(
+      and(
+        eq(table.id, rule.id),
+        eq(table.enabled, true),
+        alertRuleNotRunningWhere(now),
+        alertRulePreviousEvaluationWhere(rule),
+      ),
+    )
+    .returning({ id: table.id });
+  return rows.length > 0;
+}
+
 export async function evaluateAndNotifyAnalyticsAlertRule(
   rule: AnalyticsAlertRule,
   now: Date = new Date(),
@@ -416,12 +470,13 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
   }
 
   const body = alertBody(rule, evaluation);
-  const stored = await notify(
+  const channels = ensureInboxNotificationChannel(rule.channels);
+  const delivery = await notifyWithDelivery(
     {
       severity: rule.severity,
       title: `Analytics alert: ${rule.name}`,
       body,
-      channels: rule.channels,
+      channels,
       metadata: {
         kind: "analytics_alert",
         ruleId: rule.id,
@@ -438,13 +493,22 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
         filters: rule.filters,
         sampleEvents: evaluation.sampleEvents,
         emailRecipients: rule.emailRecipients,
+        requestedChannels: rule.channels,
       },
     },
     { owner: rule.ownerEmail },
   );
+  if (delivery.deliveredChannels.length === 0) {
+    await markRuleStatus(rule.id, {
+      lastEvaluatedAt: evaluatedAt,
+      lastStatus: "error",
+      lastError: "Analytics alert notification was not delivered.",
+    });
+    return { ruleId: rule.id, status: "error", ...evaluation };
+  }
 
   await recordIncident(rule, {
-    notificationId: stored?.id,
+    notificationId: delivery.notification?.id,
     triggeredAt: evaluatedAt,
     windowStart,
     windowEnd,
@@ -459,11 +523,16 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
   return {
     ruleId: rule.id,
     status: "triggered",
-    notificationId: stored?.id,
+    notificationId: delivery.notification?.id,
     ...evaluation,
   };
 }
 
+function ensureInboxNotificationChannel(channels: string[]): string[] {
+  const normalized = channels.map((channel) => channel.trim()).filter(Boolean);
+  return normalized.includes("inbox") ? normalized : ["inbox", ...normalized];
+}
+
 export async function markAnalyticsAlertRuleError(
   id: string,
   error: unknown,

package/corpus/templates/assets/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/brain/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/calendar/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/clips/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/clips/.agents/skills/recording/SKILL.md

@@ -31,9 +31,38 @@ Some recordings are linked to a meeting — when `meeting_id` is non-null on the
 4. **Record.** Start a `MediaRecorder` with `mimeType: "video/webm;codecs=vp9,opus"` (fallback to vp8, then browser default). Use `timeslice: 2000` so chunks arrive every 2s.
 5. **Upload each chunk.** `ondataavailable` POSTs the chunk bytes to `/api/uploads/chunk` with headers `X-Recording-Id` and `X-Chunk-Index`. Don't retry inline — buffer failed chunks in `IndexedDB` and let a background worker re-send.
 6. **Live transcription.** Alongside the MediaRecorder, `useLiveTranscription` runs the Web Speech API to accumulate transcript text in real time. On stop, the client calls `save-browser-transcript` to persist the result immediately — no API key needed. Desktop recordings use local Whisper/macOS speech first when available, and fall back to Web Speech in the webview on non-mac before relying on upload transcription.
-7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
+7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, makes the media seekable (see below), uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
 8. **Navigate.** Once the row is `ready` the UI navigates to `/r/:id`.
 
+## Seekable playback (don't ship raw MediaRecorder output)
+
+Raw `MediaRecorder` files are not friendly to progressive HTTP playback, which
+shows up as "clip takes minutes to load" and "re-buffers every time I seek"
+even though the file downloads fine:
+
+- **MP4** is written with the `moov` metadata atom *after* `mdat`, so a player
+  must fetch the whole file before it can start or seek.
+- **WebM** is a live stream with no Cues (seek index) and an unknown Segment
+  duration, so Chrome won't honor `currentTime = X` and has to scan/download.
+
+`finalize-recording` fixes this before upload: MP4 gets pure-TS faststart
+(`server/lib/faststart.ts`), WebM gets a lossless `ffmpeg -c copy` remux that
+writes a SeekHead + Cues + real duration (`server/lib/video-remux.ts`). Both are
+best-effort — on failure we upload the original, never block finalize. Recordings
+above `CLIPS_INLINE_REMUX_MAX_BYTES` (default 200 MB) skip the inline pass and
+are repaired in the background.
+
+The **streaming/resumable** upload path forwards raw bytes straight to the
+provider and cannot rewrite them inline, so `finalize-recording` schedules a
+background `ensureRecordingSeekable` pass for those.
+
+To repair clips uploaded before this existed (or via streaming), call the
+`reprocess-recording` action: `--id`, `--ids='[...]'`, or `--all --limit=N`. It
+re-fetches provider media, rewrites it, re-uploads, and repoints the row. It's
+idempotent (already-seekable clips are skipped unless `--force`) and only touches
+provider-hosted clips owned by the caller. This is the right tool when a user
+reports a specific slow/buffering clip.
+
 ## Loom import
 
 Use `import-loom-recording` for Loom share or embed URLs. The action validates

package/corpus/templates/clips/actions/finalize-recording.ts

@@ -40,12 +40,27 @@ import {
   getResumableSession,
 } from "../server/lib/resumable-session.js";
 import { isStreamingUploadDisabled } from "../server/lib/streaming-upload-mode.js";
+import { remuxWebmToSeekable } from "../server/lib/video-remux.js";
 import {
   requiresConfiguredVideoStorage,
   STORAGE_SETUP_REQUIRED_REASON,
 } from "../server/lib/video-storage.js";
+import {
+  ensureRecordingSeekable,
+  markRecordingSeekable,
+} from "./lib/ensure-seekable-video.js";
 import requestTranscript from "./request-transcript.js";
 
+// Recordings up to this size get their seekable rewrite applied inline during
+// finalize (we already hold the assembled bytes). Larger recordings are handed
+// off to the background/reprocess path so we don't stretch the finalize
+// request or exhaust serverless /tmp. Override with CLIPS_INLINE_REMUX_MAX_BYTES.
+function inlineRemuxMaxBytes(): number {
+  const raw = Number(process.env.CLIPS_INLINE_REMUX_MAX_BYTES ?? "");
+  if (Number.isFinite(raw) && raw > 0) return Math.floor(raw);
+  return 200 * 1024 * 1024;
+}
+
 /**
  * Decode a base64 string back into a Uint8Array.
  * We store chunks as base64 in application_state because the SQL JSON
@@ -118,6 +133,10 @@ async function markRecordingReady(params: {
   finalHasAudio: boolean;
   finalHasCamera: boolean;
   existingTitle: string;
+  // Whether a seekable rewrite (MP4 faststart / WebM Cues remux) was already
+  // applied to the uploaded bytes. When false, a best-effort background repair
+  // is triggered so streamed/raw uploads still become seekable.
+  seekableApplied: boolean;
 }) {
   const {
     id,
@@ -131,6 +150,7 @@ async function markRecordingReady(params: {
     finalHasAudio,
     finalHasCamera,
     existingTitle,
+    seekableApplied,
   } = params;
   const db = getDb();
   const now = new Date().toISOString();
@@ -181,6 +201,30 @@ async function markRecordingReady(params: {
   });
   await writeAppState("refresh-signal", { ts: Date.now() });
 
+  if (seekableApplied) {
+    // Uploaded bytes are already start-playable and seekable — remember it so
+    // later reprocess sweeps skip this clip.
+    await markRecordingSeekable(id, videoUrl).catch((err) => {
+      console.warn("[finalize] failed to write seekable marker", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  } else {
+    // Streaming/resumable (or oversized) uploads shipped raw MediaRecorder
+    // bytes with no seekable rewrite: an MP4 with a trailing moov or a WebM
+    // without a Cues index buffers on load and re-buffers on every seek. Fix
+    // it in the background so playback is smooth without blocking finalize.
+    void Promise.resolve(
+      ensureRecordingSeekable({ recordingId: id, ownerEmail }),
+    ).catch((err: unknown) => {
+      console.warn("[finalize] background seekable remux failed", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  }
+
   // Kick off transcription in the background — fire-and-forget so the chunk
   // endpoint gets a quick response. The request context (user email via
   // AsyncLocalStorage) carries through to async continuations.
@@ -375,6 +419,10 @@ export default defineAction({
             ...readyParams,
             videoUrl,
             videoSizeBytes: resumableSession.bytesUploaded,
+            // Streaming path forwards raw MediaRecorder bytes straight to the
+            // provider — no faststart/Cues rewrite happened. Repair in the
+            // background.
+            seekableApplied: false,
           });
           // Delete only after durable state is written — so a retry before
           // this point can still find the session and re-enter this path.
@@ -521,9 +569,14 @@ export default defineAction({
       // recordings.
       parts.length = 0;
 
-      // Apply faststart to MP4 files — moves the moov atom before mdat so
-      // browsers can begin playback immediately via HTTP range requests.
+      // Make the assembled recording seekable before upload — we already hold
+      // the full bytes, so a viewer never has to wait through a non-seekable
+      // first play. MP4: relocate moov ahead of mdat (pure TS). WebM: remux to
+      // add a Cues index + real duration (ffmpeg -c copy). When neither runs
+      // (unknown format, oversized, or ffmpeg unavailable) `seekableApplied`
+      // stays false and markRecordingReady schedules a background repair.
       let uploadData = assembled;
+      let seekableApplied = false;
       if (videoFormat === "mp4") {
         try {
           uploadData = applyFaststart(assembled);
@@ -561,6 +614,32 @@ export default defineAction({
           }
           throw err;
         }
+        // moov is present and validated — the MP4 is start-playable/seekable.
+        seekableApplied = true;
+      } else if (videoFormat === "webm") {
+        // MediaRecorder WebM has no Cues index and an unknown duration, so
+        // Chrome buffers on load and re-buffers on every seek. A lossless
+        // `ffmpeg -c copy` remux rewrites it with a SeekHead + Cues + real
+        // duration. Bounded by size so finalize stays fast; larger clips get a
+        // background pass. Best-effort: on any failure we upload the original.
+        if (assembled.byteLength <= inlineRemuxMaxBytes()) {
+          try {
+            const seekable = await remuxWebmToSeekable(uploadData);
+            if (seekable.changed) {
+              uploadData = seekable.bytes;
+              seekableApplied = true;
+              debugLog("[finalize] webm remux applied", {
+                id,
+                bytes: uploadData.byteLength,
+              });
+            }
+          } catch (err) {
+            console.warn("[finalize] webm remux failed, uploading as-is", {
+              id,
+              err: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
       }
 
       let upload: Awaited<ReturnType<typeof uploadFile>>;
@@ -721,12 +800,13 @@ export default defineAction({
       debugLog("[finalize] done", {
         id,
         videoUrl: upload.url,
-        bytes: assembled.byteLength,
+        bytes: uploadData.byteLength,
       });
       return markRecordingReady({
         ...readyParams,
         videoUrl: upload.url,
-        videoSizeBytes: assembled.byteLength,
+        videoSizeBytes: uploadData.byteLength,
+        seekableApplied,
       });
     } finally {
       // Unconditional chunk scratch-space cleanup. Runs on success AND on

package/corpus/templates/clips/actions/lib/ensure-seekable-video.ts

@@ -0,0 +1,256 @@
+/**
+ * Repair an already-stored recording so it plays back and seeks instantly.
+ *
+ * This is the fetch-based counterpart to the inline seekable pass in
+ * `finalize-recording`. It re-fetches a recording's stored provider media,
+ * runs the format-appropriate seekable rewrite (MP4 faststart / WebM Cues
+ * remux), and, when that changed the bytes, re-uploads the fixed file and
+ * repoints the recording at it.
+ *
+ * Used by:
+ *   - `reprocess-recording` — owner/agent triggered backfill of clips that were
+ *     uploaded before the seekable pass existed (or via the streaming path,
+ *     which never applied it).
+ *   - `finalize-recording` — a best-effort background pass for the resumable
+ *     streaming path, whose bytes live at the provider and were never buffered
+ *     server-side for an inline rewrite.
+ *
+ * Everything is best-effort and non-destructive: if we can't fetch, can't
+ * improve, or can't re-upload, the existing recording is left exactly as-is.
+ */
+
+import {
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { MAX_UPLOAD_BYTES } from "@shared/upload-limits.js";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../../server/db/index.js";
+import { ownerEmailMatches } from "../../server/lib/recordings.js";
+import {
+  makeSeekable,
+  type VideoFormat,
+} from "../../server/lib/video-remux.js";
+import { isLoomRecordingSource } from "../../shared/loom.js";
+
+const PROVIDER_FETCH_TIMEOUT_MS = 60_000;
+
+export type EnsureSeekableStatus =
+  | "optimized"
+  | "already-optimized"
+  | "skipped-not-ready"
+  | "skipped-no-media"
+  | "skipped-local-media"
+  | "skipped-too-large"
+  | "skipped-fetch-failed"
+  | "skipped-upload-failed"
+  | "not-found";
+
+export interface EnsureSeekableResult {
+  recordingId: string;
+  status: EnsureSeekableStatus;
+  changed: boolean;
+  videoUrl?: string | null;
+  detail?: string;
+}
+
+/** application_state key marking a recording's media as already made seekable. */
+export function seekableMarkerKey(recordingId: string): string {
+  return `recording-seekable-${recordingId}`;
+}
+
+/**
+ * Record that `videoUrl` for `recordingId` has been made seekable, so later
+ * sweeps skip it. Scoped by URL so a re-upload that changes the URL is not
+ * mistaken for already-processed.
+ */
+export async function markRecordingSeekable(
+  recordingId: string,
+  videoUrl: string | null | undefined,
+): Promise<void> {
+  await writeAppState(seekableMarkerKey(recordingId), {
+    recordingId,
+    videoUrl: videoUrl ?? null,
+    at: new Date().toISOString(),
+  });
+}
+
+async function isAlreadyMarked(
+  recordingId: string,
+  videoUrl: string | null,
+): Promise<boolean> {
+  const marker = await readAppState(seekableMarkerKey(recordingId)).catch(
+    () => null,
+  );
+  return Boolean(
+    marker &&
+    typeof marker === "object" &&
+    (marker as { videoUrl?: unknown }).videoUrl === videoUrl,
+  );
+}
+
+function isRemoteProviderUrl(videoUrl: string | null | undefined): boolean {
+  return typeof videoUrl === "string" && /^https:\/\//i.test(videoUrl.trim());
+}
+
+async function fetchProviderBytes(
+  videoUrl: string,
+): Promise<
+  { ok: true; bytes: Uint8Array } | { ok: false; reason: EnsureSeekableStatus }
+> {
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    PROVIDER_FETCH_TIMEOUT_MS,
+  );
+  try {
+    const res = await fetch(videoUrl, { signal: controller.signal });
+    if (!res.ok) return { ok: false, reason: "skipped-fetch-failed" };
+
+    const declaredLength = Number(res.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength === 0)
+      return { ok: false, reason: "skipped-fetch-failed" };
+    if (buf.byteLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+    return { ok: true, bytes: buf };
+  } catch {
+    return { ok: false, reason: "skipped-fetch-failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Ensure a single recording's stored media is seekable. Owner-scoped: pass the
+ * resolved owner email so the DB lookup can only touch that owner's rows.
+ */
+export async function ensureRecordingSeekable(params: {
+  recordingId: string;
+  ownerEmail: string;
+  force?: boolean;
+}): Promise<EnsureSeekableResult> {
+  const { recordingId, ownerEmail, force = false } = params;
+  const db = getDb();
+
+  const [rec] = await db
+    .select({
+      id: schema.recordings.id,
+      status: schema.recordings.status,
+      videoUrl: schema.recordings.videoUrl,
+      videoFormat: schema.recordings.videoFormat,
+      sourceAppName: schema.recordings.sourceAppName,
+    })
+    .from(schema.recordings)
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  if (!rec) {
+    return { recordingId, status: "not-found", changed: false };
+  }
+  if (rec.status !== "ready") {
+    return { recordingId, status: "skipped-not-ready", changed: false };
+  }
+  if (isLoomRecordingSource(rec)) {
+    return { recordingId, status: "skipped-local-media", changed: false };
+  }
+  if (!rec.videoUrl) {
+    return { recordingId, status: "skipped-no-media", changed: false };
+  }
+  // Only provider-hosted media can be re-fetched and re-uploaded. Local/dev
+  // blobs (served from application_state via /api/video) and other relative
+  // URLs are left untouched.
+  if (!isRemoteProviderUrl(rec.videoUrl)) {
+    return {
+      recordingId,
+      status: "skipped-local-media",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  if (!force && (await isAlreadyMarked(recordingId, rec.videoUrl))) {
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const fetched = await fetchProviderBytes(rec.videoUrl);
+  if (!fetched.ok) {
+    return { recordingId, status: fetched.reason, changed: false };
+  }
+
+  const videoFormat: VideoFormat = rec.videoFormat === "mp4" ? "mp4" : "webm";
+  const seekable = await makeSeekable({
+    mediaBytes: fetched.bytes,
+    videoFormat,
+  });
+
+  if (!seekable.changed) {
+    // Already seekable (or unimprovable) — remember so we don't refetch it.
+    await markRecordingSeekable(recordingId, rec.videoUrl);
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const mimeType = videoFormat === "mp4" ? "video/mp4" : "video/webm";
+  const upload = await uploadFile({
+    data: seekable.bytes,
+    filename: `${recordingId}.${videoFormat}`,
+    mimeType,
+    ownerEmail,
+    skipCompressionWait: true,
+  });
+
+  if (!upload?.url) {
+    // Could not re-upload — do NOT touch the row; the original still plays.
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  await db
+    .update(schema.recordings)
+    .set({
+      videoUrl: upload.url,
+      videoSizeBytes: seekable.bytes.byteLength,
+      updatedAt: new Date().toISOString(),
+    })
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  await markRecordingSeekable(recordingId, upload.url);
+  await writeAppState("refresh-signal", { ts: Date.now() });
+
+  return {
+    recordingId,
+    status: "optimized",
+    changed: true,
+    videoUrl: upload.url,
+  };
+}