@hubfluencer/mcp 0.10.0 → 0.11.0

package/README.md

@@ -68,7 +68,7 @@ claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hub
 
 ## Tools
 
-93 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+95 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
 below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
 instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
 → +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
@@ -86,6 +86,8 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
 | `create_editor_ad` | Create an editor project, attach optional local product/logo/closing assets, and return the live autopilot quote. Omit `max_credits` to stop free; provide an approved cap to launch. For a mascot/hero product that must remain identical with no humans, pass `cast_mode:"product_only"` plus `product_image_path`. | **0** until capped launch |
 | `start_autopilot` | Quote autopilot on an **existing** editor draft when called with only `slug`; launch only with an explicit `max_credits` that covers the estimate and an adequate balance. On a completed project, pass `restart:true` to quote and build a fresh creative run; omit it to resume pending edits. | **0** quote; credits on capped launch |
+| `retry_editor_batch` | Recover `batch_retry_required` by atomically re-queueing the failed scene and resuming its prepaid batch. If the parent Autopilot run is terminal, quote/relaunch it separately afterward. | **0 additional** |
+| `cancel_editor_batch` | Cancel an awaiting/running/paused editor batch. Destructive after scene dispatch: prepaid credits are not refunded (an awaiting-preview batch is refunded server-side). | **0 additional** |
 | `create_slider` | Create an image-carousel draft: one prompt → N still slides + a ready-to-post caption + hashtags. `mode` `creative` (story) or `ad_driven` (facts). | **0** |
 | `generate_slider` | Render a carousel (copy → AI backgrounds → composite). Poll `get_slider` until `completed`. | **1 / slide** (3–10) |
 | `get_slider` | Read a carousel's status and, when completed, the per-slide image URLs + caption + hashtags. | **0** |
@@ -98,7 +100,7 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | Tool | What it does | Cost |
 |---|---|---|
 | `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme` / `cast_mode` (`product_only` needs `set_product` before generation; `presenter_led` needs a configured presenter). | **0** |
-| `get_editor` | Full project state (scenario, segments, narration, music, latest render, quota) — the review step. | **0** |
+| `get_editor` | Full project state by default for compatibility; pass `response_format:"concise"` for a smaller review projection. | **0** |
 | `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
 | `apply_scenario` | Compile the **ready** scenario into per-scene prompts on the timeline (`segments_count` 0 or 3..10; omitted uses the generated scenario count, then 5; AI scenes replaced, uploads preserved). Polls until applied (~2 min budget). | **0** |
 | `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
@@ -120,7 +122,7 @@ Reads are confined to `HUBFLUENCER_INPUT_DIR`. All $0.
 
 Size units are exact: videos are capped at **500 MB decimal (500,000,000 bytes)**; product
 images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
-(20,971,520 bytes)**; logos at **1 MiB (1,048,576 bytes)**. Editor video multipart starts at
+(20,971,520 bytes)**; logos at **5 MiB (5,242,880 bytes)**. Editor video multipart starts at
 **50 MiB (52,428,800 bytes)**.
 
 | Tool | What it does |
@@ -131,7 +133,7 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `set_product` | Upload an editor product image (JPEG/PNG, ≤8 MiB) and attach it as the project product. |
 | `set_product_placement` | Set where the product appears on pending AI scenes: `throughout` or `end`. |
 | `set_closing_image` | Set the ~2s end-card image (JPEG/PNG, ≤20 MiB; upload a file, or reuse the product image with `from_product:true`). |
-| `set_logo` | Upload a brand logo overlay (JPEG/PNG, ≤1 MiB; editor only; optional treatment/position/duration). |
+| `set_logo` | Upload a brand logo overlay (JPEG/PNG, ≤5 MiB; editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image (JPEG/PNG, ≤20 MiB) to a **short**. |
 | `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its corner and `throughout`/`end_card`/`none` (hide) treatment. The logo is never sent to the video model. |
 | `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
@@ -251,14 +253,18 @@ edit are **0 credits** — you only pay to generate/render.
 
 **One shot (recommended):**
 `make_video({ prompt: "an ad for…", save_path: "ad.mp4" })` → returns `{ ready, video_url, saved_to, estimated_credits, available_credits }`.
-It prices the job and only charges if it's affordable (and within `max_credits` if you set one); otherwise it returns
-`charged:false` with the estimate and a free draft slug. Preview first with `make_video({ prompt, dry_run:true })`.
+It prices the job and only launches if it's affordable (and within `max_credits` if you set one); otherwise it returns
+`charged:false` with the estimate and a free draft slug. Shorts charge at launch. Editors return the authorized cap and
+observed incremental spend (`authorized_credits`, `credits_spent`) instead of treating authorization as a charge.
+Preview first with `make_video({ prompt, dry_run:true })`.
 If it returns `terminal:false`, the render is still going — call `wait_for_completion` with the returned slug.
 
 **Granular (control/recovery):**
 `create_short` → optional `generate_hook_variations` (test hook angles free) / `generate_short_text` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
 `create_editor_ad` (free configure + quote) → obtain spend approval → `start_autopilot {slug, max_credits}` → `wait_for_completion {kind:"editor"}` → `download_result`.
 
+If waiting returns `stage:"batch_retry_required"`, call `retry_editor_batch` to continue the prepaid failed scene, or `cancel_editor_batch` to abandon the batch. Resolve that child batch before calling `start_autopilot` again; a retry does not itself authorize a new parent Autopilot run.
+
 **Iterate a short for free (never re-roll):** the first `generate_short` (15 credits) buys the footage +
 music; after that, every text/style/CTA/end-card/logo tweak re-renders over them for **0 credits** —
 `update_short` (new hook/CTA/style) → `rerender_short` → compare → repeat → keep the winner. Logo

package/dist/index.js

@@ -29554,7 +29554,8 @@ function normalizeStatus(kind, slug, data) {
   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 batchActive = batchStatus === "running" || batchStatus === "preparing" || batchStatus === "awaiting_previews";
+  const batchRetryRequired = batchStatus === "paused_for_retry";
   const batchInsufficientCredits = batchStatus === "paused_insufficient_credits";
   const batchFailed = batchStatus === "failed";
   const autopilotActive = [
@@ -29598,33 +29599,42 @@ function normalizeStatus(kind, slug, data) {
     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 childWorkActive = batchActive || renderActive || scenarioActive || narrationActive || audioActive || activeSegments.length > 0;
+  const autopilotStartedAt = typeof d.autopilot_started_at === "string" ? Date.parse(d.autopilot_started_at) : Number.NaN;
+  const now = Date.now();
+  const autopilotResumeGraceActive = autopilotActive && Number.isFinite(autopilotStartedAt) && autopilotStartedAt <= now && now - autopilotStartedAt <= 120000;
+  const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
+  const batchRecoveryActive = autopilotFailed && batchActive;
+  const childFailureActionable = !batchRecoveryActive && (!autopilotActive || !childWorkActive && !autopilotResumeGraceActive);
+  const workActive = autopilotActive || childWorkActive;
   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;
+  const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
+  const renderFailed = renderStatus === "failed" && childFailureActionable;
+  const failed = parentFailureActionable && !deliveredArtifactSupersedesOrchestrationFailure || renderFailed || childFailureActionable && scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure || childFailureActionable && scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure || childFailureActionable && narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure || childFailureActionable && batchFailed && !deliveredArtifactSupersedesOrchestrationFailure || childFailureActionable && failedSegments.length > 0 || childFailureActionable && audioFailed;
+  const terminal = ready || failed || batchRetryRequired || batchInsufficientCredits || !workActive;
   let stage = autopilot;
   if (ready)
     stage = "completed";
-  else if (autopilot === "failed")
+  else if (batchRetryRequired)
+    stage = "batch_retry_required";
+  else if (parentFailureActionable && autopilot === "failed")
     stage = "failed";
-  else if (autopilot === "cancelled")
+  else if (parentFailureActionable && autopilot === "cancelled")
     stage = "cancelled";
   else if (renderFailed)
     stage = "render_failed";
-  else if (scenarioApplyFailed)
+  else if (childFailureActionable && scenarioApplyFailed)
     stage = "scenario_apply_failed";
-  else if (scenarioFailed)
+  else if (childFailureActionable && scenarioFailed)
     stage = "scenario_failed";
-  else if (narrationFailed)
+  else if (childFailureActionable && narrationFailed)
     stage = "narration_failed";
-  else if (batchFailed)
+  else if (childFailureActionable && batchFailed)
     stage = "batch_failed";
-  else if (failedSegments.length > 0)
+  else if (childFailureActionable && failedSegments.length > 0)
     stage = "segment_failed";
-  else if (audioFailed)
+  else if (childFailureActionable && audioFailed)
     stage = "audio_failed";
   else if (batchInsufficientCredits)
     stage = "insufficient_credits";
@@ -29643,6 +29653,7 @@ function normalizeStatus(kind, slug, data) {
   else if (!workActive && stale)
     stage = "editing_required";
   const segmentError = failedSegments.map((segment) => segment.error_message).find((value) => typeof value === "string" && value.length > 0);
+  const actionableChildError = childFailureActionable ? latest.error_message ?? d.scenario_apply_error_message ?? d.scenario_error_message ?? d.narration_error_message ?? d.batch_generation_error_message ?? segmentError ?? audioError : null;
   return {
     kind,
     slug,
@@ -29650,7 +29661,7 @@ function normalizeStatus(kind, slug, data) {
     terminal,
     ready,
     video_url: videoUrl,
-    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),
+    error: ready ? null : batchRetryRequired ? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing." : (parentFailureActionable ? d.autopilot_error_message : null) ?? actionableChildError ?? (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")
@@ -30243,7 +30254,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.10.0",
+  version: "0.11.0",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -30646,6 +30657,9 @@ var createEditorOutput = exports_external.object({
   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(),
+  launched: exports_external.boolean().optional(),
+  authorized_credits: exports_external.number().optional(),
+  credits_spent: exports_external.number().optional(),
   charged: exports_external.boolean().optional(),
   note: exports_external.string().optional(),
   next: exports_external.string().optional()
@@ -30662,6 +30676,9 @@ var makeVideoOutput = exports_external.object({
   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(),
+  launched: exports_external.boolean().optional(),
+  authorized_credits: exports_external.number().optional(),
+  credits_spent: exports_external.number().optional(),
   charged: exports_external.boolean().optional(),
   saved_to: exports_external.union([exports_external.string(), exports_external.null()]).optional(),
   timed_out: exports_external.boolean().optional(),
@@ -31122,7 +31139,7 @@ var ALLOW_LOOPBACK_FETCH = /^http:\/\/(localhost|127\.0\.0\.1|\[?::1\]?)/.test(p
 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_LOGO_BYTES = 5 * 1024 * 1024;
 var MAX_SHORT_LOGO_BYTES = 5 * 1024 * 1024;
 var MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 var MULTIPART_THRESHOLD = 50 * 1024 * 1024;
@@ -31821,7 +31838,7 @@ CREDITS (spent server-side; each tool prices before charging — see its descrip
 - 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. 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.
+- 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; batch_retry_required = call retry_editor_batch or cancel_editor_batch before starting Autopilot again; 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)
@@ -31841,8 +31858,7 @@ async function pollToTerminal(client, kind, slug, extra, budgetMs, intervalMs) {
   }
   return status;
 }
-async function pollSegmentToTerminal(client, slug, segmentId, extra, budgetMs, intervalMs) {
-  const deadline = Date.now() + budgetMs;
+async function pollSegmentToTerminal(client, slug, segmentId, extra, deadline, intervalMs) {
   const sid = String(segmentId);
   const read = async () => {
     const res = await client.get(`/editor/${slug}`, undefined, deadline);
@@ -31991,6 +32007,7 @@ registerTool("make_video", {
   const costPath = kind === "short" ? `/shorts/${slug}/cost` : `/editor/${slug}/autopilot/cost`;
   let estimated_credits = null;
   let available_credits = null;
+  let authorizedCredits;
   try {
     const cost = asRecord(asRecord(await client.get(costPath)).data);
     estimated_credits = typeof cost.total === "number" ? cost.total : null;
@@ -32025,6 +32042,7 @@ registerTool("make_video", {
     if (approvedCap === null) {
       throw new Error("Editor autopilot launch requires max_credits or a live quote");
     }
+    authorizedCredits = approvedCap;
     await client.post(`/editor/${slug}/autopilot`, { max_credits: approvedCap }, makeVideoAutopilotKey(slug, args, startState));
   }
   await reportProgress(extra, 0, `started ${kind} ${slug}`);
@@ -32033,12 +32051,29 @@ registerTool("make_video", {
   if (status.ready && status.video_url && args.save_path) {
     saved_to = (await downloadTo(status.video_url, args.save_path)).saved_to;
   }
+  let editorCreditsSpent;
+  if (kind === "editor") {
+    try {
+      const current = asRecord(asRecord(await client.get(`/editor/${slug}`, undefined, Date.now() + 5000)).data);
+      if (typeof current.autopilot_credits_spent === "number") {
+        editorCreditsSpent = current.autopilot_credits_spent;
+      }
+    } catch {}
+  }
+  const billing = kind === "short" ? { charged: true } : {
+    launched: true,
+    authorized_credits: authorizedCredits,
+    ...editorCreditsSpent === undefined ? {} : {
+      credits_spent: editorCreditsSpent,
+      charged: editorCreditsSpent > 0
+    }
+  };
   const result = {
     ...status,
     kind_inferred: requestedKind === undefined,
     estimated_credits,
     available_credits,
-    charged: true,
+    ...billing,
     saved_to,
     timed_out: !status.terminal
   };
@@ -32046,7 +32081,7 @@ registerTool("make_video", {
   const links = status.ready && status.video_url ? [mp4Link(status.video_url, slug)] : [];
   return ok({
     ...result,
-    note: status.ready ? "Done. Presigned ~24h URL — download promptly." : status.terminal ? `Terminal (${status.stage}). ${status.error ?? ""}`.trim() + ` To restart, fix the cause (often credits) then re-run make_video, or resume with ${resume}.` : `Still rendering — call wait_for_completion(${resumeArgs}).`
+    note: status.ready ? "Done. Presigned ~24h URL — download promptly." : status.terminal ? status.stage === "batch_retry_required" ? `Terminal (${status.stage}). ${status.error ?? ""} Resolve the paused batch before restarting Autopilot.`.trim() : `Terminal (${status.stage}). ${status.error ?? ""}`.trim() + ` To restart, fix the cause (often credits) then re-run make_video, or resume with ${resume}.` : `Still rendering — call wait_for_completion(${resumeArgs}).`
   }, links);
 }));
 registerTool("get_credits", {
@@ -32735,7 +32770,7 @@ registerTool("create_editor_ad", {
     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_path: exports_external.string().optional().describe("Local logo (.jpg/.jpeg/.png, ≤5 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."),
@@ -32846,7 +32881,10 @@ registerTool("create_editor_ad", {
       kind: "editor",
       status,
       ...quote,
-      charged: true,
+      launched: true,
+      authorized_credits: args.max_credits,
+      credits_spent: 0,
+      charged: false,
       next: "wait_for_completion"
     });
   } finally {
@@ -32855,7 +32893,7 @@ registerTool("create_editor_ad", {
 }));
 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. 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" }).',
+  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, except when status is batch_retry_required: " + "call retry_editor_batch (then wait for that prepaid batch) or cancel_editor_batch first. 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."),
@@ -32901,10 +32939,52 @@ registerTool("start_autopilot", {
     kind: "editor",
     status,
     ...quote,
-    charged: true,
+    launched: true,
+    authorized_credits: args.max_credits,
+    credits_spent: 0,
+    charged: false,
     next: "wait_for_completion"
   });
 }));
+registerTool("retry_editor_batch", {
+  title: "Retry a paused editor batch",
+  description: "Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " + "scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " + "paid. It does not authorize or restart a failed parent Autopilot run; after retrying, wait for the batch " + "to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " + "relaunch only with an approved cap. A batch parked on " + "insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
+  inputSchema: { slug: exports_external.string().describe("Editor project slug") },
+  annotations: {
+    title: "Retry editor batch",
+    ...WRITE,
+    idempotentHint: false
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/video-factories/${args.slug}/retry-batch-segment`);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    slug: args.slug,
+    charged: false,
+    note: "The failed scene retry is queued and the prepaid batch is running. Wait for it to settle; if the parent Autopilot run is then terminal, quote start_autopilot again and relaunch only with an approved max_credits cap.",
+    next: "wait_for_completion"
+  });
+}));
+registerTool("cancel_editor_batch", {
+  title: "Cancel an editor batch",
+  description: "Cancels an editor batch in awaiting_previews, running, or paused_for_retry so the project can be edited or " + "Autopilot can be started again. Cancellation is destructive: dispatched scene work is stopped and its prepaid " + "credits are not refunded; only an awaiting_previews batch (before dispatch) is refunded by the server. Spends " + "0 additional credits. Scope: video:generate.",
+  inputSchema: { slug: exports_external.string().describe("Editor project slug") },
+  annotations: {
+    title: "Cancel editor batch",
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    idempotentHint: false
+  }
+}, tool(async (args, client) => {
+  const res = await client.post(`/video-factories/${args.slug}/cancel-batch`);
+  return ok({
+    ...asRecord(asRecord(res).data ?? res),
+    slug: args.slug,
+    charged: false,
+    next: "get_status"
+  });
+}));
 registerTool("get_ai_assists", {
   title: "Get AI assist quota",
   description: "Returns the free daily AI-assist quota {used, limit, bonus, remaining, resets_at, unlock_cost, " + "unlock_batch_size}. AI assists power helper calls (generate_scenario, generate_narration, " + "enhance_prompt, suggest_next_scene, suggest_music_prompt). Default limit is 20/day. When remaining " + "hits 0 those helpers return 429 — either unlock_ai_assists (1 credit → +10) or write the content " + "yourself with set_scenario / set_narration_script / set_segment_prompt (those are free, no quota).",
@@ -32964,14 +33044,67 @@ registerTool("create_editor_draft", {
     next: "generate_scenario | set_scenario, then get_editor to review, then apply_scenario"
   });
 }));
+function conciseEditorState(value) {
+  const data = asRecord(value);
+  const keys = [
+    "slug",
+    "status",
+    "autopilot_status",
+    "autopilot_current_step",
+    "autopilot_error_step",
+    "autopilot_error_code",
+    "autopilot_error_message",
+    "autopilot_max_credits",
+    "autopilot_credits_spent",
+    "scenario_status",
+    "scenario_apply_status",
+    "scenario_prompt",
+    "batch_generation_status",
+    "narration_status",
+    "narration_script",
+    "narration_stale",
+    "voice_stale",
+    "music_stale",
+    "segments_count",
+    "current_audio",
+    "current_music",
+    "latest_render",
+    "project_spend",
+    "ai_assist_quota"
+  ];
+  const result = {};
+  for (const key of keys) {
+    if (key in data)
+      result[key] = data[key];
+  }
+  result.segments = Array.isArray(data.segments) ? data.segments.map((segment) => ({
+    id: segment.id,
+    position: segment.position,
+    prompt: segment.prompt,
+    status: segment.status,
+    source_type: segment.source_type,
+    use_previous_frame: segment.use_previous_frame,
+    protagonist_presence: segment.protagonist_presence,
+    cast_mode_snapshot: segment.cast_mode_snapshot,
+    video_stale: segment.video_stale,
+    error_code: segment.error_code,
+    error_message: segment.error_message,
+    narration_text: segment.narration_text
+  })) : [];
+  return result;
+}
 registerTool("get_editor", {
-  title: "Get full editor state (review step)",
-  description: "Returns the full editor project state: scenario_prompt, segments[] (with prompts + status), " + "narration_script/status, music, latest_render, segments_count, ai_assist_quota. This is the REVIEW " + "step — call it after generating the scenario/segments to inspect and decide what to edit.",
-  inputSchema: { slug: exports_external.string().describe("Editor project slug") },
+  title: "Get editor state (review step)",
+  description: "Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration, audio, render, spend, and quota.",
+  inputSchema: {
+    slug: exports_external.string().describe("Editor project slug"),
+    response_format: exports_external.enum(["concise", "full"]).default("full")
+  },
   annotations: { title: "Get editor", ...RO }
 }, tool(async (args, client) => {
   const res = await client.get(`/editor/${args.slug}`);
-  return ok(asRecord(res).data);
+  const data = asRecord(res).data;
+  return ok(args.response_format === "full" ? data : conciseEditorState(data));
 }));
 registerTool("set_scenario", {
   title: "Set the editor scenario",
@@ -33178,23 +33311,25 @@ registerTool("generate_all_segments", {
     idempotentHint: false
   }
 }, tool(async (args, client, extra) => {
-  const res = await client.get(`/editor/${args.slug}`);
+  const overallDeadline = Date.now() + 280000;
+  const res = await client.get(`/editor/${args.slug}`, undefined, overallDeadline);
   const data = asRecord(asRecord(res).data);
   const segments = Array.isArray(data.segments) ? data.segments : [];
-  const pending = segments.filter((s) => {
+  const unfinished = segments.filter((s) => {
+    if (s.source_type === "upload")
+      return false;
     const st = s.status ?? s.generation_status;
-    return st === undefined || st === "pending" || st === "draft" || st === "failed";
-  });
-  const overallDeadline = Date.now() + 280000;
-  const PER_SEGMENT_MAX_MS = 6 * 60 * 1000;
+    return st !== "completed";
+  }).sort((a, b) => Number(a.position ?? Number.MAX_SAFE_INTEGER) - Number(b.position ?? Number.MAX_SAFE_INTEGER));
+  const SUBMIT_HEADROOM_MS = 61000;
   const generated = [];
   let n = 0;
-  for (const seg of pending) {
+  for (const seg of unfinished) {
     const id = seg.id;
     if (id === undefined)
       continue;
     const sid = id;
-    const remainingMs = overallDeadline - Date.now();
+    let remainingMs = overallDeadline - Date.now();
     if (remainingMs <= 0) {
       return ok({
         slug: args.slug,
@@ -33203,19 +33338,41 @@ registerTool("generate_all_segments", {
         note: "Wall-clock budget reached — stopped before the next scene. Re-run generate_all_segments to continue (it retries failed/pending scenes and skips completed ones)."
       });
     }
-    await reportProgress(extra, ++n, `generating segment ${String(sid)} (${n}/${pending.length})`, pending.length);
-    try {
-      await client.post(`/editor/${args.slug}/segments/${String(sid)}/generate`, undefined, undefined);
-    } catch (e) {
+    await reportProgress(extra, ++n, `generating segment ${String(sid)} (${n}/${unfinished.length})`, unfinished.length);
+    const initialStatus = seg.status ?? seg.generation_status;
+    if (initialStatus !== "processing") {
+      remainingMs = overallDeadline - Date.now();
+      if (remainingMs < SUBMIT_HEADROOM_MS) {
+        return ok({
+          slug: args.slug,
+          generated,
+          timed_out: true,
+          note: "Wall-clock budget is too low to safely start another paid scene. Re-run generate_all_segments to continue; completed scenes are skipped."
+        });
+      }
+      try {
+        await client.post(`/editor/${args.slug}/segments/${String(sid)}/generate`, undefined, undefined);
+      } catch (e) {
+        return ok({
+          slug: args.slug,
+          generated,
+          stopped_at: sid,
+          error: errMessage(e),
+          note: "Stopped on first error — fix the cause (often credits) and re-run; completed scenes are skipped, failed/pending are retried."
+        });
+      }
+    }
+    remainingMs = overallDeadline - Date.now();
+    if (remainingMs <= 0) {
       return ok({
         slug: args.slug,
         generated,
         stopped_at: sid,
-        error: errMessage(e),
-        note: "Stopped on first error — fix the cause (often credits) and re-run; completed scenes are skipped, failed/pending are retried."
+        timed_out: true,
+        note: "The scene was submitted, but the wall-clock budget ended before its status could be checked. Re-run generate_all_segments later to continue safely."
       });
     }
-    const seg_result = await pollSegmentToTerminal(client, args.slug, sid, extra, Math.min(PER_SEGMENT_MAX_MS, remainingMs), 15000);
+    const seg_result = await pollSegmentToTerminal(client, args.slug, sid, extra, overallDeadline, 15000);
     if (seg_result.status === "failed") {
       return ok({
         slug: args.slug,
@@ -33234,7 +33391,34 @@ registerTool("generate_all_segments", {
         note: "A scene is still rendering after the poll budget. Re-run generate_all_segments later to continue (it retries failed/pending, skips completed), or watch it with get_editor."
       });
     }
-    generated.push(sid);
+    if (initialStatus !== "processing")
+      generated.push(sid);
+  }
+  if (overallDeadline - Date.now() < 1000) {
+    return ok({
+      slug: args.slug,
+      generated,
+      timed_out: true,
+      note: "Wall-clock budget reached before the final reconciliation read. Re-run generate_all_segments to confirm completion; completed scenes are skipped."
+    });
+  }
+  const finalRes = await client.get(`/editor/${args.slug}`, undefined, overallDeadline);
+  const finalData = asRecord(asRecord(finalRes).data);
+  const finalSegments = Array.isArray(finalData.segments) ? finalData.segments : [];
+  const stillUnfinished = finalSegments.filter((segment) => {
+    if (segment.source_type === "upload")
+      return false;
+    const status = segment.status ?? segment.generation_status;
+    return status !== "completed";
+  });
+  if (stillUnfinished.length > 0) {
+    return ok({
+      slug: args.slug,
+      generated,
+      timed_out: true,
+      in_flight_segment_ids: stillUnfinished.map((segment) => segment.id).filter((id) => id !== undefined),
+      note: "Some scenes are still processing. Re-run generate_all_segments later; it will wait for in-flight scenes and generate only unfinished ones."
+    });
   }
   return ok({
     slug: args.slug,
@@ -33616,7 +33800,7 @@ registerTool("set_closing_image", {
 }));
 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 (≤1 MiB; 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 (≤5 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)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   "license": "MIT",
   "author": "Monocursive <contact@monocursive.com>",

package/src/core.ts

@@ -457,15 +457,14 @@ export function normalizeStatus(
 	);
 	const batchStatus = (d.batch_generation_status as string) ?? null;
 	// The batch enum's ACTIVE states (video_factory.ex): preparing (spinning up),
-	// awaiting_previews (previews generating), running, and paused_for_retry
-	// (auto-resuming). "queued" is not a real value and was dropped; "preparing"
-	// and "awaiting_previews" were missing, so an in-flight batch briefly looked
-	// idle and could be reported terminal mid-run.
+	// awaiting_previews (previews generating), and running. "queued" is not a real
+	// value and was dropped. paused_for_retry is deliberately NOT active: no worker
+	// owns it until the user explicitly retries or cancels the paused batch.
 	const batchActive =
 		batchStatus === "running" ||
 		batchStatus === "preparing" ||
-		batchStatus === "awaiting_previews" ||
-		batchStatus === "paused_for_retry";
+		batchStatus === "awaiting_previews";
+	const batchRetryRequired = batchStatus === "paused_for_retry";
 	// A parked batch that ran out of credits: it cannot progress without the user
 	// topping up or reducing scope, so it is a needs-user-action TERMINAL state
 	// (not active work to wait on).
@@ -566,14 +565,39 @@ export function normalizeStatus(
 		currentMusic.status === "processing" ||
 		newerAudioVersions.some(versionActive) ||
 		newerMusicVersions.some(versionActive);
-	const workActive =
-		autopilotActive ||
+	const childWorkActive =
 		batchActive ||
 		renderActive ||
 		scenarioActive ||
 		narrationActive ||
 		audioActive ||
 		activeSegments.length > 0;
+	// A resumed Autopilot briefly exposes the previous attempt's failed child
+	// states before its new worker reaches and clears them. Suppress that history
+	// only while real child work is active or for a short, timestamped hand-off
+	// window. A parent stuck "running" with no worker must eventually surface the
+	// child failure instead of making wait_for_completion poll forever.
+	const autopilotStartedAt =
+		typeof d.autopilot_started_at === "string"
+			? Date.parse(d.autopilot_started_at)
+			: Number.NaN;
+	const now = Date.now();
+	const autopilotResumeGraceActive =
+		autopilotActive &&
+		Number.isFinite(autopilotStartedAt) &&
+		autopilotStartedAt <= now &&
+		now - autopilotStartedAt <= 120_000;
+	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
+	// Retrying a paused batch deliberately leaves the failed parent Autopilot
+	// marker in place while the already-paid child batch finishes. In that one
+	// state combination the parent/old scene failures are history, not a reason
+	// to return terminal immediately. Once the batch settles, the parent failure
+	// becomes actionable again and the agent can quote/relaunch Autopilot.
+	const batchRecoveryActive = autopilotFailed && batchActive;
+	const childFailureActionable =
+		!batchRecoveryActive &&
+		(!autopilotActive || (!childWorkActive && !autopilotResumeGraceActive));
+	const workActive = autopilotActive || childWorkActive;
 	// Orchestration failures are historical once a repaired timeline has a fresh,
 	// completed MP4. Keeping them terminal would permanently block download_result
 	// after a successful granular recovery.
@@ -586,17 +610,26 @@ export function normalizeStatus(
 		failedSegments.length === 0 &&
 		!audioFailed;
 	const ready = deliveredArtifactSupersedesOrchestrationFailure;
-	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
-	const renderFailed = renderStatus === "failed";
+	const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
+	const renderFailed = renderStatus === "failed" && childFailureActionable;
 	const failed =
-		(autopilotFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
+		(parentFailureActionable &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
 		renderFailed ||
-		(scenarioApplyFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(scenarioFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(narrationFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		(batchFailed && !deliveredArtifactSupersedesOrchestrationFailure) ||
-		failedSegments.length > 0 ||
-		audioFailed;
+		(childFailureActionable &&
+			scenarioApplyFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			scenarioFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			narrationFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable &&
+			batchFailed &&
+			!deliveredArtifactSupersedesOrchestrationFailure) ||
+		(childFailureActionable && failedSegments.length > 0) ||
+		(childFailureActionable && audioFailed);
 	// Terminal = control should return to the agent because nothing will progress
 	// without another tool call. With every async job type folded into workActive
 	// above (autopilot, batch, segments, scenario, narration, audio, render), NO
@@ -605,21 +638,35 @@ export function normalizeStatus(
 	// a new tool call can move it, so wait_for_completion must return instead of
 	// polling its full budget. (ready is subsumed by !workActive but kept for
 	// clarity; explicit failure states are terminal even while cleanup work spins.)
-	const terminal = ready || failed || batchInsufficientCredits || !workActive;
+	const terminal =
+		ready ||
+		failed ||
+		batchRetryRequired ||
+		batchInsufficientCredits ||
+		!workActive;
 	let stage = autopilot;
 	// Failure always wins over an unrelated active flag. Workers can leave an
 	// outer autopilot/batch state active after a child stage has failed; reporting
 	// the active stage would make agents poll forever instead of taking action.
 	if (ready) stage = "completed";
-	else if (autopilot === "failed") stage = "failed";
-	else if (autopilot === "cancelled") stage = "cancelled";
+	// A paused child batch is the immediate recovery gate even when its parent
+	// Autopilot run has already failed/cancelled. Reporting only the generic
+	// parent terminal state hides the one action that must happen before a new
+	// Autopilot run is allowed to start.
+	else if (batchRetryRequired) stage = "batch_retry_required";
+	else if (parentFailureActionable && autopilot === "failed") stage = "failed";
+	else if (parentFailureActionable && 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 (childFailureActionable && scenarioApplyFailed)
+		stage = "scenario_apply_failed";
+	else if (childFailureActionable && scenarioFailed) stage = "scenario_failed";
+	else if (childFailureActionable && narrationFailed)
+		stage = "narration_failed";
+	else if (childFailureActionable && batchFailed) stage = "batch_failed";
+	else if (childFailureActionable && failedSegments.length > 0)
+		stage = "segment_failed";
+	else if (childFailureActionable && audioFailed) stage = "audio_failed";
 	else if (batchInsufficientCredits) stage = "insufficient_credits";
 	else if (activeSegments.length > 0) stage = "segment_processing";
 	else if (batchActive) stage = "segment_generation";
@@ -633,6 +680,15 @@ export function normalizeStatus(
 		.find(
 			(value): value is string => typeof value === "string" && value.length > 0,
 		);
+	const actionableChildError = childFailureActionable
+		? ((latest.error_message as string) ??
+			(d.scenario_apply_error_message as string) ??
+			(d.scenario_error_message as string) ??
+			(d.narration_error_message as string) ??
+			(d.batch_generation_error_message as string) ??
+			segmentError ??
+			audioError)
+		: null;
 	return {
 		kind,
 		slug,
@@ -642,17 +698,15 @@ export function normalizeStatus(
 		video_url: videoUrl,
 		error: ready
 			? null
-			: ((d.autopilot_error_message as string) ??
-				(latest.error_message as string) ??
-				(d.scenario_apply_error_message as string) ??
-				(d.scenario_error_message as string) ??
-				(d.narration_error_message as string) ??
-				(d.batch_generation_error_message as string) ??
-				segmentError ??
-				audioError ??
-				(batchInsufficientCredits
-					? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then resume."
-					: null)),
+			: batchRetryRequired
+				? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing."
+				: ((parentFailureActionable
+						? (d.autopilot_error_message as string)
+						: null) ??
+					actionableChildError ??
+					(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)

package/src/index.ts

@@ -620,7 +620,7 @@ CREDITS (spent server-side; each tool prices before charging — see its descrip
 - 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. 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.
+- 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; batch_retry_required = call retry_editor_batch or cancel_editor_batch before starting Autopilot again; 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)
@@ -683,10 +683,9 @@ async function pollSegmentToTerminal(
 	slug: string,
 	segmentId: string | number,
 	extra: ToolExtra,
-	budgetMs: number,
+	deadline: number,
 	intervalMs: number,
 ): Promise<{ status: string; error: string | null; timed_out: boolean }> {
-	const deadline = Date.now() + budgetMs;
 	const sid = String(segmentId);
 	const read = async (): Promise<{ status: string; error: string | null }> => {
 		// Bound each poll GET's retries by the loop deadline (see fetchStatus).
@@ -1135,6 +1134,7 @@ registerTool(
 					: `/editor/${slug}/autopilot/cost`;
 			let estimated_credits: number | null = null;
 			let available_credits: number | null = null;
+			let authorizedCredits: number | undefined;
 			try {
 				const cost = asRecord(
 					asRecord(await client.get<{ data: unknown }>(costPath)).data,
@@ -1238,6 +1238,7 @@ registerTool(
 						"Editor autopilot launch requires max_credits or a live quote",
 					);
 				}
+				authorizedCredits = approvedCap;
 				await client.post(
 					`/editor/${slug}/autopilot`,
 					// Use the caller's explicit cap when given, otherwise the live
@@ -1272,12 +1273,50 @@ registerTool(
 					.saved_to;
 			}
 
+			// Shorts charge atomically when generation starts. Editor autopilot only
+			// authorizes a cap at launch and spends incrementally as child work starts,
+			// so report observed run spend instead of claiming the whole launch charged.
+			// If this receipt-enrichment read fails, omit the charge claim entirely.
+			let editorCreditsSpent: number | undefined;
+			if (kind === "editor") {
+				try {
+					const current = asRecord(
+						asRecord(
+							await client.get<{ data: unknown }>(
+								`/editor/${slug}`,
+								undefined,
+								Date.now() + 5_000,
+							),
+						).data,
+					);
+					if (typeof current.autopilot_credits_spent === "number") {
+						editorCreditsSpent = current.autopilot_credits_spent;
+					}
+				} catch {
+					// The launch/poll result remains valid without receipt enrichment.
+				}
+			}
+
+			const billing =
+				kind === "short"
+					? { charged: true }
+					: {
+							launched: true,
+							authorized_credits: authorizedCredits,
+							...(editorCreditsSpent === undefined
+								? {}
+								: {
+										credits_spent: editorCreditsSpent,
+										charged: editorCreditsSpent > 0,
+									}),
+						};
+
 			const result = {
 				...status,
 				kind_inferred: requestedKind === undefined,
 				estimated_credits,
 				available_credits,
-				charged: true,
+				...billing,
 				saved_to,
 				timed_out: !status.terminal,
 			};
@@ -1297,13 +1336,15 @@ registerTool(
 					note: status.ready
 						? "Done. Presigned ~24h URL — download promptly."
 						: status.terminal
-							? // A terminal-but-not-ready make_video is a failed/cancelled run.
-								// Point at a restart: re-running make_video now genuinely restarts
-								// (the start key folds the failure state, so it no longer replays the
-								// dead 202), or resume the pipeline directly. Fix the cause (often
-								// credits) first.
-								`Terminal (${status.stage}). ${status.error ?? ""}`.trim() +
-								` To restart, fix the cause (often credits) then re-run make_video, or resume with ${resume}.`
+							? status.stage === "batch_retry_required"
+								? `Terminal (${status.stage}). ${status.error ?? ""} Resolve the paused batch before restarting Autopilot.`.trim()
+								: // A terminal-but-not-ready make_video is normally a failed/cancelled run.
+									// Point at a restart: re-running make_video now genuinely restarts
+									// (the start key folds the failure state, so it no longer replays the
+									// dead 202), or resume the pipeline directly. Fix the cause (often
+									// credits) first.
+									`Terminal (${status.stage}). ${status.error ?? ""}`.trim() +
+									` To restart, fix the cause (often credits) then re-run make_video, or resume with ${resume}.`
 							: `Still rendering — call wait_for_completion(${resumeArgs}).`,
 				},
 				links,
@@ -3060,7 +3101,7 @@ registerTool(
 			logo_path: z
 				.string()
 				.optional()
-				.describe("Local logo (.jpg/.jpeg/.png, ≤1 MiB) to overlay."),
+				.describe("Local logo (.jpg/.jpeg/.png, ≤5 MiB) to overlay."),
 			logo_treatment: z
 				.enum(["intro", "outro", "both", "none"])
 				.optional()
@@ -3318,7 +3359,10 @@ registerTool(
 					kind: "editor",
 					status,
 					...quote,
-					charged: true,
+					launched: true,
+					authorized_credits: args.max_credits,
+					credits_spent: 0,
+					charged: false,
 					next: "wait_for_completion",
 				});
 			} finally {
@@ -3338,7 +3382,9 @@ registerTool(
 			"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 " +
+			"or double-charges. Failed or cancelled runs resume normally, except when status is batch_retry_required: " +
+			"call retry_editor_batch (then wait for that prepaid batch) or cancel_editor_batch first. 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: z.string().describe("Editor project slug"),
@@ -3455,13 +3501,79 @@ registerTool(
 				kind: "editor",
 				status,
 				...quote,
-				charged: true,
+				launched: true,
+				authorized_credits: args.max_credits,
+				credits_spent: 0,
+				charged: false,
 				next: "wait_for_completion",
 			});
 		},
 	),
 );
 
+registerTool(
+	"retry_editor_batch",
+	{
+		title: "Retry a paused editor batch",
+		description:
+			"Recovers an editor whose normalized status is batch_retry_required by atomically re-queueing the failed " +
+			"scene and resuming its prepaid batch. This spends 0 additional credits: the batch generation was already " +
+			"paid. It does not authorize or restart a failed parent Autopilot run; after retrying, wait for the batch " +
+			"to settle. If the parent is then terminal, call start_autopilot without max_credits for a fresh quote and " +
+			"relaunch only with an approved cap. A batch parked on " +
+			"insufficient_credits needs a top-up/scope change instead. Scope: video:generate.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: {
+			title: "Retry editor batch",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/video-factories/${args.slug}/retry-batch-segment`,
+		);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			slug: args.slug,
+			charged: false,
+			note: "The failed scene retry is queued and the prepaid batch is running. Wait for it to settle; if the parent Autopilot run is then terminal, quote start_autopilot again and relaunch only with an approved max_credits cap.",
+			next: "wait_for_completion",
+		});
+	}),
+);
+
+registerTool(
+	"cancel_editor_batch",
+	{
+		title: "Cancel an editor batch",
+		description:
+			"Cancels an editor batch in awaiting_previews, running, or paused_for_retry so the project can be edited or " +
+			"Autopilot can be started again. Cancellation is destructive: dispatched scene work is stopped and its prepaid " +
+			"credits are not refunded; only an awaiting_previews batch (before dispatch) is refunded by the server. Spends " +
+			"0 additional credits. Scope: video:generate.",
+		inputSchema: { slug: z.string().describe("Editor project slug") },
+		annotations: {
+			title: "Cancel editor batch",
+			readOnlyHint: false,
+			destructiveHint: true,
+			openWorldHint: true,
+			idempotentHint: false,
+		},
+	},
+	tool(async (args: { slug: string }, client) => {
+		const res = await client.post<{ data: unknown }>(
+			`/video-factories/${args.slug}/cancel-batch`,
+		);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			slug: args.slug,
+			charged: false,
+			next: "get_status",
+		});
+	}),
+);
+
 // ── AI assists (free daily quota) ───────────────────────────────────────────
 
 registerTool(
@@ -3660,21 +3772,81 @@ registerTool(
 	),
 );
 
+function conciseEditorState(value: unknown): Record<string, unknown> {
+	const data = asRecord(value);
+	const keys = [
+		"slug",
+		"status",
+		"autopilot_status",
+		"autopilot_current_step",
+		"autopilot_error_step",
+		"autopilot_error_code",
+		"autopilot_error_message",
+		"autopilot_max_credits",
+		"autopilot_credits_spent",
+		"scenario_status",
+		"scenario_apply_status",
+		"scenario_prompt",
+		"batch_generation_status",
+		"narration_status",
+		"narration_script",
+		"narration_stale",
+		"voice_stale",
+		"music_stale",
+		"segments_count",
+		"current_audio",
+		"current_music",
+		"latest_render",
+		"project_spend",
+		"ai_assist_quota",
+	] as const;
+	const result: Record<string, unknown> = {};
+	for (const key of keys) {
+		if (key in data) result[key] = data[key];
+	}
+	result.segments = Array.isArray(data.segments)
+		? (data.segments as Record<string, unknown>[]).map((segment) => ({
+				id: segment.id,
+				position: segment.position,
+				prompt: segment.prompt,
+				status: segment.status,
+				source_type: segment.source_type,
+				use_previous_frame: segment.use_previous_frame,
+				protagonist_presence: segment.protagonist_presence,
+				cast_mode_snapshot: segment.cast_mode_snapshot,
+				video_stale: segment.video_stale,
+				error_code: segment.error_code,
+				error_message: segment.error_message,
+				narration_text: segment.narration_text,
+			}))
+		: [];
+	return result;
+}
+
 registerTool(
 	"get_editor",
 	{
-		title: "Get full editor state (review step)",
+		title: "Get editor state (review step)",
 		description:
-			"Returns the full editor project state: scenario_prompt, segments[] (with prompts + status), " +
-			"narration_script/status, music, latest_render, segments_count, ai_assist_quota. This is the REVIEW " +
-			"step — call it after generating the scenario/segments to inspect and decide what to edit.",
-		inputSchema: { slug: z.string().describe("Editor project slug") },
+			"Returns the full editor state by default for backward compatibility. Pass response_format:'concise' for a smaller review projection containing orchestration, scenario, scene prompts/status, narration, audio, render, spend, and quota.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			response_format: z.enum(["concise", "full"]).default("full"),
+		},
 		annotations: { title: "Get editor", ...RO },
 	},
-	tool(async (args: { slug: string }, client) => {
-		const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
-		return ok(asRecord(res).data);
-	}),
+	tool(
+		async (
+			args: { slug: string; response_format: "concise" | "full" },
+			client,
+		) => {
+			const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+			const data = asRecord(res).data;
+			return ok(
+				args.response_format === "full" ? data : conciseEditorState(data),
+			);
+		},
+	),
 );
 
 registerTool(
@@ -4123,20 +4295,30 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client, extra) => {
-		const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
+		// One absolute deadline owns the entire read/submit/poll/reconcile path.
+		// Start it before the initial retrying GET so no preparatory request sits
+		// outside the advertised ~280s tool budget.
+		const overallDeadline = Date.now() + 280_000;
+		const res = await client.get<{ data: unknown }>(
+			`/editor/${args.slug}`,
+			undefined,
+			overallDeadline,
+		);
 		const data = asRecord(asRecord(res).data);
 		const segments = Array.isArray(data.segments)
 			? (data.segments as Record<string, unknown>[])
 			: [];
-		const pending = segments.filter((s) => {
-			const st = (s.status as string) ?? (s.generation_status as string);
-			return (
-				st === undefined ||
-				st === "pending" ||
-				st === "draft" ||
-				st === "failed"
+		const unfinished = segments
+			.filter((s) => {
+				if (s.source_type === "upload") return false;
+				const st = (s.status as string) ?? (s.generation_status as string);
+				return st !== "completed";
+			})
+			.sort(
+				(a, b) =>
+					Number(a.position ?? Number.MAX_SAFE_INTEGER) -
+					Number(b.position ?? Number.MAX_SAFE_INTEGER),
 			);
-		});
 
 		// Overall wall-clock budget: cap the whole call at the same 280s ceiling the
 		// other wait loops use (under a typical 300s client timeout). Without it a
@@ -4144,20 +4326,23 @@ registerTool(
 		// hours) in a single call. When the budget runs out mid-batch we stop and
 		// return the standard resume contract — call again and it naturally continues
 		// with whatever scenes are still pending (completed ones are skipped).
-		const overallDeadline = Date.now() + 280_000;
-		// Each scene's own poll budget stays generous (a Veo scene can take minutes)
-		// but is clamped to the time left overall so one scene can't overrun 280s.
-		const PER_SEGMENT_MAX_MS = 6 * 60 * 1000;
+		// Every scene poll receives this same absolute deadline, so time already spent
+		// on earlier reads, submissions, and scenes is never granted again.
+		// Reserve a full non-idempotent POST timeout plus one final status read before
+		// starting another paid scene. POSTs deliberately aren't aborted/retried, so
+		// beginning one in the last seconds of the budget would make a client timeout
+		// ambiguous after the server may already have accepted the charge.
+		const SUBMIT_HEADROOM_MS = 61_000;
 
 		const generated: Array<string | number> = [];
 		let n = 0;
-		for (const seg of pending) {
+		for (const seg of unfinished) {
 			const id = seg.id;
 			if (id === undefined) continue;
 			const sid = id as string | number;
 			// Stop before submitting another scene once the overall budget is spent, so
 			// the call returns instead of charging + waiting past the deadline.
-			const remainingMs = overallDeadline - Date.now();
+			let remainingMs = overallDeadline - Date.now();
 			if (remainingMs <= 0) {
 				return ok({
 					slug: args.slug,
@@ -4169,22 +4354,45 @@ registerTool(
 			await reportProgress(
 				extra,
 				++n,
-				`generating segment ${String(sid)} (${n}/${pending.length})`,
-				pending.length,
+				`generating segment ${String(sid)} (${n}/${unfinished.length})`,
+				unfinished.length,
 			);
-			try {
-				await client.post(
-					`/editor/${args.slug}/segments/${String(sid)}/generate`,
-					undefined,
-					undefined,
-				);
-			} catch (e) {
+			const initialStatus =
+				(seg.status as string) ?? (seg.generation_status as string);
+			if (initialStatus !== "processing") {
+				remainingMs = overallDeadline - Date.now();
+				if (remainingMs < SUBMIT_HEADROOM_MS) {
+					return ok({
+						slug: args.slug,
+						generated,
+						timed_out: true,
+						note: "Wall-clock budget is too low to safely start another paid scene. Re-run generate_all_segments to continue; completed scenes are skipped.",
+					});
+				}
+				try {
+					await client.post(
+						`/editor/${args.slug}/segments/${String(sid)}/generate`,
+						undefined,
+						undefined,
+					);
+				} catch (e) {
+					return ok({
+						slug: args.slug,
+						generated,
+						stopped_at: sid,
+						error: errMessage(e),
+						note: "Stopped on first error — fix the cause (often credits) and re-run; completed scenes are skipped, failed/pending are retried.",
+					});
+				}
+			}
+			remainingMs = overallDeadline - Date.now();
+			if (remainingMs <= 0) {
 				return ok({
 					slug: args.slug,
 					generated,
 					stopped_at: sid,
-					error: errMessage(e),
-					note: "Stopped on first error — fix the cause (often credits) and re-run; completed scenes are skipped, failed/pending are retried.",
+					timed_out: true,
+					note: "The scene was submitted, but the wall-clock budget ended before its status could be checked. Re-run generate_all_segments later to continue safely.",
 				});
 			}
 			// Gate on THIS segment finishing before starting the next, so the next
@@ -4196,7 +4404,7 @@ registerTool(
 				args.slug,
 				sid,
 				extra,
-				Math.min(PER_SEGMENT_MAX_MS, remainingMs),
+				overallDeadline,
 				15000,
 			);
 			if (seg_result.status === "failed") {
@@ -4217,7 +4425,45 @@ registerTool(
 					note: "A scene is still rendering after the poll budget. Re-run generate_all_segments later to continue (it retries failed/pending, skips completed), or watch it with get_editor.",
 				});
 			}
-			generated.push(sid);
+			if (initialStatus !== "processing") generated.push(sid);
+		}
+
+		// Reconcile against a fresh authoritative snapshot. A scene may have been
+		// processing when this call started, or a completion webhook may still be
+		// landing; never claim "all generated" while any AI scene is unfinished.
+		if (overallDeadline - Date.now() < 1_000) {
+			return ok({
+				slug: args.slug,
+				generated,
+				timed_out: true,
+				note: "Wall-clock budget reached before the final reconciliation read. Re-run generate_all_segments to confirm completion; completed scenes are skipped.",
+			});
+		}
+		const finalRes = await client.get<{ data: unknown }>(
+			`/editor/${args.slug}`,
+			undefined,
+			overallDeadline,
+		);
+		const finalData = asRecord(asRecord(finalRes).data);
+		const finalSegments = Array.isArray(finalData.segments)
+			? (finalData.segments as Record<string, unknown>[])
+			: [];
+		const stillUnfinished = finalSegments.filter((segment) => {
+			if (segment.source_type === "upload") return false;
+			const status =
+				(segment.status as string) ?? (segment.generation_status as string);
+			return status !== "completed";
+		});
+		if (stillUnfinished.length > 0) {
+			return ok({
+				slug: args.slug,
+				generated,
+				timed_out: true,
+				in_flight_segment_ids: stillUnfinished
+					.map((segment) => segment.id)
+					.filter((id) => id !== undefined),
+				note: "Some scenes are still processing. Re-run generate_all_segments later; it will wait for in-flight scenes and generate only unfinished ones.",
+			});
 		}
 		return ok({
 			slug: args.slug,
@@ -5018,7 +5264,7 @@ registerTool(
 	{
 		title: "Set a brand logo overlay (0 credits)",
 		description:
-			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤1 MiB; PNG keeps " +
+			"Uploads a local brand logo and overlays it on the video. Accepted: .png/.jpg/.jpeg (≤5 MiB; PNG keeps " +
 			"transparency), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. Optional placement controls: treatment, " +
 			"position, duration_seconds.",
 		inputSchema: {

package/src/output-schemas.ts

@@ -249,6 +249,9 @@ export const createEditorOutput = z
 		estimated_credits: z.union([z.number(), z.null()]).optional(),
 		available_credits: z.union([z.number(), z.null()]).optional(),
 		affordable: z.boolean().optional(),
+		launched: z.boolean().optional(),
+		authorized_credits: z.number().optional(),
+		credits_spent: z.number().optional(),
 		charged: z.boolean().optional(),
 		note: z.string().optional(),
 		next: z.string().optional(),
@@ -269,6 +272,9 @@ export const makeVideoOutput = z
 		estimated_credits: z.union([z.number(), z.null()]).optional(),
 		available_credits: z.union([z.number(), z.null()]).optional(),
 		affordable: z.boolean().optional(),
+		launched: z.boolean().optional(),
+		authorized_credits: z.number().optional(),
+		credits_spent: z.number().optional(),
 		charged: z.boolean().optional(),
 		saved_to: z.union([z.string(), z.null()]).optional(),
 		timed_out: z.boolean().optional(),

package/src/uploads.ts

@@ -63,7 +63,7 @@ const ALLOW_LOOPBACK_FETCH =
 const MAX_VIDEO_BYTES = 500_000_000; // EditorUpload.@max_upload_bytes
 const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 export const MAX_PRODUCT_IMAGE_BYTES = 8 * 1024 * 1024;
-export const MAX_LOGO_BYTES = 1 * 1024 * 1024; // Editor.Logo.@max_logo_bytes
+export const MAX_LOGO_BYTES = 5 * 1024 * 1024; // Editor.Logo.@max_logo_bytes
 export const MAX_SHORT_LOGO_BYTES = 5 * 1024 * 1024;
 export const MAX_CLOSING_IMAGE_BYTES = 20 * 1024 * 1024;
 const MULTIPART_THRESHOLD = 50 * 1024 * 1024; // @multipart_min_size — at/above this, use multipart