Merge remote-tracking branch 'origin/main' into claude/agent-device-2027-9d286e

* origin/main:
  feat(interaction): accept `fill <target> ""` as the clear-field primitive (#2066)
  fix(ci): spawn the differential's agent-device CLI as argv, not one option (#2069)
  fix(daemon): keep the recovery hint on Maestro replay errors (#2075)

# Conflicts:
#	src/commands/command-input.ts

Author: thymikee

.github/workflows/conformance-differential.yml

@@ -32,7 +32,11 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  AGENT_DEVICE_CLI: '--experimental-strip-types src/bin.ts'
+  # Entry script and node flags are separate on purpose: one variable cannot
+  # encode both without either corrupting a path that contains spaces or
+  # spawning the whole line as a single node option.
+  AGENT_DEVICE_CLI: 'src/bin.ts'
+  AGENT_DEVICE_CLI_NODE_FLAGS: '--experimental-strip-types'
   DIFFERENTIAL_ONLY: ${{ github.event.inputs.only || '' }}
   # CI should not phone home, and it keeps `maestro --version` to just the
   # version instead of prefixing an analytics notice.

.github/workflows/ios.yml

@@ -144,6 +144,7 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testPenalizedCoordinateTapOnNonTextControlDoesNotAuthorizeBareType \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBareDelayedTypeFailsWhenTappedInputDisappearsMidCommand \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSynthesizedTextCommitProgressWalksExpectedPrefixOnly \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testEmptyReplacementWithoutResolvableTargetFailsClosed \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testTextEntryTapWitnessIsBoundToTargetIdentity \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTapTextInputProbeSkipsPenalizedXCTestChannel \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testCoordinateTextInputCandidateMustBeEnabledAndContainTheTouchPoint \

android/snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/AccessibilityTreeXml.java

@@ -35,6 +35,13 @@ static void appendNode(
       appendWindowMetadata(xml, windowMetadata);
     }
     appendNonEmptyAttribute(xml, "text", node.getText());
+    // getText() returns the HINT for an empty field on modern Android, so `text` alone cannot
+    // distinguish a cleared field from one whose value equals its hint; only this flag can
+    // (#2063 empty-fill verification).
+    appendTrueAttribute(
+        xml,
+        "hint-showing",
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && node.isShowingHintText());
     appendNonEmptyAttribute(xml, "resource-id", node.getViewIdResourceName());
     appendAttribute(xml, "class", node.getClassName());
     appendNonEmptyAttribute(xml, "package", node.getPackageName());

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextTyping.swift

@@ -15,6 +15,36 @@ extension RunnerTests {
   ) -> TextEntryResult {
     let totalStartedAt = Date()
     guard !text.isEmpty else {
+      // Replacing a field WITH the empty string is the clear-field primitive (#2063): the typing
+      // is vacuous but the clear is not. Returning here unconditionally left the old value in
+      // place while the response reported "typed". Append (`type`) and unrepaired entry stay
+      // no-ops, which is what an empty payload means for them.
+      if repairMode == .replacement {
+        guard let clearTarget = resolveTextEntryElement(app: app, target: target) else {
+          // No resolvable input means no clear happened — including the synthesized
+          // first-responder route, whose target carries no element. Success here would claim a
+          // clear the runner never performed.
+          logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: 0, mode: repairMode)
+          return TextEntryResult(
+            verified: nil,
+            repaired: false,
+            expectedText: "",
+            observedText: nil,
+            failure: .notFocused
+          )
+        }
+        clearTextInput(clearTarget)
+        // nil means the value is unreadable (secure fields), not "not empty": leave `verified`
+        // nil there rather than reporting a mismatch the runner cannot actually observe.
+        let observed = editableTextValue(for: clearTarget, treatingPlaceholderAsEmpty: true)
+        logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: 0, mode: repairMode)
+        return TextEntryResult(
+          verified: observed.map { $0.isEmpty },
+          repaired: false,
+          expectedText: "",
+          observedText: observed
+        )
+      }
       logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: 0, mode: repairMode)
       return TextEntryResult(verified: true, repaired: false, expectedText: "", observedText: "")
     }

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+TextEntryPolicyTests.swift

