@hubfluencer/mcp 0.15.0 → 0.17.0

package/src/core.ts

@@ -9,6 +9,11 @@
 
 import { createHash } from "node:crypto";
 import { isAbsolute, resolve, sep } from "node:path";
+import {
+	type GenerationSummary,
+	generationSummarySchema,
+	knownGenerationActionTypesFrom,
+} from "./generation-summary.js";
 
 export type Kind = "short" | "editor" | "tracking" | "slider";
 
@@ -265,6 +270,15 @@ export interface NormalizedStatus {
 	ready: boolean;
 	video_url: string | null;
 	error: string | null;
+	/** Stable API lifecycle contract, including the idle run_id-null state. */
+	generation_summary?: GenerationSummary;
+	/** Canonical run identity, null only for the idle projection. */
+	run_id?: string | null;
+	/** Immutable workflow identity, null for idle projections. */
+	workflow?: string | null;
+	revision?: number | null;
+	poll_after_ms?: number | null;
+	available_actions?: string[];
 	/** Short only: exact API failure phase instead of a collapsed terminal state. */
 	failed_stage?: string;
 	/** Short only: stable machine-readable terminal failure classification. */
@@ -275,8 +289,6 @@ export interface NormalizedStatus {
 	failure_source?: string;
 	/** Short only: paid generation attempt number that failed. */
 	failure_attempt?: number;
-	/** Short only: current paid attempt; echo when cancelling. */
-	generation_attempt?: number;
 	/** Short only: completed/current Veo clip count for useful long-poll progress. */
 	segments_completed?: number;
 	/** Short only: total current Veo clips in the paid attempt. */
@@ -289,6 +301,8 @@ export interface NormalizedStatus {
 	active_segment_ids?: Array<number | string>;
 	/** Editor only: completed current scene ids invalidated by continuity edits. */
 	stale_segment_ids?: Array<number | string>;
+	/** Editor Autopilot only: server-verified quoted delivery contract. */
+	autopilot_contract_satisfied?: boolean;
 	/** Short only (additive, absent on older APIs): the newest render row is a free re-render. */
 	latest_render_free?: boolean;
 	/**
@@ -299,6 +313,21 @@ export interface NormalizedStatus {
 	last_free_rerender_failed?: boolean;
 }
 
+/**
+ * Lightweight projection of one `GET /video-factories` index row.
+ *
+ * That generic endpoint spans Editor, campaign, and creative factories and does
+ * not embed `generation_summary`; it is discovery metadata, not a lifecycle
+ * read. Keep this projection deliberately tolerant and direct callers to the
+ * product-specific status tools for authoritative state.
+ */
+export interface FactoryIndexProject {
+	slug: string;
+	kind_detail: string | null;
+	stage: string;
+	video_url: string | null;
+}
+
 /** The structured fields of an API error envelope errMessage formats from. */
 export interface ApiErrorFields {
 	status: number;
@@ -318,16 +347,13 @@ export interface ApiErrorFields {
  *
  * For a 402 it surfaces the structured credit shortfall the server attaches so
  * the agent can report exactly how short it is instead of a bare sentence. The
- * canonical shape is required_credits/available_credits (tracking render +
- * editor render); it falls back to the legacy required/available keys (older
- * faceless 402s) so the counts always surface regardless of which the route
- * returns.
+ * canonical shape is required_credits/available_credits.
  */
 export function formatApiErrorMessage(f: ApiErrorFields): string {
 	const base = `API error (HTTP ${f.status}${f.code ? `, ${f.code}` : ""}): ${f.message}`;
 	const body = asRecord(f.body);
-	const req = body.required_credits ?? body.required;
-	const have = body.available_credits ?? body.available;
+	const req = body.required_credits;
+	const have = body.available_credits;
 	if (req != null || have != null) {
 		return `${base} (needs ${req ?? "?"} credits, have ${have ?? "?"}).`;
 	}
@@ -338,6 +364,118 @@ export function asRecord(v: unknown): Record<string, unknown> {
 	return v && typeof v === "object" ? (v as Record<string, unknown>) : {};
 }
 
+/** Preserves Short-specific recovery and progress fields across lifecycle projections. */
+function shortProductFields(
+	d: Record<string, unknown>,
+): Partial<
+	Pick<
+		NormalizedStatus,
+		| "failed_stage"
+		| "failure_code"
+		| "failure_details"
+		| "failure_source"
+		| "failure_attempt"
+		| "segments_completed"
+		| "segments_total"
+		| "active_segment_positions"
+		| "latest_render_free"
+		| "last_free_rerender_failed"
+	>
+> {
+	const fields: Partial<NormalizedStatus> = {};
+
+	if (typeof d.failed_stage === "string") fields.failed_stage = d.failed_stage;
+	if (typeof d.failure_code === "string") fields.failure_code = d.failure_code;
+	if (d.failure_details && typeof d.failure_details === "object") {
+		fields.failure_details = d.failure_details as Record<string, unknown>;
+	}
+	if (typeof d.failure_source === "string")
+		fields.failure_source = d.failure_source;
+	if (typeof d.failure_attempt === "number") {
+		fields.failure_attempt = d.failure_attempt;
+	}
+	if (typeof d.segments_completed === "number") {
+		fields.segments_completed = d.segments_completed;
+	}
+	if (typeof d.segments_total === "number") {
+		fields.segments_total = d.segments_total;
+	}
+	if (
+		Array.isArray(d.active_segment_positions) &&
+		d.active_segment_positions.every((position) => typeof position === "number")
+	) {
+		fields.active_segment_positions = d.active_segment_positions as number[];
+	}
+	if (typeof d.latest_render_free === "boolean") {
+		fields.latest_render_free = d.latest_render_free;
+	}
+	if (typeof d.last_free_rerender_failed === "boolean") {
+		fields.last_free_rerender_failed = d.last_free_rerender_failed;
+	}
+
+	return fields;
+}
+
+/** Preserves Editor delivery-freshness diagnostics outside lifecycle authority. */
+function editorProductFields(
+	d: Record<string, unknown>,
+	latest: Record<string, unknown>,
+): Pick<NormalizedStatus, "active_segment_ids" | "stale_segment_ids"> &
+	Partial<Pick<NormalizedStatus, "stale" | "autopilot_contract_satisfied">> {
+	const segments = Array.isArray(d.segments) ? d.segments.map(asRecord) : [];
+	const activeSegments = segments.filter((segment) => {
+		const status = segment.status;
+		const previewStatus = segment.preview_status;
+		return (
+			status === "processing" ||
+			previewStatus === "processing" ||
+			previewStatus === "generating"
+		);
+	});
+	const staleSegments = segments.filter(
+		(segment) => segment.video_stale === true && segment.status === "completed",
+	);
+	const stale =
+		latest.is_stale === true ||
+		staleSegments.length > 0 ||
+		d.narration_stale === true ||
+		d.voice_stale === true ||
+		d.music_stale === true;
+	const ids = (rows: Record<string, unknown>[]): Array<number | string> =>
+		rows
+			.map((row) => row.id)
+			.filter(
+				(id): id is number | string =>
+					typeof id === "number" || typeof id === "string",
+			);
+
+	return {
+		// A legacy render without a hash has `is_stale:null`. Preserve that as
+		// unknown instead of laundering it into stale:false/current.
+		...(stale || latest.is_stale === false ? { stale } : {}),
+		active_segment_ids: ids(activeSegments),
+		stale_segment_ids: ids(staleSegments),
+		...(typeof d.autopilot_contract_satisfied === "boolean"
+			? {
+					autopilot_contract_satisfied:
+						d.autopilot_contract_satisfied as boolean,
+				}
+			: {}),
+	};
+}
+
+export function normalizeFactoryIndexProject(
+	data: unknown,
+): FactoryIndexProject {
+	const row = asRecord(data);
+	return {
+		slug: typeof row.slug === "string" ? row.slug : "",
+		kind_detail: typeof row.kind === "string" ? row.kind : null,
+		stage: typeof row.status === "string" ? row.status : "unknown",
+		video_url: typeof row.video_url === "string" ? row.video_url : null,
+	};
+}
+
 /** Collapses the short/editor state payloads into one shape the agent can poll. */
 export function normalizeStatus(
 	kind: Kind,
@@ -346,56 +484,62 @@ export function normalizeStatus(
 ): NormalizedStatus {
 	const d = asRecord(data);
 	const latest = asRecord(d.latest_render);
-	const videoUrl = (latest.video_url as string) ?? null;
+	const videoUrl =
+		typeof latest.video_url === "string" ? latest.video_url : null;
+
+	if (kind === "short" || kind === "editor") {
+		const parsed = generationSummarySchema.safeParse(d.generation_summary);
+		if (!parsed.success) {
+			throw new Error(
+				`The Hubfluencer ${kind} response did not contain a valid generation_summary. Refresh after the API and MCP contracts are upgraded together.`,
+			);
+		}
+
+		const summary = parsed.data;
+		const terminal = [
+			"needs_input",
+			"completed",
+			"failed",
+			"cancelled",
+		].includes(summary.status);
+		const availableActions = knownGenerationActionTypesFrom(summary);
+		const editorFields =
+			kind === "editor" ? editorProductFields(d, latest) : null;
+		const productFields = editorFields ?? shortProductFields(d);
+		// `generation_summary` owns lifecycle state, but the current Editor
+		// timeline's delivery freshness is a separate product contract. A completed
+		// render artifact may remain downloadable after an edit, so the still-present
+		// `is_stale` / `*_stale` wire fields must prevent that historical MP4 from
+		// being presented as current.
+		const editingRequired =
+			kind === "editor" &&
+			summary.status === "completed" &&
+			editorFields?.stale === true;
+		const editorDeliveryFresh =
+			kind !== "editor" || editorFields?.stale === false;
+		const ready =
+			summary.status === "completed" &&
+			availableActions.includes("download_result") &&
+			!editingRequired &&
+			editorDeliveryFresh &&
+			Boolean(videoUrl);
 
-	if (kind === "short") {
-		const stage = (d.stage as string) ?? "unknown";
-		const status: NormalizedStatus = {
+		return {
 			kind,
 			slug,
-			stage,
-			terminal: stage === "video_ready" || stage === "failed",
-			ready: stage === "video_ready",
+			stage: editingRequired ? "editing_required" : summary.phase,
+			terminal,
+			ready,
 			video_url: videoUrl,
-			error: (d.error_message as string) ?? null,
+			error: summary.failure?.message ?? null,
+			generation_summary: summary,
+			run_id: summary.run_id,
+			workflow: summary.workflow,
+			revision: summary.revision,
+			poll_after_ms: summary.timing.poll_after_ms,
+			available_actions: availableActions,
+			...productFields,
 		};
-		if (typeof d.failed_stage === "string")
-			status.failed_stage = d.failed_stage;
-		if (typeof d.failure_code === "string")
-			status.failure_code = d.failure_code;
-		if (d.failure_details && typeof d.failure_details === "object")
-			status.failure_details = d.failure_details as Record<string, unknown>;
-		if (typeof d.failure_source === "string")
-			status.failure_source = d.failure_source;
-		if (typeof d.failure_attempt === "number")
-			status.failure_attempt = d.failure_attempt;
-		if (typeof d.generation_attempt === "number")
-			status.generation_attempt = d.generation_attempt;
-		if (typeof d.segments_completed === "number")
-			status.segments_completed = d.segments_completed;
-		if (typeof d.segments_total === "number")
-			status.segments_total = d.segments_total;
-		if (
-			Array.isArray(d.active_segment_positions) &&
-			d.active_segment_positions.every(
-				(position) => typeof position === "number",
-			)
-		) {
-			status.active_segment_positions = d.active_segment_positions as number[];
-		}
-		// Additive free-re-render bookkeeping (2026-07 API): surfaced only when
-		// the server actually sends the booleans, so older payloads normalize
-		// byte-identically. A failed free re-render does NOT flip stage to
-		// "failed" server-side — the delivered video stays visible — so these
-		// flags are the only signal that the newest render row was a free
-		// re-render (or a failed one worth retrying, still free).
-		if (typeof d.latest_render_free === "boolean") {
-			status.latest_render_free = d.latest_render_free;
-		}
-		if (typeof d.last_free_rerender_failed === "boolean") {
-			status.last_free_rerender_failed = d.last_free_rerender_failed;
-		}
-		return status;
 	}
 
 	if (kind === "tracking") {
@@ -443,355 +587,114 @@ export function normalizeStatus(
 		};
 	}
 
-	// editor. A completed render is only "ready" when it still represents the
-	// CURRENT timeline and no newer scene/audio work is active or stale. The API
-	// intentionally keeps the last successful MP4 available after edits; treating
-	// that historical delivery as current made get_status/wait_for_completion
-	// return immediately while paid regenerations were still running.
-	const autopilot = (d.autopilot_status as string) ?? "unknown";
-	const renderStatus = (latest.status as string) ?? null;
-	const segments = Array.isArray(d.segments) ? d.segments.map(asRecord) : [];
-	// "Active" means a scene is genuinely mid-generation. Crucially it must NOT
-	// include the *idle* defaults: segment.status "pending" and preview_status
-	// "pending" are the never-generated / cleared-preview defaults the API stamps
-	// on every fresh scene (video_segment.ex: status default "pending",
-	// preview_status default "pending"). Counting either as active made a fully
-	// idle draft report stage "segment_processing" with every scene in
-	// active_segment_ids, so wait_for_completion burned its whole budget on a
-	// project that isn't generating anything. The real in-flight states are
-	// segment.status "processing" and preview_status "generating" (its wire enum
-	// is pending|generating|completed|failed|stale — "processing" is kept only as
-	// a defensive alias, it never appears).
-	const activeSegments = segments.filter((segment) => {
-		const status = segment.status as string | undefined;
-		const preview = segment.preview_status as string | undefined;
-		return (
-			status === "processing" ||
-			preview === "processing" ||
-			preview === "generating"
-		);
-	});
-	const staleSegments = segments.filter(
-		(segment) => segment.video_stale === true && segment.status === "completed",
-	);
-	const failedSegments = segments.filter(
-		(segment) => segment.status === "failed",
-	);
-	const batchStatus = (d.batch_generation_status as string) ?? null;
-	// The batch enum's ACTIVE states (video_factory.ex): preparing (spinning up),
-	// awaiting_previews (previews generating), and running. "queued" is not a real
-	// value and was dropped. paused_for_retry is deliberately NOT active: no worker
-	// owns it until the user explicitly retries or cancels the paused batch.
-	const batchActive =
-		batchStatus === "running" ||
-		batchStatus === "preparing" ||
-		batchStatus === "awaiting_previews";
-	// The scene batch commits `completed` before the durable auto-render handoff
-	// creates its VideoResult row. While the persisted intent remains armed, the
-	// server still owns the project and a reconciler may create the render at any
-	// moment. Treat that narrow gap as active work so wait_for_completion cannot
-	// return an idle/terminal result just before the render appears.
-	const autoRenderHandoffActive =
-		batchStatus === "completed" && d.auto_render_after_batch === true;
-	const batchRetryRequired = batchStatus === "paused_for_retry";
-	// A parked batch that ran out of credits: it cannot progress without the user
-	// topping up or reducing scope, so it is a needs-user-action TERMINAL state
-	// (not active work to wait on).
-	const batchInsufficientCredits =
-		batchStatus === "paused_insufficient_credits";
-	const batchFailed = batchStatus === "failed";
-	const autopilotActive = [
-		"pending",
-		"running",
-		"generating",
-		"rendering",
-	].includes(autopilot);
-	const audioStale =
-		d.narration_stale === true ||
-		d.voice_stale === true ||
-		d.music_stale === true;
-	const renderStale = latest.is_stale === true;
-	// Only an explicit false proves the completed render matches the live editor.
-	// Legacy/null/omitted freshness is unknown and must never be promoted to ready.
-	const renderFresh = latest.is_stale === false;
-	const stale = renderStale || staleSegments.length > 0 || audioStale;
-	// A render in flight is active work too — fold it into workActive so the
-	// terminal computation below can never fire while a render is queued/running.
-	// "pending" here is NOT an idle default: a video_results row only exists once
-	// a render was actually requested, so a pending latest render is queued work.
-	const renderActive =
-		renderStatus === "pending" ||
-		renderStatus === "rendering" ||
-		renderStatus === "processing";
-	// Scenario text generation / scenario apply run as async workers too
-	// (scenario_status: none|generating|ready|failed; scenario_apply_status:
-	// idle|pending|applying|failed) — count them as active so a wait right after
-	// generate_scenario/apply_scenario doesn't bail out as an "idle" draft.
-	const scenarioActive =
-		d.scenario_status === "generating" ||
-		d.scenario_apply_status === "pending" ||
-		d.scenario_apply_status === "applying";
-	// Narration generation is a distinct async worker that runs before an
-	// AudioVersion exists. Without this gate, a project with an older completed
-	// render looks ready/terminal during narration regeneration and
-	// wait_for_completion can return that old MP4 while the new script is still
-	// being produced.
-	const narrationActive = d.narration_status === "generating";
-	const scenarioFailed = d.scenario_status === "failed";
-	const scenarioApplyFailed = d.scenario_apply_status === "failed";
-	const narrationFailed = d.narration_status === "failed";
-	// First-time generation is visible through the current selection. A
-	// regeneration intentionally keeps the prior completed version current until
-	// the replacement lands, so inspect the version histories as well; otherwise
-	// an old matching render can look ready while a paid replacement is running.
-	const currentAudio = asRecord(d.current_audio);
-	const currentMusic = asRecord(d.current_music);
-	const audioVersions = Array.isArray(d.audio_versions)
-		? d.audio_versions.map(asRecord)
-		: [];
-	const musicVersions = Array.isArray(d.music_versions)
-		? d.music_versions.map(asRecord)
-		: [];
-	const numericVersion = (version: unknown): number =>
-		typeof version === "number" && Number.isFinite(version) ? version : 0;
-	const selectedAudioVersion = numericVersion(currentAudio.version);
-	const selectedMusicVersion = numericVersion(currentMusic.version);
-	const newerAudioVersions = audioVersions.filter(
-		(version) => numericVersion(version.version) > selectedAudioVersion,
-	);
-	const newerMusicVersions = musicVersions.filter(
-		(version) => numericVersion(version.version) > selectedMusicVersion,
-	);
-	const versionActive = (version: Record<string, unknown>) =>
-		version.status === "pending" || version.status === "processing";
-	const newestVersion = (versions: Array<Record<string, unknown>>) =>
-		versions.reduce<Record<string, unknown> | null>((latest, version) => {
-			if (!latest) return version;
-			return numericVersion(version.version) > numericVersion(latest.version)
-				? version
-				: latest;
-		}, null);
-	const newestReplacementAudio = newestVersion(newerAudioVersions);
-	const newestReplacementMusic = newestVersion(newerMusicVersions);
-	const audioFailed =
-		currentAudio.status === "failed" ||
-		currentMusic.status === "failed" ||
-		newestReplacementAudio?.status === "failed" ||
-		newestReplacementMusic?.status === "failed";
-	const audioError = [
-		newestReplacementAudio?.error_message,
-		newestReplacementMusic?.error_message,
-		currentAudio.error_message,
-		currentMusic.error_message,
-	].find(
-		(value): value is string =>
-			typeof value === "string" && value.trim().length > 0,
-	);
-	const audioActive =
-		currentAudio.status === "pending" ||
-		currentAudio.status === "processing" ||
-		currentMusic.status === "pending" ||
-		currentMusic.status === "processing" ||
-		newerAudioVersions.some(versionActive) ||
-		newerMusicVersions.some(versionActive);
-	const childWorkActive =
-		batchActive ||
-		autoRenderHandoffActive ||
-		renderActive ||
-		scenarioActive ||
-		narrationActive ||
-		audioActive ||
-		activeSegments.length > 0;
-	// A resumed Autopilot briefly exposes the previous attempt's failed child
-	// states before its new worker reaches and clears them. Suppress that history
-	// only while real child work is active or for a short, timestamped hand-off
-	// window. A parent stuck "running" with no worker must eventually surface the
-	// child failure instead of making wait_for_completion poll forever.
-	const autopilotStartedAt =
-		typeof d.autopilot_started_at === "string"
-			? Date.parse(d.autopilot_started_at)
-			: Number.NaN;
-	const now = Date.now();
-	const autopilotResumeGraceActive =
-		autopilotActive &&
-		Number.isFinite(autopilotStartedAt) &&
-		autopilotStartedAt <= now &&
-		now - autopilotStartedAt <= 120_000;
-	const autopilotFailed = autopilot === "failed" || autopilot === "cancelled";
-	// Retrying a paused batch deliberately leaves the failed parent Autopilot
-	// marker in place while the already-paid child batch finishes. In that one
-	// state combination the parent/old scene failures are history, not a reason
-	// to return terminal immediately. Once the batch settles, the parent failure
-	// becomes actionable again and the agent can quote/relaunch Autopilot.
-	const batchRecoveryActive = autopilotFailed && batchActive;
-	const childFailureActionable =
-		!batchRecoveryActive &&
-		(!autopilotActive || (!childWorkActive && !autopilotResumeGraceActive));
-	const workActive = autopilotActive || childWorkActive;
-	// Orchestration failures are historical once a repaired timeline has a fresh,
-	// completed MP4. Keeping them terminal would permanently block download_result
-	// after a successful granular recovery.
-	const deliveredArtifactSupersedesOrchestrationFailure =
-		renderStatus === "completed" &&
-		Boolean(videoUrl) &&
-		renderFresh &&
-		!stale &&
-		!workActive &&
-		failedSegments.length === 0 &&
-		!audioFailed;
-	const ready = deliveredArtifactSupersedesOrchestrationFailure;
-	const parentFailureActionable = autopilotFailed && !batchRecoveryActive;
-	const renderFailed = renderStatus === "failed" && childFailureActionable;
-	const failed =
-		(parentFailureActionable &&
-			!deliveredArtifactSupersedesOrchestrationFailure) ||
-		renderFailed ||
-		(childFailureActionable &&
-			scenarioApplyFailed &&
-			!deliveredArtifactSupersedesOrchestrationFailure) ||
-		(childFailureActionable &&
-			scenarioFailed &&
-			!deliveredArtifactSupersedesOrchestrationFailure) ||
-		(childFailureActionable &&
-			narrationFailed &&
-			!deliveredArtifactSupersedesOrchestrationFailure) ||
-		(childFailureActionable &&
-			batchFailed &&
-			!deliveredArtifactSupersedesOrchestrationFailure) ||
-		(childFailureActionable && failedSegments.length > 0) ||
-		(childFailureActionable && audioFailed);
-	// Terminal = control should return to the agent because nothing will progress
-	// without another tool call. With every async job type folded into workActive
-	// above (autopilot, batch, segments, scenario, narration, audio, render), NO
-	// work active means exactly that — whether the project is ready, failed,
-	// stale (editing_required), parked on credits, or a pristine idle draft, only
-	// a new tool call can move it, so wait_for_completion must return instead of
-	// polling its full budget. (ready is subsumed by !workActive but kept for
-	// clarity; explicit failure states are terminal even while cleanup work spins.)
-	const terminal =
-		ready ||
-		failed ||
-		batchRetryRequired ||
-		batchInsufficientCredits ||
-		!workActive;
-	let stage = autopilot;
-	// Failure always wins over an unrelated active flag. Workers can leave an
-	// outer autopilot/batch state active after a child stage has failed; reporting
-	// the active stage would make agents poll forever instead of taking action.
-	if (ready) stage = "completed";
-	// A paused child batch is the immediate recovery gate even when its parent
-	// Autopilot run has already failed/cancelled. Reporting only the generic
-	// parent terminal state hides the one action that must happen before a new
-	// Autopilot run is allowed to start.
-	else if (batchRetryRequired) stage = "batch_retry_required";
-	else if (parentFailureActionable && autopilot === "failed") stage = "failed";
-	else if (parentFailureActionable && autopilot === "cancelled")
-		stage = "cancelled";
-	else if (renderFailed) stage = "render_failed";
-	else if (childFailureActionable && scenarioApplyFailed)
-		stage = "scenario_apply_failed";
-	else if (childFailureActionable && scenarioFailed) stage = "scenario_failed";
-	else if (childFailureActionable && narrationFailed)
-		stage = "narration_failed";
-	else if (childFailureActionable && batchFailed) stage = "batch_failed";
-	else if (childFailureActionable && failedSegments.length > 0)
-		stage = "segment_failed";
-	else if (childFailureActionable && audioFailed) stage = "audio_failed";
-	else if (batchInsufficientCredits) stage = "insufficient_credits";
-	else if (activeSegments.length > 0) stage = "segment_processing";
-	else if (batchActive) stage = "segment_generation";
-	else if (autoRenderHandoffActive) stage = "rendering";
-	else if (renderActive) stage = "rendering";
-	else if (scenarioActive) stage = "scenario_processing";
-	else if (narrationActive) stage = "narration_processing";
-	else if (audioActive) stage = "audio_processing";
-	else if (!workActive && stale) stage = "editing_required";
-	const segmentError = failedSegments
-		.map((segment) => segment.error_message)
-		.find(
-			(value): value is string => typeof value === "string" && value.length > 0,
+	throw new Error(`Unsupported Hubfluencer project kind: ${String(kind)}`);
+}
+
+export class GenerationStartStateContractError extends Error {
+	constructor(reason: string) {
+		super(
+			`Invalid canonical generation summary for start discrimination: ${reason}`,
 		);
-	const actionableChildError = childFailureActionable
-		? ((latest.error_message as string) ??
-			(d.scenario_apply_error_message as string) ??
-			(d.scenario_error_message as string) ??
-			(d.narration_error_message as string) ??
-			(d.batch_generation_error_message as string) ??
-			segmentError ??
-			audioError)
-		: null;
-	return {
-		kind,
-		slug,
-		stage,
-		terminal,
-		ready,
-		video_url: videoUrl,
-		error: ready
-			? null
-			: batchRetryRequired
-				? "Batch generation is paused after a failed scene. Call retry_editor_batch or cancel_editor_batch before continuing."
-				: ((parentFailureActionable
-						? (d.autopilot_error_message as string)
-						: null) ??
-					actionableChildError ??
-					(batchInsufficientCredits
-						? "Batch generation paused: not enough credits to finish. Top up or reduce scope, then invoke the generation/render path again; retry_editor_batch only applies to paused_for_retry."
-						: null)),
-		stale,
-		active_segment_ids: activeSegments
-			.map((segment) => segment.id)
-			.filter(
-				(id): id is number | string =>
-					typeof id === "number" || typeof id === "string",
-			),
-		stale_segment_ids: staleSegments
-			.map((segment) => segment.id)
-			.filter(
-				(id): id is number | string =>
-					typeof id === "number" || typeof id === "string",
-			),
-	};
+		this.name = "GenerationStartStateContractError";
+	}
 }
 
 /**
- * A discriminator folded into make_video's start idempotency key so a re-run
- * AFTER a terminal failure genuinely restarts instead of replaying the failed
- * run's cached 202 for 24h (the server caches idempotent POSTs). Mirrors the
- * tracking render key's anti-replay design (which folds the failed result id):
+ * Canonical discriminator folded into make_video's start idempotency key.
  *
- *   - Not terminally failed (fresh draft, in flight, or completed) → "start", a
- *     STABLE token. A transport retry of the same start therefore reuses the key
- *     and dedupes (a double-start is also independently blocked server-side by
- *     the already-running / 409 gate), so no double charge.
- *   - Terminally failed → a signature of the per-attempt-varying render
- *     id/version (plus the failure step/stage), so a re-run reads the failed
- *     state, mints a DIFFERENT key, and re-enqueues the pipeline. Each subsequent
- *     rendered failure changes latest_render.id, so successive retries keep
- *     minting fresh keys rather than replaying a dead 202.
+ * The stable `start` token deliberately survives idle, accepted/nonterminal,
+ * completed, and non-restartable terminal snapshots. That preserves exact
+ * transport replay of the original logical start. Only a terminal snapshot
+ * which explicitly advertises the server-owned `start_generation` capability
+ * mints a new key, using canonical run/revision/failure identity. Product detail
+ * fields are never consulted here.
  *
- * Pure: derived solely from the status payload the caller already fetched.
+ * A response that is missing or violates the stable summary contract fails
+ * closed. Starting chargeable work without a trustworthy authority snapshot
+ * would turn a contract/version outage into an unsafe new intent.
  */
 export function startStateDiscriminator(kind: Kind, data: unknown): string {
-	const d = asRecord(data);
-	const latest = asRecord(d.latest_render);
-	const renderSig = `${latest.id ?? ""}:${latest.version ?? ""}`;
+	if (kind !== "short" && kind !== "editor") {
+		throw new GenerationStartStateContractError(`unsupported product ${kind}`);
+	}
 
-	if (kind === "short") {
-		const stage = (d.stage as string) ?? "";
-		if (stage !== "failed") return "start";
-		return `failed:${d.failed_stage ?? ""}:${renderSig}`;
+	const parsed = generationSummarySchema.safeParse(
+		asRecord(data).generation_summary,
+	);
+	if (!parsed.success) {
+		throw new GenerationStartStateContractError(
+			"missing or malformed generation_summary",
+		);
 	}
 
-	// editor
-	const autopilot = (d.autopilot_status as string) ?? "";
-	const renderStatus = (latest.status as string) ?? "";
-	const failed =
-		autopilot === "failed" ||
-		autopilot === "cancelled" ||
-		renderStatus === "failed";
-	if (!failed) return "start";
-	return `failed:${autopilot}:${d.autopilot_error_step ?? ""}:${renderSig}`;
+	const summary = parsed.data;
+	validateSummaryProduct(kind, summary);
+
+	const restartAvailable = summary.available_actions.some(
+		(action) => action.type === "start_generation",
+	);
+	const restartableTerminal =
+		restartAvailable &&
+		(summary.status === "failed" || summary.status === "cancelled");
+
+	if (!restartableTerminal) return "start";
+
+	const attemptIdentity = terminalAttemptIdentity(summary);
+	return `restart:${idemKey(
+		"generation-restart",
+		kind,
+		attemptIdentity,
+		summary.workflow ?? "",
+		String(summary.workflow_version ?? ""),
+		String(summary.revision ?? ""),
+		summary.status,
+		summary.failure?.code ?? "",
+	)}`;
+}
+
+function validateSummaryProduct(
+	kind: "short" | "editor",
+	summary: GenerationSummary,
+): void {
+	if (summary.status === "idle") {
+		if (summary.run_id !== null || summary.workflow !== null) {
+			throw new GenerationStartStateContractError(
+				"idle summary carries run identity",
+			);
+		}
+		return;
+	}
+
+	const workflow = summary.workflow;
+	if (workflow === null) {
+		throw new GenerationStartStateContractError(
+			"non-idle summary has no workflow",
+		);
+	}
+
+	const belongsToProduct =
+		kind === "short"
+			? workflow.startsWith("short.")
+			: workflow.startsWith("editor.");
+	if (!belongsToProduct) {
+		throw new GenerationStartStateContractError("workflow/product mismatch");
+	}
+
+	if (summary.run_id === null) {
+		throw new GenerationStartStateContractError(
+			"run identity/workflow mismatch",
+		);
+	}
+}
+
+function terminalAttemptIdentity(summary: GenerationSummary): string {
+	if (summary.run_id === null) {
+		throw new GenerationStartStateContractError(
+			"restartable terminal summary has no durable attempt identity",
+		);
+	}
+
+	return summary.run_id;
 }
 
 /** Stable idempotency key for a logical operation, so a retried call is safe. */
@@ -817,6 +720,7 @@ export function idemKey(...parts: string[]): string {
 /** make_video's editor draft-create key (`POST /editor`). */
 export interface MakeVideoEditorCreateArgs {
 	prompt: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -831,6 +735,7 @@ export function makeVideoEditorCreateKey(a: MakeVideoEditorCreateArgs): string {
 	return idemKey(
 		"make-editor",
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -857,6 +762,7 @@ export function makeVideoAutopilotKey(
 		"autopilot",
 		slug,
 		a.prompt,
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -872,6 +778,7 @@ export function makeVideoAutopilotKey(
 /** create_editor_ad's draft-create and autopilot-start key argument set. */
 export interface EditorAdKeyArgs {
 	product_prompt?: string;
+	segments_count?: number;
 	product_subject?: string;
 	project_intent?: string;
 	language?: string;
@@ -906,6 +813,7 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 	return idemKey(
 		"create-editor",
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -931,18 +839,22 @@ export function editorAdCreateKey(a: EditorAdKeyArgs): string {
 
 /**
  * create_editor_ad's autopilot-start key (`POST /editor/:slug/autopilot`). Folds
- * the create params AND the approved max_credits cap. There is no startState
- * discriminator (this tool starts right after create, so there is no prior
- * terminal state to guard against), so max_credits is what lets a re-call with a
- * RAISED cap after a failed/over-cap launch mint a fresh key and re-enqueue
- * rather than replay the server's 24h-cached dead 202. Self-consistent per-tool
- * only.
+ * the create params, approved max_credits cap, AND the canonical start-state
+ * discriminator observed immediately before launch. The create endpoint is
+ * idempotent and can return an existing failed/cancelled draft, so the start key
+ * must rotate with that durable attempt identity instead of replaying an older
+ * 24h-cached 202. Self-consistent per-tool only.
  */
-export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
+export function editorAdAutopilotKey(
+	slug: string,
+	a: EditorAdKeyArgs,
+	startState: string,
+): string {
 	return idemKey(
 		"autopilot",
 		slug,
 		a.product_prompt ?? "",
+		a.segments_count === undefined ? "" : String(a.segments_count),
 		a.product_subject ?? "",
 		a.project_intent ?? "",
 		a.language ?? "en",
@@ -961,6 +873,7 @@ export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
 			? ""
 			: String(a.logo_duration_seconds),
 		a.max_credits === undefined ? "" : String(a.max_credits),
+		startState,
 	);
 }