fix(android): shell-quote free-text arguments reaching the device shell

[thymikee]

Summary

• Shell-quote free-form text sent through Android's adb shell path for type/fill and clipboard write, so shell metacharacters cannot be re-tokenized as commands.
• Reuse shellQuoteIfNeeded, remove the Android-local duplicate, and preserve unquoted arguments that are already shell-safe.
• Keep multi-word clipboard content as one device-side argument.

This is the Android shell-argument fix split from #1639 and is now rebased onto main after #1708.

Validation

• Exact rebased head 10e0833ad: pnpm check:affected --head 10e0833ad --run passed (207 test files, 1,713 tests; changed lines 2/2 and branches 2/2 covered).
• Regression proof: reverting the quoting calls makes typeAndroid shell-quotes text containing shell metacharacters and writeAndroidClipboardWithAdb shell-quotes text containing metacharacters fail; restoring them returns the suite to green.
• Pre-rebase live-device evidence for the same production quoting patch (b6ab28803): Pixel 7 API 36, test IME disabled, diagnostic backend confirmed as adb-shell; shell-metacharacter text round-tripped exactly in the UI and raw UI Automator output. The device session and emulator were cleaned up afterward.
• Android API 36 does not expose a usable cmd clipboard shell command (ClipboardService has no shell handler), so clipboard coverage is red-proven at the adb argument seam instead of claiming a live path that cannot execute on that image.
• GitHub CI has been restarted for the rebased head.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.05 MB	2.05 MB	+140 B
JS gzip	665.2 kB	665.2 kB	+62 B
npm tarball	802.2 kB	802.2 kB	+71 B
npm unpacked	2.80 MB	2.80 MB	+140 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.9 ms	27.9 ms	+0.1 ms
CLI --help	66.7 ms	66.7 ms	+0.1 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/screenshot-result.js	-148 B	-90 B
dist/src/agent-device-client.js	+30 B	+10 B
dist/src/internal/daemon.js	+37 B	+9 B
dist/src/runtime.js	0 B	-2 B
dist/src/context.js	0 B	-2 B

[thymikee]

Reviewed exact head b6ab2880. No code finding: both production routes now apply the shared shell quoting after Android %s encoding, preserving one device-shell argument for text entry and clipboard writes. The regressions exercise the shipped helpers and would fail if either quote call were reverted; the provider scenario remains a useful daemon-route contract.

Not ready yet: required live Android evidence is absent. Rebuild the Android artifacts, run without the test IME/provider-native injector, and attach literal UI read-back for shell-metacharacter type input plus clipboard read-back for multi-word, metacharacter, and embedded-apostrophe values; include snapshot -i --json showing android-helper and matching helper version. Current completed checks are green, with required lanes still pending. No code blocker or conflict found.

[thymikee]

Coverage is red here, and it is not attributable to this change. Evidence, since "unrelated flake" deserves proof rather than assertion:

