finding: the ADR-0082 D4 ratchet's only trigger needs a Playwright browser the dev containers cannot supply at the expected revision #7315

Observation-class finding recorded while running the console pin bump for #7268 (PR #7308). Nothing a product user hits; it is a durability risk for a gate that runs on-demand only. Filed unassigned, no pm:queue — for triage to grade.

What happened

scripts/gen-sdui-manifest.sh is, by explicit decision (#5960), the only trigger for the ADR-0082 D4 spec-registry declaration-parity ratchet: never a CI job, run on demand when the objectui pin moves. It needs Playwright chromium.

In the dispatch container PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers is pre-populated, but with chromium build 1194, laid out the old way:

/opt/pw-browsers/chromium_headless_shell-1194/chrome-linux/headless_shell
/opt/pw-browsers/chromium-1194/chrome-linux/chrome

objectui at the new pin pulls playwright 1.62.1, which looks for build 1234 at the newer path, and fails:

browserType.launch: Executable doesn't exist at
  /opt/pw-browsers/chromium_headless_shell-1234/chrome-headless-shell-linux64/chrome-headless-shell

The remedy both scripts print — pnpm exec playwright install chromium-headless-shell — is unavailable here: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 is set and agents are instructed not to run it.

Why it is worth recording rather than shrugging at

The script is deliberately a reminder, not a hard gate, so that a machine without Playwright can still move the pin — a good decision, and this finding does not dispute it. But it means the failure mode the reminder exists to prevent is precisely "nobody ran it", and a browser that cannot launch converts every pin-bump dispatch into that case without any gate going red. The pin bump is the ratchet's only trigger, so a skipped run is not deferred coverage, it is coverage that never happens for that range.

Workaround that worked (no install, no shared-state mutation)

A symlink tree in the agent's own scratchpad, named for the revision playwright wants, pointing at the binaries the container already has:

D=$SCRATCH/pw/chromium_headless_shell-1234
mkdir -p "$D/chrome-headless-shell-linux64"
touch "$D/INSTALLATION_COMPLETE" "$D/DEPENDENCIES_VALIDATED"
SRC=/opt/pw-browsers/chromium_headless_shell-1194/chrome-linux
for f in "$SRC"/*; do ln -sfn "$f" "$D/chrome-headless-shell-linux64/$(basename "$f")"; done
ln -sfn "$SRC/headless_shell" "$D/chrome-headless-shell-linux64/chrome-headless-shell"

PLAYWRIGHT_BROWSERS_PATH=$SCRATCH/pw pnpm sdui:manifest

Chromium 141.0.7390.37 driven by playwright 1.62.1 ran the dump and the ratchet cleanly: 57 public blocks written, no new DECLARATION divergence vs accepted baseline. So the version gap is cosmetic for this workload — it is the path/revision lookup that fails, not the browser.

Candidate dispositions (not decided here)

1. Leave as is and let each pin-bump dispatch rediscover it. Cheapest; also how it stays a silent skip.
2. Record the workaround in docs/releases-maintenance.md under "After the pin moves", next to the existing Playwright note — the smallest change that removes the rediscovery cost.
3. Have gen-sdui-manifest.sh fall back to a discovered local chromium (executablePath) when the expected revision is absent, and say loudly which binary it used. Larger surface; the dump script lives in objectui, not here, so this may need a change on that side.
4. Align the container image's pre-installed browser with the playwright version the pinned objectui pulls. Outside this repo.

No option is recommended — the trade-off is a devx/infra call, and item 3 in particular crosses a repo boundary.

Evidence

Measured 2026-08-10 during PR #7308 (pin 09987b680d53 → 8aad9fd50b16). The ratchet ultimately ran and was green, so this bump has full D4 coverage; the finding is about the next one.

Generated by Claude Code