@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -250,6 +250,18 @@ describe("agent-mode contract", () => {
     expect(run.stdout).toContain("No composition found");
   });
 
+  it("a render that fails under --json prints only the envelope on stdout", async () => {
+    const project = join(home, "render-json");
+    mkdirSync(project, { recursive: true });
+    writeFileSync(join(project, "index.html"), "<!doctype html><html><body></body></html>");
+    const run = await runAsAgent(["render", project, "--variables", "{bad", "--json"]);
+    expectQuiet(run);
+    expect(run.code, run.stderr).toBe(1);
+    expect(run.stdout.trim().split("\n")).toHaveLength(1);
+    expectJsonFailure(run, "runtime_error");
+    expect(JSON.parse(run.stdout).error.message).toBe("Invalid JSON in --variables");
+  });
+
   it("an unknown command under --json is an envelope with the suggestion", async () => {
     const run = await runAsAgent(["rendr", "--json"]);
     expect(run.code).toBe(2);
 
@@ -347,7 +347,8 @@ export default defineCommand({
     },
     json: {
       type: "boolean",
-      description: "With --batch, emit exactly one final JSON result document.",
+      description:
+        "With --batch, emit exactly one final JSON result document. Without --batch, print no progress, and on failure print the JSON error envelope.",
       default: false,
     },
     resolution: {
 
@@ -91,6 +91,9 @@ export async function executeRenderPlan(
     }
   }
 
+  const variables = plan.batchPath
+    ? undefined
+    : resolveVariablesArg(plan.variablesArg, plan.variablesFileArg);
   if (!plan.useDocker) await refuseLowDiskBeforeBrowserDownload(plan);
   const browserPath = plan.useDocker
     ? undefined
@@ -113,13 +116,12 @@ export async function executeRenderPlan(
     return;
   }
 
-  const variables = resolveVariablesArg(plan.variablesArg, plan.variablesFileArg);
   if (variables && Object.keys(variables).length > 0) {
     const issues = validateVariablesAgainstProject(plan.renderTarget, variables);
-    reportVariableIssues(issues, { strict: plan.strictVariables, quiet: plan.quiet });
+    reportVariableIssues(issues, { strict: plan.strictVariables, quiet: plan.effectiveQuiet });
   }
 
-  if (plan.proresProfile && !PRORES_PROFILES[plan.proresProfile].alpha && !plan.quiet) {
+  if (plan.proresProfile && !PRORES_PROFILES[plan.proresProfile].alpha && !plan.effectiveQuiet) {
     console.log(
       c.dim(`ProRes ${plan.proresProfile} has no alpha channel: transparent areas render black.`),
     );
@@ -165,7 +167,7 @@ export function renderOptionsFromPlan(
     bufferSize: plan.bufferSize,
     videoFrameFormat: plan.videoFrameFormat,
     pageMotionBlur: plan.pageMotionBlur,
-    quiet: plan.quiet,
+    quiet: plan.effectiveQuiet,
     browserPath,
     debug: plan.debug,
     resumeSegments: plan.resumeSegments,
 
@@ -585,7 +585,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
     keepSegments: args["keep-segments"] ?? false,
     bestEffort: args["best-effort"] ?? true,
     batchJson,
-    effectiveQuiet: quiet || (batchPath != null && batchJson),
+    effectiveQuiet: quiet || batchJson,
     strictAll: args["strict-all"] ?? false,
     strictErrors: (args.strict ?? false) || (args["strict-all"] ?? false),
     crf,