Skip to content

feat(harmonyos): verify foreground after open instead of trusting the launch line - #4293

Open
strzhao wants to merge 4 commits into
callstack:mainfrom
strzhao:forge/open-foreground-check
Open

strzhao wants to merge 4 commits into
callstack:mainfrom
strzhao:forge/open-foreground-check

Conversation

@strzhao

@strzhao strzhao commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

On HarmonyOS, open reported success off the start ability successfully stdout line alone — on a locked screen the report said Opened while the screen showed the lock face, and the session kept reasoning from a state the device never entered. openHarmonyApp now polls the app state (up to 5s, reusing the FOREGROUND parsing from apps state) after the launch line: when the launched bundle does not hold the foreground, the result carries an open_not_foreground warning telling the caller to unlock first; --foreground mode escalates that to a hard failure.

10 files changed (app-lifecycle polling, result plumbing, tests).

Validation

  • Head: 45a07a8 on a68693c (includes review-fix commit; help wording synced for both audiences per the flag-types rule).
  • pnpm run typecheck, pnpm run lint, app-lifecycle tests, integration-progress --check, fallow, freerange: pass locally.
  • Independent cold review: applied. CI runs the full gates on push.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 14 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/platform-harmonyos/src/runtime.test.ts">

<violation number="1" location="packages/platform-harmonyos/src/runtime.test.ts:454">
P3: This test leaves Vitest fake timers installed after it finishes. Restore real timers in cleanup (as `packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts` does), otherwise teardown or any additional tests in this worker can observe mocked `Date` and timer APIs.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

});

