@aicopycoders/exodus 2026.9.1100-beta.1 → 2026.9.1100-beta.3

package/assets/skills/exodus-video/SKILL.md

@@ -117,7 +117,9 @@ scene-NN.keyframe.<ext>  the picture for scene NN
 scene-NN.voice.<ext>     the voice track for scene NN, when one was delivered
                          (a Show whose voices live inside the clips delivers none)
 scene-NN.<ext>           the clip for scene NN, usually .mp4, voice included
-scene-NN.words.json      [{w, s, e}] word timings inside that clip, for captions
+scene-NN.words.json      [{w, s, e}] word timings for the speech in that scene, from
+                         the clip's own dialogue or, on a narrated scene, from the
+                         voice track (seconds from the start of that file)
 music.<ext>              the music bed, composed to the clips' total length
 manifest.json            the index below
 ```
@@ -130,6 +132,8 @@ storyboard, reference, music         filenames, or null when not delivered
 scenes[]                             one per scene, in order
   sceneIndex, durationSec            the run's number and the clip's real length
   clip, voice, keyframe, words       filenames, or null
+  wordsFrom                          clip | voice, which file the word times are
+                                     timed against; null when none came
   clipStatus                         done | failed | running | pending | missing
   error                              why the clip failed, when it did
   flagged, findings[]                QC verdict: {check, code, severity: fail|warn, detail}
@@ -140,6 +144,9 @@ failed[]                             files that did not download: {file, url, er
 How to read it before cutting:
 
 - `clipStatus: "done"` and a `clip` filename: the scene is cuttable.
+- `wordsFrom: "voice"` (or narration in the storyboard with no on-camera line):
+  a narrated scene. Its clip is picture only; the voice track is the sound.
+  Never cut a narrated scene with the clip's own audio.
 - `flagged: true` is a warning, not a block. The clip was delivered anyway; the
   findings say what the QC model saw (`wrong-character`, `eyeline-off`,
   `set-drift`, `speech-cutoff`, `framing-off`). Tell the user which scenes are
@@ -159,10 +166,15 @@ How to read it before cutting:
 
 Use the bundled script. It reads the manifest, puts every A-roll scene in order
 as the spine, lays each cutaway over the spine at the moment its line is spoken,
-normalizes everything to 1080x1920 at 24 fps, fills a silent clip with the
-scene's voice track, lays the music bed underneath at a low level, and writes one
-MP4 with faststart for upload. The path is from the workspace root; from a brand
-subfolder, prefix `../`:
+normalizes everything to 1080x1920 at 24 fps, and writes one MP4 with faststart
+for upload. The audio track comes first: a narrated scene (narration in the
+storyboard, no on-camera line) plays its voice track and nothing the clip
+recorded, and the picture is fitted to the voice (a longer clip is trimmed, a
+longer voice is sped up to at most 1.26x and then the last frame holds). A
+dialogue scene keeps the line it performed. Every segment is loudness-normalized
+to -16 LUFS, a continuous room-tone bed runs under the whole ad so the joins do
+not read as dead air, and the music bed sits underneath at a low level. The path
+is from the workspace root; from a brand subfolder, prefix `../`:
 
 ```
 node .claude/skills/exodus-video/scripts/first-cut.mjs ./ad-<runId>
@@ -185,6 +197,9 @@ the same words grouped into short subtitle lines. `--out v2.mp4` names them
 
 The times are on the finished ad's timeline, so a word's time is where you hear
 it in the MP4. Cutaways contribute nothing, because their audio never plays. A
+narrated scene counts even when it is only a picture and a voice track: its word
+times come from the voice track, and `manifest.json` says `wordsFrom: "clip"` or
+`"voice"` per scene so you can tell which file a scene's times were read off. A
 scene that came with no word times leaves a gap, and the report names it. When no
 scene delivered word times the script writes neither file and says so. Tell the
 user the two files exist and that they are what the editor imports for captions.

