@hubfluencer/mcp 0.9.1 → 0.11.0

package/src/index.ts

@@ -121,6 +121,7 @@ import {
 	MAX_CLOSING_IMAGE_BYTES,
 	MAX_LOGO_BYTES,
 	MAX_PRODUCT_IMAGE_BYTES,
+	MAX_SHORT_LOGO_BYTES,
 	type PreparedUploadFile,
 	preparedUploadIdentity,
 	prepareImageUpload,
@@ -614,12 +615,12 @@ DELEGATE THE CONTENT OPERATION (the full loop — steps 1-3 are $0)
 8. RECURRING: create_series + plan_series_episodes → materialize_episode drafts each episode; get_series_dashboard shows upcoming/drafted/published lanes; mark_episode_posted closes a recurring show's loop.
 
 CREDITS (spent server-side; each tool prices before charging — see its description)
-- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
+- Free (0 credits): every draft create/edit, reorder, all slider re-composites, short re-renders (rerender_short — applies text/style/CTA/end-card/logo edits over a short's already-paid footage), and the whole onboard/plan/pack/materialize path (steps 1-3). get_credits shows the balance.
 - Charged: short render 15; editor AI scene 5 (4 in a batch of ≥3); voice 3; music 5; editor render 0 (auto-charges ungenerated scenes); slider 1/slide; tracking render 1 (refunded on failure). make_video supports dry_run/max_credits; create_editor_ad/start_autopilot require max_credits before launching.
 - AI ASSISTS (all generate_*/enhance/suggest/plan/hook tools) draw a FREE daily quota (20/day), NOT credits. On 429, set auto_unlock:true to spend 1 credit for +10 assists (retried once), or write the copy yourself and use the set_* tools.
 
 WAITING & RESUMING
-- Renders run async and can take minutes. wait_for_completion polls a budget capped at 280s; if it returns terminal=false / timed_out, just CALL IT AGAIN with the same slug. make_video returns the slug + a resume hint on timeout. 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)
@@ -682,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).
@@ -1134,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,
@@ -1237,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
@@ -1271,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,
 			};
