Skip to content

Give a clear error when Chromium's sandbox can't start, and make design-build preflight launch the browser (GST-1906) - #4162

Merged
capy-ai[bot] merged 2 commits into
mainfrom
capy/browser-sandbox-error
Nov 8, 2026
Merged

capy-ai[bot] merged 2 commits into
mainfrom
capy/browser-sandbox-error

Conversation

@garrytan

@garrytan garrytan commented Nov 8, 2026 •

Copy link
Copy Markdown
Owner

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 --build finds 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

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
Before (main 9740bfd, user.max_user_namespaces=0):
$ gstack-design-build preflight --inventory inv.json
PREFLIGHT: ok engine=browse states=1 targets=loopback mutations=unknown
exit=0

After (this branch, same host):
$ gstack-design-build preflight --inventory inv.json
DESIGN_BUILD: unrendered code=BROWSER_SANDBOX (Chromium could not start its sandbox: this Linux host does not let unprivileged users create user namespaces ... or set GSTACK_CHROMIUM_NO_SANDBOX=1 to run Chromium without its sandbox. Use that only for pages you trust ... No usable sandbox! ...) | fix: allow unprivileged user namespaces, or set GSTACK_CHROMIUM_NO_SANDBOX=1 only if every page in the run is trusted, then rerun /design-review --build
exit=4
  • One error for a sandbox that can't start. When Chromium aborts with "No usable sandbox!", browse fails with a single message naming both fixes. You can allow user namespaces (the Ubuntu AppArmor setting), or set 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.
  • No automatic retry without the sandbox. The only new host signal is Docker's /.dockerenv, which now counts as a container, the same as CONTAINER.
  • Preflight launches the browser it found. It opens and closes one tab through the same path render uses, including the lazy Chromium install. A sandbox failure stops the run with DESIGN_BUILD: unrendered code=BROWSER_SANDBOX, and any other launch failure stops it with NO_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 preflight still printed PREFLIGHT: ok before 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.ts gain one .catch(explainSandboxFailure), which rethrows every error that is not a sandbox abort unchanged, so XProtect and custom-Chromium handling keep their behavior (read at browse/src/chromium-sandbox.ts:49-52). renderWithBrowse keeps its tab-open path, now shared with launchBrowse; the existing fake-browse tests in test/aside-render.test.ts still pass over it, and the real sandbox failure was reproduced on this host with user.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 --build died 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 with BROWSER_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.ts new; browse/test/browser-manager-unit.test.ts and test/design-build.test.ts extended). 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:

  • explainSandboxFailure passes a non-sandbox launch error through unchanged (only sandbox aborts are tested).
  • Preflight with the Aside engine skips launchBrowse (every preflight test stubs launch or uses browse).
  • The extension launch path's explainSandboxFailure wiring (rejected: same helper already covered through launch() and handoff()).

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:

  • [INFORMATIONAL] (confidence: 6/10, red-team) browse/src/chromium-sandbox.ts:22: counting /.dockerenv as 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 (/.dockerenv counts as a container); raised for the owner to confirm.
  • [INFORMATIONAL] (confidence: 8/10, core) 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.

  • INFORMATIONAL 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)
  • INFORMATIONAL lib/design-build.ts:220 Any non-sandbox preflight launch failure is labeled NO_BROWSER with the gstack-browser-ensure fix
  • INFORMATIONAL lib/design-build.ts:217 Preflight 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 repo
  • INFORMATIONAL browse/src/browser-manager.ts:701 Sandbox error replaces the GSTACK_CHROMIUM_PATH message; the binary name survives only in cause
  • INFORMATIONAL browse/src/browser-manager.ts:2262 Cosmetic: multi-line framing of the handoff and browseRunner error text
  • INFORMATIONAL lib/aside-render.ts:600 launchBrowse ignores closetab's result, so a failed close leaves the probe tab open while preflight reports success

