@trawlme/cli 3.12.0 → 3.12.2

package/dist/lib/session-capture.d.ts

@@ -7,31 +7,7 @@ export interface CaptureCounts {
     cookiesDroppedInvalid: number;
     originsCaptured: number;
     originsDroppedOutOfScope: number;
-    /** An in-scope page's localStorage could not be captured, for one of
-     *  four reasons — never a CLI bug, which propagates as a failed capture
-     *  instead (trawl_cli#183 post-cap review finding B, sharpened by the R4
-     *  fix below): a `readPageOverCdp` rejection — ANY CDP-level rejection
-     *  scoped to THIS page's `attachToTarget`/`Runtime.evaluate` round-trip,
-     *  whatever its error class (a timeout because the page's renderer was
-     *  blocked — a native dialog, a synchronous script, a paused debugger; or
-     *  a plain rejection because the target closed mid-attach/mid-evaluate,
-     *  e.g. an OAuth popup the human closed at the wrong instant); the read
-     *  threw INSIDE the page (e.g. a `SecurityError` on partitioned/sandboxed
-     *  storage); or `Runtime.evaluate` succeeded with no exception but
-     *  returned a value that doesn't match the `{name,value}[]` shape asked
-     *  for (a page tampering with a global to hand back garbage without ever
-     *  throwing). The discriminant is PROVENANCE, not error type: did the
-     *  rejection come out of a CDP call scoped to this one page, or out of
-     *  this file's OWN code running on data CDP already handed back? Only the
-     *  latter is a CLI bug, and only the latter propagates. None of these
-     *  four is the same fact as "0 keys": CDP itself was reachable (or the
-     *  pipe wouldn't still be open), the origin just could not be read.
-     *  Counted, never the exception text/URL/value itself (a page controls
-     *  that content). */
     originsUnreadable: number;
-    /** The tracked tab was closed before Enter — cookies were still read,
-     *  localStorage was not (the completion path the issue calls out:
-     *  "closing the window also completes"). */
     closedEarly: boolean;
 }
 export type CaptureFailureReason = 'non_interactive' | 'no_chrome' | 'launch_failed' | 'capture_failed' | 'process_exited_before_capture' | 'cdp_protocol_error' | 'no_cookies_in_scope';
@@ -50,7 +26,6 @@ interface RawCapture {
     origins: RawOriginLocalStorage[];
     originsUnreadable: number;
 }
-/** Every effectful step captureSession needs — overridable for tests. */
 export interface CaptureDeps {
     detectNonInteractive(): string | null;
     findChrome(): string | null;
@@ -60,121 +35,21 @@ export interface CaptureDeps {
         proc: ChildProcess;
         cdp: CdpPipe;
     }>;
-    /** Resolve once Chrome has opened the target URL as a page target. */
     findPageTarget(cdp: CdpPipe): Promise<string>;
-    /**
-     * Race the "done" signal: Enter in the terminal, or the tracked tab
-     * being closed. Resolves with whether the tab closed before Enter.
-     * `cleanup` MUST be wired to the readline Interface's own `'SIGINT'`
-     * event (not just `process.on('SIGINT', …)`) — a TTY readline prompt
-     * puts stdin in raw mode, which stops Ctrl-C from ever generating a real
-     * OS SIGINT in the first place; only the Interface itself observes the
-     * raw 0x03 byte and re-synthesizes it as its own `'SIGINT'` event.
-     */
     waitForDone(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
         closedEarly: boolean;
     }>;
-    /** Read the full (unscoped) cookie jar + open pages' localStorage. */
     readCapture(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
-    /**
-     * Register `cleanup` to run on every ORDINARY terminating signal this
-     * process can still run code for: SIGINT, SIGTERM, and SIGHUP
-     * (trawl_cli#183 review finding 1 — SIGTERM/SIGHUP were missing
-     * entirely, so `timeout` without `--signal`, a bare `kill <pid>`, most
-     * supervisors, and closing the terminal tab mid-login all skipped
-     * cleanup and left Chrome running with the profile on disk). SIGKILL is
-     * the only signal that cannot be handled at all, by any process, ever —
-     * see this function's own default implementation
-     * (`registerTerminationHandlers`) for that boundary spelled out.
-     * Returns an unregister function.
-     */
     onSigint(cleanup: () => void): () => void;
 }
-/**
- * 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 declare function findPageTargetDefault(cdp: CdpPipe): Promise<string>;
 export declare function waitForDoneDefault(cdp: CdpPipe, targetId: string, cleanup: () => void): Promise<{
     closedEarly: boolean;
 }>;
-/**
- * @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 declare const LOCALSTORAGE_READ_TIMEOUT_MS = 30000;
 export declare function readCaptureDefault(cdp: CdpPipe, targetUrl: string, closedEarly: boolean): Promise<RawCapture>;
-/**
- * @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 declare function rmSyncWithRetry(dir: string): void;
-/**
- * @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 declare function registerTerminationHandlers(cleanup: () => void): () => void;
-/**
- * @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 declare function checkInteractiveEnvironment(): string | null;
-/**
- * @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 declare function captureSession(targetUrl: string, depsOverride?: Partial<CaptureDeps>): Promise<CaptureResult>;
 export {};

package/dist/lib/session-capture.js

@@ -1,24 +1,3 @@
-/**
- * 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';
@@ -27,23 +6,10 @@ 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 (;;) {
@@ -70,13 +36,6 @@ export async function waitForDoneDefault(cdp, targetId, cleanup) {
                 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;
@@ -86,9 +45,6 @@ export async function waitForDoneDefault(cdp, targetId, cleanup) {
             }
         });
         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();
@@ -108,73 +64,12 @@ export async function waitForDoneDefault(cdp, targetId, cleanup) {
         });
     });
 }
-/**
- * @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 {
@@ -183,28 +78,11 @@ async function readPageOverCdp(cdp, 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);
@@ -219,8 +97,6 @@ async function readPageOverCdp(cdp, targetId) {
                 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
             }
         }
     }
@@ -245,23 +121,6 @@ export async function readCaptureDefault(cdp, targetUrl, closedEarly) {
         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);
@@ -273,42 +132,12 @@ export async function readCaptureDefault(cdp, targetUrl, closedEarly) {
             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;
         }
@@ -318,17 +147,6 @@ export async function readCaptureDefault(cdp, targetUrl, closedEarly) {
     }
     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++) {
@@ -343,30 +161,11 @@ export function rmSyncWithRetry(dir) {
         }
     }
 }
-/** 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) => {
@@ -382,19 +181,6 @@ export function registerTerminationHandlers(cleanup) {
             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 });
 }
@@ -411,13 +197,6 @@ function defaultDeps() {
         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();
@@ -434,31 +213,12 @@ export async function captureSession(targetUrl, depsOverride = {}) {
     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
@@ -466,19 +226,15 @@ export async function captureSession(targetUrl, depsOverride = {}) {
             }
         }
         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);
@@ -491,10 +247,6 @@ export async function captureSession(targetUrl, depsOverride = {}) {
         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,
@@ -513,9 +265,6 @@ export async function captureSession(targetUrl, depsOverride = {}) {
         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 {
@@ -540,14 +289,6 @@ export async function captureSession(targetUrl, depsOverride = {}) {
         };
     }
     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,
@@ -562,29 +303,7 @@ export async function captureSession(targetUrl, depsOverride = {}) {
                 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',