fix(browser): name the Cloak setContent hang instead of advising a longer timeout (#448)

[Ayushraj06-bit]

Description

#448 is misdiagnosed. filechooser already works on the local Cloak runtime — page.setContent() is what hangs.

Running the issue's program unchanged against real Cloak reproduces the timeout. Changing only setContent to goto and leaving every other line identical:

A) direct Playwright on Cloak : "evidence.pdf"
B) through browser run        : ok, "evidence.pdf"

So the chooser is forwarded, setFiles takes in-memory payloads, and an input removed right after click() is fine. The program never got that far: it spent its whole budget on statement one, and browser run replied Split the task into a smaller run or increase --timeout — advice that cannot work, and sends the caller back around the same 30s wall.

Cause. Cloak's Chromium accepts Runtime.enable but never emits Runtime.consoleAPICalled. Playwright resolves Frame.setContent on a console.debug(<tag>) sentinel it writes from the utility world beside document.write, so the promise never settles even though the markup has landed:

[stock chromium]     setContent: RESOLVED 11ms | console ev: ["log:main-log","debug:main-debug"]
[cloak humanize:on]  setContent: HUNG 8005ms   | content landed: "hi" | console ev: []
[cloak humanize:off] setContent: HUNG 8005ms   | content landed: "hi" | console ev: []

Reproduced with cloakbrowser alone, humanize on and off, so it is upstream of webcmd and not the browser-run bridge. This is CloakHQ/cloakbrowser#360, which Cloak-HQ confirmed and root-caused to the binary's DevTools layer on 2026-06-07, with a fix promised in "the next binary build". It is still open, and still reproduces on the current binary three months later. It also explains the issue's control: with stock playwright-core, setContent resolves normally. And why Cloak 0.5.9 changed nothing — it is the browser binary, not the wrapper.

Fix. Classify that timeout and name the cause and the recovery CloakBrowser itself publishes on #360, reusing the timeoutKind / timeoutRunError path that already backs POPUP_WAIT_TIMEOUT_HINT and DOWNLOAD_WAIT_TIMEOUT_HINT. Two deliberate constraints:

• setContent is checked last, so popup and download keep every timeout they claim today.
• Message detection requires the setting frame content call log and a timeout, because a detached frame or closed target logs that same line and must not be retyped.

The hint points at the upstream workaround rather than a data: URL, because it keeps the page on its current origin — and webcmd already has a separate typed error for data:/about:blank documents losing localStorage:

await page.evaluate(html => { document.open(); document.write(html); document.close(); }, html);
await page.waitForLoadState('load');

Verified end to end through browser run on real Cloak: completes in 21ms, leaves page.url() untouched, and the issue's full filechooser program then returns evidence.pdf.

This does not make setContent work — that needs the binary fix tracked in #360.

Alternative considered. Reimplementing setContent in PlaywrightTransport to bypass the sentinel would make the call work, but it re-derives raceNavigationAction and lifecycle semantics by hand and changes setContent for stock Chromium and SLAB too — a large diff for a defect that is not webcmd's.

Related issue: #448

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🌐 New site adapter
• 📝 Documentation
• ♻️ Refactor
• 🔧 CI / build / tooling

Checklist

• I ran the checks relevant to this PR
• I updated tests or docs if needed
• I included output or screenshots when useful
• If I edited skill-src/, I ran make build and committed skills/ — not edited

Adapter Notes

Not an adapter change.

Screenshots / Output

npm run typecheck && npm run build && npm test
npx vitest run --project unit src/browser/run/runner.test.ts

Two tests fail on main and pass here:

× tells the caller to navigate instead when a run that sets content times out
× types a setContent timeout as a browser-run timeout

-   "hint": "page.setContent() never resolves on the local Cloak runtime. …"
+   "hint": "Split the task into a smaller run or increase --timeout."

runner.test.ts goes to 96 passed (96). The other five added tests are regression guards that hold on main too: popup/download precedence, the generic hint, and two that keep a non-timeout setContent failure from being retyped.

typecheck exit 0, build exit 0. My Windows box has 28 pre-existing failures (22 EPERM … symlink, plus \-vs-/ path assertions); I diffed the failure set against a pristine checkout of main and it is byte-identical, with passing counts 3590 → 3597 for the added tests.

Evidence above is from cloakbrowser 0.4.5 / Chromium 146.0.7680.177.5, headed persistent context — the configuration session-manager.ts launches.

---

Notes

• Refs, not Fixes. This PR changes no filechooser code, because that path works, and it does not make setContent resolve. I'd suggest closing Local Cloak browser-run does not forward transient filechooser events #448 as misdiagnosed once you've read the reproduction, but this shouldn't auto-close it.
• The 🟠 advisory docs-sync comment above is the known bug in fix(docs-review): constrain the advisory review with the schema it already defines #466 (response_format schema dropped by fix: parse fenced docs review json #260), not a finding about this change — same limitation string on feat: modular suite with interactive cloner TUI, browser-router, and ppt generator #525, Add Application Rescue Agent #523, agent #517, feat: add automated finance and invoice tracking plugin #516, # feat(cloner): Universal Website Cloner, WCAG 2.1 Audit & Design System Studio (webcmd clone) #515, feat: add universal website task engine UI #513 and feat(cli): add Weaver, a block-art terminal mascot #511.
• The hint names Cloak specifically. I verified stock Chromium (fine) and Cloak (broken); I did not test SLAB.
• Like the popup and download hints, this is a source heuristic: a timed-out run whose source contains .setContent( gets the hint even if it hung elsewhere. Popup and download take precedence.
• No CHANGELOG entry, assuming release-please owns that file — happy to add one.
• Worth its own issue if you want it: because those console events never arrive, page.on('console') never fires on the default runtime, so page-side console.log is silently dropped in every browser-run program.

Refs #448

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.