@@ -445,6 +445,26 @@ extension RunnerTests {
     XCTAssertEqual(result.failure, .commitNotObserved)
   }
 
+  // `fill <target> ""` is the clear-field primitive (#2063). When no clear target resolves —
+  // Springboard's home screen has no focused text input — the empty-text replacement path must
+  // fail closed: it used to fall through to the vacuous-typing early return and report
+  // `verified: true` for a clear that never ran.
+  func testEmptyReplacementWithoutResolvableTargetFailsClosed() {
+    let result = typeTextReliably(
+      app: springboard,
+      target: TextEntryTarget(element: nil, refreshPoint: nil, prefersFocusedElement: false),
+      text: "",
+      delaySeconds: 0,
+      repairMode: .replacement,
+      xCTestChannelPenalized: false,
+      synthesizer: RecordingTextEntrySynthesizer()
+    )
+
+    XCTAssertEqual(result.failure, .notFocused)
+    XCTAssertNil(result.verified)
+    XCTAssertNil(result.observedText)
+  }
+
   // Companion to the above: text carrying a submit key must skip the wait entirely, same as the
   // append route (`awaitSynthesizedFirstResponderCommit`) — the app may clear or rewrite the field
   // on submit, so there is nothing meaningful to poll toward.

packages/contracts/src/interactor-types.ts

