Launch mode, observe-only input, target cycling, and reliability fixes (0.7.0) - #7

…erve-only and target cycling

this.mode carried two unrelated values: the backend decision (attach vs
agent-browser) at construction, then the render mode (kitty/symbols/text)
once run() assigned pickRenderMode's result. The second assignment erased
the first, so a pane started with HERDR_BROWSER_CDP_URL or a cdp-url config
never entered the attach tick path — it sat in agent-browser mode waiting
for a session — and a runtime 'a'-key attach clobbered the render mode,
breaking kitty PNG and text rendering for the rest of the pane's life.
Tests missed it because they drive tick() without run(). Backend checks now
read this.backend; this.mode is render-only and null until run() picks it.
The header shows the endpoint host:port (never the capability token path)
instead of the meaningless session name while attached.

Also removes a merge artifact from 294cade where navigate()'s
networkBaselinePending=true fix (34d1559) was immediately undone by the
pre-fix line the merge kept — a busy-guarded baseline read would replay the
whole failure log on the next poll.

On top of the split, two planned follow-ups from the attach-mode plan land:
'o' toggles observe-only (clicks, wheel, keys, prompts, and Cmd+click
handoffs are dropped at the pane, so watching a live automation run cannot
perturb it — the toggle itself and pane-view keys stay reachable), and 't'
wires the already-implemented cycleTarget() backend to a key so the pane
can move between page targets, with a banner when there is only one.
Regression tests cover the split, the baseline flag, and both keys.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

… the attach header

The failed-request paragraph kept both sides of the 294cade merge — the
pre-fix and post-fix wording of the dedupe-window sentence ran into each
other mid-sentence. Restore the 34d1559 wording, which matches the code
(a repeat paints once and stays collapsed until quiet for 60 seconds).
Document the new t (cycle page targets) and o (observe-only) keys and the
endpoint host:port header shown while attached.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

The pane no longer requires any pre-existing engine: l finds a local
Chromium (HERDR_BROWSER_CHROMIUM / chromium config file, then PATH names
and the macOS app bundles), starts it headless with
--remote-debugging-port=0 and a per-workspace profile under the plugin
state dir, reads the bound port from DevToolsActivePort, and attaches
through the normal attach path. HERDR_BROWSER_LAUNCH_HEADED=1 launches a
visible window. Root (containers, CI) adds --no-sandbox, since Chrome
refuses to start as root without it.

Ownership is the deliberate difference from plain attach: the pane spawned
this browser, so quitting the pane — or attaching to a different endpoint —
kills it instead of leaking a headless Chrome. The endpoint guarantees are
unchanged: loopback port, capability token never displayed.

Also fixes the unattached key gate, which swallowed 'a' — the documented
attach key was unreachable exactly when attaching is the answer (no session
yet, or a dead endpoint). 'a' and 'l' now pass the gate. Verified end to
end against a real Chromium: launch, attach, navigate, screencast frames,
screenshot, console + network-failure feed, and child kill on cleanup.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

launchChromium refuses before spawning on Node < 22 — attaching to the
result needs the global WebSocket client, and a browser the pane can never
attach to would idle until quit. Firefox endpoints now fail with a named
banner ('browser has no CDP screencast') instead of a raw protocol error,
closing a deferred item from the attach plan. A real-browser integration
test drives launch mode end to end — spawn, DevToolsActivePort, attach,
navigate, screencast frame, console feed, child kill — and skips cleanly
where no Chromium or WebSocket client exists, so the Node 20 CI leg and
engine-less machines stay green. Version 0.7.0; plan doc records the wave.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…efuses in attach mode

Three findings from an adversarial re-read plus the recording gap:

- spawn() reports a missing or non-executable Chromium (a typo'd
  HERDR_BROWSER_CHROMIUM) as an async 'error' event; without a listener it
  became an uncaughtException that took the whole pane down. The launcher
  now listens, aborts the port wait, and banners the real reason.
- --headless=new was removed in newer Chromes; plain --headless selects new
  headless on 112+ and old headless (which also serves DevTools and
  screencast) before that.
- record.mjs hardcoded plugin version 0.6.0, which the 0.7.0 bump missed.
  Now single-sourced from package.json; the Start/Stop manifest identity
  check still fails closed across an upgrade.

Recording captures the workspace's agent-browser session; in CDP attach
mode there is none, and record-start would have spawned and recorded a
fresh, unrelated headless browser. record.sh now resolves the endpoint the
same way open.sh does and refuses with an explanation, in both the env-var
and config-file cases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

attachCdp refuses on Node < 22 (no WebSocket client) before touching the
backend, so every attach-mode behavioral test that drives tick() failed on
the CI matrix's Node 20 leg — a gap the broken workflow had always hidden.
Those tests now skip under the same condition production refuses under,
verified with node --no-experimental-websocket: 0 failures, 18 skips.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…robing

