@opengeni/runtime 0.6.1 → 0.7.0

package/src/sandbox/op-correlation.ts

@@ -0,0 +1,70 @@
+// Durable op-identity correlation (op-stream ruling B1): the DURABLE op id a
+// sandbox transport op carries is `{sdk_tool_call_id}:{ordinal}` — minted ABOVE
+// the transport, at the semantic layer. The tool call id lives in the model's
+// function_call (persisted run history), so a re-dispatched turn re-executes the
+// SAME function_call with the SAME call id, and the transport's idempotent
+// OpStart turns an at-least-once re-execution into an ATTACH instead of a
+// re-run. The ordinal is the deterministic position of the physical sub-op
+// inside one tool invocation (a tool that performs read→write→rm mints :0, :1,
+// :2), so a re-executed invocation re-mints identical ids.
+//
+// The correlation rides an AsyncLocalStorage bound around the SDK tool's
+// `execute` (see `withExecOpCorrelation` in the runtime barrel): the SDK's tool
+// machinery passes `details.toolCall` (with `callId`) into every function-tool
+// invocation, and the shell capability's `configureTools` hook lets us wrap
+// exec_command without touching the SDK. Per-async-chain storage keeps PARALLEL
+// tool calls correctly separated.
+//
+// This module is deliberately dependency-free (node:async_hooks only) so the
+// agent-loop-free sandbox leaf may import it: the leaf READS the context; only
+// the runtime barrel (which owns the SDK imports) BINDS it.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+interface ToolCallCorrelation {
+  /** The sanitized sdk tool call id (a legal NATS subject-token fragment). */
+  callId: string;
+  /** The next sub-op ordinal within this tool invocation (mutable). */
+  ordinal: number;
+}
+
+const storage = new AsyncLocalStorage<ToolCallCorrelation>();
+
+/**
+ * Sanitize a tool call id into a legal NATS subject TOKEN fragment. The op id
+ * is interpolated into the per-op frame subject, whose tokens must not contain
+ * whitespace/control characters or the subject-structure characters (`.`,
+ * `*`, `>`); the runner refuses illegal ids loudly. The mapping is INJECTIVE
+ * (each disallowed char becomes `_<hex>_`), so two distinct call ids can never
+ * collide into one op id — a collision would merge two different execs through
+ * the idempotent-OpStart dedup and return the wrong result.
+ */
+export function sanitizeOpIdToken(raw: string): string {
+  return raw.replace(/[^A-Za-z0-9_-]/g, (c) => `_${c.charCodeAt(0).toString(16)}_`);
+}
+
+/**
+ * Bind a tool-call correlation context around `fn` (the tool's execute). Every
+ * durable op id minted inside — however deep in the transport — is
+ * `{callId}:{ordinal}` with ordinals starting at 0 per invocation.
+ */
+export function runWithToolCallCorrelation<T>(callId: string, fn: () => T): T {
+  return storage.run({ callId: sanitizeOpIdToken(callId), ordinal: 0 }, fn);
+}
+
+/**
+ * Mint the next durable op id for the current tool invocation, or null when no
+ * correlation context is bound (a non-tool caller, e.g. Channel-A structural
+ * exec). Callers fall back to a random unique id — safe (never collides, never
+ * wrongly dedups), merely not stable across a turn re-dispatch, which degrades
+ * that one op to today's at-least-once semantics.
+ */
+export function nextDurableOpId(): string | null {
+  const context = storage.getStore();
+  if (!context) {
+    return null;
+  }
+  const ordinal = context.ordinal;
+  context.ordinal += 1;
+  return `${context.callId}:${ordinal}`;
+}

package/src/sandbox/providers/index.ts

