fix: isolate ProofShot session lifecycle

PROOFSHOT.md

@@ -11,13 +11,16 @@ After building or modifying UI features, verify with this workflow:
 
 ProofShot keeps all `proofshot exec` commands inside the same isolated `agent-browser` session that was created by `proofshot start`, so recording, screenshots, and browser actions stay aligned.
 
+Use `--url` on `start` when verification must begin on a specific target. In an isolated HOME, ProofShot discovers executable-only Chrome/Chromium installs from system/account locations; use `--browser-executable /absolute/path/to/chrome` to select one explicitly.
+
 Key proofshot exec commands:
 - `proofshot exec snapshot -i` — see interactive elements
 - `proofshot exec click @e3` — click an element
 - `proofshot exec fill @e2 "text"` — fill a form field
 - `proofshot exec screenshot step.png` — capture a moment
 
 Artifacts saved to ./proofshot-artifacts/ including video, screenshots, errors, and summary.
+Custom `--output` paths do not move active control state, so a separate `proofshot stop` still finds the session. `stop` is idempotent; after `stop --no-close`, run a later plain `stop` to close that exact retained browser without rebundling.
 You can customize browser launch behavior in `proofshot.config.json`, including HTTPS error ignoring, a custom browser executable path, and a project-specific `agent-browser` config path.
 
 Use `proofshot doctor` when the local setup looks wrong. It prints the current config path, browser mode, viewport, installed binaries, and any active ProofShot session.

README.md

@@ -140,6 +140,7 @@ proofshot start                                        # Server already running
 proofshot start --run "npm run dev" --port 3000         # Start and capture server
 proofshot start --description "Verify checkout flow"    # Add description to report
 proofshot start --url http://localhost:3000/login       # Open specific URL
+proofshot start --browser-executable /path/to/chrome    # Reuse an exact browser binary
 proofshot start --headed                                # Show browser (debugging)
 proofshot start --force                                 # Override a stale session from a previous crash
 ```
@@ -158,6 +159,10 @@ You can also configure browser launch behavior in `proofshot.config.json`:
 
 Set `browser.configPath` when you need ProofShot to run `agent-browser` against a project-specific config instead of inheriting `~/.agent-browser/config.json`. Relative paths are resolved from the directory that contains `proofshot.config.json`.
 
+ProofShot discovers system and account-level Chrome/Chromium installs even when the command runs with an isolated `HOME`. If no runnable browser is found, `start` prints the exact `agent-browser install` action. An explicit `--browser-executable` takes precedence for one run.
+
+`--output` changes only where evidence is written. Active control state stays in the configured/default output directory, so later `proofshot exec` and `proofshot stop` processes can find the same session.
+
 ### `proofshot stop`
 
 Stop recording, collect errors, generate proof artifacts.
@@ -167,6 +172,8 @@ proofshot stop              # Stop session and close browser
 proofshot stop --no-close   # Stop but keep browser open
 ```
 
+`stop` is idempotent. With `--no-close`, ProofShot retains exact ownership metadata after bundling; run a later plain `proofshot stop` to close that browser without rebuilding the artifacts.
+
 ### `proofshot exec`
 
 Pass-through to agent-browser with automatic session logging. Captures timestamps, element data, and resolves screenshot paths.
