cozyclay 1.10.0 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # Changelog
 
+## 2.0.2
+
+The first-run audit release: `npx cozyclay` is exercised end to end as a new
+user, and the things that broke on that path are fixed. 2.0.1 (the camera
+tutorial refresh and light-mode default, #586) was tagged but never reached
+npm; this release carries it.
+
+Agent and package
+
+- The Studio Agent panel in the npm package answered every turn with
+  "502 — agent unavailable": the sidecar's Studio tools imported `three`
+  (a devDependency the package does not ship) through `src/scenes.js`. The
+  timeline clock moved to its own module and a test now walks every import
+  reachable from `bin/` and fails on any chain to `three`. (#591)
+- A CLIProxy key in the environment no longer leaves the panel on the ChatGPT
+  sign-in wall; readiness counts every key-authenticated provider. (#591)
+- `CCLAY_KIMODO_HOST=… npx cozyclay` died at start with
+  `Cannot find package 'three'`: the motion bridge now runs from the staged
+  MCP runtime (which carries `three`, `tools/` and `dist/models`), and the
+  package isolation test keeps it that way. (#591)
+- A live-hub port already taken by another CozyClay is reported on the
+  launcher's terminal and named in the pane's error instead of
+  "Studio execution is not installed"; agent handler failures are logged
+  before the 502; a session id with no record no longer shows
+  "Previous conversation could not be restored". (#591)
+
+Studio
+
+- Create on the start screen opens the selected sample scene under the typed
+  name instead of an empty stage named after it; starting over with unsaved
+  work asks first. (#591)
+- Reloading a project created from the start screen brought the previous
+  session's walking take back onto the character, with "Unsaved changes":
+  the hosted-demo seed re-fired on every mount while the bridge probe was
+  down. It now skips a saved project (a `?scene=` launch still seeds), and a
+  reload opens on the clean checkpoint. (#591)
+- With a take installed, the gizmo and the Transform panel's Position and
+  Rotation move the character again; the take keeps animating relative to
+  the new placement. (#591)
+- The shot card's hover actions sit above the card, so clicking a short
+  shot's name selects it instead of hitting Delete. Draw rail is disabled
+  with a reason when no shot is selected. (#591)
+
+Tests
+
+- The start-screen and project-menu browser suites run against the v2
+  shell again, gain the sample-card Create regression, and join the CI
+  browser matrix as observation suites; new regressions cover the package
+  import graph, CLIProxy readiness, the stage transform and the reload
+  session. (#591)
+
+## 2.0.1
+
+- The camera tutorial follows the v2 shell and new installs default to the
+  light theme. (#586)
+
+## 2.0.0
+
+CozyClay 2.0 is the v2 editor: a floating-glass shell with light and dark
+themes, one four-mode Studio (Stage, Pose, Camera, Motion on keys 1-4), and
+the v2 Outliner, Sequencer, start screen, Details panels and Preferences.
+Under it, every document edit, whether it comes from the UI, the Agent panel,
+MCP or the CLI, now runs through one command bus on a document store with one
+undo history, so anything the editor can do is callable by an agent without
+separate wiring. The Studio Agent panel in the npm package works again
+(#576). **No MCP tool or CLI command was removed**: legacy MCP tools are
+aliases of bus commands and answer the editor's receipts.
+
+Studio
+
+- Floating-glass shell: the viewport fills the window and the top bar, both
+  columns, the dock and the status strip float over it. Light and dark
+  themes, and the stage follows the theme live. The dock runs Animation |
+  Assets tabs sized to the Sequencer's lanes, with the shot preview docked at
+  its right end; the standing status row is gone and live export status
+  floats in the viewport. (#570, #572, #519)
+- One four-mode switch, Stage, Pose, Camera and Motion, on keys 1-4. Pose
+  mode is the single way into IK (W/E/R pick ik, trail and pin there); the
+  timeline IK toggle and the Rig Control IK buttons are gone, and leaving
+  Pose ends IK. (#521)
+- v2 Outliner: 36 px header with the item count, search, typed rows, amber
+  selection; right-click Create replaces the toolbar's + Add object. (#525)
+- v2 Sequencer: header, readout and actions, a 190 px track tree, clip
+  fills, amber playhead, keys and pin bands, scrollable camera, rail and
+  crane rows. (#528)
+- v2 start screen: project nav, template categories, recent rows, the
+  browser project store and a project preview; File › New opens the same
+  screen. (#531, #551)
+- v2 Details panels and primitives: pose tools with an auto-fix preview,
+  motion details with takes, the viewport toolbar and overlays, the top bar,
+  menus and status bar, the content browser and log, and the Preferences
+  dialog. (#522, #523, #524, #526, #527, #529, #530, #532)
+- Generate actions have one home: the top-bar Generate Motion button runs
+  every prompt block when any block has text. Copy follows v2: "ARDY" leaves
+  the user-facing text, pose toasts say "Pose mode", path endpoints read
+  PATH START / PATH END, the first-run guide says Outliner. (#550, #551)
+- Top-View props recede so the camera, cast and rail read first. (#566)
+- When WebGL is unavailable the stage says so instead of staying blank. (#518)
+- 194 dead CSS rules are gone and the v2 information architecture is
+  recorded in `docs/studio-ui-ia.md`; Details, Outliner and top-bar props
+  that were never read are dropped. (#533, #552, #556, #558, #560, #562)
+- Korean UI: 56 reversed `ko()` argument pairs in the motion card are fixed
+  (#505, by @romanr), as are the VideoCapturePanel quality-gate messages
+  (#565).
+
+IK and motion
+
+- IK and motion trails on the split architecture: delta IK drag baking over
+  the raw clip, per-key blend persistence, a remembered IK camera entry,
+  trail picking against the rendered rig, limb, head and root trail edits
+  with conflict warnings. (#511)
+- Range pin with an exact hinge solve and body reach compensation, carried
+  through persistence, undo/redo, timeline bands and preview markers. (#515)
+- Fit to platforms with Fit / Remove controls and a stable knee bend side,
+  verified over 784 cases with no reverse bends. (#517)
+- One motion generation pipeline on the job contract: `motion.generate`
+  serves the UI, the Agent and MCP alike, with concurrent-edit parity (a
+  stale job publishes nothing, an unrelated object edit still installs),
+  Stop and cancel, reconnect, and receipt undo. The agent-only motion
+  pipeline is deleted. (#444, #452)
+- Image-to-video motion is named `i2v` in code and "AI motion" in the UI;
+  "fal" names only the provider adapter. Command ids, analytics values and
+  persisted values are unchanged. (#509)
+
+Command bus and document store
+
+- Every document mutation runs through one command bus: wire transactions,
+  a scoped job fence, receipts, refusals and exposure. Action registrations,
+  the agent binding and the domain writers moved out of App.jsx. (#435,
+  #437, #459, #460, #477)
+- A document store owns stage, objects, shots, cast, motion and IK, and
+  project and scenes, each routed through the bus, with collection element
+  kinds and cross-domain undo order. (#449, #447, #445, #441, #442, #448,
+  #461, #480)
+- One store-owned undo history; the per-domain history owners are gone.
+  (#494) Duplicate agent paths are removed: `inspect_studio`, `run_action`
+  and `verify_result` are the three tool families, `operate_studio` is an
+  alias, and selection, playhead and view changes add no undo entries.
+  (#495) The writer baseline is zero and parity is complete: all 62
+  document-mutating UI handlers reach `run`, enforced by ratchet tests and
+  a generated parity matrix. (#436, #496)
+
+Agent
+
+- The Studio agent pane reaches the whole Studio through the action
+  registry the UI dispatches through, and every bus command is discoverable
+  and callable through agent `run_action`, MCP `studio_commands` /
+  `studio_run` and `cclay live commands` / `cclay live run` with no
+  agent-specific wiring. (#423, #438)
+- Motion failures are visible and routable, `verify_result` reports
+  honestly, and a failed attempt no longer uses up the message's one
+  generation. (#426)
+- Minimal Studio Agent panel: an icon-only head, the account under the ⋯
+  menu, one-line notices, an empty state with suggestion chips; it sits
+  under Details in the right column instead of replacing it. (#574, #570)
+- In the npm package the Studio Agent panel loads its live tools from the
+  staged MCP runtime that `cclay mcp` installs once per version, so the live
+  hub starts and the pane works; `mcp/mesh-file.mjs` ships with the package
+  and `cclay mcp` starts again. A runtime that cannot be installed is
+  reported on the launcher's terminal. (#576)
+
+MCP
+
+- Legacy tools are thin aliases of bus commands and return the editor's JSON
+  receipts: revision before and after, retained undo and refusal codes.
+  `apply_batch` maps to `objects.batch` and keeps `atomic`, `stopOnError`
+  and one undo entry; replacing scene ids needs a Studio-issued confirmation
+  token. (#446)
+- `initialize` waits the SDK's default 60 s. (#502)
+
+Analytics
+
+- Builder telemetry: pose edits, i2v motion A→B, `$exception`, a device
+  profile (GPU and frame rate), the install source from
+  `npx cozyclay --via`, use case and update status. (#466)
+
+Tools
+
+- A mocap research bench under `tools/bench/` and `tools/gt-render/`:
+  ground-truth part-colour renders with camera truths (#428), a GVHMR
+  extraction bench (#430), a scorer for pose, trajectory, endpoints, overlap
+  and contact (#431), 3D fit stages F0-F5 (#432), a cube-contact scenario
+  (#454), the observation-driven GVHMR tuning ladder G0-G5 (#462, #488,
+  #492) and the known-character tracker T1 (#500).
+
+Housekeeping
+
+- The camera-rail browser test waits for the delete toast, which exposed and
+  fixed a stale-toast dismissal bug (#470, #483); the lifecycle test waits
+  for the grandchild to disappear (#479).
+- The owner's v2 editor design contract is adopted in the docs (#512).
+- Repository traffic is archived to the `metrics` branch twice a week.
+
 ## 1.10.0
 
 Props and characters can now be hidden without being deleted, the Studio top

package/bin/agent/agent-routes.mjs

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes, randomUUID } from "node:crypto";
-import { basename } from "node:path";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
 import * as defaultAuth from "../codex-auth.mjs";
 import { publishLiveEndpoint, removeLiveEndpoint } from "../live-endpoint.mjs";
 import { createCodexClient } from "./codex-client.mjs";
@@ -230,13 +231,30 @@ function defaultClient(auth, requestContext) {
 const liveHubOwner = () => process.env.COZYCLAY_LIVE_OWNER
 	|| (basename(process.argv[1] ?? "") === "dev-full.mjs" ? "dev-full" : "cozyclay");
 
+/** The two live-tool modules. A source checkout resolves them from the
+ * repository, where mcp/ has its own node_modules. The published package
+ * ships mcp/ without zod, three or ws, so the launcher passes an `mcpRuntime`
+ * whose ensure() installs the staged runtime (bin/mcp-runtime.mjs) once per
+ * version and the modules are imported from that root instead (#576). */
+async function liveToolsModules(mcpRuntime) {
+	if (!mcpRuntime) return Promise.all([import("../../mcp/tool-handlers.mjs"), import("../../mcp/live-hub.mjs")]);
+	const root = await mcpRuntime.ensure();
+	const staged = (file) => pathToFileURL(join(root, "mcp", file)).href;
+	return Promise.all([import(staged("tool-handlers.mjs")), import(staged("live-hub.mjs"))]);
+}
+
 /** Start the optional registry/live dependencies without making signed-out
  * startup depend on an MCP dependency install. Failures remain visible on use. */
-function liveToolsRuntime() {
-	return Promise.all([import("../../mcp/tool-handlers.mjs"), import("../../mcp/live-hub.mjs")]).then(async ([registry, { startLiveHub }]) => {
+function liveToolsRuntime(mcpRuntime) {
+	return liveToolsModules(mcpRuntime).then(async ([registry, { startLiveHub }]) => {
 		const owner = liveHubOwner();
 		const token = randomBytes(32).toString("hex");
-		const liveHub = await startLiveHub(Number(process.env.COZYCLAY_LIVE_PORT ?? 5184), { token, owner });
+		const livePort = Number(process.env.COZYCLAY_LIVE_PORT ?? 5184);
+		const liveHub = await startLiveHub(livePort, { token, owner });
+		// EADDRINUSE comes back as null: another CozyClay (or its dev server) owns
+		// the port, and the Studio page is built to connect to that port, so the
+		// pane would answer every turn with a misleading capability error.
+		if (!liveHub) console.error(`cozyclay: live hub port ${livePort} is already in use (another CozyClay or its dev server?); the Agent pane cannot drive this Studio until that port is free.`);
 		registry.setLiveHub(liveHub);
 		const handlers = registry.createToolHandlers().map((tool) => ({
 			...tool,
@@ -257,14 +275,20 @@ function liveToolsRuntime() {
 			publishLiveEndpoint({ port: liveHub.port, token, owner });
 			liveHub.server?.once("close", () => removeLiveEndpoint(liveHub.port));
 		}
-		return { liveHub, handlers };
-	}).catch((error) => ({ error }));
+		return { liveHub, handlers, hubPortBusy: !liveHub ? livePort : null };
+	}).catch((error) => {
+		// The pane answers CAPABILITY_MISSING on use; the reason belongs on the
+		// launcher's terminal rather than nowhere.
+		console.error(`cozyclay: Studio live tools unavailable: ${error?.message ?? error}`);
+		for (const line of error?.lines ?? []) console.error(`cozyclay: ${line}`);
+		return { error };
+	});
 }
 
-export function createAgentHandler({ auth = defaultAuth, codex, models, codexBaseUrl, cliproxyBaseUrl, env, fauxProvider, handlers, liveHub, port, getBridgeOrigin, studioRuntime, clock = Date.now, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, sessionStore: injectedSessionStore } = {}) {
+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 } = {}) {
 	const requestContext = new AsyncLocalStorage();
 	codex ||= defaultClient(auth, requestContext);
-	const runtime = handlers !== undefined || liveHub !== undefined ? Promise.resolve({ handlers: handlers ?? [], liveHub }) : liveToolsRuntime();
+	const runtime = handlers !== undefined || liveHub !== undefined ? Promise.resolve({ handlers: handlers ?? [], liveHub }) : liveToolsRuntime(mcpRuntime);
 	const renderGuidance = async (environment) => {
 		try {
 			const { handlers: tools, liveHub: hub } = await runtime;
@@ -306,7 +330,6 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	const sessionStore = injectedSessionStore ?? createSessionStore();
 	const studioSessions = new Map();
 	const studioEvents = new Map();
-	let ownedStudioRuntime = studioRuntime || null;
 	const studioOwnerTokens = new Map();
 	const parseCookies = req => Object.fromEntries(String(req.headers.cookie || "").split(";").map(part => part.trim().split("=")).filter(([key, value]) => key && value).map(([key, value]) => [key, decodeURIComponent(value)]));
 	const pruneStudioSessions = () => {
@@ -323,13 +346,6 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		if (!owner || supplied !== owner) throw Object.assign(new Error("Studio session owner mismatch."), { code: "AUTH_REQUIRED" });
 		return owner;
 	};
-	const studioRuntimeFor = async hub => {
-		if (ownedStudioRuntime) return ownedStudioRuntime;
-		const { createStudioMotionRuntime } = await import("./motion-runtime.mjs");
-		if (!hub) return null;
-		ownedStudioRuntime = createStudioMotionRuntime({ liveHub: hub, getBridgeOrigin, clock });
-		return ownedStudioRuntime;
-	};
 	const emitStudioEvent = (turnId, event) => {
 		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
@@ -353,7 +369,6 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		if (kind !== "signed_out" && kind !== "replaced") return;
 		for (const session of sessions.values()) session.controller?.abort();
 		for (const session of studioSessions.values()) session.controller?.abort();
-		void ownedStudioRuntime?.dispose?.(); ownedStudioRuntime = studioRuntime || null;
 		for (const runner of [...workflowRunners.values(), ...studioRunners.values()]) void runner.close?.();
 		workflowRunners.clear(); studioRunners.clear();
 		workflowModels = models;
@@ -401,36 +416,21 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			// An owned retired id is still stale while another motion job is active:
 			// this Stop cannot acknowledge the current turn's different job.
 			if (value.jobId && session.activeJobId && value.jobId !== session.activeJobId) throw new StudioProtocolError("STALE_TARGET", "Stop does not target the active motion job.");
-			// #379 / 16r: a job's id is only "acknowledged" by THIS turn's held motion
-			// tool — session.activeJobId now stays set only while that job is genuinely
-			// still in flight (or pending an explicit accept), and activeJobTurnId ties
-			// it to the turn that admitted it. A retired job from an earlier turn must
-			// never make a later, unrelated turn's Stop go quiet.
+			// Only this turn's held editor job can settle the tool quietly. A retired
+			// job from an earlier turn must never silence an unrelated turn's Stop.
 			const acknowledged = Boolean(session.activeJobId) && session.activeJobTurnId === value.turnId;
-			// The runtime is the only thing that knows whether the job was applied.
-			// Forwarding its outcome keeps the panel from turning "I could not find
-			// out" into "nothing was applied"; a discarded outcome reads as proof.
+			// The editor's outcome, not a sidecar abort, establishes application.
 			let outcome = null;
-			if (jobId && ownedStudioRuntime?.stop) outcome = await ownedStudioRuntime.stop(jobId);
+			if (jobId) outcome = await session.controlJob('job.cancel', jobId);
 			if (jobId && session.activeJobId === jobId) { session.activeJobId = null; session.activeJobTurnId = null; }
-			// #379 / 16q: `session.controller.signal` is the SAME signal wired into the
-			// active turn's prompt context (`:520 signal: controller.signal`), which
-			// pi's `withAbortSignal`/`awaitWithContext` races against every awaited
-			// internal step — aborting it here interrupts the in-flight generate_motion
-			// tool call's OWN completion machinery before it can settle, well before
-			// pi's own graceful `lane.abort()` (below) ever runs. A job the runtime
-			// actually acknowledged already resolved the held tool call with its real
-			// outcome via `runtime.stop()` above; the only abort this stop still needs
-			// is the graceful one that stops the model from being prompted again, so
-			// `session.controller` must NOT be touched on that path (no other tool is
-			// concurrently in flight while generate_motion holds the turn). A stop
-			// for a job this turn never acknowledged (none active, or a retired one
-			// from an earlier turn) never resolved anything for THIS turn and stays a
-			// plain (loud) abort on both signals.
+			// Let the acknowledged job settle its held tool with that outcome before
+			// aborting the model lane. Aborting the shared signal would interrupt the
+			// tool first and lose the editor's proof. Without a held job, abort both.
 			if (!acknowledged) session.controller?.abort();
 			await session.modelSession?.abort?.("studio stop", acknowledged ? { quiet: true } : undefined);
 			json(res, 200, { ok: true, status: jobId ? "stopped" : "detached", ...(outcome ? { outcome: { status: outcome.status ?? null, code: outcome.code ?? null, mutated: outcome.mutated ?? null } } : {}) }); return true;
 		}
+		if (!studioRuntime && !hub && hubDeps.hubPortBusy) throw new StudioProtocolError("CAPABILITY_MISSING", `The Studio live hub could not start: port ${hubDeps.hubPortBusy} is in use by another CozyClay or its dev server. Free that port and relaunch.`);
 		if (!studioRuntime && (!hub?.command || !hub?.workspaceId)) throw new StudioProtocolError("CAPABILITY_MISSING", "Studio execution is not installed.");
 		if (!value.context.host.workspaceHandle) throw new StudioProtocolError("LIVE_HUB_UNAVAILABLE", "A connected editor handle is required.");
 		let session = studioSessions.get(value.sessionId);
@@ -440,7 +440,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			studioOwner(req, value.sessionId, true);
 			let persisted = null;
 			try { persisted = sessionStore.read(value.sessionId); } catch { persisted = null; }
-			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") : []), generationPrompt: null, host: null, updatedAt: clock() };
+			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();
@@ -468,33 +468,52 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		const admission = {
 			commandId: () => randomUUID(), host: studioIdentity(value.context.host), revision: value.context.revision.scene,
 			refresh: async () => {
-				const refreshed = studioRuntime?.readContext ? await studioRuntime.readContext(value.context.host) : await authoritativeStudioContext(value, hub);
+				// Read at the admitted host: a scene action may have opened another
+				// scene of this workspace during the turn (studio-tools adopts it).
+				const host = { ...value.context.host, ...admission.host };
+				const refreshed = studioRuntime?.readContext ? await studioRuntime.readContext(host) : await authoritativeStudioContext({ ...value, context: { ...value.context, host } }, hub);
 				admission.revision = refreshed.revision.scene;
 			},
 		};
-		const runtimeForJob = await studioRuntimeFor(hub);
-		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, session: { signal: controller.signal, admission }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
-		const motion = async args => {
-			if (session.generationPrompt === value.text) throw new StudioProtocolError("AUTH_REQUIRED", "This generation request already has a retained result; start a new explicit request.");
-			if (!runtimeForJob) throw new StudioProtocolError("CAPABILITY_MISSING", "Studio motion runtime is unavailable.");
-			const character = value.context.entities.find(entity => entity.id === args.characterId && entity.kind === "character");
-			if (!character) throw new StudioProtocolError("TARGET_NOT_READY", "The admitted character is unavailable.");
-			const commandId = randomUUID(); const host = { ...value.context.host, workspaceHandle: value.context.host.workspaceHandle };
-			const admissionResult = runtimeForJob.admit({ hostBinding: host, characterId: args.characterId, targetToken: character.token, turnId: value.turnId, commandId, authorization: { id: randomUUID(), generations: 1 }, source: args.source, repair: args.repair ?? "bounded" });
-			session.motionJobIds.add(admissionResult.jobId); persistenceMeta.motionJobIds = [...session.motionJobIds]; session.activeJobId = admissionResult.jobId; session.activeJobTurnId = value.turnId; session.generationPrompt = value.text;
-			const unsubscribe = runtimeForJob.subscribe(admissionResult.jobId, event => send({ ...event, sourceEventSeq: event.eventSeq }));
-			// Subscription precedes start, including replay of the queued admission event.
-			let outcome;
-			try { outcome = await runtimeForJob.start(admissionResult.jobId); if (outcome?.ok && outcome.status === "installed") send({ type: "receipt", receipt: outcome }); return outcome; }
-			finally {
-				unsubscribe();
-				// A job still awaiting an explicit accept (review_required) stays "active"
-				// for the accept route's ownership check (:678); every other outcome —
-				// installed, cancelled, proved-not-applied, failed, or a thrown error —
-				// is terminal for this session and must not leak into a later turn's Stop.
-				if (session.activeJobId === admissionResult.jobId && outcome?.status !== "review_required") { session.activeJobId = null; session.activeJobTurnId = null; }
+		// One motion generation per user message, whichever path starts it:
+		// generate_motion below and a run_action job action share this gate.
+		const generation = { used: false, failures: 0 };
+		// The editor's command index (authoritative context) declares each action's
+		// generation and hub timeout; no sidecar list of actions exists.
+		const controlJob = async (action, jobId) => {
+			await admission.refresh();
+			return hub.command('run_action', { name: 'run_action', args: { action, args: { jobId, ...(action === 'job.await' ? { timeoutMs: 300_000 } : {}) } },
+				commandId: randomUUID(), host: admission.host, expectedRevision: admission.revision }, value.context.host.workspaceHandle, { timeoutMs: 300_000 });
+		};
+		session.controlJob = controlJob;
+		const onJob = async started => {
+			const jobId = started.jobId;
+			session.motionJobIds.add(jobId);
+			persistenceMeta.motionJobIds = [...session.motionJobIds];
+			session.activeJobId = jobId; session.activeJobTurnId = value.turnId;
+			const cancel = () => { void controlJob('job.cancel', jobId).catch(error => send({ type: 'error', code: error.code ?? 'CANCEL_FAILED', message: error.message })); };
+			controller.signal.addEventListener('abort', cancel, { once: true });
+			if (controller.signal.aborted) cancel();
+			send({ type: 'job.state', jobId, commandId: started.commandId, state: 'generating', phase: 'generating' });
+			try {
+				const outcome = await controlJob('job.await', jobId);
+				send({ type: 'job.state', jobId, commandId: outcome.commandId, state: outcome.ok ? 'installed' : outcome.code === 'CANCELLED' ? 'cancelled' : 'failed', phase: 'complete' });
+				return outcome;
+			} finally {
+				controller.signal.removeEventListener('abort', cancel);
+				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 motion = async args => {
+			// Private artifact IDs belonged to the retired sidecar runtime. Reuse
+			// retained editor takes through motion.loadVersion, not another installer.
+			if (args.source.kind !== 'generate') throw new StudioProtocolError('CAPABILITY_MISSING', 'Private motion artifacts are no longer retained. Use motion.loadVersion for an editor take.');
+			await tools.internal.invoke('inspect_studio', { scope: 'motion', ids: [args.characterId] });
+			const receipt = await tools.internal.invoke('generate_motion', args);
+			if (receipt.ok && receipt.status === 'completed') send({ type: 'receipt', receipt });
+			return receipt;
+		};
 		const modelTools = tools.map(tool => ({
 			...tool,
 			handler: async args => {
@@ -699,14 +718,6 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			}
 			return true;
 		}
-		if (path.startsWith("/agent/jobs/") && path.endsWith("/accept") && req.method === "POST") {
-			if (!await hasAnyCredential()) { json(res, 401, { error: { code: "AUTH_REQUIRED", message: "Sign in or configure a provider key." } }); return true; }
-			let value; try { value = await readBody(req); } catch { json(res, 400, { error: "invalid request" }); return true; }
-			const jobId = decodeURIComponent(path.slice("/agent/jobs/".length, -"/accept".length)); const session = studioSessions.get(value?.sessionId);
-			if (!session || session.owner !== parseCookies(req).studio_owner || value.surface !== "studio" || value.explicitUnverifiedAcceptance !== true || !session.turns.has(value.turnId) || session.activeJobId !== jobId) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Only the owning Studio UI may accept this candidate." } }); return true; }
-			try { const receipt = await ownedStudioRuntime.accept(jobId); const record = studioEvents.get(value.turnId); if (record) { emitStudioEvent(value.turnId, { type: "receipt", receipt }); emitStudioEvent(value.turnId, { type: "done" }); record.terminal = true; } session.activeJobId = null; session.activeJobTurnId = null; json(res, 200, { receipt }); } catch (error) { json(res, 409, { error: { code: error.code || "VERIFICATION_FAILED", message: error.message } }); }
-			return true;
-		}
 		if (req.method !== "POST" || !["/agent/turn", "/agent/stop"].includes(path)) {
 			json(res, 404, { error: "not found" }); return true;
 		}
@@ -841,7 +852,6 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		for (const runner of workflowRunners.values()) await runner.close?.();
 		for (const runner of studioRunners.values()) await runner.close?.();
 		workflowRunners.clear(); studioRunners.clear();
-		if (ownedStudioRuntime?.dispose) await ownedStudioRuntime.dispose();
 		studioSessions.clear(); studioEvents.clear(); studioOwnerTokens.clear();
 		sessions.clear();
 		const { liveHub: hub } = await runtime;

package/bin/agent/agent-runner.mjs

@@ -228,11 +228,18 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 			const messages = entries.filter((entry) => entry.type === "message").map((entry) => entry.message);
 			if (messages.length <= state.persisted) return;
 			const aborted = state.active?.abortRequested === true;
-			const pending = messages.slice(state.persisted).filter((message) => !(aborted && message?.role === "assistant") && !(message?.role === "assistant" && message?.stopReason === "error"));
+			const newlyGenerated = messages.slice(state.persisted);
+			const failedAssistant = newlyGenerated.find((message) => message?.role === "assistant" && (aborted || message.stopReason === "error"));
+			const pending = newlyGenerated.filter((message) => !(aborted && message?.role === "assistant") && !(message?.role === "assistant" && message?.stopReason === "error"));
 			state.persisted = messages.length;
-			if (!pending.length) return;
 			const input = state.lastInput || {};
-			await sessionStore.append(sessionId, pending, { surface, ...(input.meta || {}) });
+			if (pending.length) await sessionStore.append(sessionId, pending, { surface, ...(input.meta || {}) });
+			if (failedAssistant && sessionStore.appendTurnError) {
+				const rawMessage = failedAssistant.errorMessage || "The model or live editor could not complete this turn.";
+				const message = aborted ? "The turn was aborted." : sanitizeUpstreamDetail(JSON.stringify({ message: rawMessage })) || rawMessage;
+				const code = aborted ? "aborted" : classifyProviderError(rawMessage);
+				await sessionStore.appendTurnError(sessionId, { code, message, at: new Date().toISOString() }, { surface, ...(input.meta || {}) });
+			}
 		};
 
 		// pi calls AgentTool.execute(toolCallId, params, signal, onUpdate) — the