@@ -66,16 +66,22 @@ export function assertProviderRegistryInvariants(): void {
   for (const backend of SandboxBackend.options) {
     const registration = PROVIDER_REGISTRY[backend];
     if (registration.backend !== backend) {
-      throw new Error(`PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`);
+      throw new Error(
+        `PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`,
+      );
     }
     if (registration.descriptor.backend !== backend) {
-      throw new Error(`PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`);
+      throw new Error(
+        `PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`,
+      );
     }
     if (backend === "none") {
       // "none" has no SDK client (build returns undefined); the descriptor
       // backendId "none" is self-consistent.
       if (registration.descriptor.backendId !== "none") {
-        throw new Error(`"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`);
+        throw new Error(
+          `"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`,
+        );
       }
       continue;
     }

package/src/sandbox/providers/modal.ts

@@ -6,7 +6,14 @@ import { SandboxConfigError } from "../errors";
 import type { ProviderRegistration } from "./types";
 
 const MODAL_ORPHAN_SWEEP_LIMIT = 50;
-const MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS = 30 * 60_000;
+// A provider box is invisible to the lease until Modal create + manifest
+// materialization returns and the creation callback records its instance id.
+// Production baseline (2026-07-15, all 8 turn workers): 155/155 completed creates
+// finished under 10s (154 under 2.5s). Two minutes is a 12x observed-max buffer,
+// while avoiding the former 30-minute retention of boxes abandoned by a rolling
+// worker restart. The live-instance guard below remains authoritative: once a box
+// is recorded by any lease, age and missing/stale tags can never terminate it.
+const MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS = 2 * 60_000;
 
 export type ModalSandboxAttribution = {
   leaseId: string;
@@ -31,7 +38,9 @@ export type ModalOrphanSweepResult = {
   skipped: number;
 };
 
-export function modalSandboxAttributionEnvironment(input: ModalSandboxAttribution): Record<string, string> {
+export function modalSandboxAttributionEnvironment(
+  input: ModalSandboxAttribution,
+): Record<string, string> {
   return {
     OPENGENI_SANDBOX_LEASE_ID: input.leaseId,
     OPENGENI_SANDBOX_GROUP_ID: input.sandboxGroupId,
@@ -39,7 +48,9 @@ export function modalSandboxAttributionEnvironment(input: ModalSandboxAttributio
   };
 }
 
-export function modalSandboxAttributionTags(input: ModalSandboxAttribution): Record<string, string> {
+export function modalSandboxAttributionTags(
+  input: ModalSandboxAttribution,
+): Record<string, string> {
   return {
     opengeni: "true",
     opengeni_lease_id: input.leaseId,
@@ -70,10 +81,11 @@ export const modalProvider: ProviderRegistration = {
       sandboxCreateTimeoutS: Math.ceil(settings.sandboxWarmingTimeoutMs / 1000),
       exposedPorts,
       env: environment,
-      // The Modal JS SDK's sandbox default command already sleeps until timeout
-      // or explicit termination. Do not let the Agents extension stamp a separate
-      // hardcoded sleep command; OPENGENI_MODAL_TIMEOUT_SECONDS owns lifetime.
-      useSleepCmd: false,
+      // A registry image's own CMD is not a sandbox keepalive contract (for
+      // example, python:3.12-slim can exit immediately). Keep the provider's
+      // control process alive so exec/resume remains available; Modal's hard
+      // timeout and explicit OpenGeni teardown still own the box lifetime.
+      useSleepCmd: true,
     };
     // gap-fill (module 03 §4.1): these SDK options were previously unmapped.
     // ALWAYS pin idleTimeoutMs (sandbox-file-persistence): an UNSET idle timeout
@@ -206,7 +218,9 @@ export function resolveModalImageSelector(settings: Settings): ModalImageSelecto
   }
   const registryImage = cachedModalRegistryImage(settings);
   return registryImage
-    ? ModalImageSelector.fromImage(registryImage as Parameters<typeof ModalImageSelector.fromImage>[0])
+    ? ModalImageSelector.fromImage(
+        registryImage as Parameters<typeof ModalImageSelector.fromImage>[0],
+      )
     : ModalImageSelector.fromTag(settings.modalImageRef);
 }
 
@@ -216,7 +230,9 @@ export function __resetModalRegistryImageCacheForTest(): void {
   inFlightRegistryImages.clear();
 }
 
-function modalClientOptions(settings: Settings): ConstructorParameters<ModalModule["ModalClient"]>[0] {
+function modalClientOptions(
+  settings: Settings,
+): ConstructorParameters<ModalModule["ModalClient"]>[0] {
   return {
     ...(settings.modalTokenId ? { tokenId: settings.modalTokenId } : {}),
     ...(settings.modalTokenSecret ? { tokenSecret: settings.modalTokenSecret } : {}),
@@ -248,7 +264,10 @@ export async function tagModalSandbox(
   }
 }
 
-export async function terminateModalSandboxById(settings: Settings, sandboxId: string): Promise<boolean> {
+export async function terminateModalSandboxById(
+  settings: Settings,
+  sandboxId: string,
+): Promise<boolean> {
   if (!sandboxId) {
     return true;
   }
@@ -291,14 +310,22 @@ function tagsFromInfo(info: ModalSandboxInfo): Record<string, string> {
 }
 
 function sandboxCreatedAtMs(info: ModalSandboxInfo): number | null {
-  if (typeof info.createdAt !== "number" || !Number.isFinite(info.createdAt) || info.createdAt <= 0) {
+  if (
+    typeof info.createdAt !== "number" ||
+    !Number.isFinite(info.createdAt) ||
+    info.createdAt <= 0
+  ) {
     return null;
   }
   // Modal protobuf timestamps in this SDK are seconds as doubles.
-  return info.createdAt < 10_000_000_000 ? Math.floor(info.createdAt * 1000) : Math.floor(info.createdAt);
+  return info.createdAt < 10_000_000_000
+    ? Math.floor(info.createdAt * 1000)
+    : Math.floor(info.createdAt);
 }
 
-function attributionKey(input: Pick<ModalSandboxAttribution, "leaseId" | "workspaceId" | "sandboxGroupId">): string {
+function attributionKey(
+  input: Pick<ModalSandboxAttribution, "leaseId" | "workspaceId" | "sandboxGroupId">,
+): string {
   return `${input.workspaceId}:${input.sandboxGroupId}:${input.leaseId}`;
 }
 
@@ -316,6 +343,18 @@ export async function sweepModalOrphanSandboxes(
   const maxTerminations = options.maxTerminations ?? MODAL_ORPHAN_SWEEP_LIMIT;
   const unattributedGraceMs = options.unattributedGraceMs ?? MODAL_UNATTRIBUTED_ORPHAN_GRACE_MS;
   const liveByAttribution = new Map(liveLeases.map((lease) => [attributionKey(lease), lease]));
+  // LIVE-INSTANCE GUARD: a box that any live lease's envelope points at is NEVER
+  // an orphan, whatever its tags say. Tags are best-effort attribution (setTags
+  // is a separate call after create and can fail or lag); the lease envelope is
+  // the source of truth the turn path actually resumes by. Judging by tags alone
+  // terminated a LIVE box mid-turn at exactly creation+30min (staging session
+  // e644e8a8, 2026-07-06) — the box's unpushed work was unrecoverable because
+  // nothing outside the reaper drain persists /workspace.
+  const liveByInstanceId = new Map(
+    liveLeases
+      .filter((lease) => lease.instanceId)
+      .map((lease) => [lease.instanceId as string, lease]),
+  );
   const ownedClient = options.client ? null : await createModalClient(settings);
   const modal = (options.client ?? ownedClient)! as ModalCpListClient;
   try {
@@ -350,9 +389,40 @@ export async function sweepModalOrphanSandboxes(
         const leaseId = tags.opengeni_lease_id;
         const workspaceId = tags.opengeni_workspace_id;
         const sandboxGroupId = tags.opengeni_sandbox_group_id;
+        const liveByInstance = info.id ? liveByInstanceId.get(info.id) : undefined;
+        if (liveByInstance) {
+          // Live-instance guard (see above): a live lease resumes this exact box
+          // by id — hard-skip it, and HEAL its attribution tags when they are
+          // missing/stale so it stops looking sweep-eligible. Best-effort: a
+          // failed re-tag must never fail the sweep (the guard, not the tags,
+          // is what protects the box now).
+          if (
+            leaseId !== liveByInstance.leaseId ||
+            workspaceId !== liveByInstance.workspaceId ||
+            sandboxGroupId !== liveByInstance.sandboxGroupId
+          ) {
+            try {
+              const sandbox = await modal.sandboxes.fromId(info.id);
+              await sandbox.setTags(
+                modalSandboxAttributionTags({
+                  leaseId: liveByInstance.leaseId,
+                  workspaceId: liveByInstance.workspaceId,
+                  sandboxGroupId: liveByInstance.sandboxGroupId,
+                }),
+              );
+            } catch {
+              // Tag healing is opportunistic; the instance guard already
+              // protects this box on every future sweep pass.
+            }
+          }
+          skipped += 1;
+          continue;
+        }
         let reason: ModalOrphanSweepTermination["reason"] | null = null;
         if (leaseId && workspaceId && sandboxGroupId) {
-          const live = liveByAttribution.get(attributionKey({ leaseId, workspaceId, sandboxGroupId }));
+          const live = liveByAttribution.get(
+            attributionKey({ leaseId, workspaceId, sandboxGroupId }),
+          );
           if (!live || (live.instanceId && live.instanceId !== info.id)) {
             reason = "stale_attribution";
           }

package/src/sandbox/providers/selfhosted.ts

@@ -20,10 +20,7 @@ import {
   type ControlRpc,
   type NatsRequestConnection,
 } from "../selfhosted/control-rpc";
-import {
-  SelfhostedSandboxClient,
-  type SelfhostedRelayConfig,
-} from "../selfhosted/session";
+import { SelfhostedSandboxClient, type SelfhostedRelayConfig } from "../selfhosted/session";
 import type { ProviderRegistration } from "./types";
 
 /**

package/src/sandbox/recording.ts

@@ -1,6 +1,6 @@
 // @opengeni/runtime/sandbox — the recording loop (P4.3).
 //
-// ffmpeg x11grab on :0 → mp4/webm artifact on the box → read bytes → PUT to
+// ffmpeg x11grab on :0 → mp4/webm artifact on the box → direct scoped PUT to
 // object storage → recording.available. The "agent films itself proving the fix"
 // loop: ffmpeg reads exactly the :0 framebuffer the agent's computer-use draws to
 // and the human watches over Channel B (zero projection).
@@ -9,22 +9,16 @@
 // Temporal, NO worker RPC, NO actor. They live in the agent-loop-free leaf so the
 // SAME process that already holds the resumed-by-id box (the agent turn's own
 // activity for an on-turn recording, or the API in-process for an off-turn/manual
-// finalize) reads the bytes and PUTs them straight to storage. The bytes go
-// box → process memory → storage PUT and are NEVER serialized as a Temporal
-// activity result — the 256 MB-vs-payload-limit concern dissolves (F10).
+// finalize) authorizes a direct box-to-storage upload. Recording bytes never
+// enter worker memory or a Temporal payload (F10).
 //
 // ── Adversarial-review fixes folded in (module 05 §Adversarial) ──────────────
 //   F1  exec is OPTIONAL on Modal (only execCommand) — every command dual-paths.
-//   F3  exec/execCommand YIELDS — the SIGINT-and-wait loop is bounded well under
-//       the yield window; a direct `base64` exec does the byte transfer.
-//   F8  the byte read does NOT assume any over-limit behavior — we cap the ffmpeg
-//       file by size on the box first (stat) and fail `max-bytes-exceeded` rather
-//       than silently uploading a truncated video.
-//   FR  the byte transfer is a DIRECT exec (`base64 <abs-path>`), NOT readFile:
-//       the recording lives at an absolute /tmp path (never the user's workspace
-//       /git tree), and readFile rejects paths outside the manifest workspace
-//       root ("escapes the workspace root"). The base64 exec passes
-//       maxOutputTokens:null so a large recording is never truncated.
+//   F3  exec/execCommand YIELDS — the stop and direct-upload commands are bounded.
+//   F8  size is gated on the box first (stat); over-limit artifacts fail instead
+//       of being uploaded partially.
+//   FR  curl reads the absolute /tmp artifact in the box and sends it directly to
+//       the short-lived scoped URL. No workspace-root read API is involved.
 //   F9  the box file is deleted ONLY after the storage PUT confirms — never
 //       before (so a failed upload leaves the bytes recoverable for a retry).
 //   F12 ffmpeg/x11vnc backgrounding does not block the yield (nohup … & echo $!).
@@ -54,24 +48,44 @@ export function extForCodec(codec: RecordingCodec): string {
 
 /** No exec/execCommand on the session — the box cannot run ffmpeg. */
 export class RecordingUnavailableError extends Error {
-  constructor(message: string) { super(message); this.name = "RecordingUnavailableError"; }
+  constructor(message: string) {
+    super(message);
+    this.name = "RecordingUnavailableError";
+  }
 }
-/** ffmpeg failed, the file is missing, or the byte read failed. */
+/** ffmpeg failed, the file is missing, or the artifact is over its size limit. */
 export class RecordingError extends Error {
-  constructor(message: string, readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable") {
+  constructor(
+    message: string,
+    readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable",
+  ) {
     super(message);
     this.name = "RecordingError";
   }
 }
 
 // The structural slice of a provider session the recording loop drives. exec and
-// execCommand are optional (Modal has only execCommand — F1); readFile present on
-// every desktop-capable provider.
-type ExecResultLike = { output?: string; stdout?: string; stderr?: string; exitCode?: number | null; sessionId?: number };
+// execCommand are optional (Modal has only execCommand — F1).
+type ExecResultLike = {
+  output?: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  sessionId?: number;
+};
 type RecordingSession = {
-  exec?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<ExecResultLike>;
-  execCommand?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<string>;
-  readFile?: (args: { path: string; runAs?: string; maxBytes?: number }) => Promise<string | Uint8Array>;
+  exec?: (args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }) => Promise<ExecResultLike>;
+  execCommand?: (args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }) => Promise<string>;
 };
 
 function shq(s: string): string {
@@ -80,11 +94,12 @@ function shq(s: string): string {
 
 function resultOutput(result: ExecResultLike | string): string {
   if (typeof result === "string") return result;
-  return [result.output, result.stderr, result.stdout].filter((v): v is string => typeof v === "string" && v.length > 0).join("\n");
+  return [result.output, result.stderr, result.stdout]
+    .filter((v): v is string => typeof v === "string" && v.length > 0)
+    .join("\n");
 }
 
-// Default per-command output cap (tokens). The byte-read path overrides this to
-// `null` (no truncation) so a base64-encoded recording is never clipped.
+// Default per-command output cap (tokens). Recording transfer does not use stdout.
 const DEFAULT_MAX_OUTPUT_TOKENS = 4_000;
 
 async function run(
@@ -92,20 +107,23 @@ async function run(
   cmd: string,
   runAs?: string,
   yieldTimeMs = EXEC_YIELD_MS,
-  maxOutputTokens: number | null = DEFAULT_MAX_OUTPUT_TOKENS,
+  maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS,
 ): Promise<string> {
-  // `maxOutputTokens: null` disables the provider's output truncation entirely
-  // (SDK truncateOutput returns the raw text when the cap is nullish).
-  const args = { cmd, ...(runAs ? { runAs } : {}), yieldTimeMs, maxOutputTokens } as {
-    cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number;
-  };
+  const args: {
+    cmd: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  } = { cmd, ...(runAs ? { runAs } : {}), yieldTimeMs, maxOutputTokens };
   if (typeof session.exec === "function") {
     return resultOutput(await session.exec(args));
   }
   if (typeof session.execCommand === "function") {
     return resultOutput(await session.execCommand(args));
   }
-  throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording unavailable");
+  throw new RecordingUnavailableError(
+    "session cannot run commands (no exec/execCommand) — recording unavailable",
+  );
 }
 
 // Extract the command body from a provider exec banner. Modal's execCommand
@@ -149,7 +167,10 @@ export type RecordingProcess = {
  * block on the recording). A hard `-t <maxSeconds>` ceiling bounds a runaway file
  * across a multi-day turn. Returns the handle the caller carries to stop+finalize.
  */
-export async function startRecording(session: unknown, input: StartRecordingInput): Promise<RecordingProcess> {
+export async function startRecording(
+  session: unknown,
+  input: StartRecordingInput,
+): Promise<RecordingProcess> {
   const s = session as RecordingSession;
   const codec = input.codec ?? "h264-mp4";
   const dimensions = input.dimensions ?? DEFAULT_DIMENSIONS;
@@ -162,9 +183,10 @@ export async function startRecording(session: unknown, input: StartRecordingInpu
   const pidFile = `${tmp}/og-rec-${input.recordingId}.pid`;
   const logFile = `${tmp}/og-rec-${input.recordingId}.log`;
   const [w, h] = dimensions;
-  const enc = codec === "vp9-webm"
-    ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1`
-    : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
+  const enc =
+    codec === "vp9-webm"
+      ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1`
+      : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
   const ffmpeg =
     `nohup ffmpeg -hide_banner -loglevel error -f x11grab -draw_mouse 1 -framerate ${framerate} ` +
     `-video_size ${w}x${h} -i ${display}.0 -t ${maxSeconds} ${enc} ${boxPath} ` +
@@ -194,45 +216,41 @@ export async function stopRecording(session: unknown, proc: RecordingProcess): P
   await run(s, `bash -lc ${shq(wait)}`, proc.runAs, STOP_YIELD_MS).catch(() => undefined);
 }
 
-export type FinalizeRecordingResult = {
-  bytes: Uint8Array;
+export type RecordingArtifactMetadata = {
   contentType: RecordingContentType;
   sizeBytes: number;
   durationSeconds: number;
 };
 
 /**
- * Read the finalized recording bytes off the box.
- *
- * TRANSPORT: the bytes are read via a DIRECT exec (`base64 <path>` over stdout),
- * NOT via session.readFile(). The recording artifact lives at an absolute /tmp
- * path on purpose — recordings must never be written inside the user's workspace
- * /git tree — but session.readFile() resolves every path against the manifest
- * workspace root and rejects anything outside it ("Sandbox path … escapes the
- * workspace root"), which fataled finalize. Raw exec runs unrestricted shell, so
- * `base64` reads the /tmp file directly; we decode the base64 back to bytes here.
- * The byte-read exec passes `maxOutputTokens: null` so the provider never
- * truncates a large recording's base64.
- *
- * F8: we DO NOT assume any over-limit behavior. First `stat` the file size on the
- * box; if it exceeds maxBytes, fail `max-bytes-exceeded` (never upload a truncated
- * video). Otherwise read the raw bytes.
- *
- * F9: this does NOT delete the box file. The caller deletes it (deleteRecordingArtifacts)
- * ONLY after the storage PUT + `available` commit — so a failed upload leaves the
- * bytes recoverable on the box for a retry.
- *
- * F14: duration is wall-clock (now − startedAt), a close approximation of the
- * SIGINT-flushed video length.
+ * Inspect and size-gate the finalized recording while it is still on the box.
+ * No recording bytes cross into the worker process.
  */
-export async function readRecordingBytes(session: unknown, proc: RecordingProcess, maxBytes = DEFAULT_MAX_BYTES): Promise<FinalizeRecordingResult> {
+export async function inspectRecordingArtifact(
+  session: unknown,
+  proc: RecordingProcess,
+  maxBytes = DEFAULT_MAX_BYTES,
+): Promise<RecordingArtifactMetadata> {
   const s = session as RecordingSession;
   if (typeof s.exec !== "function" && typeof s.execCommand !== "function") {
-    throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording finalize unavailable");
+    throw new RecordingUnavailableError(
+      "session cannot run commands (no exec/execCommand) — recording finalize unavailable",
+    );
   }
-  // F8: size-gate on the box before reading into memory.
-  const sizeOut = (await run(s, `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`, proc.runAs)).trim();
-  const sizeLine = sizeOut.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "MISSING";
+  // F8: size-gate on the box before authorizing the upload.
+  const sizeOut = (
+    await run(
+      s,
+      `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`,
+      proc.runAs,
+    )
+  ).trim();
+  const sizeLine =
+    sizeOut
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .pop() ?? "MISSING";
   if (sizeLine === "MISSING" || sizeLine === "") {
     throw new RecordingError(`recording file missing on box: ${proc.boxPath}`, "box-death");
   }
@@ -243,44 +261,82 @@ export async function readRecordingBytes(session: unknown, proc: RecordingProces
   if (size > maxBytes) {
     throw new RecordingError(`recording ${size}B exceeds max ${maxBytes}B`, "max-bytes-exceeded");
   }
-  // Read the bytes via a DIRECT exec (base64, no output truncation), so the
-  // absolute /tmp path is NOT run through the workspace-root-scoped readFile guard.
-  const STOP_YIELD = 60_000; // a large recording's base64 read may take longer than the default exec yield.
-  const encoded = stripExecBanner(
-    await run(s, `bash -lc ${shq(`base64 ${proc.boxPath}`)}`, proc.runAs, STOP_YIELD, null),
-  );
-  const base64 = encoded.replace(/\s+/g, "");
-  if (base64.length === 0) {
-    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
-  }
-  let bytes: Uint8Array;
-  try {
-    bytes = Uint8Array.from(Buffer.from(base64, "base64"));
-  } catch (error) {
-    throw new RecordingError(`recording base64 decode failed: ${error instanceof Error ? error.message : String(error)}`, "ffmpeg-error");
-  }
-  if (bytes.length === 0) {
-    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
-  }
   return {
-    bytes,
     contentType: contentTypeForCodec(proc.codec),
-    sizeBytes: bytes.length,
+    sizeBytes: size,
     durationSeconds: Math.max(0, Math.round((Date.now() - proc.startedAt) / 1000)),
   };
 }
 
+const RECORDING_UPLOAD_OK = "OPENGENI_RECORDING_UPLOAD_OK";
+const RECORDING_UPLOAD_MAX_SECONDS = 300;
+
+/**
+ * Upload the finalized artifact directly from the sandbox to a scoped object-
+ * storage URL. The worker carries only the short URL/headers and metadata; it
+ * never materializes a base64 string or Uint8Array for a recording that may be
+ * hundreds of megabytes. curl's success marker makes an exec transport that
+ * returns non-zero command output instead of throwing still fail closed.
+ */
+export async function uploadRecordingArtifact(
+  session: unknown,
+  proc: RecordingProcess,
+  input: {
+    url: string;
+    requiredHeaders: Record<string, string>;
+    maxBytes?: number;
+    maxSeconds?: number;
+  },
+): Promise<RecordingArtifactMetadata> {
+  const maxSeconds = input.maxSeconds ?? RECORDING_UPLOAD_MAX_SECONDS;
+  if (!Number.isSafeInteger(maxSeconds) || maxSeconds <= 0 || maxSeconds > 300) {
+    throw new Error("recording upload maxSeconds must be an integer between 1 and 300");
+  }
+  const metadata = await inspectRecordingArtifact(session, proc, input.maxBytes);
+  const headers = Object.entries(input.requiredHeaders)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `--header ${shq(`${name}: ${value}`)}`)
+    .join(" ");
+  const upload = [
+    "set -euo pipefail",
+    `curl --fail --silent --show-error --connect-timeout 20 --max-time ${maxSeconds} --request PUT ${headers} --upload-file ${shq(proc.boxPath)} ${shq(input.url)}`,
+    `printf '${RECORDING_UPLOAD_OK}\\n'`,
+  ].join("; ");
+  const output = stripExecBanner(
+    await run(
+      session as RecordingSession,
+      `bash -lc ${shq(upload)}`,
+      proc.runAs,
+      (maxSeconds + 10) * 1_000,
+    ),
+  );
+  if (!output.includes(RECORDING_UPLOAD_OK)) {
+    throw new Error("recording upload did not confirm success");
+  }
+  return metadata;
+}
+
 /**
  * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
  * and the `available` row committed — never before. Best-effort; never throws.
  */
-export async function deleteRecordingArtifacts(session: unknown, proc: RecordingProcess): Promise<void> {
+export async function deleteRecordingArtifacts(
+  session: unknown,
+  proc: RecordingProcess,
+): Promise<void> {
   const s = session as RecordingSession;
   const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
-  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(() => undefined);
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(
+    () => undefined,
+  );
 }
 
 /** The storage object key for a recording artifact (parallels the file-asset layout). */
-export function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string {
+export function recordingStorageKey(
+  workspaceId: string,
+  sessionId: string,
+  recordingId: string,
+  codec: RecordingCodec,
+): string {
   return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
 }