@@ -211,6 +218,8 @@ Remove the `./proofshot-artifacts/` directory.
 proofshot clean
 ```
 
+`clean` refuses while active or retained session control state exists. Run `proofshot stop` first so ProofShot does not discard exact process ownership metadata.
+
 ### `proofshot doctor`
 
 Print the current ProofShot environment, including config path, browser mode, viewport, installed binaries, and any active session.

content/docs/concepts/how-it-works.mdx

@@ -45,11 +45,11 @@ ProofShot uses a three-phase model.
 `proofshot start` initializes the session:
 
 1. Check if the port is available (fail fast on conflicts)
-2. Spawn the dev server if `--run` is provided, pipe output to `server.log`
+2. Spawn an isolated dev-server process session if `--run` is provided, pipe timestamped output to `server.log`, and persist its immutable PID/process-group identity
 3. Wait for the port to respond (polls every 500ms, 30s timeout)
-4. Open headless Chromium
+4. Open the requested URL in a short, collision-safe agent-browser session and persist its daemon identity
 5. Start video recording
-6. Write `.session.json` (active session state) and `metadata.json` (git branch/commit, persists after stop)
+6. Write `.session.json` to the configured/default control directory and `metadata.json` beside the evidence (git branch/commit, persists after stop)
 
 Recording is mandatory. If it fails after 3 retries, the session aborts.
 
@@ -69,18 +69,19 @@ Each `proofshot exec` call:
 
 1. Collects browser console errors and output (point-in-time snapshot)
 2. Stops video recording
-3. Closes the browser
-4. Trims video dead time using ffmpeg (5s buffer before first action, 3s after last). Adjusts all `session-log.json` timestamps by the trim offset.
-5. Scans `server.log` with multi-language regex patterns for errors
-6. Generates `SUMMARY.md` and `viewer.html`
-7. Clears `.session.json`
+3. Closes the exact owned browser session
+4. Stops only the dev-server process session created by this run
+5. Trims video dead time using ffmpeg (5s buffer before first action, 3s after last). Adjusts all `session-log.json` timestamps by the trim offset.
+6. Scans `server.log` with multi-language regex patterns for errors
+7. Generates `SUMMARY.md` and `viewer.html`
+8. Clears `.session.json` (or retains exact browser ownership after `--no-close`)
 
 ## Design principles
 
 **Graceful degradation.** Missing ffmpeg? Video trimming is skipped. Element data capture fails? Overlays are skipped. Browser already closed? Silent catch. Non-critical failures never abort a session.
 
 **Minimal dependencies.** Three production dependencies: `commander`, `chalk`, `detect-port`. agent-browser is an optional peer dependency. Small install, small supply chain.
 
-**Session isolation.** `.session.json` lives in the output directory, not globally. This supports parallel sessions in different projects.
+**Session isolation.** Each project keeps control state in its configured/default output directory. A CLI-only custom evidence path cannot hide the session from a later process, while different projects still run independently.
 
 **ESM-only.** All imports use explicit `.js` extensions for correct resolution after TypeScript compilation.

content/docs/faq.mdx

@@ -28,7 +28,7 @@ The skill file installed by `proofshot install` teaches your agent the three-ste
 Stable handles to interactive elements on a page. When your agent runs `agent-browser snapshot -i`, it gets a list like `@e1: button "Submit"`, `@e2: input "Email"`. These references persist across commands within a session, so the agent can target elements reliably without CSS selectors.
 
 **Can I run multiple sessions at the same time?**
-Yes. Session state (`.session.json`) lives in the output directory, not globally. Different projects with different output directories can run sessions concurrently.
+Yes. Session state (`.session.json`) lives in each project's configured/default output directory, not globally. Different projects can run concurrently. A one-run `--output` override moves evidence without changing where that project finds active control state.
 
 **What languages does error detection support?**
 JavaScript/Node.js, Python, Ruby/Rails, Go, Java/Kotlin, Rust, PHP, C#/.NET, Elixir/Phoenix, plus generic patterns for `FATAL`, `CRITICAL`, and segfaults. See [How to add error patterns](/docs/guides/add-error-pattern) to extend support.
@@ -39,7 +39,10 @@ When ffmpeg is available, `proofshot stop` cuts dead time from the video — kee
 ## Troubleshooting
 
 **"No active session" when running exec or stop**
-You need to run `proofshot start` first. Each session writes `.session.json` — if it's missing, there's no active session to operate on.
+You need to run `proofshot start` before `exec`. `stop` is idempotent, so it succeeds without changing artifacts when the session is already stopped.
+
+**Chrome is installed, but an isolated HOME cannot find it**
+ProofShot checks system paths and executable-only browser caches under the real account home without reusing a browser profile or storage. You can also pass one exact path with `proofshot start --browser-executable /absolute/path/to/chrome`. If nothing is runnable, run the `agent-browser install` command printed by `proofshot start`.
 
 **Server errors aren't being detected**
 Server log capture only works when ProofShot starts the server itself via `--run`. If your server was already running on the port, ProofShot skips spawning and gets no logs.

content/docs/reference/cli.mdx

@@ -48,23 +48,26 @@ proofshot start [options]
 | `--description <text>` | Description of what you're verifying (appears in reports) | — |
 | `--headed` | Show the browser window (visible Chromium) | `false` |
 | `--output <dir>` | Custom output directory for artifacts | `./proofshot-artifacts` |
+| `--browser-executable <path>` | Use an exact Chrome/Chromium executable | auto-discovered |
+| `--force` | Clean up and replace an active session | `false` |
 
 **Examples:**
 
 ```sh
 proofshot start                                            # Server already running on port 3000
 proofshot start --run "npm run dev" --port 3000             # Start server, capture logs
 proofshot start --url http://localhost:3000/login            # Open a specific page