test('openApplication fails when --foreground demands the foreground and the launch never surfaces', async () => {
vi.useFakeTimers();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This test leaves Vitest fake timers installed after it finishes. Restore real timers in cleanup (as packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts does), otherwise teardown or any additional tests in this worker can observe mocked Date and timer APIs.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/platform-harmonyos/src/runtime.test.ts, line 454:

<comment>This test leaves Vitest fake timers installed after it finishes. Restore real timers in cleanup (as `packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts` does), otherwise teardown or any additional tests in this worker can observe mocked `Date` and timer APIs.</comment>

<file context>
@@ -362,3 +363,137 @@ function gestureHost(): PlatformRuntimeHost {
+});
+
+test('openApplication fails when --foreground demands the foreground and the launch never surfaces', async () => {
+  vi.useFakeTimers();
+  launchDumpHdc();
+  const hdc = vi.mocked(runHarmonyShell);
</file context>

@thymikee

thymikee commented Nov 6, 2026

Copy link
Copy Markdown
Member

Thanks for this. At 45a07a8 the change needs a live HarmonyOS run before it can merge, and two open review threads still need fixes. All 13 checks pass, but no CI lane runs a HarmonyOS device or HDC, so green CI proves only the mocked unit tests and gates. No conflicts.

This changes the HarmonyOS open lifecycle on a real device, and the PR has no live run (app-lifecycle.ts#L287). The whole fix assumes that on a locked screen aa dump -l names no FOREGROUND mission, or names a different bundle. That shape appears only in fixtures and in the doc comment. If HarmonyOS keeps the launched mission in state #FOREGROUND behind the keyguard, the poll confirms at once and the reported bug remains. Mocked tests cannot show this (see docs/agents/pull-requests.md, which notes HarmonyOS has no CI device). Please post a run on a real device or emulator at 45a07a8 with: (a) the screen locked, the raw hdc shell aa dump -l output, then agent-device open <bundle> --platform harmonyos --json returning ok:true with a warnings entry containing open-not-foreground and data.timing.foregroundVerification; (b) the screen locked, the same open with --foreground returning ok:false, COMMAND_FAILED, and details.reason open-not-foreground; (c) the screen unlocked, a control open with no foreground warning, no foregroundVerification, and its duration.

On the open threads: the P1 thread on a failed read becoming "not foreground" still stands (#4293 (comment), any hdc failure becomes unconfirmed). The P2 thread on the 5s budget still stands (#4293 (comment), worst case about 10.5s). So do the test helper thread (#4293 (comment)) and the fake-timers thread (#4293 (comment)). The thread on inherited-app reopen (#4293 (comment)) does not apply today: that path fails at bm dump -n / aa start before verification runs, and a no-target reopen is refused in session-open.ts. Please resolve it. I inferred that from parseHarmonyLaunchTarget and did not observe it on a device.

Could one typed verdict replace the boolean that is only ever false? For example { verdict: 'held' } | { verdict: 'not-held'; foregroundPackage?: string } | { verdict: 'probe-failed'; code: string } plus the owner's budgetMs, mirroring PostOpenObservation. One HarmonyOS foreground-read primitive in app-state.ts would return it per read and match any FOREGROUND mission, and both readHarmonyAppState and the open poll would call it. The daemon's completeOpenCommand already owns the open's warnings and the --foreground composition, so it could be the only policy site. It would warn with platform-neutral text on not-held and probe-failed, and refuse --foreground only on not-held. A probe failure would never read as not-foreground, the daemon would name no platform, and the leaf would throw nothing. The live run should first confirm that the lock-screen aa dump -l shape works as a signal at all.

Not blocking, and fine to take or leave: pollHarmonyOpenForeground compares the bundle only with the first FOREGROUND mission, so split-screen or floating windows on tablets and foldables could report unconfirmed (confirm when any FOREGROUND mission names the bundle, and include a multi-window dump in the run or call it out of scope); openNotForegroundWarning in session-open-execution.ts hard-codes 'HarmonyOS' and the leaf's 5s budget in daemon text; OpenForegroundVerification.confirmed in application-lifecycle-runtime.ts is never true, and the daemon test helper has an unused onOpenApplication parameter; readHarmonyForegroundMission repeats the read in readHarmonyAppState, differing only in timeout and in returning undefined; and the PR body says 10 files (the diff has 14), spells the reason open_not_foreground (the code uses open-not-foreground), links no issue, and lists no device run or open risk.

I could not check what aa dump -l prints on a locked screen or in multi-window layouts, and I did not run the tests locally. I also did not check whether request.scope.signal fires at the client deadline, so I do not know if the ~10.5s worst case can outrun a short client timeout.

Before merge, please post the live run at 45a07a8, then fix the probe-failure and budget threads.

@thymikee

thymikee commented Nov 7, 2026

Copy link
Copy Markdown
Member

Tracked in #4318, group B (HarmonyOS). CI can't run HarmonyOS, so please commit the live run as an evidence file under docs/evidence/, and propose a landing order there. HarmonyOS moves to a plugin in 0.22 (#4317).

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/evidence/harmonyos-open-foreground-2026-11-08.md">

<violation number="1" location="docs/evidence/harmonyos-open-foreground-2026-11-08.md:60">
P3: This evidence record misstates the validation result: `app-lifecycle.test.ts` contains 24 tests, not 89. Replace the count with the actual number or record the command and suite that produced 89 so the live-run evidence remains independently verifiable.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic


## Suite

`packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts`: 89 tests

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This evidence record misstates the validation result: app-lifecycle.test.ts contains 24 tests, not 89. Replace the count with the actual number or record the command and suite that produced 89 so the live-run evidence remains independently verifiable.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/evidence/harmonyos-open-foreground-2026-11-08.md, line 60:

<comment>This evidence record misstates the validation result: `app-lifecycle.test.ts` contains 24 tests, not 89. Replace the count with the actual number or record the command and suite that produced 89 so the live-run evidence remains independently verifiable.</comment>

<file context>
@@ -0,0 +1,61 @@
+
+## Suite
+
+`packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts`: 89 tests
+pass on this branch's build (typecheck and lint clean).
</file context>
Suggested change
`packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts`: 89 tests
`packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts`: 24 tests

@strzhao

strzhao commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Evidence committed to the branch: docs/evidence/harmonyos-open-foreground-2026-11-08.md — the poll's live data source (aa dump -l names the launched bundle state #FOREGROUND after open), a positive run through the branch CLI, and an honest statement of why the unconfirmed shape is pinned by the unit tests rather than reproduced live (triggering it needs the keyguard, whose PIN this evidence session must not handle). Head is now 99e4622.

🤖 Generated with Claude Code

@thymikee

thymikee commented Nov 8, 2026

Copy link
Copy Markdown
Member

I reviewed 99e4622 against the earlier findings, and one evidence gap from that review is still open. All 13 checks pass, but no CI lane runs a HarmonyOS device or HDC, so green covers only mocked tests and gates, not the changed device route. I did not run the tests, and I had no HarmonyOS device. I judged the tests by reading the diff and test bodies.

The evidence file still records only the unlocked positive route: an elided aa dump -l and a human-format Opened: line (docs/evidence/harmonyos-open-foreground-2026-11-08.md:41). The two routes this PR adds were never run on a device: locked plain open (warning plus timing.foregroundVerification) and locked --foreground (ok:false, COMMAND_FAILED, details.reason open-not-foreground). Line 41 still states as fact that the keyguard leaves no FOREGROUND mission, while the same paragraph says that shape was not reproduced. The unlocked control has no --json output, no duration, no proof that foregroundVerification is absent, and the file names no commit SHA. The fix depends on an unobserved assumption. If HarmonyOS keeps the launched mission in state #FOREGROUND behind the keyguard, the poll confirms at once (app-lifecycle.ts:291), open still reports success on a locked screen, and the reported bug remains. Issue #4318 and the earlier review both require this run.

The rule the code must satisfy is that open reports open-not-foreground when, and only when, the launched app is not visible to the user, shown on a real device. Please record the following in the evidence file, with the tested commit SHA. (a) With the device locked, the complete raw hdc shell aa dump -l, then agent-device open <bundle> --platform harmonyos --json returning ok:true with a warnings entry containing open-not-foreground and data.timing.foregroundVerification. (b) Locked, the same open with --foreground returning ok:false, COMMAND_FAILED, details.reason open-not-foreground. (c) Unlocked, the same open with --json showing no such warning, no foregroundVerification, and its duration. The tool never needs the PIN: lock the device with the power button, and unlock it by hand before (c). If the locked dump shows the bundle as FOREGROUND, aa dump -l is not a usable signal and the design must change. Until then, please remove or attribute the line 41 assertion.

On the open inline threads: the comments on all-failed probe reads becoming confirmed:false (r4497023199), flags: {} hiding --foreground (r4497023212), and the 5s budget overrun (r4497023234) all still stand, unchanged since 45a07a8. Two lower-priority ones also still apply. The one about URL positionals (r4497023215) does not apply: launch-target parsing and the aa start check throw before verification runs. I inferred that from the code and did not see it on a device, so please resolve it. I did not determine whether request.scope.signal fires at the client deadline, so I do not know whether the roughly 10s worst case can outrun a short client timeout.

Before merge, please commit the locked plain, locked --foreground and unlocked control runs with raw aa dump -l and --json output at a named SHA, then fix the probe-failure and 5s budget threads.

@thymikee

Copy link
Copy Markdown
Member

This branch now conflicts with main. Please rebase and address the outstanding review findings in the same push. I will review the updated head.

strzhao and others added 4 commits November 15, 2026 01:04
… dispatches

`aa start` reports an accepted launch, not a visible app, so an open under a
lock screen succeeded beside an invisible app and only a later snapshot told
the truth. HarmonyOS now polls its foreground read for up to 5s after the
dispatch. A launch that never surfaced carries a typed
`timing.foregroundVerification` fact and the open warns `open-not-foreground`
with the app that held the foreground; `open --foreground` fails with
`details.reason: open-not-foreground` instead.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Review follow-ups on the foreground verification. The versioned help now
states the HarmonyOS side of `--foreground` beside its iOS snapshot
semantics, in the flag declaration and in the open command detail that
owns the open reasons. The open-not-foreground warning reads as a
sentence for both its holder and unreadable-foreground arms, and the
patch carries a changeset.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…ion list

Co-Authored-By: Claude Code <noreply@anthropic.com>
…stayed backgrounded

The poll bounds each read by the budget's remainder, tracks whether any read
parsed a foreground mission at all, and marks a budget with zero parseable
reads as an unreadable probe. The verify carries that as its own typed reason
(open-foreground-probe-unreadable) instead of open-not-foreground, the daemon
warning says the read claims nothing about the foreground, and the route
tests pin the --foreground hard failure and the unreadable warning.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@strzhao
strzhao force-pushed the forge/open-foreground-check branch from 99e4622 to 70bfed4 Compare November 14, 2026 17:11
@strzhao

strzhao commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (the commands.md conflict keeps main's close/relaunch notes beside this branch's HarmonyOS open line), and all three outstanding findings are fixed at 70bfed4.

A failed probe is no longer a backgrounded verdict (r4497023199). The poll tracks whether any read parsed a foreground mission at all: each read is bounded by the budget's remainder (both the aa dump -l timeout and the sleep), and a budget that closes with zero parseable reads answers probeState: 'unreadable'. The verify carries that as its own typed failure — reason open-foreground-probe-unreadable under --foreground, and a warning that claims nothing about the foreground on a plain open — while open-not-foreground stays reserved for a probe that read another app holding the foreground. OpenForegroundVerification in contracts carries the optional probeState.

--foreground contract pinned (r4497023212). The route test passes { foreground: true } and asserts the openApplication failure propagates with reason open-not-foreground; the unreadable case asserts the new warning and the absence of the old one.

Budget overrun (r4497023234). The remaining-time check now runs before each read, and both the read timeout and the sleep clamp to that remainder.

The thread on URL positionals is resolved as you marked it. 122 platform and 230 lifecycle tests, typecheck, lint, and fallow pass at the pushed head.

@thymikee

Copy link
Copy Markdown
Member

I reviewed 70bfed4 after the earlier conflict notice (#4293 (comment)). A failed foreground read no longer reports open-not-foreground, and the poll now clamps each read and sleep to the 5s budget. The new classification has one wrong case, and the help and live evidence do not match it yet. All 16 checks pass at this commit, and there are no conflicts.

A successful aa dump -l that lists missions with none FOREGROUND (the lock-screen shape) is now reported as an unreadable probe. sawReadable is set only when a FOREGROUND mission parses (app-lifecycle.ts:304), and the test at app-lifecycle.test.ts:426 pins that. Opening an app under a lock screen now tells the user to check the device connection instead of unlocking, and open --foreground fails with open-foreground-probe-unreadable. Callers that branch on details.reason will retry connectivity instead of unlocking. The rule should be: unreadable means every read in the budget failed to run (threw, timed out or returned unparseable output), never that a read succeeded and no mission is foreground. Please have readHarmonyForegroundMission return a result that tells a successful read from a failed one, set sawReadable on any successful read, and restore the open-not-foreground expectations at :426 and :530. Please also add a test where every read rejects.

The new reason open-foreground-probe-unreadable is not documented anywhere. The CLI help (app.ts:216), the --foreground input description, the client-app.ts JSDoc, website/docs/docs/commands.md and the changeset all still say an unreadable foreground yields open-not-foreground. After the fix above, please state both reasons on every surface that names open-not-foreground: open-not-foreground when the device read no foreground for the launched app (unlock and retry), and open-foreground-probe-unreadable when no read of the mission list succeeded (check the connection). The "could not read any foreground app" branch in openNotForegroundWarning should match whichever case remains reachable.

The only live run in the evidence record is the confirmed path, and it predates this change. Once the classification is fixed, please attach a live HarmonyOS run at the PR head. With the keyguard up, plain open <bundle> should show the open-not-foreground warning, and open <bundle> --foreground --json should show details.reason open-not-foreground. A second run with a failed probe (for example hdc disconnected after dispatch, or a stubbed hdc returning non-zero) should show open-foreground-probe-unreadable. If you cannot get past the device PIN, say so and a maintainer can run the keyguard case. I did not run tests locally or on a device, and I did not confirm that the keyguard leaves no FOREGROUND mission; that part relies on the evidence record and the poll's doc comment.

Not blocking, and fine to take or leave: the open-foreground-probe-unreadable throw in app-lifecycle.ts:357 has no test of its own (the daemon test stubs the outcome), and the daemon warning and platform error hard-code 5s while the budget lives in HARMONY_OPEN_FOREGROUND_POLL_BUDGET_MS.

Could one fact simplify this? The platform owner could return only when unconfirmed { state: 'other-foreground', foregroundPackage } | { state: 'no-foreground' } | { state: 'probe-failed' }, and map the first two to open-not-foreground and the third to open-foreground-probe-unreadable. The daemon would render one warning keyed on state. The confirmed: false plus optional modifier combination that mixed up lock screen and failed reads could not be represented, and HarmonyOpenForegroundRead would go away. Only the OpenForegroundVerification contract type, which this PR introduces, would have to change first.

On the open threads: the useFakeTimers restore in runtime.test.ts (thread) and the stale "89 tests" line in the evidence record (thread) still apply; both are lower priority, and the second is 24 test() calls at head. These threads are addressed at head and can be resolved: the failed-read classification (thread) once the first finding above is fixed, the real-binding open-not-foreground test (thread), and the per-read budget clamp (thread). This one needs no code change, because URL and deep-link targets skip verification at app-lifecycle.ts:350: thread.

Before merge, the lock-screen classification needs the fix above, then the help and docs need both reasons, and then the live keyguard run needs attaching.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants