From 0ddbcaf9048fba33a15d7246f413162d148b6e02 Mon Sep 17 00:00:00 2001
From: szdziedzic <szymon@expo.dev>
Date: Wed, 5 Aug 2026 14:09:01 +0200
Subject: [PATCH 1/4] feat: add scale-only screenshot sizing

---
 .../RunnerTests+CommandExecution.swift        |  12 +-
 .../RunnerTests+Models.swift                  |   1 -
 .../RunnerTests+ScreenRecorder.swift          |  24 +-
 .../RecordingScripts/recording-resize.swift   | 225 ------------------
 apple/runner/RUNNER_PROTOCOL.md               |   2 +-
 .../src/internal/__tests__/script.test.ts     |  12 +-
 .../ad-script/src/internal/script-utils.ts    |   3 -
 packages/ad-script/src/internal/script.ts     |   8 -
 packages/contracts/src/client-capture.ts      |   2 +-
 .../contracts/src/client-observability.ts     |   1 -
 packages/contracts/src/client-request.ts      |   1 -
 packages/contracts/src/screenshot.ts          |  91 +++++--
 scripts/integration-progress-model.ts         |   2 +-
 scripts/layering/facade-symbols.ts            |   2 +
 src/__tests__/cli-client-commands.test.ts     |   6 +-
 src/__tests__/cli-config.test.ts              |  24 ++
 src/__tests__/client.test.ts                  |  23 ++
 src/backend.ts                                |   1 -
 src/cli-schema/cli-config.ts                  |   2 +-
 src/cli-schema/option-schema.test.ts          |   6 +
 .../__tests__/args-parse-interaction.test.ts  |  21 +-
 .../__tests__/cli-help-command-usage.test.ts  |   4 +-
 src/cli/parser/args.ts                        |   5 +-
 src/cli/parser/cli-help.ts                    |   6 +-
 src/commands/capture/index.test.ts            |   6 +-
 src/commands/capture/runtime/screenshot.ts    |   8 +-
 .../capture/screenshot-options.test.ts        |  30 ++-
 src/commands/capture/screenshot.ts            |  23 +-
 src/commands/cli-grammar/flag-types.ts        |   2 +-
 src/commands/command-flags.ts                 |   1 -
 src/commands/command-input.ts                 |  33 ++-
 src/commands/recording/index.test.ts          |   2 -
 src/commands/recording/index.ts               |   8 +-
 .../recording/runtime/recording.test.ts       |   2 -
 src/commands/recording/runtime/recording.ts   |   9 -
 src/commands/runtime-types.ts                 |   2 +-
 src/daemon/__tests__/context.test.ts          |   4 +-
 .../request-router-screenshot.test.ts         |  12 +-
 src/daemon/__tests__/session-store.test.ts    |  10 +-
 ...cord-trace-ios-simulator-recording.test.ts |   1 -
 .../__tests__/record-trace-ios.test.ts        |   1 -
 .../handlers/__tests__/record-trace.test.ts   | 157 ++----------
 .../handlers/record-trace-android-recovery.ts |   2 -
 src/daemon/handlers/record-trace-android.ts   |  83 +------
 .../record-trace-ios-simulator-recording.ts   |  21 --
 src/daemon/handlers/record-trace-ios.ts       |   2 -
 .../record-trace-recording-backends.ts        |   1 -
 src/daemon/handlers/record-trace-recording.ts |  33 +--
 src/daemon/handlers/record-trace-types.ts     |   8 +-
 src/daemon/request-generic-dispatch.ts        |   2 +-
 src/daemon/session-event-action.ts            |   4 +-
 src/daemon/types.ts                           |   1 -
 .../core/__tests__/runner-client.test.ts      |   2 -
 .../apple/core/runner/runner-contract.ts      |   1 -
 src/recording/__tests__/overlay.test.ts       |  28 +--
 .../__tests__/recording-scripts.test.ts       |  12 -
 src/recording/overlay.ts                      |  26 --
 src/utils/__tests__/png-resize.test.ts        |  30 +--
 src/utils/png-resize.ts                       |  36 +--
 src/utils/screenshot-density.ts               |   4 +-
 src/utils/source-value.test.ts                |  13 +
 src/utils/source-value.ts                     |   6 +-
 .../live-capture-scenario.ts                  |   4 +-
 .../live-observability-scenario.ts            |   2 -
 .../ios-simulator-e2e/live-runner.ts          |   4 +-
 .../integration/live-device-e2e/assertions.ts |   2 +-
 .../android-recording.test.ts                 |  24 +-
 .../provider-scenarios/assertions.ts          |   6 +
 .../ios-record-trace.test.ts                  |   4 +-
 .../provider-scenarios/macos-desktop.test.ts  |  32 ++-
 .../macos-recording.test.ts                   |   2 -
 website/docs/docs/client-api.md               |   4 +-
 website/docs/docs/commands.md                 |  10 +-
 website/docs/docs/configuration.md            |   6 +-
 74 files changed, 403 insertions(+), 807 deletions(-)
 delete mode 100644 apple/runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift

diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 3446c5e10c..148ec37caa 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -1475,24 +1475,18 @@ extension RunnerTests {
       if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
         return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
       }
-      if let requestedMaxSize = command.maxSize, requestedMaxSize < 1 {
-        return Response(ok: false, error: ErrorPayload(message: "recordStart maxSize must be a positive integer"))
-      }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
         let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
-        let maxSizeLabel = command.maxSize.map(String.init) ?? "native"
         NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ maxSize=%@",
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
           requestedOutPath,
           resolvedOutPath,
-          fpsLabel,
-          maxSizeLabel
+          fpsLabel
         )
         let recorder = ScreenRecorder(
           outputPath: resolvedOutPath,
-          fps: command.fps.map { Int32($0) },
-          maxSize: command.maxSize
+          fps: command.fps.map { Int32($0) }
         )
         try recorder.start { [weak self] in
           return self?.captureRunnerFrame()
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index d153acfb71..feb3eff78b 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -136,7 +136,6 @@ struct Command: Codable {
   let gesturePlan: RunnerGesturePlan?
   let outPath: String?
   let fps: Int?
-  let maxSize: Int?
   let interactiveOnly: Bool?
   let depth: Int?
   let scope: String?
diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
index 668489454a..40b96ec935 100644
--- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
+++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
@@ -7,7 +7,6 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
-    private let maxSize: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -26,10 +25,9 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?, maxSize: Int?) {
+    init(outputPath: String, fps: Int32?) {
       self.outputPath = outputPath
       self.fps = fps
-      self.maxSize = maxSize
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -50,7 +48,7 @@ extension RunnerTests {
       while Date() < bootstrapDeadline {
         if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
-          dimensions = scaledDimensions(width: cgImage.width, height: cgImage.height)
+          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
@@ -261,23 +259,5 @@ extension RunnerTests {
       return pixelBuffer
     }
 
-    private func scaledDimensions(width: Int, height: Int) -> CGSize {
-      guard let maxSize, maxSize > 0 else {
-        return CGSize(width: width, height: height)
-      }
-      let longest = max(width, height)
-      guard longest > maxSize else {
-        return CGSize(width: width, height: height)
-      }
-      let scale = Double(maxSize) / Double(longest)
-      return CGSize(
-        width: scaledEvenDimension(width, scale: scale),
-        height: scaledEvenDimension(height, scale: scale)
-      )
-    }
-
-    private func scaledEvenDimension(_ value: Int, scale: Double) -> Int {
-      max(2, Int((Double(value) * scale / 2.0).rounded()) * 2)
-    }
   }
 }
diff --git a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
deleted file mode 100644
index 1557617bd9..0000000000
--- a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
+++ /dev/null
@@ -1,225 +0,0 @@
-import AVFoundation
-import Foundation
-
-enum ResizeError: Error, CustomStringConvertible {
-  case invalidArgs(String)
-  case missingVideoTrack
-  case exportFailed(String)
-
-  var description: String {
-    switch self {
-    case .invalidArgs(let message):
-      return message
-    case .missingVideoTrack:
-      return "Input video does not contain a video track."
-    case .exportFailed(let message):
-      return message
-    }
-  }
-}
-
-do {
-  try run()
-} catch {
-  fputs("recording-resize: \(error)\n", stderr)
-  exit(1)
-}
-
-func run() throws {
-  let arguments = Array(CommandLine.arguments.dropFirst())
-  let parsedArgs = try parseArguments(arguments)
-  let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
-  let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
-
-  if FileManager.default.fileExists(atPath: outputURL.path) {
-    try FileManager.default.removeItem(at: outputURL)
-  }
-
-  let asset = AVURLAsset(url: inputURL)
-  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
-    throw ResizeError.missingVideoTrack
-  }
-
-  let sourceRenderSize = resolvedRenderSize(for: sourceVideoTrack)
-  if max(sourceRenderSize.width, sourceRenderSize.height) <= CGFloat(parsedArgs.maxSize) {
-    try FileManager.default.copyItem(at: inputURL, to: outputURL)
-    return
-  }
-
-  let renderSize = scaledRenderSize(sourceRenderSize, maxSize: parsedArgs.maxSize)
-  let composition = AVMutableComposition()
-  let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
-
-  guard let compositionVideoTrack = composition.addMutableTrack(
-    withMediaType: .video,
-    preferredTrackID: kCMPersistentTrackID_Invalid
-  ) else {
-    throw ResizeError.exportFailed("Failed to create composition video track.")
-  }
-  try compositionVideoTrack.insertTimeRange(fullRange, of: sourceVideoTrack, at: .zero)
-
-  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
-     let compositionAudioTrack = composition.addMutableTrack(
-       withMediaType: .audio,
-       preferredTrackID: kCMPersistentTrackID_Invalid
-     ) {
-    try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
-  }
-
-  let scale = renderSize.width / sourceRenderSize.width
-  let videoComposition = AVMutableVideoComposition()
-  videoComposition.renderSize = renderSize
-  videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
-
-  let instruction = AVMutableVideoCompositionInstruction()
-  instruction.timeRange = fullRange
-  let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
-  // Scale the full preferred transform (including translation) to match the smaller render canvas.
-  let scaledTransform = scaledPreferredTransform(sourceVideoTrack.preferredTransform, scale: scale)
-  layerInstruction.setTransform(scaledTransform, at: .zero)
-  instruction.layerInstructions = [layerInstruction]
-  videoComposition.instructions = [instruction]
-
-  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
-  guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
-    throw ResizeError.exportFailed("Failed to create export session.")
-  }
-
-  exporter.outputURL = outputURL
-  exporter.outputFileType = .mp4
-  exporter.videoComposition = videoComposition
-  exporter.shouldOptimizeForNetworkUse = true
-
-  let semaphore = DispatchSemaphore(value: 0)
-  exporter.exportAsynchronously {
-    semaphore.signal()
-  }
-  if semaphore.wait(timeout: .now() + 120) == .timedOut {
-    exporter.cancelExport()
-    throw ResizeError.exportFailed("Resize export timed out.")
-  }
-
-  if exporter.status != .completed {
-    throw ResizeError.exportFailed(exporter.error?.localizedDescription ?? "Resize export failed.")
-  }
-}
-
-enum ExportQuality: String {
-  case medium
-  case high
-}
-
-func parseArguments(
-  _ arguments: [String]
-) throws -> (inputPath: String, outputPath: String, maxSize: Int, exportQuality: ExportQuality) {
-  var inputPath: String?
-  var outputPath: String?
-  var maxSize: Int?
-  // Export quality defaults to medium so re-encoded recordings stay fast by default.
-  // Pass --quality high to opt into a slower highest-quality export.
-  var exportQuality: ExportQuality = .medium
-  var index = 0
-
-  while index < arguments.count {
-    let argument = arguments[index]
-    let nextIndex = index + 1
-    switch argument {
-    case "--input":
-      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--input requires a value") }
-      inputPath = arguments[nextIndex]
-      index += 2
-    case "--output":
-      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--output requires a value") }
-      outputPath = arguments[nextIndex]
-      index += 2
-    case "--max-size":
-      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--max-size requires a value") }
-      guard let parsed = Int(arguments[nextIndex]), parsed >= 1 else {
-        throw ResizeError.invalidArgs("--max-size must be a positive integer")
-      }
-      maxSize = parsed
-      index += 2
-    case "--quality":
-      guard nextIndex < arguments.count else {
-        throw ResizeError.invalidArgs("--quality requires a value")
-      }
-      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
-        throw ResizeError.invalidArgs("--quality must be one of: medium, high")
-      }
-      exportQuality = parsed
-      index += 2
-    default:
-      throw ResizeError.invalidArgs("Unknown argument: \(argument)")
-    }
-  }
-
-  guard let inputPath, let outputPath, let maxSize else {
-    throw ResizeError.invalidArgs(
-      "Usage: recording-resize.swift --input <video> --output <video> --max-size <px> [--quality <medium|high>]"
-    )
-  }
-  return (inputPath, outputPath, maxSize, exportQuality)
-}
-
-func exportPresetName(
-  for exportQuality: ExportQuality,
-  compatibleWith asset: AVAsset
-) -> String {
-  switch exportQuality {
-  case .high:
-    return AVAssetExportPresetHighestQuality
-  case .medium:
-    // Mirror the touch-overlay export: prefer the faster medium preset, falling back to
-    // highest quality only when medium is not available for this composition.
-    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
-    return compatible.contains(AVAssetExportPresetMediumQuality)
-      ? AVAssetExportPresetMediumQuality
-      : AVAssetExportPresetHighestQuality
-  }
-}
-
-func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
-  let transformed = track.naturalSize.applying(track.preferredTransform)
-  return CGSize(width: abs(transformed.width), height: abs(transformed.height))
-}
-
-func scaledRenderSize(_ renderSize: CGSize, maxSize: Int) -> CGSize {
-  let longest = max(renderSize.width, renderSize.height)
-  guard longest > CGFloat(maxSize) else { return renderSize }
-  let scale = CGFloat(maxSize) / longest
-  return CGSize(
-    width: scaledDimension(renderSize.width, scale: scale),
-    height: scaledDimension(renderSize.height, scale: scale)
-  )
-}
-
-func scaledDimension(_ value: CGFloat, scale: CGFloat) -> CGFloat {
-  let evenValue = Int((Double(value * scale) / 2.0).rounded()) * 2
-  return CGFloat(max(2, evenValue))
-}
-
-func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
-  let minFrameDuration = track.minFrameDuration
-  if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
-    return minFrameDuration
-  }
-
-  let nominalFrameRate = track.nominalFrameRate
-  if nominalFrameRate > 0 {
-    let timescale = Int32(max(1, round(nominalFrameRate)))
-    return CMTime(value: 1, timescale: timescale)
-  }
-
-  return CMTime(value: 1, timescale: 60)
-}
-
-func scaledPreferredTransform(_ transform: CGAffineTransform, scale: CGFloat) -> CGAffineTransform {
-  CGAffineTransform(
-    a: transform.a * scale,
-    b: transform.b * scale,
-    c: transform.c * scale,
-    d: transform.d * scale,
-    tx: transform.tx * scale,
-    ty: transform.ty * scale
-  )
-}
diff --git a/apple/runner/RUNNER_PROTOCOL.md b/apple/runner/RUNNER_PROTOCOL.md
index 407e5dfef4..d23a2d566d 100644
--- a/apple/runner/RUNNER_PROTOCOL.md
+++ b/apple/runner/RUNNER_PROTOCOL.md
@@ -32,7 +32,7 @@ Examples:
 ```
 
 ```json
-{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "maxSize": 720 }
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }
 ```
 
 ```json
diff --git a/packages/ad-script/src/internal/__tests__/script.test.ts b/packages/ad-script/src/internal/__tests__/script.test.ts
index 15b56a7216..612cee029f 100644
--- a/packages/ad-script/src/internal/__tests__/script.test.ts
+++ b/packages/ad-script/src/internal/__tests__/script.test.ts
@@ -50,14 +50,12 @@ test('formatPortableActionLine preserves inline open runtime hints', () => {
   );
 });
 