+proofshot start --browser-executable /path/to/chrome          # Use an exact browser binary
 proofshot start --description "Verify checkout flow"        # Add description to report
 proofshot start --headed                                    # Show the browser window
 ```
 
 **What happens:**
-1. If `--run` is provided: starts the dev server, pipes output to `server.log`, waits for the port
+1. If `--run` is provided: fails without killing anything when the port is occupied; otherwise starts an owned dev-server process session, pipes timestamped output to `server.log`, and waits for the port
 2. Opens headless Chromium via agent-browser
 3. Navigates to `--url` (or `http://localhost:<port>`)
 4. Starts video recording (retries up to 3 times)
-5. Writes `.session.json` and `metadata.json` (git branch and commit SHA)
+5. Writes control `.session.json` to the configured/default output and durable `metadata.json` beside the evidence. A CLI-only `--output` changes evidence placement, not control discovery.
 
 ---
 
@@ -83,11 +86,14 @@ proofshot stop [options]
 **What happens:**
 1. Collects console errors and output from the browser
 2. Stops video recording
-3. Closes the browser (unless `--no-close`)
-4. Trims video dead time (requires ffmpeg): 5s buffer before first action, 3s after last
-5. Scans `server.log` for errors across 10+ languages
-6. Generates `SUMMARY.md` and `viewer.html`
-7. Clears `.session.json`
+3. Closes the exact owned browser session (unless `--no-close`)
+4. Stops only the dev-server process session created by this ProofShot start
+5. Trims video dead time (requires ffmpeg): 5s buffer before first action, 3s after last
+6. Scans `server.log` for errors across 10+ languages
+7. Generates `SUMMARY.md` and `viewer.html`
+8. Clears `.session.json`, or retains it after `--no-close` until a later plain `stop` closes that exact browser
+
+Repeated `stop` calls are successful no-ops. If bundling fails, control state remains retryable; a later `stop` reuses already-collected artifacts instead of widening process cleanup.
 
 ---
 
@@ -187,4 +193,4 @@ Remove the entire artifacts directory.
 proofshot clean
 ```
 
-Deletes `./proofshot-artifacts/` (or the configured output directory). No flags.
+Deletes `./proofshot-artifacts/` (or the configured output directory). No flags. If active or retained control state exists, `clean` refuses and asks you to run `proofshot stop` first so exact process ownership metadata is not discarded.

proofshot-spec.md

@@ -303,6 +303,8 @@ proofshot clean
 # Removes ./proofshot-artifacts/
 ```
 
+If `.session.json` exists, `clean` refuses and directs the user to `proofshot stop`; it never discards exact process ownership metadata or performs implicit broad cleanup.
+
 ### `proofshot pr`
 
 Format artifacts for inclusion in a PR description.
