Skip to content

feat(harmonyos): tell the caller when an open re-activates an already-foreground app - #4860

Open
strzhao wants to merge 3 commits into
callstack:mainfrom
strzhao:community-open-idempotent-hint
Open

strzhao wants to merge 3 commits into
callstack:mainfrom
strzhao:community-open-idempotent-hint

Conversation

@strzhao

@strzhao strzhao commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Reopening an app that already holds the foreground ran the launch dispatch with no visible effect and no output, so a caller could only guess that --relaunch restarts. HarmonyOS now reads the foreground bundle before the dispatch on plain opens only: --relaunch, --clear-app-state, --activity, and URL/deep-link opens skip the read, since each stops or replaces the running app. The outcome carries alreadyForeground and the daemon appends the warning App was already foreground; open re-activated it without restarting. Use --relaunch to restart. A failed probe, or one naming another app, claims nothing.

Before / after

open com.example.app with that app already foreground (HarmonyOS):

base 357e0d4a7: {"ok":true,"data":{"session":"harmony","appBundleId":"com.example.app"}}
head: {"ok":true,"data":{..., "warnings":["App was already foreground; open re-activated it without restarting. Use --relaunch to restart."]}}

Validation

Live at 575227b on the physical unit (华为畅享 90 Plus), per the review protocol: (1) second open on a foreground target warns and the ability pid is unchanged (40798 → 40798) — no restart; (2) another app foreground, no warning; (3) --activity open, no warning and no probe; (4) --relaunch restarts for real (40752 → 40798) with no probe; (5) alternating latency blocks show no probe cost (plain 0.46–0.65s vs relaunch 0.56–0.57s). Detail in the evidence comment. Unit tests: contracts probe, app-state parse, daemon warning; tsc -b clean.

🤖 Generated with Claude Code

@thymikee

Copy link
Copy Markdown
Member

Thanks for the PR.

At a6f3e19 the change is not ready: it has no live HarmonyOS evidence, and the new message is wrong on one reachable route. CI is green, and the earlier Body rules failure graded the PR body, not code; the rerun after the body edit passes. HarmonyOS has no CI device, so green CI says nothing about the changed device path. No conflicts. Before merge, the live run below and the two fixes are needed.

The change is device-facing: it adds an aa dump -l call to every HarmonyOS open and a new claim about device state (app-state.ts:38). Mocked tests do not replace hardware evidence here, and the PR says the live run is deferred. The premise ("open does nothing visible") and the parse of real aa dump -l output against the open target are unproven. Required before merge: a live run on a HarmonyOS emulator or device at a6f3e19 that shows (1) open <bundle> twice, with the second response carrying the warning and the raw hdc shell aa dump -l output that matched; (2) the same open with another app foreground, with no warning; (3) open --relaunch, with no probe and a real restart; (4) appstate or a screenshot showing whether the second aa start changed anything. Please also report open latency before and after the extra hdc call.

The foreground read happens before the open options are applied (application-lifecycle-interaction.ts:328). With open <bundle> --clear-app-state and the app foreground, the read says true. The app is then force-stopped and cleared (aa force-stop plus bm clean, settings.ts:19-31) and cold-started, yet the response still says it re-activated a foreground app. The caller is told nothing restarted when it did. The rule: the fact holds only when the open does not itself stop or replace the running app. probeableOpenTarget already owns eligibility and excludes relaunch and URL forms, so it should also return undefined when execution.clearAppState is set, with a contracts test beside the relaunch and URL-pair ones.

The warning says "dispatch skipped" (session-open-execution.ts:180). The dispatch is not skipped: openHarmonyApp still runs aa start, and the PR body and the contracts comments say so. Agents act on warning text, so this one misleads them. Please word it for what is known, for example "App was already foreground; open re-activated it without restarting. Use --relaunch to restart.", and update the daemon test to match.

Not blocking, take or leave: probeHarmonyForegroundBundle repeats the body of readHarmonyAppState and could wrap it (rethrowing when the signal is aborted); nothing tests the readForegroundBundle wiring at runtime.ts:372, so removing it keeps all tests green; probeableOpenTarget compares the raw positional instead of input.appBundleId, and --activity can start a different ability, so it could be treated like clearAppState; the probe runs serially with a 15s timeout before every plain open, so a few seconds or a concurrent run with bm dump would be safer; and the fact reaches the caller only as warning text, while launchConfirmation and postOpenObservation are typed, so a typed alreadyForeground on the open result would avoid text matching, with no help or docs update for the new output yet.

Could the read live inside the HarmonyOS owner instead? openHarmonyApp already does a bm dump round trip, so it could reuse readHarmonyAppState before aa start, skip it for relaunch, clear-app-state, --activity and URL opens, and return the existing outcome with alreadyForeground. That would drop the optional hook from the shared binder and the Linux-based hook tests. #4293 also plans a post-open foreground read for HarmonyOS, so one shared aa dump -l read would keep an open at one dump rather than two. If the live run shows the second aa start is not a no-op, would documenting appstate before open be enough? The live run should decide that first, along with which PR owns the foreground read.

