@trawlme/cli 3.11.0 → 3.12.0

package/README.md

@@ -113,9 +113,12 @@ trawl scraps account delete <id> [--force] [--json]
 trawl scraps account clear-session <id> [--json]
 trawl scraps account status <id> [--json]
 trawl scraps account session set <id> -c <file> [--json]
+trawl scraps account session capture <id> [--chrome <path>] [--json]
 ```
 
-`account session set` uploads a Puppeteer cookie JSON array to bootstrap a logged-in session without storing credentials (BYO-cookies). A missing `-u/--username`/`-p/--password` on `account set` follows the same [non-interactive rule](#non-interactive-rule) as `login`.
+`account session set` uploads a cookie JSON array — or a `{ cookies, origins }` storageState file (see `session capture` below) — to bootstrap a logged-in session without storing credentials (BYO-cookies). A missing `-u/--username`/`-p/--password` on `account set` follows the same [non-interactive rule](#non-interactive-rule) as `login`.
+
+`account session capture <id>` is the one-command version of the same idea: it opens a real, visible Chrome window at the scrap's target URL, waits for **you** to log in there — 2FA included — then reads the resulting session over the Chrome DevTools Protocol (cookies **and** per-origin localStorage) and uploads it. You stay authenticated as yourself; Trawl never sees your credentials, and responsibility for lawful use of the captured session stays with you. The capture is scoped to the scrap's own target host by RFC 6265 domain-matching, the same rule a real browser uses to decide which cookies to send: a cookie explicitly scoped to a domain (e.g. `Domain=example.com`) is in scope for that host and its subdomains, while a host-only cookie (no `Domain` attribute) is in scope only for the exact host it was set on — never a sibling subdomain, even one sharing a parent domain, and never another tenant on the same multi-tenant hosting domain (e.g. a different `*.github.io` site). localStorage follows the same anchor: an origin is in scope only if it's the target host itself or a subdomain of it. The one deliberate gap: a host-only cookie set on a sibling host (e.g. `auth.example.com` while the scrap targets `app.example.com`) is excluded — a real browser would never send it to the target host either, so nothing replay-relevant is lost unless the scrap script itself later navigates to that sibling. Completion is explicit: press Enter in the terminal once you're signed in — the primary path, and the only one guaranteed cross-platform. Closing the Chrome window also completes the capture (cookies only, not localStorage) when Chrome itself stays running after its last window closes, which this CLI verified on macOS; on a platform where closing the last window quits Chrome entirely, the command reports that fact instead of a session, and pressing Enter is the reliable path there. This command needs a local interactive terminal with a real display; it does not work headless, in CI, or over a plain SSH session, and auto-detects a system Chrome/Chromium (override with `--chrome <path>` or `TRAWL_CHROME_PATH`). Never prints the captured session itself, in any mode — `--json` echoes only the server's response plus capture counts.
 
 ### Claude Code skills
 

package/dist/commands/scraps.js

@@ -12,6 +12,8 @@ import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix, isAuthWa
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 import { maybeShowReferralTip } from '../lib/tips.js';
 import { maybeSuggestSkillsForAuthWall } from '../lib/skillsNudge.js';
+import { captureSession, checkInteractiveEnvironment, LOCALSTORAGE_READ_TIMEOUT_MS, } from '../lib/session-capture.js';
+import { assertSecureTransport } from '../lib/secure-transport.js';
 import { getApiUrl } from '../lib/config.js';
 import { resolveDocsUrls, resolveFailureKindDocsUrl } from '../lib/docs.js';
 /**
@@ -1595,32 +1597,69 @@ account
 const accountSession = account
     .command('session')
     .description('Manage scrap account session cookies (flavour B BYO-cookies)');
+/** Structural check only (bare origin format, {name,value} shape) — the
+ *  server's sessionShape.js does the authoritative validation. No domain
+ *  scoping here: unlike `capture`'s CDP path, a hand-authored/exported file
+ *  has no "target URL" to scope against, and the human supplying it already
+ *  chose what to include. */
+function isValidOriginsShape(value) {
+    return (Array.isArray(value) &&
+        value.every((o) => o &&
+            typeof o === 'object' &&
+            typeof o.origin === 'string' &&
+            Array.isArray(o.localStorage) &&
+            o.localStorage.every((kv) => kv && typeof kv === 'object' && typeof kv.name === 'string' && typeof kv.value === 'string')));
+}
 // account session set
 accountSession
     .command('set <id>')
-    .description('Upload browser session cookies for a scrap (Puppeteer cookie JSON array)')
-    .requiredOption('-c, --cookies <file>', 'Path to a Puppeteer cookie JSON array file')
+    .description('Upload a browser session for a scrap — a cookie JSON array, or a { cookies, origins } storageState file (see `session capture`)')
+    .requiredOption('-c, --cookies <file>', 'Path to a cookie JSON array, or a storageState file ({ cookies, origins? })')
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
+    // A session is a bearer-equivalent secret — refuse to PUT it over
+    // plain HTTP (trawl_cli#183 review finding 5). Checked before anything
+    // else in this action, including the file read below.
+    const secureTransportError = assertSecureTransport(getApiUrl());
+    if (secureTransportError) {
+        usageError(secureTransportError, { json: opts.json });
+        return;
+    }
     const { existsSync, readFileSync } = await import('fs');
     if (!existsSync(opts.cookies)) {
         usageError(`File not found: ${opts.cookies}`, { json: opts.json });
         return;
     }
     let cookies;
+    let origins;
     try {
         const raw = readFileSync(opts.cookies, 'utf-8');
-        cookies = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            cookies = parsed;
+        }
+        else if (parsed && typeof parsed === 'object' && Array.isArray(parsed.cookies)) {
+            // storageState-shaped file — trawl_cli#183's `session capture` output shape.
+            const shaped = parsed;
+            cookies = shaped.cookies;
+            if (shaped.origins !== undefined) {
+                if (!isValidOriginsShape(shaped.origins)) {
+                    usageError('origins must be an array of { origin: string, localStorage: [{name, value}] }', { json: opts.json });
+                    return;
+                }
+                origins = shaped.origins;
+            }
+        }
+        else {
+            usageError('Cookies file must contain a JSON array, or a { cookies, origins? } storageState object', { json: opts.json });
+            return;
+        }
     }
     catch (e) {
         usageError(`Failed to parse cookies file: ${e.message}`, { json: opts.json });
         return;
     }
-    if (!Array.isArray(cookies)) {
-        usageError('Cookies file must contain a JSON array', { json: opts.json });
-        return;
-    }
     if (cookies.length === 0) {
         usageError('Cookies array must not be empty', { json: opts.json });
         return;
@@ -1629,7 +1668,10 @@ accountSession
         usageError('Each cookie must have a name (string) and value (string)', { json: opts.json });
         return;
     }
-    const call = () => api.put(`/api/scraps/${id}/account/session`, { cookies });
+    const body = { cookies };
+    if (origins)
+        body.origins = origins;
+    const call = () => api.put(`/api/scraps/${id}/account/session`, body);
     if (opts.json) {
         const data = await call();
         json(data);
@@ -1642,6 +1684,164 @@ accountSession
     const acc = data.account;
     console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
 });
+/**
+ * @desc Map a failed `captureSession()` result onto this CLI's existing
+ * exit-code taxonomy (#71/#88/#107). `no_cookies_in_scope` is the one
+ * outcome where everything ran correctly but nothing was found to upload —
+ * a business-level refusal (exit 1, kind:"refused"), not a usage mistake.
+ *
+ * `capture_failed` (trawl_cli#183 R4) is a SECOND exception, for the
+ * opposite reason: launch + handshake already succeeded — Chrome was
+ * reachable over CDP, a page was already open — and the failure is a
+ * genuine bug in this CLI (or an unanticipated non-page-scoped failure),
+ * never a "cannot run in this environment" problem. Routing it through
+ * `usageError`'s exit 2 / "cannot complete in the current environment"
+ * framing would misclassify it exactly the way a bare `launch_failed` used
+ * to before the R4 fix. Reported instead through `reportError` with a bare
+ * `Error` — `classifyError` has no dedicated `kind` for it, so it falls
+ * into the generic `kind:"unknown"`/exit 1 bucket, the SAME code an
+ * unhandled bug reaching index.ts's own top-level catch would already get.
+ * Never `RefusalError` (this is not a business-logic refusal, everything
+ * up to this point may have gone fine) and never `UsageError` (nothing
+ * about the invocation or the environment was wrong).
+ *
+ * Every remaining reason (non_interactive, no_chrome, launch_failed, the CDP
+ * pipe closing before capture, a corrupt CDP frame tearing it down) means
+ * THIS invocation cannot complete in the current environment — exit 2, the
+ * same bucket `confirmDestructive`'s own non-interactive refusal uses.
+ */
+function reportCaptureFailure(result, opts) {
+    if (result.reason === 'no_cookies_in_scope') {
+        process.exitCode = reportError(new RefusalError(result.message), { json: opts.json });
+        return;
+    }
+    if (result.reason === 'capture_failed') {
+        process.exitCode = reportError(new Error(result.message), { json: opts.json });
+        return;
+    }
+    usageError(result.message, { json: opts.json });
+}
+// account session capture — trawl_cli#183
+accountSession
+    .command('capture <id>')
+    .description('Open a headed Chrome to the scrap\'s target URL, wait for you to log in (2FA included), and capture the session over CDP — cookies AND localStorage. Requires a local interactive terminal with a display; does not work headless, in CI, or over a plain SSH session. You stay authenticated as yourself — Trawl never sees your credentials. Responsibility for lawful use of the captured session stays with you.')
+    .option('--chrome <path>', 'Path to a Chrome/Chromium executable (auto-detected if omitted)')
+    .option('--json', 'Output as JSON (counts only — a session is a bearer secret and is never printed, in any mode)')
+    .action(async (id, opts) => {
+    validateObjectId(id);
+    // A captured session is a bearer-equivalent secret — refuse to PUT it
+    // over plain HTTP (trawl_cli#183 review finding 5). Checked before
+    // anything else, including the scrap lookup below (which itself
+    // already sends the auth token over whatever transport is configured).
+    const secureTransportError = assertSecureTransport(getApiUrl());
+    if (secureTransportError) {
+        usageError(secureTransportError, { json: opts.json });
+        return;
+    }
+    const scrap = await api.get(`/api/scraps/${id}`);
+    if (!scrap.url) {
+        usageError(`Scrap ${id} has no target URL configured — nothing to open a browser to. A URL can be set with: trawl scraps update ${id} -u <url>`, { json: opts.json });
+        return;
+    }
+    // Validated here, before captureSession ever creates a temp profile:
+    // `existsSync` alone doesn't mean `spawn()` can run the file — a
+    // non-executable path fails asynchronously deep inside chrome-launch.ts
+    // instead. That failure is still caught there (an 'error' listener is
+    // the safety net for anything not caught by this pre-flight — a race,
+    // a permission change after this check, PUPPETEER_EXECUTABLE_PATH/
+    // CHROME_PATH), but a pre-flight check gives a faster, more specific
+    // message for the common case: an explicit path the user pointed at.
+    if (opts.chrome) {
+        const { existsSync, accessSync, constants } = await import('fs');
+        if (!existsSync(opts.chrome)) {
+            usageError(`Chrome not found at: ${opts.chrome}`, { json: opts.json });
+            return;
+        }
+        try {
+            accessSync(opts.chrome, constants.X_OK);
+        }
+        catch {
+            usageError(`Chrome exists at ${opts.chrome} but is not executable.`, { json: opts.json });
+            return;
+        }
+    }
+    else if (process.env.TRAWL_CHROME_PATH) {
+        // Same check, same reasoning, for the env-var form of an explicit
+        // path — findChrome() gives TRAWL_CHROME_PATH top precedence and
+        // would otherwise hand this same non-executable path straight to
+        // captureSession.
+        const trawlChromePath = process.env.TRAWL_CHROME_PATH;
+        const { existsSync, accessSync, constants } = await import('fs');
+        if (existsSync(trawlChromePath)) {
+            try {
+                accessSync(trawlChromePath, constants.X_OK);
+            }
+            catch {
+                usageError(`Chrome exists at ${trawlChromePath} (TRAWL_CHROME_PATH) but is not executable.`, { json: opts.json });
+                return;
+            }
+        }
+    }
+    // Check the same guard captureSession runs internally BEFORE printing
+    // anything about a Chrome window that may never open — otherwise a
+    // non-interactive run saw "a window will open" immediately followed by
+    // "this cannot work headless" (trawl_cli#183 gap).
+    const nonInteractiveReason = checkInteractiveEnvironment();
+    if (nonInteractiveReason) {
+        reportCaptureFailure({ ok: false, reason: 'non_interactive', message: nonInteractiveReason }, opts);
+        return;
+    }
+    // Progress/prompts are stderr-only, in every mode — stdout under
+    // --json must stay a single parseable document (#88/#107's rule,
+    // restated for this command by trawl_cli#183's own hard rules).
+    console.error(chalk.dim(`Chrome will open at ${scrap.url} for you to log in there (2FA included); capture completes when you press Enter back in this terminal.`));
+    const result = await captureSession(scrap.url, opts.chrome ? { findChrome: () => opts.chrome ?? null } : {});
+    if (!result.ok) {
+        reportCaptureFailure(result, opts);
+        return;
+    }
+    const call = () => api.put(`/api/scraps/${id}/account/session`, {
+        cookies: result.storageState.cookies,
+        origins: result.storageState.origins,
+    });
+    if (opts.json) {
+        const data = await call();
+        // Never the session itself — only what the server echoes back, plus
+        // counts (#183 hard rule: no cookie/localStorage VALUE, ever, under
+        // --json or otherwise).
+        json({ account: data.account, targetDomain: result.targetDomain, capture: result.counts });
+        return;
+    }
+    const data = await spin(call, {
+        text: `Uploading captured session for scrap ${chalk.bold(id)}…`,
+        successText: `Session captured for scrap ${chalk.bold(id)}: ${result.counts.cookiesCaptured} cookie(s), ${result.counts.originsCaptured} origin(s) in scope for ${result.targetDomain}`,
+    });
+    const acc = data.account;
+    console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
+    if (result.counts.cookiesDroppedOutOfScope > 0 || result.counts.originsDroppedOutOfScope > 0) {
+        console.log(chalk.dim(`  Scoped to ${result.targetDomain}: dropped ${result.counts.cookiesDroppedOutOfScope} cookie(s) and ${result.counts.originsDroppedOutOfScope} origin(s) outside that domain.`));
+    }
+    if (result.counts.closedEarly) {
+        console.log(chalk.dim('  The browser window was closed before Enter — localStorage was not captured (cookies only).'));
+    }
+    if (result.counts.originsUnreadable > 0) {
+        // Impossible to overlook (chalk.yellow + ⚠, not the routine chalk.dim
+        // scope-drop note above) — this is a DEGRADED capture: cookies still
+        // uploaded, but at least one in-scope origin's localStorage did not.
+        // Two distinct causes share this one count: the page threw reading
+        // `window.localStorage` (e.g. a SecurityError on partitioned
+        // storage), or the read never got a response within
+        // LOCALSTORAGE_READ_TIMEOUT_MS (the page's renderer was blocked — a
+        // native dialog, a synchronous script, a paused debugger;
+        // trawl_cli#183 review finding 3's own pipe-level timeout fix
+        // reopened finding 4's exact bug class on this one path, since a
+        // timeout does not close the pipe the way a corrupt frame does). The
+        // two are not split apart here: both mean the same actionable fact
+        // ("re-run once nothing is blocking that tab") and neither one names
+        // the page URL/title/exception text — a page controls that content.
+        console.log(chalk.yellow(`  ⚠ ${result.counts.originsUnreadable} origin(s) could not be captured — threw reading localStorage, or gave no response within ${LOCALSTORAGE_READ_TIMEOUT_MS / 1000}s (a blocked tab). Not the same as being empty; cookies were still captured.`));
+    }
+});
 // account status
 account
     .command('status <id>')

package/dist/lib/cdp-pipe.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Raw Chrome DevTools Protocol client over Chrome's `--remote-debugging-pipe`
+ * transport (trawl_cli#183) — zero new dependencies. This is the SAME
+ * transport Puppeteer's own `pipe: true` mode uses: Chrome reads NUL
+ * (`\0`)-delimited JSON command messages on fd 3 and writes NUL-delimited
+ * JSON response/event messages on fd 4. No port, no `ws`, no HTTP polling
+ * of a `/json/version` endpoint, no parsing Chrome's stderr for a
+ * `DevTools listening on ws://…` line.
+ *
+ * Deliberately generic over any `Writable`/`Readable` pair (not tied to a
+ * real ChildProcess) so the framing/dispatch logic is fully testable with
+ * in-memory streams standing in for "Chrome" — see cdp-pipe.test.ts.
+ */
+import type { Readable, Writable } from 'node:stream';
+type EventHandler = (params: unknown, sessionId?: string) => void;
+/**
+ * A frame Chrome sent could not be parsed as JSON (trawl_cli#183 review
+ * finding 3). Distinguished from the generic "Chrome closed the CDP pipe"
+ * error so a caller can tell "the peer sent garbage and was cut off" apart
+ * from "the process actually exited" — `captureSession` reports the two
+ * with different, factual reasons rather than defaulting a corrupt-frame
+ * case to "Chrome exited".
+ */
+export declare class CdpProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * A `send()` command's own deadline elapsed with no response (trawl_cli#183
+ * review finding 3's fix; the gap it reopened is finding 4's bug class —
+ * see session-capture.ts's `readCaptureDefault`). Deliberately a SIBLING of
+ * `CdpProtocolError`, never a subclass: a protocol error means the pipe
+ * itself can no longer be trusted, so it is torn down (`isClosed` flips
+ * true, every OTHER pending command rejects too). A timeout means exactly
+ * ONE command never got an answer — Chrome is still running, the pipe is
+ * still open, every other in-flight/future command is unaffected. Making
+ * this a `CdpProtocolError` subclass would let a caller's
+ * `instanceof CdpProtocolError` (or a future one) treat a single slow
+ * command as proof the whole browser is gone, which is false. Carries only
+ * `method` and `timeoutMs` — never `params`, which can carry page-
+ * controlled data.
+ */
+export declare class CdpTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}
+export declare class CdpPipe {
+    private readonly writeStream;
+    private readonly commandTimeoutMs;
+    private nextId;
+    private buffer;
+    private readonly pending;
+    private readonly listeners;
+    private closed;
+    private protocolErr;
+    constructor(writeStream: Writable, readStream: Readable, commandTimeoutMs?: number);
+    private onClosed;
+    /**
+     * @desc A frame that fails to parse as JSON used to be dropped silently
+     * (`msg = undefined`, dispatch skipped) — any `send()` whose response was
+     * that exact frame then hung forever, since nothing ever rejected it.
+     * Now the whole pipe is torn down the same way a real Chrome exit is:
+     * every pending command rejects (with a `CdpProtocolError`, not the
+     * generic close message, so the cause is distinguishable), `isClosed`
+     * flips true, and `onClose` subscribers fire — the peer sent a frame
+     * that doesn't fit the protocol, so nothing it says next can be trusted
+     * either. The raw frame content is never included in the error message —
+     * it can carry page-controlled data (e.g. a `Runtime.evaluate` result).
+     */
+    private onProtocolError;
+    private onData;
+    private dispatch;
+    /**
+     * Send a CDP command and resolve with its `result`. Rejects if the pipe
+     * closes (Chrome exited, or a corrupt frame tore it down — see
+     * `onProtocolError`) before a response arrives, or with a
+     * `CdpTimeoutError` if no response arrives within `timeoutMs` (defaults
+     * to the pipe's own `commandTimeoutMs`, 30s) — the timeout names the
+     * METHOD, never `params` (which can carry page-controlled data).
+     * @param timeoutMs — per-call override. Lets a caller pin its own named
+     * deadline as an assertable constant rather than relying on the pipe's
+     * default silently matching (see session-capture.ts's
+     * `LOCALSTORAGE_READ_TIMEOUT_MS`, which currently equals this pipe's own
+     * 30s default but is passed explicitly anyway — a post-cap review found
+     * that giving `Runtime.evaluate` a SHORTER override here, on the
+     * assumption a page-blocked renderer "won't unblock itself in 30s any
+     * more than in 5", cut off real-but-slow work that finished on its own;
+     * there is no override value proven safe, so this parameter exists for
+     * callers that want one, not as a recommendation to use a shorter one).
+     */
+    send<T = unknown>(method: string, params?: unknown, sessionId?: string, timeoutMs?: number): Promise<T>;
+    /** Subscribe to a CDP event (`'Target.targetDestroyed'`, …). Returns an
+     *  unsubscribe function. */
+    on(method: string, handler: EventHandler): () => void;
+    /** Subscribe to the pipe closing (Chrome process gone). */
+    onClose(handler: () => void): () => void;
+    get isClosed(): boolean;
+    /** Set only when the pipe was torn down because of a corrupt frame — as
+     *  opposed to a real Chrome exit — so a caller can report the actual
+     *  cause instead of defaulting every close to "Chrome exited". */
+    get protocolError(): CdpProtocolError | undefined;
+}
+export {};

