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/devindex 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.mdindex 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 Constraintsdiff --git a/docs/architecture/instance-charts.md b/docs/architecture/instance-charts.mdindex 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.mdindex 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 APIcmd/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 Considerationsdiff --git a/docs/benchmark.md b/docs/benchmark.mdindex 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-runtables, raw transcripts, token breakdowns, variance discussion, andthe full list of measurement caveats.diff --git a/docs/commands.md b/docs/commands.mdindex a316abd6..b99e6e24 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -163,11 +163,12 @@ pinchtab network # List captured network requestspinchtab network <requestId> # Show one request in detailpinchtab network --stream # Stream network entriespinchtab 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/promptpinchtab dialog dismiss # Dismiss dialogpinchtab 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.mdindex 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 toAnthropic.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 appendsthe 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 theheader 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 ofGroups 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 intervaland 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.mdindex 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.mdindex 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}/tabNotes:- `/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.mdindex 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 Supportdiff --git a/docs/guides/agent-identity.md b/docs/guides/agent-identity.mdindex 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.mdindex 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.mdindex 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 secretecho "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_TOKENservices:pinchtab:image: pinchtab/pinchtabsecrets:- 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.## Composediff --git a/docs/guides/mcp-agents.md b/docs/guides/mcp-agents.mdindex 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.## Prerequisitesdiff --git a/docs/implementations/chrome-files.md b/docs/implementations/chrome-files.mdindex 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 proc2. **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.mdindex 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 instIf 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 TerminationEven 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 RemovalOnce 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 Safetydiff --git a/docs/implementations/index.md b/docs/implementations/index.mdindex 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.mdindex 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.mdindex 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 themaximum tab count (`MaxTabs`) is reached:@@ -922,7 +925,7 @@ CPU usage remains bounded while I/O parallelism is maximized.```goos: windowsgoarch: amd64-pkg: github.com/nicholasgasior/pinchtab/internal/bridge+pkg: github.com/pinchtab/pinchtab/internal/bridgecpu: Intel(R) Core(TM) i5-4300U CPU @ 1.90GHzBenchmarkTabExecutor_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 BBenchmarkTabExecutor_ParallelSameTab-4 1000000 1386 ns/op 136 B/op 3 allocs/opBenchmarkTabExecutor_WithWork-4 1515068 766.4 ns/op 136 B/op 2 allocs/opPASS-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 racesgo 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.mdindex 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`### Dialogdiff --git a/docs/reference/click.md b/docs/reference/click.mdindex 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.mdindex 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 Pagesdiff --git a/docs/reference/hover.md b/docs/reference/hover.mdindex 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.mdindex 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-facingNote: 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.mdindex 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 Shapesdiff --git a/docs/reference/mouse.md b/docs/reference/mouse.mdindex 278c499d..c1dc65ab 100644--- a/docs/reference/mouse.md+++ b/docs/reference/mouse.md@@ -42,6 +42,7 @@ pinchtab drag e5 400,320Notes:+- 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.mdindex 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 setpinchtab 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 Endpointsdiff --git a/docs/reference/strategies.md b/docs/reference/strategies.mdindex 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 PolicyValid policies in the current implementation:@@ -209,6 +227,7 @@ always-on = default, launched at startup, restarted under restart polisimple = on-demand shorthand auto-launchexplicit = most control, no shorthand auto-launchsimple-autorestart = one managed browser with crash recovery+no-instance = pure proxy/hub for remote bridges, never launches Chromefcfs = deterministicround_robin = balanced rotationdiff --git a/docs/reference/tabs.md b/docs/reference/tabs.mdindex 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.mdindex 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.mdindex b6a039bd..f37f08b3 100644--- a/docs/showcase.md+++ b/docs/showcase.md@@ -99,7 +99,7 @@ pinchtab click e14curl -s http://127.0.0.1:9867/screenshot > smoke.jpgls -lh smoke.jpg# CLI Alternative-pinchtab ss -o smoke.jpg+pinchtab screenshot -o smoke.jpg# ResponseSaved smoke.jpg (55876 bytes)```@@ -168,7 +168,7 @@ Saved report.pdf (1494657 bytes)curl -s http://127.0.0.1:9867/screenshot > page.jpgls -lh page.jpg# CLI Alternative-pinchtab ss -o page.jpg+pinchtab screenshot -o page.jpg# ResponseSaved page.jpg (55876 bytes)```diff --git a/scripts/README.md b/scripts/README.mdindex 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.shnew file mode 100755index 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