Skip to content

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

test: add docker soak/stability lane and persona onboarding lane

Bosch41ae6eb53edf
diff --git a/tests/install-ux/.gitignore b/tests/install-ux/.gitignore
new file mode 100644
index 00000000..34da3fd0
--- /dev/null
+++ b/tests/install-ux/.gitignore
@@ -0,0 +1,2 @@
+results/
+.bin/
diff --git a/tests/install-ux/Dockerfile.base b/tests/install-ux/Dockerfile.base
new file mode 100644
index 00000000..a62b847f
--- /dev/null
+++ b/tests/install-ux/Dockerfile.base
@@ -0,0 +1,5 @@
+# No-browser base for the install-UX personas that start on a fresh machine with
+# no browser installed (S-B, S-D). curl + ca-certificates only.
+FROM debian:stable-slim
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
diff --git a/tests/install-ux/PERSONAS.md b/tests/install-ux/PERSONAS.md
new file mode 100644
index 00000000..40c1394c
--- /dev/null
+++ b/tests/install-ux/PERSONAS.md
@@ -0,0 +1,23 @@
+# Onboarding persona × condition × goal matrix
+
+Goal: pressure-test new-user onboarding. A blind agent simulates each persona reaching a
+first-step goal using only user-facing docs, in the persona's container.
+
+| ID | Container | Persona (skill) | Starting condition | First-step goal | Primarily probes |
+|----|-----------|-----------------|--------------------|-----------------|------------------|
+| S-A | `ptux-sa` | Impatient first-timer (low) | chromium present | open example.com, read title | happy path + IDPI block for a non-technical user |
+| S-B | `ptux-sb` | Backend dev (high) | **no browser** | scrape a page's heading | no-browser cold start, scraping flow |
+| S-C | `ptux-sc` | Privacy researcher (med) | chromium present | browse the **public** web | IDPI allowlist / guards journey, security legibility |
+| S-D | `ptux-sd` | DevOps / CI (high) | **no browser, minimal** | scriptable title (JSON/exit codes, restart) | scriptability, restart cleanliness |
+| S-E | `ptux-se` | Mis-set config (med) | chromium + **bogus `browser.binary`** | get nav working again | diagnosability (doctor), recovery |
+| S-F | `ptux-sf` | API integrator (high) | chromium + curl | open a page via the **HTTP API** | API discoverability, auth/token UX |
+
+## Per-scenario record (each agent returns)
+Chronological friction log → for each step: command, key output (quoted), user
+interpretation, could-proceed-from-the-messaging-alone (yes/partial/no), one-line fix.
+Then: goal achieved? top friction points; onboarding verdict for that persona.
+
+## Synthesis (after a run)
+- Cross-persona friction table (recurring vs persona-specific).
+- Ranked onboarding improvements scoped to what's fixable in this repo.
+- Validation that prior fixes still hold under persona pressure.
diff --git a/tests/install-ux/README.md b/tests/install-ux/README.md
new file mode 100644
index 00000000..a27bb6f1
--- /dev/null
+++ b/tests/install-ux/README.md
@@ -0,0 +1,39 @@
+# PinchTab onboarding / install-UX persona lane
+
+Agent-driven tests of the **new-user onboarding experience**. Each scenario pairs a user
+persona (skill level + intent) with a starting condition and a first-step goal, then a
+**blind agent** simulates that user reaching the goal using ONLY the user-facing docs, in a
+fresh container. We collect friction and turn it into fixes.
+
+This is NOT a CI unit test — it needs Docker plus an LLM agent runtime (e.g. Claude
+subagents) to play the personas. The scenario definitions, container provisioning, and agent
+brief here make it repeatable.
+
+## How to run
+
+```bash
+# 1. Provision one clean container per persona (each with its starting condition)
+tests/install-ux/setup.sh
+
+# 2. For each persona, launch a blind agent with:
+# - tests/install-ux/subagent-context.md (shared rules + the persona's brief)
+# - the persona's container name (e.g. ptux-sa)
+# The agent operates the container via `docker exec <name> bash -lc '...'`,
+# reads ONLY user-facing docs (README.md, skills/pinchtab/SKILL.md, docs/**),
+# and returns a friction log.
+
+# 3. Tear down
+docker rm -f ptux-sa ptux-sb ptux-sc ptux-sd ptux-se ptux-sf
+```
+
+## Files
+- `PERSONAS.md` — the persona × condition × goal matrix.
+- `setup.sh` — provisions the per-persona containers with their starting conditions.
+- `subagent-context.md` — shared blind-agent rules + the per-persona briefs to hand each agent.
+
+## What good looks like
+Every persona should reach its goal, and — critically — recover from each obstacle using the
+tool's OWN output/docs (no guessing, no source-reading). The friction log scores each step
+`yes/partial/no` on "could proceed from the messaging alone." See the repo's commit history
+for fixes that came out of earlier runs (no-browser guidance, IDPI remediation, session
+auto-start, `config --help` discoverability, etc.).
diff --git a/tests/install-ux/setup.sh b/tests/install-ux/setup.sh
new file mode 100755
index 00000000..d8f4c6b4
--- /dev/null
+++ b/tests/install-ux/setup.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Provision one clean container per onboarding persona, each with its starting
+# condition. Then drive each with a blind agent using subagent-context.md.
+set -euo pipefail
+
+REPO="$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)"
+HERE="$REPO/tests/install-ux"
+cd "$REPO"
+
+case "$(uname -m)" in
+ aarch64|arm64) GOARCH=arm64 ;;
+ x86_64|amd64) GOARCH=amd64 ;;
+ *) echo "unsupported arch $(uname -m)"; exit 1 ;;
+esac
+
+echo "[ux] building linux/$GOARCH pinchtab binary..."
+mkdir -p "$HERE/.bin"
+CGO_ENABLED=0 GOOS=linux GOARCH="$GOARCH" go build -ldflags="-s -w" -o "$HERE/.bin/pinchtab" ./cmd/pinchtab
+
+echo "[ux] building images..."
+docker build -q -f "$REPO/tests/soak/Dockerfile" -t pinchtab-ux-browser "$REPO/tests/soak" >/dev/null # chromium + curl
+docker build -q -f "$HERE/Dockerfile.base" -t pinchtab-ux-base "$HERE" >/dev/null # no browser
+
+mk(){ # name image
+ docker rm -f "$1" >/dev/null 2>&1 || true
+ docker run -d --name "$1" --shm-size=512m "$2" sleep infinity >/dev/null
+ docker cp "$HERE/.bin/pinchtab" "$1:/usr/local/bin/pinchtab" >/dev/null
+ docker exec "$1" chmod +x /usr/local/bin/pinchtab
+}
+
+mk ptux-sa pinchtab-ux-browser # impatient first-timer, browser present
+mk ptux-sb pinchtab-ux-base # backend dev, NO browser
+mk ptux-sc pinchtab-ux-browser # privacy researcher, browser present
+mk ptux-sd pinchtab-ux-base # devops/CI, minimal, NO browser
+mk ptux-se pinchtab-ux-browser # mis-set browser.binary
+mk ptux-sf pinchtab-ux-browser # API integrator (curl present)
+
+# S-E: pre-set a bogus browser.binary in the DEFAULT config the agent will read.
+docker exec ptux-se sh -c 'pinchtab config init >/dev/null 2>&1 && pinchtab config set browser.binary /opt/not-a-real-chrome >/dev/null 2>&1'
+
+echo "[ux] persona containers ready:"
+for c in ptux-sa ptux-sb ptux-sc ptux-sd ptux-se ptux-sf; do
+ br=$(docker exec "$c" sh -c 'command -v chromium >/dev/null && echo chromium || echo NONE')
+ printf " %-9s browser=%s\n" "$c" "$br"
+done
+echo "[ux] now launch a blind agent per persona using tests/install-ux/subagent-context.md"
diff --git a/tests/install-ux/subagent-context.md b/tests/install-ux/subagent-context.md
new file mode 100644
index 00000000..b3fee525
--- /dev/null
+++ b/tests/install-ux/subagent-context.md
@@ -0,0 +1,59 @@
+# Blind persona agent — context
+
+Hand this (plus ONE persona brief from the table below) to an agent to simulate a new
+PinchTab user. Provision the containers first with `tests/install-ux/setup.sh`.
+
+## Shared rules (apply to every persona)
+
+You are role-playing a PERSONA using PinchTab for the first time. Stay in character and
+report friction.
+
+**Your machine** is the running container named in your brief (e.g. `ptux-sa`). Run every
+command by wrapping it:
+
+ docker exec <CONTAINER> bash -lc '<command>'
+
+Files, installed packages, and background processes persist between calls; shell env does
+NOT (re-export or use absolute values). Background a long-running server with `nohup ... &`.
+
+**What you may read** (on the host repo) — user-facing docs ONLY: `README.md`,
+`skills/pinchtab/SKILL.md`, and anything under `docs/` they point to. You MUST NOT read
+source code (`internal/`, `cmd/`, `*.go`), tests, or any scratch/tmp path. You are a user
+who has only the docs + whatever the CLI/API prints back.
+
+**Rules:** use only documented commands and what the tool tells you. On an error, consult
+the docs and the tool's own output first — do NOT read source. For each obstacle record
+whether PinchTab's OWN output/docs led you to the fix, or you had to guess. Timebox; if
+blocked after exhausting docs + CLI output, record it and stop.
+
+**Deliverable** (your final message): a chronological friction log — per step: the command,
+key output (quoted/trimmed), your interpretation AS THIS PERSONA, could-you-proceed-from-the-
+messaging-alone (yes/partial/no), one-line fix. Then: goal achieved? top friction points
+(worst first); onboarding verdict for this persona (1-2 sentences). Quote real output.
+
+## Persona briefs
+
+- **S-A — `ptux-sa` — impatient non-technical first-timer (low skill).** You paste documented
+ commands literally and lose patience fast; you don't know terms like "headless"/"allowlist".
+ Goal: open `https://example.com` and tell me its page title.
+
+- **S-B — `ptux-sb` — backend dev on a fresh headless server (high skill), no browser
+ installed.** You improvise but expect good tooling. Goal: scrape the main heading / visible
+ text of a simple web page.
+
+- **S-C — `ptux-sc` — privacy-conscious researcher (medium skill), browser present.** You want
+ to understand the security posture before loosening it. Goal: successfully browse the PUBLIC
+ web — load a real public site and read something off it — configuring whatever is required.
+
+- **S-D — `ptux-sd` — DevOps engineer wiring CI (high skill), minimal container, no browser.**
+ You value reproducibility, JSON output, stable exit codes, clean restarts. Goal: reliably
+ get a page's title in a scriptable way (prefer JSON/exit codes), and restart the server once
+ to confirm it comes back cleanly.
+
+- **S-E — `ptux-se` — developer who previously fiddled with config (medium skill).** A browser
+ is available but navigation is failing; you don't remember what you changed. Goal: get
+ navigation working again. (Does the tool DIAGNOSE the misconfig and tell you the fix?)
+
+- **S-F — `ptux-sf` — AI-tooling engineer integrating over the HTTP API (high skill),** browser
+ + curl present. Goal: using the documented HTTP API (prefer `curl` over `pinchtab nav`), bring
+ up the control plane, authenticate, open a page, and read its title via the API.
diff --git a/tests/soak/.gitignore b/tests/soak/.gitignore
new file mode 100644
index 00000000..34da3fd0
--- /dev/null
+++ b/tests/soak/.gitignore
@@ -0,0 +1,2 @@
+results/
+.bin/
diff --git a/tests/soak/Dockerfile b/tests/soak/Dockerfile
new file mode 100644
index 00000000..13873bbf
--- /dev/null
+++ b/tests/soak/Dockerfile
@@ -0,0 +1,7 @@
+# Soak/stability test image: Chromium + Python (to serve fixtures) + curl.
+# The pinchtab binary and fixtures are injected at provision time by setup.sh, so
+# this image rarely needs rebuilding.
+FROM debian:stable-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ chromium ca-certificates curl python3 \
+ && rm -rf /var/lib/apt/lists/*
diff --git a/tests/soak/README.md b/tests/soak/README.md
new file mode 100644
index 00000000..7f28e15c
--- /dev/null
+++ b/tests/soak/README.md
@@ -0,0 +1,57 @@
+# PinchTab browser soak / stability lane
+
+Docker-based stress tests for browser **stability, responsiveness, and recoverability**
+under sustained load. Not a unit test — requires Docker, runs for minutes to an hour, and
+is meant as a manual / nightly check. Drives the `chrome` provider (Debian Chromium) by
+default.
+
+## Quick start
+
+```bash
+# 1. Provision a container (builds the binary + image, starts a guards-down server)
+tests/soak/setup.sh
+
+# 2a. Stability soak — reuse ONE browser under mixed load for an hour
+tests/soak/soak.sh 3600
+
+# 2b. OR find the breaking point — unbounded tabs under a tight cap
+MEM_CAP=1g SHM=256m MAX_TABS=200 tests/soak/setup.sh
+tests/soak/burst.sh 1200
+
+# 3. Tear down
+docker rm -f pinchtab-soak
+```
+
+Results (CSV + summary) land in `tests/soak/results/` (git-ignored).
+
+## What each measures
+
+- **soak.sh** — reuses the *same* long-lived browser across cycles of randomized light /
+ heavy / fixture loads, grows & churns tabs, periodically idles a few minutes then
+ re-probes, and on unresponsiveness restarts + records recovery. Watches for responsiveness
+ drift, memory growth/leaks, and crashes over time.
+- **burst.sh** — opens a fresh heavy tab every ~1s with no eviction relief under a tight
+ memory cap, to drive the browser to its breaking point (renderer OOM) and exercise
+ recovery. Records the first breaking point (tabs/memory/OOM) and recovery success.
+
+## Tuning (env vars on setup.sh)
+
+| Var | Default | Use |
+|-----|---------|-----|
+| `MEM_CAP` | `2g` | lower (e.g. `1g`) to reach a breaking point sooner |
+| `SHM` | `1g` | Chrome shared memory; lower (`256m`) stresses harder |
+| `MAX_TABS` | `20` | raise (e.g. `200`) so tabs grow unbounded for burst.sh |
+| `HEAVY_MB` | `5` | size of the generated `heavy.html` |
+| `CPUS` | `2` | CPU limit |
+
+## Reference baseline (what "healthy" looks like)
+
+From a 1-hour soak at `maxTabs=20`, 2 GB cap, Chromium 149, arm64:
+- responsiveness flat at **p50 ~11 ms** (no drift, even after multi-minute idles)
+- memory self-bounds (LRU eviction at `maxTabs` caps tabs → caps memory); no leak
+- **zero** unresponsive events / failed navs over 120 cycles
+
+Breaking point only appears when `maxTabs` is raised past available RAM: ~**10 heavy tabs
+per GB** → Chrome renderer OOM. The control plane + existing tabs stay responsive (~16 ms);
+only *new-tab creation* fails. Recovery via `pinchtab server restart` is reliable (~6 s).
+See the in-tree design note for the auto-recovery follow-up.
diff --git a/tests/soak/burst.sh b/tests/soak/burst.sh
new file mode 100755
index 00000000..e39c2a03
--- /dev/null
+++ b/tests/soak/burst.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Escalated burst: grow tabs UNBOUNDED with heavy pages to find the browser's
+# breaking point and exercise recovery. Provision with a tight cap and a high tab
+# limit first, e.g.: MEM_CAP=1g SHM=256m MAX_TABS=200 tests/soak/setup.sh
+#
+# Usage: CONTAINER=pinchtab-soak FIX_PORT=8088 tests/soak/burst.sh [DURATION_SECONDS]
+set +e
+CN="${CONTAINER:-pinchtab-soak}"
+FIX="${FIX_PORT:-8088}"
+DURATION="${1:-1200}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESULTS="${RESULTS_DIR:-$HERE/results}"; mkdir -p "$RESULTS"
+METRICS="$RESULTS/burst_metrics.csv"; SUMMARY="$RESULTS/burst_summary.txt"
+START=$(date +%s); DEADLINE=$((START + DURATION))
+
+HEAVY=("http://localhost:$FIX/heavy.html" https://en.wikipedia.org/wiki/Operating_system "http://localhost:$FIX/ecommerce.html" "http://localhost:$FIX/dashboard.html")
+
+timed(){ docker exec "$CN" sh -c 'S=$(date +%s%3N); { '"$1"' ; } >/dev/null 2>&1; rc=$?; E=$(date +%s%3N); echo "$((E-S))|$rc"'; }
+ex(){ docker exec "$CN" sh -c "$1" 2>/dev/null; }
+tabcount(){ ex 'pinchtab tab --json' | grep -o '"id"' | wc -l | tr -d ' '; }
+cmem(){ docker stats --no-stream --format '{{.MemUsage}}' "$CN" 2>/dev/null | awk '{print $1}' | sed 's/MiB//;s/GiB/*1024/' | bc 2>/dev/null | cut -d. -f1; }
+chromemem(){ ex "ps -o rss,comm 2>/dev/null | awk '/chrom/{s+=\$1} END{print int(s/1024)}'"; }
+oomflag(){ docker inspect "$CN" --format '{{.State.OOMKilled}}' 2>/dev/null; }
+
+echo "ts,elapsed_s,cycle,tabs,cmem_mb,chrome_mb,health_ms,health_ok,probe_ms,probe_ok,nav_ms,nav_ok,event" > "$METRICS"
+cycle=0; breaks=0; recoveries=0; failed_rec=0; peakmem=0; peaktabs=0; firstbreak=""
+
+echo "[burst] $CN for ${DURATION}s; metrics -> $METRICS"
+while [ "$(date +%s)" -lt "$DEADLINE" ]; do
+ cycle=$((cycle+1))
+ IFS='|' read -r hms hrc <<<"$(timed 'pinchtab health')"
+ IFS='|' read -r pms prc <<<"$(timed 'pinchtab title')"
+ tabs=$(tabcount); [ -z "$tabs" ] && tabs=0
+ cm=$(cmem); [ -z "$cm" ] && cm=0; chm=$(chromemem); [ -z "$chm" ] && chm=0
+ [ "${cm:-0}" -gt "$peakmem" ] 2>/dev/null && peakmem=$cm
+ [ "${tabs:-0}" -gt "$peaktabs" ] 2>/dev/null && peaktabs=$tabs
+ hok=$([ "$hrc" = 0 ] && echo 1 || echo 0); pok=$([ "$prc" = 0 ] && echo 1 || echo 0)
+
+ u=${HEAVY[$((RANDOM%${#HEAVY[@]}))]}
+ IFS='|' read -r nms nrc <<<"$(timed "pinchtab nav $u --new-tab")"
+ nok=$([ "$nrc" = 0 ] && echo 1 || echo 0)
+
+ broke=0; { [ "$hrc" != 0 ] || [ "$prc" != 0 ] || [ "${pms:-99999}" -gt 20000 ] || [ "$nrc" != 0 ]; } && broke=1
+ if [ "$broke" = 1 ]; then
+ breaks=$((breaks+1)); oom=$(oomflag)
+ [ -z "$firstbreak" ] && firstbreak="cycle $cycle @ $(($(date +%s)-START))s: tabs=$tabs mem=${cm}MB chrome=${chm}MB oom=$oom (health_rc=$hrc title_rc=$prc title_ms=$pms nav_rc=$nrc)"
+ echo "$(date +%s),$(($(date +%s)-START)),$cycle,$tabs,$cm,$chm,$hms,$hok,$pms,$pok,$nms,$nok,BREAK(oom=$oom)" >> "$METRICS"
+ IFS='|' read -r rms rrc <<<"$(timed 'pinchtab server restart')"; sleep 8
+ IFS='|' read -r r2ms r2rc <<<"$(timed "pinchtab nav http://localhost:$FIX/article.html")"
+ if [ "$r2rc" = 0 ]; then recoveries=$((recoveries+1)); ev="RECOVERED(restart ${rms}ms, nav ${r2ms}ms)"; else failed_rec=$((failed_rec+1)); ev="RECOVERY-FAILED(rc=$r2rc)"; fi
+ echo "$(date +%s),$(($(date +%s)-START)),$cycle,$(tabcount),$(cmem),$(chromemem),-,-,-,-,-,-,$ev" >> "$METRICS"
+ sleep 2; continue
+ fi
+ echo "$(date +%s),$(($(date +%s)-START)),$cycle,$tabs,$cm,$chm,$hms,$hok,$pms,$pok,$nms,$nok,grow" >> "$METRICS"
+ sleep 1
+done
+
+{
+ echo "PinchTab BURST (escalated) summary"
+ echo "duration: $(($(date +%s)-START))s cycles: $cycle"
+ echo "break events: $breaks recovered: $recoveries recovery-failed: $failed_rec"
+ echo "peak mem: ${peakmem}MB peak tabs: $peaktabs"
+ echo "FIRST BREAKING POINT: ${firstbreak:-none (survived full run)}"
+} | tee "$SUMMARY"
diff --git a/tests/soak/setup.sh b/tests/soak/setup.sh
new file mode 100755
index 00000000..72bab243
--- /dev/null
+++ b/tests/soak/setup.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Provision a clean PinchTab soak container: cross-compile the binary for the
+# container arch, build the image, start the container under resource limits, and
+# bring up a fixture server + a guards-down PinchTab server.
+#
+# Env (all optional):
+# CONTAINER container name (default: pinchtab-soak)
+# MEM_CAP docker --memory (default: 2g)
+# SHM docker --shm-size (default: 1g)
+# CPUS docker --cpus (default: 2)
+# MAX_TABS instanceDefaults.maxTabs (default: 20 — raise to find the breaking point)
+# FIX_PORT fixture http port (default: 8088)
+# HEAVY_MB approx size of heavy.html in MB (default: 5)
+set -euo pipefail
+
+CONTAINER="${CONTAINER:-pinchtab-soak}"
+MEM_CAP="${MEM_CAP:-2g}"
+SHM="${SHM:-1g}"
+CPUS="${CPUS:-2}"
+MAX_TABS="${MAX_TABS:-20}"
+FIX_PORT="${FIX_PORT:-8088}"
+HEAVY_MB="${HEAVY_MB:-5}"
+
+REPO="$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)"
+HERE="$REPO/tests/soak"
+cd "$REPO"
+
+case "$(uname -m)" in
+ aarch64|arm64) GOARCH=arm64 ;;
+ x86_64|amd64) GOARCH=amd64 ;;
+ *) echo "unsupported arch $(uname -m)"; exit 1 ;;
+esac
+
+echo "[soak] building linux/$GOARCH pinchtab binary..."
+mkdir -p "$HERE/.bin"
+CGO_ENABLED=0 GOOS=linux GOARCH="$GOARCH" go build -ldflags="-s -w" -o "$HERE/.bin/pinchtab" ./cmd/pinchtab
+
+echo "[soak] building image..."
+docker build -q -f "$HERE/Dockerfile" -t pinchtab-soak-img "$HERE" >/dev/null
+
+echo "[soak] starting container '$CONTAINER' (mem=$MEM_CAP shm=$SHM cpus=$CPUS maxTabs=$MAX_TABS)..."
+docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+docker run -d --name "$CONTAINER" --shm-size="$SHM" --memory="$MEM_CAP" --cpus="$CPUS" \
+ pinchtab-soak-img sleep infinity >/dev/null
+
+docker cp "$HERE/.bin/pinchtab" "$CONTAINER:/usr/local/bin/pinchtab" >/dev/null
+docker exec "$CONTAINER" chmod +x /usr/local/bin/pinchtab
+docker cp "$REPO/tests/tools/fixtures" "$CONTAINER:/fixtures" >/dev/null
+
+echo "[soak] generating heavy.html (~${HEAVY_MB}MB)..."
+docker exec "$CONTAINER" python3 -c "
+rows=int(${HEAVY_MB}*8000)
+open('/fixtures/heavy.html','w').write('<html><body><table>'+''.join(f'<tr><td>{i}</td><td>lorem ipsum dolor sit amet {i}</td></tr>' for i in range(rows))+'</table>'+'<div>filler</div>'*int(${HEAVY_MB}*4000)+'</body></html>')
+import os; print(' heavy.html', round(os.path.getsize('/fixtures/heavy.html')/1e6,1),'MB')
+"
+
+docker exec -d "$CONTAINER" sh -c "cd /fixtures && python3 -m http.server $FIX_PORT --bind 127.0.0.1"
+sleep 1
+
+# Guards-down so public + heavy pages load without the IDPI allowlist getting in the way.
+docker exec "$CONTAINER" sh -c "
+ pinchtab config init >/dev/null 2>&1
+ pinchtab security down >/dev/null 2>&1
+ pinchtab config set instanceDefaults.maxTabs $MAX_TABS >/dev/null 2>&1
+ pinchtab config set security.allowedDomains 'localhost,127.0.0.1,::1,en.wikipedia.org,example.com,news.ycombinator.com' >/dev/null 2>&1
+"
+docker exec -d "$CONTAINER" sh -c 'pinchtab server -b >/tmp/srv.log 2>&1'
+sleep 3
+
+docker exec "$CONTAINER" sh -c "
+ echo '[soak] ready:'
+ pinchtab nav http://localhost:$FIX_PORT/heavy.html >/dev/null 2>&1 && echo ' heavy nav OK'
+ echo \" instance: \$(pinchtab instances 2>&1 | head -1)\"
+ echo \" maxTabs=\$(pinchtab config get instanceDefaults.maxTabs) fixtures=http://localhost:$FIX_PORT\"
+"
+echo "[soak] container '$CONTAINER' ready. Run: CONTAINER=$CONTAINER FIX_PORT=$FIX_PORT tests/soak/soak.sh 3600"
diff --git a/tests/soak/soak.sh b/tests/soak/soak.sh
new file mode 100755
index 00000000..1625e1f0
--- /dev/null
+++ b/tests/soak/soak.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# Stability soak: reuse the SAME browser across cycles under randomized mixed load
+# (light / heavy / fixture pages), grow & churn tabs, periodically idle a few
+# minutes then re-probe, and on unresponsiveness attempt a restart + record whether
+# it recovered. Provision the container first with tests/soak/setup.sh.
+#
+# Usage: CONTAINER=pinchtab-soak FIX_PORT=8088 tests/soak/soak.sh [DURATION_SECONDS]
+set +e
+CN="${CONTAINER:-pinchtab-soak}"
+FIX="${FIX_PORT:-8088}"
+DURATION="${1:-3600}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESULTS="${RESULTS_DIR:-$HERE/results}"; mkdir -p "$RESULTS"
+METRICS="$RESULTS/soak_metrics.csv"; SUMMARY="$RESULTS/soak_summary.txt"
+START=$(date +%s); DEADLINE=$((START + DURATION))
+
+LIGHT=(https://example.com "http://localhost:$FIX/article.html" "http://localhost:$FIX/form.html" "http://localhost:$FIX/qa.html")
+HEAVY=("http://localhost:$FIX/heavy.html" https://en.wikipedia.org/wiki/Web_browser https://en.wikipedia.org/wiki/Operating_system https://news.ycombinator.com)
+FIXP=(article.html form.html ecommerce.html dashboard.html spa.html serp.html directory.html accordion.html iframe.html editor.html autocomplete.html wizard.html)
+
+timed(){ docker exec "$CN" sh -c 'S=$(date +%s%3N); { '"$1"' ; } >/dev/null 2>&1; rc=$?; E=$(date +%s%3N); echo "$((E-S))|$rc"'; }
+ex(){ docker exec "$CN" sh -c "$1" 2>/dev/null; }
+tabcount(){ ex 'pinchtab tab --json' | grep -o '"id"' | wc -l | tr -d ' '; }
+cmem(){ docker stats --no-stream --format '{{.MemUsage}}' "$CN" 2>/dev/null | awk '{print $1}' | sed 's/MiB//;s/GiB/*1024/' | bc 2>/dev/null | cut -d. -f1; }
+chromemem(){ ex "ps -o rss,comm 2>/dev/null | awk '/chrom/{s+=\$1} END{print int(s/1024)}'"; }
+
+echo "ts,elapsed_s,cycle,phase,tabs,cmem_mb,chrome_mb,health_ms,health_ok,probe_ms,probe_ok,action,note" > "$METRICS"
+cycle=0; fails=0; recoveries=0; failed_recoveries=0; peakmem=0; peaktabs=0; firstbreak=""
+log(){ echo "$(date +%s),$(($(date +%s)-START)),$cycle,$1,$2,$3,$4,$5,$6,$7,$8,$9,${10}" >> "$METRICS"; }
+
+echo "[soak] $CN for ${DURATION}s; metrics -> $METRICS"
+while [ "$(date +%s)" -lt "$DEADLINE" ]; do
+ cycle=$((cycle+1))
+ IFS='|' read -r hms hrc <<<"$(timed 'pinchtab health')"
+ IFS='|' read -r pms prc <<<"$(timed 'pinchtab title')"
+ tabs=$(tabcount); [ -z "$tabs" ] && tabs=0
+ cm=$(cmem); [ -z "$cm" ] && cm=0
+ chm=$(chromemem); [ -z "$chm" ] && chm=0
+ [ "${cm:-0}" -gt "$peakmem" ] 2>/dev/null && peakmem=$cm
+ [ "${tabs:-0}" -gt "$peaktabs" ] 2>/dev/null && peaktabs=$tabs
+ hok=$([ "$hrc" = 0 ] && echo 1 || echo 0); pok=$([ "$prc" = 0 ] && echo 1 || echo 0)
+ unresp=0; { [ "$hrc" != 0 ] || [ "$prc" != 0 ] || [ "${pms:-99999}" -gt 20000 ]; } && unresp=1
+
+ if [ "$unresp" = 1 ]; then
+ fails=$((fails+1)); [ -z "$firstbreak" ] && firstbreak="cycle $cycle @ $(($(date +%s)-START))s (tabs=$tabs,mem=${cm}MB)"
+ IFS='|' read -r rms rrc <<<"$(timed 'pinchtab server restart')"; sleep 6
+ IFS='|' read -r r2ms r2rc <<<"$(timed 'pinchtab title')"
+ if [ "$r2rc" = 0 ]; then recoveries=$((recoveries+1)); note="UNRESPONSIVE→RECOVERED(restart ${rms}ms,probe ${r2ms}ms)"; else failed_recoveries=$((failed_recoveries+1)); note="UNRESPONSIVE→RECOVERY-FAILED"; fi
+ log "probe" "$tabs" "$cm" "$chm" "$hms" "$hok" "$pms" "$pok" "recover" "$note"; continue
+ fi
+
+ r=$((RANDOM % 12)); action=""; note=""
+ if [ "$r" -lt 4 ]; then
+ u=${HEAVY[$((RANDOM%${#HEAVY[@]}))]}; nt=$([ $((RANDOM%2)) = 0 ] && echo --new-tab || echo ""); action="nav-heavy $nt"
+ IFS='|' read -r ams arc <<<"$(timed "pinchtab nav $u $nt")"; note="heavy ${ams}ms rc=$arc $u"
+ elif [ "$r" -lt 7 ]; then
+ u=${LIGHT[$((RANDOM%${#LIGHT[@]}))]}; action="nav-light"
+ IFS='|' read -r ams arc <<<"$(timed "pinchtab nav $u")"; note="light ${ams}ms rc=$arc"
+ elif [ "$r" -lt 9 ]; then
+ f=${FIXP[$((RANDOM%${#FIXP[@]}))]}; action="nav-fixture --new-tab"
+ IFS='|' read -r ams arc <<<"$(timed "pinchtab nav http://localhost:$FIX/$f --new-tab")"; note="fixture $f ${ams}ms rc=$arc"
+ elif [ "$r" -lt 10 ]; then
+ action="search"; IFS='|' read -r ams arc <<<"$(timed "pinchtab nav http://localhost:$FIX/serp.html && pinchtab text")"; note="search+extract ${ams}ms rc=$arc"
+ elif [ "$r" -lt 11 ]; then
+ if [ "$tabs" -gt 8 ]; then id=$(ex 'pinchtab tab --json' | grep -o '"id":"[^"]*"' | tail -1 | cut -d'"' -f4); ex "pinchtab close $id"; action="close-tab"; note="closed $id (tabs were $tabs)"; else action="extract"; IFS='|' read -r ams arc <<<"$(timed 'pinchtab snap')"; note="snap ${ams}ms rc=$arc"; fi
+ else
+ action="extract"; IFS='|' read -r ams arc <<<"$(timed 'pinchtab text')"; note="text ${ams}ms rc=$arc"
+ fi
+ log "load" "$tabs" "$cm" "$chm" "$hms" "$hok" "$pms" "$pok" "$action" "$note"
+
+ if [ $((cycle % 7)) = 0 ]; then
+ docker exec "$CN" python3 -c "import random;n=random.randint(8000,70000);open('/fixtures/heavy.html','w').write('<html><body><table>'+''.join(f'<tr><td>{i}</td><td>lorem {i}</td></tr>' for i in range(n))+'</table>'+'<div>x</div>'*random.randint(5000,30000)+'</body></html>')" 2>/dev/null
+ fi
+ if [ $((cycle % 10)) = 0 ]; then sleep $((120 + RANDOM % 120)); else sleep $((4 + RANDOM % 16)); fi
+done
+
+{
+ echo "PinchTab soak summary"
+ echo "duration: $(($(date +%s)-START))s cycles: $cycle"
+ echo "unresponsive events: $fails recovered: $recoveries recovery-failed: $failed_recoveries"
+ echo "peak container mem: ${peakmem}MB peak tabs: $peaktabs"
+ echo "first breaking point: ${firstbreak:-none (stable for full run)}"
+ echo "metrics: $METRICS"
+} | tee "$SUMMARY"