@@ -285,6 +285,12 @@ export type Interactor = {
   hoverRef?(ref: string): Promise<Record<string, unknown> | void>;
   focus(x: number, y: number): Promise<Record<string, unknown> | void>;
   type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
+  /**
+   * Replace the target's text with `text`. The empty string is the clear request (#2063), not a
+   * no-op: an implementation must empty the field or fail — never report success over an
+   * untouched value. A backend with no clear mechanism refuses the empty text up front (see the
+   * webdriver interactor).
+   */
   fill(
     x: number,
     y: number,

packages/maestro/src/internal/export-flow.ts

@@ -266,6 +266,20 @@ function convertFillAction(
   }
   const tapTarget = readTapTarget(target, undefined, resolveSelector);
   if (!tapTarget) return { kind: 'unsupported', message: 'fill target is not Maestro-compatible' };
+  if (text.length === 0) {
+    // The clear request (#2063): `inputText: ""` types nothing in Maestro, so the recorded
+    // clear would silently become a no-op. `eraseText` is Maestro's clear verb; without a
+    // count it erases up to its 50-character default, which is a bound this export cannot
+    // recover the real length for.
+    return {
+      kind: 'commands',
+      commands: [{ tapOn: tapTarget }, 'eraseText'],
+      warnings: [
+        ...readLabelSelectorWarnings(target),
+        'fill "" exports as tapOn + eraseText; Maestro erases at most its 50-character default',
+      ],
+    };
+  }
   return {
     kind: 'commands',
     commands: [{ tapOn: tapTarget }, { inputText: text }],

packages/maestro/test/conformance/differential/engine-process.test.ts

@@ -3,7 +3,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { test } from 'node:test';
-import { classifyAgentDeviceFailure, runAgentDeviceEngine } from './engine-process.ts';
+import {
+  classifyAgentDeviceFailure,
+  resolveAgentDeviceCliArgv,
+  runAgentDeviceEngine,
+} from './engine-process.ts';
 
 test('agent-device JSON distinguishes infrastructure from behavioral failures', () => {
   const result = (infrastructure?: true) =>
@@ -29,7 +33,7 @@ test('agent-device execution accepts a CLI path containing spaces', () => {
   const cliPath = path.join(root, 'agent device.mjs');
   try {
     fs.writeFileSync(cliPath, '');
-    assert.deepEqual(runAgentDeviceEngine(cliPath, []), {
+    assert.deepEqual(runAgentDeviceEngine([cliPath], []), {
       engine: 'agent-device',
       outcome: 'pass',
       exitCode: 0,
@@ -38,3 +42,25 @@ test('agent-device execution accepts a CLI path containing spaces', () => {
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
+
+test('the CLI argv keeps node flags and the entry script apart', () => {
+  // The default is the source CLI the device workflows name explicitly.
+  assert.deepEqual(resolveAgentDeviceCliArgv(undefined, undefined), [
+    '--experimental-strip-types',
+    'src/bin.ts',
+  ]);
+  // An entry path is never split, so spaces in it survive.
+  assert.deepEqual(resolveAgentDeviceCliArgv('/tmp/agent device.mjs', ''), [
+    '/tmp/agent device.mjs',
+  ]);
+  assert.deepEqual(resolveAgentDeviceCliArgv('/tmp/agent device.mjs', undefined), [
+    '--experimental-strip-types',
+    '/tmp/agent device.mjs',
+  ]);
+  // Flags are split, which is exact because a node flag cannot contain a space.
+  assert.deepEqual(resolveAgentDeviceCliArgv('bin/x.mjs', '--no-warnings  --enable-source-maps'), [
+    '--no-warnings',
+    '--enable-source-maps',
+    'bin/x.mjs',
+  ]);
+});

packages/maestro/test/conformance/differential/engine-process.ts

@@ -32,8 +32,41 @@ export function classifyAgentDeviceFailure(stdout: string): 'behavioral' | 'infr
   }
 }
 
-export function runAgentDeviceEngine(cliPath: string, args: string[]): EngineResult {
-  const result = spawnSync(process.execPath, [cliPath, ...args, '--json'], {
+/**
+ * The agent-device CLI the differential drives, as two variables that cannot be
+ * confused for one another:
+ *
+ *   AGENT_DEVICE_CLI            the entry script — ONE path, never split, so a
+ *                               path containing spaces survives verbatim
+ *   AGENT_DEVICE_CLI_NODE_FLAGS node flags — split on whitespace, which is exact
+ *                               because a node flag cannot contain a space
+ *
+ * One variable holding `--experimental-strip-types src/bin.ts` cannot express
+ * both: splitting it corrupts `/tmp/agent device.mjs`, and not splitting it
+ * spawns the whole line as a single node option — the bug that infrastructure-
+ * failed every scenario from 2026-08-25. Set the flags variable to the empty
+ * string to run an entry that needs none (a built `bin/agent-device.mjs`).
+ */
+const DEFAULT_CLI_ENTRY = 'src/bin.ts';
+const DEFAULT_CLI_NODE_FLAGS = '--experimental-strip-types';
+
+export function resolveAgentDeviceCliArgv(
+  entry: string | undefined,
+  nodeFlags: string | undefined,
+): string[] {
+  const flags = (nodeFlags ?? DEFAULT_CLI_NODE_FLAGS).split(/\s+/).filter(Boolean);
+  return [...flags, entry?.trim() || DEFAULT_CLI_ENTRY];
+}
+
+/**
+ * `cliArgv` is a node argv — flags and entry script as separate elements, built
+ * by `resolveAgentDeviceCliArgv`. Never a command line: spawning one as a single
+ * argument aborts node before the CLI loads ("bad option: --experimental-strip-
+ * types src/bin.ts"), which every scenario then reports as an infrastructure
+ * failure. An entry path reaching this array is already its own element.
+ */
+export function runAgentDeviceEngine(cliArgv: readonly string[], args: string[]): EngineResult {
+  const result = spawnSync(process.execPath, [...cliArgv, ...args, '--json'], {
     cwd: process.cwd(),
     encoding: 'utf8',
   });

packages/maestro/test/conformance/differential/run.test.ts

@@ -174,7 +174,7 @@ test('an ordinary Maestro process failure cannot satisfy a behavioral waiver', (
       {
         dryRun: false,
         maestroBin: `${process.execPath} ${maestroCli}`,
-        agentDeviceCli,
+        agentDeviceCliArgv: [agentDeviceCli],
       },
     );
 
@@ -186,6 +186,99 @@ test('an ordinary Maestro process failure cannot satisfy a behavioral waiver', (
   }
 });
 
+// The production route the P1 review asked for: environment -> parseRunnerArgs ->
+// runScenario -> spawn. Calling runAgentDeviceEngine with a hand-built argv proves
+// the spawn, but not that the two variables reach it intact — and it is the
+// environment contract that broke the nightly and that a whitespace-split
+// AGENT_DEVICE_CLI would break again in the other direction.
+describe('the agent-device CLI environment route', () => {
+  const ROUTE_SCENARIO = {
+    id: 'cli-env-route',
+    flow: 'differential/flows/settle-after-tap.yaml',
+    comparesAcrossEngines: 'test fixture',
+    expect: 'pass',
+    divergenceMeans: 'test fixture',
+  } as const;
+
+  /** Run one scenario with AGENT_DEVICE_CLI* set, restoring the environment after. */
+  function reportForEnvironment(entry: string, nodeFlags: string, maestroCli: string) {
+    const previous = {
+      entry: process.env.AGENT_DEVICE_CLI,
+      flags: process.env.AGENT_DEVICE_CLI_NODE_FLAGS,
+    };
+    process.env.AGENT_DEVICE_CLI = entry;
+    process.env.AGENT_DEVICE_CLI_NODE_FLAGS = nodeFlags;
+    try {
+      const options = parseRunnerArgs([]);
+      return {
+        argv: options.agentDeviceCliArgv,
+        report: runScenario(ROUTE_SCENARIO, {
+          ...options,
+          maestroBin: `${process.execPath} ${maestroCli}`,
+        }),
+      };
+    } finally {
+      restoreEnv('AGENT_DEVICE_CLI', previous.entry);
+      restoreEnv('AGENT_DEVICE_CLI_NODE_FLAGS', previous.flags);
+    }
+  }
+
+  function restoreEnv(name: string, value: string | undefined): void {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+
+  /**
+   * `spaced` is a subdirectory whose NAME carries the space, so the entry path
+   * holds one whatever the file is called. The maestro stub deliberately stays
+   * out of it: `runMaestroEngine` still splits its command on spaces, and a
+   * spaced stub path would fail this test for the other engine's reason.
+   */
+  function withFixtureRoot(run: (spaced: string, maestroCli: string) => void): void {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-env-route-'));
+    const spaced = path.join(root, 'agent device');
+    fs.mkdirSync(spaced);
+    const maestroCli = path.join(root, 'maestro.mjs');
+    fs.writeFileSync(maestroCli, 'process.exit(0);\n');
+    try {
+      run(spaced, maestroCli);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  test('a CLI path containing spaces reaches the spawn unsplit', () => {
+    withFixtureRoot((spaced, maestroCli) => {
+      const entry = path.join(spaced, 'cli.mjs');
+      fs.writeFileSync(entry, 'process.exit(0);\n');
+
+      const { argv, report } = reportForEnvironment(entry, '', maestroCli);
+
+      assert.deepEqual(argv, [entry], 'the entry path must stay one argument');
+      assert.equal(report.agentDevice.outcome, 'pass');
+      assert.equal(report.failed, false);
+    });
+  });
+
+  test('node flags stay separate arguments alongside a spaced path', () => {
+    withFixtureRoot((spaced, maestroCli) => {
+      const entry = path.join(spaced, 'cli.ts');
+      fs.writeFileSync(entry, 'const code: number = 0;\nprocess.exit(code);\n');
+
+      const { argv, report } = reportForEnvironment(
+        entry,
+        '--experimental-strip-types',
+        maestroCli,
+      );
+
+      // Neither property is expressible in a single whitespace-joined variable.
+      assert.deepEqual(argv, ['--experimental-strip-types', entry]);
+      assert.equal(report.agentDevice.outcome, 'pass');
+      assert.equal(report.failed, false);
+    });
+  });
+});
+
 test('every device flow targets the fixture app the workflow installs', () => {
   for (const scenario of DIFFERENTIAL_SCENARIOS) {
     const flowPath = path.join(CONFORMANCE_DIR, scenario.flow);