@cueframe/kernel 0.1.1 → 0.1.3

package/dist/{chunk-DK2ODBNT.js → chunk-NQSMEUJ6.js}

@@ -20,15 +20,15 @@ import {
   scoreAndRank,
   segmentShots,
   stabilizeSelectionHysteresis
-} from "./chunk-HY3RIEZW.js";
+} from "./chunk-ZPRBGW4Y.js";
 import {
   flattenCompoundClips,
   hasCompoundClips
-} from "./chunk-TWQOKKAF.js";
+} from "./chunk-23HFEKV7.js";
 import {
   compositionHasVo,
   roleDefaultGainDb
-} from "./chunk-JMURQODM.js";
+} from "./chunk-VZ7TYX6Z.js";
 import {
   SHOT_SCALE_TARGET,
   shotScaleZoom
@@ -36,7 +36,7 @@ import {
 import {
   CueframeError,
   encodeError
-} from "./chunk-OCFDUCF4.js";
+} from "./chunk-AW57IWNW.js";
 
 // ../execution/core/src/render/emphasis.ts
 function buildEmphasisSet(emphasisWords) {
@@ -182,8 +182,6 @@ function projectClipEffects(clip, renderClipId) {
   const effects = clip.effects;
   if (!effects || effects.length === 0) return [];
   return effects.map((e, idx) => ({
-    // Deterministic, unique within the RenderInput: derives from the render-clip
-    // id + the effect's index on the clip (so React keys / clipFrames don't collide).
     id: `${renderClipId}::effect:${idx}`,
     primitiveId: e.primitiveId,
     params: e.params ?? {},
@@ -397,9 +395,6 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
         sourceOutFrames: sourceInFrames + subDurationFrames,
         timelineStartFrames: timelineCursorFrames,
         durationInFrames: subDurationFrames,
-        // Clip-relative trajectory origin: every sub-span of this clip shares the
-        // clip's trim.start, so the crop can rebase source-absolute span frames
-        // to the clip-relative (trajectory) frame across the excludedRanges gaps.
         trimStartFrames: frames(trimStart, fps),
         ...c.source.playbackRate !== void 0 ? { playbackRate: c.source.playbackRate } : {},
         ...c.source.volume !== void 0 ? { volume: c.source.volume } : {},
@@ -409,44 +404,14 @@ function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls, traj
         ...c.scale !== void 0 ? { scale: c.scale } : {},
         ...c.rotation !== void 0 ? { rotation: c.rotation } : {},
         ...c.animate !== void 0 ? { animate: c.animate } : {},
-        // Output-space placement. A sub-frame `region` makes the clip occupy
-        // only that rect of the output (PiP / split-screen / inset) — lower
-        // tracks show through the uncovered area. Carried per-clip (shared by
-        // every sub-span split from one wire clip). `fit` selects cover/contain.
         ...c.region !== void 0 ? { region: c.region } : {},
         ...c.fit !== void 0 ? { fit: c.fit } : {},
-        // Clip transition-in. Attached only to the FIRST span of a clip
-        // (transitions apply between original clips, not split sub-clips).
-        // The canonical `{type,duration}` maps to the render-input string enum
-        // + a frame count; without this the authored transition was dropped
-        // and rendered as a dead hard cut (mirror of tracksToRenderInput.ts).
         ...s === 0 && c.transitionIn ? {
           transitionIn: mapTransitionType(c.transitionIn.type),
           transitionDurationFrames: Math.max(1, Math.round(c.transitionIn.duration * fps))
         } : {},
-        // Per-frame crop trajectory URL. When present, the renderer
-        // applies the trajectory's per-frame normalized centers as a
-        // CSS transform over the raw video to produce the cropped
-        // output. Keyed by the PARENT wire-clip id `c.id` (NOT the
-        // sub-span `subId`): the trajectory map is per-clip (Phase 2), and
-        // every sub-span split from a clip shares that clip's trajectory.
-        // Resolved at the caller layer (Temporal activity), which looks up
-        // mediaItems.variants[intentHash][aspect].trajectoryR2Key per clip
-        // and presigns it.
         ...trajectoryUrls?.[c.id] !== void 0 ? { cropTrajectoryUrl: trajectoryUrls[c.id] } : {},
-        // The same trajectory IN MEMORY — the editor's path. It derives the
-        // trajectory client-side from the presigned subject track on the media
-        // row, so there is no object to fetch. Keyed by the PARENT wire-clip id
-        // for the same reason the URL map is. See `CompositionClip.cropTrajectory`.
         ...trajectories?.[c.id] !== void 0 ? { cropTrajectory: trajectories[c.id] } : {},
-        // Captions-behind CO-VIEW. Content-driven (Phase 6): the matte gate baked
-        // a crop-independent frame-packed co-view (scene over matte, one opaque
-        // H.264) for any clip whose timeline range overlaps a behind-subject
-        // caption window, surfaced here as coViewUrls[mediaId]. MATTE PRESENCE is
-        // the gate — no per-clip enable flag. The renderer splits the packed
-        // decode into the scene background + the subject cut-out foreground, and
-        // the global caption layer's behind tokens render between them (the
-        // output-space z-split in MainComposition).
         ...coViewUrls?.[c.source.mediaId] !== void 0 ? { packedUrl: coViewUrls[c.source.mediaId] } : {}
       });
     }
@@ -494,26 +459,17 @@ function projectImageTrack(track, fps, srcUrls) {
     clips.push({
       id: c.id,
       src,
-      // Stills have no source timeline — sourceIn/Out are zero. The
-      // renderer keys on mediaType==='image' to skip source-relative
-      // seeking entirely.
       sourceInFrames: 0,
       sourceOutFrames: 0,
       timelineStartFrames,
       durationInFrames,
       mediaType: "image",
       kenBurns: c.source.kenBurns ?? "in",
-      // The agent's authored camera channel for the still. When present it
-      // DRIVES the point-zoom (StillCrop derives the still trajectory from it);
-      // `kenBurns` is the fallback when no reframe was authored. This is how an
-      // image gets an arbitrary point-zoom (zoom into a UI element), not just
-      // the centered kenBurns presets.
       ...c.source.reframe !== void 0 && c.source.reframe.segments.length > 0 ? { reframe: c.source.reframe } : {},
       ...c.opacity !== void 0 ? { opacity: c.opacity } : {},
       ...c.scale !== void 0 ? { scale: c.scale } : {},
       ...c.rotation !== void 0 ? { rotation: c.rotation } : {},
       ...c.animate !== void 0 ? { animate: c.animate } : {},
-      // Output-space placement (PiP / inset still). See projectMediaTrack.
       ...c.region !== void 0 ? { region: c.region } : {},
       ...c.fit !== void 0 ? { fit: c.fit } : {}
     });
@@ -621,9 +577,6 @@ function projectOverlayTrack(track, fps, alphaUrls = {}, jsSourceByClipId = {})
       ...c.source.zPlane !== void 0 ? { zPlane: c.source.zPlane } : {},
       ...c.source.anchor !== void 0 ? { anchor: c.source.anchor } : {},
       ...c.source.parallax !== void 0 ? { parallax: c.source.parallax } : {},
-      // Output-space placement (clip-level, like media/image): the overlay
-      // primitive occupies only this sub-rect of the output (PiP / inset card).
-      // MainComposition wraps it in the same RegionBox; absent = full frame.
       ...c.region !== void 0 ? { region: c.region } : {},
       ...c.fit !== void 0 ? { fit: c.fit } : {},
       ...overlayTransitionFields(c, fps),
@@ -855,14 +808,8 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
     ...cap?.emphasisPlate != null ? { emphasisPlate: cap.emphasisPlate } : {},
     ...cap?.emphasisPlateColor ? { emphasisPlateColor: cap.emphasisPlateColor } : {},
     ...cap?.emphasisPlateTextColor ? { emphasisPlateTextColor: cap.emphasisPlateTextColor } : {},
-    // Brand accent → active/emphasis word color (today's behavior); a
-    // creator-set caption highlightColor is caption-specific identity and
-    // WINS over the generic accent.
     ...brandAccent ? { highlightColor: brandAccent, emphasisColor: brandAccent } : {},
     ...cap?.highlightColor ? { highlightColor: cap.highlightColor } : {},
-    // Brand-motion-derived caption entrance is the generic fallback; a
-    // caption-specific entrance (cap.*) is identity and WINS, so it spreads
-    // AFTER captionMotion.
     ...captionMotion ?? {},
     ...cap?.entrance ? { entrance: cap.entrance } : {},
     ...cap?.entranceMs != null ? { entranceMs: cap.entranceMs } : {},
@@ -876,22 +823,13 @@ function compositionToRenderInput(composition, srcUrls, trajectoryUrls, coViewUr
     height,
     fps,
     durationInFrames,
-    // Target platform (from the wire `Format`) frozen onto the render input so the
-    // composition floor's safe-zone placement clears that surface's UI chrome.
-    // Absent ⇒ the floor's 'unknown' (broadcast) default. Output-determining, so
-    // it's part of the render cache key (RENDER_CACHE_VERSION bumped alongside).
     ...composition.format.platform !== void 0 ? { platform: composition.format.platform } : {},
     ...audioTracks.length > 0 ? { audioTracks } : {},
     ...effects.length > 0 ? { effects } : {},
     ...hasCaptions ? { captionSegments } : {},
-    // Depth for the caption layer. Only meaningful alongside captions, so it is
-    // emitted with them — a `captionsBehind` on a composition with no caption
-    // words would be a flag describing nothing.
     ...hasCaptions && composition.captions?.zPlane === "behind-subject" ? { captionsBehind: true } : {},
     ...captionStyle ? { captionStyle } : {},
     ...brandKit ? { brandKit } : {}
-    // (fitMode deleted 2026-05-25 — baked variants replace render-time fit
-    // decisions; the chosen variant URL IS the framing.)
   };
 }
 function assembleRenderInput(composition, resolved) {
@@ -940,27 +878,17 @@ var BPP = {
 function bppToCrf(bpp) {
   return Math.max(15, Math.min(36, Math.round(51 - bpp * 120)));
 }
-function computeExportDimensions(sourceWidth, sourceHeight, format, quality) {
-  let w;
-  let h;
-  if (format === "source") {
-    w = sourceWidth;
-    h = sourceHeight;
-  } else {
-    const preset = FORMAT_PRESETS[format];
-    const shortEdge = Math.min(sourceWidth, sourceHeight);
-    const minAspect = Math.min(preset.aspectWidth, preset.aspectHeight);
-    w = Math.round(shortEdge * (preset.aspectWidth / minAspect));
-    h = Math.round(shortEdge * (preset.aspectHeight / minAspect));
-  }
-  w = w % 2 === 0 ? w : w + 1;
-  h = h % 2 === 0 ? h : h + 1;
-  if (quality === "source") {
-    return { width: w, height: h, crf: void 0 };
-  }
+function qualityToCrf(quality) {
+  if (quality === "source") return void 0;
   const bpp = BPP[quality];
-  if (bpp === void 0) return { width: w, height: h, crf: void 0 };
-  return { width: w, height: h, crf: bppToCrf(bpp) };
+  return bpp === void 0 ? void 0 : bppToCrf(bpp);
+}
+function resolutionToOutputSize(width, height, resolution) {
+  if (resolution === "source") return void 0;
+  const preset = RESOLUTION_PRESETS[resolution];
+  const shortEdge = Math.min(width, height);
+  if (!preset || shortEdge <= 0 || shortEdge === preset.height) return void 0;
+  return { outputWidth: ensureEven(Math.round(width * preset.height / shortEdge)) };
 }
 function ensureEven(n) {
   return n % 2 === 0 ? n : n + 1;
@@ -1725,10 +1653,6 @@ function deriveTrajectory(track, segments, aspect, bakeVersion, isGenerated = fa
       subject,
       segCuts,
       fps,
-      // The all-faces cameraPath sizes its deadzone-inclusion crop window from
-      // the output aspect + the segment's authored zoom (default 1.0). Other
-      // modes ignore these. Per-shot zoom calibration (below) is `face`-only, so
-      // the all-faces window matches the emitted `zoom_scale` for every sub-shot.
       aspect,
       zoomScale
     );
@@ -1812,8 +1736,6 @@ function deriveTrajectory(track, segments, aspect, bakeVersion, isGenerated = fa
       const zooms = seg.ease ? buildEasedZooms(subLen, fps, zoom, seg.ease.in, seg.ease.out) : void 0;
       out.push({
         idx: out.length,
-        // Frame-based off the SNAPPED segStart (not the authored seg.startSec) so
-        // the segment times line up with the cut-aligned slice the render reads.
         start_sec: (segStart + a) / fps,
         end_sec: (segStart + b) / fps,
         zoom_scale: zoom,
@@ -1823,11 +1745,6 @@ function deriveTrajectory(track, segments, aspect, bakeVersion, isGenerated = fa
         subjects: subSubjects,
         caption_band_reserve: captionBandReserve(aspect),
         ...zooms ? { zooms } : {},
-        // Emit the DERIVED `overframed` outcome ONLY when true (an all-faces
-        // sub-shot whose group is wider than the aspect). Omitted (undefined) on
-        // a fitting group and every other mode, so the field never appears unless
-        // it is the documented widest-honest-frame case — keeps the trajectory
-        // JSON minimal and the golden diff scoped to real over-wide shots.
         ...overframed ? { overframed: true } : {}
       });
     }
@@ -1921,7 +1838,8 @@ export {
   FORMAT_PRESETS,
   RESOLUTION_PRESETS,
   bppToCrf,
-  computeExportDimensions,
+  qualityToCrf,
+  resolutionToOutputSize,
   ensureEven,
   faceArea,
   resolveSubjectFaces,

package/dist/{chunk-YX2GSJK7.js → chunk-RP4SXXLJ.js}

@@ -1,6 +1,6 @@
 import {
   FitText
-} from "./chunk-AYVJXDLB.js";
+} from "./chunk-XHGZ2E77.js";
 import {
   ACCENT,
   BG,

package/dist/{chunk-P727GZVO.js → chunk-SAMQUUO5.js}

@@ -4,15 +4,15 @@ import {
 import {
   resolveContrast
 } from "./chunk-EMGFZ3PR.js";
+import {
+  resolveFitFontSize
+} from "./chunk-XHGZ2E77.js";
 import {
   fadeProgress,
   resolveEasing,
   staggerUp,
   wordPop
 } from "./chunk-ZFEXATWN.js";
-import {
-  resolveFitFontSize
-} from "./chunk-AYVJXDLB.js";
 
 // ../execution/primitives/src/hero-text/HeroText.tsx
 import { useCurrentFrame, useVideoConfig } from "remotion";
@@ -92,8 +92,6 @@ function HeroText({
         fontSize,
         fontWeight: fontWeight ?? 800,
         letterSpacing: "-0.02em",
-        // behind-subject host: a real off-white color, NO contrast shadow — the
-        // subject silhouette biting the letters supplies the depth.
         color: textColor ?? resolveContrast({ behindSubject: true }).textColor,
         fontFamily: fontFamily ?? resolveTypeface("display")
       }

package/dist/{chunk-MMEJ3Y7E.js → chunk-SDCEJAO2.js}

@@ -5,7 +5,7 @@ import {
   isOk,
   opById,
   safeParse
-} from "./chunk-SIGGQRY2.js";
+} from "./chunk-DL7WYISQ.js";
 
 // ../mcp/src/wait.ts
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -14,7 +14,47 @@ var DEFAULT_POLL_MS = 3e3;
 function fmtTime(sec) {
   return `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, "0")}`;
 }
+function describeProgress(json, nowMs) {
+  const status = json?.processingStatus?.phase ?? json?.status;
+  const phase = json?.progress?.phase;
+  const percent = json?.processingStatus?.percent ?? json?.progress?.percent;
+  const updatedAt = json?.updatedAt ?? json?.progress?.updatedAt;
+  const parts = [];
+  if (typeof status === "string" && status) parts.push(`Last status: ${status}`);
+  if (typeof phase === "string" && phase && phase !== status) parts.push(`phase: ${phase}`);
+  if (typeof percent === "number" && Number.isFinite(percent)) parts.push(`progress: ${percent}%`);
+  if (typeof updatedAt === "string" && updatedAt) {
+    parts.push(`updatedAt: ${updatedAt}`);
+    const parsed = Date.parse(updatedAt);
+    if (Number.isFinite(parsed) && nowMs >= parsed) {
+      const staleSec = Math.floor((nowMs - parsed) / 1e3);
+      if (staleSec >= 60) parts.push(`unchanged for ~${fmtTime(staleSec)}`);
+    }
+  }
+  return parts.join("; ");
+}
 var KINDS = {
+  media: {
+    operationId: "getMedia",
+    mapArg: (_p, id) => id,
+    terminal: (j) => {
+      const phase = String(j?.processingStatus?.phase ?? j?.status ?? "");
+      if (phase === "complete" || phase === "completed" || phase === "ready") {
+        const lines = ["Media ready."];
+        if (j?.id) lines.push(`Media ID: ${j.id}`);
+        if (j?.name) lines.push(`Name: ${j.name}`);
+        if (typeof j?.duration === "number") lines.push(`Duration: ${j.duration.toFixed(2)}s`);
+        if (j?.mimeType) lines.push(`Type: ${j.mimeType}`);
+        lines.push("\nUse this media ID with get_media_context, suggest_briefs, or as a composition source.");
+        return { ok: true, text: lines.join("\n") };
+      }
+      if (phase === "error" || phase === "failed" || phase === "cancelled") {
+        const cause = j?.processingStatus?.error ?? j?.processingStatus?.message ?? j?.error ?? "";
+        return { ok: false, text: `Media ${phase}${cause ? `: ${typeof cause === "string" ? cause : JSON.stringify(cause)}` : ""}.` };
+      }
+      return null;
+    }
+  },
   render: {
     operationId: "getRender",
     mapArg: (p, id, projectId) => p === "renderId" ? id : projectId,
@@ -33,9 +73,15 @@ Download URL: ${url}`);
         const lines = [`Render ${s}${cause ? `: ${cause}` : ""}.`];
         if (j?.errorCode) lines.push(`Code: ${j.errorCode}${j?.category ? ` (${j.category})` : ""}`);
         if (typeof j?.retryable === "boolean") {
-          lines.push(
-            j.retryable ? "retryable: true \u2014 transient pipeline failure; call retry_render to re-attempt." : `retryable: false \u2014 deterministic defect${j?.category ? ` (category ${j.category})` : ""}; fix the composition before re-rendering \u2014 retry_render alone will not help.`
-          );
+          if (j?.category === "internal") {
+            lines.push(
+              `retryable: ${j.retryable} \u2014 Cueframe reported an INTERNAL pipeline defect. The composition has not been proven invalid; do not mutate it to work around this failure. Correlate the renderId/requestId in Axiom or Sentry and fix the failing pipeline stage.`
+            );
+          } else {
+            lines.push(
+              j.retryable ? "retryable: true \u2014 transient pipeline failure; call retry_render to re-attempt." : `retryable: false \u2014 deterministic defect${j?.category ? ` (category ${j.category})` : ""}; fix the composition before re-rendering \u2014 retry_render alone will not help.`
+            );
+          }
         }
         return { ok: false, text: lines.join("\n") };
       }
@@ -93,11 +139,6 @@ Download URL: ${url}`);
     }
   },
   consult: {
-    // A consult job IS a composeJob (routes/consult.ts returns consultJobId =
-    // composeJobId) — same detail op, different terminal: the advisory envelope
-    // (assessment / proposals / principles / plan), never the compose kind's
-    // "winner — render it" text. Before this kind existed, consult was a
-    // DEAD-END: its advisoryResult was unreachable over the curated surface.
     operationId: "getComposeJob",
     mapArg: (p, id, projectId) => p === "composeJobId" ? id : projectId,
     terminal: (j) => {
@@ -187,8 +228,6 @@ ${lines.join("\n\n")}${tail}`
     }
   },
   verify: {
-    // The generic jobs resource (GET /v1/jobs/{id}) — verify is its first
-    // tenant; future job kinds reuse this parser instead of adding adapters.
     operationId: "getJob",
     mapArg: (_p, id) => id,
     terminal: (j) => {
@@ -226,35 +265,66 @@ Worst-first critique: ${r.critique}`);
         lines.push("\nFix the lowest criterion via apply_composition, then re-verify.");
         return { ok: true, text: lines.join("\n") };
       }
-      if (s === "failed") return jobFailedResult("Verify", "score_composition", j);
+      if (s === "failed" || s === "cancelled") return jobFailedResult("Verify", "score_composition", j);
+      return null;
+    }
+  },
+  preview_frame: {
+    operationId: "getJob",
+    mapArg: (_p, id) => id,
+    terminal: (j) => {
+      const status = String(j?.status ?? "");
+      if (status === "succeeded") {
+        const result = j?.result ?? {};
+        const artifacts = Array.isArray(result.artifacts) ? result.artifacts : [];
+        const urls = artifacts.map((artifact) => artifact.url).filter((url) => typeof url === "string" && url.length > 0);
+        const lines = [`Preview-frame complete: ${artifacts.length} artifact(s).`];
+        for (const artifact of artifacts) {
+          lines.push(
+            `- ${typeof artifact.beatSec === "number" ? `${artifact.beatSec.toFixed(2)}s` : artifact.id ?? "frame"}${artifact.url ? ` \u2014 ${artifact.url}` : " \u2014 missing presigned URL"}`
+          );
+        }
+        lines.push(`
+Snapshot provenance: ${JSON.stringify(result.previewed ?? {})}`);
+        lines.push(`Geometry: ${JSON.stringify(result.geometry ?? {})}`);
+        if (result.warnings?.length) lines.push(`Warnings: ${JSON.stringify(result.warnings)}`);
+        lines.push("\nThe images ride with this result; judge the pixels and use layers/geometry as evidence.");
+        return { ok: urls.length === artifacts.length && artifacts.length > 0, text: lines.join("\n"), mediaUrls: urls };
+      }
+      if (status === "failed" || status === "cancelled") {
+        return jobFailedResult("Preview-frame", "preview_frame", j);
+      }
       return null;
     }
   },
   preview: {
-    // Generic jobs resource — preview job (single-component still).
     operationId: "getJob",
     mapArg: (_p, id) => id,
     terminal: (j) => {
       const s = String(j?.status ?? "");
       if (s === "succeeded") {
         const r = j?.result ?? {};
+        const isImage = r.artifactKind === "image" || r.contentType?.startsWith("image/") === true || !r.artifactKind && !r.contentType && /\.(?:png|jpe?g|webp)(?:\?|$)/i.test(r.url ?? "");
+        const label = isImage ? "Image" : r.artifactKind === "motion" ? "Motion clip" : "Artifact";
         return {
           ok: true,
-          mediaUrls: r.url ? [r.url] : void 0,
+          // MCP image blocks are image-only. Motion remains a truthful URL;
+          // attaching WebM bytes as an image corrupts the model-facing media type.
+          mediaUrls: r.url && isImage ? [r.url] : void 0,
           text: r.url ? `Preview ready.
 
-Clip: ${r.url}${r.urlExpiresAt ? `
+${label}: ${r.url}${r.contentType ? `
+Content-Type: ${r.contentType}` : ""}${r.urlExpiresAt ? `
 (link valid until ${r.urlExpiresAt})` : ""}
 
 Inspect it, fix the component via create_component if needed, and re-preview.` : "Preview succeeded but returned no url \u2014 inspect GET /v1/jobs for the raw result."
         };
       }
-      if (s === "failed") return jobFailedResult("Preview", "preview_component", j);
+      if (s === "failed" || s === "cancelled") return jobFailedResult("Preview", "preview_component", j);
       return null;
     }
   },
   brand_kit_extract: {
-    // Generic jobs resource — brand-token extraction job.
     operationId: "getJob",
     mapArg: (_p, id) => id,
     terminal: (j) => {
@@ -279,10 +349,14 @@ Review the tokens, then create_brand_kit to persist a kit. (0 tokens usually mea
   }
 };
 function jobFailedResult(label, reEnqueueTool, j) {
-  const code = String(j?.error?.code ?? "unknown");
+  const cancelled = j?.status === "cancelled";
+  const code = String(j?.error?.code ?? (cancelled ? "cancelled" : "unknown"));
   const msg = typeof j?.error?.message === "string" ? j.error.message : "";
-  const retryHint = code === "job_timeout" ? ` The executor died mid-run and the stall sweep reaped the job \u2014 re-enqueue ${reEnqueueTool} to retry.` : "";
-  return { ok: false, text: `${label} failed (${code})${msg ? `: ${msg}` : ""}.${retryHint}` };
+  const retryHint = code === "job_timeout" ? ` The executor died mid-run and the stall sweep reaped the job \u2014 inspect this jobId in Axiom/Sentry before retrying; re-enqueue ${reEnqueueTool} only after the failing pipeline stage is healthy.` : "";
+  return {
+    ok: false,
+    text: `${label} ${cancelled ? "cancelled" : "failed"} (${code})${msg ? `: ${msg}` : ""}.${retryHint}`
+  };
 }
 async function waitForJob(ex, kind, id, projectId, deadline, deps = {}) {
   const sleep = deps.sleep ?? defaultSleep;
@@ -290,7 +364,7 @@ async function waitForJob(ex, kind, id, projectId, deadline, deps = {}) {
   const pollMs = deps.pollMs ?? DEFAULT_POLL_MS;
   const cfg = KINDS[kind];
   const op = opById(cfg.operationId);
-  let lastStatus = "";
+  let lastProgress = "";
   const INVOKE_BUDGET_MS = deps.invokeBudgetMs ?? 2e3;
   let firstPoll = true;
   while (firstPoll || now() + INVOKE_BUDGET_MS < deadline) {
@@ -309,12 +383,12 @@ async function waitForJob(ex, kind, id, projectId, deadline, deps = {}) {
       const json = safeParse(res.text);
       const t = cfg.terminal(json);
       if (t) return t;
-      if (json && typeof json.status === "string") lastStatus = json.status;
+      lastProgress = describeProgress(json, now());
     }
     if (now() + pollMs + INVOKE_BUDGET_MS >= deadline) break;
     await sleep(pollMs);
   }
-  const tail = lastStatus ? ` Last status: ${lastStatus}.` : "";
+  const tail = lastProgress ? ` ${lastProgress}.` : "";
   return {
     ok: true,
     stillRunning: true,