Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
ad08ad7
feat(harmonyos): verify the launched app in the foreground after open…
strzhao Nov 6, 2026
0ed91d6
fix(harmonyos): sync open foreground help, warning prose, and changeset
strzhao Nov 6, 2026
55440d0
docs(evidence): record the open foreground poll against the live miss…
strzhao Nov 8, 2026
904df19
fix(harmonyos): keep a failed foreground probe from claiming the app …
strzhao Nov 14, 2026
ca855cc
fix(harmonyos): tell a successful no-foreground read from a failed probe
strzhao Nov 16, 2026
55c66d3
docs(evidence): run the failed-probe open live and restate the suite …
strzhao Nov 16, 2026
27911d8
fix(harmonyos): bound the foreground poll by the request deadline
strzhao Nov 17, 2026
4b3f7c5
fix(harmonyos): name the deadline window when the clamp spent the budget
strzhao Nov 18, 2026
a63a89d
refactor(harmonyos): flatten the open foreground verify and its failu…
strzhao Nov 18, 2026
bcfae37
fix(harmonyos): name the window that actually bounded the poll
strzhao Nov 18, 2026
4795068
docs(evidence): re-attempt the keyguard and re-capture the failed pro…
strzhao Nov 18, 2026
8413723
refactor(harmonyos): render the probe window from the computed budget
strzhao Nov 19, 2026
6a05d66
test(harmonyos): pin the clamped probe window against a literal 5s re…
strzhao Nov 19, 2026
86bfc20
fix(harmonyos): read a mission-less keyguard dump as no-foreground
strzhao Nov 19, 2026
1c7e133
fix(harmonyos): tell a keyguard's mission-less dump from aa error text
strzhao Nov 19, 2026
19645bc
docs(evidence): write the secure-keyguard protocol into the doc
strzhao Nov 20, 2026
1df833a
fix(harmonyos): stub the paired runtime hints the open input now carries
strzhao Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 156 additions & 0 deletions docs/evidence/harmonyos-open-foreground-2026-11-08.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# HarmonyOS open foreground verification, 2026-11-08

Evidence for #4293 (verify foreground after open instead of trusting the
launch line): the post-check reads the mission list live after the dispatch
and only then reports the open. On this device `aa dump -l` names the
foreground bundle per mission, which is exactly what the poll consumes.

All runs below are at the head that reports the poll as one state:
`other-foreground` names a holder, `no-foreground` is a read that answered
with no foreground mission, and `probe-failed` is a budget whose every read
failed to run.

## Device

- HUAWEI 畅享 90 Plus, model `JDY-AL50`, HarmonyOS 7.0.0.111 (SP10C00E111R4P3), API 26
- Serial `77TYD26826028730`, USB, `hdc shell` as uid 2000 (shell)

## The confirmed path, live at the head

A plain open of an idle app confirms within the first poll read and rides
with no verification fact and no warning:

```json
{"success": true, "data": {"appName": "com.stringzhao.moonwell",
"warnings": null}}
```

The mission list read the same seconds after the dispatch:

```sh
$ hdc -t 77TYD26826028730 shell "aa dump -l"
bundle name [com.stringzhao.moonwell]
state #FOREGROUND start time [914348158]
```

## The keyguard shape of the mission list, observed live

With the screen suspended, `aa dump -l` answers with missions and no
`state #FOREGROUND` line anywhere (12 missions, all `#BACKGROUND`) — the
read that the poll classifies as `no-foreground`:

```sh
$ hdc -t 77TYD26826028730 shell "power-shell suspend"
SuspendDevice is called
$ hdc -t 77TYD26826028730 shell "aa dump -l" | grep -c "state #FOREGROUND"
0
```

This unit could not carry that shape through a full open: a shell-launched
`aa start` wakes the screen and takes the foreground even from the
suspended state (the poll confirmed on its first read, twice, with a fresh
`start time` on the relaunch). Crossing a secure keyguard needs the unlock
PIN, which this evidence session does not handle, so the end-to-end
`no-foreground` open remains maintainer-runnable.

## The maintainer-run protocol for the secure keyguard

The run needs a unit whose secure (PIN) keyguard `aa start` does not
dismiss. Record three outputs at the current head:

1. Plain `open <bundle> --platform harmonyos` prints the
open-not-foreground warning.
2. `open <bundle> --platform harmonyos --foreground --json` fails with
`error.details.reason` `open-not-foreground`, the "Unlock the device
screen" hint, and "within 5s".
3. The raw `aa dump -l` from the locked unit shows mission blocks with
zero `state #FOREGROUND` lines, or section headers with no mission
blocks at all.

If the dump carries a shape neither rule classifies as
`no-foreground-mission`, fix the parser for it in the same push.

One wider keyguard shape is pinned in the suite without a live row: a dump
that answers with its section headers (`User ID #`) but no `Mission ID #`
block at all (a lock screen that hides the mission list). The parser
classifies it as `no-foreground-mission` — the unlock-hint path — and
keeps `unparseable` for an empty answer and for `aa` error text, so a
locked unit cannot fall through to the connection hint.

