From c57e759ae6eee0c312db4acd525ae381b8e2405d Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Sun, 11 Oct 2026 07:30:25 +0800
Subject: [PATCH] fix(browser): bypass desktop keyrings in verification
 fixtures

Use password-store=basic for owned raw Chrome verification processes and document the same option for dedicated caller-owned Linux investigation profiles. Locked keyrings can stall navigation and leave placeholder frame URLs; keep the existing committed-URL authorization boundary.

Validation: real Chrome 154 CLI and stdio MCP browser verifier passed on macOS ARM64, plus docs freshness and check:fast. The locked Linux desktop keyring environment was not reproduced locally.
---
 docs/browser-observation.md                       | 6 ++++++
 docs/testing.md                                   | 6 ++++++
 scripts/lib/browser-runtime-fixture-lifecycle.mjs | 1 +
 scripts/verify-real-browser.mjs                   | 1 +
 4 files changed, 14 insertions(+)

diff --git a/docs/browser-observation.md b/docs/browser-observation.md
index ca793ac5b2..3cdac5aa14 100644
--- a/docs/browser-observation.md
+++ b/docs/browser-observation.md
@@ -53,6 +53,12 @@ google-chrome \
 
 REA does not launch, own, or terminate this browser. Use a dedicated profile and stop it yourself when the investigation is complete. Do not expose the debugging port on a non-loopback interface.
 
+On Linux, a reachable but locked desktop keyring can stall Chrome before its
+first navigation. For a dedicated investigation profile, add
+`--password-store=basic` to bypass that keyring. Empty or placeholder frame URLs
+then describe an unloaded page; REA continues to require an allowed, committed
+URL. See [the startup investigation](https://github.com/morluto/rea/issues/1384#issuecomment-6093781686).
+
 ## Request boundary
 
 CDP connections enforce the shared 64 MiB limit per WebSocket message. A larger
diff --git a/docs/testing.md b/docs/testing.md
index 3c05df0962..3f91188e82 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -391,6 +391,12 @@ regressions until a real fixture establishes equivalent coverage.
 
 `verify:browser` exercises source-map failure isolation and expanded-output limits through the compiled CLI and stdio MCP with real Chrome. It also submits five 2 MiB source-map annotations, checks retained script identities and explicit map omissions, and closes its owned fixture target. Replacement and document-reset behavior has separate producer-boundary coverage.
 
+The raw Chrome fixture launchers use `--password-store=basic` so Linux startup
+does not wait for an unlock prompt from a reachable but locked desktop keyring.
+Such a stall leaves the initial page unloaded with empty or placeholder CDP URLs;
+it does not establish permission to capture that page. See
+[the keyring diagnosis](https://github.com/morluto/rea/issues/1384#issuecomment-6093781686).
+
 `verify:browser` also captures a source-owned noise canvas as a real PNG above
 8 MiB through the CLI and stdio MCP, with complete byte/digest parity and real PNG
 decoding. Its SDK client explicitly permits the larger inline JSON response;
diff --git a/scripts/lib/browser-runtime-fixture-lifecycle.mjs b/scripts/lib/browser-runtime-fixture-lifecycle.mjs
index 2ab048cf27..24b88c793e 100644
--- a/scripts/lib/browser-runtime-fixture-lifecycle.mjs
+++ b/scripts/lib/browser-runtime-fixture-lifecycle.mjs
@@ -18,6 +18,7 @@ export async function startRuntimeFixtureBrowser(executable, origin) {
       command: executable,
       arguments: [
         "--headless=new",
+        "--password-store=basic",
         ...(process.env.REA_BROWSER_NO_SANDBOX === "true"
           ? ["--no-sandbox"]
           : []),
diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjs
index 4dd4928546..a63024b49a 100644
--- a/scripts/verify-real-browser.mjs
+++ b/scripts/verify-real-browser.mjs
@@ -64,6 +64,7 @@ try {
     executable,
     [
       "--headless=new",
+      "--password-store=basic",
       ...(process.env.REA_BROWSER_NO_SANDBOX === "true"
         ? ["--no-sandbox"]
         : []),