@hubfluencer/mcp 0.15.0 → 0.17.0

package/src/index.ts

@@ -55,6 +55,7 @@ import {
 	makeVideoAutopilotKey,
 	makeVideoEditorCreateKey,
 	type NormalizedStatus,
+	normalizeFactoryIndexProject,
 	normalizeStatus,
 	resolveSavePath,
 	sliderCreateKey,
@@ -64,14 +65,21 @@ import {
 	validateLanguage,
 	validateProductPrompt,
 } from "./core.js";
+import { runDoctor } from "./doctor.js";
+import {
+	type GenerationSummary,
+	generationSummarySchema,
+} from "./generation-summary.js";
 import { runLogin } from "./login.js";
 import {
 	createCampaignOutput,
 	createDraftOutput,
 	createEditorOutput,
 	downloadResultOutput,
+	genericToolOutput,
 	getCampaignPackOutput,
 	getCreditsOutput,
+	getEditorOutput,
 	getRecommendationsOutput,
 	getSeriesDashboardOutput,
 	getSliderOutput,
@@ -101,6 +109,7 @@ import {
 	validatePerformanceMetrics,
 	validateReviewOutput,
 } from "./perf-review-assets.js";
+import { pollWithFinalReconciliation } from "./polling.js";
 import {
 	buildScheduledPostBody,
 	calendarScopeErrorText,
@@ -114,6 +123,12 @@ import {
 	summarizeSeries,
 	validateScheduledPostCopy,
 } from "./series-calendar.js";
+import { runInstallSkill } from "./skill-installer.js";
+import {
+	profileFromArgs,
+	toolEnabled,
+	withoutProfileArgs,
+} from "./tool-profile.js";
 import {
 	CATALOG_ASSET_EXTS,
 	closePreparedUploadFile,
@@ -154,6 +169,115 @@ async function fetchStatus(
 	return normalizeStatus(kind, slug, asRecord(res).data);
 }
 
+type ProductKind = "editor" | "short";
+
+interface ObservedGenerationAction {
+	state: Record<string, unknown>;
+	summary: GenerationSummary;
+	stepKey: string | null;
+	completedStatus?: NormalizedStatus;
+	activeReplay?: true;
+	settledReplay?: true;
+}
+
+/**
+ * Reads and validates the current product-owned action immediately before a
+ * write. The summary is an authority observation, not a bearer capability:
+ * the API rechecks all of these fences under its command lock.
+ */
+async function observedGenerationAction(
+	client: HubfluencerClient,
+	product: ProductKind,
+	slug: string,
+	actionType: string,
+	options: {
+		workflows?: readonly string[];
+		statuses?: readonly string[];
+		requireStep?: boolean;
+		allowIdleAuthority?: boolean;
+		recoverCompleted?: boolean;
+		recoverActive?: boolean;
+		recoverCancelled?: boolean;
+	} = {},
+): Promise<ObservedGenerationAction> {
+	const path = product === "short" ? `/shorts/${slug}` : `/editor/${slug}`;
+	const response = await client.get<{ data: unknown }>(path);
+	const state = asRecord(asRecord(response).data);
+	const parsed = generationSummarySchema.safeParse(state.generation_summary);
+	if (!parsed.success) {
+		throw new Error(
+			`The Hubfluencer ${product} response did not contain a valid generation_summary; refresh before continuing.`,
+		);
+	}
+
+	const summary = parsed.data;
+	if (options.recoverCompleted === true) {
+		const completedStatus = normalizeStatus(product, slug, state);
+		if (completedStatus.ready && completedStatus.video_url) {
+			return { state, summary, stepKey: null, completedStatus };
+		}
+	}
+	const idleAuthority =
+		options.allowIdleAuthority === true &&
+		summary.status === "idle" &&
+		summary.workflow === null &&
+		summary.workflow_version === null &&
+		summary.run_id === null &&
+		summary.revision === null;
+	if (
+		options.workflows &&
+		!idleAuthority &&
+		(!summary.workflow || !options.workflows.includes(summary.workflow))
+	) {
+		throw new Error(
+			`The current ${product} workflow does not authorize ${actionType}; refresh before continuing.`,
+		);
+	}
+	if (options.statuses && !options.statuses.includes(summary.status)) {
+		throw new Error(
+			`The current ${product} generation status does not authorize ${actionType}; refresh before continuing.`,
+		);
+	}
+	const canonicalAuthority =
+		typeof summary.run_id === "string" &&
+		Number.isInteger(summary.revision) &&
+		(summary.revision as number) >= 0;
+	if (!canonicalAuthority && !idleAuthority) {
+		throw new Error(
+			`The current ${product} generation authority is missing its run or revision fence; refresh before continuing.`,
+		);
+	}
+
+	if (
+		options.recoverActive === true &&
+		(summary.status === "queued" || summary.status === "running")
+	) {
+		return { state, summary, stepKey: null, activeReplay: true };
+	}
+	if (options.recoverCancelled === true && summary.status === "cancelled") {
+		return { state, summary, stepKey: null, settledReplay: true };
+	}
+
+	const action = summary.available_actions.find(
+		(candidate) => candidate.type === actionType,
+	);
+	if (!action) {
+		throw new Error(
+			`The server does not currently advertise ${actionType} for this ${product}; refresh before continuing.`,
+		);
+	}
+	if (
+		options.requireStep &&
+		(typeof action.step_key !== "string" || action.step_key.length === 0)
+	) {
+		throw new Error(
+			`The advertised ${actionType} action is missing its step fence; refresh before continuing.`,
+		);
+	}
+
+	return { state, summary, stepKey: action.step_key };
+}
+
 async function editorAutopilotQuote(
 	client: HubfluencerClient,
 	slug: string,
@@ -161,11 +285,14 @@ async function editorAutopilotQuote(
 		language?: string;
 		product_subject?: string;
 		product_prompt?: string;
+		segments_count?: number;
 		restart?: boolean;
 	} = {},
 ): Promise<{
 	estimated_credits: number | null;
 	available_credits: number | null;
+	scene_count: number | null;
+	target_duration_seconds: number | null;
 	affordable: boolean;
 }> {
 	try {
@@ -175,6 +302,8 @@ async function editorAutopilotQuote(
 			params.set("product_subject", overrides.product_subject);
 		if (overrides.product_prompt !== undefined)
 			params.set("product_prompt", overrides.product_prompt);
+		if (overrides.segments_count !== undefined)
+			params.set("segments_count", String(overrides.segments_count));
 		if (overrides.restart) params.set("restart", "true");
 		const query = params.toString();
 		const response = await client.get<{ data: unknown }>(
@@ -187,9 +316,17 @@ async function editorAutopilotQuote(
 			typeof cost.available_credits === "number"
 				? cost.available_credits
 				: null;
+		const scene_count =
+			typeof cost.scene_count === "number" ? cost.scene_count : null;
+		const target_duration_seconds =
+			typeof cost.target_duration_seconds === "number"
+				? cost.target_duration_seconds
+				: null;
 		return {
 			estimated_credits,
 			available_credits,
+			scene_count,
+			target_duration_seconds,
 			affordable:
 				estimated_credits !== null &&
 				available_credits !== null &&
@@ -213,6 +350,8 @@ async function editorAutopilotQuote(
 		return {
 			estimated_credits: null,
 			available_credits: null,
+			scene_count: null,
+			target_duration_seconds: null,
 			affordable: false,
 		};
 	}
@@ -363,10 +502,13 @@ function ok(payload: unknown, links: ResourceLink[] = []) {
 	const result: {
 		content: typeof content;
 		structuredContent?: Record<string, unknown>;
-	} = { content };
-	if (payload && typeof payload === "object" && !Array.isArray(payload)) {
-		result.structuredContent = payload as Record<string, unknown>;
-	}
+	} = {
+		content,
+		structuredContent:
+			payload && typeof payload === "object" && !Array.isArray(payload)
+				? (payload as Record<string, unknown>)
+				: { value: payload },
+	};
 	return result;
 }
 
@@ -411,21 +553,18 @@ function errMessage(e: unknown): string {
  * silently no-op'ing the purchase (no credit spent, no assists added) while
  * still returning 200. Snapshotting means a transport retry of the SAME unlock
  * replays safely (no double-charge), but a DISTINCT "buy another batch" call
- * gets a fresh key and executes. Falls back to no key (each call executes) if
- * the snapshot can't be read — safer than risking a replayed no-op.
+ * gets a fresh key and executes. If the snapshot cannot be read, fail before
+ * the paid POST: a nonce fallback cannot distinguish a transport retry from a
+ * genuine new purchase and could double-charge after an accepted/lost response.
  */
 async function unlockKey(client: HubfluencerClient): Promise<string> {
-	try {
-		const res = await client.get<{ data: unknown }>("/ai-assists");
-		const d = asRecord(asRecord(res).data);
-		return idemKey(
-			"unlock-ai-assists",
-			String(d.used ?? ""),
-			String(d.bonus ?? ""),
-		);
-	} catch {
-		return "";
-	}
+	const res = await client.get<{ data: unknown }>("/ai-assists");
+	const d = asRecord(asRecord(res).data);
+	return idemKey(
+		"unlock-ai-assists",
+		String(d.used ?? ""),
+		String(d.bonus ?? ""),
+	);
 }
 
 /**
@@ -434,25 +573,17 @@ async function unlockKey(client: HubfluencerClient): Promise<string> {
  * deterministic, so replaying an identical (narration, voice) call is correct
  * and free, while regenerating after the narration or voice changes gets a
  * fresh key and actually re-runs — a fixed slug+voice key would replay stale
- * audio for 24h after a narration edit. Falls back to no key on read failure.
+ * audio for 24h after a narration edit. If the input snapshot cannot be read,
+ * fail before the paid POST rather than minting a retry-unstable nonce.
  */
 async function voiceKey(
 	client: HubfluencerClient,
 	slug: string,
 	voiceId: string,
 ): Promise<string> {
-	try {
-		const res = await client.get<{ data: unknown }>(`/editor/${slug}`);
-		const d = asRecord(asRecord(res).data);
-		return idemKey(
-			"gen-voice",
-			slug,
-			voiceId,
-			String(d.narration_script ?? ""),
-		);
-	} catch {
-		return "";
-	}
+	const res = await client.get<{ data: unknown }>(`/editor/${slug}`);
+	const d = asRecord(asRecord(res).data);
+	return idemKey("gen-voice", slug, voiceId, String(d.narration_script ?? ""));
 }
 
 /**
@@ -481,7 +612,7 @@ async function withAssist<T>(
 		return await fn();
 	} catch (e) {
 		const he = e as HubfluencerError;
-		if (!he || he.status !== 429) throw e;
+		if (he?.status !== 429) throw e;
 		if (!autoUnlock) throw e;
 		// One unlock (1 credit → +10 assists), then one retry. A 402 here means
 		// the account is out of credits — let it propagate to a clean fail().
@@ -617,6 +748,8 @@ const WRITE = {
 // call (the per-tool `description`s carry the specifics). Kept concise: the two
 // altitudes (one-shot asset vs. the full delegate-my-content-operation loop),
 // money, how waiting/resuming works, and the local-file sandbox.
+const activeToolProfile = profileFromArgs(process.argv.slice(2));
+
 const SERVER_INSTRUCTIONS = `Hubfluencer turns a prompt — or a whole product page — into finished, post-ready vertical videos and image carousels, and can run the surrounding content operation (plan → draft → review → schedule → measure → repeat).
 
 MAKE ONE ASSET (simplest)
@@ -639,13 +772,16 @@ 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; 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.
+- Every Editor and Short read includes a non-null generation_summary. Treat its status, timing, blockers, and available_actions as the only lifecycle authority; product and latest-render fields are authoring or delivery details, never competing control state. Poll only while generation_summary.timing.poll_after_ms is a positive integer; null means stop. Invoke only an action advertised by generation_summary.available_actions, carrying every route fence required by that product command. wait_for_completion enforces those timing hints within a budget capped at 280s; when timed_out, call it again with the same slug. A terminal summary can require a start/retry/input/review action instead of more polling; download only when download_result is advertised.
+- Editor delivery freshness is separate from lifecycle authority: after a completed summary, raw render/scene/audio staleness forces normalized stale:true, ready:false, and stage:"editing_required". The retained MP4 is historical; re-render before delivery. list_projects factory rows are lightweight mixed-kind discovery records without generation_summary, so use get_status/get_editor before acting.
 - 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)
 - Reads (upload_video / product / logo / closing / poster) are confined to HUBFLUENCER_INPUT_DIR (default: cwd); writes (save_path on wait_for_completion / download_result) are confined to HUBFLUENCER_OUTPUT_DIR (default: cwd), .mp4 only. Paths outside the base are refused.
 
-AUTH: set HUBFLUENCER_API_TOKEN (Settings → Access tokens) or run \`npx -y @hubfluencer/mcp login\`. HUBFLUENCER_BASE_URL overrides the API host; HUBFLUENCER_CREDENTIALS overrides the device-link credentials path.`;
+AUTH: set HUBFLUENCER_API_TOKEN (Settings → Access tokens) or run \`npx -y @hubfluencer/mcp@${VERSION} login\`. HUBFLUENCER_BASE_URL overrides the API host; HUBFLUENCER_CREDENTIALS overrides the device-link credentials path.
+
+TOOL PROFILE: ${activeToolProfile}. The default full profile preserves every workflow. The opt-in creator profile keeps the high-level create, iterate, recovery, and delivery tools visible so tools/list uses much less agent context; switch with --profile creator or HUBFLUENCER_MCP_PROFILE=creator.`;
 
 const server = new McpServer(
 	{ name: "hubfluencer", version: VERSION },
@@ -662,9 +798,69 @@ type LooseRegister = (
 	config: object,
 	handler: (...args: never[]) => unknown,
 ) => void;
-const registerTool = server.registerTool.bind(
+const registerToolRaw = server.registerTool.bind(
 	server,
 ) as unknown as LooseRegister;
+const registerTool: LooseRegister = (name, config, handler) => {
+	if (!toolEnabled(activeToolProfile, name)) return;
+	const toolConfig = config as Record<string, unknown>;
+	registerToolRaw(
+		name,
+		toolConfig.outputSchema
+			? toolConfig
+			: { ...toolConfig, outputSchema: genericToolOutput },
+		handler,
+	);
+};
+
+function serverStoppedPolling(kind: Kind, status: NormalizedStatus): boolean {
+	return (
+		(kind === "editor" || kind === "short") &&
+		status.ready === false &&
+		!(typeof status.poll_after_ms === "number" && status.poll_after_ms > 0)
+	);
+}
+
+function makeVideoPollingStopNote(status: NormalizedStatus): string {
+	const actions = status.available_actions ?? [];
+	const advertised =
+		actions.length > 0
+			? `The server advertises only: ${actions.join(", ")}. Follow one of those exact actions before polling again.`
+			: "The server did not advertise a next action. Inspect generation_summary.blockers before doing anything else.";
+	const restart = actions.includes("start_generation")
+		? "start_generation is advertised, so re-running make_video is allowed after the blocker is resolved."
+		: "Do not re-run make_video: start_generation is not advertised.";
+
+	return `Polling stopped at ${status.stage}. ${status.error ?? ""} ${advertised} ${restart}`
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+async function recoverCompletedMakeVideo(
+	status: NormalizedStatus,
+	savePath: string | undefined,
+	kindInferred: boolean,
+) {
+	const videoUrl = status.video_url;
+	if (!status.ready || !videoUrl) return null;
+
+	const saved_to = savePath
+		? (await downloadTo(videoUrl, savePath)).saved_to
+		: null;
+	return ok(
+		{
+			...status,
+			kind_inferred: kindInferred,
+			charged: false,
+			replayed: true,
+			saved_to,
+			timed_out: false,
+			polling_stopped: false,
+			note: "Recovered the existing completed output. Nothing was charged.",
+		},
+		[mp4Link(videoUrl, status.slug)],
+	);
+}
 
 async function pollToTerminal(
 	client: HubfluencerClient,
@@ -674,15 +870,20 @@ async function pollToTerminal(
 	budgetMs: number,
 	intervalMs: number,
 ): Promise<NormalizedStatus> {
-	const deadline = Date.now() + budgetMs;
-	let status = await fetchStatus(client, kind, slug, deadline);
-	let n = 0;
-	while (!status.terminal && Date.now() + intervalMs <= deadline) {
-		await reportProgress(extra, ++n, `stage: ${status.stage}`);
-		await sleep(intervalMs);
-		status = await fetchStatus(client, kind, slug, deadline);
-	}
-	return status;
+	return pollWithFinalReconciliation({
+		read: (deadline) => fetchStatus(client, kind, slug, deadline),
+		isTerminal: (status) => status.terminal,
+		shouldContinue: (status) =>
+			(kind !== "editor" && kind !== "short") ||
+			(typeof status.poll_after_ms === "number" && status.poll_after_ms > 0),
+		budgetMs,
+		intervalMs: (status) =>
+			typeof status.poll_after_ms === "number"
+				? Math.min(60_000, Math.max(5_000, status.poll_after_ms))
+				: intervalMs,
+		onPoll: (status, pollNumber) =>
+			reportProgress(extra, pollNumber, `stage: ${status.stage}`),
+	});
 }
 
 /**
@@ -749,7 +950,8 @@ registerTool(
 		title: "Make a video from a prompt (one shot)",
 		description:
 			"The simplest path: give a prompt, get a finished MP4. Creates the project (free), PRICES it against " +
-			"your live credit balance, then — only if it's affordable and within max_credits — starts generation, " +
+			"your live credit balance, then — only if it's affordable, within max_credits, and the canonical " +
+			"generation_summary advertises start_generation — starts generation, " +
 			"polls to completion (emitting progress), and (if save_path is given) downloads the result. " +
 			"Spends credits (15 for a short; a multi-scene editor ad ~28). Pass dry_run:true to preview the cost " +
 			"WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " +
@@ -799,6 +1001,15 @@ registerTool(
 				.describe(
 					"EDITOR only: social_ad for promotional content (product focus + CTA) or creative_story (default).",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"EDITOR only: exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad.",
+				),
 			language: z
 				.enum(LANGUAGES)
 				.optional()
@@ -978,6 +1189,7 @@ registerTool(
 				kind?: string;
 				product_subject?: string;
 				project_intent?: string;
+				segments_count?: number;
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
@@ -1022,6 +1234,9 @@ registerTool(
 			const requestedKind =
 				args.kind === "short" || args.kind === "editor" ? args.kind : undefined;
 			const kind: Kind = requestedKind ?? inferKind(args.prompt);
+			if (kind !== "editor" && args.segments_count !== undefined) {
+				return fail("segments_count is only supported for editor videos.");
+			}
 			const waitSeconds = Math.min(
 				280,
 				Math.max(10, args.max_wait_seconds ?? 240),
@@ -1128,6 +1343,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						export_aspect_ratio: args.aspect,
@@ -1145,9 +1361,66 @@ registerTool(
 				);
 				slug = created.data.slug;
 			}
+			// A deterministic create replay may already represent accepted work.
+			// Recover that canonical run before quoting or requiring a fresh
+			// start_generation action: active/completed work must be resumed, never
+			// rejected or charged again because its cost route is no longer launchable.
+			let observedStart: ObservedGenerationAction | undefined;
+			let observationError: unknown;
+			let activeReplay = false;
+			if (!args.dry_run) {
+				try {
+					observedStart = await observedGenerationAction(
+						client,
+						kind === "short" ? "short" : "editor",
+						slug,
+						"start_generation",
+						kind === "short"
+							? {
+									workflows: ["short.generation"],
+									statuses: [
+										"idle",
+										"queued",
+										"running",
+										"failed",
+										"cancelled",
+									],
+									allowIdleAuthority: true,
+									recoverCompleted: true,
+									recoverActive: true,
+								}
+							: {
+									workflows: ["editor.autopilot"],
+									statuses: [
+										"idle",
+										"queued",
+										"running",
+										"failed",
+										"cancelled",
+									],
+									allowIdleAuthority: true,
+									recoverCompleted: true,
+									recoverActive: true,
+								},
+					);
+					const recovery = observedStart.completedStatus
+						? await recoverCompletedMakeVideo(
+								observedStart.completedStatus,
+								args.save_path,
+								requestedKind === undefined,
+							)
+						: null;
+					if (recovery) return recovery;
+					activeReplay = observedStart.activeReplay === true;
+				} catch (error) {
+					// A non-launching pricing result below can still safely return its
+					// free draft. Re-throw before any paid POST when launch is possible.
+					observationError = error;
+				}
+			}
 
 			// 2) Preflight cost vs the live balance BEFORE charging. Shorts retain
-			//    their fixed-price compatibility behavior, but an editor without a
+			//    their fixed-price behavior, but an editor without a
 			//    readable quote must never fall through to the API's uncapped launch.
 			const costPath =
 				kind === "short"
@@ -1156,18 +1429,21 @@ registerTool(
 			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,
-				);
-				estimated_credits = typeof cost.total === "number" ? cost.total : null;
-				available_credits =
-					typeof cost.available_credits === "number"
-						? cost.available_credits
-						: null;
-			} catch {
-				// The editor branch below fails closed unless the caller supplied an
-				// explicit cap that the launch endpoint can enforce independently.
+			if (!activeReplay) {
+				try {
+					const cost = asRecord(
+						asRecord(await client.get<{ data: unknown }>(costPath)).data,
+					);
+					estimated_credits =
+						typeof cost.total === "number" ? cost.total : null;
+					available_credits =
+						typeof cost.available_credits === "number"
+							? cost.available_credits
+							: null;
+				} catch {
+					// The editor branch below fails closed unless the caller supplied an
+					// explicit cap that the launch endpoint can enforce independently.
+				}
 			}
 
 			const resume =
@@ -1189,13 +1465,14 @@ registerTool(
 
 			// 3) Stop BEFORE charging on dry_run, an uncapped editor with no live
 			//    quote, an over-cap estimate, or a balance we already know is too
-			//    low. The free draft is returned so the caller can retry the quote,
-			//    top up, or raise the cap without an orphan or surprise charge.
+			//    low. An already-active replay bypasses launch admission entirely:
+			//    it is existing paid work to resume, not a new charge.
 			if (
-				args.dry_run ||
-				editorPriceUnavailableWithoutCap ||
-				overCap ||
-				!affordable
+				!activeReplay &&
+				(args.dry_run ||
+					editorPriceUnavailableWithoutCap ||
+					overCap ||
+					!affordable)
 			) {
 				const note = args.dry_run
 					? `Dry run — created a free draft and priced it (${estimated_credits ?? "?"} credits, have ${available_credits ?? "?"}). To run it: ${resume}.`
@@ -1216,69 +1493,66 @@ registerTool(
 				});
 			}
 
-			// 4) Affordable and authorized — start the charging pipeline. Read the
-			//    project's current state first and fold an anti-replay discriminator
-			//    into the start key: on a re-run AFTER a terminal failure the server's
-			//    24h idempotency cache would otherwise replay the failed run's cached
-			//    202 and never restart (the exact trap generate_short warns about).
-			//    startStateDiscriminator returns a STABLE "start" for a fresh/in-flight
-			//    project (so a transport double-send still dedupes — and the server's
-			//    already-running / 409 gate independently blocks a double charge) but a
-			//    per-attempt signature once terminally failed, so a genuine re-run mints
-			//    a fresh key and re-enqueues. Best-effort: if the read fails we fall
-			//    back to the stable "start" (the server gate remains the real guard).
-			let startState = "start";
-			try {
-				const cur = await client.get<{ data: unknown }>(
-					kind === "short" ? `/shorts/${slug}` : `/editor/${slug}`,
+			// 4) Affordable and caller-authorized — start only when the canonical
+			//    preflight above advertised start_generation. An active replay has
+			//    already been accepted and proceeds directly to polling.
+			if (!observedStart) {
+				throw (
+					observationError ??
+					new Error("Missing canonical generation authority before paid launch")
 				);
-				startState = startStateDiscriminator(kind, asRecord(cur).data);
-			} catch {
-				// status unreadable — keep the stable token (the server gate still holds)
 			}
 
-			if (kind === "short") {
-				await client.post(
-					`/shorts/${slug}/generate`,
-					// Only send a body when the caller opts out of server auto-copy —
-					// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
-					args.skip_auto_text ? { skip_auto_text: true } : undefined,
-					// gen-short:<slug> + the failure-state discriminator: a fresh/in-flight
-					// short reuses "gen-short:<slug>:start" (transport-retry dedupe), a
-					// re-run after a failed render gets a fresh key and re-renders.
-					// skip_auto_text is folded in so a bare-clip run never replays a
-					// cached auto-copy run's response (or vice versa) on the same slug.
-					`gen-short:${slug}:${startState}${args.skip_auto_text ? ":bare" : ""}`,
-				);
-			} else {
-				const approvedCap = args.max_credits ?? estimated_credits;
-				if (approvedCap === null) {
-					// Belt-and-suspenders invariant behind the fail-closed branch above:
-					// never let a future condition refactor revive an uncapped editor POST.
-					throw new Error(
-						"Editor autopilot launch requires max_credits or a live quote",
+			if (!activeReplay) {
+				const startState = startStateDiscriminator(kind, observedStart.state);
+
+				if (kind === "short") {
+					await client.post(
+						`/shorts/${slug}/generate`,
+						// Only send a body when the caller opts out of server auto-copy —
+						// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
+						args.skip_auto_text ? { skip_auto_text: true } : undefined,
+						// gen-short:<slug> + the failure-state discriminator: a fresh/in-flight
+						// short reuses "gen-short:<slug>:start" (transport-retry dedupe), a
+						// re-run after a failed render gets a fresh key and re-renders.
+						// skip_auto_text is folded in so a bare-clip run never replays a
+						// cached auto-copy run's response (or vice versa) on the same slug.
+						`gen-short:${slug}:${startState}${args.skip_auto_text ? ":bare" : ""}`,
+					);
+				} else {
+					const approvedCap = args.max_credits ?? estimated_credits;
+					if (approvedCap === null) {
+						// Belt-and-suspenders invariant behind the fail-closed branch above:
+						// never let a future condition refactor revive an uncapped editor POST.
+						throw new Error(
+							"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
+						// estimate. The API recomputes under its launch lock and rejects a
+						// price increase before any state change or charge.
+						{ max_credits: approvedCap },
+						// Fold the create-affecting params AND the failure-state discriminator
+						// into the start key so it tracks the inputs + current state, not just
+						// the slug. This key is only compared against a retry of *this* tool on
+						// *this* slug; the other autopilot entry points use a different field
+						// set/order on purpose (the server idempotency cache is scoped to
+						// path+key, and the slug — already in the path — is unique per draft),
+						// so the shapes are not meant to be interchangeable across tools.
+						// Composition lives in core.ts, shared with the golden-pin test.
+						makeVideoAutopilotKey(slug, args, startState),
 					);
 				}
-				authorizedCredits = approvedCap;
-				await client.post(
-					`/editor/${slug}/autopilot`,
-					// Use the caller's explicit cap when given, otherwise the live
-					// estimate. The API recomputes under its launch lock and rejects a
-					// price increase before any state change or charge.
-					{ max_credits: approvedCap },
-					// Fold the create-affecting params AND the failure-state discriminator
-					// into the start key so it tracks the inputs + current state, not just
-					// the slug. This key is only compared against a retry of *this* tool on
-					// *this* slug; the other autopilot entry points use a different field
-					// set/order on purpose (the server idempotency cache is scoped to
-					// path+key, and the slug — already in the path — is unique per draft),
-					// so the shapes are not meant to be interchangeable across tools.
-					// Composition lives in core.ts, shared with the golden-pin test.
-					makeVideoAutopilotKey(slug, args, startState),
-				);
 			}
 
-			await reportProgress(extra, 0, `started ${kind} ${slug}`);
+			await reportProgress(
+				extra,
+				0,
+				`${activeReplay ? "resumed" : "started"} ${kind} ${slug}`,
+			);
 			const status = await pollToTerminal(
 				client,
 				kind,
@@ -1320,10 +1594,12 @@ registerTool(
 
 			const billing =
 				kind === "short"
-					? { charged: true }
+					? { charged: true, ...(activeReplay ? { replayed: true } : {}) }
 					: {
-							launched: true,
-							authorized_credits: authorizedCredits,
+							launched: !activeReplay,
+							...(activeReplay
+								? { replayed: true }
+								: { authorized_credits: authorizedCredits }),
 							...(editorCreditsSpent === undefined
 								? {}
 								: {
@@ -1332,6 +1608,7 @@ registerTool(
 									}),
 						};
 
+			const pollingStopped = serverStoppedPolling(kind, status);
 			const result = {
 				...status,
 				kind_inferred: requestedKind === undefined,
@@ -1339,7 +1616,8 @@ registerTool(
 				available_credits,
 				...billing,
 				saved_to,
-				timed_out: !status.terminal,
+				timed_out: !status.terminal && !pollingStopped,
+				polling_stopped: pollingStopped,
 			};
 			// Thread the caller's save_path into the resume hint so the one-shot
 			// "download to this path" intent survives a mid-render timeout —
@@ -1356,17 +1634,19 @@ registerTool(
 					...result,
 					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()
-								: // 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}).`,
+						: pollingStopped
+							? makeVideoPollingStopNote(status)
+							: status.terminal
+								? 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,
 			);
@@ -1461,8 +1741,9 @@ registerTool(
 	{
 		title: "List recent projects",
 		description:
-			"Lists the caller's recent shorts and editor/video-factory projects, each normalized to " +
-			"{slug, stage, terminal, ready, video_url}. By default the shorts listing is limited to " +
+			"Lists the caller's recent shorts plus lightweight editor/video-factory discovery rows. Shorts " +
+			"carry normalized lifecycle state; generic factory rows carry {slug, kind_detail, stage, video_url} " +
+			"because that mixed-kind index has no generation_summary. By default the shorts listing is limited to " +
 			"in-progress/failed; pass include_completed:true to also surface finished shorts — useful to " +
 			"recover a lost slug. Capped to the most recent items per kind (use get_status for authoritative state).",
 		inputSchema: {
@@ -1499,23 +1780,35 @@ registerTool(
 			};
 			const shortRows = rows(shortsRaw);
 			const factoryRows = rows(factoriesRaw);
+			// Shorts already have a dedicated, summary-bearing lane above. The
+			// generic endpoint also returns their backing video_factory rows, so
+			// filter them before applying the per-kind cap: otherwise one Short is
+			// duplicated and a page of recent Shorts can crowd Editors/campaigns
+			// out of lightweight discovery entirely.
+			const genericFactoryRows = factoryRows.filter(
+				(row) => row.kind !== "short",
+			);
+			const shortTotal = asRecord(asRecord(shortsRaw).meta).total;
+			const shortsTruncated =
+				(typeof shortTotal === "number" && shortTotal > cap) ||
+				shortRows.length > cap;
 
 			const shorts = shortRows
 				.slice(0, cap)
 				.map((s) => normalizeStatus("short", String(s.slug ?? ""), s));
-			// /video-factories spans editor + campaign + creative kinds; normalize
-			// each through the editor shape so the agent gets one consistent status
-			// envelope instead of a heavy, unlabeled raw payload.
-			const projects = factoryRows.slice(0, cap).map((f) => ({
-				...normalizeStatus("editor", String(f.slug ?? ""), f),
-				kind_detail: (f.kind as string) ?? null,
-			}));
+			// /video-factories spans editor + campaign + creative kinds and its real
+			// index serializer deliberately omits generation_summary. This lane is
+			// discovery-only; never feed these rows through the fail-closed product
+			// lifecycle normalizer.
+			const projects = genericFactoryRows
+				.slice(0, cap)
+				.map(normalizeFactoryIndexProject);
 
 			return ok({
 				shorts,
 				projects,
 				note:
-					shortRows.length > cap || factoryRows.length > cap
+					shortsTruncated || genericFactoryRows.length > cap
 						? `Showing up to ${cap} per kind; more exist — raise limit or use get_status.`
 						: undefined,
 			});
@@ -2541,7 +2834,7 @@ registerTool(
 			"use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " +
 			"Safe to call again: a " +
 			"duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " +
-			"short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " +
+			"or cancelled short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " +
 			"auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " +
 			"bare clip). A transient 5xx is reconciled against the project state: accepted work is returned as " +
 			"in-progress, while an unchanged draft is retried once. Then poll with get_status or " +
@@ -2562,17 +2855,38 @@ registerTool(
 		annotations: { title: "Generate short", ...WRITE },
 	},
 	tool(async (args: { slug: string; skip_auto_text?: boolean }, client) => {
-		// No stable idempotency key (see generate_slider): a per-slug key would
-		// replay the first response for 24h and block an intentional re-generation
-		// of a failed short. Double-charge is prevented server-side — the batch
-		// claim's conditional update rolls back the losing transaction's credit
-		// deduction — and a 409 means a render is already running.
+		const observedStart = await observedGenerationAction(
+			client,
+			"short",
+			args.slug,
+			"start_generation",
+			{
+				workflows: ["short.generation"],
+				statuses: ["idle", "queued", "running", "failed", "cancelled"],
+				allowIdleAuthority: true,
+				recoverActive: true,
+			},
+		);
+		if (observedStart.activeReplay) {
+			return ok(normalizeStatus("short", args.slug, observedStart.state));
+		}
+		// This observed attempt owns one stable request key. A transport retry
+		// after a lost response sees the active run above; a genuine later rerun
+		// observes a different terminal run/revision and derives a fresh key.
+		const requestKey = idemKey(
+			"generate-short",
+			args.slug,
+			args.skip_auto_text ? "bare" : "auto-copy",
+			observedStart.summary.run_id ?? "idle",
+			String(observedStart.summary.revision ?? "idle"),
+		);
 		const submit = () =>
 			client.post<{ data: unknown }>(
 				`/shorts/${args.slug}/generate`,
 				// Only send a body when the caller opts out of server auto-copy —
 				// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
 				args.skip_auto_text ? { skip_auto_text: true } : undefined,
+				requestKey,
 			);
 
 		try {
@@ -2582,15 +2896,10 @@ registerTool(
 		} catch (e) {
 			const statusCode = (e as { status?: number }).status;
 			if (statusCode === 409) {
-				return ok({
-					kind: "short",
-					slug: args.slug,
-					stage: "processing",
-					terminal: false,
-					ready: false,
-					video_url: null,
-					error: null,
-				});
+				// A conflict says only that the POST did not start new work. Return
+				// the validated server-owned lifecycle instead of fabricating a
+				// summary-less "processing" state from the HTTP code.
+				return ok(await fetchStatus(client, "short", args.slug));
 			}
 
 			if (statusCode !== undefined && statusCode >= 500) {
@@ -2603,12 +2912,20 @@ registerTool(
 					throw e;
 				}
 
-				// Only the active render stage proves this POST crossed the paid
-				// launch transaction. A previous completed/failed result can still be
-				// visible after an early 5xx; returning it here would masquerade stale
-				// work as the newly accepted generation.
-				if (reconciled.stage === "rendering") return ok(reconciled);
-				if (reconciled.stage !== "draft") throw e;
+				// Any canonical active summary makes a blind retry unsafe: it may be
+				// the just-accepted debit or work that already owned the product.
+				if (
+					reconciled.generation_summary?.status === "queued" ||
+					reconciled.generation_summary?.status === "running"
+				) {
+					return ok(reconciled);
+				}
+				if (
+					reconciled.generation_summary?.status !== "idle" ||
+					!reconciled.available_actions?.includes("start_generation")
+				) {
+					throw e;
+				}
 
 				// A Short launch changes the durable factory out of draft in the
 				// same transaction as the debit. Still-draft therefore proves the
@@ -2620,15 +2937,7 @@ registerTool(
 					);
 				} catch (retryError) {
 					if ((retryError as { status?: number }).status === 409) {
-						return ok({
-							kind: "short",
-							slug: args.slug,
-							stage: "processing",
-							terminal: false,
-							ready: false,
-							video_url: null,
-							error: null,
-						});
+						return ok(await fetchStatus(client, "short", args.slug));
 					}
 					throw retryError;
 				}
@@ -2643,17 +2952,20 @@ registerTool(
 	{
 		title: "Cancel a running short generation",
 		description:
-			"Stops the caller-observed paid Short attempt, fences late provider callbacks, and refunds the 15-credit " +
-			"generation exactly once. Pass generation_attempt from get_status so a delayed command cannot cancel a " +
-			"newer run on the same draft. The draft is preserved for editing and regeneration. Safe to repeat with " +
-			"the same attempt after a successful cancellation. Scope: video:generate.",
+			"Stops the currently observed paid Short generation through the product-scoped cancellation route, " +
+			"fences late provider callbacks, and settles its refund exactly once. The canonical generation_run_id is " +
+			"read from get_status when omitted. The draft is preserved for editing and " +
+			"regeneration. Safe to repeat after a successful cancellation. The raw REST route requires Idempotency-Key; " +
+			"reuse one only for transport retries of this exact run. Scope: video:generate.",
 		inputSchema: {
 			slug: z.string().describe("Slug of the processing short"),
-			generation_attempt: z
-				.number()
-				.int()
-				.min(0)
-				.describe("generation_attempt from the latest get_status response"),
+			generation_run_id: z
+				.string()
+				.uuid()
+				.optional()
+				.describe(
+					"Exact run fence from get_status; normally omitted because the tool reads current status first",
+				),
 		},
 		annotations: {
 			title: "Cancel short generation",
@@ -2663,16 +2975,54 @@ registerTool(
 			idempotentHint: true,
 		},
 	},
-	tool(async (args: { slug: string; generation_attempt: number }, client) => {
-		const res = await client.post<{ data: unknown }>(
-			`/shorts/${args.slug}/cancel`,
-			{ generation_attempt: args.generation_attempt },
-			undefined,
+	tool(async (args: { slug: string; generation_run_id?: string }, client) => {
+		const observed = await observedGenerationAction(
+			client,
+			"short",
+			args.slug,
+			"cancel_generation",
+			{
+				workflows: ["short.generation"],
+				statuses: ["queued", "running", "cancelled"],
+				recoverCancelled: true,
+			},
+		);
+		const generationRunId = observed.summary.run_id;
+		if (typeof generationRunId !== "string" || generationRunId.length === 0) {
+			throw new Error(
+				"The Short response did not include a canonical run_id; refresh get_status before cancelling safely.",
+			);
+		}
+		if (
+			args.generation_run_id !== undefined &&
+			args.generation_run_id !== generationRunId
+		) {
+			throw new Error(
+				"The supplied generation_run_id does not match the authoritative Short state; refresh before cancelling.",
+			);
+		}
+		const receiptKey = idemKey(
+			"cancel-short-generation",
+			args.slug,
+			generationRunId,
 		);
-		const data = asRecord(asRecord(res).data ?? res);
+
+		const data = observed.settledReplay
+			? observed.state
+			: asRecord(
+					asRecord(
+						await client.post<{ data: unknown }>(
+							`/shorts/${args.slug}/cancel`,
+							{ generation_run_id: generationRunId },
+							receiptKey,
+						),
+					).data,
+				);
 		return ok({
 			...data,
 			slug: args.slug,
+			run_id: observed.summary.run_id,
+			workflow: observed.summary.workflow,
 			charged: false,
 			// The cancel endpoint returns the short's STATE, not a refund receipt,
 			// so don't assert refunded:true on every call — a repeat cancel is a
@@ -3176,7 +3526,8 @@ registerTool(
 			"and prices autopilot (server-orchestrated " +
 			"scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " +
 			"Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " +
-			"the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " +
+			"the paid pipeline only when max_credits is supplied, covers the estimate, and the canonical generation_summary " +
+			"advertises start_generation. Then poll with get_status / " +
 			"wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " +
 			"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 " +
@@ -3245,6 +3596,15 @@ registerTool(
 				.enum(["9:16", "16:9", "1:1"])
 				.optional()
 				.describe('Aspect ratio (default "9:16")'),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Exact number of 8-second AI scenes (3–10). Use 3 for a concise ~24s ad; omit to retain the server default.",
+				),
 			product_image_path: z
 				.string()
 				.optional()
@@ -3310,6 +3670,7 @@ registerTool(
 				theme?: string;
 				voice_id?: string;
 				export_aspect_ratio?: string;
+				segments_count?: number;
 				product_image_path?: string;
 				product_description?: string;
 				closing_image_path?: string;
@@ -3386,6 +3747,7 @@ registerTool(
 					{
 						language: args.language ?? "en",
 						product_prompt: args.product_prompt,
+						segments_count: args.segments_count,
 						product_subject: args.product_subject,
 						project_intent: args.project_intent,
 						creative_format: args.creative_format,
@@ -3464,7 +3826,9 @@ registerTool(
 				if (args.logo_path && Object.keys(logoSettings).length > 0)
 					await client.patch(`/editor/${slug}/logo`, logoSettings);
 
-				const quote = await editorAutopilotQuote(client, slug);
+				const quote = await editorAutopilotQuote(client, slug, {
+					segments_count: args.segments_count,
+				});
 				const overCap =
 					args.max_credits !== undefined &&
 					quote.estimated_credits !== null &&
@@ -3493,17 +3857,41 @@ registerTool(
 					});
 				}
 
+				// POST /editor is idempotent and may return an existing terminal draft.
+				// Re-read the canonical product authority after the quote and immediately
+				// before the chargeable launch. Legacy lifecycle columns never authorize
+				// this write, and a completed project requires the explicit restart flow.
+				const observedStart = await observedGenerationAction(
+					client,
+					"editor",
+					slug,
+					"start_generation",
+					{
+						workflows: ["editor.autopilot"],
+						statuses: ["idle", "failed", "cancelled"],
+						allowIdleAuthority: true,
+					},
+				);
+				const startState = startStateDiscriminator(
+					"editor",
+					observedStart.state,
+				);
+
 				const started = await client.post<{ data: unknown }>(
 					`/editor/${slug}/autopilot`,
-					{ max_credits: args.max_credits },
+					{
+						max_credits: args.max_credits,
+						segments_count: args.segments_count,
+					},
 					// Fold the create-affecting params into the start key so it tracks
-					// inputs, not just the slug. Self-consistent per-tool only: this key
-					// is compared against retries of *this* tool on *this* slug. The
+					// inputs plus the observed attempt, not just the slug. Self-consistent
+					// per-tool only: this key is compared against retries of *this* tool
+					// on *this* slug. The
 					// field set/order differs from make_video / start_autopilot on
 					// purpose (server cache is path+key scoped, slug is unique per
 					// draft), so the keys are not interchangeable across tools.
 					// Composition lives in core.ts, shared with the golden-pin test.
-					editorAdAutopilotKey(slug, args),
+					editorAdAutopilotKey(slug, args, startState),
 				);
 				const status = normalizeStatus("editor", slug, asRecord(started).data);
 				return ok({
@@ -3533,10 +3921,10 @@ registerTool(
 			"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 " +
+			"the tool re-reads generation_summary and starts only when start_generation is advertised, so an active run " +
+			"cannot be double-started or double-charged. Resolve any advertised retry/input action first. For a completed " +
+			"Autopilot run, set restart:true to quote and build a fresh creative run; restart:true is rejected for every " +
+			"non-completed state. Then poll with " +
 			'wait_for_completion({ slug, kind: "editor" }).',
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
@@ -3561,6 +3949,15 @@ registerTool(
 				.describe(
 					"Optional freeform brief to set/replace before launch. Omit to keep the stored brief; send blank to clear it.",
 				),
+			segments_count: z
+				.number()
+				.int()
+				.min(3)
+				.max(10)
+				.optional()
+				.describe(
+					"Optional exact number of 8-second AI scenes (3–10). Omit to keep the stored structural target.",
+				),
 			max_credits: z
 				.number()
 				.int()
@@ -3586,6 +3983,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				max_credits?: number;
 				restart?: boolean;
 			},
@@ -3601,6 +3999,7 @@ registerTool(
 				language?: string;
 				product_subject?: string;
 				product_prompt?: string;
+				segments_count?: number;
 				restart?: boolean;
 			} = {};
 			if (args.language !== undefined) overrides.language = args.language;
@@ -3608,6 +4007,8 @@ registerTool(
 				overrides.product_subject = args.product_subject;
 			if (args.product_prompt !== undefined)
 				overrides.product_prompt = args.product_prompt;
+			if (args.segments_count !== undefined)
+				overrides.segments_count = args.segments_count;
 			if (args.restart) overrides.restart = true;
 
 			const quote = await editorAutopilotQuote(client, slug, overrides);
@@ -3637,17 +4038,47 @@ registerTool(
 				});
 			}
 
+			const observedStart = await observedGenerationAction(
+				client,
+				"editor",
+				slug,
+				"start_generation",
+				{
+					workflows: ["editor.autopilot"],
+					statuses: ["idle", "failed", "cancelled", "completed"],
+					allowIdleAuthority: true,
+				},
+			);
+			if (
+				observedStart.summary.status === "completed" &&
+				args.restart !== true
+			) {
+				throw new Error(
+					"A completed Autopilot project requires restart:true for the advertised fresh start.",
+				);
+			}
+			if (
+				observedStart.summary.status !== "completed" &&
+				args.restart === true
+			) {
+				throw new Error(
+					"restart:true is valid only for a completed Autopilot generation; refresh before continuing.",
+				);
+			}
+
 			const started = await client.post<{ data: unknown }>(
 				`/editor/${slug}/autopilot`,
 				{ ...overrides, max_credits: args.max_credits },
-				// Each call is a genuine new start attempt (matching the in-app Launch
-				// button). A per-invocation nonce makes the idempotency key unique so the
-				// server's 24h idempotency cache can't replay a PRIOR start's response on
-				// a deliberate relaunch (resume after a failure / top-up). Transport-level
-				// retries of THIS call reuse this one computed key, so an accidental
-				// double-send is still deduped; a genuine double-start is independently
-				// prevented server-side by the already-running gate.
-				idemKey("autopilot", slug, randomUUID()),
+				// The observed canonical run/revision (or stable idle identity) rotates
+				// after every accepted attempt. This keeps transport retries stable while
+				// preventing an older 24h receipt from replaying over a later fresh start.
+				idemKey(
+					"autopilot",
+					slug,
+					observedStart.summary.run_id ?? "idle",
+					String(observedStart.summary.revision ?? "idle"),
+					JSON.stringify({ ...overrides, max_credits: args.max_credits }),
+				),
 			);
 			const status = normalizeStatus("editor", slug, asRecord(started).data);
 			return ok({
@@ -3670,12 +4101,13 @@ registerTool(
 	{
 		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. Before retrying you may REPAIR the one failed scene: while paused_for_retry, set_segment_prompt can " +
+			"Runs only when generation_summary advertises retry_generation for the observed Editor batch, then atomically re-queues its exact failed " +
+			"scene, preview, render, or delivery step and resumes the prepaid batch. This spends 0 additional credits: the batch generation was already " +
+			"paid. When batch_generation_failed_position names a scene, you may REPAIR that one failed scene before retrying: while paused_for_retry, set_segment_prompt can " +
 			"edit that scene's prompt (and use_previous_frame) — but only for the exact failed position the server " +
 			"names in batch_generation_failed_position (from get_editor); the rest of the paused batch stays " +
-			"mutation-locked. Explicit paused retries are capped — once the failure code is free_retries_exhausted a " +
+			"mutation-locked. A null position identifies positionless render/delivery work and is not authoring permission. " +
+			"Explicit paused scene retries are capped — once the failure code is free_retries_exhausted a " +
 			"further retry is rejected (start a fresh run instead). 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 " +
@@ -3689,18 +4121,26 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
-		const command = await observedEditorBatchCommand(client, args.slug, [
-			"paused_for_retry",
-		]);
+		const command = await observedEditorBatchCommand(
+			client,
+			args.slug,
+			"retry_generation",
+		);
 		const res = await client.post<{ data: unknown }>(
-			`/video-factories/${args.slug}/retry-batch-segment`,
+			`/editor/${args.slug}/generation/batch/retry`,
 			command,
+			idemKey(
+				"editor-batch-retry",
+				args.slug,
+				command.generation_run_id,
+				String(command.generation_revision),
+			),
 		);
 		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.",
+			note: "The exact failed batch step is queued and the prepaid batch is running. The route returns only the updated generation_summary. 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",
 		});
 	}),
@@ -3711,10 +4151,11 @@ registerTool(
 	{
 		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.",
+			"Cancels the current editor batch — pay-as-you-go or prepaid — while it is active or failed and parked for an in-place retry, including a batch parked " +
+			"needs-input on a scene review. Use this to abandon a permanent failure and unlock the project without paying for another provider retry. Completed scenes remain settled; charges for scenes that never delivered are " +
+			"refunded on settlement. Spends " +
+			"0 additional credits. The raw REST route requires Idempotency-Key; reuse one only for transport retries of " +
+			"the same observed batch command. Scope: video:generate.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: {
 			title: "Cancel editor batch",
@@ -3725,13 +4166,15 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
-		const command = await observedEditorBatchCommand(client, args.slug, [
-			"preparing",
-			"paused_for_retry",
-		]);
+		const command = await observedEditorBatchCommand(
+			client,
+			args.slug,
+			"cancel_generation",
+		);
 		const res = await client.post<{ data: unknown }>(
-			`/video-factories/${args.slug}/cancel-batch`,
-			command,
+			`/editor/${args.slug}/generation/batch/cancel`,
+			{ generation_run_id: command.generation_run_id },
+			idemKey("cancel-editor-batch", args.slug, command.generation_run_id),
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
@@ -3742,50 +4185,171 @@ registerTool(
 	}),
 );
 
-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.
+ * Reads the canonical Editor batch run fence immediately before issuing a
+ * recovery command. The API validates the run and revision under the run lock,
+ * so a replacement run or phase transition is a safe stale-command conflict.
  */
 async function observedEditorBatchCommand(
 	client: HubfluencerClient,
 	slug: string,
-	allowedStatuses: readonly EditorBatchCommandStatus[],
+	actionType: "retry_generation" | "cancel_generation",
 ): Promise<{
-	expected_batch_run_id: string | null;
-	expected_batch_status: EditorBatchCommandStatus;
+	generation_run_id: string;
+	generation_revision: number;
 }> {
-	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)
-	) {
+	const observed = await observedGenerationAction(
+		client,
+		"editor",
+		slug,
+		actionType,
+		{
+			workflows: ["editor.batch"],
+			statuses:
+				actionType === "retry_generation"
+					? ["failed", "needs_input"]
+					: ["running", "needs_input", "failed"],
+		},
+	);
+	const { summary } = observed;
+	const runId = summary.run_id;
+	if (typeof runId !== "string" || runId.trim().length === 0) {
 		throw new Error(
-			`Editor batch is not in an allowed phase (${allowedStatuses.join(" or ")}); refresh status before retrying.`,
+			"Editor generation summary did not include a canonical run id; refresh status before continuing.",
 		);
 	}
 
-	const runId = state.batch_generation_run_id;
-	if (
-		runId !== null &&
-		(typeof runId !== "string" || runId.trim().length === 0)
-	) {
+	if (summary.workflow !== "editor.batch") {
 		throw new Error(
-			"Editor state did not include a valid batch_generation_run_id; refresh status before retrying.",
+			"The current generation workflow is not the observed Editor batch; refresh before continuing.",
 		);
 	}
 
-	return {
-		expected_batch_run_id: runId,
-		expected_batch_status: status as EditorBatchCommandStatus,
+	const command: {
+		generation_run_id: string;
+		generation_revision: number;
+	} = {
+		generation_run_id: runId,
+		generation_revision: summary.revision as number,
 	};
+
+	return command;
 }
 
+registerTool(
+	"provide_generation_input",
+	{
+		title: "Resolve required generation input",
+		description:
+			"Resumes the exact Editor or Short needs-input run advertised by generation_summary. " +
+			"Use action=edit_required_input with a non-empty input object, or action=review_spend_cap " +
+			"with a higher max_credits value. The tool re-reads and sends the current run, revision, " +
+			"and blocking-step fences; stale actions fail without mutating newer work.",
+		inputSchema: {
+			kind: z.enum(["editor", "short"]),
+			slug: z.string().describe("Editor or Short project slug"),
+			action: z.enum(["edit_required_input", "review_spend_cap"]),
+			input: z
+				.record(z.string(), z.unknown())
+				.optional()
+				.describe("Required product input for edit_required_input"),
+			max_credits: z
+				.number()
+				.int()
+				.positive()
+				.max(1_000_000)
+				.optional()
+				.describe("Higher approved cap for review_spend_cap"),
+		},
+		annotations: {
+			title: "Resolve generation input",
+			...WRITE,
+			idempotentHint: true,
+		},
+	},
+	tool(
+		async (
+			args: {
+				kind: ProductKind;
+				slug: string;
+				action: "edit_required_input" | "review_spend_cap";
+				input?: Record<string, unknown>;
+				max_credits?: number;
+			},
+			client,
+		) => {
+			if (
+				args.action === "edit_required_input" &&
+				(!args.input || Object.keys(args.input).length === 0)
+			) {
+				return fail("edit_required_input requires a non-empty input object.");
+			}
+			if (
+				args.action === "review_spend_cap" &&
+				args.max_credits === undefined
+			) {
+				return fail("review_spend_cap requires max_credits.");
+			}
+
+			const observed = await observedGenerationAction(
+				client,
+				args.kind,
+				args.slug,
+				args.action,
+				{ statuses: ["needs_input"], requireStep: true },
+			);
+			const runId = observed.summary.run_id as string;
+			const revision = observed.summary.revision as number;
+			const stepKey = observed.stepKey as string;
+			const body: Record<string, unknown> = {
+				generation_run_id: runId,
+				generation_revision: revision,
+				step_key: stepKey,
+			};
+			if (args.action === "edit_required_input") body.input = args.input;
+			else body.max_credits = args.max_credits;
+
+			const endpoint =
+				args.action === "edit_required_input"
+					? "generation/input"
+					: "generation/spend-cap";
+			const productPath = args.kind === "short" ? "shorts" : "editor";
+			const requestKey = idemKey(
+				"provide-generation-input",
+				args.kind,
+				args.slug,
+				args.action,
+				runId,
+				String(revision),
+				stepKey,
+				JSON.stringify(args.input ?? {}),
+				String(args.max_credits ?? ""),
+			);
+			const response = await client.post<{ data: unknown }>(
+				`/${productPath}/${args.slug}/${endpoint}`,
+				body,
+				requestKey,
+			);
+			const resumedSummary = generationSummarySchema.safeParse(
+				asRecord(asRecord(response).data).generation_summary,
+			);
+			if (!resumedSummary.success) {
+				throw new Error(
+					`The Hubfluencer ${args.kind} recovery response did not contain a valid generation_summary. The idempotent command may already have been accepted; re-read status before continuing.`,
+				);
+			}
+
+			return ok({
+				slug: args.slug,
+				kind: args.kind,
+				action: args.action,
+				generation_summary: resumedSummary.data,
+				next: "wait_for_completion",
+			});
+		},
+	),
+);
+
 // ── AI assists (free daily quota) ───────────────────────────────────────────
 
 registerTool(
@@ -3973,6 +4537,7 @@ registerTool(
 function conciseEditorState(value: unknown): Record<string, unknown> {
 	const data = asRecord(value);
 	const keys = [
+		"generation_summary",
 		"slug",
 		"status",
 		"autopilot_status",
@@ -4028,11 +4593,12 @@ registerTool(
 	{
 		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_status, current_audio, current_music, latest_render, batch_generation_status, spend, and quota.",
+			"Returns a concise editor review projection by default. Both formats validate and include the required generation_summary lifecycle authority. Pass response_format:'full' only when all authoring details are required.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
-			response_format: z.enum(["concise", "full"]).default("full"),
+			response_format: z.enum(["concise", "full"]).default("concise"),
 		},
+		outputSchema: getEditorOutput,
 		annotations: { title: "Get editor", ...RO },
 	},
 	tool(
@@ -4041,9 +4607,23 @@ registerTool(
 			client,
 		) => {
 			const res = await client.get<{ data: unknown }>(`/editor/${args.slug}`);
-			const data = asRecord(res).data;
+			const data = asRecord(asRecord(res).data);
+			const summary = generationSummarySchema.safeParse(
+				data.generation_summary,
+			);
+			if (!summary.success) {
+				throw new Error(
+					"The Hubfluencer Editor response did not contain a valid generation_summary. Refresh after the API and MCP contracts are upgraded together.",
+				);
+			}
+			const authoritativeData = {
+				...data,
+				generation_summary: summary.data,
+			};
 			return ok(
-				args.response_format === "full" ? data : conciseEditorState(data),
+				args.response_format === "full"
+					? authoritativeData
+					: conciseEditorState(authoritativeData),
 			);
 		},
 	),
@@ -4410,15 +4990,87 @@ registerTool(
 		annotations: { title: "Generate segment", ...WRITE, idempotentHint: false },
 	},
 	tool(async (args: { slug: string; segment_id: number | string }, client) => {
+		const requestKey = idemKey(
+			"generate-segment",
+			args.slug,
+			String(args.segment_id),
+			randomUUID(),
+		);
 		const res = await client.post<{ data: unknown }>(
 			`/editor/${args.slug}/segments/${String(args.segment_id)}/generate`,
 			undefined,
-			undefined,
+			requestKey,
 		);
 		return ok(asRecord(res).data ?? res);
 	}),
 );
 
+registerTool(
+	"retry_segment_generation",
+	{
+		title: "Retry the current failed segment generation",
+		description:
+			"Retries the exact failed Editor scene step in place for 0 additional credits. This is only " +
+			"available when generation_summary advertises retry_generation for editor.scene.generate or " +
+			"editor.scene.regenerate. The tool re-reads and submits the current run, revision, and step fences, " +
+			"so it cannot retry a stale attempt or a different current scene.",
+		inputSchema: {
+			slug: z.string().describe("Editor project slug"),
+			segment_id: z
+				.union([z.number(), z.string()])
+				.describe("Failed current segment id from get_editor"),
+		},
+		annotations: {
+			title: "Retry segment generation",
+			...WRITE,
+			idempotentHint: true,
+		},
+	},
+	tool(async (args: { slug: string; segment_id: number | string }, client) => {
+		const observed = await observedGenerationAction(
+			client,
+			"editor",
+			args.slug,
+			"retry_generation",
+			{
+				workflows: ["editor.scene.generate", "editor.scene.regenerate"],
+				statuses: ["failed"],
+				requireStep: true,
+			},
+		);
+		const runId = observed.summary.run_id as string;
+		const revision = observed.summary.revision as number;
+		const stepKey = observed.stepKey as string;
+		const requestKey = idemKey(
+			"retry-segment-generation",
+			args.slug,
+			String(args.segment_id),
+			runId,
+			String(revision),
+			stepKey,
+		);
+		const response = await client.post<{ data: unknown }>(
+			`/editor/${args.slug}/segments/${String(args.segment_id)}/retry`,
+			{
+				generation_run_id: runId,
+				generation_revision: revision,
+				step_key: stepKey,
+			},
+			requestKey,
+		);
+		const data = asRecord(asRecord(response).data);
+		const retrySummary = generationSummarySchema.safeParse(
+			data.generation_summary,
+		);
+		if (!retrySummary.success) {
+			throw new Error(
+				"The Hubfluencer Editor scene-retry response did not contain a valid generation_summary. The idempotent retry may already have been accepted; re-read the Editor before continuing.",
+			);
+		}
+		return ok({ ...data, generation_summary: retrySummary.data });
+	}),
+);
+
 registerTool(
 	"cancel_segment_generation",
 	{
@@ -4428,7 +5080,8 @@ registerTool(
 			"prevents a delayed command from cancelling a newer attempt. The token is returned by get_editor. " +
 			"Refunds that scene's charge idempotently (a free retry creates no refund). Use cancel_editor_batch or " +
 			"cancel_autopilot for workflow-owned scenes. After cancellation, edit the prompt if needed and call " +
-			"generate_segment again. Scope: video:generate.",
+			"generate_segment again. The raw REST route requires Idempotency-Key; reuse one only for transport retries " +
+			"of this exact fenced cancellation. Scope: video:generate.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			segment_id: z
@@ -4456,10 +5109,41 @@ registerTool(
 			},
 			client,
 		) => {
+			const observed = await observedGenerationAction(
+				client,
+				"editor",
+				args.slug,
+				"cancel_generation",
+				{
+					workflows: ["editor.scene.generate", "editor.scene.regenerate"],
+					statuses: ["queued", "running"],
+				},
+			);
+			const segments = Array.isArray(observed.state.segments)
+				? observed.state.segments.map(asRecord)
+				: [];
+			const segment = segments.find(
+				(candidate) => String(candidate.id) === String(args.segment_id),
+			);
+			if (
+				!segment ||
+				segment.generation_claim_token !== args.generation_claim_token
+			) {
+				throw new Error(
+					"The supplied generation_claim_token does not match the scene owned by the authoritative generation action; refresh get_editor before cancelling.",
+				);
+			}
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/segments/${String(args.segment_id)}/cancel`,
 				{ expected_generation_claim_token: args.generation_claim_token },
-				undefined,
+				idemKey(
+					"cancel-segment-generation",
+					args.slug,
+					String(args.segment_id),
+					observed.summary.run_id as string,
+					String(observed.summary.revision),
+					args.generation_claim_token ?? "none",
+				),
 			);
 			return ok({
 				...asRecord(asRecord(res).data ?? res),
@@ -4476,15 +5160,14 @@ registerTool(
 	{
 		title: "Cancel a running Autopilot run",
 		description:
-			"Stops an in-flight Autopilot run on an editor project: sets autopilot_status to cancelled so the " +
-			"orchestration chain (scenario → scenes → narration → voice → music → render) advances no further. Use " +
-			"this when Autopilot is still running and you want to halt it. Any scenes already charged stay charged and " +
+			"Stops an in-flight Autopilot run only when generation_summary advertises cancel_generation for the " +
+			"editor.autopilot workflow. The orchestration chain (scenario → scenes → narration → voice → music → render) advances no further. Any scenes already charged stay charged and " +
 			"all completed work (generated scenes, voice, music, a finished render) is kept — a step already enqueued " +
-			"may still finish, but nothing new is started. Idempotent: a no-op that returns the project unchanged when " +
-			"Autopilot is not running (already completed, failed, cancelled, or never launched), so it is safe to " +
-			"repeat. It does NOT itself refund or re-run anything. For a non-Autopilot prepaid batch " +
-			"(batch_generation_status preparing / paused_for_retry) use cancel_editor_batch; to stop one " +
-			"individually-generated scene use cancel_segment_generation. Scope: video:generate.",
+			"may still finish, but nothing new is started. Transport retries are idempotent for the same observed run; " +
+			"if cancellation is no longer advertised the tool fails closed without POST. It does NOT itself refund or " +
+			"re-run anything. For an advertised Editor batch cancellation use cancel_editor_batch; to stop one " +
+			"individually-generated scene use cancel_segment_generation. The raw REST route requires Idempotency-Key. " +
+			"Scope: video:generate.",
 		inputSchema: { slug: z.string().describe("Editor project slug") },
 		annotations: {
 			title: "Cancel autopilot",
@@ -4495,14 +5178,35 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string }, client) => {
+		const observed = await observedGenerationAction(
+			client,
+			"editor",
+			args.slug,
+			"cancel_generation",
+			{
+				workflows: ["editor.autopilot"],
+				statuses: ["queued", "running"],
+			},
+		);
+		const receiptKey = idemKey(
+			"cancel-autopilot",
+			args.slug,
+			observed.summary.run_id ?? randomUUID(),
+			String(observed.summary.revision),
+		);
+
 		const res = await client.post<{ data: unknown }>(
 			`/editor/${args.slug}/autopilot/cancel`,
-			undefined,
-			undefined,
+			{
+				generation_run_id: observed.summary.run_id,
+			},
+			receiptKey,
 		);
 		return ok({
 			...asRecord(asRecord(res).data ?? res),
 			slug: args.slug,
+			run_id: observed.summary.run_id,
+			workflow: observed.summary.workflow,
 			charged: false,
 			next: "get_status",
 		});
@@ -4547,10 +5251,16 @@ registerTool(
 			args: { slug: string; segment_id: number | string; prompt?: string },
 			client,
 		) => {
+			const requestKey = idemKey(
+				"regenerate-segment",
+				args.slug,
+				String(args.segment_id),
+				randomUUID(),
+			);
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/segments/${String(args.segment_id)}/regenerate`,
 				args.prompt !== undefined ? { prompt: args.prompt } : undefined,
-				undefined,
+				requestKey,
 			);
 			return ok({
 				...asRecord(asRecord(res).data ?? res),
@@ -4589,6 +5299,7 @@ registerTool(
 		// 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 requestNonce = randomUUID();
 		const res = await client.get<{ data: unknown }>(
 			`/editor/${args.slug}`,
 			undefined,
@@ -4663,7 +5374,12 @@ registerTool(
 					await client.post(
 						`/editor/${args.slug}/segments/${String(sid)}/generate`,
 						undefined,
-						undefined,
+						idemKey(
+							"generate-all-segment",
+							args.slug,
+							String(sid),
+							requestNonce,
+						),
 					);
 				} catch (e) {
 					return ok({
@@ -4813,8 +5529,17 @@ registerTool(
 		},
 	},
 	tool(async (args: { slug: string; auto_unlock?: boolean }, client) => {
+		// Narration is non-deterministic, so each explicit tool invocation owns a
+		// fresh logical-attempt key. Keep that key outside withAssist so its one
+		// post-unlock retry reuses the same replay fence instead of forking a
+		// second narration attempt.
+		const requestKey = idemKey("generate-narration", args.slug, randomUUID());
 		const res = await withAssist(client, args.auto_unlock ?? false, () =>
-			client.post<{ data: unknown }>(`/editor/${args.slug}/generate-narration`),
+			client.post<{ data: unknown }>(
+				`/editor/${args.slug}/generate-narration`,
+				undefined,
+				requestKey,
+			),
 		);
 		return ok(asRecord(res).data ?? res);
 	}),
@@ -4899,10 +5624,11 @@ registerTool(
 			if (args.genre !== undefined) body.genre = args.genre;
 			if (args.tempo !== undefined) body.tempo = args.tempo;
 			if (args.instruments !== undefined) body.instruments = args.instruments;
+			const requestKey = idemKey("generate-music", args.slug, randomUUID());
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/generate-music`,
 				body,
-				undefined,
+				requestKey,
 			);
 			return ok({
 				...asRecord(asRecord(res).data ?? res),
@@ -4932,10 +5658,11 @@ registerTool(
 	},
 	tool(async (args: { slug: string }, client) => {
 		try {
+			const requestKey = idemKey("render-editor", args.slug, randomUUID());
 			const res = await client.post<{ data: unknown }>(
 				`/editor/${args.slug}/render`,
 				undefined,
-				undefined,
+				requestKey,
 			);
 			return ok(asRecord(res).data ?? res);
 		} catch (e) {
@@ -5102,8 +5829,44 @@ registerTool(
 		annotations: { title: "Retry render", ...WRITE, idempotentHint: false },
 	},
 	tool(async (args: { slug: string; render_id: number | string }, client) => {
+		const observed = await observedGenerationAction(
+			client,
+			"editor",
+			args.slug,
+			"retry_generation",
+			{
+				workflows: ["editor.render", "editor.render.retry"],
+				statuses: ["failed"],
+			},
+		);
+		const runId = observed.summary.run_id as string;
+		const revision = observed.summary.revision as number;
+		const rendersResponse = await client.get<{ data: unknown }>(
+			`/editor/${args.slug}/renders`,
+		);
+		const renders = asRecord(rendersResponse).data;
+		const render = Array.isArray(renders)
+			? renders
+					.map(asRecord)
+					.find((candidate) => String(candidate.id) === String(args.render_id))
+			: undefined;
+		if (render?.status !== "failed" || render.generation_run_id !== runId) {
+			throw new Error(
+				"The selected render is not the failed render owned by the current retry action; refresh list_renders before continuing.",
+			);
+		}
+
+		const requestKey = idemKey(
+			"retry-render",
+			args.slug,
+			String(args.render_id),
+			runId,
+			String(revision),
+		);
 		const res = await client.post<{ data: unknown }>(
 			`/editor/${args.slug}/renders/${String(args.render_id)}/retry`,
+			{ generation_revision: revision },
+			requestKey,
 		);
 		return ok(asRecord(res).data ?? res);
 	}),
@@ -5665,7 +6428,9 @@ registerTool(
 			treatment: z
 				.enum(["throughout", "end_card", "none"])
 				.optional()
-				.describe("When the logo appears (default throughout)"),
+				.describe(
+					"When the logo appears. Omit for automatic treatment: transparent wordmarks run throughout; opaque square artwork moves to the end card.",
+				),
 		},
 		annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false },
 	},
@@ -5690,7 +6455,7 @@ registerTool(
 				{
 					s3_key,
 					position: args.position ?? "top-right",
-					treatment: args.treatment ?? "throughout",
+					...(args.treatment ? { treatment: args.treatment } : {}),
 				},
 			);
 			return ok(asRecord(res).data ?? res);
@@ -5760,7 +6525,10 @@ registerTool(
 			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " +
 			"tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " +
 			"slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " +
-			"slide is composited, and you read the per-slide image URLs with get_slider. During paid short " +
+			"slide is composited, and you read the per-slide image URLs with get_slider. Editor/Short results also " +
+			"include the required generation_summary; normalized lifecycle fields are derived from that authority. Editor " +
+			"delivery freshness is separate: a completed stale timeline returns stage=editing_required and ready=false even " +
+			"when a historical MP4 remains. During paid short " +
 			"generation, segments_completed / segments_total and active_segment_positions report real clip progress.",
 		inputSchema: { slug: z.string(), kind: kindSchema },
 		outputSchema: getStatusOutput,
@@ -5777,13 +6545,11 @@ registerTool(
 	{
 		title: "Wait for a render to finish",
 		description:
-			"Polls status (emitting progress) until terminal or the wait budget is exhausted. " +
-			"Generation can take several minutes; if it returns terminal=false, call again to keep waiting. " +
-			"terminal=true does NOT always mean ready=true: an editor can go terminal in a needs-action stage " +
-			'(stage "editing_required" — a delivered render is stale after edits, regenerate the reported scenes/audio; ' +
-			'stage "insufficient_credits" — a batch is parked, top up or reduce scope; ' +
-			'stage "idle" — a draft with nothing generating, start generation first) that only a further tool call ' +
-			"can advance — do NOT just re-poll those. " +
+			"Polls status (emitting progress) until terminal, the server withdraws polling, or the wait budget is exhausted. " +
+			"For Editor/Short it polls only while generation_summary.timing.poll_after_ms is a positive integer; null stops polling. The " +
+			"poll_interval_seconds argument is only a fallback for tracking/slider. timed_out is true only when the client budget " +
+			"expires; polling_stopped is true when the server requests a stop so callers can invoke the advertised action immediately. " +
+			"When polling stops, inspect generation_summary.available_actions and invoke only an advertised start/retry/input/review/download action; do not derive the next command from normalized stage. " +
 			"Pass save_path to download the finished MP4 when it's ready (e.g. to resume a make_video that timed out mid-render). " +
 			'Works for kind:"slider" too, but a carousel has no MP4 — it just goes terminal when composited; read the slide ' +
 			"images with get_slider (save_path is ignored for sliders).",
@@ -5803,7 +6569,9 @@ registerTool(
 				.min(5)
 				.max(60)
 				.optional()
-				.describe("Default 15"),
+				.describe(
+					"Tracking/slider fallback interval (default 15s). Editor/Short use generation_summary.timing.poll_after_ms.",
+				),
 			save_path: z
 				.string()
 				.optional()
@@ -5849,7 +6617,13 @@ registerTool(
 				saved_to = (await downloadTo(status.video_url, args.save_path))
 					.saved_to;
 			}
-			const out = { ...status, saved_to, timed_out: !status.terminal };
+			const polling_stopped = serverStoppedPolling(args.kind, status);
+			const out = {
+				...status,
+				saved_to,
+				timed_out: !status.terminal && !polling_stopped,
+				polling_stopped,
+			};
 			const links =
 				status.ready && status.video_url
 					? [mp4Link(status.video_url, args.slug)]
@@ -6665,7 +7439,7 @@ registerTool(
 						draft_script: z.string().optional(),
 						caption: z.string().optional(),
 						hashtags: z.array(z.string()).optional(),
-						credit_estimate: z.record(z.unknown()).optional(),
+						credit_estimate: z.record(z.string(), z.unknown()).optional(),
 					}),
 				)
 				.describe("1-12 variations to persist (echo them from the board)"),
@@ -8025,17 +8799,28 @@ registerTool(
 // ── Boot ──────────────────────────────────────────────────────────────────────
 
 async function main() {
+	const args = withoutProfileArgs(process.argv.slice(2));
 	// `hubfluencer-mcp login [name]` runs the device-link login instead of the
 	// server. Single bin keeps the install idiomatic: `npx -y @hubfluencer/mcp`
 	// starts the server; `npx -y @hubfluencer/mcp login` connects an account.
-	if (process.argv[2] === "login") {
-		await runLogin(process.argv[3]);
+	if (args[0] === "login") {
+		await runLogin(args[1]);
+		return;
+	}
+	if (args[0] === "doctor") {
+		await runDoctor(activeToolProfile, args.includes("--json"));
+		return;
+	}
+	if (args[0] === "install-skill") {
+		await runInstallSkill(args);
 		return;
 	}
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 	// stderr is safe; stdout is reserved for the MCP protocol.
-	console.error("hubfluencer-mcp running on stdio");
+	console.error(
+		`hubfluencer-mcp running on stdio (profile: ${activeToolProfile})`,
+	);
 }
 
 main().catch((e) => {