@@ -115,6 +115,21 @@ test('the typed reason survives a changed human message and an unrelated exit co
   assert.equal(shouldRetryIosSimulatorScreenshot(error), true);
 });
 
+test.each(['\n', '\r\n'])(
+  'a PNG diagnostic before the stderr header preserves typed retry with line ending %j',
+  async (lineEnding) => {
+    const stderr = [
+      'Detected file type from extension: PNG',
+      ...protocolTimeout().split('\n'),
+    ].join(lineEnding);
+    const { error } = await captureScreenshot(() => commandFailed(stderr, 60));
+
+    assert.equal(details(error).stderr, stderr);
+    assert.equal(details(error).reason, SIMCTL_SCREENSHOT_TIMEOUT_REASON);
+    assert.equal(shouldRetryIosSimulatorScreenshot(error), true);
+  },
+);
+
 test('the adapter accepts a leading protocol header with CRLF line endings', async () => {
   const { error } = await captureScreenshot(() =>
     commandFailed(protocolTimeout().replaceAll('\n', '\r\n'), 60),
@@ -225,8 +240,8 @@ test('the adapter ignores a header that simctl did not print at the top level',
     ['nested underlying-error header only', () => commandFailed(nestedOnly, 149)],
     ['header printed on stdout instead of stderr', () => commandFailed('', 60, stdoutOnly)],
     [
-      'matching header after a diagnostic preamble',
-      () => commandFailed(`Diagnostic preamble\n${protocolTimeout()}`, 60),
+      'indented matching header after a diagnostic preamble',
+      () => commandFailed(`Detected file type from extension: PNG\n    ${protocolTimeout()}`, 60),
     ],
     [
       'matching header after an unrelated top-level error',
 
@@ -56,50 +56,24 @@ async function runSimctlCommand(
   return await runCommand('xcrun', [...simctlCommand(args)], options);
 }
 
-/**
- * simctl's own error-protocol header, printed once at the top of stderr ahead of the human
- * sentence it renders: `An error was encountered processing the command (domain=…, code=…):`.
- * The header line is the protocol; the text after it is CoreSimulator's prose. A nested
- * `Underlying error (…)` line is indented and is never this line.
- */
+/** The first unindented simctl error header; diagnostic lines can precede it on stderr. */
 const SIMCTL_ERROR_HEADER =
-  /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):[\t ]*(?:\r?\n|$)/;
+  /^An error was encountered processing the command \(domain=([^,]+), code=(-?\d+)\):[\t ]*(?:\r?\n|$)/m;
 
-/**
- * `NSPOSIXErrorDomain` code 60 is macOS `ETIMEDOUT`: the tool's own answer that the screenshot
- * call timed out. This is the only place that reads it, so the verdict becomes a typed reason here
- * and nothing downstream re-parses the tool's text. A nested `Underlying error (…)` line is
- * indented and is never the header, and a code the header does not state is not this reason.
- */
+/** macOS ETIMEDOUT in simctl's protocol, classified only by this local adapter. */
 const SIMCTL_SCREENSHOT_TIMEOUT_DOMAIN = 'NSPOSIXErrorDomain';
 const SIMCTL_SCREENSHOT_TIMEOUT_CODE = 60;
 
-/**
- * `details.reason` this adapter stamps when simctl's screenshot call reports its own protocol
- * timeout. Owned beside the parse that mints it; the screenshot retry and runner-fallback decisions
- * read the reason and never the tool's wording.
- */
+/** The local screenshot timeout reason consumed by retry and runner fallback. */
 export const SIMCTL_SCREENSHOT_TIMEOUT_REASON = 'simulator-screenshot-timeout';
 
-/**
- * The screenshot subcommand of an otherwise-unscoped simctl argv: `io <udid> screenshot …`. The
- * `--set <path>` prefix is stripped first, and the flag fragments simctl's screenshot options add
- * (`--mask=`, `--display=`) come after the subcommand, so positions 0 and 2 are the verb pair.
- */
+/** Screenshot options follow `io <udid> screenshot`; a simulator-set prefix precedes it. */
 function isSimctlScreenshotArgs(args: ScopedSimctlArgs): boolean {
   const unscoped = args[0] === '--set' ? args.slice(2) : args;
   return unscoped[0] === 'io' && unscoped[2] === 'screenshot';
 }
 
-/**
- * The local simctl adapter: the one producer that runs `xcrun simctl` itself, so the one place
- * allowed to read the tool's error protocol. A failed screenshot call answers with the typed
- * {@link SIMCTL_SCREENSHOT_TIMEOUT_CODE} reason and keeps every exit-failure detail the exec layer
- * would have produced; other failures, and other subcommands, keep exec's own behaviour.
- *
- * `reason` is stamped, never host-kit's `timeoutMs`: that field is exec's evidence that *it* killed
- * a child at its deadline, and `isCommandTimeoutError` reads it as such.
- */
+/** Stamp {@link SIMCTL_SCREENSHOT_TIMEOUT_REASON}, preserving exec's own timeout evidence. */
 async function runLocalSimctlCommand(
   args: ScopedSimctlArgs,
   options?: AppleToolExecOptions,