## The failed-probe path, live at the head

The second unconfirmed classification uses the maintainer's offered stub:
a shim `hdc` on the daemon's PATH returns exit 1 with stderr
`shim: poll read refused` for every `aa dump -l`, and passes every other
invocation to the real binary. The launch dispatch is the real dispatch
against the real device; only the poll's reads fail, the way a flaky
connection fails them.

Plain open stays green and carries the unreadable-probe warning:

```json
{"success": true, "data": {"warnings": ["The launch dispatch succeeded,
but the foreground probe could not read the device within 5s
(open-foreground-probe-unreadable). This claims nothing about whether
the app reached the foreground; check the device connection, then run
the open again."]}}
```

`--foreground` fails hard with the same classification:

```json
{"success": false, "error": {"code": "COMMAND_FAILED",
"message": "The launch dispatch for com.stringzhao.moonwell succeeded,
but the foreground probe could not read the device within 5s",
"hint": "Check the device connection, then run the open again.",
"details": {"reason": "open-foreground-probe-unreadable",
"dispatched": "unknown"}}}
```

The `dispatched: "unknown"` disclosure comes from the request dispatch
ledger.

## Decision paths pinned by the suite

- `pollHarmonyOpenForeground classifies a mission list with no foreground mission as no-foreground` — the lock-screen shape
- `pollHarmonyOpenForeground reports probe-failed when every read fails`
- `pollHarmonyOpenForeground names the app that kept the foreground when the launch never surfaces` — `other-foreground`
- `verifyHarmonyOpenForeground attaches no-foreground when a read answered with no foreground mission`
- `verifyHarmonyOpenForeground fails --foreground with the unreadable reason when every read fails`
- plus the confirmed, keep-polling, and abort shapes

## Suite

`packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts`: 32 tests
pass on this branch's build; the full `check:unit` suite is green (20109
tests, lint clean) with `origin/main` pointed at the upstream base. The
count includes the clamped probe-failed window case: a deadline about 2s
out with every read failing asserts `within 2s`, so a revert to a literal
`5s` fails the suite.

## 2026-11-19 re-attempt at head d295556df

The keyguard re-check: with the screen suspended the mission list shows the
no-foreground shape again (11 missions, zero `state #FOREGROUND`), and the
`open --relaunch` dispatch again wakes this unit past the suspended state —
the poll confirmed on its first read and two missions went FOREGROUND. The
end-to-end `no-foreground` open keeps needing the secure keyguard; a
maintainer run at this head remains the path.

## The failed-probe path re-captured at head d295556df

The shim-hdc protocol (every `aa dump -l` answers exit 1; the dispatch is
the real dispatch on the real device):

```json
{"success": false, "error": {"code": "COMMAND_FAILED",
"message": "The launch dispatch for com.stringzhao.moonwell succeeded,
but the foreground probe could not read the device within 5s",
"hint": "Check the device connection, then run the open again.",
"details": {"reason": "open-foreground-probe-unreadable"}}}
```

