browser-trace: fix bodies-snapshot dir + add helper

[skyzer]

Problem

Following the documented two-step workflow in browser-to-api/SKILL.md ends with this snapshot step:

cp -r "$(browse network path | jq -r .path)" .o11y/<run>/cdp/network/bodies/

On macOS (BSD cp), this fails before bisect-cdp.mjs has been run because the parent directory cdp/network/ does not exist yet and BSD cp will not create the parent for a trailing-slash destination.

Reproduce on a clean macOS:

node scripts/start-capture.mjs 9222 demo
browse network on
browse open https://example.com
cp -r "$(browse network path | jq -r .path)" .o11y/demo/cdp/network/bodies/
# cp: .o11y/demo/cdp/network/bodies/: No such file or directory

The current docs only suggest the manual cp after the snapshot step, and discover.mjs then silently runs without response bodies, producing a spec with no response schemas.

Fix

Two-part change, smallest surface area that closes the gap:

1. browser-trace/scripts/start-capture.mjs — also ensure cdp/network/ exists up front (one line). bisect-cdp.mjs still creates it later via writeJsonl; this just moves creation earlier so the snapshot step does not depend on bisect having run first.

2. browser-trace/scripts/snapshot-bodies.mjs (new) — encodes the safe snapshot path: resolves browse network path, copies via fs.cpSync (sidesteps BSD vs GNU cp variance entirely), and by default runs `browse network off` (--no-off to skip). Replaces the brittle cp one-liner in both browser-to-api/SKILL.md and REFERENCE.md.

The manual cp pattern is kept in REFERENCE.md as commented context for hand-rolling, with the mkdir -p step it actually needs.

Usage after this PR

```bash
node ../browser-trace/scripts/start-capture.mjs "$TARGET" my-site
browse network on
browse open https://example.com
node ../browser-trace/scripts/snapshot-bodies.mjs my-site # ← was a brittle cp
node ../browser-trace/scripts/stop-capture.mjs my-site
node ../browser-trace/scripts/bisect-cdp.mjs my-site
node scripts/discover.mjs --run .o11y/my-site
```

Verification

End-to-end against `@browserbasehq/[email protected]` on macOS 25.4.0:

• `start-capture` now creates `.o11y//cdp/network/` as part of the initial dir setup ✓
• `snapshot-bodies ` produces `{"bodies_dest":"...","files":466,"ran_off":true}` ✓
• `snapshot-bodies --no-off` skips the `browse network off` call ✓
• `discover.mjs` picks up the bodies automatically and infers response schemas ✓
• All previously documented jq + query.mjs recipes still work against the bisected output ✓

Scope kept narrow

No other behavior changes. `bisect-cdp.mjs`, `stop-capture.mjs`, `discover.mjs`, the pipeline stages, and all output formats are untouched.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2906b16c8a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Fall back when browse network path --json exits non-zero

The script exits immediately when browse network path --json returns a non-zero status, so the documented compatibility fallback to plain browse network path never runs in the common “unknown flag” case on older browse versions. In those environments, snapshot-bodies.mjs fails even though the non-JSON command could still provide a valid path, blocking body snapshotting for the whole workflow.

Useful? React with 👍 / 👎.