@agent-native/core 0.92.12 → 0.94.0

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

@@ -15,11 +15,9 @@ import {
   deleteAppState,
 } from "@agent-native/core/application-state";
 import { emit } from "@agent-native/core/event-bus";
-import {
-  getActiveFileUploadProvider,
-  uploadFile,
-} from "@agent-native/core/file-upload";
+import { uploadFile } from "@agent-native/core/file-upload";
 import { captureRouteError } from "@agent-native/core/server";
+import { isStoredButUnservableFinalizeError } from "@shared/finalize-recovery.js";
 import { MAX_UPLOAD_BYTES as MAX_RECORDING_UPLOAD_BYTES } from "@shared/upload-limits.js";
 import { and, eq, isNull, ne } from "drizzle-orm";
 import { z } from "zod";
@@ -31,6 +29,7 @@ import {
   applyFaststart,
   hasPlayableMp4Metadata,
 } from "../server/lib/faststart.js";
+import { dispatchPostFinalizeJob } from "../server/lib/post-finalize-dispatch.js";
 import {
   listRecordingChunkKeys,
   validateRecordingChunkKeys,
@@ -43,6 +42,7 @@ import {
   deleteResumableSession,
   getResumableSession,
 } from "../server/lib/resumable-session.js";
+import { resolveResumableUploadProvider } from "../server/lib/resumable-upload-provider.js";
 import { isStreamingUploadDisabled } from "../server/lib/streaming-upload-mode.js";
 import {
   probeHasAudioStream,
@@ -52,11 +52,7 @@ 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";
+import { markRecordingSeekable } from "./lib/ensure-seekable-video.js";
 
 // Recordings up to this size get their seekable rewrite applied inline during
 // finalize (we already hold the assembled bytes). Larger recordings are handed
@@ -392,25 +388,28 @@ async function markRecordingReady(params: {
   } 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", {
+    // without a Cues index buffers on load and re-buffers on every seek. A
+    // fresh self-dispatched request owns the repair so serverless runtimes do
+    // not freeze it when this finalize request returns.
+    await dispatchPostFinalizeJob({
+      recordingId: id,
+      kind: "seekable",
+    }).catch((err: unknown) => {
+      console.warn("[finalize] seekable remux dispatch 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.
-  void Promise.resolve(
-    requestTranscript.run({ recordingId: id, force: true }),
-  ).catch((err: unknown) => {
-    console.error("[finalize] background transcript failed", {
+  // Transcription can outlive the upload request. Dispatch it into a fresh
+  // invocation instead of leaving an unawaited promise in this serverless
+  // function, where it can be frozen immediately after the response is sent.
+  await dispatchPostFinalizeJob({
+    recordingId: id,
+    kind: "transcript",
+  }).catch((err: unknown) => {
+    console.error("[finalize] transcript dispatch failed", {
       id,
       error: err instanceof Error ? err.message : String(err),
     });
@@ -511,6 +510,12 @@ export default defineAction({
       // chunks are gone by then).
       if (existing.status === "ready" && existing.videoUrl) {
         debugLog("[finalize] already finalized, returning existing", { id });
+        // A prior attempt may have persisted the ready row and then failed
+        // before deleting its resumable-session handle. The provider upload is
+        // complete at this point, so retire only the local retry state.
+        await deleteResumableSession(id).catch((err) =>
+          console.warn("[finalize] failed to delete resumable session:", err),
+        );
         return {
           id,
           status: "ready" as const,
@@ -581,8 +586,43 @@ export default defineAction({
           id,
           providerId: resumableSession.providerId,
         });
+        if (
+          existing.status === "failed" &&
+          typeof existing.failureReason === "string" &&
+          isStoredButUnservableFinalizeError(existing.failureReason)
+        ) {
+          // Verification failed after the provider may already have completed
+          // the multipart upload. Move only that known-recoverable failure
+          // back to processing. A later user abort writes a different failed
+          // state, and markRecordingReady's status guard will still win.
+          const recoveryStartedAt = new Date().toISOString();
+          await db
+            .update(schema.recordings)
+            .set({
+              status: "processing",
+              failureReason: null,
+              updatedAt: recoveryStartedAt,
+            })
+            .where(
+              and(
+                eq(schema.recordings.id, id),
+                ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+                eq(schema.recordings.status, "failed"),
+                eq(schema.recordings.failureReason, existing.failureReason),
+              ),
+            );
+          await writeAppState(`recording-upload-${id}`, {
+            ...(uploadState ?? {}),
+            recordingId: id,
+            status: "processing",
+            failureReason: null,
+            updatedAt: recoveryStartedAt,
+          });
+        }
         try {
-          const uploadProvider = getActiveFileUploadProvider();
+          const uploadProvider = await resolveResumableUploadProvider(
+            resumableSession.providerId,
+          );
           if (!uploadProvider?.resumable) {
             throw new Error("No resumable upload provider configured");
           }

package/corpus/templates/clips/actions/get-recording-player-data.ts

@@ -36,6 +36,7 @@ import {
   normalizeTranscriptSegments,
   parseTranscriptSegments,
 } from "../shared/transcript-segments.js";
+import { resolveTranscriptPresentation } from "../shared/transcript-status.js";
 
 function safeJsonObject(raw: string | null | undefined) {
   if (!raw) return {};
@@ -215,6 +216,7 @@ export default defineAction({
       transcript?.status === "ready" &&
       !transcript.fullText?.trim() &&
       transcriptSegments.length === 0;
+    const transcriptPresentation = resolveTranscriptPresentation(transcript);
 
     // Normalize the dev-fallback videoUrl:
     //   1. Rewrite legacy `/api/uploads/:id/blob` to `/api/video/:id` so old
@@ -283,12 +285,14 @@ export default defineAction({
       },
       transcript: transcript
         ? {
-            status: transcriptReadyButEmpty ? "failed" : transcript.status,
+            status: transcriptReadyButEmpty
+              ? "failed"
+              : transcriptPresentation.status,
             language: transcript.language,
             fullText: transcript.fullText,
             failureReason: transcriptReadyButEmpty
               ? "No speech was detected by transcription. Check microphone and speech permissions, then retry transcription."
-              : transcript.failureReason,
+              : transcriptPresentation.failureReason,
             segments: transcriptSegments,
             cleanup: cleanupState
               ? {

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

@@ -29,9 +29,11 @@ import { and, eq } from "drizzle-orm";
 
 import { getDb, schema } from "../../server/db/index.js";
 import { queueBuilderMediaCompression } from "../../server/lib/builder-media-compression.js";
+import { deleteRecordingMediaObjects } from "../../server/lib/recording-media-cleanup.js";
 import { ownerEmailMatches } from "../../server/lib/recordings.js";
 import {
   makeSeekable,
+  normalizeTimelineToMp4,
   type VideoFormat,
 } from "../../server/lib/video-remux.js";
 import { isLoomRecordingSource } from "../../shared/loom.js";
@@ -46,6 +48,7 @@ export type EnsureSeekableStatus =
   | "skipped-local-media"
   | "skipped-too-large"
   | "skipped-fetch-failed"
+  | "skipped-normalize-failed"
   | "skipped-upload-failed"
   | "not-found";
 
@@ -137,8 +140,14 @@ export async function ensureRecordingSeekable(params: {
   recordingId: string;
   ownerEmail: string;
   force?: boolean;
+  normalizeTimeline?: boolean;
 }): Promise<EnsureSeekableResult> {
-  const { recordingId, ownerEmail, force = false } = params;
+  const {
+    recordingId,
+    ownerEmail,
+    force = false,
+    normalizeTimeline = false,
+  } = params;
   const db = getDb();
 
   const [rec] = await db
@@ -181,7 +190,11 @@ export async function ensureRecordingSeekable(params: {
     };
   }
 
-  if (!force && (await isAlreadyMarked(recordingId, rec.videoUrl))) {
+  if (
+    !normalizeTimeline &&
+    !force &&
+    (await isAlreadyMarked(recordingId, rec.videoUrl))
+  ) {
     return {
       recordingId,
       status: "already-optimized",
@@ -196,12 +209,27 @@ export async function ensureRecordingSeekable(params: {
   }
 
   const videoFormat: VideoFormat = rec.videoFormat === "mp4" ? "mp4" : "webm";
-  const seekable = await makeSeekable({
-    mediaBytes: fetched.bytes,
-    videoFormat,
-  });
+  const seekable = normalizeTimeline
+    ? await normalizeTimelineToMp4({
+        mediaBytes: fetched.bytes,
+        videoFormat,
+      })
+    : await makeSeekable({
+        mediaBytes: fetched.bytes,
+        videoFormat,
+      });
 
   if (!seekable.changed) {
+    if (normalizeTimeline) {
+      return {
+        recordingId,
+        status: "skipped-normalize-failed",
+        changed: false,
+        videoUrl: rec.videoUrl,
+        detail:
+          "Timeline normalization could not produce a verified MP4; the original recording was left unchanged.",
+      };
+    }
     // Already seekable (or unimprovable) — remember so we don't refetch it.
     await markRecordingSeekable(recordingId, rec.videoUrl);
     return {
@@ -212,14 +240,23 @@ export async function ensureRecordingSeekable(params: {
     };
   }
 
-  const mimeType = videoFormat === "mp4" ? "video/mp4" : "video/webm";
+  const outputFormat: VideoFormat = normalizeTimeline ? "mp4" : videoFormat;
+  const mimeType = outputFormat === "mp4" ? "video/mp4" : "video/webm";
   const upload = await uploadFile({
     data: seekable.bytes,
-    filename: `${recordingId}.${videoFormat}`,
+    filename: normalizeTimeline
+      ? `${recordingId}-timeline-normalized-${Date.now()}.mp4`
+      : `${recordingId}.${outputFormat}`,
     mimeType,
     ownerEmail,
     stableUrl: true,
     recordAsset: false,
+  }).catch((err) => {
+    console.warn("[ensure-seekable-video] repaired media upload failed", {
+      recordingId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
   });
 
   if (!upload?.url) {
@@ -232,10 +269,11 @@ export async function ensureRecordingSeekable(params: {
     };
   }
 
-  await db
+  const updated = await db
     .update(schema.recordings)
     .set({
       videoUrl: upload.url,
+      videoFormat: outputFormat,
       videoSizeBytes: seekable.bytes.byteLength,
       updatedAt: new Date().toISOString(),
     })
@@ -243,8 +281,32 @@ export async function ensureRecordingSeekable(params: {
       and(
         eq(schema.recordings.id, recordingId),
         ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+        eq(schema.recordings.videoUrl, rec.videoUrl),
       ),
+    )
+    .returning({
+      id: schema.recordings.id,
+      videoUrl: schema.recordings.videoUrl,
+      videoFormat: schema.recordings.videoFormat,
+    });
+
+  if (
+    updated.length !== 1 ||
+    updated[0]?.videoUrl !== upload.url ||
+    updated[0]?.videoFormat !== outputFormat
+  ) {
+    await deleteRecordingMediaObjects(
+      { id: recordingId, videoUrl: upload.url },
+      { protectedUrls: [rec.videoUrl] },
     );
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      videoUrl: rec.videoUrl,
+      detail: "Recording changed while repaired media was uploading.",
+    };
+  }
 
   await markRecordingSeekable(recordingId, upload.url);
   await writeAppState("refresh-signal", { ts: Date.now() });
@@ -257,6 +319,7 @@ export async function ensureRecordingSeekable(params: {
     providerId: upload.provider,
     assetDbId: upload.id,
     sourceSizeBytes: seekable.bytes.byteLength,
+    locallyTranscoded: normalizeTimeline,
   }).catch((err) => {
     console.warn("[ensure-seekable-video] media compression queue failed", {
       recordingId,

package/corpus/templates/clips/actions/list-recordings.ts

@@ -9,6 +9,7 @@ import {
   inArray,
   isNull,
   isNotNull,
+  not,
   notInArray,
   sql,
 } from "drizzle-orm";
@@ -27,10 +28,10 @@ function escapeLike(s: string): string {
 
 export default defineAction({
   description:
-    "List recordings visible to the current user. Supports filtering by view (library/space/archive/trash/all), folder, space, tag, free-text, and sort.",
+    "List recordings visible to the current user. Supports filtering by view (library/shared/space/archive/trash/all), folder, space, tag, free-text, and sort. The shared view returns accessible recordings owned by someone else.",
   schema: z.object({
     view: z
-      .enum(["library", "space", "archive", "trash", "all"])
+      .enum(["library", "shared", "space", "archive", "trash", "all"])
       .default("library")
       .describe("Which list to show"),
     folderId: z
@@ -90,8 +91,23 @@ export default defineAction({
       if (orgId) {
         whereClauses.push(eq(schema.recordings.organizationId, orgId));
       }
+    }
+
+    // Shared = recordings admitted by the normal sharing access filter but
+    // owned by someone else. This includes direct user/org grants and org-wide
+    // visibility, while public-only links remain excluded by accessFilter.
+    if (args.view === "shared") {
+      const email = getRequestUserEmail();
+      whereClauses.push(
+        email
+          ? not(ownerEmailMatches(schema.recordings.ownerEmail, email))
+          : sql`1 = 0`,
+      );
+    }
+
+    if (args.view === "library" || args.view === "shared") {
       // Meeting recordings are transcript-only (no playable media) and live on
-      // the /meetings surface, so keep them out of the Library list. The link
+      // the /meetings surface, so keep them out of clip library views. The link
       // is meetings.recordingId (no meetingId column on recordings), so exclude
       // any recording referenced by a meeting. The subquery filters out NULLs
       // so NOT IN doesn't collapse to an empty result under SQL NULL semantics.

package/corpus/templates/clips/actions/navigate.ts

@@ -7,6 +7,7 @@
  *
  * Usage:
  *   pnpm action navigate --view=library
+ *   pnpm action navigate --view=shared
  *   pnpm action navigate --view=recording --recordingId=<id>
  *   pnpm action navigate --view=meeting --meetingId=<id>
  *   pnpm action navigate --view=dictate
@@ -20,6 +21,7 @@ import { z } from "zod";
 
 const Views = [
   "library",
+  "shared",
   "spaces",
   "space",
   "archive",

package/corpus/templates/clips/actions/regenerate-title.ts

@@ -32,6 +32,7 @@ import {
   fallbackTitleFromTranscript,
 } from "./lib/title-fallback.js";
 import { isAutoTitleReplaceable, isDefaultTitle } from "./lib/title-source.js";
+import regenerateSummary from "./regenerate-summary.js";
 
 function transcriptTextFromSegments(raw: string | null | undefined): string {
   if (!raw) return "";
@@ -67,19 +68,23 @@ function buildTitleContext({
 export async function queueTitleRegenerationRequest({
   recordingId,
   currentTitle,
+  currentDescription,
   transcriptText,
   transcriptStatus = "ready",
   segmentsJson = "[]",
   ownerEmail,
   includeFullVideoInAi,
+  includeSummary = false,
 }: {
   recordingId: string;
   currentTitle: string | null | undefined;
+  currentDescription?: string | null;
   transcriptText: string;
   transcriptStatus?: string;
   segmentsJson?: string | null;
   ownerEmail?: string | null;
   includeFullVideoInAi?: boolean;
+  includeSummary?: boolean;
 }) {
   const agentsContext = await loadAgentsMdContext({
     ownerEmail,
@@ -87,22 +92,29 @@ export async function queueTitleRegenerationRequest({
   });
   const useVideo =
     includeFullVideoInAi ?? (await readIncludeFullVideoInAi(ownerEmail));
+  const summaryInstruction = includeSummary
+    ? ` Also include \`--description="..."\` with a useful 2-4 sentence summary of what the Clip covers.`
+    : "";
   const baseMessage =
-    `Regenerate the title for recording ${recordingId}. ` +
-    `Read the native transcript and AGENTS.md context in this request's context and call ` +
-    `\`update-recording --id=${recordingId} --title="..."\` with a concise ` +
-    `4-9 word descriptive title. Current title: "${currentTitle ?? ""}". ` +
+    `Generate a concise, specific 4-9 word title for recording ${recordingId}. ` +
+    `Read the native transcript and AGENTS.md context in this request's context, summarize the actual subject instead of quoting the opening words, and call ` +
+    `\`update-recording --id=${recordingId} --title="..."\`${summaryInstruction} ` +
+    `Current title: "${currentTitle ?? ""}". Current description: "${currentDescription ?? ""}". ` +
     "Do not prompt the user.";
   const request = {
-    kind: "regenerate-title" as const,
+    kind: includeSummary
+      ? ("generate-metadata" as const)
+      : ("regenerate-title" as const),
     recordingId,
     requestedAt: new Date().toISOString(),
     currentTitle: currentTitle ?? "",
+    currentDescription: currentDescription ?? "",
     transcriptStatus,
     transcriptText,
     segmentsJson: segmentsJson ?? "[]",
     agentsContext,
     includeFullVideoInAi: useVideo,
+    includeSummary,
     message: withFullVideoAiInstructions(baseMessage, recordingId, useVideo),
   };
 
@@ -122,6 +134,13 @@ export default defineAction({
       .describe(
         "Optional native Web Speech/macOS Speech transcript text to title from immediately.",
       ),
+    includeSummary: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "Also queue an automatic recording description after the transcript-backed title. Used by the post-transcription pipeline.",
+      ),
   }),
   run: async (args) => {
     await assertAccess("recording", args.recordingId, "editor");
@@ -132,6 +151,7 @@ export default defineAction({
         id: schema.recordings.id,
         title: schema.recordings.title,
         titleSource: schema.recordings.titleSource,
+        description: schema.recordings.description,
       })
       .from(schema.recordings)
       .where(eq(schema.recordings.id, args.recordingId))
@@ -157,11 +177,13 @@ export default defineAction({
       await queueTitleRegenerationRequest({
         recordingId: args.recordingId,
         currentTitle: rec.title,
+        currentDescription: rec.description,
         transcriptStatus: transcript?.status ?? "pending",
         transcriptText: transcriptText || "",
         segmentsJson: transcript?.segmentsJson ?? "[]",
         ownerEmail: getRequestUserEmail() ?? transcript?.ownerEmail,
         includeFullVideoInAi: true,
+        includeSummary: args.includeSummary,
       });
       console.log(
         `Delegation queued: regenerate-title (full video) for ${args.recordingId}`,
@@ -231,6 +253,12 @@ export default defineAction({
           if (result.provider === "builder") {
             await clearBuilderCreditsExhausted();
           }
+          const summaryResult =
+            args.includeSummary && !rec.description?.trim()
+              ? await regenerateSummary.run({
+                  recordingId: args.recordingId,
+                })
+              : null;
 
           console.log(
             `Regenerated title for ${args.recordingId} via ${result.provider}: ${generatedTitle}`,
@@ -240,6 +268,7 @@ export default defineAction({
             recordingId: args.recordingId,
             title: generatedTitle,
             provider: result.provider,
+            summaryQueued: summaryResult?.queued === true,
           };
         }
 
@@ -281,20 +310,35 @@ export default defineAction({
           .update(schema.recordings)
           .set({
             title: fallbackTitle,
-            titleSource: "ai",
+            // This is an immediate heuristic while the agent prepares the
+            // real transcript-backed title. Keep it replaceable.
+            titleSource: "context",
             updatedAt: new Date().toISOString(),
           })
           .where(eq(schema.recordings.id, args.recordingId));
         await writeAppState("refresh-signal", { ts: Date.now() });
+        await queueTitleRegenerationRequest({
+          recordingId: args.recordingId,
+          currentTitle: fallbackTitle,
+          currentDescription: rec.description,
+          transcriptStatus: transcript?.status ?? "ready",
+          transcriptText,
+          segmentsJson: transcript?.segmentsJson ?? "[]",
+          ownerEmail: getRequestUserEmail() ?? transcript?.ownerEmail,
+          includeFullVideoInAi: false,
+          includeSummary: args.includeSummary,
+        });
 
         console.log(
-          `Regenerated title for ${args.recordingId} via local fallback: ${fallbackTitle}`,
+          `Set temporary title for ${args.recordingId} via local fallback and queued transcript-backed refinement: ${fallbackTitle}`,
         );
         return {
           updated: true,
+          queued: true,
           recordingId: args.recordingId,
           title: fallbackTitle,
           provider: "local",
+          summaryQueued: args.includeSummary,
         };
       }
     }
@@ -311,11 +355,13 @@ export default defineAction({
     await queueTitleRegenerationRequest({
       recordingId: args.recordingId,
       currentTitle: rec.title,
+      currentDescription: rec.description,
       transcriptStatus: transcript?.status ?? "pending",
       transcriptText,
       segmentsJson: transcript?.segmentsJson ?? "[]",
       ownerEmail: getRequestUserEmail() ?? transcript?.ownerEmail,
       includeFullVideoInAi: false,
+      includeSummary: args.includeSummary,
     });
 
     console.log(`Delegation queued: regenerate-title for ${args.recordingId}`);

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

@@ -16,6 +16,7 @@
  *   pnpm action reprocess-recording --ids='["id1","id2"]'
  *   pnpm action reprocess-recording --all --limit=20
  *   pnpm action reprocess-recording --id=<recordingId> --force
+ *   pnpm action reprocess-recording --id=<recordingId> --normalizeTimeline
  */
 
 import { defineAction } from "@agent-native/core";
@@ -34,6 +35,11 @@ import {
 
 const MAX_TARGETS_PER_CALL = 100;
 const DEFAULT_ALL_LIMIT = 20;
+const cliBoolean = z.preprocess((value) => {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  return value;
+}, z.boolean());
 
 function parseIds(value: unknown): string[] {
   if (Array.isArray(value)) {
@@ -58,7 +64,7 @@ function parseIds(value: unknown): string[] {
 
 export default defineAction({
   description:
-    "Repair slow-loading or buffering recordings by rewriting their stored video to be start-playable and seekable (MP4 faststart / WebM Cues remux) and re-uploading it. Use for clips that take a long time to load or re-buffer when scrubbing. Pass `id` for one clip, `ids` for several, or `all: true` to sweep the caller's ready clips (bounded by `limit`). Already-seekable clips are skipped unless `force` is true.",
+    "Repair playback of existing recordings and re-upload the fixed media without replacing the original unless the repair succeeds. By default this makes MP4/WebM start-playable and seekable. Set `normalizeTimeline: true` when a clip freezes or stops visually despite a longer duration because its video timestamps have large gaps; this transcodes to constant-frame-rate faststart MP4, preserves audio, and holds the last captured frame through missing-video gaps. Pass `id` for one clip, `ids` for several, or `all: true` for a bounded owner-scoped sweep. Already-seekable clips are skipped unless `force` is true; timeline normalization always runs when explicitly requested.",
   schema: z.object({
     id: z.string().optional().describe("A single recording id to repair."),
     ids: z
@@ -67,8 +73,7 @@ export default defineAction({
       .describe(
         "Multiple recording ids (array, or JSON/comma string for CLI).",
       ),
-    all: z.coerce
-      .boolean()
+    all: cliBoolean
       .optional()
       .describe(
         "Repair the caller's own ready clips, most recent first, up to `limit`.",
@@ -82,10 +87,14 @@ export default defineAction({
       .describe(
         `Max clips to process when using \`all\` (default ${DEFAULT_ALL_LIMIT}).`,
       ),
-    force: z.coerce
-      .boolean()
+    force: cliBoolean
       .optional()
       .describe("Re-run even on clips already marked seekable."),
+    normalizeTimeline: cliBoolean
+      .optional()
+      .describe(
+        "Transcode sparse/discontinuous video timestamps to constant-frame-rate faststart MP4 while preserving audio. Use when playback freezes or appears to stop before the declared duration.",
+      ),
   }),
   run: async (args) => {
     const db = getDb();
@@ -132,7 +141,12 @@ export default defineAction({
     for (const recordingId of targetIds) {
       try {
         results.push(
-          await ensureRecordingSeekable({ recordingId, ownerEmail, force }),
+          await ensureRecordingSeekable({
+            recordingId,
+            ownerEmail,
+            force,
+            normalizeTimeline: args.normalizeTimeline === true,
+          }),
         );
       } catch (err) {
         console.warn("[reprocess-recording] failed for", recordingId, err);