@pinepaper.studio/mcp-server 1.6.23 → 1.6.25

package/dist/tools/handlers.js

@@ -5,13 +5,15 @@
  * Supports i18n for localized error and success messages.
  * Supports browser execution via Puppeteer.
  */
+import { nestedIgnoredPaths } from './nested-ignored.js';
 import { CRAFT_FRAME_JS, generateDrawWeave, generateDrawKnots, generateDrawSashiko, generateDrawSubdivision, generateUiKit, uiKitCallProblems, } from './craft-tools.js';
 import { codeGenerator, generateQueryMutationsCode, SHEET_RUBRIC } from '../types/code-generator.js';
+import { expandBatchMacros, BatchMacroError } from './batch-macros.js';
 import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ChoreographInputSchema, EmitterInputSchema, MorphSequenceInputSchema, OriginalCharacterInputSchema, LookInputSchema, RenderHookInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
-AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
+AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentBatchOperationSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
 // Letter collage schemas
 CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
 // Map schemas
@@ -26,15 +28,16 @@ ImportImageInputSchema,
 // Tool guide schema
 // Ontology schemas
 // Scene management schemas
-ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
+ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, PatternInputSchema, FlipInputSchema, 
 // New consolidated tool schemas
 SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, HandDrawnInputSchema, PenFigureInputSchema, CreateCharacterInputSchema, CharacterActionInputSchema, CharacterPoseInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, PlaceOnSurfaceInputSchema, DrawWeaveInputSchema, DrawKnotsInputSchema, DrawSashikoInputSchema, DrawSubdivisionInputSchema, UiKitInputSchema, StyledSceneInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError, z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { effectClass } from './effect-class.js';