• This branch touches only src/platforms/android/** and Android test fixtures. The failing file is src/daemon/handlers/__tests__/session-test-reporter-values.test.ts, last modified on main by fix: stop the unit suite from leaking temp directories #1593.
• fix(ios): keep the baseline presentation when a tap corroboration has no request flags #1646 and fix(remote): stop persisting the daemon bearer token, and authenticate forced-reconnect release correctly #1648 both pass Coverage from the identical base. Coverage runs the full suite (674 files / 5768 tests), so those runs executed this exact test successfully.
• Run in isolation it passes on both this branch and main: Test Files 1 passed (1) / Tests 4 passed (4).
• It failed twice here with byte-identical assertions, so it is reproducible under full-suite load — not random.

Root cause: the test asserts absolute indices into a timing-dependent event array.

const firstStep = hookValue(hooks, 3, 'onTestStep');
expect(hookValue(hooks, 5, 'onTestStep')).toMatchObject({ attempt: 2, … });

CI observed 6 hooks where 8 were expected (expected [ 'onSuiteStart', 'onTestStart', …(6) ] to deeply equal [ Array(8) ]), so index 3 held onTestResult rather than onTestStep and every later index shifted. The onTestStep hooks come from the per-attempt AsyncLocalStorage context across a retry, so whenever the suite's step/retry emission varies under load, the positional assertions break.

This is a latent defect on main. What this branch does is change which Android provider-scenario files run concurrently in the same shard, shifting the scheduling enough to expose it — deterministically for this file set, which is why a rerun reproduced it exactly.

Note it is outside CONTENTION_RETRY_FILES, and the job says so: No retry: a failure landed outside the enumerated retry list. Adding it there would be the wrong remedy anyway — that policy is timeouts-only, proven by the runner, and these are assertion failures. The fix belongs in the test: select hooks by name (or filter to onTestStep entries) instead of indexing into positions whose meaning depends on how many hooks happened to fire.

Not fixing it in this PR — that would bundle an unrelated main-branch test defect into an Android platform change, which is exactly the mixing the split was meant to undo. Happy to send it as its own PR.

This PR stays a draft regardless, pending live emulator evidence with the test IME off.

[thymikee]

Live Android evidence — exact head b6ab28803

Emulator Pixel_7_CI (Android 16 / API 36), Settings → "Search Settings" field. Artifacts rebuilt first: pnpm build + pnpm build:android producing both helper APKs at 0.20.5.

One correction worth recording, because it nearly invalidated the run: --test-ime is default on for emulators per the CLI's own help, so merely omitting it is not enough — --no-test-ime had to be passed explicitly, or the adb shell fallback this PR fixes would never execute and a green result would prove nothing. Backend was then confirmed from diagnostics rather than from the flag, on all four type invocations:

{"phase":"android_text_injection","command":"type","data":{"action":"type","backend":"adb-shell","textLength":27}}

1. type with shell metacharacters — PASS

node bin/agent-device.mjs type 'echo;`id`;$(whoami)&ls test' --debug --state-dir … --json
→ {"success":true,"data":{"text":"echo;`id`;$(whoami)&ls test","message":"Typed 27 chars"}}

The exec_command trail shows the fix doing its job — chunks carrying metacharacters are single-quoted, the safe trailing chunk is left bare (and note %s space-encoding sits inside the quotes, i.e. encode-then-quote order held):

adb -s emulator-5554 shell input text 'echo;`id'
adb -s emulator-5554 shell input text '`;$(whoa'
adb -s emulator-5554 shell input text 'mi)&ls%st'
adb -s emulator-5554 shell input text est

Read-back, exact match:

node bin/agent-device.mjs get text @e82 --json   → "text": "echo;`id`;$(whoami)&ls test"

Independently corroborated through a raw adb shell uiautomator dump, bypassing agent-device's own read path entirely: text="echo;id;$(whoami)&ls test" (the & being correct XML escaping of a literal &).

Disclosed anomaly: the first attempt read back one extra ;, confirmed at raw-XML level so it was a real on-device discrepancy, not a parsing artifact. Investigated rather than discarded: the identical string and the identical chunk-boundary substring both round-tripped correctly on re-send, and the argv sent to adb was byte-identical across all attempts — so argument construction is deterministic. Attributed to a one-off emulator keystroke double-fire in input text, not to this change. Recorded here rather than omitted.

2. Clipboard round-trip — NOT CAPTURED, environment gap

clipboard write 'android otp code'
→ UNSUPPORTED_OPERATION: Android shell clipboard write is not supported on this device.

Root-caused independently of agent-device:

adb -s emulator-5554 shell cmd clipboard set text 'hello world'
→ No shell command implementation.   (exit 0)

The clipboard service exists (service list → 104 clipboard: [android.content.IClipboard]) but its shell-command handler is unimplemented on this build — cmd clipboard returns the same with no subcommand at all, and dumpsys clipboard is empty. Not a permissions issue (adb root refused on a production build; still fails). Reproduced identically on a second, differently-imaged emulator (Television_4K, Google TV, API 36), so it is not specific to the Play-certified image. Only android-36/android-37.0 are installed locally, both Play-certified/TV variants.

So the multi-word / metacharacter / embedded-apostrophe clipboard read-backs you asked for could not be produced on any locally available image. The quoting on that path is covered by the committed unit tests, but I am not offering those as a substitute for the live evidence you specified.

3. snapshot -i --json — PASS

"androidSnapshot": {
  "backend": "android-helper",
  "helperVersion": "0.20.5",
  "helperApiVersion": "2",
  "helperTransport": "persistent-session",
  "installReason": "current"
}

helperVersion matches the freshly built agent-device-android-snapshot-helper-0.20.5.apk exactly.

Cleanup

Session closed, daemon stopped gracefully, both emulators killed (adb devices empty afterwards). Nothing outstanding. Raw ndjson, uiautomator XML dumps and debug logs under /tmp/ad-evidence-1645/.

---

Staying a draft. Two of three requirements are met with live evidence; the clipboard round-trip is blocked by an image capability gap rather than by anything in this change. If you have a device or system image where cmd clipboard is implemented, I will run it there. Otherwise the call on whether the text-entry evidence plus unit coverage clears the bar for the clipboard path is yours, not mine.

Separately, Coverage remains red here for the unrelated session-test-reporter-values.test.ts index-assertion defect diagnosed above.

[thymikee]

Evidence re-review at unchanged head b6ab2880: code remains clean and the new live proof clears the adb-shell text-entry side. Explicit --no-test-ime, diagnostics naming backend: adb-shell, encode-then-quote argv, exact agent-device read-back, independent raw uiautomator corroboration, matching android-helper metadata, and complete cleanup make that evidence production-shaped.

Readiness is still blocked by two concrete residuals:

1. The clipboard production path still has no successful on-device round trip for multiword/metacharacter/apostrophe values. The API 36 images honestly demonstrate an environment capability gap (cmd clipboard has no shell implementation), not a code failure, but the requested path evidence remains absent. It needs a device/image implementing that shell handler, or an explicit maintainer decision to accept unit-only residual risk.
2. Coverage is still confirmed red on the unrelated load-sensitive session-test-reporter-values.test.ts absolute-index assertions. That is not attributable to this Android quoting change, but the current head remains red until rerun green or the latent test defect is fixed separately.

No ready-for-human label yet.

[thymikee]

cmd clipboard capability — settled, with evidence

Following up the earlier "could not capture the clipboard round-trip" gap. I did not want to leave that as "the emulator didn't like it", so here is a defensible answer.

Environment: ro.build.version.release=16, sdk=36, ro.build.type=user, sdk_gphone64_arm64, fingerprint google/sdk_gphone64_arm64/emu64a:16/BP22.250221.010/13193326:user/release-keys.

Every spelling returns the identical, instant, exit-0 No shell command implementation. — no args, help, set text, set-text, the whole thing quoted as one arg, setPrimaryClip, -- set text x, get, get-text, getPrimaryClip, clear, list, read, write. The invariance is itself the finding: that string is Binder's default onShellCommand(), printed before any subcommand parsing, so it fires only when the target Binder object never overrode onShellCommand() at all. It is not a syntax or spelling problem.

Raw binder rules out a permission wall, from the other direction:

• service call clipboard 1 (setPrimaryClip) reached real application code and threw IllegalArgumentException("No items") from ClipboardService$ClipboardImpl.checkAndSetPrimaryClip(ClipboardService.java:553) — exception code 0xfffffffd = EX_ILLEGAL_ARGUMENT, not EX_SECURITY. That is ordinary validation failing because service call's scalar-only syntax cannot marshal a ClipData Parcelable — not access denial.
• service call clipboard 3 likewise reached real code and threw from java.util.Objects.
• So the service is alive, registered, and reachable by this shell. It simply has no shell-command surface.
• dumpsys clipboard returns empty with exit 0 — consistent with no dump handler either.

One over-read avoided: cmd -l does list clipboard. That is not evidence of shell-command support — the same list includes raw HAL interfaces like android.hardware.gnss.IGnss/default that plainly cannot take shell text. It reflects ServiceManager registration only. Flagging so nobody later cites it as a counter-example.

Conclusion: on this AOSP ClipboardService implementation there is no onShellCommand() override, so cmd clipboard genuinely does not exist as a shell surface. Note this is not the Android-10+ foreground-app clipboard restriction — dispatch never gets far enough for that to apply. Since no invocation works, there was no live command to exercise and the three round-trips (multi-word / metacharacter / embedded-apostrophe) were not captured; fabricating them was not an option.

Where that leaves this PR. Text entry is proven live (metacharacter payload, exact read-back, corroborated through a raw uiautomator dump), and the android-helper snapshot backend/version check passed. The clipboard quoting is exercised only by unit tests, and I am not presenting those as a substitute for the live evidence you asked for.

Your call on how to proceed:

1. Point me at a device or image where cmd clipboard is implemented — physical device, or an older/AOSP google_apis (non-Play-certified) image. No sdkmanager is installed locally, so downloading one needs cmdline-tools first; say the word and I will.
2. Or accept that the clipboard path is defensively quoted and unit-tested, on the basis that the shell surface it guards does not exist on modern Android at all — in which case this PR's live bar is already met by the text-entry evidence.

I would lean to (2), with the reasoning recorded here rather than assumed — but it is a judgement about your evidence bar, so it should be yours.

[thymikee]

Re-reviewed unchanged head b6ab28803 with the new capability investigation. No code findings. The adb-shell text path is proven live with --no-test-ime, exact UI/raw-uiautomator read-back, and encode-then-quote diagnostics. The missing clipboard round-trip is no longer treated as a code/evidence blocker: the API 36 investigation proves Binder's clipboard service has no onShellCommand() surface, so there is no production command to exercise on those images; the pure argv-quoting behavior remains pinned by a red-proven unit regression.

Readiness is still blocked by the confirmed red Coverage lane on untouched, load-sensitive absolute-index reporter assertions. No ready-for-human label until Coverage reruns green or that main-branch test defect is fixed separately. PR body is stale about “No emulator run yet” and unavailable local gates.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-10 11:47 UTC