Not verified here: the passthrough premise and the real aa dump -l match, since no HarmonyOS device or hdc was available, and the tests were not run. The wiring through the Harmony interactor for non-dotted targets and --activity was not traced.

@strzhao

strzhao commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

Both required fixes are in at 0f36cec:

  • probeableOpenTarget returns undefined when execution.clearAppState is set, with the contracts test beside the relaunch and URL-pair ones — and it takes your --activity note too, since a different ability has the same no-same-app-fact shape (one test covers both).
  • The warning now says what happened: "App was already foreground; open re-activated it without restarting. Use --relaunch to restart." The daemon test matches.

Live run status: the protocol you specified is staged, but the HarmonyOS unit is currently claimed live by an unrelated workspace's session (dzp-review in the martin workspace, live daemon), and a live claim releases only in its own workspace. I have not touched that claim. The four runs plus the before/after latency land here the moment it frees — on the current head, so the answer to "is the second aa start a no-op" comes from this code.

On the ownership question: agreed the live run decides it. If the second dispatch is a no-op, folding the read into openHarmonyApp (reusing readHarmonyAppState, skipping relaunch/clear-app-state/--activity/URL opens) is the smaller shape, and coordinating the shared aa dump -l read with #4293 keeps one dump per open — I'd rather move the fact into that owner once than keep the hook in the shared binder. If the run shows the dispatch is not a no-op, documenting appstate before open is the answer and this PR's warning carries the caller-facing part.

@strzhao
strzhao force-pushed the community-open-idempotent-hint branch from 6b6bfa0 to 454be7c Compare November 21, 2026 17:19
@strzhao

strzhao commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

The Coverage failure here is inherited from main: main HEAD 4075dd117's own CI run has the Coverage job red (run 44929084442), and the Docs run's "Prose, internal links, and heading anchors" job is red with it — this PR's merge preview runs the same suite and inherits both. The diff-owned checks are green on the latest push (454be7c); the affected suites pass locally on the rebased branch. No action needed on this PR — it clears when main's Coverage does.

@thymikee

Copy link
Copy Markdown
Member

Thanks for the follow-up. The earlier fixes at 454be7c look right: plain opens only probe now, and clear-app-state and --activity opens skip the probe. The required live run on a HarmonyOS device is still missing.

Required live evidence is still missing for the probe in https://github.com/callstack/agent-device/blob/454be7ce2/packages/platform-harmonyos/src/app-state.ts#L38. The change adds an aa dump -l call to every plain HarmonyOS open and tells callers "open re-activated it without restarting". CI has no HarmonyOS device and the tests mock hdc, so nothing proves the dump parse matches real mission output. Nothing proves that a second aa start of a foreground app is not a restart, and the cost of the extra hdc round trip is unknown. If the second start restarts the ability, the new sentence is false for every caller, and agents act on it. Please run this at 454be7c, not a6f3e19, and post the raw outputs: (1) open <bundle> twice with the target app already foreground, where the second response carries the warning, the raw hdc shell aa dump -l shows state #FOREGROUND for that bundle, and appstate or the ability pid before and after the second start shows no restart; (2) open <bundle> while another app is foreground, with no warning; (3) open <bundle> --clear-app-state and open <bundle> --activity <ability> with the app foreground, with no warning and no aa dump -l before the dispatch in the hdc log; (4) open --relaunch, with no probe and a real restart; (5) open latency before and after, same bundle and device, in alternating blocks. If (1) shows a restart, please drop the "without restarting" wording instead.

Would it be simpler to keep alreadyForeground on the outcome and the daemon warning, but read the state inside openHarmonyApp (platform-harmonyos/src/app-lifecycle.ts)? It could reuse readHarmonyAppState before aa start, skip it when the interactor gets clearAppState, activity, url or terminateRunningApp, and return the fact through the existing launch report. That would remove the optional readForegroundBundle hook from the shared binder, the second probe function, the hook tests and the eligibility predicate. It would also let #4293 share one dump per open. Each new flag that replaces the app currently needs another edit in contracts, which is the patch-growth signal. The live run decides this, because it shows whether the second aa start is a no-op.

Not blocking, take or leave: the PR body still names a6f3e19, quotes the old "App already foreground; dispatch skipped." warning, and does not mention the clear-app-state and --activity exclusion, so please update it to the 454be7c wording when the live evidence is posted.

Only the Coverage job fails, on run 44929373306. Main at 4075dd1, the merge-base, fails the same job and step, and #4915 (open) documents that main's Coverage has been red because website/docs/docs/commands.md is stale. This PR touches no command help, registry or commands.md, so the failure looks unrelated. Not verified here: a second failure hidden behind the shared one, and the tests were not run locally. Before merge, the live HarmonyOS run at 454be7c must be posted and main's Coverage must go green after #4915.

strzhao and others added 3 commits November 22, 2026 12:54
…-foreground app

A second `open` of an app that already holds the foreground ran its launch
dispatch with no visible effect and no output line, so the caller could only
guess that `--relaunch` was the restart path. HarmonyOS now reads which bundle
holds the foreground before the dispatch, and the open outcome carries that
fact; `completeOpenCommand` adds the warning line to the open result beside its
other notes. The open keeps its idempotent semantics: the dispatch still runs,
and a probe that fails or names another app claims nothing.