Exploratory 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_namespaces was set to 0 for probes 2 and 3 and restored to 64045 afterwards.

  • Probe 1 pass: preflight on a sandbox-capable host prints PREFLIGHT: ok engine=browse, exit 0.
  • Probe 2 pass: with namespaces denied, preflight prints DESIGN_BUILD: unrendered code=BROWSER_SANDBOX with the actionable error, exit 4, before any URL check.
  • Probe 3 pass: with namespaces denied, browse goto exits 1 with the one sandbox error after Server 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/browse was 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.ts is 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 /.dockerenv counting 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, launchBrowse factored out of renderWithBrowse for 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 preflight now launching the browser and its new BROWSER_SANDBOX code.

Documentation health

File Status
docs/troubleshooting.md Current: the new chromium-sandbox-unavailable entry matches the error text and the fix
docs/howto-preview-a-frontend.md Current: the preflight row lists BROWSER_SANDBOX and links to the troubleshooting entry
README.md Current: the Linux sandbox hint is accurate but names only GSTACK_CHROMIUM_NO_SANDBOX=1
docs/design-lint.md Current: its NO_BROWSER code belongs to the lint, so this change doesn't affect it

Coverage debt: BROWSER_SANDBOX has reference coverage (the how-to table and the troubleshooting entry). CHROMIUM_SANDBOX_HELP and sandboxFailure are internal, so they need no docs. The README sandbox hint could link to docs/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).
  • Pregate on the final tree: requires-remote cleared (macOS and Windows jobs green in runs 42474196870 and 42474196852).
  • Exploratory QA: preflight and browse goto with user.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)

{
  "schema_version": 1,
  "pr": 4162,
  "head": "39d3854655a646d787c00731013ae1cea7be5058",
  "version": "1.98.0.0",
  "base": "main",
  "gate": {
    "focused": {
      "pass": 65,
      "fail": 0,
      "skip": 0
    },
    "free": {
      "pass": 1643,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "free",
      "run": 42474196870,
      "attempt": 1,
      "tree": "151b877dcf7d1278cb4d25ab68abbc96e80b178d"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "151b877dcf7d1278cb4d25ab68abbc96e80b178d",
  "product_patch_id": "e65e1dab63812f4a3a05904dd26f834b3de808ee",
  "gstack_version": "1.98.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 243,
    "rules": "c6a079fdf812f479",
    "base": "9740bfd9407253d9e4a8d2c34d8d00db1e3578e2",
    "registry": "9740bfd9407253d9e4a8d2c34d8d00db1e3578e2",
    "gate_scan": {
      "tagged": 1,
      "head": "39d3854655a646d787c00731013ae1cea7be5058"
    },
    "reasons": [
      "gate-class",
      "risk:security",
      "runtime=243"
    ],
    "risk": [
      "security"
    ],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @151b877dcf7d (8 checks, current for 39d3854655a6)",
  "requires_remote": [
    "free-tests.yml/cso-macos-launcher: https://github.com/garrytan/gstack/actions/runs/42474196870/attempts/1",
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42474196870/attempts/1",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/42474196852/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=151b877dcf7d tests=36476 skipped=71 runs=42474196870/1 profiles=ci-reuse/free-tests heads=39d3854655a6 verified=2026-11-08T11:15:37.978Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, CONTRIBUTING.md (troubleshooting.md, howto-preview-a-frontend.md, README.md, design-lint.md read)"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 0,
    "deferred": 0,
    "noted": 0,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 1,
    "ledgers_read": 3,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  },
  "review_targeted": {
    "classes": [
      "gate"
    ],
    "rules": "8811fd300bf305f0",
    "brief_sha": "7f92a0d0a8319c3c0e076fb3b1a4689c45120b2be2c14dfc7d4cb03aafa9d6a5",
    "product_patch_id": "e65e1dab63812f4a3a05904dd26f834b3de808ee",
    "status": "done",
    "findings": 0,
    "raised_by": "targeted"
  }
}

Open in Capy

…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>
@trunk-io

trunk-io Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot merged commit 6042f6a into main Nov 8, 2026
54 checks passed
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.

1 participant