package/assets/skills/exodus-video/scripts/first-cut.mjs

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 // A plain first cut from a folder written by `exodus video pull`: the A-roll
 // scenes in the manifest's order make the spine, each cutaway lays over the
-// spine at the moment its cued line is spoken, the music bed goes underneath,
-// and one MP4 comes out ready to upload.
+// spine at the moment its cued line is spoken, a room-tone bed and the music
+// bed go underneath, and one MP4 comes out ready to upload.
 //
 //   node first-cut.mjs <pulled-dir> [--out cut.mp4] [--skip 2,5] [--no-music]
 //
-// A scene with a clip contributes the clip. A clip with no audio stream gets
-// the scene's voice track, or silence. A scene with no clip but a keyframe
-// becomes a still for the length of its voice track, else the storyboard's
-// planned duration, with the voice if one was delivered. --skip drops scenes.
+// The audio track comes first. A narrated scene (the storyboard gives it
+// narration and no on-camera line) plays its voice track and NOTHING the clip
+// recorded: the voice replaces the clip's audio, and the picture is fitted to
+// the voice, trimmed when the clip runs longer, sped up to at most 1.26x and
+// then held on its last frame when the voice runs longer. A dialogue scene
+// keeps the audio it performed. A scene with no clip but a keyframe becomes a
+// still for the length of its voice track, else the storyboard's planned
+// duration. Every segment is loudness-normalized to -16 LUFS before the join.
+// --skip drops scenes.
 //
 // After the render it writes the whole ad's word times beside the MP4, as
 // <out>.words.json and <out>.srt, for captioning in post.
@@ -26,6 +31,16 @@ const norm = (label) =>
   `[${label}]scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=decrease,` +
   `pad=${WIDTH}:${HEIGHT}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS},format=yuv420p`;
 const stereo = "aresample=48000,aformat=channel_layouts=stereo";
