shotops-mcp 0.9.0 → 0.9.2

package/dist/local.js

@@ -20,9 +20,11 @@ import { URL as NodeUrl, fileURLToPath } from "node:url";
 function studioOrigin() {
   return (process.env.STUDIO_ORIGIN || "https://shotops.dev").replace(/\/+$/, "");
 }
+function authorityOrigin() {
+  return (process.env.SHOTOPS_AUTH_ORIGIN || "https://mcp.shotops.dev").replace(/\/+$/, "");
+}
 function deployTarget() {
   if (process.env.VERCEL) return "vercel";
-  if (process.env.FLY_APP_NAME) return "fly";
   return "local";
 }
 function maxInlineScreenshotBytes() {
@@ -890,13 +892,19 @@ var init_capabilities = __esm({
 });
 
 // src/authorization.ts
+function planRequiredMessage(requiredPlan) {
+  if (requiredPlan && requiredPlan !== "pro") {
+    return `This action needs the ${requiredPlan} plan \u2014 upgrade at https://shotops.dev/app.`;
+  }
+  return "This action needs an active Pro trial or Pro. Start the free trial or upgrade at https://shotops.dev/app.";
+}
 function authorizationMessage(decision) {
   if (decision.allowed) return null;
   switch (decision.reason) {
     case "authentication_required":
       return "Sign in to use this capability.";
     case "plan_required":
-      return `This action requires the ${decision.requiredPlan ?? "required"} plan.`;
+      return planRequiredMessage(decision.requiredPlan);
     case "trial_choice_required":
       return "Your Pro trial has ended. Choose Pro or Free at https://shotops.dev/app before using this action.";
     case "limit_reached":
@@ -932,7 +940,7 @@ function capabilityDenialFromError(error) {
 function capabilityDenialMessage(denial) {
   switch (denial.reason) {
     case "plan_required":
-      return `This action requires the ${denial.requiredPlan ?? "required"} plan.`;
+      return planRequiredMessage(denial.requiredPlan);
     case "trial_choice_required":
       return "Your Pro trial has ended. Choose Pro or Free at https://shotops.dev/app before using this action.";
     case "billing_unavailable":
@@ -1512,18 +1520,37 @@ ${list}${more}` : "";
   }
   return "No such project on this account." + offer;
 }
+function disclosureStatement(disclosure) {
+  return `This call moves ${disclosure.moves}, because ${disclosure.why}. It is kept for ${disclosure.retentionDays} days and then removed. What retains it: ${disclosure.retainedBy}`;
+}
 function buildIdentityInstructions(version2) {
   return `This server is ShotOps build \`${version2}\` (package version, plus the deployed commit after the \`+\` when hosted) \u2014 quote it verbatim if asked what version of ShotOps this is, and say that nothing more precise is visible from here. A project\u2019s \`schema\` and a look\u2019s version number (v70, v71 \u2026) describe the USER\u2019S saved work and are never the answer to that question.`;
 }
-var BROWSER_FIRST_ROUTE, SAVE_PROJECT_NEXT_STEP, SERVER_INSTRUCTIONS, ANONYMOUS_TOOLS;
+var BROWSER_FIRST_ROUTE, OFFER_SAVE_PROJECT_NEXT_STEP, ACCOUNT_UPLOAD_DISCLOSURE, PENDING_CLAIM_DISCLOSURE, SERVER_INSTRUCTIONS, ANONYMOUS_TOOLS;
 var init_toolContract = __esm({
   "src/toolContract.ts"() {
     "use strict";
     init_shotLookProjection();
+    init_retentionPolicy();
     BROWSER_FIRST_ROUTE = `No file transfer is needed at all: the user can sign in at https://shotops.dev, drop the screenshots into a project, set that project's reach to "Your account", and you then render it from here with render_project({ project }) and NO screenshots \u2014 the project already holds them.`;
-    SAVE_PROJECT_NEXT_STEP = {
+    OFFER_SAVE_PROJECT_NEXT_STEP = {
+      action: "offer_save_project",
       tool: "save_project",
-      reason: "These panels are images only \u2014 render_strip saved nothing, so this design will not outlive the conversation. Call save_project with the same screenshots and NO `project` argument to create a new editable ShotOps project, then give the user the openUrl it returns. Do this even if they only asked for renders or a bundle. Skip it only if they explicitly said not to save a project, or name an existing project only if they explicitly said the work belongs there."
+      projectCreated: false,
+      consent: "required",
+      reason: "No ShotOps project exists for this strip and nothing was written \u2014 these panels are images only, so the design behind them ends with the conversation. That is the correct default for a preview, not a problem to fix. OFFER a save when the user shows they want this work preserved, shared, reused or kept editable; only then call save_project with the same screenshots and NO `project` argument, and hand back the openUrl it returns. Asking for images, full-resolution panels or a bundle is not that intent, and neither is silence: if you cannot put the question to the user, return these panels with the offer standing rather than saving on their behalf. Name an existing project as `project` only when they said the work belongs there."
+    };
+    ACCOUNT_UPLOAD_DISCLOSURE = {
+      moves: "the screenshot bytes you supply, into private storage scoped to this ShotOps account",
+      why: "a render reads a stored ref instead of carrying full-resolution pixels through the conversation, and only an account-scoped ref can be re-rendered later",
+      retentionDays: retentionDays(RETENTION_POLICY.hostedAssetTtlMs),
+      retainedBy: "save_project \u2014 a saved project keeps every ref it references for as long as it references it. Nothing else retains an upload, and nothing is retained automatically."
+    };
+    PENDING_CLAIM_DISCLOSURE = {
+      moves: "the raw PNGs read from this machine, together with the project record, into private pending-claim storage on the ShotOps server",
+      why: "an unsigned local save has no account to file the project under, so the project can only reopen whole in a browser if its sources are staged alongside the record",
+      retentionDays: retentionDays(RETENTION_POLICY.pendingProjectClaimTtlMs),
+      retainedBy: "opening the returned openUrl and signing in within the window, which makes that person the owner and turns the staged copy into their project. Unclaimed, the record and the PNGs are swept."
     };
     SERVER_INSTRUCTIONS = [
       "ShotOps makes the marketing screenshots an app store listing needs. Give it the raw screen",
@@ -1585,18 +1612,17 @@ var init_toolContract = __esm({
       '   render_strip output:"urls" result as `panels` to package without re-rendering. On the LOCAL',
       "   stdio tier (no account, so no upload refs) pass panels straight off disk instead:",
       '   panels: [{ "path": "/abs/panel-01.png" }, \u2026] \u2014 the same { path } local-only door as screenshots.',
-      "4. NEW work becomes a NEW editable ShotOps project by default: call save_project WITHOUT a",
-      "   `project` argument, then give its `openUrl` to the user. A signed-in/token-backed call returns",
-      '   a projectId immediately; unsigned local stdio returns status:"pending_claim" with NO projectId,',
-      "   and the user becomes its owner by opening the link and signing in within 7 days. Do this even",
-      "   when they asked only",
-      "   for renders or a bundle \u2014 do not merely offer. Skip project creation only when the user",
-      "   explicitly says not to save/create a project. If they explicitly say the work belongs in an",
-      "   existing project, pass that project as `project` so save_project updates it, and return that",
-      "   `openUrl` instead. Never infer an update target from the most-recent project.",
+      "4. PERSISTENCE IS A SEPARATE ASK. A render creates nothing and updates nothing \u2014 the result says",
+      "   so structurally (`contract.effects.projectMutation: false`), and a project-less render also",
+      "   carries a `nextStep` whose action is `offer_save_project`: an OFFER to relay, never consent to",
+      "   act on. Call save_project only once the user has shown they want this work preserved, shared,",
+      "   reused or kept editable. Then omit `project` to create a NEW project and hand back its",
+      "   `openUrl`; pass `project` only when they named an existing one. See the lifecycle section below.",
       "5. Hosted sources and private outputs expire after the retention window unless a Project or another live",
-      "   resource retains them. After delivery, OFFER to clean up unreferenced artifacts by opaque id.",
-      "   Call delete_assets({ assetIds: [...] }) only when the user explicitly asks; referenced assets are refused.",
+      "   resource retains them. After delivery, OFFER to clean up UNREFERENCED temporary artifacts by",
+      "   opaque id. Call delete_assets({ assetIds: [...] }) only when the user explicitly asks; anything a",
+      "   Project, operation, share or preview still depends on is refused \u2014 never propose deleting an",
+      "   asset a Project references, and never present cleanup as a step that has to happen.",
       "",
       "## Preview is open; STORE-READY OUTPUT needs an active Pro trial or Pro",
       "Two different things, and the split is the same on the hosted server and on `npx shotops-mcp`:",
@@ -1605,7 +1631,7 @@ var init_toolContract = __esm({
       "including a zip composed only from panels that were already rendered \u2014 needs a signed-in account",
       "on an active Pro trial or Pro. The refusal arrives BEFORE anything is rendered, written,",
       "uploaded or charged, so a denied call costs the user nothing and leaves no half-made files.",
-      "account_status answers this in one free call: no credits, no free-preview allowance, no uploads,",
+      "account_status answers this in one free call: no cloud credits, no free-preview allowance, no uploads,",
       "no writes. Call it before starting a long full-resolution job you are not sure will be allowed,",
       "and relay its `nextStep` (sign_in, choose_plan, upgrade, retry) rather than retrying the refused",
       "call unchanged. Never guess at someone's plan and never claim a limit it did not report.",
@@ -1723,29 +1749,45 @@ var init_toolContract = __esm({
       "and heldVersion with a structured `history` denial; explicit historical renders use the latest",
       "saved Look instead. A retained Hold stays preserved and becomes active again after upgrading.",
       "",
-      // #213 — this section is ALSO carried structurally, as SAVE_PROJECT_NEXT_STEP above, which
+      // This section is ALSO carried structurally, as OFFER_SAVE_PROJECT_NEXT_STEP above, which
       // render_strip attaches to every project-less render because some clients never deliver these
       // instructions. Edit the two together: prose that says one thing while the wire says another is
       // worse than either alone.
-      "## Save every new MCP creation as an editable project (the default)",
-      "A new strip made through MCP should outlive the conversation as a real ShotOps project the user",
-      "can open + refine. After creating the design, call save_project with NO `project` argument so it",
-      "creates a NEW project. It always returns an openUrl \u2014 hand it back to the user. Authenticated",
-      "calls also return projectId; unsigned local stdio returns an explicit pending_claim with no",
-      "invented id, and opening that URL + signing in within 7 days makes the user its owner. This is",
-      "the default even when the request only mentions",
-      'renders, PNGs, or a bundle; do not wait for a separate "save it" request.',
-      "There are only two user-directed exceptions: (1) if they explicitly say not to create/save a",
-      "project, do not call save_project; (2) if they explicitly say the work belongs in an existing",
-      "project, thread that projectId/name back as `project` so save_project UPDATES it in place, then",
-      "return its openUrl. Never silently choose a recent project: no explicit target means NEW project.",
-      "save_project is FAST and never renders \u2014 it saves structure + look only. render_strip no longer",
-      "writes projects at all; emit_bundle still carries the older createProject flag for backward",
-      "compatibility, but new conversational flows should keep rendering and project writes separate.",
-      "Ordinary local render/export uploads nothing. Only an unsigned local save_project deliberately",
-      "uploads its local raw PNGs to temporary private claim storage so the claimed project reopens whole.",
+      "## The lifecycle \u2014 preview by default, persistence on request",
+      "Six steps, in order. Only the preview happens on its own; every other step needs something the",
+      "user said.",
+      "1. INSPECT when the input, the persistence or the cost is uncertain. account_status is free and",
+      "   says what this connection may do, what a preview costs here, and whether store-ready output is",
+      "   available at all. read_project says what a saved project already holds.",
+      "2. PREVIEW, and create nothing. render_strip / render_project with `preview: true` shows the design",
+      "   without writing a project, updating a project, or asking anyone for permission beyond the",
+      "   request itself. This is the default visual step and the thing to reach for first.",
+      "3. OFFER TO SAVE \u2014 only after the user expressed a PRESERVE, COLLABORATE, REUSE or CONTINUE-EDITING",
+      '   intent ("keep this", "I want to tweak it later", "send it to my designer"). save_project with NO',
+      "   `project` argument then creates a NEW project and always returns an `openUrl` to hand back; a",
+      "   signed-in or token-backed call also returns a projectId, while unsigned local stdio returns",
+      '   status:"pending_claim" with NO invented id and the user becomes owner by opening the link and',
+      "   signing in inside the claim window. If they said the work belongs in an EXISTING project, pass",
+      "   it as `project` and save_project updates that one in place. Never infer an update target from",
+      "   the most recently edited project, and never read a render, a bundle request or silence as",
+      "   agreement to save. If your client cannot put the question to the user at all, deliver the",
+      "   result and the offer \u2014 do not save for them.",
+      "4. DISCLOSE BEFORE BYTES MOVE. Ordinary local rendering and exporting upload nothing. Three calls",
+      "   do move bytes into ShotOps storage \u2014 import_screenshot and request_screenshot_upload on the",
+      "   hosted server, and an UNSIGNED local save_project, which stages its raw local PNGs in private",
+      "   claim storage so the claimed project reopens whole. Before each, say what moves, why, how long",
+      "   it is kept and the explicit action that retains it. Each of those results carries the same four",
+      "   facts as a `disclosure` block; relay it rather than paraphrasing a retention window.",
+      "5. PRODUCE FINAL only once entitlement and readiness allow it, carrying back the exact waiver",
+      "   receipts the server handed you. Refusals arrive before any charge, any pixel and any file.",
+      "6. DELIVER, then OFFER cleanup of unreferenced temporary assets only. Never propose deleting",
+      "   something a project still points at, and never make cleanup automatic.",
+      "save_project is FAST and never renders \u2014 structure + look only. render_strip does not write",
+      "projects at all. emit_bundle still accepts the older `createProject` flag for backward",
+      "compatibility: use it ONLY when the user explicitly asked for both the bundle and a saved project,",
+      "and never infer it from a bundle request.",
       "",
-      "## IMPORTANT \u2014 make the saved strip re-openable",
+      "## When you DO save, make the strip re-openable",
       "The record itself never stores screenshot BYTES (zero-custody). What it can store is a MANIFEST:",
       "when the screenshots you rendered with were account-scoped refs (from request_screenshot_upload",
       "or import_screenshot), saving the project records where those uploads live, and the user opens it",
@@ -4564,7 +4606,7 @@ var init_resultContract = __esm({
       "What this call DID to the world, independent of what it returned. Every flag is stated on every result, false included: an absent flag would be indistinguishable from an effect nobody thought to declare."
     );
     costSchema = z3.object({
-      unit: z3.literal("credit").describe("Public credits \u2014 the same unit every ShotOps surface quotes."),
+      unit: z3.literal("credit").describe("Public cloud credits \u2014 the same unit every ShotOps surface quotes."),
       model: z3.enum(["metered", "anonymous_allowance", "unmetered"]).describe(
         "How this connection pays. `unmetered` is local stdio, which renders on the caller\u2019s own machine; `anonymous_allowance` is the unsigned hosted taste."
       ),
@@ -4573,7 +4615,7 @@ var init_resultContract = __esm({
       reserved: z3.number().optional().describe("Held against the wallet for the duration of the call (#666)."),
       released: z3.number().optional().describe("Given back \u2014 an unused reservation or a refund after a post-charge failure (#666)."),
       settled: z3.number().optional().describe("Actually taken. Absent when nothing was charged."),
-      balanceAfter: z3.number().optional().describe("The wallet\u2019s public credit balance once this call settled."),
+      balanceAfter: z3.number().optional().describe("The wallet\u2019s public cloud credit balance once this call settled."),
       refillAt: z3.string().optional().describe("ISO 8601. When the wallet is next topped up; absent when none is scheduled.")
     }).passthrough();
     artifactSchema = z3.object({
@@ -4736,7 +4778,7 @@ var init_resultContract = __esm({
 
 // src/outputSchemas.ts
 import { z as z4 } from "zod";
-var projectSummary, storedAssetOutput, panelDeliveryOutput, panelOutput, lookHistoryAccess, noteField, creditsField, layoutFindingOutput, layoutAdvisoryOutput, contractField, operationStateOutputSchema, durableRenderFinalOutputSchema, durableBundleFinalOutputSchema, renderStripOutputSchema, optionalShape, operationStateShape, renderStripToolOutputSchema, emitBundleOutputSchema, emitBundleToolOutputSchema, saveProjectOutputSchema, layoutFieldDiff, layoutReportShape, layoutReportOutput, readLookOutputSchema, storedScreenshots, readProjectOutputSchema, agentOutcomeOutput, refineProjectOutputSchema, renderProjectOutputSchema, renderProjectToolOutputSchema, productionOperationOutputSchema, saveLookOutputSchema, holdLookOutputSchema, releaseLookOutputSchema, describeLookOutputSchema, accountCreditBalanceSchema, accountStatusOutputSchema, requestScreenshotUploadOutputSchema, importedScreenshotOutput, importScreenshotOutputSchema, deleteAssetsOutputSchema;
+var projectSummary, storedAssetOutput, panelDeliveryOutput, panelOutput, lookHistoryAccess, noteField, creditsField, layoutFindingOutput, layoutAdvisoryOutput, contractField, disclosureField, operationStateOutputSchema, durableRenderFinalOutputSchema, durableBundleFinalOutputSchema, renderStripOutputSchema, optionalShape, operationStateShape, renderStripToolOutputSchema, emitBundleOutputSchema, emitBundleToolOutputSchema, saveProjectOutputSchema, layoutFieldDiff, layoutReportShape, layoutReportOutput, readLookOutputSchema, storedScreenshots, readProjectOutputSchema, agentOutcomeOutput, refineProjectOutputSchema, renderProjectOutputSchema, renderProjectToolOutputSchema, productionOperationOutputSchema, saveLookOutputSchema, holdLookOutputSchema, releaseLookOutputSchema, describeLookOutputSchema, accountCreditBalanceSchema, accountStatusOutputSchema, requestScreenshotUploadOutputSchema, importedScreenshotOutput, importScreenshotOutputSchema, deleteAssetsOutputSchema, advertisedWithFailure, refineProjectToolOutputSchema, saveProjectToolOutputSchema, readLookToolOutputSchema, readProjectToolOutputSchema, saveLookToolOutputSchema, holdLookToolOutputSchema, releaseLookToolOutputSchema, requestScreenshotUploadToolOutputSchema, importScreenshotToolOutputSchema, deleteAssetsToolOutputSchema;
 var init_outputSchemas = __esm({
   "src/outputSchemas.ts"() {
     "use strict";
@@ -4794,6 +4836,15 @@ var init_outputSchemas = __esm({
       "What is wrong with this render\u2019s COMPOSITION, measured on the panels it just returned. ABSENT means there is nothing to report \u2014 a clean strip, or one whose captions could not be measured. Advisory: the panels are already rendered and nothing here changed a pixel."
     );
     contractField = resultEnvelopeSchema.optional();
+    disclosureField = z4.object({
+      moves: z4.string().describe("The bytes that left the caller\u2019s control, in plain words."),
+      why: z4.string().describe("What the move buys \u2014 never a restatement of the mechanism."),
+      retentionDays: z4.number().int().positive().describe("How long ShotOps keeps it without an explicit retaining action. Read from the retention policy, never typed."),
+      retainedBy: z4.string().describe("The explicit action that keeps it past that window."),
+      statement: z4.string().describe("The same four facts as one sentence, safe to relay verbatim.")
+    }).passthrough().optional().describe(
+      "Stated because this call moved caller bytes into ShotOps storage. Relay it before or with the result; do not paraphrase the retention window."
+    );
     operationStateOutputSchema = z4.object({
       ok: z4.boolean(),
       operationId: z4.string(),
@@ -4841,15 +4892,26 @@ var init_outputSchemas = __esm({
       renderMs: z4.number(),
       output: z4.enum(["inline", "urls"]),
       locale: z4.string(),
-      // #213 — the follow-up the contract has always required, carried in the output because that is
-      // the one channel every client delivers (SERVER_INSTRUCTIONS are truncated or dropped by some).
-      // Declared rather than left to .passthrough() so an agent reading the schema sees it exists.
+      // The OFFER a project-less render carries, in the output because that is the one channel every
+      // client delivers (SERVER_INSTRUCTIONS are truncated or dropped by some). Declared rather than
+      // left to .passthrough() so an agent reading the schema sees it exists.
+      //
+      // `action` and `consent` are what keep it an offer. This field used to be a bare
+      // `{ tool: 'save_project', reason }` whose prose told an agent to save unless the user opted
+      // out — a render request read as consent to write a durable record. It is now typed as the
+      // question it always should have been.
+      //
       // OPTIONAL for the #196 reason: a render tied to an existing project omits it, and a declared
       // output field that a legitimate response omits must never be required — the SDK validates
       // structuredContent, so that would turn a SUCCESSFUL render into a validation error.
       // renderProjectOutputSchema extends this and never emits it; optional keeps that honest.
       nextStep: z4.object({
-        tool: z4.literal("save_project"),
+        action: z4.literal("offer_save_project").describe("An offer to put to the user. Never a command, and never consent already given."),
+        tool: z4.literal("save_project").describe("The door that would persist this work, if they ask for it."),
+        projectCreated: z4.literal(false).describe("No project was created or updated by this call \u2014 the same fact as `contract.effects.projectMutation`."),
+        consent: z4.literal("required").describe(
+          "Saving needs the user\u2019s own preserve/reuse/keep-editing intent. A client that cannot ask returns this offer unresolved rather than saving."
+        ),
         reason: z4.string()
       }).optional(),
       credits: creditsField,
@@ -4911,7 +4973,14 @@ var init_outputSchemas = __esm({
       // #224 — save_project used to DROP this entirely: it destructured `{ look, style }` out of
       // resolveLook and never forwarded the note, on the one tool where a wrong composition is
       // PERSISTED rather than merely rendered.
-      note: noteField
+      note: noteField,
+      // Only on the unsigned local pending-claim path, the one save that stages raw PNGs off this
+      // machine. A signed save moves no bytes and states nothing.
+      disclosure: disclosureField,
+      // #662 — the effects of the one call in this contract whose job IS a project write:
+      // `projectMutation` is true here and false on every render, which is what makes "a render never
+      // triggers a project write" a fact an agent can test rather than a promise in prose.
+      contract: contractField
     }).passthrough();
     layoutFieldDiff = z4.object({
       is: z4.string().describe("The value this strip actually holds. `(none)` means the field is absent."),
@@ -5137,12 +5206,12 @@ var init_outputSchemas = __esm({
         model: z4.enum(["metered", "anonymous_allowance", "unmetered"]),
         previewPanel: z4.number(),
         fullResolutionPanel: z4.number()
-      }).passthrough().describe("How work is paid for here, in public credits. Every figure comes from the monetization policy."),
+      }).passthrough().describe("How work is paid for here, in public cloud credits. Every figure comes from the monetization policy."),
       failureCatalog: z4.object({ codes: z4.array(z4.string()), nextActions: z4.array(z4.string()) }).passthrough().describe("The CLOSED set of failure codes and next-actions this server can produce. Identical on both doors."),
       account: z4.object({
         credits: accountCreditBalanceSchema.optional()
       }).passthrough().describe(
-        "The account-wide wallet, named apart from a single call\u2019s debit: this is the BALANCE, while a render\u2019s `contract.cost.settled` is what that one call took. The legacy top-level `credits` key still carries the same balance for the compatibility window."
+        "The account-wide cloud credit wallet, named apart from a single call\u2019s debit: this is the BALANCE, while a render\u2019s `contract.cost.settled` is what that one call took. The legacy top-level `credits` key still carries the same balance for the compatibility window."
       )
     }).passthrough();
     requestScreenshotUploadOutputSchema = z4.object({
@@ -5157,7 +5226,8 @@ var init_outputSchemas = __esm({
           )
         }).passthrough()
       ),
-      instructions: z4.string()
+      instructions: z4.string(),
+      disclosure: disclosureField
     }).passthrough();
     importedScreenshotOutput = z4.object({
       ok: z4.boolean(),
@@ -5173,7 +5243,8 @@ var init_outputSchemas = __esm({
       ok: z4.boolean(),
       count: z4.number().int().nonnegative(),
       screenshots: z4.array(importedScreenshotOutput),
-      instructions: z4.string()
+      instructions: z4.string(),
+      disclosure: disclosureField
     }).passthrough();
     deleteAssetsOutputSchema = z4.object({
       ok: z4.boolean(),
@@ -5181,6 +5252,17 @@ var init_outputSchemas = __esm({
       deletedRefs: z4.array(z4.string()),
       message: z4.string()
     }).passthrough();
+    advertisedWithFailure = (strict) => z4.object({ ...optionalShape(strict.shape), ok: z4.boolean().optional() }).passthrough();
+    refineProjectToolOutputSchema = advertisedWithFailure(refineProjectOutputSchema);
+    saveProjectToolOutputSchema = advertisedWithFailure(saveProjectOutputSchema);
+    readLookToolOutputSchema = advertisedWithFailure(readLookOutputSchema);
+    readProjectToolOutputSchema = advertisedWithFailure(readProjectOutputSchema);
+    saveLookToolOutputSchema = advertisedWithFailure(saveLookOutputSchema);
+    holdLookToolOutputSchema = advertisedWithFailure(holdLookOutputSchema);
+    releaseLookToolOutputSchema = advertisedWithFailure(releaseLookOutputSchema);
+    requestScreenshotUploadToolOutputSchema = advertisedWithFailure(requestScreenshotUploadOutputSchema);
+    importScreenshotToolOutputSchema = advertisedWithFailure(importScreenshotOutputSchema);
+    deleteAssetsToolOutputSchema = advertisedWithFailure(deleteAssetsOutputSchema);
   }
 });
 
@@ -5278,7 +5360,7 @@ var init_schemas = __esm({
       "Render a specific saved look version of the project (implies the saved look). Omit = the project's HELD version if one is held (hold_look), else the latest saved look."
     );
     createProjectFlag = z5.boolean().optional().describe(
-      "Also save this render as an editable ShotOps project the signed-in user can open + refine (returns projectId + an openUrl). Pass an existing `project` id to update it instead of creating a new one. Full-res only \u2014 not allowed with preview:true. The record embeds no image bytes; a token-backed local save may separately upload private source refs so the project reopens with its screenshots."
+      "COMPATIBILITY INPUT: also save this render as an editable ShotOps project (returns projectId + an openUrl). Set it ONLY when the user explicitly asked for both the bundle and a saved project \u2014 never infer it from a delivery request, and prefer save_project, which is the normal persistence door. Pass an existing `project` id to update that project instead of creating a new one. Full-res only \u2014 not allowed with preview:true. The record embeds no image bytes; a token-backed local save may separately upload private source refs so the project reopens with its screenshots."
     );
     projectName = z5.string().optional().describe('Name for the created project (when createProject makes a new one). Default "ShotOps render".');
     sourceDir = z5.string().optional().describe(
@@ -5801,7 +5883,7 @@ var init_monetizationPolicy = __esm({
         failedRenewalGraceMs: 7 * 24 * 60 * 60 * 1e3
       }
     };
-    LEDGER_UNITS_PER_PUBLIC_CREDIT = 2500;
+    LEDGER_UNITS_PER_PUBLIC_CREDIT = 1250;
   }
 });
 
@@ -9294,6 +9376,9 @@ function assertOutcome(outcome) {
 async function runAgentTurn(input, ports) {
   const instruction = input.instruction.trim();
   if (!instruction) throw new Error("Agent instruction must not be empty");
+  const turnId = input.turnId;
+  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 loaded = await ports.loadProject();
   const before = loaded.state;
@@ -9311,7 +9396,7 @@ async function runAgentTurn(input, ports) {
   let terminalOutcome = null;
   let invalid = false;
   let cancelled = false;
-  await ports.emit({ type: "turn_started" });
+  await emit({ type: "turn_started" });
   try {
     rendered = await ports.renderComposed(working, 0);
   } catch {
@@ -9326,7 +9411,7 @@ async function runAgentTurn(input, ports) {
       break;
     }
     const phase = phaseFor(cycle);
-    await ports.emit({ type: "phase_changed", cycle, phase });
+    await emit({ type: "phase_changed", cycle, phase });
     let authorization;
     try {
       authorization = await ports.authorize({
@@ -9355,7 +9440,7 @@ async function runAgentTurn(input, ports) {
       createdAt: now()
     };
     passes.push(pass);
-    await ports.emit({ type: "pass_completed", cycle, pass });
+    await emit({ type: "pass_completed", cycle, pass });
     if (input.cancelled?.()) {
       cancelled = true;
       break;
@@ -9399,7 +9484,7 @@ async function runAgentTurn(input, ports) {
       };
       selected = checkpoint;
       if (checkpoint.changed.length > 0 && (!best || checkpoint.quality >= best.quality)) best = checkpoint;
-      await ports.emit({
+      await emit({
         type: "draft_applied",
         cycle,
         checkpointId: checkpoint.id,
@@ -9431,7 +9516,7 @@ async function runAgentTurn(input, ports) {
   if (terminalOutcome || invalid) best = null;
   selected = best;
   const selectedState = selected?.state ?? before;
-  await ports.emit({ type: "draft_selected", checkpointId: selected?.id ?? 0, state: selectedState });
+  await emit({ type: "draft_selected", checkpointId: selected?.id ?? 0, state: selectedState });
   let outcome = terminalOutcome ?? applicationOutcome({
     changed: selected?.changed ?? [],
     invalid,
@@ -9440,7 +9525,7 @@ async function runAgentTurn(input, ports) {
   let committed = false;
   let commitData;
   if (outcome.status === "applied" || outcome.status === "applied_with_remaining") {
-    await ports.emit({ type: "commit_started", outcome });
+    await emit({ type: "commit_started", outcome });
     const commit = await ports.commit({
       before,
       after: selectedState,
@@ -9451,13 +9536,13 @@ async function runAgentTurn(input, ports) {
     if (commit.ok) {
       committed = true;
       commitData = commit.data;
-      await ports.emit({ type: "commit_succeeded", data: commit.data, outcome });
+      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.");
-      await ports.emit({ type: "draft_rolled_back", outcome });
+      await emit({ type: "draft_rolled_back", outcome });
     }
   } else {
-    await ports.emit({ type: "draft_rolled_back", outcome });
+    await emit({ type: "draft_rolled_back", outcome });
   }
   const changed = committed ? selected?.changed ?? [] : [];
   const selectedStale = staleCaptionLocaleCount(selectedState.staleCaptionTranslations);
@@ -9480,6 +9565,7 @@ async function runAgentTurn(input, ports) {
     usage: aggregateUsage(passes)
   };
   const result = {
+    turnId,
     outcome,
     legacy,
     before,
@@ -9489,7 +9575,7 @@ async function runAgentTurn(input, ports) {
     ...commitData === void 0 ? {} : { commitData }
   };
   assertOutcome(outcome);
-  await ports.emit({ type: "turn_completed", result });
+  await emit({ type: "turn_completed", result });
   void input.requestedCycle;
   return result;
 }
@@ -9535,6 +9621,9 @@ var init_agentTurnConformance = __esm({
     };
     AGENT_TURN_CONFORMANCE_FIXTURE = {
       input: {
+        // A uuid, because every surface's receipt keys on this value and the receipt table's primary
+        // key is one. The fixture is what a surface adapter replays, so it carries a real-shaped id.
+        turnId: "4f4b2f4a-4a7b-4f31-8e21-2c1c4a9b6d10",
         instruction: "Give the phone more depth",
         focus: { kind: "device", frameId: "p1", deviceId: "s1", label: "Frame 1 \xB7 home.png" }
       },
@@ -10082,6 +10171,12 @@ function backgroundViewport(value, label) {
   }
   return { panelIndex: Number(row.panelIndex), panelCount: Number(row.panelCount) };
 }
+function textList(value, label, allowEmpty = false) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
+    throw new ProductionWorkerRequestError(`${label} must be ${allowEmpty ? "an" : "a non-empty"} array`);
+  }
+  return value.map((entry, index) => text(entry, `${label}[${index}]`));
+}
 function uniqueTexts(value, label, allowEmpty = false) {
   if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
     throw new ProductionWorkerRequestError(`${label} must be ${allowEmpty ? "an" : "a non-empty"} array`);
@@ -10102,7 +10197,10 @@ function panelRecipe(value, index, allowEmptyScreenshots) {
   const viewport = backgroundViewport(row.backgroundViewport, `panels[${index}].backgroundViewport`);
   return {
     key: text(row.key, `panels[${index}].key`),
-    screenshotAssetIds: uniqueTexts(
+    // A panel is a COMPOSITION, not a set of images: positions may repeat the same picture, and
+    // `loadAssets` already dedupes ids into a Map before resolving bytes. Uniqueness here rejected
+    // legal input — `uniqueTexts` belongs on `bundle.locales`, where a repeat means something.
+    screenshotAssetIds: textList(
       row.screenshotAssetIds,
       `panels[${index}].screenshotAssetIds`,
       allowEmptyScreenshots
@@ -10312,7 +10410,7 @@ async function startDurableProduction(deps, input) {
       return errorResult("That idempotency key already belongs to a different production request.", "idempotency_conflict");
     }
     if (error instanceof ProductionReservationInsufficientCreditsError) {
-      return errorResult("There are not enough credits to reserve this production render.", "quota_exhausted", {
+      return errorResult("There are not enough cloud credits to reserve this production render.", "quota_exhausted", {
         required: publicCreditsForLedgerUnits(error.required),
         available: publicCreditsForLedgerUnits(error.availability.available)
       });
@@ -10375,7 +10473,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "shotops-mcp",
-      version: "0.9.0",
+      version: "0.9.2",
       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.",
@@ -10867,7 +10965,7 @@ async function renderStrip(deps, args, scope, signal) {
         locale: locale2,
         ...screenshotLocales.length > 0 ? { screenshotLocales } : {},
         ...note ? { note } : {},
-        ...args.project ? {} : { nextStep: SAVE_PROJECT_NEXT_STEP },
+        ...args.project ? {} : { nextStep: OFFER_SAVE_PROJECT_NEXT_STEP },
         resolvedInput: resolvedInputContract(snapshot),
         readiness: readinessContract(preReady.report)
       }
@@ -10943,15 +11041,16 @@ async function renderStrip(deps, args, scope, signal) {
     // #563 — the composition's own verdict, ADDITIVE: absent on a clean render, so a response with
     // nothing to say keeps exactly the key set it had before.
     ...result.layout ? { layout: result.layout } : {},
-    // #213 — tell the model, in the output, to turn this render into a real project. The prose
-    // contract already requires it; this is the copy a client cannot drop (toolContract.ts).
+    // The OFFER, in the output, because a client may never have received the prose contract
+    // (toolContract.ts owns the wording). It states that no project exists and names the door; it
+    // does not tell an agent to walk through it, and `consent: "required"` says so on the wire.
     //
     // Only when the render was NOT tied to a project. On render_strip, `project` names a LOOK
     // SOURCE, not a save target — so a caller who already has a project in play must not be nudged
     // into minting a second one, and telling them to UPDATE it would be wrong too (they asked to
     // render with its styling, not to file work under it). That case stays with the prose, which
     // handles it correctly: "Never infer an update target from the most-recent project."
-    ...args.project ? {} : { nextStep: SAVE_PROJECT_NEXT_STEP },
+    ...args.project ? {} : { nextStep: OFFER_SAVE_PROJECT_NEXT_STEP },
     // #662 — the versioned result envelope. Additive: every field above is unchanged, and an old
     // client that has never heard of `contract` sees exactly the payload it saw yesterday.
     contract: successContract(deps, {
@@ -13047,12 +13146,14 @@ async function handleImportScreenshot(deps, args) {
     return errorResult(results.map((r) => r.error).filter(Boolean).join("\n\n"));
   }
   const locale2 = args.locale?.trim() || void 0;
+  const stored = imported.some((result) => typeof result.ref === "string" && result.ref.length > 0);
   return textResult({
     ok: imported.length === results.length,
     count: imported.length,
     screenshots: results,
     ...locale2 ? { locale: locale2 } : {},
-    instructions: instructionsFor(results)
+    ...stored ? { disclosure: { ...ACCOUNT_UPLOAD_DISCLOSURE, statement: disclosureStatement(ACCOUNT_UPLOAD_DISCLOSURE) } } : {},
+    instructions: instructionsFor(results) + (stored ? ` ${disclosureStatement(ACCOUNT_UPLOAD_DISCLOSURE)}` : "")
   });
 }
 var init_toolsImport = __esm({
@@ -13084,7 +13185,11 @@ async function handleRequestScreenshotUpload(deps, args) {
     slots: slots.map(({ assetId: _assetId, ...slot2 }) => ({ ...slot2, variant })),
     ...locale2 ? { locale: locale2 } : {},
     ...family ? { family } : {},
-    instructions: 'PUT each screenshot\'s raw PNG bytes to its uploadUrl, e.g.: curl -T screenshot.png "$UPLOAD_URL" \u2014 then pass { "ref": "THE_MATCHING_REF" } as that screenshot\'s entry in render_strip/emit_bundle\'s `screenshots` array. If you passed `names`, that ref already carries its filename \u2014 no need to also set `name` on the screenshot entry. Unretained uploads expire after 7 days; saving them in a Project retains them while referenced.' + (locale2 ? ` For render_strip/emit_bundle, place each ref under the matching per-locale key, e.g. { "locales": { "${locale2}": { "ref": "THE_REF" } } }.` : "") + (locale2 || family ? " For render_project, pass each slot's `variant` through with its ref so that exact device-family + locale cell overrides the project instead of its base screenshot." : "")
+    // Minting a slot is the moment to say where the bytes are about to go, not after they are
+    // there. The window is read from the retention policy — typing "7 days" here is how two
+    // surfaces end up promising different weeks.
+    disclosure: { ...ACCOUNT_UPLOAD_DISCLOSURE, statement: disclosureStatement(ACCOUNT_UPLOAD_DISCLOSURE) },
+    instructions: `PUT each screenshot's raw PNG bytes to its uploadUrl, e.g.: curl -T screenshot.png "$UPLOAD_URL" \u2014 then pass { "ref": "THE_MATCHING_REF" } as that screenshot's entry in render_strip/emit_bundle's \`screenshots\` array. If you passed \`names\`, that ref already carries its filename \u2014 no need to also set \`name\` on the screenshot entry. ${disclosureStatement(ACCOUNT_UPLOAD_DISCLOSURE)}` + (locale2 ? ` For render_strip/emit_bundle, place each ref under the matching per-locale key, e.g. { "locales": { "${locale2}": { "ref": "THE_REF" } } }.` : "") + (locale2 || family ? " For render_project, pass each slot's `variant` through with its ref so that exact device-family + locale cell overrides the project instead of its base screenshot." : "")
   });
 }
 async function handleDeleteAssets(deps, args) {
@@ -13118,7 +13223,7 @@ async function handleDeleteAssets(deps, args) {
       deletedCount: deletedAssetIds.length,
       deletedAssetIds,
       notFoundAssetIds: results.filter((result) => result.outcome === "not_found").map((result) => result.requestedAssetId),
-      message: "Deleted every unreferenced owned asset. Missing or already-deleted assets are idempotent; live dependencies are never removed."
+      message: "Deleted every unreferenced owned asset. Missing or already-deleted assets are idempotent; live dependencies are never removed. An asset a Project, operation, share or preview still points at is refused rather than removed, and is never worth proposing for cleanup."
     });
   } catch (err) {
     return errorResult(err.message);
@@ -13128,6 +13233,7 @@ var init_toolsUploads = __esm({
   "src/toolsUploads.ts"() {
     "use strict";
     init_tools();
+    init_toolContract();
     init_screenVariants();
   }
 });
@@ -13343,7 +13449,16 @@ async function handleSaveProject(deps, args) {
       locale: locale2,
       ...outputDevices.length > 0 ? { outputs: outputDevices.map((d) => d.id) } : {},
       ...note ? { note } : {},
-      message: `Project staged as a private pending claim \u2014 open ${p.openUrl} and sign in within 7 days to become its owner. Always give this openUrl to the user; no projectId exists until the claim is completed.`
+      // The one local path that moves bytes off this machine. Stated with the result, from the
+      // retention policy's own number, rather than left for the user to discover when the claim
+      // window closes over their staged PNGs.
+      disclosure: { ...PENDING_CLAIM_DISCLOSURE, statement: disclosureStatement(PENDING_CLAIM_DISCLOSURE) },
+      contract: successContract(deps, {
+        tool: "save_project",
+        kind: "mutate",
+        effects: { projectMutation: true, upload: true, retainedStorage: true }
+      }),
+      message: `Project staged as a private pending claim \u2014 open ${p.openUrl} and sign in within ${PENDING_CLAIM_DISCLOSURE.retentionDays} days to become its owner. Always give this openUrl to the user; no projectId exists until the claim is completed. ` + disclosureStatement(PENDING_CLAIM_DISCLOSURE)
     });
   }
   return textResult({
@@ -13357,6 +13472,16 @@ async function handleSaveProject(deps, args) {
     // byte-identical to before.
     ...outputDevices.length > 0 ? { outputs: outputDevices.map((d) => d.id) } : {},
     ...note ? { note } : {},
+    // #662 — this is the ONE tool in the contract whose job is a project write, and the envelope
+    // says so: `projectMutation: true` here, false on every render. That pair is what makes
+    // "a render never creates a project on its own" checkable rather than merely promised.
+    // Nothing is uploaded on this path: the record is structure + look, and the refs it points at
+    // were already in storage before this call.
+    contract: successContract(deps, {
+      tool: "save_project",
+      kind: "mutate",
+      effects: { projectMutation: true, retainedStorage: true }
+    }),
     message: `Saved as an editable ShotOps project \u2014 open it at ${p.openUrl} (sign in as the same account). Thread this projectId back on later renders to update it in place.`
   });
 }
@@ -13497,17 +13622,15 @@ var init_toolsProject = __esm({
 });
 
 // src/refineProjectReceipt.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
-function mintTurnId() {
-  return `turn_${randomUUID3()}`;
-}
 function failure(error, message) {
   return { ok: false, error, message };
 }
-function refineProjectReceipt(turnId, turn) {
+function refineProjectReceipt(turn) {
   return {
     ok: true,
-    turnId,
+    // The id the ADAPTER minted for this turn (#580), never one a caller supplied and never one a
+    // door invented alongside it: the receipt row and this line carry the same identity.
+    turnId: turn.turnKey,
     projectId: turn.projectId,
     outcome: turn.outcome,
     changed: [...turn.outcome.changed],
@@ -13519,11 +13642,11 @@ function refineProjectReceipt(turnId, turn) {
     allowance: turn.allowance
   };
 }
-function refineProjectResult(turnId, turn) {
+function refineProjectResult(turn) {
   if ("error" in turn) {
     return failure(turn.error, turn.message);
   }
-  return refineProjectReceipt(turnId, turn);
+  return refineProjectReceipt(turn);
 }
 function refineProjectUnavailable(message) {
   return failure("service_unavailable", message);
@@ -13693,7 +13816,7 @@ function previewUsage(deps, snapshot) {
 }
 function statusMessage(deps, snapshot, step) {
   if (step === "none") {
-    return "This connection can produce store-ready output: full-resolution render_strip and render_project, and every emit_bundle form." + (isLocal(deps) ? " Local rendering spends no credits." : "");
+    return "This connection can produce store-ready output: full-resolution render_strip and render_project, and every emit_bundle form." + (isLocal(deps) ? " Local rendering spends no cloud credits." : "");
   }
   if (step === "sign_in" && !snapshot.authenticated && deps.anonymous) {
     return `This connection is not signed in. It can import screenshots and render up to ${ANONYMOUS.attempts} preview strips of up to ${ANONYMOUS.maxPanels} panels each per ${Math.round(ANONYMOUS.windowSeconds / 86400)} days. ` + productionDenialMessage(snapshot.productionExport, deps);
@@ -13904,7 +14027,7 @@ async function handleReadLook(deps, args) {
     return textResult({
       saved: false,
       project: { id: project2.id, name: project2.name },
-      message: `No saved look on project "${project2.name}". Style a strip in ShotOps and use the Edited chip \u2192 Save this version, or compose one here with describe_look + save_look.`
+      message: `No saved look on project "${project2.name}". Style a strip in ShotOps and use the Save version button on the stage, or compose one here with describe_look + save_look.`
     });
   }
   const layout = deriveLayoutReport(saved.look);
@@ -14610,7 +14733,7 @@ function registerTools(server, deps) {
     "render_strip",
     {
       title: "Render App Store screenshots",
-      description: 'Make the store screenshots: raw app screen captures in, finished marketing panels out. Each screenshot is composited into a styled 3D device mockup, laid out as an App Store screenshot strip with the headlines you pass, and returned as per-panel PNGs at the App Store panel size `panelPresetId` names. This is the tool for a strip built from screenshots you have in hand; to reproduce one a designer already saved, use render_project. In ChatGPT, call import_screenshot first and pass the returned refs in the preferred flat form: { "screenshots": [{ "ref": "\u2026" }] } \u2014 each flat entry is one panel, and nested slots only when ONE panel should hold several phones. Art-direct it with `style`/`look` or a project\'s saved look, iterate with a low-res `preview` at a quarter the render cost, and take results `inline` or as `urls` for large payloads. Screenshots can vary per store locale via { "locales": \u2026 } entries \u2014 `locale` picks which variant renders (missing variants fall back to en-US). For real, full-resolution screenshots call request_screenshot_upload first \u2014 inline base64 is for small payloads only. CALL describe_look FIRST when nobody has said how the strip should look \u2014 it returns the five palette presets, the three layout templates and every styling field with its default, and guessing a colour scheme out of 30 raw fields is how strips end up looking improvised. PICK `style.layout` FROM THE LONGEST HEADLINE IN THE SET, once, before anything else: "standard" reserves 2 lines (~36 characters) with the whole device under them, "bleed" reserves 4 (~72) with the device running off the bottom edge, "top-bleed" inverts that. The text region is RESERVED, NOT FITTED \u2014 held at full size whether or not the headline fills it, because a fixed reservation is the only thing that makes every device in a swiped SET land on the same line. Do not close a gap by shrinking vOffset on the short panels, and never assemble a composition out of raw phoneHeight/vOffset numbers: pick a layout, then override one field if you must (the template expands first, your field wins). Past the reservation the caption band grows down INTO the phone \u2014 the failure to avoid. THE RESPONSE ANSWERS BACK: an optional `layout` block names every caption sitting on a device, every caption collision and every device pair overlapping without reading as composed, by frame number and depth. When the repair is deterministic it also carries `layout.correctedLook` \u2014 pass that straight back as `look` to re-render clean. No `layout` key means the composition measured clean. Read it before you show the panels. This tool ONLY renders images: it never creates or updates a project (use save_project for that) and no store credential is involved.',
+      description: 'Make the store screenshots: raw app screen captures in, finished marketing panels out. Each screenshot is composited into a styled 3D device mockup, laid out as an App Store screenshot strip with the headlines you pass, and returned as per-panel PNGs at the App Store panel size `panelPresetId` names. This is the tool for a strip built from screenshots you have in hand; to reproduce one a designer already saved, use render_project. In ChatGPT, call import_screenshot first and pass the returned refs in the preferred flat form: { "screenshots": [{ "ref": "\u2026" }] } \u2014 each flat entry is one panel, and nested slots only when ONE panel should hold several phones. Art-direct it with `style`/`look` or a project\'s saved look, iterate with a low-res `preview` at a quarter the render cost, and take results `inline` or as `urls` for large payloads. Screenshots can vary per store locale via { "locales": \u2026 } entries \u2014 `locale` picks which variant renders (missing variants fall back to en-US). For real, full-resolution screenshots call request_screenshot_upload first \u2014 inline base64 is for small payloads only. CALL describe_look FIRST when nobody has said how the strip should look \u2014 it returns the five palette presets, the three layout templates and every styling field with its default, and guessing a colour scheme out of 30 raw fields is how strips end up looking improvised. PICK `style.layout` FROM THE LONGEST HEADLINE IN THE SET, once, before anything else: "standard" reserves 2 lines (~36 characters) with the whole device under them, "bleed" reserves 4 (~72) with the device running off the bottom edge, "top-bleed" inverts that. The text region is RESERVED, NOT FITTED \u2014 held at full size whether or not the headline fills it, because a fixed reservation is the only thing that makes every device in a swiped SET land on the same line. Do not close a gap by shrinking vOffset on the short panels, and never assemble a composition out of raw phoneHeight/vOffset numbers: pick a layout, then override one field if you must (the template expands first, your field wins). Past the reservation the caption band grows down INTO the phone \u2014 the failure to avoid. THE RESPONSE ANSWERS BACK: an optional `layout` block names every caption sitting on a device, every caption collision and every device pair overlapping without reading as composed, by frame number and depth. When the repair is deterministic it also carries `layout.correctedLook` \u2014 pass that straight back as `look` to re-render clean. No `layout` key means the composition measured clean. Read it before you show the panels. This tool ONLY renders images: it never creates or updates a project, and the result says so \u2014 `contract.effects.projectMutation` is false on every render. A render with no `project` also carries a `nextStep` with action `offer_save_project`, which states that no project exists and names save_project as the door. That is an OFFER to put to the user, never consent already given: save only after they show they want this work preserved, shared, reused or kept editable, and if you cannot ask them, return the panels with the offer standing. No store credential is involved.',
       inputSchema: renderStripAdvertisedShape,
       outputSchema: renderStripToolOutputSchema,
       // ADDITIVE, not destructive: this can mint private generated assets but cannot change a
@@ -14631,7 +14754,7 @@ function registerTools(server, deps) {
     "emit_bundle",
     {
       title: "Export fastlane bundle",
-      description: 'Deliver the finished store screenshots as one file the user can actually upload: a `fastlane deliver`-ready zip holding the screenshots, a pre-filled Deliverfile that is screenshots-only and never submits, and a README. Three ways in, same zip out \u2014 render the strip here from `screenshots`; re-zip pre-rendered `panels` refs from a prior render_strip `output: "urls"` call (no re-render, near-instant); or name a saved `project` alone and it packages the screenshots that project already holds, with nothing attached to this conversation. `locales: [...]` emits ONE localized bundle with a fastlane/screenshots/<locale>/ folder per language, so every language uploads in a single fastlane run \u2014 pair it with per-locale { "locales": \u2026 } screenshot/panel entries, or with a `project`, which supplies each locale\'s own caption words. Returns the zip `inline` or as a `url` for large payloads, and can mint a 14-day share link to a landing page. YOU upload it with your own fastlane: this server never touches an Apple or store credential, never creates an App Store version, and never submits for review.',
+      description: 'Deliver the finished store screenshots as one file the user can actually upload: a `fastlane deliver`-ready zip holding the screenshots, a pre-filled Deliverfile that is screenshots-only and never submits, and a README. Three ways in, same zip out \u2014 render the strip here from `screenshots`; re-zip pre-rendered `panels` refs from a prior render_strip `output: "urls"` call (no re-render, near-instant); or name a saved `project` alone and it packages the screenshots that project already holds, with nothing attached to this conversation. `locales: [...]` emits ONE localized bundle with a fastlane/screenshots/<locale>/ folder per language, so every language uploads in a single fastlane run \u2014 pair it with per-locale { "locales": \u2026 } screenshot/panel entries, or with a `project`, which supplies each locale\'s own caption words. Returns the zip `inline` or as a `url` for large payloads, and can mint a 14-day share link to a landing page. Bundling is not saving: `createProject` is a compatibility input kept for older callers, so set it only when the user explicitly asked for BOTH a bundle and a saved project \u2014 never infer it from a delivery request, and use save_project for an ordinary save. YOU upload the zip with your own fastlane: this server never touches an Apple or store credential, never creates an App Store version, and never submits for review.',
       inputSchema: emitBundleAdvertisedShape,
       outputSchema: emitBundleToolOutputSchema,
       annotations: OPEN_WORLD_DESTRUCTIVE_WRITE,
@@ -14652,9 +14775,9 @@ function registerTools(server, deps) {
     "save_project",
     {
       title: "Save as editable project",
-      description: "Let the user keep the strip: save it as an editable ShotOps project they can open in the web app, refine by hand, and have re-rendered later by render_project. Returns an openUrl to hand back and, when already authenticated, a projectId. Unsigned local stdio instead returns an explicit seven-day pending claim; the user owns it after opening the URL and signing in. No panel PNGs are returned. Do this when the design should outlive the conversation, not just when they want the images. Fast, and it does NOT render: it builds a byte-free structure + look record, so no panel bytes are returned and it never hits the render timeout. Unsigned local save deliberately uploads the raw local PNGs to temporary private claim storage; ordinary local render/export never uploads. `outputs` names the device sizes the project targets; an existing `project` id updates that project in place, omitting it creates a new one. For new MCP-created work this is the default final persistence step: omit `project` to create a new one and give the returned openUrl to the user. Skip it only when the user explicitly says not to create/save a project; pass `project` only when they explicitly say the work belongs in that existing project.",
+      description: "Let the user keep the strip: save it as an editable ShotOps project they can open in the web app, refine by hand, and have re-rendered later by render_project. Returns an openUrl to hand back and, when already authenticated, a projectId. Unsigned local stdio instead returns an explicit pending claim; the user owns it after opening the URL and signing in. No panel PNGs are returned. Fast, and it does NOT render: it builds a byte-free structure + look record, so no panel bytes are returned and it never hits the render timeout. `outputs` names the device sizes the project targets; an existing `project` id updates that project in place, omitting it creates a new one. CALL IT WHEN THE USER ASKS FOR PERSISTENCE, not as the closing step of every job: this is the door for someone who said they want to keep, share, reuse or keep editing the work. A request for images, full-resolution panels or a bundle is not that, and neither is silence \u2014 a render already told them nothing was saved and offered this call. Pass `project` only when they named an existing project as the target; never infer one from the most recently edited. An UNSIGNED local save is the one local path that moves bytes: it stages the raw PNGs in private claim storage so the claimed project reopens whole, and its result carries a `disclosure` block naming what moved, why, how long it is kept and what retains it. Ordinary local render/export never uploads.",
       inputSchema: saveProjectAdvertisedShape,
-      outputSchema: saveProjectOutputSchema,
+      outputSchema: saveProjectToolOutputSchema,
       annotations: DESTRUCTIVE_WRITE,
       _meta: toolMeta(deps, "save_project", "Saving ShotOps project\u2026", "ShotOps project saved")
     },
@@ -14666,7 +14789,7 @@ function registerTools(server, deps) {
       title: "Read saved look",
       description: "Match a design the user already approved instead of inventing a new one: returns the saved ShotOps look on a project \u2014 the device, background and caption styling a human tuned in the web app \u2014 so the next render comes out looking like theirs. Styling only: no screenshots, no caption words, no credentials. Comes with the latest version, the held version (if any) and the full `versions` history. Feed the returned look back into render_strip/emit_bundle as `look`, or just pass `useSavedLook: true`; render an older entry with `version`, or make one the default with hold_look.",
       inputSchema: readLookShape,
-      outputSchema: readLookOutputSchema,
+      outputSchema: readLookToolOutputSchema,
       annotations: READ_ONLY,
       _meta: toolMeta(deps, "read_look", "Reading saved look\u2026", "Saved look read")
     },
@@ -14678,7 +14801,7 @@ function registerTools(server, deps) {
       title: "Read full project",
       description: 'Find out what the designer changed in a strip: returns a project\'s FULL current state \u2014 the frame order they settled on (panels), the caption words they typed for each locale (captionText), the locale list, and the styling \u2014 as an opaque ProjectFile, not just the look. To answer a recurring "any updates?", remember the returned `updatedAt` and re-read later; a newer value means the strip was edited since. It ALSO answers whether the project already holds its own screenshots: `screenshots.available` true means render_project can render it with NO `screenshots` argument and nothing attached \u2014 check that before concluding you need the files. Read-only, never returns screenshot bytes, no store credential.',
       inputSchema: readProjectShape,
-      outputSchema: readProjectOutputSchema,
+      outputSchema: readProjectToolOutputSchema,
       annotations: READ_ONLY,
       _meta: toolMeta(deps, "read_project", "Reading ShotOps project\u2026", "ShotOps project read")
     },
@@ -14713,7 +14836,7 @@ function registerTools(server, deps) {
       title: "Refine a saved project",
       description: "Edit an existing ShotOps project conversationally through one bounded Agent turn. Pass the project id or exact name, the requested change, and optionally the selected frame, device, or caption as focus. A supported request commits exactly once and returns the actual committed diff. Ambiguity, missing input, unsupported intent, a concurrent edit, or a failed pass returns its own typed outcome with no partial project saved. This changes the saved project but returns no panel pixels; call render_project afterwards to see or export the result.",
       inputSchema: refineProjectShape,
-      outputSchema: refineProjectOutputSchema,
+      outputSchema: refineProjectToolOutputSchema,
       annotations: DESTRUCTIVE_WRITE,
       _meta: toolMeta(deps, "refine_project", "Refining ShotOps project\u2026", "ShotOps project refined")
     },
@@ -14725,7 +14848,7 @@ function registerTools(server, deps) {
       title: "Save look",
       description: "Make a design the user liked reusable: persists a composed ShotOps look (styling only) on a project as a new version, so their next strip \u2014 rendered here or opened in the web app \u2014 starts from the design they just approved instead of a default. Offer it once they are happy with how a strip looks. Use describe_look for the field catalog; caption words are never stored, so pass those per render. No store credential is involved.",
       inputSchema: saveLookAdvertisedShape,
-      outputSchema: saveLookOutputSchema,
+      outputSchema: saveLookToolOutputSchema,
       annotations: ADDITIVE_WRITE,
       _meta: toolMeta(deps, "save_look", "Saving ShotOps look\u2026", "ShotOps look saved")
     },
@@ -14737,7 +14860,7 @@ function registerTools(server, deps) {
       title: "Hold a look version",
       description: "Freeze which design gets rendered: pin one saved look version as this project's DEFAULT, so a designer can keep experimenting and saving newer versions without changing what agents deliver. The version must already exist (see read_look `versions`). render_strip/emit_bundle with `useSavedLook: true` then render the held one. release_look goes back to Follow latest. No credential.",
       inputSchema: holdLookShape,
-      outputSchema: holdLookOutputSchema,
+      outputSchema: holdLookToolOutputSchema,
       annotations: IDEMPOTENT_WRITE,
       _meta: toolMeta(deps, "hold_look", "Holding look version\u2026", "Look version held")
     },
@@ -14749,7 +14872,7 @@ function registerTools(server, deps) {
       title: "Release the held look",
       description: "Go back to rendering the newest design: clears a project\u2019s held version (undo hold_look), so agents Follow latest and pick up whatever the designer saved most recently. No-op if nothing was held. No store credential.",
       inputSchema: releaseLookShape,
-      outputSchema: releaseLookOutputSchema,
+      outputSchema: releaseLookToolOutputSchema,
       annotations: IDEMPOTENT_WRITE,
       _meta: toolMeta(deps, "release_look", "Releasing look version\u2026", "Look version released")
     },
@@ -14771,9 +14894,9 @@ function registerTools(server, deps) {
     "request_screenshot_upload",
     {
       title: "Upload full-size screenshots",
-      description: "Get screenshots that live only on the USER's own machine into a render, at full resolution and without their bytes ever transiting this conversation. It mints signed upload URLs you (or the user's shell) PUT each raw PNG to, and hands back a `ref` per slot to pass into render_strip/emit_bundle. Use it in non-ChatGPT MCP clients and automation, and instead of inline base64 for any real full-resolution screenshot. In ChatGPT, attachments go through import_screenshot instead \u2014 and a user with a ShotOps account can skip file transfer entirely by dropping the screenshots into a project and calling render_project. Uploading one batch per store locale? Tag each batch with `locale` (echoed back for your bookkeeping).",
+      description: "Get screenshots that live only on the USER's own machine into a render, at full resolution and without their bytes ever transiting this conversation. It mints signed upload URLs you (or the user's shell) PUT each raw PNG to, and hands back a `ref` per slot to pass into render_strip/emit_bundle. Use it in non-ChatGPT MCP clients and automation, and instead of inline base64 for any real full-resolution screenshot. In ChatGPT, attachments go through import_screenshot instead \u2014 and a user with a ShotOps account can skip file transfer entirely by dropping the screenshots into a project and calling render_project. Uploading one batch per store locale? Tag each batch with `locale` (echoed back for your bookkeeping). The result carries a `disclosure` block \u2014 what moves into ShotOps storage, why, how long it is kept and the explicit action that retains it. Say that before the bytes move, and relay its numbers rather than your own.",
       inputSchema: requestScreenshotUploadShape,
-      outputSchema: requestScreenshotUploadOutputSchema,
+      outputSchema: requestScreenshotUploadToolOutputSchema,
       annotations: ADDITIVE_WRITE,
       _meta: toolMeta(deps, "request_screenshot_upload", "Preparing screenshot uploads\u2026", "Screenshot uploads ready")
     },
@@ -14787,9 +14910,9 @@ function registerTools(server, deps) {
     "import_screenshot",
     {
       title: "Import screenshots",
-      description: 'How screenshots that exist only in THIS conversation get into ShotOps so they can be rendered: one call takes several \u2014 an attached PNG or JPEG, or a PNG/JPEG URL \u2014 and hands each back as a private, account-scoped `ref` the render tools accept, with the image bytes moving server-to-server so they never enter model context. Every entry of `screenshots` names EXACTLY ONE source: { "url": "https://\u2026" } (this server fetches PNG or JPEG and converts JPEG to PNG \u2014 works on any client), { "file": \u2026 } (a ChatGPT attachment descriptor; in ChatGPT it arrives as the top-level `file` parameter instead), or (local stdio server only) { "path": "/abs/shot.png" }. Results come back one per entry in input order, and a failed entry reports its own error without cancelling the rest \u2014 re-import just that one. Then call render_strip with the preferred flat input { "screenshots": [{ "ref": "THE_REF" }] }; the same refs work in emit_bundle, and with their filenames in render_project. If the screenshots are only on the user\'s machine and this is the hosted server, there is no URL to give \u2014 use request_screenshot_upload instead.',
+      description: 'How screenshots that exist only in THIS conversation get into ShotOps so they can be rendered: one call takes several \u2014 an attached PNG or JPEG, or a PNG/JPEG URL \u2014 and hands each back as a private, account-scoped `ref` the render tools accept, with the image bytes moving server-to-server so they never enter model context. Every entry of `screenshots` names EXACTLY ONE source: { "url": "https://\u2026" } (this server fetches PNG or JPEG and converts JPEG to PNG \u2014 works on any client), { "file": \u2026 } (a ChatGPT attachment descriptor; in ChatGPT it arrives as the top-level `file` parameter instead), or (local stdio server only) { "path": "/abs/shot.png" }. Results come back one per entry in input order, and a failed entry reports its own error without cancelling the rest \u2014 re-import just that one. Then call render_strip with the preferred flat input { "screenshots": [{ "ref": "THE_REF" }] }; the same refs work in emit_bundle, and with their filenames in render_project. If the screenshots are only on the user\'s machine and this is the hosted server, there is no URL to give \u2014 use request_screenshot_upload instead. An import that produced refs puts the bytes in ShotOps storage and says so in a `disclosure` block: what moved, why, how long it is kept and the explicit action that retains it. A local { "path" } import moves nothing and discloses nothing.',
       inputSchema: importScreenshotAdvertisedShape,
-      outputSchema: importScreenshotOutputSchema,
+      outputSchema: importScreenshotToolOutputSchema,
       annotations: ADDITIVE_WRITE,
       _meta: toolMeta(deps, "import_screenshot", "Importing attached screenshot\u2026", "Attached screenshot imported", {
         "openai/fileParams": ["file"]
@@ -14801,9 +14924,9 @@ function registerTools(server, deps) {
     "delete_assets",
     {
       title: "Delete uploaded assets",
-      description: "Clean up after delivery: permanently removes the private screenshots, rendered panels and generated bundles ShotOps is holding for this account. Offer it once the user has their files, and call it only when they explicitly ask \u2014 this is irreversible. It cannot reach another account\u2019s files, and it refuses any asset still referenced by a live Project, production operation, share or preview.",
+      description: "Clean up after delivery: permanently removes the private screenshots, rendered panels and generated bundles ShotOps is holding for this account. Offer it once the user has their files, and call it only when they explicitly ask \u2014 this is irreversible. Offer only UNREFERENCED temporary assets: anything a live Project, production operation, share or preview still depends on is refused, so proposing one is proposing a failure. It cannot reach another account\u2019s files. Cleanup is never a step that has to happen \u2014 an asset left alone simply expires.",
       inputSchema: deleteAssetsShape,
-      outputSchema: deleteAssetsOutputSchema,
+      outputSchema: deleteAssetsToolOutputSchema,
       annotations: IDEMPOTENT_DESTRUCTIVE_WRITE,
       _meta: toolMeta(deps, "delete_assets", "Deleting ShotOps assets\u2026", "ShotOps assets deleted")
     },
@@ -14813,7 +14936,7 @@ function registerTools(server, deps) {
     "account_status",
     {
       title: "Check what this connection can do",
-      description: 'Ask whether this connection may produce store-ready screenshots \u2014 full-resolution panels and the fastlane bundle \u2014 before starting a render that might be refused. It reports whether an account is signed in, its plan, trial and remaining ShotOps credits, what a PREVIEW costs here, and \u2014 the field to branch on \u2014 whether production output is available: full-resolution render_strip and render_project, and every emit_bundle form. `production.available: false` comes with a machine-readable `nextStep` (sign_in, choose_plan, upgrade or retry) and a sentence to relay to the user; do not retry the production call until that step is done. CALL THIS FIRST when the user asks for a fastlane bundle, final panels, or "the real files" and you do not already know this connection can produce them \u2014 a refusal after a long render wastes their time, and this call is free: it spends no credits, uses up no free preview, uploads nothing, and writes nothing. Previewing never depends on it, so keep rendering previews regardless.',
+      description: 'Ask whether this connection may produce store-ready screenshots \u2014 full-resolution panels and the fastlane bundle \u2014 before starting a render that might be refused. It reports whether an account is signed in, its plan, trial and remaining ShotOps cloud credits, what a PREVIEW costs here, and \u2014 the field to branch on \u2014 whether production output is available: full-resolution render_strip and render_project, and every emit_bundle form. `production.available: false` comes with a machine-readable `nextStep` (sign_in, choose_plan, upgrade or retry) and a sentence to relay to the user; do not retry the production call until that step is done. CALL THIS FIRST when the user asks for a fastlane bundle, final panels, or "the real files" and you do not already know this connection can produce them \u2014 a refusal after a long render wastes their time, and this call is free: it spends no cloud credits, uses up no free preview, uploads nothing, and writes nothing. Previewing never depends on it, so keep rendering previews regardless.',
       inputSchema: accountStatusShape,
       outputSchema: accountStatusOutputSchema,
       annotations: READ_ONLY,
@@ -15543,7 +15666,17 @@ var init_controlPlaneContract = __esm({
 function controlPlaneUrl() {
   return (process.env.SHOTOPS_CONTROL_PLANE_URL || DEFAULT_CONTROL_PLANE_URL).replace(/\/+$/, "");
 }
-async function callOp(token, op, args = {}) {
+function retryAfterMs(res, attempt) {
+  const header = res.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, 3e4);
+    const at = Date.parse(header);
+    if (Number.isFinite(at)) return Math.min(Math.max(at - Date.now(), 0), 3e4);
+  }
+  return Math.min(1e3 * 2 ** attempt, 8e3);
+}
+async function callOp(token, op, args = {}, attempt = 0) {
   const res = await fetch(controlPlaneUrl(), {
     method: "POST",
     headers: {
@@ -15564,6 +15697,15 @@ async function callOp(token, op, args = {}) {
     if (res.status === 401) {
       throw new Error("control plane rejected the token \u2014 check SHOTOPS_TOKEN, or mint a new one in ShotOps.");
     }
+    if (res.status === 429) {
+      if (attempt < RATE_LIMIT_RETRIES) {
+        await sleep(retryAfterMs(res, attempt));
+        return await callOp(token, op, args, attempt + 1);
+      }
+      throw new Error(
+        `ShotOps is refusing new requests right now (429 after ${RATE_LIMIT_RETRIES + 1} attempts). This is upstream load shedding, not your account or your token \u2014 wait a minute and run it again. A long multi-panel render is the usual trigger.`
+      );
+    }
     if (res.status === 426) {
       const minimum = parsed?.minimumVersion;
       const floor = typeof minimum === "string" && minimum.length > 0 ? ` (${minimum} or newer)` : "";
@@ -15694,7 +15836,8 @@ function connectHostedBridge(token) {
         generations: [...settlement.generationIds],
         outcome: settlement.outcome,
         committed: settlement.committed,
-        capped: settlement.capped
+        capped: settlement.capped,
+        receipt: settlement.receipt
       });
       return { balanceCredits: res.balanceCredits, refundedCredits: res.refundedCredits };
     },
@@ -15725,7 +15868,7 @@ function connectHostedBridge(token) {
     }
   };
 }
-var DEFAULT_CONTROL_PLANE_URL, MAX_PASS_BODY_BYTES, ControlPlaneOperationError;
+var DEFAULT_CONTROL_PLANE_URL, MAX_PASS_BODY_BYTES, ControlPlaneOperationError, RATE_LIMIT_RETRIES, sleep;
 var init_hostedBridge = __esm({
   "src/hostedBridge.ts"() {
     "use strict";
@@ -15750,6 +15893,8 @@ var init_hostedBridge = __esm({
         this.requiredPlan = typeof body?.requiredPlan === "string" ? body.requiredPlan : null;
       }
     };
+    RATE_LIMIT_RETRIES = 3;
+    sleep = (ms) => new Promise((resolve10) => setTimeout(resolve10, ms));
   }
 });
 
@@ -15921,7 +16066,7 @@ 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, finalizeSchema, createSessionSchema, historySchema, REFINE_FIELD_LABELS;
+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;
 var init_refineProjectContracts = __esm({
   "../api/_lib/refineProjectContracts.ts"() {
     "use strict";
@@ -16239,6 +16384,10 @@ var init_refineProjectContracts = __esm({
       projectId: z9.string().uuid(),
       sessionId: z9.string().uuid(),
       turnId: z9.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(),
@@ -16283,7 +16432,15 @@ var init_refineProjectContracts = __esm({
         });
       }
     });
-    finalizeSchema = z9.union([durableFinalizeSchema, legacyFinalizeSchema]);
+    revertSchema = z9.object({
+      intent: z9.literal("revert"),
+      projectId: z9.string().uuid(),
+      /** The committed turn being undone. Becomes the new receipt's `parent_turn_id`. */
+      turnId: z9.string().uuid(),
+      /** The revert's own turn id, minted by the browser exactly as a turn id is. */
+      revertTurnId: z9.string().uuid()
+    });
+    finalizeSchema = z9.union([revertSchema, durableFinalizeSchema, legacyFinalizeSchema]);
     createSessionSchema = z9.object({
       projectId: z9.string().uuid(),
       sessionId: z9.string().uuid(),
@@ -16340,6 +16497,7 @@ var init_refineProjectContracts = __esm({
 });
 
 // src/agentTurnAdapter.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
 function recordEnvelope(existing, state) {
   const stored = existing != null && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : { record: 2 };
   return { ...stored, project: serializeProject(state) };
@@ -16578,6 +16736,7 @@ function applyAllowance(allowance, pass) {
   if (pass.remaining !== null) allowance.remaining = pass.remaining;
 }
 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);
   applyAllowance(context.allowance, result.allowance);
   if (result.ok) {
@@ -16605,23 +16764,28 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
   if (!decision.allowed) {
     return decision.reason === "forbidden" ? { ...NOT_FOUND } : { error: "capability_denied", message: denial ?? "This action is not available." };
   }
+  const turnId = randomUUID3();
+  const turnKey = `turn_${turnId}`;
+  const startedAt = input.startedAt ?? (/* @__PURE__ */ new Date()).toISOString();
   const allowance = { remaining: null, refunded: 0, settled: false };
   let storedRecord;
   let screenSources = null;
   const context = {
     userId: deps.userId,
     projectId: project2.id,
-    turnKey: input.turnKey,
+    turnKey,
+    screenshotCount: 0,
     instruction: input.instruction,
     focus: input.focus,
     allowance,
     runtime
   };
   const result = await runAgentTurn({
+    turnId,
     instruction: input.instruction,
     focus: input.focus,
     requestedCycle: input.requestedCycle,
-    startedAt: input.startedAt,
+    startedAt,
     cancelled: input.cancelled
   }, {
     loadProject: async () => {
@@ -16673,35 +16837,60 @@ async function runMcpProjectAgentTurn(deps, input, runtime) {
     },
     emit: async (event) => {
       if (event.type === "turn_completed") {
-        if (event.result.legacy.passes.length === 0) {
+        const generationIds = event.result.legacy.passes.map((pass) => pass.generationId);
+        if (generationIds.length > 0) {
+          try {
+            const settlement = await runtime.settleTurn({
+              userId: deps.userId,
+              projectId: project2.id,
+              turnKey,
+              generationIds,
+              outcome: event.result.outcome,
+              committed: event.result.committed,
+              capped: event.result.legacy.status === "capped",
+              receipt: {
+                turnId: event.turnId,
+                startedAt,
+                completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                screenshotCount: context.screenshotCount,
+                instructionLength: input.instruction.length
+              }
+            });
+            allowance.remaining = settlement.balanceCredits;
+            allowance.refunded = settlement.refundedCredits;
+            allowance.settled = true;
+          } catch (error) {
+            runtime.log("mcp_agent_turn_settlement_failed", {
+              turnKey,
+              ...safeFailureDiagnostic(error)
+            });
+          }
+        } else {
           allowance.settled = true;
-          await runtime.emit(event);
-          return;
         }
         try {
-          const settlement = await runtime.settleTurn({
+          await runtime.recordReceipt?.({
+            turnId: event.turnId,
             userId: deps.userId,
             projectId: project2.id,
-            turnKey: input.turnKey,
-            generationIds: event.result.legacy.passes.map((pass) => pass.generationId),
+            parentTurnId: null,
             outcome: event.result.outcome,
             committed: event.result.committed,
-            capped: event.result.legacy.status === "capped"
+            generationIds,
+            refundedCredits: allowance.refunded,
+            startedAt,
+            completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            screenshotCount: context.screenshotCount,
+            instructionLength: input.instruction.length
           });
-          allowance.remaining = settlement.balanceCredits;
-          allowance.refunded = settlement.refundedCredits;
-          allowance.settled = true;
         } catch (error) {
-          runtime.log("mcp_agent_turn_settlement_failed", {
-            turnKey: input.turnKey,
-            ...safeFailureDiagnostic(error)
-          });
+          runtime.log("mcp_agent_turn_receipt_failed", { turnKey, ...safeFailureDiagnostic(error) });
         }
       }
       await runtime.emit(event);
     }
   });
-  return { ...result, projectId: project2.id, allowance };
+  return { ...result, turnKey, projectId: project2.id, allowance };
 }
 var VISION_BASE64_BUDGET, NOT_FOUND;
 var init_agentTurnAdapter = __esm({
@@ -16737,7 +16926,10 @@ function writeErrorFrom(error) {
 function localAgentTurnRuntime(bridge) {
   return {
     plannerPass: (_userId, request, turnKey) => bridge.refinePass(request.projectId, request, turnKey),
-    settleTurn: ({ projectId, turnKey, generationIds, outcome, committed, capped }) => bridge.settleRefineTurn(projectId, { turnKey, generationIds, outcome, committed, capped }),
+    // 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.
+    settleTurn: ({ projectId, turnKey, generationIds, outcome, committed, capped, receipt }) => bridge.settleRefineTurn(projectId, { turnKey, generationIds, outcome, committed, capped, receipt }),
     writeProjectRecord: async (projectId, expectedVersion, record6) => {
       try {
         const written = await bridge.updateProjectRecord(projectId, record6, expectedVersion);
@@ -16751,19 +16943,17 @@ function localAgentTurnRuntime(bridge) {
   };
 }
 async function runLocalRefineTurn(deps, bridge, input) {
-  const turnId = mintTurnId();
   try {
     const turn = await runMcpProjectAgentTurn(
       deps,
       {
-        turnKey: turnId,
         instruction: input.instruction,
         focus: input.focus ?? { kind: "project", label: "Whole project" },
         ...input.project ? { project: input.project } : {}
       },
       localAgentTurnRuntime(bridge)
     );
-    return refineProjectResult(turnId, turn);
+    return refineProjectResult(turn);
   } catch {
     return refineProjectUnavailable("The Agent could not complete this turn. Nothing changed\u2014try again.");
   }
@@ -22414,7 +22604,7 @@ var PLACEHOLDER_PORT = 8765;
 var CLIENT_NAME = "ShotOps CLI";
 var LOGIN_TIMEOUT_MS = 5 * 60 * 1e3;
 function authOrigin() {
-  return studioOrigin();
+  return authorityOrigin();
 }
 function base64url2(buf) {
   return buf.toString("base64url");
@@ -22738,7 +22928,7 @@ async function startStdioServer(token) {
   const localInstructions = token ? `${SERVER_INSTRUCTIONS}
 
 ## Local mode (this connection)
-Rendering runs on THIS machine \u2014 free, no timeout ceiling. A hosted token is configured, so save_project / read_look / save_look also work (they read/write your hosted ShotOps account). refine_project runs the Agent turn HERE, rendering on this machine to inspect its own work, and asks ShotOps' servers only to run each AI pass \u2014 so it costs AI credits on your account, and one call commits at most one edit to the saved project. Never re-implement its edit by hand; ${LOCAL_INTAKE}` : `${SERVER_INSTRUCTIONS}
+Rendering runs on THIS machine \u2014 free, no timeout ceiling. A hosted token is configured, so save_project / read_look / save_look also work (they read/write your hosted ShotOps account). refine_project runs the Agent turn HERE, rendering on this machine to inspect its own work, and asks ShotOps' servers only to run each AI pass \u2014 so it costs AI cloud credits on your account, and one call commits at most one edit to the saved project. Never re-implement its edit by hand; ${LOCAL_INTAKE}` : `${SERVER_INSTRUCTIONS}
 
 ## Local mode (this connection)
 Rendering runs on THIS machine \u2014 free, no timeout ceiling. No hosted token is configured. A NEW save_project with local { "path": "..." } PNGs deliberately uploads one temporary private handoff and returns status:"pending_claim" + an openUrl: ALWAYS give that URL to the user. The user owns the project only after opening it and signing in within 7 days; no projectId exists before then. Passing an existing project requires SHOTOPS_TOKEN and is refused here. Ordinary render_strip / emit_bundle calls upload NOTHING, and an explicit request not to save means do not call save_project. read_look / save_look / read_project / render_project / refine_project / share links still require an account connection. ${LOCAL_INTAKE}`;