@@ -1296,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,
@@ -1436,7 +1478,7 @@ registerTool(
 			"Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " +
 			"segments + an on-screen title overlay + music; 14s when it ends on a poster or brand-lockup end card). " +
 			"Returns the slug, costs 0 credits. Follow with generate_short to render. Iteration is FREE after that " +
-			"first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card " +
+			"first generate: the 15 credits bought the footage + music, and every later text/style/CTA/end-card/logo " +
 			"tweak re-renders over them for 0 credits (update_short → rerender_short). " +
 			"BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " +
 			"title), and pick a music_vibe plus visual_language that fit the brand. " +
@@ -1447,8 +1489,8 @@ registerTool(
 			"default). If headline/subheadline/text_beats are left blank, the server auto-writes the headline + " +
 			"caption beats at generate time (pass skip_auto_text:true to generate_short for a deliberately bare clip). " +
 			"To brand it further, attach a product image " +
-			"(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " +
-			"overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
+			"(set_short_product), a deterministic brand logo (set_short_logo), or an end-card poster " +
+			"(set_short_poster) before generate_short.",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -1736,9 +1778,10 @@ registerTool(
 		title: "Update a short draft (0 credits)",
 		description:
 			"Patches an existing short draft — only the fields you pass change; omitted fields are left untouched. " +
-			"0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card fields " +
+			"0 credits, no re-render by itself. APPLYING the edit: changed only text/style/CTA/end-card/logo fields " +
 			"(headline, subheadline, text_beats, cta_text, offer_text, badge_text, star_rating, colors, font, " +
-			"position, animation, closing_claim, brand_name, poster_includes_lockup, end_card) on an " +
+			"position, animation, closing_claim, brand_name, poster_includes_lockup, end_card, short_logo_position, " +
+			"short_logo_treatment) on an " +
 			"already-generated short? " +
 			"rerender_short applies them for 0 credits. Footage/music-affecting edits (product_prompt, product " +
 			"image, creative_format, visual_language, theme, music_vibe, music_instruments, language) need " +
@@ -1922,6 +1965,20 @@ registerTool(
 					"Set true if your poster already contains brand name/CTA/badges — suppresses the overlaid " +
 						"claim/CTA so they don't collide (default false).",
 				),
+			short_logo_position: z
+				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
+				.optional()
+				.describe(
+					"Corner for the deterministic brand-logo overlay (set the image with set_short_logo). Moving it is " +
+						"a FREE re-render — logo fields never cost credits.",
+				),
+			short_logo_treatment: z
+				.enum(["throughout", "end_card", "none"])
+				.optional()
+				.describe(
+					'When the brand logo shows: "throughout" the footage, only on the "end_card", or "none" to hide it. ' +
+						"FREE re-render.",
+				),
 			brand_profile_id: z
 				.number()
 				.int()
@@ -1967,6 +2024,12 @@ registerTool(
 				brand_name?: string;
 				end_card?: string;
 				poster_includes_lockup?: boolean;
+				short_logo_position?:
+					| "top-left"
+					| "top-right"
+					| "bottom-left"
+					| "bottom-right";
+				short_logo_treatment?: "throughout" | "end_card" | "none";
 				brand_profile_id?: number;
 			},
 			client,
@@ -2013,6 +2076,13 @@ registerTool(
 			if (args.end_card !== undefined) body.end_card = args.end_card;
 			if (args.poster_includes_lockup !== undefined)
 				body.poster_includes_lockup = args.poster_includes_lockup;
+			// Logo overlay placement — the API maps these body keys straight onto the
+			// factory (short_logo_position/short_logo_treatment). They're excluded from
+			// the paid-inputs snapshot, so a corner/treatment change is a FREE re-render.
+			if (args.short_logo_position !== undefined)
+				body.short_logo_position = args.short_logo_position;
+			if (args.short_logo_treatment !== undefined)
+				body.short_logo_treatment = args.short_logo_treatment;
 			if (args.brand_profile_id !== undefined)
 				body.brand_profile_id = args.brand_profile_id;
 
@@ -2024,7 +2094,7 @@ registerTool(
 			return ok({
 				...asRecord(data),
 				next:
-					"Saved. Only text/style/CTA/end-card changed on an already-generated short? " +
+					"Saved. Only text/style/CTA/end-card/logo changed on an already-generated short? " +
 					`rerender_short({ slug: "${args.slug}" }) applies it for 0 credits. Footage/music edits ` +
 					"(prompt, product image, format, visual_language, theme, music_*, language) need " +
 					"generate_short (15 credits).",
@@ -2464,8 +2534,9 @@ registerTool(
 	{
 		title: "Re-render a short (FREE — 0 credits)",
 		description:
-			"FREE re-render: applies the short's current text/style/CTA/end-card state over the already-paid " +
-			"footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks. Footage or music " +
+			"FREE re-render: applies the short's current text/style/CTA/end-card/logo state over the already-paid " +
+			"footage and music — 0 credits. Use after update_short for copy/style/CTA tweaks, or after a logo change " +
+			"(set_short_logo, or short_logo_position/short_logo_treatment via update_short). Footage or music " +
 			"changes need generate_short (15 credits) instead. Edits that add/remove the end card (poster, " +
 			"end_card) can shift the video between 12s and 14s; when the pinned music bed is shorter than the " +
 			"export it crossfades into a repeated continuation, then fades at the export end, without regeneration. " +
@@ -3030,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()
@@ -3288,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 {
@@ -3308,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"),
@@ -3425,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(
@@ -3630,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(
@@ -4093,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
@@ -4114,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,
@@ -4139,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
@@ -4166,7 +4404,7 @@ registerTool(
 				args.slug,
 				sid,
 				extra,
-				Math.min(PER_SEGMENT_MAX_MS, remainingMs),
+				overallDeadline,
 				15000,
 			);
 			if (seg_result.status === "failed") {
@@ -4187,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,
@@ -4988,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: {
@@ -5043,11 +5319,11 @@ registerTool(
 	),
 );
 
-// ── Shorts: branding images (product + end-card poster) ──────────────────────
+// ── Shorts: branding images (product + logo + end-card poster) ───────────────
 //
 // The editor branding tools above hit /editor/...; these hit /shorts/... A short
-// has no logo overlay (editor-only), but it CAN feature a product image woven
-// into the footage and a closing end-card poster. Both are 0 credits.
+// Product images are woven into AI footage; logos are deterministic Forge
+// overlays; posters are closing cards. All are 0 credits.
 
 registerTool(
 	"set_short_product",
@@ -5096,6 +5372,57 @@ registerTool(
 	),
 );
 
+registerTool(
+	"set_short_logo",
+	{
+		title: "Set a Short brand logo overlay (0 credits)",
+		description:
+			"Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " +
+			"AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " +
+			"it appears throughout the footage or only on the end card.",
+		inputSchema: {
+			slug: z.string().describe("Short slug"),
+			file_path: z.string().describe("Local logo image (.png/.jpg/.jpeg)"),
+			position: z
+				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
+				.optional()
+				.describe("Logo corner (default top-right)"),
+			treatment: z
+				.enum(["throughout", "end_card", "none"])
+				.optional()
+				.describe("When the logo appears (default throughout)"),
+		},
+		annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false },
+	},
+	tool(
+		async (
+			args: {
+				slug: string;
+				file_path: string;
+				position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+				treatment?: "throughout" | "end_card" | "none";
+			},
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/shorts/${args.slug}/logo/presign`,
+				args.file_path,
+				MAX_SHORT_LOGO_BYTES,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/logo/confirm`,
+				{
+					s3_key,
+					position: args.position ?? "top-right",
+					treatment: args.treatment ?? "throughout",
+				},
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
 registerTool(
 	"set_short_poster",
 	{
@@ -5105,7 +5432,7 @@ registerTool(
 			"render from 12s to 14s). Accepted: " +
 			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
 			" (≤20 MiB = 20,971,520 bytes), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
-			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+			"again replaces it. Use set_short_logo for an exact, non-generative brand overlay.",
 		inputSchema: {
 			slug: z.string().describe("Short slug (from create_short)"),
 			file_path: z.string().describe("Local poster image (.jpg/.jpeg/.png)"),