* docs+ux: make device ownership discoverable end to end
Complete the #1320 agent experience so 'busy? -> inspect -> choose or
release' is discoverable from every surface an agent actually reads:
- devices now projects the blocking claim owner per row (claimedBy with
session and workspace, observe-policy projection; provably dead owners are
excluded because the next open replaces them automatically), so an agent
told a device is busy can pick a free one from the same listing.
- help debugging gains a 'Device busy and ownership' section separating the
two DEVICE_IN_USE flavors and their exact recoveries.
- AGENTS.md documents both flavors; docs/agents/device-verification.md
retires the last ps/kill recovery guidance in favor of device status,
daemon stop --state-dir, and device release --stale (Stage 5 of #1320).
- ADR-0010 no longer calls DEVICE_IN_USE 'the only retriable code' without
naming the claim path's non-retriable override.
- The rendered cross-worktree claim error gains a help-conformance quiz case
binding (sample-output-device-claim-inspects-owner).
- README points at device status / device release --stale.
Part of #1320.
* fix: key ownership projection by canonical device identity end to end
Review findings on #2165:
- blockingClaimOwnersByDevice keyed claims and inventory rows by bare
device.id, so a live Android claim could project claimedBy onto an
unrelated same-id Apple/Harmony/Vega row, with scan order picking the
displayed owner. Both sides now use the canonical local device key
(claim.deviceKey against canonicalLocalDeviceKey of the row's claim
identity). The cross-family same-id regression was observed red against
the bare-id keying.
- The projection is now asserted across every hop the PR promises: client
normalization preserves well-formed claimedBy and drops malformed ones,
and the devices CLI formatter carries it through JSON data and renders
the text line (MCP shares the same serialization).
* docs: reposition README around mobile app automation for AI agents
Lead the README with the category (mobile app automation, testing, and
verification for AI coding agents) and the three surfaces (CLI, MCP
server, Node.js API) so humans and search engines can classify it, then
keep verification and evidence as the differentiator.
- Move per-platform transport/caveat sentences (HarmonyOS HDC/uitest,
Vega VVD-only) out of the intro into "How it works" and add an inline
guard comment plus an AGENTS.md rule so new platforms only add a name
to the intro list.
- Add MCP and Node.js quick starts next to the CLI walkthrough.
- Add a works-with/proof line, a "What to ask your agent" prompt list,
a product-ladder sentence, and two AEO-shaped FAQ entries.
- Point the cloud/remote row at the remote proxy and device clouds docs.
- Align npm, MCP registry, and docs-site descriptions with the same
category phrasing.
- Remove em dashes and evaluative filler per the humanizer skill.
* docs: tighten README hero, link proof points, move install above capabilities
* docs: add mobile-MCP FAQ distinction, sharpen hero support line, drop coming-soon
* docs: make the build-on-top audience explicit in README
* docs: trim README repetition and signposting
* docs: close the session in finally in the README Node.js snippet
* feat: add HarmonyOS device automation foundation
Add HDC-backed discovery, snapshots, application lifecycle, and core mobile interactions.
Route HarmonyOS through the platform registry and client contracts.
Cover parsing and capability parity with focused tests.
* feat: support HarmonyOS HAP deployment
Install and reinstall signed HAP archives through HDC.
Resolve bundle identities from module metadata and relaunch after package replacement.
Extend deploy routing and capability coverage for HarmonyOS.
* feat: add HarmonyOS single-pointer gestures
Execute pan, fling, and swipe plans through HDC uiInput primitives.
Derive scroll coordinates from the live ArkUI viewport.
Keep unsupported multi-touch gestures explicitly rejected.
* refactor: split session inventory command handling
Separate session, device, capability, and app inventory response paths.
Preserve the public inventory response contract while reducing handler complexity.
* feat: support HarmonyOS keyboard actions
Route HarmonyOS enter, return, and dismiss through HDC key events.
Expose supported keyboard actions through the system command metadata.
Keep keyboard visibility inspection explicitly unsupported.
* fix: reject unsupported HarmonyOS drag gestures
Keep drag unavailable until HDC can preserve source and destination hold semantics.
* feat: add HarmonyOS app log streaming
1. Stream HarmonyOS app logs through PID-scoped hilog sessions.\n2. Record HarmonyOS app identity during bundle-id opens for app-scoped commands.\n3. Cover backend routing and bundle identity resolution.
* feat: report HarmonyOS foreground app state
1. Read the foreground HarmonyOS mission through aa dump.\n2. Expose HarmonyOS appstate with package and ability metadata.\n3. Add parser coverage for foreground and missing-state cases.
* fix: advertise appstate through capabilities
1. Classify appstate in the command descriptor capability matrix.\n2. Surface supported appstate commands in capability inventory.\n3. Cover the advertised Android capability contract.
* feat: sample HarmonyOS process performance
1. Sample HarmonyOS process CPU and resident memory through HDC.\n2. Expose the verified metrics through the shared perf command.\n3. Keep frame and memory snapshot collection explicitly unavailable.
* feat: clear HarmonyOS app state
1. Add HarmonyOS settings clear-app-state through bundle cleanup.\n2. Force stop the app before clearing data and cache.\n3. Reject all unverified HarmonyOS settings explicitly.
* docs: document HarmonyOS support
1. Describe HarmonyOS HDC prerequisites and HAP installation.\n2. Add HarmonyOS to platform discovery and product documentation.\n3. Document verified performance limits for the public HDC surface.
* fix: preserve HarmonyOS deploy session identity
1. Bind a resolved HarmonyOS bundle after install or reinstall.\n2. Keep app-scoped logs and observability available after deployment.\n3. Cover session identity preservation for HarmonyOS reinstall.
* test: lock HarmonyOS capability boundary
1. Add an independent HarmonyOS capability-matrix oracle and exact advertised-command regression test.
2. Document current HDC-backed support and evidence-based unsupported command boundaries.
* refactor: simplify HarmonyOS shared platform boundaries
1. Split device selection and settings dispatch into focused helpers without changing behavior.
2. Keep HarmonyOS serial selection and lock-policy classification covered by regression tests.
3. Remove Fallow complexity findings from the HarmonyOS diff against upstream main.
* fix: bound default HarmonyOS HDC commands
1. Apply a 15 second timeout to ordinary HDC operations.
2. Preserve operation-specific timeout budgets for installation and capture paths.
3. Add regression coverage for default and overridden HDC timeouts.
* feat: add HarmonyOS screen recording
Implement physical-device whole-screen recording through the system recorder and HDC media transfer.
Reject unsupported HarmonyOS recording scopes and export flags.
Cover capability routing, media retrieval, cleanup, and simulator rejection.
* feat: report HarmonyOS HDC readiness
Add an HDC version check to the HarmonyOS doctor flow.
Document HarmonyOS as a supported doctor platform and cover the result.
* refactor: simplify HarmonyOS recording checks
Reduce recording validation and test complexity without changing behavior.
* test: cover HarmonyOS platform contracts
Synchronize public platform expectations across CLI, MCP, replay, and inventory tests.
Mock HarmonyOS inventory probes to preserve concurrent test behavior.
* test: model HarmonyOS recording capability
Require a physical HarmonyOS device in the independent capability parity oracle.
* test: cover HarmonyOS input and lifecycle paths
Exercise HDC input, lifecycle, installation, and relaunch command sequences.
* test: cover HarmonyOS device observability paths
Exercise discovery, screenshot validation, and process performance sampling.
* docs: define HarmonyOS CI hardware policy
Keep HDC hardware validation local and require mocked CI contract tests.
* fix: honor HarmonyOS app inventory filters
* fix: bound HarmonyOS app inventory classification
1. 限制应用元数据分类并发并为默认清单设置整体时限.
2. 将请求取消信号传递给 HarmonyOS 应用清单读取.
3. 补充失败时中止在飞读取且不继续排队的回归测试.
* fix: preserve HarmonyOS inventory failure causes
1. 保留触发应用元数据分类失败的原始错误, 避免被取消同级任务覆盖.
2. 补充总时限中止在飞读取且不启动排队任务的回归测试.
3. 验证后序任务失败时保留默认筛选的恢复提示.
* feat: support --settle on scroll and back (#1638)
Scroll-then-observe and back-then-observe are legitimate agent pairs, but
the post-action observation registry never grew past the touch commands, so
`--settle` on either was rejected with INVALID_ARGS — burning a tool call
each in AppControlBench's bsky-16.
Both commands now carry the `settle` descriptor trait, and every surface
derives from it rather than a hand list: CLI allowed flags, MCP/SDK input
fields, the flag-sourced timeout envelope, and MCP ref-pinning. The CLI
flag/metadata helpers moved out of the interaction family into
post-action-observation-grammar.ts (back is a system command), and
SETTLE_REF_ISSUING_TOOLS became a derivation — a hand list would have
silently stopped pinning the new commands' refs.
settleAfterInteraction and the new settleObservationCommand are two entry
points over one engine: same loop, storage, hints, and diff bounds, with the
target-less path supplying its own baseline and no proximity point. The
daemon reaches that command through the runtime surface, never by importing
`commands/` (R2) — the same seam the touch handlers use for press/fill —
and generic-settle.ts is loaded through a lazy `await import` returning a
closure, so the interaction runtime subgraph stays out of this dispatcher's
static graph (a static edge folded ~18 files into the daemon-server type
cycle; R10 caught it).
Both of generic-settle's orderings are load-bearing and tested: the baseline
is frozen before dispatch (and before the Android dialog preflight), and the
observation runs after markDeferredInteractionOutcome so settle's first
capture folds in the #1542 stabilization rather than racing it. The ADR 0014
"a settled diff publishes refs" rule moved to settle-ref-issuance.ts, shared
by both routes.
One divergence is deliberate: scroll/back resolve no element, so the diff
baseline is the session's STORED pre-action tree — "settled tree vs the
last tree you observed" — not press's freshly resolved pre-action capture.
Both commands also switch to preserve-daemon on timeout, which changes the
non-settle path too: with --settle their dominant hang mode is now a wedged
accessibility bridge, and a timed-out capture must not reset the daemon and
lose every session (#1105). The reviewed-set gate records it.
Live-validated on an iOS 26.2 simulator (Settings): scroll --settle settled
in 1786ms with a +6/-6 diff carrying fresh refs; back --settle in 771ms with
+15/-6. Alternating cost runs, one call vs the pair it replaces:
scroll 2.9-3.0s vs 5.3-5.6s, back 3.1-3.2s vs 4.7-5.1s. Those include the
#1627 deep-capture extension.
* fix: render settled-diff refs paste-ready in CLI output
A settled diff activates a PARTIAL ref frame (ADR 0014), which admits only
the pinned `@eN~s<gen>` form of the refs it issued. The unchanged-interactive
tail already rendered that way, but the diff's own added lines rendered the
bare `@eN` embedded in the snapshot line — so a CLI caller who copied the
ref the diff just handed them got `plain_ref_requires_complete_frame` and had
to append the generation by hand.
Added lines now render pinned when the response carries `refsGeneration`,
exactly like the tail. Removed lines render verbatim: they name elements that
just left the screen, and `SettleDiffLine` never gives them a ref.
This is not new to scroll/back — press/click/fill/longpress had the same gap
since #1101. MCP was never affected: its ref-pin store rewrites plain refs on
the way in, which is why the model never sees a suffix.
Live: `scroll down --settle` now emits `+ @e14~s218078 [cell] "Game Center"`,
and `press @e14~s218078` copied straight out of that line taps successfully.
* test: record the pinned-diff-ref bytes in the output-economy baseline
Rendering added diff-line refs pinned costs 8 bytes in the two settle CLI
text samples (two `~s<gen>` suffixes). The output-economy baseline is the
tripwire for exactly this, so the increase takes an explicit reviewed waiver
rather than a silent baseline bump — the same one the settled TAIL's pins
already carry, for the same ADR 0014 reason.
Only `bytes` moves: lines, refs, hints, and shape are unchanged, which is the
evidence that this is a suffix on existing refs and not a new payload.
Caught by CI, not locally: `pnpm test:unit` runs unit-core and
subprocess-stub only, while the Coverage lane runs every vitest project.
* test: prove the generic settle degrades when its runtime cannot be built
`createGenericSettleRuntime` catches and returns undefined so an observation
that cannot even start does not fail an action that already succeeded. That
was a claim in a docstring with nothing behind it — the one changed line the
coverage gate reported uncovered (95/96).
The test puts the session in the state the catch exists for: the router
handed us a session that is no longer in the store, so building the settle
runtime throws SESSION_NOT_FOUND. The response keeps its scroll result and
simply carries no settle payload. Removing the try/catch fails it.
* build: teach fallow that vi.mock reaches pinOwnProcessStartTime dynamically
Not from this PR: #1642 added `pinOwnProcessStartTime` on main, and its three
consumers reach it the only way a Vitest module mock can —
`vi.mock(path, async (importOriginal) => (await import('...')).pinOwnProcessStartTime(...))`.
Dependency analysis cannot follow that dynamic import to a consumer, so the
export reads as dead the moment any PR pulls that file into its audit scope.
This PR is the one that did.
The entry records the consumers by path and the reason, matching the
daemon route-handler entry directly above it, which exists for the same
dynamic-`import()` limitation.
* refactor: adopt the best of the parallel #1653 implementation
Two sessions independently built #1638 (PR #1650 and PR #1653) and converged
on the same architecture — trait in the registry, one engine with two entry
points, runtime-command seam, lazy import, preserve-daemon, stored-baseline
honesty. #1650 continues; this folds in what #1653 did better:
- The agent-facing help core loop (cli-help.ts) now names scroll and back as
settle-capable. Without this, the benchmarked closed-grammar help line kept
instructing agents that --settle is only for press/click/fill/longpress —
actively steering the AppControlBench models away from what #1638 shipped.
- issueSettleRefs moves into session-snapshot.ts, beside the partial-frame
primitive it wraps, deleting the single-function settle-ref-issuance module.
- Their seam tests: back reader→writer settle plumbing, back CLI settle
rendering, and a trait-less generic command (home) ignoring a stray settle
flag rather than observing or rejecting.
What #1650 had that #1653 lacked, for the record: the SETTLE_REF_ISSUING_TOOLS
registry derivation (without it, MCP never pins a scroll/back settle diff's
refs and the partial frame rejects every follow-up), BackCommandResult.settle
in contracts, back's MCP output schema, paste-ready pinned diff refs, and the
docs/changelog/baseline surfaces.
* bench: help-conformance case for settled scroll-to-find planning
The #1638 extension of the closed --settle grammar to scroll/back is the
feature's entire payoff — collapsing scroll-then-observe into one call — and
the closed command list is an enumerated N whose enumerator is this bench.
The regex over the help text proves the sentence exists; this case checks
whether a model plans differently because of it.
One focused case, deliberately not coached: a pinned visible-first snapshot
(rendered by formatSnapshotText, pinned by the sample-producers gate) whose
wanted row is summarized off-screen with no ref anywhere in the output. The
tempting pre-#1638 plan is `scroll` plus a separate `snapshot -i`; acceptance
is the single settled call. Scoring was verified against eight plan shapes in
both directions before recording.
Model-backed record (claude-haiku-4-5, 3 trials, current help): 0/3 — but the
decomposition is the finding. Settle eligibility GENERALIZED (3/3 trials put
--settle on scroll unprompted; the mutation-suffix framing concern did not
materialize) and the two-call habit is residual (1/3). All three trials failed
on `scroll @e3 down --settle` — the pre-existing #1366 scroll-takes-no-target
confusion, which the live CLI recovers with a dedicated hint but a single-shot
bench cannot. The recorded gap is therefore a first-30 doc gap (nothing
teaches that scroll takes no target), not a settle-eligibility gap; tuning the
case until it passes would just delete the evidence.
* fix: auto-manage metro companion for remote runs
* fix: fail fast on non-retryable metro bridge errors
* fix: scope metro companion ownership by profile
* fix: align remote close metro companion cleanup
* fix: guard metro companion shutdown reconnect
* test: ignore expected bridge reset in metro reconnect test
* chore: format, cleanup
Michał Pierzchała