@@ -448,3 +448,14 @@ test('batch rejects a fill step that asks for stdin text before daemon dispatch'
   assert.equal(result.calls.length, 0);
   assert.match(result.stderr, /Batch step 1: fill textStdin is not supported/);
 });
+
+test('batch passes an explicit fill textStdin false through to dispatch', async () => {
+  const result = await runCliCapture([
+    'batch',
+    '--steps',
+    '[{"command":"fill","input":{"target":{"kind":"ref","ref":"@e3"},"text":"x","textStdin":false}}]',
+  ]);
+
+  assert.equal(result.calls.length, 1);
+  assert.doesNotMatch(result.stderr, /textStdin is not supported/);
+});
@@ -82,7 +82,7 @@ function assertNoStdinFillStep(
   input: CommandInput,
   stepNumber: number,
 ): void {
-  if (command !== PUBLIC_COMMANDS.fill || input.textStdin === undefined) return;
+  if (command !== PUBLIC_COMMANDS.fill || input.textStdin !== true) return;
   throw new AppError(
     'INVALID_ARGS',
     `Batch step ${stepNumber}: fill textStdin is not supported because batch steps have no stdin of their own. Run that fill on its own with --text-stdin.`,
 
@@ -38,20 +38,38 @@ test('accepts input exactly at the byte limit', async () => {
   expect(await readFillTextFromStdin(pipe(text))).toBe(text);
 });
 
+test('keeps a leading byte order mark', async () => {
+  expect(await readFillTextFromStdin(pipe(Buffer.from([0xef, 0xbb, 0xbf, 0x61])))).toBe('\uFEFFa');
+});
+
 test.each([
-  ['a terminal', () => terminal(), 'fill_text_stdin_tty'],
-  ['empty input', () => pipe(), 'fill_text_stdin_empty'],
-  ['input that is only a newline', () => pipe('\n'), 'fill_text_stdin_empty'],
+  ['a terminal', () => terminal(), 'fill_text_stdin_tty', undefined],
+  ['empty input', () => pipe(), 'fill_text_stdin_empty', undefined],
+  ['input that is only a newline', () => pipe('\n'), 'fill_text_stdin_empty', undefined],
   [
     'input over the byte limit',
     () => pipe('s3cret'.repeat(FILL_TEXT_STDIN_MAX_BYTES)),
     'fill_text_stdin_too_large',
+    's3cret',
+  ],
+  [
+    'invalid UTF-8 bytes',
+    () => pipe(Buffer.from('bad-bytes-'), Buffer.from([0xff])),
+    'fill_text_stdin_invalid_utf8',
+    'bad-bytes-',
   ],
-  ['invalid UTF-8', () => pipe(Buffer.from([0x73, 0x33, 0xff])), 'fill_text_stdin_invalid_utf8'],
-])('refuses %s with a typed reason and no echoed input', async (_name, stdin, reason) => {
+  [
+    'a string chunk with a lone surrogate',
+    () => pipe('lone-surrogate-\uD800'),
+    'fill_text_stdin_invalid_utf8',
+    'lone-surrogate-',
+  ],
+])('refuses %s with a typed reason and no echoed input', async (_name, stdin, reason, input) => {
   const error = await readError(stdin());
 
   expect(error.code).toBe('INVALID_ARGS');
   expect(error.details?.reason).toBe(reason);
-  expect(JSON.stringify({ message: error.message, details: error.details })).not.toMatch(/s3cret/);
+  if (input !== undefined) {
+    expect(JSON.stringify({ message: error.message, details: error.details })).not.toContain(input);
+  }
 });
@@ -6,9 +6,10 @@ export const FILL_TEXT_STDIN_MAX_BYTES = 64 * 1024;
 type StdinSource = AsyncIterable<Uint8Array | string> & { isTTY?: boolean };
 
 /**
- * Reads the `fill --text-stdin` value. Exactly one trailing `\n` or `\r\n` is removed so
- * `echo "$X"` and `printf '%s' "$X"` send the same text; all other whitespace is kept.
- * The value may be a secret: no error raised here includes any of the bytes read.
+ * Reads the `fill --text-stdin` value. Exactly one trailing `\n` or `\r\n` is removed so a value
+ * piped with or without a final newline sends the same text; all other whitespace, including a
+ * leading byte order mark, is kept. The value may be a secret: no error raised here includes any
+ * of the bytes read.
  */
 export async function readFillTextFromStdin(stdin: StdinSource): Promise<string> {
   if (stdin.isTTY) {
@@ -24,7 +25,7 @@ export async function readFillTextFromStdin(stdin: StdinSource): Promise<string>
   const chunks: Uint8Array[] = [];
   let byteLength = 0;
   for await (const chunk of stdin) {
-    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+    const bytes = typeof chunk === 'string' ? encodeWellFormed(chunk) : chunk;
     byteLength += bytes.byteLength;
     if (byteLength > FILL_TEXT_STDIN_MAX_BYTES) {
       throw new AppError(
@@ -45,16 +46,28 @@ export async function readFillTextFromStdin(stdin: StdinSource): Promise<string>
   return text;
 }
 
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/** `Buffer.from` would turn a lone surrogate into U+FFFD; refuse it like an invalid byte. */
+function encodeWellFormed(chunk: string): Uint8Array {
+  if (LONE_SURROGATE.test(chunk)) throw invalidUtf8Error();
+  return Buffer.from(chunk, 'utf8');
+}
+
 function decodeUtf8(bytes: Uint8Array): string {
   try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
   } catch {
-    throw new AppError('INVALID_ARGS', 'fill --text-stdin input is not valid UTF-8.', {
-      reason: 'fill_text_stdin_invalid_utf8',
-    });
+    throw invalidUtf8Error();
   }
 }
 
+function invalidUtf8Error(): AppError {
+  return new AppError('INVALID_ARGS', 'fill --text-stdin input is not valid UTF-8.', {
+    reason: 'fill_text_stdin_invalid_utf8',
+  });
+}
+
 function stripOneTrailingNewline(text: string): string {
   if (text.endsWith('\r\n')) return text.slice(0, -2);
   if (text.endsWith('\n')) return text.slice(0, -1);
 
@@ -426,7 +426,7 @@ const interactionCliSchemas = {
   },
   fill: {
     usageOverride:
-      'fill <x> <y> <text> | fill <@ref|selector> <text> | fill <x> <y>|<@ref|selector> --text-stdin',
+      'fill <x> <y> <text> | fill <@ref|selector> <text> | fill <x y|@ref|selector> --text-stdin',
     usageFlags: [],
     positionalArgs: ['targetOrX', 'yOrText', 'text?'],
     allowsExtraPositionals: true,
 
@@ -83,6 +83,21 @@ test('fill --text-stdin reads only the target and leaves the text to stdin', ()
   }
 });
 
+test('fill --text-stdin refuses an unreadable target without echoing it', () => {
+  for (const positionals of [['stray-secret'], ['e3stray'], ['stray secret words']]) {
+    let caught: unknown;
+    try {
+      interactionCliReaders.fill(positionals, { ...BASE_FLAGS, textStdin: true });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught, positionals.join(' ')).toBeInstanceOf(AppError);
+    const error = caught as AppError;
+    expect(error.details?.reason).toBe('fill_text_stdin_target_invalid');
+    expect(JSON.stringify({ message: error.message, details: error.details })).not.toMatch(/stray/);
+  }
+});
+
 test('fill --text-stdin refuses a text argument without echoing it', () => {
   for (const positionals of [
     ['@e57', 'argv-secret'],
 
@@ -84,18 +84,9 @@ export const interactionCliReaders = {
     delayMs: flags.delayMs,
   }),
   fill: (positionals, flags) => {
-    const decoded = readFillTargetFromPositionals(positionals);
-    if (flags.textStdin && decoded.text !== undefined) {
-      // The message names neither source: the positional may already be the secret.
-      throw new AppError(
-        'INVALID_ARGS',
-        'fill --text-stdin reads the text from stdin, so it cannot also take a text argument.',
-        {
-          reason: 'fill_text_source_conflict',
-          hint: 'Pass only the target, for example: printf %s "$PASSWORD" | agent-device fill @e3 --text-stdin. Quote a multi-word selector so no part of it is read as text.',
-        },
-      );
-    }
+    const decoded = flags.textStdin
+      ? readStdinFillTarget(positionals)
+      : readFillTargetFromPositionals(positionals);
     return {
       ...commonInputFromFlags(flags),
       ...selectorSnapshotInputFromFlags(flags),
@@ -166,6 +157,36 @@ export const interactionDaemonWriters = {
   ]),
 } satisfies Record<string, DaemonWriter>;
 
+/**
+ * Reads only the target for `fill --text-stdin`. A stray positional may be the secret itself
+ * (`fill --text-stdin "$PASSWORD"`), so neither a parse failure nor the conflict echoes any of them.
+ */
+function readStdinFillTarget(
+  positionals: string[],
+): ReturnType<typeof readFillTargetFromPositionals> {
+  let decoded: ReturnType<typeof readFillTargetFromPositionals>;
+  try {
+    decoded = readFillTargetFromPositionals(positionals);
+  } catch (error) {
+    if (!(error instanceof AppError)) throw error;
+    throw new AppError('INVALID_ARGS', 'fill --text-stdin could not read the target.', {
+      reason: 'fill_text_stdin_target_invalid',
+      hint: 'Pass only the target: an @ref, a quoted selector, or x y coordinates. The text itself goes to stdin.',
+    });
+  }
+  if (decoded.text !== undefined) {
+    throw new AppError(
+      'INVALID_ARGS',
+      'fill --text-stdin reads the text from stdin, so it cannot also take a text argument.',
+      {
+        reason: 'fill_text_source_conflict',
+        hint: 'Pass only the target, for example: printf %s "$PASSWORD" | agent-device fill @e3 --text-stdin. Quote a multi-word selector so no part of it is read as text.',
+      },
+    );
+  }
+  return decoded;
+}
+
 function readLongPressTargetFromPositionals(positionals: string[]): LongPressOptions {
   const targetPositionals = readLongPressTargetPositionals(positionals);
   return {
 
@@ -180,7 +180,7 @@ Reusable open-to-destination scripts:
   The live app receives the value; recording state and the published script contain only \${PASSWORD}. Reuse the same name for repeated values; --record-as is fill-only, requires an armed recording, and is mutually exclusive with --no-record. Replay with AD_VAR_PASSWORD still set, or pass --env PASSWORD=<value>. Do not record passwords/tokens without --record-as; their literal text is written to the .ad target.
   To keep the value out of the CLI's argv as well, pipe it in with --text-stdin instead of a text argument:
     printf %s "$AD_VAR_PASSWORD" | agent-device fill 'id="password"' --text-stdin --record-as PASSWORD
-  --text-stdin reads at most 64 KiB, removes exactly one trailing newline, and refuses a terminal, empty input, or an extra text argument. While recording is armed it needs --record-as or --no-record; otherwise the step is left out of recorded actions. It is not available inside batch steps.
+  --text-stdin reads at most 64 KiB, removes exactly one trailing newline, and refuses a terminal, empty input, invalid UTF-8, or an extra text argument. While recording is armed, --record-as publishes \${VAR} and --no-record leaves the step out; passing neither is an error. Without an armed recording the step is not recorded. It is not available inside batch steps.
 
 Replay divergence and repair:
   A failing replay/test step returns REPLAY_DIVERGENCE with a bounded report (screen digest, ranked selector suggestions, resume). Fix app state, then resume with replay --from <n> --plan-digest <sha256> (both from the report's resume field) to continue without re-running earlier steps; resume never re-executes skipped steps, so app state there is the caller's responsibility. --from is replay-only; test rejects it. The digest binds the script, includes, effective --platform/--target, and per-action runtime/identity; native .ad interpolation is late-bound so changing only its values keeps the digest, while Maestro environment substitution can change it.
 
@@ -787,7 +787,7 @@ test('a stdin fill without --record-as never enters recording state', () => {
 
   expect(action).toBeUndefined();
   expect(session.actions).toHaveLength(0);
-  expect(JSON.stringify(session)).not.toContain(secret);
+  expect(session.recordedFillLiterals).toBeUndefined();
 });
 
 test('a stdin fill with --record-as is recorded as its ${VAR} placeholder', () => {
 
@@ -465,7 +465,7 @@ agent-device gesture transform 200 420 80 -40 2 35 700 # combined pan, zoom, and
 ```
 
 `fill` clears then types. `type` does not clear.
-`fill --text-stdin` reads the text from stdin instead of a text argument, so a secret never appears in the CLI's process arguments. It reads at most 64 KiB, removes exactly one trailing newline (`\n` or `\r\n`, so `echo` and `printf %s` send the same value), and refuses a terminal, empty input, or an additional text argument. The value is registered as sensitive for diagnostics. While script recording is armed, combine it with `--record-as <VAR>` to publish `${VAR}`, or `--no-record` to leave the step out; otherwise the step is not recorded. Batch steps do not accept it.
+`fill --text-stdin` reads the text from stdin instead of a text argument, so a secret never appears in the CLI's process arguments. Pipe the value with `printf %s`, which sends it verbatim. It reads at most 64 KiB, removes exactly one trailing newline (`\n` or `\r\n`), and refuses a terminal, empty input, invalid UTF-8, or an additional text argument. The value is registered as sensitive for diagnostics. While script recording is armed, combine it with `--record-as <VAR>` to publish `${VAR}`, or `--no-record` to leave the step out; passing neither is an error. Without an armed recording the step is not recorded. Batch steps do not accept it.
 When an interaction fails, see [Retry after a failed command](#retry-after-a-failed-command) before you retry.
 `type` accepts text only. Do not pass `@ref` to `type`; use `fill @ref "text"` to target a field directly, or `press @ref` then `type "text"` to append in the focused field.
 If `type` reports `TEXT_INPUT_NOT_FOCUSED`, focus a visible text input and retry; when accessibility does not expose the input, use a coordinate focus command before typing.