@apmantza/greedysearch-pi 1.8.5 → 1.8.6

package/CHANGELOG.md

@@ -1,6 +1,116 @@
 # Changelog
 
-## Unreleased
+## [1.8.6] — 2026-05-04
+
+### Bing Copilot: Headless Cloudflare Recovery
+
+- **Auto-retry triggers on all Bing failures** — Error pattern expanded from `input not found|verification` to include `clipboard` failures, so any extraction failure triggers the visible Chrome recovery.
+- **Clipboard retry** — `bing-copilot.mjs` now retries clipboard extraction once with a 2s delay, matching the Perplexity extractor pattern.
+- **Cloudflare detection** — If the clipboard is empty and the AI copy button is hidden, the extractor checks the accessibility tree for Cloudflare challenge text and logs it explicitly for faster diagnosis.
+- **DOM extraction fallback** — If clipboard fails and the copy button is missing (headless anti-bot behavior), attempts direct text extraction from the `copilot.fun` → blob: iframe chain via CDP targets. Falls through to the visible auto-retry if Cloudflare blocks the iframe.
+- **Investigation confirmed** — In headless mode, Copilot renders the AI response inside a `copilot.fun` → blob: iframe sandbox with a Cloudflare Turnstile challenge. The `copy-ai-message-button` (`data-testid`) is hidden. Content is unreachable from both the main frame JS (cross-origin) and CDP iframe traversal (Cloudflare blocks load). The only viable path is visible Chrome recovery — once cookies are cached in the profile, subsequent headless searches pass transparently.
+
+### Visible Chrome Recovery
+
+- **Mode-aware `ensureChrome()`** — `src/search/chrome.mjs` now reads a mode marker file (`greedysearch-chrome-mode`) written by `launch.mjs`. When `GREEDY_SEARCH_VISIBLE=1` and Chrome is running headless, it kills and relaunches in visible mode with a forced relaunch guard (always relaunches after kill, even if port wasn't freed).
+- **`launch.mjs` mode check on reuse** — When Chrome is already running and visible is requested (`GREEDY_SEARCH_VISIBLE=1`), checks the mode file. If headless, kills the running instance and launches visible instead of reusing.
+- **Mode file cleanup** — Mode marker file cleaned on `--kill`, ghost cleanup, and idle timeout kill.
+- **`bin/launch-visible.mjs`** — Standalone visible Chrome launcher. Nukes any process on port 9222 (by PID file + port scan), launches Chrome without `--headless`, and writes `"visible"` to the mode file. No ghost cleanup complexity, no mode switching — fire-and-forget visible Chrome.
+- **`bin/visible.mjs`** — Convenience wrapper: kills headless, then launches visible (delegates to `launch-visible.mjs`).
+- **Progress notification** — When the auto-retry launches visible Chrome for manual Cloudflare verification, a `PROGRESS:bing:needs-human` line is emitted to stderr. The progress tracker renders `🔓 bing needs manual verification` in the Pi UI.
+- **Idle cleanup preserves mode** — Headless idle timeout cleanup now also removes the mode marker file.
+
+### Security & Robustness
+
+- **Chrome process cleanup hardening** — `launch-visible.mjs` uses `taskkill /F /PID X /T` (process tree kill) on Windows to prevent orphan renderer processes. Repeated up to 5s until port 9222 is confirmed free.
+- **Zombie Chrome prevention** — `launch.mjs` and `chrome.mjs` now clean up the mode marker and PID file consistently across all kill paths (--kill, ghost cleanup, idle timeout).
+
+### Added
+
+- **`google-search` engine** — plain Google search extractor (locale-agnostic, `textarea[name="q"]`). Returns title/URL/snippet for traditional 10-blue-link results. Aliases: `gs`, `googlesearch`.
+
+### Headless Mode (default)
+
+- **Chrome now runs headless by default** — no window, no GUI, purely background. Set `GREEDY_SEARCH_VISIBLE=1` to show the browser window.
+- **Anti-detection stealth** — Patches injected via `Page.addScriptToEvaluateOnNewDocument` (runs before any page JS):
+  - `Runtime.enable` / CDP marker deletion (`__REBROWSER_*`, `__nightmare`, `__phantom`, etc.)
+  - `navigator.webdriver` → `false`, `navigator.plugins` → realistic list, `navigator.languages` → `['en-US', 'en']`
+  - `window.chrome` shim, WebGL vendor → Intel Iris, `hardwareConcurrency` → 8, `deviceMemory` → 8
+  - `TrustedTypes` policy, `requestAnimationFrame` keep-alive (prevents headless stall detection)
+  - `--disable-blink-features=AutomationControlled`, realistic `--user-agent`, `--window-size=1920,1080`
+- **Human click simulation** — All verification/clicks now use CDP `Input.dispatchMouseEvent` with multi-event `mouseMoved→pressed→released`, ±3px coordinate jitter, and random delays (80–180ms hover, 30–90ms hold). Detection scripts return element selectors instead of clicking in-page; `handleVerification` performs human clicks via `humanClickElement()`/`humanClickXY()`. Applies to Turnstile iframes, reCAPTCHA, Cloudflare challenges, Microsoft auth, Copilot modals, and all generic verify/continue buttons.
+- **Idle auto-cleanup** — Headless Chrome auto-killed after `GREEDY_SEARCH_IDLE_TIMEOUT_MINUTES` (default 5 min) of inactivity. Kills only the PID-tracked instance on port 9222 — never touches the main Chrome session. Activity timestamp written at search start and end.
+
+### Performance
+
+- **Timeouts cut ~40–50%** across all extractors — typical search ~60–90s → ~30–45s:
+  - `TIMING`: postNav 1500→800ms, postNavSlow 2000→1000ms, postClick 400→250ms, postType 400→250ms, inputPoll 400→300ms, copyPoll 600→400ms, afterVerify 3000→2000ms
+  - Defaults: waitForCopyButton 60s→30s, waitForStreamComplete 30s→20s, handleVerification 60s→30s
+  - Per-extractor: Google stream 45s→30s, Gemini copyButton 120s→60s + inputDeadline 10s→8s, Perplexity inputDeadline 8s→5s + stream 30s→20s, Bing verification 90s→30s + copyButton 60s→30s
+  - Engine process timeout: 90s→60s (180s→120s Gemini)
+
+### Security
+
+- **SonarCloud security hotspots fixed** — Two open hotspots resolved:
+  - _Weak cryptography (S2245)_ in `extractors/consent.mjs`: replaced `Math.random()` with `crypto.randomInt()` for the mouse-jitter RNG. Not actually security-sensitive (used only for ±3px jitter and timing delays), but compliant now.
+  - _PATH injection (S4036)_ in `src/search/chrome.mjs`: `spawn("node", ...)` replaced with `spawn(process.execPath, ...)` so the launcher doesn't rely on the `PATH` environment variable.
+- **Query/prompt leakage prevention** — Queries and synthesis prompts no longer appear in OS process tables. All `spawn()` calls now pipe query/prompt through stdin via `--stdin` flag instead of command-line arguments. Affects `runSearch`, `runExtractor`, `synthesizeWithGemini`, and all 5 extractors (`perplexity`, `bing-copilot`, `google-ai`, `google-search`, `gemini`).
+
+### Visual
+
+- **Redesigned banner** — Cleaner SVG layout with pi logo icon, no text, no lens graphic. Gemini Synthesizer pill badge integrated. Three design iterations landed on a minimal icon-only look (`docs/banner.svg`).
+
+### Fixed
+
+- **Gemini & Bing copy button race condition** — Both extractors were capturing the user's query instead of the AI's answer. Root cause: `document.querySelector()` returns the first copy button in DOM order, which is the user's echoed message (above the assistant's response). For short queries this triggers instantly. Fixed by: (1) replacing `waitForCopyButton` with `waitForStreamComplete` to ensure the response finishes streaming before copying, and (2) clicking the **last** copy button (`querySelectorAll` + `[length-1]`) instead of the first — matching Perplexity's proven pattern. Also added periodic scroll-to-bottom alongside stream wait for Gemini to trigger lazy-loaded content.
+- **Progress tracker shows false ✅ for errors** — `makeProgressTracker` in `shared.ts` completely ignored the `status` parameter, always showing `✅ done` for every engine. Now correctly tracks per-engine status and shows `❌ failed` when an engine errors.
+- **Synthesis echoes engine JSON when engines fail** — When Perplexity/Bing fail, Gemini was echoing the engine summary JSON back as its "answer". `synthesis-runner.mjs` now detects this pattern (engine keys without synthesis fields) and treats it as a parse failure, falling back to individual engine results.
+- **`headless=false` parameter ignored** — The `--headless` flag was never checked by `search.mjs` or `launch.mjs`; they only read `GREEDY_SEARCH_VISIBLE`. `shared.ts` now propagates the visibility preference via the env var when `headless=false` is passed.
+
+### Cloudflare / Verification Recovery
+
+- **Auto-recovery from Cloudflare blocks** — When Perplexity (`#ask-input` not found) or Bing (`input not found` / `verification required`) fail in headless mode, `search.mjs` now:
+  1. Detects the Cloudflare/verification error pattern
+  2. Kills headless Chrome, relaunches in visible mode
+  3. Retries the blocked engines — Cloudflare bypasses, cookies stored in Chrome profile
+  4. Kills visible Chrome, relaunches headless
+  5. Continues remaining pipeline (source fetch, synthesis)
+  6. Cookies persist — subsequent headless searches pass transparently
+
+### Removed
+
+- **`coding_task` tool removed** — `bin/coding-task.mjs`, `src/formatters/coding.ts`, registration deleted (644 lines).
+- **`deep_research` tool removed** — handler, test, and `formatDeepResearch` + helpers deleted (521 lines). Use `greedy_search` with `depth: "deep"`.
+- **Minimize debug logs** — Removed 9 verbose `[minimize]` console.log statements from launch.mjs.
+
+### Fixes
+
+- **Code scanning alerts resolved (5 alerts)** — (1) Added `permissions: contents: read` to `sync-to-webaio.yml` workflow (#14). (2) Fixed backslash escaping in `consent.mjs`'s `humanClickElement` selector injection (#10) — selectors containing backslashes (e.g., `\"`) weren't properly escaped before DOM injection. (3) Fixed same backslash escaping in `google-search.mjs`'s `SEARCH_BOX` selector in 3 locations (#11-13).
+- **`cdp.mjs` `getPages()` filter** — Allows `chrome://newtab/` (headless Chrome default initial tab). Prevents "No Chrome tabs found" on cold start.
+
+### Security
+
+- **SonarCloud: Log injection vulnerability (1 alert)** — `bin/launch.mjs` no longer logs the raw WebSocket debugger URL (user-controlled data). Replaced with a static "WebSocket URL received" message to prevent query/URL content from leaking into logs.
+
+### Code Quality
+
+- **SonarCloud batch fixes (~52 issues resolved)** across 16 source files:
+  - `S7781` — Replaced 18 `String#replace()` calls with `String#replaceAll()` for global replacements (regex → literal where applicable).
+  - `S1128` — Removed 15 unused imports (`dirname`, `join`, `relative`, `spawn`, `tmpdir`, `existsSync`, `shouldUseBrowser`, `closeTabs`, `cdp`, `openNewTab`, `closeTab`, `activateTab`, `trimText`).
+  - `S7773` — Migrated 11 `parseInt`/`parseFloat` calls to `Number.parseInt`/`Number.parseFloat`.
+  - `S7780` — Wrapped 8 CDP eval templates containing backslash sequences in `String.raw()` to eliminate double-escaping.
+  - `S7735` — Eliminated 13 negated-condition ternaries by inverting the conditional logic (`!== -1 ? ... : null` → `=== -1 ? null : ...`).
+
+### Security Hotspot Review
+
+- **SonarCloud: 20 security hotspots reviewed and marked Safe** — All outstanding hotspots were assessed and resolved in SonarCloud:
+  - `S4721` OS Command Injection (×2) — Inputs are hardcoded (`port=9222`) or parsed from system output and validated via `Number.parseInt`. Not user-controlled.
+  - `S5852` Regex ReDoS (×10) — Regexes operate on bounded input with negated char classes or short fixed patterns. No practical denial-of-service risk.
+  - `S4036` PATH environment variable (×8) — Local CLI extension spawning package-internal Node scripts. PATH is host-controlled; no untrusted input reaches the command.
+
+### Tooling
+
+- **SonarCloud configuration** — Added `sonar-project.properties` with exclusions for `test/**`, `test.mjs`, `test.sh`, `test_unit.mjs`, and `scripts/**` so test-only code does not skew source quality metrics.
 
 ## v1.8.5 (2026-04-29)
 

package/README.md

@@ -1,98 +1,150 @@
-# GreedySearch for Pi
-
-Multi-engine AI web search for Pi via browser automation.
-
-- No API keys
-- Real browser results (Perplexity, Bing Copilot, Google AI)
-- Optional Gemini synthesis with source grounding
-
-## Install
-
-```bash
-pi install npm:@apmantza/greedysearch-pi
-```
-
-Or from git:
-
-```bash
-pi install git:github.com/apmantza/GreedySearch-pi
-```
-
-## Tools
-
-- `greedy_search` - fast or grounded multi-engine search
-- `coding_task` - browser-routed Gemini/Copilot coding assistance
-
-## Quick usage
-
-```js
-greedy_search({ query: "React 19 changes" })
-greedy_search({ query: "Prisma vs Drizzle", engine: "all", depth: "fast" })
-greedy_search({ query: "Best auth architecture 2026", engine: "all", depth: "deep" })
-```
-
-## Parameters (`greedy_search`)
-
-- `query` (required)
-- `engine`: `all` (default), `perplexity`, `bing`, `google`, `gemini`
-- `depth`: `standard` (default), `fast`, `deep`
-- `fullAnswer`: return full single-engine output instead of preview
-
-## Depth modes
-
-- `fast` - quickest, no synthesis/source fetching
-- `standard` - balanced default for `engine: "all"` (synthesis + fetched sources)
-- `deep` - strongest grounding and confidence metadata
-
-## Runtime commands
-
-```bash
-node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs
-node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs --status
-node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs --kill
-```
-
-## Requirements
-
-- Chrome
-- Node.js 20.11.0+ (22+ recommended)
-
-## Source fetching
-
-When using `depth: "standard"` or `depth: "deep"`, source content is fetched and synthesized:
-
-- **Reddit** — Uses Reddit's public `.json` API for posts and comments (no scraping)
-- **GitHub** — Uses GitHub REST API for repos, READMEs, and file trees
-- **General web** — Mozilla Readability extraction with browser fallback for bot-blocked pages
-- **Metadata** — title, author/byline, site name, publish date, language, excerpt
-
-## Project layout
-
-- `bin/` - runtime CLIs (`search.mjs`, `launch.mjs`, `cdp.mjs`, `coding-task.mjs`)
-- `extractors/` - engine-specific automation
-- `src/` - ranking/fetching/formatting internals (includes `reddit.mjs`, `github.mjs`, `fetcher.mjs`)
-- `skills/` - Pi skill metadata
-
-## Testing
-
-Cross-platform test runner (Windows + Unix):
-```bash
-npm test              # run all tests
-npm run test:quick    # skip slow tests
-npm run test:smoke    # basic health check
-```
-
-Full bash test suite (Unix only):
-```bash
-npm run test:bash           # comprehensive tests
-./test.sh parallel          # race condition tests
-./test.sh flags             # flag/option tests
-```
-
-## Changelog
-
-See `CHANGELOG.md`.
-
-## License
-
-MIT
+# GreedySearch for Pi
+
+![GreedySearch](docs/banner.svg)
+
+Multi-engine AI web search for Pi via browser automation.
+
+- No API keys
+- Real browser results (Perplexity, Bing Copilot, Google AI)
+- Optional Gemini synthesis with source grounding
+- Chrome runs headless by default — no window, purely background
+
+## Install
+
+```bash
+pi install npm:@apmantza/greedysearch-pi
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/apmantza/GreedySearch-pi
+```
+
+## Tools
+
+- `greedy_search` — multi-engine AI web search
+- `websearch` — lightweight DuckDuckGo/Brave search (via pi-webaio)
+- `webfetch` / `webpull` — page fetching and site crawling (via pi-webaio)
+
+## Quick usage
+
+```js
+greedy_search({ query: "React 19 changes" });
+greedy_search({ query: "Prisma vs Drizzle", engine: "all", depth: "fast" });
+greedy_search({
+  query: "Best auth architecture 2026",
+  engine: "all",
+  depth: "deep",
+});
+// Headless is the default — no window. To see the browser:
+// Set GREEDY_SEARCH_VISIBLE=1 before launching Pi
+```
+
+## Parameters (`greedy_search`)
+
+- `query` (required)
+- `engine`: `all` (default), `perplexity`, `bing`, `google`, `gemini`
+- `depth`: `standard` (default), `fast`, `deep`
+- `fullAnswer`: return full single-engine output instead of preview
+- `headless`: set to `false` to show Chrome window (default: `true`)
+
+## Environment variables
+
+| Variable                             | Default       | Description                                               |
+| ------------------------------------ | ------------- | --------------------------------------------------------- |
+| `GREEDY_SEARCH_VISIBLE`              | (unset)       | Set to `1` to show Chrome window instead of headless      |
+| `GREEDY_SEARCH_IDLE_TIMEOUT_MINUTES` | `5`           | Minutes of inactivity before auto-killing headless Chrome |
+| `GREEDY_SEARCH_LOCALE`               | `en`          | Default result language (en, de, fr, es, ja, etc.)        |
+| `CHROME_PATH`                        | auto-detected | Path to Chrome/Chromium executable                        |
+
+## Depth modes
+
+- `fast` - quickest, no synthesis/source fetching
+- `standard` - balanced default for `engine: "all"` (synthesis + fetched sources)
+- `deep` - strongest grounding and confidence metadata
+
+## Runtime commands
+
+````bash
+# Headless (default, no GUI)
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs --status
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch.mjs --kill
+
+# Visible (show browser window — useful for one-time Cloudflare clearance)
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch-visible.mjs
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch-visible.mjs --kill
+
+# Chrome auto-cleaned after 5 min idle (prevents OOM)
+# Override: GREEDY_SEARCH_IDLE_TIMEOUT_MINUTES=10
+
+## Requirements
+
+- Chrome
+- Node.js 20.11.0+ (22+ recommended)
+
+## Known engine quirks
+
+### Bing Copilot
+
+Bing Copilot detects headless Chrome and sandboxes all AI responses inside nested iframes (`copilot.microsoft.com` → `copilot.fun` → `blob:`). In this mode the copy button is hidden and the Cloudflare Turnstile challenge blocks content delivery. The clipboard-based extraction cannot work.
+
+**Auto-recovery:** When Bing fails with any extraction error (clipboard, verification, Cloudflare), GreedySearch automatically switches to **visible Chrome**, retries the search, and caches Cloudflare clearance cookies in the Chrome profile. You may need to solve the Cloudflare challenge **once** manually when the visible Chrome window appears. After that, all subsequent headless searches bypass the challenge — the cookies persist in the profile.
+
+If you prefer to skip the auto-recovery delay, launch visible Chrome ahead of time:
+
+```bash
+node ~/.pi/agent/git/GreedySearch-pi/bin/launch-visible.mjs
+````
+
+## Anti-detection
+
+Headless Chrome auto-injects stealth patches before any page JavaScript runs:
+
+- `navigator.webdriver` hidden, plugins/languages faked, `window.chrome` shimmed
+- WebGL vendor spoofed (Intel Iris), realistic hardware concurrency / memory
+- CDP automation markers deleted, `requestAnimationFrame` kept alive
+- Human-like click simulation with coordinate jitter and variable delays
+
+This bypasses casual bot detection (basic `navigator.webdriver` checks) but does not defeat commercial anti-bot services (DataDome, PerimeterX, Kasada). **Bing Copilot specifically detects headless and sandboxes responses behind Cloudflare Turnstile** — see [Known engine quirks](#known-engine-quirks) for the auto-recovery mechanism.
+
+When using `depth: "standard"` or `depth: "deep"`, source content is fetched and synthesized:
+
+- **Reddit** — Uses Reddit's public `.json` API for posts and comments (no scraping)
+- **GitHub** — Uses GitHub REST API for repos, READMEs, and file trees
+- **General web** — Mozilla Readability extraction with browser fallback for bot-blocked pages
+- **Metadata** — title, author/byline, site name, publish date, language, excerpt
+
+## Project layout
+
+- `bin/` — runtime CLIs (`search.mjs`, `launch.mjs`, `launch-visible.mjs`, `visible.mjs`, `cdp.mjs`)
+- `extractors/` — engine-specific automation + stealth/consent handling
+- `src/` — search pipeline, chrome management, source fetching, formatting
+- `skills/` — Pi skill metadata
+
+## Testing
+
+Cross-platform test runner (Windows + Unix):
+
+```bash
+npm test              # run all tests
+npm run test:quick    # skip slow tests
+npm run test:smoke    # basic health check
+```
+
+Full bash test suite (Unix only):
+
+```bash
+npm run test:bash           # comprehensive tests
+./test.sh parallel          # race condition tests
+./test.sh flags             # flag/option tests
+```
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+## License
+
+MIT

package/bin/cdp.mjs

@@ -28,7 +28,7 @@ const DAEMON_CONNECT_RETRIES = 20;
 const DAEMON_CONNECT_DELAY = 300;
 const MIN_TARGET_PREFIX_LEN = 8;
 
-const _tmpdir = tmpdir().replace(/\\/g, "/");
+const _tmpdir = tmpdir().replaceAll("\\", "/");
 const PAGES_CACHE = `${_tmpdir}/cdp-pages.json`;
 
 function sockPath(targetId) {
@@ -66,7 +66,7 @@ function getWsUrl() {
 	// so GreedySearch targets its own Chrome, not the user's main session.
 	const profileDir = process.env.CDP_PROFILE_DIR;
 	if (profileDir) {
-		const p = `${profileDir.replace(/\\/g, "/")}/DevToolsActivePort`;
+		const p = `${profileDir.replaceAll("\\", "/")}/DevToolsActivePort`;
 		if (existsSync(p)) {
 			const lines = readFileSync(p, "utf8").trim().split("\n");
 			return `ws://localhost:${lines[0]}${lines[1]}`;
@@ -233,7 +233,9 @@ class CDP {
 async function getPages(cdp) {
 	const { targetInfos } = await cdp.send("Target.getTargets");
 	return targetInfos.filter(
-		(t) => t.type === "page" && !t.url.startsWith("chrome://"),
+		(t) =>
+			t.type === "page" &&
+			(!t.url.startsWith("chrome://") || t.url === "chrome://newtab/"),
 	);
 }
 
@@ -365,7 +367,7 @@ async function shotStr(cdp, sid, filePath) {
 	if (dpr === 1) {
 		try {
 			const raw = await evalStr(cdp, sid, "window.devicePixelRatio");
-			const parsed = parseFloat(raw);
+			const parsed = Number.parseFloat(raw);
 			if (parsed > 0) dpr = parsed;
 		} catch {}
 	}
@@ -482,8 +484,8 @@ async function clickStr(cdp, sid, selector) {
 }
 
 async function clickXyStr(cdp, sid, x, y) {
-	const cx = parseFloat(x);
-	const cy = parseFloat(y);
+	const cx = Number.parseFloat(x);
+	const cy = Number.parseFloat(y);
 	if (Number.isNaN(cx) || Number.isNaN(cy))
 		throw new Error("x and y must be numbers (CSS pixels)");
 	const base = { x: cx, y: cy, button: "left", clickCount: 1, modifiers: 0 };
@@ -514,7 +516,10 @@ async function typeStr(cdp, sid, text) {
 
 async function loadAllStr(cdp, sid, selector, intervalMs = 1500) {
 	if (!selector) throw new Error("CSS selector required");
-	intervalMs = Math.min(Math.max(parseInt(intervalMs, 10) || 1500, 100), 30000);
+	intervalMs = Math.min(
+		Math.max(Number.parseInt(intervalMs, 10) || 1500, 100),
+		30000,
+	);
 	let clicks = 0;
 	const deadline = Date.now() + 5 * 60 * 1000;
 	while (Date.now() < deadline) {
@@ -662,7 +667,7 @@ async function runDaemon(targetId) {
 						cdp,
 						sessionId,
 						args[0],
-						args[1] ? parseInt(args[1], 10) : 1500,
+						args[1] ? Number.parseInt(args[1], 10) : 1500,
 					);
 					break;
 				case "evalraw":

package/bin/launch-visible.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// launch-visible.mjs — launch GreedySearch Chrome in VISIBLE mode (window shown).
+// No headless, no mode switching, no ghost cleanup complexity.
+//
+// Usage:
+//   node bin/launch-visible.mjs          — launch visible Chrome
+//   node bin/launch-visible.mjs --kill   — stop Chrome
+//   node bin/launch-visible.mjs --status — check if running
+
+import { execSync, spawn } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import http from "node:http";
+import { platform, tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PORT = 9222;
+const PROFILE_DIR = join(tmpdir(), "greedysearch-chrome-profile");
+const ACTIVE_PORT = join(PROFILE_DIR, "DevToolsActivePort");
+const PID_FILE = join(tmpdir(), "greedysearch-chrome.pid");
+const MODE_FILE = join(tmpdir(), "greedysearch-chrome-mode");
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+function findChrome() {
+	const os = platform();
+	const candidates =
+		os === "win32"
+			? [
+					"C:/Program Files/Google/Chrome/Application/chrome.exe",
+					"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+				]
+			: os === "darwin"
+				? [
+						"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+						"/Applications/Chromium.app/Contents/MacOS/Chromium",
+					]
+				: [
+						"/usr/bin/google-chrome",
+						"/usr/bin/google-chrome-stable",
+						"/usr/bin/chromium-browser",
+						"/usr/bin/chromium",
+					];
+	return candidates.find(existsSync) || null;
+}
+
+function isRunning() {
+	if (!existsSync(PID_FILE)) return false;
+	const pid = Number.parseInt(readFileSync(PID_FILE, "utf8").trim(), 10);
+	if (!pid) return false;
+	try {
+		process.kill(pid, 0);
+		return pid;
+	} catch {
+		return false;
+	}
+}
+
+function getPortPid(port) {
+	try {
+		const os = platform();
+		if (os === "win32") {
+			const out = execSync(`netstat -ano -p TCP 2>nul`, { encoding: "utf8" });
+			const regex = new RegExp(
+				String.raw`TCP\s+[^\s]*:${port}\s+[^\s]*:0\s+LISTENING\s+(\d+)`,
+				"i",
+			);
+			const match = out.match(regex);
+			return match ? Number.parseInt(match[1], 10) : null;
+		}
+	} catch {
+		return null;
+	}
+}
+
+function killProcess(pid) {
+	try {
+		if (platform() === "win32") {
+			execSync(`taskkill /F /PID ${pid} /T`, { stdio: "ignore" });
+		} else {
+			process.kill(pid, "SIGKILL");
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function httpGet(url, timeoutMs = 1000) {
+	return new Promise((resolve) => {
+		const req = http.get(url, (res) => {
+			let body = "";
+			res.on("data", (d) => (body += d));
+			res.on("end", () => resolve({ ok: res.statusCode === 200, body }));
+		});
+		req.on("error", () => resolve({ ok: false }));
+		req.setTimeout(timeoutMs, () => {
+			req.destroy();
+			resolve({ ok: false });
+		});
+	});
+}
+
+async function waitForPort(timeoutMs = 15000) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const { ok, body } = await httpGet(
+			`http://localhost:${PORT}/json/version`,
+			1500,
+		);
+		if (ok) {
+			try {
+				const { webSocketDebuggerUrl } = JSON.parse(body);
+				const wsPath = new URL(webSocketDebuggerUrl).pathname;
+				writeFileSync(ACTIVE_PORT, `${PORT}\n${wsPath}`, "utf8");
+				return true;
+			} catch {}
+		}
+		await new Promise((r) => setTimeout(r, 400));
+	}
+	return false;
+}
+
+// ─── Nuke any Chrome holding port 9222 ────────────────────────────
+
+function nukePort() {
+	// Kill by PID file
+	const pid = isRunning();
+	if (pid) killProcess(pid);
+
+	// Kill by port (ghost)
+	const portPid = getPortPid(PORT);
+	if (portPid && portPid !== pid) killProcess(portPid);
+
+	// Clean up files
+	try {
+		unlinkSync(PID_FILE);
+	} catch {}
+	try {
+		unlinkSync(ACTIVE_PORT);
+	} catch {}
+	try {
+		unlinkSync(MODE_FILE);
+	} catch {}
+
+	// Wait for port to free
+	return new Promise((resolve) => {
+		const start = Date.now();
+		const check = () => {
+			const p = getPortPid(PORT);
+			if (!p) return resolve(true);
+			if (Date.now() - start > 5000) return resolve(false);
+			killProcess(p);
+			setTimeout(check, 500);
+		};
+		check();
+	});
+}
+
+// ─── Main ─────────────────────────────────────────────────────────
+
+async function main() {
+	const arg = process.argv[2];
+
+	if (arg === "--kill") {
+		await nukePort();
+		console.log("Chrome stopped.");
+		return;
+	}
+
+	if (arg === "--status") {
+		const pid = isRunning() || getPortPid(PORT);
+		if (pid) {
+			console.log(`Running — pid ${pid}, port ${PORT}`);
+		} else {
+			console.log("Not running.");
+		}
+		return;
+	}
+
+	// Nuke anything on the port before launching
+	console.log("Stopping any existing Chrome on port 9222...");
+	await nukePort();
+
+	const CHROME_EXE = process.env.CHROME_PATH || findChrome();
+	if (!CHROME_EXE) {
+		console.error("Chrome not found. Set CHROME_PATH env var.");
+		process.exit(1);
+	}
+
+	mkdirSync(PROFILE_DIR, { recursive: true });
+
+	// Visible-only flags — NO --headless
+	const flags = [
+		`--remote-debugging-port=${PORT}`,
+		"--disable-features=DevToolsPrivacyUI",
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--disable-default-apps",
+		`--user-data-dir=${PROFILE_DIR}`,
+		"--profile-directory=Default",
+		"--new-window",
+		"about:blank",
+	];
+
+	console.log("Launching visible Chrome...");
+	const proc = spawn(CHROME_EXE, flags, {
+		detached: true,
+		stdio: "ignore",
+	});
+	proc.unref();
+
+	const chromePid = proc.pid;
+	writeFileSync(PID_FILE, String(chromePid));
+	writeFileSync(MODE_FILE, "visible", "utf8");
+	console.log(`Chrome PID: ${chromePid}`);
+
+	const ready = await waitForPort();
+	if (!ready) {
+		console.error("Chrome did not become ready within 15s.");
+		process.exit(1);
+	}
+
+	console.log("Visible Chrome ready on port 9222.");
+	console.log("Keep this terminal open to keep Chrome alive.");
+}
+
+main();