package/dist/lib/cdp-pipe.js

@@ -0,0 +1,221 @@
+/** Reserved internal event name — never collides with a real CDP method
+ *  (every real one is `Domain.method`, always containing a dot). Emitted
+ *  once the read side of the pipe ends/errors, so any in-flight capture
+ *  can tell "Chrome went away" apart from "the browser answered". */
+const PIPE_CLOSED = '__pipe_closed__';
+/** A per-command deadline that never fires under normal operation. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+/**
+ * A frame Chrome sent could not be parsed as JSON (trawl_cli#183 review
+ * finding 3). Distinguished from the generic "Chrome closed the CDP pipe"
+ * error so a caller can tell "the peer sent garbage and was cut off" apart
+ * from "the process actually exited" — `captureSession` reports the two
+ * with different, factual reasons rather than defaulting a corrupt-frame
+ * case to "Chrome exited".
+ */
+export class CdpProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CdpProtocolError';
+    }
+}
+/**
+ * A `send()` command's own deadline elapsed with no response (trawl_cli#183
+ * review finding 3's fix; the gap it reopened is finding 4's bug class —
+ * see session-capture.ts's `readCaptureDefault`). Deliberately a SIBLING of
+ * `CdpProtocolError`, never a subclass: a protocol error means the pipe
+ * itself can no longer be trusted, so it is torn down (`isClosed` flips
+ * true, every OTHER pending command rejects too). A timeout means exactly
+ * ONE command never got an answer — Chrome is still running, the pipe is
+ * still open, every other in-flight/future command is unaffected. Making
+ * this a `CdpProtocolError` subclass would let a caller's
+ * `instanceof CdpProtocolError` (or a future one) treat a single slow
+ * command as proof the whole browser is gone, which is false. Carries only
+ * `method` and `timeoutMs` — never `params`, which can carry page-
+ * controlled data.
+ */
+export class CdpTimeoutError extends Error {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs) {
+        super(`CDP command '${method}' timed out after ${timeoutMs}ms without a response`);
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+        this.name = 'CdpTimeoutError';
+    }
+}
+export class CdpPipe {
+    writeStream;
+    commandTimeoutMs;
+    nextId = 1;
+    buffer = '';
+    pending = new Map();
+    listeners = new Map();
+    closed = false;
+    protocolErr;
+    constructor(writeStream, readStream, commandTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+        this.writeStream = writeStream;
+        this.commandTimeoutMs = commandTimeoutMs;
+        readStream.setEncoding('utf8');
+        readStream.on('data', (chunk) => this.onData(chunk));
+        readStream.on('end', () => this.onClosed());
+        readStream.on('close', () => this.onClosed());
+        readStream.on('error', () => this.onClosed());
+        // fd 3 (write) and fd 4 (read) are separate sockets — Chrome dying can
+        // surface as an EPIPE on a write that lands before the read side's
+        // 'end'/'close' ever fires. An unhandled 'error' on a Writable is a
+        // thrown exception with no listener, which would kill the whole CLI
+        // process and skip captureSession's `finally` (so the temp profile is
+        // never cleaned up) — routing it through the same onClosed() path
+        // keeps "Chrome went away" a single, always-handled state.
+        writeStream.on('error', () => this.onClosed());
+    }
+    onClosed(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const closeErr = err ?? new Error('Chrome closed the CDP pipe');
+        for (const { reject } of this.pending.values())
+            reject(closeErr);
+        this.pending.clear();
+        const set = this.listeners.get(PIPE_CLOSED);
+        if (set)
+            for (const fn of set)
+                fn(undefined);
+    }
+    /**
+     * @desc A frame that fails to parse as JSON used to be dropped silently
+     * (`msg = undefined`, dispatch skipped) — any `send()` whose response was
+     * that exact frame then hung forever, since nothing ever rejected it.
+     * Now the whole pipe is torn down the same way a real Chrome exit is:
+     * every pending command rejects (with a `CdpProtocolError`, not the
+     * generic close message, so the cause is distinguishable), `isClosed`
+     * flips true, and `onClose` subscribers fire — the peer sent a frame
+     * that doesn't fit the protocol, so nothing it says next can be trusted
+     * either. The raw frame content is never included in the error message —
+     * it can carry page-controlled data (e.g. a `Runtime.evaluate` result).
+     */
+    onProtocolError() {
+        if (this.closed)
+            return;
+        const err = new CdpProtocolError('Chrome sent a CDP frame that failed to parse as JSON — the pipe can no longer be trusted and has been torn down; any in-flight command was rejected.');
+        this.protocolErr = err;
+        this.onClosed(err);
+    }
+    onData(chunk) {
+        // Once torn down (a real close, or a corrupt frame — onProtocolError)
+        // the read stream can still be alive and keep delivering chunks from
+        // an untrusted peer; without this, a later VALID-looking event frame
+        // would still `dispatch()` to any listener still registered instead
+        // of being ignored, and `this.buffer` would keep growing forever.
+        if (this.closed)
+            return;
+        this.buffer += chunk;
+        let idx = this.buffer.indexOf('\0');
+        while (idx !== -1) {
+            const raw = this.buffer.slice(0, idx);
+            this.buffer = this.buffer.slice(idx + 1);
+            if (raw.length > 0) {
+                let msg;
+                try {
+                    msg = JSON.parse(raw);
+                }
+                catch {
+                    this.onProtocolError();
+                    return; // torn down — whatever else is buffered is moot
+                }
+                this.dispatch(msg);
+            }
+            idx = this.buffer.indexOf('\0');
+        }
+    }
+    dispatch(msg) {
+        if (typeof msg.id === 'number' && this.pending.has(msg.id)) {
+            const entry = this.pending.get(msg.id);
+            this.pending.delete(msg.id);
+            if (msg.error)
+                entry.reject(new Error(`${msg.error.message} (code ${msg.error.code})`));
+            else
+                entry.resolve(msg.result);
+            return;
+        }
+        if (typeof msg.method === 'string') {
+            const set = this.listeners.get(msg.method);
+            if (set)
+                for (const fn of set)
+                    fn(msg.params, msg.sessionId);
+        }
+    }
+    /**
+     * Send a CDP command and resolve with its `result`. Rejects if the pipe
+     * closes (Chrome exited, or a corrupt frame tore it down — see
+     * `onProtocolError`) before a response arrives, or with a
+     * `CdpTimeoutError` if no response arrives within `timeoutMs` (defaults
+     * to the pipe's own `commandTimeoutMs`, 30s) — the timeout names the
+     * METHOD, never `params` (which can carry page-controlled data).
+     * @param timeoutMs — per-call override. Lets a caller pin its own named
+     * deadline as an assertable constant rather than relying on the pipe's
+     * default silently matching (see session-capture.ts's
+     * `LOCALSTORAGE_READ_TIMEOUT_MS`, which currently equals this pipe's own
+     * 30s default but is passed explicitly anyway — a post-cap review found
+     * that giving `Runtime.evaluate` a SHORTER override here, on the
+     * assumption a page-blocked renderer "won't unblock itself in 30s any
+     * more than in 5", cut off real-but-slow work that finished on its own;
+     * there is no override value proven safe, so this parameter exists for
+     * callers that want one, not as a recommendation to use a shorter one).
+     */
+    send(method, params = {}, sessionId, timeoutMs = this.commandTimeoutMs) {
+        if (this.closed)
+            return Promise.reject(this.protocolErr ?? new Error('Chrome closed the CDP pipe'));
+        const id = this.nextId++;
+        const req = { id, method, params };
+        if (sessionId)
+            req.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            // Every settle path (dispatch's resolve/reject, this timeout, a
+            // write-side EPIPE below, and onClosed's reject-all on a pipe
+            // teardown) goes through these two wrappers, so the timer is always
+            // cleared exactly once no matter which path wins the race.
+            const settleResolve = (v) => {
+                clearTimeout(timer);
+                resolve(v);
+            };
+            const settleReject = (e) => {
+                clearTimeout(timer);
+                reject(e);
+            };
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                settleReject(new CdpTimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: settleResolve, reject: settleReject });
+            this.writeStream.write(`${JSON.stringify(req)}\0`, (err) => {
+                if (err) {
+                    this.pending.delete(id);
+                    settleReject(err);
+                }
+            });
+        });
+    }
+    /** Subscribe to a CDP event (`'Target.targetDestroyed'`, …). Returns an
+     *  unsubscribe function. */
+    on(method, handler) {
+        if (!this.listeners.has(method))
+            this.listeners.set(method, new Set());
+        this.listeners.get(method).add(handler);
+        return () => this.listeners.get(method)?.delete(handler);
+    }
+    /** Subscribe to the pipe closing (Chrome process gone). */
+    onClose(handler) {
+        return this.on(PIPE_CLOSED, () => handler());
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    /** Set only when the pipe was torn down because of a corrupt frame — as
+     *  opposed to a real Chrome exit — so a caller can report the actual
+     *  cause instead of defaulting every close to "Chrome exited". */
+    get protocolError() {
+        return this.protocolErr;
+    }
+}

package/dist/lib/chrome-discovery.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @desc Resolve the Chrome executable to launch. Precedence: an explicit
+ * `--chrome <path>` flag (validated by the caller) > `TRAWL_CHROME_PATH` >
+ * `PUPPETEER_EXECUTABLE_PATH`/`CHROME_PATH` (common conventions other
+ * tools already set) > the well-known per-OS install paths. Returns null
+ * when nothing is found — the caller is responsible for a factual,
+ * non-guessing error message.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {NodeJS.Platform} platform
+ * @param {(path: string) => boolean} exists — injectable for tests.
+ */
+export declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;