Repository navigation
Headless webBrowser.openUrl should log setup URL for remote operators, not auto-launch a host GUI browser (preserve first-run onboarding intent) #891
Description
Summary
The headless build must never launch a host GUI browser by default. Discovered live (2026-08-11): the moment webBrowser.openUrl was repaired (#865/#881 -- it had been inert ONLY because the script did not compile), finishInstall's setup-page open started executing for real, repeatedly launching Safari at http://127.0.0.1:5336 on the maintainer's desktop during first-run test cycles.
Why this is a policy issue, not a test bug
- Any script in any loaded root can call webBrowser.openUrl; a HEADLESS server/CLI process reaching into the host GUI session is wrong by default (surprise side effects on developer machines, CI runners, remote servers).
- The webBrowser.openUrl fails to compile headless; blocks first-run finishInstall flow #865 history shows "it never happened before" was an accident of corruption, not a design decision.
Proposed policy
- In FRONTIER_HEADLESS builds, webBrowser.openUrl defaults to log-and-record (no exec of open/xdg-open): log the URL at info level and set a session-visible marker (e.g. system.temp.Frontier.lastOpenUrlRequest) so flows and tests can assert the INTENT without the side effect.
- Explicit opt-in for real launches (flag or pref, e.g. --allow-gui-browser), for interactive local use.
- The sanctioned path for automated browser verification is agent-browser (frontier-cli --browser integration) -- the Manila-wave acceptance flow already plans on it.
- Immediate mitigation (in flight, unit-855): test sessions shadow openUrl with a recording no-op; the recording doubles as the first-run acceptance signal.
Exit criteria
- Headless default: no process exec on openUrl; URL logged + marker set
- Opt-in flag documented
- Behavioral test: openUrl under headless default performs no exec (assert marker, assert no child process)
- first-run flow asserts the setup-page open INTENT via the marker
Cross-references: #865, #881, #867 (setup-page flow), #855 (where it surfaced).
Activity
[-]Headless webBrowser.openUrl launches host GUI browser; must default to log-and-record with explicit opt-in[/-][+]Headless webBrowser.openUrl should log setup URL for remote operators, not auto-launch a host GUI browser (preserve first-run onboarding intent)[/+]jsavin commentedon Aug 11, 2026
Correction: this is onboarding UX, not a bug to suppress (maintainer context, 2026-08-11)
The browser-open is NOT a debug artifact -- it is the legacy first-run ONBOARDING FLOW. Frontier launched a GUI browser to the setupFrontier page specifically to collect configuration from potentially non-technical server owners (site name, admin credentials, server config). It is a real product requirement and it is exactly what the current goal means by "completes first-run" / "serves a page in a browser." The setup page SHOULD open in a browser on a genuine first run.
So the fix is context-aware relocation, NOT suppression:
Detection of "headless vs interactive" is the design question: FRONTIER_HEADLESS build flag is the coarse signal; a runtime pref (--allow-gui-browser / a config bool) lets a local headless-built CLI still opt into launching. Default for the headless build = log-and-mark; opt-in = launch.
What triggered this: repairing webBrowser.openUrl (#881) un-deadened finishInstall's setup-page open (inert only because the script didn't compile), which then launched Safari on the maintainer's desktop during firstRootRun test cycles. The onboarding intent is right; the host-GUI launch from a headless test context is the only wrong part.
Renamed/rescoped accordingly. Exit criteria updated:
Cross-references: #865, #881, #867 (setup-page reachability -- the operator must be ABLE to reach the logged URL, incl. after restart), #855, ROOT_BUILD/Manila-wave (agent-browser is the automated onboarding-verification path).
docs(planning): clarify first-run is operator-attended onboarding, no…
fix(cli): #891 gate round -- error-path ownership in setpendingbrowse…
docs(cli): #891 -- correct the P1-2 comment; the protect-block path i…
fix(cli): #891 -- headless sys.openUrl logs the setup URL instead of …