HERDR_BROWSER_OBSERVE=1 (or the observe config file) starts the pane
observe-only for watch-the-agent workflows; o still toggles.
HERDR_BROWSER_LAUNCH=1 (or the launch config file) makes the first
unattached tick launch a local Chromium instead of waiting for an
agent-browser session — one attempt, banner on failure, and a configured
cdp-url endpoint still wins. An in-flight launch now also holds the banner
against the waiting-for-session tick.

Probe order change from CI evidence: 'chromium' on Ubuntu is often a snap
wrapper whose confinement cannot read a profile directory outside $HOME —
it never writes DevToolsActivePort and the launch times out (exactly what
the integration test caught on the runner). google-chrome, nearly always a
real binary where present, is probed first.

Adds a CI badge and documents the new knobs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

The console discontinuity line now says '— launched Chromium —' when the
pane launched the browser itself (attachTo grows an optional note). The
plugin manifest description mentions all three backends. The security
section states plainly that chromium/cdp-url config files and their env
equivalents are trusted local configuration.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…redials its dead port

The launched Chromium's DevTools port dies with it, so on its exit the
attach retry loop would dial a corpse every cooldown while the banner
claimed to be retrying something recoverable. The exit handler (when the
pane is still pointed at the launched endpoint) now detaches, latches the
retry cooldown, and says what actually helps. Pane-initiated kills are
unaffected: cleanup and attach-elsewhere clear launchedChild before the
exit event fires, and a fresh l or a resets the latch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…dings

A high-effort review of the branch surfaced seven findings; all are fixed:

- open.sh's backend arbitration only knew cdp-url, so in a launch-first
  workspace a Cmd+click spawned an invisible, unrelated agent-browser
  session instead of navigating the pane's launched Chromium. Arbitration
  now lives in lib.sh (cdp_endpoint_configured / launch_configured /
  observe_configured, in lockstep with the renderer's knobs) and both
  pane-owned modes take the handoff-file path.
- open.sh also required agent-browser before the arbitration branch, so an
  attach/launch workspace could not even open the pane without it. The
  requirement moved onto the branch that invokes agent-browser.
- record.sh's refusal now covers launch mode, which equally has no
  agent-browser session to record.
- An observe-configured workspace's open action refuses link navigation:
  in agent-browser mode the daemon is navigated outside the pane, so the
  pane-side latch alone could not keep the promise. README scopes the
  runtime toggle's caveat honestly.
- Launch-failure banners are held for 30s against the waiting-for-session
  tick that repainted over them within a second.
- A Chromium crash between the DevToolsActivePort read and the queued
  attach now latches and banners; the queued attach notices the corpse.
  Both death checks also handle signal deaths (exitCode stays null,
  signalCode is set) — SIGKILL previously evaded them.
- Observe/launch env knobs use || like cdp-url, so a set-but-empty env var
  falls through to the config file instead of silently disabling it.
- README's probe-order sentence matches the google-chrome-first code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…l Chrome on CI

The banner-hold test built a renderer with no PATH at all; sh then falls
back to the system default path, where CI runners have a real
/usr/bin/google-chrome — the probe found it, the test launched an actual
browser, and its open handles (child process, CDP WebSocket) hung the
Node 22 job until the workflow timeout. mkRenderer now sets
PATH=/nonexistent by default so the launch-mode probe is deterministically
empty in every unit test; tests that want a real browser (the integration
test) construct their own env with a real PATH.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY

…er; shell parity

Round two of review findings, all in the unattached-pane paths the first
round created:

- A Cmd+click in a launch workspace whose browser is not up now triggers
  the launch and parks the URL, delivered on attach (fresh within 2 min).
  Previously the handoff was written but nothing consumed it — the click
  silently vanished, and a later successful attach replayed an arbitrarily
  old URL. Handoff files older than 5 minutes are now dropped outright.
- A pane switched to attach/launch at runtime (the a or l key) leaves a
  backend marker; open.sh routes clicks to the handoff file when a live
  pane holds the marker, instead of spawning the invisible agent-browser
  session the arbitration exists to prevent. A dead pane's stale marker is
  ignored, and cleanup removes it.
- The post-failure waiting banner in a launch workspace now gives accurate
  advice — press l or Cmd+click to retry — instead of advertising a click
  path that previously did nothing.
- cdp_endpoint_configured treats whitespace-only env values as unset,
  restoring the lockstep its comment claims with resolveCdpEndpoint, and
  is a silent predicate (callers no longer redirect dead output).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7GSCAnQs6T6FgK9fzNXCY