The window text stays "within 5s" here because the CLI request's deadline
left the full budget — the deadline wording fires only when the deadline
actually clamped the poll (pinned by the partly-clamped and spent-deadline
tests).
4 changes: 2 additions & 2 deletions packages/command-registry/src/flag-definitions-action.ts
Original file line number Diff line number Diff line change
Expand Up @@ -414,9 +414,9 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
type: 'boolean',
usageLabel: '--foreground',
usageDescription:
'open: keep normal app/device selection and return an initial snapshot of the first screen (a local iOS simulator waits up to 10s for it); without an app, resolve the sole running app on the sole booted iOS simulator',
'open: keep normal app/device selection and return an initial snapshot of the first screen (a local iOS simulator waits up to 10s for it); without an app, resolve the sole running app on the sole booted iOS simulator; on HarmonyOS with an app target, fail when the launched app does not hold the foreground within 5s',
inputDescription:
'Include an initial interactive snapshot in a fresh open response. With no app argument, discover the sole running app on the sole booted iOS simulator; ambiguous environments fail closed.',
'Include an initial interactive snapshot in a fresh open response. With no app argument, discover the sole running app on the sole booted iOS simulator; ambiguous environments fail closed. On HarmonyOS with an app target, the open fails with details.reason open-not-foreground when the app never holds the foreground within 5s, or open-foreground-probe-unreadable when no read succeeds in that budget.',
projectConfig: false,
recorded: false,
},
Expand Down
2 changes: 1 addition & 1 deletion packages/command-surface/src/management/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ export const openCommandFacet = defineCommandFacet({
summary: 'Open an app, deep link or URL, save replays',
searchHint: 'relaunch',
cliDetail:
'Use --platform to bind URL/deep-link opens to the target platform. For local or Limrun iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app\'s Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app\'s launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+<slug> scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; for url-owner-unresolved, answer the prompt with alert accept; for alert-unrecognized, read the alert with alert get first, because it can be the app\'s own alert (such as a permission prompt) rather than the launch confirmation, and answer with alert accept only when it is the launch confirmation; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. When the runner reports its main-thread timeout for the accept and the prompt is still up, open presses Open again, but only when the time the open request has left covers a whole press and the read that checks it. A recognized prompt still visible after a failed accept, or once that time is gone, also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. The prompt is recognized by the OS\'s own wording of its title and buttons in the Simulator\'s preferred languages; when the runner cannot read that wording, the prompt stays on screen as alert-unrecognized. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
'Use --platform to bind URL/deep-link opens to the target platform. For local or Limrun iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app\'s Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app\'s launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+<slug> scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; for url-owner-unresolved, answer the prompt with alert accept; for alert-unrecognized, read the alert with alert get first, because it can be the app\'s own alert (such as a permission prompt) rather than the launch confirmation, and answer with alert accept only when it is the launch confirmation; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. When the runner reports its main-thread timeout for the accept and the prompt is still up, open presses Open again, but only when the time the open request has left covers a whole press and the read that checks it. A recognized prompt still visible after a failed accept, or once that time is gone, also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. The prompt is recognized by the OS\'s own wording of its title and buttons in the Simulator\'s preferred languages; when the runner cannot read that wording, the prompt stays on screen as alert-unrecognized. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session. On HarmonyOS, open reads the foreground app for up to 5s after dispatch. When the launched app never holds it, open succeeds with a warning that names open-not-foreground with the app that held the foreground, or that no mission is foreground; unlock and run the open again. A budget whose every read fails names open-foreground-probe-unreadable instead and claims nothing; check the connection. With --foreground, it fails with details.reason open-not-foreground or open-foreground-probe-unreadable.',
mcpDetail:
"metroHost, metroPort, and bundleUrl choose the app's Metro server and save its address for later reloads. launchUrl selects the app's launch URL and does not select the reload server. A fresh open without Metro hints clears an older same-name binding; close also clears it.",
},
Expand Down
28 changes: 28 additions & 0 deletions packages/contracts/src/application-lifecycle-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,11 @@ export type ApplicationLifecycleExecution = Readonly<{
launchConsole?: string;
launchArgs?: readonly string[];
clearAppState?: boolean;
/**
* `open --foreground` with an app target. A launch-verified owner treats "the launched app never
* held the foreground" as this open's failure instead of a success beside a warning.
*/
foreground?: boolean;
iosXctestrunFile?: string;
iosXctestDerivedDataPath?: string;
iosXctestEnvDir?: string;
Expand Down Expand Up @@ -144,8 +149,31 @@ export type OpenApplicationTiming = Readonly<{
postOpenObservation?: PostOpenObservation;
/** Why the observation could not run; present exactly when it is `probe-failed`. */
postOpenObservationFailure?: PostOpenObservationFailure;
/**
* Present when the owner verified after its dispatch which app holds the foreground, and the
* launched app never did. An unconfirmed read under `open --foreground` fails the open instead.
*/
foregroundVerification?: OpenForegroundVerification;
}>;

/**
* What an owner learned when it verified after its dispatch which app holds the foreground, and
* the launched app never held it. A launch dispatch can report success while a system surface (a
* lock screen is the typical one) keeps the launched app behind it, so the verification is a
* bounded poll of the platform's own foreground read. It is present only when unconfirmed, and
* its state names what the probe actually saw:
*
* - `other-foreground`: a read succeeded and named another app in the foreground.
* - `no-foreground`: a read succeeded and no mission is foreground. A lock screen is the typical
* cause; unlock the device and retry.
* - `probe-failed`: no read in the budget produced a parsed mission list. Check the device
* connection; this claims nothing about the launched app.
*/
export type OpenForegroundVerification =
| Readonly<{ state: 'other-foreground'; foregroundPackage: string }>
| Readonly<{ state: 'no-foreground' }>
| Readonly<{ state: 'probe-failed' }>;

/**
* What an app open learned about the launched app before it returned. A local iOS Simulator asks
* its host AX bridge; a local Android device captures the app through the snapshot helper. Each
Expand Down
5 changes: 4 additions & 1 deletion packages/contracts/src/client-app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,10 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
/**
* Include an initial interactive snapshot in a fresh open response. With no
* app argument, discover the sole running app on the sole booted iOS
* simulator; ambiguous environments fail closed.
* simulator; ambiguous environments fail closed. On HarmonyOS with an app
* target, the open fails with details.reason open-not-foreground when the
* app never holds the foreground within 5s, or
* open-foreground-probe-unreadable when no read succeeds in that budget.
*/
foreground?: boolean;
saveScript?: boolean | string;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ export function applicationLifecycleExecutionFromRequest(
launchConsole: req.flags?.launchConsole,
launchArgs: req.flags?.launchArgs,
clearAppState: req.flags?.clearAppState,
foreground: req.flags?.foreground === true,
iosXctestrunFile: req.flags?.iosXctestrunFile,
iosXctestDerivedDataPath: req.flags?.iosXctestDerivedDataPath,
iosXctestEnvDir: req.flags?.iosXctestEnvDir,
Expand Down
Loading
Loading