@agent-native/core 0.134.0 → 0.135.0

package/corpus/templates/clips/server/lib/recording-upload-state.ts

@@ -4,14 +4,46 @@ function escapeLike(value: string): string {
   return value.replace(/[!%_]/g, (match) => `!${match}`);
 }
 
-function chunkPrefix(recordingId: string): string {
-  return `recording-chunks-${recordingId}-`;
+function chunkPrefix(
+  recordingId: string,
+  generationId?: string | null,
+): string {
+  return generationId
+    ? `recording-chunks-${recordingId}-${generationId}-`
+    : `recording-chunks-${recordingId}-`;
 }
 
 function likePrefix(prefix: string): string {
   return `${escapeLike(prefix)}%`;
 }
 
+function exactChunkKeyArgs(
+  ownerEmail: string,
+  recordingId: string,
+  generationId?: string | null,
+): [string, string, number, string, string] {
+  const prefix = chunkPrefix(recordingId, generationId);
+  return [
+    ownerEmail,
+    likePrefix(prefix),
+    prefix.length + 6,
+    `${prefix}000000`,
+    `${prefix}999999`,
+  ];
+}
+
+const exactChunkKeyWhere = `session_id = ? AND key LIKE ? ESCAPE '!' AND length(key) = ? AND key >= ? AND key <= ?`;
+
+function isChunkKeyForGeneration(
+  key: string,
+  recordingId: string,
+  generationId?: string | null,
+): boolean {
+  const prefix = chunkPrefix(recordingId, generationId);
+  if (!key.startsWith(prefix)) return false;
+  return /^\d+$/.test(key.slice(prefix.length));
+}
+
 function numberFromRowValue(value: unknown): number {
   if (typeof value === "number" && Number.isFinite(value)) return value;
   if (typeof value === "bigint") return Number(value);
@@ -81,21 +113,25 @@ export function validateRecordingChunkKeys(
 export async function listRecordingChunkKeys(
   ownerEmail: string,
   recordingId: string,
+  generationId?: string | null,
 ): Promise<string[]> {
   const { rows } = await getDbExec().execute({
-    sql: `SELECT key FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
-    args: [ownerEmail, likePrefix(chunkPrefix(recordingId))],
+    sql: `SELECT key FROM application_state WHERE ${exactChunkKeyWhere}`,
+    args: exactChunkKeyArgs(ownerEmail, recordingId, generationId),
   });
-  return rows.map((row) => String(row.key));
+  return rows
+    .map((row) => String(row.key))
+    .filter((key) => isChunkKeyForGeneration(key, recordingId, generationId));
 }
 
 export async function deleteRecordingChunks(
   ownerEmail: string,
   recordingId: string,
+  generationId?: string | null,
 ): Promise<number> {
   const result = await getDbExec().execute({
-    sql: `DELETE FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
-    args: [ownerEmail, likePrefix(chunkPrefix(recordingId))],
+    sql: `DELETE FROM application_state WHERE ${exactChunkKeyWhere}`,
+    args: exactChunkKeyArgs(ownerEmail, recordingId, generationId),
   });
   return result.rowsAffected ?? 0;
 }
@@ -103,13 +139,14 @@ export async function deleteRecordingChunks(
 export async function sumRecordingChunkBytes(
   ownerEmail: string,
   recordingId: string,
+  generationId?: string | null,
 ): Promise<number> {
   const bytesExpression = isPostgres()
     ? `COALESCE(SUM((value::jsonb ->> 'bytes')::bigint), 0)`
     : `COALESCE(SUM(json_extract(value, '$.bytes')), 0)`;
   const { rows } = await getDbExec().execute({
-    sql: `SELECT ${bytesExpression} AS bytes FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
-    args: [ownerEmail, likePrefix(chunkPrefix(recordingId))],
+    sql: `SELECT ${bytesExpression} AS bytes FROM application_state WHERE ${exactChunkKeyWhere}`,
+    args: exactChunkKeyArgs(ownerEmail, recordingId, generationId),
   });
   return numberFromRowValue(rows[0]?.bytes);
 }

package/corpus/templates/clips/server/lib/recordings.ts

@@ -5,9 +5,14 @@ import {
   getRequestUserEmail,
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
+import { getUserSetting } from "@agent-native/core/settings";
 import { and, count, desc, eq, sql } from "drizzle-orm";
 import { HTTPError, type H3Event } from "h3";
 
+import {
+  CLIPS_USER_PREFS_KEY,
+  type ClipsUserPrefs,
+} from "../../shared/clips-ai-prefs.js";
 import { getDb, schema } from "../db/index.js";
 
 export function getCurrentOwnerEmail(): string {
@@ -99,6 +104,25 @@ export async function getOrganizationDefaultVisibility(
   }
 }
 
+/**
+ * Visibility for a new recording: the personal preference of the creator
+ * wins, then the organization default, then the built-in default.
+ */
+export async function getDefaultRecordingVisibility(
+  organizationId: string | null | undefined,
+): Promise<RecordingVisibility> {
+  const email = getRequestUserEmail();
+  if (email) {
+    const prefs = (await getUserSetting(
+      normalizeOwnerEmail(email),
+      CLIPS_USER_PREFS_KEY,
+    )) as ClipsUserPrefs | null;
+    const preferred = prefs?.defaultRecordingVisibility;
+    if (isRecordingVisibility(preferred)) return preferred;
+  }
+  return getOrganizationDefaultVisibility(organizationId);
+}
+
 const ORG_ROLE_RANK: Record<OrganizationAccessRole, number> = {
   member: 1,
   admin: 2,

package/corpus/templates/clips/server/lib/resumable-session.ts

@@ -12,12 +12,16 @@ export interface StoredResumableSession {
   lastCommittedIndex?: number;
 }
 
-const key = (recordingId: string) => `resumable-session-${recordingId}`;
+const key = (recordingId: string, generationId?: string | null) =>
+  generationId
+    ? `resumable-session-${recordingId}-${generationId}`
+    : `resumable-session-${recordingId}`;
 
 export async function getResumableSession(
   recordingId: string,
+  generationId?: string | null,
 ): Promise<StoredResumableSession | null> {
-  const raw = await readAppState(key(recordingId));
+  const raw = await readAppState(key(recordingId, generationId));
   if (!raw || typeof raw !== "object") return null;
   return raw as unknown as StoredResumableSession;
 }
@@ -25,15 +29,17 @@ export async function getResumableSession(
 export async function setResumableSession(
   recordingId: string,
   session: StoredResumableSession,
+  generationId?: string | null,
 ): Promise<void> {
   await writeAppState(
-    key(recordingId),
+    key(recordingId, generationId),
     session as unknown as Record<string, unknown>,
   );
 }
 
 export async function deleteResumableSession(
   recordingId: string,
+  generationId?: string | null,
 ): Promise<void> {
-  await deleteAppState(key(recordingId));
+  await deleteAppState(key(recordingId, generationId));
 }

package/corpus/templates/clips/server/lib/transactional-email-templates.ts

@@ -9,6 +9,8 @@ const CLIPS_BRAND_NAME = "Clips";
 const EMAIL_SEND_TIMEOUT_MS = 60_000;
 const FRIENDLY_REPLY_TO = "hello@agent-native.com";
 const UNTITLED_CLIP = "Untitled Clip";
+const ACTIVITY_EMAIL_FOOTER =
+  "You received this because email notifications are on in your Clips settings.";
 
 interface TransactionalEmailBase {
   to: string;
@@ -37,6 +39,25 @@ export type ClipsTransactionalEmailInput =
   | (TransactionalEmailBase & {
       kind: "two-clips";
       generatedSummary?: string | null;
+    })
+  | (TransactionalEmailBase & {
+      kind: "activity-comment";
+      recordingId: string;
+      title?: string | null;
+      authorEmail?: string | null;
+      authorName?: string | null;
+      content: string;
+      videoTimestampMs?: number | null;
+      isReply?: boolean;
+    })
+  | (TransactionalEmailBase & {
+      kind: "activity-reaction";
+      recordingId: string;
+      title?: string | null;
+      emoji: string;
+      authorEmail?: string | null;
+      authorName?: string | null;
+      videoTimestampMs?: number | null;
     });
 
 export interface ClipsTransactionalEmailRenderOptions {
@@ -103,6 +124,31 @@ function clipUrl(
   return appUrlForPath(`/r/${encodeURIComponent(recordingId)}`, options);
 }
 
+function clipCommentsUrl(
+  recordingId: string,
+  videoTimestampMs: number | null | undefined,
+  options: ClipsTransactionalEmailRenderOptions,
+): string {
+  const url = new URL(clipUrl(recordingId, options));
+  url.searchParams.set("panel", "comments");
+  if (typeof videoTimestampMs === "number" && videoTimestampMs > 0) {
+    url.searchParams.set("t", String(Math.floor(videoTimestampMs / 1000)));
+  }
+  return url.toString();
+}
+
+function formatTimestamp(ms: number): string {
+  const total = Math.floor(ms / 1000);
+  const minutes = Math.floor(total / 60);
+  const seconds = total % 60;
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+function quotedExcerpt(value: string): string {
+  const text = singleLine(value);
+  return text.length > 280 ? `${text.slice(0, 277)}…` : text;
+}
+
 function recordUrl(options: ClipsTransactionalEmailRenderOptions): string {
   return appUrlForPath("/record", options);
 }
@@ -232,6 +278,69 @@ export function renderClipsTransactionalEmail(
       });
       return { subject, ...rendered };
     }
+
+    case "activity-comment": {
+      const author =
+        singleLine(input.authorName) ||
+        normalizeEmailDisplayName(input.authorEmail, "Someone");
+      const at =
+        typeof input.videoTimestampMs === "number" && input.videoTimestampMs > 0
+          ? ` at ${formatTimestamp(input.videoTimestampMs)}`
+          : "";
+      const subject = input.isReply
+        ? `${author} replied on “${title}”`
+        : `${author} commented on “${title}”`;
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        preheader: subject,
+        heading: input.isReply
+          ? `${author} replied on your Clip`
+          : `${author} commented on your Clip`,
+        paragraphs: [
+          `${emailStrong(author)} left a ${input.isReply ? "reply" : "comment"} on ${emailStrong(title!)}${at}.`,
+          `“${quotedExcerpt(input.content)}”`,
+        ],
+        cta: {
+          label: "Read and reply",
+          url: clipCommentsUrl(
+            input.recordingId,
+            input.videoTimestampMs,
+            options,
+          ),
+        },
+        footer: ACTIVITY_EMAIL_FOOTER,
+      });
+      return { subject, ...rendered };
+    }
+
+    case "activity-reaction": {
+      const author =
+        singleLine(input.authorName) ||
+        normalizeEmailDisplayName(input.authorEmail, "Someone");
+      const at =
+        typeof input.videoTimestampMs === "number" && input.videoTimestampMs > 0
+          ? ` at ${formatTimestamp(input.videoTimestampMs)}`
+          : "";
+      const subject = `${author} reacted ${input.emoji} on “${title}”`;
+      const rendered = renderEmail({
+        brandName: CLIPS_BRAND_NAME,
+        preheader: subject,
+        heading: "Someone reacted to your Clip",
+        paragraphs: [
+          `${emailStrong(author)} reacted ${emailStrong(input.emoji)} on ${emailStrong(title!)}${at}.`,
+        ],
+        cta: {
+          label: "See Clip activity",
+          url: clipCommentsUrl(
+            input.recordingId,
+            input.videoTimestampMs,
+            options,
+          ),
+        },
+        footer: ACTIVITY_EMAIL_FOOTER,
+      });
+      return { subject, ...rendered };
+    }
   }
 }
 

package/corpus/templates/clips/server/lib/upload-interruption.ts

@@ -0,0 +1,8 @@
+export const RETRYABLE_UPLOAD_INTERRUPTION_REASON =
+  "Upload was interrupted. The local recording is safe; retry from the Clips desktop app.";
+
+export function isRetryableUploadInterruption(
+  failureReason: string | null | undefined,
+): boolean {
+  return failureReason === RETRYABLE_UPLOAD_INTERRUPTION_REASON;
+}

package/corpus/templates/clips/server/lib/upload-lease.ts

@@ -12,7 +12,7 @@
  */
 
 import { getDbExec, isPostgres } from "@agent-native/core/db";
-import { and, eq, inArray, sql } from "drizzle-orm";
+import { and, eq, inArray, isNull, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -37,6 +37,7 @@ export type UploadLeaseResult =
   | { held: true }
   | {
       held: false;
+      staleAttempt: boolean;
       status: string | null;
       failureReason: string | null;
       videoUrl: string | null;
@@ -53,7 +54,12 @@ export type UploadLeaseResult =
  */
 export async function renewUploadLease(
   recordingId: string,
-  options: { now?: number; uploadProgress?: number } = {},
+  options: {
+    now?: number;
+    uploadProgress?: number;
+    attemptId?: string | null;
+    generationId?: string | null;
+  } = {},
 ): Promise<UploadLeaseResult> {
   const now = options.now ?? Date.now();
   const held = await getDb()
@@ -72,6 +78,23 @@ export async function renewUploadLease(
       and(
         eq(schema.recordings.id, recordingId),
         inArray(schema.recordings.status, [...IN_PROGRESS_STATUSES]),
+        ...(options.attemptId === undefined
+          ? []
+          : [
+              options.attemptId === null
+                ? isNull(schema.recordings.uploadAttemptId)
+                : eq(schema.recordings.uploadAttemptId, options.attemptId),
+            ]),
+        ...(options.generationId === undefined
+          ? []
+          : [
+              options.generationId === null
+                ? isNull(schema.recordings.uploadGenerationId)
+                : eq(
+                    schema.recordings.uploadGenerationId,
+                    options.generationId,
+                  ),
+            ]),
       ),
     )
     .returning({ id: schema.recordings.id });
@@ -87,12 +110,23 @@ export async function renewUploadLease(
       videoUrl: schema.recordings.videoUrl,
       videoSizeBytes: schema.recordings.videoSizeBytes,
       durationMs: schema.recordings.durationMs,
+      uploadAttemptId: schema.recordings.uploadAttemptId,
+      uploadGenerationId: schema.recordings.uploadGenerationId,
     })
     .from(schema.recordings)
     .where(eq(schema.recordings.id, recordingId));
 
   return {
     held: false,
+    staleAttempt:
+      (options.attemptId !== undefined || options.generationId !== undefined) &&
+      IN_PROGRESS_STATUSES.includes(
+        row?.status as (typeof IN_PROGRESS_STATUSES)[number],
+      ) &&
+      ((options.attemptId !== undefined &&
+        row?.uploadAttemptId !== options.attemptId) ||
+        (options.generationId !== undefined &&
+          row?.uploadGenerationId !== options.generationId)),
     status: row?.status ?? null,
     failureReason: row?.failureReason ?? null,
     videoUrl: row?.videoUrl ?? null,
@@ -106,6 +140,7 @@ export interface ReapedUpload {
   ownerEmail: string;
   status: string;
   leaseExpiresAt: string;
+  uploadGenerationId: string | null;
 }
 
 export interface ReapResult {
@@ -137,7 +172,7 @@ export async function reapExpiredUploads(
 
   // guard:allow-unscoped — system upload reaper, owner-agnostic by design.
   const probe = await exec.execute({
-    sql: `SELECT id, owner_email, status, upload_lease_expires_at
+    sql: `SELECT id, owner_email, status, upload_lease_expires_at, upload_generation_id
           FROM recordings
           WHERE status IN ('uploading', 'processing')
             AND upload_lease_expires_at IS NOT NULL
@@ -154,6 +189,10 @@ export async function reapExpiredUploads(
     ownerEmail: String(row.owner_email ?? ""),
     status: String(row.status ?? ""),
     leaseExpiresAt: String(row.upload_lease_expires_at ?? ""),
+    uploadGenerationId:
+      typeof row.upload_generation_id === "string"
+        ? row.upload_generation_id
+        : null,
   }));
 
   let failed = 0;
@@ -184,9 +223,16 @@ export async function reapExpiredUploads(
     failed = terminated.size;
 
     for (const id of terminated) {
+      const generationId = expired.find(
+        (row) => row.id === id,
+      )?.uploadGenerationId;
       await exec.execute({
         sql: `DELETE FROM application_state WHERE key = ${p(1)}`,
-        args: [`resumable-session-${id}`],
+        args: [
+          generationId
+            ? `resumable-session-${id}-${generationId}`
+            : `resumable-session-${id}`,
+        ],
       });
     }
   }

package/corpus/templates/clips/server/lib/video-filmstrip-sprite.ts

@@ -0,0 +1,207 @@
+/**
+ * Generate a filmstrip sprite — one JPEG holding a grid of evenly-spaced video
+ * frames — so the editor timeline renders thumbnails as a single cached image
+ * request instead of decoding the video in the browser.
+ *
+ * Why a sprite rather than per-frame files: one ffmpeg pass, one upload, one
+ * HTTP request, and the grid geometry is enough for CSS `background-position`
+ * to address any cell. The browser fallback in `app/lib/video-filmstrip.ts`
+ * needs one seek per frame and cannot read cross-origin media at all.
+ *
+ * Three constraints worth keeping in mind:
+ *
+ *   - Cells are padded to an exact size (`force_original_aspect_ratio=decrease`
+ *     plus `pad`) so the returned grid geometry is exact without probing the
+ *     source. Letterboxed bars on odd aspect ratios are the deliberate cost of
+ *     not having to decode the output to learn its dimensions.
+ *   - Sampling starts half a cell in, matching the browser fallback: cell `i`
+ *     shows the midpoint of the time slot it occupies, not its leading edge.
+ *   - Input arrives as bytes and is written to a temp file, like every other
+ *     ffmpeg path here. That means the whole file is buffered in memory by the
+ *     caller, which is the practical ceiling on this approach for long
+ *     recordings on small hosts.
+ */
+
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { isFfmpegAvailable, runFfmpeg, withRemuxSlot } from "./video-remux.js";
+
+const SPRITE_TIMEOUT_MS = 90_000;
+
+export const DEFAULT_FILMSTRIP_FRAME_COUNT = 40;
+// A sprite is decoded whole by the browser, so cap the grid: 120 cells at the
+// default size is already a ~1600x1080 image.
+export const MAX_FILMSTRIP_FRAME_COUNT = 120;
+export const DEFAULT_FILMSTRIP_FRAME_WIDTH = 160;
+export const DEFAULT_FILMSTRIP_FRAME_HEIGHT = 90;
+export const DEFAULT_FILMSTRIP_COLUMNS = 10;
+
+export type FilmstripSpriteStatus =
+  | "generated"
+  | "skipped-no-ffmpeg"
+  | "skipped-no-duration"
+  | "skipped-no-media"
+  | "failed-ffmpeg"
+  | "failed-empty-output";
+
+/** Everything the UI needs to address one cell of the sprite. */
+export interface FilmstripSpriteGrid {
+  frameCount: number;
+  columns: number;
+  rows: number;
+  frameWidth: number;
+  frameHeight: number;
+}
+
+export interface FilmstripSpriteResult {
+  status: FilmstripSpriteStatus;
+  /** Present only when `status === "generated"`. */
+  sprite?: { bytes: Uint8Array; grid: FilmstripSpriteGrid };
+  detail?: string;
+}
+
+export interface GenerateFilmstripSpriteInput {
+  mediaBytes: Uint8Array;
+  durationMs: number;
+  frameCount?: number;
+  frameWidth?: number;
+  frameHeight?: number;
+  columns?: number;
+}
+
+/**
+ * Lay `frameCount` cells out into a grid no wider than `columns`. Exported so
+ * callers can compute the same geometry the sprite will have without
+ * regenerating it.
+ */
+export function filmstripGrid(input: {
+  frameCount: number;
+  columns: number;
+  frameWidth: number;
+  frameHeight: number;
+}): FilmstripSpriteGrid {
+  const frameCount = Math.min(
+    MAX_FILMSTRIP_FRAME_COUNT,
+    Math.max(1, Math.floor(input.frameCount)),
+  );
+  const columns = Math.max(1, Math.min(input.columns, frameCount));
+  return {
+    frameCount,
+    columns,
+    rows: Math.ceil(frameCount / columns),
+    frameWidth: input.frameWidth,
+    frameHeight: input.frameHeight,
+  };
+}
+
+/**
+ * Build the ffmpeg filter chain that samples `frameCount` frames across
+ * `durationMs` and tiles them into `grid`. Exported for tests: the sampling
+ * offset and rate are the parts most likely to drift from the browser
+ * fallback's expectations.
+ */
+export function filmstripSpriteFilter(input: {
+  durationMs: number;
+  grid: FilmstripSpriteGrid;
+}): { seekSeconds: string; filter: string } {
+  const { durationMs, grid } = input;
+  const cellMs = durationMs / grid.frameCount;
+  const fps = grid.frameCount / (durationMs / 1000);
+
+  return {
+    // Half a cell in, so each tile is the midpoint of its slot.
+    seekSeconds: (cellMs / 2 / 1000).toFixed(6),
+    filter: [
+      `fps=${fps.toFixed(6)}`,
+      `scale=${grid.frameWidth}:${grid.frameHeight}:force_original_aspect_ratio=decrease`,
+      `pad=${grid.frameWidth}:${grid.frameHeight}:-1:-1:color=black`,
+      `tile=${grid.columns}x${grid.rows}`,
+    ].join(","),
+  };
+}
+
+export async function generateFilmstripSprite(
+  input: GenerateFilmstripSpriteInput,
+): Promise<FilmstripSpriteResult> {
+  const {
+    mediaBytes,
+    durationMs,
+    frameCount = DEFAULT_FILMSTRIP_FRAME_COUNT,
+    frameWidth = DEFAULT_FILMSTRIP_FRAME_WIDTH,
+    frameHeight = DEFAULT_FILMSTRIP_FRAME_HEIGHT,
+    columns = DEFAULT_FILMSTRIP_COLUMNS,
+  } = input;
+
+  if (mediaBytes.byteLength === 0) {
+    return { status: "skipped-no-media" };
+  }
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    return { status: "skipped-no-duration" };
+  }
+  if (!isFfmpegAvailable()) {
+    return {
+      status: "skipped-no-ffmpeg",
+      detail:
+        "No ffmpeg binary available; the editor falls back to browser-side frame extraction.",
+    };
+  }
+
+  const grid = filmstripGrid({ frameCount, columns, frameWidth, frameHeight });
+  const { seekSeconds, filter } = filmstripSpriteFilter({ durationMs, grid });
+
+  const dir = await mkdtemp(join(tmpdir(), "clips-filmstrip-"));
+  const inputPath = join(dir, "input.media");
+  const outputPath = join(dir, "sprite.jpg");
+
+  try {
+    await writeFile(inputPath, mediaBytes);
+    await withRemuxSlot(() =>
+      runFfmpeg(
+        [
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-nostdin",
+          "-y",
+          // Input seeking: cheap, and puts the first sample at a cell midpoint.
+          "-ss",
+          seekSeconds,
+          "-i",
+          inputPath,
+          "-an",
+          "-sn",
+          "-vf",
+          filter,
+          // The tile filter emits the finished grid as a single frame.
+          "-frames:v",
+          "1",
+          "-q:v",
+          "4",
+          "-f",
+          "image2",
+          outputPath,
+        ],
+        { timeoutMs: SPRITE_TIMEOUT_MS, label: "filmstrip sprite" },
+      ),
+    );
+
+    const bytes = new Uint8Array(await readFile(outputPath));
+    if (bytes.byteLength === 0) {
+      return {
+        status: "failed-empty-output",
+        detail: "ffmpeg reported success but wrote an empty sprite",
+      };
+    }
+
+    return { status: "generated", sprite: { bytes, grid } };
+  } catch (err) {
+    return {
+      status: "failed-ffmpeg",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/corpus/templates/clips/server/lib/video-remux.ts

@@ -125,7 +125,11 @@ function startsWithMagic(bytes: Uint8Array, magic: number[]): boolean {
   return true;
 }
 
-async function runFfmpeg(args: string[]): Promise<void> {
+export async function runFfmpeg(
+  args: string[],
+  options: { timeoutMs?: number; label?: string } = {},
+): Promise<void> {
+  const { timeoutMs = REMUX_TIMEOUT_MS, label = "remux" } = options;
   await new Promise<void>((resolve, reject) => {
     const child = spawn(ffmpegCommand(), args, {
       stdio: ["ignore", "ignore", "pipe"],
@@ -133,8 +137,8 @@ async function runFfmpeg(args: string[]): Promise<void> {
     let stderr = "";
     const timeout = setTimeout(() => {
       child.kill("SIGKILL");
-      reject(new Error(`ffmpeg remux timed out\n${stderr}`));
-    }, REMUX_TIMEOUT_MS);
+      reject(new Error(`ffmpeg ${label} timed out\n${stderr}`));
+    }, timeoutMs);
 
     child.stderr?.on("data", (chunk: Buffer) => {
       stderr = (stderr + chunk.toString("utf8")).slice(-STDERR_LIMIT);
@@ -244,7 +248,12 @@ export async function probeHasAudioStream(
   }
 }
 
-async function withRemuxSlot<T>(fn: () => Promise<T>): Promise<T> {
+/**
+ * Bound concurrent ffmpeg invocations process-wide. Every ffmpeg caller must go
+ * through this, including non-remux jobs — the limit protects the box, not the
+ * remux path specifically.
+ */
+export async function withRemuxSlot<T>(fn: () => Promise<T>): Promise<T> {
   if (activeRemuxes >= MAX_CONCURRENT_REMUXES) {
     await new Promise<void>((resolve) => remuxWaiters.push(resolve));
   }