@trawlme/cli 3.11.0 → 3.12.0

package/dist/lib/session-capture.js

@@ -0,0 +1,600 @@
+/**
+ * Orchestrates `trawl scraps account session capture <id>` (trawl_cli#183):
+ * launch a headed, isolated Chrome; let a human log in (2FA included —
+ * Trawl/the agent never sees credentials); read the resulting session over
+ * CDP; scope it to the target domain; hand back a storageState-shaped
+ * result. Does NOT talk to the Trawl API — the command layer
+ * (commands/scraps.ts) owns the `PUT /api/scraps/:id/account/session`
+ * call, same as every other command in this CLI owns its own `api.*`
+ * calls.
+ *
+ * Every I/O boundary (Chrome discovery/launch, the CDP calls themselves,
+ * the temp profile, the "done" prompt) is behind the `Deps` interface so
+ * the orchestration logic — the guard, the race, cleanup-always, count
+ * assembly — is fully testable without a real browser. `captureSession`
+ * itself never throws for an EXPECTED failure (no chrome, non-interactive,
+ * zero in-scope cookies) — those come back as `{ ok: false, reason,
+ * message }` for the command layer to map to the right exit code. An
+ * UNEXPECTED failure (Chrome crashed mid-flight, a CDP call errored) is
+ * caught and returned the same way rather than propagated, so cleanup
+ * always still runs via the single `finally`.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { findChrome } from './chrome-discovery.js';
+import { launchChrome } from './chrome-launch.js';
+import { detectNonInteractive } from './session-capture-guard.js';
+import { mapCookies, mapOrigins, getTargetHost, isOriginHostInScope, } from './storage-state.js';
+/** Shared between the two call sites that can observe Chrome having
+ *  exited before a capture completed (mid-wait, and mid-readCapture). */
+const PROCESS_EXITED_MESSAGE = 'Chrome exited before the session was read — nothing uploaded. The capture completes on Enter in the terminal; Chrome exiting first ends the run without a session.';
+/** Shared between the two call sites that can observe a corrupt CDP frame
+ *  tearing the pipe down (mid-wait, and mid-readCapture) — trawl_cli#183
+ *  review finding 3. `protocolError.message` is internal, factual text
+ *  with no page-controlled content (see cdp-pipe.ts's onProtocolError). */
+function cdpProtocolErrorMessage(protocolError) {
+    return `${protocolError.message} Nothing was uploaded.`;
+}
+/**
+ * The three real (non-fake) CDP orchestration steps, exported for direct
+ * testing against a minimal fake CdpPipe — session-capture.test.ts covers
+ * the OUTER guard/race/cleanup logic with these swapped out entirely;
+ * session-capture-defaults.test.ts covers these directly instead, since
+ * "test the wiring" and "test the wired thing" are two different jobs.
+ */
+export async function findPageTargetDefault(cdp) {
+    const deadline = Date.now() + 10_000;
+    for (;;) {
+        const { targetInfos } = await cdp.send('Target.getTargets');
+        const page = targetInfos.find((t) => t.type === 'page');
+        if (page)
+            return page.targetId;
+        if (Date.now() > deadline)
+            throw new Error('Chrome did not open a page target in time');
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+export async function waitForDoneDefault(cdp, targetId, cleanup) {
+    await cdp.send('Target.setDiscoverTargets', { discover: true });
+    return new Promise((resolve) => {
+        let settled = false;
+        const offDestroyed = cdp.on('Target.targetDestroyed', (params) => {
+            const p = params;
+            if (!settled && p.targetId === targetId) {
+                settled = true;
+                offDestroyed();
+                offClose();
+                rl.close();
+                resolve({ closedEarly: true });
+            }
+        });
+        // If the whole Chrome process dies mid-wait (crash, or a platform where
+        // closing the last window quits it) no `targetDestroyed` event can ever
+        // arrive on a dead pipe — without this, the prompt sits there forever
+        // giving the human no feedback. `captureSession` checks its own
+        // `pipeClosed` flag right after this resolves and turns it into the
+        // factual `process_exited_before_capture` result immediately, rather
+        // than waiting on a keypress that was never going to fix anything.
+        const offClose = cdp.onClose(() => {
+            if (!settled) {
+                settled = true;
+                offDestroyed();
+                rl.close();
+                resolve({ closedEarly: true });
+            }
+        });
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        // Ctrl-C during this prompt never reaches `process` as a real SIGINT —
+        // raw-mode TTY input disables signal generation for it — so the
+        // Interface's own synthesized 'SIGINT' is the only place to catch it.
+        rl.on('SIGINT', () => {
+            settled = true;
+            offDestroyed();
+            offClose();
+            rl.close();
+            cleanup();
+            process.exit(130);
+        });
+        rl.question('Capture completes on Enter once you are signed in, or when the Chrome window is closed: ', () => {
+            if (!settled) {
+                settled = true;
+                offDestroyed();
+                offClose();
+                rl.close();
+                resolve({ closedEarly: false });
+            }
+        });
+    });
+}
+/**
+ * @desc The deadline for the ONE CDP command in this file that runs inside
+ * a page's own renderer rather than Chrome's browser process:
+ * `Runtime.evaluate` reading `window.localStorage`. Deliberately the SAME
+ * 30s as `CdpPipe`'s own browser-process default, not a shorter override —
+ * a post-cap review (trawl_cli#183) found that an earlier 5s value here cut
+ * off a real, terminating synchronous computation (the shape of an
+ * anti-bot challenge solve) at ~5s: `originsUnreadable:1` for a page that
+ * would have captured cleanly at 7s. There is no value that is provably
+ * "long enough" — a renderer truly blocked forever (a native dialog, a
+ * paused debugger) costs the same whether the ceiling is 5s or 30s, while
+ * a renderer doing bounded work of unknown-but-finite length keeps a
+ * chance of finishing for as long as this stays generous. 30s is a
+ * JUDGEMENT call on that trade-off, not a provably-correct number — kept
+ * equal to the pipe's own default so this file doesn't invent a second
+ * number to defend. Passed explicitly to `send()` anyway (rather than
+ * relying on the pipe's own default silently matching) so the deadline
+ * stays a named, assertable constant here regardless of what the pipe
+ * default happens to be. Whatever the outcome, it is always COUNTED and
+ * SURFACED (`originsUnreadable`, plus the human-facing ⚠ line in
+ * scraps.ts) — never silently swallowed; see `readCaptureDefault` below
+ * for the stderr progress line that covers the wait itself.
+ */
+export const LOCALSTORAGE_READ_TIMEOUT_MS = 30_000;
+/** How long to wait, mid-read, before printing a factual "still waiting"
+ *  progress line to stderr — a human who just pressed Enter and is now
+ *  staring at silence for up to `LOCALSTORAGE_READ_TIMEOUT_MS` has no way
+ *  to tell "still working" from "hung". Well under the read deadline so it
+ *  fires long before the read could time out; never printed for a read
+ *  that resolves before this fires (cleared in a `finally`). */
+const LOCALSTORAGE_READ_PROGRESS_MS = 5_000;
+/**
+ * @desc Structural guard for `Runtime.evaluate`'s returned value (see
+ * `readCaptureDefault`'s call site) — trawl_cli#183 post-cap review finding
+ * B. `returnByValue: true` means CDP itself, not page script, produced this
+ * value, but a page can still make the EXPRESSION return arbitrary garbage
+ * without throwing (tampering with `Object.entries`, `Array.prototype.map`,
+ * etc.) — this is the backstop for that, not a claim that the expression
+ * itself is un-tamperable. Anything that fails this check is treated as
+ * page-controlled misbehavior, counted the same as a thrown read.
+ */
+function isLocalStorageEntriesShape(value) {
+    return (Array.isArray(value) &&
+        value.every((e) => typeof e === 'object' && e !== null && typeof e.name === 'string' && typeof e.value === 'string'));
+}
+/**
+ * @desc Phase 1 of the per-page read (trawl_cli#183 R4 fix): every CDP
+ * round-trip SCOPED TO ONE PAGE — attach, the localStorage evaluate,
+ * detach. Every round this catch block went through classified errors by
+ * TYPE (a `CdpTimeoutError` counts, "anything else" rethrows) — the wrong
+ * criterion, because a plain `Error` is exactly what BOTH a page-caused CDP
+ * rejection and a CLI bug look like; no error-class taxonomy tells them
+ * apart. The right discriminant is PROVENANCE: did the rejection come out
+ * of a CDP call for this page, or out of this file's own code running on
+ * data CDP already handed back? This function's OWN BOUNDARY draws that
+ * line structurally instead — `readCaptureDefault` treats ANY rejection
+ * out of here as page-caused, whatever its error class: a `CdpTimeoutError`
+ * (the renderer never answered — a native dialog, a synchronous script, a
+ * paused debugger), or a plain rejection because the target closed
+ * mid-attach/mid-evaluate (reproduced against real Chrome: a second
+ * in-scope page — an OAuth popup, say — closing at the moment the loop
+ * reaches it rejects `Target.attachToTarget` with a plain
+ * `Error("No target with given id found (code -32602)")`, pipe still open,
+ * not a timeout). The one exception `readCaptureDefault` still special-
+ * cases on the way out is `cdp.isClosed` — that means the PIPE itself
+ * died, not this page, and belongs to every other page too.
+ */
+async function readPageOverCdp(cdp, targetId) {
+    let sessionId;
+    try {
+        const attached = await cdp.send('Target.attachToTarget', {
+            targetId,
+            flatten: true,
+        });
+        sessionId = attached.sessionId;
+        // A human who just pressed Enter has no signal at all while this one
+        // call is in flight — print a factual "still waiting" line to stderr
+        // if it runs past LOCALSTORAGE_READ_PROGRESS_MS, so a bounded-but-slow
+        // page (or a genuinely blocked one) doesn't read as a hung CLI.
+        // Cleared unconditionally in the inner `finally` so it never fires
+        // for a read that already resolved. Never the page's URL/title —
+        // only the fact that a read is in progress.
+        const progressTimer = setTimeout(() => {
+            process.stderr.write(`  still waiting for a page to finish its scripts (up to ${LOCALSTORAGE_READ_TIMEOUT_MS / 1000}s)…\n`);
+        }, LOCALSTORAGE_READ_PROGRESS_MS);
+        try {
+            return await cdp.send('Runtime.evaluate', {
+                // Builds the {name,value}[] array directly and returns it via
+                // CDP's OWN serialisation (`returnByValue: true`) rather than
+                // calling the page's `JSON.stringify` and parsing the result
+                // ourselves — trawl_cli#183 post-cap review finding B: a page
+                // that overrides `window.JSON.stringify` to return `"null"`
+                // made our own later `JSON.parse` + `.length` throw a TypeError
+                // that used to be laundered into `originsUnreadable`,
+                // indistinguishable from an ordinary blocked-tab capture.
+                // Chrome's inspector serialiser cannot be tampered with from
+                // page script the way `JSON.stringify` can.
+                expression: 'Object.entries(window.localStorage).map(([name, value]) => ({ name, value }))',
+                returnByValue: true,
+            }, sessionId, LOCALSTORAGE_READ_TIMEOUT_MS);
+        }
+        finally {
+            clearTimeout(progressTimer);
+        }
+    }
+    finally {
+        if (sessionId) {
+            try {
+                await cdp.send('Target.detachFromTarget', { sessionId });
+            }
+            catch {
+                // already detached / target gone — non-fatal either way: this
+                // page's origin is already about to be counted or captured
+            }
+        }
+    }
+}
+export async function readCaptureDefault(cdp, targetUrl, closedEarly) {
+    const { cookies } = await cdp.send('Storage.getCookies', {});
+    if (closedEarly)
+        return { cookies, origins: [], originsUnreadable: 0 };
+    const targetHost = getTargetHost(targetUrl);
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    const pages = targetInfos.filter((t) => t.type === 'page');
+    const origins = [];
+    let originsUnreadable = 0;
+    for (const page of pages) {
+        let origin;
+        try {
+            const u = new URL(page.url);
+            if (!isOriginHostInScope(u.hostname, targetHost))
+                continue;
+            origin = u.origin;
+        }
+        catch {
+            continue;
+        }
+        // Phase 1 — readPageOverCdp above; see its own doc comment. Any
+        // rejection out of it is page-caused BY PROVENANCE, not by error class
+        // (trawl_cli#183 R4) — count it and move on to the next page. The one
+        // exception is `cdp.isClosed`: if the WHOLE pipe was torn down (Chrome
+        // exited, or a corrupt frame — trawl_cli#183 review finding 3), every
+        // remaining `cdp.send` in this loop would reject the same way;
+        // swallowing that here would finish the loop and report an apparently-
+        // successful capture with fewer origins than real. Rethrown so
+        // captureSession's own pipeClosed/protocolError handling reports the
+        // actual cause. Checked unconditionally, before looking at the
+        // rejection at all — a dead pipe is true regardless of which error
+        // under it happens to be surfacing, including a `CdpTimeoutError` that
+        // raced a teardown on the same tick (a `CdpProtocolError` teardown
+        // flips `isClosed` before it rejects any pending command — see
+        // cdp-pipe.ts's `onClosed` — so this one check already covers both
+        // causes; there is no separate `instanceof CdpProtocolError` branch to
+        // maintain).
+        let evalResult;
+        try {
+            evalResult = await readPageOverCdp(cdp, page.targetId);
+        }
+        catch (e) {
+            if (cdp.isClosed)
+                throw e;
+            originsUnreadable++;
+            process.stderr.write('  one in-scope page could not be read over CDP — counted, continuing…\n');
+            continue;
+        }
+        // Phase 2 — post-processing: a decision THIS FILE's OWN code makes on
+        // data CDP already handed back, never another CDP call. Deliberately
+        // OUTSIDE the try/catch above (trawl_cli#183 R4 fix): a bug in this
+        // code must propagate as a genuinely FAILED capture, never get caught
+        // by the page-provenance catch above and laundered into one more
+        // `originsUnreadable` count indistinguishable from an ordinary blocked
+        // tab. That laundering is exactly the bug class R3 fixed once already
+        // (trawl_cli#183 post-cap review finding B) — classifying by error TYPE
+        // inside a single catch cannot keep it fixed, because a plain `Error`
+        // is exactly what BOTH a page-caused CDP rejection (R4) and a CLI bug
+        // (R3) look like; a FUNCTION BOUNDARY can, because Phase 2 never runs
+        // inside Phase 1's `try`. Page garbage is still handled here, by the
+        // structural `isLocalStorageEntriesShape` guard below — but that is a
+        // decision this code makes on data, not an exception this code merely
+        // swallows.
+        if (evalResult.exceptionDetails) {
+            // Runtime.evaluate SUCCEEDED at the CDP layer but the expression
+            // threw INSIDE the page (e.g. a SecurityError on partitioned/
+            // sandboxed storage) — result.value is then undefined, which used
+            // to be silently read as "0 keys" and the origin dropped, making a
+            // blocked read indistinguishable from genuinely empty localStorage
+            // (trawl_cli#183 review finding 4). Counted separately; never the
+            // exception text itself — a page controls that string.
+            originsUnreadable++;
+            continue;
+        }
+        const value = evalResult.result?.value;
+        if (!isLocalStorageEntriesShape(value)) {
+            // Runtime.evaluate raised no page-side exception and CDP's own
+            // serialiser did its job, but the returned value is not the
+            // `{name,value}[]` shape the expression asked for — a page can
+            // still tamper with a global to hand back arbitrary garbage WITHOUT
+            // ever throwing (trawl_cli#183 post-cap review finding B). That is
+            // page-controlled misbehavior, exactly the same actionable fact as a
+            // thrown read — count it, never trust the shape blindly, and never
+            // surface its content (a page controls it).
+            originsUnreadable++;
+            continue;
+        }
+        if (value.length > 0) {
+            origins.push({ origin, entries: value });
+        }
+    }
+    return { cookies, origins, originsUnreadable };
+}
+/**
+ * @desc `rmSync` with a short, bounded, SYNCHRONOUS retry (max ~200ms
+ * total). Verified against a real Chrome launch (trawl_cli#183's loopback
+ * E2E): even after killing Chrome's whole process group (see
+ * chrome-launch.ts's `detached`), a helper subprocess can hold a file
+ * under the profile open for a few milliseconds after the kill signal is
+ * delivered — a bare `rmSync` right after `kill()` lost that race and
+ * silently leaked the temp profile every time. Stays synchronous
+ * (`Atomics.wait`, no `await`) because cleanup must be callable from a
+ * signal handler right before `process.exit()`.
+ */
+export function rmSyncWithRetry(dir) {
+    const MAX_ATTEMPTS = 5;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            return;
+        }
+        catch (e) {
+            if (attempt === MAX_ATTEMPTS)
+                throw e;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40);
+        }
+    }
+}
+/** The conventional shell exit code for each terminating signal this
+ *  process still handles (128 + signal number) — reused here so a killed
+ *  capture reports the same code a bare, unhandled kill would have. */
+const TERMINATION_EXIT_CODES = {
+    SIGHUP: 129,
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+/**
+ * @desc The default `onSigint` implementation, exported for direct testing
+ * (same pattern as `findPageTargetDefault`/`waitForDoneDefault`/
+ * `readCaptureDefault` above — this file's own convention keeps "test the
+ * wiring" and "test the wired thing" separate). Registers `cleanup` on
+ * SIGINT, SIGTERM, AND SIGHUP (trawl_cli#183 review finding 1 — only
+ * SIGINT was registered before this; `timeout` without `--signal`, a bare
+ * `kill <pid>`, most supervisors, and closing the terminal tab mid-login
+ * all default-terminate a process via SIGTERM/SIGHUP, and Node runs no
+ * `finally` for a default-terminated process). SIGKILL is the one signal
+ * this — or any handler, in any process — cannot observe: the OS tears
+ * the process down directly, no userspace code runs at all, so Chrome and
+ * the temp profile are left behind whenever that specific signal is what
+ * ends this process. That gap is inherent, not something a different
+ * signal list here could close.
+ */
+export function registerTerminationHandlers(cleanup) {
+    const signals = Object.keys(TERMINATION_EXIT_CODES);
+    const handlers = signals.map((signal) => {
+        const handler = () => {
+            cleanup();
+            process.exit(TERMINATION_EXIT_CODES[signal]);
+        };
+        process.on(signal, handler);
+        return { signal, handler };
+    });
+    return () => {
+        for (const { signal, handler } of handlers)
+            process.off(signal, handler);
+    };
+}
+/**
+ * @desc The same guard `captureSession` runs internally as its very first
+ * step, exposed so the command layer can call it BEFORE printing anything
+ * about a Chrome window that may never open. Without this, `scraps.ts`
+ * printed its "a Chrome window will open" banner unconditionally, ahead of
+ * this exact check inside `captureSession` — so a non-interactive run saw
+ * that banner immediately followed by "this cannot work headless"
+ * (trawl_cli#183 gap). Reads live process state once; pure
+ * `detectNonInteractive` stays the single source of truth for both call
+ * sites.
+ * @returns {string | null} a factual reason when this command cannot
+ * proceed in the current environment, or null when it can.
+ */
+export function checkInteractiveEnvironment() {
+    return detectNonInteractive({ stdinIsTTY: Boolean(process.stdin.isTTY), platform: process.platform, env: process.env });
+}
+function defaultDeps() {
+    return {
+        detectNonInteractive: checkInteractiveEnvironment,
+        findChrome: () => findChrome(),
+        mkdtemp: () => mkdtempSync(join(tmpdir(), 'trawl-session-')),
+        rmSync: rmSyncWithRetry,
+        launch: (chromePath, targetUrl, userDataDir) => launchChrome(chromePath, targetUrl, userDataDir),
+        findPageTarget: findPageTargetDefault,
+        waitForDone: waitForDoneDefault,
+        readCapture: readCaptureDefault,
+        onSigint: registerTerminationHandlers,
+    };
+}
+/**
+ * @desc Run the full capture flow for one scrap's target URL.
+ * @param {string} targetUrl
+ * @param {Partial<CaptureDeps>} depsOverride — for tests; real deps fill in
+ * the rest.
+ * @returns {Promise<CaptureResult>}
+ */
+export async function captureSession(targetUrl, depsOverride = {}) {
+    const deps = { ...defaultDeps(), ...depsOverride };
+    const guardMessage = deps.detectNonInteractive();
+    if (guardMessage)
+        return { ok: false, reason: 'non_interactive', message: guardMessage };
+    const chromePath = deps.findChrome();
+    if (!chromePath) {
+        return {
+            ok: false,
+            reason: 'no_chrome',
+            message: 'No Chrome or Chromium executable was found. Google Chrome, once installed, is auto-detected; TRAWL_CHROME_PATH names one explicitly.',
+        };
+    }
+    const userDataDir = deps.mkdtemp();
+    let proc;
+    let cleaned = false;
+    // Covers every path this process can observe: return, throw, and SIGINT,
+    // SIGTERM, and SIGHUP (via onSigint/registerTerminationHandlers above —
+    // trawl_cli#183 review finding 1: SIGTERM/SIGHUP were missing before
+    // this, so `timeout` without `--signal`, a bare `kill <pid>`, most
+    // supervisors, and closing the terminal tab mid-login all skipped
+    // cleanup). A SIGKILL of this process itself (OOM, a CI timeout,
+    // `kill -9`) is NOT observable by any handler here — Chrome exits on its
+    // own when the CDP pipe hits EOF, but this cleanup, and so the temp
+    // profile removal below, never runs. That gap is inherent to any
+    // local-Chrome-launch design (not specific to the pipe transport) and is
+    // not closed here.
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        try {
+            if (proc?.pid) {
+                // Kill Chrome's WHOLE process group (it and its own renderer/GPU/
+                // network-service helpers — chrome-launch.ts launches it
+                // `detached` on POSIX for exactly this), never just the single
+                // main-process pid: a bare `proc.kill()` left helper processes
+                // holding the profile open, which is what made rmSync lose the
+                // race below (see rmSyncWithRetry's own comment). Never `-pid` on
+                // win32 — there are no POSIX process groups there, and it isn't
+                // detached in the first place (chrome-launch.ts).
+                if (process.platform === 'win32')
+                    proc.kill('SIGKILL');
+                else
+                    process.kill(-proc.pid, 'SIGKILL');
+            }
+        }
+        catch {
+            // already gone
+        }
+        try {
+            deps.rmSync(userDataDir);
+        }
+        catch {
+            // best-effort — never let cleanup itself throw out of a signal handler
+        }
+    };
+    const unregisterSigint = deps.onSigint(cleanup);
+    let launched;
+    // See CaptureStage's own doc comment. Read only in the catch block below
+    // to decide launch_failed vs capture_failed — never assigned 'upload'.
+    let stage = 'launch';
+    try {
+        launched = await deps.launch(chromePath, targetUrl, userDataDir);
+        proc = launched.proc;
+        let pipeClosed = false;
+        const offClose = launched.cdp.onClose(() => {
+            pipeClosed = true;
+        });
+        stage = 'handshake';
+        const targetId = await deps.findPageTarget(launched.cdp);
+        const { closedEarly } = await deps.waitForDone(launched.cdp, targetId, cleanup);
+        if (pipeClosed) {
+            // A corrupt EVENT frame during the wait (e.g. a garbled
+            // targetDestroyed) tears the pipe down the same way a real Chrome
+            // exit does — `protocolError` distinguishes the two so this doesn't
+            // default to "Chrome exited" for a cause that wasn't that.
+            if (launched.cdp.protocolError) {
+                return {
+                    ok: false,
+                    reason: 'cdp_protocol_error',
+                    message: cdpProtocolErrorMessage(launched.cdp.protocolError),
+                };
+            }
+            return {
+                ok: false,
+                reason: 'process_exited_before_capture',
+                message: PROCESS_EXITED_MESSAGE,
+            };
+        }
+        stage = 'capture';
+        const raw = await deps.readCapture(launched.cdp, targetUrl, closedEarly);
+        offClose();
+        const cookieResult = mapCookies(raw.cookies, targetUrl);
+        const originResult = mapOrigins(raw.origins, targetUrl);
+        // The exact host cookies/origins were scoped against above — not a
+        // peeled "registrable domain" (trawl_cli#183 review finding 2; see
+        // storage-state.ts's module doc comment for why peeling was the bug).
+        const targetDomain = getTargetHost(targetUrl);
+        if (cookieResult.cookies.length === 0) {
+            return {
+                ok: false,
+                reason: 'no_cookies_in_scope',
+                message: `0 cookies in scope for ${targetDomain} — nothing uploaded. Login had not completed on that domain when the capture ran.`,
+            };
+        }
+        return {
+            ok: true,
+            storageState: { cookies: cookieResult.cookies, origins: originResult.origins },
+            targetDomain,
+            counts: {
+                cookiesCaptured: cookieResult.cookies.length,
+                cookiesDroppedOutOfScope: cookieResult.droppedOutOfScope,
+                cookiesDroppedInvalid: cookieResult.droppedInvalid,
+                originsCaptured: originResult.origins.length,
+                originsDroppedOutOfScope: originResult.droppedOutOfScope,
+                originsUnreadable: raw.originsUnreadable,
+                closedEarly,
+            },
+        };
+    }
+    catch (e) {
+        // A CDP call (readCapture, most likely) can reject mid-flight because
+        // Chrome died, or a corrupt frame tore the pipe down, AFTER waitForDone
+        // already resolved normally — the `pipeClosed` check above only covers
+        // the window up to that point. `protocolError` is checked FIRST (it
+        // implies `isClosed` too) so a corrupt-frame failure reports its own
+        // factual reason instead of the generic "Chrome exited"; `isClosed`
+        // alone still distinguishes a real exit from every other unexpected
+        // failure here (a malformed response, a genuinely broken launch).
+        if (launched?.cdp.protocolError) {
+            return {
+                ok: false,
+                reason: 'cdp_protocol_error',
+                message: cdpProtocolErrorMessage(launched.cdp.protocolError),
+            };
+        }
+        if (launched?.cdp.isClosed) {
+            return {
+                ok: false,
+                reason: 'process_exited_before_capture',
+                message: PROCESS_EXITED_MESSAGE,
+            };
+        }
+        // trawl_cli#183 R4: everything above already special-cases a dead pipe
+        // (real exit or a corrupt frame). What's left here — the pipe still
+        // open, no protocol error — used to fall into one undifferentiated
+        // `launch_failed` regardless of WHEN it happened. That mislabels a
+        // `readCapture` failure that occurs after launch + handshake already
+        // succeeded (Chrome reachable over CDP, a page already open, the human
+        // already done logging in): every LEGITIMATE per-page CDP rejection at
+        // that point is already counted as `originsUnreadable` by
+        // `readCaptureDefault`'s own provenance boundary (see
+        // `readPageOverCdp`'s doc comment) — so anything that still reaches
+        // here from the `capture` stage is a genuine bug in THIS CLI (or an
+        // unanticipated non-page-scoped failure, e.g. `Storage.getCookies`
+        // itself), never a "Chrome could not be launched/driven" problem.
+        // `launch`/`handshake` stay `launch_failed`, message unchanged.
+        if (stage === 'capture') {
+            // Never `(e as Error).message` here: the whole point of the R3/R4
+            // history (trawl_cli#183 post-cap review finding B, then R4) is that
+            // a bug in THIS FILE's own code can be TRIGGERED by page-influenced
+            // data (a tampered global, a crafted return value) — nothing
+            // guarantees the resulting exception's own message is free of it, so
+            // the stage name is the only safe, fixed vocabulary to report here.
+            // No counts either: `readCapture` rejected before returning any —
+            // there is no partial `raw` to report counts from.
+            return {
+                ok: false,
+                reason: 'capture_failed',
+                message: 'The capture failed during the capture stage, after Chrome was already reachable over CDP and a page was already open — this is a CLI-side failure, not a page or environment problem. Nothing was uploaded.',
+            };
+        }
+        return { ok: false, reason: 'launch_failed', message: `Chrome could not be driven over CDP: ${e.message}` };
+    }
+    finally {
+        unregisterSigint();
+        cleanup();
+    }
+}