Skip to content

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

feat: silent-drop recovery + stealth-score measurement tooling

Luigi Agosti2b22982433fb
diff --git a/.gitignore b/.gitignore
index 4c8d51be..99d42467 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,3 +60,5 @@ tests/tools/browserbench/results/
/runner
tests/tools/scripts/runner
skills/agent-browser
+tests/stealth-score/results/
+tests/stealth-score/.tmp/
diff --git a/dev b/dev
index f097b1e1..398a7920 100755
--- a/dev
+++ b/dev
@@ -29,7 +29,7 @@ COMMANDS=(
"e2e:🐳:E2E suites (add --provider=chrome|cloak to swap browser; default chrome)"
" basic:🐳:Basic suite (api + cli + infra)"
" extended:🐳:Extended suite (all extended)"
- " smoke:🐳:Alias for smoke ci (CI-backed subset)"
+ " smoke:🐳:E2E smoke subset"
" smoke-plugin:🐳:OpenClaw plugin Docker smoke"
" api:🐳:API basic tests"
" cli:🐳:CLI basic tests"
@@ -39,10 +39,9 @@ COMMANDS=(
" cli-extended:🐳:CLI extended tests"
" infra-extended:🐳:Infra extended (multi-instance)"
" test <name>:🐳:Run a single E2E test by start_test name"
- "smoke:πŸ’¨:All local smoke checks (use --provider=chrome|cloak|all or filter names)"
- " ci:πŸ’¨:CI-backed smoke subset only"
- " cloakbrowser:πŸ’¨:Browser parity / CloakBrowser smoke"
- " cdp-attach:πŸ’¨:CDP attach smoke"
+ "smoke:πŸ’¨:Docker smoke checks (use --provider=chrome|cloak|all or filter names)"
+ " cloakbrowser:πŸ’¨:Docker browser parity / CloakBrowser smoke"
+ " cdp-attach:πŸ’¨:Docker CDP attach smoke"
" live-detection:πŸ’¨:Advisory live detection-site probe (external network)"
"opt:⚑:Optimization baseline"
" baseline:⚑:Run optimization baseline lane"
@@ -291,13 +290,15 @@ run_command() {
exec bash tests/manual/openclaw-plugin-smoke/run.sh "${smoke_args[@]}"
;;
"e2e smoke"|"e2e smoke "*)
- echo " ${ACCENT}${BOLD}🐳 E2E smoke moved to ./dev smoke ci${NC}"
+ echo " ${ACCENT}${BOLD}🐳 E2E smoke${NC}"
echo ""
- local -a smoke_args=()
+ local -a smoke_args=("smoke")
if [ "$target" != "e2e smoke" ]; then
- read -r -a smoke_args <<< "${target#e2e smoke }"
+ local -a extra_args=()
+ read -r -a extra_args <<< "${target#e2e smoke }"
+ smoke_args+=("${extra_args[@]}")
fi
- exec bash scripts/dev-smoke.sh ci "${smoke_args[@]}"
+ run_e2e_runner "${smoke_args[@]}"
;;
"e2e"*)
local -a e2e_args=()
@@ -462,9 +463,9 @@ if [ $# -gt 0 ]; then
e2e)
if [ "${2:-}" = "smoke" ]; then
echo ""
- echo " ${ACCENT}${BOLD}🐳 E2E smoke moved to ./dev smoke ci${NC}"
+ echo " ${ACCENT}${BOLD}🐳 E2E smoke${NC}"
echo ""
- exec bash scripts/dev-smoke.sh ci "${@:3}"
+ run_e2e_runner smoke "${@:3}"
fi
if [ "${2:-}" = "test" ]; then
if [ $# -lt 3 ] || [ -z "${3:-}" ]; then
diff --git a/internal/bridge/init.go b/internal/bridge/init.go
index 1eee3012..e44f5697 100644
--- a/internal/bridge/init.go
+++ b/internal/bridge/init.go
@@ -13,10 +13,11 @@ const popupGuardInitScript = stealth.PopupGuardInitScript
// InitChrome initializes a Chrome browser for a Bridge instance.
func InitChrome(cfg *config.RuntimeConfig, bundle *stealth.Bundle) (context.Context, context.CancelFunc, context.Context, context.CancelFunc, stealth.LaunchMode, error) {
return bridgeruntime.InitChrome(cfg, bundle, bridgeruntime.Hooks{
- SetHumanRandSeed: SetHumanRandSeed,
- IsChromeProfileLockError: isChromeProfileLockError,
- ClearStaleChromeProfile: clearStaleChromeProfileLock,
- ConfigureChromeProcessCmd: configureChromeProcess,
+ SetHumanRandSeed: SetHumanRandSeed,
+ IsChromeProfileLockError: isChromeProfileLockError,
+ ClearStaleChromeProfile: clearStaleChromeProfileLock,
+ ConfigureChromeProcessCmd: configureChromeProcess,
+ QuarantineCorruptedProfile: quarantineCorruptedProfile,
})
}
diff --git a/internal/bridge/profile_lock.go b/internal/bridge/profile_lock.go
index 2e7a65f7..068f0b0e 100644
--- a/internal/bridge/profile_lock.go
+++ b/internal/bridge/profile_lock.go
@@ -122,6 +122,31 @@ func clearStaleChromeProfileLock(profileDir, errMsg string) (bool, error) {
return removed, nil
}
+// quarantineCorruptedProfile renames profileDir to "<profileDir>.quarantine-<ts>"
+// and recreates an empty directory at the original path. Used to recover
+// from silent CDP attach failures where CloakBrowser refuses to ingest
+// existing profile state.
+func quarantineCorruptedProfile(profileDir string) (string, error) {
+ profileDir = strings.TrimSpace(profileDir)
+ if profileDir == "" {
+ return "", fmt.Errorf("empty profile dir")
+ }
+ if _, err := os.Stat(profileDir); err != nil {
+ if os.IsNotExist(err) {
+ return "", nil
+ }
+ return "", fmt.Errorf("stat profile dir: %w", err)
+ }
+ quarantinePath := fmt.Sprintf("%s.quarantine-%d", profileDir, time.Now().Unix())
+ if err := os.Rename(profileDir, quarantinePath); err != nil {
+ return "", fmt.Errorf("rename profile dir: %w", err)
+ }
+ if err := os.MkdirAll(profileDir, 0755); err != nil {
+ return quarantinePath, fmt.Errorf("recreate profile dir: %w", err)
+ }
+ return quarantinePath, nil
+}
+
func isProfileOwnedByRunningPinchtab(profileDir string) (bool, int) {
pidFile := filepath.Join(profileDir, "pinchtab.pid")
data, err := os.ReadFile(pidFile)
diff --git a/internal/bridge/profile_lock_test.go b/internal/bridge/profile_lock_test.go
index 8ec930c0..4c042e1c 100644
--- a/internal/bridge/profile_lock_test.go
+++ b/internal/bridge/profile_lock_test.go
@@ -4,10 +4,76 @@ import (
"os"
"path/filepath"
"reflect"
+ "strings"
"testing"
"time"
)
+func TestQuarantineCorruptedProfile(t *testing.T) {
+ t.Parallel()
+
+ tmp := t.TempDir()
+ profileDir := filepath.Join(tmp, "default")
+ if err := os.MkdirAll(filepath.Join(profileDir, "Default"), 0755); err != nil {
+ t.Fatalf("setup: %v", err)
+ }
+ marker := filepath.Join(profileDir, "Default", "Preferences")
+ if err := os.WriteFile(marker, []byte("original"), 0644); err != nil {
+ t.Fatalf("write marker: %v", err)
+ }
+
+ quarantinePath, err := quarantineCorruptedProfile(profileDir)
+ if err != nil {
+ t.Fatalf("quarantineCorruptedProfile: %v", err)
+ }
+ if quarantinePath == "" {
+ t.Fatal("expected non-empty quarantine path")
+ }
+ if !strings.HasPrefix(quarantinePath, profileDir+".quarantine-") {
+ t.Fatalf("quarantine path %q should start with %q.quarantine-", quarantinePath, profileDir)
+ }
+
+ // Original marker must live in the quarantined copy, not the new empty dir.
+ if _, err := os.Stat(filepath.Join(quarantinePath, "Default", "Preferences")); err != nil {
+ t.Fatalf("expected marker preserved in quarantine: %v", err)
+ }
+ if _, err := os.Stat(marker); !os.IsNotExist(err) {
+ t.Fatalf("expected fresh profile dir empty, but original marker still present: err=%v", err)
+ }
+
+ // Fresh profile dir must exist and be writable.
+ info, err := os.Stat(profileDir)
+ if err != nil {
+ t.Fatalf("expected recreated profile dir: %v", err)
+ }
+ if !info.IsDir() {
+ t.Fatalf("expected directory at %s", profileDir)
+ }
+}
+
+func TestQuarantineCorruptedProfile_MissingDir(t *testing.T) {
+ t.Parallel()
+
+ path, err := quarantineCorruptedProfile(filepath.Join(t.TempDir(), "does-not-exist"))
+ if err != nil {
+ t.Fatalf("missing dir should not error: %v", err)
+ }
+ if path != "" {
+ t.Fatalf("missing dir should return empty quarantine path, got %q", path)
+ }
+}
+
+func TestQuarantineCorruptedProfile_EmptyPath(t *testing.T) {
+ t.Parallel()
+
+ if _, err := quarantineCorruptedProfile(""); err == nil {
+ t.Fatal("expected error for empty profile dir")
+ }
+ if _, err := quarantineCorruptedProfile(" "); err == nil {
+ t.Fatal("expected error for blank profile dir")
+ }
+}
+
func TestIsChromeProfileLockError(t *testing.T) {
t.Parallel()
diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.go
index ee7525c4..1ddd32d6 100644
--- a/internal/bridge/runtime/init.go
+++ b/internal/bridge/runtime/init.go
@@ -46,6 +46,11 @@ type Hooks struct {
IsChromeProfileLockError func(string) bool
ClearStaleChromeProfile func(profileDir, errMsg string) (bool, error)
ConfigureChromeProcessCmd func(*exec.Cmd)
+ // QuarantineCorruptedProfile moves profileDir aside and recreates an
+ // empty dir at the same path. Used to recover from silent CDP attach
+ // failures (observed with CloakBrowser when the profile dir holds
+ // state it cannot ingest). Returns the quarantine path on success.
+ QuarantineCorruptedProfile func(profileDir string) (string, error)
}
// InitChrome initializes a Chrome browser for a Bridge instance.
@@ -251,10 +256,10 @@ func setupAllocator(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hoo
}
func startChrome(parentCtx context.Context, cfg *config.RuntimeConfig, bundle *stealth.Bundle, opts []chromedp.ExecAllocatorOption, debugPort int, hooks Hooks, geoAlignment launchGeoAlignment) (context.Context, context.CancelFunc, stealth.LaunchMode, error) {
- return startChromeWithRecovery(parentCtx, cfg, bundle, opts, debugPort, hooks, geoAlignment, false)
+ return startChromeWithRecovery(parentCtx, cfg, bundle, opts, debugPort, hooks, geoAlignment, false, false)
}
-func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfig, bundle *stealth.Bundle, opts []chromedp.ExecAllocatorOption, debugPort int, hooks Hooks, geoAlignment launchGeoAlignment, retriedProfileLock bool) (context.Context, context.CancelFunc, stealth.LaunchMode, error) {
+func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfig, bundle *stealth.Bundle, opts []chromedp.ExecAllocatorOption, debugPort int, hooks Hooks, geoAlignment launchGeoAlignment, retriedProfileLock, retriedProfileCorruption bool) (context.Context, context.CancelFunc, stealth.LaunchMode, error) {
allocCtx, allocCancel := chromedp.NewExecAllocator(parentCtx, opts...)
browserCtx, browserCancel := chromedp.NewContext(allocCtx)
@@ -266,6 +271,7 @@ func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfi
const chromeStartupTimeout = 20 * time.Second
type runResult struct{ err error }
runCh := make(chan runResult, 1)
+ startTs := time.Now()
go func() {
runCh <- runResult{chromedp.Run(browserCtx, chromedp.ActionFunc(func(ctx context.Context) error {
return nil
@@ -281,6 +287,8 @@ func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfi
}
if err != nil {
+ elapsed := time.Since(startTs)
+ silentDrop := isSilentCDPAttachFailure(cfg, err, parentCtx, browserCtx, elapsed)
browserCancel()
allocCancel()
errMsg := err.Error()
@@ -289,17 +297,35 @@ func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfi
if hooks.ClearStaleChromeProfile != nil {
if recovered, _ := hooks.ClearStaleChromeProfile(cfg.ProfileDir, errMsg); recovered {
time.Sleep(250 * time.Millisecond)
- return startChromeWithRecovery(parentCtx, cfg, bundle, opts, debugPort, hooks, geoAlignment, true)
+ return startChromeWithRecovery(parentCtx, cfg, bundle, opts, debugPort, hooks, geoAlignment, true, retriedProfileCorruption)
}
}
}
+ if silentDrop && !retriedProfileCorruption && hooks.QuarantineCorruptedProfile != nil && strings.TrimSpace(cfg.ProfileDir) != "" {
+ if quarantinePath, qerr := hooks.QuarantineCorruptedProfile(cfg.ProfileDir); qerr == nil {
+ slog.Warn("cloakbrowser silently dropped CDP attach; quarantined profile and retrying with fresh profile",
+ "originalProfile", cfg.ProfileDir,
+ "quarantinedTo", quarantinePath,
+ "elapsedMs", elapsed.Milliseconds())
+ time.Sleep(500 * time.Millisecond)
+ return startChromeWithRecovery(parentCtx, cfg, bundle, opts, debugPort, hooks, geoAlignment, retriedProfileLock, true)
+ } else {
+ slog.Warn("cloakbrowser silently dropped CDP attach; profile quarantine failed",
+ "originalProfile", cfg.ProfileDir,
+ "err", qerr.Error())
+ }
+ }
+
if shouldRetryChromeStartupWithDirectLaunch(parentCtx, err) && debugPort > 0 {
slog.Warn("chrome startup failed via allocator, trying direct-launch fallback", "port", debugPort, "error", errMsg)
time.Sleep(500 * time.Millisecond)
return startChromeWithRemoteAllocator(parentCtx, cfg, bundle, debugPort, bundle.Script, geoAlignment)
}
+ if silentDrop {
+ return nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to connect to chrome: %w (cloakbrowser dropped CDP attach silently after %dms; profile %q may be corrupted β€” try removing it or use a fresh profile)", err, elapsed.Milliseconds(), cfg.ProfileDir)
+ }
return nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to connect to chrome: %w", err)
}
@@ -325,6 +351,34 @@ func isStartupTimeout(err error) bool {
return strings.Contains(msg, "deadline exceeded") || strings.Contains(msg, "context deadline exceeded")
}
+// isSilentCDPAttachFailure detects the CloakBrowser-specific pattern where
+// Chrome accepts the launch, prints "DevTools listening", responds to the
+// initial Target.setDiscoverTargets, but then drops the websocket between
+// Target.attachToTarget and the reply β€” chromedp internally cancels the
+// browser context and chromedp.Run returns "context canceled" within a
+// few hundred milliseconds. Manifests when the profile dir holds state
+// CloakBrowser refuses to ingest.
+func isSilentCDPAttachFailure(cfg *config.RuntimeConfig, err error, parentCtx, browserCtx context.Context, elapsed time.Duration) bool {
+ if cfg == nil || !config.IsCloakBrowserProvider(cfg.BrowserProvider) {
+ return false
+ }
+ if err == nil {
+ return false
+ }
+ if parentCtx != nil && parentCtx.Err() != nil {
+ return false
+ }
+ if browserCtx == nil || browserCtx.Err() == nil {
+ return false
+ }
+ if !errors.Is(err, context.Canceled) && !strings.Contains(err.Error(), "context canceled") {
+ return false
+ }
+ // The silent drop is fast β€” chromedp cancels within ~1s. Any later
+ // failure is more likely a real timeout from a different cause.
+ return elapsed < 5*time.Second
+}
+
func shouldRetryChromeStartupWithDirectLaunch(parentCtx context.Context, err error) bool {
if isStartupTimeout(err) {
return true
diff --git a/internal/orchestrator/launch_target_config_test.go b/internal/orchestrator/launch_target_config_test.go
index c9c6d1c6..e510c3b9 100644
--- a/internal/orchestrator/launch_target_config_test.go
+++ b/internal/orchestrator/launch_target_config_test.go
@@ -3,6 +3,7 @@ package orchestrator
import (
"encoding/json"
"os"
+ "strings"
"testing"
"github.com/pinchtab/pinchtab/internal/config"
@@ -160,11 +161,11 @@ func TestWriteAttachChildConfigPreservesRuntimeModeAndEngine(t *testing.T) {
if fc.Security.Attach.Enabled == nil || *fc.Security.Attach.Enabled {
t.Errorf("Security.Attach.Enabled = %v, want false", fc.Security.Attach.Enabled)
}
- if len(fc.Security.Attach.AllowHosts) != 0 {
- t.Errorf("Security.Attach.AllowHosts = %v, want empty", fc.Security.Attach.AllowHosts)
+ if got := strings.Join(fc.Security.Attach.AllowHosts, ","); got != "*" {
+ t.Errorf("Security.Attach.AllowHosts = %q, want *", got)
}
- if len(fc.Security.Attach.AllowSchemes) != 0 {
- t.Errorf("Security.Attach.AllowSchemes = %v, want empty", fc.Security.Attach.AllowSchemes)
+ if got := strings.Join(fc.Security.Attach.AllowSchemes, ","); got != "http,ws" {
+ t.Errorf("Security.Attach.AllowSchemes = %q, want http,ws", got)
}
if fc.Security.Attach.ForwardProxyAuth == nil || *fc.Security.Attach.ForwardProxyAuth {
t.Errorf("Security.Attach.ForwardProxyAuth = %v, want false", fc.Security.Attach.ForwardProxyAuth)
diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.go
index ddd686ec..88b9b4f5 100644
--- a/internal/orchestrator/orchestrator.go
+++ b/internal/orchestrator/orchestrator.go
@@ -631,8 +631,12 @@ func (o *Orchestrator) writeAttachChildConfig(port, provider, stateDir string) (
fc.Observability.Activity.Enabled = &activityEnabled
fc.Browser.Provider = provider
attachDisabled := false
+ allowHosts := append([]string(nil), fc.Security.Attach.AllowHosts...)
+ allowSchemes := append([]string(nil), fc.Security.Attach.AllowSchemes...)
fc.Security.Attach = config.AttachConfig{
Enabled: &attachDisabled,
+ AllowHosts: allowHosts,
+ AllowSchemes: allowSchemes,
ForwardProxyAuth: &attachDisabled,
}
diff --git a/scripts/README.md b/scripts/README.md
index 09a9301e..2e3d0a3c 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -48,8 +48,7 @@ Development and CI scripts for PinchTab.
## `./dev` shortcuts
-- `./dev smoke ci` runs the CI-backed smoke subset through the Go e2e runner, including host Docker smoke checks.
-- `PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE=<image> ./dev smoke ci --filter release` skips the release-image build and runs the matching Docker smoke checks against the specified image tag.
-- `./dev smoke` runs all local smoke categories: CI smoke, browser parity, CDP attach, and live detection.
-- `./dev e2e --provider=cloak` runs the regular e2e suites against the prebuilt CloakBrowser provider image.
+- `./dev smoke` runs Docker smoke harnesses: browser parity, CDP attach, and live detection. The host shell remains the harness, but PinchTab and the browser under test run in containers.
+- `./dev e2e [suite]` runs E2E suites through the Go runner. The default provider is Chrome; pass `--provider=cloak` to run against CloakBrowser. The runner builds `pinchtab-cloakbrowser:test` from `tests/tools/docker/cloakbrowser-smoke.Dockerfile` unless `SKIP_BUILD=1` is set.
+- `PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE=<image> ./dev e2e smoke --filter release` skips the release-image build and runs the matching Docker smoke checks against the specified image tag.
- `./dev smoke cloakbrowser [--provider=chrome|cloak|all] [--multi-target|--profile-persistence|--profile-lock-recovery]` runs the specialized Chrome/CloakBrowser parity smoke via `scripts/docker-browser-parity-smoke.sh`. It builds the provider images from `tests/tools/docker/chrome-smoke.Dockerfile` and `tests/tools/docker/cloakbrowser-smoke.Dockerfile`; set `SKIP_BUILD=1` to require prebuilt images. The Cloak leg also honors `PINCHTAB_CLOAKBROWSER_E2E_SCENARIOS` for the scenario list.
diff --git a/scripts/dev-smoke.sh b/scripts/dev-smoke.sh
index 0e21c23c..28117b87 100644
--- a/scripts/dev-smoke.sh
+++ b/scripts/dev-smoke.sh
@@ -15,22 +15,19 @@ usage() {
cat <<'EOF'
Usage:
./dev smoke [--provider=chrome|cloak|all] [filter...]
- ./dev smoke ci [--provider=chrome|cloak] [--filter TEXT]
./dev smoke cdp-attach [chrome|cloak|all]
./dev smoke live-detection [--provider=chrome|cloak|all]
./dev smoke cloakbrowser [--provider=chrome|cloak|all] [special flags]
Filters:
- ci, e2e Run the CI-backed E2E smoke subset
cloakbrowser Run browser parity / CloakBrowser smoke
browser-parity Alias for cloakbrowser
cdp-attach Run CDP attach smoke
live-detection Run advisory live detection smoke
- docker, mcp, api... Passed to the E2E smoke runner as --filter
Defaults:
- ./dev smoke Runs all local smoke categories for all supported providers
- ./dev smoke ci Runs only the CI smoke subset, default provider chrome
+ ./dev smoke Runs Docker smoke categories for supported providers:
+ browser parity, CDP attach, and live detection
Special cloakbrowser flags:
--multi-target
@@ -40,13 +37,18 @@ EOF
}
provider=""
-ci_only=0
dry_run=0
logs="${E2E_LOGS:-hide}"
-e2e_filter=""
declare -a filters=()
declare -a parity_args=()
+e2e_smoke_error() {
+ echo "${ERROR}E2E smoke now lives under './dev e2e smoke'.${NC}" >&2
+ echo "${MUTED}Examples:${NC} ./dev e2e smoke --provider=chrome" >&2
+ echo "${MUTED} ${NC} ./dev e2e smoke --provider=cloak --filter recording" >&2
+ exit 1
+}
+
append_unique() {
local value="$1"
local existing
@@ -58,7 +60,7 @@ append_unique() {
is_named_smoke_filter() {
case "$1" in
- ci|ci-smoke|e2e|e2e-smoke|cloakbrowser|browser-parity|cdp-attach|live-detection)
+ cloakbrowser|browser-parity|cdp-attach|live-detection)
return 0
;;
*)
@@ -69,13 +71,6 @@ is_named_smoke_filter() {
append_smoke_filter() {
case "$1" in
- ci|ci-smoke)
- ci_only=1
- append_unique "e2e"
- ;;
- e2e|e2e-smoke)
- append_unique "e2e"
- ;;
cloakbrowser|browser-parity)
append_unique "browser-parity"
;;
@@ -83,7 +78,10 @@ append_smoke_filter() {
append_unique "$1"
;;
*)
- append_unique "$1"
+ echo "${ERROR}unknown smoke filter: $1${NC}" >&2
+ echo "${MUTED}Use './dev e2e smoke --filter $1' for E2E smoke filters.${NC}" >&2
+ usage >&2
+ exit 1
;;
esac
}
@@ -132,8 +130,7 @@ while [ "$#" -gt 0 ]; do
exit 0
;;
--ci)
- ci_only=1
- append_unique "e2e"
+ e2e_smoke_error
;;
--dry-run)
dry_run=1
@@ -179,11 +176,8 @@ while [ "$#" -gt 0 ]; do
usage >&2
exit 1
;;
- ci|ci-smoke)
- append_smoke_filter "$1"
- ;;
- e2e|e2e-smoke)
- append_smoke_filter "$1"
+ ci|ci-smoke|e2e|e2e-smoke)
+ e2e_smoke_error
;;
cloakbrowser|browser-parity)
append_smoke_filter "$1"
@@ -202,11 +196,7 @@ while [ "$#" -gt 0 ]; do
done
if [ -z "$provider" ]; then
- if [ "$ci_only" -eq 1 ]; then
- provider="chrome"
- else
- provider="all"
- fi
+ provider="all"
fi
case "$logs" in
@@ -246,13 +236,11 @@ run_step() {
return "$code"
}
-run_e2e_smoke() {
- local selected_provider="$1"
- local filter="${2:-}"
- local -a args=(go run ./tests/tools/runner e2e --suite smoke --provider "$selected_provider" --logs "$logs")
- [ "$dry_run" -eq 1 ] && args+=(--dry-run)
- [ -n "$filter" ] && args+=(--filter "$filter")
- run_step 0 "E2E smoke subset (${selected_provider}${filter:+, filter=${filter}})" "${args[@]}"
+run_browser_parity() {
+ local allow_skip="$1"
+ local selected_provider="$2"
+ run_step "$allow_skip" "Browser parity smoke (${selected_provider})" \
+ bash scripts/docker-browser-parity-smoke.sh "--provider=${selected_provider}" ${parity_args[@]+"${parity_args[@]}"}
}
run_cdp_attach() {
@@ -265,54 +253,29 @@ run_live_detection() {
run_step "$2" "Live detection smoke (${selected_provider})" bash scripts/docker-live-detection-smoke.sh --provider="$selected_provider"
}
-provider_list() {
- case "$1" in
- all) printf '%s\n' chrome cloak ;;
- *) printf '%s\n' "$1" ;;
- esac
-}
-
failures=0
run_or_record() {
"$@" || failures=1
}
-if [ "$ci_only" -eq 1 ]; then
- if [ "$provider" = "all" ]; then
- echo "${ERROR}./dev smoke ci accepts --provider=chrome|cloak, not all${NC}" >&2
- exit 1
- fi
- if [ "${#filters[@]}" -gt 0 ]; then
- for filter in "${filters[@]}"; do
- [ "$filter" = "e2e" ] && continue
- e2e_filter="$filter"
- done
- fi
- run_e2e_smoke "$provider" "$e2e_filter"
- exit $?
-fi
-
if [ "${#filters[@]}" -eq 0 ]; then
- # Full local smoke: run all categories. Browser parity runs before Cloak E2E
- # because it builds the local CloakBrowser smoke image when needed.
+ # Full Docker smoke excludes the Go E2E smoke subset. Run that explicitly via
+ # `./dev e2e smoke`, which keeps the provider smoke harnesses and E2E lanes
+ # separate.
case "$provider" in
chrome)
- run_or_record run_e2e_smoke chrome ""
- run_or_record run_step 1 "Browser parity smoke (chrome)" bash scripts/docker-browser-parity-smoke.sh --provider=chrome "${parity_args[@]}"
+ run_or_record run_browser_parity 1 chrome
run_or_record run_cdp_attach chrome 1
run_or_record run_live_detection chrome 1
;;
cloak)
- run_or_record run_step 1 "Browser parity smoke (cloak)" bash scripts/docker-browser-parity-smoke.sh --provider=cloak "${parity_args[@]}"
- run_or_record run_e2e_smoke cloak ""
+ run_or_record run_browser_parity 1 cloak
run_or_record run_cdp_attach cloak 1
run_or_record run_live_detection cloak 1
;;
all)
- run_or_record run_e2e_smoke chrome ""
- run_or_record run_step 1 "Browser parity smoke (all)" bash scripts/docker-browser-parity-smoke.sh --provider=all "${parity_args[@]}"
- run_or_record run_e2e_smoke cloak ""
+ run_or_record run_browser_parity 1 all
run_or_record run_cdp_attach all 1
run_or_record run_live_detection chrome 1
run_or_record run_live_detection cloak 1
@@ -321,13 +284,8 @@ if [ "${#filters[@]}" -eq 0 ]; then
else
for filter in "${filters[@]}"; do
case "$filter" in
- e2e)
- while IFS= read -r selected_provider; do
- run_or_record run_e2e_smoke "$selected_provider" ""
- done < <(provider_list "$provider")
- ;;
browser-parity)
- run_or_record run_step 0 "Browser parity smoke (${provider})" bash scripts/docker-browser-parity-smoke.sh --provider="$provider" "${parity_args[@]}"
+ run_or_record run_browser_parity 0 "$provider"
;;
cdp-attach)
run_or_record run_cdp_attach "$provider" 0
@@ -341,9 +299,9 @@ else
fi
;;
*)
- while IFS= read -r selected_provider; do
- run_or_record run_e2e_smoke "$selected_provider" "$filter"
- done < <(provider_list "$provider")
+ echo "${ERROR}unknown smoke filter: $filter${NC}" >&2
+ echo "${MUTED}Use './dev e2e smoke --filter $filter' for E2E smoke filters.${NC}" >&2
+ failures=1
;;
esac
done
diff --git a/scripts/docker-cdp-attach-smoke.sh b/scripts/docker-cdp-attach-smoke.sh
index 4cb1964e..270df774 100755
--- a/scripts/docker-cdp-attach-smoke.sh
+++ b/scripts/docker-cdp-attach-smoke.sh
@@ -3,12 +3,13 @@
#
# Two legs:
# 1. Chrome CDP attach β€” starts a Chromium headless container with remote
-# debugging enabled, runs the PinchTab server on the host, POSTs to
-# /instances/attach with provider=chrome, and asserts the bridge wraps it.
+# debugging enabled, starts PinchTab in Docker, POSTs to /instances/attach
+# with provider=chrome, and asserts the bridge wraps it.
# 2. CloakBrowser CDP attach β€” same as above but uses the local
# pinchtab-cloakbrowser:test image. Skipped if the image is unavailable.
#
-# This smoke is opt-in and is NOT part of default CI.
+# The host process is only the harness. PinchTab and the browser under test run
+# in Docker containers on a temporary Docker network.
#
# Usage:
# ./dev smoke cdp-attach # both legs
@@ -16,11 +17,12 @@
# ./dev smoke cdp-attach cloak # CloakBrowser leg only
#
# Env overrides:
-# PINCHTAB_BINARY Path to the pinchtab binary (default: ./dist/pinchtab or `go run`)
-# PINCHTAB_CDP_PORT Host port for the external CDP browser (default: 19222)
-# PINCHTAB_SERVER_PORT Host port for PinchTab server (default: 19867)
+# PINCHTAB_CDP_PORT Host port for external CDP readiness checks (default: 19222)
+# PINCHTAB_SERVER_PORT Host port for the PinchTab API container (default: 19867)
+# PINCHTAB_CDP_SMOKE_PINCHTAB_IMAGE PinchTab image (default: pinchtab-local:test)
# PINCHTAB_CDP_SMOKE_CHROME_IMAGE Chrome image (default: chromedp/headless-shell:stable)
# PINCHTAB_CDP_SMOKE_CLOAK_IMAGE CloakBrowser image (default: pinchtab-cloakbrowser:test)
+# SKIP_BUILD=1 Reuse existing PinchTab image; do not docker build
set -euo pipefail
@@ -31,27 +33,35 @@ LEG="${1:-all}"
CHROME_IMAGE="${PINCHTAB_CDP_SMOKE_CHROME_IMAGE:-chromedp/headless-shell:stable}"
CLOAK_IMAGE="${PINCHTAB_CDP_SMOKE_CLOAK_IMAGE:-pinchtab-cloakbrowser:test}"
+PINCHTAB_IMAGE="${PINCHTAB_CDP_SMOKE_PINCHTAB_IMAGE:-pinchtab-local:test}"
CDP_PORT="${PINCHTAB_CDP_PORT:-19222}"
SERVER_PORT="${PINCHTAB_SERVER_PORT:-19867}"
+PINCHTAB_CONTAINER_PORT="9867"
CLOAK_DEVTOOLS_PORT="9222"
CLOAK_FORWARD_PORT="9223"
+CHROME_ALIAS="chrome-cdp"
+CLOAK_ALIAS="cloak-cdp"
TOKEN="cdp-attach-smoke-${RANDOM}${RANDOM}"
TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pinchtab-cdp-attach.XXXXXX")"
CHROME_CONTAINER="pinchtab-cdp-smoke-chrome-${RANDOM}"
CLOAK_CONTAINER="pinchtab-cdp-smoke-cloak-${RANDOM}"
-PINCHTAB_PID=""
+PINCHTAB_CONTAINER="pinchtab-cdp-smoke-server-${RANDOM}"
+NETWORK="pinchtab-cdp-smoke-net-${RANDOM}"
+NETWORK_CREATED=0
FAILED=0
ATTACHED_INSTANCE_ID=""
+CDP_ATTACH_URL=""
+CDP_ATTACH_HOST=""
cleanup() {
set +e
- if [ -n "${PINCHTAB_PID}" ] && kill -0 "${PINCHTAB_PID}" 2>/dev/null; then
- kill "${PINCHTAB_PID}" 2>/dev/null || true
- wait "${PINCHTAB_PID}" 2>/dev/null || true
- fi
+ docker rm -f "${PINCHTAB_CONTAINER}" >/dev/null 2>&1 || true
docker rm -f "${CHROME_CONTAINER}" >/dev/null 2>&1 || true
docker rm -f "${CLOAK_CONTAINER}" >/dev/null 2>&1 || true
+ if [ "${NETWORK_CREATED}" -eq 1 ]; then
+ docker network rm "${NETWORK}" >/dev/null 2>&1 || true
+ fi
if [ "${FAILED}" -ne 0 ]; then
echo ""
echo "Artifacts kept at: ${TMP_DIR}"
@@ -80,29 +90,18 @@ require_cmd docker
require_cmd curl
require_cmd jq
-BIN="${PINCHTAB_BINARY:-}"
-if [ -z "${BIN}" ]; then
- if [ -x "${ROOT}/dist/pinchtab" ]; then
- BIN="${ROOT}/dist/pinchtab"
- else
- echo "Building pinchtab binary…"
- (cd "${ROOT}" && go build -o "${TMP_DIR}/pinchtab" ./cmd/pinchtab)
- BIN="${TMP_DIR}/pinchtab"
- fi
-fi
-[ -x "${BIN}" ] || fail "pinchtab binary not executable at ${BIN}"
-
CONFIG_FILE="${TMP_DIR}/config.json"
write_config() {
local provider="$1" binary="${2:-}"
cat > "${CONFIG_FILE}" <<EOF
{
- "server": { "port": "${SERVER_PORT}", "bind": "127.0.0.1", "token": "${TOKEN}" },
+ "server": { "port": "${PINCHTAB_CONTAINER_PORT}", "bind": "0.0.0.0", "token": "${TOKEN}", "stateDir": "/data" },
"browser": { "provider": "${provider}", "binary": "${binary}" },
+ "multiInstance": { "strategy": "explicit" },
"security": {
"attach": {
"enabled": true,
- "allowHosts": ["127.0.0.1", "localhost", "::1"],
+ "allowHosts": ["${CDP_ATTACH_HOST}", "${CHROME_ALIAS}", "${CLOAK_ALIAS}", "127.0.0.1", "localhost", "::1"],
"allowSchemes": ["ws", "http"]
}
}
@@ -110,6 +109,33 @@ write_config() {
EOF
}
+ensure_pinchtab_image() {
+ if [ "${SKIP_BUILD:-}" = "1" ]; then
+ if docker image inspect "${PINCHTAB_IMAGE}" >/dev/null 2>&1; then
+ echo "Reusing existing PinchTab image: ${PINCHTAB_IMAGE} (SKIP_BUILD=1)"
+ return
+ fi
+ skip "PinchTab image '${PINCHTAB_IMAGE}' not found and SKIP_BUILD=1 is set"
+ fi
+ echo "Building PinchTab image: ${PINCHTAB_IMAGE}"
+ docker build -t "${PINCHTAB_IMAGE}" "${ROOT}"
+}
+
+ensure_network() {
+ if [ "${NETWORK_CREATED}" -eq 1 ]; then
+ return
+ fi
+ docker network create "${NETWORK}" >/dev/null
+ NETWORK_CREATED=1
+}
+
+container_ip() {
+ local name="$1" ip
+ ip="$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "${name}")"
+ [ -n "${ip}" ] || fail "could not resolve Docker IP for ${name}"
+ printf '%s\n' "${ip}"
+}
+
wait_http() {
local url="$1" tries="${2:-60}"
for _ in $(seq 1 "${tries}"); do
@@ -140,23 +166,31 @@ api_get() {
}
start_pinchtab() {
- echo ">>> Starting PinchTab server on :${SERVER_PORT}"
- PINCHTAB_TOKEN="${TOKEN}" PINCHTAB_CONFIG="${CONFIG_FILE}" \
- "${BIN}" server >"${TMP_DIR}/pinchtab.log" 2>&1 &
- PINCHTAB_PID=$!
+ local provider="$1"
+ echo ">>> Starting PinchTab server container on host :${SERVER_PORT}"
+ docker rm -f "${PINCHTAB_CONTAINER}" >/dev/null 2>&1 || true
+ docker run -d --rm --name "${PINCHTAB_CONTAINER}" \
+ --network "${NETWORK}" \
+ --user 1000:1000 \
+ --shm-size=2g \
+ -p "127.0.0.1:${SERVER_PORT}:${PINCHTAB_CONTAINER_PORT}" \
+ -e "PINCHTAB_TOKEN=${TOKEN}" \
+ -e "PINCHTAB_CONFIG=/config/config.json" \
+ -v "${CONFIG_FILE}:/config/config.json:ro" \
+ --tmpfs /tmp:rw,nosuid,nodev,size=512m,mode=1777 \
+ --tmpfs /data:rw,nosuid,nodev,size=1024m,uid=1000,gid=1000,mode=0755 \
+ "${PINCHTAB_IMAGE}" \
+ >/dev/null
if ! wait_api_http "http://127.0.0.1:${SERVER_PORT}/health" 60; then
- cat "${TMP_DIR}/pinchtab.log" || true
+ docker logs "${PINCHTAB_CONTAINER}" >"${TMP_DIR}/pinchtab-${provider}.log" 2>&1 || true
+ cat "${TMP_DIR}/pinchtab-${provider}.log" || true
fail "PinchTab server did not become healthy"
fi
- echo " pinchtab pid=${PINCHTAB_PID}"
+ echo " container=${PINCHTAB_CONTAINER}"
}
stop_pinchtab() {
- if [ -n "${PINCHTAB_PID}" ] && kill -0 "${PINCHTAB_PID}" 2>/dev/null; then
- kill "${PINCHTAB_PID}" 2>/dev/null || true
- wait "${PINCHTAB_PID}" 2>/dev/null || true
- fi
- PINCHTAB_PID=""
+ docker rm -f "${PINCHTAB_CONTAINER}" >/dev/null 2>&1 || true
}
assert_attached_instance() {
@@ -164,7 +198,7 @@ assert_attached_instance() {
local resp http
resp="$(api_post /instances/attach "$(jq -nc \
--arg name "${name}" \
- --arg url "http://127.0.0.1:${CDP_PORT}" \
+ --arg url "${CDP_ATTACH_URL}" \
--arg provider "${provider}" \
'{name:$name, cdpUrl:$url, provider:$provider}')")"
echo " /instances/attach response: ${resp}" >&2
@@ -200,9 +234,14 @@ run_chrome_leg() {
echo ""
echo "=== Chrome CDP attach leg ==="
+ ensure_pinchtab_image
+ ensure_network
+
echo ">>> Starting Chromium container on :${CDP_PORT}"
local -a docker_args=(
docker run -d --rm --name "${CHROME_CONTAINER}"
+ --network "${NETWORK}"
+ --network-alias "${CHROME_ALIAS}"
-p "127.0.0.1:${CDP_PORT}:9222" \
"${CHROME_IMAGE}"
)
@@ -229,8 +268,11 @@ run_chrome_leg() {
fail "Chromium DevTools not reachable on :${CDP_PORT}"
fi
+ CDP_ATTACH_HOST="$(container_ip "${CHROME_CONTAINER}")"
+ CDP_ATTACH_URL="http://${CDP_ATTACH_HOST}:9222"
+
write_config "chrome"
- start_pinchtab
+ start_pinchtab "chrome"
ATTACHED_INSTANCE_ID=""
assert_attached_instance "smoke-chrome" "chrome"
local inst_id="${ATTACHED_INSTANCE_ID}"
@@ -252,6 +294,8 @@ run_chrome_leg() {
run_cloak_leg() {
echo ""
echo "=== CloakBrowser CDP attach leg ==="
+ ensure_pinchtab_image
+ ensure_network
if ! docker image inspect "${CLOAK_IMAGE}" >/dev/null 2>&1; then
skip "CloakBrowser image '${CLOAK_IMAGE}' not present β€” build with tests/tools/docker/cloakbrowser-smoke.Dockerfile to enable"
fi
@@ -261,6 +305,8 @@ run_cloak_leg() {
echo ">>> Starting CloakBrowser container on :${CDP_PORT}"
docker run -d --rm --name "${CLOAK_CONTAINER}" \
+ --network "${NETWORK}" \
+ --network-alias "${CLOAK_ALIAS}" \
-p "127.0.0.1:${CDP_PORT}:${CLOAK_FORWARD_PORT}" \
-e CLOAK_DEVTOOLS_PORT="${CLOAK_DEVTOOLS_PORT}" \
-e CLOAK_FORWARD_PORT="${CLOAK_FORWARD_PORT}" \
@@ -294,8 +340,11 @@ run_cloak_leg() {
fail "CloakBrowser DevTools not reachable on :${CDP_PORT}"
fi
+ CDP_ATTACH_HOST="$(container_ip "${CLOAK_CONTAINER}")"
+ CDP_ATTACH_URL="http://${CDP_ATTACH_HOST}:${CLOAK_FORWARD_PORT}"
+
write_config "cloak" "/opt/cloakbrowser/chrome"
- start_pinchtab
+ start_pinchtab "cloak"
ATTACHED_INSTANCE_ID=""
assert_attached_instance "smoke-cloak" "cloak"
local inst_id="${ATTACHED_INSTANCE_ID}"
diff --git a/skills/pinchtab-stealth-score/SKILL.md b/skills/pinchtab-stealth-score/SKILL.md
new file mode 100644
index 00000000..bd0df5f6
--- /dev/null
+++ b/skills/pinchtab-stealth-score/SKILL.md
@@ -0,0 +1,222 @@
+---
+name: pinchtab-stealth-score
+description: "Run the PinchTab stealth-score sweep against 15 bot-detection / fingerprint sites (sannysoft, rebrowser, deviceandbrowserinfo, iphey, whoer, browserscan, pixelscan, fingerprint-scan, incolumitas, fvision, amiunique, browserleaks, creepjs, coveryourtracks, fingerprint-demo). Starts a Docker PinchTab container per provider (chrome / cloak / both), spawns a blind agent that drives PinchTab through plain-English per-site playbooks, captures structured metrics, prints a side-by-side comparison highlighting divergent metrics, and appends to history.jsonl for cross-session tracking. Use when asked to 'run stealth score', 'compare cloak vs chrome detection', 'measure stealth', or '/pinchtab-stealth-score'."
+---
+
+# PinchTab Stealth Score
+
+Drive PinchTab through a list of public bot-detection sites under each browser
+provider (`chrome`, `cloak`, or `both`), and collect the metrics that matter
+most for analyst comparison. The Docker plumbing rebuilds the PinchTab image
+from current source so you're benchmarking the working tree.
+
+The shape is the same as `/pinchtab-opt`: one container per run, one blind
+agent that reads English playbooks and drives PinchTab through `./scripts/pt`,
+records per-site metrics, and the orchestrator summarizes.
+
+## Argument Parsing
+
+- `/pinchtab-stealth-score` β†’ default to `both`
+- `/pinchtab-stealth-score chrome` β†’ chrome only
+- `/pinchtab-stealth-score cloak` β†’ cloak only
+- `/pinchtab-stealth-score both` β†’ run both sequentially
+
+Anything else β†’ print this section and abort.
+
+## Site Catalogue
+
+The agent processes the sites listed in `tests/stealth-score/sites/index.md`
+(currently 15). The list is dynamic β€” to add or remove sites you only edit
+that index and the matching `<id>.md` playbook. The skill itself doesn't hard-
+code site names.
+
+Current sites (15) β€” `sannysoft`, `rebrowser`, `deviceandbrowserinfo`, `iphey`,
+`whoer`, `browserscan`, `pixelscan`, `fingerprint-scan`, `incolumitas`,
+`fvision`, `amiunique`, `browserleaks` (multi-page: canvas+webgl+fonts+tls),
+`creepjs`, `coveryourtracks`, `fingerprint-demo`.
+
+Expected duration: ~12-15 min per provider once images are cached, so a `both`
+run takes ~25-30 min plus first-time image build (~10 min for cloak).
+
+## Path Resolution
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+SCORE_DIR="$PROJECT_ROOT/tests/stealth-score"
+RESULTS_DIR="$SCORE_DIR/results"
+TIMESTAMP=$(date -u +%Y%m%dT%H%M%SZ)
+mkdir -p "$RESULTS_DIR"
+```
+
+## Prerequisites
+
+Docker must be running.
+
+```bash
+docker info >/dev/null 2>&1 || { echo "Docker not running"; exit 1; }
+```
+
+If port 9867 on the host is already taken (e.g. a native PinchTab server), free
+it first β€” both the chrome and cloak containers bind 9867:
+
+```bash
+pinchtab daemon stop 2>&1 || true
+sleep 2
+pkill -9 -f "pinchtab " 2>/dev/null || true
+```
+
+## Execution
+
+For each requested provider, run the same loop:
+
+### 1. Bring up the container
+
+```bash
+"$SCORE_DIR/up.sh" "$PROVIDER"
+```
+
+`up.sh` builds the appropriate image if absent (chrome-smoke or cloakbrowser),
+writes a provider config with open `allowedDomains`, and starts a container
+named `stealth-score-pinchtab` on host port 9867. It exits non-zero if the
+container fails to become healthy.
+
+To force a rebuild: `REBUILD=1 "$SCORE_DIR/up.sh" "$PROVIDER"`.
+
+### 2. Seed the report JSON
+
+```bash
+REPORT_FILE="$RESULTS_DIR/${PROVIDER}_${TIMESTAMP}.json"
+cat > "$REPORT_FILE" <<JSON
+{
+ "provider": "${PROVIDER}",
+ "timestamp": "${TIMESTAMP}",
+ "started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+ "completed_at": null,
+ "sites_processed": 0,
+ "sites": []
+}
+JSON
+```
+
+### 3. Spawn the agent
+
+Use the **Agent** tool. Prompt template β€” replace `{PROVIDER}`, `{REPORT_FILE}`,
+`{PROJECT_ROOT}`:
+
+```
+You are running a PinchTab stealth-score sweep against a Docker container.
+
+PROVIDER: {PROVIDER}
+REPORT_FILE: {REPORT_FILE}
+PROJECT_ROOT: {PROJECT_ROOT}
+
+Read these files first (do NOT read anything under tests/stealth-score/results/):
+1. {PROJECT_ROOT}/tests/stealth-score/subagent-context.md β€” environment, wrapper, recording format.
+2. {PROJECT_ROOT}/tests/stealth-score/sites/index.md β€” list of sites to process and in what order.
+3. {PROJECT_ROOT}/skills/pinchtab/SKILL.md β€” PinchTab command reference.
+
+The site list currently has ~15 entries. Work through them in the order index.md gives. For each site:
+- Read its playbook (sites/<id>.md). It describes what to navigate to, what to wait for, any clicks needed, and which metrics to capture.
+- Drive PinchTab through the {PROJECT_ROOT}/tests/tools/scripts/pt wrapper. Before any pt call: cd {PROJECT_ROOT}/tests/tools and export PINCHTAB_CONTAINER=stealth-score-pinchtab and PINCHTAB_TOKEN=stealth-score-token.
+- Extract the listed metrics from what you actually observe on the page. Capture as many of the listed metrics as you can find β€” partial captures are fine; record "unavailable" plus a brief reason when a metric isn't present.
+- Append a JSON record to REPORT_FILE per the recording format in subagent-context.md.
+
+Time-box each site to ~2 minutes. If a site is slow, hangs, or shows a Cloudflare challenge, record what you have, set notes accordingly, and move on.
+
+Finalize the report (set completed_at + sites_processed) and print STEALTH_SCORE_RUN_COMPLETE on stdout as your final line.
+
+The container is already running and healthy. Do NOT touch Docker, do NOT switch providers, do NOT run `pinchtab server` or `daemon` β€” the wrapper talks to the container directly.
+```
+
+### 4. Tear down
+
+```bash
+"$SCORE_DIR/down.sh"
+```
+
+When both providers are requested, run **sequentially**: up β†’ agent β†’ down for
+chrome, then up β†’ agent β†’ down for cloak. They share port 9867.
+
+## Summarize
+
+After all per-provider JSON reports exist, build the side-by-side comparison
+using the Go runner:
+
+```bash
+"$PROJECT_ROOT/tests/tools/scripts/runner" stealth compare \
+ "$RESULTS_DIR"/*_${TIMESTAMP}.json
+```
+
+If the `runner` binary isn't built yet (it's gitignored β€” built on demand by `./dev`):
+
+```bash
+go build -o "$PROJECT_ROOT/tests/tools/scripts/runner" \
+ ./tests/tools/runner
+```
+
+The summarizer:
+
+1. Prints a markdown comparison: headline counts, a **divergent-metrics** table
+ (only rows where chrome and cloak disagree on real values), and per-site
+ tables for every metric captured by either provider. Pipe directly to the user.
+2. Appends one JSON line to `tests/stealth-score/history.jsonl` per
+ comparison run (run id, providers, sites count, divergence count, list of
+ divergent metrics). The file is kept in the repo so multi-session history
+ survives.
+3. Regenerates `tests/stealth-score/history.md` β€” last-20-runs table view.
+
+Present the markdown table to the user as-is. Mention the history files
+when reporting so the user knows where to look for trends.
+
+## Output Layout
+
+```
+tests/stealth-score/
+β”œβ”€β”€ up.sh # boot docker container per provider
+β”œβ”€β”€ down.sh # tear down docker container
+β”œβ”€β”€ sites/
+β”‚ β”œβ”€β”€ index.md # ordered list of sites to process
+β”‚ β”œβ”€β”€ sannysoft.md # static table β€” webdriver/permissions/webgl rows
+β”‚ β”œβ”€β”€ rebrowser.md # puppeteer/playwright leak probes
+β”‚ β”œβ”€β”€ deviceandbrowserinfo.md # bot/human verdict + suspicious signals
+β”‚ β”œβ”€β”€ iphey.md # reliability badge, proxy/VPN/DNS leak flags
+β”‚ β”œβ”€β”€ whoer.md # anonymity %, proxy/VPN, browser consistency
+β”‚ β”œβ”€β”€ browserscan.md # bot-detection per-test rows + IP + canvas + webrtc
+β”‚ β”œβ”€β”€ pixelscan.md # bot score + automation flags (needs click)
+β”‚ β”œβ”€β”€ fingerprint-scan.md # bot risk score, automation flags
+β”‚ β”œβ”€β”€ incolumitas.md # behavioural + TLS/JA3 + WebRTC + proxy
+β”‚ β”œβ”€β”€ fvision.md # fv.pro privacy/leak summary
+β”‚ β”œβ”€β”€ amiunique.md # per-attribute uniqueness ratios
+β”‚ β”œβ”€β”€ browserleaks.md # multi-nav: /canvas + /webgl + /fonts + /tls
+β”‚ β”œβ”€β”€ creepjs.md # heavy JS suite; trust score + fingerprint hashes
+β”‚ β”œβ”€β”€ coveryourtracks.md # EFF tracking-resistance (needs button click)
+β”‚ └── fingerprint-demo.md # FingerprintJS commercial demo
+β”œβ”€β”€ subagent-context.md # blind agent's environment + recording format
+β”œβ”€β”€ history.jsonl # one-line summary per comparison run (kept in repo)
+β”œβ”€β”€ history.md # last-20 runs rendered table (regenerated each run)
+β”œβ”€β”€ .tmp/ # gitignored; per-provider configs written by up.sh
+└── results/ # gitignored; <provider>_<ts>.json per run
+```
+
+## Adding or Removing Sites
+
+1. Create `tests/stealth-score/sites/<id>.md` from the existing playbooks. Keep
+ the structure: URL β†’ readiness signal β†’ steps β†’ metrics table β†’ gotchas.
+2. Add the new id to `tests/stealth-score/sites/index.md` in the order you
+ want it processed.
+
+That's it. No code change. The agent reads the index fresh every run.
+
+## Notes
+
+- This is **advisory**, not a CI gate. A non-zero detection score on cloak
+ that matches chrome's baseline is a generic Chromium signal, not a
+ CloakBrowser regression.
+- Heavy SPA detection pages (creepjs, browserscan) take 20-40 s to settle.
+ The playbooks use `wait --text` for the actual readiness signal so the
+ agent doesn't read mid-load placeholders. If a page is still loading after
+ the playbook's recommended waits, the agent should record `"unavailable"`
+ for affected metrics and explain in `notes` β€” don't paper over it with
+ guesses.
+- The Docker container exposes PinchTab on 9867. The `./scripts/pt` wrapper
+ reads `PINCHTAB_CONTAINER` env to know which container to exec into.
diff --git a/tests/stealth-score/down.sh b/tests/stealth-score/down.sh
new file mode 100755
index 00000000..18f46265
--- /dev/null
+++ b/tests/stealth-score/down.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# tests/stealth-score/down.sh β€” tear down the stealth-score docker container.
+set -euo pipefail
+docker rm -f stealth-score-pinchtab >/dev/null 2>&1 || true
+echo "stealth-score-pinchtab removed"
diff --git a/tests/stealth-score/history.jsonl b/tests/stealth-score/history.jsonl
new file mode 100644
index 00000000..73b52536
--- /dev/null
+++ b/tests/stealth-score/history.jsonl
@@ -0,0 +1,2 @@
+{"run_id": "20260520T114255Z", "appended_at": "2026-05-20T11:55:11Z", "providers": ["chrome", "cloak"], "sites_total": 6, "captured": {"chrome": 6, "cloak": 6}, "divergences": 11, "divergent_metrics": [{"site": "sannysoft", "metric": "languages"}, {"site": "sannysoft", "metric": "webgl_renderer"}, {"site": "sannysoft", "metric": "webgl_vendor"}, {"site": "browserscan", "metric": "hardware_concurrency"}, {"site": "browserscan", "metric": "robot_verdict"}, {"site": "browserscan", "metric": "ua_browser"}, {"site": "pixelscan", "metric": "automation_flags"}, {"site": "creepjs", "metric": "fingerprint_id"}, {"site": "amiunique", "metric": "attributes_count"}, {"site": "amiunique", "metric": "similarity_ratio"}, {"site": "amiunique", "metric": "uniqueness_verdict"}]}
+{"run_id": "20260520T125839Z", "appended_at": "2026-05-20T13:23:22Z", "providers": ["chrome", "cloak"], "sites_total": 15, "captured": {"chrome": 15, "cloak": 15}, "divergences": 85, "divergent_metrics": [{"site": "sannysoft", "metric": "audio_codecs"}, {"site": "sannysoft", "metric": "languages"}, {"site": "sannysoft", "metric": "media_devices"}, {"site": "sannysoft", "metric": "permissions_state"}, {"site": "sannysoft", "metric": "user_agent"}, {"site": "sannysoft", "metric": "video_codecs"}, {"site": "sannysoft", "metric": "webgl_renderer"}, {"site": "sannysoft", "metric": "webgl_vendor"}, {"site": "rebrowser", "metric": "dummy_function"}, {"site": "rebrowser", "metric": "expose_function_leak"}, {"site": "rebrowser", "metric": "main_world_execution"}, {"site": "rebrowser", "metric": "pw_init_scripts"}, {"site": "rebrowser", "metric": "source_url_leak"}, {"site": "rebrowser", "metric": "viewport"}, {"site": "deviceandbrowserinfo", "metric": "bot_activity_verdict"}, {"site": "deviceandbrowserinfo", "metric": "mouse_behaviour"}, {"site": "deviceandbrowserinfo", "metric": "suspicious_signals"}, {"site": "deviceandbrowserinfo", "metric": "user_agent_check"}, {"site": "deviceandbrowserinfo", "metric": "weak_fingerprint_flag"}, {"site": "iphey", "metric": "digital_identity_consistency"}, {"site": "whoer", "metric": "anonymity_score_pct"}, {"site": "whoer", "metric": "dns"}, {"site": "whoer", "metric": "ip_country"}, {"site": "whoer", "metric": "proxy_detected"}, {"site": "whoer", "metric": "timezone"}, {"site": "whoer", "metric": "vpn_detected"}, {"site": "whoer", "metric": "webrtc_leak"}, {"site": "browserscan", "metric": "hardware_concurrency"}, {"site": "browserscan", "metric": "native_user_agent"}, {"site": "browserscan", "metric": "ua_browser"}, {"site": "pixelscan", "metric": "automation_flags"}, {"site": "pixelscan", "metric": "bot_score"}, {"site": "pixelscan", "metric": "cdp"}, {"site": "pixelscan", "metric": "user_agent"}, {"site": "pixelscan", "metric": "webdriver_value"}, {"site": "fingerprint-scan", "metric": "automation_flags"}, {"site": "fingerprint-scan", "metric": "bot_risk_score"}, {"site": "fingerprint-scan", "metric": "browser_signature"}, {"site": "fingerprint-scan", "metric": "fingerprint_id"}, {"site": "incolumitas", "metric": "asn"}, {"site": "incolumitas", "metric": "behavioural_score"}, {"site": "incolumitas", "metric": "canvas_fingerprint"}, {"site": "incolumitas", "metric": "challenge_verdict"}, {"site": "incolumitas", "metric": "navigator_anomalies"}, {"site": "incolumitas", "metric": "proxy_vpn_datacenter"}, {"site": "incolumitas", "metric": "tcp_ip_fingerprint"}, {"site": "incolumitas", "metric": "tls_fingerprint"}, {"site": "incolumitas", "metric": "webrtc_leaks"}, {"site": "fvision", "metric": "automation_indicators"}, {"site": "fvision", "metric": "browser"}, {"site": "fvision", "metric": "canvas_leak"}, {"site": "fvision", "metric": "fonts_leak"}, {"site": "fvision", "metric": "ip_country"}, {"site": "fvision", "metric": "isp"}, {"site": "fvision", "metric": "platform"}, {"site": "fvision", "metric": "privacy_score"}, {"site": "fvision", "metric": "resolution"}, {"site": "fvision", "metric": "timezone"}, {"site": "fvision", "metric": "webgl_leak"}, {"site": "amiunique", "metric": "attributes_count"}, {"site": "amiunique", "metric": "http_headers_distinct"}, {"site": "amiunique", "metric": "js_attributes_count"}, {"site": "amiunique", "metric": "language_uniqueness"}, {"site": "amiunique", "metric": "similarity_ratio"}, {"site": "amiunique", "metric": "uniqueness_verdict"}, {"site": "browserleaks", "metric": "canvas_signature"}, {"site": "browserleaks", "metric": "canvas_uniqueness"}, {"site": "browserleaks", "metric": "fonts_count"}, {"site": "browserleaks", "metric": "tls_ja3"}, {"site": "browserleaks", "metric": "tls_ja4_o"}, {"site": "browserleaks", "metric": "webgl_image_hash"}, {"site": "browserleaks", "metric": "webgl_renderer"}, {"site": "browserleaks", "metric": "webgl_report_hash"}, {"site": "browserleaks", "metric": "webgl_vendor"}, {"site": "creepjs", "metric": "canvas_hash"}, {"site": "creepjs", "metric": "fingerprint_id"}, {"site": "creepjs", "metric": "fonts_count"}, {"site": "creepjs", "metric": "timezone"}, {"site": "creepjs", "metric": "trust_score"}, {"site": "coveryourtracks", "metric": "fingerprint_uniqueness_pct"}, {"site": "coveryourtracks", "metric": "fingerprinting_resistance"}, {"site": "coveryourtracks", "metric": "invisible_tracker_protection"}, {"site": "coveryourtracks", "metric": "tracker_protection"}, {"site": "fingerprint-demo", "metric": "bot_likelihood"}, {"site": "fingerprint-demo", "metric": "visitor_id"}]}
diff --git a/tests/stealth-score/history.md b/tests/stealth-score/history.md
new file mode 100644
index 00000000..564a6ff4
--- /dev/null
+++ b/tests/stealth-score/history.md
@@ -0,0 +1,6 @@
+# Stealth Score β€” History (last 2 runs)
+
+| run_id | providers | sites | divergences | divergent metrics |
+|---|---|---|---|---|
+| `20260520T125839Z` | chrome, cloak | 15 | 85 | sannysoft/audio_codecs; sannysoft/languages; sannysoft/media_devices; sannysoft/permissions_state; sannysoft/user_agent (+80 more) |
+| `20260520T114255Z` | chrome, cloak | 6 | 11 | sannysoft/languages; sannysoft/webgl_renderer; sannysoft/webgl_vendor; browserscan/hardware_concurrency; browserscan/robot_verdict (+6 more) |
diff --git a/tests/stealth-score/sites/amiunique.md b/tests/stealth-score/sites/amiunique.md
new file mode 100644
index 00000000..7f6a7a81
--- /dev/null
+++ b/tests/stealth-score/sites/amiunique.md
@@ -0,0 +1,37 @@
+# amiunique β€” AmIUnique Fingerprint Report
+
+**URL**: https://amiunique.org/fingerprint
+
+AmIUnique computes a fingerprint and reports how unique it is across observed
+browsers. The page is divided into JS attributes and HTTP-header attributes β€”
+both must render before the uniqueness verdict appears.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://amiunique.org/fingerprint --new-tab --print-tab-id`.
+2. **Wait for the uniqueness verdict** β€” `wait --text "Almost"` or `wait --text "fingerprint"` (timeout 30 s).
+3. **Read** β€” `text` first. If the JS-attributes section still says "No data available", `wait 5000` and retry; that section sometimes lags.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| uniqueness_verdict | "Almost! Only N browsers..." / "Yes! You are unique" / "shared" |
+| similarity_ratio | "1 in N" ratio or percentage |
+| attributes_count | number of attributes reported in the JS+HTTP tables |
+| js_attributes_count | number of JS-collected attributes (or "unavailable") |
+| http_attributes_count | number of HTTP-collected attributes |
+| http_headers_distinct | true/false β€” HTTP headers flagged as distinct |
+| user_agent_uniqueness | User-Agent attribute similarity ratio |
+| accept_header_uniqueness | Accept header similarity ratio |
+| language_uniqueness | Accept-Language similarity ratio |
+| fonts_uniqueness | Fonts attribute similarity ratio (JS section) |
+| canvas_uniqueness | Canvas attribute similarity ratio |
+| webgl_uniqueness | WebGL attribute similarity ratio |
+| screen_resolution | screen dimensions reported |
+| timezone | reported timezone |
+
+## Common gotchas
+
+- If the JS attributes section permanently shows "No data available" β€” that's a fingerprintable signal in itself (means the browser blocked the data export). Record `attributes_count` as the HTTP-only count and put a note about the JS section.
diff --git a/tests/stealth-score/sites/browserleaks.md b/tests/stealth-score/sites/browserleaks.md
new file mode 100644
index 00000000..d19be5be
--- /dev/null
+++ b/tests/stealth-score/sites/browserleaks.md
@@ -0,0 +1,57 @@
+# browserleaks β€” BrowserLeaks Multi-Probe
+
+**URLs** (the playbook navigates four sub-pages and merges metrics):
+
+- https://browserleaks.com/canvas
+- https://browserleaks.com/webgl
+- https://browserleaks.com/fonts
+- https://browserleaks.com/tls
+
+BrowserLeaks doesn't issue an overall score β€” it produces extremely detailed
+per-category breakdowns. We capture the most-cited identifiers per category.
+
+## Steps
+
+For each URL in the list above:
+
+1. `nav <url> --new-tab --print-tab-id --dismiss-banners`. Save the tab ID.
+2. `wait --text "Fingerprint" --timeout 20000` (most BrowserLeaks pages render that label).
+3. `text` and capture the relevant metrics for that page.
+4. Close the tab when done β€” `tab close <id>` β€” to keep things tidy.
+
+After all four navs, aggregate into ONE record with `site: "browserleaks"` and
+all metrics merged into the same `metrics` map.
+
+## Metrics
+
+From /canvas:
+| key | what to look for |
+|----------------------|-------------------------------------------|
+| canvas_signature | "Signature" hash near the top |
+| canvas_uniqueness | uniqueness % or ratio shown |
+
+From /webgl:
+| key | what to look for |
+|----------------------|-------------------------------------------|
+| webgl_vendor | UNMASKED_VENDOR or "Vendor" row |
+| webgl_renderer | UNMASKED_RENDERER or "Renderer" row |
+| webgl_image_hash | "Image Hash" / "WebGL Hash" |
+
+From /fonts:
+| key | what to look for |
+|----------------------|-------------------------------------------|
+| fonts_count | number of fonts detected |
+| fonts_signature | fonts fingerprint hash if shown |
+
+From /tls:
+| key | what to look for |
+|----------------------|-------------------------------------------|
+| tls_ja3 | JA3 hash if shown |
+| tls_ja4 | JA4 hash if shown |
+| tls_user_agent | TLS-derived UA / client guess |
+| http2_fingerprint | HTTP/2 / Akamai fingerprint if shown |
+
+## Gotchas
+
+- BrowserLeaks pages embed an ad banner; `--dismiss-banners` usually clears it but if a banner blocks reads, `click` the visible Accept / Close.
+- /tls is sometimes very slow on first hit (the server runs a live TLS probe). `wait 6000` after nav before reading if the JA3 cell is empty.
diff --git a/tests/stealth-score/sites/browserscan.md b/tests/stealth-score/sites/browserscan.md
new file mode 100644
index 00000000..a1549cda
--- /dev/null
+++ b/tests/stealth-score/sites/browserscan.md
@@ -0,0 +1,45 @@
+# browserscan β€” BrowserScan Bot Detection
+
+**URL**: https://www.browserscan.net/bot-detection
+
+The browserscan bot-detection page runs ~25 client-side checks and renders a
+headline verdict plus per-test status. The page is JS-driven; checks run after
+load and the final verdict can take 15-30 s to appear.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://www.browserscan.net/bot-detection --new-tab --print-tab-id`.
+2. **Wait for verdict to render** β€” try (in order):
+ - `wait --text "You're not a Robot"` (or "You are a Robot") β€” timeout 30 s
+ - If neither resolves, `wait --text "WebDriver"` and re-read.
+3. **Dismiss any consent banner** β€” `nav <url> --new-tab --dismiss-banners` already does this on initial nav; if a banner blocks reads later, click the visible Accept button.
+4. **Read** β€” `text` first; fall back to `text --full` if value cells are empty.
+5. **Extract** the values below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|-----------------------------------------------------------|
+| robot_verdict | headline verdict ("You're not a Robot" / "You're a Robot" / "Test Results: Normal") |
+| webdriver | value cell for the WebDriver row |
+| cdp | value cell for the CDP row |
+| native_user_agent | value cell for "Native UserAgent" |
+| hardware_concurrency | numeric value (e.g. "8" or "4") |
+| timezone_consistency | ok/warn/error label for the Timezone row |
+| ua_browser | browser name + version reported |
+| ip_address | IP shown on the page |
+| ip_country | country / city reported |
+| dns_leak | yes/no β€” DNS-leak verdict |
+| webrtc_leak | yes/no β€” WebRTC IP leak |
+| canvas_fingerprint | canvas hash if shown |
+| webgl_fingerprint | WebGL hash if shown |
+| client_rects | client-rects fingerprint hash |
+| fonts_count | number of fonts detected |
+| hsts_supported | yes/no |
+| port_scan_open | any open-port indicators flagged |
+| ssl_fingerprint | TLS/JA3 hash if shown |
+
+## Common gotchas
+
+- The page sometimes renders only labels without value cells if it gives up waiting on a slow check. In that case, scroll the page (`scroll 800`) and re-read.
+- IP and location values may be masked as `---.---.---.---` until checks complete β€” that's expected for the first few seconds.
diff --git a/tests/stealth-score/sites/coveryourtracks.md b/tests/stealth-score/sites/coveryourtracks.md
new file mode 100644
index 00000000..ef3355cb
--- /dev/null
+++ b/tests/stealth-score/sites/coveryourtracks.md
@@ -0,0 +1,30 @@
+# coveryourtracks β€” EFF's Cover Your Tracks
+
+**URL**: https://coveryourtracks.eff.org/
+
+EFF's privacy/fingerprint testing tool. Focuses on how unique and trackable
+your browser is across the web.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://coveryourtracks.eff.org/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Click the test button** β€” usually `Test your browser` or `Test with a real tracking company`. Pick the **basic** test (left button) for speed. Use `find "test your browser button"` then click the returned ref, or `click "text:Test your browser" --wait-nav`.
+3. **Wait for the result** β€” `wait --text "fingerprint" --timeout 60000`. EFF's test takes 20-40 s.
+4. **Read** β€” `text` first.
+5. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|--------------------------------|--------------------------------------------------------------------|
+| fingerprint_uniqueness_pct | percentage / "1 in N" ratio under "Browser uniqueness" |
+| tracker_protection | verdict for "Is your browser blocking tracking ads?" |
+| invisible_tracker_protection | verdict for "Is your browser blocking invisible trackers?" |
+| fingerprinting_resistance | verdict β€” "Strong / Partial / Some / None" protection |
+| bits_of_identifying_info | numeric "bits of identifying information" |
+| do_not_track | DNT header echoed back (yes/no/unset) |
+
+## Gotchas
+
+- EFF's site is heavy; the "results" view renders well below the fold. Scroll (`scroll 1500`) after the test completes if metrics aren't in the first `text` dump.
+- The "real tracking company" button leads to a slow third-party flow β€” stick with the basic test unless explicitly asked otherwise.
diff --git a/tests/stealth-score/sites/creepjs.md b/tests/stealth-score/sites/creepjs.md
new file mode 100644
index 00000000..a0fb73bf
--- /dev/null
+++ b/tests/stealth-score/sites/creepjs.md
@@ -0,0 +1,41 @@
+# creepjs β€” CreepJS Browser Fingerprinting
+
+**URL**: https://creepjs.org/
+
+CreepJS runs ~50 fingerprint tests on load and computes a "trust score" plus
+counts of inconsistent signals ("lies"). The page takes 20-40 s to finish.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://creepjs.org/ --new-tab --print-tab-id`. Save the tab ID.
+2. **Wait for the trust score to render**. The page shows a progress line like "Analyzing your browser... N/55" while running; once done, the actual numeric trust score appears. Try (in order):
+ - `wait --text "trust score"` (timeout 30 s)
+ - If that hits a value cell that still says "Analyzing", add `wait 5000` and retry the read.
+3. **Read the rendered report**. Prefer `text` (Readability-filtered) first. If sections are missing, retry with `text --full`.
+4. **Extract** the values listed below. If a metric truly isn't present, record `"unavailable"` + the reason in `notes`.
+
+## Metrics
+
+| key | what to look for |
+|----------------------|------------------------------------------------------------------|
+| trust_score | numeric 0-100 next to "trust score" (may be absent on new layout)|
+| lies_count | integer next to "lies" header (often "lies (N)") |
+| fingerprint_id | short hex hash labelled "fingerprint" near the top |
+| bot | yes/no/probably from the "bot" or "bot pattern" row |
+| headless | yes/no/probably from the "headless rating" / "headless" row |
+| system | OS+arch short string (e.g. "Linux x86_64") |
+| gpu | GPU vendor/model string from the GPU row |
+| timezone | reported JS timezone (e.g. "UTC", "Europe/Rome") |
+| language | navigator.language reported |
+| canvas_hash | canvas fingerprint hash (short hex) |
+| audio_fingerprint | audio fingerprint hash if shown |
+| fonts_count | number of fonts detected |
+| cpu_cores | hardware concurrency value |
+| coverage | "coverage %" value if shown β€” proportion of tests that ran |
+| stack_lies | any specific stack/error-trace lies flagged |
+| webgl_hash | WebGL fingerprint hash if shown |
+
+## Common gotchas
+
+- CreepJS is heavy. Don't trust the first snapshot β€” re-read after a 5 s wait if the trust score cell still shows "Analyzing".
+- Some rows render as separate cells; you may need `text "#trust-score"` style selectors or a fresh `snap` to find the value.
diff --git a/tests/stealth-score/sites/deviceandbrowserinfo.md b/tests/stealth-score/sites/deviceandbrowserinfo.md
new file mode 100644
index 00000000..f5e18303
--- /dev/null
+++ b/tests/stealth-score/sites/deviceandbrowserinfo.md
@@ -0,0 +1,28 @@
+# deviceandbrowserinfo β€” Are You A Bot?
+
+**URL**: https://deviceandbrowserinfo.com/are_you_a_bot
+
+A page-level bot-detection verdict combining UA checks, mouse/typing behaviour,
+and fingerprint sanity.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://deviceandbrowserinfo.com/are_you_a_bot --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the verdict** β€” `wait --text "bot" --timeout 20000`.
+3. **Read** β€” `text` first.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| bot_activity_verdict | "bot" / "human" / "suspicious" headline verdict |
+| suspicious_signals | list of signals flagged (UA, mouse, typing, weak fingerprint) |
+| user_agent_check | UA verdict (passed/failed/normal) |
+| mouse_behaviour | mouse-activity check result |
+| weak_fingerprint_flag | yes/no for "weak fingerprint" |
+| browser | browser identification string |
+
+## Gotchas
+
+- The mouse/typing behaviour check expects real interaction; in a headless container these will almost always flag. Capture verbatim β€” that's the comparable signal.
diff --git a/tests/stealth-score/sites/fingerprint-demo.md b/tests/stealth-score/sites/fingerprint-demo.md
new file mode 100644
index 00000000..3ee24f29
--- /dev/null
+++ b/tests/stealth-score/sites/fingerprint-demo.md
@@ -0,0 +1,36 @@
+# fingerprint-demo β€” FingerprintJS Demo
+
+**URL**: https://fingerprint.com/demo/
+
+The FingerprintJS commercial demo renders a stable visitorId and several
+detection metrics (incognito, bot likelihood, browser/OS). Values are
+"Loading metric value" placeholders until the SDK finishes.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://fingerprint.com/demo/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the visitor ID to resolve** β€” `wait --not-text "Loading visitor ID" --timeout 30000`. The visitorId is the slowest field; once it shows, the rest are usually ready.
+3. **Read** β€” `text` first. If most fields still say "Loading metric value", `wait 5000` and re-read.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|-----------------------|---------------------------------------------------------------|
+| visitor_id | hex-style hash next to "Visitor ID" |
+| confidence | confidence score next to visitorId (e.g. "0.97") |
+| incognito | "yes"/"no" next to "Incognito" |
+| bot_likelihood | label or score ("Good bot" / "Bad bot" / "Not detected" / "Automation Detected") |
+| browser_detected | browser + version (e.g. "Chrome 130 on Linux") |
+| operating_system | OS name + version reported |
+| ip | IP shown by the demo |
+| ip_location | location reported next to IP |
+| vpn_detected | yes/no β€” VPN detection result |
+| public_proxy | yes/no β€” public-proxy detection |
+| tor_detected | yes/no β€” Tor detection |
+| jailbroken | yes/no β€” jailbreak/root detection (often "No" for desktop) |
+
+## Common gotchas
+
+- The demo embeds in an iframe. `text` may need a frame scope; if you can't read the value cells from the top frame, try `find "Visitor ID"` to locate the ref and read from that.
+- The bot likelihood field may simply not be exposed in the free demo; record `"unavailable"` + reason in notes if so.
diff --git a/tests/stealth-score/sites/fingerprint-scan.md b/tests/stealth-score/sites/fingerprint-scan.md
new file mode 100644
index 00000000..6b2f3fdb
--- /dev/null
+++ b/tests/stealth-score/sites/fingerprint-scan.md
@@ -0,0 +1,28 @@
+# fingerprint-scan β€” Fingerprint-Scan.com
+
+**URL**: https://fingerprint-scan.com/
+
+A bot-risk-oriented fingerprint scan; groups several JS-side checks similar to
+Pixelscan or Iphey.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://fingerprint-scan.com/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the verdict** β€” `wait --text "risk" --timeout 30000` (or "score").
+3. **Read** β€” `text` first.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| bot_risk_score | numeric risk score or label |
+| fingerprint_consistency | "consistent" / "inconsistent" verdict |
+| automation_flags | list of automation-related signals raised |
+| fingerprint_uniqueness | uniqueness ratio if shown |
+| ip_reputation | clean / proxy / vpn / datacenter verdict |
+| browser_signature | browser identification string |
+
+## Gotchas
+
+- Some scans require clicking a "Start" button before running. If nothing renders after the initial wait, look for a Start / Scan button via `find "start" / "scan"` and click it; then re-wait.
diff --git a/tests/stealth-score/sites/fvision.md b/tests/stealth-score/sites/fvision.md
new file mode 100644
index 00000000..03ab9f5a
--- /dev/null
+++ b/tests/stealth-score/sites/fvision.md
@@ -0,0 +1,30 @@
+# fvision β€” F.Vision / FV.Pro Privacy Check
+
+**URL**: https://fv.pro/check-privacy
+
+Fingerprint / privacy summary popular in anti-detect communities. Reports
+canvas, WebGL, fonts leaks plus automation indicators.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://fv.pro/check-privacy --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the summary** β€” `wait --text "fingerprint" --timeout 30000` or `wait --text "privacy"`.
+3. **Read** β€” `text` first.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| privacy_score | overall score / verdict label |
+| canvas_leak | canvas fingerprint hash or "leaked" label |
+| webgl_leak | WebGL fingerprint hash or "leaked" label |
+| fonts_leak | fonts list / count / leak label |
+| automation_indicators | list of automation signals raised |
+| ip_country | reported IP country |
+| timezone | reported timezone |
+
+## Gotchas
+
+- If fv.pro redirects to a different domain (anti-detect vendors often rebrand), follow the redirect; record the actual URL the agent observed.
+- This site is community-maintained β€” some metrics may be missing on a given visit. Record `"unavailable"` and note which fields were absent.
diff --git a/tests/stealth-score/sites/incolumitas.md b/tests/stealth-score/sites/incolumitas.md
new file mode 100644
index 00000000..e8acec1f
--- /dev/null
+++ b/tests/stealth-score/sites/incolumitas.md
@@ -0,0 +1,43 @@
+# incolumitas β€” Bot Detector (Incolumitas)
+
+**URL**: https://bot.incolumitas.com/
+
+One of the most comprehensive public bot/anti-detect probes β€” behavioural
+classification plus dozens of technical checks (TCP/IP, TLS/JA3, canvas, WebGL,
+WebRTC, proxy/datacenter, HTTP header anomalies, timezone consistency).
+Maintained by Nik (incolumitas.com); regularly updated.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://bot.incolumitas.com/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the behavioural classifier to settle** β€” the page often shows
+ `Bot likelihood: ...` once the JS finishes. Try (in order):
+ - `wait --text "Bot likelihood" --timeout 30000`
+ - If that times out, `wait --text "Behavioral" --timeout 15000`.
+ - Always `wait 4000` after the first hit to let secondary sections render.
+3. **Scroll the page** β€” `scroll 1500` then `scroll 1500` again so the lower
+ technical tables come into the snapshot. Re-read `text` after each scroll.
+4. **Read** β€” `text` first; fall back to `text --full` for dense tables.
+5. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|----------------------------------|--------------------------------------------------------------------|
+| behavioural_score | numeric 0-1 next to "behavioralClassificationScore" or "Bot likelihood" |
+| challenge_verdict | "human" / "bot" / "unknown" final classification line |
+| tcp_ip_fingerprint | TCP/IP fingerprint hash or OS guess (e.g. "Linux 5.x") |
+| tls_fingerprint | TLS / JA3 / JA4 hash if shown |
+| canvas_fingerprint | canvas hash next to "Canvas" / "canvasFp" |
+| webgl_fingerprint | WebGL hash next to "WebGL" / "webglFp" |
+| proxy_vpn_datacenter | proxy/VPN/datacenter verdict (e.g. "Datacenter IP", "Residential") |
+| webrtc_leaks | any WebRTC IP leaked vs none |
+| http_headers_verdict | header sanity check verdict (Accept-Language consistency etc.) |
+| timezone_consistency | "consistent"/"inconsistent" verdict between JS timezone and IP geo |
+| navigator_anomalies | one-line summary of navigator inconsistencies flagged |
+
+## Gotchas
+
+- The page is large; an initial `text` won't cover the technical-table sections at the bottom. Always scroll twice and re-read.
+- "Bot likelihood" can render as a number or as a colored label ("human" / "automated"). Capture verbatim.
+- If the page shows a Cloudflare interstitial first, record `metrics: {}` + `notes: "cloudflare interstitial"` and move on.
diff --git a/tests/stealth-score/sites/index.md b/tests/stealth-score/sites/index.md
new file mode 100644
index 00000000..7813c6cd
--- /dev/null
+++ b/tests/stealth-score/sites/index.md
@@ -0,0 +1,27 @@
+# Stealth-score Site Index
+
+Per-site playbooks live alongside this file. Each describes WHAT to capture;
+HOW to drive PinchTab is in `tests/stealth-score/subagent-context.md`.
+
+Process the sites in this order. Fast / static sites come first so they always
+get captured even if a long run runs into time limits; heavier JS-driven sites
+and multi-page navs are at the bottom.
+
+1. [sannysoft](sannysoft.md) β€” static table, lowest noise. WebGL/permissions/UA rows.
+2. [rebrowser](rebrowser.md) β€” modern Chromium leak tests (exposeFunctionLeak etc).
+3. [deviceandbrowserinfo](deviceandbrowserinfo.md) β€” bot/human verdict + suspicious signals.
+4. [iphey](iphey.md) β€” reliability badge, proxy/VPN/DNS leak flags.
+5. [whoer](whoer.md) β€” anonymity %, proxy/VPN detection, browser consistency.
+6. [browserscan](browserscan.md) β€” bot-detection per-test rows + IP / WebRTC / canvas.
+7. [pixelscan](pixelscan.md) β€” requires a Start Check click; bot score + automation flags.
+8. [fingerprint-scan](fingerprint-scan.md) β€” bot risk score, automation flags.
+9. [incolumitas](incolumitas.md) β€” most comprehensive: behavioural + TLS/JA3 + WebRTC + proxy + timezone.
+10. [fvision](fvision.md) β€” fv.pro privacy/leak summary (canvas/WebGL/fonts).
+11. [amiunique](amiunique.md) β€” per-attribute uniqueness ratios.
+12. [browserleaks](browserleaks.md) β€” multi-nav: /canvas + /webgl + /fonts + /tls.
+13. [creepjs](creepjs.md) β€” heavy JS suite; trust score + fingerprint hashes.
+14. [coveryourtracks](coveryourtracks.md) β€” EFF tracking-resistance test; needs a button click.
+15. [fingerprint-demo](fingerprint-demo.md) β€” FingerprintJS commercial demo; SDK can be slow/refuse headless.
+
+Add sites by creating a new `<id>.md` playbook here and listing it above. The
+agent processes whatever it finds in this index in order.
diff --git a/tests/stealth-score/sites/iphey.md b/tests/stealth-score/sites/iphey.md
new file mode 100644
index 00000000..a10abfe8
--- /dev/null
+++ b/tests/stealth-score/sites/iphey.md
@@ -0,0 +1,33 @@
+# iphey β€” IP/Browser Reliability (iphey.com)
+
+**URL**: https://iphey.com/
+
+Reports a "trustworthy / suspicious" reliability verdict, digital-identity
+consistency, automation signs, and proxy/leak flags. Compact summary page.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://iphey.com/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the reliability badge** β€” `wait --text "Trustworthy"` (or "Suspicious"). Timeout 20 s.
+3. **Read** β€” `text` first.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|--------------------------------|--------------------------------------------------------------------|
+| reliability_verdict | "Trustworthy" / "Suspicious" / "Unreliable" badge |
+| digital_identity_consistency | yes/no β€” does locale/timezone/IP geo align |
+| automation_signs | list of automation-related flags raised |
+| proxy_flag | proxy detected: yes/no |
+| vpn_flag | VPN detected: yes/no |
+| datacenter_flag | datacenter IP detected: yes/no |
+| webrtc_leak | yes/no β€” any WebRTC IP leaked |
+| dns_leak | yes/no β€” DNS-leak verdict |
+| fingerprint_uniqueness | uniqueness score or ratio if shown |
+| timezone | reported timezone (string) |
+
+## Gotchas
+
+- The reliability badge color matters (green=trustworthy, red=suspicious); capture the literal word.
+- If results take >30 s to settle, record what you have and put `notes: "page slow to settle"`.
diff --git a/tests/stealth-score/sites/pixelscan.md b/tests/stealth-score/sites/pixelscan.md
new file mode 100644
index 00000000..71ab1d55
--- /dev/null
+++ b/tests/stealth-score/sites/pixelscan.md
@@ -0,0 +1,42 @@
+# pixelscan β€” Pixelscan Bot Check
+
+**URL**: https://pixelscan.net/bot-check
+
+Pixelscan exposes a "Start Check" button β€” the verdict only renders after you
+click it. The page text statically contains both verdict labels (`You're
+Definitely a Human` and `Bot Behavior Detected`); ignore them until you've
+clicked Start and the page updates.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://pixelscan.net/bot-check --new-tab --print-tab-id`.
+2. **Wait for the Start Check button** β€” `wait --text "Start Check"` (timeout 15 s).
+3. **Click Start Check** β€” `find "Start Check button"` then click the returned ref, or `click "text:Start Check"`. Use `--snap-diff` so you see the page transition.
+4. **Wait for the result** β€” pixelscan renders the verdict inline. The result is ready when one of the per-test rows (`Webdriver`, `Browser`, `Canvas`) shows a non-pending value. `wait --text "Webdriver" --timeout 30000`.
+5. **Read** β€” `text` first.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| bot_score | headline ("You're Definitely a Human" / "Bot Behavior Detected" / numeric score) |
+| consistent | yes/no consistency verdict (often "Consistent" / "Inconsistent") |
+| chrome_signature | row value for "ChromeDriverSignature" β€” Clear/Detected |
+| automation_flags | comma-list of rows showing "Detected" |
+| mismatch_summary | one-line summary of any timezone/locale/IP mismatch lines |
+| ip_address | IP shown on the page |
+| timezone | reported JS timezone |
+| timezone_offset | reported timezone offset |
+| language | reported navigator.language |
+| canvas_hash | canvas fingerprint hash |
+| webgl_hash | WebGL fingerprint hash |
+| user_agent | UA string |
+| screen_resolution | reported screen dimensions |
+| webdriver_value | navigator.webdriver value (true/false/undefined) |
+| tampered_functions | "TamperedFunctions" row β€” Clear / Detected |
+| unusual_window_properties | "UnusualWindowProperties" row β€” Clear / Detected |
+
+## Common gotchas
+
+- The page text contains BOTH verdict strings statically β€” don't extract them blindly. Only trust the headline after the post-click result has rendered.
+- If the click fails (overlay/banner), reload (`reload`) and try again. Pixelscan sometimes shows a Cloudflare interstitial first; record `metrics: {}` + `notes: "cloudflare interstitial"` and move on if it persists.
diff --git a/tests/stealth-score/sites/rebrowser.md b/tests/stealth-score/sites/rebrowser.md
new file mode 100644
index 00000000..8a9eec9c
--- /dev/null
+++ b/tests/stealth-score/sites/rebrowser.md
@@ -0,0 +1,33 @@
+# rebrowser β€” Rebrowser Bot Detector
+
+**URL**: https://bot-detector.rebrowser.net/
+
+Targets modern Chromium automation leaks (Puppeteer / Playwright / chromedp
+fingerprints): exposeFunctionLeak, sourceUrlLeak, mainWorldExecution, etc.
+Compact result table.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://bot-detector.rebrowser.net/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the test table** β€” `wait --text "exposeFunctionLeak"` or `wait --text "mainWorldExecution"`. Timeout 20 s.
+3. **Read** β€” `text` first; `text --full` if rows are missing.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | row label |
+|---------------------------|--------------------------------------------|
+| expose_function_leak | "exposeFunctionLeak" |
+| source_url_leak | "sourceUrlLeak" |
+| main_world_execution | "mainWorldExecution" |
+| dummy_function | "dummyFn" or similar puppeteer probe |
+| navigator_webdriver | navigator.webdriver value reported |
+| user_agent | UA string reported |
+| overall_verdict | any headline pass/fail label |
+
+For each, capture either "passed"/"failed" or the literal value shown.
+
+## Gotchas
+
+- Page is small and fast β€” if `wait` returns immediately, that means the table is already there. Don't re-wait unnecessarily.
+- New tests are added over time; capture any additional rows you see verbatim with kebab-case keys.
diff --git a/tests/stealth-score/sites/sannysoft.md b/tests/stealth-score/sites/sannysoft.md
new file mode 100644
index 00000000..ae553add
--- /dev/null
+++ b/tests/stealth-score/sites/sannysoft.md
@@ -0,0 +1,44 @@
+# sannysoft β€” Sannysoft Antibot Test Table
+
+**URL**: https://bot.sannysoft.com/
+
+A static table of automated checks (WebDriver, Permissions, WebGL, Languages,
+…) β€” each row shows "passed" (green) or "failed" (red). One of the lowest-noise
+sites in this set.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://bot.sannysoft.com/ --new-tab --print-tab-id`.
+2. **Wait for the table** β€” `wait --text "WebDriver"` (timeout 15 s). The table renders nearly synchronously; no JS spinning.
+3. **Read** β€” `text` works; if rows are truncated try `text --full`.
+4. **Extract** the row values below.
+
+## Metrics
+
+For each metric, the value cell after the row label is either "passed" or "failed" (sometimes a short reason). Capture exactly what the cell shows.
+
+| key | row label |
+|----------------------|----------------------------------------------------|
+| webdriver | "WebDriver (New)" or "WebDriver" |
+| webdriver_advanced | "WebDriver Advanced" |
+| chrome_obj | "Chrome (New)" / window.chrome |
+| permissions | "Permissions" |
+| plugins_length | "Plugins Length (Old)" |
+| languages | "Languages (Old)" |
+| webgl_vendor | "WebGL Vendor" |
+| webgl_renderer | "WebGL Renderer" |
+| broken_image | "Broken Image Dimensions" |
+| webgl_image_hash | "WebGL Image Hash" row if present |
+| iframe_chrome | "iframe.contentWindow.chrome" or similar |
+| function_to_string | "Function.prototype.toString" row |
+| toSource | "toSource" row if present |
+| audio_codecs | "AudioCodecs" or audio codec support row |
+| video_codecs | "VideoCodecs" or video codec support row |
+| media_devices | navigator.mediaDevices probe |
+| user_agent | UA string shown at the top of the page |
+| permissions_state | notification permission row if present |
+
+## Common gotchas
+
+- WebGL rows are the most informative for comparing chrome vs cloak β€” cloak should report a believable consumer GPU (NVIDIA / Intel / Apple) while headless chrome typically reports "no webgl context".
+- Sannysoft's first table is the "modern detect" set; the second table is the "old detect" set. Use the modern table for the rows above.
diff --git a/tests/stealth-score/sites/whoer.md b/tests/stealth-score/sites/whoer.md
new file mode 100644
index 00000000..d05657db
--- /dev/null
+++ b/tests/stealth-score/sites/whoer.md
@@ -0,0 +1,32 @@
+# whoer β€” Whoer.net Anonymity Check
+
+**URL**: https://whoer.net/
+
+Anonymity score plus proxy/VPN detection, browser-fingerprint consistency, and
+bot-like behaviour flags.
+
+## Steps
+
+1. **Open in a new tab** β€” `nav https://whoer.net/ --new-tab --print-tab-id --dismiss-banners`.
+2. **Wait for the score** β€” `wait --text "%" --timeout 20000` (anonymity is shown as a percentage).
+3. **Read** β€” `text` first.
+4. **Extract** the metrics below.
+
+## Metrics
+
+| key | what to look for |
+|---------------------------|---------------------------------------------------------------|
+| anonymity_score_pct | numeric % next to "Your anonymity" / "Anonymity" |
+| proxy_detected | yes/no β€” proxy detection verdict |
+| vpn_detected | yes/no β€” VPN detection verdict |
+| browser_consistency | consistent / inconsistent verdict |
+| bot_signals | list of bot-like behaviour flags |
+| ip_country | reported IP country / city |
+| dns | reported DNS provider |
+| timezone | reported timezone |
+| webrtc_leak | yes/no β€” WebRTC IP leak |
+
+## Gotchas
+
+- Whoer's site has heavy ads; `--dismiss-banners` helps but if a sticky banner blocks reads after settle, `scroll 800` past it.
+- The anonymity score includes IP geo, timezone consistency, and JS features β€” interpret comparatively between providers rather than as an absolute pass/fail.
diff --git a/tests/stealth-score/subagent-context.md b/tests/stealth-score/subagent-context.md
new file mode 100644
index 00000000..d9901617
--- /dev/null
+++ b/tests/stealth-score/subagent-context.md
@@ -0,0 +1,121 @@
+# Stealth Score Subagent Context
+
+You are driving PinchTab in a Docker container against public bot-detection
+sites. Your job: visit each site in `tests/stealth-score/sites/index.md`,
+follow its playbook, and write a structured JSON report.
+
+Do not touch Docker, do not switch providers, do not read other runs'
+artifacts. The orchestrator already brought up the container for you.
+
+Do not read anything under `tests/stealth-score/results/`.
+
+## Inputs You Receive
+
+- `PROVIDER`: `chrome` or `cloak` β€” already configured in the container.
+- `REPORT_FILE`: absolute path of the pre-seeded JSON file to append to.
+- `PROJECT_ROOT`: absolute path of the pinchtab repo.
+
+## Working Directory and Wrapper
+
+Always run from `tests/tools` so the `./scripts/pt` wrapper resolves:
+
+```bash
+cd $PROJECT_ROOT/tests/tools
+export PINCHTAB_CONTAINER=stealth-score-pinchtab
+export PINCHTAB_TOKEN=stealth-score-token
+```
+
+`./scripts/pt` forwards every argument to the `pinchtab` CLI inside the
+container. Use it exactly like the local CLI:
+
+```bash
+./scripts/pt health
+TAB=$(./scripts/pt nav https://example.com --new-tab --print-tab-id)
+./scripts/pt --tab "$TAB" snap
+```
+
+Read `$PROJECT_ROOT/skills/pinchtab/SKILL.md` for the full command surface.
+
+## Session
+
+Create one session up-front and reuse it across all sites:
+
+```bash
+export PINCHTAB_SESSION=$(./scripts/pt session create --agent-id stealth-${PROVIDER})
+```
+
+## Per-Site Loop
+
+For every site listed in `$PROJECT_ROOT/tests/stealth-score/sites/index.md`:
+
+1. Read its playbook (`tests/stealth-score/sites/<id>.md`). It tells you the
+ URL, the readiness signal, any click/scroll/wait the page needs, and the
+ metrics to extract.
+2. Drive PinchTab to follow the playbook. Use refs from `snap` when targeting
+ elements; use `wait --text` / `wait --not-text` to settle SPAs. Don't
+ hard-code sleeps unless the playbook explicitly says so.
+3. Extract the listed metrics from `text` / `snap` output. Record what you
+ actually saw. If a metric is genuinely unreadable, record `"unavailable"`
+ and explain in `notes`. Do **not** invent values. Do **not** carry values
+ between sites.
+4. Append a record to `REPORT_FILE`:
+
+```json
+{
+ "site": "<id>",
+ "url": "<url from playbook>",
+ "tab_id": "<from --print-tab-id>",
+ "metrics": {
+ "<key>": "<value>",
+ ...
+ },
+ "notes": "<optional one-line caveats>"
+}
+```
+
+Safe-append helper:
+
+```bash
+python3 - <<'PY'
+import json
+path = "<REPORT_FILE>"
+entry = { "site": "<id>", "url": "<url>", "tab_id": "<id>", "metrics": {...}, "notes": "..." }
+data = json.load(open(path))
+data["sites"].append(entry)
+json.dump(data, open(path, "w"), indent=2)
+PY
+```
+
+## Quality Bar
+
+| Good | Bad |
+|--------------------------------------------|------------------------------|
+| `trust_score: "62.0"` | `trust_score: "see page"` |
+| `webdriver: "passed"` | `webdriver: "ok"` |
+| `robot_verdict: "You're not a Robot"` | `robot_verdict: "no"` |
+| `bot_score: "0.12 (Likely human)"` | `bot_score: "low"` |
+
+If a site shows a Cloudflare challenge ("Just a moment...", "attention
+required"), record `metrics: {}` and `notes: "cloudflare challenge"` and
+move on β€” do not call `/solve` without explicit user approval.
+
+## Completion
+
+After every site has a record:
+
+```bash
+python3 - <<'PY'
+import json, time
+path = "<REPORT_FILE>"
+d = json.load(open(path))
+d["completed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+d["sites_processed"] = len(d["sites"])
+json.dump(d, open(path, "w"), indent=2)
+PY
+```
+
+Print exactly this as your final stdout line:
+
+```
+STEALTH_SCORE_RUN_COMPLETE provider=<provider> sites_processed=<n>
+```
diff --git a/tests/stealth-score/up.sh b/tests/stealth-score/up.sh
new file mode 100755
index 00000000..b8e08e6a
--- /dev/null
+++ b/tests/stealth-score/up.sh
@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# tests/stealth-score/up.sh <provider>
+#
+# Bring up a Docker container for stealth-score work with the requested
+# browser provider (chrome | cloak). The container exposes PinchTab on host
+# port 9867 and the agent drives it through the existing ./scripts/pt
+# wrapper. When the agent is done, call down.sh to tear it down.
+#
+# Build behaviour:
+# - Reuses cached images if present (pinchtab-chrome-smoke:test,
+# pinchtab-cloakbrowser:test). Set REBUILD=1 to force fresh builds.
+#
+# Side effects:
+# - Stops/removes any existing container named "stealth-score-pinchtab".
+# - Writes a temp config to tests/stealth-score/.tmp/.
+set -euo pipefail
+
+PROVIDER="${1:?provider required (chrome|cloak)}"
+case "$PROVIDER" in chrome|cloak) ;; *) echo "invalid provider: $PROVIDER"; exit 2 ;; esac
+
+ROOT="$(git rev-parse --show-toplevel)"
+NAME="stealth-score-pinchtab"
+TOKEN="stealth-score-token"
+CONFIG_DIR="$ROOT/tests/stealth-score/.tmp"
+CONFIG_PATH="$CONFIG_DIR/pinchtab-$PROVIDER.json"
+mkdir -p "$CONFIG_DIR"
+
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/smoke-common.sh"
+# shellcheck source=/dev/null
+source "$ROOT/scripts/lib/smoke-config.sh"
+
+ensure_image() {
+ local image="$1" dockerfile="$2"
+ if [ "${REBUILD:-}" = "1" ] || ! docker image inspect "$image" >/dev/null 2>&1; then
+ echo "Building $image..." >&2
+ if [ -n "$dockerfile" ]; then
+ docker build -f "$ROOT/$dockerfile" -t "$image" "$ROOT" >&2
+ else
+ docker build -t "$image" "$ROOT" >&2
+ fi
+ else
+ echo "Reusing $image (set REBUILD=1 to rebuild)" >&2
+ fi
+}
+
+case "$PROVIDER" in
+ chrome)
+ ensure_image "pinchtab-local:test" ""
+ ensure_image "pinchtab-chrome-smoke:test" "tests/tools/docker/chrome-smoke.Dockerfile"
+ IMAGE="pinchtab-chrome-smoke:test"
+ CLOAK_BIN=""
+ ;;
+ cloak)
+ ensure_image "pinchtab-cloakbrowser:test" "tests/tools/docker/cloakbrowser-smoke.Dockerfile"
+ IMAGE="pinchtab-cloakbrowser:test"
+ CLOAK_BIN="/opt/cloakbrowser/chrome"
+ ;;
+esac
+
+write_provider_config "$PROVIDER" "$CONFIG_PATH" "$TOKEN" "stealth-score-fixtures.local" "" "$CLOAK_BIN"
+
+# Open allowedDomains so the agent can hit the public detection sites.
+python3 - "$CONFIG_PATH" <<'PY'
+import json, sys
+p = sys.argv[1]
+c = json.load(open(p))
+c.setdefault("security", {})["allowedDomains"] = []
+json.dump(c, open(p, "w"), indent=2)
+PY
+
+docker rm -f "$NAME" >/dev/null 2>&1 || true
+
+docker run -d --name "$NAME" \
+ -p 127.0.0.1:9867:9867 \
+ --shm-size=2g \
+ --dns 8.8.8.8 --dns 1.1.1.1 \
+ -v "$CONFIG_PATH:/fixture-config/pinchtab.json:ro" \
+ -e PINCHTAB_CONFIG=/fixture-config/pinchtab.json \
+ "$IMAGE" >/dev/null
+
+echo "Waiting for /health on 127.0.0.1:9867..." >&2
+for i in $(seq 1 40); do
+ if curl -sf -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9867/health >/dev/null 2>&1; then
+ cat <<EOF
+READY
+container=$NAME
+provider=$PROVIDER
+token=$TOKEN
+port=9867
+config=$CONFIG_PATH
+EOF
+ exit 0
+ fi
+ sleep 1
+done
+
+echo "FAILED to become healthy after 40s" >&2
+docker logs "$NAME" 2>&1 | tail -40 >&2
+exit 1
diff --git a/tests/tools/runner/internal/e2e/e2e.go b/tests/tools/runner/internal/e2e/e2e.go
index 28126deb..7444066d 100644
--- a/tests/tools/runner/internal/e2e/e2e.go
+++ b/tests/tools/runner/internal/e2e/e2e.go
@@ -35,8 +35,8 @@ Options:
--extra FILES Add extra scenario files, space-separated
--logs show|hide Control compose build/runner output
--provider chrome|cloak
- Select browser provider (default: chrome). Cloak requires
- the prebuilt pinchtab-cloakbrowser:test image.
+ Select browser provider (default: chrome). Cloak builds
+ pinchtab-cloakbrowser:test unless SKIP_BUILD=1 is set.
--dry-run Print the compose plan without running it
--help, -h Show this help
`
diff --git a/tests/tools/runner/internal/e2e/e2e_test.go b/tests/tools/runner/internal/e2e/e2e_test.go
index 5d9b6f70..90e4a9bc 100644
--- a/tests/tools/runner/internal/e2e/e2e_test.go
+++ b/tests/tools/runner/internal/e2e/e2e_test.go
@@ -598,6 +598,7 @@ func TestBringUpSharedStackCloakBuildsSupportImagesOnly(t *testing.T) {
logsMode: "hide",
overrides: &providerOverrides{
provider: "cloak",
+ image: defaultCloakImage,
composeFiles: []string{"/tmp/docker-compose.cloak.yml"},
},
}
diff --git a/tests/tools/runner/internal/e2e/provider.go b/tests/tools/runner/internal/e2e/provider.go
index fd2c9988..c33ca986 100644
--- a/tests/tools/runner/internal/e2e/provider.go
+++ b/tests/tools/runner/internal/e2e/provider.go
@@ -11,11 +11,8 @@ import (
"time"
)
-// cloakImage is the prebuilt image the cloak provider expects to find locally.
-// It is built by tests/tools/docker/cloakbrowser-smoke.Dockerfile and is
-// intentionally never auto-built by the e2e runner β€” it is too heavy and the
-// Cloak binary license requires explicit opt-in.
-const cloakImage = "pinchtab-cloakbrowser:test"
+const defaultCloakImage = "pinchtab-cloakbrowser:test"
+const defaultCloakDockerfile = "tests/tools/docker/cloakbrowser-smoke.Dockerfile"
const dryRunCloakComposeOverride = "<generated-cloak-compose-override>"
// pinchtabServices enumerates every pinchtab variant present in the e2e
@@ -35,6 +32,7 @@ var pinchtabServices = []string{
// configs the runner mounts in place of the chrome configs.
type providerOverrides struct {
provider string
+ image string
tmpDir string
composeFiles []string
}
@@ -52,15 +50,17 @@ func (r *Runner) prepareProviderOverrides() (*providerOverrides, error) {
if r.args.Provider != "cloak" {
return nil, fmt.Errorf("unsupported provider: %s", r.args.Provider)
}
+ image := cloakProviderImage()
if r.args.DryRun {
return &providerOverrides{
provider: "cloak",
+ image: image,
composeFiles: []string{dryRunCloakComposeOverride},
}, nil
}
- if err := assertCloakImagePresent(); err != nil {
+ if err := r.ensureCloakImage(image); err != nil {
return nil, err
}
@@ -93,13 +93,14 @@ func (r *Runner) prepareProviderOverrides() (*providerOverrides, error) {
overridePath := filepath.Join(tmp, "docker-compose.cloak.yml")
fixturesDir := filepath.Join(r.repoRoot, "tests/e2e/fixtures")
- if err := writeCloakComposeOverride(overridePath, cloakConfigs, fixturesDir); err != nil {
+ if err := writeCloakComposeOverride(overridePath, cloakConfigs, fixturesDir, image); err != nil {
_ = os.RemoveAll(tmp)
return nil, fmt.Errorf("write cloak compose override: %w", err)
}
return &providerOverrides{
provider: "cloak",
+ image: image,
tmpDir: tmp,
composeFiles: []string{overridePath},
}, nil
@@ -112,19 +113,72 @@ func (o *providerOverrides) cleanup() {
_ = os.RemoveAll(o.tmpDir)
}
-func assertCloakImagePresent() error {
- cmd := exec.Command("docker", "image", "inspect", cloakImage)
- cmd.Stdout = nil
- cmd.Stderr = nil
- if err := cmd.Run(); err != nil {
- return fmt.Errorf(
- "%s image not found; build via tests/tools/docker/cloakbrowser-smoke.Dockerfile or `./dev smoke cloakbrowser` first",
- cloakImage,
- )
+func cloakProviderImage() string {
+ for _, env := range []string{"PINCHTAB_E2E_CLOAK_IMAGE", "PINCHTAB_PARITY_CLOAK_IMAGE"} {
+ if v := strings.TrimSpace(os.Getenv(env)); v != "" {
+ return v
+ }
+ }
+ return defaultCloakImage
+}
+
+func cloakProviderDockerfile() string {
+ if v := strings.TrimSpace(os.Getenv("PINCHTAB_CLOAKBROWSER_DOCKERFILE")); v != "" {
+ return v
+ }
+ return defaultCloakDockerfile
+}
+
+func (r *Runner) ensureCloakImage(image string) error {
+ if strings.TrimSpace(os.Getenv("SKIP_BUILD")) == "1" {
+ present, err := dockerImagePresent(image)
+ if err != nil {
+ return err
+ }
+ if present {
+ _, _ = fmt.Fprintf(r.stdout, " provider image: reusing %s (SKIP_BUILD=1)\n", image)
+ return nil
+ }
+ return fmt.Errorf("%s image not found and SKIP_BUILD=1 is set; build with %s or unset SKIP_BUILD", image, cloakProviderDockerfile())
+ }
+
+ dockerfile := cloakProviderDockerfile()
+ dockerfilePath := dockerfile
+ if !filepath.IsAbs(dockerfilePath) {
+ dockerfilePath = filepath.Join(r.repoRoot, dockerfilePath)
+ }
+ if _, err := os.Stat(dockerfilePath); err != nil {
+ return fmt.Errorf("cloak Dockerfile not found at %s: %w", dockerfile, err)
+ }
+
+ code := r.runLoggedCommand(
+ "building Cloak provider image",
+ stackOutput,
+ []string{"docker", "build", "-f", dockerfilePath, "-t", image, r.repoRoot},
+ )
+ if code != 0 {
+ return fmt.Errorf("build Cloak provider image failed (exit %d)", code)
}
return nil
}
+func dockerImagePresent(image string) (bool, error) {
+ cmd := exec.Command("docker", "image", "inspect", image)
+ out, err := cmd.CombinedOutput()
+ if err == nil {
+ return true, nil
+ }
+ msg := strings.TrimSpace(string(out))
+ lower := strings.ToLower(msg)
+ if strings.Contains(lower, "no such image") || strings.Contains(lower, "not found") {
+ return false, nil
+ }
+ if msg == "" {
+ return false, fmt.Errorf("inspect Docker image %s: %w", image, err)
+ }
+ return false, fmt.Errorf("inspect Docker image %s: %w: %s", image, err, msg)
+}
+
// writeCloakConfig reads a chrome-flavoured pinchtab config and writes a
// cloak-flavoured copy: it preserves every other field and injects the
// browser.provider + browser.binary + browser.cloak block. The fingerprint
@@ -162,14 +216,14 @@ func writeCloakConfig(src, dst string) error {
}
// writeCloakComposeOverride writes a compose file that targets each pinchtab
-// service: swaps the image to the prebuilt cloak image, drops the build
+// service: swaps the image to the cloak provider image, drops the build
// directive (via image-only + pull_policy:never), remaps the config bind mount
// onto the cloak-flavoured copy we just generated, and preserves extension
// fixture mounts needed by extension-parity E2E tests.
//
// The override is intentionally written as YAML by hand (no third-party deps)
// since the structure is small and stable.
-func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixturesDir string) error {
+func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixturesDir, image string) error {
type extensionMount struct {
sourceDir string
target string
@@ -222,7 +276,7 @@ func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixt
var b strings.Builder
b.WriteString("# Generated by tests/tools/runner β€” provider=cloak override.\n")
- b.WriteString("# Swaps every pinchtab* service onto the prebuilt cloak image and\n")
+ b.WriteString("# Swaps every pinchtab* service onto the cloak provider image and\n")
b.WriteString("# mounts the cloak-flavoured runtime config in place of the chrome one.\n")
b.WriteString("services:\n")
@@ -239,7 +293,7 @@ func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixt
continue
}
fmt.Fprintf(&b, " %s:\n", svc)
- fmt.Fprintf(&b, " image: %s\n", cloakImage)
+ fmt.Fprintf(&b, " image: %s\n", image)
fmt.Fprintf(&b, " pull_policy: never\n")
// Keep the override self-contained: every provider=cloak service gets
// the rewritten config plus the same extension fixtures its Chrome
diff --git a/tests/tools/runner/internal/e2e/provider_test.go b/tests/tools/runner/internal/e2e/provider_test.go
index 335fddc2..6628e582 100644
--- a/tests/tools/runner/internal/e2e/provider_test.go
+++ b/tests/tools/runner/internal/e2e/provider_test.go
@@ -1,6 +1,7 @@
package e2e
import (
+ "bytes"
"os"
"path/filepath"
"strings"
@@ -22,7 +23,7 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {
"pinchtab-bridge.json": filepath.Join(tmp, "pinchtab-bridge.json"),
}
- if err := writeCloakComposeOverride(outPath, configs, fixturesDir); err != nil {
+ if err := writeCloakComposeOverride(outPath, configs, fixturesDir, defaultCloakImage); err != nil {
t.Fatal(err)
}
@@ -67,7 +68,7 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {
if !strings.Contains(block, want) {
t.Fatalf("%s override missing cloak config mount %q:\n%s", svc, want, block)
}
- if !strings.Contains(block, "image: "+cloakImage) {
+ if !strings.Contains(block, "image: "+defaultCloakImage) {
t.Fatalf("%s override missing cloak image:\n%s", svc, block)
}
if !strings.Contains(block, "pull_policy: never") {
@@ -76,6 +77,62 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {
}
}
+func TestEnsureCloakImageBuildsByDefault(t *testing.T) {
+ tmp := t.TempDir()
+ logPath := filepath.Join(tmp, "docker.log")
+ fakeDocker := filepath.Join(tmp, "docker")
+ script := "#!/bin/sh\n" +
+ "echo \"$@\" >> \"" + logPath + "\"\n" +
+ "if [ \"$1\" = \"image\" ] && [ \"$2\" = \"inspect\" ]; then\n" +
+ " echo \"Error response from daemon: No such image: $3\" >&2\n" +
+ " exit 1\n" +
+ "fi\n" +
+ "if [ \"$1\" = \"build\" ]; then\n" +
+ " exit 0\n" +
+ "fi\n" +
+ "exit 2\n"
+ if err := os.WriteFile(fakeDocker, []byte(script), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("PATH", tmp+":"+os.Getenv("PATH"))
+
+ repoRoot := t.TempDir()
+ dockerfilePath := filepath.Join(repoRoot, defaultCloakDockerfile)
+ if err := os.MkdirAll(filepath.Dir(dockerfilePath), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(dockerfilePath, []byte("FROM scratch\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+
+ var stdout, stderr bytes.Buffer
+ r := &Runner{
+ stdout: &stdout,
+ stderr: &stderr,
+ repoRoot: repoRoot,
+ logsMode: "hide",
+ }
+ if err := r.ensureCloakImage(defaultCloakImage); err != nil {
+ t.Fatalf("ensureCloakImage returned error: %v\nstderr: %s", err, stderr.String())
+ }
+
+ raw, err := os.ReadFile(logPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ calls := string(raw)
+ for _, want := range []string{
+ "build -f " + dockerfilePath + " -t " + defaultCloakImage + " " + repoRoot,
+ } {
+ if !strings.Contains(calls, want) {
+ t.Fatalf("docker calls missing %q:\n%s", want, calls)
+ }
+ }
+ if strings.Contains(calls, "image inspect") {
+ t.Fatalf("default Cloak image setup should build without reusing stale images:\n%s", calls)
+ }
+}
+
func TestWriteCloakConfigPreservesExtensionPaths(t *testing.T) {
tmp := t.TempDir()
src := filepath.Join(tmp, "pinchtab.json")
diff --git a/tests/tools/runner/internal/e2e/runner.go b/tests/tools/runner/internal/e2e/runner.go
index 248a4ab3..22a2b8c0 100644
--- a/tests/tools/runner/internal/e2e/runner.go
+++ b/tests/tools/runner/internal/e2e/runner.go
@@ -120,7 +120,7 @@ func (r *Runner) Run() int {
r.overrides = overrides
if overrides != nil {
defer overrides.cleanup()
- _, _ = fmt.Fprintf(r.stdout, " provider: %s (image: %s)\n", overrides.provider, cloakImage)
+ _, _ = fmt.Fprintf(r.stdout, " provider: %s (image: %s)\n", overrides.provider, overrides.image)
}
code := r.run()
duration := time.Since(started)
@@ -564,10 +564,9 @@ func (r *Runner) planSuites(defs []suiteDef) ([]suitePlan, int) {
}
func (r *Runner) bringUpSharedStack(composeFile string, services []string) int {
- // Cloak runs against a prebuilt image (pinchtab-cloakbrowser:test) that
- // must NOT be rebuilt by this lane. We still build support images such as
- // fixtures and runners so clean workstations do not depend on stale local
- // images.
+ // Cloak pinchtab services are supplied by the provider override image.
+ // Build support images such as fixtures and runners, but keep compose from
+ // rebuilding the overridden pinchtab services.
skipPinchtabBuild := r.overrides != nil && r.overrides.provider == "cloak"
if skipPinchtabBuild {
if code := r.buildSharedStack(composeFile, cloakSupportBuildServices()...); code != 0 {
diff --git a/tests/tools/runner/internal/stealth/compare.go b/tests/tools/runner/internal/stealth/compare.go
new file mode 100644
index 00000000..c00d3a67
--- /dev/null
+++ b/tests/tools/runner/internal/stealth/compare.go
@@ -0,0 +1,473 @@
+package stealth
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+ "time"
+)
+
+// Report is the on-disk shape written by the stealth-score subagent.
+type Report struct {
+ Provider string `json:"provider"`
+ Timestamp string `json:"timestamp"`
+ StartedAt string `json:"started_at,omitempty"`
+ CompletedAt string `json:"completed_at,omitempty"`
+ SitesProcessed int `json:"sites_processed,omitempty"`
+ ArtifactDir string `json:"artifact_dir,omitempty"`
+ Sites []SiteRow `json:"sites"`
+}
+
+type SiteRow struct {
+ Site string `json:"site"`
+ URL string `json:"url,omitempty"`
+ TabID string `json:"tab_id,omitempty"`
+ Metrics map[string]string `json:"metrics"`
+ Notes string `json:"notes,omitempty"`
+}
+
+// Divergence is one metric where two providers disagreed on real values.
+type Divergence struct {
+ Site string `json:"site"`
+ Metric string `json:"metric"`
+}
+
+// HistoryEntry is the on-disk shape appended to history.jsonl per compare run.
+type HistoryEntry struct {
+ RunID string `json:"run_id"`
+ AppendedAt string `json:"appended_at"`
+ Providers []string `json:"providers"`
+ SitesTotal int `json:"sites_total"`
+ Captured map[string]int `json:"captured"`
+ Divergences int `json:"divergences"`
+ DivergentMetrics []Divergence `json:"divergent_metrics"`
+}
+
+const historyRenderLimit = 20
+
+// RunCompare implements `runner stealth compare`.
+//
+// usage: runner stealth compare [--no-history] [--history-dir <dir>] <report1.json> <report2.json> ...
+//
+// Loads each report, prints a markdown comparison to stdout, and (unless
+// --no-history is set) appends a one-line summary to history.jsonl + regenerates
+// history.md in the chosen --history-dir. When exactly two reports are passed,
+// a "Divergences" callout is rendered above the per-site tables.
+func RunCompare(argv []string, stdout, stderr io.Writer) int {
+ var (
+ noHistory bool
+ historyDir string
+ paths []string
+ )
+
+ i := 0
+ for i < len(argv) {
+ switch argv[i] {
+ case "--no-history":
+ noHistory = true
+ i++
+ case "--history-dir":
+ if i+1 >= len(argv) {
+ _, _ = fmt.Fprintln(stderr, "stealth compare: --history-dir requires a value")
+ return 1
+ }
+ historyDir = argv[i+1]
+ i += 2
+ case "-h", "--help":
+ _, _ = fmt.Fprintln(stdout, compareUsage)
+ return 0
+ default:
+ if strings.HasPrefix(argv[i], "-") {
+ _, _ = fmt.Fprintf(stderr, "stealth compare: unknown option %q\n", argv[i])
+ return 1
+ }
+ paths = append(paths, argv[i])
+ i++
+ }
+ }
+
+ if len(paths) == 0 {
+ _, _ = fmt.Fprintln(stderr, compareUsage)
+ return 2
+ }
+
+ reports := make([]Report, 0, len(paths))
+ for _, p := range paths {
+ r, err := loadReport(p)
+ if err != nil {
+ _, _ = fmt.Fprintf(stderr, "stealth compare: %v\n", err)
+ return 1
+ }
+ reports = append(reports, r)
+ }
+
+ md, divs := render(paths, reports)
+ _, _ = io.WriteString(stdout, md)
+
+ if !noHistory && len(reports) == 2 {
+ dir := historyDir
+ if dir == "" {
+ // Default: place history files next to the first report.
+ dir = filepath.Dir(paths[0])
+ // If reports/ β†’ ../ (so history.jsonl is in tests/stealth-score/).
+ if filepath.Base(dir) == "results" {
+ dir = filepath.Dir(dir)
+ }
+ }
+ if err := appendHistory(dir, reports, divs); err != nil {
+ _, _ = fmt.Fprintf(stderr, "stealth compare: history append failed: %v\n", err)
+ // Don't fail the whole run on history errors.
+ }
+ }
+ return 0
+}
+
+const compareUsage = `usage: runner stealth compare [--no-history] [--history-dir <dir>] <report1.json> [<report2.json> ...]
+
+Renders a side-by-side markdown comparison from per-provider stealth-score
+JSON reports. When exactly two reports are passed, a "Divergences" callout
+shows metrics where the providers disagreed on real values (entries marked
+"unavailable" on either side are excluded).
+
+Options:
+ --no-history Do not append to history.jsonl / regenerate history.md.
+ --history-dir <dir> Where history.jsonl/history.md live. Default: parent of
+ the reports' directory (so a typical run drops history
+ next to the skill's tests/stealth-score/ directory).`
+
+func loadReport(path string) (Report, error) {
+ var r Report
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ return r, fmt.Errorf("read %s: %w", path, err)
+ }
+ if err := json.Unmarshal(raw, &r); err != nil {
+ return r, fmt.Errorf("parse %s: %w", path, err)
+ }
+ return r, nil
+}
+
+// collectSites returns site IDs in declaration order across reports, plus a
+// per-site slot table (one slot per report position).
+func collectSites(reports []Report) ([]string, map[string][]*SiteRow) {
+ var ordered []string
+ seen := map[string]bool{}
+ for _, r := range reports {
+ for _, s := range r.Sites {
+ if !seen[s.Site] {
+ seen[s.Site] = true
+ ordered = append(ordered, s.Site)
+ }
+ }
+ }
+ slots := map[string][]*SiteRow{}
+ for _, sid := range ordered {
+ slots[sid] = make([]*SiteRow, len(reports))
+ }
+ for ri := range reports {
+ r := &reports[ri]
+ for si := range r.Sites {
+ s := &r.Sites[si]
+ slots[s.Site][ri] = s
+ }
+ }
+ return ordered, slots
+}
+
+// divergences returns metrics where two providers gave different real values.
+// Only meaningful with exactly two reports; caller guards.
+func divergences(sites []string, slots map[string][]*SiteRow) []Divergence {
+ var out []Divergence
+ for _, sid := range sites {
+ entries := slots[sid]
+ a, b := entries[0], entries[1]
+ if a == nil || b == nil {
+ continue
+ }
+ keys := map[string]bool{}
+ for k := range a.Metrics {
+ keys[k] = true
+ }
+ for k := range b.Metrics {
+ keys[k] = true
+ }
+ var ks []string
+ for k := range keys {
+ ks = append(ks, k)
+ }
+ sort.Strings(ks)
+ for _, k := range ks {
+ av, aok := a.Metrics[k]
+ bv, bok := b.Metrics[k]
+ if !aok || !bok {
+ continue
+ }
+ if strings.EqualFold(strings.TrimSpace(av), "unavailable") || strings.EqualFold(strings.TrimSpace(bv), "unavailable") {
+ continue
+ }
+ if strings.TrimSpace(av) == strings.TrimSpace(bv) {
+ continue
+ }
+ out = append(out, Divergence{Site: sid, Metric: k})
+ }
+ }
+ return out
+}
+
+func shorten(s string, n int) string {
+ s = strings.ReplaceAll(s, "|", `\|`)
+ s = strings.ReplaceAll(s, "\n", " ")
+ if len(s) <= n {
+ return s
+ }
+ return s[:n-3] + "..."
+}
+
+func render(paths []string, reports []Report) (string, []Divergence) {
+ providers := make([]string, len(reports))
+ for i, r := range reports {
+ providers[i] = r.Provider
+ if providers[i] == "" {
+ providers[i] = "?"
+ }
+ }
+ sites, slots := collectSites(reports)
+
+ runID := ""
+ if len(reports) > 0 {
+ runID = reports[0].Timestamp
+ }
+ if runID == "" {
+ runID = time.Now().UTC().Format("20060102T150405Z")
+ }
+
+ var b strings.Builder
+ fmt.Fprintf(&b, "# Stealth Score β€” %s β€” %s\n\n", strings.Join(providers, " vs "), runID)
+ fmt.Fprintf(&b, "**Run id**: `%s` \n", runID)
+ counts := make([]string, len(reports))
+ for i, r := range reports {
+ counts[i] = fmt.Sprintf("%s: %d", providers[i], len(r.Sites))
+ }
+ fmt.Fprintf(&b, "**Sites**: %d total (%s) \n", len(sites), strings.Join(counts, " / "))
+
+ var divs []Divergence
+ if len(reports) == 2 {
+ divs = divergences(sites, slots)
+ fmt.Fprintf(&b, "**Divergent metrics**: %d\n\n", len(divs))
+ if len(divs) > 0 {
+ b.WriteString("## Divergences (where providers disagree)\n\n")
+ fmt.Fprintf(&b, "| site | metric | %s | %s |\n", providers[0], providers[1])
+ b.WriteString("|---|---|---|---|\n")
+ for _, d := range divs {
+ a := slots[d.Site][0]
+ bRow := slots[d.Site][1]
+ av, bv := a.Metrics[d.Metric], bRow.Metrics[d.Metric]
+ fmt.Fprintf(&b, "| %s | %s | %s | %s |\n", d.Site, d.Metric, shorten(av, 60), shorten(bv, 60))
+ }
+ b.WriteString("\n")
+ } else {
+ b.WriteString("_no divergent metrics β€” both providers reported the same values everywhere data was available._\n\n")
+ }
+ } else {
+ b.WriteString("\n")
+ }
+
+ b.WriteString("## Full per-site comparison\n\n")
+ for _, sid := range sites {
+ entries := slots[sid]
+ var url string
+ for _, e := range entries {
+ if e != nil && e.URL != "" {
+ url = e.URL
+ break
+ }
+ }
+ fmt.Fprintf(&b, "### %s\n%s\n\n", sid, url)
+
+ // Union of keys, in declaration order across providers.
+ var keys []string
+ seen := map[string]bool{}
+ for _, e := range entries {
+ if e == nil {
+ continue
+ }
+ // stable but readable order
+ var local []string
+ for k := range e.Metrics {
+ local = append(local, k)
+ }
+ sort.Strings(local)
+ for _, k := range local {
+ if !seen[k] {
+ seen[k] = true
+ keys = append(keys, k)
+ }
+ }
+ }
+
+ if len(keys) == 0 {
+ b.WriteString("_no metrics captured_\n")
+ for ri, e := range entries {
+ if e != nil && e.Notes != "" {
+ fmt.Fprintf(&b, "- _%s note: %s_\n", providers[ri], e.Notes)
+ }
+ }
+ b.WriteString("\n")
+ continue
+ }
+
+ header := append([]string{"metric"}, providers...)
+ b.WriteString("| " + strings.Join(header, " | ") + " |\n")
+ b.WriteString("|" + strings.Repeat("---|", len(header)) + "\n")
+ for _, k := range keys {
+ row := []string{k}
+ for _, e := range entries {
+ if e == nil {
+ row = append(row, "β€”")
+ continue
+ }
+ v, ok := e.Metrics[k]
+ if !ok {
+ row = append(row, "β€”")
+ continue
+ }
+ row = append(row, shorten(v, 60))
+ }
+ b.WriteString("| " + strings.Join(row, " | ") + " |\n")
+ }
+ for ri, e := range entries {
+ if e != nil && e.Notes != "" {
+ fmt.Fprintf(&b, "\n- _%s note: %s_\n", providers[ri], e.Notes)
+ }
+ }
+ b.WriteString("\n")
+ }
+
+ b.WriteString("## Artifacts\n")
+ for i, p := range paths {
+ rel := p
+ if abs, err := filepath.Abs(p); err == nil {
+ if cwd, err := os.Getwd(); err == nil {
+ if r, err := filepath.Rel(cwd, abs); err == nil {
+ rel = r
+ }
+ }
+ }
+ fmt.Fprintf(&b, "- %s: `%s`\n", providers[i], rel)
+ }
+ b.WriteString("\n")
+ return b.String(), divs
+}
+
+func appendHistory(dir string, reports []Report, divs []Divergence) error {
+ if dir == "" {
+ return fmt.Errorf("history dir is empty")
+ }
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ return fmt.Errorf("mkdir history dir: %w", err)
+ }
+
+ providers := make([]string, len(reports))
+ captured := map[string]int{}
+ maxSites := 0
+ for i, r := range reports {
+ providers[i] = r.Provider
+ captured[r.Provider] = len(r.Sites)
+ if len(r.Sites) > maxSites {
+ maxSites = len(r.Sites)
+ }
+ }
+ entry := HistoryEntry{
+ RunID: reports[0].Timestamp,
+ AppendedAt: time.Now().UTC().Format(time.RFC3339),
+ Providers: providers,
+ SitesTotal: maxSites,
+ Captured: captured,
+ Divergences: len(divs),
+ DivergentMetrics: divs,
+ }
+ if entry.DivergentMetrics == nil {
+ entry.DivergentMetrics = []Divergence{}
+ }
+
+ line, err := json.Marshal(entry)
+ if err != nil {
+ return fmt.Errorf("marshal history entry: %w", err)
+ }
+
+ jsonlPath := filepath.Join(dir, "history.jsonl")
+ f, err := os.OpenFile(jsonlPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+ if err != nil {
+ return fmt.Errorf("open history.jsonl: %w", err)
+ }
+ if _, err := f.Write(append(line, '\n')); err != nil {
+ _ = f.Close()
+ return fmt.Errorf("write history.jsonl: %w", err)
+ }
+ if err := f.Close(); err != nil {
+ return fmt.Errorf("close history.jsonl: %w", err)
+ }
+
+ return renderHistoryMD(dir, historyRenderLimit)
+}
+
+func renderHistoryMD(dir string, limit int) error {
+ jsonlPath := filepath.Join(dir, "history.jsonl")
+ raw, err := os.ReadFile(jsonlPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ return fmt.Errorf("read history.jsonl: %w", err)
+ }
+ var rows []HistoryEntry
+ for _, ln := range strings.Split(string(raw), "\n") {
+ ln = strings.TrimSpace(ln)
+ if ln == "" {
+ continue
+ }
+ var e HistoryEntry
+ if err := json.Unmarshal([]byte(ln), &e); err != nil {
+ // Skip malformed lines rather than failing β€” history is best-effort.
+ continue
+ }
+ rows = append(rows, e)
+ }
+ // Last N, newest first.
+ if len(rows) > limit {
+ rows = rows[len(rows)-limit:]
+ }
+ // reverse
+ for i, j := 0, len(rows)-1; i < j; i, j = i+1, j-1 {
+ rows[i], rows[j] = rows[j], rows[i]
+ }
+
+ var b strings.Builder
+ fmt.Fprintf(&b, "# Stealth Score β€” History (last %d runs)\n\n", len(rows))
+ b.WriteString("| run_id | providers | sites | divergences | divergent metrics |\n")
+ b.WriteString("|---|---|---|---|---|\n")
+ for _, r := range rows {
+ var sample []string
+ for _, d := range r.DivergentMetrics {
+ if len(sample) >= 5 {
+ break
+ }
+ sample = append(sample, fmt.Sprintf("%s/%s", d.Site, d.Metric))
+ }
+ summary := strings.Join(sample, "; ")
+ if rest := len(r.DivergentMetrics) - len(sample); rest > 0 {
+ summary += fmt.Sprintf(" (+%d more)", rest)
+ }
+ if summary == "" {
+ summary = "β€”"
+ }
+ fmt.Fprintf(&b, "| `%s` | %s | %d | %d | %s |\n", r.RunID, strings.Join(r.Providers, ", "), r.SitesTotal, r.Divergences, summary)
+ }
+
+ mdPath := filepath.Join(dir, "history.md")
+ return os.WriteFile(mdPath, []byte(b.String()), 0o644)
+}
diff --git a/tests/tools/runner/internal/stealth/compare_test.go b/tests/tools/runner/internal/stealth/compare_test.go
new file mode 100644
index 00000000..66036622
--- /dev/null
+++ b/tests/tools/runner/internal/stealth/compare_test.go
@@ -0,0 +1,252 @@
+package stealth
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func writeReport(t *testing.T, path string, r Report) {
+ t.Helper()
+ data, err := json.MarshalIndent(r, "", " ")
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ t.Fatalf("mkdir: %v", err)
+ }
+ if err := os.WriteFile(path, data, 0o644); err != nil {
+ t.Fatalf("write: %v", err)
+ }
+}
+
+func TestCompareDivergences(t *testing.T) {
+ tmp := t.TempDir()
+ resultsDir := filepath.Join(tmp, "results")
+
+ chromePath := filepath.Join(resultsDir, "chrome.json")
+ cloakPath := filepath.Join(resultsDir, "cloak.json")
+
+ writeReport(t, chromePath, Report{
+ Provider: "chrome",
+ Timestamp: "20260520T100000Z",
+ Sites: []SiteRow{
+ {
+ Site: "sannysoft",
+ URL: "https://bot.sannysoft.com/",
+ Metrics: map[string]string{
+ "webdriver": "passed",
+ "webgl_vendor": "Canvas has no webgl context",
+ },
+ },
+ {
+ Site: "creepjs",
+ URL: "https://creepjs.org/",
+ Metrics: map[string]string{
+ "trust_score": "38",
+ "bot": "probably",
+ "gpu": "unavailable",
+ },
+ },
+ },
+ })
+ writeReport(t, cloakPath, Report{
+ Provider: "cloak",
+ Timestamp: "20260520T100000Z",
+ Sites: []SiteRow{
+ {
+ Site: "sannysoft",
+ URL: "https://bot.sannysoft.com/",
+ Metrics: map[string]string{
+ "webdriver": "passed",
+ "webgl_vendor": "Google Inc. (NVIDIA)",
+ },
+ },
+ {
+ Site: "creepjs",
+ URL: "https://creepjs.org/",
+ Metrics: map[string]string{
+ "trust_score": "62",
+ "bot": "no",
+ "gpu": "RTX 4060",
+ },
+ },
+ },
+ })
+
+ var stdout, stderr bytes.Buffer
+ rc := RunCompare([]string{chromePath, cloakPath}, &stdout, &stderr)
+ if rc != 0 {
+ t.Fatalf("exit code = %d; stderr=%q", rc, stderr.String())
+ }
+
+ out := stdout.String()
+
+ wantDivergences := []string{
+ "sannysoft | webgl_vendor",
+ "creepjs | trust_score",
+ "creepjs | bot",
+ }
+ for _, want := range wantDivergences {
+ if !strings.Contains(out, want) {
+ t.Errorf("missing divergent row %q in output", want)
+ }
+ }
+
+ // "webdriver" is the same on both sides β€” should NOT appear in divergences section
+ // but should still appear in the per-site full table.
+ divIdx := strings.Index(out, "## Divergences")
+ fullIdx := strings.Index(out, "## Full per-site comparison")
+ if divIdx == -1 || fullIdx == -1 || divIdx > fullIdx {
+ t.Fatalf("expected Divergences before Full per-site comparison; got divIdx=%d fullIdx=%d", divIdx, fullIdx)
+ }
+ divergencesSection := out[divIdx:fullIdx]
+ if strings.Contains(divergencesSection, "webdriver") {
+ t.Errorf("webdriver should not be in Divergences section (same on both providers)")
+ }
+
+ // gpu was "unavailable" on chrome β€” should be skipped from divergences even though
+ // values differ.
+ if strings.Contains(divergencesSection, "gpu") {
+ t.Errorf("gpu should be skipped from Divergences (chrome value was 'unavailable')")
+ }
+
+ // History should have been written to tmp/ (default = parent of reports/).
+ historyPath := filepath.Join(tmp, "history.jsonl")
+ hist, err := os.ReadFile(historyPath)
+ if err != nil {
+ t.Fatalf("history.jsonl missing: %v", err)
+ }
+ if !strings.Contains(string(hist), `"divergences":3`) {
+ t.Errorf("history entry should record 3 divergences; got: %s", hist)
+ }
+ if !strings.Contains(string(hist), `"run_id":"20260520T100000Z"`) {
+ t.Errorf("history entry missing run_id; got: %s", hist)
+ }
+
+ mdPath := filepath.Join(tmp, "history.md")
+ md, err := os.ReadFile(mdPath)
+ if err != nil {
+ t.Fatalf("history.md missing: %v", err)
+ }
+ if !strings.Contains(string(md), "20260520T100000Z") {
+ t.Errorf("history.md should reference run id")
+ }
+}
+
+func TestCompareNoHistory(t *testing.T) {
+ tmp := t.TempDir()
+ resultsDir := filepath.Join(tmp, "results")
+ chromePath := filepath.Join(resultsDir, "chrome.json")
+ cloakPath := filepath.Join(resultsDir, "cloak.json")
+
+ writeReport(t, chromePath, Report{Provider: "chrome", Timestamp: "ts", Sites: []SiteRow{{Site: "a", Metrics: map[string]string{"x": "1"}}}})
+ writeReport(t, cloakPath, Report{Provider: "cloak", Timestamp: "ts", Sites: []SiteRow{{Site: "a", Metrics: map[string]string{"x": "2"}}}})
+
+ var stdout, stderr bytes.Buffer
+ if rc := RunCompare([]string{"--no-history", chromePath, cloakPath}, &stdout, &stderr); rc != 0 {
+ t.Fatalf("exit code = %d; stderr=%q", rc, stderr.String())
+ }
+
+ if _, err := os.Stat(filepath.Join(tmp, "history.jsonl")); !os.IsNotExist(err) {
+ t.Errorf("--no-history should suppress history.jsonl creation; err=%v", err)
+ }
+}
+
+func TestCompareSingleReport(t *testing.T) {
+ tmp := t.TempDir()
+ chromePath := filepath.Join(tmp, "chrome.json")
+ writeReport(t, chromePath, Report{Provider: "chrome", Timestamp: "ts", Sites: []SiteRow{{Site: "a", URL: "u", Metrics: map[string]string{"x": "1"}}}})
+
+ var stdout, stderr bytes.Buffer
+ if rc := RunCompare([]string{chromePath}, &stdout, &stderr); rc != 0 {
+ t.Fatalf("exit code = %d; stderr=%q", rc, stderr.String())
+ }
+ out := stdout.String()
+ if strings.Contains(out, "## Divergences") {
+ t.Errorf("single-report run should not render Divergences section")
+ }
+ if !strings.Contains(out, "## Full per-site comparison") {
+ t.Errorf("single-report run should still render per-site table")
+ }
+ // Single-report runs should NOT touch history.
+ if _, err := os.Stat(filepath.Join(tmp, "history.jsonl")); !os.IsNotExist(err) {
+ t.Errorf("single-report run should not create history.jsonl; err=%v", err)
+ }
+}
+
+func TestCompareMissingFile(t *testing.T) {
+ var stdout, stderr bytes.Buffer
+ rc := RunCompare([]string{"/no/such/path.json"}, &stdout, &stderr)
+ if rc == 0 {
+ t.Errorf("expected non-zero exit code for missing file")
+ }
+ if !strings.Contains(stderr.String(), "/no/such/path.json") {
+ t.Errorf("stderr should mention missing path; got %q", stderr.String())
+ }
+}
+
+func TestCompareUsageOnNoArgs(t *testing.T) {
+ var stdout, stderr bytes.Buffer
+ rc := RunCompare(nil, &stdout, &stderr)
+ if rc != 2 {
+ t.Errorf("expected exit 2 for no args; got %d", rc)
+ }
+ if !strings.Contains(stderr.String(), "usage:") {
+ t.Errorf("expected usage in stderr; got %q", stderr.String())
+ }
+}
+
+func TestHistoryAppendsAndCapsAtLimit(t *testing.T) {
+ tmp := t.TempDir()
+
+ // Pre-seed history.jsonl with N existing entries to exercise the limit cap.
+ historyPath := filepath.Join(tmp, "history.jsonl")
+ var buf bytes.Buffer
+ for i := 0; i < historyRenderLimit+5; i++ {
+ entry := HistoryEntry{
+ RunID: "old",
+ AppendedAt: "t",
+ Providers: []string{"chrome", "cloak"},
+ SitesTotal: 1,
+ Captured: map[string]int{"chrome": 1, "cloak": 1},
+ Divergences: 0,
+ DivergentMetrics: []Divergence{},
+ }
+ ln, _ := json.Marshal(entry)
+ buf.Write(ln)
+ buf.WriteByte('\n')
+ }
+ if err := os.WriteFile(historyPath, buf.Bytes(), 0o644); err != nil {
+ t.Fatalf("seed history: %v", err)
+ }
+
+ chromePath := filepath.Join(tmp, "chrome.json")
+ cloakPath := filepath.Join(tmp, "cloak.json")
+ writeReport(t, chromePath, Report{Provider: "chrome", Timestamp: "new", Sites: []SiteRow{{Site: "a", Metrics: map[string]string{"x": "1"}}}})
+ writeReport(t, cloakPath, Report{Provider: "cloak", Timestamp: "new", Sites: []SiteRow{{Site: "a", Metrics: map[string]string{"x": "2"}}}})
+
+ var stdout, stderr bytes.Buffer
+ if rc := RunCompare([]string{"--history-dir", tmp, chromePath, cloakPath}, &stdout, &stderr); rc != 0 {
+ t.Fatalf("exit %d; stderr=%q", rc, stderr.String())
+ }
+
+ mdRaw, err := os.ReadFile(filepath.Join(tmp, "history.md"))
+ if err != nil {
+ t.Fatalf("read history.md: %v", err)
+ }
+ md := string(mdRaw)
+ // history.md should only show the last historyRenderLimit rows.
+ if got := strings.Count(md, "`"); got > (historyRenderLimit*2)+5 {
+ t.Errorf("history.md should cap at %d rows; counted %d backticks", historyRenderLimit, got)
+ }
+ // Newest first: "new" row should appear before any "old" row.
+ newIdx := strings.Index(md, "`new`")
+ oldIdx := strings.Index(md, "`old`")
+ if newIdx == -1 || oldIdx == -1 || newIdx > oldIdx {
+ t.Errorf("history.md should show newest first; newIdx=%d oldIdx=%d", newIdx, oldIdx)
+ }
+}
diff --git a/tests/tools/runner/internal/stealth/stealth.go b/tests/tools/runner/internal/stealth/stealth.go
new file mode 100644
index 00000000..cc6937b5
--- /dev/null
+++ b/tests/tools/runner/internal/stealth/stealth.go
@@ -0,0 +1,29 @@
+// Package stealth implements the `runner stealth` subcommand family.
+//
+// It aggregates per-provider stealth-score JSON reports produced by the
+// /pinchtab-stealth-score skill, prints a side-by-side markdown comparison,
+// and appends a one-line summary to history.jsonl so cross-session trends
+// can be inspected.
+package stealth
+
+import (
+ "fmt"
+ "io"
+)
+
+// Run is the entry point dispatched from runner main.
+func Run(argv []string, stdout, stderr io.Writer) int {
+ if len(argv) == 0 {
+ _, _ = fmt.Fprintln(stderr, "usage: runner stealth <compare> [args...]")
+ return 1
+ }
+
+ switch argv[0] {
+ case "compare":
+ return RunCompare(argv[1:], stdout, stderr)
+ default:
+ _, _ = fmt.Fprintf(stderr, "runner stealth: unknown subcommand %q\n", argv[0])
+ _, _ = fmt.Fprintln(stderr, "Use: compare")
+ return 1
+ }
+}
diff --git a/tests/tools/runner/main.go b/tests/tools/runner/main.go
index 78145c0a..fc08d0fa 100644
--- a/tests/tools/runner/main.go
+++ b/tests/tools/runner/main.go
@@ -8,6 +8,7 @@ import (
"github.com/pinchtab/pinchtab/tests/tools/runner/internal/bench"
"github.com/pinchtab/pinchtab/tests/tools/runner/internal/e2e"
"github.com/pinchtab/pinchtab/tests/tools/runner/internal/opt"
+ "github.com/pinchtab/pinchtab/tests/tools/runner/internal/stealth"
)
func main() {
@@ -32,6 +33,8 @@ func run(argv []string, stdout, stderr io.Writer) int {
return opt.Run(argv[1:], stdout, stderr)
case "merge-reports", "verify-answers", "inject-usage":
return opt.Run(argv, stdout, stderr)
+ case "stealth":
+ return stealth.Run(argv[1:], stdout, stderr)
default:
if argv[0] == "--lane" || argv[0] == "--help" || argv[0] == "-h" {
return bench.Run(argv, stdout, stderr)
@@ -48,6 +51,7 @@ func run(argv []string, stdout, stderr io.Writer) int {
_, _ = fmt.Fprintln(stderr, " runner step-end ...")
_, _ = fmt.Fprintln(stderr, " runner opt merge-reports ...")
_, _ = fmt.Fprintln(stderr, " runner opt verify-answers ...")
+ _, _ = fmt.Fprintln(stderr, " runner stealth compare report1.json report2.json")
return 1
}
}