-test('record replay script parses fps, max-size, quality, and hide-touches flags', () => {
-  const script =
-    'record start "./capture.mp4" --fps 24 --max-size 1024 --quality high --hide-touches\n';
+test('record replay script parses fps, quality, and hide-touches flags', () => {
+  const script = 'record start "./capture.mp4" --fps 24 --quality high --hide-touches\n';
   const parsed = parseReplayScriptDetailed(script).actions;
 
   assert.deepEqual(parsed[0]?.positionals, ['start', './capture.mp4']);
   assert.equal(parsed[0]?.flags.fps, 24);
-  assert.equal(parsed[0]?.flags.screenshotMaxSize, 1024);
   assert.equal(parsed[0]?.flags.quality, 'high');
   assert.equal(parsed[0]?.flags.hideTouches, true);
 });
@@ -71,7 +69,7 @@ test('screenshot replay script round-trips screenshot flags', () => {
       flags: {
         screenshotPixelDensity: 2,
         screenshotFullscreen: true,
-        screenshotMaxSize: 1024,
+        screenshotScale: 0.3,
         screenshotNoStabilize: true,
       },
     },
@@ -80,14 +78,14 @@ test('screenshot replay script round-trips screenshot flags', () => {
   const script = formatReplayScriptForTest(actions);
   assert.match(
     script,
-    /screenshot "\.\/page\.png" --pixel-density 2 --fullscreen --max-size 1024 --no-stabilize/,
+    /screenshot "\.\/page\.png" --pixel-density 2 --fullscreen --scale 0.3 --no-stabilize/,
   );
 
   const parsed = parseReplayScriptDetailed(script).actions;
   assert.deepEqual(parsed[0]?.positionals, ['./page.png']);
   assert.equal(parsed[0]?.flags.screenshotPixelDensity, 2);
   assert.equal(parsed[0]?.flags.screenshotFullscreen, true);
-  assert.equal(parsed[0]?.flags.screenshotMaxSize, 1024);
+  assert.equal(parsed[0]?.flags.screenshotScale, 0.3);
   assert.equal(parsed[0]?.flags.screenshotNoStabilize, true);
 });
 
diff --git a/packages/ad-script/src/internal/script-utils.ts b/packages/ad-script/src/internal/script-utils.ts
index ad5b6f3b35..666ca5ec7d 100644
--- a/packages/ad-script/src/internal/script-utils.ts
+++ b/packages/ad-script/src/internal/script-utils.ts
@@ -202,9 +202,6 @@ export function appendRecordActionScriptArgs(parts: string[], action: SessionAct
   if (typeof action.flags?.fps === 'number') {
     parts.push('--fps', String(action.flags.fps));
   }
-  if (typeof action.flags?.screenshotMaxSize === 'number') {
-    parts.push('--max-size', String(action.flags.screenshotMaxSize));
-  }
   if (typeof action.flags?.quality === 'number' || typeof action.flags?.quality === 'string') {
     parts.push('--quality', String(action.flags.quality));
   }
diff --git a/packages/ad-script/src/internal/script.ts b/packages/ad-script/src/internal/script.ts
index da224eee84..b9d10553b2 100644
--- a/packages/ad-script/src/internal/script.ts
+++ b/packages/ad-script/src/internal/script.ts
@@ -436,14 +436,6 @@ function parseReplayScriptLine(line: string): SessionAction | null {
         index += 1;
         continue;
       }
-      if (token === '--max-size' && index + 1 < args.length) {
-        const parsedMaxSize = Number(args[index + 1]);
-        if (Number.isFinite(parsedMaxSize)) {
-          action.flags.screenshotMaxSize = Math.floor(parsedMaxSize);
-        }
-        index += 1;
-        continue;
-      }
       positionals.push(token);
     }
     action.positionals = positionals;
diff --git a/packages/contracts/src/client-capture.ts b/packages/contracts/src/client-capture.ts
index 848ac098ad..aa02ebec5c 100644
--- a/packages/contracts/src/client-capture.ts
+++ b/packages/contracts/src/client-capture.ts
@@ -61,7 +61,7 @@ export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
   overlayRefs?: boolean;
   pixelDensity?: number;
   fullscreen?: boolean;
-  maxSize?: number;
+  scale?: number;
   stabilize?: boolean;
   normalizeStatusBar?: boolean;
   surface?: SessionSurface;
diff --git a/packages/contracts/src/client-observability.ts b/packages/contracts/src/client-observability.ts
index 41754c457d..07442b998e 100644
--- a/packages/contracts/src/client-observability.ts
+++ b/packages/contracts/src/client-observability.ts
@@ -45,7 +45,6 @@ export type RecordOptions = AgentDeviceRequestOverrides & {
   action: 'start' | 'stop';
   path?: string;
   fps?: number;
-  maxSize?: number;
   quality?: RecordingExportQuality;
   hideTouches?: boolean;
   recordingScope?: RecordingScope;
diff --git a/packages/contracts/src/client-request.ts b/packages/contracts/src/client-request.ts
index 0b4f23fc99..02cdc9e349 100644
--- a/packages/contracts/src/client-request.ts
+++ b/packages/contracts/src/client-request.ts
@@ -31,7 +31,6 @@ export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   forceFull?: boolean;
   count?: number;
   fps?: number;
-  maxSize?: number;
   recordingScope?: RecordingScope;
   quality?: RecordingExportQuality;
   hideTouches?: boolean;
diff --git a/packages/contracts/src/screenshot.ts b/packages/contracts/src/screenshot.ts
index 8576c4f1f0..916ff1464d 100644
--- a/packages/contracts/src/screenshot.ts
+++ b/packages/contracts/src/screenshot.ts
@@ -5,7 +5,7 @@ export const SCREENSHOT_COMMAND_FLAG_KEYS = [
   'overlayRefs',
   'screenshotPixelDensity',
   'screenshotFullscreen',
-  'screenshotMaxSize',
+  'screenshotScale',
   'screenshotNoStabilize',
   'screenshotNormalizeStatusBar',
 ] as const;
@@ -13,7 +13,7 @@ export const SCREENSHOT_COMMAND_FLAG_KEYS = [
 export const SCREENSHOT_ACTION_FLAG_KEYS = [
   'screenshotPixelDensity',
   'screenshotFullscreen',
-  'screenshotMaxSize',
+  'screenshotScale',
   'screenshotNoStabilize',
   'screenshotNormalizeStatusBar',
 ] as const;
@@ -23,8 +23,9 @@ type ScreenshotSpecificFlagKey = (typeof SCREENSHOT_ACTION_FLAG_KEYS)[number];
 type ScreenshotSpecificFlagDefinition = {
   key: ScreenshotSpecificFlagKey;
   names: readonly string[];
-  type: 'boolean' | 'int';
+  type: 'boolean' | 'int' | 'number';
   min?: number;
+  max?: number;
   usageLabel: string;
   usageDescription: string;
 };
@@ -48,12 +49,14 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
       'Screenshot: on web capture the full page; on macOS app sessions capture the full desktop instead of the app window',
   },
   {
-    key: 'screenshotMaxSize',
-    names: ['--max-size'],
-    type: 'int',
-    min: 1,
-    usageLabel: '--max-size <px>',
-    usageDescription: 'Screenshot/record: downscale so the longest edge is at most <px>',
+    key: 'screenshotScale',
+    names: ['--scale'],
+    type: 'number',
+    min: 0.01,
+    max: 1,
+    usageLabel: '--scale <0.01-1>',
+    usageDescription:
+      'Screenshot: resize both dimensions by this factor (or use AGENT_DEVICE_SCREENSHOT_SCALE)',
   },
   {
     key: 'screenshotNoStabilize',
@@ -85,7 +88,16 @@ const SCREENSHOT_SCRIPT_INT_FLAGS = [
     key: 'screenshotPixelDensity',
     label: 'screenshot --pixel-density',
   },
-  { token: '--max-size', key: 'screenshotMaxSize', label: 'screenshot --max-size' },
+] as const;
+
+const SCREENSHOT_SCRIPT_NUMBER_FLAGS = [
+  {
+    token: '--scale',
+    key: 'screenshotScale',
+    label: 'screenshot --scale',
+    min: 0.01,
+    max: 1,
+  },
 ] as const;
 
 export type ScreenshotRequestFlags = {
@@ -93,7 +105,7 @@ export type ScreenshotRequestFlags = {
   overlayRefs?: boolean;
   screenshotPixelDensity?: number;
   screenshotFullscreen?: boolean;
-  screenshotMaxSize?: number;
+  screenshotScale?: number;
   screenshotNoStabilize?: boolean;
   screenshotNormalizeStatusBar?: boolean;
 };
@@ -110,7 +122,7 @@ export type ScreenshotRuntimeFlags = Pick<
   ScreenshotRequestFlags,
   | 'screenshotPixelDensity'
   | 'screenshotFullscreen'
-  | 'screenshotMaxSize'
+  | 'screenshotScale'
   | 'screenshotNoStabilize'
   | 'screenshotNormalizeStatusBar'
 >;
@@ -119,7 +131,7 @@ export type ScreenshotPublicOptions = {
   overlayRefs?: boolean;
   pixelDensity?: number;
   fullscreen?: boolean;
-  maxSize?: number;
+  scale?: number;
   stabilize?: boolean;
   normalizeStatusBar?: boolean;
 };
@@ -128,7 +140,7 @@ export type ScreenshotRuntimeOptions = {
   overlayRefs?: boolean;
   pixelDensity?: number;
   fullscreen?: boolean;
-  maxSize?: number;
+  scale?: number;
   stabilize?: boolean;
   normalizeStatusBar?: boolean;
 };
@@ -140,7 +152,7 @@ export function screenshotOptionsFromFlags(
     overlayRefs: flags?.overlayRefs,
     pixelDensity: flags?.screenshotPixelDensity,
     fullscreen: flags?.screenshotFullscreen,
-    maxSize: flags?.screenshotMaxSize,
+    scale: flags?.screenshotScale,
     stabilize: flags?.screenshotNoStabilize ? false : undefined,
     normalizeStatusBar: flags?.screenshotNormalizeStatusBar,
   });
@@ -153,7 +165,7 @@ export function screenshotFlagsFromOptions(
     overlayRefs: options.overlayRefs,
     screenshotPixelDensity: options.screenshotPixelDensity ?? options.pixelDensity,
     screenshotFullscreen: options.screenshotFullscreen ?? options.fullscreen,
-    screenshotMaxSize: options.screenshotMaxSize ?? options.maxSize,
+    screenshotScale: options.screenshotScale,
     screenshotNoStabilize:
       options.screenshotNoStabilize ?? (options.stabilize === false ? true : undefined),
     screenshotNormalizeStatusBar:
@@ -161,6 +173,24 @@ export function screenshotFlagsFromOptions(
   });
 }
 
+export function screenshotFlagsFromPublicOptions(
+  options: ScreenshotPublicOptions & Partial<ScreenshotRequestFlags> = {},
+): Partial<ScreenshotRequestFlags> {
+  return screenshotFlagsFromOptions({
+    ...options,
+    screenshotScale: options.screenshotScale ?? options.scale,
+  });
+}
+
+export function validateScreenshotScale(options: Pick<ScreenshotPublicOptions, 'scale'>): void {
+  if (
+    options.scale !== undefined &&
+    (!Number.isFinite(options.scale) || options.scale < 0.01 || options.scale > 1)
+  ) {
+    throw new AppError('INVALID_ARGS', 'screenshot scale must be between 0.01 and 1');
+  }
+}
+
 export function appendScreenshotScriptFlags(
   parts: string[],
   flags: Partial<ScreenshotRequestFlags> | undefined,
@@ -169,8 +199,8 @@ export function appendScreenshotScriptFlags(
     parts.push('--pixel-density', String(flags.screenshotPixelDensity));
   }
   if (flags?.screenshotFullscreen) parts.push('--fullscreen');
-  if (typeof flags?.screenshotMaxSize === 'number') {
-    parts.push('--max-size', String(flags.screenshotMaxSize));
+  if (typeof flags?.screenshotScale === 'number') {
+    parts.push('--scale', String(flags.screenshotScale));
   }
   if (flags?.screenshotNoStabilize) parts.push('--no-stabilize');
   if (flags?.screenshotNormalizeStatusBar) parts.push('--normalize-status-bar');
@@ -185,7 +215,8 @@ export function readScreenshotScriptFlag(params: {
   const token = args[index];
   return (
     readScreenshotBooleanScriptFlag(token, flags, index) ??
-    readScreenshotIntScriptFlag({ args, index, flags, token }) ?? { handled: false }
+    readScreenshotIntScriptFlag({ args, index, flags, token }) ??
+    readScreenshotNumberScriptFlag({ args, index, flags, token }) ?? { handled: false }
   );
 }
 
@@ -214,11 +245,29 @@ function readScreenshotIntScriptFlag(params: {
 }): { handled: true; nextIndex: number } | undefined {
   const definition = SCREENSHOT_SCRIPT_INT_FLAGS.find((entry) => entry.token === params.token);
   if (!definition) return undefined;
-  const value = params.args[params.index + 1];
-  const parsed = value === undefined ? NaN : Number(value);
+  const parsed = Number(params.args[params.index + 1]);
   if (!Number.isInteger(parsed) || parsed < 1) {
     throw new AppError('INVALID_ARGS', `${definition.label} requires a positive integer`);
   }
   params.flags[definition.key] = parsed;
   return { handled: true, nextIndex: params.index + 1 };
 }
+
+function readScreenshotNumberScriptFlag(params: {
+  args: readonly string[];
+  index: number;
+  flags: Partial<ScreenshotRequestFlags>;
+  token: string | undefined;
+}): { handled: true; nextIndex: number } | undefined {
+  const definition = SCREENSHOT_SCRIPT_NUMBER_FLAGS.find((entry) => entry.token === params.token);
+  if (!definition) return undefined;
+  const parsed = Number(params.args[params.index + 1]);
+  if (!Number.isFinite(parsed) || parsed < definition.min || parsed > definition.max) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `${definition.label} requires a number from ${definition.min} to ${definition.max}`,
+    );
+  }
+  params.flags[definition.key] = parsed;
+  return { handled: true, nextIndex: params.index + 1 };
+}
diff --git a/scripts/integration-progress-model.ts b/scripts/integration-progress-model.ts
index e36a59fc42..84c4f75aeb 100644
--- a/scripts/integration-progress-model.ts
+++ b/scripts/integration-progress-model.ts
@@ -172,7 +172,7 @@ function summarizeProviderScenarioFlagCoverage(files) {
     ['out', 'artifact output path plumbing'],
     ['overlayRefs', 'screenshot ref overlay annotation'],
     ['screenshotFullscreen', 'screenshot full-screen capture mode'],
-    ['screenshotMaxSize', 'screenshot max-size post-processing'],
+    ['screenshotScale', 'screenshot proportional scaling post-processing'],
     ['screenshotNoStabilize', 'screenshot stabilization opt-out', ['stabilize']],
     ['restart', 'logs clear --restart workflow'],
     ['networkInclude', 'network dump include modes', ['include']],
diff --git a/scripts/layering/facade-symbols.ts b/scripts/layering/facade-symbols.ts
index 105e0ab9d5..d036020bb7 100644
--- a/scripts/layering/facade-symbols.ts
+++ b/scripts/layering/facade-symbols.ts
@@ -504,10 +504,12 @@ export const FACADE_SYMBOLS: readonly (readonly [string, readonly string[]])[] =
       'readSnapshotDiagnosticsSummary',
       'recordSnapshotTiming',
       'screenshotFlagsFromOptions',
+      'screenshotFlagsFromPublicOptions',
       'screenshotOptionsFromFlags',
       'snapshotCaptureAnnotationsFrom',
       'summarizeSnapshotDiagnostics',
       'summarizeSnapshotTimingSamples',
+      'validateScreenshotScale',
     ],
   ],
   [
diff --git a/src/__tests__/cli-client-commands.test.ts b/src/__tests__/cli-client-commands.test.ts
index 1d9352c8e1..dde6f5b649 100644
--- a/src/__tests__/cli-client-commands.test.ts
+++ b/src/__tests__/cli-client-commands.test.ts
@@ -432,7 +432,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
     | {
         path?: string;
         overlayRefs?: boolean;
-        maxSize?: number;
+        scale?: number;
         stabilize?: boolean;
       }
     | undefined;
@@ -457,7 +457,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
       help: false,
       version: false,
       overlayRefs: true,
-      screenshotMaxSize: 1024,
+      screenshotScale: 0.3,
       screenshotNoStabilize: true,
     },
     client,
@@ -467,7 +467,7 @@ test('screenshot forwards --overlay-refs to the client capture API', async () =>
   assert.deepEqual(observed, {
     path: '/tmp/screenshot.png',
     overlayRefs: true,
-    maxSize: 1024,
+    scale: 0.3,
     stabilize: false,
   });
 });
diff --git a/src/__tests__/cli-config.test.ts b/src/__tests__/cli-config.test.ts
index b691c5a5d1..15844410fe 100644
--- a/src/__tests__/cli-config.test.ts
+++ b/src/__tests__/cli-config.test.ts
@@ -42,6 +42,30 @@ test('CLI merges config defaults with precedence user < project < env < CLI', as
   fs.rmSync(root, { recursive: true, force: true });
 });
 
+test('screenshot scale supports env defaults with CLI precedence', async () => {
+  const { root, home, project } = makeTempWorkspace();
+
+  const fromEnv = await runCliCapture(['screenshot', 'env.png', '--json'], {
+    cwd: project,
+    env: { HOME: home, AGENT_DEVICE_SCREENSHOT_SCALE: '0.3' },
+    defaultResponse: { ok: true, data: { path: 'env.png' } },
+  });
+
+  assert.equal(fromEnv.code, null);
+  assert.equal(fromEnv.calls[0]?.flags?.screenshotScale, 0.3);
+
+  const fromCli = await runCliCapture(['screenshot', 'cli.png', '--scale', '0.5', '--json'], {
+    cwd: project,
+    env: { HOME: home, AGENT_DEVICE_SCREENSHOT_SCALE: '0.3' },
+    defaultResponse: { ok: true, data: { path: 'cli.png' } },
+  });
+
+  assert.equal(fromCli.code, null);
+  assert.equal(fromCli.calls[0]?.flags?.screenshotScale, 0.5);
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
 test('config can set appsFilter through canonical enum values', async () => {
   const { root, home, project } = makeTempWorkspace();
   fs.mkdirSync(path.join(home, '.agent-device'), { recursive: true });
diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts
index 1e366534b2..fa818dacfa 100644
--- a/src/__tests__/client.test.ts
+++ b/src/__tests__/client.test.ts
@@ -1218,6 +1218,29 @@ test('capture.screenshot normalizes the default-level result (unchanged)', async
   assert.deepEqual(result.identifiers, { session: 'qa' });
 });
 
+test('capture.screenshot forwards public scale as the screenshot sizing flag', async () => {
+  const setup = createTransport(async (req) => {
+    assert.equal(req.command, 'screenshot');
+    assert.equal(req.flags?.screenshotScale, 0.3);
+    return { ok: true, data: { path: '/tmp/shot.png' } };
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await client.capture.screenshot({ scale: 0.3 });
+});
+
+test('gesture scale does not leak into screenshot sizing flags', async () => {
+  const setup = createTransport(async (req) => {
+    assert.equal(req.command, 'gesture');
+    assert.deepEqual(req.input, { kind: 'pinch', scale: 0.8 });
+    assert.equal(req.flags?.screenshotScale, undefined);
+    return { ok: true, data: {} };
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await client.interactions.pinch({ scale: 0.8 });
+});
+
 test('capture.snapshot passes a digest (non-default level) payload through unnormalized', async () => {
   const digest = {
     nodeCount: 3,
diff --git a/src/backend.ts b/src/backend.ts
index 98a6f67593..2f2e8ff9c4 100644
--- a/src/backend.ts
+++ b/src/backend.ts
@@ -290,7 +290,6 @@ export type BackendInstallResult = Record<string, unknown> & {
 export type BackendRecordingOptions = {
   outPath?: string;
   fps?: number;
-  maxSize?: number;
   quality?: RecordingExportQuality;
   showTouches?: boolean;
 };
diff --git a/src/cli-schema/cli-config.ts b/src/cli-schema/cli-config.ts
index 7b5522d04b..57bf550358 100644
--- a/src/cli-schema/cli-config.ts
+++ b/src/cli-schema/cli-config.ts
@@ -67,7 +67,7 @@ const PROJECT_CONFIG_FLAG_KEYS = new Set<FlagKey>([
   'snapshotForceFull',
   'screenshotPixelDensity',
   'screenshotFullscreen',
-  'screenshotMaxSize',
+  'screenshotScale',
   'screenshotNoStabilize',
   'screenshotNormalizeStatusBar',
   'overlayRefs',
diff --git a/src/cli-schema/option-schema.test.ts b/src/cli-schema/option-schema.test.ts
index 7237ca571d..f8963c81eb 100644
--- a/src/cli-schema/option-schema.test.ts
+++ b/src/cli-schema/option-schema.test.ts
@@ -56,6 +56,12 @@ test('option schema exposes env defaults and command scoping', () => {
   assert.equal(snapshotDepth.supportsCommand('snapshot'), true);
   assert.equal(snapshotDepth.supportsCommand('open'), false);
 
+  const screenshotScale = getOptionSpec('screenshotScale');
+  assert.ok(screenshotScale);
+  assert.deepEqual(screenshotScale.env.names, ['AGENT_DEVICE_SCREENSHOT_SCALE']);
+  assert.equal(screenshotScale.supportsCommand('screenshot'), true);
+  assert.equal(screenshotScale.supportsCommand('record'), false);
+
   const metroBearerToken = getOptionSpec('metroBearerToken');
   assert.ok(metroBearerToken);
   assert.deepEqual(metroBearerToken.env.names, ['AGENT_DEVICE_METRO_BEARER_TOKEN']);
diff --git a/src/cli/parser/__tests__/args-parse-interaction.test.ts b/src/cli/parser/__tests__/args-parse-interaction.test.ts
index 9fbe69fe3e..912509e50c 100644
--- a/src/cli/parser/__tests__/args-parse-interaction.test.ts
+++ b/src/cli/parser/__tests__/args-parse-interaction.test.ts
@@ -211,13 +211,14 @@ test('parseArgs recognizes record --quality flag', () => {
   assert.equal(parsed.flags.quality, 'high');
 });
 
-test('parseArgs recognizes record --max-size flag', () => {
-  const parsed = parseArgs(['record', 'start', './capture.mp4', '--max-size', '1024'], {
-    strictFlags: true,
-  });
-  assert.equal(parsed.command, 'record');
-  assert.deepEqual(parsed.positionals, ['start', './capture.mp4']);
-  assert.equal(parsed.flags.screenshotMaxSize, 1024);
+test('parseArgs rejects removed record --max-size flag', () => {
+  assert.throws(
+    () =>
+      parseArgs(['record', 'start', './capture.mp4', '--max-size', '1024'], {
+        strictFlags: true,
+      }),
+    /Unknown flag: --max-size/,
+  );
 });
 
 test('parseArgs recognizes record --hide-touches flag', () => {
@@ -248,8 +249,8 @@ test('parseArgs recognizes screenshot flags', () => {
       '--full',
       '-f',
       '--fullscreen',
-      '--max-size',
-      '1024',
+      '--scale',
+      '0.3',
       '--no-stabilize',
       '--normalize-status-bar',
     ],
@@ -261,7 +262,7 @@ test('parseArgs recognizes screenshot flags', () => {
   assert.deepEqual(parsed.positionals, ['page.png']);
   assert.equal(parsed.flags.screenshotPixelDensity, 2);
   assert.equal(parsed.flags.screenshotFullscreen, true);
-  assert.equal(parsed.flags.screenshotMaxSize, 1024);
+  assert.equal(parsed.flags.screenshotScale, 0.3);
   assert.equal(parsed.flags.screenshotNoStabilize, true);
   assert.equal(parsed.flags.screenshotNormalizeStatusBar, true);
 });
diff --git a/src/cli/parser/__tests__/cli-help-command-usage.test.ts b/src/cli/parser/__tests__/cli-help-command-usage.test.ts
index 72c8f9fc88..bd52f79a36 100644
--- a/src/cli/parser/__tests__/cli-help-command-usage.test.ts
+++ b/src/cli/parser/__tests__/cli-help-command-usage.test.ts
@@ -301,10 +301,10 @@ test('command usage shows record touch-overlay opt-out flag', async () => {
   if (help === null) throw new Error('Expected command help text');
   assert.match(
     help,
-    /record start \[path\] \[--scope <app\|device\|system>\] \[--fps <n>\] \[--max-size <px>\] \[--quality <medium\|high>\] \[--hide-touches\] \| record stop/,
+    /record start \[path\] \[--scope <app\|device\|system>\] \[--fps <n>\] \[--quality <medium\|high>\] \[--hide-touches\] \| record stop/,
   );
   assert.match(help, /--scope <app\|device\|system>/);
-  assert.match(help, /--max-size <px>/);
+  assert.doesNotMatch(help, /--max-size/);
   assert.match(help, /--quality <medium\|high>/);
   assert.match(help, /--hide-touches/);
   assert.match(help, /skip touch-overlay post-processing/);
diff --git a/src/cli/parser/args.ts b/src/cli/parser/args.ts
index 4346efbeca..29d3c0a51d 100644
--- a/src/cli/parser/args.ts
+++ b/src/cli/parser/args.ts
@@ -301,7 +301,10 @@ function parseFlagValue(
   if (typeof definition.max === 'number' && parsed > definition.max) {
     throw new AppError('INVALID_ARGS', `Invalid ${labelForFlag(token)}: ${value}`);
   }
-  return { value: Math.floor(parsed), consumeNext: inlineValue === undefined };
+  return {
+    value: definition.type === 'int' ? Math.floor(parsed) : parsed,
+    consumeNext: inlineValue === undefined,
+  };
 }
 
 function labelForFlag(token: string): string {
diff --git a/src/cli/parser/cli-help.ts b/src/cli/parser/cli-help.ts
index c40a0a273e..b1d214e9f9 100644
--- a/src/cli/parser/cli-help.ts
+++ b/src/cli/parser/cli-help.ts
@@ -118,6 +118,10 @@ const CONFIGURATION_LINES = [
 const ENVIRONMENT_LINES = [
   { label: 'AGENT_DEVICE_SESSION', description: 'Explicit session name' },
   { label: 'AGENT_DEVICE_PLATFORM', description: 'Default platform binding' },
+  {
+    label: 'AGENT_DEVICE_SCREENSHOT_SCALE',
+    description: 'Default screenshot scale factor',
+  },
   { label: 'AGENT_DEVICE_SESSION_LOCK', description: 'Bound-session conflict mode' },
   { label: 'AGENT_DEVICE_DAEMON_BASE_URL', description: 'Connect to remote daemon' },
   {
@@ -373,7 +377,7 @@ Validation and evidence:
     agent-device press 124 817
     agent-device snapshot -i
   Startup/CPU/memory/frame first pass: perf metrics --json (bare perf and metrics are aliases). Focused frame/jank health: perf frames --json. Memory-only sample: perf memory sample --json returns compact JSON with bounded top offenders. Heap/memgraph artifact escalation: perf memory snapshot --out heap.artifact; use --kind android-hprof on Android or --kind memgraph on supported Apple simulator/macOS app sessions. Android native profiling: perf cpu profile start|stop|report --kind simpleperf --out <path>; Android native traces: perf trace start|stop --kind perfetto --out <path>. Artifact collectors return compact state/path/size metadata only; raw heap/profile/trace files stay on disk. Treat native perf output as the agent evidence: for example, a Perfetto stop can return state=stopped, outPath=/tmp/app.perfetto-trace, sizeBytes=5392410, and method=adb-shell-perfetto while the 5.3 MB raw trace stays in the artifact. This is better than raw dumps for agents because it is stable, bounded, and keeps large artifacts out of context. heapprofd is deferred until Perfetto plumbing is available. Replay divergence and resume: a failing replay/test step returns REPLAY_DIVERGENCE with a bounded report (screen digest, ranked selector suggestions, resume). Repair app state, then resume with replay --from <n> --plan-digest <sha256> (both from the report's resume field) to continue from the failed step without re-running earlier ones; resume never re-executes skipped steps, so app state is the caller's responsibility, and it is rejected with INVALID_ARGS when the plan digest is stale, --from is out of range, or the skipped range/target touches runtime control flow. The plan digest binds the script, its includes, the effective --platform/--target, and per-action runtime/identity. Native .ad interpolation is late-bound after planning, so changing only its values keeps the digest; Maestro environment substitution occurs during compatibility parsing and can change action inputs, includes, or control expansion, so it can change the digest. --from is replay-only; test rejects it. Native .ad session takeover: replay <file>.ad --keep-session suppresses exactly an authored terminal close and returns the surviving session for continued commands; interior closes still run, close-less scripts are unchanged, and test/Maestro reject the option. --update/-u no longer rewrites the script (ADR 0012) — it is a no-op kept for compatibility; every divergence already carries the same ranked suggestions. Agent-supervised repair (heal-by-doing): arm replay <file>.ad --save-script[=<out>] before step 1 (armed once; --from continuations do not need it again). Every divergence carries a repairHint: record-and-heal means press the correct control via a blessed @ref from the divergence's screen.refs, recorded (no --no-record), then continue with replay --from <n+1> --plan-digest <sha256>; state-repair means the script is correct but app state is not, so fix state with --no-record actions, then replay --from <n> --plan-digest <sha256> to re-run the unchanged step; caution means something already matches the recorded selector, so a blind re-press may repeat the mistake; manual means no safe automated repair could be proven. (If close --save-script is run before a required resume, the repair is aborted and no script is written). While armed, read-only inspection YOU run to locate the repair target (snapshot -i, get attrs, find, is) is excluded from the healed script by default — no --no-record needed; the script's own authored get/is/find steps are unaffected and stay in the heal. If the step you are repairing is itself a read, pass --record on that one command so it lands in the heal (--record is accepted only on snapshot/get/is and a read-only find; it is mutually exclusive with --no-record). Ending the repair with close --save-script[=<out>] writes only the steps recorded since the arming replay as <out>, defaulting to the <file> sibling <stem>.healed.ad — review its diff before promoting it over the original.
-  Recording: record start/stop. The default scope is app and expects an active session created by open <app>; this keeps app proof videos tied to the intended app session. Use record start --scope device/system to explicitly request whole-screen capture where the selected backend supports it, such as recordings that intentionally span multiple apps, home screen, settings, or app transitions. Use --max-size to cap the longest edge and --quality medium|high to choose output quality across Android and Apple targets. By default, stop burns touch overlays into the video; use record start --hide-touches for the fastest raw recording. Android record start publishes a durable device manifest. Android adb screenrecord has a 180s platform limit, so longer Android recordings are returned as multiple MP4 chunks while the daemon stays alive; after daemon restart, record stop recovers only manifest-owned chunks and warns when gesture overlays are unavailable. For gesture-heavy iOS simulator proof videos, prefer --hide-touches because overlay timing depends on a stable runner session while gestures are executing. Tracing: trace start ./trace.log, trace stop ./trace.log. Paths are positional.
+  Recording: record start/stop. The default scope is app and expects an active session created by open <app>; this keeps app proof videos tied to the intended app session. Use record start --scope device/system to explicitly request whole-screen capture where the selected backend supports it, such as recordings that intentionally span multiple apps, home screen, settings, or app transitions. Use --quality medium|high to choose output quality across Android and Apple targets. By default, stop burns touch overlays into the video; use record start --hide-touches for the fastest raw recording. Android record start publishes a durable device manifest. Android adb screenrecord has a 180s platform limit, so longer Android recordings are returned as multiple MP4 chunks while the daemon stays alive; after daemon restart, record stop recovers only manifest-owned chunks and warns when gesture overlays are unavailable. For gesture-heavy iOS simulator proof videos, prefer --hide-touches because overlay timing depends on a stable runner session while gestures are executing. Tracing: trace start ./trace.log, trace stop ./trace.log. Paths are positional.
   Stable known flow: batch ./steps.json, not workflow batch.
   Inline batch JSON example:
     agent-device batch --steps '[{"command":"open","input":{"app":"settings"}},{"command":"wait","input":{"kind":"duration","durationMs":100}}]'
diff --git a/src/commands/capture/index.test.ts b/src/commands/capture/index.test.ts
index 045766c52b..5e6bdd651d 100644
--- a/src/commands/capture/index.test.ts
+++ b/src/commands/capture/index.test.ts
@@ -74,13 +74,13 @@ describe('capture command interface', () => {
   test('reads screenshot path and writes screenshot flags', () => {
     const input = screenshotCliReader(
       ['page.png'],
-      flags({ screenshotPixelDensity: 2, screenshotFullscreen: true, screenshotMaxSize: 1024 }),
+      flags({ screenshotPixelDensity: 2, screenshotFullscreen: true, screenshotScale: 0.3 }),
     );
     expect(input).toMatchObject({
       path: 'page.png',
       pixelDensity: 2,
       fullscreen: true,
-      maxSize: 1024,
+      scale: 0.3,
     });
     expect(screenshotDaemonWriter(input)).toMatchObject({
       command: 'screenshot',
@@ -88,7 +88,7 @@ describe('capture command interface', () => {
       options: {
         screenshotPixelDensity: 2,
         screenshotFullscreen: true,
-        screenshotMaxSize: 1024,
+        screenshotScale: 0.3,
       },
     });
   });
diff --git a/src/commands/capture/runtime/screenshot.ts b/src/commands/capture/runtime/screenshot.ts
index dc79f67f19..250c42cb95 100644
--- a/src/commands/capture/runtime/screenshot.ts
+++ b/src/commands/capture/runtime/screenshot.ts
@@ -1,6 +1,7 @@
 import { AppError } from '@agent-device/kernel/errors';
+import { validateScreenshotScale } from '@agent-device/contracts/capture';
 import { successText } from '../../../utils/success-text.ts';
-import { resizePngFileToMaxSize } from '../../../utils/png-resize.ts';
+import { resizePngFileToScale } from '../../../utils/png-resize.ts';
 import type { ArtifactDescriptor } from '../../../io.ts';
 import type { RuntimeCommand, ScreenshotCommandOptions } from '../../runtime-types.ts';
 import { reserveCommandOutput } from '../../io-policy.ts';
@@ -18,6 +19,7 @@ export const screenshotCommand: RuntimeCommand<
   if (!runtime.backend.captureScreenshot) {
     throw new AppError('UNSUPPORTED_OPERATION', 'screenshot is not supported by this backend');
   }
+  validateScreenshotScale(options);
 
   const reserved = await reserveCommandOutput(runtime, options.out, {
     field: 'path',
@@ -46,8 +48,8 @@ export const screenshotCommand: RuntimeCommand<
         surface: options.surface,
       },
     );
-    if (options.maxSize !== undefined) {
-      await resizePngFileToMaxSize(reserved.path, options.maxSize);
+    if (options.scale !== undefined) {
+      await resizePngFileToScale(reserved.path, options.scale);
     }
     artifact = await reserved.publish();
   } catch (error) {
diff --git a/src/commands/capture/screenshot-options.test.ts b/src/commands/capture/screenshot-options.test.ts
index 6b71e91193..4108e4298e 100644
--- a/src/commands/capture/screenshot-options.test.ts
+++ b/src/commands/capture/screenshot-options.test.ts
@@ -7,7 +7,9 @@ import {
   SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS,
   readScreenshotScriptFlag,
   screenshotFlagsFromOptions,
+  screenshotFlagsFromPublicOptions,
   screenshotOptionsFromFlags,
+  validateScreenshotScale,
 } from '@agent-device/contracts/capture';
 
 test('screenshot flag projection maps CLI flags to runtime options', () => {
@@ -16,7 +18,7 @@ test('screenshot flag projection maps CLI flags to runtime options', () => {
       overlayRefs: true,
       screenshotPixelDensity: 2,
       screenshotFullscreen: true,
-      screenshotMaxSize: 1024,
+      screenshotScale: 0.3,
       screenshotNoStabilize: true,
       screenshotNormalizeStatusBar: true,
     }),
@@ -24,7 +26,7 @@ test('screenshot flag projection maps CLI flags to runtime options', () => {
       overlayRefs: true,
       pixelDensity: 2,
       fullscreen: true,
-      maxSize: 1024,
+      scale: 0.3,
       stabilize: false,
       normalizeStatusBar: true,
     },
@@ -37,7 +39,6 @@ test('screenshot flag projection maps public options to request flags', () => {
       overlayRefs: true,
       pixelDensity: 3,
       fullscreen: true,
-      maxSize: 512,
       stabilize: false,
       normalizeStatusBar: true,
     }),
@@ -45,13 +46,24 @@ test('screenshot flag projection maps public options to request flags', () => {
       overlayRefs: true,
       screenshotPixelDensity: 3,
       screenshotFullscreen: true,
-      screenshotMaxSize: 512,
       screenshotNoStabilize: true,
       screenshotNormalizeStatusBar: true,
     },
   );
 });
 
+test('screenshot flag projection maps public scale to its request flag', () => {
+  assert.deepEqual(screenshotFlagsFromPublicOptions({ scale: 0.3 }), {
+    screenshotScale: 0.3,
+  });
+});
+
+test('screenshot scale is bounded', () => {
+  assert.doesNotThrow(() => validateScreenshotScale({ scale: 0.3 }));
+  assert.throws(() => validateScreenshotScale({ scale: 0 }), /between 0\.01 and 1/);
+  assert.throws(() => validateScreenshotScale({ scale: 1.01 }), /between 0\.01 and 1/);
+});
+
 test('screenshot script flags use the shared recorded flag contract', () => {
   const parts: string[] = [];
   const flags = {};
@@ -62,7 +74,7 @@ test('screenshot script flags use the shared recorded flag contract', () => {
   assert.deepEqual(result, { handled: true, nextIndex: 0 });
   result = readScreenshotScriptFlag({ args: ['--fullscreen'], index: 0, flags });
   assert.deepEqual(result, { handled: true, nextIndex: 0 });
-  result = readScreenshotScriptFlag({ args: ['--max-size', '640'], index: 0, flags });
+  result = readScreenshotScriptFlag({ args: ['--scale', '0.3'], index: 0, flags });
   assert.deepEqual(result, { handled: true, nextIndex: 1 });
   result = readScreenshotScriptFlag({ args: ['--no-stabilize'], index: 0, flags });
   assert.deepEqual(result, { handled: true, nextIndex: 0 });
@@ -77,15 +89,15 @@ test('screenshot script flags use the shared recorded flag contract', () => {
     '--pixel-density',
     '3',
     '--fullscreen',
-    '--max-size',
-    '640',
+    '--scale',
+    '0.3',
     '--no-stabilize',
     '--normalize-status-bar',
   ]);
   assert.deepEqual(SCREENSHOT_ACTION_FLAG_KEYS, [
     'screenshotPixelDensity',
     'screenshotFullscreen',
-    'screenshotMaxSize',
+    'screenshotScale',
     'screenshotNoStabilize',
     'screenshotNormalizeStatusBar',
   ]);
@@ -98,7 +110,7 @@ test('screenshot script flags use the shared recorded flag contract', () => {
     'overlayRefs',
     'screenshotPixelDensity',
     'screenshotFullscreen',
-    'screenshotMaxSize',
+    'screenshotScale',
     'screenshotNoStabilize',
     'screenshotNormalizeStatusBar',
   ]);
diff --git a/src/commands/capture/screenshot.ts b/src/commands/capture/screenshot.ts
index d1b2014b61..5c0dd11ca5 100644
--- a/src/commands/capture/screenshot.ts
+++ b/src/commands/capture/screenshot.ts
@@ -3,10 +3,17 @@ import type { CaptureScreenshotOptions } from '@agent-device/contracts/client';
 import { SESSION_SURFACES } from '@agent-device/contracts/session';
 import {
   SCREENSHOT_COMMAND_FLAG_KEYS,
-  screenshotFlagsFromOptions,
+  screenshotFlagsFromPublicOptions,
   screenshotOptionsFromFlags,
+  validateScreenshotScale,
 } from '@agent-device/contracts/capture';
-import { booleanField, enumField, integerField, stringField } from '../command-input.ts';
+import {
+  booleanField,
+  enumField,
+  integerField,
+  numberField,
+  stringField,
+} from '../command-input.ts';
 import { defineExecutableCommand } from '../command-contract.ts';
 import { commonInputFromFlags, optionalString, request } from '../cli-grammar/common.ts';
 import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
@@ -27,7 +34,7 @@ const screenshotCommandMetadata = defineFieldCommandMetadata(
       min: 1,
     }),
     fullscreen: booleanField(),
-    maxSize: integerField(),
+    scale: numberField('Screenshot scale factor.', { min: 0.01, max: 1 }),
     stabilize: booleanField(),
     normalizeStatusBar: booleanField(),
     surface: enumField(SESSION_SURFACES),
@@ -41,7 +48,7 @@ const screenshotCommandDefinition = defineExecutableCommand(
 
 const screenshotCliSchema = {
   helpDescription:
-    'Capture screenshot (web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --max-size to downscale, --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops)',
+    'Capture screenshot (web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator chrome, or --no-stabilize for low-latency Android capture loops)',
   summary:
     'Capture screenshot with optional density, full-page, desktop, downscale, or ref overlay modes',
   positionalArgs: ['path?'],
@@ -54,11 +61,13 @@ export const screenshotCliReader: CliReader = (positionals, flags) => ({
   ...screenshotOptionsFromFlags(flags),
 });
 
-export const screenshotDaemonWriter: DaemonWriter = (input) =>
-  request(PUBLIC_COMMANDS.screenshot, optionalString(input.path), {
+export const screenshotDaemonWriter: DaemonWriter = (input) => {
+  validateScreenshotScale(input as CaptureScreenshotOptions);
+  return request(PUBLIC_COMMANDS.screenshot, optionalString(input.path), {
     ...input,
-    ...screenshotFlagsFromOptions(input as CaptureScreenshotOptions),
+    ...screenshotFlagsFromPublicOptions(input as CaptureScreenshotOptions),
   });
+};
 
 export const screenshotCommandFacet = defineCommandFacet({
   name: SCREENSHOT_COMMAND_NAME,
diff --git a/src/commands/cli-grammar/flag-types.ts b/src/commands/cli-grammar/flag-types.ts
index f46c19f505..aa83ab8b74 100644
--- a/src/commands/cli-grammar/flag-types.ts
+++ b/src/commands/cli-grammar/flag-types.ts
@@ -3,7 +3,7 @@ import type { CliFlags } from '@agent-device/contracts/command';
 export type { CliFlags } from '@agent-device/contracts/command';
 
 export type FlagKey = keyof CliFlags;
-type FlagType = 'boolean' | 'int' | 'enum' | 'string' | 'booleanOrString';
+type FlagType = 'boolean' | 'int' | 'number' | 'enum' | 'string' | 'booleanOrString';
 
 export type FlagDefinition = {
   key: FlagKey;
diff --git a/src/commands/command-flags.ts b/src/commands/command-flags.ts
index 14b9d69aea..3ff5e393e5 100644
--- a/src/commands/command-flags.ts
+++ b/src/commands/command-flags.ts
@@ -77,7 +77,6 @@ function buildFlags(options: InternalRequestOptions): CommandFlags {
     out: options.out,
     count: options.count,
     fps: options.fps,
-    screenshotMaxSize: options.maxSize,
     quality: options.quality,
     hideTouches: options.hideTouches,
     recordingScope: options.recordingScope,
diff --git a/src/commands/command-input.ts b/src/commands/command-input.ts
index c745bc79f7..637bdc7dba 100644
--- a/src/commands/command-input.ts
+++ b/src/commands/command-input.ts
@@ -96,8 +96,16 @@ export function stringSchema(description?: string): JsonSchema {
   return { type: 'string', ...(description ? { description } : {}) };
 }
 
-function numberSchema(description?: string): JsonSchema {
-  return { type: 'number', ...(description ? { description } : {}) };
+function numberSchema(
+  description?: string,
+  options: { min?: number; max?: number } = {},
+): JsonSchema {
+  return {
+    type: 'number',
+    ...(description ? { description } : {}),
+    ...(options.min === undefined ? {} : { minimum: options.min }),
+    ...(options.max === undefined ? {} : { maximum: options.max }),
+  };
 }
 
 function integerSchema(description?: string): JsonSchema {
@@ -161,8 +169,13 @@ export function stringField(description?: string): CommandField<string> {
   return optionalField(stringSchema(description), optionalString);
 }
 
-export function numberField(description?: string): CommandField<number> {
-  return optionalField(numberSchema(description), optionalNumberValue);
+export function numberField(
+  description?: string,
+  options: { min?: number; max?: number } = {},
+): CommandField<number> {
+  return optionalField(numberSchema(description, options), (record, key) =>
+    optionalNumberValue(record, key, options),
+  );
 }
 
 export function integerField(
@@ -392,12 +405,22 @@ function requiredNumber(record: Record<string, unknown>, key: string): number {
   return value;
 }
 
-function optionalNumberValue(record: Record<string, unknown>, key: string): number | undefined {
+function optionalNumberValue(
+  record: Record<string, unknown>,
+  key: string,
+  options: { min?: number; max?: number } = {},
+): number | undefined {
   const value = record[key];
   if (value === undefined) return undefined;
   if (typeof value !== 'number' || !Number.isFinite(value)) {
     throw new AppError('INVALID_ARGS', `Expected ${key} to be a finite number.`);
   }
+  if (options.min !== undefined && value < options.min) {
+    throw new Error(`Expected ${key} to be at least ${options.min}.`);
+  }
+  if (options.max !== undefined && value > options.max) {
+    throw new Error(`Expected ${key} to be at most ${options.max}.`);
+  }
   return value;
 }
 
diff --git a/src/commands/recording/index.test.ts b/src/commands/recording/index.test.ts
index c7b5e0996d..1cbee28772 100644
--- a/src/commands/recording/index.test.ts
+++ b/src/commands/recording/index.test.ts
@@ -34,7 +34,6 @@ describe('recording command interface', () => {
     expect(
       recordCliReader(['start', './capture.mp4'], {
         fps: 30,
-        screenshotMaxSize: 1024,
         quality: 'high',
         hideTouches: true,
         recordingScope: 'device',
@@ -43,7 +42,6 @@ describe('recording command interface', () => {
       action: 'start',
       path: './capture.mp4',
       fps: 30,
-      maxSize: 1024,
       quality: 'high',
       hideTouches: true,
       recordingScope: 'device',
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index 7c63adb878..e2b5860bbf 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -33,7 +33,6 @@ export const recordCommandMetadata = defineFieldCommandMetadata(
     action: requiredField(enumField(RECORDING_ACTION_VALUES)),
     path: stringField(),
     fps: integerField(),
-    maxSize: integerField(),
     quality: enumField(RECORDING_EXPORT_QUALITIES),
     hideTouches: booleanField(),
     recordingScope: enumField(RECORDING_SCOPE_VALUES),
@@ -61,13 +60,13 @@ export const traceCommandDefinition = defineExecutableCommand(
 
 const recordCliSchema = {
   usageOverride:
-    'record start [path] [--scope <app|device|system>] [--fps <n>] [--max-size <px>] [--quality <medium|high>] [--hide-touches] | record stop',
+    'record start [path] [--scope <app|device|system>] [--fps <n>] [--quality <medium|high>] [--hide-touches] | record stop',
   listUsageOverride: 'record start [path] | record stop',
   helpDescription:
-    'Start/stop screen recording. The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Use --max-size to limit dimensions and --quality to choose medium or high export quality',
+    'Start/stop screen recording. The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Use --quality to choose medium or high export quality',
   summary: 'Start or stop screen recording',
   positionalArgs: ['start|stop', 'path?'],
-  allowedFlags: ['recordingScope', 'fps', 'screenshotMaxSize', 'quality', 'hideTouches'],
+  allowedFlags: ['recordingScope', 'fps', 'quality', 'hideTouches'],
 } as const satisfies CommandSchemaOverride;
 
 const traceCliSchema = {
@@ -84,7 +83,6 @@ export const recordCliReader: CliReader = (positionals, flags) => ({
   action: readRecordingAction(positionals[0], RECORD_COMMAND_NAME),
   path: positionals[1],
   fps: flags.fps,
-  maxSize: flags.screenshotMaxSize,
   quality: flags.quality as RecordOptions['quality'],
   hideTouches: flags.hideTouches,
   recordingScope: flags.recordingScope,
diff --git a/src/commands/recording/runtime/recording.test.ts b/src/commands/recording/runtime/recording.test.ts
index ab019a04ec..de24b67e7b 100644
--- a/src/commands/recording/runtime/recording.test.ts
+++ b/src/commands/recording/runtime/recording.test.ts
@@ -46,7 +46,6 @@ test('record and trace runtime commands call typed backend lifecycle primitives'
     action: 'start',
     out: { kind: 'path', path: '/tmp/out.mp4' },
     fps: 30,
-    maxSize: 1024,
     quality: 'high',
     hideTouches: true,
   });
@@ -64,7 +63,6 @@ test('record and trace runtime commands call typed backend lifecycle primitives'
       options: {
         outPath: '/tmp/out.mp4',
         fps: 30,
-        maxSize: 1024,
         quality: 'high',
         showTouches: false,
       },
diff --git a/src/commands/recording/runtime/recording.ts b/src/commands/recording/runtime/recording.ts
index de58b01dca..67388355a6 100644
--- a/src/commands/recording/runtime/recording.ts
+++ b/src/commands/recording/runtime/recording.ts
@@ -25,7 +25,6 @@ export type RecordingRecordCommandOptions = CommandContext & {
   action: 'start' | 'stop';
   out?: FileOutputRef;
   fps?: number;
-  maxSize?: number;
   quality?: RecordingExportQuality;
   hideTouches?: boolean;
 };
@@ -129,8 +128,6 @@ function normalizeRecordingOptions(
   if (outPath) backendOptions.outPath = outPath;
   const fps = normalizeRecordingFps(options.fps);
   if (fps !== undefined) backendOptions.fps = fps;
-  const maxSize = normalizeRecordingMaxSize(options.maxSize);
-  if (maxSize !== undefined) backendOptions.maxSize = maxSize;
   const quality = normalizeRecordingExportQuality(options.quality);
   if (quality !== undefined) backendOptions.quality = quality;
   if (options.hideTouches !== undefined) backendOptions.showTouches = options.hideTouches !== true;
@@ -141,12 +138,6 @@ function normalizeRecordingFps(value: number | undefined): number | undefined {
   return value === undefined ? undefined : requireIntInRange(value, 'fps', 1, 60);
 }
 
-function normalizeRecordingMaxSize(value: number | undefined): number | undefined {
-  return value === undefined
-    ? undefined
-    : requireIntInRange(value, 'maxSize', 1, Number.MAX_SAFE_INTEGER);
-}
-
 function normalizeRecordingExportQuality(
   value: RecordingExportQuality | undefined,
 ): BackendRecordingOptions['quality'] {
diff --git a/src/commands/runtime-types.ts b/src/commands/runtime-types.ts
index ff89c4164c..e21bf67c72 100644
--- a/src/commands/runtime-types.ts
+++ b/src/commands/runtime-types.ts
@@ -49,7 +49,7 @@ export type ScreenshotCommandOptions = CommandContext & {
   fullscreen?: boolean;
   overlayRefs?: boolean;
   pixelDensity?: number;
-  maxSize?: number;
+  scale?: number;
   stabilize?: boolean;
   normalizeStatusBar?: boolean;
   appId?: string;
diff --git a/src/daemon/__tests__/context.test.ts b/src/daemon/__tests__/context.test.ts
index b096cee491..48bdbd44e0 100644
--- a/src/daemon/__tests__/context.test.ts
+++ b/src/daemon/__tests__/context.test.ts
@@ -30,11 +30,11 @@ test('contextFromFlags forwards generic app-state clearing', () => {
 test('contextFromFlags forwards screenshot flags from CLI flags', () => {
   const flags: CommandFlags = {
     screenshotFullscreen: true,
-    screenshotMaxSize: 1024,
+    screenshotScale: 0.3,
     screenshotNoStabilize: true,
   };
   const context = contextFromFlags('/tmp/agent-device.log', flags);
   assert.equal(context.screenshotFullscreen, true);
-  assert.equal(context.screenshotMaxSize, 1024);
+  assert.equal(context.screenshotScale, 0.3);
   assert.equal(context.screenshotNoStabilize, true);
 });
diff --git a/src/daemon/__tests__/request-router-screenshot.test.ts b/src/daemon/__tests__/request-router-screenshot.test.ts
index 60735df155..5f7bd4d15f 100644
--- a/src/daemon/__tests__/request-router-screenshot.test.ts
+++ b/src/daemon/__tests__/request-router-screenshot.test.ts
@@ -445,10 +445,10 @@ test('non-iOS screenshot response tolerates malformed PNG metadata', async () =>
   }
 });
 
-test('iOS simulator screenshot omits logical density metadata after --max-size downscale', async () => {
+test('iOS simulator screenshot omits logical density metadata after --scale downscale', async () => {
   const sessionStore = makeSessionStore('agent-device-router-screenshot-');
   sessionStore.set('default', makeIosSession('default'));
-  const screenshotPath = path.join(os.tmpdir(), `agent-device-ios-max-size-${Date.now()}.png`);
+  const screenshotPath = path.join(os.tmpdir(), `agent-device-ios-scale-${Date.now()}.png`);
 
   mockDispatch.mockImplementation(async (_device, command) => {
     if (command === 'screenshot') {
@@ -471,16 +471,16 @@ test('iOS simulator screenshot omits logical density metadata after --max-size d
     session: 'default',
     command: 'screenshot',
     positionals: [screenshotPath],
-    flags: { screenshotMaxSize: 437, screenshotPixelDensity: 2 },
-    meta: { requestId: 'req-ios-screenshot-max-size-meta' },
+    flags: { screenshotScale: 0.5, screenshotPixelDensity: 2 },
+    meta: { requestId: 'req-ios-screenshot-scale-meta' },
   });
 
   expect(response.ok).toBe(true);
   if (response.ok) {
     expect(response.data).toMatchObject({
       path: screenshotPath,
-      width: 201,
-      height: 437,
+      width: 402,
+      height: 874,
     });
     expect(response.data).not.toHaveProperty('logicalWidth');
     expect(response.data).not.toHaveProperty('logicalHeight');
diff --git a/src/daemon/__tests__/session-store.test.ts b/src/daemon/__tests__/session-store.test.ts
index 2596fc95b7..9675edcd34 100644
--- a/src/daemon/__tests__/session-store.test.ts
+++ b/src/daemon/__tests__/session-store.test.ts
@@ -432,7 +432,6 @@ test('writeSessionLog persists record --hide-touches flags in script output', ()
     flags: {
       platform: 'ios',
       fps: 30,
-      screenshotMaxSize: 1024,
       quality: 'high',
       hideTouches: true,
     },
@@ -440,10 +439,7 @@ test('writeSessionLog persists record --hide-touches flags in script output', ()
   });
 
   const script = writeScript(fixture);
-  assert.match(
-    script,
-    /record start "\.\/capture\.mp4" --fps 30 --max-size 1024 --quality high --hide-touches/,
-  );
+  assert.match(script, /record start "\.\/capture\.mp4" --fps 30 --quality high --hide-touches/);
 });
 
 test('writeSessionLog persists screenshot flags in script output', () => {
@@ -452,12 +448,12 @@ test('writeSessionLog persists screenshot flags in script output', () => {
   fixture.store.recordAction(fixture.session, {
     command: 'screenshot',
     positionals: ['./page.png'],
-    flags: { platform: 'ios', screenshotFullscreen: true, screenshotMaxSize: 1024 },
+    flags: { platform: 'ios', screenshotFullscreen: true, screenshotScale: 0.3 },
     result: {},
   });
 
   const script = writeScript(fixture);
-  assert.match(script, /screenshot "\.\/page\.png" --fullscreen --max-size 1024/);
+  assert.match(script, /screenshot "\.\/page\.png" --fullscreen --scale 0\.3/);
 });
 
 test('writeSessionLog persists inline open runtime hints in script output', () => {
diff --git a/src/daemon/handlers/__tests__/record-trace-ios-simulator-recording.test.ts b/src/daemon/handlers/__tests__/record-trace-ios-simulator-recording.test.ts
index 786220fcbc..38bf582931 100644
--- a/src/daemon/handlers/__tests__/record-trace-ios-simulator-recording.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace-ios-simulator-recording.test.ts
@@ -265,7 +265,6 @@ function makeDeps(overrides: Pick<RecordTraceDeps, 'startIosSimulatorRecording'>
     waitForStableFile: async () => {},
     isPlayableVideo: async () => true,
     trimRecordingStart: async () => {},
-    resizeRecording: async () => {},
     overlayRecordingTouches: async () => {},
   };
 }
diff --git a/src/daemon/handlers/__tests__/record-trace-ios.test.ts b/src/daemon/handlers/__tests__/record-trace-ios.test.ts
index 772f47ddef..05992f67cc 100644
--- a/src/daemon/handlers/__tests__/record-trace-ios.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace-ios.test.ts
@@ -34,7 +34,6 @@ test('startIosDeviceRecording stops stale runner recording and retries with the
     waitForStableFile: async () => {},
     isPlayableVideo: async () => true,
     trimRecordingStart: async () => {},
-    resizeRecording: async () => {},
     overlayRecordingTouches: async () => {},
   };
 
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index dca07b4b9d..ae28b92d29 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -35,7 +35,6 @@ vi.mock('../../../recording/overlay.ts', async (importOriginal) => {
   return {
     ...actual,
     trimRecordingStart: vi.fn(async () => {}),
-    resizeRecording: vi.fn(async () => {}),
     overlayRecordingTouches: vi.fn(async () => {}),
   };
 });
@@ -58,14 +57,13 @@ import { handleRecordTraceCommands } from '../record-trace.ts';
 import { stopSessionRecordingForTeardown } from '../record-trace-recording.ts';
 import { deriveRecordingTelemetryPath } from '../../recording-telemetry.ts';
 import { SessionStore } from '../../session-store.ts';
-import type { SessionState } from '../../types.ts';
+import type { DaemonRequest, SessionState } from '../../types.ts';
 import {
   IOS_RUNNER_CONTAINER_BUNDLE_IDS,
   runAppleRunnerCommand,
 } from '../../../platforms/apple/core/runner/runner-client.ts';
 import {
   getRecordingOverlaySupportWarning,
-  resizeRecording,
   trimRecordingStart,
   overlayRecordingTouches,
 } from '../../../recording/overlay.ts';
@@ -79,7 +77,6 @@ type RunnerCall = {
   command: string;
   outPath?: string;
   fps?: number;
-  maxSize?: number;
   appBundleId?: string;
   logPath?: string;
   traceLogPath?: string;
@@ -90,7 +87,6 @@ const mockRunCmdBackground = vi.mocked(runCmdBackground);
 const mockRunAppleRunnerCommand = vi.mocked(runAppleRunnerCommand);
 const mockResolveTargetDevice = vi.mocked(resolveTargetDevice);
 const mockEnsureDeviceReady = vi.mocked(ensureDeviceReady);
-const mockResizeRecording = vi.mocked(resizeRecording);
 const mockTrimRecordingStart = vi.mocked(trimRecordingStart);
 const mockOverlayRecordingTouches = vi.mocked(overlayRecordingTouches);
 const mockWaitForStableFile = vi.mocked(waitForStableFile);
@@ -230,7 +226,7 @@ function mockIosSimulatorRecordingStart(
 }
 
 function isAndroidScreenrecordStartCommand(command: string): boolean {
-  return /^-s emulator-5554 shell screenrecord (?:--size 756x1344 )?--bit-rate (?:8000000|20000000) \/(?:sdcard|data\/local\/tmp)\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+  return /^-s emulator-5554 shell screenrecord --bit-rate (?:8000000|20000000) \/(?:sdcard|data\/local\/tmp)\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
     command,
   );
 }
@@ -244,10 +240,10 @@ async function runRecordCommand(params: {
   flags?: {
     fps?: number;
     quality?: string;
-    screenshotMaxSize?: number;
     hideTouches?: boolean;
     recordingScope?: 'app' | 'device' | 'system';
   };
+  rawFlags?: Record<string, unknown>;
   sessionExplicit?: boolean;
   clientArtifactPaths?: Record<string, string>;
 }) {
@@ -257,7 +253,7 @@ async function runRecordCommand(params: {
       session: params.sessionName,
       command: 'record',
       positionals: params.positionals,
-      flags: params.flags ?? {},
+      flags: (params.rawFlags ?? params.flags ?? {}) as DaemonRequest['flags'],
       meta:
         params.cwd || params.clientArtifactPaths || params.sessionExplicit
           ? {
@@ -284,7 +280,6 @@ function setupRunnerRecordingMocks(
       command: command.command,
       outPath: command.outPath,
       fps: command.fps,
-      maxSize: command.maxSize,
       appBundleId: command.appBundleId,
       logPath: options?.logPath,
       traceLogPath: options?.traceLogPath,
@@ -311,7 +306,6 @@ beforeEach(() => {
     throw new Error('runCmdBackground should not be used in this test');
   });
   mockRunAppleRunnerCommand.mockImplementation(async () => ({}));
-  mockResizeRecording.mockImplementation(async () => {});
   mockTrimRecordingStart.mockImplementation(async () => {});
   mockOverlayRecordingTouches.mockImplementation(async () => {});
   mockWaitForStableFile.mockImplementation(async () => {});
@@ -526,7 +520,7 @@ test('record start web rejects native recording flags before delegating', async
       sessionStore,
       sessionName,
       positionals: ['start', path.join(os.tmpdir(), `${sessionName}.webm`)],
-      flags: { fps: 0, quality: 'high', screenshotMaxSize: 1024, hideTouches: true },
+      flags: { fps: 0, quality: 'high', hideTouches: true },
     });
 
     expect(start?.ok).toBe(false);
@@ -534,10 +528,30 @@ test('record start web rejects native recording flags before delegating', async
       throw new Error(`expected web recording start failure, got ${JSON.stringify(start)}`);
     }
     expect(start.error.code).toBe('INVALID_ARGS');
-    expect(start.error.message).toContain('--fps, --quality, --max-size, --hide-touches');
+    expect(start.error.message).toContain('--fps, --quality, --hide-touches');
   });
 });
 
+test('record start rejects the removed max-size field from older remote clients', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'recording-legacy-max-size';
+  sessionStore.set(sessionName, makeOpenedIosSimulatorSession(sessionName));
+
+  const start = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './legacy-max-size.mp4'],
+    rawFlags: { screenshotMaxSize: 720 },
+  });
+
+  expect(start?.ok).toBe(false);
+  if (!start || start.ok) {
+    throw new Error(`expected recording start failure, got ${JSON.stringify(start)}`);
+  }
+  expect(start.error.code).toBe('INVALID_ARGS');
+  expect(start.error.message).toBe('record --max-size is not supported');
+});
+
 test('record start web requires an existing browser session', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'web-recording-no-open';
@@ -929,64 +943,6 @@ test('record stop trims iOS device recordings from target app readiness before o
   expect((response as any).data?.overlayWarning).toBe(overlaySupportWarning);
 });
 
-test('record stop resizes iOS simulator recording when max-size is explicit', async () => {
-  const sessionStore = makeSessionStore();
-  const sessionName = 'ios-sim-quality';
-  sessionStore.set(sessionName, makeOpenedIosSimulatorSession(sessionName));
-
-  mockIosSimulatorRecordingStart();
-
-  await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['start', './sim-quality.mp4'],
-    flags: { screenshotMaxSize: 720 },
-  });
-
-  const responseStop = await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['stop'],
-  });
-
-  expect(responseStop?.ok).toBe(true);
-  expect(mockResizeRecording).toHaveBeenCalledWith({
-    videoPath: path.resolve('./sim-quality.mp4'),
-    maxSize: 720,
-    exportQuality: 'medium',
-    targetLabel: 'iOS recording',
-  });
-});
-
-test('record stop forwards the requested quality to the resize step', async () => {
-  const sessionStore = makeSessionStore();
-  const sessionName = 'ios-sim-export-quality';
-  sessionStore.set(sessionName, makeOpenedIosSimulatorSession(sessionName));
-
-  mockIosSimulatorRecordingStart();
-
-  await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['start', './sim-export-quality.mp4'],
-    flags: { screenshotMaxSize: 720, quality: 'high' },
-  });
-
-  const responseStop = await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['stop'],
-  });
-
-  expect(responseStop?.ok).toBe(true);
-  expect(mockResizeRecording).toHaveBeenCalledWith({
-    videoPath: path.resolve('./sim-export-quality.mp4'),
-    maxSize: 720,
-    exportQuality: 'high',
-    targetLabel: 'iOS recording',
-  });
-});
-
 test('record stop leaves a short visual tail after iOS simulator gestures', async () => {
   vi.useFakeTimers();
   const sessionStore = makeSessionStore();
@@ -1548,34 +1504,6 @@ test('record stop skips touch overlay export when no gestures were recorded', as
   expect((responseStop as any).data?.overlayWarning).toBeUndefined();
 });
 
-test('record stop keeps iOS simulator video when resize export fails', async () => {
-  const sessionStore = makeSessionStore();
-  const sessionName = 'ios-sim-resize-fail';
-  sessionStore.set(sessionName, makeOpenedIosSimulatorSession(sessionName));
-
-  mockIosSimulatorRecordingStart();
-
-  mockResizeRecording.mockImplementation(async () => {
-    throw new Error('resize failed');
-  });
-
-  await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['start', './sim-resize-fail.mp4'],
-    flags: { screenshotMaxSize: 720 },
-  });
-
-  const responseStop = await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['stop'],
-  });
-
-  expect(responseStop?.ok).toBe(true);
-  expect((responseStop as any).data?.overlayWarning ?? '').toMatch(/failed to resize recording/i);
-});
-
 test('record start does not fail when iOS simulator runner warm-up fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim-warm-failure';
@@ -1889,39 +1817,6 @@ test('record start/stop overlays Android gestures by default on devices', async
   }
 });
 
-test('record start rejects Android max-size when wm size is unparseable', async () => {
-  const sessionStore = makeSessionStore();
-  const sessionName = 'android-quality-unparseable';
-  sessionStore.set(
-    sessionName,
-    makeSession(sessionName, {
-      platform: 'android',
-      id: 'emulator-5554',
-      name: 'Android',
-      kind: 'device',
-      booted: true,
-    }),
-  );
-
-  mockRunCmd.mockImplementation(async (_cmd, args) => {
-    const command = args.join(' ');
-    if (command === '-s emulator-5554 shell wm size') {
-      return { stdout: 'w=oops\n', stderr: '', exitCode: 0 };
-    }
-    return { stdout: '', stderr: '', exitCode: 0 };
-  });
-
-  const response = await runRecordCommand({
-    sessionStore,
-    sessionName,
-    positionals: ['start', './android.mp4'],
-    flags: { screenshotMaxSize: 720, quality: 'high' },
-  });
-
-  expect(response?.ok).toBe(false);
-  expect((response as any).error?.code).toBe('COMMAND_FAILED');
-});
-
 test('record stop keeps Android video when overlay export fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-overlay-warning';
diff --git a/src/daemon/handlers/record-trace-android-recovery.ts b/src/daemon/handlers/record-trace-android-recovery.ts
index fbaa8f8130..d7173b74c6 100644
--- a/src/daemon/handlers/record-trace-android-recovery.ts
+++ b/src/daemon/handlers/record-trace-android-recovery.ts
@@ -41,7 +41,6 @@ type AndroidRecordingBase = Pick<
   | 'clientOutPath'
   | 'telemetryPath'
   | 'startedAt'
-  | 'maxSize'
   | 'exportQuality'
   | 'showTouches'
   | 'gestureEvents'
@@ -699,7 +698,6 @@ function buildAndroidRecordingFromManifest(
     clientOutPath: recordingBase.clientOutPath,
     telemetryPath: recordingBase.telemetryPath,
     startedAt: manifest.startedAt,
-    maxSize: recordingBase.maxSize,
     exportQuality: recordingBase.exportQuality,
     showTouches: false,
     gestureEvents: [],
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index a13d45aed8..07f33a7d83 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -28,8 +28,6 @@ import {
   writeAndroidRecoveryRotatingMetadata,
 } from './record-trace-android-recovery.ts';
 
-type AndroidRecordingSize = { width: number; height: number };
-
 const ANDROID_RECORDING_BIT_RATE: Record<RecordingExportQuality, number> = {
   medium: 8_000_000,
   high: 20_000_000,
@@ -52,7 +50,6 @@ type AndroidRecordingBase = Pick<
   | 'clientOutPath'
   | 'telemetryPath'
   | 'startedAt'
-  | 'maxSize'
   | 'exportQuality'
   | 'showTouches'
   | 'gestureEvents'
@@ -181,66 +178,11 @@ function androidRemoteRecordingPaths(timestamp: number, preferredDir?: string):
   return orderedDirs.map((dir) => `${dir}/${fileName}`);
 }
 
-async function resolveAndroidRecordingSize(params: {
-  deviceId: string;
-  maxSize: number | undefined;
-}): Promise<AndroidRecordingSize | undefined> {
-  const { deviceId, maxSize } = params;
-  if (maxSize === undefined) {
-    return undefined;
-  }
-
-  const sizeResult = await runAndroidRecordingAdb(deviceId, ['shell', 'wm', 'size'], {
-    allowFailure: true,
-    timeoutMs: ANDROID_RECORDING_PROBE_TIMEOUT_MS,
-  });
-  const match =
-    sizeResult.stdout.match(/Override size:\s*(\d+)x(\d+)/) ??
-    sizeResult.stdout.match(/Physical size:\s*(\d+)x(\d+)/);
-  if (sizeResult.exitCode !== 0 || !match) {
-    throw new Error(
-      `failed to resolve Android screen size for recording max-size: ${formatRecordTraceExecFailure(sizeResult, 'adb shell wm size')}`,
-    );
-  }
-
-  return scaledSizeToMax({
-    width: Number(match[1]),
-    height: Number(match[2]),
-    maxSize,
-  });
-}
-
-function scaledSizeToMax(size: AndroidRecordingSize & { maxSize: number }): AndroidRecordingSize {
-  const longest = Math.max(size.width, size.height);
-  if (longest <= size.maxSize) {
-    return { width: size.width, height: size.height };
-  }
-  if (longest === 0) {
-    return { width: size.width, height: size.height };
-  }
-  const scale = size.maxSize / longest;
-  if (!Number.isFinite(scale)) {
-    return { width: size.width, height: size.height };
-  }
-  return {
-    width: scaledEvenDimension(size.width, scale),
-    height: scaledEvenDimension(size.height, scale),
-  };
-}
-
-function scaledEvenDimension(value: number, scale: number): number {
-  return Math.max(2, Math.round((value * scale) / 2) * 2);
-}
-
 function buildAndroidScreenrecordCommand(
   remotePath: string,
-  size: AndroidRecordingSize | undefined,
   quality: RecordingExportQuality,
 ): string {
   const screenrecordArgs = ['screenrecord'];
-  if (size) {
-    screenrecordArgs.push('--size', `${size.width}x${size.height}`);
-  }
   screenrecordArgs.push('--bit-rate', String(ANDROID_RECORDING_BIT_RATE[quality]));
   screenrecordArgs.push(remotePath);
   return `${screenrecordArgs.join(' ')} >/dev/null 2>&1 & echo $!`;
@@ -277,19 +219,17 @@ async function forceStopAndroidProcess(deviceId: string, pid: string): Promise<b
 
 async function startAndroidScreenrecordChunk(params: {
   device: AndroidDevice;
-  recordingSize: AndroidRecordingSize | undefined;
   quality: RecordingExportQuality;
   preferredRemoteDir?: string;
   hooks?: AndroidRecordingChunkStartHooks;
 }): Promise<AndroidRecordingChunkStart | { error: DaemonResponse }> {
-  const { device, recordingSize, quality, preferredRemoteDir, hooks } = params;
+  const { device, quality, preferredRemoteDir, hooks } = params;
   let lastStartError =
     'failed to start recording: Android screenrecord did not begin producing frames';
 
   for (const remotePath of androidRemoteRecordingPaths(Date.now(), preferredRemoteDir)) {
     const attempt = await tryStartAndroidScreenrecordAtPath({
       device,
-      recordingSize,
       quality,
       remotePath,
       hooks,
@@ -305,12 +245,11 @@ async function startAndroidScreenrecordChunk(params: {
 
 async function tryStartAndroidScreenrecordAtPath(params: {
   device: AndroidDevice;
-  recordingSize: AndroidRecordingSize | undefined;
   quality: RecordingExportQuality;
   remotePath: string;
   hooks?: AndroidRecordingChunkStartHooks;
 }): Promise<AndroidRecordingChunkStartAttempt> {
-  const { device, recordingSize, quality, remotePath, hooks } = params;
+  const { device, quality, remotePath, hooks } = params;
   const prepareError = await hooks?.prepareRemotePath?.(remotePath);
   if (prepareError) {
     return { kind: 'failed', message: prepareError };
@@ -318,7 +257,7 @@ async function tryStartAndroidScreenrecordAtPath(params: {
 
   const startResult = await runAndroidRecordingAdb(
     device.id,
-    ['shell', buildAndroidScreenrecordCommand(remotePath, recordingSize, quality)],
+    ['shell', buildAndroidScreenrecordCommand(remotePath, quality)],
     {
       allowFailure: true,
       timeoutMs: ANDROID_RECORDING_PROBE_TIMEOUT_MS,
@@ -379,21 +318,10 @@ export async function startAndroidRecording(params: {
   recordingBase: AndroidRecordingBase;
 }): Promise<DaemonResponse | AndroidRecording> {
   const { sessionName, activeSession, device, recordingBase } = params;
-  let recordingSize: AndroidRecordingSize | undefined;
-  try {
-    recordingSize = await resolveAndroidRecordingSize({
-      deviceId: device.id,
-      maxSize: recordingBase.maxSize,
-    });
-  } catch (error) {
-    return errorResponse('COMMAND_FAILED', error instanceof Error ? error.message : String(error));
-  }
-
   const quality = recordingBase.exportQuality ?? DEFAULT_RECORDING_EXPORT_QUALITY;
   const recordingId = randomUUID();
   const chunk = await startAndroidScreenrecordChunk({
     device,
-    recordingSize,
     quality,
     hooks: {
       prepareRemotePath: async (remotePath) =>
@@ -433,7 +361,6 @@ export async function startAndroidRecording(params: {
     sessionName,
     device,
     recording,
-    recordingSize,
     quality,
   });
   return recording;
@@ -468,10 +395,9 @@ function scheduleAndroidRecordingChunks(params: {
   sessionName: string;
   device: AndroidDevice;
   recording: AndroidRecording;
-  recordingSize: AndroidRecordingSize | undefined;
   quality: RecordingExportQuality;
 }): void {
-  const { activeSession, sessionName, device, recording, recordingSize, quality } = params;
+  const { activeSession, sessionName, device, recording, quality } = params;
   scheduleAndroidRecordingRotation({
     recording,
     finishCurrentChunk: async (chunk) =>
@@ -488,7 +414,6 @@ function scheduleAndroidRecordingChunks(params: {
     startNextChunk: async (preferredRemoteDir, nextIndex) => {
       const nextChunk = await startAndroidScreenrecordChunk({
         device,
-        recordingSize,
         quality,
         preferredRemoteDir,
         hooks: {
diff --git a/src/daemon/handlers/record-trace-ios-simulator-recording.ts b/src/daemon/handlers/record-trace-ios-simulator-recording.ts
index 2b0ac7395f..274b8efeef 100644
--- a/src/daemon/handlers/record-trace-ios-simulator-recording.ts
+++ b/src/daemon/handlers/record-trace-ios-simulator-recording.ts
@@ -176,27 +176,6 @@ export async function stopIosSimulatorRecording(params: {
     );
   }
 
-  if (recording.maxSize !== undefined) {
-    try {
-      await withDiagnosticTimer(
-        'record_stop_resize',
-        () =>
-          deps.resizeRecording({
-            videoPath: recording.outPath,
-            maxSize: recording.maxSize!,
-            exportQuality: recording.exportQuality,
-            targetLabel: 'iOS recording',
-          }),
-        {
-          outPath: recording.outPath,
-          maxSize: recording.maxSize,
-        },
-      );
-    } catch (error) {
-      recording.overlayWarning = `failed to resize recording: ${formatRecordTraceError(error)}`;
-    }
-  }
-
   await withDiagnosticTimer(
     'record_stop_finalize_overlay',
     () =>
diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
index 86cff2fe3b..6c8f461979 100644
--- a/src/daemon/handlers/record-trace-ios.ts
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -189,7 +189,6 @@ export async function startIosDeviceRecording(params: {
         command: 'recordStart',
         outPath: recordingFileName,
         fps: fpsFlag,
-        maxSize: recordingBase.maxSize,
         appBundleId,
       },
       runnerOptions,
@@ -293,7 +292,6 @@ export async function startMacOsRecording(params: {
         command: 'recordStart',
         outPath: recordingBase.outPath,
         fps: fpsFlag,
-        maxSize: recordingBase.maxSize,
         appBundleId,
       },
       getIosRunnerOptions(req, logPath, activeSession),
diff --git a/src/daemon/handlers/record-trace-recording-backends.ts b/src/daemon/handlers/record-trace-recording-backends.ts
index 8661782c1f..da43562c1d 100644
--- a/src/daemon/handlers/record-trace-recording-backends.ts
+++ b/src/daemon/handlers/record-trace-recording-backends.ts
@@ -322,7 +322,6 @@ const RECORDING_BACKENDS_BY_TAG: Record<RecordingBackendTag, RecordingStartBacke
 const WEB_UNSUPPORTED_RECORDING_FLAGS = [
   ['fps', '--fps'],
   ['quality', '--quality'],
-  ['screenshotMaxSize', '--max-size'],
   ['hideTouches', '--hide-touches'],
 ] as const satisfies readonly (readonly [keyof NonNullable<DaemonRequest['flags']>, string])[];
 
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 7cf4df1baa..7e7f4459ca 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -13,11 +13,7 @@ import path from 'node:path';
 import { resolveTargetDevice } from '../../core/dispatch.ts';
 import { runAppleRunnerCommand } from '../../platforms/apple/core/runner/runner-client.ts';
 import { runXcrun } from '../../platforms/apple/core/tool-provider.ts';
-import {
-  overlayRecordingTouches,
-  resizeRecording,
-  trimRecordingStart,
-} from '../../recording/overlay.ts';
+import { overlayRecordingTouches, trimRecordingStart } from '../../recording/overlay.ts';
 import { runCmd } from '../../utils/exec.ts';
 import { sleep } from '../../utils/timeouts.ts';
 import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
@@ -84,7 +80,6 @@ function buildRecordTraceDeps(): RecordTraceDeps {
     waitForStableFile,
     isPlayableVideo,
     trimRecordingStart,
-    resizeRecording,
     overlayRecordingTouches,
   };
 }
@@ -119,7 +114,6 @@ function buildRecordingBase(params: {
           ...(activeSession.appName ? { name: activeSession.appName } : {}),
         }
       : undefined,
-    maxSize: req.flags?.screenshotMaxSize,
     exportQuality: exportQuality ?? DEFAULT_RECORDING_EXPORT_QUALITY,
     showTouches: req.flags?.hideTouches !== true,
     gestureEvents: [],
@@ -187,12 +181,12 @@ function validateRecordingStartRequest(params: {
   const { req, activeSession, device, backend } = params;
   const validators = [
     () => validateNoActiveRecording(activeSession),
+    () => validateRemovedRecordingMaxSizeFlag(req.flags),
     () => backend.validateStart?.(req) ?? null,
     () =>
       validateRecordingStartFlags({
         fpsFlag: req.flags?.fps,
         qualityFlag: req.flags?.quality,
-        maxSizeFlag: req.flags?.screenshotMaxSize,
       }),
     () => requireCommandSupported('record', device),
   ];
@@ -249,14 +243,16 @@ function validateNoActiveRecording(activeSession: SessionState): DaemonResponse
 function validateRecordingStartFlags(flags: {
   fpsFlag: number | undefined;
   qualityFlag: RecordingQualityInput;
-  maxSizeFlag: number | undefined;
 }): DaemonResponse | null {
-  const { fpsFlag, qualityFlag, maxSizeFlag } = flags;
-  return (
-    validateRecordingFpsFlag(fpsFlag) ??
-    validateRecordingQualityFlag(qualityFlag) ??
-    validateRecordingMaxSizeFlag(maxSizeFlag)
-  );
+  const { fpsFlag, qualityFlag } = flags;
+  return validateRecordingFpsFlag(fpsFlag) ?? validateRecordingQualityFlag(qualityFlag);
+}
+
+function validateRemovedRecordingMaxSizeFlag(flags: DaemonRequest['flags']): DaemonResponse | null {
+  const rawFlags = flags as Record<string, unknown> | undefined;
+  return rawFlags && Object.hasOwn(rawFlags, 'screenshotMaxSize')
+    ? errorResponse('INVALID_ARGS', 'record --max-size is not supported')
+    : null;
 }
 
 function validateRecordingFpsFlag(fpsFlag: number | undefined): DaemonResponse | null {
@@ -287,13 +283,6 @@ function validateRecordingQualityFlag(qualityFlag: RecordingQualityInput): Daemo
   return null;
 }
 
-function validateRecordingMaxSizeFlag(maxSizeFlag: number | undefined): DaemonResponse | null {
-  if (maxSizeFlag !== undefined && (!Number.isInteger(maxSizeFlag) || maxSizeFlag < 1)) {
-    return errorResponse('INVALID_ARGS', 'max-size must be a positive integer');
-  }
-  return null;
-}
-
 function prepareRecordingStart(
   req: DaemonRequest,
   backend: ReturnType<typeof resolveRecordingBackendForDevice>,
diff --git a/src/daemon/handlers/record-trace-types.ts b/src/daemon/handlers/record-trace-types.ts
index b43330dcca..fb4059a235 100644
--- a/src/daemon/handlers/record-trace-types.ts
+++ b/src/daemon/handlers/record-trace-types.ts
@@ -1,10 +1,6 @@
 import type { RecordingExportQuality, RecordingScope } from '@agent-device/contracts/recording';
 import type { runAppleRunnerCommand } from '../../platforms/apple/core/runner/runner-client.ts';
-import type {
-  overlayRecordingTouches,
-  resizeRecording,
-  trimRecordingStart,
-} from '../../recording/overlay.ts';
+import type { overlayRecordingTouches, trimRecordingStart } from '../../recording/overlay.ts';
 import type { runCmd } from '../../utils/exec.ts';
 import type { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
 import type { RecordingProvider } from '../recording-provider.ts';
@@ -20,7 +16,6 @@ export type RecordTraceDeps = {
   waitForStableFile: typeof waitForStableFile;
   isPlayableVideo: typeof isPlayableVideo;
   trimRecordingStart: typeof trimRecordingStart;
-  resizeRecording: typeof resizeRecording;
   overlayRecordingTouches: typeof overlayRecordingTouches;
 };
 
@@ -35,7 +30,6 @@ export type RecordingBase = {
     bundleId: string;
     name?: string;
   };
-  maxSize?: number;
   exportQuality?: RecordingExportQuality;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
diff --git a/src/daemon/request-generic-dispatch.ts b/src/daemon/request-generic-dispatch.ts
index 900a932ad7..f778522c48 100644
--- a/src/daemon/request-generic-dispatch.ts
+++ b/src/daemon/request-generic-dispatch.ts
@@ -217,7 +217,7 @@ async function executeScreenshotPlatformCommand(params: {
       device: session.device,
       path: data.path,
       requestedPixelDensity: request.flags?.screenshotPixelDensity,
-      maxSize: request.flags?.screenshotMaxSize,
+      scale: request.flags?.screenshotScale,
     }),
   );
   return data;
diff --git a/src/daemon/session-event-action.ts b/src/daemon/session-event-action.ts
index 9309a18f9d..cca238d27e 100644
--- a/src/daemon/session-event-action.ts
+++ b/src/daemon/session-event-action.ts
@@ -310,7 +310,7 @@ const SAFE_ACTION_FLAG_SPECS: Record<string, SafeFlagSpec> = {
     ],
     numbers: [
       { source: 'screenshotPixelDensity', output: 'pixelDensity' },
-      { source: 'screenshotMaxSize', output: 'maxSize' },
+      { source: 'screenshotScale', output: 'scale' },
     ],
   },
   [PUBLIC_COMMANDS.snapshot]: {
@@ -327,7 +327,7 @@ const SAFE_ACTION_FLAG_SPECS: Record<string, SafeFlagSpec> = {
   },
   [PUBLIC_COMMANDS.record]: {
     booleans: [{ source: 'hideTouches' }],
-    numbers: [{ source: 'fps' }, { source: 'screenshotMaxSize', output: 'maxSize' }],
+    numbers: [{ source: 'fps' }],
     enums: [{ source: 'recordingScope', output: 'scope', values: RECORDING_SCOPE_VALUES }],
   },
   [PUBLIC_COMMANDS.apps]: {
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 3390fb24a1..8c670bca59 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -288,7 +288,6 @@ type SessionRecordingBase = {
     bundleId: string;
     name?: string;
   };
-  maxSize?: number;
   exportQuality?: RecordingExportQuality;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
diff --git a/src/platforms/apple/core/__tests__/runner-client.test.ts b/src/platforms/apple/core/__tests__/runner-client.test.ts
index 22743bdce0..9d9f754052 100644
--- a/src/platforms/apple/core/__tests__/runner-client.test.ts
+++ b/src/platforms/apple/core/__tests__/runner-client.test.ts
@@ -182,7 +182,6 @@ const runnerProtocolCommandFixtures: Record<RunnerCommand['command'], RunnerComm
     command: 'recordStart',
     outPath: '/tmp/runner-recording.mp4',
     fps: 30,
-    maxSize: 720,
   },
   recordStop: { command: 'recordStop' },
   status: { command: 'status', statusCommandId: 'runner-command-1' },
@@ -384,7 +383,6 @@ test('runner protocol fixtures cover every runner command with JSON-safe samples
   assert.equal(roundTrip.screenshot!.fullscreen, true);
   assert.equal(roundTrip.rotate!.orientation, 'landscape-left');
   assert.equal(roundTrip.recordStart!.fps, 30);
-  assert.equal(roundTrip.recordStart!.maxSize, 720);
 });
 
 test('withRunnerCommandId replaces blank command ids', () => {
diff --git a/src/platforms/apple/core/runner/runner-contract.ts b/src/platforms/apple/core/runner/runner-contract.ts
index beaf283f50..35a64fa75b 100644
--- a/src/platforms/apple/core/runner/runner-contract.ts
+++ b/src/platforms/apple/core/runner/runner-contract.ts
@@ -90,7 +90,6 @@ export type RunnerCommand = {
   gesturePlan?: GesturePlan;
   outPath?: string;
   fps?: number;
-  maxSize?: number;
   interactiveOnly?: boolean;
   depth?: number;
   scope?: string;
diff --git a/src/recording/__tests__/overlay.test.ts b/src/recording/__tests__/overlay.test.ts
index 69ed8ddd2f..6f86d3b7a0 100644
--- a/src/recording/__tests__/overlay.test.ts
+++ b/src/recording/__tests__/overlay.test.ts
@@ -27,11 +27,7 @@ vi.mock('../../utils/video.ts', () => ({
   waitForPlayableVideo: vi.fn(async () => {}),
 }));
 
-import {
-  buildRecordingScriptPathCandidates,
-  overlayRecordingTouches,
-  resizeRecording,
-} from '../overlay.ts';
+import { buildRecordingScriptPathCandidates, overlayRecordingTouches } from '../overlay.ts';
 import { AppError } from '@agent-device/kernel/errors';
 import { runCmd } from '../../utils/exec.ts';
 
@@ -134,28 +130,6 @@ test('overlay forwards the requested high export preset', async () => {
   );
 });
 
-test('resize forwards max-size and defaults to the fast medium export preset', async () => {
-  const videoPath = path.join(tmpDir, 'recording.mp4');
-  fs.writeFileSync(videoPath, 'original');
-
-  await resizeRecording({ videoPath, maxSize: 1024 });
-
-  expect(helperScriptArgs()).toEqual(
-    expect.arrayContaining(['--max-size', '1024', '--quality', 'medium']),
-  );
-});
-
-test('resize forwards the requested high export preset', async () => {
-  const videoPath = path.join(tmpDir, 'recording.mp4');
-  fs.writeFileSync(videoPath, 'original');
-
-  await resizeRecording({ videoPath, maxSize: 720, exportQuality: 'high' });
-
-  expect(helperScriptArgs()).toEqual(
-    expect.arrayContaining(['--max-size', '720', '--quality', 'high']),
-  );
-});
-
 test('recording script candidates include packaged dist apple-runner source', () => {
   const packageRoot = path.join(tmpDir, 'package');
   const scriptPath = path.join(
diff --git a/src/recording/__tests__/recording-scripts.test.ts b/src/recording/__tests__/recording-scripts.test.ts
index 45e7b5a36c..45f7da53e4 100644
--- a/src/recording/__tests__/recording-scripts.test.ts
+++ b/src/recording/__tests__/recording-scripts.test.ts
@@ -48,18 +48,6 @@ test(
   SWIFT_TYPECHECK_TIMEOUT_MS,
 );
 
-test(
-  'recording resize Swift script typechecks',
-  async (t) => {
-    if (process.platform !== 'darwin') {
-      t.skip('Swift recording scripts are only validated on macOS');
-    }
-
-    await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-resize.swift'));
-  },
-  SWIFT_TYPECHECK_TIMEOUT_MS,
-);
-
 test(
   'recording inspect Swift script typechecks',
   async (t) => {
diff --git a/src/recording/overlay.ts b/src/recording/overlay.ts
index f9cd31d800..510355223c 100644
--- a/src/recording/overlay.ts
+++ b/src/recording/overlay.ts
@@ -54,7 +54,6 @@ function resolveRecordingScriptPath(scriptName: string): string {
 
 let overlayScriptPath: string | undefined;
 let trimScriptPath: string | undefined;
-let resizeScriptPath: string | undefined;
 
 export function getRecordingOverlaySupportWarning(
   hostPlatform: NodeJS.Platform = process.platform,
@@ -75,11 +74,6 @@ function getTrimScriptPath(): string {
   return trimScriptPath;
 }
 
-function getResizeScriptPath(): string {
-  resizeScriptPath ??= resolveRecordingScriptPath('recording-resize.swift');
-  return resizeScriptPath;
-}
-
 async function exportProcessedVideo(params: {
   videoPath: string;
   scriptPath: string;
@@ -164,23 +158,3 @@ export async function overlayRecordingTouches(params: {
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
   });
 }
-
-export async function resizeRecording(params: {
-  videoPath: string;
-  maxSize: number;
-  exportQuality?: RecordingExportQuality;
-  targetLabel?: string;
-}): Promise<void> {
-  const {
-    videoPath,
-    maxSize,
-    exportQuality = DEFAULT_RECORDING_EXPORT_QUALITY,
-    targetLabel = 'recording',
-  } = params;
-  await exportProcessedVideo({
-    videoPath,
-    scriptPath: getResizeScriptPath(),
-    scriptArgs: ['--max-size', String(maxSize), '--quality', exportQuality],
-    commandDescription: `Failed to resize the ${targetLabel}`,
-  });
-}
diff --git a/src/utils/__tests__/png-resize.test.ts b/src/utils/__tests__/png-resize.test.ts
index e29655323c..af8bc248c1 100644
--- a/src/utils/__tests__/png-resize.test.ts
+++ b/src/utils/__tests__/png-resize.test.ts
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from '../png.ts';
-import { resizePngFileToMaxSize } from '../png-resize.ts';
+import { resizePngFileToScale } from '../png-resize.ts';
 import { terminatePngWorker } from '../png-worker-client.ts';
 import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
 
@@ -11,34 +11,20 @@ afterAll(async () => {
   await terminatePngWorker();
 });
 
-test('resizePngFileToMaxSize leaves smaller images unchanged', async () => {
-  const filePath = tmpPngPath('unchanged');
-  const png = new PNG({ width: 4, height: 2 });
-  setPngPixel(png, 3, 1, 45, 90, 135);
-  fs.writeFileSync(filePath, PNG.sync.write(png));
-
-  await resizePngFileToMaxSize(filePath, 8);
-
-  const unchanged = PNG.sync.read(fs.readFileSync(filePath));
-  assert.equal(unchanged.width, 4);
-  assert.equal(unchanged.height, 2);
-  assert.deepEqual(readPngPixel(unchanged, 3, 1), [45, 90, 135, 255]);
-});
-
-test('resizePngFileToMaxSize shrinks the longest edge to the limit', async () => {
-  const filePath = tmpPngPath('shrunk');
-  const png = new PNG({ width: 8, height: 4 });
+test('resizePngFileToScale shrinks both dimensions proportionally', async () => {
+  const filePath = tmpPngPath('scaled');
+  const png = new PNG({ width: 10, height: 4 });
   for (let pixel = 0; pixel < png.width * png.height; pixel += 1) {
     setPngPixel(png, pixel % png.width, Math.floor(pixel / png.width), 40, 80, 120);
   }
   fs.writeFileSync(filePath, PNG.sync.write(png));
 
-  await resizePngFileToMaxSize(filePath, 4);
+  await resizePngFileToScale(filePath, 0.3);
 
   const resized = PNG.sync.read(fs.readFileSync(filePath));
-  assert.equal(resized.width, 4);
-  assert.equal(resized.height, 2);
-  assert.deepEqual(readPngPixel(resized, 3, 1), [40, 80, 120, 255]);
+  assert.equal(resized.width, 3);
+  assert.equal(resized.height, 1);
+  assert.deepEqual(readPngPixel(resized, 2, 0), [40, 80, 120, 255]);
 });
 
 function tmpPngPath(prefix: string): string {
diff --git a/src/utils/png-resize.ts b/src/utils/png-resize.ts
index 257f54658a..e9b783dedf 100644
--- a/src/utils/png-resize.ts
+++ b/src/utils/png-resize.ts
@@ -3,28 +3,30 @@ import { AppError } from '@agent-device/kernel/errors';
 import { PNG } from './png.ts';
 import { decodePngAsync, encodePngAsync } from './png-worker-client.ts';
 
-/**
- * Resizes a PNG file in place so its longest edge fits `maxSize`. Decode and
- * encode run on the PNG worker thread (daemon screenshot `--max-size` path);
- * the in-memory box-filter resample itself is cheap enough to stay inline.
- */
-export async function resizePngFileToMaxSize(filePath: string, maxSize: number): Promise<void> {
-  if (!Number.isInteger(maxSize) || maxSize < 1) {
-    throw new AppError('INVALID_ARGS', 'Screenshot max size must be a positive integer');
+/** Resizes a PNG in place by a proportional scale factor from 0.01 through 1. */
+export async function resizePngFileToScale(filePath: string, scale: number): Promise<void> {
+  if (!Number.isFinite(scale) || scale < 0.01 || scale > 1) {
+    throw new AppError('INVALID_ARGS', 'Screenshot scale must be between 0.01 and 1');
   }
+  if (scale === 1) return;
 
-  const source = await decodePngAsync(await fs.readFile(filePath), 'screenshot');
-  const longestEdge = Math.max(source.width, source.height);
-
-  if (longestEdge <= maxSize) {
-    return;
-  }
-
-  const scale = maxSize / longestEdge;
+  const source = await readPng(filePath);
   const width = Math.max(1, Math.round(source.width * scale));
   const height = Math.max(1, Math.round(source.height * scale));
-  const resized = resizePngBox(source, width, height);
+  await writeResizedPng(filePath, source, width, height);
+}
 
+async function readPng(filePath: string): Promise<PNG> {
+  return await decodePngAsync(await fs.readFile(filePath), 'screenshot');
+}
+
+async function writeResizedPng(
+  filePath: string,
+  source: PNG,
+  width: number,
+  height: number,
+): Promise<void> {
+  const resized = resizePngBox(source, width, height);
   await fs.writeFile(filePath, await encodePngAsync(resized));
 }
 
diff --git a/src/utils/screenshot-density.ts b/src/utils/screenshot-density.ts
index 523ecf8fbf..617ee758b9 100644
--- a/src/utils/screenshot-density.ts
+++ b/src/utils/screenshot-density.ts
@@ -41,7 +41,7 @@ export async function readScreenshotResultMetadata(params: {
   device: ScreenshotDensityDevice;
   path: string;
   requestedPixelDensity: number | undefined;
-  maxSize: number | undefined;
+  scale: number | undefined;
 }): Promise<ScreenshotResultData> {
   const requiresDensityMetadata = supportsScreenshotPixelDensity(params.device);
   let size: ScreenshotPixelSize;
@@ -55,7 +55,7 @@ export async function readScreenshotResultMetadata(params: {
     width: size.width,
     height: size.height,
   };
-  if (!requiresDensityMetadata || params.maxSize !== undefined) {
+  if (!requiresDensityMetadata || (params.scale !== undefined && params.scale !== 1)) {
     return result;
   }
 
diff --git a/src/utils/source-value.test.ts b/src/utils/source-value.test.ts
index 24ef08ed52..5f4d5cb4e6 100644
--- a/src/utils/source-value.test.ts
+++ b/src/utils/source-value.test.ts
@@ -156,6 +156,19 @@ describe('parseSourceValue integers', () => {
   });
 });
 
+describe('parseSourceValue numbers', () => {
+  test('accepts finite decimal numbers and numeric strings', () => {
+    expect(parse({ type: 'number' }, 0.3)).toBe(0.3);
+    expect(parse({ type: 'number' }, '0.75')).toBe(0.75);
+  });
+
+  test('rejects non-numeric input and enforces bounds', () => {
+    expectInvalidArgs(() => parse({ type: 'number' }, 'abc'), 'Expected number');
+    expectInvalidArgs(() => parse({ type: 'number', min: 0.01 }, 0), 'Must be >= 0.01');
+    expectInvalidArgs(() => parse({ type: 'number', max: 1 }, 1.1), 'Must be <= 1');
+  });
+});
+
 describe('parseSourceValue multiple', () => {
   test('maps over an array, parsing each entry with the singular definition', () => {
     expect(parse({ type: 'int', multiple: true }, ['1', '2', 3])).toEqual([1, 2, 3]);
diff --git a/src/utils/source-value.ts b/src/utils/source-value.ts
index 305d9546dc..64d1f22a27 100644
--- a/src/utils/source-value.ts
+++ b/src/utils/source-value.ts
@@ -1,7 +1,7 @@
 import { AppError } from '@agent-device/kernel/errors';
 
 export type SourceValueDefinition = {
-  type: 'boolean' | 'int' | 'enum' | 'string' | 'booleanOrString';
+  type: 'boolean' | 'int' | 'number' | 'enum' | 'string' | 'booleanOrString';
   multiple?: boolean;
   enumValues?: readonly string[];
   min?: number;
@@ -75,10 +75,10 @@ export function parseSourceValue(
   }
   const parsed =
     typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : Number.NaN;
-  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+  if (!Number.isFinite(parsed) || (definition.type === 'int' && !Number.isInteger(parsed))) {
     throw new AppError(
       'INVALID_ARGS',
-      `Invalid value for "${rawKey}" in ${sourceLabel}. Expected integer.`,
+      `Invalid value for "${rawKey}" in ${sourceLabel}. Expected ${definition.type === 'int' ? 'integer' : 'number'}.`,
     );
   }
   if (typeof definition.min === 'number' && parsed < definition.min) {
diff --git a/test/integration/android-emulator-e2e/live-capture-scenario.ts b/test/integration/android-emulator-e2e/live-capture-scenario.ts
index d25f769dbd..f575d78ee7 100644
--- a/test/integration/android-emulator-e2e/live-capture-scenario.ts
+++ b/test/integration/android-emulator-e2e/live-capture-scenario.ts
@@ -12,8 +12,8 @@ export async function assertCaptureAndClose(context: LiveContext): Promise<void>
   const screenshot = await runStep(context, 'capture fixture screenshot', [
     'screenshot',
     screenshotPath,
-    '--max-size',
-    '900',
+    '--scale',
+    '0.5',
   ]);
   assert.ok(
     JSON.stringify(screenshot.json?.data).includes(screenshotPath),
diff --git a/test/integration/android-emulator-e2e/live-observability-scenario.ts b/test/integration/android-emulator-e2e/live-observability-scenario.ts
index f3337bf71f..ba9de674bf 100644
--- a/test/integration/android-emulator-e2e/live-observability-scenario.ts
+++ b/test/integration/android-emulator-e2e/live-observability-scenario.ts
@@ -82,8 +82,6 @@ async function assertTraceAndRecording(context: LiveContext): Promise<void> {
     'start',
     recordingPath,
     '--hide-touches',
-    '--max-size',
-    '720',
   ]);
   await runStep(context, 'return to Android fixture home before recording', [
     'click',
diff --git a/test/integration/ios-simulator-e2e/live-runner.ts b/test/integration/ios-simulator-e2e/live-runner.ts
index 88f8ce4f8c..c07fee072d 100644
--- a/test/integration/ios-simulator-e2e/live-runner.ts
+++ b/test/integration/ios-simulator-e2e/live-runner.ts
@@ -232,8 +232,8 @@ async function assertCapture(context: LiveContext): Promise<void> {
   const screenshot = await runStep(context, 'capture fixture screenshot', [
     'screenshot',
     screenshotPath,
-    '--max-size',
-    '900',
+    '--scale',
+    '0.5',
   ]);
   assertJsonContains(screenshot, screenshotPath, 'screenshot response should return artifact path');
   assertPngFile(screenshotPath);
diff --git a/test/integration/live-device-e2e/assertions.ts b/test/integration/live-device-e2e/assertions.ts
index 53f7a521c1..20a91e2594 100644
--- a/test/integration/live-device-e2e/assertions.ts
+++ b/test/integration/live-device-e2e/assertions.ts
@@ -51,7 +51,7 @@ export function createLiveDeviceAssertions<
   }
 
   async function capturePng(context: Context, step: string, outputPath: string): Promise<void> {
-    await runStep(context, step, ['screenshot', outputPath, '--max-size', '900']);
+    await runStep(context, step, ['screenshot', outputPath, '--scale', '0.5']);
     assertPngFile(outputPath);
   }
 
diff --git a/test/integration/provider-scenarios/android-recording.test.ts b/test/integration/provider-scenarios/android-recording.test.ts
index 1f0dc9cbf7..26f0e6c092 100644
--- a/test/integration/provider-scenarios/android-recording.test.ts
+++ b/test/integration/provider-scenarios/android-recording.test.ts
@@ -895,7 +895,6 @@ async function exerciseAndroidRecordingFlow(context: {
 
   const recordStart = await context.daemon.callCommand('record', ['start', context.recordingPath], {
     hideTouches: true,
-    screenshotMaxSize: 1344,
     quality: 'high',
   });
   assertRecordingStarted(recordStart, { showTouches: false });
@@ -911,7 +910,10 @@ function assertAndroidRecordingFlow(context: {
 }): void {
   const { recordingPath, adbCalls, pullCalls } = context;
   assert.equal(fs.existsSync(recordingPath), true);
-  assertCommandCall(adbCalls, ['shell', 'wm', 'size']);
+  assert.equal(
+    adbCalls.some((args) => args.join(' ') === 'shell wm size'),
+    false,
+  );
   assert.ok(adbCalls.some((args) => isAndroidHighQualityScreenrecordStartCommand(args.join(' '))));
   assertCommandCall(adbCalls, ['shell', 'kill', '-2', '4321']);
   assert.equal(pullCalls.length, 1);
@@ -1551,20 +1553,6 @@ function androidAdbResult(args: string[]): {
   if (command === 'shell getprop sys.boot_completed') {
     return { stdout: '1\n', stderr: '', exitCode: 0 };
   }
-  if (command === 'shell wm size') {
-    return {
-      stdout: 'Physical size: 1440x2560\nOverride size: 1080x1920\n',
-      stderr: '',
-      exitCode: 0,
-    };
-  }
-  if (
-    /^shell screenrecord --size 756x1344 --bit-rate 20000000 \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
-      command,
-    )
-  ) {
-    return { stdout: '4321\n', stderr: '', exitCode: 0 };
-  }
   if (isAndroidScreenrecordStartCommand(command)) {
     return { stdout: '4321\n', stderr: '', exitCode: 0 };
   }
@@ -1582,13 +1570,13 @@ function androidAdbResult(args: string[]): {
 }
 
 function isAndroidScreenrecordStartCommand(command: string): boolean {
-  return /^shell screenrecord (?:--size 756x1344 )?--bit-rate (?:8000000|20000000) \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+  return /^shell screenrecord --bit-rate (?:8000000|20000000) \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
     command,
   );
 }
 
 function isAndroidHighQualityScreenrecordStartCommand(command: string): boolean {
-  return /^shell screenrecord --size 756x1344 --bit-rate 20000000 \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+  return /^shell screenrecord --bit-rate 20000000 \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
     command,
   );
 }
diff --git a/test/integration/provider-scenarios/assertions.ts b/test/integration/provider-scenarios/assertions.ts
index 2c39669b58..0557d16983 100644
--- a/test/integration/provider-scenarios/assertions.ts
+++ b/test/integration/provider-scenarios/assertions.ts
@@ -107,3 +107,9 @@ function pngSignature(): Buffer {
 export function assertPngFile(filePath: string): void {
   assert.deepEqual(fs.readFileSync(filePath).subarray(0, 8), pngSignature());
 }
+
+export function assertPngDimensions(filePath: string, width: number, height: number): void {
+  const png = PNG.sync.read(fs.readFileSync(filePath));
+  assert.equal(png.width, width);
+  assert.equal(png.height, height);
+}
diff --git a/test/integration/provider-scenarios/ios-record-trace.test.ts b/test/integration/provider-scenarios/ios-record-trace.test.ts
index 7a8e843a6c..d62018d648 100644
--- a/test/integration/provider-scenarios/ios-record-trace.test.ts
+++ b/test/integration/provider-scenarios/ios-record-trace.test.ts
@@ -124,7 +124,7 @@ async function recordPhysicalHappyPath(daemon: ScenarioDaemon, outPath: string):
   const start = await daemon.callCommand(
     'record',
     ['start', outPath],
-    { fps: 30, screenshotMaxSize: 720, quality: 'high', hideTouches: true },
+    { fps: 30, quality: 'high', hideTouches: true },
     { meta: { requestId: 'ios-physical-record-start' } },
   );
   assertRecordingStarted(start, { showTouches: false });
@@ -166,13 +166,11 @@ function assertPhysicalRecordingEvidence(
     {
       command: request?.command,
       fps: request?.fps,
-      maxSize: request?.maxSize,
       appBundleId: request?.appBundleId,
     },
     {
       command: 'recordStart',
       fps: 30,
-      maxSize: 720,
       appBundleId: 'com.apple.Preferences',
     },
   );
diff --git a/test/integration/provider-scenarios/macos-desktop.test.ts b/test/integration/provider-scenarios/macos-desktop.test.ts
index 88245c1d84..e3ef8870f9 100644
--- a/test/integration/provider-scenarios/macos-desktop.test.ts
+++ b/test/integration/provider-scenarios/macos-desktop.test.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import { test } from 'vitest';
-import { assertFlatToolCall, assertPngFile } from './assertions.ts';
+import { assertFlatToolCall, assertPngDimensions, assertPngFile } from './assertions.ts';
 import { PROVIDER_SCENARIO_MACOS } from './fixtures.ts';
 import { createProviderScenarioTempPath, withProviderScenarioResource } from './harness.ts';
 import { createMacOsDesktopWorld } from './macos-world.ts';
@@ -90,6 +90,10 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
         'agent-device-provider-scenario-macos',
         'png',
       );
+      const scaledScreenshotPath = createProviderScenarioTempPath(
+        'agent-device-provider-scenario-macos-scaled',
+        'png',
+      );
       try {
         await runProviderScenario(daemon, [
           {
@@ -293,18 +297,30 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
             },
           },
           {
-            name: 'capture fullscreen desktop screenshot with max-size',
+            name: 'capture fullscreen desktop screenshot',
             command: 'screenshot',
             flags: {
               out: screenshotPath,
               screenshotFullscreen: true,
-              screenshotMaxSize: 1,
             },
             expectData: { path: screenshotPath },
             assert: () => {
               assertPngFile(screenshotPath);
             },
           },
+          {
+            name: 'capture token-conscious desktop screenshot with scale',
+            command: 'screenshot',
+            flags: {
+              out: scaledScreenshotPath,
+              screenshotFullscreen: true,
+              screenshotScale: 0.5,
+            },
+            expectData: { path: scaledScreenshotPath },
+            assert: () => {
+              assertPngDimensions(scaledScreenshotPath, 32, 32);
+            },
+          },
           {
             name: 'capture desktop surface snapshot',
             command: 'snapshot',
@@ -460,6 +476,15 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
           'desktop',
           '--fullscreen',
         ]);
+        assertFlatToolCall(appleTool.calls, [
+          'macos-helper',
+          'screenshot',
+          '--out',
+          scaledScreenshotPath,
+          '--surface',
+          'desktop',
+          '--fullscreen',
+        ]);
         assertFlatToolCall(appleTool.calls, [
           'macos-helper',
           'read',
@@ -505,6 +530,7 @@ test('Provider-backed integration macOS desktop flow uses semantic host and help
         ]);
       } finally {
         fs.rmSync(screenshotPath, { force: true });
+        fs.rmSync(scaledScreenshotPath, { force: true });
       }
       runnerTranscript.assertComplete();
     },
diff --git a/test/integration/provider-scenarios/macos-recording.test.ts b/test/integration/provider-scenarios/macos-recording.test.ts
index 24bcf620f7..ac129a95f1 100644
--- a/test/integration/provider-scenarios/macos-recording.test.ts
+++ b/test/integration/provider-scenarios/macos-recording.test.ts
@@ -21,7 +21,6 @@ test('Provider-backed integration macOS recording flow uses runner provider thro
         command: 'recordStart',
         outPath: recordingPath,
         fps: 30,
-        maxSize: 1024,
         appBundleId: 'com.apple.systempreferences',
       },
       result: {},
@@ -47,7 +46,6 @@ test('Provider-backed integration macOS recording flow uses runner provider thro
       const recordStart = await daemon.callCommand('record', ['start', recordingPath], {
         hideTouches: true,
         fps: 30,
-        screenshotMaxSize: 1024,
       });
       assertRecordingStarted(recordStart, { outPath: recordingPath, showTouches: false });
 
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index 90c0fe52c7..517f4b6510 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -320,7 +320,9 @@ Web probes sample HTML media elements. Host-system probes use `platform: 'macos'
 
 For Apple native profiling, call `perf({ area: 'cpu', subject: 'profile', action: 'start', kind: 'xctrace', template: 'Time Profiler', out: 'app.trace' })`, then stop with the same trace path and write a compact report with `action: 'report'`. `area: 'trace'` supports xctrace templates such as `Animation Hitches`. Responses include artifact paths and compact metadata only.
 
-`client.recording.record({ action: 'start', path, maxSize: 1024, quality: 'medium' })` starts a recording capped to a 1024 px longest edge with medium output quality.
+`client.recording.record({ action: 'start', path, quality: 'medium' })` starts a recording with medium output quality.
+
+`client.capture.screenshot({ path, scale: 0.3 })` captures a screenshot at 30% of its original width and height. `scale` accepts `0.01` through `1`.
 
 `client.batch.run({ steps })` accepts structured steps:
 `{ command: 'open', input: { app: 'settings' } }`. Step `input` uses the same fields as the
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 31b41fc5c1..6444595f0b 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -835,7 +835,7 @@ agent-device metro reload --bundle-url "http://localhost:8081/index.bundle?platf
 ```bash
 agent-device screenshot                 # Auto filename
 agent-device screenshot page.png        # Explicit screenshot path
-agent-device screenshot page.png --max-size 1024  # Downscale longest edge for agent-friendly artifacts
+agent-device screenshot page.png --scale 0.3  # Resize both dimensions to 30% for agent context
 agent-device screenshot page.png --overlay-refs  # Draw current @eN refs and target rectangles onto the PNG
 agent-device screenshot baseline.png --normalize-status-bar  # Normalize iOS simulator chrome for reusable diff baselines
 agent-device screenshot page.png --platform web --fullscreen  # On web, --fullscreen/--full/-f captures the entire document
@@ -850,16 +850,17 @@ agent-device record start               # Start app-scoped recording after open
 agent-device record start session.mp4   # Start app-scoped recording to explicit path
 agent-device record start session.mp4 --scope device  # Intentionally record the full simulator/device screen
 agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
-agent-device record start session.mp4 --max-size 1024 # Downscale longest edge
 agent-device record start session.mp4 --quality high # Higher-quality export (slower)
 agent-device record stop                # Stop active recording
 ```
 
 - Recordings always produce a video artifact. `record start` defaults to app scope and requires an active session from `open <app>`; use `--scope device` or `--scope system` to explicitly request whole-screen capture where the selected backend supports it, such as recordings that intentionally span the full screen, multiple apps, settings, home screen, or app transitions. When touch visualization is enabled, recordings also produce a gesture telemetry sidecar that can be used for post-processing or inspection.
-- `screenshot --max-size <px>` preserves aspect ratio and only downscales when the saved PNG's longest edge is larger than the requested size.
+- `screenshot --scale <factor>` proportionally resizes both dimensions. The accepted range is `0.01` through `1`; use `1` for full resolution.
+- Set `AGENT_DEVICE_SCREENSHOT_SCALE=0.3` (or `screenshotScale` in config) to mirror Argent-style token-conscious screenshot defaults. An explicit `--scale` overrides it.
+- Keep the scale default unset, or use `--scale 1`, when full-resolution screenshots are required for reusable pixel-diff baselines.
 - `screenshot --overlay-refs` captures a fresh full snapshot and burns visible `@eN` refs plus their target rectangles into the saved PNG.
 - `screenshot --normalize-status-bar` temporarily normalizes iOS simulator status-bar chrome for deterministic screenshot baselines; ordinary screenshots leave the simulator's current chrome visible.
-- `screenshot --max-size <px> --overlay-refs` writes a smaller image and draws refs for that final image size; avoid very small max sizes when text, icons, or labels need to remain readable.
+- `screenshot --scale <factor> --overlay-refs` writes a smaller image and draws refs for that final image size; avoid very small scales when text, icons, or labels need to remain readable.
 - `diff screenshot` compares the current live screenshot to `--baseline`, or compares `--baseline` to an optional saved `current.png` path without requiring an active session. Its text output reports ranked changed regions with screen-space rectangles, changed-pixel counts, and each region's share of the diff; JSON also includes normalized rectangles. The earlier best-effort `ocr` and `nonTextDeltas` analyzers are retired; their optional result fields remain for source compatibility but are no longer emitted, so use the baseline/current images and diff artifact with vision for qualitative interpretation. It writes a diff PNG with a light grayscale current-screen context, red-tinted changed pixels, and outlined changed regions when `--out` is provided. Live iOS simulator diffs normalize status-bar chrome by default; use `screenshot --normalize-status-bar` when capturing reusable baselines.
 - `diff screenshot --overlay-refs` additionally writes a separate current-screen overlay guide for live captures without using that annotated image for the pixel comparison. If current-screen refs intersect changed regions, the output lists the best ref matches under those regions. Saved-image comparisons do not have live accessibility refs, so `--overlay-refs` is unavailable when a `current.png` path is provided.
 - In `--json` mode, each overlay ref also includes a screenshot-space `center` point for coordinate fallback like `press <x> <y>`.
@@ -942,7 +943,6 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical iOS device capture is best-effort: dropped frames are expected and true 60 FPS is not guaranteed even with `--fps 60`.
 - Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
-- `--max-size <px>` preserves aspect ratio and only downscales when the recording's longest edge is larger than the requested size.
 - `--quality <medium|high>` controls recording output quality. Android maps it to `adb shell screenrecord --bit-rate`; Apple targets use it for export/encoding. `medium` is the default; pass `high` for evidence, release notes, or debugging visual artifacts. Legacy numeric values are still accepted for compatibility: `5`-`7` map to `medium`, and `8`-`10` map to `high`.
 
 ## Tracing
diff --git a/website/docs/docs/configuration.md b/website/docs/docs/configuration.md
index 98883da39c..803d19767c 100644
--- a/website/docs/docs/configuration.md
+++ b/website/docs/docs/configuration.md
@@ -35,6 +35,7 @@ Environment variables follow the same fields using `AGENT_DEVICE_*` uppercase sn
 - `session` -> `AGENT_DEVICE_SESSION`
 - `daemonBaseUrl` -> `AGENT_DEVICE_DAEMON_BASE_URL`
 - `androidDeviceAllowlist` -> `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST`
+- `screenshotScale` -> `AGENT_DEVICE_SCREENSHOT_SCALE`
 
 Config and environment sources use canonical option values rather than CLI flag names. Example:
 - config: `"appsFilter": "user-installed"`
@@ -87,7 +88,7 @@ user- or explicit-config only:
 - request headers and structured install sources
 - local code and write destinations (`reporter`, `reportJunit`, `saveScript`, `launchConsole`)
 
-Project config can use project-safe command defaults such as `snapshotDepth`, `snapshotScope`, `activity`, `relaunch`, `shutdown`, `fps`, and `quality`. Local path and executable-module selectors such as `stepsFile` and `reporter` are user- or explicit-config only.
+Project config can use project-safe command defaults such as `snapshotDepth`, `snapshotScope`, `screenshotScale`, `activity`, `relaunch`, `shutdown`, `fps`, and `quality`. Local path and executable-module selectors such as `stepsFile` and `reporter` are user- or explicit-config only.
 
 `install-from-source` can read a structured GitHub Actions artifact source from user or explicit config when a compatible remote daemon resolves CI artifacts server-side. Repository config rejects this operator-controlled source:
 
@@ -115,7 +116,7 @@ These env vars are the supported user-facing configuration surface. Other `AGENT
 
 | Category | Env vars | Decision |
 | --- | --- | --- |
-| CLI defaults and config | `AGENT_DEVICE_CONFIG`, `AGENT_DEVICE_SESSION`, `AGENT_DEVICE_PLATFORM`, `AGENT_DEVICE_SESSION_LOCK`, `AGENT_DEVICE_DAEMON_BASE_URL`, `AGENT_DEVICE_DAEMON_AUTH_TOKEN`, `AGENT_DEVICE_CLOUD_BASE_URL` | Public |
+| CLI defaults and config | `AGENT_DEVICE_CONFIG`, `AGENT_DEVICE_SESSION`, `AGENT_DEVICE_PLATFORM`, `AGENT_DEVICE_SCREENSHOT_SCALE`, `AGENT_DEVICE_SESSION_LOCK`, `AGENT_DEVICE_DAEMON_BASE_URL`, `AGENT_DEVICE_DAEMON_AUTH_TOKEN`, `AGENT_DEVICE_CLOUD_BASE_URL` | Public |
 | Device scoping | `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` | Public |
 | Local daemon storage | `AGENT_DEVICE_STATE_DIR` | Public |
 | Metro and install helpers | `AGENT_DEVICE_METRO_BEARER_TOKEN`, `AGENT_DEVICE_BUNDLETOOL_JAR` | Public |
@@ -130,6 +131,7 @@ Command-specific keys are applied only when the current command supports them.
 Examples:
 - A default `snapshotDepth` applies to `snapshot`, `diff snapshot`, `click`, `fill`, `get`, `wait`, `find`, and `is`.
 - The same `snapshotDepth` value is ignored for commands like `open`, `close`, or `devices`.
+- A default `screenshotScale` (or `AGENT_DEVICE_SCREENSHOT_SCALE`) applies to `screenshot`; an explicit `--scale` wins.
 
 This keeps one shared config file usable across different command families.
 

From a6881be0b785dc0295a52fb167921c6e7417acd9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 6 Aug 2026 08:24:45 +0200
Subject: [PATCH 2/4] fix: refuse retired --max-size inputs on every released
 surface

Released sizing inputs must fail closed with migration guidance instead of
silently producing native-size artifacts:

- contracts: RETIRED_SCREENSHOT_MAX_SIZE declaration + SCREENSHOT_SCALE_LIMITS
  as the single source for the scale bounds and migration messages
- .ad parser: released 'screenshot ... --max-size N' and 'record start ...
  --max-size N' lines now refuse at parse time (frozen replay-compat witnesses)
- daemon: screenshot rejects old-client screenshotMaxSize like recording does;
  the recording guard now shares the same contract data
- Node client: screenshot/record daemon writers refuse the removed { maxSize }
  option before transport
- CLI: --max-size unknown-flag error carries the migration guidance
- config/env: stale screenshotMaxSize config keys and the retired
  AGENT_DEVICE_SCREENSHOT_MAX_SIZE env var are refused for sizing commands
  (other commands keep working)

Quality: numberField now reuses the canonical readOptionalNumber contract
helper (AppError bounds instead of plain Error); png-resize inlines one-use
wrappers and restores the worker-thread rationale; docs typo fixed.
---
 .../src/internal/__tests__/script.test.ts     | 18 +++++
 packages/ad-script/src/internal/script.ts     |  8 ++-
 packages/contracts/src/input-validation.ts    | 19 ++++++
 packages/contracts/src/screenshot.ts          | 65 +++++++++++++++++--
 scripts/layering/facade-symbols.ts            |  5 ++
 src/__tests__/cli-config.test.ts              | 52 +++++++++++++++
 src/__tests__/client.test.ts                  | 32 +++++++++
 src/cli-schema/cli-config.ts                  | 24 +++++++
 .../__tests__/args-parse-interaction.test.ts  | 14 +++-
 src/cli/parser/command-suggestions.ts         |  4 ++
 .../capture/screenshot-options.test.ts        | 18 +++++
 src/commands/capture/screenshot.ts            |  5 +-
 src/commands/command-input.ts                 | 24 ++-----
 src/commands/recording/index.ts               |  8 ++-
 .../request-router-screenshot.test.ts         | 34 +++++++++-
 .../handlers/__tests__/record-trace.test.ts   |  4 +-
 src/daemon/handlers/record-trace-recording.ts |  7 +-
 src/daemon/request-generic-dispatch.ts        |  5 +-
 src/utils/png-resize.ts                       | 30 ++++-----
 website/docs/docs/commands.md                 |  4 +-
 20 files changed, 321 insertions(+), 59 deletions(-)

diff --git a/packages/ad-script/src/internal/__tests__/script.test.ts b/packages/ad-script/src/internal/__tests__/script.test.ts
index 612cee029f..72a0d3e810 100644
--- a/packages/ad-script/src/internal/__tests__/script.test.ts
+++ b/packages/ad-script/src/internal/__tests__/script.test.ts
@@ -60,6 +60,24 @@ test('record replay script parses fps, quality, and hide-touches flags', () => {
   assert.equal(parsed[0]?.flags.hideTouches, true);
 });
 
+// Frozen replay-compat witnesses: these exact `--max-size` lines shipped in
+// released `.ad` scripts. The retired flag must be refused with migration
+// guidance — it must never silently degrade into extra positionals and a
+// native-size capture. Do not update these inputs; they pin released syntax.
+test('released screenshot --max-size lines are refused with migration guidance', () => {
+  assert.throws(() => parseReplayScriptDetailed('screenshot "./page.png" --max-size 1024\n'), {
+    code: 'INVALID_ARGS',
+    message: /screenshot --max-size was removed; use --scale/,
+  });
+});
+
+test('released record --max-size lines are refused with migration guidance', () => {
+  assert.throws(() => parseReplayScriptDetailed('record start "./capture.mp4" --max-size 1024\n'), {
+    code: 'INVALID_ARGS',
+    message: /record --max-size was removed/,
+  });
+});
+
 test('screenshot replay script round-trips screenshot flags', () => {
   const actions: SessionAction[] = [
     {
diff --git a/packages/ad-script/src/internal/script.ts b/packages/ad-script/src/internal/script.ts
index b9d10553b2..41ea7bff9d 100644
--- a/packages/ad-script/src/internal/script.ts
+++ b/packages/ad-script/src/internal/script.ts
@@ -1,7 +1,10 @@
 import { AppError } from '@agent-device/kernel/errors';
 import { recordingQualityInputToExportQuality } from '@agent-device/contracts/recording';
 import { describeReplayGestureArityError } from '@agent-device/contracts/interaction';
-import { readScreenshotScriptFlag } from '@agent-device/contracts/capture';
+import {
+  RETIRED_SCREENSHOT_MAX_SIZE,
+  readScreenshotScriptFlag,
+} from '@agent-device/contracts/capture';
 import type { DeviceTarget, PlatformSelector } from '@agent-device/kernel/device';
 import { PLATFORM_SELECTORS } from '@agent-device/kernel/device';
 import { parseReplayOpenFlags } from './open-script.ts';
@@ -415,6 +418,9 @@ function parseReplayScriptLine(line: string): SessionAction | null {
     const positionals: string[] = [];
     for (let index = 0; index < args.length; index += 1) {
       const token = args[index]!;
+      if (token === RETIRED_SCREENSHOT_MAX_SIZE.cliToken) {
+        throw new AppError('INVALID_ARGS', RETIRED_SCREENSHOT_MAX_SIZE.migration.record);
+      }
       if (token === '--hide-touches') {
         action.flags.hideTouches = true;
         continue;
diff --git a/packages/contracts/src/input-validation.ts b/packages/contracts/src/input-validation.ts
index 169f1c53e7..25eee8dd81 100644
--- a/packages/contracts/src/input-validation.ts
+++ b/packages/contracts/src/input-validation.ts
@@ -19,3 +19,22 @@ export function readOptionalInteger(
   }
   return numberValue;
 }
+
+export function readOptionalNumber(
+  record: Record<string, unknown>,
+  key: string,
+  options: { min?: number; max?: number } = {},
+): number | undefined {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new AppError('INVALID_ARGS', `Expected ${key} to be a finite number.`);
+  }
+  if (options.min !== undefined && value < options.min) {
+    throw new AppError('INVALID_ARGS', `Expected ${key} to be at least ${options.min}.`);
+  }
+  if (options.max !== undefined && value > options.max) {
+    throw new AppError('INVALID_ARGS', `Expected ${key} to be at most ${options.max}.`);
+  }
+  return value;
+}
diff --git a/packages/contracts/src/screenshot.ts b/packages/contracts/src/screenshot.ts
index 916ff1464d..04ccf20ea3 100644
--- a/packages/contracts/src/screenshot.ts
+++ b/packages/contracts/src/screenshot.ts
@@ -1,5 +1,49 @@
 import { AppError } from '@agent-device/kernel/errors';
 
+export const SCREENSHOT_SCALE_LIMITS = { min: 0.01, max: 1 } as const;
+
+/**
+ * `--max-size` shipped in released CLIs, `.ad` scripts, Node options
+ * (`maxSize`), request flags (`screenshotMaxSize`), and the derived
+ * `AGENT_DEVICE_SCREENSHOT_MAX_SIZE` env var. Every surface that used to honor
+ * it must refuse with this migration guidance — sizing must never disappear
+ * silently.
+ */
+export const RETIRED_SCREENSHOT_MAX_SIZE = {
+  flagKey: 'screenshotMaxSize',
+  cliToken: '--max-size',
+  envVar: 'AGENT_DEVICE_SCREENSHOT_MAX_SIZE',
+  publicOptionKey: 'maxSize',
+  migration: {
+    screenshot:
+      'screenshot --max-size was removed; use --scale <0.01-1> (or AGENT_DEVICE_SCREENSHOT_SCALE) to downscale proportionally',
+    record: 'record --max-size was removed; recordings capture at native resolution',
+  },
+} as const;
+
+type RetiredMaxSizeCommand = keyof typeof RETIRED_SCREENSHOT_MAX_SIZE.migration;
+
+export function retiredScreenshotMaxSizeFlagError(
+  command: RetiredMaxSizeCommand,
+  flags: object | undefined,
+): string | undefined {
+  return flags && Object.hasOwn(flags, RETIRED_SCREENSHOT_MAX_SIZE.flagKey)
+    ? RETIRED_SCREENSHOT_MAX_SIZE.migration[command]
+    : undefined;
+}
+
+export function validateNoRetiredScreenshotMaxSize(
+  command: RetiredMaxSizeCommand,
+  input: object,
+): void {
+  if (
+    Object.hasOwn(input, RETIRED_SCREENSHOT_MAX_SIZE.publicOptionKey) ||
+    Object.hasOwn(input, RETIRED_SCREENSHOT_MAX_SIZE.flagKey)
+  ) {
+    throw new AppError('INVALID_ARGS', RETIRED_SCREENSHOT_MAX_SIZE.migration[command]);
+  }
+}
+
 export const SCREENSHOT_COMMAND_FLAG_KEYS = [
   'out',
   'overlayRefs',
@@ -52,8 +96,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
     key: 'screenshotScale',
     names: ['--scale'],
     type: 'number',
-    min: 0.01,
-    max: 1,
+    min: SCREENSHOT_SCALE_LIMITS.min,
+    max: SCREENSHOT_SCALE_LIMITS.max,
     usageLabel: '--scale <0.01-1>',
     usageDescription:
       'Screenshot: resize both dimensions by this factor (or use AGENT_DEVICE_SCREENSHOT_SCALE)',
@@ -95,8 +139,8 @@ const SCREENSHOT_SCRIPT_NUMBER_FLAGS = [
     token: '--scale',
     key: 'screenshotScale',
     label: 'screenshot --scale',
-    min: 0.01,
-    max: 1,
+    min: SCREENSHOT_SCALE_LIMITS.min,
+    max: SCREENSHOT_SCALE_LIMITS.max,
   },
 ] as const;
 
@@ -173,6 +217,11 @@ export function screenshotFlagsFromOptions(
   });
 }
 
+/**
+ * Also maps the public `scale` option. `screenshotFlagsFromOptions` is fed
+ * generic cross-command option bags where a bare `scale` key belongs to the
+ * pinch gesture, so only this screenshot-boundary projection may read it.
+ */
 export function screenshotFlagsFromPublicOptions(
   options: ScreenshotPublicOptions & Partial<ScreenshotRequestFlags> = {},
 ): Partial<ScreenshotRequestFlags> {
@@ -183,11 +232,12 @@ export function screenshotFlagsFromPublicOptions(
 }
 
 export function validateScreenshotScale(options: Pick<ScreenshotPublicOptions, 'scale'>): void {
+  const { min, max } = SCREENSHOT_SCALE_LIMITS;
   if (
     options.scale !== undefined &&
-    (!Number.isFinite(options.scale) || options.scale < 0.01 || options.scale > 1)
+    (!Number.isFinite(options.scale) || options.scale < min || options.scale > max)
   ) {
-    throw new AppError('INVALID_ARGS', 'screenshot scale must be between 0.01 and 1');
+    throw new AppError('INVALID_ARGS', `screenshot scale must be between ${min} and ${max}`);
   }
 }
 
@@ -213,6 +263,9 @@ export function readScreenshotScriptFlag(params: {
 }): { handled: true; nextIndex: number } | { handled: false } {
   const { args, flags, index } = params;
   const token = args[index];
+  if (token === RETIRED_SCREENSHOT_MAX_SIZE.cliToken) {
+    throw new AppError('INVALID_ARGS', RETIRED_SCREENSHOT_MAX_SIZE.migration.screenshot);
+  }
   return (
     readScreenshotBooleanScriptFlag(token, flags, index) ??
     readScreenshotIntScriptFlag({ args, index, flags, token }) ??
diff --git a/scripts/layering/facade-symbols.ts b/scripts/layering/facade-symbols.ts
index d036020bb7..68164776da 100644
--- a/scripts/layering/facade-symbols.ts
+++ b/scripts/layering/facade-symbols.ts
@@ -267,6 +267,7 @@ export const FACADE_SYMBOLS: readonly (readonly [string, readonly string[]])[] =
       'readBatchStepInputObject',
       'readBatchStepRecord',
       'readOptionalInteger',
+      'readOptionalNumber',
       'resolveIosDeviceDeepLinkBundleId',
     ],
   ],
@@ -477,8 +478,10 @@ export const FACADE_SYMBOLS: readonly (readonly [string, readonly string[]])[] =
       'DiffSnapshotCommandResult',
       'FindLocator',
       'PublicSnapshotCaptureAnnotations',
+      'RETIRED_SCREENSHOT_MAX_SIZE',
       'SCREENSHOT_ACTION_FLAG_KEYS',
       'SCREENSHOT_COMMAND_FLAG_KEYS',
+      'SCREENSHOT_SCALE_LIMITS',
       'SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS',
       'ScreenshotDispatchFlags',
       'ScreenshotPublicOptions',
@@ -503,12 +506,14 @@ export const FACADE_SYMBOLS: readonly (readonly [string, readonly string[]])[] =
       'readSerializedSnapshotCaptureAnnotations',
       'readSnapshotDiagnosticsSummary',
       'recordSnapshotTiming',
+      'retiredScreenshotMaxSizeFlagError',
       'screenshotFlagsFromOptions',
       'screenshotFlagsFromPublicOptions',
       'screenshotOptionsFromFlags',
       'snapshotCaptureAnnotationsFrom',
       'summarizeSnapshotDiagnostics',
       'summarizeSnapshotTimingSamples',
+      'validateNoRetiredScreenshotMaxSize',
       'validateScreenshotScale',
     ],
   ],
diff --git a/src/__tests__/cli-config.test.ts b/src/__tests__/cli-config.test.ts
index 15844410fe..a5bf157d53 100644
--- a/src/__tests__/cli-config.test.ts
+++ b/src/__tests__/cli-config.test.ts
@@ -66,6 +66,58 @@ test('screenshot scale supports env defaults with CLI precedence', async () => {
   fs.rmSync(root, { recursive: true, force: true });
 });
 
+test('retired screenshot max-size env var fails closed for sizing commands only', async () => {
+  const { root, home, project } = makeTempWorkspace();
+  const env = { HOME: home, AGENT_DEVICE_SCREENSHOT_MAX_SIZE: '900' };
+
+  const screenshot = await runCliCapture(['screenshot', 'env.png'], {
+    cwd: project,
+    env,
+    defaultResponse: { ok: true, data: { path: 'env.png' } },
+  });
+  assert.equal(screenshot.code, 1);
+  assert.match(screenshot.stderr, /AGENT_DEVICE_SCREENSHOT_MAX_SIZE was removed/);
+  assert.match(screenshot.stderr, /use --scale/);
+  assert.equal(screenshot.calls.length, 0);
+
+  const record = await runCliCapture(['record', 'stop'], {
+    cwd: project,
+    env,
+    defaultResponse: { ok: true, data: {} },
+  });
+  assert.equal(record.code, 1);
+  assert.match(record.stderr, /AGENT_DEVICE_SCREENSHOT_MAX_SIZE was removed/);
+
+  const unaffected = await runCliCapture(['devices', '--json'], {
+    cwd: project,
+    env,
+    defaultResponse: { ok: true, data: { devices: [] } },
+  });
+  assert.equal(unaffected.code, null);
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('retired screenshotMaxSize config key is refused with migration guidance', async () => {
+  const { root, home, project } = makeTempWorkspace();
+  fs.writeFileSync(
+    path.join(project, 'agent-device.json'),
+    JSON.stringify({ screenshotMaxSize: 900 }),
+  );
+
+  const result = await runCliCapture(['screenshot', 'config.png'], {
+    cwd: project,
+    env: { HOME: home },
+    defaultResponse: { ok: true, data: { path: 'config.png' } },
+  });
+
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /"screenshotMaxSize".*was removed/);
+  assert.match(result.stderr, /screenshotScale/);
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
 test('config can set appsFilter through canonical enum values', async () => {
   const { root, home, project } = makeTempWorkspace();
   fs.mkdirSync(path.join(home, '.agent-device'), { recursive: true });
diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts
index fa818dacfa..2d7d73bc90 100644
--- a/src/__tests__/client.test.ts
+++ b/src/__tests__/client.test.ts
@@ -1241,6 +1241,38 @@ test('gesture scale does not leak into screenshot sizing flags', async () => {
   await client.interactions.pinch({ scale: 0.8 });
 });
 
+// Released Node callers passed `{ maxSize }`; it must be refused with migration
+// guidance instead of being silently dropped into a native-size capture.
+test('capture.screenshot rejects the removed maxSize option before transport', async () => {
+  const setup = createTransport(async () => {
+    throw new Error('transport should not be reached for a retired option');
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await assert.rejects(
+    () =>
+      client.capture.screenshot({ maxSize: 1024 } as Parameters<
+        typeof client.capture.screenshot
+      >[0]),
+    /screenshot --max-size was removed; use --scale/,
+  );
+});
+
+test('recording.record rejects the removed maxSize option before transport', async () => {
+  const setup = createTransport(async () => {
+    throw new Error('transport should not be reached for a retired option');
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await assert.rejects(
+    () =>
+      client.recording.record({ action: 'start', maxSize: 720 } as Parameters<
+        typeof client.recording.record
+      >[0]),
+    /record --max-size was removed/,
+  );
+});
+
 test('capture.snapshot passes a digest (non-default level) payload through unnormalized', async () => {
   const digest = {
     nodeCount: 3,
diff --git a/src/cli-schema/cli-config.ts b/src/cli-schema/cli-config.ts
index 57bf550358..6a8fdc6bc5 100644
--- a/src/cli-schema/cli-config.ts
+++ b/src/cli-schema/cli-config.ts
@@ -10,6 +10,7 @@ import {
   parseOptionValueFromSource,
 } from './option-schema.ts';
 import { parseInstallSourceConfig } from '../utils/install-source-config.ts';
+import { RETIRED_SCREENSHOT_MAX_SIZE } from '@agent-device/contracts/capture';
 import type { EnvMap } from '../utils/env-map.ts';
 
 export function resolveConfigBackedFlagDefaults(options: {
@@ -199,6 +200,12 @@ function parseConfigObject(
     const key = rawKey as FlagKey;
     const spec = getOptionSpec(key);
     if (!spec) {
+      if (rawKey === RETIRED_SCREENSHOT_MAX_SIZE.flagKey) {
+        throw new AppError(
+          'INVALID_ARGS',
+          `Config key "${rawKey}" in ${origin.label} was removed; use "screenshotScale" (0.01-1) to downscale screenshots. Recordings capture at native resolution.`,
+        );
+      }
       throw new AppError('INVALID_ARGS', `Unknown config key "${rawKey}" in ${origin.label}.`);
     }
     if (!spec.configurable) {
@@ -227,7 +234,24 @@ function parseConfigObject(
   return flags;
 }
 
+// Commands that honored AGENT_DEVICE_SCREENSHOT_MAX_SIZE in released versions.
+// A stale env var must fail closed for them (sizing must not silently vanish)
+// while every other command keeps working.
+const RETIRED_MAX_SIZE_ENV_COMMANDS = new Set(['screenshot', 'record']);
+
 function readEnvFlagDefaults(env: EnvMap, command: string | null): Partial<CliFlags> {
+  const retiredEnvValue = env[RETIRED_SCREENSHOT_MAX_SIZE.envVar];
+  if (
+    command !== null &&
+    RETIRED_MAX_SIZE_ENV_COMMANDS.has(command) &&
+    typeof retiredEnvValue === 'string' &&
+    retiredEnvValue.trim().length > 0
+  ) {
+    throw new AppError(
+      'INVALID_ARGS',
+      `${RETIRED_SCREENSHOT_MAX_SIZE.envVar} was removed. ${RETIRED_SCREENSHOT_MAX_SIZE.migration[command === 'record' ? 'record' : 'screenshot']}`,
+    );
+  }
   const flags: Partial<CliFlags> = {};
   for (const spec of getConfigurableOptionSpecs(command)) {
     if (spec.key === 'installSource') continue;
diff --git a/src/cli/parser/__tests__/args-parse-interaction.test.ts b/src/cli/parser/__tests__/args-parse-interaction.test.ts
index 912509e50c..f2a0e25b06 100644
--- a/src/cli/parser/__tests__/args-parse-interaction.test.ts
+++ b/src/cli/parser/__tests__/args-parse-interaction.test.ts
@@ -211,13 +211,23 @@ test('parseArgs recognizes record --quality flag', () => {
   assert.equal(parsed.flags.quality, 'high');
 });
 
-test('parseArgs rejects removed record --max-size flag', () => {
+test('parseArgs rejects removed record --max-size flag with migration guidance', () => {
   assert.throws(
     () =>
       parseArgs(['record', 'start', './capture.mp4', '--max-size', '1024'], {
         strictFlags: true,
       }),
-    /Unknown flag: --max-size/,
+    /Unknown flag: --max-size\. .*record --max-size was removed/,
+  );
+});
+
+test('parseArgs rejects removed screenshot --max-size flag with migration guidance', () => {
+  assert.throws(
+    () =>
+      parseArgs(['screenshot', 'page.png', '--max-size', '1024'], {
+        strictFlags: true,
+      }),
+    /Unknown flag: --max-size\. screenshot --max-size was removed; use --scale/,
   );
 });
 
diff --git a/src/cli/parser/command-suggestions.ts b/src/cli/parser/command-suggestions.ts
index 2973078cd3..5ed06293e9 100644
--- a/src/cli/parser/command-suggestions.ts
+++ b/src/cli/parser/command-suggestions.ts
@@ -1,3 +1,4 @@
+import { RETIRED_SCREENSHOT_MAX_SIZE } from '@agent-device/contracts/capture';
 import { listCliCommandNames } from '../../command-catalog.ts';
 
 /**
@@ -162,5 +163,8 @@ export function formatUnknownFlagMessage(token: string): string {
   if (REMOVED_SESSION_LOCK_ALIASES.has(token.toLowerCase())) {
     return `Unknown flag: ${token}. Use --session-lock reject|strip instead.`;
   }
+  if (token.toLowerCase() === RETIRED_SCREENSHOT_MAX_SIZE.cliToken) {
+    return `Unknown flag: ${token}. ${RETIRED_SCREENSHOT_MAX_SIZE.migration.screenshot}. ${RETIRED_SCREENSHOT_MAX_SIZE.migration.record}.`;
+  }
   return `Unknown flag: ${token}`;
 }
diff --git a/src/commands/capture/screenshot-options.test.ts b/src/commands/capture/screenshot-options.test.ts
index 4108e4298e..af477d08f4 100644
--- a/src/commands/capture/screenshot-options.test.ts
+++ b/src/commands/capture/screenshot-options.test.ts
@@ -9,6 +9,7 @@ import {
   screenshotFlagsFromOptions,
   screenshotFlagsFromPublicOptions,
   screenshotOptionsFromFlags,
+  validateNoRetiredScreenshotMaxSize,
   validateScreenshotScale,
 } from '@agent-device/contracts/capture';
 
@@ -64,6 +65,23 @@ test('screenshot scale is bounded', () => {
   assert.throws(() => validateScreenshotScale({ scale: 1.01 }), /between 0\.01 and 1/);
 });
 
+test('retired max-size inputs are refused with migration guidance', () => {
+  assert.throws(
+    () => readScreenshotScriptFlag({ args: ['--max-size', '640'], index: 0, flags: {} }),
+    {
+      code: 'INVALID_ARGS',
+      message: /screenshot --max-size was removed; use --scale/,
+    },
+  );
+  assert.throws(() => validateNoRetiredScreenshotMaxSize('screenshot', { maxSize: 1024 }), {
+    message: /screenshot --max-size was removed/,
+  });
+  assert.throws(() => validateNoRetiredScreenshotMaxSize('record', { screenshotMaxSize: 720 }), {
+    message: /record --max-size was removed/,
+  });
+  assert.doesNotThrow(() => validateNoRetiredScreenshotMaxSize('screenshot', { scale: 0.3 }));
+});
+
 test('screenshot script flags use the shared recorded flag contract', () => {
   const parts: string[] = [];
   const flags = {};
diff --git a/src/commands/capture/screenshot.ts b/src/commands/capture/screenshot.ts
index 5c0dd11ca5..8a9cc6b8e5 100644
--- a/src/commands/capture/screenshot.ts
+++ b/src/commands/capture/screenshot.ts
@@ -3,8 +3,10 @@ import type { CaptureScreenshotOptions } from '@agent-device/contracts/client';
 import { SESSION_SURFACES } from '@agent-device/contracts/session';
 import {
   SCREENSHOT_COMMAND_FLAG_KEYS,
+  SCREENSHOT_SCALE_LIMITS,
   screenshotFlagsFromPublicOptions,
   screenshotOptionsFromFlags,
+  validateNoRetiredScreenshotMaxSize,
   validateScreenshotScale,
 } from '@agent-device/contracts/capture';
 import {
@@ -34,7 +36,7 @@ const screenshotCommandMetadata = defineFieldCommandMetadata(
       min: 1,
     }),
     fullscreen: booleanField(),
-    scale: numberField('Screenshot scale factor.', { min: 0.01, max: 1 }),
+    scale: numberField('Screenshot scale factor.', SCREENSHOT_SCALE_LIMITS),
     stabilize: booleanField(),
     normalizeStatusBar: booleanField(),
     surface: enumField(SESSION_SURFACES),
@@ -62,6 +64,7 @@ export const screenshotCliReader: CliReader = (positionals, flags) => ({
 });
 
 export const screenshotDaemonWriter: DaemonWriter = (input) => {
+  validateNoRetiredScreenshotMaxSize('screenshot', input);
   validateScreenshotScale(input as CaptureScreenshotOptions);
   return request(PUBLIC_COMMANDS.screenshot, optionalString(input.path), {
     ...input,
diff --git a/src/commands/command-input.ts b/src/commands/command-input.ts
index 637bdc7dba..7db7ddc6d5 100644
--- a/src/commands/command-input.ts
+++ b/src/commands/command-input.ts
@@ -4,7 +4,10 @@ import type {
   ElementTarget,
   InteractionTarget,
 } from '@agent-device/contracts/client';
-import { readOptionalInteger as optionalInteger } from '@agent-device/contracts/command';
+import {
+  readOptionalInteger as optionalInteger,
+  readOptionalNumber as optionalNumberValue,
+} from '@agent-device/contracts/command';
 import {
   DEVICE_TARGETS,
   PLATFORM_SELECTORS,
@@ -405,25 +408,6 @@ function requiredNumber(record: Record<string, unknown>, key: string): number {
   return value;
 }
 
-function optionalNumberValue(
-  record: Record<string, unknown>,
-  key: string,
-  options: { min?: number; max?: number } = {},
-): number | undefined {
-  const value = record[key];
-  if (value === undefined) return undefined;
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw new AppError('INVALID_ARGS', `Expected ${key} to be a finite number.`);
-  }
-  if (options.min !== undefined && value < options.min) {
-    throw new Error(`Expected ${key} to be at least ${options.min}.`);
-  }
-  if (options.max !== undefined && value > options.max) {
-    throw new Error(`Expected ${key} to be at most ${options.max}.`);
-  }
-  return value;
-}
-
 function optionalBoolean(record: Record<string, unknown>, key: string): boolean | undefined {
   const value = record[key];
   if (value === undefined) return undefined;
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index e2b5860bbf..e476fbd79f 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -1,4 +1,5 @@
 import type { RecordOptions } from '@agent-device/contracts/client';
+import { validateNoRetiredScreenshotMaxSize } from '@agent-device/contracts/capture';
 import {
   RECORDING_EXPORT_QUALITIES,
   RECORDING_SCOPE_VALUES,
@@ -94,10 +95,15 @@ export const traceCliReader: CliReader = (positionals, flags) => ({
   path: positionals[1],
 });
 
-export const recordDaemonWriter: DaemonWriter = direct(RECORD_COMMAND_NAME, (input) =>
+const recordDirectWriter = direct(RECORD_COMMAND_NAME, (input) =>
   recordingPositionals(input as RecordOptions),
 );
 
+export const recordDaemonWriter: DaemonWriter = (input) => {
+  validateNoRetiredScreenshotMaxSize('record', input);
+  return recordDirectWriter(input);
+};
+
 export const traceDaemonWriter: DaemonWriter = direct(TRACE_COMMAND_NAME, (input) =>
   recordingPositionals(input as RecordOptions),
 );
diff --git a/src/daemon/__tests__/request-router-screenshot.test.ts b/src/daemon/__tests__/request-router-screenshot.test.ts
index 5f7bd4d15f..18eeeacf99 100644
--- a/src/daemon/__tests__/request-router-screenshot.test.ts
+++ b/src/daemon/__tests__/request-router-screenshot.test.ts
@@ -20,7 +20,7 @@ vi.mock('../../platforms/android/app-lifecycle.ts', async (importOriginal) => {
 import { dispatchCommand } from '../../core/dispatch.ts';
 import { createRequestHandler } from '../request-router.ts';
 import { dispatchScreenshotViaRuntime } from '../screenshot-runtime.ts';
-import type { SessionState } from '../types.ts';
+import type { DaemonRequest, SessionState } from '../types.ts';
 import { LeaseRegistry } from '../lease-registry.ts';
 import { attachRefs } from '@agent-device/kernel/snapshot';
 import { PNG } from '../../utils/png.ts';
@@ -488,6 +488,38 @@ test('iOS simulator screenshot omits logical density metadata after --scale down
   }
 });
 
+test('screenshot rejects the removed max-size field from older remote clients', async () => {
+  const sessionStore = makeSessionStore('agent-device-router-screenshot-');
+  sessionStore.set('default', makeIosSession('default'));
+
+  mockDispatch.mockImplementation(async () => {
+    throw new Error('dispatch should not run for a retired-flag request');
+  });
+
+  const handler = createRequestHandler({
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    token: 'test-token',
+    sessionStore,
+    leaseRegistry: new LeaseRegistry(),
+    trackDownloadableArtifact: () => 'artifact-id',
+  });
+
+  const response = await handler({
+    token: 'test-token',
+    session: 'default',
+    command: 'screenshot',
+    positionals: ['./legacy-max-size.png'],
+    flags: { screenshotMaxSize: 720 } as unknown as DaemonRequest['flags'],
+    meta: { requestId: 'req-ios-screenshot-legacy-max-size' },
+  });
+
+  expect(response.ok).toBe(false);
+  if (!response.ok) {
+    expect(response.error.code).toBe('INVALID_ARGS');
+    expect(response.error.message).toContain('screenshot --max-size was removed; use --scale');
+  }
+});
+
 test('screenshot resolves --out flag path against request cwd', async () => {
   const callerCwd = mkdtempForTestSync('agent-device-screenshot-out-cwd-');
   const sessionStore = makeSessionStore('agent-device-router-screenshot-');
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index ae28b92d29..6f0788762b 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -549,7 +549,9 @@ test('record start rejects the removed max-size field from older remote clients'
     throw new Error(`expected recording start failure, got ${JSON.stringify(start)}`);
   }
   expect(start.error.code).toBe('INVALID_ARGS');
-  expect(start.error.message).toBe('record --max-size is not supported');
+  expect(start.error.message).toBe(
+    'record --max-size was removed; recordings capture at native resolution',
+  );
 });
 
 test('record start web requires an existing browser session', async () => {
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 7e7f4459ca..3f8709fd7d 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -8,6 +8,7 @@ import {
   recordingQualityInputToExportQuality,
 } from '@agent-device/contracts/recording';
 import { AppError, toAppErrorCode } from '@agent-device/kernel/errors';
+import { retiredScreenshotMaxSizeFlagError } from '@agent-device/contracts/capture';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveTargetDevice } from '../../core/dispatch.ts';
@@ -249,10 +250,8 @@ function validateRecordingStartFlags(flags: {
 }
 
 function validateRemovedRecordingMaxSizeFlag(flags: DaemonRequest['flags']): DaemonResponse | null {
-  const rawFlags = flags as Record<string, unknown> | undefined;
-  return rawFlags && Object.hasOwn(rawFlags, 'screenshotMaxSize')
-    ? errorResponse('INVALID_ARGS', 'record --max-size is not supported')
-    : null;
+  const message = retiredScreenshotMaxSizeFlagError('record', flags);
+  return message ? errorResponse('INVALID_ARGS', message) : null;
 }
 
 function validateRecordingFpsFlag(fpsFlag: number | undefined): DaemonResponse | null {
diff --git a/src/daemon/request-generic-dispatch.ts b/src/daemon/request-generic-dispatch.ts
index f778522c48..23925d086c 100644
--- a/src/daemon/request-generic-dispatch.ts
+++ b/src/daemon/request-generic-dispatch.ts
@@ -23,7 +23,8 @@ import {
   recordTouchVisualizationEvent,
 } from './recording-gestures.ts';
 import { markPostGestureStabilization } from './post-gesture-stabilization.ts';
-import { normalizeError } from '@agent-device/kernel/errors';
+import { AppError, normalizeError } from '@agent-device/kernel/errors';
+import { retiredScreenshotMaxSizeFlagError } from '@agent-device/contracts/capture';
 import { expireRefFrame } from './ref-frame.ts';
 import {
   resolveRefFrameEffect,
@@ -197,6 +198,8 @@ async function executeScreenshotPlatformCommand(params: {
   dispatchContext: DaemonCommandContext;
 }): Promise<Record<string, unknown>> {
   const { session, request, positionals, out, dispatchContext } = params;
+  const retiredMaxSize = retiredScreenshotMaxSizeFlagError('screenshot', request.flags);
+  if (retiredMaxSize) throw new AppError('INVALID_ARGS', retiredMaxSize);
   assertSupportedScreenshotPixelDensity(session.device, request.flags?.screenshotPixelDensity);
   const data = await dispatchScreenshotViaRuntime({
     session,
diff --git a/src/utils/png-resize.ts b/src/utils/png-resize.ts
index e9b783dedf..7bbab74696 100644
--- a/src/utils/png-resize.ts
+++ b/src/utils/png-resize.ts
@@ -1,33 +1,25 @@
 import { promises as fs } from 'node:fs';
 import { AppError } from '@agent-device/kernel/errors';
+import { SCREENSHOT_SCALE_LIMITS } from '@agent-device/contracts/capture';
 import { PNG } from './png.ts';
 import { decodePngAsync, encodePngAsync } from './png-worker-client.ts';
 
-/** Resizes a PNG in place by a proportional scale factor from 0.01 through 1. */
+/**
+ * Resizes a PNG file in place by a proportional scale factor. Decode and
+ * encode run on the PNG worker thread (daemon screenshot `--scale` path);
+ * the in-memory box-filter resample itself is cheap enough to stay inline.
+ */
 export async function resizePngFileToScale(filePath: string, scale: number): Promise<void> {
-  if (!Number.isFinite(scale) || scale < 0.01 || scale > 1) {
-    throw new AppError('INVALID_ARGS', 'Screenshot scale must be between 0.01 and 1');
+  const { min, max } = SCREENSHOT_SCALE_LIMITS;
+  if (!Number.isFinite(scale) || scale < min || scale > max) {
+    throw new AppError('INVALID_ARGS', `Screenshot scale must be between ${min} and ${max}`);
   }
   if (scale === 1) return;
 
-  const source = await readPng(filePath);
+  const source = await decodePngAsync(await fs.readFile(filePath), 'screenshot');
   const width = Math.max(1, Math.round(source.width * scale));
   const height = Math.max(1, Math.round(source.height * scale));
-  await writeResizedPng(filePath, source, width, height);
-}
-
-async function readPng(filePath: string): Promise<PNG> {
-  return await decodePngAsync(await fs.readFile(filePath), 'screenshot');
-}
-
-async function writeResizedPng(
-  filePath: string,
-  source: PNG,
-  width: number,
-  height: number,
-): Promise<void> {
-  const resized = resizePngBox(source, width, height);
-  await fs.writeFile(filePath, await encodePngAsync(resized));
+  await fs.writeFile(filePath, await encodePngAsync(resizePngBox(source, width, height)));
 }
 
 export async function resizePngFile(
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 6444595f0b..be8f16fefd 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -855,8 +855,8 @@ agent-device record stop                # Stop active recording
 ```
 
 - Recordings always produce a video artifact. `record start` defaults to app scope and requires an active session from `open <app>`; use `--scope device` or `--scope system` to explicitly request whole-screen capture where the selected backend supports it, such as recordings that intentionally span the full screen, multiple apps, settings, home screen, or app transitions. When touch visualization is enabled, recordings also produce a gesture telemetry sidecar that can be used for post-processing or inspection.
-- `screenshot --scale <factor>` proportionally resizes both dimensions. The accepted range is `0.01` through `1`; use `1` for full resolution.
-- Set `AGENT_DEVICE_SCREENSHOT_SCALE=0.3` (or `screenshotScale` in config) to mirror Argent-style token-conscious screenshot defaults. An explicit `--scale` overrides it.
+- `screenshot --scale <factor>` proportionally resizes both dimensions. The accepted range is `0.01` through `1`; use `1` for full resolution. The former `--max-size <px>` flag was removed and is refused with migration guidance wherever it appears (CLI, `.ad` scripts, Node options, config, and the retired `AGENT_DEVICE_SCREENSHOT_MAX_SIZE` env var).
+- Set `AGENT_DEVICE_SCREENSHOT_SCALE=0.3` (or `screenshotScale` in config) as a token-conscious screenshot default for agent workflows. An explicit `--scale` overrides it.
 - Keep the scale default unset, or use `--scale 1`, when full-resolution screenshots are required for reusable pixel-diff baselines.
 - `screenshot --overlay-refs` captures a fresh full snapshot and burns visible `@eN` refs plus their target rectangles into the saved PNG.
 - `screenshot --normalize-status-bar` temporarily normalizes iOS simulator status-bar chrome for deterministic screenshot baselines; ordinary screenshots leave the simulator's current chrome visible.

From 219cd83f9334848b95fd0477098d17e9933992f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 6 Aug 2026 08:47:12 +0200
Subject: [PATCH 3/4] test: drop retired maxSize entries from the MCP
 undocumented-input allowlist

---
 src/mcp/__tests__/command-tools.test.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/mcp/__tests__/command-tools.test.ts b/src/mcp/__tests__/command-tools.test.ts
index 0150eadc4b..58af3d9fa3 100644
--- a/src/mcp/__tests__/command-tools.test.ts
+++ b/src/mcp/__tests__/command-tools.test.ts
@@ -992,7 +992,6 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([
   'record.action',
   'record.fps',
   'record.hideTouches',
-  'record.maxSize',
   'record.path',
   'record.quality',
   'record.recordingScope',
@@ -1007,7 +1006,6 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([
   'replay.saveScript',
   'replay.update',
   'screenshot.fullscreen',
-  'screenshot.maxSize',
   'screenshot.normalizeStatusBar',
   'screenshot.overlayRefs',
   'screenshot.stabilize',

From 4cf4eb4a8aabe75a88fbbb96c7e7a97d213d7aca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Thu, 6 Aug 2026 12:28:34 +0200
Subject: [PATCH 4/4] fix: refuse retired maxSize at the MCP field-projection
 seam + release-provenance corpus witnesses

- readFieldInput silently dropped undeclared keys before the daemon writers
  could refuse them, so an MCP call carrying { maxSize } reached transport and
  returned native-size success. New retiredField() combinator declares the
  removed key in the field map: the projection seam refuses it with the
  canonical migration message and the JSON schema no longer advertises it.
  Real-route MCP executor regressions cover screenshot and record.
- replay-compat corpus: derived v0.20.5 witnesses for the released screenshot
  and record --max-size forms (SHA-256 pinned, new retired-capture-size
  coverage surface) so check:replay-compat proves the shipped syntax refuses
  with migration guidance instead of degrading silently.
---
 .../src/internal/__tests__/script.test.ts     |  9 ++---
 src/commands/capture/screenshot.ts            |  3 ++
 src/commands/command-input.ts                 | 27 +++++++++++++-
 src/commands/recording/index.ts               |  7 +++-
 src/mcp/__tests__/command-tools.test.ts       | 35 ++++++++++++++++++
 test/replay-compat/corpus.test.ts             |  1 +
 test/replay-compat/manifest.ts                | 36 +++++++++++++++++++
 .../scripts/docs/record-max-size.v0.20.5.ad   |  7 ++++
 .../docs/screenshot-max-size.v0.20.5.ad       |  6 ++++
 9 files changed, 125 insertions(+), 6 deletions(-)
 create mode 100644 test/replay-compat/scripts/docs/record-max-size.v0.20.5.ad
 create mode 100644 test/replay-compat/scripts/docs/screenshot-max-size.v0.20.5.ad

diff --git a/packages/ad-script/src/internal/__tests__/script.test.ts b/packages/ad-script/src/internal/__tests__/script.test.ts
index 72a0d3e810..d56d21c19f 100644
--- a/packages/ad-script/src/internal/__tests__/script.test.ts
+++ b/packages/ad-script/src/internal/__tests__/script.test.ts
@@ -60,10 +60,11 @@ test('record replay script parses fps, quality, and hide-touches flags', () => {
   assert.equal(parsed[0]?.flags.hideTouches, true);
 });
 
-// Frozen replay-compat witnesses: these exact `--max-size` lines shipped in
-// released `.ad` scripts. The retired flag must be refused with migration
-// guidance — it must never silently degrade into extra positionals and a
-// native-size capture. Do not update these inputs; they pin released syntax.
+// Parser-level witnesses of the retired `--max-size` refusal. The
+// release-provenance frozen forms live in the replay-compat corpus
+// (test/replay-compat/scripts/docs/{screenshot,record}-max-size.v0.20.5.ad);
+// these fast unit copies pin the same behavior at the parse seam: refusal
+// with migration guidance, never a silent degrade into extra positionals.
 test('released screenshot --max-size lines are refused with migration guidance', () => {
   assert.throws(() => parseReplayScriptDetailed('screenshot "./page.png" --max-size 1024\n'), {
     code: 'INVALID_ARGS',
diff --git a/src/commands/capture/screenshot.ts b/src/commands/capture/screenshot.ts
index 529e09173e..46d76f7dce 100644
--- a/src/commands/capture/screenshot.ts
+++ b/src/commands/capture/screenshot.ts
@@ -2,6 +2,7 @@ import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
 import type { CaptureScreenshotOptions } from '@agent-device/contracts/client';
 import { SESSION_SURFACES } from '@agent-device/contracts/session';
 import {
+  RETIRED_SCREENSHOT_MAX_SIZE,
   SCREENSHOT_COMMAND_FLAG_KEYS,
   SCREENSHOT_SCALE_LIMITS,
   screenshotFlagsFromPublicOptions,
@@ -14,6 +15,7 @@ import {
   enumField,
   integerField,
   numberField,
+  retiredField,
   stringField,
 } from '../command-input.ts';
 import { defineExecutableCommand } from '../command-contract.ts';
@@ -38,6 +40,7 @@ const screenshotCommandMetadata = defineFieldCommandMetadata(
     }),
     fullscreen: booleanField(),
     scale: numberField('Screenshot scale factor.', SCREENSHOT_SCALE_LIMITS),
+    maxSize: retiredField(RETIRED_SCREENSHOT_MAX_SIZE.migration.screenshot),
     stabilize: booleanField(),
     normalizeStatusBar: booleanField(),
     surface: enumField(SESSION_SURFACES),
diff --git a/src/commands/command-input.ts b/src/commands/command-input.ts
index 7db7ddc6d5..21b07203e9 100644
--- a/src/commands/command-input.ts
+++ b/src/commands/command-input.ts
@@ -141,6 +141,7 @@ export type CommandField<T> = {
   schema: JsonSchema;
   required: boolean;
   read: FieldReader<T>;
+  retired?: true;
 };
 
 export type CommandFieldMap = Record<string, CommandField<unknown>>;
@@ -172,6 +173,26 @@ export function stringField(description?: string): CommandField<string> {
   return optionalField(stringSchema(description), optionalString);
 }
 
+/**
+ * A released input key that was removed. Declared in the field map so the
+ * projection seam (`readFieldInput`) refuses it with migration guidance
+ * instead of silently dropping it; excluded from the JSON schema so tools no
+ * longer advertise it.
+ */
+export function retiredField(message: string): CommandField<never> {
+  return {
+    schema: { type: 'null' },
+    required: false,
+    retired: true,
+    read: (record, key) => {
+      if (Object.hasOwn(record, key)) {
+        throw new AppError('INVALID_ARGS', message);
+      }
+      return undefined;
+    },
+  };
+}
+
 export function numberField(
   description?: string,
   options: { min?: number; max?: number } = {},
@@ -543,7 +564,11 @@ function integerSchemaWithBounds(
 }
 
 function fieldProperties(fields: CommandFieldMap): Record<string, JsonSchema> {
-  return Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, field.schema]));
+  return Object.fromEntries(
+    Object.entries(fields)
+      .filter(([, field]) => !field.retired)
+      .map(([key, field]) => [key, field.schema]),
+  );
 }
 
 function requiredFieldNames(fields: CommandFieldMap): string[] {
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index 95efd423f8..81caaa9380 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -1,5 +1,8 @@
 import type { RecordOptions } from '@agent-device/contracts/client';
-import { validateNoRetiredScreenshotMaxSize } from '@agent-device/contracts/capture';
+import {
+  RETIRED_SCREENSHOT_MAX_SIZE,
+  validateNoRetiredScreenshotMaxSize,
+} from '@agent-device/contracts/capture';
 import {
   RECORDING_EXPORT_QUALITIES,
   RECORDING_SCOPE_VALUES,
@@ -14,6 +17,7 @@ import {
   enumField,
   integerField,
   requiredField,
+  retiredField,
   stringField,
 } from '../command-input.ts';
 import { defineCommandFacet, defineCommandFamilyFromFacets } from '../family/types.ts';
@@ -36,6 +40,7 @@ export const recordCommandMetadata = defineFieldCommandMetadata(
     action: requiredField(enumField(RECORDING_ACTION_VALUES)),
     path: stringField(),
     fps: integerField(),
+    maxSize: retiredField(RETIRED_SCREENSHOT_MAX_SIZE.migration.record),
     quality: enumField(RECORDING_EXPORT_QUALITIES),
     hideTouches: booleanField(),
     recordingScope: enumField(RECORDING_SCOPE_VALUES),
diff --git a/src/mcp/__tests__/command-tools.test.ts b/src/mcp/__tests__/command-tools.test.ts
index 58af3d9fa3..40c48bd3d3 100644
--- a/src/mcp/__tests__/command-tools.test.ts
+++ b/src/mcp/__tests__/command-tools.test.ts
@@ -1052,6 +1052,41 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([
   'wait.timeoutMs',
 ]);
 
+// Retired-input regressions run the REAL command route (no runCommand
+// injection): field projection used to silently drop the removed `maxSize`
+// key before the daemon writers could refuse it, returning native-size
+// success. The retired-field seam must refuse at projection, before any
+// client method or transport is reached.
+test('MCP screenshot refuses the removed maxSize input with migration guidance', async () => {
+  const executor = createCommandToolExecutor({
+    createClient: () => ({}) as AgentDeviceClient,
+  });
+
+  const result = await executor.execute('screenshot', { maxSize: 1024 });
+
+  assert.equal(result.isError, true);
+  assert.match(result.content[0]?.text ?? '', /screenshot --max-size was removed; use --scale/);
+});
+
+test('MCP record refuses the removed maxSize input with migration guidance', async () => {
+  const executor = createCommandToolExecutor({
+    createClient: () => ({}) as AgentDeviceClient,
+  });
+
+  const result = await executor.execute('record', { action: 'start', maxSize: 720 });
+
+  assert.equal(result.isError, true);
+  assert.match(result.content[0]?.text ?? '', /record --max-size was removed/);
+});
+
+test('MCP screenshot and record schemas do not advertise the retired maxSize input', () => {
+  for (const name of ['screenshot', 'record']) {
+    const tool = listCommandTools().find((candidate) => candidate.name === name);
+    assert.ok(tool);
+    assert.equal('maxSize' in (tool.inputSchema.properties ?? {}), false);
+  }
+});
+
 test('MCP tool inputs do not add undocumented properties', () => {
   const undescribed: string[] = [];
   for (const tool of listCommandTools()) {
diff --git a/test/replay-compat/corpus.test.ts b/test/replay-compat/corpus.test.ts
index 44697a0929..5f38ca3ffe 100644
--- a/test/replay-compat/corpus.test.ts
+++ b/test/replay-compat/corpus.test.ts
@@ -25,6 +25,7 @@ const REQUIRED_COVERAGE_KEYS: Record<ReplayCompatCoverage, true> = {
   'context-header': true,
   'env-vars': true,
   quoting: true,
+  'retired-capture-size': true,
   'retired-gesture': true,
   'target-annotation': true,
   'wait-landmark': true,
diff --git a/test/replay-compat/manifest.ts b/test/replay-compat/manifest.ts
index 449c047a48..3e63a73bd3 100644
--- a/test/replay-compat/manifest.ts
+++ b/test/replay-compat/manifest.ts
@@ -22,6 +22,7 @@ export const REPLAY_COMPAT_RELEASED_TAGS: readonly string[] = [
   'v0.16.0',
   'v0.16.8',
   'v0.20.0',
+  'v0.20.5',
 ];
 
 /**
@@ -49,6 +50,7 @@ export type ReplayCompatCoverage =
   | 'context-header'
   | 'env-vars'
   | 'quoting'
+  | 'retired-capture-size'
   | 'retired-gesture'
   | 'target-annotation'
   | 'wait-landmark';
@@ -396,4 +398,38 @@ export const REPLAY_COMPAT_CORPUS: ReplayCompatEntry[] = [
     },
     note: 'Pre-removal `gesture swipe` durationMs positional as the v0.16.8 recorder wrote it.',
   },
+  {
+    id: 'docs/screenshot-max-size@v0.20.5',
+    file: 'scripts/docs/screenshot-max-size.v0.20.5.ad',
+    recordedBy: 'v0.20.5',
+    provenance: {
+      kind: 'derived',
+      from: 'packages/contracts/src/screenshot.ts@v0.20.5 (appendScreenshotScriptFlags emitted `--max-size <px>` on recorded screenshot lines)',
+      sha256: '1e575d82ae56e0a828a09d220459ae1aab3059076817f1f64dc3cef243f19889',
+    },
+    covers: ['context-header', 'wait-landmark', 'quoting', 'retired-capture-size'],
+    verdict: {
+      kind: 'fails',
+      code: 'INVALID_ARGS',
+      hint: 'screenshot --max-size was removed; use --scale <0.01-1> (or AGENT_DEVICE_SCREENSHOT_SCALE) to downscale proportionally',
+    },
+    note: 'Pre-removal screenshot `--max-size` flag as the v0.20.5 recorder wrote it. Sole witness of the screenshot sizing migration refusal; without it a parser change could silently demote the flag to ignored positionals and capture at native size.',
+  },
+  {
+    id: 'docs/record-max-size@v0.20.5',
+    file: 'scripts/docs/record-max-size.v0.20.5.ad',
+    recordedBy: 'v0.20.5',
+    provenance: {
+      kind: 'derived',
+      from: 'packages/ad-script/src/internal/script-utils.ts@v0.20.5 (appendRecordActionScriptArgs emitted `--max-size <px>` between `--fps` and `--quality`)',
+      sha256: '882b415a1eb03fedae22526fa48ab6a46cd796d6341aadb0fc783682e2844378',
+    },
+    covers: ['context-header', 'retired-capture-size'],
+    verdict: {
+      kind: 'fails',
+      code: 'INVALID_ARGS',
+      hint: 'record --max-size was removed; recordings capture at native resolution',
+    },
+    note: 'Pre-removal record `--max-size` flag in the full recorded flag order as the v0.20.5 recorder wrote it. Sole witness of the recording sizing migration refusal.',
+  },
 ];
diff --git a/test/replay-compat/scripts/docs/record-max-size.v0.20.5.ad b/test/replay-compat/scripts/docs/record-max-size.v0.20.5.ad
new file mode 100644
index 0000000000..77bbe3a55c
--- /dev/null
+++ b/test/replay-compat/scripts/docs/record-max-size.v0.20.5.ad
@@ -0,0 +1,7 @@
+context platform=ios
+
+open "Agent Device Tester" --relaunch
+record start "./capture.mp4" --fps 24 --max-size 1024 --quality high --hide-touches
+wait "Gesture lab" 30000
+record stop
+close
diff --git a/test/replay-compat/scripts/docs/screenshot-max-size.v0.20.5.ad b/test/replay-compat/scripts/docs/screenshot-max-size.v0.20.5.ad
new file mode 100644
index 0000000000..47545eed10
--- /dev/null
+++ b/test/replay-compat/scripts/docs/screenshot-max-size.v0.20.5.ad
@@ -0,0 +1,6 @@
+context platform=ios
+
+open "Agent Device Tester" --relaunch
+wait "Gesture lab" 30000
+screenshot "./page.png" --max-size 1024
+close