Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: fix inaccuracies across guides, references, and architecture pages

Luigi Agosti7b8cab65298b
diff --git a/dev b/dev
index 2f0258aa..e7ad7187 100755
--- a/dev
+++ b/dev
@@ -47,6 +47,7 @@ COMMANDS=(
" agent-browser:πŸ“Š:Run agent-browser benchmark via Anthropic Messages API"
" browserbench:πŸ“Š:Run BrowserBench CSV tasks through PinchTab"
"doctor:🩺:Setup dev environment"
+ "install:πŸ“¦:Build & install to ~/.local/bin (override with PINCHTAB_INSTALL_DIR)"
"check go:πŸ§ͺ:Go only"
"check dashboard:πŸ§ͺ:Dashboard only"
"check npm:πŸ§ͺ:npm package only"
@@ -283,6 +284,7 @@ run_command() {
"dev") exec bash scripts/dev.sh ;;
"dashboard") exec bash scripts/dev-dashboard.sh ;;
"build") exec bash scripts/build.sh ;;
+ "install") exec bash scripts/install.sh ;;
"binary") exec bash scripts/binary.sh ;;
"binary all"|"binaries") exec bash scripts/binary.sh all ;;
"all")
diff --git a/docs/architecture/find.md b/docs/architecture/find.md
index 62775699..52bb6d8e 100644
--- a/docs/architecture/find.md
+++ b/docs/architecture/find.md
@@ -47,7 +47,7 @@ Each accessibility node is converted into a descriptor with:
- `documentIdx`
- positional hints: `depth`, `siblingIndex`, `siblingCount`, `labelledBy`
-PinchTab owns extraction of DOM-only metadata from backend node ids. The `semantic` package owns structured locator parsing and matching for `role:`, `text:`, `label:`, `placeholder:`, `alt:`, `title:`, `testid:`, `first:`, `last:`, and `nth:` forms.
+PinchTab owns extraction of DOM-only metadata from backend node ids. The structured locator parsing and matching for `role:`, `text:`, `label:`, `placeholder:`, `alt:`, `title:`, `testid:`, `first:`, `last:`, and `nth:` forms is delegated to the external `github.com/pinchtab/semantic` Go module (a sibling package, not part of this repo). The in-repo `internal/autosolver/semantic/adapter.go` is just a thin adapter that wires the module into the autosolver.
CSS, XPath, refs, frame scoping, converting a matched ref back to a backend node, and the existing DOM-backed action `text:` selector remain PinchTab responsibilities.
@@ -108,9 +108,9 @@ After a successful match, PinchTab records:
This allows recovery logic to attempt a semantic re-match if a later action fails because the old ref became stale after a page update.
-## Orchestrator Routing
+## Routing
-The orchestrator exposes `POST /tabs/{id}/find` and proxies it to the correct running instance. The actual matching implementation remains in the shared handler layer.
+`POST /tabs/{id}/find` (and the active-tab shorthand `POST /find`) is registered by the shared handler layer in `internal/handlers/handlers.go`. The orchestrator proxies these requests to the correct running instance via its routing layer; it does not own the route itself.
## Design Constraints
diff --git a/docs/architecture/instance-charts.md b/docs/architecture/instance-charts.md
index 82778675..d72ec5ee 100644
--- a/docs/architecture/instance-charts.md
+++ b/docs/architecture/instance-charts.md
@@ -95,12 +95,16 @@ The main instance fields surfaced by the current API are:
- `profileId`
- `profileName`
- `port`
+- `url`
+- `mode` (`headless` or `headed`)
- `headless`
- `status`
- `startTime`
- `error`
- `attached`
+- `attachType` (`cdp` or `bridge`, for attached instances)
- `cdpUrl`
+- `securityPolicy`
Useful interpretation:
diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.md
index d530fe1a..469780d9 100644
--- a/docs/architecture/mcp.md
+++ b/docs/architecture/mcp.md
@@ -35,7 +35,7 @@ pinchtab mcp
β”œβ”€β”€ reads PINCHTAB_TOKEN (env or config)
β”‚
β”œβ”€β”€ creates internal/mcp.Client (HTTP client with 120 s timeout)
- β”œβ”€β”€ registers 34 MCP tools via mcp-go SDK
+ β”œβ”€β”€ registers 38 MCP tools via mcp-go SDK
└── calls server.ServeStdio() (blocking read loop)
```
@@ -45,10 +45,18 @@ The process exits when stdin is closed by the client.
```
internal/mcp/
-β”œβ”€β”€ server.go # NewServer() wires tools β†’ handlers; Serve() starts stdio
-β”œβ”€β”€ tools.go # allTools() β€” JSON-schema tool definitions for all 34 tools
-β”œβ”€β”€ handlers.go # handlerMap() β€” one handler closure per tool
-└── client.go # Client β€” thin HTTP wrapper for PinchTab REST API
+β”œβ”€β”€ server.go # NewServer() wires tools β†’ handlers; Serve() starts stdio
+β”œβ”€β”€ tools.go # allTools() β€” JSON-schema tool definitions for all 38 tools
+β”œβ”€β”€ handlers.go # handlerMap() β€” registers each tool's handler
+β”œβ”€β”€ handlers_helpers.go # shared argument parsing / response helpers
+β”œβ”€β”€ handlers_navigation.go # navigate, snapshot, frame, screenshot, get_text
+β”œβ”€β”€ handlers_interaction.go # click, type, press, hover, focus, select, scroll(_into_view), fill
+β”œβ”€β”€ handlers_content.go # eval, pdf, find
+β”œβ”€β”€ handlers_tabs.go # list_tabs, close_tab, health, cookies, connect_profile
+β”œβ”€β”€ handlers_wait.go # wait, wait_for_selector/text/url/load/function
+β”œβ”€β”€ handlers_network.go # network, network_detail/clear/route/unroute
+β”œβ”€β”€ handlers_dialog.go # dialog
+└── client.go # Client β€” thin HTTP wrapper for PinchTab REST API
cmd/pinchtab/
└── cmd_mcp.go # runMCP() β€” reads config, calls mcp.Serve()
@@ -88,19 +96,20 @@ The context passed from the MCP SDK carries the client's deadline, so long-runni
- a 120-second timeout (covers page loads and PDF exports)
- optional `Authorization: Bearer <token>` header injection
- a 10 MB response body limit
-- URL validation in `handleNavigate` (must start with `http://` or `https://`)
+
+URL validation lives in `handleNavigate` (`handlers_navigation.go`), which calls `internal/urls.Sanitize` to normalize bare hostnames to `https://` and reject non-HTTP(S) schemes (`file://`, `javascript:`, etc.).
## Tool Categories
| Category | Count | REST Endpoints Used |
|----------|-------|---------------------|
-| Navigation | 4 | `/navigate`, `/snapshot`, `/screenshot`, `/text` |
-| Interaction | 8 | `/action` |
+| Navigation | 5 | `/navigate`, `/snapshot`, `/frame`, `/screenshot`, `/text` |
+| Interaction | 9 | `/action` |
| Keyboard | 4 | `/action` |
| Content | 3 | `/evaluate`, `/pdf`, `/find` |
| Tab Management | 5 | `/tabs`, `/health`, `/cookies`, `/profiles/{id}/instance` |
| Wait utilities | 6 | `/wait` |
-| Network | 3 | `/network` |
+| Network | 5 | `/network`, `/network/route` (POST/DELETE) |
| Dialog | 1 | `/dialog` |
## Security Considerations
diff --git a/docs/benchmark.md b/docs/benchmark.md
index 28b5ed5a..c684e8fc 100644
--- a/docs/benchmark.md
+++ b/docs/benchmark.md
@@ -81,22 +81,25 @@ Two structural differences drive the gap:
## Reproducing
```bash
-cd tests/benchmark
-docker compose up -d --build
-./scripts/run-optimization.sh
+# From the repo root. The benchmark runs in Docker and the entry points
+# live in tests/tools/, not tests/benchmark/.
-# Baseline (deterministic, ~30s)
-./scripts/baseline.sh
+# Deterministic baseline (no API key required)
+./dev opt baseline
# PinchTab and agent-browser lanes (Anthropic API key required)
-ANTHROPIC_API_KEY=... ./scripts/run-api-benchmark.ts --lane pinchtab --groups 0,1
-ANTHROPIC_API_KEY=... ./scripts/run-api-benchmark.ts --lane agent-browser --groups 0,1
+ANTHROPIC_API_KEY=... ./dev bench pinchtab --groups 0,1
+ANTHROPIC_API_KEY=... ./dev bench agent-browser --groups 0,1
-# Inspect usage
-jq '.run_usage' results/pinchtab_benchmark_*.json
-jq '.run_usage' results/agent_browser_benchmark_*.json
+# Inspect usage (results land under tests/benchmark/results/)
+jq '.run_usage' tests/benchmark/results/pinchtab_benchmark_*.json
+jq '.run_usage' tests/benchmark/results/agent_browser_benchmark_*.json
```
+The shell entry points and Docker compose files live under
+`tests/tools/scripts/` and `tests/tools/docker-compose*.yml`; the agent
+loop is the Go binary at `tests/tools/runner/`.
+
See the [benchmark deep dive](./deep-dive/benchmark.md) for per-run
tables, raw transcripts, token breakdowns, variance discussion, and
the full list of measurement caveats.
diff --git a/docs/commands.md b/docs/commands.md
index a316abd6..b99e6e24 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -163,11 +163,12 @@ pinchtab network # List captured network requests
pinchtab network <requestId> # Show one request in detail
pinchtab network --stream # Stream network entries
pinchtab network --clear # Clear captured network data
-pinchtab network-export # Export as HAR 1.2 (saved to exports/)
-pinchtab network-export -o session.har # Export to specific file
-pinchtab network-export --format ndjson # Export as NDJSON (one entry per line)
-pinchtab network-export --body # Include response bodies
-pinchtab network-export --stream -o l.har # Live capture to file while browsing
+# HAR / NDJSON export is available over HTTP (no dedicated CLI subcommand):
+# curl http://127.0.0.1:9867/network/export β†’ HAR 1.2 archive
+# curl http://127.0.0.1:9867/network/export?format=ndjson β†’ NDJSON (one entry per line)
+# curl http://127.0.0.1:9867/network/export?body=1 β†’ include response bodies
+# curl http://127.0.0.1:9867/network/export/stream β†’ live HAR stream
+# Per-tab variants live under /tabs/{id}/network/export[/stream].
pinchtab dialog accept [text] # Accept alert/confirm/prompt
pinchtab dialog dismiss # Dismiss dialog
pinchtab console # Show console logs
@@ -302,7 +303,6 @@ Commands with `--tab` currently include:
- `keyup`
- `scrollintoview`
- `network`
-- `network-export`
- `wait`
- `dialog accept`
- `dialog dismiss`
diff --git a/docs/deep-dive/benchmark.md b/docs/deep-dive/benchmark.md
index 8dfbb1c0..af9fc76f 100644
--- a/docs/deep-dive/benchmark.md
+++ b/docs/deep-dive/benchmark.md
@@ -63,7 +63,7 @@ For each step:
1. The runner sends the task description plus the accumulated transcript to
Anthropic.
2. The model emits a shell command (one of `./scripts/pt ...`, `./scripts/ab
- ...`, or `./scripts/runner step-end ...`).
+ ...`, or `./scripts/runner step-end ...`, all under `tests/tools/scripts/`).
3. The runner executes the command inside the lane's container and appends
the result to the transcript.
4. Once the model answers, `./scripts/runner step-end` records the answer and
@@ -107,7 +107,7 @@ deliberate, to keep the comparison fair:
agent-browser --full`. In the benchmark the runner extracts only the
header plus `references/commands.md` and `references/snapshot-refs.md`
and drops the rest (see
- `tests/tools/runner/prompt.go:DownloadAgentBrowserSkill`).
+ `tests/tools/runner/internal/bench/prompt.go:DownloadAgentBrowserSkill`).
In a 10-step test, the full reference bundles would dominate `cache_read`
tokens on the lane that happens to ship more reference content. Charging
@@ -347,8 +347,9 @@ dynamic-content interactions β€” make up most of Group 1 and all of
Groups 2–5.
A stronger future comparison would co-design the task set with both teams,
-or run a much larger task set (the full 39-group benchmark lives in
-`tests/benchmark/`) so idiosyncratic per-task biases average out.
+or run a much larger task set (the in-repo benchmark groups live in
+`tests/benchmark/` β€” `group-00.md` through `group-05.md` today, with room to
+grow) so idiosyncratic per-task biases average out.
### 2. Partial-skill configuration
@@ -482,7 +483,7 @@ Machine-specific paths have been replaced with `<repo>` for portability.
## Future Work
- Fix the two measurement bugs (pinchtab tool-calls, cache-create drop) in
- `tests/tools/runner/recordstep.go`
+ `tests/tools/runner/internal/bench/recordstep.go`
- 10+ runs per lane at extended scope to tighten the confidence interval
and characterise the agent-browser outlier rate
- Model comparison (Haiku vs Sonnet vs Opus)
diff --git a/docs/deep-dive/lite-engin-prototype.md b/docs/deep-dive/lite-engin-prototype.md
index b5674dbc..542e6344 100644
--- a/docs/deep-dive/lite-engin-prototype.md
+++ b/docs/deep-dive/lite-engin-prototype.md
@@ -82,12 +82,13 @@ No handler, config, or CMD changes needed.
### Modified Files (8)
| File | Change |
|------|--------|
-| `internal/config/config.go` | Added `Engine` field to RuntimeConfig + ServerConfig |
+| `internal/config/config_types.go` | Added `Engine` field to RuntimeConfig + ServerConfig |
| `internal/handlers/handlers.go` | Added `Router *engine.Router` field, `useLite()` helper |
| `internal/handlers/navigation.go` | Lite fast path before ensureChrome |
| `internal/handlers/snapshot.go` | Lite fast path with SnapshotNode β†’ A11yNode conversion |
| `internal/handlers/text.go` | Lite fast path returning plain text |
-| `cmd/pinchtab/cmd_bridge.go` | Engine router wiring based on config mode |
+| `cmd/pinchtab/cmd_bridge.go` | Resolves engine mode (`resolveBridgeEngine`) from CLI flag and config |
+| `internal/server/bridge.go` | Constructs the `engine.Router` (`engine.NewRouter(mode, lite)`) and wires it into the handler |
| `go.mod` | Added gost-dom/browser v0.11.0, gost-dom/css v0.1.0 |
| `go.sum` | Updated checksums |
diff --git a/docs/endpoints.md b/docs/endpoints.md
index da2b61b8..e4941d00 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -110,9 +110,9 @@ Notes:
- `POST /tabs/{id}/handoff` marks the tab as `paused_handoff` and records a reason
- `GET /tabs/{id}/handoff` returns the current handoff state, or `active` when no handoff is set
- `POST /tabs/{id}/resume` clears the handoff state and can carry resume metadata for the caller
-- current behavior is advisory only: handoff state is not yet a hard block on subsequent automation requests
-- treat the current implementation as temporary coordination state, not as a security boundary
-- there is currently no dedicated CLI wrapper for handoff or resume; use the HTTP API
+- a paused-handoff tab is a hard block on the action-execution routes (`/action`, `/actions`, `/macro`): they return `409 tab_paused_handoff` until `/resume` clears the state
+- treat the handoff record as coordination state, not as a security boundary β€” non-action endpoints (snapshots, screenshots, network logs, evals subject to their own gates) remain reachable
+- CLI wrappers exist: `pinchtab handoff`, `pinchtab resume`, `pinchtab handoff-status`, plus the `pinchtab tab handoff|resume|handoff-status` aliases
## Tab Locking
@@ -541,7 +541,7 @@ POST /instances/{id}/tab
Notes:
- `/instances/start` and `/instances/launch` use `mode`, not `headless`
-- `/instances/launch` is a compatibility alias over `/instances/start`
+- `/instances/launch` is a sibling endpoint of `/instances/start` (separate handler `handleLaunchByName`), kept for the launch-by-profile workflow; `name` on the body is no longer supported, profiles must already exist
- instance responses include both `mode` and `headless`
- instance start surfaces accept `securityPolicy.allowedDomains` for additive instance-scoped IDPI/domain allowlist overrides
- create profiles explicitly with `POST /profiles`; `name` is no longer supported on `/instances/launch`
diff --git a/docs/get-started.md b/docs/get-started.md
index 900b3d8c..0958021d 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -52,7 +52,7 @@ go build -o pinchtab ./cmd/pinchtab
./pinchtab --version
```
-**[Full build guide ->](architecture/building.md)**
+**[Full build & contribution guide ->](guides/contributing.md)**
## Platform Support
diff --git a/docs/guides/agent-identity.md b/docs/guides/agent-identity.md
index bb818b2b..a1698d65 100644
--- a/docs/guides/agent-identity.md
+++ b/docs/guides/agent-identity.md
@@ -52,7 +52,7 @@ Sessions are the full identity solution. Each session is a revocable, server-man
- **Labels** β€” human-readable names like "research task" or "daily scrape"
- **Activity grouping** β€” all requests within a session are grouped in the dashboard
-- **Idle timeout** β€” sessions expire after 12 hours of inactivity (configurable)
+- **Idle timeout** β€” sessions expire after 30 minutes of inactivity (configurable)
- **Max lifetime** β€” hard expiry after 24 hours (configurable)
- **Revocation** β€” kill a session without rotating the server token
@@ -140,9 +140,9 @@ curl -X POST http://localhost:9867/sessions/ses_e6ac8132fe7e7016/revoke \
| Setting | Default | Description |
|---------|---------|-------------|
-| `sessions.agent.enabled` | `false` | Enable agent sessions |
+| `sessions.agent.enabled` | `true` | Enable agent sessions |
| `sessions.agent.mode` | `preferred` | Auth mode: `off`, `preferred`, `required` |
-| `sessions.agent.idleTimeoutSec` | `43200` (12h) | Session expires after this many seconds of inactivity |
+| `sessions.agent.idleTimeoutSec` | `1800` (30m) | Session expires after this many seconds of inactivity |
| `sessions.agent.maxLifetimeSec` | `86400` (24h) | Hard session expiry |
If a session record carries explicit grants, those grants narrow which endpoint groups the session may call. If a session has no explicit grants, it can use the normal non-admin automation API by default, while dashboard/admin routes remain blocked. That default is meant for trusted automation only.
diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md
index 2f9d74e4..561b5872 100644
--- a/docs/guides/contributing.md
+++ b/docs/guides/contributing.md
@@ -193,7 +193,7 @@ ls -la pinchtab
### Start (Headless)
```bash
-./pinchtab
+./pinchtab server
```
**Expected output:**
@@ -205,18 +205,23 @@ auth disabled (set PINCHTAB_TOKEN to enable)
### Start (Headed Mode)
```bash
-BRIDGE_HEADLESS=false ./pinchtab
+./pinchtab server --headed
```
-Opens Chrome in the foreground.
+Opens Chrome in the foreground for the default instance.
### Background
```bash
-nohup ./pinchtab > pinchtab.log 2>&1 &
-tail -f pinchtab.log # Watch logs
+./pinchtab server --background # spawns detached, prints JSON with pid/url/token
+./pinchtab server -b # short form
```
+The `--background` flag forks a properly detached server process and returns
+`{"pid": ..., "url": ..., "token": ...}` on stdout, so scripts can capture the
+URL/token without log scraping. For a longer-lived install, use
+`pinchtab daemon install` instead.
+
---
## Part 4: Quick Test
@@ -453,7 +458,7 @@ This will tell you exactly what's missing or misconfigured.
**"Port 9867 already in use"**
- Check: `lsof -i :9867`
-- Stop other instance or use different port: `BRIDGE_PORT=9868 ./pinchtab`
+- Stop other instance or change the port via config: `pinchtab config set server.port 9868`
**Build fails**
1. Verify dependencies: `go mod download`
diff --git a/docs/guides/docker.md b/docs/guides/docker.md
index 94e94bb2..4835314f 100644
--- a/docs/guides/docker.md
+++ b/docs/guides/docker.md
@@ -186,34 +186,26 @@ Example: `docker run -p 127.0.0.1:9867:9867` keeps PinchTab reachable only from
### Docker Secrets (Sensitive Configuration)
-For production deployments, use Docker secrets instead of env vars for `PINCHTAB_TOKEN`:
+The image only consumes `PINCHTAB_TOKEN` from the environment β€” it does not read a `PINCHTAB_TOKEN_FILE` indirection. To use Docker secrets, source the secret file in your own entrypoint or wrapper before running the image:
```bash
# Create a secret
echo "your-secret-token" | docker secret create pinchtab_token -
-# Use it in docker-compose.yml
+# Use it in docker-compose.yml β€” read the secret file and export PINCHTAB_TOKEN
services:
pinchtab:
image: pinchtab/pinchtab
secrets:
- pinchtab_token
- environment:
- PINCHTAB_TOKEN_FILE: /run/secrets/pinchtab_token
- # ... rest of config
+ entrypoint: ["/bin/sh", "-c"]
+ command:
+ - |
+ export PINCHTAB_TOKEN="$(cat /run/secrets/pinchtab_token)"
+ exec /usr/local/bin/docker-entrypoint.sh pinchtab
```
-Or with `docker run`:
-
-```bash
-docker run -d \
- --name pinchtab \
- --secret pinchtab_token \
- -e PINCHTAB_TOKEN_FILE=/run/secrets/pinchtab_token \
- pinchtab/pinchtab
-```
-
-Secrets are mounted read-only and never appear in `docker ps` or logs.
+Secrets mounted at `/run/secrets/...` are read-only and never appear in `docker ps` or logs.
## Compose
diff --git a/docs/guides/mcp-agents.md b/docs/guides/mcp-agents.md
index 52d7fec0..f4e00d55 100644
--- a/docs/guides/mcp-agents.md
+++ b/docs/guides/mcp-agents.md
@@ -12,7 +12,7 @@ This guide walks through setting up PinchTab as an MCP tool server for AI coding
## What is MCP?
-The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI models to external tools. PinchTab implements an MCP server that exposes 34 browser-control tools β€” navigation, interaction, screenshot, PDF export, waits, network inspection, and more β€” over a simple stdio interface that every major AI client supports.
+The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI models to external tools. PinchTab implements an MCP server that exposes 38 browser-control tools β€” navigation, interaction, screenshot, PDF export, waits, network inspection, and more β€” over a simple stdio interface that every major AI client supports.
## Prerequisites
diff --git a/docs/implementations/chrome-files.md b/docs/implementations/chrome-files.md
index f98c1be7..3126382a 100644
--- a/docs/implementations/chrome-files.md
+++ b/docs/implementations/chrome-files.md
@@ -49,4 +49,4 @@ If you see the error `"The profile appears to be in use by another Chromium proc
2. **Stale Locks**: If no process is active, PinchTab will attempt to automatically clear stale `SingletonLock` files on the next startup.
3. **Manual Fix**: In rare cases, you may need to manually remove the `SingletonLock` file from the profile directory.
-For more details on how PinchTab recovers from crashes, see [Chrome Profile Lock Recovery](docs/implementations/chrome-profile-lock-recovery.md).
+For more details on how PinchTab recovers from crashes, see [Chrome Profile Lock Recovery](./chrome-profile-lock-recovery.md).
diff --git a/docs/implementations/chrome-profile-lock-recovery.md b/docs/implementations/chrome-profile-lock-recovery.md
index a12cc313..63c5fa19 100644
--- a/docs/implementations/chrome-profile-lock-recovery.md
+++ b/docs/implementations/chrome-profile-lock-recovery.md
@@ -12,7 +12,7 @@ The recovery process follows a multi-layered approach to distinguish between a t
### 1. Detection
-During initialization in `internal/bridge/init.go`, if Chrome fails to start, PinchTab checks the error message for signatures of a profile lock:
+During initialization in `internal/bridge/runtime/init.go` (with bridge wiring in `internal/bridge/bridge_lifecycle.go`), if Chrome fails to start, PinchTab checks the error message for signatures of a profile lock:
- `The profile appears to be in use by another Chromium process`
- `The profile appears to be in use by another Chrome process`
- `process_singleton_posix.cc` (indicating a failure in the ProcessSingleton logic)
@@ -31,14 +31,14 @@ To safely clear a lock, PinchTab must be certain no *other* active PinchTab inst
If a headless PinchTab instance cannot acquire a lock on the requested profile directory (because another PinchTab instance is genuinely using it), it automatically falls back to creating a unique temporary profile directory. This allows multiple headless bridges to run concurrently even if they all default to the same profile path, while still preserving isolation and safety.
-### 4. Stale Process Termination
+### 4a. Stale Process Termination
Even if the previous PinchTab instance is dead, orphaned Chrome processes might still be holding the profile lock.
- **Process Listing**: PinchTab scans the system process list for any processes launched with the same `--user-data-dir`.
- **Aggressive Cleanup**: If the `pinchtab.pid` check confirms no active owner, PinchTab sends `SIGKILL` to any orphaned Chrome processes associated with that profile. This is necessary because Chrome's internal "singleton" logic can be extremely stubborn if it thinks another process is even partially alive.
-### 4. Lock File Removal
+### 4b. Lock File Removal
Once stale processes are terminated, PinchTab removes the following files from the profile directory:
- `SingletonLock`
@@ -55,7 +55,8 @@ The logic is distributed across these components:
- **`internal/bridge/profile_lock.go`**: Core logic for detection, PID lock management (`AcquireProfileLock`), and stale file removal.
- **`internal/bridge/profile_lock_pid_*.go`**: Platform-specific implementations for PID probing and process killing (supports Unix-like systems and Windows).
-- **`internal/bridge/init.go`**: Orchestrates the retry logic within `startChromeWithRecovery`.
+- **`internal/bridge/runtime/init.go`**: Orchestrates the retry logic within `startChromeWithRecovery`.
+- **`internal/bridge/bridge_lifecycle.go`**: Calls `AcquireProfileLock` and `EnsureChrome` during bridge startup.
- **`internal/server/bridge.go`**: Ensures clean shutdown via signal handling to prevent locks from being left behind in the first place.
## Multi-Instance Safety
diff --git a/docs/implementations/index.md b/docs/implementations/index.md
index 7c714246..4c684bab 100644
--- a/docs/implementations/index.md
+++ b/docs/implementations/index.md
@@ -7,5 +7,6 @@ Use these pages when you want lower-level detail than the architecture overview,
- [Lite Engine](./lite-engine.md) β€” Chrome-free DOM capture using Gost-DOM
- [Managed Bridge vs Managed Direct CDP](./managed-bridge-vs-managed-direct-cdp.md)
- [Chrome Profile Lock Recovery](./chrome-profile-lock-recovery.md)
+- [Chrome Files](./chrome-files.md)
- [Parallel Tab Execution](./parallel-tab-execution.md)
- [Docker Local Testing](./docker-local-testing.md)
diff --git a/docs/implementations/lite-engine.md b/docs/implementations/lite-engine.md
index 4fa318ae..601b3946 100644
--- a/docs/implementations/lite-engine.md
+++ b/docs/implementations/lite-engine.md
@@ -211,7 +211,9 @@ CS: 687 ms vs 130 ms).
| `internal/handlers/navigation.go` | `useLite()` fast path, `X-Engine` header |
| `internal/handlers/snapshot.go` | `SnapshotNode β†’ A11yNode` conversion for lite path |
| `internal/handlers/text.go` | Lite text fast path |
-| `cmd/pinchtab/cmd_bridge.go` | Router wiring from `config.Engine` at startup |
+| `cmd/pinchtab/cmd_bridge.go` | Resolves the engine mode string from CLI flag / config (`resolveBridgeEngine`) |
+| `internal/server/bridge.go` | Wires the `engine.Router` (`engine.NewRouter(mode, lite)`) into the handler at startup |
+| `internal/config/config_types.go` | `RuntimeConfig.Engine` / `ServerConfig.Engine` fields |
---
diff --git a/docs/implementations/parallel-tab-execution.md b/docs/implementations/parallel-tab-execution.md
index 83d96013..9efaa6a7 100644
--- a/docs/implementations/parallel-tab-execution.md
+++ b/docs/implementations/parallel-tab-execution.md
@@ -104,10 +104,10 @@ return te.safeRun(ctx, tabID, task) // Execute with panic recovery
| Component | Location | Purpose |
|-----------|----------|---------|
-| `TabExecutor` | `internal/bridge/tab_executor.go` | Core parallel execution engine |
+| `TabExecutor` | `internal/bridge/tabs/tab_executor.go` (re-exported via `internal/bridge/tabs_facade.go`) | Core parallel execution engine |
| `TabManager.Execute()` | `internal/bridge/tab_manager.go` | Integration point for handlers |
| `Bridge.Execute()` | `internal/bridge/bridge.go` | BridgeAPI interface method |
-| `LockManager` | `internal/bridge/lock.go` | Per-tab ownership locks with TTL |
+| `LockManager` | `internal/bridge/tabs/lock.go` (re-exported via `internal/bridge/tabs_facade.go`) | Per-tab ownership locks with TTL |
| `TabEntry` | `internal/bridge/bridge.go` | Per-tab chromedp context + metadata |
### How It Works
@@ -239,18 +239,21 @@ system architecture.
#### What Was Introduced
-**Semantic CDP IDs** β€” Before PR #145, tab identifiers were opaque hashes:
-`tab_abc12345` (12 characters, derived from hashing the Chrome target ID). PR
-#145 replaced this with semantic prefixed IDs: `tab_D25F4C74E1A3...` (40
-characters, with the CDP target ID embedded directly). This zero-state design
-eliminates the need for ID mapping tables and enables cross-process consistencyβ€”
-any process can reconstruct the tab ID from the CDP target ID by simply prefixing
-it.
+**Raw CDP target IDs as tab IDs** β€” Before PR #145, tab identifiers were opaque
+hashes: `tab_abc12345` (12 characters, derived from hashing the Chrome target
+ID). PR #145 replaced the hash with the raw CDP target ID itself, and the
+current implementation is a passthrough β€” runtime tab IDs are exactly the CDP
+target ID with no `tab_` prefix or hashing. This zero-state design eliminates
+the need for ID mapping tables and enables cross-process consistency: any
+process can route to a tab by referring to its CDP target ID directly.
-Key functions introduced:
-- `TabIDFromCDPTarget()` β€” prefixes instead of hashing
-- `StripTabPrefix()` β€” extracts the raw CDP ID from a semantic tab ID
-- `TabHashIDForCDP()` β€” reverse lookup (now trivial: just add prefix)
+Key function (in `internal/ids/ids.go`):
+
+- `Manager.TabIDFromCDPTarget(cdpTargetID)` β€” returns the CDP target ID as-is.
+
+Synthetic hashed IDs (`tab_XXXXXXXX`) are still produced by `Manager.TabID`
+for callers that need a synthetic identifier, but runtime browser tab routing
+uses the raw CDP target ID directly.
**Tab eviction policies** β€” PR #145 introduced configurable eviction when the
maximum tab count (`MaxTabs`) is reached:
@@ -922,7 +925,7 @@ CPU usage remains bounded while I/O parallelism is maximized.
```
goos: windows
goarch: amd64
-pkg: github.com/nicholasgasior/pinchtab/internal/bridge
+pkg: github.com/pinchtab/pinchtab/internal/bridge
cpu: Intel(R) Core(TM) i5-4300U CPU @ 1.90GHz
BenchmarkTabExecutor_SequentialSameTab-4 548190 2140 ns/op 136 B/op 3 allocs/op
@@ -930,7 +933,7 @@ BenchmarkTabExecutor_ParallelDifferentTabs-4 1317826 837.0 ns/op 136 B
BenchmarkTabExecutor_ParallelSameTab-4 1000000 1386 ns/op 136 B/op 3 allocs/op
BenchmarkTabExecutor_WithWork-4 1515068 766.4 ns/op 136 B/op 2 allocs/op
PASS
-ok github.com/nicholasgasior/pinchtab/internal/bridge 10.356s
+ok github.com/pinchtab/pinchtab/internal/bridge 10.356s
```
**Key observations:**
@@ -1112,23 +1115,24 @@ Located in `internal/bridge/tab_executor_test.go`:
- **Rapid create/remove** cycles
- **30 goroutines** targeting the same tab
-### Automated Integration Tests (11 tests)
-
-Located in `tests/manual/test-parallel-execution.ps1`:
-
-| Test | Name | What It Validates |
-|------|------|------------------|
-| 1 | Parallel Search Engines | 3 tabs navigate concurrently, URLs isolated |
-| 2 | Resource Limit Enforcement | 5 tabs with maxParallel=2, queuing works |
-| 3 | Same Tab Sequential Ordering | 3 concurrent snapshots on same tab execute sequentially |
-| 4 | Failure Isolation | Invalid URL in one tab doesn't affect other tabs |
-| 5 | Sequential vs Parallel Timing | Measures wall-clock comparison (see Performance Comparison) |
-| 6 | Invalid Tab ID Handling | Non-existent, fake, and closed tab IDs rejected |
-| 7 | Rapid Tab Open/Close Stability | 10 create-navigate-snapshot-close cycles |
-| 8 | Concurrent Snapshots Cross-Tab | 3 simultaneous snapshots, no data leakage |
-| 9 | Request Timeout Handling | Short timeout + tab usability after timeout |
-| 10 | Same Tab State Overwrite | 3 sequential navigations on one tab, each overwrites |
-| 11 | Navigate + Snapshot Race | Concurrent navigate(TabA) + snapshot(TabB) |
+### Integration Coverage
+
+End-to-end coverage of the parallel execution model lives in the bridge package
+tests under `internal/bridge/` (executed with `go test ./internal/bridge/...`)
+and in the manual smoke harnesses under `tests/manual/`. The earlier
+PowerShell-based integration suite has been retired in favour of the Go
+test suite, which exercises the same scenarios:
+
+| Scenario | What It Validates |
+|----------|-------------------|
+| Parallel different tabs | Cross-tab concurrency, URLs isolated |
+| Resource limit enforcement | maxParallel cap and queuing behaviour |
+| Same-tab sequential ordering | Per-tab mutex serializes calls |
+| Failure isolation | A failing/panicking tab does not affect others |
+| Sequential vs parallel timing | Wall-clock comparison (see Performance Comparison) |
+| Rapid tab open/close stability | No mutex/goroutine leaks across cycles |
+| Context timeouts under load | Saturated semaphore returns deadline-exceeded |
+| RemoveTab during active execution | RemoveTab waits for in-flight work to drain |
### Benchmarks
@@ -1159,7 +1163,6 @@ go test -v -count=1 ./internal/bridge/
# 3. Race detector β€” zero data races
go test -race -count=1 ./internal/bridge/
-# 4. Integration tests β€” all 11 pass (26 assertions)
-# Requires a running PinchTab instance
-.\tests\manual\test-parallel-execution.ps1 -Port 9867
+# 4. Manual smoke harnesses
+ls tests/manual/ # autosolver-check.sh, autosolver-realworld.sh, openclaw-plugin-smoke, ...
```
diff --git a/docs/mcp.md b/docs/mcp.md
index 23074987..155c356c 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -81,21 +81,22 @@ pinchtab --server http://remote:9867 mcp
## Available Tools
-PinchTab currently exposes 34 tools:
+PinchTab currently exposes 38 tools:
-- Navigation: 4
-- Interaction: 8
+- Navigation: 5
+- Interaction: 9
- Keyboard: 4
- Content: 3
- Tab management: 5
- Wait utilities: 6
-- Network: 3
+- Network: 5
- Dialog: 1
### Navigation
- `pinchtab_navigate`
- `pinchtab_snapshot`
+- `pinchtab_frame`
- `pinchtab_screenshot`
- `pinchtab_get_text`
@@ -108,6 +109,7 @@ PinchTab currently exposes 34 tools:
- `pinchtab_focus`
- `pinchtab_select`
- `pinchtab_scroll`
+- `pinchtab_scroll_into_view`
- `pinchtab_fill`
### Keyboard
@@ -145,6 +147,8 @@ PinchTab currently exposes 34 tools:
- `pinchtab_network`
- `pinchtab_network_detail`
- `pinchtab_network_clear`
+- `pinchtab_network_route`
+- `pinchtab_network_unroute`
### Dialog
diff --git a/docs/reference/click.md b/docs/reference/click.md
index 65260289..31fa0132 100644
--- a/docs/reference/click.md
+++ b/docs/reference/click.md
@@ -24,6 +24,7 @@ OK
| `--dialog-action` | Auto-handle JS dialog: `accept` or `dismiss` |
| `--dialog-text` | Prompt response text (with `--dialog-action accept`) |
| `--x`, `--y` | Click at specific coordinates |
+| `--humanize` | Use humanized bezier+jitter input path (overrides instance config) |
| `--json` | Full JSON response |
| `--tab` | Target specific tab |
@@ -45,7 +46,7 @@ pinchtab click --x 100 --y 200 # Click at coordinates
- Refs for iframe descendants can be clicked directly without frame switch
- Selector lookup is limited to current frame scope (default: `main`)
- Use [`/frame`](./frame.md) before selector-based iframe actions
-- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) first for dynamic UI
+- Missing selectors fail immediately; use `pinchtab wait` first for dynamic UI (see [`commands.md`](../commands.md))
- The API also accepts `selector` field: `{"kind":"click","selector":"#login"}`
- Raw input is the default. To opt a click into the slower humanized path for a page that needs it, pass `humanize:true` in the action JSON or set `instanceDefaults.humanize:true`.
diff --git a/docs/reference/fill.md b/docs/reference/fill.md
index c45fb7b9..a71f530e 100644
--- a/docs/reference/fill.md
+++ b/docs/reference/fill.md
@@ -37,7 +37,7 @@ pinchtab fill e8 "value" --snap # Fill and show snapshot
- Refs for iframe descendants can be filled directly without frame switch
- Selector lookup is limited to current frame scope (default: `main`)
- Use [`/frame`](./frame.md) before selector-based iframe fills
-- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) first for async fields
+- Missing selectors fail immediately; use `pinchtab wait` first for async fields (see [`commands.md`](../commands.md))
- For API, use `selector` field for CSS/XPath/text selectors
## Related Pages
diff --git a/docs/reference/hover.md b/docs/reference/hover.md
index 533d39ea..3c5abc82 100644
--- a/docs/reference/hover.md
+++ b/docs/reference/hover.md
@@ -20,6 +20,7 @@ Use this when menus or tooltips appear only after hover.
|------|-------------|
| `--css` | CSS selector instead of ref |
| `--x`, `--y` | Hover at specific coordinates |
+| `--humanize` | Use humanized bezier+jitter input path (overrides instance config) |
| `--json` | Full JSON response |
| `--tab` | Target specific tab |
diff --git a/docs/reference/index.md b/docs/reference/index.md
index c7002a86..88bb2d9c 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -5,6 +5,7 @@ Reference pages for the current PinchTab CLI and closely related command-facing
Note: this index is generated and should be checked against the code when commands change.
- [CLI Overview](./cli.md)
+- [Cache](./cache.md)
- [Click](./click.md)
- [Config](./config.md)
- [Eval](./eval.md)
@@ -16,6 +17,7 @@ Note: this index is generated and should be checked against the code when comman
- [Handoff](./handoff.md)
- [Hover](./hover.md)
- [Instances](./instances.md)
+- [Keyboard](./keyboard.md)
- [Mouse](./mouse.md)
- [Navigate](./navigate.md)
- [PDF](./pdf.md)
@@ -25,6 +27,7 @@ Note: this index is generated and should be checked against the code when comman
- [Screenshot](./screenshot.md)
- [Scroll](./scroll.md)
- [Select](./select.md)
+- [Sessions](./sessions.md)
- [Snapshot](./snapshot.md)
- [Solve](./solve.md)
- [Strategies](./strategies.md)
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index d1b9d82f..fb83012c 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -1,8 +1,8 @@
# MCP Tool Reference
-PinchTab currently exposes 34 MCP tools. All tool names are prefixed with `pinchtab_` and are served over stdio JSON-RPC.
+PinchTab currently exposes 38 MCP tools. All tool names are prefixed with `pinchtab_` and are served over stdio JSON-RPC.
-For selector-based interaction tools, prefer `selector`. `ref` is still accepted as a deprecated fallback on the element-action tools.
+For selector-based interaction tools, prefer `selector`. `ref` and `query` are still accepted as deprecated/alias fallbacks on the element-action tools (`query` is shorthand for `find:<text>`).
If you allow MCP browsing on non-local or non-trusted domains, treat `pinchtab_snapshot` and `pinchtab_get_text` output as untrusted page data. Those tools can surface hostile prompt text from visited pages; operators should keep IDPI/domain restrictions narrow unless wider access is intentional.
@@ -23,23 +23,27 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
| Tool | Key Parameters | Notes |
| --- | --- | --- |
-| `pinchtab_navigate` | `url` required, `tabId` optional | Uses `/navigate`; omitting `tabId` opens a new tab |
+| `pinchtab_navigate` | `url` required, `tabId`, `snap` | Uses `/navigate`; omitting `tabId` opens a new tab. `snap=true` returns an interactive compact snapshot in the same response |
| `pinchtab_snapshot` | `tabId`, `interactive`, `compact`, `format`, `diff`, `selector`, `maxTokens`, `depth`, `noAnimations` | `selector` scopes the snapshot; `format` is limited to `compact` or `text` |
+| `pinchtab_frame` | `tabId`, `target` | Get or set the frame scope for selector-based actions on the tab; `target` accepts `main`, a snapshot ref, an iframe selector, or a frame name/URL |
| `pinchtab_screenshot` | `tabId`, `selector`, `css1x`, `format`, `quality` | `selector` captures a specific element in current frame scope; `css1x=true` exports selector shots at CSS pixel size; `format` is `jpeg` or `png` |
| `pinchtab_get_text` | `tabId`, `raw`, `format`, `maxChars` | `raw=true` maps to `/text?mode=raw`; `format=text/plain` returns plain text; inherits the current `pinchtab_frame` scope for that tab |
## Interaction
+All element-action tools accept the unified `selector` and the legacy aliases `ref` (deprecated) and `query` (semantic shorthand).
+
| Tool | Key Parameters | Notes |
| --- | --- | --- |
-| `pinchtab_click` | `selector` required, `tabId`, `ref`, `waitNav` | Click element by selector; `waitNav=true` waits for navigation |
-| `pinchtab_type` | `selector` required, `text` required, `tabId`, `ref` | Sends key events |
+| `pinchtab_click` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId`, `dialogAction`, `dialogText`, `waitNav`, `snap` | Click element by selector or coordinate; `dialogAction` handles a dialog opened by the click; `waitNav=true` waits for navigation; `snap=true` returns a snapshot |
+| `pinchtab_type` | `selector`, `ref`, `query`, `text` required, `tabId` | Sends key events at the targeted input |
| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |
-| `pinchtab_hover` | `selector` required, `tabId`, `ref` | Hover element |
-| `pinchtab_focus` | `selector` required, `tabId`, `ref` | Focus element |
-| `pinchtab_select` | `selector` required, `value` required, `tabId`, `ref` | Select `<option>` by value or visible text |
-| `pinchtab_scroll` | `selector`, `pixels`, `tabId`, `ref` | Omit `selector` to scroll the page |
-| `pinchtab_fill` | `selector` required, `value` required, `tabId`, `ref` | Direct fill instead of keystrokes |
+| `pinchtab_hover` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId` | Hover an element or coordinate |
+| `pinchtab_focus` | `selector`, `ref`, `query`, `tabId`, `nodeId` | Focus element |
+| `pinchtab_select` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text |
+| `pinchtab_scroll` | `selector`, `ref`, `query`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit `selector` to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |
+| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions |
+| `pinchtab_fill` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes |
## Keyboard
@@ -54,9 +58,9 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
| Tool | Key Parameters | Notes |
| --- | --- | --- |
-| `pinchtab_eval` | `expression` required, `tabId` | Requires `security.allowEvaluate` (documented non-default JS-execution opt-in) |
+| `pinchtab_eval` | `expression` required, `tabId` | Requires `security.allowEvaluate` (documented non-default JS-execution opt-in). Not frame-scoped β€” current `pinchtab_frame` state does not change evaluation context |
| `pinchtab_pdf` | `tabId`, `landscape`, `scale`, `pageRanges` | Returns base64-encoded PDF content |
-| `pinchtab_find` | `query` required, `tabId` | Semantic element search |
+| `pinchtab_find` | `query` required, `tabId` | Semantic element search; returns `best_ref` and selector hints to reuse in action tools |
## Tab Management
@@ -73,10 +77,10 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
| Tool | Key Parameters | Notes |
| --- | --- | --- |
| `pinchtab_wait` | `ms` required | Fixed-duration wait, capped at 30000 ms |
-| `pinchtab_wait_for_selector` | `selector` required, `timeout`, `state`, `tabId` | `state` is `visible` or `hidden` |
+| `pinchtab_wait_for_selector` | `selector` required, `timeout`, `state`, `tabId` | `state` is `visible` (default) or `hidden` |
| `pinchtab_wait_for_text` | `text` required, `timeout`, `tabId` | Wait for body text |
| `pinchtab_wait_for_url` | `url` required, `timeout`, `tabId` | URL glob match |
-| `pinchtab_wait_for_load` | `load` required, `timeout`, `tabId` | Currently supports `networkidle` |
+| `pinchtab_wait_for_load` | `load` required, `timeout`, `tabId` | `load` is `ready-state` (`readyState=complete`), `content-loaded` (`readyState` in `{interactive, complete}`), or `network-idle` (0 in-flight requests for 500 ms) |
| `pinchtab_wait_for_function` | `fn` required, `timeout`, `tabId` | JS expression must become truthy |
## Network
@@ -86,12 +90,14 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
| `pinchtab_network` | `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize` | Lists recent network requests |
| `pinchtab_network_detail` | `requestId` required, `tabId`, `body` | `body=true` includes response body when available |
| `pinchtab_network_clear` | `tabId` | Clears one tab or all tabs when omitted |
+| `pinchtab_network_route` | `tabId` required, `pattern` required, `action`, `body`, `contentType`, `status`, `resourceType`, `method` | Install a request-interception rule on a tab. `action` is `continue` (default), `abort`, or `fulfill`. `fulfill` is blocked on hosts in `security.allowedDomains` and falls through to a real fetch on those hosts |
+| `pinchtab_network_unroute` | `tabId` required, `pattern` | Remove a tab's interception rule by pattern, or all rules when `pattern` is omitted |
## Dialog
| Tool | Key Parameters | Notes |
| --- | --- | --- |
-| `pinchtab_dialog` | `action` required, `text`, `tabId` | `action` is `accept` or `dismiss` |
+| `pinchtab_dialog` | `action` required, `text`, `tabId` | `action` is `accept` or `dismiss`; `text` is used as the prompt response with `accept` |
## Return Shapes
diff --git a/docs/reference/mouse.md b/docs/reference/mouse.md
index 278c499d..c1dc65ab 100644
--- a/docs/reference/mouse.md
+++ b/docs/reference/mouse.md
@@ -42,6 +42,7 @@ pinchtab drag e5 400,320
Notes:
+- All `mouse` subcommands and `drag` accept `--humanize` to opt the action into the humanized bezier+jitter input path (overrides `instanceDefaults.humanize`).
- `mouse move` accepts either coordinates or a unified selector.
- `mouse down` and `mouse up` accept an optional selector. Without one, they use the current pointer position.
- `mouse wheel` accepts either a delta form (`<dy> [--dx <n>]`) or an optional selector. Without a selector, it uses the current pointer position.
diff --git a/docs/reference/sessions.md b/docs/reference/sessions.md
index 5e14e0e0..58af8440 100644
--- a/docs/reference/sessions.md
+++ b/docs/reference/sessions.md
@@ -36,9 +36,9 @@ In `config.json`:
## Lifecycle
-1. **Create** β€” via dashboard API: `POST /sessions`
-2. **Use** β€” agent sends `Authorization: Session ses_...` with each request
-3. **Revoke** β€” permanently disable: `POST /sessions/{id}/revoke`
+1. **Create** β€” `pinchtab session create --agent-id <id>` (or `POST /sessions` directly)
+2. **Use** β€” agent sends `Authorization: Session ses_...` with each request, or sets `PINCHTAB_SESSION`
+3. **Revoke** β€” `pinchtab session revoke <session-id>` (or `POST /sessions/{id}/revoke`)
## Security
@@ -65,14 +65,21 @@ That default is a convenience for trusted automation, not a sandbox. If you need
## CLI Usage
```bash
-# Set session token
-export PINCHTAB_SESSION=ses_abc123...
+# Create a new session (prints token to stdout with --print-token)
+pinchtab session create --agent-id agent-1 --print-token
+export PINCHTAB_SESSION=$(pinchtab session create --agent-id agent-1 --print-token)
-# CLI automatically uses session auth
+# CLI automatically uses session auth when PINCHTAB_SESSION is set
pinchtab snap
-# Check session info
+# Inspect the current session (uses PINCHTAB_SESSION)
pinchtab session info
+
+# List all sessions on the server (server bearer token required)
+pinchtab session list
+
+# Revoke a session by id
+pinchtab session revoke ses_abc123def456
```
## API Endpoints
diff --git a/docs/reference/strategies.md b/docs/reference/strategies.md
index acae4447..36cd0767 100644
--- a/docs/reference/strategies.md
+++ b/docs/reference/strategies.md
@@ -20,6 +20,7 @@ Valid strategies in the current implementation:
- `simple`
- `explicit`
- `simple-autorestart`
+- `no-instance`
### `simple`
@@ -85,6 +86,23 @@ Best fit:
- unattended local services
- environments where one browser should come back after a crash
+### `no-instance`
+
+`no-instance` runs PinchTab as a hub that does not launch any local Chrome processes. It only accepts remote bridges via `POST /instances/attach-bridge` and proxies shorthand requests to the first attached bridge.
+
+Behavior:
+
+- never launches a local instance
+- registers the orchestrator API in no-launch mode
+- shorthand routes (`/snapshot`, `/text`, `/navigate`, `/tabs`, etc.) proxy to the first attached remote bridge, or return `503 no remote instances connected β€” attach a bridge first` when none is attached
+- `GET /tabs` returns an empty list when no bridge is attached, instead of erroring
+
+Best fit:
+
+- bridge-orchestrator deployments where browsers run on other hosts (Tailscale, remote workers)
+- centralized routing tiers that should never spawn Chrome themselves
+- environments where the local PinchTab process must remain a pure proxy
+
## Allocation Policy
Valid policies in the current implementation:
@@ -209,6 +227,7 @@ always-on = default, launched at startup, restarted under restart poli
simple = on-demand shorthand auto-launch
explicit = most control, no shorthand auto-launch
simple-autorestart = one managed browser with crash recovery
+no-instance = pure proxy/hub for remote bridges, never launches Chrome
fcfs = deterministic
round_robin = balanced rotation
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index 07842bd4..fb1cf104 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -246,7 +246,13 @@ curl -X POST http://localhost:9867/tabs/<tabId>/cookies \
-d '{"cookies":[{"name":"session","value":"abc"}]}'
```
-There is no dedicated top-level cookies CLI command today.
+A `pinchtab cookies` CLI command is available; today it exposes a single subcommand:
+
+```bash
+pinchtab cookies clear # clear all cookies via CDP (affects all origins)
+```
+
+Reading and writing cookie payloads is HTTP-only.
## Metrics
@@ -276,5 +282,4 @@ There are also active-tab forms at `POST /lock` and `POST /unlock`.
- There is no `GET /tabs/{id}` endpoint for fetching single-tab metadata.
- `GET /tabs` and `GET /instances/tabs` serve different purposes and are not interchangeable.
-- In the CLI, tab-scoped work happens through top-level commands with `--tab`, not through `pinchtab tab <subcommand>` variants.
-- There is no dedicated CLI `handoff` or `resume` command today.
+- In the CLI, tab-scoped work happens through top-level commands with `--tab`, not through `pinchtab tab <subcommand>` variants β€” except for `handoff`, `resume`, and `handoff-status`, which are exposed both as top-level commands and as `pinchtab tab handoff|resume|handoff-status` subcommands.
diff --git a/docs/reference/type.md b/docs/reference/type.md
index 119d56a8..01782d04 100644
--- a/docs/reference/type.md
+++ b/docs/reference/type.md
@@ -16,6 +16,7 @@ OK
| Flag | Description |
|------|-------------|
+| `--humanize` | Use humanized per-character keypress timing (overrides instance config) |
| `--json` | Full JSON response |
| `--tab` | Target specific tab |
@@ -25,7 +26,7 @@ OK
- Accepts unified selectors: `e8`, `#name`, `xpath://input`, `text:Name`
- Selector lookup is limited to current frame scope (default: `main`)
- Use [`/frame`](./frame.md) before iframe typing
-- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) for async fields
+- Missing selectors fail immediately; use `pinchtab wait` for async fields (see [`commands.md`](../commands.md))
- For typing into focused element, use `keyboard type`
- Raw keyboard input is the default. To opt a type action into the slower humanized per-character path, pass `humanize:true` in the action JSON or set `instanceDefaults.humanize:true`.
diff --git a/docs/showcase.md b/docs/showcase.md
index b6a039bd..f37f08b3 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -99,7 +99,7 @@ pinchtab click e14
curl -s http://127.0.0.1:9867/screenshot > smoke.jpg
ls -lh smoke.jpg
# CLI Alternative
-pinchtab ss -o smoke.jpg
+pinchtab screenshot -o smoke.jpg
# Response
Saved smoke.jpg (55876 bytes)
```
@@ -168,7 +168,7 @@ Saved report.pdf (1494657 bytes)
curl -s http://127.0.0.1:9867/screenshot > page.jpg
ls -lh page.jpg
# CLI Alternative
-pinchtab ss -o page.jpg
+pinchtab screenshot -o page.jpg
# Response
Saved page.jpg (55876 bytes)
```
diff --git a/scripts/README.md b/scripts/README.md
index eb1339c0..97183d17 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -21,6 +21,7 @@ Development and CI scripts for PinchTab.
| Script | Purpose |
|--------|---------|
| `build.sh` | Full build (dashboard + Go) without starting the server |
+| `install.sh` | Full build + install to `~/.local/bin/pinchtab` (override with `PINCHTAB_INSTALL_DIR`); re-signs ad-hoc on macOS |
| `binary.sh` | Release-style stripped binary build into `dist/` for the current platform, or the full matrix with `all` |
| `build-dashboard.sh` | Generate TS types (tygo) + build React dashboard + copy to Go embed |
| `autosolver-realworld-smoke.sh` | Smoke-test real-world autosolver flow against an external detection page |
diff --git a/scripts/install.sh b/scripts/install.sh
new file mode 100755
index 00000000..3d95542c
--- /dev/null
+++ b/scripts/install.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# Build Pinchtab and install it locally for development use.
+# Builds straight into the install path so the linker's ad-hoc signature
+# stays valid on Apple Silicon (a plain `cp` invalidates it and macOS
+# kills the process on launch).
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+INSTALL_DIR="${PINCHTAB_INSTALL_DIR:-$HOME/.local/bin}"
+INSTALL_PATH="$INSTALL_DIR/pinchtab"
+
+mkdir -p "$INSTALL_DIR"
+
+./scripts/build-dashboard.sh
+
+echo "πŸ”¨ Building Go β†’ $INSTALL_PATH"
+go build -o "$INSTALL_PATH" ./cmd/pinchtab
+
+if [[ "$(uname -s)" == "Darwin" ]]; then
+ echo "πŸ” Re-signing (ad-hoc) for macOS"
+ codesign --force --sign - "$INSTALL_PATH"
+fi
+
+if command -v brew >/dev/null 2>&1 && brew list pinchtab >/dev/null 2>&1; then
+ if [[ -L /opt/homebrew/bin/pinchtab || -L /usr/local/bin/pinchtab ]]; then
+ echo "⚠️ Homebrew pinchtab is linked and may shadow this build."
+ echo " Run: brew unlink pinchtab"
+ fi
+fi
+
+echo "βœ… Installed: $INSTALL_PATH"
+"$INSTALL_PATH" --version