Repository navigation
Give a clear error when Chromium's sandbox can't start, and make design-build preflight launch the browser (GST-1906) - #4162
Merged
Conversation
…gn-build preflight launch the browser (GST-1906) On Linux hosts that deny unprivileged user namespaces (stock Ubuntu 23.10+ under AppArmor, non-root Docker), Chromium aborts with "No usable sandbox!". browse now fails with one error naming both fixes (allow user namespaces, or GSTACK_CHROMIUM_NO_SANDBOX=1 for trusted pages only) with Chromium's line below it, and never turns the sandbox off on its own. Docker's /.dockerenv now counts as a container, like CONTAINER. gstack-design-build preflight opens and closes one tab in the browser it found and stops with code=BROWSER_SANDBOX and the same error when that launch fails. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
|
😎 This pull request was merged. |
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
On Linux hosts that block Chromium's sandbox (stock Ubuntu 23.10+ under AppArmor, non-root Docker), gstack's browser now stops with one clear error that names both fixes, and
/design-review --buildfinds the problem before it starts work. This serves the README's promise that gstack's own browser works out of the box on Linux.What changed
design-build preflight on a host that blocks Chromium's sandbox: it used to say ok, now it stops with BROWSER_SANDBOX and the fix.
Before/after as text
GSTACK_CHROMIUM_NO_SANDBOX=1, which is only for pages you trust. Chromium's own line stays below it. The same text reaches the headed handoff error and design-build preflight./.dockerenv, which now counts as a container, the same asCONTAINER.DESIGN_BUILD: unrendered code=BROWSER_SANDBOX, and any other launch failure stops it withNO_BROWSER.Why
"Server failed to start" followed by a wall of Playwright log was all a user on stock Ubuntu 24.04 or in non-root Docker got, and
gstack-design-build preflightstill printedPREFLIGHT: okbefore the run died later. Now the first command that touches the browser says what is wrong and how to fix it, and gstack never decides on its own to drop the sandbox on a host it hasn't classified.Blast radius
The four Playwright launch sites in
browse/src/browser-manager.tsgain one.catch(explainSandboxFailure), which rethrows every error that is not a sandbox abort unchanged, so XProtect and custom-Chromium handling keep their behavior (read atbrowse/src/chromium-sandbox.ts:49-52).renderWithBrowsekeeps its tab-open path, now shared withlaunchBrowse; the existing fake-browse tests intest/aside-render.test.tsstill pass over it, and the real sandbox failure was reproduced on this host withuser.max_user_namespaces=0(repro and Exploratory QA below).Summary
On a host that denies unprivileged user namespaces, Chromium aborts with "No usable sandbox!" and gstack showed a raw Playwright log; preflight did not start the browser at all, so
/design-review --builddied mid-run. This PR maps that abort to one actionable error at every launch site, with no retry and no automatic sandbox-off, and makes preflight do a real launch so the run stops at the start withBROWSER_SANDBOX. A follow-up commit only rewords the changelog fragment.Test Coverage
Step 7 audit (audit-only, no tests generated): 15 of 18 changed paths tested (83%), value-weighted 83%. Quality: 9 paths at three stars, 6 at two, 0 at one.
Tests: 1762 files before and after (the new and changed tests landed in the original commit:
browse/test/chromium-sandbox.test.tsnew;browse/test/browser-manager-unit.test.tsandtest/design-build.test.tsextended). Fail-first: 6 of the 7 new tests fail on main 9740bfd; the seventh, "no signal keeps the sandbox on", guards against an automatic sandbox-off being added.Test value: 0 tests written, 1 rejected by the authoring gate, 0 existing tests extended, 0 paths weakly covered.
Gaps left as proposed tests:
explainSandboxFailurepasses a non-sandbox launch error through unchanged (only sandbox aborts are tested).launchBrowse(every preflight test stubs launch or uses browse).explainSandboxFailurewiring (rejected: same helper already covered throughlaunch()andhandoff()).Tests ran: focused 65
Tests ran: free carried from CI (see Test plan)
Pre-Landing Review
Pre-Landing Review: 2 issues — 0 auto-fixed, 2 asked (0 fixed, 2 skipped), 0 deferred, 0 noted
Both are below the blocking floor (a finding blocks only if it would fail a test, break production, or lose data or secrets) and stay unfixed here:
browse/src/chromium-sandbox.ts:22: counting/.dockerenvas a container turns the sandbox off for non-root Docker users even where it would have worked. Kept: this is the lane's ruled design (/.dockerenvcounts as a container); raised for the owner to confirm.docs/troubleshooting.md:1700: the sentence "gstack never turns the sandbox off on its own: it already does so for root, CI, CONTAINER and Docker's /.dockerenv" contradicts itself; it should say gstack turns it off on its own only for those hosts.Gate edits: none detected (7 listed, 5 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)
Outside review: completed (openai/gpt-6.1-sol, host subagent), VERDICT: FINDINGS with 1 Low, Blocks: no. Native adversarial review: 5 findings (1 Medium, 4 Low), all Blocks: no. Targeted gate reader: no findings.
Review notes
Below the blocking floor (advisory, informational, test-gap or wording items); recorded here and not fixed in this PR.
browse/src/chromium-sandbox.ts:22/.dockerenv turns the sandbox off in every Docker container with no opt-back-in (duplicate of red-team#1, multi-source)lib/design-build.ts:220Any non-sandbox preflight launch failure is labeled NO_BROWSER with the gstack-browser-ensure fixlib/design-build.ts:217Preflight now starts the browse daemon (may run gstack-browser-ensure up to 600 s) before the UNAUTHORIZED_TARGET check; design-build-e2e daemon outlives its temp repobrowse/src/browser-manager.ts:701Sandbox error replaces the GSTACK_CHROMIUM_PATH message; the binary name survives only in causebrowse/src/browser-manager.ts:2262Cosmetic: multi-line framing of the handoff and browseRunner error textlib/aside-render.ts:600launchBrowse ignores closetab's result, so a failed close leaves the probe tab open while preflight reports successExploratory QA
Functional (CLI) smoke on this host (uid 1001, no
/.dockerenv, no CI or CONTAINER), owned loopback fixture on 127.0.0.1:5611.user.max_user_namespaceswas set to 0 for probes 2 and 3 and restored to 64045 afterwards.PREFLIGHT: ok engine=browse, exit 0.DESIGN_BUILD: unrendered code=BROWSER_SANDBOXwith the actionable error, exit 4, before any URL check.browse gotoexits 1 with the one sandbox error afterServer failed to start:and does not navigate, so there is no retry without the sandbox.Verdict: pass. Limits: smoke budget only (3 probes, 32 s); probe 1 finished in 0.8 s, so it alone does not prove a cold Chromium start (probe 2 does prove the launch path is real);
browse/dist/browsewas built from HEAD's browse source (mtimes, clean tree), not rebuilt for this run.Design Review
No frontend files changed — design review skipped.
Eval Results
Evals not run. No prompt, template or judge changed, but
lib/design-build.tsis a derived reference, so the PR selector picks 108 behavioral probes (the gate-tier touchfile plan selects 18 tests in 7 shards). At 3-trial behavior panels that is at least 54 agent sessions, over this run's $10 eval cap, so the selection goes to the owner instead. Spend: $0.Review bot comments
No review bot comments.
Scope Drift
Scope Check: CLEAN
Intent: give one actionable error when Chromium's sandbox can't start, never turn the sandbox off automatically (beyond
/.dockerenvcounting as a container), and make design-build preflight launch the browser for real.Delivered: a sandbox policy module with the one error, the abort mapped at the four launch sites with no retry,
launchBrowsefactored out ofrenderWithBrowsefor preflight, tests, docs and a changelog fragment.Plan Completion
Plan completion audit: not run (no plan is bound to this branch and no docs/designs/ file matches). This is a bug fix (plan exempt) with a repro on main and failing-first tests.
Verification Results
No plan verification items (no plan file). Automatic Exploratory QA above: 3 PASS, 0 FAIL, 0 BLOCKED, 0 NOT RUN.
TODOS
No TODO items completed in this PR.
Documentation
Status: current. The docs already cover this change, so no edits were needed.
Scope: 9740bfd..0cd09a7 (1 commit, 10 files) plus the unstaged change to changelog.d/capy-browser-sandbox-error.md. Nothing was staged and there were no new files. Checked: the new Chromium sandbox error (
browse/src/chromium-sandbox.ts),gstack-design-build preflightnow launching the browser and its newBROWSER_SANDBOXcode.Documentation health
chromium-sandbox-unavailableentry matches the error text and the fixBROWSER_SANDBOXand links to the troubleshooting entryGSTACK_CHROMIUM_NO_SANDBOX=1NO_BROWSERcode belongs to the lint, so this change doesn't affect itCoverage debt:
BROWSER_SANDBOXhas reference coverage (the how-to table and the troubleshooting entry).CHROMIUM_SANDBOX_HELPandsandboxFailureare internal, so they need no docs. The README sandbox hint could link todocs/troubleshooting.md#chromium-sandbox-unavailable. That is a minor gap.Diagram drift: none found.
Test plan
bun test --timeout=30000 browse/test/chromium-sandbox.test.ts browse/test/browser-manager-unit.test.ts test/design-build.test.ts: 65 tests pass at 39d3854.bun run test: carried from CI free-tests run 42474196870/1 at tree 151b877dcf7d (1643 files, 36476 tests, green).browse gotowithuser.max_user_namespaces=0(3 of 3 probes pass).🤖 Generated with Claude Code
Agent notes
Refs GST-1906
Approvals
No approvals recorded for branch capy/browser-sandbox-error.
Plan: exempt: bug fix
REVIEW_LOOP: passes=1 blocking_found=0 deferred=0 noted=0 fixed=0 scope=frozen ledgers_read=3 dispatches=4
Gate edits: none detected (7 listed, 5 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)