@@ -362,22 +364,26 @@ async function ensureDevServer(config, errorLogPath: string) {
 
 ## 6. Session State
 
-ProofShot uses a `.session.json` file in the output directory to track the active session:
+ProofShot uses a `.session.json` file in the configured/default output directory to track the active session. A CLI-only `--output` override moves evidence but not this discoverable control file:
 
 ```json
 {
   "startedAt": "2026-02-25T14:32:00.000Z",
   "description": "Login form: fill credentials, submit, verify redirect",
-  "outputDir": "./proofshot-artifacts",
-  "videoPath": "./proofshot-artifacts/session-2026-02-25.webm",
-  "serverErrorLog": "./proofshot-artifacts/server-errors.log",
+  "outputDir": "/audit/custom-evidence",
+  "sessionDir": "/audit/custom-evidence/2026-02-25_login-form",
+  "sessionName": "ps-2026-02-a1b2c3d4e5f6",
+  "targetUrl": "http://localhost:5173/login",
+  "agentBrowserSocketDir": "/run/user/1000/proofshot/agent-browser",
+  "videoPath": "/audit/custom-evidence/2026-02-25_login-form/session.webm",
+  "serverErrorLog": "/audit/custom-evidence/2026-02-25_login-form/server.log",
   "port": 5173,
-  "framework": "Vite",
-  "pid": 12345
+  "serverProcess": { "pid": 12345, "processGroupId": 12345, "sessionId": 12345, "startTime": "987654" },
+  "browserProcess": { "pid": 12367, "processGroupId": 12367, "sessionId": 12367, "startTime": "987699" }
 }
 ```
 
-`proofshot stop` reads this file to know where to find artifacts and what metadata to include in the summary.
+`proofshot exec` and `proofshot stop` read this file from separate CLI processes. Cleanup verifies the immutable identities and signals only process groups inside the recorded process sessions; it never kills by command name or occupied port.
 
 ---
 
@@ -568,8 +574,8 @@ function ab(command: string): string {
 proofshot start:
   1. Load config
   2. Ensure output dir exists
-  3. Start dev server (if needed), piping stderr to server-errors.log
-  4. Open browser via agent-browser
+  3. Fail actionably if the requested port is occupied; otherwise start an owned dev-server process session and timestamp output in server.log
+  4. Open the requested URL in a short, collision-safe agent-browser session and persist its daemon identity
   5. Start recording via agent-browser
   6. Write .session.json with metadata
   7. Print instructions for the agent
@@ -581,12 +587,13 @@ proofshot stop:
   2. Collect console errors via agent-browser errors
   3. Collect console output via agent-browser console
   4. Stop recording via agent-browser record stop
-  5. Close browser via agent-browser close
-  6. Read server-errors.log
-  7. List all screenshots in output dir
-  8. Generate SUMMARY.md
-  9. Delete .session.json
-  10. Print summary to stdout
+  5. Close the exact browser session via agent-browser close
+  6. Stop only the owned dev-server process session
+  7. Read server.log
+  8. List all screenshots in the evidence session dir
+  9. Generate SUMMARY.md and viewer.html
+  10. Delete .session.json (or retain exact browser ownership after --no-close)
+  11. Print summary to stdout
 ```
 
 ### Server Error Capture

skills/claude/SKILL.md

@@ -27,7 +27,7 @@ Use ProofShot after:
 proofshot start --run "your-dev-command" --port PORT --description "what you are about to verify"
 ```
 
-This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically.
+This opens a browser and begins recording. If the port is already in use, ProofShot leaves that unowned listener alone and asks you to choose another port or stop it explicitly.
 
 **Always use `--run`** to let proofshot start and capture your dev server output (server logs appear in the proof report).
 Only omit `--run` if the server was explicitly started by the user or another process — without it, no server logs are captured.

skills/codex/SKILL.md

@@ -26,7 +26,7 @@ Use ProofShot after:
 proofshot start --run "your-dev-command" --port PORT --description "what you are about to verify"
 ```
 
-This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically.
+This opens a browser and begins recording. If the port is already in use, ProofShot leaves that unowned listener alone and asks you to choose another port or stop it explicitly.
 
 **Always use `--run`** to let proofshot start and capture your dev server output (server logs appear in the proof report).
 Only omit `--run` if the server was explicitly started by the user or another process — without it, no server logs are captured.

skills/cursor/proofshot.mdc

@@ -9,7 +9,7 @@ After modifying UI files, visually verify changes with this workflow:
 
 1. Start session: `proofshot start --run "your-dev-command" --port PORT --description "what you are verifying"`
    Always use --run so proofshot captures server logs. Only omit --run if the server was started by the user.
-   If the port is in use, proofshot kills the existing process. Add --force if a stale session blocks startup.
+   If the port is in use, ProofShot leaves that unowned listener alone; choose another port or stop it explicitly. Add --force only if a stale ProofShot session blocks startup.
 2. Drive browser: Use `proofshot exec` commands to navigate, click, fill forms, and take screenshots
 3. Stop session: `proofshot stop` to bundle video + screenshots + error report
 

skills/generic/PROOFSHOT.md

@@ -6,7 +6,7 @@ After building or modifying UI features, verify with this workflow:
 
 1. Start: `proofshot start --run "your-dev-command" --port PORT --description "what you are verifying"`
    Always use --run so proofshot captures server logs. Only omit --run if the server was started by the user.
-   If the port is in use, proofshot kills the existing process. Add --force if a stale session blocks startup.
+   If the port is in use, ProofShot leaves that unowned listener alone; choose another port or stop it explicitly. Add --force only if a stale ProofShot session blocks startup.
 2. Test: Use `proofshot exec` to navigate, click, fill forms, take screenshots
 3. Stop: `proofshot stop` — bundles video, screenshots, and error report
 

skills/opencode/SKILL.md

@@ -27,7 +27,7 @@ Use ProofShot after:
 proofshot start --run "your-dev-command" --port PORT --description "what you are about to verify"
 ```
 
-This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically.
+This opens a browser and begins recording. If the port is already in use, ProofShot leaves that unowned listener alone and asks you to choose another port or stop it explicitly.
 
 **Always use `--run`** to let proofshot start and capture your dev server output (server logs appear in the proof report).
 Only omit `--run` if the server was explicitly started by the user or another process - without it, no server logs are captured.