docs: troubleshooting note for 'connected but actions time out'

[lianghua1]

Ran into a state today that cost me a couple of hours because every signal the CLI gives you points at the wrong thing, so I wrote up the diagnosis. Docs-only, no code changes.

The symptom

bsk browsers lists the browser. bsk doctor is ok on every line. bsk tab list answers. But anything that drives the page hangs:

$ bsk session start
error: session creation timed out waiting for extension

$ bsk evaluate "1+1" --session <id>
error: operation timed out
details: tool RPC timed out after 30s

Even about:blank + evaluate "1+1" times out. I spent a while reloading the extension and restarting the daemon, since "connected" is the only state the CLI surfaces.

What the log actually showed

bsk logs had the answer the whole time:

{"message":"browser connected","id":"23841dec","generation":5}
{"message":"client did not send handshake in time; dropping connection","timeout_secs":5}
{"message":"ws connection error","error":"handshake first-frame timeout"}
{"message":"browser reconnect: replacing previous registration","old_generation":9,"new_generation":10}
{"message":"browser connected","id":"23841dec","generation":10}

One instance_id, generation climbing 1→10. So it's a single extension control plane that keeps missing HANDSHAKE_FIRST_FRAME_TIMEOUT (crates/bsk-cli/src/daemon/ws.rs, 5s) and reconnecting into the same slot — not two browsers competing for one id, which is what the generation numbers first suggested to me.

And then the part that explains why the error is a bare timeout instead of a clean disconnect: a reconnect replaces the registered BrowserClient under the same instance_id, so an action RPC issued during the cycle can be waiting on a connection that's already being torn down. The registry has a live entry the whole time, so nothing ever reports a lost connection.

The doc

docs/troubleshooting-wedged-actions.md:

• the log signature that distinguishes this (instance_id constant, generation climbing)
• what it is not — daemon restart, the two-different-ids multi-instance case (chrome.debugger wedges for all profiles once a second profile connects (Yandex Browser 26.8, bsk 0.3.0) #272 / browser skill chrome extension not working [WSTransport] disconnect during connect #246), or a stuck CDP session (Debugger is not attached to the tab, which is chrome.debugger wedges for all profiles once a second profile connects (Yandex Browser 26.8, bsk 0.3.0) #272)
• graduated recovery: check load → reload extension → restart browser → confirm generation stops climbing
• a note that metadata commands keep working during the window, so they aren't evidence that actions work

Linked from the "Verify the connection" step in Quick Start, where someone hitting this would be looking, and from the developer guide index next to the other doc links.

Why I think this is worth a page rather than just "reload it"

Every state the CLI prints can be true while actions are unusable. connected, doctor: ok, browsers: 1 — all correct, all misleading. The one line that resolves it (handshake first-frame timeout next to a climbing generation) isn't in the summary output, so the default path is to debug the extension. A doc is the cheapest fix; if you'd rather surface that condition in doctor (e.g. warn when a reconnect replaces a live generation more than N times in a window), I'm happy to take a shot at that instead or as well.

Verified against the source

Both constants the doc cites are real, and I checked line references against current main:

• HANDSHAKE_FIRST_FRAME_TIMEOUT — crates/bsk-cli/src/daemon/ws.rs:173
• DEFAULT_INITIAL_DELAY_MS / DEFAULT_MAX_DELAY_MS — apps/extension/src/transport/ws-transport.ts:4-5
• the reconnect-replaces-registration log line — crates/bsk-cli/src/daemon/browsers.rs (Registry::insert)

Environment

Windows, bsk 0.3.0, daemon 0.3.0, extension 0.3.0, protocol 1.3, Chrome 153, default profile. Recovered after the reconnect cycle settled; I did not capture a clean before/after on an idle machine, so I've deliberately written the doc around the log signature rather than claiming a specific trigger.