cozyclay 2.0.2 → 2.1.1

package/bin/agent/studio-rebase.mjs

@@ -0,0 +1,314 @@
+// Auto-rebase policy for a Studio command refused at admission.
+//
+// STALE_SCENE and TARGET_BUSY are admission refusals: the editor applied
+// nothing. The agent used to pay a whole model turn per refusal (inspect, then
+// resubmit). This module decides, conservatively and from evidence, when the
+// identical command may be re-sent once, and what to tell the model when it may
+// not. Pure functions over plain context/entity rows; no I/O but `fetchRows`.
+//
+// What "unchanged" means. The editor mints one `token` per entity and rotates
+// it whenever any non-display field of that entity changes (position, rotation,
+// scale, colour, parent, motion, ...; display-only name/tint do not rotate it).
+// The agent's baseline is the token it last SAW for an id:
+//   - the turn's own context (detailed rows),
+//   - inspect_studio rows,
+//   - the state right after the agent's own applied command (read back from the
+//     authoritative context at the revision that command published),
+//   - the fresh state quoted in an earlier teaching error.
+// An entity the agent merely saw as an index row (id/name/position) has no
+// token and cannot be proven unchanged.
+const IDENTITY = ["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"];
+/** Tools whose targets are entities with tokens. Shot/stage patches, framing,
+ * actions, undo and view changes carry no per-entity fingerprint: never retried. */
+const REBASE_TOOLS = new Set(["arrange_objects", "arrange_characters", "patch_elements"]);
+const DISPLAY_SKIP = new Set(["token", "detailsOmitted"]);
+const MAX_LINES = 8, MAX_FIELDS = 6, MESSAGE_CAP = 900;
+
+const round = value => typeof value === "number" ? Math.round(value * 100) / 100 : value;
+const norm = value => Array.isArray(value) ? value.map(norm)
+  : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, norm(value[key])])) : round(value);
+const same = (a, b) => JSON.stringify(norm(a)) === JSON.stringify(norm(b));
+const show = value => {
+  const n = norm(value);
+  if (n && typeof n === "object" && ["x", "y", "z"].every(axis => typeof n[axis] === "number")) return `(${n.x}, ${n.y}, ${n.z})`;
+  const text = JSON.stringify(n);
+  return text === undefined ? "absent" : text.length > 48 ? `${text.slice(0, 47)}…` : text;
+};
+const sameHost = (a, b) => Boolean(a && b) && IDENTITY.every(key => a[key] === b[key]);
+const nameKey = value => typeof value === "string" ? value.normalize("NFC").trim().toLowerCase() : null;
+
+/** The agent's record of what it last saw per entity id. */
+function createSeen(baseline) {
+  const rows = new Map();   // id -> detailed row carrying a token
+  const known = new Set();  // every id the agent has been shown, detailed or indexed
+  const index = new Map();  // id -> last compact row (name/position) the agent saw
+  const seen = {
+    hasBaseline: false,
+    rows, known,
+    observeRow(row) {
+      if (!row || typeof row.id !== "string") return;
+      known.add(row.id);
+      if (typeof row.token === "string") { rows.set(row.id, structuredClone(row)); index.set(row.id, { name: row.name, position: row.position }); }
+      else seen.observeIndexRow(row);
+    },
+    observeIndexRow(row) {
+      if (!row || typeof row.id !== "string") return;
+      known.add(row.id);
+      const before = rows.get(row.id);
+      // A compact row that disagrees with the stored detail is newer knowledge
+      // without a token: the stored token no longer describes what was seen.
+      if (before && (!same(before.name, row.name) || !same(before.position, row.position))) rows.delete(row.id);
+      index.set(row.id, { name: row.name, position: row.position });
+    },
+    /** Everything in a context (or only `only` ids) was shown to the agent. */
+    observeContext(context, only = null) {
+      if (!context || typeof context !== "object") return;
+      const wanted = id => !only || only.has(id);
+      const detailed = new Set();
+      for (const row of Array.isArray(context.entities) ? context.entities : []) { detailed.add(row?.id); if (wanted(row?.id)) seen.observeRow(row); }
+      for (const row of Array.isArray(context.entityIndex) ? context.entityIndex : []) if (!detailed.has(row?.id) && wanted(row?.id)) seen.observeIndexRow(row);
+      if (!only) seen.hasBaseline = true;
+    },
+    /** Result of any tool: inspect rows and context, read defensively from either shape. */
+    observeResult(result) {
+      if (!result || typeof result !== "object") return;
+      if (result.context) seen.observeContext(result.context);
+      for (const row of Array.isArray(result.entities) ? result.entities : []) seen.observeRow(row);
+    },
+    /** The agent no longer holds a verifiable view of these ids. */
+    forget(ids) { for (const id of ids) rows.delete(id); },
+    drop(ids) { for (const id of ids) { rows.delete(id); known.delete(id); index.delete(id); } },
+  };
+  if (baseline) seen.observeContext(baseline);
+  return seen;
+}
+
+/** Every id-shaped string an argument tree mentions. Over-approximate on purpose:
+ * a string that merely equals an entity id makes that entity a target. */
+function referencedStrings(value, out = new Set()) {
+  if (typeof value === "string") out.add(value);
+  else if (Array.isArray(value)) for (const item of value) referencedStrings(item, out);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) referencedStrings(item, out);
+  return out;
+}
+
+function eligibility(name, args) {
+  if (!REBASE_TOOLS.has(name)) return `${name} reads state with no per-entity fingerprint, so it is never replayed automatically`;
+  if (name === "patch_elements" && args.ops.some(op => op?.target?.kind !== "object" && op?.target?.kind !== "character")) return "shot and stage edits have no per-entity fingerprint, so they are never replayed automatically";
+  return null;
+}
+
+function diffRow(base, current) {
+  if (current.detailsOmitted) return [];
+  const fields = [...new Set([...Object.keys(base), ...Object.keys(current)])].filter(key => !DISPLAY_SKIP.has(key));
+  const lines = [];
+  for (const key of fields) if (!same(base[key], current[key])) lines.push(`${key} ${show(base[key])} -> ${show(current[key])}`);
+  return lines;
+}
+
+const rowsById = rows => new Map((Array.isArray(rows) ? rows : []).filter(row => typeof row?.id === "string").map(row => [row.id, row]));
+
+/** Compare the agent's baseline with the fresh authoritative context. */
+function surveyChanges(seen, fresh, extraRows = new Map()) {
+  const detailed = rowsById(fresh?.entities);
+  for (const [id, row] of extraRows) detailed.set(id, row);
+  const indexed = rowsById(fresh?.entityIndex);
+  const changed = [], removed = [], unchecked = [];
+  for (const [id, base] of seen.rows) {
+    const current = detailed.get(id);
+    if (current) { if (current.token !== base.token || !same(base.name, current.name)) changed.push({ id, fields: diffRow(base, current) }); }
+    else if (indexed.has(id)) unchecked.push(id);
+    else removed.push(id);
+  }
+  for (const id of seen.known) if (!seen.rows.has(id) && !detailed.has(id) && !indexed.has(id)) removed.push(id);
+  const added = [...new Set([...detailed.keys(), ...indexed.keys()])].filter(id => !seen.known.has(id));
+  return { changed, removed: [...new Set(removed)], added, unchecked };
+}
+
+const describeChanges = (survey, only = null) => {
+  const wanted = id => !only || only.has(id);
+  const lines = [];
+  for (const { id, fields } of survey.changed) if (wanted(id)) lines.push(`${id}: ${fields.length ? fields.slice(0, MAX_FIELDS).join("; ") : "changed (fields not itemised)"}`);
+  const removed = survey.removed.filter(wanted);
+  if (removed.length) lines.push(`removed: ${removed.slice(0, 8).join(", ")}`);
+  if (!only && survey.added.length) lines.push(`added: ${survey.added.slice(0, 8).join(", ")}${survey.added.length > 8 ? ` (+${survey.added.length - 8})` : ""}`);
+  return lines.length > MAX_LINES ? [...lines.slice(0, MAX_LINES), `(+${lines.length - MAX_LINES} more)`] : lines;
+};
+
+/**
+ * Decide whether the refused command may be re-sent once.
+ * Retry only when ALL hold:
+ *  1. the tool is arrange_objects, arrange_characters, or patch_elements on object/character targets;
+ *  2. the refusal proved nothing was applied (the caller checks the receipt);
+ *  3. the fresh context is the SAME document identity and its revision differs from the one refused;
+ *  4. every id the arguments mention that the agent knows is still present, with the SAME token and
+ *     name the agent last saw (a token the agent never saw counts as changed);
+ *  5. for create ops, no entity the agent has not seen carries the same name.
+ */
+async function decideRebase({ name, args, seen, fresh, host, refusedRevision, fetchRows }) {
+  const survey = () => surveyChanges(seen, fresh, extra);
+  const extra = new Map();
+  const result = (retry, reason, targets = [], only = null) => ({ retry, reason, targets, survey: survey(), lines: describeChanges(survey(), only) });
+  if (!fresh || typeof fresh !== "object" || !fresh.revision) return { retry: false, reason: "no fresh context", targets: [], survey: null, lines: [] };
+  if (!sameHost(host, fresh.host)) return result(false, "the live document or scene changed, not just its contents");
+  if (fresh.revision.scene === refusedRevision) return result(false, "the scene revision did not move, so a resend would be refused the same way");
+  const blocked = eligibility(name, args);
+  if (blocked) return result(false, blocked);
+
+  const freshIds = new Set([...rowsById(fresh.entities).keys(), ...rowsById(fresh.entityIndex).keys()]);
+  const mentioned = referencedStrings(args);
+  const targets = [...new Set([...mentioned].filter(value => seen.known.has(value) || freshIds.has(value)))];
+  const ops = Array.isArray(args.ops) ? args.ops : [];
+  const creates = ops.filter(op => op?.op === "create");
+  if (!targets.length && !seen.hasBaseline) return result(false, "the agent has no recorded view of the scene to compare against");
+
+  const detailed = rowsById(fresh.entities);
+  const needDetail = targets.filter(id => !detailed.has(id) && freshIds.has(id));
+  if (needDetail.length && typeof fetchRows === "function") {
+    try { for (const row of await fetchRows(needDetail)) if (typeof row?.id === "string" && typeof row.token === "string") extra.set(row.id, row); } catch { /* unverifiable below */ }
+  }
+  const current = id => extra.get(id) ?? detailed.get(id);
+  const reasons = [];
+  for (const id of targets) {
+    const base = seen.rows.get(id), row = current(id);
+    if (!freshIds.has(id)) reasons.push(`${id} no longer exists`);
+    else if (!seen.known.has(id)) reasons.push(`${id} is new since you last looked`);
+    else if (!base) reasons.push(`${id} was not read with detail since it last changed (or you edited it before the edit reached you); its state cannot be proven unchanged`);
+    else if (!row) reasons.push(`${id} could not be re-read`);
+    else if (row.token !== base.token) reasons.push(`${id} was edited by someone else`);
+    else if (!same(base.name, row.name)) reasons.push(`${id} was renamed`);
+  }
+  if (reasons.length) {
+    const only = new Set(targets);
+    return { ...result(false, reasons.join("; "), targets, only), failedTargets: reasons };
+  }
+  const taken = new Map();
+  for (const row of [...rowsById(fresh.entities).values(), ...rowsById(fresh.entityIndex).values()]) if (!seen.known.has(row.id) && nameKey(row.name)) taken.set(nameKey(row.name), row.id);
+  const collisions = creates.map(op => nameKey(op.name)).filter(key => key && taken.has(key));
+  if (collisions.length) return result(false, `an object named "${collisions[0]}" appeared since you last looked (${taken.get(collisions[0])})`, targets);
+  return result(true, "targets unchanged", targets);
+}
+
+const trim = text => text.length > MESSAGE_CAP ? `${text.slice(0, MESSAGE_CAP - 1)}…` : text;
+
+/** The teaching text appended to a STALE_SCENE the agent must handle itself. */
+function staleTeaching({ original, verdict, refusedRevision, freshRevision, name }) {
+  const detail = verdict.lines.length ? ` What changed since you last looked: ${verdict.lines.join(" | ")}.` : "";
+  const why = verdict.reason === "no fresh context" ? "" : ` Not retried automatically: ${verdict.reason}.`;
+  return trim(`${original}${why}${detail} Your admission is already refreshed to revision ${freshRevision}${refusedRevision !== undefined ? ` (was ${refusedRevision})` : ""}: adapt ${name} to the state above and resubmit it; inspect again only for ids not listed.`);
+}
+
+/** The teaching text for a TARGET_BUSY that outlived the wait. */
+function busyTeaching({ original, waitedMs, ids }) {
+  const gesture = /gesture/i.test(original);
+  const target = ids.length ? ` (it targets ${ids.slice(0, 6).join(", ")})` : "";
+  return trim(gesture
+    ? `${original} The user is dragging or editing in the editor right now${target}; nothing was applied. Waited ${waitedMs} ms and retried once, still busy. Do not loop on this tool: tell the user you are waiting, then retry after they release.`
+    : `${original} Nothing was applied. Waited ${waitedMs} ms and retried once, still busy${target}. Do not loop on this tool: finish or cancel the open operation, or ask the user.`);
+}
+
+/** Mark a result that only succeeded because the sidecar re-sent it. */
+function annotateRebased(result, info) {
+  const message = trim(info.reason === "target_busy"
+    ? `Editor was mid-gesture; waited ${info.waitedMs} ms and re-sent the command once.`
+    : `Scene revision moved ${info.fromRevision} -> ${info.toRevision} by edits that left the targets unchanged; command re-sent once.`).slice(0, 120);
+  const warnings = [...(Array.isArray(result?.warnings) ? result.warnings : []), { code: "AUTO_REBASED", message }];
+  return { ...result, autoRebased: true, autoRebase: info, warnings };
+}
+
+// One bounded wait for a TARGET_BUSY editor gesture to end (under the 1.5 s ceiling).
+export const BUSY_WAIT_MS = 1200;
+const sleepUnlessAborted = (ms, signal) => new Promise(resolve => {
+  if (signal?.aborted) return resolve(false);
+  const done = value => { clearTimeout(timer); signal?.removeEventListener?.("abort", onAbort); resolve(value); };
+  const onAbort = () => done(false);
+  const timer = setTimeout(() => done(true), ms);
+  signal?.addEventListener?.("abort", onAbort, { once: true });
+});
+
+/**
+ * The recovery wrapper around one admission attempt (`attempt(name, args, scratch)`
+ * in studio-tools.mjs, which fills `scratch.fresh`, `.refusedRevision`, `.generation`).
+ * Exactly one re-send per call, whichever refusal: a second one is the model's.
+ */
+export function createRebaser({ session, liveHub, workspaceHandle, mutationNames, attempt }) {
+  const seen = createSeen(session?.baseline);
+  const admission = session?.admission;
+  /** An inspect result re-admits at its revision (either result shape) and shows the agent entity state. */
+  const afterInspect = result => {
+    const revision = result?.context?.revision?.scene ?? result?.revision?.scene ?? result?.revision;
+    if (Number.isSafeInteger(revision) && admission) admission.revision = revision;
+    seen.observeResult(result);
+  };
+  // The agent's own applied command is the newest thing it knows about the
+  // entities it touched. When the receipt carries their tokens use them;
+  // otherwise read the authoritative context, trusting it only at the revision
+  // that command published (nothing slipped in between).
+  const observeOwnEdit = async result => {
+    const affected = new Set(Array.isArray(result?.affectedIds) ? result.affectedIds : []);
+    if (!affected.size || result?.ok === false) return;
+    const tokened = new Set();
+    for (const item of Array.isArray(result.delta) ? result.delta : []) {
+      if (affected.has(item?.id) && typeof item.after?.token === "string") { tokened.add(item.id); seen.observeRow({ ...(seen.rows.get(item.id) ?? {}), ...item.after, id: item.id }); }
+    }
+    const rest = new Set([...affected].filter(id => !tokened.has(id)));
+    if (!rest.size) return;
+    seen.forget(rest);
+    if (typeof admission?.snapshot !== "function") return;
+    try {
+      const snapshot = await admission.snapshot();
+      if (snapshot?.revision?.scene !== admission.revision) return;
+      seen.observeContext(snapshot, rest);
+      const present = new Set([...(snapshot.entities ?? []), ...(snapshot.entityIndex ?? [])].map(row => row.id));
+      seen.drop([...rest].filter(id => !present.has(id)));
+    } catch { /* the edit stays unverifiable; a later stale is simply not retried */ }
+  };
+  const fetchRows = async ids => {
+    const read = await liveHub.command("inspect_studio", { scope: "entities", ids: ids.slice(0, 32), limit: Math.min(32, ids.length) }, workspaceHandle);
+    return Array.isArray(read?.entities) ? read.entities : [];
+  };
+  const run = async (name, args) => {
+    const scratch = {};
+    try { return await attempt(name, args, scratch); }
+    catch (error) {
+      const refused = error?.receipt?.mutated === undefined || error.receipt.mutated === false; // nothing applied, provably
+      if (!admission || !mutationNames.has(name) || name === "verify_result" || !refused || scratch.generation) throw error;
+      const targetIds = () => [...referencedStrings(args)].filter(id => seen.known.has(id));
+      if (error?.code === "TARGET_BUSY") {
+        const waitedMs = session.busyWaitMs ?? BUSY_WAIT_MS;
+        if (!await (session.sleep ?? sleepUnlessAborted)(waitedMs, session.signal)) throw error;
+        try { return annotateRebased(await attempt(name, args, {}), { reason: "target_busy", waitedMs, retried: true }); }
+        catch (second) {
+          if (second?.code !== "TARGET_BUSY") throw second;
+          throw Object.assign(new Error(busyTeaching({ original: second.message, waitedMs, ids: targetIds() })), { code: "TARGET_BUSY", receipt: second.receipt, autoRebased: false });
+        }
+      }
+      if (error?.code !== "STALE_SCENE" || !scratch.fresh) throw error;
+      const fromRevision = scratch.refusedRevision, fresh = scratch.fresh;
+      let verdict;
+      try { verdict = await decideRebase({ name, args, seen, fresh, host: admission.host, refusedRevision: fromRevision, fetchRows }); }
+      catch { throw error; }
+      if (!verdict.retry) {
+        // The teaching error quotes the fresh state of what it lists, so that is
+        // now what the agent has seen of those ids.
+        seen.observeContext(fresh, new Set([...verdict.survey?.changed.map(item => item.id) ?? [], ...verdict.targets]));
+        seen.drop(verdict.survey?.removed ?? []);
+        throw Object.assign(new Error(staleTeaching({ original: error.message, verdict, refusedRevision: fromRevision, freshRevision: fresh.revision?.scene ?? admission.revision, name })), { code: "STALE_SCENE", receipt: error.receipt, autoRebased: false });
+      }
+      const unrelated = (verdict.survey?.changed.length ?? 0) + (verdict.survey?.added.length ?? 0) + (verdict.survey?.removed.length ?? 0);
+      const again = {};
+      let result;
+      try { result = await attempt(name, args, again); }
+      catch (second) {
+        // The one re-send was spent. Say what moved so the model need not guess.
+        if (second?.code !== "STALE_SCENE" || !again.fresh) throw second;
+        let more = null;
+        try { more = await decideRebase({ name, args, seen, fresh: again.fresh, host: admission.host, refusedRevision: again.refusedRevision, fetchRows }); } catch { /* plain error below */ }
+        const verdict2 = { ...(more ?? { lines: [], survey: null, targets: [] }), reason: `it was already re-sent once automatically (revision ${fromRevision} -> ${fresh.revision.scene}) and the scene moved again` };
+        throw Object.assign(new Error(staleTeaching({ original: second.message, verdict: verdict2, refusedRevision: again.refusedRevision, freshRevision: again.fresh.revision?.scene ?? admission.revision, name })), { code: "STALE_SCENE", receipt: second.receipt, autoRebased: false });
+      }
+      return annotateRebased(result, { reason: "stale_scene", fromRevision, toRevision: fresh.revision.scene, retried: true, targets: verdict.targets, unrelatedChanges: unrelated });
+    }
+  };
+  return { seen, afterInspect, observeOwnEdit, run };
+}

