cozyclay 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## Unreleased
+
+## 2.1.0 - 2026-10-12
+
+Storyboard and Animation modes. A project is now either a storyboard (a row of
+still panels) or an animation (moving shots); both are on in a normal launch.
+
+Modes
+
+- The start screen has a Storyboard / Animation control, the project keeps its
+  mode through save and reopen, and the top bar shows it as a badge. A
+  storyboard project hides the Generate group and Motion mode (`4`); motion
+  commands are refused with a reason instead of failing quietly. (#649, #650)
+- The bottom dock has a **Board** tab in storyboard projects: one card per
+  panel with a greybox thumbnail, caption, hold, duplicate, delete and
+  drag-to-reorder. Each panel can keep its own cast placement. (#640, #641)
+- **Stylize** turns a panel into a finished picture through the image route
+  and keeps it in the project beside the greybox; **Send to Workflow** puts
+  the stylized image or the greybox on a Workflow canvas with a connected
+  Video node. (#643, #645)
+
+Capsule figures
+
+- A rigless **Capsule figure** joins the Assets tile list for blocking: stand,
+  sit or lie, set in Details. It follows root paths in the viewport and in
+  exports. Rig-only tools (Pose, IK, motion, take import, physics) refuse it
+  and say why. (#634, #635)
+
+Storyboard exports
+
+- The Export menu of a storyboard lists **Contact sheet (PNG)**, **Panel pack
+  (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and
+  **Depth + normal (PNG)**. File ▸ **Export as Animation project…** turns the
+  panels into an Animation project. Keyframe pack and shot video stay
+  Animation-only.
+
+Agent and MCP
+
+- In a storyboard project the Studio Agent adds one panel per request, frames
+  it and never generates motion; the Studio context and `describe_scene` now
+  report the project mode and each character's kind. (#637, #642)
+- MCP motion tools answer `NOT_IN_MODE` in a storyboard and
+  `TARGET_NOT_READY` on a capsule figure; `add_character` takes a model and
+  posture. (#652)
+
+Analytics and docs
+
+- Three counts-only events: `storyboard:panel_created` (`source`),
+  `storyboard:panel_stylized` (`outcome`) and `cast:proxy_added`
+  (`surface`); `scene:created` carries `previs_mode`, and the export
+  `export_kind` vocabulary gains `contact_sheet`, `panel_pack`, `animatic`
+  and `animation_project`. Captions, names and prompts are never properties.
+  Disclosed in `docs/privacy.md` and `docs/analytics-queries.md`. (#653)
+- README has a **Modes** section; the Agent rules, the Studio IA and the
+  capsule-figure notes are updated. (#653)
+
 ## 2.0.2
 
 The first-run audit release: `npx cozyclay` is exercised end to end as a new

package/README.md

@@ -52,7 +52,7 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 
 |  | |
 | --- | --- |
-| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with the transform strip's gizmo. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye Top-View drives 2D root waypoints for character paths. **View ▾** on the viewport bar holds the reference grid and Auto Color — Blender's random viewport color, so twenty grey blockout boxes stay tellable apart without touching the colors you authored (captures include the display colors while it is on). |
+| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with the transform strip's gizmo. Cast people from **Assets › Characters**: a rigged character you can pose and animate, or a **Capsule figure** — a rigless stand-in with one posture (stand, sit or lie) chosen in Details, for blocking where nobody needs to move their limbs. Capsule figures follow root paths and per-panel placements like any character but refuse pose, IK and motion tools, with the reason in the tooltip. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye Top-View drives 2D root waypoints for character paths. **View ▾** on the viewport bar holds the reference grid and Auto Color — Blender's random viewport color, so twenty grey blockout boxes stay tellable apart without touching the colors you authored (captures include the display colors while it is on). |
 | **Fly the camera** | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, `F` frames — the muscle memory you already have from a 3D editor. Fly, pan and orbit lock the pointer for the hold, so the view can turn past the window edge. Selecting the camera switches to Camera mode. **Look through** in the Shot monitor puts you behind the shot camera with the same bindings; click the on-screen **Shot camera** indicator or press `Esc` to return to the free camera. |
 | **Cut and move the camera** | Add shots on the timeline, draw a dolly rail on the Top-View, set speed, height and crane, and preview the move through the shot camera. Each shot carries a **Target model** (Seedance 2.5, Kling 2, Veo 3, self-hosted MiniMax-H3) and is flagged when the cut runs past that model's limits. |
 | **Export for AI video** | One **Export ▾** menu: a keyframe pack (first/last frame, clip, camera JSON, prompt, README) as a zip, an mp4 of the shot, depth + normal conditioning passes, a storyboard contact sheet, and an OTIO cut list. Seedance 2.5 reads the pack's greybox clip as its white-model reference video, and MiniMax H3, Wan 3.0, LTX Desktop and fal render-to-real accept the same clip. The **Shot Prompt** turns the framing into a structured prompt for the model you picked. |
@@ -61,6 +61,21 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 | **Capture motion from video or a photo** | Drop a clip or a still: the GPU box runs [GVHMR](https://github.com/zju3dv/GVHMR) and the result is retargeted onto the character with stabilisation, contact correction and a quality gate. |
 | **Direct it with an AI** | Open the **Agent panel** (`Cmd/Ctrl+B`), sign in with your ChatGPT account, and ask for a shot in plain language; the conversation survives reloads and you can paste a reference screenshot into it. Or connect Claude — or any MCP client — or drive the Studio from a terminal with `cclay live`. All three place the cast, frame "a low wide profile", generate multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control). |
 
+## Modes
+
+A project is either a **Storyboard** or an **Animation**. Pick it on the start screen (the badge in the top bar shows which one you are in); a project keeps its mode when saved and reopened.
+
+| | Storyboard | Animation |
+| --- | --- | --- |
+| **Choose it when** | You want a row of still panels: framing, who stands where, a caption and a hold per panel | You want moving shots: motion on a timeline, camera moves, takes |
+| **Timeline** | The **Board** dock tab: one card per panel with a greybox thumbnail, caption, hold, duplicate, delete and drag-to-reorder | Shots on the timeline, with motion and Prompt Blocks |
+| **Cast** | Rigged characters or capsule figures; each panel can keep its own placement ("Use stage placement" clears it) | Rigged characters with Pose and Motion mode; capsule figures for blocking |
+| **Motion tools** | Hidden: no Generate group, no Motion mode (`4`); the agent has no `generate_motion` and the MCP motion tools answer `NOT_IN_MODE` | Available |
+| **Agent** | **Agent · Storyboard** builds one panel per request and never generates motion | The full Studio tool set |
+| **Exports** | **Stylize** a panel through the image route, **Send to Workflow** (the stylized image or the greybox) from its card, plus the Export ▾ menu: **Contact sheet (PNG)**, **Panel pack (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and **Depth + normal (PNG)**; File ▸ **Export as Animation project…** turns the panels into an Animation. There is no keyframe pack or shot video in a storyboard | Export ▾: keyframe pack, mp4, depth + normal passes, contact sheet, OTIO cut list |
+
+Start in Storyboard when you are deciding what the shots are, then open the idea as an Animation when it needs motion.
+
 ## Quick start
 
 You need Node.js 22.19 or newer, npm or bun, and a Chromium-based browser.
@@ -182,7 +197,7 @@ Every control's home is recorded in [`docs/studio-ui-ia.md`](docs/studio-ui-ia.m
 | --- | --- |
 | [`docs/kimodo-setup.md`](docs/kimodo-setup.md) | Installing Kimodo: the route table, CUDA over SSH, local MLX/Metal/CPU generation and what each route supports |
 | [`docs/agent-cli.md`](docs/agent-cli.md) | Driving the Studio from a terminal with `cclay live` |
-| [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking |
+| [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking, and the one-panel-per-request rule in storyboards |
 | [`mcp/README.md`](mcp/README.md) | MCP tools, transports, and the live-control protocol |
 | [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md) | Where every Studio control lives and why |
 | [`docs/privacy.md`](docs/privacy.md) | The full analytics disclosure: events, identifiers, opt-out, internal QA marking |

package/THIRD_PARTY_NOTICES.md

@@ -165,6 +165,14 @@ Their transitive runtime dependencies, which the agent sidecar also loads, are:
 - `ignore` — License: MIT — https://github.com/kaelzhang/node-ignore
 - `yaml` — License: ISC — https://github.com/eemeli/yaml
 
+## jpeg-js
+
+The MCP runtime decodes JPEG reference images for `compare_sculpt` with `jpeg-js`, on the local machine.
+
+- Copyright (c) 2014, Eugene Ware and Adobe
+- License: BSD-3-Clause
+- Source: https://github.com/jpeg-js/jpeg-js
+
 ## CozyClay license scope
 
 The CozyClay combined work in this repository is distributed under AGPL-3.0-or-later, subject to the transition details in `LICENSING.md`. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, the bundled fonts, the character rigs, or any other third-party component.

package/bin/agent/agent-routes.mjs

@@ -10,6 +10,7 @@ import { createAgentTools, SYSTEM_PROMPT, pickWorkspace } from "./agent-tools.mj
 import { createVideoAdapters, validateFalVideoRequest } from "./video-adapters.mjs";
 import { createSessionStore, transcriptFromHistory } from "./session-store.mjs";
 import { createAgentRunner } from "./agent-runner.mjs";
+import { STUDIO_SYSTEM_PROMPT_STORYBOARD } from "./studio-prompt.mjs";
 
 // Values the codex backend accepts for reasoning.effort (its own 400 lists them).
 export const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
@@ -19,7 +20,7 @@ const json = (res, status, value) => {
 	res.end(JSON.stringify(value));
 };
 
-export function allowAgentOrigin(req, port) {
+function allowAgentOrigin(req, port) {
 	return [`http://127.0.0.1:${port}`, `http://${"local" + "host"}:${port}`].includes(req.headers.origin)
 		|| (req.headers.origin === undefined && req.method === "GET"
 			&& [`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host));
@@ -27,6 +28,8 @@ export function allowAgentOrigin(req, port) {
 
 // Two 1920x1080 PNG data URLs (frame + reference) fit comfortably in this.
 const IMAGE_BODY_LIMIT = 24 * 1024 * 1024;
+// The sizes gpt-image-2 accepts; omitted means the backend's own choice.
+const IMAGE_SIZES = ["auto", "1024x1024", "1536x1024", "1024x1536"];
 
 // Attached scene references (#167): identity sheets and the environment
 // reference. Capped because every one of them is another full image the
@@ -41,6 +44,10 @@ const ATTACHMENTS_MAX = 4;
 const ATTACHMENT_MAX_CHARS = 6_000_000;
 const TURN_BODY_LIMIT = ATTACHMENTS_MAX * ATTACHMENT_MAX_CHARS + 64 * 1024;
 
+// How long GET /agent/turn/<id>/supervisor holds a request for a review that
+// is still running before it answers 204 (#728).
+const SUPERVISOR_WAIT_MS = 180_000;
+
 /** Reject anything that is not a short list of inline {dataUrl, name?} images.
  * The Studio envelope validates its own copy; this is the legacy body's. */
 function validAttachments(attachments) {
@@ -60,7 +67,6 @@ const agentToolCategory = (name) => {
 	// Studio families are authored edits or reads; the analytics vocabulary has
 	// no Studio-specific category, so a write says so and everything else does not.
 	if (["arrange_objects", "arrange_characters", "patch_elements", "frame_shot", "undo_edit"].includes(name)) return "scene_write";
-	if (["inspect_studio", "operate_studio", "verify_result", "generate_motion"].includes(name)) return "other";
 	if (name === "run_workflow") return "workflow_run";
 	if (name === "describe_workflow" || name === "focus_workflow_node") return "workflow_read";
 	if (["add_workflow_node", "update_workflow_node", "remove_workflow_node", "connect_workflow_nodes", "disconnect_workflow_nodes", "set_workflow_node_output"].includes(name)) return "workflow_write";
@@ -75,6 +81,55 @@ const agentFailureCode = (error, signal, tool = false) => advisory(() => {
 	if (error?.status === 429) return "rate_limited";
 	return tool ? "tool_failed" : "upstream";
 }, tool ? "tool_failed" : "upstream");
+/**
+ * One user message is one editor transaction: every Studio turn whose editor
+ * reports a previsMode opens agent.turn.begin and closes agent.turn.finish, so
+ * all of its mutations land as ONE history entry and one receipt frame. A
+ * context without a previsMode comes from an editor that predates turn
+ * transactions and runs unwrapped. rollback() cancels the open transaction
+ * (restoring the pre-turn document) and reopens it for the rest of the turn.
+ */
+const agentTurn = ({ hub, context, turnId, admission }) => {
+	const wrapped = Boolean(context.scene?.previsMode);
+	const host = Object.fromEntries(["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"].map(key => [key, context.host[key]]));
+	const control = async action => {
+		const receipt = await hub.command("run_action", {
+			name: "run_action", args: { action, args: { turnId } }, turnId,
+			commandId: randomUUID(), host, expectedRevision: admission.revision,
+		}, context.host.workspaceHandle);
+		if (!receipt.ok) throw Object.assign(new Error(receipt.message), { code: receipt.code });
+		return receipt;
+	};
+	const open = async () => { await control("agent.turn.begin"); admission.turnId = turnId; };
+	return {
+		async rollback() {
+			if (admission.turnId !== turnId) return null;
+			delete admission.turnId;
+			const receipt = await control("agent.turn.cancel");
+			await admission.refresh();
+			await open();
+			return receipt;
+		},
+		run: start => async function* (input) {
+			if (!wrapped) { yield* start(input); return; }
+			await open();
+			let terminal;
+			try {
+				for await (const frame of start(input)) {
+					if (frame.type === "done") terminal = frame; else yield frame;
+				}
+			} finally {
+				// A rollback whose reopen failed has already closed the transaction.
+				if (admission.turnId === turnId) {
+					delete admission.turnId;
+					const receipt = await control("agent.turn.finish");
+					if (receipt.authored) yield { type: "receipt", receipt };
+				}
+			}
+			if (terminal) yield terminal;
+		},
+	};
+};
 // These existing canvas commands only return a node/edge after publishing a
 // new insertion. Read/focus, generic accepted responses, update no-ops and run
 // outputs (which can echo old values) are deliberately not application proof.
@@ -134,6 +189,8 @@ function validReferences(references) {
  * owns the geometry, each character sheet owns one performer's look and the
  * environment reference owns the location.
  */
+export const FRAME_COMPOSITION_GUIDANCE = "Use the first image (a clay blocking frame) as the layout: keep its composition and camera angle, and keep the pose but make it look natural. Render it as:";
+
 export function referenceGuidance(references = []) {
 	const list = Array.isArray(references) ? references : [];
 	if (!list.length) return "";
@@ -143,6 +200,8 @@ export function referenceGuidance(references = []) {
 			lines.push(`Character ${entry.name || "reference"}: match the identity, face, hair and wardrobe from the attached character sheet.`);
 		} else if (entry.role === "environment") {
 			lines.push("Environment: take the location look, materials, palette and lighting from the attached environment reference.");
+		} else if (entry.role === "reference") {
+			lines.push(`Reference ${entry.name || "image"}: use it for the look the prompt asks for (subject, wardrobe, style); keep the exact pose, body position and camera framing of the first image.`);
 		}
 	}
 	return `\n${lines.join("\n")}`;
@@ -174,7 +233,7 @@ function quotaEvent(codex, headers) {
 // one line — without it neither the log nor the panel can say why a turn died.
 const UPSTREAM_DETAIL_MAX = 200;
 export function sanitizeUpstreamDetail(body) {
-	let message = null;
+	let message;
 	try {
 		const parsed = JSON.parse(body);
 		const candidate = parsed?.error?.message ?? parsed?.error ?? parsed?.message ?? parsed?.detail;
@@ -285,7 +344,10 @@ function liveToolsRuntime(mcpRuntime) {
 	});
 }
 
-export function createAgentHandler({ auth = defaultAuth, codex, models, codexBaseUrl, cliproxyBaseUrl, env, fauxProvider, handlers, liveHub, mcpRuntime, port, studioRuntime, clock = Date.now, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, sessionStore: injectedSessionStore } = {}) {
+// `supervisor` (#728) defaults off only under an injected scripted provider:
+// a test's script is an exact queue of replies, and a review would take one
+// meant for a later turn. The real sidecar never injects one.
+export function createAgentHandler({ auth = defaultAuth, codex, models, codexBaseUrl, cliproxyBaseUrl, env, fauxProvider, handlers, liveHub, mcpRuntime, port, studioRuntime, clock = Date.now, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, sessionStore: injectedSessionStore, supervisor = !fauxProvider } = {}) {
 	const requestContext = new AsyncLocalStorage();
 	codex ||= defaultClient(auth, requestContext);
 	const runtime = handlers !== undefined || liveHub !== undefined ? Promise.resolve({ handlers: handlers ?? [], liveHub }) : liveToolsRuntime(mcpRuntime);
@@ -347,6 +409,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		return owner;
 	};
 	const emitStudioEvent = (turnId, event) => {
+		// The supervisor note lands after the turn ended (#728): it joins the turn's
+		// record, terminal or not, but never resurrects one that was retired.
+		if (event.type === "supervisor" && !studioEvents.has(turnId)) return;
 		const record = studioEvents.get(turnId) || { next: 0, events: [], listeners: new Set(), terminal: false };
 		// Execution telemetry is advisory and is validated key-by-key in the
 		// browser: it carries no replay cursor, is never retained for a resume,
@@ -377,10 +442,10 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	});
 
 	const studioIdentity = host => Object.fromEntries(["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"].map(key => [key, host[key]]));
-	const writeStudioStream = (res, record, after = 0, req = null) => {
+	const writeStudioStream = (res, record, after = 0) => {
 		res.writeHead(200, { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache", connection: "keep-alive" }); res.flushHeaders?.();
 		let cursor = after; const send = event => {
-			if (res.destroyed) return;
+			if (res.destroyed || res.writableEnded) return;
 			if (event.eventSeq === undefined) { res.write(`data: ${JSON.stringify(event)}\n\n`); return; }
 			if (event.eventSeq > cursor) { cursor = event.eventSeq; res.write(`data: ${JSON.stringify(event)}\n\n`); }
 		};
@@ -401,8 +466,8 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	};
 	const handleStudioTurn = async (req, res, value, path) => {
 		const { StudioProtocolError, validateStudioContextFreshness } = await import("../../src/studio-agent-protocol.js");
-		const [{ createStudioTools }, { encodeStudioContext }] = await Promise.all([
-			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"),
+		const [{ createStudioTools }, { encodeStudioContext }, { createScriptTool }, { runSupervisor, shouldSupervise }] = await Promise.all([
+			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"), import("./script-tool.mjs"), import("./supervisor.mjs"),
 		]);
 		const hubDeps = await runtime; const hub = hubDeps.liveHub || liveHub;
 		if (path === "/agent/stop") {
@@ -436,43 +501,65 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		let session = studioSessions.get(value.sessionId);
 		const suppliedOwner = parseCookies(req).studio_owner;
 		if (session && suppliedOwner && session.owner !== suppliedOwner) throw new StudioProtocolError("AUTH_REQUIRED", "Studio session owner mismatch.");
+		const existing = session?.turns.get(value.turnId);
+		if (existing) { session.updatedAt = clock(); writeStudioStream(res, existing, 0); return true; }
+		let current;
+		try { current = studioRuntime?.readContext ? await studioRuntime.readContext(value.context.host) : await authoritativeStudioContext(value, hub); }
+		catch (error) { if (error instanceof StudioProtocolError) throw error; if (error?.code) throw new StudioProtocolError(error.code, error.message); throw new StudioProtocolError("CAPABILITY_MISSING", "The connected editor does not expose authoritative Studio context."); }
+		validateStudioContextFreshness(value.context, current);
+		// The session, and the owner token only this turn's response can hand
+		// the browser, exist only once the turn is admitted. Minting them before
+		// a refusal (the editor still reconnecting after a restart) left a
+		// session whose owner the browser never received: its cookie from the
+		// previous server then failed every retry with "owner mismatch".
 		if (!session) {
 			studioOwner(req, value.sessionId, true);
 			let persisted = null;
-			try { persisted = sessionStore.read(value.sessionId); } catch { persisted = null; }
+			try { persisted = sessionStore.read(value.sessionId); } catch { /* an unreadable history starts the session fresh */ }
 			session = { owner: studioOwnerTokens.get(value.sessionId), history: persisted?.history ?? [], persistedItems: persisted?.history?.length ?? 0, meta: persisted?.meta ?? null, turns: new Map(), controller: null, activeJobId: null, activeJobTurnId: null, motionJobIds: new Set(Array.isArray(persisted?.meta?.motionJobIds) ? persisted.meta.motionJobIds.filter(id => typeof id === "string") : []), host: null, updatedAt: clock() };
 			studioSessions.set(value.sessionId, session);
 		}
 		session.updatedAt = clock();
-		const existing = session.turns.get(value.turnId);
-		if (existing) { writeStudioStream(res, existing, 0, req); return true; }
-		let current;
-		try { current = studioRuntime?.readContext ? await studioRuntime.readContext(value.context.host) : await authoritativeStudioContext(value, hub); }
-		catch (error) { if (error instanceof StudioProtocolError) throw error; if (error?.code) throw new StudioProtocolError(error.code, error.message); throw new StudioProtocolError("CAPABILITY_MISSING", "The connected editor does not expose authoritative Studio context."); }
-		validateStudioContextFreshness(value.context, current);
 		if (studioRuntime?.handleTurn) { await studioRuntime.handleTurn(value, req, res); return true; }
 		const record = { next: 0, events: [], listeners: new Set(), terminal: false }; studioEvents.set(value.turnId, record); session.turns.set(value.turnId, record); session.host = studioIdentity(value.context.host);
 		res.setHeader("set-cookie", `studio_owner=${encodeURIComponent(session.owner)}; Path=/agent; HttpOnly; SameSite=Strict`);
-		const close = writeStudioStream(res, record, 0, req);
-		const send = event => emitStudioEvent(value.turnId, event);
+		const close = writeStudioStream(res, record, 0);
+		// What the supervisor reviews once the turn is over: every frame but text
+		// and telemetry, and the last stretch of text the model wrote.
+		const turnFrames = [];
+		let replySegment = "", lastReply = "";
+		const send = event => {
+			if (event.type === "text.delta") { replySegment += event.text ?? ""; lastReply = replySegment; }
+			else if (!["execution_telemetry", "execution_tool_started"].includes(event.type)) {
+				if (event.type === "tool.start") replySegment = "";
+				turnFrames.push(event);
+			}
+			emitStudioEvent(value.turnId, event);
+		};
 		// The Studio turn is measured exactly like the Workflow turn, correlated by
 		// the turn id the host already owns (the frozen envelope carries no room
 		// for a second one).
 		const telemetry = createTurnTelemetry(send, value.turnId);
 		let turnOutcome = "succeeded", turnFailureCode = null, toolFailed = false;
-		const controller = new AbortController(); session.controller = controller;
+		const controller = new AbortController(); session.controller = controller; session.activeTurnId = value.turnId;
 		// Admission is the document identity plus the exact scene revision each
 		// command expects. Per-entity tokens are deliberately absent: the revision
 		// already moves whenever any authored content changes, and a turn's second
 		// edit to the same entity would otherwise carry a token the first edit retired.
 		const admission = {
 			commandId: () => randomUUID(), host: studioIdentity(value.context.host), revision: value.context.revision.scene,
-			refresh: async () => {
-				// Read at the admitted host: a scene action may have opened another
-				// scene of this workspace during the turn (studio-tools adopts it).
+			// Read at the admitted host: a scene action may have opened another
+			// scene of this workspace during the turn (studio-tools adopts it).
+			snapshot: async () => {
 				const host = { ...value.context.host, ...admission.host };
-				const refreshed = studioRuntime?.readContext ? await studioRuntime.readContext(host) : await authoritativeStudioContext({ ...value, context: { ...value.context, host } }, hub);
+				return studioRuntime?.readContext ? await studioRuntime.readContext(host) : await authoritativeStudioContext({ ...value, context: { ...value.context, host } }, hub);
+			},
+			// Re-admits at the live revision and hands back the context it read, which
+			// the tools compare against what the agent last saw (studio-rebase.mjs).
+			refresh: async () => {
+				const refreshed = await admission.snapshot();
 				admission.revision = refreshed.revision.scene;
+				return refreshed;
 			},
 		};
 		// One motion generation per user message, whichever path starts it:
@@ -504,7 +591,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				if (session.activeJobId === jobId) { session.activeJobId = null; session.activeJobTurnId = null; }
 			}
 		};
-		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, session: { signal: controller.signal, admission, generation, onJob, actionIndex: current?.actionIndex ?? [] }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
+		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, previsMode: value.context.scene?.previsMode, session: { signal: controller.signal, admission, generation, onJob, actionIndex: current?.actionIndex ?? [], baseline: value.context }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
 		const motion = async args => {
 			// Private artifact IDs belonged to the retired sidecar runtime. Reuse
 			// retained editor takes through motion.loadVersion, not another installer.
@@ -525,12 +612,35 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				return { ...result, visualStatus: visual.visualStatus, imageId: visual.imageId, revision: visual.revision, receiptId: visual.receiptId, ...(visual.dataUrl ? { dataUrl: visual.dataUrl } : {}) };
 			},
 		}));
+		const turnTransaction = agentTurn({ hub, context: current, turnId: value.turnId, admission });
+		const script = createScriptTool({ tools: modelTools, signal: controller.signal, emit: send });
+		const scriptTool = {
+			...script,
+			// A script that fails after it edited the scene rolls the turn back, so
+			// the model retries from the pre-turn document, never from half a script.
+			handler: async (args, options) => {
+				const result = await script.handler(args, options);
+				if (result.ok || !result.calls.some(call => call.ok && Number.isSafeInteger(call.revision?.after) && call.revision.after !== call.revision.before)) return result;
+				const rollback = await turnTransaction.rollback();
+				return rollback ? { ...result, rollback: { status: "rolled_back", receiptId: rollback.receiptId, revision: rollback.revision, affectedIds: rollback.affectedIds.slice(0, 8) } } : result;
+			},
+		};
 		let frameObservation;
 		if (value.attachFrame) {
 			const captured = await hub.command("capture_framing_png", {}, value.context.host.workspaceHandle);
 			if (!captured?.dataUrl?.startsWith("data:image/")) throw new StudioProtocolError("TARGET_NOT_READY", "The current frame has no image bytes.");
 			const match = /^data:([^;]+);base64,(.*)$/.exec(captured.dataUrl);
 			frameObservation = { data: match[2], mimeType: match[1], revision: captured.revision, receiptId: captured.receiptId };
+		} else if (value.context.scene?.characterCount >= 2 || (value.context.shots?.length ?? 0) >= 1 || /샷|컷|카메라|커버리지|OTS|투샷|프레임|shot|camera|coverage|two-shot|framing/i.test(value.text || "")) {
+			// A staging or coverage request also sees the top-view plan; without it the turn just runs.
+			try {
+				const captured = await hub.command("capture_plan_png", {}, value.context.host.workspaceHandle);
+				const match = /^data:([^;]+);base64,(.*)$/.exec(captured?.dataUrl ?? "");
+				if (!match) throw new Error("The plan capture has no image bytes.");
+				frameObservation = { kind: "plan", data: match[2], mimeType: match[1], revision: captured.revision ?? value.context.revision?.scene ?? null, receiptId: captured.receiptId };
+			} catch (error) {
+				console.warn(`[agent] plan observation skipped: ${error.message}`);
+			}
 		}
 		const telemetryTools = new Map();
 		const emitFrame = frame => {
@@ -545,6 +655,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				toolFailed = true;
 				if (typeof frame.error === "string" && frame.error.startsWith("Validation failed for tool ")) frame.error = "INVALID_ARGUMENT: Unexpected field.";
 			}
+			// A command the sidecar re-sent once (stale revision, busy gesture) is
+			// marked on the frame itself; the receipt carries autoRebased and a warning.
+			if (frame.ok && frame.result?.autoRebased === true) frame.autoRebased = true;
 			send(frame);
 			if (record) {
 				record.execution.executed(frame.ok ? "succeeded" : (controller.signal.aborted ? "cancelled" : "failed"));
@@ -560,10 +673,15 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			if (frame.type === "done") {
 			if (turnOutcome === "succeeded" && !toolFailed) telemetry.finished("succeeded", null);
 			else telemetry.finished(turnOutcome, turnFailureCode || "tool_failed");
+			// Marked before the done frame leaves, so a client that asks for the
+			// review the moment its stream ends finds it pending, not absent.
+			// The author's own switch (value.supervisor === false) skips this turn's review.
+			if (supervisor && process.env.COZYCLAY_SUPERVISOR !== "off" && value.supervisor !== false && !controller.signal.aborted && shouldSupervise(turnFrames)) record.supervisor = "pending";
 			}
 			send(frame);
 		};
 		const persistenceMeta = { sceneName: value.context?.scene?.name ?? value.context?.sceneName ?? null, firstText: value.text, motionJobIds: [...session.motionJobIds] };
+		const modelKey = value.model || (fauxProvider ? `${fauxProvider.provider?.id || fauxProvider.provider || "faux"}/scripted` : "gpt-6-astra");
 		let runner = studioRunners.get(value.sessionId);
 		if (!runner) {
 			runner = createAgentRunner({ models: await ensureWorkflowModels(), fauxProvider, sessionStore, clock, codexBaseUrl, cliproxyBaseUrl, auth, env });
@@ -571,10 +689,10 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		}
 		try {
 			if (!session.modelSession) session.modelSession = await runner.openSession(value.sessionId, { surface: "studio" });
-			for await (const frame of session.modelSession.start({
-				surface: "studio", sessionId: value.sessionId, model: value.model || (fauxProvider ? `${fauxProvider.provider?.id || fauxProvider.provider || "faux"}/scripted` : "gpt-6-astra"), effort: value.effort,
+			for await (const frame of turnTransaction.run(input => session.modelSession.start(input))({
+				surface: "studio", sessionId: value.sessionId, model: modelKey, effort: value.effort,
 				text: value.text, attachments: value.attachments, contextText: encodeStudioContext(value.context), frameObservation,
-				context: value.context, tools: modelTools, signal: controller.signal, emit: send,
+				context: value.context, tools: [...modelTools, scriptTool], systemPrompt: value.context.scene?.previsMode === "storyboard" ? STUDIO_SYSTEM_PROMPT_STORYBOARD : undefined, signal: controller.signal, emit: send,
 				meta: persistenceMeta,
 				quotaEvent: headers => codex?.parseQuotaHeaders ? quotaEvent(codex, headers) : { type: "quota", plan: null, primary: { usedPercent: null, windowMinutes: null, resetAt: null }, credits: { has: null } },
 			})) emitFrame(frame);
@@ -587,7 +705,25 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		}
 		if (controller.signal.aborted) { turnOutcome = "cancelled"; turnFailureCode = "aborted"; }
 		if (!record.terminal) emitFrame({ type: "done" });
-		close(); if (!res.writableEnded) res.end(); session.controller = null; return true;
+		close(); if (!res.writableEnded) res.end(); session.controller = null; session.activeTurnId = null;
+		// The review starts only now, after the stream has ended, and only ever
+		// appends one note to the record: it neither delays nor steers the turn.
+		if (record.supervisor === "pending") void (async () => {
+			const startedAt = Date.now();
+			let frame;
+			try {
+				frame = await runSupervisor({ registry: await ensureWorkflowModels(), modelKey, effort: process.env.COZYCLAY_SUPERVISOR_EFFORT || "high", turnId: value.turnId, request: value.text, frames: turnFrames, reply: lastReply,
+					hub, workspaceHandle: value.context.host.workspaceHandle, admission, baseline: value.context, actions: current?.actionIndex ?? [] });
+			} catch (error) {
+				frame = { type: "supervisor", turnId: value.turnId, verdict: "unavailable", model: modelKey, effort: null, elapsedMs: Date.now() - startedAt, summary: "", items: [], issues: [], fixes: [], droppedFixes: [], counts: { blocker: 0, concern: 0, note: 0, fixes: 0 }, reason: "The supervisor could not start." };
+			}
+			// COZYCLAY_SUPERVISOR_AUTOFIX=blocker (#743) only marks a note whose
+			// blockers carry fixes; turns stay the panel's to start, never the sidecar's.
+			if (process.env.COZYCLAY_SUPERVISOR_AUTOFIX === "blocker" && frame.fixes?.some(fix => fix.severity === "blocker")) frame = { ...frame, autofix: { eligible: true, severity: "blocker" } };
+			record.supervisor = "done";
+			emitStudioEvent(value.turnId, frame);
+		})();
+		return true;
 	};
 	const handle = async (req, res, path = new URL(req.url, "http://127.0.0.1").pathname) => {
 		if (!path.startsWith("/agent/")) return false;
@@ -601,7 +737,34 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			if (!record || !session || parseCookies(req).studio_owner !== session.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio event stream is not owned by this session." } }); return true; }
 			const after = Number(new URL(req.url, "http://127.0.0.1").searchParams.get("after") || 0);
 			if (!Number.isSafeInteger(after) || after < 0) { json(res, 400, { error: "invalid cursor" }); return true; }
-			writeStudioStream(res, record, after, req); return true;
+			writeStudioStream(res, record, after); return true;
+		}
+		// The supervisor note for one Studio turn (#728): 200 with the note once it
+		// exists, held up to SUPERVISOR_WAIT_MS while it is pending, 204 when the
+		// turn was never reviewed or the wait ran out.
+		if (path.startsWith("/agent/turn/") && path.endsWith("/supervisor") && req.method === "GET") {
+			if (!await hasAnyCredential()) { json(res, 401, { error: { code: "AUTH_REQUIRED", message: "Sign in or configure a provider key." } }); return true; }
+			const turnId = decodeURIComponent(path.slice("/agent/turn/".length, -"/supervisor".length));
+			const session = [...studioSessions.values()].find(candidate => candidate.turns.has(turnId)); const record = studioEvents.get(turnId);
+			if (!record || !session) { json(res, 404, { error: "turn not found" }); return true; }
+			if (parseCookies(req).studio_owner !== session.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio supervisor note is not owned by this session." } }); return true; }
+			const noContent = () => { res.writeHead(204, { "cache-control": "no-store" }); res.end(); };
+			const existing = record.events.findLast(event => event.type === "supervisor");
+			if (existing) { json(res, 200, existing); return true; }
+			if (record.supervisor !== "pending") { noContent(); return true; }
+			await new Promise(resolve => {
+				let timer;
+				const settle = note => {
+					clearTimeout(timer); record.listeners.delete(listener); res.off("close", onClose);
+					if (note !== undefined && !res.writableEnded && !res.destroyed) { if (note) json(res, 200, note); else noContent(); }
+					resolve();
+				};
+				const listener = event => { if (event.type === "supervisor") settle(event); };
+				const onClose = () => settle(undefined);
+				record.listeners.add(listener); res.once("close", onClose);
+				timer = setTimeout(() => settle(null), SUPERVISOR_WAIT_MS);
+			});
+			return true;
 		}
 		if (path.startsWith("/agent/turn/") && path.endsWith("/steer") && req.method === "POST") {
 			const turnId = decodeURIComponent(path.slice("/agent/turn/".length, -"/steer".length));
@@ -610,12 +773,15 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				value = await readBody(req, TURN_BODY_LIMIT);
 				if (!value || typeof value.text !== "string" || !value.text.trim() || !validAttachments(value.attachments)) throw new Error("Invalid request.");
 			} catch { json(res, 400, { error: "invalid request" }); return true; }
-			// Studio turnIds are frozen envelopes; their events are keyed in studioSessions,
-			// never in the Workflow `sessions` map, so that lookup alone tells them apart.
-			if ([...studioSessions.values()].some(candidate => candidate.turns.has(turnId))) { json(res, 409, { error: { code: "STEER_UNSUPPORTED", message: "Steering a Studio turn is not supported." } }); return true; }
-			const session = [...sessions.values()].find(candidate => candidate.turnId === turnId);
+			// Studio turns are keyed in studioSessions, never in the Workflow
+			// `sessions` map, so that lookup alone tells them apart. Only the cookie
+			// owner of the Studio session may steer its running turn.
+			const studio = [...studioSessions.values()].find(candidate => candidate.turns.has(turnId));
+			if (studio && parseCookies(req).studio_owner !== studio.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio turn is not owned by this session." } }); return true; }
+			const session = studio ?? [...sessions.values()].find(candidate => candidate.turnId === turnId);
 			if (!session) { json(res, 404, { error: "turn not found" }); return true; }
-			if (!session.running || !session.modelSession) { json(res, 409, { error: { code: "NO_ACTIVE_TURN", message: "This turn already ended." } }); return true; }
+			const active = studio ? studio.activeTurnId === turnId && studio.controller && !studio.controller.signal.aborted : session.running;
+			if (!active || !session.modelSession) { json(res, 409, { error: { code: "NO_ACTIVE_TURN", message: "This turn already ended." } }); return true; }
 			const images = (Array.isArray(value.attachments) ? value.attachments : []).map(attachment => {
 				const match = /^data:([^;]+);base64,(.*)$/.exec(attachment?.dataUrl || "");
 				return match ? { type: "image", data: match[2], mimeType: match[1] } : null;
@@ -678,7 +844,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			let value;
 			try {
 				value = await readBody(req, IMAGE_BODY_LIMIT);
-				if (typeof value.prompt !== "string" || !value.prompt.trim() || typeof value.imageDataUrl !== "string" || !value.imageDataUrl.startsWith("data:image/") || (value.referenceDataUrl !== undefined && (typeof value.referenceDataUrl !== "string" || !value.referenceDataUrl.startsWith("data:image/"))) || !validReferences(value.references) || (value.quality !== undefined && !["auto", "low", "medium", "high"].includes(value.quality))) throw new Error("Invalid request.");
+				if (typeof value.prompt !== "string" || !value.prompt.trim() || typeof value.imageDataUrl !== "string" || !value.imageDataUrl.startsWith("data:image/") || (value.referenceDataUrl !== undefined && (typeof value.referenceDataUrl !== "string" || !value.referenceDataUrl.startsWith("data:image/"))) || !validReferences(value.references) || (value.composition !== undefined && !["frame", "sheet"].includes(value.composition)) || (value.quality !== undefined && !["auto", "low", "medium", "high"].includes(value.quality)) || (value.size !== undefined && !IMAGE_SIZES.includes(value.size))) throw new Error("Invalid request.");
 			} catch { json(res, 400, { error: "invalid request" }); return true; }
 			if (!await auth.getAccessToken()) { json(res, 401, { error: { code: "auth", message: "Sign in with ChatGPT in the Agent panel." } }); return true; }
 			try {
@@ -687,8 +853,17 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				// Scene references (#167) are appended after the frame/reference pair,
 				// and the prompt says what each attachment is for.
 				const references = Array.isArray(value.references) ? value.references : [];
-				const prompt = `${value.prompt}${await renderGuidance(value.prompt)}${referenceGuidance(references)}`;
-				const result = await codex.editImage({ ...value, prompt, extraImages: references.map((entry) => entry.dataUrl) });
+				// composition "frame": the attached frame was framed by hand (Pose mode), so the shot
+				// camera's description would contradict it; the frame alone owns camera and pose.
+				// composition "sheet" (Sculpt blueprint): a model sheet, not a shot, so no scene or
+				// camera guidance is added; the prompt is sent as written.
+				const prompt = value.composition === "sheet"
+					? value.prompt
+					: value.composition === "frame"
+						? `${FRAME_COMPOSITION_GUIDANCE}\n${value.prompt}${referenceGuidance(references)}`
+						: `${value.prompt}${await renderGuidance(value.prompt)}${referenceGuidance(references)}`;
+				const { composition: _composition, ...request } = value;
+				const result = await codex.editImage({ ...request, prompt, extraImages: references.map((entry) => entry.dataUrl) });
 				json(res, 200, { dataUrl: `data:image/png;base64,${result.pngBase64}`, width: result.width, height: result.height });
 			} catch (error) { json(res, error.status === 401 ? 401 : 502, { error: errorInfo(error) }); }
 			return true;