+import { exportFileReceiptOrReason, receiptErrorLine } from './export-file-receipt.js';
+import { ExportStepError, errorText, verifySavedFile, writeStep, bytesForSave } from './export-file-check.js';
 import { EFFECT_BEFORE_JS, effectAfterJs, namedItemIds, idMayBeGone, NO_CHANGE_NOTE } from './effect-check.js';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
 import { join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
@@ -44,6 +47,7 @@ import { formatErrorContext, captureCanvasState } from '../execution/index.js';
 import { FILTER_PARAM_RANGES } from './engine-lists.js';
 import { getSessionManager } from '../agent/session-manager.js';
 import { vocabularyHintForPath, validateBatchVocabulary, detectBatchPropertyTypos } from '../ontology/hints.js';
+import { compileBatchTimelines } from './timeline.js';
 import { cameraHandlers } from './handlers/camera.js';
 import { fontHandlers } from './handlers/font.js';
 import { toolGuideHandlers } from './handlers/tool-guide.js';
@@ -54,12 +58,15 @@ import { exportHandlers } from './handlers/export.js';
 import { generateHandlers } from './handlers/generate.js';
 import { beatHandlers } from './handlers/beats.js';
 import { planCharacter, generateCharacterCode } from './handlers/character.js';
+import { jsLiteral } from '../utils/js-literal.js';
 import { buildZip } from '../utils/zip.js';
 import { buildScc } from '../utils/scc.js';
 import { checkContrast, checkFlashes, parseCssColor } from '../utils/a11y.js';
 import { buildHtml5Ad, buildPlayable, externalRequests, pinSceneBackground } from '../utils/ad-package.js';
 import { safeFetch, checkUrl, UnsafeUrlError } from '../utils/safe-fetch.js';
 import { confineAssetPath } from '../utils/asset-paths.js';
+import { env } from '../utils/env.js';
+import { getExportDir, exportFileLink } from '../utils/export-dir.js';
 /**
  * Registry of per-domain handler maps. Tools listed here short-circuit the
  * main switch at dispatch time (see handleToolCallInner). New domains are
@@ -82,7 +89,7 @@ function getDomainHandlers() {
  * Defaults to 'on_request' for optimal performance.
  */
 export function getScreenshotMode() {
-    const mode = process.env.PINEPAPER_SCREENSHOT_MODE?.toLowerCase();
+    const mode = env('PINEPAPER_SCREENSHOT_MODE')?.toLowerCase();
     if (mode === 'always' || mode === 'never' || mode === 'on_request') {
         return mode;
     }
@@ -92,9 +99,8 @@ export function getScreenshotMode() {
 // =============================================================================
 // EXPORT FILE SAVE HELPERS
 // =============================================================================
-export function getExportDir() {
-    return process.env.PINEPAPER_EXPORT_DIR || join(tmpdir(), 'pinepaper-exports');
-}
+// The export folder, one definition for the writers and for path confinement (utils/export-dir.ts).
+export { getExportDir };
 // wav joins them: a minute of 48kHz 16-bit is ~5.8 MB of base64 and the ten
 // minutes the schema allows is ~77 MB. Deliverable across the bridge, useless
 // pasted into a response.
@@ -130,10 +136,10 @@ const SAVE_THRESHOLD_BYTES = 180_000; // ~180KB base64 ≈ 135KB decoded
  */
 const EXPORT_GOVERNOR_DEFAULT_MS = 300_000;
 function exportGovernorTimeoutMs() {
-    const raw = Number(process.env.PINEPAPER_EXPORT_TIMEOUT);
+    const raw = Number(env('PINEPAPER_EXPORT_TIMEOUT'));
     if (!Number.isFinite(raw) || raw <= 0)
         return EXPORT_GOVERNOR_DEFAULT_MS;
-    const protocolFloor = Math.max(Number(process.env.PINEPAPER_TIMEOUT) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
+    const protocolFloor = Math.max(Number(env('PINEPAPER_TIMEOUT')) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
     if (raw > protocolFloor) {
         console.error(`[PinePaper] PINEPAPER_EXPORT_TIMEOUT=${raw}ms is above the browser's protocol timeout (${protocolFloor}ms) — ` +
             'raise PINEPAPER_TIMEOUT to match, or an export past that point fails as a protocol error rather than a governor timeout.');
@@ -372,12 +378,15 @@ async function saveAdExport(r, input, platform) {
         const html = buildHtml5Ad(r.adPage, opts);
         const zip = buildZip([{ name: 'index.html', data: html }]);
         files.zip = join(exportDir, `${stamp}.zip`);
-        await writeFile(files.zip, zip);
+        await writeStep(files.zip, () => writeFile(files.zip, zip));
+        await verifySavedFile(files.zip, zip.length);
         uploadBytes = zip.length;
         // The backup image is uploaded BESIDE the zip, not inside it.
         if (r.backupImage && r.backupImage.startsWith('data:')) {
             files.backupImage = join(exportDir, `${stamp}_backup.png`);
-            await writeFile(files.backupImage, Buffer.from(r.backupImage.split(',')[1], 'base64'));
+            const backup = bytesForSave(r.backupImage, 'the backup image');
+            await writeStep(files.backupImage, () => writeFile(files.backupImage, backup));
+            await verifySavedFile(files.backupImage, backup.length);
         }
         else {
             warnings.push({ code: 'no_backup_image', message: 'no backup image was made (the studio could not capture a frame); display networks require one — export format "png" at the same size.' });
@@ -386,8 +395,9 @@ async function saveAdExport(r, input, platform) {
     else {
         const html = buildPlayable(r.adPage, opts);
         files.html = join(exportDir, `${stamp}.html`);
-        await writeFile(files.html, html, 'utf-8');
+        await writeStep(files.html, () => writeFile(files.html, html, 'utf-8'));
         uploadBytes = Buffer.byteLength(html, 'utf-8');
+        await verifySavedFile(files.html, uploadBytes);
     }
     // 150 KB is Google Ads' display HTML5 figure; some uploads allow 600 KB, and
     // playable networks set their own — so it is a default, not a rule.
@@ -411,27 +421,31 @@ async function saveAdExport(r, input, platform) {
         content: [{
                 type: 'text',
                 text: `Ad saved:\n\n${Object.entries(files).map(([k, v]) => `${k}: ${v}`).join('\n')}\nFormat: ${r.format}\nSize: ${r.adSize.width}x${r.adSize.height}, upload ${(uploadBytes / 1024).toFixed(1)} KB\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-            }],
+            }, ...Object.values(files).filter((f) => typeof f === 'string').map((f) => exportFileLink(f))],
     };
 }
 async function saveExportToFile(data, format, platform) {
     const exportDir = getExportDir();
-    await mkdir(exportDir, { recursive: true });
+    await writeStep(exportDir, () => mkdir(exportDir, { recursive: true }));
     const ext = getFileExtension(format);
     const timestamp = Date.now();
     const fileName = `pinepaper_${platform}_${timestamp}.${ext}`;
     const filePath = join(exportDir, fileName);
-    if (data.startsWith('data:')) {
-        const base64Data = data.split(',')[1];
-        const buffer = Buffer.from(base64Data, 'base64');
-        await writeFile(filePath, buffer);
-        return { filePath, fileSize: buffer.length };
+    // A data URL is decoded (base64 or percent-encoded); plain text (SVG, captions) is written as UTF-8. Nothing to
+    // write is the `export` or `save` step's failure, named — it used to write a 0-byte file and report it saved.
+    let buffer;
+    try {
+        buffer = bytesForSave(data, `the ${format} export`);
     }
-    else {
-        // Plain text (SVG)
-        await writeFile(filePath, data, 'utf-8');
-        return { filePath, fileSize: Buffer.byteLength(data, 'utf-8') };
+    catch (e) {
+        if (e instanceof ExportStepError)
+            throw new ExportStepError(e.step, filePath, e.reason);
+        throw e;
     }
+    await writeStep(filePath, () => writeFile(filePath, buffer));
+    // Read back: success is a file that exists and holds what was written.
+    await verifySavedFile(filePath, buffer.length);
+    return { filePath, fileSize: buffer.length };
 }
 /**
  * Page a RETAINED export out of the studio's export store into a local file.
@@ -459,15 +473,16 @@ async function streamRetainedExportToFile(controller, retained, platform) {
     let offset = 0;
     let chunks = 0;
     // Start from empty: appendFile would otherwise extend a same-millisecond file.
-    await writeFile(filePath, Buffer.alloc(0));
+    await writeStep(filePath, () => writeFile(filePath, Buffer.alloc(0)));
     // Returns the error rather than throwing it, so `throw await abandon(...)`
     // reads as a throw to the type checker and narrows what follows.
-    const abandon = async (why) => {
+    // Paging the bytes out is the `save` step; a refusal from the file system is the `write` step.
+    const abandon = async (why, step = 'save') => {
         try {
             await unlink(filePath);
         }
         catch { /* nothing written yet */ }
-        return new Error(
+        return new ExportStepError(step, filePath, 
         // The promise now names the call that keeps it. It was true before and
         // unreachable: reading a held export mutates nothing, so "it can be paged
         // again" was always correct and there was no door to page it through.
@@ -546,7 +561,12 @@ async function streamRetainedExportToFile(controller, retained, platform) {
         const buf = Buffer.from(chunk.data || '', 'base64');
         if (buf.length === 0 && chunk.eof !== true)
             throw await abandon('the studio returned an empty chunk before the end of the file');
-        await appendFile(filePath, buf);
+        try {
+            await appendFile(filePath, buf);
+        }
+        catch (writeError) {
+            throw await abandon(`appending ${buf.length} bytes at offset ${offset} failed: ${errorText(writeError, 'the file system gave no reason')}`, 'write');
+        }
         offset += buf.length;
         chunks++;
         if (chunk.eof === true)
@@ -557,6 +577,16 @@ async function streamRetainedExportToFile(controller, retained, platform) {
     if (offset !== retained.size) {
         throw await abandon(`reassembled ${offset} bytes but the studio reported ${retained.size}`);
     }
+    // An empty export is not a saved file, and neither is one the disk does not hold: read it back BEFORE the
+    // studio's copy is released, so a failure here still leaves the bytes recoverable.
+    if (offset === 0)
+        throw await abandon('the studio held an empty export (0 bytes): there is nothing to save');
+    try {
+        await verifySavedFile(filePath, offset);
+    }
+    catch (verifyError) {
+        throw await abandon(errorText(verifyError instanceof ExportStepError ? verifyError.reason : verifyError, 'the written file could not be read back'), 'write');
+    }
     // Only now is it safe to drop the studio's copy.
     try {
         await controller.executeCode(codeGenerator.generateReleaseExport(retained.exportId), false);
@@ -572,7 +602,7 @@ async function streamRetainedExportToFile(controller, retained, platform) {
  * Defaults to 'puppeteer' for live execution.
  */
 export function getExecutionMode() {
-    const mode = process.env.PINEPAPER_EXECUTION_MODE?.toLowerCase();
+    const mode = env('PINEPAPER_EXECUTION_MODE')?.toLowerCase();
     if (mode === 'puppeteer' || mode === 'code') {
         return mode;
     }
@@ -685,10 +715,40 @@ function withSessionNote(out, r) {
     }
     return out;
 }
+export const RECEIPTS_META_KEY = 'pinepaper.studio/receipts';
+/** The engine run's receipts (report.receipts: { calls, byDoor, notes }), when any call has something to say. */
+export function engineReceipts(report) {
+    const r = report && typeof report === 'object' ? report.receipts : undefined;
+    if (!r || !Array.isArray(r.notes) || r.notes.length === 0)
+        return null;
+    return { calls: Number(r.calls) || 0, byDoor: r.byDoor ?? {}, notes: r.notes };
+}
+/**
+ * agent_export answered from the export's own result and never read the run's report (AR-1 R2): an export's engine
+ * warnings and receipts are now on the reply like every other tool's — a text line an agent reads, and _meta.
+ */
+export function withEngineReport(result, report) {
+    if (!report || result.isError)
+        return result;
+    const receipts = engineReceipts(report);
+    const engineWarnings = Array.isArray(report.engineWarnings) ? report.engineWarnings.filter((w) => w && typeof w === 'object') : [];
+    if (!receipts && !engineWarnings.length)
+        return result;
+    const body = { ...(receipts ? { receipts } : {}), ...(engineWarnings.length ? { engineWarnings } : {}) };
+    return {
+        ...result,
+        content: [...(result.content ?? []), { type: 'text', text: `ENGINE RECEIPTS: ${JSON.stringify(body)}` }],
+        _meta: { ...(result._meta ?? {}), [RECEIPTS_META_KEY]: body },
+    };
+}
 function executedResult(code, result, screenshot, description, report) {
     const resultObj = { success: true, result };
     if (description)
         resultObj.description = description;
+    // The scene lint after the code ran, when there is something to say.
+    const lint = report && Array.isArray(report.lintWarnings) ? report.lintWarnings : [];
+    if (lint.length)
+        resultObj.lintWarnings = lint;
     // Surface the governor's model-actionable feedback (app.runGenerated report):
     // warnings (e.g. "500 items created one-by-one — prefer a pattern"), item count,
     // and guard trips. Omitted entirely on pre-governor FxTool builds (no report).
@@ -711,6 +771,11 @@ function executedResult(code, result, screenshot, description, report) {
             governor.loopGuardTripped = true;
         if (Object.keys(governor).length)
             resultObj.governor = governor;
+        // AR-1 R2: what each engine call did with what it was given (FxTool js/core/Receipt.js) — only when a call
+        // renamed, fell back, dropped or warned; a run whose calls all applied as asked adds nothing.
+        const receipts = engineReceipts(report);
+        if (receipts)
+            resultObj.receipts = receipts;
     }
     // THE CODE ECHO WAS 90% OF THE RESPONSE, AND THE AGENT WROTE THE REQUEST.
     //
@@ -728,7 +793,7 @@ function executedResult(code, result, screenshot, description, report) {
     const content = [
         { type: 'text', text: JSON.stringify(resultObj, null, 2) },
     ];
-    if (process.env.PINEPAPER_ECHO_CODE === '1') {
+    if (env('PINEPAPER_ECHO_CODE') === '1') {
         content.push({ type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` });
     }
     if (screenshot) {
@@ -758,7 +823,7 @@ function screenshotResult(screenshot) {
  * error code, not a program, and stripping those would take information away.
  */
 function redactGeneratedCode(details) {
-    if (process.env.PINEPAPER_ECHO_CODE === '1')
+    if (env('PINEPAPER_ECHO_CODE') === '1')
         return details;
     if (!details || typeof details !== 'object' || Array.isArray(details))
         return details;
@@ -777,6 +842,44 @@ function redactGeneratedCode(details) {
         },
     };
 }
+/**
+ * The studio's scene-lint warnings on an export (FxTool lintScene), one line each, so a centred title that runs
+ * out of the frame ("IGNAL" for "SIGNAL") is read on the success path rather than left in the JSON. Empty when none.
+ */
+export function lintLines(exportResult) {
+    const w = exportResult?.lintWarnings;
+    if (!Array.isArray(w) || !w.length)
+        return '';
+    return w.map((x) => `LINT: ${String(x?.message ?? x?.code ?? 'scene lint warning')}\n`).join('');
+}
+/**
+ * The file as ffprobe read it, when it disagrees with what the studio encoded: one line per field. A summary
+ * line when they agree; nothing when there is no summary.
+ */
+export function probeLines(receipt) {
+    const p = receipt.probe;
+    if (!p)
+        return '';
+    const head = `Probe: ${p.container} ${p.codec} ${p.width}x${p.height}${p.fps ? ` @ ${p.fps} fps` : ''}, ${p.durationS} s, ${p.frames} frame${p.frames === 1 ? '' : 's'}`;
+    const c = receipt.probeCheck;
+    if (!c)
+        return `${head}\n`;
+    if (c.tool === null)
+        return `${head} (not read back: ${c.reason})\n`;
+    if (c.ok)
+        return `${head} (ffprobe agrees)\n`;
+    if (!c.mismatches?.length)
+        return `${head}\nPROBE: ${c.reason ?? 'ffprobe could not confirm the file'}\n`;
+    return `${head}\n` + c.mismatches.map((m) => `PROBE MISMATCH: ${m.field} — the studio encoded ${JSON.stringify(m.studio)}, ffprobe reads ${JSON.stringify(m.file)}\n`).join('');
+}
+/**
+ * An export that failed at a step, as an error result: `{ step, path, reason }` in the data and in the words.
+ * A non-ExportStepError is named at `fallbackStep` with its own message, never "undefined".
+ */
+function exportStepErrorResult(e, fallbackStep, extra = {}, toolName = 'pinepaper_agent_export') {
+    const err = e instanceof ExportStepError ? e : new ExportStepError(fallbackStep, null, errorText(e, `the ${fallbackStep} step failed with no reason given`));
+    return errorResult(ErrorCodes.EXECUTION_ERROR, err.message, { ...err.toData(), ...extra }, { toolName });
+}
 export function errorResult(code, message, rawDetails, context) {
     // THE GENERATED SCRIPT IS NOT THE ERROR.
     //
@@ -811,15 +914,19 @@ export function errorResult(code, message, rawDetails, context) {
         isError: true,
     };
 }
-function handleValidationError(error, i18n) {
+function handleValidationError(error, i18n, args) {
     const message = i18n
         ? i18n.getError('validationError', { message: 'Invalid input parameters' })
         : 'Invalid input parameters';
-    const details = error.errors.map((e) => {
+    const details = error.issues.map((e) => {
         const path = e.path.join('.');
         const detail = { path, message: e.message };
-        if (e.code === 'invalid_enum_value') {
-            const received = e.received;
+        // zod 4 names a value outside an enum `invalid_value` and no longer carries what was sent; it is read back from the
+        // call's own arguments along the issue's path, so the vocabulary hint ("did you mean …") still has a word to match.
+        if (e.code === 'invalid_value') {
+            let received = args;
+            for (const k of e.path)
+                received = received && typeof received === 'object' ? received[k] : undefined;
             const hint = vocabularyHintForPath(path, received);
             if (hint)
                 detail.vocabulary = hint;
@@ -979,9 +1086,7 @@ export async function customCodeRollback(controller, error) {
         removed = v.removed ?? 0;
         left = typeof v.left === 'number' ? v.left : -1;
     }
-    catch {
-        rolledBack = false;
-    }
+    catch { /* rolledBack stays false: nothing was confirmed removed */ }
     const scene = rolledBack
         ? (removed > 0
             ? `The ${removed} item(s) this call created before it stopped were removed. Changes it made to items that already existed are not reverted.`
@@ -1062,23 +1167,34 @@ async function writeResultDataToFile(out, ext) {
         return out;
     }
     const r = obj.result;
-    if (!r || r.data === undefined || r.data === null)
+    if (!r || r.success === false)
         return out;
-    let bytes;
-    if (typeof r.data === 'string' && r.data.startsWith('data:'))
-        bytes = Buffer.from(r.data.slice(r.data.indexOf(',') + 1), 'base64');
-    else if (typeof r.data === 'string')
-        bytes = Buffer.from(r.data, 'utf-8');
-    else
-        bytes = Buffer.from(JSON.stringify(r.data), 'utf-8');
+    if (r.data === undefined || r.data === null) {
+        // A result that says in fields that it wrote no file (png-sequence frames left in the page: `file: null` and
+        // `why`) claims no file: it passes as it is. Any other success with nothing to write is the exit-0-without-file
+        // case, named.
+        if (r.file === null && typeof r.why === 'string' && r.why.trim())
+            return out;
+        const err = new ExportStepError('export', null, `the ${ext} export reported success but returned no file data`);
+        return errorResult(ErrorCodes.EXECUTION_ERROR, err.message, { ...err.toData(), result: r });
+    }
     const dir = getExportDir();
-    await mkdir(dir, { recursive: true });
     const filePath = join(dir, `pinepaper_${String(r.format ?? 'export').replace(/[^a-z0-9-]/gi, '')}_${Date.now()}.${ext}`);
-    await writeFile(filePath, bytes);
-    const { data: _d, ...rest } = r;
-    void _d;
-    obj.result = { ...rest, filePath, bytes: bytes.length };
-    return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1)] };
+    // No success without a file that exists and is not empty: each failure names its step, path and reason.
+    try {
+        const bytes = typeof r.data === 'string' ? bytesForSave(r.data, `the ${ext} export`) : Buffer.from(JSON.stringify(r.data), 'utf-8');
+        await writeStep(filePath, async () => { await mkdir(dir, { recursive: true }); await writeFile(filePath, bytes); });
+        await verifySavedFile(filePath, bytes.length);
+        const { data: _d, ...rest } = r;
+        void _d;
+        obj.result = { ...rest, filePath, bytes: bytes.length };
+        return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1), exportFileLink(filePath, bytes.length)] };
+    }
+    catch (e) {
+        const err = e instanceof ExportStepError ? new ExportStepError(e.step, e.path ?? filePath, e.reason)
+            : new ExportStepError('write', filePath, errorText(e, 'the file could not be written'));
+        return errorResult(ErrorCodes.EXECUTION_ERROR, err.message, err.toData());
+    }
 }
 /**
  * pinepaper_capture_frames with `sheet`: one tiled image of the film, saved
@@ -1282,8 +1398,9 @@ ${code}
         tracker.startTimer(`${timerId}_screenshot`);
     }
     // Agent-written code is rolled back when it fails part-way; a tool's own
-    // emitter is not (its verdict already describes what it left behind).
-    const rollbackOnFailure = toolName === 'pinepaper_execute_custom_code'
+    // emitter is not (its verdict already describes what it left behind), except
+    // an atomic batch, whose contract is that a refused call changed nothing.
+    const rollbackOnFailure = (toolName === 'pinepaper_execute_custom_code' || options.rollbackCreatedOnFailure === true)
         && await markItemsBeforeRun(controller);
     const governorTimeoutMs = LONG_GOVERNOR_BUDGET_MS[toolName];
     // NO SILENT SUCCESS (effect-class.ts / effect-check.ts): fingerprint a
@@ -1308,6 +1425,10 @@ ${code}
         ...(governorTimeoutMs ? { governorTimeoutMs } : {}),
     });
     const browserDuration = tracker.endTimer(`${timerId}_browser_execution`);
+    // THE SCENE LINT RIDES OUT OF BAND: an emitter that ran app.lintScene() returns it under __ppLint, and
+    // execute_custom_code returns its own value under __ppValue. Both are unwrapped HERE, before any verdict reads the
+    // result, so the code's own value is what is judged and returned, and the lint sits beside it.
+    const lintWarnings = unwrapLint(result);
     // THE METRIC RECORDS THE CALL'S VERDICT, NOT THE TRANSPORT'S (gate H2,
     // 1.6.19). result.success only says the code RAN; an emitter that ran and
     // returned { success: false } is a failed call, and get_performance_metrics
@@ -1352,6 +1473,8 @@ ${code}
         // PP_LOOP_BUDGET, PP_TIMEOUT) so the model can correct on the next turn.
         {
             code, errorCode: result.errorCode, governorReport: result.report,
+            failures: stepFailures(toolName, result.result, result.error || 'Failed to execute code in browser'),
+            ...(lintWarnings.length ? { lintWarnings } : {}),
             ...(rollbackOnFailure ? await customCodeRollback(controller, result.error) : {}),
         }, {
             toolName,
@@ -1383,6 +1506,8 @@ ${code}
             .slice(0, 3);
         return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, said.length ? `${inner} The studio said: ${said.join(' | ')}` : inner, {
             code, result: result.result, governorReport: result.report,
+            failures: stepFailures(toolName, result.result, inner),
+            ...(lintWarnings.length ? { lintWarnings } : {}),
             ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
         }, { toolName, canvasState: canvasState || undefined }), timing);
     }
@@ -1434,6 +1559,46 @@ ${code}
  * string with no `success: true` beside it is a failure too — it is what the
  * emitters' catch blocks return.
  */
+/**
+ * Move an emitter's out-of-band scene lint (`__ppLint`) off its result, and unwrap execute_custom_code's own value
+ * (`__ppValue`). The lint is also put on `run.report.lintWarnings`, where executedResult reads it. Returns the lint.
+ */
+export function unwrapLint(run) {
+    const r = run.result;
+    if (!r || typeof r !== 'object' || Array.isArray(r) || !('__ppLint' in r))
+        return [];
+    const lint = Array.isArray(r.__ppLint) ? r.__ppLint : [];
+    if ('__ppValue' in r || r.__ppWrapped === true)
+        run.result = r.__ppValue;
+    else {
+        const { __ppLint: _l, ...rest } = r;
+        void _l;
+        run.result = rest;
+    }
+    if (lint.length)
+        run.report = { ...(run.report ?? {}), lintWarnings: lint };
+    return lint;
+}
+/**
+ * Every failed step of a call as `{ step, itemId, reason }`, never a bare message: a batch's own `failures`, a
+ * result that names its step, or the call itself with the item it named.
+ */
+export function stepFailures(toolName, value, message) {
+    const v = value;
+    const reasonOf = (x) => (typeof x === 'string' && x.trim() ? x : '');
+    if (v && typeof v === 'object' && Array.isArray(v.failures) && v.failures.length) {
+        return v.failures.map((f) => ({
+            step: reasonOf(f.step) || toolName,
+            itemId: typeof f.itemId === 'string' ? f.itemId : null,
+            reason: reasonOf(f.reason) || reasonOf(f.error) || message,
+        }));
+    }
+    return [{
+            step: (v && typeof v === 'object' && reasonOf(v.step)) || toolName,
+            itemId: v && typeof v === 'object' && typeof v.itemId === 'string' ? v.itemId : null,
+            reason: (v && typeof v === 'object' && (reasonOf(v.reason) || reasonOf(v.error))) || reasonOf(message) || `${toolName} failed with no reason given`,
+        }];
+}
 export function innerFailure(value) {
     if (!value || typeof value !== 'object')
         return null;
@@ -1605,6 +1770,15 @@ export const HIDDEN_ARGUMENTS = {
     pinepaper_query_capabilities: ['query'],
     pinepaper_text_effect: ['startAt', 'hideAfter'],
 };
+/**
+ * Nested keys (paths with [] for any array index) a handler accepts that its published schema closes over without
+ * listing. Shrink-only, held exact by nested-ignored-coverage.test.ts; publishing one means deleting it here.
+ */
+export const NESTED_HIDDEN = {
+    pinepaper_create_item: ['keyframes[].hold', 'keyframes[].interpolation'],
+    pinepaper_create_scene: ['animations[].startTime'],
+    pinepaper_keyframe_animate: ['keyframes[].hold', 'keyframes[].interpolation'],
+};
 /** Tools whose schema passes every key through: nothing is dropped. */
 export const PASSTHROUGH_ARGUMENT_TOOLS = new Set(['pinepaper_equation_path', 'pinepaper_ui_kit']);
 const IGNORED_ARGUMENT_HINTS = {
@@ -1635,8 +1809,9 @@ export function ignoredArgumentKeys(toolName, args, published) {
         return [];
     const known = new Set([...(published ?? []), ...(HIDDEN_ARGUMENTS[toolName] ?? [])]);
     let schema = IGNORED_ARGUMENT_SCHEMAS[toolName];
-    while (schema instanceof z.ZodEffects)
-        schema = schema._def.schema;
+    // zod 4: a preprocess or transform is a ZodPipe (preprocess: transform → object; .transform: object → transform).
+    while (schema instanceof z.ZodPipe)
+        schema = (schema._def.in instanceof z.ZodObject || !(schema._def.out instanceof z.ZodObject) ? schema._def.in : schema._def.out);
     if (schema instanceof z.ZodObject)
         Object.keys(schema.shape).forEach((k) => known.add(k));
     else if (published === undefined)
@@ -1651,13 +1826,66 @@ export function ignoredArgumentsNote(toolName, args, published) {
     return `IGNORED ARGUMENTS: ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not a parameter of ${toolName}, so ${ignored.length > 1 ? 'they had' : 'it had'} no effect.`
         + (hints.length ? ` ${[...new Set(hints)].join(' ')}` : '');
 }
-/** The same check, against the tool's published schema. */
+/** The same check, against the tool's published schema, and below the top level (AR-1 R2: nested-ignored.ts). */
 export async function ignoredArgumentsNoteFor(toolName, args) {
     const published = await publishedArguments(toolName);
-    const ignored = ignoredArgumentKeys(toolName, args, published);
+    const top = ignoredArgumentKeys(toolName, args, published);
+    const nested = PASSTHROUGH_ARGUMENT_TOOLS.has(toolName) || published === null ? [] : await nestedIgnoredFor(toolName, args);
+    const ignored = [...top, ...nested];
     if (!ignored.length)
         return null;
-    return { note: ignoredArgumentsNote(toolName, args, published), ignored };
+    const topNote = top.length ? ignoredArgumentsNote(toolName, args, published) : '';
+    const nestedNote = nested.length
+        ? `IGNORED ARGUMENTS: ${nested.join(', ')} ${nested.length > 1 ? 'are' : 'is'} not a parameter of ${toolName}, so ${nested.length > 1 ? 'they had' : 'it had'} no effect.`
+        : '';
+    return { note: [topNote, nestedNote].filter(Boolean).join(' '), ignored };
+}
+async function nestedIgnoredFor(toolName, args) {
+    const { PINEPAPER_TOOLS } = await import('./definitions.js');
+    const tool = PINEPAPER_TOOLS.find((t) => t.name === toolName);
+    if (!tool)
+        return [];
+    const hidden = new Set(NESTED_HIDDEN[toolName] ?? []);
+    const paths = nestedIgnoredPaths(tool.inputSchema, args).filter((p) => !hidden.has(p.replace(/\[\d+\]/g, '[]')));
+    return toolName === 'pinepaper_agent_batch_execute' ? [...paths, ...batchOpIgnoredPaths(args)] : paths;
+}
+/**
+ * Batch op keys the batch reads that AgentBatchOperationSchema does not list. The op schema is passthrough (a create
+ * takes shape properties flat), so these arrive intact; batch-op-keys.test.ts fails when the batch code reads a key
+ * that is in neither list, so a working key is never reported. Shrink-only.
+ */
+export const BATCH_OP_HIDDEN = {
+    '*': ['_step', 'id'],
+    keyframe_animate: ['params', 'timeUnits', 'timeOffset', 'clipInPoint', 'clipOutPoint'],
+    timeline: ['repeat', 'yoyo', 'anchor'],
+};
+/** Hints for the slips that land on a key another op type reads. */
+const BATCH_OP_HINTS = {
+    'relation.params': 'a relation op takes its parameters as relationOptions',
+    'modify.x': 'a modify op takes changes inside properties', 'modify.y': 'a modify op takes changes inside properties',
+};
+/**
+ * A key on a batch op that nothing reads (the passthrough schema let it in, so the nested walk cannot see it). A
+ * `create` folds every op-level key into its properties, which create_item's own property report covers, so only the
+ * other op types are checked here.
+ */
+export function batchOpIgnoredPaths(args) {
+    const ops = Array.isArray(args.operations) ? args.operations : [];
+    const shape = Object.keys(AgentBatchOperationSchema.shape);
+    const out = [];
+    ops.forEach((op, i) => {
+        const type = op && typeof op === 'object' && !Array.isArray(op) ? String(op.type) : 'create';
+        if (type === 'create')
+            return;
+        const known = new Set([...shape, ...BATCH_OP_HIDDEN['*'], ...(BATCH_OP_HIDDEN[type] ?? [])]);
+        for (const k of Object.keys(op)) {
+            if (known.has(k))
+                continue;
+            const hint = BATCH_OP_HINTS[`${type}.${k}`];
+            out.push(`operations[${i}].${k}${hint ? ` (${hint})` : ''}`);
+        }
+    });
+    return out.slice(0, 50);
 }
 export const IGNORED_ARGUMENTS_META_KEY = 'pinepaper.studio/ignoredArguments';
 export async function handleToolCall(toolName, args, options = {}) {
@@ -1798,6 +2026,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateStagger(input);
                 return executeOrGenerate(code, `Stagger: ${input.action}`, options, 'pinepaper_stagger');
             }
+            case 'pinepaper_pattern': {
+                const input = PatternInputSchema.parse(args);
+                const code = codeGenerator.generatePattern(input);
+                return executeOrGenerate(code, `Pattern: ${input.action}${input.id ? ' ' + input.id : ''}`, options, 'pinepaper_pattern');
+            }
             case 'pinepaper_flip': {
                 const input = FlipInputSchema.parse(args);
                 const code = codeGenerator.generateFlip(input);
@@ -2396,7 +2629,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                             const controller = options.browserController || getBrowserController();
                             if (!controller.connected)
                                 await controller.connect();
-                            const r = await controller.executeCode(`(function() { const ids = ${JSON.stringify(itemIds)}; return ids.filter(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return !(e && e.item); }); })();`, false);
+                            const r = await controller.executeCode(`(function() { const ids = ${jsLiteral(itemIds)}; return ids.filter(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return !(e && e.item); }); })();`, false);
                             if (r.success && Array.isArray(r.result))
                                 missingItems = r.result;
                         }
@@ -2840,7 +3073,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 // Falls back to the PINEPAPER_STUDIO_URL env var, else PuppeteerController's
                 // built-in prod default. "/editor" + agent params are appended by the controller.
                 const rawUrl = typeof args.url === 'string' ? args.url.trim() : '';
-                const studioUrl = (rawUrl || (process.env.PINEPAPER_STUDIO_URL || '').trim()) || undefined;
+                const studioUrl = (rawUrl || (env('PINEPAPER_STUDIO_URL') || '').trim()) || undefined;
                 // Only http(s) is supported — reject file://, data://, javascript:, etc.
                 if (studioUrl) {
                     const v = validateStudioUrl(studioUrl);
@@ -2993,7 +3226,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     version: SERVER_VERSION,
                     toolkit: detectToolkit(),
                     verbosity: detectVerbosity(),
-                    locale: process.env.PINEPAPER_LOCALE || 'en',
+                    locale: env('PINEPAPER_LOCALE') || 'en',
                     executionMode: options.executionMode || getExecutionMode(),
                     screenshotMode: options.screenshotMode || getScreenshotMode(),
                 };
@@ -3095,6 +3328,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         })),
                         profiles: {
                             'full+verbose': fullTokens,
+                            'core+compact': Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity('compact'), 'core')), 'utf-8') / 4),
                             'agent+compact': agentCompactTokens,
                             'agent+minimal': agentMinimalTokens,
                         },
@@ -3107,7 +3341,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     const recs = toolDefsSection.recommendations;
                     const alternatives = [];
                     for (const v of ['compact', 'minimal']) {
-                        for (const k of ['full', 'agent', 'minimal']) {
+                        for (const k of ['full', 'agent', 'core', 'minimal']) {
                             if (k === toolkit && v === verbosity)
                                 continue;
                             const t = Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity(v), k)), 'utf-8') / 4);
@@ -3549,7 +3783,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                 type: 'text',
                                 // The script is not part of the answer here either — same reason
                                 // errors no longer carry it. PINEPAPER_ECHO_CODE=1 brings it back.
-                                text: (process.env.PINEPAPER_ECHO_CODE === '1'
+                                text: (env('PINEPAPER_ECHO_CODE') === '1'
                                     ? `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\n`
                                     : '')
                                     + `Full screenshot saved to: ${filePath} (${(fileSize / 1024).toFixed(1)} KB)\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
@@ -3611,8 +3845,26 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         })));
                     }
                 }
+                let expanded;
+                try {
+                    expanded = expandBatchMacros(input.operations);
+                }
+                catch (e) {
+                    if (e instanceof BatchMacroError)
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, e.message, {}, { toolName: 'pinepaper_agent_batch_execute' });
+                    throw e;
+                }
+                // A timeline op compiles on the server: a tween it cannot honour is refused by name here, before the canvas is
+                // touched (skipValidation does not bypass it — there is nothing to send for a tween that did not compile).
+                if (expanded.some((op) => op.type === 'timeline')) {
+                    const tl = compileBatchTimelines(expanded);
+                    if (tl.errors.length > 0) {
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, `The timeline was refused (${tl.errors.length} problem${tl.errors.length > 1 ? 's' : ''}); nothing was run. Fix ${tl.errors.length > 1 ? 'each' : 'it'} and send the batch again.`, tl.errors.map((e) => ({ path: e.path, reason: e.message })));
+                    }
+                }
                 const code = codeGenerator.generateAgentBatchExecute(input);
-                const description = `Batch executed ${input.operations.length} operations${input.atomic !== false ? ' (atomic)' : ''}`;
+                const description = `Batch executed ${input.operations.length} operations${input.atomic !== false ? ' (atomic)' : ''}`
+                    + (expanded.length !== input.operations.length ? ` (${expanded.length} after expanding ring / grid / orbit / stagger)` : '');
                 // Check for out-of-bounds items before execution
                 let boundsWarning = '';
                 const sizeOp = input.operations.find((op) => op.type === 'set_canvas_size');
@@ -3620,7 +3872,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     const cw = sizeOp.width || 1920;
                     const ch = sizeOp.height || 1080;
                     const oobItems = [];
-                    input.operations.forEach((op, idx) => {
+                    expanded.forEach((op, idx) => {
                         if (op.type === 'create' && op.position) {
                             const { x, y } = op.position;
                             if (x < 0 || y < 0 || x > cw || y > ch) {
@@ -3632,7 +3884,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         boundsWarning = `\n\nWARNING: ${oobItems.length} item(s) positioned outside canvas bounds (${cw}x${ch}): ${oobItems.join(', ')}. Items may be clipped or invisible.`;
                     }
                 }
-                const batchResult = await executeOrGenerate(code, description, options, 'pinepaper_agent_batch_execute');
+                const batchResult = await executeOrGenerate(code, description, input.atomic !== false ? { ...options, rollbackCreatedOnFailure: true } : options, 'pinepaper_agent_batch_execute');
                 // Append bounds warning if any
                 if (boundsWarning && batchResult.content && batchResult.content.length > 0) {
                     const firstContent = batchResult.content[0];
@@ -3804,13 +4056,14 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                             format,
                             chunkBytes: Number(exportResult.chunkBytes) || undefined,
                         }, input.platform || 'auto');
-                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, chunks };
-                        return {
+                        const receipt = await exportFileReceiptOrReason(filePath, exportResult);
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, chunks, file: receipt };
+                        return withEngineReport({
                             content: [{
                                     type: 'text',
-                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-                                }],
-                        };
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n${receiptErrorLine(receipt)}${'receiptError' in receipt ? '' : probeLines(receipt)}${lintLines(exportResult)}\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                }, exportFileLink(filePath, fileSize)],
+                        }, exportBrowserResult.report);
                     }
                     catch (streamError) {
                         // The export is still held — the message says so and names the id,
@@ -3824,7 +4077,14 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 // SCC (CEA-608, 8.37): the studio sent the cues; encoded here.
                 if (format === 'scc' && Array.isArray(exportResult?.sccCues)) {
                     const scc = buildScc(exportResult.sccCues);
-                    const { filePath, fileSize } = await saveExportToFile(scc.text, 'scc', input.platform || 'auto');
+                    let saved;
+                    try {
+                        saved = await saveExportToFile(scc.text, 'scc', input.platform || 'auto');
+                    }
+                    catch (saveError) {
+                        return exportStepErrorResult(saveError, 'save', { format: 'scc' });
+                    }
+                    const { filePath, fileSize } = saved;
                     const warnings = [];
                     if (scc.truncated)
                         warnings.push({ code: 'caption_truncated', message: `${scc.truncated} caption(s) did not fit two rows of 32 characters and were cut. Split long captions into more cues.` });
@@ -3835,10 +4095,22 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     const { sccCues: _c, ...rest } = exportResult;
                     void _c;
                     const cleanResult = { ...rest, filePath, fileSize, frameRate: '29.97 drop-frame', fidelity: { warnings } };
-                    return { content: [{ type: 'text', text: `Export saved to file:\n\nFile: ${filePath}\nFormat: scc (CEA-608, CC1, pop-on)\nSize: ${fileSize} bytes\n\nResult: ${JSON.stringify(cleanResult, null, 2)}` }] };
+                    return withEngineReport({ content: [{ type: 'text', text: `Export saved to file:\n\nFile: ${filePath}\nFormat: scc (CEA-608, CC1, pop-on)\nSize: ${fileSize} bytes\n\nResult: ${JSON.stringify(cleanResult, null, 2)}` }, exportFileLink(filePath, fileSize)] }, exportBrowserResult.report);
                 }
                 if ((format === 'html5-ad' || format === 'playable') && typeof exportResult?.adPage === 'string') {
-                    return saveAdExport(exportResult, input, input.platform || 'auto');
+                    try {
+                        return withEngineReport(await saveAdExport(exportResult, input, input.platform || 'auto'), exportBrowserResult.report);
+                    }
+                    catch (saveError) {
+                        return exportStepErrorResult(saveError, 'save', { format });
+                    }
+                }
+                // NO SUCCESS WITHOUT BYTES. Every delivering branch above returned; what is left must carry the file's
+                // data. A success with none (no data field, an empty string) used to fall through to the inline return and
+                // report success with nothing in it. An estimate is the one answer that is not a file.
+                if (!exportResult?.estimateOnly && !(typeof data === 'string' && data.length > 0)) {
+                    const err = new ExportStepError('export', null, `the studio reported a successful ${format} export but returned no file data (${data === undefined ? 'no data field' : typeof data === 'string' ? 'an empty string' : `a ${data === null ? 'null' : typeof data}`})`);
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, err.message, { ...err.toData(), format, result: exportResult }, { toolName: 'pinepaper_agent_export' });
                 }
                 const shouldSaveToFile = data && typeof data === 'string' && (options.saveToFile ||
                     ALWAYS_SAVE_FORMATS.has(format) ||
@@ -3846,29 +4118,33 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 if (shouldSaveToFile) {
                     try {
                         const { filePath, fileSize } = await saveExportToFile(data, format, input.platform || 'auto');
-                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize };
+                        const receipt = await exportFileReceiptOrReason(filePath, exportResult);
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, file: receipt };
                         // A mix that dropped sounds wrote a perfectly good file that is
                         // missing tracks. It rides the SUCCESS path, which is exactly why
                         // it has to be said out loud here rather than left in the JSON.
                         const dropNote = exportResult.incomplete;
-                        return {
+                        return withEngineReport({
                             content: [{
                                     type: 'text',
                                     text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n`
                                         + (dropNote ? `DROPPED: ${dropNote}\n` : '')
+                                        + receiptErrorLine(receipt)
+                                        + ('receiptError' in receipt ? '' : probeLines(receipt))
+                                        + lintLines(exportResult)
                                         + `\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-                                }],
-                        };
+                                }, exportFileLink(filePath, fileSize)],
+                        }, exportBrowserResult.report);
                     }
                     catch (saveError) {
+                        // A failed save is a failed export, never a success with a note inside it: the step, the path and
+                        // the reason, and the data stripped so the error is not the size of the video.
                         console.error('[PinePaper] Failed to save export to file:', saveError);
-                        // Strip the massive data to prevent oversized response
-                        const strippedResult = { ...exportResult, data: `[${format} export data — file save failed: ${saveError instanceof Error ? saveError.message : 'unknown error'}]` };
-                        return executedResult(code, strippedResult, exportBrowserResult.screenshot, description);
+                        return exportStepErrorResult(saveError, 'save', { format, bytes: typeof data === 'string' ? data.length : 0 });
                     }
                 }
-                // Small export — return inline (existing behavior)
-                return executedResult(code, exportResult, exportBrowserResult.screenshot, description);
+                // Small export — return inline (existing behavior). The bytes are in the result, checked non-empty above.
+                return executedResult(code, exportResult, exportBrowserResult.screenshot, description, exportBrowserResult.report);
             }
             case 'pinepaper_design_styles':
                 return dataResult({ styles: designSystems.listStyles() });
@@ -4039,11 +4315,8 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         };
                     }
                     catch (saveError) {
-                        const stripped = {
-                            ...soundtrack,
-                            wavBase64: `[${soundtrack.byteLength} bytes of WAV — file save failed: ${saveError instanceof Error ? saveError.message : 'unknown error'}]`,
-                        };
-                        return executedResult(code, stripped, wavResult.screenshot, soundDescription);
+                        // The soundtrack rendered; writing it did not. That is a failed export, said as one.
+                        return exportStepErrorResult(saveError, 'save', { format: 'wav', byteLength: soundtrack.byteLength }, 'pinepaper_sound');
                     }
                 }
                 return executeOrGenerate(code, soundDescription, options, 'pinepaper_sound');
@@ -4292,7 +4565,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
     }
     catch (error) {
         if (error instanceof ZodError) {
-            return handleValidationError(error, i18n);
+            return handleValidationError(error, i18n, args);
         }
         // Try to capture canvas state for error context (if browser is connected)
         let canvasState = null;
@@ -4305,6 +4578,10 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
         catch (_stateError) {
             // Ignore errors from canvas state capture
         }
+        // An export that failed at a named step keeps its step, path and reason as fields.
+        if (error instanceof ExportStepError) {
+            return errorResult(ErrorCodes.EXECUTION_ERROR, error.message, error.toData(), { toolName, canvasState: canvasState || undefined });
+        }
         if (error instanceof Error) {
             const message = i18n
                 ? i18n.getError('executionError', { message: error.message })