package/bin/agent/studio-tools.mjs

@@ -1,15 +1,16 @@
 import { validateStudioCommand, validateStudioIdentity, STUDIO_TOOL_SCHEMAS, STUDIO_TOOLS, StudioProtocolError } from "../../src/studio-agent-protocol.js";
 import { MAX_COMMAND_TIMEOUT_MS } from "../../mcp/live-hub.mjs";
 import { generationArgs } from '../../src/motion/generation.js';
+import { createRebaser } from "./studio-rebase.mjs";
 
-const STUDIO_TOOL_RECEIPT_NOTE = " The result may be a receipt with status \"partial\": ops[].droppedPaths names exactly which authored path each op refused, and delta[].after carries the value actually landed for that target -- quote both the requested and the landed value when you report this, never say only that some paths were not applied. A STALE_SCENE error means inspect_studio once for the fresh revision, then resubmit the identical operation with that revision; it is not a permanent failure.";
+const STUDIO_TOOL_RECEIPT_NOTE = " The result may be a receipt with status \"partial\": ops[].droppedPaths names exactly which authored path each op refused, and delta[].after carries the value actually landed for that target -- quote both the requested and the landed value when you report this, never say only that some paths were not applied. The sidecar re-sends a command once, by itself, when the scene revision moved but every target is unchanged or the editor was briefly mid-gesture; such a receipt carries autoRebased: true and an AUTO_REBASED warning -- mention it. A STALE_SCENE error that still reaches you lists what changed (ids and fields) and the admission is already refreshed: adapt the operation to that and resubmit it; call inspect_studio again only for ids the list does not cover; it is not a permanent failure. A TARGET_BUSY error means the user is mid-gesture; do not loop on it.";
 const STUDIO_INSPECT_NOTE = ' The per-turn context contains entityIndex and actionIndex. Read authored state and its set schemas with scope "document", optionally selecting kinds or ids. Legacy scene/shot/motion/selection scopes are document projections too; runtime facts remain in context. Scope "entities" pages entity detail by ids or query. Pass nextCursor as cursor for the next page; on STALE_CURSOR restart without it. Scope "catalogue" lists placeable kinds and patchable paths.';
 const STUDIO_MUTATION_TOOLS = new Set(["operate_studio", "arrange_objects", "arrange_characters", "patch_elements", "frame_shot", "verify_result", "undo_edit", "run_action"]);
 const schema = name => ({ type: "function", name, description: `Studio ${name.replaceAll("_", " ")} command.${name === "generate_motion" ? " Timing: give EITHER source.durationSeconds (total) with NO per-beat seconds, OR seconds on EVERY beat with NO durationSeconds. Generation is an alias for motion.generate in the editor, including the character's root path, pose controls and take preservation. A completed receipt is undoable with undo_edit; a started receipt carries jobId for run_action job.await or job.cancel. Generation does not certify motion quality: use verify_result for motion checks and report its evidence and any warnings. One generation per user message: a second call fails with GENERATION_LIMIT." : ""}${name === "verify_result" ? " Pass exactly one of receiptId or targets (not both). An earlier receipt stays verifiable after later edits: it answers stale: true with evidenceRevision (the revision that receipt describes) beside revision (the current one), and a requested frame is captured from the current scene; report the evidence as stale, never as current." : ""}${name === "inspect_studio" ? `${STUDIO_INSPECT_NOTE} scope "actions" lists the editor actions for run_action with their availability (the reason when unavailable); with ids it answers those actions' descriptions and input schemas.` : ""}${name === "run_action" ? " Run one editor action by id (actionIndex in the context lists them) with args matching its input schema; read the schema first with inspect_studio scope \"actions\" and ids instead of guessing. A mutating action answers with a receipt (action, summary, delta) that undo_edit reverts; a job action answers status \"started\", or \"completed\" with its output when it runs to its end; only an action declared generation \"motion\" counts as this message's one generation. A document action (scenes, the project file) answers status \"completed\" and is not undoable; when it opens another scene, its host names that scene and later commands are admitted there." : ""}${STUDIO_MUTATION_TOOLS.has(name) ? STUDIO_TOOL_RECEIPT_NOTE : ""}`, parameters: STUDIO_TOOL_SCHEMAS[name] });
 export const studioToolSchemas = () => STUDIO_TOOLS.map(schema);
 const text = value => typeof value === "string" ? value : JSON.stringify(value);
 
-export function createStudioTools({ liveHub, workspaceHandle, session, resolveImage } = {}) {
+export function createStudioTools({ liveHub, workspaceHandle, session, resolveImage, previsMode } = {}) {
   if (!liveHub?.command || !workspaceHandle) throw new StudioProtocolError("LIVE_HUB_UNAVAILABLE", "An exact Studio workspace is required.");
   const mutationNames = STUDIO_MUTATION_TOOLS;
   // The turn's command index (the context's actionIndex, from the editor's own
@@ -21,17 +22,23 @@ export function createStudioTools({ liveHub, workspaceHandle, session, resolveIm
   // One motion generation per user message, shared with generate_motion when
   // the route passes the turn's gate; a bare tools instance keeps its own.
   const generationGate = session?.generation ?? { used: false, failures: 0 };
-  const invoke = async (name, args) => {
+  // What the agent last saw per entity: the basis for deciding that a stale
+  // revision left its targets untouched (studio-rebase.mjs).
+  const rebaser = createRebaser({ session, liveHub, workspaceHandle, mutationNames, attempt: (name, args, scratch) => attempt(name, args, scratch) });
+  // One admission attempt. `scratch` carries what the recovery path needs from
+  // a refusal: the revision it was admitted at and the context re-read for it.
+  const attempt = async (name, args, scratch = {}) => {
     const command = validateStudioCommand({ name, args });
-    if (name === 'generate_motion' && command.args.source.kind === 'generate') return invoke('run_action', { action: 'motion.generate', args: generationArgs(command.args) });
+    if (name === 'generate_motion' && command.args.source.kind === 'generate') return rebaser.run('run_action', { action: 'motion.generate', args: generationArgs(command.args) });
     const action = name === "run_action" ? declared.get(command.args.action) : undefined;
     const generation = action?.generation === "motion";
     if (generation && (generationGate.used || generationGate.pending)) throw new StudioProtocolError("GENERATION_LIMIT", "One motion generation per user message. Report this result and ask the user before generating again.");
     if (generation && (generationGate.failures ?? 0) >= 2) throw new StudioProtocolError("GENERATION_LIMIT", "Two motion generation attempts already failed in this user message. Report both failures to the user and ask before generating again.");
     const payload = mutationNames.has(name) && session?.admission
-      ? { name, args: command.args, commandId: session.admission.commandId(), host: session.admission.host, expectedRevision: session.admission.revision,
+      ? { name, args: command.args, commandId: session.admission.commandId(), host: session.admission.host, expectedRevision: session.admission.revision, ...(session.admission.turnId ? { turnId: session.admission.turnId } : {}),
           ...(generation && session.onJob ? { wait: false } : {}) }
       : command.args;
+    Object.assign(scratch, { generation, refusedRevision: payload.expectedRevision });
     let result;
     if (generation) generationGate.pending = true;
     try {
@@ -45,7 +52,7 @@ export function createStudioTools({ liveHub, workspaceHandle, session, resolveIm
       // A STALE_SCENE re-admits whichever family met it, so the retry the
       // model is told to make is admitted at the live revision.
       if (generation) generationGate.failures = (generationGate.failures ?? 0) + 1;
-      if (session?.admission && (error?.code === "STALE_SCENE" || (mutationNames.has(name) && error?.code === "UNCERTAIN_APPLY"))) await session.admission.refresh();
+      if (session?.admission && (error?.code === "STALE_SCENE" || (mutationNames.has(name) && error?.code === "UNCERTAIN_APPLY"))) scratch.fresh = await session.admission.refresh();
       throw error;
     } finally { if (generation) generationGate.pending = false; }
     if (result?.ok === false) {
@@ -54,7 +61,7 @@ export function createStudioTools({ liveHub, workspaceHandle, session, resolveIm
       const code = result.code ?? result.error?.code;
       const message = result.message ?? result.error?.message ?? "Studio command failed";
       if (generation) generationGate.failures = (generationGate.failures ?? 0) + 1;
-      if (session?.admission && (code === "STALE_SCENE" || result.mutated === true)) await session.admission.refresh();
+      if (session?.admission && (code === "STALE_SCENE" || result.mutated === true)) scratch.fresh = await session.admission.refresh();
       // An acknowledged Stop must settle its held card with the bus outcome,
       // not turn a proved cancellation into an interrupted/unknown tool.
       if (code === 'CANCELLED' && session?.onJob) return result;
@@ -66,16 +73,16 @@ export function createStudioTools({ liveHub, workspaceHandle, session, resolveIm
     if (name === "run_action" && result?.host && session?.admission && result.host.workspaceId === session.admission.host.workspaceId) {
       session.admission.host = validateStudioIdentity(result.host);
     }
-    if (name === "inspect_studio" && Number.isSafeInteger(result?.context?.revision?.scene) && session?.admission) {
-      session.admission.revision = result.context.revision.scene;
-    }
+    // An inspect reports the live revision at its top level (older editors embedded a context).
+    if (name === "inspect_studio") rebaser.afterInspect(result);
     if (mutationNames.has(name) && session?.admission) {
-      if (Number.isSafeInteger(result?.revision?.after)) session.admission.revision = result.revision.after;
-      else await session.admission.refresh();
+      if (Number.isSafeInteger(result?.revision?.after)) session.admission.revision = result.revision.after; else await session.admission.refresh();
+      await rebaser.observeOwnEdit(result);
     }
     return result;
   };
-  const tools = STUDIO_TOOLS.map(name => ({ ...schema(name), handler: args => invoke(name, args) }));
+	const availableTools = previsMode === "storyboard" ? STUDIO_TOOLS.filter(name => name !== "generate_motion") : STUDIO_TOOLS;
+	const tools = availableTools.map(name => ({ ...schema(name), handler: args => rebaser.run(name, args) }));
   tools.resolveImage = async (imageId, correlation = {}) => {
     if (typeof resolveImage !== "function") return { visualStatus: "unavailable", reason: "image resolver unavailable" };
     try {
@@ -84,7 +91,7 @@ export function createStudioTools({ liveHub, workspaceHandle, session, resolveIm
       return { visualStatus: "attached", dataUrl: result.dataUrl, imageId, revision: result.revision ?? null, receiptId: result.receiptId ?? correlation.receiptId ?? null };
     } catch { return { visualStatus: "unavailable", reason: "image attachment failed", imageId }; }
   };
-  tools.internal = { invoke };
+  tools.internal = { invoke: rebaser.run };
   return tools;
 }
 export function studioToolResult(result) { return text(result); }