+/** Per-segment loudness, the level every clip was normalized to before the join. */
+const LOUDNORM = "loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000";
+/** Air after the last spoken word of a narrated scene, so the line lands. */
+export const TAIL_AIR_SEC = 0.8;
+/** The most a voice track may be sped up to fit its clip. */
+export const ATEMPO_CAP = 1.26;
+/** A continuous low bed under the whole ad, so the joins between clips do not read as dead air. */
+const ROOM_TONE =
+  "anoisesrc=color=brown:amplitude=0.0035:r=48000,highpass=f=60,lowpass=f=900,aformat=channel_layouts=stereo";
+const MUSIC_VOLUME = 0.18;
 
 /** The word rule the planner sized every line with (scout models.ts wordCount). */
 export function wordCount(text) {
@@ -43,12 +58,30 @@ export function lineWordCounts(storyboard) {
 
 const CUTAWAY_KINDS = new Set(["cutaway", "insert"]);
 
+const hasText = (value) => typeof value === "string" && value.trim().length > 0;
+
+/**
+ * A narrated scene: on a script-bound storyboard (one that carries the member's
+ * script lines) the scene has narration and no on-camera line. That is the same
+ * fact the server uses to leave a narrator scene's clip mute and its voice track
+ * separate. A storyboard without script lines predates that rule: its voiced
+ * clips were lip-synced to the voice on the server, so they keep their own audio.
+ */
+export function narratedScene(scene, storyboard) {
+  const scriptBound = Array.isArray(storyboard?.script) && storyboard.script.length > 0;
+  const spoken = (Array.isArray(scene?.dialogue) ? scene.dialogue : []).some(
+    (turn) => hasText(turn?.line) || hasText(turn?.text),
+  );
+  return scriptBound && hasText(scene?.voText) && !spoken;
+}
+
 export function scenePlans(storyboard) {
   const plans = new Map();
   for (const scene of storyboard?.scenes ?? []) {
     if (typeof scene?.sceneIndex !== "number") continue;
     plans.set(scene.sceneIndex, {
       cutaway: CUTAWAY_KINDS.has(scene.kind),
+      narrated: narratedScene(scene, storyboard),
       lineIds: Array.isArray(scene.lineIds) ? scene.lineIds : [],
       cueLineId: typeof scene.cueLineId === "string" ? scene.cueLineId : null,
       durationSec: typeof scene.durationSec === "number" ? scene.durationSec : null,
@@ -57,6 +90,30 @@ export function scenePlans(storyboard) {
   return plans;
 }
 
+/**
+ * Fit a picture to its voice track. The segment runs as long as the voice plus
+ * a beat of air. A clip that runs longer is trimmed; a voice that runs longer
+ * is sped up to at most ATEMPO_CAP and the clip's last frame is held for
+ * whatever is still left. A still (no clip) simply runs the voice's length.
+ */
+export function fitNarration({ clipSeconds, voiceSeconds }) {
+  const target = voiceSeconds + TAIL_AIR_SEC;
+  if (clipSeconds === null) return { seconds: target, atempo: 1, holdSec: 0, trimmedBy: 0 };
+  if (target <= clipSeconds) {
+    return { seconds: target, atempo: 1, holdSec: 0, trimmedBy: clipSeconds - target };
+  }
+  const room = Math.max(clipSeconds - TAIL_AIR_SEC, 0.1);
+  const atempo = Math.min(ATEMPO_CAP, voiceSeconds / room);
+  const fitted = voiceSeconds / atempo + TAIL_AIR_SEC;
+  if (fitted <= clipSeconds) return { seconds: fitted, atempo, holdSec: 0, trimmedBy: 0 };
+  return { seconds: fitted, atempo, holdSec: fitted - clipSeconds, trimmedBy: 0 };
+}
+
+function scaleWords(words, atempo) {
+  if (!words || atempo === 1) return words;
+  return words.map((w) => ({ ...w, s: w.s / atempo, e: w.e / atempo }));
+}
+
 export function cueOffsetOnSpine(spine, counts, cueLineId) {
   for (const seg of spine) {
     const idx = seg.lineIds.indexOf(cueLineId);
@@ -115,29 +172,61 @@ export function buildTimeline({ manifest, storyboard, skip, probe, exists, readW
       continue;
     }
 
+    const narrated = plan.narrated || scene.wordsFrom === "voice";
+    const voice = exists(scene.voice) ? scene.voice : null;
+    const flag = scene.flagged ? " (flagged)" : "";
+
     if (exists(scene.clip)) {
       const clip = probe(scene.clip);
-      const voice = clip.hasAudio || !exists(scene.voice) ? null : scene.voice;
-      const flag = scene.flagged ? " (flagged)" : "";
-      const silent = clip.hasAudio ? "" : voice ? `, silent clip + ${voice}` : ", silent clip";
-      spine.push({
-        sceneIndex: n, source: "clip", file: scene.clip, seconds: clip.seconds,
-        hasAudio: clip.hasAudio, voice, startSec, lineIds: plan.lineIds,
-        words: readWords(scene.words), note: `${flag}${silent}`,
-      });
-      startSec += clip.seconds;
+      const base = {
+        sceneIndex: n, source: "clip", file: scene.clip, clipSeconds: clip.seconds,
+        startSec, lineIds: plan.lineIds,
+      };
+      if (voice && (narrated || !clip.hasAudio)) {
+        const fit = fitNarration({ clipSeconds: clip.seconds, voiceSeconds: probe(voice).seconds });
+        const how = [];
+        if (fit.trimmedBy > 0.05) how.push(`clip trimmed ${clip.seconds.toFixed(1)}s -> ${fit.seconds.toFixed(1)}s`);
+        if (fit.atempo > 1.001) how.push(`voice sped up ${fit.atempo.toFixed(2)}x`);
+        if (fit.holdSec > 0.05) how.push(`last frame held ${fit.holdSec.toFixed(1)}s`);
+        spine.push({
+          ...base, audio: "narration", voice, seconds: fit.seconds, atempo: fit.atempo,
+          holdSec: fit.holdSec, words: scaleWords(readWords(scene.words), fit.atempo),
+          note: `${flag}, ${voice} replaces the clip's audio${how.length ? ` (${how.join(", ")})` : ""}`,
+        });
+      } else if (narrated) {
+        spine.push({
+          ...base, audio: "silence", voice: null, seconds: clip.seconds, atempo: 1, holdSec: 0,
+          words: null,
+          note: `${flag}, narrated scene without its voice track: the clip's own audio is muted`,
+        });
+      } else if (clip.hasAudio) {
+        spine.push({
+          ...base, audio: "clip", voice: null, seconds: clip.seconds, atempo: 1, holdSec: 0,
+          words: readWords(scene.words), note: `${flag}, its own dialogue`,
+        });
+      } else {
+        spine.push({
+          ...base, audio: "silence", voice: null, seconds: clip.seconds, atempo: 1, holdSec: 0,
+          words: null, note: `${flag}, silent clip`,
+        });
+      }
+      startSec += spine[spine.length - 1].seconds;
       continue;
     }
     if (exists(scene.keyframe)) {
-      const voice = exists(scene.voice) ? scene.voice : null;
-      const seconds = voice ? probe(voice).seconds : (plan.durationSec ?? 4);
+      const fit = voice
+        ? fitNarration({ clipSeconds: null, voiceSeconds: probe(voice).seconds })
+        : { seconds: plan.durationSec ?? 4, atempo: 1, holdSec: 0 };
       spine.push({
-        sceneIndex: n, source: "still", file: scene.keyframe, seconds,
-        hasAudio: false, voice, startSec, lineIds: plan.lineIds,
-        words: null,
-        note: `${voice ? ` + ${voice}` : ", silent"} (${seconds.toFixed(1)}s, clip ${scene.clipStatus})`,
+        sceneIndex: n, source: "still", file: scene.keyframe, clipSeconds: null,
+        seconds: fit.seconds, audio: voice ? "narration" : "silence", voice, atempo: 1, holdSec: 0,
+        startSec, lineIds: plan.lineIds,
+        // #1689: on a narrated scene the words are the voice track's, and the
+        // voice starts where the segment does, so they need no offset here.
+        words: voice ? readWords(scene.words) : null,
+        note: `${flag}${voice ? ` + ${voice}` : ", silent"} (${fit.seconds.toFixed(1)}s, clip ${scene.clipStatus})`,
       });
-      startSec += seconds;
+      startSec += fit.seconds;
       continue;
     }
     dropped.push({ n, reason: `scene ${n}: ${nothing}` });
@@ -191,14 +280,20 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
       seg.source === "clip"
         ? addInput("-i", resolve(seg.file))
         : addInput("-loop", "1", "-t", String(seg.seconds), "-i", resolve(seg.file));
-    filters.push(`${norm(`${i}:v`)}[v${i}]`);
-    if (seg.hasAudio) {
-      filters.push(`[${i}:a]${stereo}[a${i}]`);
-    } else if (seg.voice) {
+    const fit = [];
+    if (seg.source === "clip" && seg.clipSeconds !== null && seg.seconds < seg.clipSeconds - 0.01) {
+      fit.push(`trim=0:${sec(seg.seconds)},setpts=PTS-STARTPTS`);
+    }
+    if (seg.holdSec > 0.01) fit.push(`tpad=stop_mode=clone:stop_duration=${sec(seg.holdSec)}`);
+    filters.push(`${norm(`${i}:v`)}${fit.length ? `,${fit.join(",")}` : ""}[v${i}]`);
+    if (seg.audio === "narration") {
       const v = addInput("-i", resolve(seg.voice));
-      filters.push(`[${v}:a]${stereo},apad,atrim=0:${seg.seconds}[a${i}]`);
+      const tempo = seg.atempo > 1.001 ? `atempo=${seg.atempo.toFixed(4)},` : "";
+      filters.push(`[${v}:a]${stereo},${tempo}${LOUDNORM},apad,atrim=0:${sec(seg.seconds)}[a${i}]`);
+    } else if (seg.audio === "clip") {
+      filters.push(`[${i}:a]${stereo},${LOUDNORM},apad,atrim=0:${sec(seg.seconds)}[a${i}]`);
     } else {
-      filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${seg.seconds}[a${i}]`);
+      filters.push(`anullsrc=r=48000:cl=stereo,atrim=0:${sec(seg.seconds)}[a${i}]`);
     }
     pairs.push(`[v${i}][a${i}]`);
   }
@@ -225,13 +320,17 @@ export function buildFfmpegArgs(timeline, { resolve, music, out }) {
     videoLabel = `ov${j}`;
   });
 
-  let audioLabel = "voice";
+  filters.push(`${ROOM_TONE}[room]`);
+  const beds = ["[room]"];
   if (music) {
     const m = addInput("-stream_loop", "-1", "-i", music);
-    filters.push(`[${m}:a]${stereo},volume=0.18[bed]`);
-    filters.push(`[voice][bed]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[mix]`);
-    audioLabel = "mix";
+    filters.push(`[${m}:a]${stereo},volume=${MUSIC_VOLUME}[bed]`);
+    beds.push("[bed]");
   }
+  filters.push(
+    `[voice]${beds.join("")}amix=inputs=${beds.length + 1}:duration=first:dropout_transition=0:normalize=0[mix]`,
+  );
+  const audioLabel = "mix";
 
   return [
     "-y", "-hide_banner", "-loglevel", "error",
@@ -462,7 +561,7 @@ function main() {
   }
   const silent = noWordTimes(timeline);
   if (silent.length > 0) console.log(`No word times: ${silent.join(", ")}`);
-  console.log(`Music bed: ${music ?? "none"}`);
+  console.log(`Room tone: under the whole ad. Music bed: ${music ?? "none"}`);
   console.log(`Upload it: exodus video upload ${manifest.runId} --file ${out}`);
 }
 

package/dist/commands/video.d.ts

@@ -41,6 +41,7 @@ export type ArtifactSubset = {
     sceneIndex?: number;
     audioUrl?: string;
     durationSec?: number;
+    words?: ClipWord[];
 } | {
     type: "text" | "primer" | "session" | "document";
 };
@@ -129,12 +130,16 @@ export type RunStop = {
 } | {
     at: "failed";
     error?: string;
+    repair?: true;
+    nodeId?: string;
+    step?: string;
 } | {
     at: "finished";
     status: string;
 };
 export declare function classifyRun(run: VideoRun): RunStop;
 export declare function stageWord(stage: string): string;
+export declare function stepName(kind: string | undefined): string;
 export declare function stopLines(stop: RunStop, runId: string, dashboardUrl: string): string[];
 export interface PullDownload {
     file: string;
@@ -149,6 +154,7 @@ export interface ManifestScene {
     durationSec: number | null;
     clip: string | null;
     words: string | null;
+    wordsFrom: "clip" | "voice" | null;
     voice: string | null;
     keyframe: string | null;
     qc: ClipQc | null;
@@ -208,6 +214,7 @@ export declare function flagFlow(runId: string, note: string, json: boolean, dep
 export declare function pullFlow(runId: string, dir: string, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function parseMvhdDurationSec(bytes: Uint8Array): number | null;
 export declare const NO_DURATION_MESSAGE: string;
+export declare function describeFetchFailure(err: unknown): string;
 export declare function uploadFlow(runId: string, filePath: string, durationFlag: string | undefined, json: boolean, deps: VideoDeps): Promise<FlowResult>;
 export declare function parsePositional(args?: string[]): string[];
 export declare function run(flags: Record<string, string | boolean>): Promise<void>;

package/dist/commands/video.js

@@ -181,6 +181,17 @@ export function classifyRun(run) {
     if (run.isTerminal)
         return { at: "finished", status: run.status };
     if (isAwaitingApproval(run.status)) {
+        if (run.pauseReason === "repair") {
+            const deadNode = run.nodes.find((n) => n.status === "failed");
+            const why = deadNode?.error ?? run.error;
+            return {
+                at: "failed",
+                repair: true,
+                nodeId: deadNode?.nodeId ?? run.pausedNodeId,
+                ...(deadNode?.kind ? { step: deadNode.kind } : {}),
+                ...(why ? { error: why } : {}),
+            };
+        }
         const pausedNode = run.nodes.find((n) => n.nodeId === run.pausedNodeId);
         if (pausedNode && parkedAtStoryboardGate(run, pausedNode)) {
             return { at: "storyboard-gate", nodeId: pausedNode.nodeId };
@@ -204,6 +215,19 @@ const STAGE_WORDS = {
 export function stageWord(stage) {
     return STAGE_WORDS[stage] ?? stage;
 }
+const STEP_NAMES = {
+    brief: "The script read",
+    storyboard: "The storyboard",
+    reference: "The reference still",
+    "scene-frames": "The scene pictures",
+    voiceover: "The voices",
+    video: "The clips",
+};
+export function stepName(kind) {
+    if (!kind)
+        return "A step in this run";
+    return STEP_NAMES[kind] ?? `The ${kind} step`;
+}
 export function stopLines(stop, runId, dashboardUrl) {
     if (stop.at === "storyboard-gate") {
         return [
@@ -221,6 +245,13 @@ export function stopLines(stop, runId, dashboardUrl) {
         ];
     }
     if (stop.at === "failed") {
+        if (stop.repair) {
+            return [
+                `${stepName(stop.step)} failed${stop.error ? `: ${stop.error}` : "."}`,
+                `Try that step again: exodus workflow repair ${runId} retry`,
+                `Or open the run:     ${dashboardUrl}/video?ad=${runId}`,
+            ];
+        }
         return [
             `This run failed${stop.error ? `: ${stop.error}` : "."}`,
             `See how far it got: exodus video status ${runId}`,
@@ -305,8 +336,11 @@ export function planPull(run, items, opts) {
         if (!artifact.audioUrl)
             continue;
         voiceByScene.set(artifact.sceneIndex, {
-            file: `${scenePrefix(artifact.sceneIndex)}.voice.${extFor(artifact.audioUrl, "audio")}`,
-            url: artifact.audioUrl,
+            download: {
+                file: `${scenePrefix(artifact.sceneIndex)}.voice.${extFor(artifact.audioUrl, "audio")}`,
+                url: artifact.audioUrl,
+            },
+            words: artifact.words ?? null,
         });
     }
     const clipByScene = new Map();
@@ -345,18 +379,30 @@ export function planPull(run, items, opts) {
     ].sort((a, b) => a - b);
     const scenes = sceneIndexes.map((sceneIndex) => {
         const clip = clipByScene.get(sceneIndex);
+        const voice = voiceByScene.get(sceneIndex);
         const item = clipItemByScene.get(sceneIndex);
-        let words = null;
+        let source = null;
+        let wordsFrom = null;
         if (clip?.words && clip.words.length > 0) {
+            source = clip.words;
+            wordsFrom = "clip";
+        }
+        else if (voice?.words && voice.words.length > 0) {
+            source = voice.words;
+            wordsFrom = "voice";
+        }
+        let words = null;
+        if (source) {
             words = `${scenePrefix(sceneIndex)}.words.json`;
-            texts.push({ file: words, body: `${JSON.stringify(clip.words, null, 2)}\n` });
+            texts.push({ file: words, body: `${JSON.stringify(source, null, 2)}\n` });
         }
         return {
             sceneIndex,
             durationSec: clip?.durationSec ?? null,
             clip: clip?.download.file ?? null,
             words,
-            voice: voiceByScene.get(sceneIndex)?.file ?? null,
+            wordsFrom,
+            voice: voice?.download.file ?? null,
             keyframe: keyframeByScene.get(sceneIndex)?.file ?? null,
             qc: clip?.qc ?? null,
             clipStatus: item?.status ?? "missing",
@@ -368,7 +414,7 @@ export function planPull(run, items, opts) {
     const downloads = [
         ...(reference ? [reference] : []),
         ...keyframeByScene.values(),
-        ...voiceByScene.values(),
+        ...[...voiceByScene.values()].map((v) => v.download),
         ...[...clipByScene.values()].map((c) => c.download),
         ...(music ? [music] : []),
     ];
@@ -396,14 +442,18 @@ export function markPullFailure(manifest, failure) {
     if (manifest.music === failure.file)
         manifest.music = null;
     for (const scene of manifest.scenes) {
+        const lostWordsSource = (scene.clip === failure.file && scene.wordsFrom === "clip") ||
+            (scene.voice === failure.file && scene.wordsFrom === "voice");
         if (scene.clip === failure.file)
             scene.clip = null;
         if (scene.voice === failure.file)
             scene.voice = null;
         if (scene.keyframe === failure.file)
             scene.keyframe = null;
-        if (scene.words === failure.file)
+        if (scene.words === failure.file || lostWordsSource) {
             scene.words = null;
+            scene.wordsFrom = null;
+        }
     }
 }
 const PULL_CONCURRENCY = 4;
@@ -607,7 +657,10 @@ export async function statusFlow(runId, json, deps) {
         row[item.itemKind] = item;
         byScene.set(item.sceneIndex, row);
     }
-    const lines = [`Ad run ${runId} — ${displayRunStatus(run.status)}`, ...stopLines(stop, runId, deps.dashboardUrl)];
+    const headline = stop.at === "failed" && stop.repair
+        ? `Ad run ${runId} — Stopped, a step failed`
+        : `Ad run ${runId} — ${displayRunStatus(run.status)}`;
+    const lines = [headline, ...stopLines(stop, runId, deps.dashboardUrl)];
     if (byScene.size === 0) {
         lines.push("", "No scenes yet — this run hasn't made anything to look at.");
     }
@@ -848,6 +901,70 @@ export function parseMvhdDurationSec(bytes) {
 export const NO_DURATION_MESSAGE = "Can't tell how long this cut is.\n" +
     "Install ffmpeg (which brings ffprobe), or pass the length yourself: --duration <seconds>";
 const MB = 1024 * 1024;
+const UPLOAD_ATTEMPTS = 3;
+const UPLOAD_BACKOFF_MS = [500, 1500];
+const UPLOAD_STEP_LABEL = {
+    mint: "asking the server for an upload slot",
+    store: "sending the file to storage",
+    register: "registering the uploaded file",
+    attach: "attaching the cut to the run",
+};
+export function describeFetchFailure(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const parts = [];
+    let cause = err.cause;
+    for (let depth = 0; depth < 2 && cause && typeof cause === "object"; depth++) {
+        const level = cause;
+        const code = typeof level.code === "string" && level.code ? level.code : undefined;
+        const message = typeof level.message === "string" && level.message ? level.message : undefined;
+        if (code && message)
+            parts.push(`${code}: ${message}`);
+        else if (code)
+            parts.push(code);
+        else if (message)
+            parts.push(message);
+        cause = level.cause;
+    }
+    return parts.length > 0 ? `${err.message} (${parts.join("; ")})` : err.message;
+}
+async function withUploadRetry(step, deps, fn) {
+    let cause = "";
+    for (let attempt = 1; attempt <= UPLOAD_ATTEMPTS; attempt++) {
+        try {
+            return { ok: true, value: await fn() };
+        }
+        catch (e) {
+            cause = describeFetchFailure(e);
+            const wait = UPLOAD_BACKOFF_MS[attempt - 1];
+            if (attempt < UPLOAD_ATTEMPTS && wait !== undefined)
+                await deps.sleep(wait);
+        }
+    }
+    return { ok: false, step, attempts: UPLOAD_ATTEMPTS, cause };
+}
+function uploadRetryResult(failed, json) {
+    if (json) {
+        return {
+            code: 1,
+            lines: [
+                JSON.stringify({
+                    ok: false,
+                    step: failed.step,
+                    attempts: failed.attempts,
+                    error: failed.cause,
+                }),
+            ],
+        };
+    }
+    return {
+        code: 1,
+        lines: [
+            `Upload failed while ${UPLOAD_STEP_LABEL[failed.step]} (${failed.attempts} tries): ${failed.cause}`,
+            "Check your connection and run the same command again.",
+        ],
+    };
+}
 export async function uploadFlow(runId, filePath, durationFlag, json, deps) {
     const stat = deps.statFile(filePath);
     if (!stat)
@@ -890,34 +1007,50 @@ export async function uploadFlow(runId, filePath, durationFlag, json, deps) {
     const durationSec = asked ?? deps.probeDurationSec(filePath) ?? parseMvhdDurationSec(bytes);
     if (durationSec === null)
         return { code: 1, lines: [NO_DURATION_MESSAGE] };
-    const mint = await deps.post(ASSET_UPLOAD_URL_PATH, {});
+    const minting = await withUploadRetry("mint", deps, () => deps.post(ASSET_UPLOAD_URL_PATH, {}));
+    if (!minting.ok)
+        return uploadRetryResult(minting, json);
+    const mint = minting.value;
     if (!mint.ok)
         return errorResult(mint, json);
     const minted = mint.data;
-    if (!minted.uploadUrl || !minted.receiptId) {
+    const uploadUrl = minted.uploadUrl;
+    const receiptId = minted.receiptId;
+    if (!uploadUrl || !receiptId) {
         return { code: 1, lines: ["The server did not hand back a place to upload to."] };
     }
-    const put = await deps.uploadBytes(minted.uploadUrl, mime, bytes);
+    const storing = await withUploadRetry("store", deps, () => deps.uploadBytes(uploadUrl, mime, bytes));
+    if (!storing.ok)
+        return uploadRetryResult(storing, json);
+    const put = storing.value;
     if (!put.ok || !put.storageId) {
         const detail = put.body ? `: ${put.body.slice(0, 200)}` : "";
         return { code: 1, lines: [`Upload failed (HTTP ${put.status})${detail}`] };
     }
-    const registered = await deps.post(ASSETS_PATH, {
-        storageId: put.storageId,
-        receiptId: minted.receiptId,
+    const storageId = put.storageId;
+    const registering = await withUploadRetry("register", deps, () => deps.post(ASSETS_PATH, {
+        storageId,
+        receiptId,
         filename: path.basename(filePath),
-    });
+    }));
+    if (!registering.ok)
+        return uploadRetryResult(registering, json);
+    const registered = registering.value;
     if (!registered.ok)
         return errorResult(registered, json);
     const asset = registered.data;
-    if (!asset.assetId) {
+    const assetId = asset.assetId;
+    if (!assetId) {
         return { code: 1, lines: ["The server stored the file but did not say what to call it."] };
     }
-    const attached = await deps.post(FINAL_PATH, {
+    const attaching = await withUploadRetry("attach", deps, () => deps.post(FINAL_PATH, {
         runId,
-        assetId: asset.assetId,
+        assetId,
         durationSec,
-    });
+    }));
+    if (!attaching.ok)
+        return uploadRetryResult(attaching, json);
+    const attached = attaching.value;
     if (!attached.ok)
         return errorResult(attached, json);
     const final = attached.data;
@@ -925,7 +1058,7 @@ export async function uploadFlow(runId, filePath, durationFlag, json, deps) {
     if (json) {
         return {
             code: 0,
-            lines: [JSON.stringify({ ok: true, runId, assetId: asset.assetId, durationSec, finalWatchUrl })],
+            lines: [JSON.stringify({ ok: true, runId, assetId, durationSec, finalWatchUrl })],
         };
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.9.1100-beta.1",
+  "version": "2026.9.1100-beta.3",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",