@hubfluencer/mcp 0.10.0 → 0.12.0

package/src/index.ts

@@ -171,9 +171,9 @@ async function editorAutopilotQuote(
 	try {
 		const params = new URLSearchParams();
 		if (overrides.language) params.set("language", overrides.language);
-		if (overrides.product_subject)
+		if (overrides.product_subject !== undefined)
 			params.set("product_subject", overrides.product_subject);
-		if (overrides.product_prompt)
+		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
@@ -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,
@@ -2979,12 +3020,12 @@ registerTool(
 			"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.",
+			"A product image is analyzed into semantic project context and sent as a product-identity reference to every " +
+			"generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " +
+			"was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " +
+			"products, visual continuity, absences, and composition directly in the brief. (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.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -3044,14 +3085,14 @@ registerTool(
 				.string()
 				.optional()
 				.describe(
-					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) to attach before autopilot.",
+					"Local product image (.jpg/.jpeg/.png, ≤8 MiB) used as the product-identity reference for every generated Editor scene and linked as the exact closing image unless one was already authored.",
 				),
 			product_description: z
 				.string()
 				.max(500)
 				.optional()
 				.describe(
-					"Exact product/character description used with product_image_path.",
+					"Product description used to ground the scenario and narration when product_image_path is supplied.",
 				),
 			closing_image_path: z
 				.string()
@@ -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()
@@ -3081,12 +3122,6 @@ registerTool(
 				.describe(
 					"Logo bumper duration in seconds, 0.5–3 (default 1.5). Requires logo_path.",
 				),
-			cast_mode: z
-				.literal("product_only")
-				.optional()
-				.describe(
-					"Lock every AI scene to the supplied product/mascot reference with no people. Requires product_image_path.",
-				),
 			max_credits: z
 				.number()
 				.int()
@@ -3122,7 +3157,6 @@ registerTool(
 					| "bottom-left"
 					| "bottom-right";
 				logo_duration_seconds?: number;
-				cast_mode?: "product_only";
 				max_credits?: number;
 			},
 			client,
@@ -3136,11 +3170,6 @@ registerTool(
 				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.",
-					);
-				}
 				// Fail fast on settings that would otherwise be silently dropped: the
 				// logo PATCH is gated on logo_path and the product_description is only
 				// sent with product_image_path, so a logo_* / product_description passed
@@ -3200,7 +3229,6 @@ registerTool(
 						theme: args.theme,
 						voice_id: args.voice_id,
 						export_aspect_ratio: args.export_aspect_ratio,
-						cast_mode: args.cast_mode,
 					},
 					// Fold every create-affecting param into the key so two calls that
 					// differ only by style/theme/voice/aspect get distinct drafts.
@@ -3318,7 +3346,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 +3369,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"),
@@ -3355,12 +3388,14 @@ registerTool(
 				.optional()
 				.describe(
 					"Optional locked product / main subject applied before launch so the AI cannot invent an " +
-						"unrelated product.",
+						"unrelated product. Omit to keep the stored subject; send blank to clear it.",
 				),
 			product_prompt: z
 				.string()
 				.optional()
-				.describe("Optional freeform brief to set/replace before launch."),
+				.describe(
+					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3455,13 +3490,132 @@ 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 command = await observedEditorBatchCommand(client, args.slug, [
+			"paused_for_retry",
+		]);
+		const res = await client.post<{ data: unknown }>(
+			`/video-factories/${args.slug}/retry-batch-segment`,
+			command,
+		);
+		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 only while it is preparing or paused_for_retry so the project can be edited or " +
+			"Autopilot can be started again. Preparing cancellation releases the uncharged preflight. Cancelling a paused " +
+			"batch is destructive: dispatched scene work is stopped and its prepaid credits are not refunded. 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 command = await observedEditorBatchCommand(client, args.slug, [
+			"preparing",
+			"paused_for_retry",
+		]);
+		const res = await client.post<{ data: unknown }>(
+			`/video-factories/${args.slug}/cancel-batch`,
+			command,
+		);
+		return ok({
+			...asRecord(asRecord(res).data ?? res),
+			slug: args.slug,
+			charged: false,
+			next: "get_status",
+		});
+	}),
+);
+
+type EditorBatchCommandStatus = "preparing" | "paused_for_retry";
+
+/**
+ * Reads the exact Editor batch ownership token immediately before issuing a
+ * recovery command. The API validates both fields under the factory row lock,
+ * so a replacement run or phase transition between this GET and the POST is a
+ * safe `batch_command_stale` conflict rather than acting on newer work.
+ */
+async function observedEditorBatchCommand(
+	client: HubfluencerClient,
+	slug: string,
+	allowedStatuses: readonly EditorBatchCommandStatus[],
+): Promise<{
+	expected_batch_run_id: string | null;
+	expected_batch_status: EditorBatchCommandStatus;
+}> {
+	const response = await client.get<{ data: unknown }>(`/editor/${slug}`);
+	const state = asRecord(asRecord(response).data);
+	const status = state.batch_generation_status;
+	if (
+		typeof status !== "string" ||
+		!allowedStatuses.includes(status as EditorBatchCommandStatus)
+	) {
+		throw new Error(
+			`Editor batch is not in an allowed phase (${allowedStatuses.join(" or ")}); refresh status before retrying.`,
+		);
+	}
+
+	const runId = state.batch_generation_run_id;
+	if (
+		runId !== null &&
+		(typeof runId !== "string" || runId.trim().length === 0)
+	) {
+		throw new Error(
+			"Editor state did not include a valid batch_generation_run_id; refresh status before retrying.",
+		);
+	}
+
+	return {
+		expected_batch_run_id: runId,
+		expected_batch_status: status as EditorBatchCommandStatus,
+	};
+}
+
 // ── AI assists (free daily quota) ───────────────────────────────────────────
 
 registerTool(
@@ -3564,17 +3718,6 @@ registerTool(
 				.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.',
 				),
-			cast_mode: z
-				.enum(["product_only", "presenter_led"])
-				.optional()
-				.describe(
-					"Who/what anchors every AI scene. product_only = a product-led ad with NO people; requires a " +
-						"product image (set_product) before generation and generates every scene from persistent product " +
-						"reference images — the best product fidelity. presenter_led = one locked presenter appears in " +
-						"every scene; requires a presenter to be configured first (in the app / REST presenter endpoints " +
-						"— no MCP tool yet), else generation fails with presenter_required. Omit for the default auto " +
-						"behavior.",
-				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -3611,7 +3754,6 @@ registerTool(
 				creative_format?: string;
 				visual_language?: string;
 				theme?: string;
-				cast_mode?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
 				project_intent?: string;
@@ -3625,7 +3767,6 @@ registerTool(
 				creative_format: args.creative_format,
 				visual_language: args.visual_language,
 				theme: args.theme,
-				cast_mode: args.cast_mode,
 				voice_id: args.voice_id,
 				export_aspect_ratio: args.export_aspect_ratio,
 				project_intent: args.project_intent,
@@ -3648,7 +3789,6 @@ registerTool(
 					args.theme ?? "",
 					args.voice_id ?? "",
 					args.export_aspect_ratio ?? "",
-					args.cast_mode ?? "",
 				),
 			);
 			return ok({
@@ -3660,21 +3800,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",
+		"batch_generation_run_id",
+		"auto_render_after_batch",
+		"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,
+				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_status, current_audio, current_music, latest_render, batch_generation_status, 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(
@@ -3726,16 +3926,16 @@ registerTool(
 				.optional()
 				.describe("How many scenes (3–10, server default 5)"),
 			creative_format: z
-				.enum(CREATIVE_FORMATS)
+				.union([z.enum(CREATIVE_FORMATS), z.literal("")])
 				.optional()
 				.describe(
 					"Persist the narrative arc / segment structure before generating. Omit to leave it unchanged; pass an empty string to clear.",
 				),
 			visual_language: z
-				.enum(VISUAL_LANGUAGES)
+				.union([z.enum(VISUAL_LANGUAGES), z.literal("")])
 				.optional()
 				.describe(
-					"Persist the visual style / render look before generating. When set it drives the look and a theme of 'none' is ignored.",
+					"Persist the visual style / render look before generating. Omit to leave it unchanged; pass an empty string to clear. When set it drives the look and a theme of 'none' is ignored.",
 				),
 			theme: z
 				.string()
@@ -4123,20 +4323,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 +4354,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 +4382,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 +4432,7 @@ registerTool(
 				args.slug,
 				sid,
 				extra,
-				Math.min(PER_SEGMENT_MAX_MS, remainingMs),
+				overallDeadline,
 				15000,
 			);
 			if (seg_result.status === "failed") {
@@ -4217,7 +4453,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,
@@ -4233,15 +4507,15 @@ registerTool(
 	{
 		title: "Set the narration script",
 		description:
-			"Writes your own narration script (1–12000 chars) instead of generating one. Free — no credits, no AI " +
+			"Writes your own narration script (1–10000 chars) instead of generating one. Free — no credits, no AI " +
 			"assist. Use this in place of generate_narration when you want to control the voiceover text. Changing the narration after generating voice/music marks them stale — regenerate (generate_voice / generate_music) before render.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			script: z
 				.string()
 				.min(1)
-				.max(12000)
-				.describe("Narration / voiceover text (1–12000 chars)"),
+				.max(10000)
+				.describe("Narration / voiceover text (1–10000 chars)"),
 		},
 		annotations: { title: "Set narration", ...WRITE, idempotentHint: true },
 	},
@@ -4258,7 +4532,7 @@ registerTool(
 	{
 		title: "Generate the narration (AI assist)",
 		description:
-			"Generates the narration script with AI from the timeline. CONSUMES 1 AI ASSIST (free daily quota) — " +
+			"Generates one coherent narration script with AI from the complete timeline. Every current scene must be completed with a known positive duration, and at least one scene must not keep original upload audio. CONSUMES 1 AI ASSIST (free daily quota) only when a fresh job is queued; an exact retry is deduplicated without consuming another assist — " +
 			"it is free of CREDITS but NOT free of quota. On 429 set auto_unlock:true (1 credit → +10 assists, " +
 			"retried once) or write the script yourself with set_narration_script.",
 		inputSchema: {
@@ -4290,7 +4564,7 @@ registerTool(
 		title: "Generate the voiceover (3 credits)",
 		description:
 			"Synthesizes the voiceover from the narration script. Costs 3 credits. Safe to retry; re-call after changing the narration or voice to regenerate." +
-			"voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
+			" All current scenes must be completed with known durations first. voice_id is REQUIRED — pick one from list_voices (≤64 chars, [A-Za-z0-9_-] only). 402 fails cleanly. Editing the scenario/narration/timeline after this marks the voice stale, and render will 422 (editor_voice_stale) until you re-run generate_voice.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			voice_id: z
@@ -4529,9 +4803,10 @@ registerTool(
 	{
 		title: "List renders for an editor project",
 		description:
-			"Lists every render version for an editor project: {id, version, status, video_url, duration_seconds, " +
-			"error_message, inserted_at}. Use it to find a FAILED render to retry, or to recover a finished video_url " +
-			"(presigned, ~24h). Read-only.",
+			"Lists every render version for an editor project: {id, version, status, video_url, thumbnail_url, " +
+			"duration_seconds, error_message, retryable, combination_hash, is_stale, inserted_at}. Use it to find a " +
+			"FAILED render to retry, or to recover a finished video_url (presigned, ~24h). status is pending | " +
+			"processing | completed | failed; is_stale null means unknown, not current. Read-only.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: { title: "List renders", ...RO },
 	},
@@ -4883,9 +5158,9 @@ registerTool(
 		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.",
+			" (≤8 MiB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Its pixels guide product identity " +
+			"in every generated Editor scene and its confirmed description grounds scenario and narration. The exact photo " +
+			"is linked as the closing image unless a separate closing image was authored; generated fine label text can still vary.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			file_path: z
@@ -4919,33 +5194,6 @@ registerTool(
 	),
 );
 
-registerTool(
-	"set_product_placement",
-	{
-		title: "Set default product placement on pending scenes (0 credits)",
-		description:
-			"Sets where the product appears across pending (never-generated) AI scenes. mode is 'throughout' (every scene) " +
-			"or 'end' (closing scene only; requires a first+last-frame capable model). 0 credits. Add a product first with " +
-			"set_product. (There is no 'none' — to remove the product, that's a separate action.)",
-		inputSchema: {
-			slug: z.string().describe("Editor project slug"),
-			mode: z.enum(["throughout", "end"]).describe("'throughout' or 'end'"),
-		},
-		annotations: {
-			title: "Set product placement",
-			...WRITE,
-			idempotentHint: true,
-		},
-	},
-	tool(async (args: { slug: string; mode: "throughout" | "end" }, client) => {
-		const res = await client.post<{ data: unknown }>(
-			`/editor/${args.slug}/product/apply-default-placement`,
-			{ placement: args.mode },
-		);
-		return ok(asRecord(res).data ?? res);
-	}),
-);
-
 registerTool(
 	"set_closing_image",
 	{
@@ -5018,7 +5266,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: {