@hubfluencer/mcp 0.8.2 → 0.9.1

package/dist/index.js

@@ -29488,13 +29488,13 @@ function normalizeStatus(kind, slug, data) {
   const latest = asRecord(d.latest_render);
   const videoUrl = latest.video_url ?? null;
   if (kind === "short") {
-    const stage = d.stage ?? "unknown";
+    const stage2 = d.stage ?? "unknown";
     const status = {
       kind,
       slug,
-      stage,
-      terminal: stage === "video_ready" || stage === "failed",
-      ready: stage === "video_ready",
+      stage: stage2,
+      terminal: stage2 === "video_ready" || stage2 === "failed",
+      ready: stage2 === "video_ready",
       video_url: videoUrl,
       error: d.error_message ?? null
     };
@@ -29522,29 +29522,128 @@ function normalizeStatus(kind, slug, data) {
     };
   }
   if (kind === "slider") {
-    const stage = d.status ?? "unknown";
+    const stage2 = d.status ?? "unknown";
     return {
       kind,
       slug,
-      stage,
-      terminal: stage === "completed" || stage === "failed",
-      ready: stage === "completed",
+      stage: stage2,
+      terminal: stage2 === "completed" || stage2 === "failed",
+      ready: stage2 === "completed",
       video_url: null,
       error: d.error_message ?? null
     };
   }
   const autopilot = d.autopilot_status ?? "unknown";
   const renderStatus = latest.status ?? null;
-  const ready = renderStatus === "completed" && Boolean(videoUrl);
-  const terminal = ready || autopilot === "failed" || autopilot === "cancelled" || renderStatus === "failed";
+  const segments = Array.isArray(d.segments) ? d.segments.map(asRecord) : [];
+  const activeSegments = segments.filter((segment) => {
+    const status = segment.status;
+    const preview = segment.preview_status;
+    return status === "processing" || preview === "processing" || preview === "generating";
+  });
+  const staleSegments = segments.filter((segment) => segment.video_stale === true && segment.status === "completed");
+  const failedSegments = segments.filter((segment) => segment.status === "failed");
+  const batchStatus = d.batch_generation_status ?? null;
+  const batchActive = batchStatus === "running" || batchStatus === "preparing" || batchStatus === "awaiting_previews" || batchStatus === "paused_for_retry";
+  const batchInsufficientCredits = batchStatus === "paused_insufficient_credits";
+  const batchFailed = batchStatus === "failed";
+  const autopilotActive = [
+    "pending",
+    "running",
+    "generating",
+    "rendering"
+  ].includes(autopilot);
+  const audioStale = d.narration_stale === true || d.voice_stale === true || d.music_stale === true;
+  const renderStale = latest.is_stale === true;
+  const renderFresh = latest.is_stale === false;
+  const stale = renderStale || staleSegments.length > 0 || audioStale;
+  const renderActive = renderStatus === "pending" || renderStatus === "rendering" || renderStatus === "processing";
+  const scenarioActive = d.scenario_status === "generating" || d.scenario_apply_status === "pending" || d.scenario_apply_status === "applying";
+  const narrationActive = d.narration_status === "generating";
+  const scenarioFailed = d.scenario_status === "failed";
+  const scenarioApplyFailed = d.scenario_apply_status === "failed";
+  const narrationFailed = d.narration_status === "failed";
+  const currentAudio = asRecord(d.current_audio);
+  const currentMusic = asRecord(d.current_music);
+  const audioVersions = Array.isArray(d.audio_versions) ? d.audio_versions.map(asRecord) : [];
+  const musicVersions = Array.isArray(d.music_versions) ? d.music_versions.map(asRecord) : [];
+  const numericVersion = (version2) => typeof version2 === "number" && Number.isFinite(version2) ? version2 : 0;
+  const selectedAudioVersion = numericVersion(currentAudio.version);
+  const selectedMusicVersion = numericVersion(currentMusic.version);
+  const newerAudioVersions = audioVersions.filter((version2) => numericVersion(version2.version) > selectedAudioVersion);
+  const newerMusicVersions = musicVersions.filter((version2) => numericVersion(version2.version) > selectedMusicVersion);
+  const versionActive = (version2) => version2.status === "pending" || version2.status === "processing";
+  const newestVersion = (versions2) => versions2.reduce((latest2, version2) => {
+    if (!latest2)
+      return version2;
+    return numericVersion(version2.version) > numericVersion(latest2.version) ? version2 : latest2;
+  }, null);
+  const newestReplacementAudio = newestVersion(newerAudioVersions);
+  const newestReplacementMusic = newestVersion(newerMusicVersions);
+  const audioFailed = currentAudio.status === "failed" || currentMusic.status === "failed" || newestReplacementAudio?.status === "failed" || newestReplacementMusic?.status === "failed";
+  const audioError = [
+    newestReplacementAudio?.error_message,
+    newestReplacementMusic?.error_message,
+    currentAudio.error_message,
+    currentMusic.error_message
+  ].find((value) => typeof value === "string" && value.trim().length > 0);
+  const audioActive = currentAudio.status === "pending" || currentAudio.status === "processing" || currentMusic.status === "pending" || currentMusic.status === "processing" || newerAudioVersions.some(versionActive) || newerMusicVersions.some(versionActive);
+  const workActive = autopilotActive || batchActive || renderActive || scenarioActive || narrationActive || audioActive || activeSegments.length > 0;
+  const deliveredArtifactSupersedesOrchestrationFailure = renderStatus === "completed" && Boolean(videoUrl) && renderFresh && !stale && !workActive && failedSegments.length === 0 && !audioFailed;
+  const ready = deliveredArtifactSupersedesOrchestrationFailure;
+  const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
+  const renderFailed = renderStatus === "failed";
+  const failed = autopilotFailed && !deliveredArtifactSupersedesOrchestrationFailure || renderFailed || scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure || scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure || narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure || batchFailed && !deliveredArtifactSupersedesOrchestrationFailure || failedSegments.length > 0 || audioFailed;
+  const terminal = ready || failed || batchInsufficientCredits || !workActive;
+  let stage = autopilot;
+  if (ready)
+    stage = "completed";
+  else if (autopilot === "failed")
+    stage = "failed";
+  else if (autopilot === "cancelled")
+    stage = "cancelled";
+  else if (renderFailed)
+    stage = "render_failed";
+  else if (scenarioApplyFailed)
+    stage = "scenario_apply_failed";
+  else if (scenarioFailed)
+    stage = "scenario_failed";
+  else if (narrationFailed)
+    stage = "narration_failed";
+  else if (batchFailed)
+    stage = "batch_failed";
+  else if (failedSegments.length > 0)
+    stage = "segment_failed";
+  else if (audioFailed)
+    stage = "audio_failed";
+  else if (batchInsufficientCredits)
+    stage = "insufficient_credits";
+  else if (activeSegments.length > 0)
+    stage = "segment_processing";
+  else if (batchActive)
+    stage = "segment_generation";
+  else if (renderActive)
+    stage = "rendering";
+  else if (scenarioActive)
+    stage = "scenario_processing";
+  else if (narrationActive)
+    stage = "narration_processing";
+  else if (audioActive)
+    stage = "audio_processing";
+  else if (!workActive && stale)
+    stage = "editing_required";
+  const segmentError = failedSegments.map((segment) => segment.error_message).find((value) => typeof value === "string" && value.length > 0);
   return {
     kind,
     slug,
-    stage: autopilot,
+    stage,
     terminal,
     ready,
     video_url: videoUrl,
-    error: d.autopilot_error_message ?? null
+    error: ready ? null : d.autopilot_error_message ?? latest.error_message ?? d.scenario_apply_error_message ?? d.scenario_error_message ?? d.narration_error_message ?? d.batch_generation_error_message ?? segmentError ?? audioError ?? (batchInsufficientCredits ? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume." : null),
+    stale,
+    active_segment_ids: activeSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string"),
+    stale_segment_ids: staleSegments.map((segment) => segment.id).filter((id) => typeof id === "number" || typeof id === "string")
   };
 }
 function startStateDiscriminator(kind, data) {
@@ -29574,10 +29673,10 @@ function makeVideoAutopilotKey(slug, a, startState) {
   return idemKey("autopilot", slug, a.prompt, a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.aspect ?? "", a.voice_id ?? "", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", startState);
 }
 function editorAdCreateKey(a) {
-  return idemKey("create-editor", a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "");
+  return idemKey("create-editor", a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_image_identity ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.closing_image_identity ?? "", a.logo_path ?? "", a.logo_identity ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.cast_mode ?? "");
 }
 function editorAdAutopilotKey(slug, a) {
-  return idemKey("autopilot", slug, a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "");
+  return idemKey("autopilot", slug, a.product_prompt ?? "", a.product_subject ?? "", a.project_intent ?? "", a.language ?? "en", a.creative_format ?? "", a.visual_language ?? "", a.theme ?? "", a.voice_id ?? "", a.export_aspect_ratio ?? "", a.product_image_path ?? "", a.product_description ?? "", a.closing_image_path ?? "", a.logo_path ?? "", a.logo_treatment ?? "", a.logo_position ?? "", a.logo_duration_seconds === undefined ? "" : String(a.logo_duration_seconds), a.cast_mode ?? "", a.max_credits === undefined ? "" : String(a.max_credits));
 }
 function sliderCreateKey(a) {
   return idemKey("create-slider", a.prompt, a.mode ?? "", a.template ?? "", a.slide_count === undefined ? "" : String(a.slide_count), a.aspect_ratio ?? "", a.accent_color ?? "", a.text_position ?? "");
@@ -29587,7 +29686,14 @@ function addSegmentKey(slug, index, nonce) {
 }
 function resolveSavePath(savePath) {
   const base = resolve(process.env.HUBFLUENCER_OUTPUT_DIR || process.cwd());
-  const target = isAbsolute(savePath) ? resolve(savePath) : resolve(base, savePath);
+  let target;
+  if (isAbsolute(savePath)) {
+    target = resolve(savePath);
+  } else {
+    const workspaceCandidate = resolve(process.cwd(), savePath);
+    const workspaceCandidateInsideBase = workspaceCandidate === base || workspaceCandidate.startsWith(base + sep);
+    target = workspaceCandidateInsideBase ? workspaceCandidate : resolve(base, savePath);
+  }
   if (!target.toLowerCase().endsWith(".mp4")) {
     throw new Error("save_path must end in .mp4");
   }
@@ -30027,7 +30133,7 @@ async function runCreateCampaign(client, args, log = () => {}) {
     items,
     summary,
     steps,
-    next: `get_campaign_pack({ id: ${campaignPackId} }) to review the drafts; then, for EACH draft you want to publish, generate it EXPLICITLY (a SEPARATE, PAID step): editor_ad/short → start_autopilot({ slug }) or the granular generate/render tools; carousel → generate_slider({ slug }).`,
+    next: `get_campaign_pack({ id: ${campaignPackId} }) to review the drafts; then quote each editor draft with start_autopilot({ slug }) and, after approval, launch with start_autopilot({ slug, max_credits: approved_cap }); use generate_short/generate_slider for approved short/carousel drafts.`,
     note: `Campaign pack ${campaignPackId} created with ${summary.created} item(s), ${draftable} materialized into editable DRAFTS. ` + (positioning ? `Positioning: ${positioning}. ` : "") + "$0 so far (free AI-assist quota + 0-credit drafts). Generation/render is a separate, explicit, PAID step per draft — nothing was generated."
   };
 }
@@ -30127,7 +30233,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.8.2",
+  version: "0.9.1",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -30293,7 +30399,7 @@ class HubfluencerClient {
         if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
           throw new Error(`Request to ${method} ${path} timed out after ${attemptTimeoutMs}ms.`);
         }
-        throw e instanceof Error ? new Error(`Network error on ${method} ${path}: ${e.message}`) : e;
+        throw e instanceof Error ? Object.assign(new Error(`Network error on ${method} ${path}: ${e.message}`), { retryable: isRetryableNetworkError(e) }) : e;
       }
       if (attempt < attempts && isRetryableStatus(res.status) && !deadlinePassed(deadline)) {
         await res.text().catch(() => {});
@@ -30437,6 +30543,9 @@ var getStatusOutput = exports_external.object({
   ready: exports_external.boolean().optional(),
   video_url: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
   error: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
+  stale: exports_external.boolean().optional(),
+  active_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
+  stale_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional()
 }).passthrough();
@@ -30448,6 +30557,9 @@ var waitForCompletionOutput = exports_external.object({
   ready: exports_external.boolean().optional(),
   video_url: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
   error: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
+  stale: exports_external.boolean().optional(),
+  active_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
+  stale_segment_ids: exports_external.array(exports_external.union([exports_external.number(), exports_external.string()])).optional(),
   latest_render_free: exports_external.boolean().optional(),
   last_free_rerender_failed: exports_external.boolean().optional(),
   saved_to: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
@@ -30511,6 +30623,11 @@ var createEditorOutput = exports_external.object({
   slug: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
   kind: exports_external.string().optional(),
   status: projectRow.optional(),
+  estimated_credits: exports_external.union([exports_external.number(), exports_external.null()]).optional(),
+  available_credits: exports_external.union([exports_external.number(), exports_external.null()]).optional(),
+  affordable: exports_external.boolean().optional(),
+  charged: exports_external.boolean().optional(),
+  note: exports_external.string().optional(),
   next: exports_external.string().optional()
 }).passthrough();
 var makeVideoOutput = exports_external.object({
@@ -30522,8 +30639,8 @@ var makeVideoOutput = exports_external.object({
   ready: exports_external.boolean().optional(),
   video_url: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
   error: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
-  estimated_credits: exports_external.unknown().optional(),
-  available_credits: exports_external.unknown().optional(),
+  estimated_credits: exports_external.union([exports_external.number(), exports_external.null()]).optional(),
+  available_credits: exports_external.union([exports_external.number(), exports_external.null()]).optional(),
   affordable: exports_external.boolean().optional(),
   charged: exports_external.boolean().optional(),
   saved_to: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
@@ -30974,14 +31091,19 @@ function calendarScopeErrorText(status, code, message) {
 }
 
 // src/uploads.ts
-import { createReadStream } from "node:fs";
-import { open, readFile, stat } from "node:fs/promises";
+import { createHash as createHash2 } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath, stat } from "node:fs/promises";
 import { basename, extname, isAbsolute as isAbsolute2, resolve as resolve2, sep as sep2 } from "node:path";
+import { Readable } from "node:stream";
 var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
 var PART_RETRIES = 2;
 var ALLOW_LOOPBACK_FETCH = /^http:\/\/(localhost|127\.0\.0\.1|\[?::1\]?)/.test(process.env.HUBFLUENCER_BASE_URL || "");
 var MAX_VIDEO_BYTES = 500000000;
 var MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+var MAX_PRODUCT_IMAGE_BYTES = 8 * 1024 * 1024;
+var MAX_LOGO_BYTES = 1 * 1024 * 1024;
+var MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 var MULTIPART_THRESHOLD = 50 * 1024 * 1024;
 var MAX_CATALOG_VIDEO_DURATION_SECONDS = 60;
 var VIDEO_EXT_MIME = {
@@ -31005,6 +31127,53 @@ var CATALOG_ASSET_EXTS = Object.keys(CATALOG_EXT_MIME);
 function catalogMaxBytes(mime) {
   return mime.startsWith("video/") ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES;
 }
+function preparedUploadIdentity(file) {
+  if (!file.bytes) {
+    throw new Error("Prepared upload has no retained byte snapshot.");
+  }
+  return `${file.size}:${createHash2("sha256").update(file.bytes).digest("hex")}`;
+}
+async function fillPositionalRead(handle, buffer, offset, length, position) {
+  let filled = 0;
+  while (filled < length) {
+    const { bytesRead } = await handle.read(buffer, offset + filled, length - filled, position + filled);
+    if (bytesRead === 0)
+      break;
+    filled += bytesRead;
+  }
+  return filled;
+}
+async function closeReadHandle(handle) {
+  await handle.close();
+}
+async function readValidatedBytes(file) {
+  const buffer = Buffer.allocUnsafe(file.size);
+  let offset = 0;
+  while (offset < file.size) {
+    const { bytesRead } = await file.handle.read(buffer, offset, file.size - offset, offset);
+    if (bytesRead === 0) {
+      throw new Error(`Short read: got ${offset} of ${file.size} validated bytes (file changed under us?).`);
+    }
+    offset += bytesRead;
+  }
+  return buffer;
+}
+function validatedByteStream(file) {
+  return Readable.from(async function* () {
+    const chunkSize = 1024 * 1024;
+    let offset = 0;
+    while (offset < file.size) {
+      const length = Math.min(chunkSize, file.size - offset);
+      const chunk = Buffer.allocUnsafe(length);
+      const filled = await fillPositionalRead(file.handle, chunk, 0, length, offset);
+      if (filled !== length) {
+        throw new Error(`Short stream read: got ${filled} of ${length} bytes at offset ${offset} (file changed under us?).`);
+      }
+      offset += filled;
+      yield chunk;
+    }
+  }());
+}
 function planMultipartParts(size, partSize) {
   if (!Number.isFinite(size) || size <= 0) {
     throw new Error(`size must be a positive number, got ${size}.`);
@@ -31027,14 +31196,29 @@ function assertFullRead(bytesRead, len, partNumber, offset) {
     throw new Error(`Short read on part ${partNumber}: got ${bytesRead} of ${len} bytes at offset ${offset} (file changed under us?).`);
   }
 }
-async function resolveReadPath(filePath, extToMime, maxBytes) {
+async function openReadPath(filePath, extToMime, maxBytes) {
   if (!filePath || typeof filePath !== "string") {
     throw new Error("file_path is required.");
   }
-  const base = resolve2(process.env.HUBFLUENCER_INPUT_DIR || process.cwd());
-  const target = isAbsolute2(filePath) ? resolve2(filePath) : resolve2(base, filePath);
+  const configuredBase = resolve2(process.env.HUBFLUENCER_INPUT_DIR || process.cwd());
+  let base;
+  try {
+    base = await realpath(configuredBase);
+  } catch (e) {
+    throw new Error(`Cannot resolve input directory ${configuredBase}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const requested = isAbsolute2(filePath) ? resolve2(filePath) : resolve2(configuredBase, filePath);
+  if (requested !== configuredBase && !requested.startsWith(configuredBase + sep2)) {
+    throw new Error(`file_path must be inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${requested}.`);
+  }
+  let target;
+  try {
+    target = await realpath(requested);
+  } catch (e) {
+    throw new Error(`Cannot read ${requested}: ${e instanceof Error ? e.message : String(e)}`);
+  }
   if (target !== base && !target.startsWith(base + sep2)) {
-    throw new Error(`file_path must be inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${target}.`);
+    throw new Error(`file_path must resolve inside ${base} (set HUBFLUENCER_INPUT_DIR to change). Refusing to read ${target}.`);
   }
   const ext = extname(target).slice(1).toLowerCase();
   const mime = extToMime[ext];
@@ -31042,21 +31226,57 @@ async function resolveReadPath(filePath, extToMime, maxBytes) {
     const allowed = Object.keys(extToMime).map((e) => `.${e}`).join(", ");
     throw new Error(`Unsupported file type ".${ext}". Allowed: ${allowed}.`);
   }
-  let size;
+  let handle;
   try {
-    const st = await stat(target);
+    handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const [openedStat, targetStat, currentTarget] = await Promise.all([
+      handle.stat(),
+      stat(target),
+      realpath(requested)
+    ]);
+    if (currentTarget !== target)
+      throw new Error("path changed while opening");
+    const st = openedStat;
     if (!st.isFile())
       throw new Error("not a regular file");
-    size = st.size;
+    if (st.dev !== targetStat.dev || st.ino !== targetStat.ino) {
+      throw new Error("opened file does not match the validated target");
+    }
+    if (st.size <= 0)
+      throw new Error(`${target} is empty.`);
+    if (st.size > maxBytes) {
+      throw new Error(`${target} is ${st.size} bytes — over the ${maxBytes}-byte cap for this asset type.`);
+    }
+    return { path: target, ext, mime, size: st.size, handle };
   } catch (e) {
+    if (handle)
+      await closeReadHandle(handle).catch(() => {
+        return;
+      });
     throw new Error(`Cannot read ${target}: ${e instanceof Error ? e.message : String(e)}`);
   }
-  if (size <= 0)
-    throw new Error(`${target} is empty.`);
-  if (size > maxBytes) {
-    throw new Error(`${target} is ${size} bytes — over the ${maxBytes}-byte cap for this asset type.`);
+}
+async function prepareImageUpload(filePath, maxBytes = MAX_IMAGE_BYTES) {
+  const file = await openReadPath(filePath, IMAGE_EXT_MIME, maxBytes);
+  try {
+    file.bytes = await readValidatedBytes(file);
+    return file;
+  } catch (error2) {
+    await closeReadHandle(file.handle);
+    throw error2;
+  }
+}
+function closePreparedUploadFile(file) {
+  return closeReadHandle(file.handle);
+}
+async function resolveReadPath(filePath, extToMime, maxBytes) {
+  const file = await openReadPath(filePath, extToMime, maxBytes);
+  try {
+    const { handle: _, ...resolved } = file;
+    return resolved;
+  } finally {
+    await closeReadHandle(file.handle);
   }
-  return { path: target, ext, mime, size };
 }
 async function resolveVideoReadPath(filePath) {
   return resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
@@ -31073,7 +31293,7 @@ async function putToPresignedUrl(url, body, contentType, timeoutMs = 300000, con
     fetchBody = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
     fetchInit = { method: "PUT", headers, body: fetchBody };
   } else {
-    stream = createReadStream(body.filePath);
+    stream = validatedByteStream(body);
     headers["content-length"] = String(contentLength ?? body.size);
     fetchInit = {
       method: "PUT",
@@ -31083,19 +31303,35 @@ async function putToPresignedUrl(url, body, contentType, timeoutMs = 300000, con
     };
   }
   fetchInit.signal = AbortSignal.timeout(timeoutMs);
+  const closeStream = async () => {
+    if (!stream || stream.closed)
+      return;
+    await new Promise((resolve3, reject) => {
+      stream?.once("close", resolve3);
+      stream?.once("error", reject);
+      stream?.destroy();
+    });
+  };
   let resp;
   try {
     resp = await fetch(url, fetchInit);
   } catch (e) {
-    stream?.destroy();
+    await closeStream().catch(() => {
+      return;
+    });
     if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
       throw markRetryable(`Upload PUT timed out after ${timeoutMs / 1000}s.`);
     }
     throw e instanceof Error ? markRetryable(`Upload PUT failed: ${e.message}`) : e;
   }
+  await closeStream();
   if (!resp.ok) {
     const text = await resp.text().catch(() => "");
-    throw new Error(`Upload PUT rejected (HTTP ${resp.status})${text ? `: ${text.slice(0, 200)}` : ""}.`);
+    const error2 = new Error(`Upload PUT rejected (HTTP ${resp.status})${text ? `: ${text.slice(0, 200)}` : ""}.`);
+    if (isRetryableStatus(resp.status)) {
+      Object.assign(error2, { retryable: true });
+    }
+    throw error2;
   }
   return resp.headers.get("etag") ?? undefined;
 }
@@ -31103,31 +31339,35 @@ function markRetryable(message) {
   return Object.assign(new Error(message), { retryable: true });
 }
 async function uploadVideoFile(client, slug, filePath, opts = {}) {
-  const file = await resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
+  const file = await openReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
   const filename = basename(file.path);
   const fit_mode = opts.fitMode === "cover" ? "cover" : undefined;
   const product_description = opts.productDescription;
-  if (file.size >= MULTIPART_THRESHOLD) {
-    return uploadVideoMultipart(client, slug, file, {
+  try {
+    if (file.size >= MULTIPART_THRESHOLD) {
+      return await uploadVideoMultipart(client, slug, file, {
+        filename,
+        fit_mode,
+        product_description
+      }, opts.onProgress);
+    }
+    const buf = await readValidatedBytes(file);
+    const presign = await client.post(`/editor/${slug}/uploads/presign`, {
       filename,
+      mime_type: file.mime,
+      size_bytes: file.size,
       fit_mode,
       product_description
-    }, opts.onProgress);
+    });
+    const { upload_id, presigned_url } = presign.data;
+    await opts.onProgress?.(0, 1, `uploading ${filename}`);
+    await putToPresignedUrl(presigned_url, buf, file.mime);
+    await opts.onProgress?.(1, 1, `uploaded ${filename}, confirming`);
+    const confirmed = await client.post(`/editor/${slug}/uploads/${upload_id}/confirm`);
+    return { upload_id, status: confirmed.data?.status ?? "processing" };
+  } finally {
+    await closeReadHandle(file.handle);
   }
-  const presign = await client.post(`/editor/${slug}/uploads/presign`, {
-    filename,
-    mime_type: file.mime,
-    size_bytes: file.size,
-    fit_mode,
-    product_description
-  });
-  const { upload_id, presigned_url } = presign.data;
-  const buf = await readFile(file.path);
-  await opts.onProgress?.(0, 1, `uploading ${filename}`);
-  await putToPresignedUrl(presigned_url, buf, file.mime);
-  await opts.onProgress?.(1, 1, `uploaded ${filename}, confirming`);
-  const confirmed = await client.post(`/editor/${slug}/uploads/${upload_id}/confirm`);
-  return { upload_id, status: confirmed.data?.status ?? "processing" };
 }
 async function uploadPartWithRetry(client, slug, ids, part_number, chunk) {
   for (let attempt = 1;; attempt++) {
@@ -31143,7 +31383,8 @@ async function uploadPartWithRetry(client, slug, ids, part_number, chunk) {
       }
       return etag;
     } catch (e) {
-      if (attempt <= PART_RETRIES && isRetryableNetworkError(e)) {
+      const status = e?.status;
+      if (attempt <= PART_RETRIES && (isRetryableNetworkError(e) || typeof status === "number" && isRetryableStatus(status))) {
         await sleep3(backoffDelayMs(attempt, DEFAULT_RETRY));
         continue;
       }
@@ -31160,18 +31401,17 @@ async function uploadVideoMultipart(client, slug, file, meta2, onProgress) {
     product_description: meta2.product_description
   });
   const { upload_id, s3_upload_id, parts_count, part_size } = init.data;
-  const plan = planMultipartParts(file.size, part_size);
-  if (plan.length !== parts_count) {
-    throw new Error(`Multipart plan mismatch: server expects ${parts_count} parts, computed ${plan.length} for ${file.size} bytes at ${part_size}/part.`);
-  }
-  await onProgress?.(0, plan.length, `uploading ${meta2.filename} in ${plan.length} parts`);
-  const fh = await open(file.path, "r");
-  const parts = [];
   try {
+    const plan = planMultipartParts(file.size, part_size);
+    if (plan.length !== parts_count) {
+      throw new Error(`Multipart plan mismatch: server expects ${parts_count} parts, computed ${plan.length} for ${file.size} bytes at ${part_size}/part.`);
+    }
+    await onProgress?.(0, plan.length, `uploading ${meta2.filename} in ${plan.length} parts`);
+    const parts = [];
     for (const { part_number, offset, len } of plan) {
       const chunk = Buffer.alloc(len);
-      const { bytesRead } = await fh.read(chunk, 0, len, offset);
-      assertFullRead(bytesRead, len, part_number, offset);
+      const filled = await fillPositionalRead(file.handle, chunk, 0, len, offset);
+      assertFullRead(filled, len, part_number, offset);
       const etag = await uploadPartWithRetry(client, slug, { upload_id, s3_upload_id }, part_number, chunk);
       parts.push({ part_number, etag });
       await onProgress?.(part_number, plan.length, `uploaded part ${part_number}/${plan.length}`);
@@ -31186,73 +31426,95 @@ async function uploadVideoMultipart(client, slug, file, meta2, onProgress) {
       });
     } catch {}
     throw e;
-  } finally {
-    await fh.close();
   }
 }
 async function uploadImageFile(client, presignPath, filePath, maxBytes = MAX_IMAGE_BYTES) {
-  const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, maxBytes);
-  const presign = await client.post(presignPath, {
-    mime_type: file.mime,
-    size_bytes: file.size
-  });
-  const { presigned_url, s3_key } = presign.data;
-  const buf = await readFile(file.path);
-  await putToPresignedUrl(presigned_url, buf, file.mime);
-  return { s3_key };
+  const ownsFile = typeof filePath === "string";
+  const file = ownsFile ? await openReadPath(filePath, IMAGE_EXT_MIME, maxBytes) : filePath;
+  try {
+    const buf = file.bytes ?? await readValidatedBytes(file);
+    const presign = await client.post(presignPath, {
+      mime_type: file.mime,
+      size_bytes: file.size
+    });
+    const { presigned_url, s3_key } = presign.data;
+    await putToPresignedUrl(presigned_url, buf, file.mime);
+    return { s3_key };
+  } finally {
+    if (ownsFile)
+      await closeReadHandle(file.handle);
+  }
 }
 async function uploadShortPoster(client, slug, filePath) {
-  const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
-  const presign = await client.post(`/shorts/${slug}/poster/presign`, { content_type: file.mime });
-  const { upload_url, s3_key } = presign;
-  const buf = await readFile(file.path);
-  await putToPresignedUrl(upload_url, buf, file.mime);
-  return { s3_key };
+  const file = await openReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
+  try {
+    const buf = await readValidatedBytes(file);
+    const presign = await client.post(`/shorts/${slug}/poster/presign`, { content_type: file.mime });
+    const { upload_url, s3_key } = presign;
+    await putToPresignedUrl(upload_url, buf, file.mime);
+    return { s3_key };
+  } finally {
+    await closeReadHandle(file.handle);
+  }
 }
 async function uploadCatalogAsset(client, filePath, opts = {}) {
-  const file = await resolveReadPath(filePath, CATALOG_EXT_MIME, MAX_VIDEO_BYTES);
-  const cap = catalogMaxBytes(file.mime);
-  if (file.size > cap) {
-    throw new Error(`${file.path} is ${file.size} bytes — over the ${cap}-byte cap for ${file.mime} catalog uploads.`);
-  }
-  if (file.mime.startsWith("video/")) {
-    const duration3 = opts.durationSeconds;
-    if (typeof duration3 !== "number" || !Number.isFinite(duration3) || duration3 <= 0 || duration3 > MAX_CATALOG_VIDEO_DURATION_SECONDS) {
-      throw new Error(`Catalog video uploads require durationSeconds to be greater than 0 and no more than ${MAX_CATALOG_VIDEO_DURATION_SECONDS} seconds.`);
+  const file = await openReadPath(filePath, CATALOG_EXT_MIME, MAX_VIDEO_BYTES);
+  try {
+    const cap = catalogMaxBytes(file.mime);
+    if (file.size > cap) {
+      throw new Error(`${file.path} is ${file.size} bytes — over the ${cap}-byte cap for ${file.mime} catalog uploads.`);
     }
+    if (file.mime.startsWith("video/")) {
+      const duration3 = opts.durationSeconds;
+      if (typeof duration3 !== "number" || !Number.isFinite(duration3) || duration3 <= 0 || duration3 > MAX_CATALOG_VIDEO_DURATION_SECONDS) {
+        throw new Error(`Catalog video uploads require durationSeconds to be greater than 0 and no more than ${MAX_CATALOG_VIDEO_DURATION_SECONDS} seconds.`);
+      }
+    }
+    const bufferedBytes = file.size < MULTIPART_THRESHOLD ? await readValidatedBytes(file) : undefined;
+    const filename = basename(file.path);
+    const presign = await client.post("/assets/presign", {
+      filename,
+      mime_type: file.mime,
+      size_bytes: file.size
+    });
+    const { asset_id, presigned_url } = presign.data;
+    if (file.size >= MULTIPART_THRESHOLD) {
+      for (let attempt = 1;; attempt++) {
+        try {
+          await putToPresignedUrl(presigned_url, { handle: file.handle, size: file.size }, file.mime, 300000, file.size);
+          break;
+        } catch (error2) {
+          if (attempt >= DEFAULT_RETRY.attempts || !isRetryableNetworkError(error2)) {
+            throw error2;
+          }
+          await sleep3(backoffDelayMs(attempt, DEFAULT_RETRY));
+        }
+      }
+    } else {
+      await putToPresignedUrl(presigned_url, bufferedBytes, file.mime);
+    }
+    const confirmBody = {};
+    if (typeof opts.description === "string" && opts.description.trim() !== "")
+      confirmBody.description = opts.description;
+    if (typeof opts.width === "number")
+      confirmBody.width = opts.width;
+    if (typeof opts.height === "number")
+      confirmBody.height = opts.height;
+    if (typeof opts.durationSeconds === "number")
+      confirmBody.duration_seconds = opts.durationSeconds;
+    const confirmed = await client.post(`/assets/${asset_id}/confirm`, confirmBody);
+    const data = confirmed.data ?? {};
+    return {
+      asset_id,
+      status: typeof data.status === "string" ? data.status : "ready",
+      media_type: typeof data.media_type === "string" ? data.media_type : "",
+      mime_type: typeof data.mime_type === "string" ? data.mime_type : file.mime,
+      filename: typeof data.filename === "string" ? data.filename : filename,
+      size_bytes: typeof data.size_bytes === "number" ? data.size_bytes : file.size
+    };
+  } finally {
+    await closeReadHandle(file.handle);
   }
-  const filename = basename(file.path);
-  const presign = await client.post("/assets/presign", {
-    filename,
-    mime_type: file.mime,
-    size_bytes: file.size
-  });
-  const { asset_id, presigned_url } = presign.data;
-  if (file.size >= MULTIPART_THRESHOLD) {
-    await putToPresignedUrl(presigned_url, { filePath: file.path, size: file.size }, file.mime, 300000, file.size);
-  } else {
-    const buf = await readFile(file.path);
-    await putToPresignedUrl(presigned_url, buf, file.mime);
-  }
-  const confirmBody = {};
-  if (typeof opts.description === "string" && opts.description.trim() !== "")
-    confirmBody.description = opts.description;
-  if (typeof opts.width === "number")
-    confirmBody.width = opts.width;
-  if (typeof opts.height === "number")
-    confirmBody.height = opts.height;
-  if (typeof opts.durationSeconds === "number")
-    confirmBody.duration_seconds = opts.durationSeconds;
-  const confirmed = await client.post(`/assets/${asset_id}/confirm`, confirmBody);
-  const data = confirmed.data ?? {};
-  return {
-    asset_id,
-    status: typeof data.status === "string" ? data.status : "ready",
-    media_type: typeof data.media_type === "string" ? data.media_type : "",
-    mime_type: typeof data.mime_type === "string" ? data.mime_type : file.mime,
-    filename: typeof data.filename === "string" ? data.filename : filename,
-    size_bytes: typeof data.size_bytes === "number" ? data.size_bytes : file.size
-  };
 }
 
 // src/index.ts
@@ -31261,6 +31523,59 @@ async function fetchStatus(client, kind, slug, deadline) {
   const res = await client.get(path, undefined, deadline);
   return normalizeStatus(kind, slug, asRecord(res).data);
 }
+async function editorAutopilotQuote(client, slug, overrides = {}) {
+  try {
+    const params = new URLSearchParams;
+    if (overrides.language)
+      params.set("language", overrides.language);
+    if (overrides.product_subject)
+      params.set("product_subject", overrides.product_subject);
+    if (overrides.product_prompt)
+      params.set("product_prompt", overrides.product_prompt);
+    if (overrides.restart)
+      params.set("restart", "true");
+    const query = params.toString();
+    const response = await client.get(`/editor/${slug}/autopilot/cost${query ? `?${query}` : ""}`);
+    const cost = asRecord(asRecord(response).data);
+    const estimated_credits = typeof cost.total === "number" ? cost.total : null;
+    const available_credits = typeof cost.available_credits === "number" ? cost.available_credits : null;
+    return {
+      estimated_credits,
+      available_credits,
+      affordable: estimated_credits !== null && available_credits !== null && available_credits >= estimated_credits
+    };
+  } catch (error2) {
+    const apiError = error2;
+    if (typeof apiError.status === "number" && apiError.status >= 400 && apiError.status < 500 && apiError.status !== 429) {
+      throw error2;
+    }
+    return {
+      estimated_credits: null,
+      available_credits: null,
+      affordable: false
+    };
+  }
+}
+async function editorChargeReceipt(client, slug, action, listPriceCredits) {
+  try {
+    const response = await client.get(`/editor/${slug}`);
+    const editor = asRecord(asRecord(response).data);
+    return {
+      action,
+      list_price_credits: listPriceCredits,
+      project_spend: editor.project_spend ?? null,
+      approved_cap: editor.autopilot_max_credits ?? null,
+      approved_run_spend: editor.autopilot_credits_spent ?? null
+    };
+  } catch {
+    return {
+      action,
+      list_price_credits: listPriceCredits,
+      project_spend: null,
+      enrichment_unavailable: true
+    };
+  }
+}
 function isRecompositeInProgressConflict(e) {
   const err = e;
   if (err?.status !== 409)
@@ -31466,14 +31781,14 @@ var WRITE = {
 var SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product page — into finished, post-ready vertical videos and image carousels, and can run the surrounding content operation (plan → draft → review → schedule → measure → repeat).
 
 MAKE ONE ASSET (simplest)
-- make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_short / create_editor_ad are the per-product one-shots; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
+- make_video({ prompt }) creates, generates, and returns a finished MP4 — it picks a single-clip short or a multi-scene editor ad from the prompt (override with kind:"short"|"editor"). create_editor_ad creates/configures/prices an editor and launches only with max_credits; create_short creates a short draft; create_slider makes an image carousel; create_tracking_video burns a CV overlay onto a local clip.
 - Granular (full control): create a draft, then drive the pipeline step by step (create_editor_draft → generate_scenario → apply_scenario → review/edit prompts (set_segment_prompt) → generate_segment(s) → generate_voice + generate_music → render; regenerate_segment re-rolls a completed scene as a new version). Poll with get_status / wait_for_completion; fetch with download_result (a slider has no MP4 — read its slides with get_slider).
 
 DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 1. ONBOARD a product: extract_product_page(url) pulls facts + imagery (SSRF-hardened, 0cr); import_product_image saves its picture/logo. Persist identity once with create_product_profile + create_brand_profile so every later draft inherits it instead of re-describing the brand.
 2. PLAN ($0, free quota — not credits): plan_campaign proposes angles/formats + a per-item credit estimate; generate_hook_variations writes hook options. create_campaign(url | product_profile_id) does 1-2 end-to-end and returns a pack of editable DRAFTS.
 3. PACK & MATERIALIZE ($0): create_campaign_pack / add_pack_variations assemble items; materialize_pack_item turns each into a 0-credit draft (editor_ad/short → a video project, carousel → a slider). list_campaign_packs lists packs; get_campaign_pack({ id }) shows every item's draft slug + credit estimate.
-4. GENERATE per draft (CREDITS — a separate, explicit step): run start_autopilot/generate_short/generate_slider on each draft slug. Nothing above this line spends video credits.
+4. GENERATE per draft (CREDITS — a separate, explicit step): start_autopilot({slug}) quotes free; after approval, start_autopilot({slug,max_credits:approved_cap}) launches. Run generate_short/generate_slider for approved short/carousel drafts. Nothing above this line spends video credits.
 5. REVIEW: create_review_link mints a no-login page where a human approves/comments (list_review_links / revoke_review_link manage them). Gate spend or posting on approval.
 6. CALENDAR (reminder-only): schedule_post / list_scheduled_posts / reschedule_post / cancel_scheduled_post stage a calendar that pushes REMINDERS to the user — it does NOT auto-publish (posting to TikTok/IG stays a human step in the app). After the user posts the presigned export, call mark_scheduled_posted.
 7. MEASURE → DOUBLE DOWN: record_performance logs views/engagement (tag creatives via set_item_attributes); get_recommendations gives a CAUTIOUS, non-causal read of your own best hook/format (present its confidence + note as-is, never upgrade them); make_more_like_winner spins fresh hooks from a proven item — feed a winner back into add_pack_variations → step 4.
@@ -31481,11 +31796,11 @@ DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 
 CREDITS (spent server-side; each tool prices before charging — see its description)
 - Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
-- Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video/create_* report the estimate first — pass dry_run to preview, max_credits to cap.
+- Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - AI ASSISTS (all generate_*/enhance/suggest/plan/hook tools) draw a FREE daily quota (20/day), NOT credits. On 429, set auto_unlock:true to spend 1 credit for +10 assists (retried once), or write the copy yourself and use the set_* tools.
 
 WAITING & RESUMING
-- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout.
+- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout. A terminal result is not always ready: an editor can go terminal in a needs-action stage (editing_required = stale after edits, regenerate the flagged scenes/audio; insufficient_credits = batch parked, top up / reduce scope; idle = draft with nothing generating, start generation first) — act on those instead of re-polling.
 - Creates and charged actions are idempotency-keyed: a transport retry is safe; a genuine re-run after a terminal FAILURE restarts rather than replaying the dead attempt.
 
 LOCAL FILES (sandboxed)
@@ -31573,7 +31888,7 @@ registerTool("make_video", {
     save_path: exports_external.string().optional().describe("Optional .mp4 path to download to (confined to HUBFLUENCER_OUTPUT_DIR or cwd)"),
     max_wait_seconds: exports_external.number().optional().describe("Block budget seconds (default 240, capped 10–280)"),
     dry_run: exports_external.boolean().optional().describe("Preview only: create a free draft, price it, and STOP before spending credits. " + "Returns {estimated_credits, available_credits, slug}. Resume with generate_short / start_autopilot."),
-    max_credits: exports_external.number().optional().describe("Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.")
+    max_credits: exports_external.number().int().nonnegative().optional().describe("Spend cap: refuse to start (no charge) if the priced estimate exceeds this. Returns the estimate.")
   },
   outputSchema: makeVideoOutput,
   annotations: { title: "Make a video", ...WRITE, idempotentHint: false }
@@ -31660,11 +31975,12 @@ registerTool("make_video", {
     estimated_credits = typeof cost.total === "number" ? cost.total : null;
     available_credits = typeof cost.available_credits === "number" ? cost.available_credits : null;
   } catch {}
-  const resume = kind === "short" ? `generate_short({ slug: "${slug}"${args.skip_auto_text ? ", skip_auto_text: true" : ""} })` : `start_autopilot({ slug: "${slug}" })`;
+  const resume = kind === "short" ? `generate_short({ slug: "${slug}"${args.skip_auto_text ? ", skip_auto_text: true" : ""} })` : `start_autopilot({ slug: "${slug}", max_credits: ${estimated_credits ?? "<approved cap>"} })`;
   const affordable = available_credits === null || estimated_credits === null || available_credits >= estimated_credits;
   const overCap = args.max_credits != null && estimated_credits != null && estimated_credits > args.max_credits;
-  if (args.dry_run || overCap || !affordable) {
-    const note = args.dry_run ? `Dry run — created a free draft and priced it (${estimated_credits ?? "?"} credits, have ${available_credits ?? "?"}). To run it: ${resume}.` : overCap ? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.` : `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
+  const editorPriceUnavailableWithoutCap = kind === "editor" && estimated_credits === null && args.max_credits == null;
+  if (args.dry_run || editorPriceUnavailableWithoutCap || overCap || !affordable) {
+    const note = args.dry_run ? `Dry run — created a free draft and priced it (${estimated_credits ?? "?"} credits, have ${available_credits ?? "?"}). To run it: ${resume}.` : editorPriceUnavailableWithoutCap ? `Pricing is temporarily unavailable, so the editor was left as a free draft and nothing was charged. Retry the quote, then run start_autopilot({ slug: "${slug}", max_credits: <approved cap> }).` : overCap ? `Estimated ${estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged. Raise max_credits, or run ${resume}.` : `Not enough credits (needs ${estimated_credits ?? "?"}, have ${available_credits ?? "?"}); nothing charged. Top up, then run ${resume}.`;
     return ok({
       slug,
       kind,
@@ -31684,7 +32000,11 @@ registerTool("make_video", {
   if (kind === "short") {
     await client.post(`/shorts/${slug}/generate`, args.skip_auto_text ? { skip_auto_text: true } : undefined, `gen-short:${slug}:${startState}${args.skip_auto_text ? ":bare" : ""}`);
   } else {
-    await client.post(`/editor/${slug}/autopilot`, undefined, makeVideoAutopilotKey(slug, args, startState));
+    const approvedCap = args.max_credits ?? estimated_credits;
+    if (approvedCap === null) {
+      throw new Error("Editor autopilot launch requires max_credits or a live quote");
+    }
+    await client.post(`/editor/${slug}/autopilot`, { max_credits: approvedCap }, makeVideoAutopilotKey(slug, args, startState));
   }
   await reportProgress(extra, 0, `started ${kind} ${slug}`);
   const status = await pollToTerminal(client, kind, slug, extra, budgetMs, 15000);
@@ -32133,7 +32453,7 @@ registerTool("generate_short", {
 }));
 registerTool("rerender_short", {
   title: "Re-render a short (FREE — 0 credits)",
-  description: "FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " + "footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. Footage or music " + "changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " + "end_card) can shift the video between 12s and 14s; the pinned music bed is faded to fit rather than " + "regenerated — for perfectly synced music after such a change, use generate_short. " + "Requires a completed generation to re-render over " + "(422 short_not_ready otherwise — run generate_short once first); while any generation/render is in " + "flight it reports in-progress (409) rather than duplicating. Then poll with get_status or " + "wait_for_completion (kind=short). A failed free re-render leaves the delivered video intact — retry " + "rerender_short, it stays free (the status fields latest_render_free / last_free_rerender_failed " + "report this when the server sends them).",
+  description: "FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " + "footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. Footage or music " + "changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " + "end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " + "export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " + "Requires a completed generation to re-render over " + "(422 short_not_ready otherwise — run generate_short once first); while any generation/render is in " + "flight it reports in-progress (409) rather than duplicating. Then poll with get_status or " + "wait_for_completion (kind=short). A failed free re-render leaves the delivered video intact — retry " + "rerender_short, it stays free (the status fields latest_render_free / last_free_rerender_failed " + "report this when the server sends them).",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)")
   },
@@ -32373,8 +32693,8 @@ registerTool("edit_slider_slide", {
   }
 }));
 registerTool("create_editor_ad", {
-  title: "Create a multi-scene editor ad (autopilot)",
-  description: "Creates an editor project from a product prompt and starts autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " + "make_video for the one-shot path. " + "BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " + "create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " + "start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " + "title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " + "For product_only or presenter_led cast modes, use create_editor_draft and configure the required " + "product/presenter before start_autopilot; this one-shot tool intentionally uses automatic casting.",
+  title: "Create, configure, and price a multi-scene editor ad",
+  description: "Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " + "and prices autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " + "the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " + "wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " + "Supplying assets here is safer than adding them after autopilot because the scenario and scenes are grounded " + "in the real product from the start. (Editor ads carry their copy in-scene/narration, not as a " + "title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.) " + "For a mascot or hero product that must stay visually identical with no human presenter, set " + "cast_mode:'product_only' together with product_image_path. Presenter-led casting still belongs on " + "create_editor_draft because it requires a separately configured presenter.",
   inputSchema: {
     product_prompt: exports_external.string().min(10).describe("Brief for the ad (min 10 chars)"),
     product_subject: exports_external.string().max(300).optional().describe('The concrete product or main subject the video must be about (e.g. "Bordeaux red wine, dark green ' + 'bottle with a gold label"). Distinct from the freeform brief: hard-grounds the AI scenario + narration ' + "so it cannot invent an unrelated product. Strongly recommended for ads."),
@@ -32384,42 +32704,140 @@ registerTool("create_editor_ad", {
     visual_language: exports_external.enum(VISUAL_LANGUAGES).optional().describe("Visual style direction and render look. Good default: kinetic_creator. When set it drives the look and a theme of 'none' is ignored."),
     theme: exports_external.string().optional().describe('Visual theme / genre overlay (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.'),
     voice_id: exports_external.string().optional().describe("Preferred narration voice id (see list_voices); omit for the default voice"),
-    export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")')
+    export_aspect_ratio: exports_external.enum(["9:16", "16:9", "1:1"]).optional().describe('Aspect ratio (default "9:16")'),
+    product_image_path: exports_external.string().optional().describe("Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot."),
+    product_description: exports_external.string().max(500).optional().describe("Exact product/character description used with product_image_path."),
+    closing_image_path: exports_external.string().optional().describe("Local closing-card image (.jpg/.jpeg/.png, ≤20 MiB)."),
+    logo_path: exports_external.string().optional().describe("Local logo (.jpg/.jpeg/.png, ≤1 MiB) to overlay."),
+    logo_treatment: exports_external.enum(["intro", "outro", "both", "none"]).optional().describe('When the logo bumper plays: "intro", "outro", "both" (default), or "none". Requires logo_path.'),
+    logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe('Logo corner: "top-left", "top-right" (default), "bottom-left", or "bottom-right". Requires logo_path.'),
+    logo_duration_seconds: exports_external.number().min(0.5).max(3).optional().describe("Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path."),
+    cast_mode: exports_external.literal("product_only").optional().describe("Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path."),
+    max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to create/configure/price only; no credits are charged.")
   },
   outputSchema: createEditorOutput,
   annotations: { title: "Create editor ad", ...WRITE, idempotentHint: true }
 }, tool(async (args, client) => {
-  const langErr = validateLanguage(args.language);
-  if (langErr)
-    return fail(langErr);
-  const promptErr = validateProductPrompt(args.product_prompt);
-  if (promptErr)
-    return fail(promptErr);
-  const created = await client.post("/editor", {
-    language: args.language ?? "en",
-    product_prompt: args.product_prompt,
-    product_subject: args.product_subject,
-    project_intent: args.project_intent,
-    creative_format: args.creative_format,
-    visual_language: args.visual_language,
-    theme: args.theme,
-    voice_id: args.voice_id,
-    export_aspect_ratio: args.export_aspect_ratio
-  }, editorAdCreateKey(args));
-  const slug = created.data.slug;
-  const started = await client.post(`/editor/${slug}/autopilot`, undefined, editorAdAutopilotKey(slug, args));
-  const status = normalizeStatus("editor", slug, asRecord(started).data);
-  return ok({ slug, kind: "editor", status, next: "wait_for_completion" });
+  const prepared = [];
+  let productImage;
+  let closingImage;
+  let logo;
+  try {
+    const langErr = validateLanguage(args.language);
+    if (langErr)
+      return fail(langErr);
+    const promptErr = validateProductPrompt(args.product_prompt);
+    if (promptErr)
+      return fail(promptErr);
+    if (args.cast_mode === "product_only" && !args.product_image_path) {
+      return fail("cast_mode product_only requires product_image_path so identity can be locked before generation.");
+    }
+    if ((args.logo_treatment !== undefined || args.logo_position !== undefined || args.logo_duration_seconds !== undefined) && !args.logo_path) {
+      return fail("logo_treatment/logo_position/logo_duration_seconds require logo_path (the logo image they style). Provide logo_path or drop these settings.");
+    }
+    if (args.product_description !== undefined && !args.product_image_path) {
+      return fail("product_description requires product_image_path (the product image it describes). Provide product_image_path or drop product_description.");
+    }
+    if (args.product_image_path) {
+      productImage = await prepareImageUpload(args.product_image_path, MAX_PRODUCT_IMAGE_BYTES);
+      prepared.push(productImage);
+    }
+    if (args.closing_image_path) {
+      closingImage = await prepareImageUpload(args.closing_image_path, MAX_CLOSING_IMAGE_BYTES);
+      prepared.push(closingImage);
+    }
+    if (args.logo_path) {
+      logo = await prepareImageUpload(args.logo_path, MAX_LOGO_BYTES);
+      prepared.push(logo);
+    }
+    const created = await client.post("/editor", {
+      language: args.language ?? "en",
+      product_prompt: args.product_prompt,
+      product_subject: args.product_subject,
+      project_intent: args.project_intent,
+      creative_format: args.creative_format,
+      visual_language: args.visual_language,
+      theme: args.theme,
+      voice_id: args.voice_id,
+      export_aspect_ratio: args.export_aspect_ratio,
+      cast_mode: args.cast_mode
+    }, editorAdCreateKey({
+      ...args,
+      product_image_identity: productImage ? preparedUploadIdentity(productImage) : undefined,
+      closing_image_identity: closingImage ? preparedUploadIdentity(closingImage) : undefined,
+      logo_identity: logo ? preparedUploadIdentity(logo) : undefined
+    }));
+    const slug = created.data.slug;
+    let configured = {};
+    if (args.product_image_path || args.closing_image_path || args.logo_path) {
+      const current = await client.get(`/editor/${slug}`);
+      configured = asRecord(asRecord(current).data);
+    }
+    if (productImage && !configured.product_url) {
+      const { s3_key } = await uploadImageFile(client, `/editor/${slug}/product/presign`, productImage, MAX_PRODUCT_IMAGE_BYTES);
+      await client.post(`/editor/${slug}/product/confirm`, {
+        s3_key,
+        product_description: args.product_description
+      });
+    }
+    if (closingImage && !configured.closing_image_url) {
+      const { s3_key } = await uploadImageFile(client, `/editor/${slug}/closing-image/presign`, closingImage, MAX_CLOSING_IMAGE_BYTES);
+      await client.post(`/editor/${slug}/closing-image/confirm`, {
+        s3_key
+      });
+    }
+    if (logo && !configured.logo_url) {
+      const { s3_key } = await uploadImageFile(client, `/editor/${slug}/logo/presign`, logo, MAX_LOGO_BYTES);
+      await client.post(`/editor/${slug}/logo/confirm`, { s3_key });
+    }
+    const logoSettings = {};
+    if (args.logo_treatment !== undefined)
+      logoSettings.logo_treatment = args.logo_treatment;
+    if (args.logo_position !== undefined)
+      logoSettings.logo_position = args.logo_position;
+    if (args.logo_duration_seconds !== undefined)
+      logoSettings.logo_duration_seconds = args.logo_duration_seconds;
+    if (args.logo_path && Object.keys(logoSettings).length > 0)
+      await client.patch(`/editor/${slug}/logo`, logoSettings);
+    const quote = await editorAutopilotQuote(client, slug);
+    const overCap = args.max_credits !== undefined && quote.estimated_credits !== null && quote.estimated_credits > args.max_credits;
+    if (args.max_credits === undefined || quote.estimated_credits === null || overCap || !quote.affordable) {
+      const note = args.max_credits === undefined ? `Free draft configured. Estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}); nothing charged. Relaunch with start_autopilot({ slug: "${slug}", max_credits: ${quote.estimated_credits ?? "<approved cap>"} }).` : quote.estimated_credits === null ? "Pricing is temporarily unavailable, so the paid pipeline was not started. Retry the quote later." : overCap ? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.` : `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`;
+      return ok({
+        slug,
+        kind: "editor",
+        ...quote,
+        charged: false,
+        note,
+        next: "start_autopilot"
+      });
+    }
+    const started = await client.post(`/editor/${slug}/autopilot`, { max_credits: args.max_credits }, editorAdAutopilotKey(slug, args));
+    const status = normalizeStatus("editor", slug, asRecord(started).data);
+    return ok({
+      slug,
+      kind: "editor",
+      status,
+      ...quote,
+      charged: true,
+      next: "wait_for_completion"
+    });
+  } finally {
+    await Promise.all(prepared.map(closePreparedUploadFile));
+  }
 }));
 registerTool("start_autopilot", {
   title: "Start autopilot on an existing editor draft",
-  description: "Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " + "EXISTING editor project/draft. Spends credits — preview the estimate first with the autopilot/cost endpoint " + "or make_video({ dry_run:true }). Each call is a genuine start attempt (like tapping Launch in the app): " + "if a run is already in progress for this slug the server returns already_running — it never double-starts " + "or double-charges. Once finished, failed, or cancelled, calling again relaunches it (resume after a top-up, raising your spend cap, or a mid-pipeline failure). Then poll with " + 'wait_for_completion({ slug, kind: "editor" }).',
+  description: "Starts server-orchestrated autopilot (scenario → segments → narration → voice → music → render) on an " + "EXISTING editor project/draft. Without max_credits it returns the live quote and charges nothing. Supply an " + "explicit max_credits cap to authorize launch; the tool refuses if pricing is unavailable, the estimate exceeds " + "the cap, or the balance is insufficient. Each authorized call is a genuine start attempt (like tapping Launch in the app): " + "if a run is already in progress for this slug the server returns already_running — it never double-starts " + "or double-charges. Failed or cancelled runs resume normally. For a completed project, set restart:true to quote and build a fresh creative run; omitting it only resumes pending edits. Then poll with " + 'wait_for_completion({ slug, kind: "editor" }).',
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     language: exports_external.enum(LANGUAGES).optional().describe('Optional language override applied before launch. Bare ISO-639-1 code only, e.g. "fr" — no ' + "region/script subtag. Drives scenario, narration, voice, and captions."),
     product_subject: exports_external.string().max(300).optional().describe("Optional locked product / main subject applied before launch so the AI cannot invent an " + "unrelated product."),
-    product_prompt: exports_external.string().optional().describe("Optional freeform brief to set/replace before launch.")
+    product_prompt: exports_external.string().optional().describe("Optional freeform brief to set/replace before launch."),
+    max_credits: exports_external.number().int().nonnegative().optional().describe("Explicit spend cap. Omit to quote only; no credits are charged."),
+    restart: exports_external.boolean().optional().describe("Set true only on a completed project to quote/build a fresh creative run. The delivered timeline stays available until replacement apply.")
   },
+  outputSchema: createEditorOutput,
   annotations: { title: "Start autopilot", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
   const langErr = validateLanguage(args.language);
@@ -32436,12 +32854,27 @@ registerTool("start_autopilot", {
     overrides.product_subject = args.product_subject;
   if (args.product_prompt !== undefined)
     overrides.product_prompt = args.product_prompt;
-  const started = await client.post(`/editor/${slug}/autopilot`, Object.keys(overrides).length > 0 ? overrides : undefined, idemKey("autopilot", slug, randomUUID()));
+  if (args.restart)
+    overrides.restart = true;
+  const quote = await editorAutopilotQuote(client, slug, overrides);
+  const overCap = args.max_credits !== undefined && quote.estimated_credits !== null && quote.estimated_credits > args.max_credits;
+  if (args.max_credits === undefined || quote.estimated_credits === null || overCap || !quote.affordable) {
+    return ok({
+      slug,
+      kind: "editor",
+      ...quote,
+      charged: false,
+      note: args.max_credits === undefined ? `Quote only: estimated ${quote.estimated_credits ?? "?"} credits (have ${quote.available_credits ?? "?"}). Pass max_credits to authorize launch.` : quote.estimated_credits === null ? "Pricing is unavailable; launch refused because the spend cap cannot be enforced." : overCap ? `Estimated ${quote.estimated_credits} credits exceeds max_credits ${args.max_credits}; nothing charged.` : `Not enough credits (needs ${quote.estimated_credits}, have ${quote.available_credits ?? "?"}); nothing charged.`
+    });
+  }
+  const started = await client.post(`/editor/${slug}/autopilot`, { ...overrides, max_credits: args.max_credits }, idemKey("autopilot", slug, randomUUID()));
   const status = normalizeStatus("editor", slug, asRecord(started).data);
   return ok({
     slug,
     kind: "editor",
     status,
+    ...quote,
+    charged: true,
     next: "wait_for_completion"
   });
 }));
@@ -32463,7 +32896,7 @@ registerTool("unlock_ai_assists", {
 }, tool(async (_args, client) => ok(await client.post("/ai-assists/unlock", undefined, await unlockKey(client)))));
 registerTool("create_editor_draft", {
   title: "Create an editor draft (no autopilot)",
-  description: "Creates an editor project from a product prompt and stops (NO autopilot). Costs 0 credits. Returns the " + "slug. Use this to drive the pipeline step by step (vs create_editor_ad which runs autopilot end to end). " + "Each AI-generated scene renders to a fixed 8 seconds (uploaded clips keep their own length). " + "product_prompt is optional content: send 10–5000 chars, or omit it entirely (empty is treated as omit).",
+  description: "Creates an editor project from a product prompt and stops (NO autopilot). Costs 0 credits. Returns the " + "slug. Use this to drive the pipeline step by step (vs create_editor_ad which configures, quotes, and can launch autopilot with a spend cap). " + "Each AI-generated scene renders to a fixed 8 seconds (uploaded clips keep their own length). " + "product_prompt is optional content: send 10–5000 chars, or omit it entirely (empty is treated as omit).",
   inputSchema: {
     product_prompt: exports_external.string().min(10).max(5000).optional().describe("Brief for the ad — 10–5000 chars, or omit entirely"),
     product_subject: exports_external.string().max(300).optional().describe("The concrete product / main subject the video must be about. Hard-grounds the AI so it cannot " + "invent an unrelated product. Recommended for ads."),
@@ -32703,7 +33136,10 @@ registerTool("regenerate_segment", {
   }
 }, tool(async (args, client) => {
   const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`, args.prompt !== undefined ? { prompt: args.prompt } : undefined, undefined);
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "scene_regeneration", 4)
+  });
 }));
 registerTool("generate_all_segments", {
   title: "Generate all pending segments (sequential)",
@@ -32820,7 +33256,10 @@ registerTool("generate_voice", {
   annotations: { title: "Generate voice", ...WRITE, idempotentHint: true }
 }, tool(async (args, client) => {
   const res = await client.post(`/editor/${args.slug}/generate-voice`, { voice_id: args.voice_id }, await voiceKey(client, args.slug, args.voice_id));
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "voice_generation", 3)
+  });
 }));
 registerTool("generate_music", {
   title: "Generate the background music (5 credits)",
@@ -32847,11 +33286,14 @@ registerTool("generate_music", {
   if (args.instruments !== undefined)
     body.instruments = args.instruments;
   const res = await client.post(`/editor/${args.slug}/generate-music`, body, undefined);
-  return ok(asRecord(res).data ?? res);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    charge_receipt: await editorChargeReceipt(client, args.slug, "music_generation", 5)
+  });
 }));
 registerTool("render", {
   title: "Render the final editor video (0 credits)",
-  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " + "segments are auto-charged at generation cost first). Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
+  description: "Renders the final MP4 from the generated segments + voice + music. Costs 0 credits (any still-ungenerated " + "segments are auto-charged at generation cost first). Render NEVER generates or charges for voice/music; a new " + "music charge comes only from generate_music or an already-running autopilot child job. Re-rendering reflects the current segments/voice/music (it does not replay a prior render). Returns the latest_render; " + 'pair with wait_for_completion({ slug, kind: "editor" }) then download_result. ' + "STALENESS: editing the scenario or narration AFTER generating voice/music marks those audio tracks stale, and render then 422s with editor_narration_stale / editor_voice_stale / editor_music_stale — regenerate the named track (generate_narration → generate_voice, and/or generate_music) before rendering.",
   inputSchema: { slug: exports_external.string().describe("Editor project slug") },
   annotations: { title: "Render", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
@@ -32965,7 +33407,7 @@ async function pollUploadToReady(client, slug, uploadId, extra, budgetMs, interv
 }
 registerTool("upload_video", {
   title: "Upload a local video clip into an editor project",
-  description: "Uploads a local video FILE (your own footage) into an editor project and, by default, adds it to the timeline " + "as a finished scene. Unlike an AI-generated scene (a fixed 8 seconds), an uploaded clip keeps its own native " + "duration. Runs presign → PUT (resumable multipart for large files) → confirm, then polls until the " + "upload is processed (ready). file_path is a LOCAL path confined to HUBFLUENCER_INPUT_DIR (or cwd). Accepted: " + VIDEO_EXTS.map((e) => `.${e}`).join(", ") + " (≤500 MB, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " + "placed — call add_segment_from_upload later.",
+  description: "Uploads a local video FILE (your own footage) into an editor project and, by default, adds it to the timeline " + "as a finished scene. Unlike an AI-generated scene (a fixed 8 seconds), an uploaded clip keeps its own native " + "duration. Runs presign → PUT (resumable multipart for large files) → confirm, then polls until the " + "upload is processed (ready). file_path is a LOCAL path confined to HUBFLUENCER_INPUT_DIR (or cwd). Accepted: " + VIDEO_EXTS.map((e) => `.${e}`).join(", ") + " (≤500 MB decimal = 500,000,000 bytes, ≤5 min). Costs 0 credits. If add_to_timeline is false (default true) the clip is uploaded but not " + "placed — call add_segment_from_upload later.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().describe("Local video file path (inside HUBFLUENCER_INPUT_DIR or cwd)"),
@@ -33038,7 +33480,7 @@ registerTool("add_segment_from_upload", {
 }));
 registerTool("use_asset_for_segment", {
   title: "Reuse a clip/asset for a specific scene (0 credits)",
-  description: "Sets a specific scene's video from an existing asset — either a ready upload (upload_id) OR a completed scene " + "in the same project (source_segment_id). Provide EXACTLY ONE. 0 credits. Use it to reuse one uploaded clip " + "across scenes, or to swap a generated scene for your own footage.",
+  description: "Sets a specific scene's video from an existing asset — either a ready upload (upload_id) OR a completed scene " + "in the same project (source_segment_id). Provide EXACTLY ONE. 0 credits. Use it to reuse one uploaded clip " + "across scenes, or to swap a generated scene for your own footage. The response includes continuity impact and " + "current narration/voice/music staleness. If the replacement duration differs, regenerate stale audio before render.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     segment_id: exports_external.union([exports_external.number(), exports_external.string()]).describe("Target scene id (from get_editor)"),
@@ -33058,11 +33500,40 @@ registerTool("use_asset_for_segment", {
   }
   const body = hasUpload ? { upload_id: args.upload_id } : { source_segment_id: args.source_segment_id };
   const res = await client.post(`/editor/${args.slug}/segments/${String(args.segment_id)}/use-asset`, body);
-  return ok(asRecord(res).data ?? res);
+  const segment = asRecord(asRecord(res).data ?? res);
+  const impact = asRecord(segment.impact);
+  const staleSegmentIds = Array.isArray(impact.stale_video_segment_ids) ? impact.stale_video_segment_ids : [];
+  const requiresRegeneration = impact.requires_regeneration === true || staleSegmentIds.length > 0;
+  let timeline;
+  try {
+    const current = await client.get(`/editor/${args.slug}`);
+    const editor = asRecord(asRecord(current).data);
+    timeline = {
+      narration_stale: editor.narration_stale === true,
+      voice_stale: editor.voice_stale === true,
+      music_stale: editor.music_stale === true,
+      stale_segment_ids: staleSegmentIds,
+      requires_regeneration: requiresRegeneration
+    };
+  } catch {
+    timeline = {
+      narration_stale: null,
+      voice_stale: null,
+      music_stale: null,
+      stale_segment_ids: staleSegmentIds,
+      requires_regeneration: requiresRegeneration,
+      enrichment_unavailable: true
+    };
+  }
+  return ok({
+    ...segment,
+    timeline,
+    next: timeline.requires_regeneration || timeline.narration_stale || timeline.voice_stale || timeline.music_stale ? "Regenerate the reported stale scenes/audio before render." : timeline.enrichment_unavailable ? "Scene swap succeeded, but audio staleness could not be verified (enrichment fetch failed) — call get_status before render to confirm." : "Timeline is current and can be rendered."
+  });
 }));
 registerTool("set_product", {
   title: "Attach a product image (from a local file)",
-  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " + "defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " + "description (≤500 chars) guides how it's woven into scenes.",
+  description: "Uploads a local product image and attaches it to the project as the product. Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. The FIRST product added " + "defaults every pending AI scene to feature it 'throughout' (change with set_product_placement). Optional " + "description (≤500 chars) guides how it's woven into scenes.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().describe("Local product image path (.jpg/.jpeg/.png)"),
@@ -33070,7 +33541,7 @@ registerTool("set_product", {
   },
   annotations: { title: "Set product", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
-  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/product/presign`, args.file_path);
+  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/product/presign`, args.file_path, MAX_PRODUCT_IMAGE_BYTES);
   const res = await client.post(`/editor/${args.slug}/product/confirm`, { s3_key, product_description: args.description });
   return ok(asRecord(res).data ?? res);
 }));
@@ -33092,7 +33563,7 @@ registerTool("set_product_placement", {
 }));
 registerTool("set_closing_image", {
   title: "Set the closing-card image (0 credits)",
-  description: "Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MB, confined " + "to HUBFLUENCER_INPUT_DIR/cwd) OR reuse the project's product image (from_product:true — a 0-credit server-side " + "copy, no upload). If a closing image already exists, pass overwrite:true to replace it (else " + "editor_closing_image_exists).",
+  description: "Sets the optional ~2s end-card image. Either upload a local file (file_path; .jpg/.jpeg/.png ≤20 MiB, confined " + "to HUBFLUENCER_INPUT_DIR/cwd) OR reuse the project's product image (from_product:true — a 0-credit server-side " + "copy, no upload). If a closing image already exists, pass overwrite:true to replace it (else " + "editor_closing_image_exists).",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().optional().describe("Local image to upload as the end card"),
@@ -33112,13 +33583,13 @@ registerTool("set_closing_image", {
   if (!args.file_path) {
     return fail("Provide file_path (a local image) or from_product:true.");
   }
-  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/closing-image/presign`, args.file_path);
+  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/closing-image/presign`, args.file_path, MAX_CLOSING_IMAGE_BYTES);
   const res = await client.post(`/editor/${args.slug}/closing-image/confirm`, { s3_key });
   return ok(asRecord(res).data ?? res);
 }));
 registerTool("set_logo", {
   title: "Set a brand logo overlay (0 credits)",
-  description: "Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤20 MB; PNG keeps " + "transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " + "position, duration_seconds.",
+  description: "Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤1 MiB; PNG keeps " + "transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " + "position, duration_seconds.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     file_path: exports_external.string().describe("Local logo image (.png/.jpg/.jpeg)"),
@@ -33128,7 +33599,7 @@ registerTool("set_logo", {
   },
   annotations: { title: "Set logo", ...WRITE, idempotentHint: false }
 }, tool(async (args, client) => {
-  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/logo/presign`, args.file_path);
+  const { s3_key } = await uploadImageFile(client, `/editor/${args.slug}/logo/presign`, args.file_path, MAX_LOGO_BYTES);
   const confirmed = await client.post(`/editor/${args.slug}/logo/confirm`, { s3_key });
   let result = asRecord(confirmed).data ?? confirmed;
   const settings = {};
@@ -33146,7 +33617,7 @@ registerTool("set_logo", {
 }));
 registerTool("set_short_product", {
   title: "Attach a product image to a short (0 credits)",
-  description: "Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " + "Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " + "(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " + "(This is the shorts equivalent of set_product for editor projects.)",
+  description: "Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " + "Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MiB = 20,971,520 bytes), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " + "(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " + "(This is the shorts equivalent of set_product for editor projects.)",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)"),
     file_path: exports_external.string().describe("Local product image path (.jpg/.jpeg/.png)"),
@@ -33164,7 +33635,7 @@ registerTool("set_short_product", {
 }));
 registerTool("set_short_poster", {
   title: "Set a short's end-card poster image (0 credits)",
-  description: "Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " + "render from 12s to 14s). Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " + "again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+  description: "Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " + "render from 12s to 14s). Accepted: " + IMAGE_EXTS.map((e) => `.${e}`).join(", ") + " (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " + "again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
   inputSchema: {
     slug: exports_external.string().describe("Short slug (from create_short)"),
     file_path: exports_external.string().describe("Local poster image (.jpg/.jpeg/.png)"),
@@ -33191,7 +33662,7 @@ registerTool("get_status", {
 }));
 registerTool("wait_for_completion", {
   title: "Wait for a render to finish",
-  description: "Polls status (emitting progress) until terminal (ready/failed) or the wait budget is exhausted. " + "Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " + "Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render). " + 'Works for kind:"slider" too, but a carousel has no MP4 — it just goes terminal when composited; read the slide ' + "images with get_slider (save_path is ignored for sliders).",
+  description: "Polls status (emitting progress) until terminal or the wait budget is exhausted. " + "Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " + "terminal=true does NOT always mean ready=true: an editor can go terminal in a needs-action stage " + '(stage "editing_required" — a delivered render is stale after edits, regenerate the reported scenes/audio; ' + 'stage "insufficient_credits" — a batch is parked, top up or reduce scope; ' + 'stage "idle" — a draft with nothing generating, start generation first) that only a further tool call ' + "can advance — do NOT just re-poll those. " + "Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render). " + 'Works for kind:"slider" too, but a carousel has no MP4 — it just goes terminal when composited; read the slide ' + "images with get_slider (save_path is ignored for sliders).",
   inputSchema: {
     slug: exports_external.string(),
     kind: kindSchema,
@@ -33766,7 +34237,7 @@ registerTool("materialize_episode", {
   const episode = summarizeEpisode(asRecord(res).data);
   return ok({
     ...episode,
-    next: episode.draft_slug ? "Generate this draft EXPLICITLY (a separate, PAID step): editor_ad/short → start_autopilot({ slug }); carousel → generate_slider({ slug })." : "Draft created — review it with list_series_episodes."
+    next: episode.draft_slug ? "Price this draft with start_autopilot({ slug }); after approval launch it with start_autopilot({ slug, max_credits: approved_cap }). Carousel generation remains a separate paid generate_slider call." : "Draft created — review it with list_series_episodes."
   });
 }));
 registerTool("get_series_dashboard", {
@@ -34116,7 +34587,7 @@ registerTool("get_asset_quota", {
 }));
 registerTool("upload_asset", {
   title: "Upload a local file to your reusable asset catalog",
-  description: "Uploads a local IMAGE or VIDEO into your reusable asset catalog so it can be reused across projects. " + `Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB, videos ≤500 MB. ` + "Runs presign → PUT → confirm; the confirm HEADs the object and validates size/type, so a mismatch 422s. " + "For a VIDEO you MUST pass duration_seconds (≤60; the server rejects a video with no/over-long duration). " + "Spends 0 credits. Scope: video:generate. Rate limit: 30/min. Requires an ACTIVE SUBSCRIPTION (402 " + "subscription_required otherwise). The local path is confined to HUBFLUENCER_INPUT_DIR (default: cwd). " + "Returns the confirmed asset id + media type + status.",
+  description: "Uploads a local IMAGE or VIDEO into your reusable asset catalog so it can be reused across projects. " + `Allowed types: ${CATALOG_ASSET_EXTS.map((e) => `.${e}`).join(", ")} — images ≤20 MiB (20,971,520 bytes), videos ≤500 MB decimal (500,000,000 bytes). ` + "Runs presign → PUT → confirm; the confirm HEADs the object and validates size/type, so a mismatch 422s. " + "For a VIDEO you MUST pass duration_seconds (≤60; the server rejects a video with no/over-long duration). " + "Spends 0 credits. Scope: video:generate. Rate limit: 30/min. Requires an ACTIVE SUBSCRIPTION (402 " + "subscription_required otherwise). The local path is confined to HUBFLUENCER_INPUT_DIR (default: cwd). " + "Returns the confirmed asset id + media type + status.",
   inputSchema: {
     file_path: exports_external.string().describe("Path to a local image/video, inside HUBFLUENCER_INPUT_DIR (default: cwd)"),
     description: exports_external.string().optional().describe("Optional description stored with the asset"),