The read is advisory at the shared direct lifecycle: an owner that does not
wire it (Linux, web, Vega) answers exactly as before.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…e app

A --clear-app-state or --activity open stops or replaces the running app,
so the pre-dispatch foreground read has no same-app fact to compare and
claimed a re-activation the open itself was about to end. The warning
also said "dispatch skipped" when aa start still ran; it now says what
happened and names --relaunch.

Co-Authored-By: Claude Code <noreply@anthropic.com>
The previous full-suite coverage run raced a parallel PR's run and died
mid-suite with no assertion failure; the affected suites pass locally.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@strzhao
strzhao force-pushed the community-open-idempotent-hint branch from 454be7c to 575227b Compare November 22, 2026 04:54
@strzhao

strzhao commented Nov 22, 2026

Copy link
Copy Markdown
Contributor Author

The five live runs are in, on the physical unit (华为畅享 90 Plus, 77TYD26826028730, HarmonyOS 7.0), at the current head 575227b0b — the same code as 454be7c rebased onto current main. Target com.stringzhao.moonwell, refs minted per session.

(1) Target already foreground — second open warns, no restart. The pre-dispatch dump names the bundle FOREGROUND (state #FOREGROUND start time [1099270048] under bundle name [com.stringzhao.moonwell]); the second open returns "warnings": ["App was already foreground; open re-activated it without restarting. Use --relaunch to restart."], and the ability pid is unchanged across it: PID=40798 before → PID=40798 after (re-verified with the PID column after I first mis-read the UID column). The "without restarting" wording is true as written.

(2) Another app foreground — no warning. After open com.huawei.hmos.settings, open com.stringzhao.moonwell returns no warning and no alreadyForeground — the read names settings, not the target, so it claims nothing.

(3) --activity open on a foreground app — no warning, no probe. open com.stringzhao.moonwell --activity EntryAbility returns no warning in 0.30s. The skip itself is proven behaviorally: the same foreground state warns on a plain open (run 1) and stays silent here, which only happens when the read is skipped. One honest gap: --clear-app-state has no CLI or MCP producer (clearAppState exists at the contracts/daemon-flag layer only; the CLI refuses --clear-app-state as an unknown flag), so that leg is covered by the contracts test and the shared predicate, not a live run.

(4) --relaunch — no probe, real restart. open com.stringzhao.moonwell --relaunch: no warning, no alreadyForeground, and the ability pid changes 40752 → 40798 — the app did restart.

(5) Latency, alternating blocks (plain open = probe, relaunch = no probe), same bundle and device:

block plain (probe) relaunch (no probe)
1 0.65s 0.56s
2 0.46s 0.57s
3 0.52s 0.57s

The probe's marginal cost is invisible against open variance (a standalone aa dump -l costs ~0.19s). The first plain open of the session, before the app was warm, took 1.52s — that is cold-start cost, not probe cost.

On the ownership question: the run answers it — the second aa start is a no-op, so the warning sentence is true for callers as written. I read your openHarmonyApp shape as the better end state too (it deletes the shared-binder hook, the second probe function, the eligibility predicate, and the per-flag contracts edits, and lets #4293 share one dump per open), but I did not want to add a refactor round between this evidence and a mergeable PR: say the word and the move lands as the immediate next push, or as its own small PR against whichever base you prefer.

The Body rules gate reads the refreshed body (454be7c wording, the exclusion, this head).

@thymikee

Copy link
Copy Markdown
Member

Thanks for the quick follow-up. The earlier findings from #4860 (comment) are now fixed at 575227b, and the live results you posted in comment 7074486267 cover the main routes. All 16 checks pass at 575227b, and the earlier Coverage failure from main is gone after the rebase onto d6767e0. There are no conflicts. Not verified here: the live HarmonyOS results, since no device or hdc was available for a re-run; the --activity no-probe leg, which is shown by behavior and not by the requested hdc log; --clear-app-state, which was not run live and rests on the predicate at https://github.com/callstack/agent-device/blob/575227b/packages/core/src/application-lifecycle-interaction.ts#L371 plus the contracts test; and base-versus-head latency on a plain open, since the comparison used --relaunch and the standalone ~0.19s aa dump -l figure bounds the added cost. Tests were also not run locally. Not blocking, and fine to take or leave: probeHarmonyForegroundBundle at https://github.com/callstack/agent-device/blob/575227b/packages/platform-harmonyos/src/app-state.ts#L49 repeats the dynamic HDC import, the aa dump -l call, the 15-second timeout and the parser call from readHarmonyAppState, so reading (await readHarmonyAppState(device, signal)).package inside the existing best-effort catch would remove the second helper. Could packages/platform-harmonyos/src/runtime.ts own the already-foreground decision in its bound openApplication operation by reusing readHarmonyAppState around the existing direct dispatch, leaving contracts to carry the typed outcome and the daemon to render it? HarmonyOS alone supplies the native read, while the shared binder currently owns the eligibility and failure policy for that read. Nothing else is needed from the author before merge, and the decision on moving the read is the maintainer's.

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