shotops-mcp 0.9.5 → 0.9.6

package/dist/local.js

@@ -24,7 +24,7 @@
   }
   await visit('')
   return hash.digest('hex')
-})(sourceDirectory) !== "05d27ff2f672ea1fb99121eb514c734ec24b952b84ee842baa15d9cf8a0e9e89") {
+})(sourceDirectory) !== "5df467e22a054acf0779df03013843f6f55d0a3e8cb9f87ecca7dca8eef02f46") {
           console.error('shotops-mcp: dist/local.js is stale; run npm run build in shotops-mcp.');
         }
       } catch { /* An unreadable checkout must not break an otherwise working CLI. */ }
@@ -1892,6 +1892,12 @@ var init_fonts = __esm({
 });
 
 // ../mockup-engine/appstore/refineIntent.ts
+function requestsBroaderDeviceScope(instruction) {
+  return BROADER_DEVICE_SCOPE.test(instruction) || NUMBERED_SIBLING_SCOPE.test(instruction);
+}
+function canRepairLayoutForFocus(focus, instruction) {
+  return focus?.kind !== "device" || requestsBroaderDeviceScope(instruction);
+}
 function structuralOperationTargets(operation) {
   switch (operation.op) {
     case "frame.add":
@@ -1931,7 +1937,7 @@ function resolveAiNumber(input, current, range) {
   if (raw === void 0 || !Number.isFinite(raw)) return void 0;
   return Math.min(Math.max(raw, range.min), range.max);
 }
-var MAX_REFINE_PROMPT_LENGTH, AI_COLORWAY_IDS, AI_CLAY_TONES, AI_SHOT_RANGES, AI_SCALE_RANGE, AI_CAPTION_FONT_IDS, AI_CAPTION_RANGES, AI_GRADIENT_STOPS;
+var MAX_REFINE_PROMPT_LENGTH, AI_COLORWAY_IDS, AI_CLAY_TONES, AI_SHOT_RANGES, AI_SCALE_RANGE, AI_CAPTION_FONT_IDS, AI_CAPTION_RANGES, AI_GRADIENT_STOPS, BROADER_DEVICE_SCOPE, NUMBERED_SIBLING_SCOPE;
 var init_refineIntent = __esm({
   "../mockup-engine/appstore/refineIntent.ts"() {
     "use strict";
@@ -1949,6 +1955,8 @@ var init_refineIntent = __esm({
     AI_CAPTION_FONT_IDS = CAPTION_FONT_IDS;
     AI_CAPTION_RANGES = CAPTION_STYLE_BOUNDS;
     AI_GRADIENT_STOPS = { min: 1, max: 6 };
+    BROADER_DEVICE_SCOPE = /\b(?:all|every|each|both|entire|whole|across|throughout|other|others|rest|remaining|project|strip|frames|screenshots|screens|devices|phones|captions)\b/i;
+    NUMBERED_SIBLING_SCOPE = /\b(?:frame|device|phone)\s+\d+\b/i;
   }
 });
 
@@ -3259,7 +3267,7 @@ function presetCaptionStyle(preset) {
   return { ...preset.caption };
 }
 function presetShotLook(preset) {
-  return { ...preset.shotLook };
+  return { ...preset.shotLook, ...preset.shotLook.angle !== void 0 ? { cameraPos: null } : {} };
 }
 function expandLookChoice(designPreset, layout) {
   const preset = designPreset === void 0 ? void 0 : designPresetById(designPreset);
@@ -7117,8 +7125,8 @@ var init_agentCapabilities = __esm({
         studioCommands: ["addPanel"],
         wire: "structuralOperations: frame.add",
         targets: ["project"],
-        requiredInputs: ["afterFrameId (optional)"],
-        limits: ["A frame created this cycle can only be addressed in the next one, after Studio reports its id."],
+        requiredInputs: ["afterFrameId (optional)", "frameRef (optional, patch-local alias)"],
+        limits: ["Declare frameRef to address the new frame in later ordered operations of the same patch. Without frameRef, wait until the next cycle reports its id."],
         evaluationCases: ["structure-add-closing-frame"]
       },
       {
@@ -7566,8 +7574,8 @@ function validateAgentOutcome(outcome) {
   if (outcome.status === "applied_with_remaining" && !outcome.remaining) {
     problems.push("applied_with_remaining must name what is still outstanding.");
   }
-  if (outcome.question !== void 0 && outcome.status !== "needs_clarification") {
-    problems.push(`Only needs_clarification carries a question, not ${outcome.status}.`);
+  if (outcome.question !== void 0 && outcome.status !== "needs_clarification" && outcome.status !== "needs_asset") {
+    problems.push(`Only needs_clarification and needs_asset carry a question, not ${outcome.status}.`);
   }
   if (outcome.status === "needs_clarification" && !outcome.question) {
     problems.push("needs_clarification must ask exactly one focused question.");
@@ -7575,6 +7583,16 @@ function validateAgentOutcome(outcome) {
   if (outcome.capabilityId !== void 0 && !capabilityById(outcome.capabilityId)) {
     problems.push(`Outcome names capability ${JSON.stringify(outcome.capabilityId)}, which the catalog does not list.`);
   }
+  if (outcome.capabilityIds !== void 0) {
+    if (!Array.isArray(outcome.capabilityIds) || outcome.capabilityIds.length > MAX_OUTCOME_CAPABILITY_IDS) {
+      problems.push(`capabilityIds must be a list of at most ${MAX_OUTCOME_CAPABILITY_IDS} catalog ids.`);
+    } else {
+      for (const id of outcome.capabilityIds) {
+        if (typeof id !== "string" || !capabilityById(id)) problems.push(`Outcome lists capability ${JSON.stringify(id)}, which the catalog does not list.`);
+      }
+      if (new Set(outcome.capabilityIds).size !== outcome.capabilityIds.length) problems.push("capabilityIds repeats an id.");
+    }
+  }
   problems.push(...boundProblems("headline", outcome.headline, AGENT_OUTCOME_BOUNDS.headline, true));
   problems.push(...boundProblems("detail", outcome.detail, AGENT_OUTCOME_BOUNDS.detail, false));
   problems.push(...boundProblems("remaining", outcome.remaining, AGENT_OUTCOME_BOUNDS.remaining, false));
@@ -7591,6 +7609,77 @@ function boundProblems(field, value, maximum, required) {
   if (value.length > maximum) return [`${field} is ${value.length} characters, over its ${maximum} bound.`];
   return [];
 }
+function capabilitiesForPatch(patch) {
+  const ids = [];
+  if (!patch) return ids;
+  const add = (id) => {
+    if (ids.indexOf(id) < 0) ids.push(id);
+  };
+  if (patch.captions) add("caption.text");
+  if (patch.screenOrder) add("frame.reorder");
+  if (patch.designPreset) add("look.design-preset");
+  if (patch.layout) add("look.layout-template");
+  if (patch.outputs) add("output.membership");
+  if (patch.locales) add("locale.membership");
+  if (patch.shots?.some((shot) => Object.keys(shot).length > 0)) add("device.look");
+  if (patch.devices?.some((device) => Object.keys(device.patch).length > 0)) add("device.look");
+  if (patch.captionStyle && Object.keys(patch.captionStyle).length > 0) add("caption.style");
+  if (patch.background && Object.keys(patch.background).length > 0) add("strip.background");
+  patch.frames?.forEach((frame) => {
+    if (frame.captionStyle && Object.keys(frame.captionStyle).length > 0) add("caption.style");
+    if (frame.background && Object.keys(frame.background).length > 0) add("frame.background");
+  });
+  patch.captionOperations?.forEach((operation) => {
+    if (operation.operation === "add") add("caption.add");
+    else if (operation.operation === "remove") add("caption.remove");
+    else add(operation.frameId === operation.toFrameId ? "caption.reorder" : "caption.move-to-frame");
+  });
+  patch.frameOperations?.forEach((operation) => {
+    if (operation.operation === "add") add("frame.add");
+    else if (operation.operation === "remove") add("frame.remove");
+    else if (operation.operation === "move") add("frame.reorder");
+    else add("frame.split");
+  });
+  patch.structuralOperations?.forEach((operation) => add(capabilityForStructuralOperation(operation)));
+  return ids;
+}
+function capabilityForStructuralOperation(operation) {
+  switch (operation.op) {
+    case "frame.add":
+      return "frame.add";
+    case "frame.remove":
+      return "frame.remove";
+    case "frame.move":
+      return "frame.reorder";
+    case "frame.split":
+      return "frame.split";
+    case "frame.combine":
+      return "frame.combine";
+    case "frame.template-reset":
+      return "look.layout-template";
+    case "caption.add":
+      return "caption.add";
+    case "caption.remove":
+      return "caption.remove";
+    // One `caption.move` covers both Studio controls: staying inside a frame is a reorder, crossing
+    // to another is a move. The catalog names them separately because the user experiences them
+    // separately.
+    case "caption.move":
+      return operation.frameId === operation.toFrameId ? "caption.reorder" : "caption.move-to-frame";
+    case "device.move":
+      return "device.move-to-frame";
+    case "device.reorder":
+      return "device.reorder";
+    case "device.remove":
+      return "device.remove";
+    case "device.add":
+      return "device.add";
+    // The catalog names this one for what the user experiences — the pixels change, the device does
+    // not — so the id deliberately does not match the wire's `device.replace`.
+    case "device.replace":
+      return "device.replace-pixels";
+  }
+}
 function applicationOutcome(facts) {
   if (facts.conflicted) {
     return {
@@ -7654,7 +7743,14 @@ function cancelledOutcome() {
     changed: []
   };
 }
-var AGENT_OUTCOME_STATUSES, AGENT_MUTATING_STATUSES, AGENT_OUTCOME_REASONS, AGENT_OUTCOME_BOUNDS;
+function withTouchedCapabilities(outcome, touched) {
+  const ids = [];
+  for (const id of touched) if (capabilityById(id) && ids.indexOf(id) < 0) ids.push(id);
+  if (outcome.capabilityId && capabilityById(outcome.capabilityId) && ids.indexOf(outcome.capabilityId) < 0) ids.push(outcome.capabilityId);
+  if (ids.length === 0) return outcome;
+  return { ...outcome, capabilityIds: ids.slice(0, MAX_OUTCOME_CAPABILITY_IDS) };
+}
+var AGENT_OUTCOME_STATUSES, AGENT_MUTATING_STATUSES, AGENT_OUTCOME_REASONS, AGENT_OUTCOME_BOUNDS, MAX_OUTCOME_CAPABILITY_IDS;
 var init_agentOutcome = __esm({
   "../mockup-engine/appstore/agentOutcome.ts"() {
     "use strict";
@@ -7693,9 +7789,39 @@ var init_agentOutcome = __esm({
       remaining: 300,
       /** The label on the single next step. */
       nextStep: 120,
-      /** The focused question on `needs_clarification`. */
-      question: 240
+      /** Transport ceiling for a complete assistant question or screenshot request; never clip it. */
+      question: 32e3
     };
+    MAX_OUTCOME_CAPABILITY_IDS = 16;
+  }
+});
+
+// ../mockup-engine/appstore/agentUnmetActions.ts
+function normalizeIds(ids) {
+  return Array.from(new Set(ids)).sort().slice(0, MAX_UNMET_ACTIONS_PER_TURN);
+}
+function classifiedDemand(ids) {
+  return { classification: "classified", actionIds: normalizeIds(ids) };
+}
+var AGENT_UNMET_ACTION_UNKNOWN, MAX_UNMET_ACTIONS_PER_TURN, AGENT_UNMET_ACTIONS, CAPABILITY_IDS, AGENT_UNMET_ACTION_VOCABULARY, NOT_MEASURED_DEMAND;
+var init_agentUnmetActions = __esm({
+  "../mockup-engine/appstore/agentUnmetActions.ts"() {
+    "use strict";
+    init_agentCapabilities();
+    AGENT_UNMET_ACTION_UNKNOWN = "unknown";
+    MAX_UNMET_ACTIONS_PER_TURN = 8;
+    AGENT_UNMET_ACTIONS = [
+      { id: "image.generate", summary: "Generate or paint new imagery rather than arranging supplied screenshots." },
+      { id: "animation.create", summary: "Animate a screen, produce a video, or export motion instead of stills." },
+      { id: "device.unsupported-model", summary: "Use a device model ShotOps does not offer." }
+    ];
+    CAPABILITY_IDS = AGENT_CAPABILITIES.map((capability) => capability.id);
+    AGENT_UNMET_ACTION_VOCABULARY = [
+      ...CAPABILITY_IDS,
+      ...AGENT_UNMET_ACTIONS.map((action) => action.id),
+      AGENT_UNMET_ACTION_UNKNOWN
+    ];
+    NOT_MEASURED_DEMAND = { classification: "not_measured", actionIds: [] };
   }
 });
 
@@ -8164,7 +8290,7 @@ function applyFrameOperation(state, operation) {
   if (operation.operation === "add") {
     if (operation.afterFrameId !== void 0 && panelIndex(state, operation.afterFrameId) < 0) return null;
     const frameId = nextAgentPanelId(state);
-    const added = addPanel(state, frameId);
+    const added = inheritFrameTemplate(addPanel(state, frameId), frameId, operation.afterFrameId ?? state.panels[state.panels.length - 1]?.id);
     return operation.afterFrameId === void 0 ? added : movePanelAfter(added, frameId, operation.afterFrameId);
   }
   if (operation.operation === "remove") {
@@ -8187,7 +8313,17 @@ function applyFrameOperation(state, operation) {
     if (!moved) return null;
     next = moved;
   }
-  return next;
+  return inheritFrameTemplate(next, newFrameId, operation.frameId);
+}
+function inheritFrameTemplate(state, panelId, fromPanelId) {
+  const source = fromPanelId === void 0 ? void 0 : state.frameTemplates?.[fromPanelId];
+  if (!source) return state;
+  const baseline = captureFrameTemplateBaseline(
+    { shots: state.shots, captionText: state.captionText, captionSlotIds: captionSlotIds(state), baseLocale: state.baseLocale },
+    panelId,
+    source.templateId
+  );
+  return { ...state, frameTemplates: { ...state.frameTemplates ?? {}, [panelId]: baseline } };
 }
 function addCaptionLayer(state, panelId, text3, style2) {
   const source = state.captionText[state.baseLocale] ?? {};
@@ -8496,16 +8632,39 @@ function applyStructuralOperation(state, operation, assets = [], bindings) {
 function applyStructuralOperations(state, patch, assets = []) {
   let next = state;
   const assetBindings = [];
-  for (const operation of normalizeStructuralOperations(patch)) {
+  const frameRefs = /* @__PURE__ */ new Map();
+  const retiredRefs = /* @__PURE__ */ new Set();
+  for (const raw of normalizeStructuralOperations(patch)) {
+    const ref = raw.op === "frame.add" ? raw.frameRef : void 0;
+    if (ref !== void 0 && (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(ref) || frameRefs.has(ref) || state.panels.some((panel) => panel.id === ref) || state.shots.some((shot) => shot.id === ref))) return null;
+    if (structuralOperationTargets(raw).frameIds.some((id) => retiredRefs.has(id))) return null;
+    const resolve14 = (id) => frameRefs.get(id) ?? id;
+    const operation = {
+      ...raw,
+      ..."frameId" in raw ? { frameId: resolve14(raw.frameId) } : {},
+      ..."toFrameId" in raw ? { toFrameId: resolve14(raw.toFrameId) } : {},
+      ..."fromFrameId" in raw ? { fromFrameId: resolve14(raw.fromFrameId) } : {},
+      ..."afterFrameId" in raw && raw.afterFrameId !== void 0 ? { afterFrameId: resolve14(raw.afterFrameId) } : {}
+    };
     const applied = applyStructuralOperation(next, operation, assets, assetBindings);
     if (!applied) return null;
+    if (ref !== void 0) {
+      const created = applied.panels.find((panel) => !next.panels.some((previous) => previous.id === panel.id));
+      if (!created) return null;
+      frameRefs.set(ref, created.id);
+    }
+    frameRefs.forEach((id, alias) => {
+      if (!applied.panels.some((panel) => panel.id === id)) retiredRefs.add(alias);
+    });
     next = applied;
   }
-  return { state: next, assetBindings };
+  const survivingRefs = Array.from(frameRefs.entries()).filter(([alias]) => !retiredRefs.has(alias));
+  return { state: next, assetBindings, ...survivingRefs.length > 0 ? { frameRefs: Object.fromEntries(survivingRefs) } : {} };
 }
 var init_refinementStructure = __esm({
   "../mockup-engine/appstore/refinementStructure.ts"() {
     "use strict";
+    init_refineIntent();
     init_defaults();
     init_recordTransforms();
     init_shot();
@@ -8877,7 +9036,7 @@ function applyProjectRefinementWithAssets(state, patch, panelIds, assets = []) {
       next = { ...next, panels, shots: shotsInPanelOrder(next.shots, panels) };
     }
   }
-  return { state: next, assetBindings: structured.assetBindings };
+  return { state: next, assetBindings: structured.assetBindings, ...structured.frameRefs ? { frameRefs: structured.frameRefs } : {} };
 }
 var init_refinement = __esm({
   "../mockup-engine/appstore/refinement.ts"() {
@@ -8964,6 +9123,67 @@ var init_appStoreLocales = __esm({
   }
 });
 
+// ../mockup-engine/appstore/agentTurnRepetition.ts
+function creationOf(operation) {
+  if (!CREATING_OPS.has(operation.op)) return null;
+  const target = "frameId" in operation ? operation.frameId : "toFrameId" in operation ? operation.toFrameId : "afterFrameId" in operation && operation.afterFrameId ? `after:${operation.afterFrameId}` : "strip";
+  return { op: operation.op, target };
+}
+function contextualCreations(operations, resolved = {}) {
+  const refs = /* @__PURE__ */ new Map();
+  return operations.map((operation) => {
+    const creation = creationOf(operation);
+    const target = creation?.target;
+    const normalized = creation && target !== void 0 ? {
+      ...creation,
+      target: target.startsWith("after:") ? `after:${refs.get(target.slice(6)) ?? target.slice(6)}` : refs.get(target) ?? target
+    } : null;
+    if (operation.op === "frame.add" && operation.frameRef && normalized) {
+      refs.set(operation.frameRef, Object.prototype.hasOwnProperty.call(resolved, operation.frameRef) ? resolved[operation.frameRef] : `created-frame:${normalized.target}`);
+    }
+    return normalized;
+  });
+}
+function creationsIn(patch, frameRefs) {
+  const operations = patch.structuralOperations ?? [];
+  const symbolic = contextualCreations(operations).flatMap((creation) => creation ? [creation] : []);
+  const durable = frameRefs ? contextualCreations(operations, frameRefs).flatMap((creation) => creation ? [creation] : []) : [];
+  return symbolic.concat(durable.filter((creation) => !symbolic.some((entry) => entry.op === creation.op && entry.target === creation.target)));
+}
+function dropRepeatedCreations(patch, already) {
+  const operations = patch.structuralOperations;
+  if (!operations || operations.length === 0 || already.length === 0) return { patch, dropped: [] };
+  const seen = new Set(already.map((creation) => `${creation.op} ${creation.target}`));
+  const dropped = [];
+  const creations = contextualCreations(operations);
+  const unavailableRefs = /* @__PURE__ */ new Set();
+  const kept = operations.filter((operation, index) => {
+    const creation = creations[index];
+    const dependent = structuralOperationTargets(operation).frameIds.some((id) => unavailableRefs.has(id));
+    if (!dependent && (!creation || !seen.has(`${creation.op} ${creation.target}`))) return true;
+    if (operation.op === "frame.add" && operation.frameRef) unavailableRefs.add(operation.frameRef);
+    if (creation) dropped.push(creation);
+    return false;
+  });
+  if (dropped.length === 0) return { patch, dropped };
+  const { structuralOperations: _dropped, ...rest } = patch;
+  void _dropped;
+  return { patch: kept.length > 0 ? { ...rest, structuralOperations: kept } : rest, dropped };
+}
+var CREATING_OPS;
+var init_agentTurnRepetition = __esm({
+  "../mockup-engine/appstore/agentTurnRepetition.ts"() {
+    "use strict";
+    init_refineIntent();
+    CREATING_OPS = /* @__PURE__ */ new Set([
+      "frame.add",
+      "frame.split",
+      "caption.add",
+      "device.add"
+    ]);
+  }
+});
+
 // ../mockup-engine/appstore/agentTurnCoordinator.ts
 function phaseFor(cycle) {
   return cycle === 1 ? "applying" : cycle === 2 ? "inspecting" : "adjusting";
@@ -9008,6 +9228,7 @@ async function runAgentTurn(input, ports) {
   if (!turnId) throw new Error("Agent turn id must not be empty");
   const emit = (event) => ports.emit({ ...event, turnId });
   const now = input.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const layoutRepairable = canRepairLayoutForFocus(input.focus, instruction);
   const loaded = await ports.loadProject();
   const before = loaded.state;
   let working = before;
@@ -9018,9 +9239,13 @@ async function runAgentTurn(input, ports) {
   let best = null;
   let selected = null;
   let workingAssetBindings = [];
+  const unmetActions = /* @__PURE__ */ new Set();
+  let demandClassified = false;
   let interpretation = "";
   let inspection = "";
   let remainingMismatch = null;
+  const appliedCreations = [];
+  const touchedCapabilities = /* @__PURE__ */ new Set();
   let terminalOutcome = null;
   let invalid2 = false;
   let cancelled = false;
@@ -9049,7 +9274,14 @@ async function runAgentTurn(input, ports) {
         focus: input.focus,
         state: working,
         rendered,
-        ...cycle > 1 ? { previous: { actualDiff: selected?.changed ?? [], inspection, cycle: cycle - 1 } } : {}
+        ...cycle > 1 ? {
+          previous: {
+            actualDiff: selected?.changed ?? [],
+            inspection,
+            cycle: cycle - 1,
+            appliedOperations: [...appliedCreations]
+          }
+        } : {}
       });
     } catch {
       terminalOutcome = failureOutcome(
@@ -9058,6 +9290,10 @@ async function runAgentTurn(input, ports) {
       );
       break;
     }
+    if (authorization.demand?.classification === "classified") {
+      demandClassified = true;
+      for (const actionId of authorization.demand.actionIds) unmetActions.add(actionId);
+    }
     interpretation ||= authorization.interpretation?.trim() || instruction;
     inspection = authorization.inspection?.trim() || "Inspected the current composed result.";
     const pass = {
@@ -9085,7 +9321,12 @@ async function runAgentTurn(input, ports) {
     }
     remainingMismatch = authorization.remainingMismatch?.trim() || authorization.followUp?.trim() || null;
     for (const change of authorization.broaderChanges ?? []) broaderChanges.add(change);
+    if (authorization.patch && cycle > 1) {
+      const guarded = dropRepeatedCreations(authorization.patch, appliedCreations);
+      if (guarded.dropped.length > 0) authorization = { ...authorization, patch: guarded.patch };
+    }
     if (authorization.patch) {
+      for (const id of capabilitiesForPatch(authorization.patch)) touchedCapabilities.add(id);
       const application = applyProjectRefinementWithAssets(
         working,
         authorization.patch,
@@ -9097,6 +9338,7 @@ async function runAgentTurn(input, ports) {
         break;
       }
       working = application.state;
+      appliedCreations.push(...creationsIn(authorization.patch, application.frameRefs));
       workingAssetBindings = [...workingAssetBindings, ...application.assetBindings];
       checkpointId += 1;
       const checkpoint = {
@@ -9123,12 +9365,14 @@ async function runAgentTurn(input, ports) {
       });
     }
     const requiresRenderedInspection = cycle === 1 && authorization.patch != null;
-    if (authorization.complete === true && !requiresRenderedInspection) {
+    const unresolvedLayout = layoutRepairable && authorization.complete === true && !requiresRenderedInspection && authorization.patch == null ? ports.unresolvedLayout?.(rendered)?.trim() || null : null;
+    if (authorization.complete === true && !requiresRenderedInspection && !(unresolvedLayout && cycle < AGENT_TURN_PASS_CAP)) {
       if (selected?.changed.length) best = selected;
-      remainingMismatch = null;
+      remainingMismatch = unresolvedLayout;
       break;
     }
-    if (authorization.followUp && !authorization.patch) break;
+    if (unresolvedLayout) remainingMismatch = unresolvedLayout;
+    else if (authorization.followUp && !authorization.patch) break;
     if (cycle < AGENT_TURN_PASS_CAP) {
       try {
         rendered = await ports.renderComposed(working, cycle);
@@ -9145,11 +9389,14 @@ async function runAgentTurn(input, ports) {
   selected = best;
   const selectedState = selected?.state ?? before;
   await emit({ type: "draft_selected", checkpointId: selected?.id ?? 0, state: selectedState });
-  let outcome = terminalOutcome ?? applicationOutcome({
-    changed: selected?.changed ?? [],
-    invalid: invalid2,
-    gaps: selected?.gaps ?? []
-  });
+  let outcome = withTouchedCapabilities(
+    terminalOutcome ?? applicationOutcome({
+      changed: selected?.changed ?? [],
+      invalid: invalid2,
+      gaps: selected?.gaps ?? []
+    }),
+    Array.from(touchedCapabilities)
+  );
   let committed = false;
   let commitData;
   if (outcome.status === "applied" || outcome.status === "applied_with_remaining") {
@@ -9166,7 +9413,10 @@ async function runAgentTurn(input, ports) {
       commitData = commit.data;
       await emit({ type: "commit_succeeded", data: commit.data, outcome });
     } else {
-      outcome = commit.reason === "stale_version" ? applicationOutcome({ changed: [], conflicted: true }) : failureOutcome("service_unavailable", "The Agent could not save this change. Nothing changed.");
+      outcome = withTouchedCapabilities(
+        commit.reason === "stale_version" ? applicationOutcome({ changed: [], conflicted: true }) : failureOutcome("service_unavailable", "The Agent could not save this change. Nothing changed."),
+        Array.from(touchedCapabilities)
+      );
       await emit({ type: "draft_rolled_back", outcome });
     }
   } else {
@@ -9200,7 +9450,8 @@ async function runAgentTurn(input, ports) {
     state: committed ? selectedState : before,
     expectedVersion: loaded.expectedVersion,
     committed,
-    ...commitData === void 0 ? {} : { commitData }
+    ...commitData === void 0 ? {} : { commitData },
+    demand: demandClassified ? classifiedDemand(unmetActions) : NOT_MEASURED_DEMAND
   };
   assertOutcome(outcome);
   await emit({ type: "turn_completed", result });
@@ -9212,10 +9463,13 @@ var init_agentTurnCoordinator = __esm({
   "../mockup-engine/appstore/agentTurnCoordinator.ts"() {
     "use strict";
     init_agentOutcome();
+    init_refineIntent();
     init_refinement();
+    init_agentUnmetActions();
     init_recordTransforms();
     init_appStoreLocales();
     init_agentAssetCustody();
+    init_agentTurnRepetition();
     AGENT_TURN_PASS_CAP = 3;
     EMPTY_USAGE = {
       inputTokens: 0,
@@ -9263,7 +9517,9 @@ var init_agentTurnConformance = __esm({
             panelId: "p1",
             frameNodeId: "frame-1",
             frameName: "home.png",
-            bytes: new Uint8Array(),
+            // Real pixels, because a surface derives its vision list from THIS state: a shot with no
+            // bytes is a blank frame, which every door drops from the turn (#829).
+            bytes: new Uint8Array([1, 2, 3]),
             look: { ...DEFAULT_LOOK },
             thumb: null,
             thumbStale: false
@@ -9331,6 +9587,8 @@ var init_agentTurnConformance = __esm({
         outcome: {
           status: "applied",
           headline: "Restyled 1 device",
+          // #840 — every capability the drafts touched, derived from the patch, travels on the outcome.
+          capabilityIds: ["device.look"],
           changed: ["Restyled 1 device"]
         },
         stateDiff: {
@@ -9399,6 +9657,7 @@ var init_agentTurnConformance = __esm({
         outcome: {
           status: "applied",
           headline: "Replaced the screenshot on 1 device",
+          capabilityIds: ["device.replace-pixels"],
           changed: ["Replaced the screenshot on 1 device"]
         },
         stateDiff: {
@@ -9461,6 +9720,7 @@ var init_appstore = __esm({
     init_agentAssetCustody();
     init_agentCapabilities();
     init_agentOutcome();
+    init_agentUnmetActions();
     init_agentTurnCoordinator();
     init_agentTurnConformance();
     init_refinement();
@@ -11136,6 +11396,33 @@ var init_production = __esm({
   }
 });
 
+// ../product/accountRights.ts
+var ACCOUNT_TRAFFIC_CLASSES, RECORDED_TRAFFIC_CLASSES;
+var init_accountRights = __esm({
+  "../product/accountRights.ts"() {
+    "use strict";
+    ACCOUNT_TRAFFIC_CLASSES = ["customer", "owner", "benchmark"];
+    RECORDED_TRAFFIC_CLASSES = [...ACCOUNT_TRAFFIC_CLASSES, "unclassified"];
+  }
+});
+
+// ../api/_lib/authorization/accountAccess.ts
+var init_accountAccess = __esm({
+  "../api/_lib/authorization/accountAccess.ts"() {
+    "use strict";
+    init_accountRights();
+    init_supabaseRest();
+  }
+});
+
+// ../api/_lib/authorization/operatorAudit.ts
+var init_operatorAudit = __esm({
+  "../api/_lib/authorization/operatorAudit.ts"() {
+    "use strict";
+    init_supabaseRest();
+  }
+});
+
 // ../api/_lib/log.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 function currentRequestId() {
@@ -11168,6 +11455,7 @@ var JWKS_TTL_MS;
 var init_supabaseAuth = __esm({
   "../api/_lib/supabaseAuth.ts"() {
     "use strict";
+    init_accountAccess();
     JWKS_TTL_MS = 10 * 60 * 1e3;
   }
 });
@@ -11214,6 +11502,8 @@ var init_polarWebhook = __esm({
 var init_billingReconcile = __esm({
   "../api/_lib/billingReconcile.ts"() {
     "use strict";
+    init_accountAccess();
+    init_operatorAudit();
     init_log();
     init_supabaseAuth();
     init_entitlement();
@@ -11224,10 +11514,62 @@ var init_billingReconcile = __esm({
   }
 });
 
+// ../api/_lib/providerUsage.ts
+var init_providerUsage = __esm({
+  "../api/_lib/providerUsage.ts"() {
+    "use strict";
+  }
+});
+
+// ../api/_lib/providerCost.ts
+var init_providerCost = __esm({
+  "../api/_lib/providerCost.ts"() {
+    "use strict";
+  }
+});
+
+// ../api/_lib/providerSpendStore.ts
+import { z as z8 } from "zod";
+var nullableCount, decimalMoney, evidenceSchema;
+var init_providerSpendStore = __esm({
+  "../api/_lib/providerSpendStore.ts"() {
+    "use strict";
+    init_providerCost();
+    init_providerUsage();
+    init_supabaseRest();
+    nullableCount = z8.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).nullable();
+    decimalMoney = z8.string().regex(/^\d{1,19}$/).refine((n) => BigInt(n) <= 9223372036854775807n);
+    evidenceSchema = z8.object({
+      state: z8.enum(["estimated", "partial", "unknown", "not_incurred"]),
+      amountNanoUsd: decimalMoney.nullable(),
+      missing: z8.array(z8.enum(["rate", "usage", "input", "input_breakdown", "inconsistent_input", "cache_read", "cache_write", "cache_write_ttl", "output", "multiple_provider_attempts", "provider_attempts_unknown", "amount_overflow"])),
+      usage: z8.object({ inputTokens: nullableCount, cacheReadTokens: nullableCount, cacheWriteTokens: nullableCount, outputTokens: nullableCount, cacheWriteTtl: z8.enum(["5m", "1h"]).nullable() }).strict().nullable(),
+      rate: z8.object({
+        version: z8.string().regex(/^[a-zA-Z0-9._-]{1,100}$/),
+        effectiveAt: z8.string().datetime(),
+        currency: z8.literal("USD"),
+        model: z8.literal("anthropic/claude-sonnet-4.6"),
+        basis: z8.literal("gateway-list-standard"),
+        region: z8.enum(["global", "us", "eu"]),
+        nanoUsdPerMillion: z8.object({ input: decimalMoney, output: decimalMoney, cacheRead: decimalMoney, cacheWrite5m: decimalMoney, cacheWrite1h: decimalMoney }).strict(),
+        sources: z8.array(z8.enum(["https://platform.claude.com/docs/en/about-claude/pricing", "https://ai-gateway.vercel.sh/v1/models"]))
+      }).strict().nullable(),
+      gateway: z8.object({ generationId: z8.string().regex(/^gen_[a-zA-Z0-9_-]{1,100}$/).nullable(), costUsd: z8.string().regex(/^\d{1,12}(\.\d{1,18})?$/).nullable(), marketCostUsd: z8.string().regex(/^\d{1,12}(\.\d{1,18})?$/).nullable(), attempts: nullableCount, route: z8.string().regex(/^[a-zA-Z0-9_-]{1,40}$/).nullable() }).strict().nullable(),
+      noAttempt: z8.literal(true).optional()
+    }).strict().superRefine((e, context) => {
+      if ((e.state === "estimated" || e.state === "partial") && e.amountNanoUsd === null || e.state === "unknown" && e.amountNanoUsd !== null || e.state === "not_incurred" && (e.amountNanoUsd !== "0" || e.noAttempt !== true)) {
+        context.addIssue({ code: "custom", message: "inconsistent spend state" });
+      }
+    });
+  }
+});
+
 // ../api/_lib/aiGenerationStore.ts
 var init_aiGenerationStore = __esm({
   "../api/_lib/aiGenerationStore.ts"() {
     "use strict";
+    init_providerUsage();
+    init_providerSpendStore();
     init_supabaseRest();
   }
 });
@@ -11716,7 +12058,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "shotops-mcp",
-      version: "0.9.5",
+      version: "0.9.6",
       private: false,
       type: "module",
       description: "The bundle-emitting MCP server over the @engine/@sync spine. Exposes ShotOps tools to ChatGPT, Claude Code, Cursor, and CI over Streamable HTTP with OAuth or personal API tokens. Hosted and MCP tool paths never accept, store, or forward a store-signing credential; the explicit local release CLI validates the user's existing key directly with Apple and records only its path. Renders via headless Playwright Chromium, the engine's native non-browser habitat (same path as mockup-mcp). Also ships as a free LOCAL stdio server (`npx shotops-mcp`) \u2014 same render, on your own machine, no account needed.",
@@ -13926,14 +14268,21 @@ function connectHostedBridge(token2) {
     async refineProject(input) {
       return callOp(token2, "refine_project", input);
     },
-    async refinePass(projectId, pass, turnKey) {
-      const body = JSON.stringify({ op: "refine_pass", project: projectId, turnKey, pass });
+    async refinePass(projectId, pass, turnKey, benchmark, attachments) {
+      const args = {
+        project: projectId,
+        turnKey,
+        pass,
+        ...benchmark === void 0 ? {} : { benchmark },
+        ...attachments === void 0 ? {} : { attachments }
+      };
+      const body = JSON.stringify({ op: "refine_pass", ...args });
       if (body.length > MAX_PASS_BODY_BYTES) {
         throw new Error(
           "This project has too many screenshots for one Agent pass. Refine a smaller selection, or run the Agent from ShotOps in the browser."
         );
       }
-      return callOp(token2, "refine_pass", { project: projectId, turnKey, pass });
+      return callOp(token2, "refine_pass", args);
     },
     async settleRefineTurn(projectId, settlement) {
       const res = await callOp(token2, "refine_finalize", {
@@ -14004,6 +14353,23 @@ var init_hostedBridge = __esm({
   }
 });
 
+// ../mockup-engine/layoutFindings.ts
+function describeUnresolvedLayout(findings) {
+  if (!findings || findings.length === 0) return null;
+  const frames = Array.from(new Set(findings.flatMap((finding) => finding.frames))).sort((left, right) => left - right).map((index) => `Frame ${index + 1}`);
+  const where = frames.length === 0 ? "" : frames.length === 1 ? ` in ${frames[0]}` : ` in ${frames.slice(0, -1).join(", ")} and ${frames[frames.length - 1]}`;
+  if (findings.length === 1) {
+    const what = findings[0].kind === "caption-device" ? "A caption still overlaps a device" : findings[0].kind === "caption-caption" ? "Two captions still overlap" : "Two devices still collide";
+    return `${what}${where}.`;
+  }
+  return `${findings.length} layout overlaps still remain${where}.`;
+}
+var init_layoutFindings = __esm({
+  "../mockup-engine/layoutFindings.ts"() {
+    "use strict";
+  }
+});
+
 // ../api/_lib/invalidRequest.ts
 function safeFailureDiagnostic(error) {
   const errorTypes = [];
@@ -14038,57 +14404,57 @@ var init_invalidRequest = __esm({
 });
 
 // ../api/_lib/aiShotProjection.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var deviceHexSchema, API_AI_SHOT_PROJECTION, API_AI_SHOT_INCLUDED_ENTRIES, API_AI_SHOT_PATCH_SHAPE, apiAiShotPatchSchema, API_AI_SHOT_PROMPT_INVENTORY;
 var init_aiShotProjection = __esm({
   "../api/_lib/aiShotProjection.ts"() {
     "use strict";
     init_refineIntent();
-    deviceHexSchema = z8.string().trim().regex(/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/);
+    deviceHexSchema = z9.string().trim().regex(/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/);
     API_AI_SHOT_PROJECTION = {
       orbit: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.orbit.min).max(AI_SHOT_RANGES.orbit.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.orbit.min).max(AI_SHOT_RANGES.orbit.max).optional(),
         prompt: `orbit: camera azimuth in degrees, ${AI_SHOT_RANGES.orbit.min} to ${AI_SHOT_RANGES.orbit.max}. 0 is straight on, negative swings the device left, positive right. Subtle is \xB15\u201320.`
       },
       roll: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.roll.min).max(AI_SHOT_RANGES.roll.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.roll.min).max(AI_SHOT_RANGES.roll.max).optional(),
         prompt: `roll: clock-hand tilt, ${AI_SHOT_RANGES.roll.min} to ${AI_SHOT_RANGES.roll.max} degrees. 0 is upright. Subtle is \xB12\u20138.`
       },
       angle: {
         exposure: "included",
-        schema: z8.enum(["front", "left", "right"]).optional(),
+        schema: z9.enum(["front", "left", "right"]).optional(),
         prompt: "angle: front | left | right \u2014 a camera PRESET. Setting it discards any orbit value on that frame, so send orbit OR angle, never both."
       },
       phoneHeight: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.phoneHeight.min).max(AI_SHOT_RANGES.phoneHeight.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.phoneHeight.min).max(AI_SHOT_RANGES.phoneHeight.max).optional(),
         prompt: `phoneHeight: ${AI_SHOT_RANGES.phoneHeight.min}\u2013${AI_SHOT_RANGES.phoneHeight.max} (% of panel height; over 100 bleeds off an edge)`
       },
       hOffset: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.hOffset.min).max(AI_SHOT_RANGES.hOffset.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.hOffset.min).max(AI_SHOT_RANGES.hOffset.max).optional(),
         prompt: `hOffset: ${AI_SHOT_RANGES.hOffset.min}\u2013${AI_SHOT_RANGES.hOffset.max} horizontal position, 0 is centred`
       },
       vOffset: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.vOffset.min).max(AI_SHOT_RANGES.vOffset.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.vOffset.min).max(AI_SHOT_RANGES.vOffset.max).optional(),
         prompt: `vOffset: ${AI_SHOT_RANGES.vOffset.min}\u2013${AI_SHOT_RANGES.vOffset.max} vertical position, 0 is centred`
       },
       material: {
         exposure: "included",
-        schema: z8.enum(["real", "clay"]).optional(),
+        schema: z9.enum(["real", "clay"]).optional(),
         prompt: `material: real | clay. colorway (real only): ${AI_COLORWAY_IDS.join(" | ")}. clayTone (clay only): ${AI_CLAY_TONES.join(" | ")}.`
       },
       colorway: {
         exposure: "included",
-        schema: z8.enum(AI_COLORWAY_IDS).optional(),
+        schema: z9.enum(AI_COLORWAY_IDS).optional(),
         prompt: `material: real | clay. colorway (real only): ${AI_COLORWAY_IDS.join(" | ")}. clayTone (clay only): ${AI_CLAY_TONES.join(" | ")}.`
       },
       clayTone: {
         exposure: "included",
-        schema: z8.enum(AI_CLAY_TONES).optional(),
+        schema: z9.enum(AI_CLAY_TONES).optional(),
         prompt: `material: real | clay. colorway (real only): ${AI_COLORWAY_IDS.join(" | ")}. clayTone (clay only): ${AI_CLAY_TONES.join(" | ")}.`
       },
       customColor: {
@@ -14103,37 +14469,37 @@ var init_aiShotProjection = __esm({
       },
       finish: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.finish.min).max(AI_SHOT_RANGES.finish.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.finish.min).max(AI_SHOT_RANGES.finish.max).optional(),
         prompt: `finish: ${AI_SHOT_RANGES.finish.min}\u2013${AI_SHOT_RANGES.finish.max} (0 matte, 1 glossy). clearcoat: ${AI_SHOT_RANGES.clearcoat.min}\u2013${AI_SHOT_RANGES.clearcoat.max} lacquer sheen on top.`
       },
       clearcoat: {
         exposure: "included",
-        schema: z8.number().min(AI_SHOT_RANGES.clearcoat.min).max(AI_SHOT_RANGES.clearcoat.max).optional(),
+        schema: z9.number().min(AI_SHOT_RANGES.clearcoat.min).max(AI_SHOT_RANGES.clearcoat.max).optional(),
         prompt: `finish: ${AI_SHOT_RANGES.finish.min}\u2013${AI_SHOT_RANGES.finish.max} (0 matte, 1 glossy). clearcoat: ${AI_SHOT_RANGES.clearcoat.min}\u2013${AI_SHOT_RANGES.clearcoat.max} lacquer sheen on top.`
       },
       flatScreen: {
         exposure: "included",
-        schema: z8.boolean().optional(),
+        schema: z9.boolean().optional(),
         prompt: "flatScreen, glare, lighting, reflections, clipToFrame: true | false."
       },
       glare: {
         exposure: "included",
-        schema: z8.boolean().optional(),
+        schema: z9.boolean().optional(),
         prompt: "flatScreen, glare, lighting, reflections, clipToFrame: true | false."
       },
       lighting: {
         exposure: "included",
-        schema: z8.boolean().optional(),
+        schema: z9.boolean().optional(),
         prompt: "flatScreen, glare, lighting, reflections, clipToFrame: true | false."
       },
       reflections: {
         exposure: "included",
-        schema: z8.boolean().optional(),
+        schema: z9.boolean().optional(),
         prompt: "flatScreen, glare, lighting, reflections, clipToFrame: true | false."
       },
       clipToFrame: {
         exposure: "included",
-        schema: z8.boolean().optional(),
+        schema: z9.boolean().optional(),
         prompt: "flatScreen, glare, lighting, reflections, clipToFrame: true | false."
       }
     };
@@ -14141,7 +14507,7 @@ var init_aiShotProjection = __esm({
     API_AI_SHOT_PATCH_SHAPE = Object.fromEntries(
       API_AI_SHOT_INCLUDED_ENTRIES.map(([field, projection]) => [field, projection.schema])
     );
-    apiAiShotPatchSchema = z8.object(API_AI_SHOT_PATCH_SHAPE);
+    apiAiShotPatchSchema = z9.object(API_AI_SHOT_PATCH_SHAPE);
     API_AI_SHOT_PROMPT_INVENTORY = [
       ...new Set(API_AI_SHOT_INCLUDED_ENTRIES.map(([, projection]) => projection.prompt))
     ];
@@ -14171,8 +14537,8 @@ var init_visionGeneration = __esm({
 });
 
 // ../api/_lib/refineProjectContracts.ts
-import { z as z9 } from "zod";
-var localeIds, MAX_DURABLE_MODEL_PROSE, hexSchema, currentColorSchema, shotPatchSchema, aiNumberSchema, captionStylePatchSchema, MAX_WIRE_GRADIENT_STOPS, gradientStopSchema, backgroundPatchSchema, stripBackgroundPatchSchema, framePatchSchema, currentCaptionStyleSchema, currentGradientStopSchema, currentStops, currentBackgroundSchema, currentStripBackgroundSchema, currentShotSchema, currentFramePatchSchema, localeCodeSchema, focusSchema, currentFrameSchema, captionOperationSchema, frameOperationSchema, frameIdSchema, assetIdSchema, structuralOperationSchema, attachmentSchema, visionScreenshotSchema, requestSchema, legacyFinalizeSchema, durableUsageSchema, durablePassSchema, durableStateDiffSchema, agentOutcomeSchema, durableFinalizeSchema, revertSchema, finalizeSchema, createSessionSchema, historySchema, REFINE_FIELD_LABELS;
+import { z as z10 } from "zod";
+var localeIds, MAX_DURABLE_MODEL_PROSE, hexSchema, currentColorSchema, shotPatchSchema, aiNumberSchema, captionStylePatchSchema, MAX_WIRE_GRADIENT_STOPS, gradientStopSchema, backgroundPatchSchema, stripBackgroundPatchSchema, framePatchSchema, currentCaptionStyleSchema, currentGradientStopSchema, currentStops, currentBackgroundSchema, currentStripBackgroundSchema, currentShotSchema, currentFramePatchSchema, localeCodeSchema, focusSchema, currentFrameSchema, captionOperationSchema, frameOperationSchema, frameIdSchema, assetIdSchema, structuralOperationSchema, attachmentSchema, refinementAttachmentsSchema, visionScreenshotSchema, requestSchema, legacyFinalizeSchema, durableUsageSchema, durablePassSchema, durableStateDiffSchema, agentOutcomeSchema, durableFinalizeSchema, revertSchema, finalizeSchema, createSessionSchema, historySchema, REFINE_FIELD_LABELS;
 var init_refineProjectContracts = __esm({
   "../api/_lib/refineProjectContracts.ts"() {
     "use strict";
@@ -14184,229 +14550,237 @@ var init_refineProjectContracts = __esm({
     init_aiShotProjection();
     localeIds = APP_STORE_LOCALES;
     MAX_DURABLE_MODEL_PROSE = 32e3;
-    hexSchema = z9.string().trim().regex(/^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
-    currentColorSchema = z9.string().trim().max(64);
+    hexSchema = z10.string().trim().regex(/^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
+    currentColorSchema = z10.string().trim().max(64);
     shotPatchSchema = apiAiShotPatchSchema;
-    aiNumberSchema = z9.union([z9.number().finite(), z9.object({ scale: z9.number().finite() })]);
-    captionStylePatchSchema = z9.object({
-      fontId: z9.enum(AI_CAPTION_FONT_IDS).optional(),
+    aiNumberSchema = z10.union([z10.number().finite(), z10.object({ scale: z10.number().finite() })]);
+    captionStylePatchSchema = z10.object({
+      fontId: z10.enum(AI_CAPTION_FONT_IDS).optional(),
       sizePt: aiNumberSchema.optional(),
       color: hexSchema.optional(),
-      align: z9.enum(["left", "center", "right"]).optional(),
+      align: z10.enum(["left", "center", "right"]).optional(),
       maxWidth: aiNumberSchema.optional(),
       lineHeight: aiNumberSchema.optional(),
-      band: z9.enum(["top", "bottom"]).optional(),
+      band: z10.enum(["top", "bottom"]).optional(),
       bandInset: aiNumberSchema.optional(),
       bandCenter: aiNumberSchema.optional(),
       reserveLines: aiNumberSchema.optional()
     });
     MAX_WIRE_GRADIENT_STOPS = 32;
-    gradientStopSchema = z9.object({ color: hexSchema, at: z9.number().finite() });
-    backgroundPatchSchema = z9.object({
-      stops: z9.array(gradientStopSchema).max(MAX_WIRE_GRADIENT_STOPS).optional(),
-      angle: z9.number().finite().optional()
+    gradientStopSchema = z10.object({ color: hexSchema, at: z10.number().finite() });
+    backgroundPatchSchema = z10.object({
+      stops: z10.array(gradientStopSchema).max(MAX_WIRE_GRADIENT_STOPS).optional(),
+      angle: z10.number().finite().optional()
     });
     stripBackgroundPatchSchema = backgroundPatchSchema.extend({
-      shadow: z9.boolean().optional(),
-      floorReflection: z9.boolean().optional()
+      shadow: z10.boolean().optional(),
+      floorReflection: z10.boolean().optional()
     });
-    framePatchSchema = z9.object({
+    framePatchSchema = z10.object({
       captionStyle: captionStylePatchSchema.optional(),
       background: backgroundPatchSchema.optional()
     });
     currentCaptionStyleSchema = captionStylePatchSchema.extend({
       color: currentColorSchema.optional()
     });
-    currentGradientStopSchema = z9.object({ color: currentColorSchema, at: z9.number().finite() });
-    currentStops = z9.array(currentGradientStopSchema).max(MAX_WIRE_GRADIENT_STOPS).optional();
+    currentGradientStopSchema = z10.object({ color: currentColorSchema, at: z10.number().finite() });
+    currentStops = z10.array(currentGradientStopSchema).max(MAX_WIRE_GRADIENT_STOPS).optional();
     currentBackgroundSchema = backgroundPatchSchema.extend({ stops: currentStops });
     currentStripBackgroundSchema = stripBackgroundPatchSchema.extend({ stops: currentStops });
     currentShotSchema = shotPatchSchema.extend({
       customColor: currentColorSchema.optional(),
       clayCustom: currentColorSchema.optional()
     });
-    currentFramePatchSchema = z9.object({
+    currentFramePatchSchema = z10.object({
       captionStyle: currentCaptionStyleSchema.optional(),
       background: currentBackgroundSchema.optional()
     });
-    localeCodeSchema = z9.string().trim().regex(/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/);
-    focusSchema = z9.discriminatedUnion("kind", [
-      z9.object({ kind: z9.literal("project"), label: z9.string().trim().min(1).max(180) }),
-      z9.object({
-        kind: z9.literal("frame"),
-        frameId: z9.string().trim().min(1).max(180),
-        label: z9.string().trim().min(1).max(180)
+    localeCodeSchema = z10.string().trim().regex(/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/);
+    focusSchema = z10.discriminatedUnion("kind", [
+      z10.object({ kind: z10.literal("project"), label: z10.string().trim().min(1).max(180) }),
+      z10.object({
+        kind: z10.literal("frame"),
+        frameId: z10.string().trim().min(1).max(180),
+        label: z10.string().trim().min(1).max(180)
       }),
-      z9.object({
-        kind: z9.literal("device"),
-        frameId: z9.string().trim().min(1).max(180),
-        deviceId: z9.string().trim().min(1).max(180),
-        label: z9.string().trim().min(1).max(180)
+      z10.object({
+        kind: z10.literal("device"),
+        frameId: z10.string().trim().min(1).max(180),
+        deviceId: z10.string().trim().min(1).max(180),
+        label: z10.string().trim().min(1).max(180)
       }),
-      z9.object({
-        kind: z9.literal("caption"),
-        frameId: z9.string().trim().min(1).max(180),
-        captionIndex: z9.number().int().min(0).max(32),
-        label: z9.string().trim().min(1).max(240)
+      z10.object({
+        kind: z10.literal("caption"),
+        frameId: z10.string().trim().min(1).max(180),
+        captionIndex: z10.number().int().min(0).max(32),
+        label: z10.string().trim().min(1).max(240)
       })
     ]);
-    currentFrameSchema = z9.object({
-      id: z9.string().trim().min(1).max(180),
-      label: z9.string().trim().min(1).max(180),
-      sourceName: z9.string().trim().min(1).max(180).nullable(),
-      devices: z9.array(z9.object({
-        id: z9.string().trim().min(1).max(180),
-        label: z9.string().trim().min(1).max(180),
+    currentFrameSchema = z10.object({
+      id: z10.string().trim().min(1).max(180),
+      label: z10.string().trim().min(1).max(180),
+      sourceName: z10.string().trim().min(1).max(180).nullable(),
+      devices: z10.array(z10.object({
+        id: z10.string().trim().min(1).max(180),
+        label: z10.string().trim().min(1).max(180),
         look: currentShotSchema
       })).max(20),
-      captions: z9.array(z9.object({
-        index: z9.number().int().min(0).max(32),
-        label: z9.string().trim().min(1).max(180),
-        text: z9.string().max(240),
+      captions: z10.array(z10.object({
+        index: z10.number().int().min(0).max(32),
+        label: z10.string().trim().min(1).max(180),
+        text: z10.string().max(240),
         style: currentCaptionStyleSchema
       })).max(32),
-      background: currentBackgroundSchema.nullable()
+      background: currentBackgroundSchema.nullable(),
+      // The per-screenshot slot this frame's pixels occupy, or null for a frame with no screenshot yet.
+      // Optional so a client that predates it still parses; the prompt then numbers by position.
+      screenshotIndex: z10.number().int().min(0).max(31).nullable().optional()
     });
-    captionOperationSchema = z9.discriminatedUnion("operation", [
-      z9.object({
-        operation: z9.literal("add"),
-        frameId: z9.string().trim().min(1).max(180),
-        afterIndex: z9.number().int().min(-1).max(32).optional(),
-        text: z9.string().trim().max(240),
+    captionOperationSchema = z10.discriminatedUnion("operation", [
+      z10.object({
+        operation: z10.literal("add"),
+        frameId: z10.string().trim().min(1).max(180),
+        afterIndex: z10.number().int().min(-1).max(32).optional(),
+        text: z10.string().trim().max(240),
         style: captionStylePatchSchema.optional()
       }),
-      z9.object({
-        operation: z9.literal("remove"),
-        frameId: z9.string().trim().min(1).max(180),
-        index: z9.number().int().min(0).max(32)
+      z10.object({
+        operation: z10.literal("remove"),
+        frameId: z10.string().trim().min(1).max(180),
+        index: z10.number().int().min(0).max(32)
       }),
-      z9.object({
-        operation: z9.literal("move"),
-        frameId: z9.string().trim().min(1).max(180),
-        index: z9.number().int().min(0).max(32),
-        toFrameId: z9.string().trim().min(1).max(180),
-        toIndex: z9.number().int().min(0).max(32).optional()
+      z10.object({
+        operation: z10.literal("move"),
+        frameId: z10.string().trim().min(1).max(180),
+        index: z10.number().int().min(0).max(32),
+        toFrameId: z10.string().trim().min(1).max(180),
+        toIndex: z10.number().int().min(0).max(32).optional()
       })
     ]);
-    frameOperationSchema = z9.discriminatedUnion("operation", [
-      z9.object({
-        operation: z9.literal("add"),
-        afterFrameId: z9.string().trim().min(1).max(180).optional()
+    frameOperationSchema = z10.discriminatedUnion("operation", [
+      z10.object({
+        operation: z10.literal("add"),
+        afterFrameId: z10.string().trim().min(1).max(180).optional()
       }),
-      z9.object({
-        operation: z9.literal("remove"),
-        frameId: z9.string().trim().min(1).max(180)
+      z10.object({
+        operation: z10.literal("remove"),
+        frameId: z10.string().trim().min(1).max(180)
       }),
-      z9.object({
-        operation: z9.literal("move"),
-        frameId: z9.string().trim().min(1).max(180),
-        afterFrameId: z9.string().trim().min(1).max(180).optional()
+      z10.object({
+        operation: z10.literal("move"),
+        frameId: z10.string().trim().min(1).max(180),
+        afterFrameId: z10.string().trim().min(1).max(180).optional()
       }),
-      z9.object({
-        operation: z9.literal("split"),
-        frameId: z9.string().trim().min(1).max(180),
-        deviceIds: z9.array(z9.string().trim().min(1).max(180)).min(1).max(20)
+      z10.object({
+        operation: z10.literal("split"),
+        frameId: z10.string().trim().min(1).max(180),
+        deviceIds: z10.array(z10.string().trim().min(1).max(180)).min(1).max(20)
       })
     ]);
-    frameIdSchema = z9.string().trim().min(1).max(180);
-    assetIdSchema = z9.string().trim().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/);
-    structuralOperationSchema = z9.discriminatedUnion("op", [
-      z9.object({ op: z9.literal("frame.add"), afterFrameId: frameIdSchema.optional() }),
-      z9.object({ op: z9.literal("frame.remove"), frameId: frameIdSchema }),
-      z9.object({ op: z9.literal("frame.move"), frameId: frameIdSchema, afterFrameId: frameIdSchema.optional() }),
-      z9.object({
-        op: z9.literal("frame.split"),
+    frameIdSchema = z10.string().trim().min(1).max(180);
+    assetIdSchema = z10.string().trim().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/);
+    structuralOperationSchema = z10.discriminatedUnion("op", [
+      z10.object({
+        op: z10.literal("frame.add"),
+        afterFrameId: frameIdSchema.optional(),
+        frameRef: z10.string().min(1).max(64).regex(/^[A-Za-z][A-Za-z0-9_-]*$/).describe("Patch-local frame alias, unique and different from every existing frame/device id. Later ordered operations may use it as a frame target. Never persisted.").optional()
+      }),
+      z10.object({ op: z10.literal("frame.remove"), frameId: frameIdSchema }),
+      z10.object({ op: z10.literal("frame.move"), frameId: frameIdSchema, afterFrameId: frameIdSchema.optional() }),
+      z10.object({
+        op: z10.literal("frame.split"),
         frameId: frameIdSchema,
-        deviceIds: z9.array(frameIdSchema).min(1).max(20)
+        deviceIds: z10.array(frameIdSchema).min(1).max(20)
       }),
-      z9.object({ op: z9.literal("frame.combine"), frameId: frameIdSchema, fromFrameId: frameIdSchema }),
-      z9.object({ op: z9.literal("frame.template-reset"), frameId: frameIdSchema }),
-      z9.object({
-        op: z9.literal("caption.add"),
+      z10.object({ op: z10.literal("frame.combine"), frameId: frameIdSchema, fromFrameId: frameIdSchema }),
+      z10.object({ op: z10.literal("frame.template-reset"), frameId: frameIdSchema }),
+      z10.object({
+        op: z10.literal("caption.add"),
         frameId: frameIdSchema,
-        afterIndex: z9.number().int().min(-1).max(32).optional(),
-        text: z9.string().trim().max(240),
+        afterIndex: z10.number().int().min(-1).max(32).optional(),
+        text: z10.string().trim().max(240),
         style: captionStylePatchSchema.optional()
       }),
-      z9.object({ op: z9.literal("caption.remove"), frameId: frameIdSchema, index: z9.number().int().min(0).max(32) }),
-      z9.object({
-        op: z9.literal("caption.move"),
+      z10.object({ op: z10.literal("caption.remove"), frameId: frameIdSchema, index: z10.number().int().min(0).max(32) }),
+      z10.object({
+        op: z10.literal("caption.move"),
         frameId: frameIdSchema,
-        index: z9.number().int().min(0).max(32),
+        index: z10.number().int().min(0).max(32),
         toFrameId: frameIdSchema,
-        toIndex: z9.number().int().min(0).max(32).optional()
+        toIndex: z10.number().int().min(0).max(32).optional()
       }),
-      z9.object({
-        op: z9.literal("device.move"),
+      z10.object({
+        op: z10.literal("device.move"),
         deviceId: frameIdSchema,
         toFrameId: frameIdSchema,
-        toIndex: z9.number().int().min(0).max(20).optional()
+        toIndex: z10.number().int().min(0).max(20).optional()
       }),
-      z9.object({ op: z9.literal("device.reorder"), deviceId: frameIdSchema, toIndex: z9.number().int().min(0).max(20) }),
-      z9.object({ op: z9.literal("device.remove"), deviceId: frameIdSchema }),
+      z10.object({ op: z10.literal("device.reorder"), deviceId: frameIdSchema, toIndex: z10.number().int().min(0).max(20) }),
+      z10.object({ op: z10.literal("device.remove"), deviceId: frameIdSchema }),
       // The two asset operations (#573). `assetId` is an OPAQUE per-turn handle, so the wire bounds its
       // shape and nothing more: a path, a URL or an account id is never a legal value here because the
       // handle table is the only thing that resolves one, and it holds only handles this turn minted.
-      z9.object({
-        op: z9.literal("device.add"),
+      z10.object({
+        op: z10.literal("device.add"),
         toFrameId: frameIdSchema,
         assetId: assetIdSchema,
-        toIndex: z9.number().int().min(0).max(20).optional()
+        toIndex: z10.number().int().min(0).max(20).optional()
       }),
-      z9.object({ op: z9.literal("device.replace"), deviceId: frameIdSchema, assetId: assetIdSchema })
+      z10.object({ op: z10.literal("device.replace"), deviceId: frameIdSchema, assetId: assetIdSchema })
     ]);
-    attachmentSchema = z9.object({
-      ref: z9.string().trim().min(1).max(512),
-      label: z9.string().trim().min(1).max(180),
-      width: z9.number().int().min(1).max(2e4).optional(),
-      height: z9.number().int().min(1).max(2e4).optional()
+    attachmentSchema = z10.object({
+      ref: z10.string().trim().min(1).max(512),
+      label: z10.string().trim().min(1).max(180),
+      width: z10.number().int().min(1).max(2e4).optional(),
+      height: z10.number().int().min(1).max(2e4).optional()
     });
-    visionScreenshotSchema = z9.object({
-      name: z9.string().trim().min(1).max(180),
-      mediaType: z9.enum(["image/png", "image/jpeg", "image/webp"]),
-      data: z9.string().min(16).max(MAX_VISION_IMAGE_BASE64).regex(/^[A-Za-z0-9+/]+=*$/)
+    refinementAttachmentsSchema = z10.array(attachmentSchema).max(MAX_START_SCREENSHOTS);
+    visionScreenshotSchema = z10.object({
+      name: z10.string().trim().min(1).max(180),
+      mediaType: z10.enum(["image/png", "image/jpeg", "image/webp"]),
+      data: z10.string().min(16).max(MAX_VISION_IMAGE_BASE64).regex(/^[A-Za-z0-9+/]+=*$/)
     });
-    requestSchema = z9.object({
-      projectId: z9.string().uuid(),
-      sessionId: z9.string().uuid().optional(),
-      turnId: z9.string().uuid().optional(),
-      cycle: z9.number().int().min(1).max(3).optional(),
-      instruction: z9.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH),
+    requestSchema = z10.object({
+      projectId: z10.string().uuid(),
+      sessionId: z10.string().uuid().optional(),
+      turnId: z10.string().uuid().optional(),
+      cycle: z10.number().int().min(1).max(3).optional(),
+      instruction: z10.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH),
       focus: focusSchema.optional(),
       baseLocale: localeCodeSchema,
-      current: z9.object({
-        captions: z9.array(z9.string().max(240)).min(1).max(MAX_START_SCREENSHOTS),
-        outputs: z9.array(z9.enum(START_OUTPUT_IDS)).min(1).max(START_OUTPUT_IDS.length),
+      current: z10.object({
+        captions: z10.array(z10.string().max(240)).min(1).max(MAX_START_SCREENSHOTS),
+        outputs: z10.array(z10.enum(START_OUTPUT_IDS)).min(1).max(START_OUTPUT_IDS.length),
         // Bounded by the CATALOG, not by six. Studio's Add-language dialog offers every catalog entry
         // with no ceiling and the reducer just appends, so a seventh language used to 400 every Agent
         // turn on that project forever. A count ceiling below what the product lets a user build is a
         // lockout; this one is only here to bound the prompt.
-        locales: z9.array(localeCodeSchema).min(1).max(localeIds.length),
-        designPreset: z9.enum(START_DESIGN_PRESET_IDS).nullable(),
-        layout: z9.enum(START_LAYOUT_IDS).nullable(),
-        frames: z9.array(currentShotSchema).min(1).max(MAX_START_SCREENSHOTS),
+        locales: z10.array(localeCodeSchema).min(1).max(localeIds.length),
+        designPreset: z10.enum(START_DESIGN_PRESET_IDS).nullable(),
+        layout: z10.enum(START_LAYOUT_IDS).nullable(),
+        frames: z10.array(currentShotSchema).min(1).max(MAX_START_SCREENSHOTS),
         background: currentStripBackgroundSchema.optional(),
-        frameStyles: z9.array(currentFramePatchSchema).min(1).max(MAX_START_SCREENSHOTS).optional(),
+        frameStyles: z10.array(currentFramePatchSchema).min(1).max(MAX_START_SCREENSHOTS).optional(),
         // Structural editing can add blank frames without adding source screenshots. Keep the vision
         // attachment ceiling at ten while allowing those real project frames back into correction
         // cycles instead of rejecting the first successful `add` operation on a full strip.
-        structure: z9.array(currentFrameSchema).min(1).max(20).optional()
+        structure: z10.array(currentFrameSchema).min(1).max(20).optional()
       }),
-      screenshots: z9.array(visionScreenshotSchema).min(1).max(MAX_START_SCREENSHOTS),
+      screenshots: z10.array(visionScreenshotSchema).min(1).max(MAX_START_SCREENSHOTS),
       // Private refs from Studio. Opaque asset handles are derived server-side, so a client cannot
       // plant its own handle table or smuggle a ref into model-visible data.
-      attachments: z9.array(attachmentSchema).max(MAX_START_SCREENSHOTS).optional(),
+      attachments: refinementAttachmentsSchema.optional(),
       // Opaque per-turn handles, on the wire because the MCP doors mint the table where the refs are
       // (the adapter) and buy the pass somewhere else — hosted in-process, local over the control
       // plane. Carrying a descriptor is not carrying authority: `{ id, label }` names nothing outside
       // the turn that minted it, binds nothing, and the Studio door overwrites this field with its own
       // table's descriptors regardless of what a client sent. The gate that matters is the
       // authoritative write, which re-checks every ref a record introduces.
-      assets: z9.array(z9.object({
-        id: z9.string().trim().min(1).max(64),
-        label: z9.string().trim().min(1).max(180),
-        width: z9.number().int().min(1).max(2e4).optional(),
-        height: z9.number().int().min(1).max(2e4).optional()
+      assets: z10.array(z10.object({
+        id: z10.string().trim().min(1).max(64),
+        label: z10.string().trim().min(1).max(180),
+        width: z10.number().int().min(1).max(2e4).optional(),
+        height: z10.number().int().min(1).max(2e4).optional()
       })).max(MAX_START_SCREENSHOTS).optional(),
       composedPreview: visionScreenshotSchema.optional(),
       // MEASURED, never authored (#550): the client derives these from the engine's own collision
@@ -14414,17 +14788,24 @@ var init_refineProjectContracts = __esm({
       // prompt renders into prose, never a value that reaches the reducer, and a strip with an unusual
       // number of overlaps must not 400 a turn that was not about layout. The client's own ceiling is
       // `MAX_REPORTED_FINDINGS` (mockup-engine/layoutFindings.ts), well inside this.
-      layoutFindings: z9.array(z9.object({
-        kind: z9.enum(["caption-caption", "caption-device", "device-device"]),
-        frames: z9.array(z9.number().int().min(0).max(31)).min(1).max(2),
-        depthPct: z9.number().int().min(0).max(100),
-        anchored: z9.boolean(),
-        clearAtScale: z9.number().min(0.05).max(1).optional()
+      layoutFindings: z10.array(z10.object({
+        kind: z10.enum(["caption-caption", "caption-device", "device-device"]),
+        frames: z10.array(z10.number().int().min(0).max(31)).min(1).max(2),
+        depthPct: z10.number().int().min(0).max(100),
+        anchored: z10.boolean(),
+        clearAtScale: z10.number().min(0.05).max(1).optional()
       })).max(24).optional(),
-      previous: z9.object({
-        actualDiff: z9.array(z9.string().trim().min(1).max(300)).max(24),
-        inspection: z9.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
-        cycle: z9.number().int().min(1).max(2)
+      previous: z10.object({
+        actualDiff: z10.array(z10.string().trim().min(1).max(300)).max(24),
+        inspection: z10.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
+        cycle: z10.number().int().min(1).max(2),
+        // The creating structural operations earlier cycles of this turn already performed, so the
+        // prompt can list them and the model stops re-adding what it added. Optional: an older client
+        // sends none, and the coordinator drops a repeat regardless.
+        appliedOperations: z10.array(z10.object({
+          op: z10.string().trim().min(1).max(40),
+          target: z10.string().trim().min(1).max(180)
+        })).max(32).optional()
       }).optional()
     }).superRefine((value, context) => {
       if (value.sessionId == null !== (value.turnId == null)) {
@@ -14454,13 +14835,13 @@ var init_refineProjectContracts = __esm({
         });
       }
     });
-    legacyFinalizeSchema = z9.object({
-      generationId: z9.string().uuid(),
-      outcome: z9.enum(["completed", "cancelled", "failed"]),
-      projectId: z9.string().uuid(),
-      instruction: z9.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH).optional(),
-      effectSummary: z9.string().trim().min(1).max(2e3).optional(),
-      turnStatus: z9.enum(["applied", "no_change", "failed", "cancelled"]).optional()
+    legacyFinalizeSchema = z10.object({
+      generationId: z10.string().uuid(),
+      outcome: z10.enum(["completed", "cancelled", "failed"]),
+      projectId: z10.string().uuid(),
+      instruction: z10.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH).optional(),
+      effectSummary: z10.string().trim().min(1).max(2e3).optional(),
+      turnStatus: z10.enum(["applied", "no_change", "failed", "cancelled"]).optional()
     }).superRefine((value, context) => {
       const durableFields = [value.instruction, value.effectSummary, value.turnStatus];
       const present = durableFields.filter((field) => field !== void 0).length;
@@ -14472,52 +14853,57 @@ var init_refineProjectContracts = __esm({
         });
       }
     });
-    durableUsageSchema = z9.object({
-      inputTokens: z9.number().int().min(0),
-      cacheReadTokens: z9.number().int().min(0).default(0),
-      imageTokens: z9.number().int().min(0).nullable(),
-      outputTokens: z9.number().int().min(0),
-      totalTokens: z9.number().int().min(0)
+    durableUsageSchema = z10.object({
+      inputTokens: z10.number().int().min(0),
+      cacheReadTokens: z10.number().int().min(0).default(0),
+      imageTokens: z10.number().int().min(0).nullable(),
+      outputTokens: z10.number().int().min(0),
+      totalTokens: z10.number().int().min(0)
     });
-    durablePassSchema = z9.object({
-      phase: z9.enum(["applying", "inspecting", "adjusting"]),
-      generationId: z9.string().uuid(),
-      summary: z9.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
+    durablePassSchema = z10.object({
+      phase: z10.enum(["applying", "inspecting", "adjusting"]),
+      generationId: z10.string().uuid(),
+      summary: z10.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
       usage: durableUsageSchema,
-      createdAt: z9.string().datetime()
+      createdAt: z10.string().datetime()
     });
-    durableStateDiffSchema = z9.object({
-      summary: z9.string().trim().min(1).max(2e3),
-      broaderChanges: z9.array(z9.string().trim().min(1).max(500)).max(24),
-      remainingMismatch: z9.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE).nullable()
+    durableStateDiffSchema = z10.object({
+      summary: z10.string().trim().min(1).max(2e3),
+      broaderChanges: z10.array(z10.string().trim().min(1).max(500)).max(24),
+      remainingMismatch: z10.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE).nullable()
     });
-    agentOutcomeSchema = z9.custom((value) => {
+    agentOutcomeSchema = z10.custom((value) => {
       try {
         return !!value && typeof value === "object" && validateAgentOutcome(value).length === 0;
       } catch {
         return false;
       }
     }, { message: "The Agent outcome is invalid." });
-    durableFinalizeSchema = z9.object({
-      projectId: z9.string().uuid(),
-      sessionId: z9.string().uuid(),
-      turnId: z9.string().uuid(),
+    durableFinalizeSchema = z10.object({
+      projectId: z10.string().uuid(),
+      sessionId: z10.string().uuid(),
+      turnId: z10.string().uuid(),
       // #580 — the retry / clarification chain, and the ONLY receipt fact this door takes from the
       // browser. Every other figure on the receipt is re-read server-side from the ledger or derived
       // from the validated outcome; a parent id is a correlation the client alone knows.
-      parentTurnId: z9.string().uuid().optional(),
-      generationIds: z9.array(z9.string().uuid()).min(1).max(3),
-      outcome: z9.enum(["completed", "cancelled", "failed"]),
-      committed: z9.boolean(),
-      instruction: z9.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH),
+      parentTurnId: z10.string().uuid().optional(),
+      generationIds: z10.array(z10.string().uuid()).min(1).max(3),
+      outcome: z10.enum(["completed", "cancelled", "failed"]),
+      committed: z10.boolean(),
+      instruction: z10.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH),
       focus: focusSchema,
-      interpretation: z9.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
-      passes: z9.array(durablePassSchema).min(1).max(3),
+      interpretation: z10.string().trim().min(1).max(MAX_DURABLE_MODEL_PROSE),
+      passes: z10.array(durablePassSchema).min(1).max(3),
       finalStateDiff: durableStateDiffSchema,
       agentOutcome: agentOutcomeSchema,
-      turnStatus: z9.enum(["applied", "no_change", "capped", "needs_input", "failed", "cancelled"]),
-      startedAt: z9.string().datetime(),
-      completedAt: z9.string().datetime()
+      // #781 — the coordinator's unmet-demand classification for the whole turn. Optional and
+      // deliberately loose here: it is analytics, so a malformed value must never fail a finalize that
+      // settles real money. `parseAgentTurnDemand` closes it against the vocabulary downstream, and
+      // anything it rejects becomes `not_measured` rather than a 400.
+      agentDemand: z10.unknown().optional(),
+      turnStatus: z10.enum(["applied", "no_change", "capped", "needs_input", "failed", "cancelled"]),
+      startedAt: z10.string().datetime(),
+      completedAt: z10.string().datetime()
     }).superRefine((value, context) => {
       const passGenerationIds = value.passes.map((pass) => pass.generationId);
       if (new Set(value.generationIds).size !== value.generationIds.length) {
@@ -14550,23 +14936,23 @@ var init_refineProjectContracts = __esm({
         });
       }
     });
-    revertSchema = z9.object({
-      intent: z9.literal("revert"),
-      projectId: z9.string().uuid(),
+    revertSchema = z10.object({
+      intent: z10.literal("revert"),
+      projectId: z10.string().uuid(),
       /** The committed turn being undone. Becomes the new receipt's `parent_turn_id`. */
-      turnId: z9.string().uuid(),
+      turnId: z10.string().uuid(),
       /** The revert's own turn id, minted by the browser exactly as a turn id is. */
-      revertTurnId: z9.string().uuid()
+      revertTurnId: z10.string().uuid()
     });
-    finalizeSchema = z9.union([revertSchema, durableFinalizeSchema, legacyFinalizeSchema]);
-    createSessionSchema = z9.object({
-      projectId: z9.string().uuid(),
-      sessionId: z9.string().uuid(),
-      firstInstruction: z9.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH).optional()
+    finalizeSchema = z10.union([revertSchema, durableFinalizeSchema, legacyFinalizeSchema]);
+    createSessionSchema = z10.object({
+      projectId: z10.string().uuid(),
+      sessionId: z10.string().uuid(),
+      firstInstruction: z10.string().trim().min(1).max(MAX_REFINE_PROMPT_LENGTH).optional()
     });
-    historySchema = z9.object({
-      projectId: z9.string().uuid(),
-      sessionId: z9.string().uuid().optional()
+    historySchema = z10.object({
+      projectId: z10.string().uuid(),
+      sessionId: z10.string().uuid().optional()
     });
     REFINE_FIELD_LABELS = {
       projectId: "the project id",
@@ -14728,47 +15114,55 @@ async function renderedTurn(deps, state, screens) {
   if (!rendered.ok) throw new Error("The project could not be rendered for Agent inspection.");
   const bytesByShotId = new Map(screens.screenManifest.map((entry) => [entry.shotId, entry.bytes]));
   const baseCaptions = resolveCaptionText(state.captionText, state.baseLocale, state.baseLocale);
-  const retained = await Promise.all(state.panels.flatMap((panel, frameIndex) => {
+  const hasPixels = (shot) => bytesByShotId.has(shot.id);
+  const visionScreens = await Promise.all(state.panels.flatMap((panel) => {
     const devices = state.shots.filter((shot) => shot.panelId === panel.id);
-    const representative = devices.find((shot) => bytesByShotId.has(shot.id));
+    const representative = devices.find(hasPixels);
     if (!representative) return [];
     const bytes = bytesByShotId.get(representative.id);
     const captions = baseCaptions[panel.id] ?? [];
     const background2 = aiBackgroundFromPanel(state.panelBackgrounds[panel.id]);
     return [compactVisionImage(bytes, representative.frameName).then((vision) => ({
-      screen: {
-        ...vision,
-        panelId: panel.id,
-        caption: captions[0]?.text ?? "",
-        frame: aiShotPatchFromLook(representative.look),
-        captionStyle: aiCaptionStyleFromLayer(captions[0]),
-        background: background2
-      },
-      structure: {
-        id: panel.id,
-        label: `Frame ${frameIndex + 1}`,
-        sourceName: devices[0]?.frameName ?? null,
-        devices: devices.map((shot, deviceIndex) => ({
-          id: shot.id,
-          label: devices.length === 1 ? shot.frameName : `${shot.frameName} \xB7 Device ${deviceIndex + 1}`,
-          look: aiShotPatchFromLook(shot.look)
-        })),
-        captions: captions.map((caption, index) => ({
-          index,
-          label: caption.text.trim() || `Caption ${index + 1}`,
-          text: caption.text,
-          style: aiCaptionStyleFromLayer(caption)
-        })),
-        background: background2
-      }
+      ...vision,
+      panelId: panel.id,
+      caption: captions[0]?.text ?? "",
+      frame: aiShotPatchFromLook(representative.look),
+      captionStyle: aiCaptionStyleFromLayer(captions[0]),
+      background: background2
     }))];
   }));
-  if (retained.length === 0) throw new Error("The project has no readable screenshots for Agent inspection.");
+  let nextScreenshot = 0;
+  const structure = state.panels.map((panel, frameIndex) => {
+    const devices = state.shots.filter((shot) => shot.panelId === panel.id);
+    const captions = baseCaptions[panel.id] ?? [];
+    const background2 = aiBackgroundFromPanel(state.panelBackgrounds[panel.id]);
+    const screenshotIndex = devices.some(hasPixels) ? nextScreenshot++ : null;
+    return {
+      id: panel.id,
+      label: `Frame ${frameIndex + 1}`,
+      sourceName: devices[0]?.frameName ?? null,
+      devices: devices.map((shot, deviceIndex) => ({
+        id: shot.id,
+        label: devices.length === 1 ? shot.frameName : `${shot.frameName} \xB7 Device ${deviceIndex + 1}`,
+        look: aiShotPatchFromLook(shot.look)
+      })),
+      captions: captions.map((caption, index) => ({
+        index,
+        label: caption.text.trim() || `Caption ${index + 1}`,
+        text: caption.text,
+        style: aiCaptionStyleFromLayer(caption)
+      })),
+      background: background2,
+      screenshotIndex
+    };
+  });
+  if (visionScreens.length === 0) throw new Error("The project has no readable screenshots for Agent inspection.");
+  const layoutFindings = rendered.layout?.findings ?? (rendered.layoutMeasured ? [] : void 0);
   return {
-    screens: retained.map((item) => item.screen),
-    structure: retained.map((item) => item.structure),
+    screens: visionScreens,
+    structure,
     ...rendered.stripBase64 ? { composedPreview: await compactVisionImage(rendered.stripBase64, "shotops-composed-preview.png") } : {},
-    ...rendered.layout?.findings ? { layoutFindings: rendered.layout.findings } : {}
+    ...layoutFindings !== void 0 ? { layoutFindings } : {}
   };
 }
 function outsideFocus(patch, focus, rendered) {
@@ -14841,11 +15235,14 @@ function requestForPass(context, input) {
     // planner pass carries about a supplied screenshot has to be meaningless outside this turn.
     ...context.assets.length > 0 ? { assets: context.assets.map((asset) => ({ ...asset })) } : {},
     ...input.rendered.composedPreview ? { composedPreview: input.rendered.composedPreview } : {},
-    ...input.rendered.layoutFindings ? { layoutFindings: input.rendered.layoutFindings } : {},
+    // #827 — `!== undefined`, not truthiness: a measured-clean render's `layoutFindings` is `[]`,
+    // which must still reach the planner (it is what says "measured, nothing wrong").
+    ...input.rendered.layoutFindings !== void 0 ? { layoutFindings: input.rendered.layoutFindings } : {},
     ...input.previous ? {
       previous: {
         ...input.previous,
-        actualDiff: [...input.previous.actualDiff]
+        actualDiff: [...input.previous.actualDiff],
+        ...input.previous.appliedOperations ? { appliedOperations: [...input.previous.appliedOperations] } : {}
       }
     } : {}
   });
@@ -14866,7 +15263,9 @@ function generatedAuthorization(request, generated, generationId, panelIds, rend
     ...generated.followUp ? { followUp: generated.followUp } : {},
     ...patch ? { patch, broaderChanges: outsideFocus(patch, request.focus ?? contextFocus(), rendered) } : {},
     ...generated.outcome ? { terminalOutcome: generated.outcome } : {},
-    ...generated.gaps ? { gaps: generated.gaps } : {}
+    ...generated.gaps ? { gaps: generated.gaps } : {},
+    // #781 — the same intent that decided the outcome, reported as this pass's unmet demand.
+    ...generated.demand ? { demand: generated.demand } : {}
   };
 }
 function contextFocus() {
@@ -14877,7 +15276,7 @@ function applyAllowance(allowance, pass) {
 }
 async function authorizePass(context, request, panelIds, rendered) {
   context.screenshotCount = request.screenshots.length + (request.composedPreview ? 1 : 0);
-  const result = await context.runtime.plannerPass(context.userId, request, context.turnKey);
+  const result = await context.runtime.plannerPass(context.userId, request, context.turnKey, context.assetTable);
   applyAllowance(context.allowance, result.allowance);
   if (result.ok) {
     return generatedAuthorization(request, result.plan, result.generationId, panelIds, rendered);
@@ -14934,7 +15333,8 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
     focus: input.focus,
     allowance,
     runtime,
-    assets: assetTable.descriptors
+    assets: assetTable.descriptors,
+    assetTable
   };
   const result = await runAgentTurn({
     turnId,
@@ -14971,6 +15371,7 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
       }
       return renderedTurn(deps, state, resolved);
     },
+    unresolvedLayout: (rendered) => describeUnresolvedLayout(rendered.layoutFindings),
     authorize: async ({ cycle, state, rendered, previous }) => {
       const request = requestForPass(context, { cycle, state, rendered, previous });
       const authorization = await authorizePass(
@@ -15023,7 +15424,8 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
                 startedAt,
                 completedAt: (/* @__PURE__ */ new Date()).toISOString(),
                 screenshotCount: context.screenshotCount,
-                instructionLength: input.instruction.length
+                instructionLength: input.instruction.length,
+                demand: event.result.demand
               }
             });
             allowance.remaining = settlement.balanceCredits;
@@ -15051,7 +15453,8 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
             startedAt,
             completedAt: (/* @__PURE__ */ new Date()).toISOString(),
             screenshotCount: context.screenshotCount,
-            instructionLength: input.instruction.length
+            instructionLength: input.instruction.length,
+            demand: event.result.demand
           });
         } catch (error) {
           runtime.log("mcp_agent_turn_receipt_failed", { turnKey, ...safeFailureDiagnostic(error) });
@@ -15070,6 +15473,7 @@ var init_agentTurnAdapter = __esm({
     init_agentOutcome();
     init_projectRecord();
     init_gradient();
+    init_layoutFindings();
     init_capabilities();
     init_invalidRequest();
     init_refineProjectContracts();
@@ -15102,7 +15506,16 @@ function writeErrorFrom(error) {
 }
 function localAgentTurnRuntime(bridge) {
   return {
-    plannerPass: (_userId, request, turnKey) => bridge.refinePass(request.projectId, request, turnKey),
+    plannerPass: (_userId, request, turnKey, assetTable) => bridge.refinePass(
+      request.projectId,
+      request,
+      turnKey,
+      void 0,
+      assetTable.descriptors.map(({ id }) => {
+        const { ref, label, width, height } = assetTable.sources[id];
+        return { ref, label, ...width ? { width } : {}, ...height ? { height } : {} };
+      })
+    ),
     // The receipt facts travel WITH settlement (#580): the server writes the one receipt for this
     // turn, keyed by the id the local coordinator ran under, and this machine — which holds no
     // Supabase credential — writes nothing durable at all.
@@ -15122,7 +15535,8 @@ function localAgentTurnRuntime(bridge) {
           startedAt: input.startedAt,
           completedAt: input.completedAt,
           screenshotCount: input.screenshotCount ?? 0,
-          instructionLength: input.instructionLength ?? 0
+          instructionLength: input.instructionLength ?? 0,
+          demand: input.demand ?? NOT_MEASURED_DEMAND
         }
       });
     },
@@ -15138,7 +15552,7 @@ function localAgentTurnRuntime(bridge) {
     log: (event, fields2) => logEvent("error", event, fields2)
   };
 }
-async function runLocalRefineTurn(deps, bridge, input) {
+async function runLocalRefineTurn(deps, bridge, input, runtimeOverrides) {
   try {
     const turn = await runMcpProjectAgentTurn(
       deps,
@@ -15148,7 +15562,7 @@ async function runLocalRefineTurn(deps, bridge, input) {
         ...input.project ? { project: input.project } : {},
         ...input.attachments?.length ? { attachments: input.attachments } : {}
       },
-      localAgentTurnRuntime(bridge)
+      runtimeOverrides ? { ...localAgentTurnRuntime(bridge), ...runtimeOverrides } : localAgentTurnRuntime(bridge)
     );
     return refineProjectResult(turn);
   } catch {
@@ -15159,6 +15573,7 @@ var init_localRefineTurn = __esm({
   "src/project/localRefineTurn.ts"() {
     "use strict";
     init_log();
+    init_agentUnmetActions();
     init_agentTurnAdapter();
     init_hostedBridge();
     init_refineProjectReceipt();
@@ -15307,7 +15722,7 @@ var init_projectClaimClient = __esm({
 
 // src/runtime/localDeps.ts
 import { readFile as readFile4 } from "node:fs/promises";
-function localToolDeps(token2) {
+function localToolDeps(token2, options = {}) {
   const base = {
     renderer: new StripRenderer({ serve: "static" }),
     // Token-backed cloud writes cross the same authority in the control plane. This local handler
@@ -15372,7 +15787,7 @@ function localToolDeps(token2) {
       }
     };
   }
-  const bridge = connectHostedBridge(token2);
+  const bridge = options.decorateBridge ? options.decorateBridge(connectHostedBridge(token2)) : connectHostedBridge(token2);
   const bridged = {
     ...base,
     resolveProject: (userId, projectId) => bridge.resolveProject(userId, projectId),
@@ -15413,7 +15828,7 @@ function localToolDeps(token2) {
       await bridge.close();
     }
   };
-  bridged.refineProject = (userId, input) => runLocalRefineTurn({ ...bridged, userId }, bridge, input);
+  bridged.refineProject = (userId, input) => runLocalRefineTurn({ ...bridged, userId }, bridge, input, options.emit ? { emit: options.emit } : void 0);
   return bridged;
 }
 async function pushScreens(bridge, projectId, record8, recordVersion, screenshots2) {