@trawlme/cli 3.11.0 → 3.12.1

package/dist/commands/scraps.js

@@ -12,58 +12,20 @@ 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';
-/**
- * #185 — `{ docs }` (spreadable, empty object when nothing to add) for a
- * run's JSON payload (`doctor`/`data --errors`/`run-info`), keyed on
- * trawl_node's `failureKind` (NOT errors.ts's unrelated `ErrorEnvelope.kind`
- * — see docs.ts's `FAILURE_KIND_DOC_PATHS` doc comment for why those two
- * `'auth'`s must never be conflated). Reuses `isAuthWall` — the SAME
- * staleness guard `formatDoctor`'s human hint and the #184 skills nudge
- * already share (a `failureKind:'auth'` stamp survives a later
- * success/regression patch, see `isAuthWall`'s own doc comment) — so a run
- * that ultimately succeeded or degraded never carries a stale `docs` link
- * either, exactly the invariant `detectWallVendor`/`isAuthWall` already
- * enforce for the human-facing surfaces. One call site, one rule, reused by
- * all three JSON surfaces below instead of three copies that could drift.
- */
 function runDocsField(run) {
     if (!isAuthWall(run))
         return {};
-    // Whole resolved object (never just `.docsUrl`) so resolveFailureKindDocsUrl
-    // can gate on rung provenance — see docs.ts's DocsUrls.docsUrlIsDerived.
-    // This call never supplies `externalDocsUrl`, so `docsUrl` here can only
-    // ever be rung-2-derived or absent — never a rung-1 server-declared root —
-    // but the gate stays explicit rather than relying on that as an invariant.
     const resolved = resolveDocsUrls({ apiBaseUrl: getApiUrl() });
     const docs = resolveFailureKindDocsUrl(run.failureKind, resolved);
     return docs ? { docs } : {};
 }
-/**
- * Print a usage/validation error consistently: human text to stderr, or a
- * machine envelope on stdout under --json (never both — reportError is the
- * single formatting path shared with index.ts's central catch, #86 finding
- * 9). Sets exit code 2 (usage) — distinct from a business-logic refusal
- * (which stays 1) or an unmapped ApiError/NetworkError (handled centrally in
- * index.ts). (#71)
- */
 function usageError(message, opts = {}) {
     process.exitCode = reportError(new UsageError(message), { json: opts.json });
 }
-/**
- * #163 — client-side URL validation shared by `create`/`update`, mirroring
- * the server's now-required-and-parseable `url` field (trawl_node#1823,
- * PR #1828: `z.string().trim().default('')` -> `z.string().trim().url()`).
- * Gives a readable message BEFORE the request goes out instead of a raw
- * 400/422 from the server. Reuses the exact same `requireUrl` helper
- * `trawl create`/`trawl login --url` already validate against (lib/validate.js),
- * just routed through this file's own return-style `usageError()` convention
- * (never throw — every other validation in this file, tier/limit/page/params/
- * status, follows the same pattern) instead of the throw-style those two
- * commands use. Returns `undefined` (never throws) on a bad value — the
- * caller must check for that and `return` without calling the API.
- */
 function tryValidateUrl(value, opts) {
     try {
         return requireUrl(value, '--url');
@@ -76,28 +38,13 @@ function tryValidateUrl(value, opts) {
         throw err;
     }
 }
-/**
- * One-line rendering of an emptyContext blob for the run-info table. Two
- * buckets are actionable and must stay distinct: selectors that matched zero
- * nodes (the page changed) and selectors the browser rejected outright
- * (`-1`, a bug in the scrap script). Folding the second into "all matched"
- * would report a broken selector as healthy. `--json` still emits the full
- * object, `page.topClasses` / `topAnchorPaths` included.
- */
 function summarizeEmptyContext(ctx) {
     if (!ctx || typeof ctx !== 'object')
         return null;
     const parts = [];
     const selectors = ctx.selectors && typeof ctx.selectors === 'object' ? ctx.selectors : {};
     const names = Object.keys(selectors);
-    // Selectors may themselves contain a comma (`div, span`), so quote each one
-    // — a raw join renders one grouping selector as if it were two.
     const list = (ns) => `${ns.slice(0, 3).map((s) => `\`${s}\``).join(', ')}${ns.length > 3 ? ` (+${ns.length - 3})` : ''}`;
-    // Four disjoint, exhaustive buckets — every selector lands in exactly one, so
-    // no count is ever dropped and none is summarised as something it is not.
-    // `selectors` comes from a Mongoose Mixed field, so a count may be `null` or
-    // a string: that is `unreadable`, which is neither healthy nor zero-match and
-    // must be named as its own thing next to the others, not collapsed into them.
     const isCount = (v) => typeof v === 'number' && Number.isFinite(v);
     const zero = names.filter((s) => selectors[s] === 0);
     const invalid = names.filter((s) => selectors[s] === -1);
@@ -111,15 +58,8 @@ function summarizeEmptyContext(ctx) {
     if (unreadable.length)
         parts.push(`unreadable: ${list(unreadable)}`);
     if (matched.length) {
-        // Named even in a mixed set: "3 of the selectors still work" is the
-        // difference between a page that moved and a page that vanished.
         parts.push(mixed ? `${matched.length} matched` : `${matched.length} selector(s), all matched`);
     }
-    // Same Mixed-field caution on the title: coerce before calling a string
-    // method (a numeric title would otherwise crash `run-info` on the very run
-    // it exists to explain), and test against null/undefined rather than
-    // truthiness so a falsy-but-real title like `0` still shows. Inner double
-    // quotes would close the wrapper early and corrupt the line.
     const title = ctx.page?.title;
     if (title !== undefined && title !== null && String(title) !== '') {
         parts.push(`title="${String(title).replace(/"/g, "'")}"`);
@@ -132,25 +72,16 @@ function lastStatus(scrap) {
     const last = scrap.history?.[0];
     if (!last)
         return 'never';
-    // status:null means a run is IN FLIGHT (node persists {status:null,
-    // statusDetail:null, inFlight:true} the moment a run starts) — that is NOT
-    // the same thing as "this scrap has never run" (no history row at all).
-    // (#88 item 1)
     if (last.status === null)
         return 'running';
     if (last.status === undefined)
         return 'never';
-    // #91 LOW — same regression-as-failure bucketing bug as doctor's badge
-    // (formatDoctor): a regression row's write actually succeeded (item count
-    // just dropped vs baseline, flagged by an async patch afterward — #88 item
-    // 2), so it must not collapse into the same 'failure' bucket a genuine
-    // failed run gets.
     if (last.status === false && last.statusDetail === 'regression')
         return 'regression';
     return last.status === true ? 'success' : 'failure';
 }
 function lastRun(scrap) {
-    return formatDate(scrap.history?.[0]?.createdAt); // #119 — unified DD/MM/YY HH:mm
+    return formatDate(scrap.history?.[0]?.createdAt);
 }
 function statusIcon(status) {
     if (status === 'success')
@@ -159,28 +90,10 @@ function statusIcon(status) {
         return chalk.red('✗');
     if (status === 'running')
         return chalk.cyan('↻');
-    // #91 LOW — distinct amber icon, never the red ✗ a genuine failure gets
-    // (mirrors doctor's "● regression" badge — see formatDoctor).
     if (status === 'regression')
         return chalk.hex('#FFA500')('▼');
     return chalk.dim('—');
 }
-/**
- * #179 — health badge, next to the existing status icon. Two distinct
- * sources, deliberately never blended into one derived verdict:
- *   1. `consecutiveFailedRuns`/`unhealthySince` — present ONLY when `--unhealthy`
- *      asked the API to attach them (see attachListCommand). This is the
- *      live, exact server verdict — shown whenever available, since it is
- *      strictly more informative than the breadcrumb below.
- *   2. `lastCronOutcome === 'skipped_unhealthy'` — always present (a normal
- *      scrap field, no extra query cost), but a STALE breadcrumb of the last
- *      scheduled tick, not a live read: never set on a no-cron scrap, lags
- *      by up to one tick, and flips back to 'ok'/'error' once the recovery
- *      probe fires. Labeled as what it is ("cron paused"), never upgraded to
- *      "unhealthy" — that word is reserved for the live verdict above.
- * Never re-derives either signal from `history[]` — both come straight off
- * the server (#1952 in trawl_node).
- */
 function healthBadge(scrap) {
     if (typeof scrap.consecutiveFailedRuns === 'number' && scrap.consecutiveFailedRuns > 0) {
         const n = scrap.consecutiveFailedRuns;
@@ -191,19 +104,6 @@ function healthBadge(scrap) {
     }
     return chalk.dim('—');
 }
-/**
- * #179 — old-server fallback for `list --unhealthy`, same shape as
- * `warnIfUnconfirmedTier` above (#86 finding 4b): an older trawl_node that
- * predates #1952 ignores the unknown `minConsecutiveFailures` query param
- * entirely and returns the FULL unfiltered list — silently presenting every
- * scrap as "unhealthy" is exactly the kind of unconfirmed-outcome lie that
- * precedent exists to prevent. A confirming server attaches
- * `consecutiveFailedRuns` to EVERY item once the param is set (the
- * controller writes `s.consecutiveFailedRuns || 0` unconditionally in that
- * branch — see trawl_node scraps.controller.js), so its total absence across
- * a non-empty response is the honest tell. Stderr only (safe under --json —
- * stdout purity is untouched), never blocks the (unreliable) results below.
- */
 function healthFilterUnconfirmed(data, unhealthyWasRequested) {
     if (!unhealthyWasRequested || data.length === 0)
         return false;
@@ -212,35 +112,19 @@ function healthFilterUnconfirmed(data, unhealthyWasRequested) {
 function warnIfUnconfirmedHealthFilter(data, unhealthyWasRequested) {
     if (!healthFilterUnconfirmed(data, unhealthyWasRequested))
         return;
-    console.error(chalk.yellow('⚠ Server did not confirm the --unhealthy filter (older server, predates trawl_node#1952) — results below are UNFILTERED, not just the unhealthy scraps.'));
+    console.error(chalk.yellow('⚠ Server did not confirm the --unhealthy filter (older server version, predates this filter) — results below are UNFILTERED, not just the unhealthy scraps.'));
 }
-/**
- * #179 — the machine-readable counterpart to the stderr warning above, in the
- * exact shape `withTierUnconfirmed` already uses for the tier case. A --json
- * caller has no reliable reason to read stderr, so without this a script sees
- * a full unfiltered list and cannot tell it is not the unhealthy set.
- * Emitted ONLY when the filter went unconfirmed — never fabricated otherwise.
- */
 function withHealthFilterUnconfirmed(rows, data, unhealthyWasRequested) {
     if (!healthFilterUnconfirmed(data, unhealthyWasRequested))
         return rows;
     return { scraps: rows, _healthFilterUnconfirmed: true };
 }
 export const scraps = new Command('scraps').description('Manage scraps');
-// shared SSE streaming helper. `asJson` (#107) emits one raw JSON object per
-// line (NDJSON) on stdout instead of the human-formatted timestamped text —
-// a streaming command still needs a pure-stdout machine mode, just line-
-// delimited instead of a single blob (there's no single "final" payload to
-// wait for).
 async function watchActivities(id, asJson) {
     if (!asJson)
         console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
     for await (const event of api.stream(`/api/scraps/${id}/activities/stream`)) {
         try {
-            // #159 — same tolerant parse as api.ts's response-parsing seam: an SSE
-            // activity line can carry the same server-side raw-control-character
-            // quirk as any other API payload, and this feeds `--json` NDJSON
-            // output too (not just create).
             const activity = parseServerJson(event);
             if (asJson) {
                 console.log(JSON.stringify(activity));
@@ -250,34 +134,12 @@ async function watchActivities(id, asJson) {
             console.log(`${chalk.dim(`[${time}]`)} ${activity.message}`);
         }
         catch {
-            // non-JSON lines are heartbeats or SSE comments — skip silently
             if (process.env['DEBUG'] && event.trim()) {
                 console.error(chalk.dim(`[SSE] skipping non-JSON: ${event}`));
             }
         }
     }
 }
-/**
- * #91 P1 / #93 item 1 — snapshot the current top history entry BEFORE
- * triggering a run, so pollRunProgress can later tell "the run we just
- * launched" apart from whatever the last run happened to be. Node persists a
- * fresh {status:null, inFlight:true} row the moment a run starts (see
- * HistorysService.create in trawl_node), so a changed history[0]._id is
- * normally an honest "the new run has begun" signal — EXCEPT `trigger`
- * (method:'worker') dedups onto an already-pending/running worker job
- * (ScrapJobsService, LIVE_STATUSES) instead of creating a new row: the top
- * row's `_id` never changes even though this launch IS that run. Recording
- * `alreadyInFlight` (status===null at capture time) lets pollRunProgress
- * recognize that dedup case too, instead of waiting forever for an `_id`
- * that will never arrive (#93 item 1).
- *
- * #97 — a failed lookup used to fall back to `{alreadyInFlight:false}` with
- * no `id`, which LOOKED identical to "scrap has never run" — but is not:
- * the scrap may well have prior (possibly terminal) history this GET simply
- * never observed. `captured:false` flags that distinction explicitly so
- * pollRunProgress can defer trusting a baseline instead of risking a stale
- * pre-existing row being reported as the run just launched.
- */
 async function captureBeforeRunState(id) {
     try {
         const scrap = await api.get(`/api/scraps/${id}`);
@@ -292,115 +154,14 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 const POLL_INTERVAL_MS = 2000;
-// Mirrors LONG_RUN_TIMEOUT_MS (#91 item 1) — the server-side worst case this
-// polls for is the same one that timeout was sized for.
 const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
-// #107 review F1 — a genuinely unreachable API must not run the watch
-// silently for the full 300s timeout with dead air; after this many
-// CONSECUTIVE (not cumulative — any successful poll resets the counter)
-// failed polls, treat it as a persistent error and surface it immediately
-// instead of waiting out the clock. At the default 2s interval this gives up
-// after ~10s of continuous failures — comfortably longer than any single
-// transient blip, nowhere near the 300s ceiling.
 const MAX_CONSECUTIVE_POLL_ERRORS = 5;
-/**
- * #91 P1 — replaces "await the run to completion, THEN open the activities
- * SSE stream" (which showed NOTHING: the activities SSE
- * (GET /api/scraps/:id/activities/stream) is backed by an in-process
- * EventEmitter with no backlog — trawl_node
- * modules/activities/services/activities.service.js — so by the time a
- * synchronous run has already finished there is nothing left to emit; and
- * the async `trigger` default enqueues the run onto a durable job queue a
- * SEPARATE cron-consumer pod drains, whose in-process emitter never reaches
- * the API pod holding the SSE connection at all).
- *
- * Instead this polls two REST reads that are BOTH Mongo-backed (not
- * in-process), so they work no matter which pod actually executed the run:
- *  - GET /api/scraps/:id/activities?history=<hid>&limit=20 — the SAME
- *    activities-list endpoint `doctor`'s fetchRunAndFix already calls
- *    (src/commands/doctor.ts) — prints each new activity line once the new
- *    run's history id is known.
- *  - GET /api/scraps/:id — history[0].status/statusDetail, the SAME
- *    terminal-status signal `lastStatus()` above already trusts (status:null
- *    === in flight, #88 item 1) to know when the run is done.
- *
- * #93 item 1 — dedup-race fix. "Is this the run we're watching?" used to be
- * a single check: `history[0]._id !== beforeHistoryId`. That's wrong when
- * `before.alreadyInFlight` is true (a `trigger` call deduped onto a worker
- * job that was ALREADY pending/running at capture time): the top row IS the
- * run we're watching, but its `_id` never changes, so the old guard never
- * released and the poll ran the full timeout to a false "Timed out". The run
- * we're watching is now EITHER a brand-new id (fresh trigger, the common
- * case) OR the same id that was already in-flight (status:null) at capture
- * (the dedup case) — a same-id row that was already TERMINAL at capture is
- * neither, and must not be latched onto as "done" (it's just the previous
- * run, still sitting there until a genuinely new run supersedes it).
- *
- * #97 — capture-failed fallback. The dedup-race fix above assumes `before`
- * is trustworthy. When `captureBeforeRunState`'s own GET threw,
- * `before.id` is `undefined` — and that is INDISTINGUISHABLE from "the
- * scrap has genuinely never run" (also `id: undefined`), which is exactly
- * the case `isNewRun` above is designed to match on the very first row that
- * ever appears. So on the very first poll, ANY pre-existing history row —
- * even the STALE PREVIOUS run, already terminal — satisfied
- * `last._id !== undefined` and got reported as "the run we just launched"
- * finishing, when it was really just whatever ran before.
- *
- * Fix: `before.captured === false` defers trusting a baseline at all.
- * Instead of comparing against the (unknown) `beforeId` from the start, the
- * FIRST successful poll read is treated as the deferred capture itself —
- * exactly what `captureBeforeRunState` would have returned had its GET
- * succeeded — and only READS from that point on are compared against it,
- * via the exact same `isNewRun` / `isDedupOntoInFlight` logic above. A
- * pre-existing terminal row observed on that first read becomes `beforeId`
- * (not a match for itself), so it correctly falls into "still the stale
- * previous run" below and the poll keeps waiting; a row still in flight
- * becomes the `alreadyInFlight` baseline, exactly like a successful capture
- * would have recorded. Either way this costs at most one extra poll
- * interval, bounded by the same deadline as everything else. The one
- * remaining edge case — capture failed AND the scrap never ran before AND
- * the triggered run already finished by the very first poll — is genuinely
- * undecidable from "stale pre-existing row" with no more information than
- * this function has, so it resolves to the same honest timeout rather than
- * risk reporting a possibly-wrong outcome (never a lie, at worst a timeout
- * telling the caller to check `doctor`).
- *
- * #107 review F1 — before this fix, `run|trigger --json --watch` was
- * outcome-blind: `quiet` suppressed ALL output (including "Run finished:
- * failure" and the timeout notice), a transient poll error was caught and
- * silently retried FOREVER within the deadline, and the process always
- * exited 0 after the poll loop regardless of what the watched run actually
- * did — dead air, then a clean exit code, even for a failed or timed-out
- * run. An agent scripting this CLI had no way to tell success from failure
- * from "we gave up". Fixed by:
- *  - emitting exactly ONE final NDJSON line on stdout under `--json` once
- *    the watch reaches ANY of its three exits (terminal status, timeout, or
- *    a persistent poll error) — `{runId,status}` (+`error` for a poll
- *    error) — while every intermediate progress line stays suppressed
- *    (unchanged from before);
- *  - setting `process.exitCode` non-zero on a genuine run failure, a
- *    timeout, or a persistent poll error, and `0` on a real success — in
- *    BOTH `--json` and human `--watch` modes (human mode used to exit 0
- *    unconditionally, the same bug, just silent instead of dishonest);
- *  - giving up after `MAX_CONSECUTIVE_POLL_ERRORS` consecutive failed reads
- *    instead of retrying the same dead endpoint for the full 300s.
- */
 export async function pollRunProgress(id, before, opts = {}) {
     const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
     const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
-    // #107 — `run --json --watch` / `trigger --json --watch` must keep stdout
-    // pure JSON: none of this function's intermediate progress text is safe to
-    // print once a caller asked for --json. `asJson` suppresses every
-    // intermediate console.log below (including the pinch celebration frame)
-    // while the polling/wait logic itself runs unchanged; the ONE exception is
-    // the single final outcome line emitted right before each return below.
     const asJson = opts.json ?? false;
     let beforeId = before?.id;
     let beforeAlreadyInFlight = before?.alreadyInFlight ?? false;
-    // #97 — only an EXPLICIT captured:false (capture's GET actually threw)
-    // defers the baseline. `before` itself being undefined (callers that skip
-    // capture entirely) or `captured` being true/absent both mean "trust
-    // beforeId as given", preserving every existing call site's behavior.
     let baselineEstablished = before?.captured ?? true;
     if (!asJson) {
         console.log(chalk.dim('Live activity streaming has no signal for this run (async/cross-pod) — polling for progress instead…\n'));
@@ -420,11 +181,6 @@ export async function pollRunProgress(id, before, opts = {}) {
         }
         catch (err) {
             consecutivePollErrors++;
-            // #107 review F1 — a single failed read is still a TRANSIENT blip,
-            // safe to retry within the deadline (unchanged). Only once reads fail
-            // this many times IN A ROW is the API treated as genuinely
-            // unreachable — surface that honestly instead of quietly burning the
-            // full 300s timeout on a dead endpoint.
             if (consecutivePollErrors >= MAX_CONSECUTIVE_POLL_ERRORS) {
                 const message = err instanceof Error ? err.message : String(err);
                 if (asJson) {
@@ -441,13 +197,8 @@ export async function pollRunProgress(id, before, opts = {}) {
         }
         const last = scrap.history?.[0];
         if (!last?._id)
-            continue; // no history row recorded yet
+            continue;
         if (!baselineEstablished) {
-            // #97 — deferred capture: whatever we see on this first successful
-            // read becomes the reference point, BEFORE the isNewRun check below
-            // ever runs against it. This must happen before that check, not
-            // after, so a pre-existing terminal row is recognized as stale on
-            // this very same iteration rather than one poll late.
             beforeId = last._id;
             beforeAlreadyInFlight = last.status === null;
             baselineEstablished = true;
@@ -455,10 +206,9 @@ export async function pollRunProgress(id, before, opts = {}) {
         const isNewRun = last._id !== beforeId;
         const isDedupOntoInFlight = last._id === beforeId && beforeAlreadyInFlight;
         if (!isNewRun && !isDedupOntoInFlight)
-            continue; // still the stale previous run
+            continue;
         try {
             const activities = await api.get(`/api/scraps/${id}/activities?history=${last._id}&limit=20`);
-            // Server returns newest-first — print unseen ones oldest-first.
             for (const a of [...(activities ?? [])].reverse()) {
                 const key = a._id ?? `${a.createdAt}:${a.message}`;
                 if (seen.has(key))
@@ -471,16 +221,9 @@ export async function pollRunProgress(id, before, opts = {}) {
             }
         }
         catch {
-            // best-effort — terminal detection below still works without activity lines
         }
         if (last.status !== null) {
             const outcome = last.statusDetail ?? (last.status ? 'success' : 'failure');
-            // #107 review F1 — the exit code, in BOTH modes: a regression row's
-            // WRITE actually succeeded (see lastStatus()'s own #91 comment above,
-            // and `scraps data`'s isRegression branch) and an 'empty' row is a
-            // genuine zero-item success — neither is a real failure. Only
-            // status:false with neither of those details (e.g. 'error', or no
-            // detail at all) is a genuine failed run.
             const isGenuineFailure = last.status === false && outcome !== 'empty' && outcome !== 'regression';
             if (asJson) {
                 const payload = { runId: last._id, status: outcome };
@@ -488,10 +231,6 @@ export async function pollRunProgress(id, before, opts = {}) {
             }
             else {
                 console.log(chalk.dim(`Run finished: ${outcome}`));
-                // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
-                // `status === true` success definition (regardless of statusDetail),
-                // never for a failed/regression run. Guarded by pinchEnabled()
-                // (NO_COLOR/non-TTY) and never under --json (stdout must stay pure).
                 if (last.status === true && pinchEnabled()) {
                     console.log(renderPinch('celebrating'));
                 }
@@ -500,9 +239,6 @@ export async function pollRunProgress(id, before, opts = {}) {
             return;
         }
     }
-    // #107 review F1 — timeout: honest non-zero exit in both modes, plus the
-    // machine-readable final line under --json (never silently exit 0 after a
-    // watch that never actually confirmed what happened).
     if (asJson) {
         const outcome = { runId: beforeId, status: 'timeout' };
         console.log(JSON.stringify(outcome));
@@ -512,20 +248,8 @@ export async function pollRunProgress(id, before, opts = {}) {
     }
     process.exitCode = 1;
 }
-// #149 item 3 — same shared-enum shape as VALID_TIERS below (~line 603):
-// keeps `--status`'s allowed values and its error message in one place,
-// mirrored from lastStatus()'s own return type so the two can never drift.
 const VALID_LAST_STATUSES = ['success', 'failure', 'never', 'running', 'regression'];
-// #179 — mirrors `UNHEALTHY_STREAK_LENGTH` in trawl_node
-// modules/scraps/helpers/scrapCronHealth.js. `--unhealthy` is a boolean
-// convenience flag for that ONE product-defined threshold (also what the
-// server's own cron-skip gate and email use), not a general numeric filter —
-// the API's `minConsecutiveFailures` param accepts any threshold, but this
-// CLI only ever asks for the one value the rest of the product means by
-// "unhealthy". If trawl_node's threshold ever changes, update this constant
-// to match.
 const UNHEALTHY_STREAK_LENGTH = 3;
-// list — promoted to a top-level verb (#108, see the AttachOptions comment above)
 export function attachListCommand(parent, attachOpts = {}) {
     return parent
         .command('list', attachOpts)
@@ -533,33 +257,14 @@ export function attachListCommand(parent, attachOpts = {}) {
         .description('List all scraps')
         .option('--json', 'Output as JSON')
         .option('--status <status>', 'Filter by last run status (success|failure|never|running|regression)')
-        // #88 item 8 — no custom parser here (unlike the old `(v) => parseInt(v,
-        // 10)`): a bad value like "abc" used to silently become NaN, which then
-        // sailed straight through `Number.isInteger`-less checks and into
-        // `.slice(0, NaN)` (silently truncates to 0 rows) or `?page=NaN` (silently
-        // sent to the server) — never a usage error. Keeping the raw string here
-        // lets the validation below mirror `history`'s own --limit check exactly
-        // (~line 660) and report the actual bad input in the error message.
         .option('--limit <n>', 'Show only the first N results')
         .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
-        // #179 — backed by the server's `minConsecutiveFailures` filter
-        // (trawl_node#1952): restricts the result set server-side to scraps
-        // whose CURRENT consecutive-failure streak is >= UNHEALTHY_STREAK_LENGTH,
-        // and annotates each returned scrap with the exact `consecutiveFailedRuns`/
-        // `unhealthySince` the aggregation computed. Deliberately never derived
-        // client-side from `history[]` — that would drift from what the web
-        // dashboard shows (comes-io/trawl_vue#1299 reads the identical filter).
         .option('--unhealthy', `Only show scraps failing their last ${UNHEALTHY_STREAK_LENGTH}+ runs (server-computed)`)
         .action(async (opts, cmd) => {
-        // #149 item 3 — validate --status against its enum the same way
-        // --tier already validates (usageError + return, checked first, before
-        // any other guard/async work — mirrors `create`/`update`'s --tier
-        // check below).
         if (opts.status !== undefined && !VALID_LAST_STATUSES.includes(opts.status)) {
             usageError(`Invalid --status "${opts.status}" (allowed: ${VALID_LAST_STATUSES.join(', ')})`, { json: opts.json });
             return;
         }
-        // Guard: --limit and --page are mutually exclusive
         if (opts.limit !== undefined && opts.page !== undefined) {
             usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
             return;
@@ -580,18 +285,13 @@ export function attachListCommand(parent, attachOpts = {}) {
                 return;
             }
         }
-        // #179 — same param on every request this action can issue (both
-        // branches below), so a filtered result stays filtered across the
-        // fetch-all pagination loop, not just its first page.
         const healthFilter = opts.unhealthy ? `&minConsecutiveFailures=${UNHEALTHY_STREAK_LENGTH}` : '';
         let data;
         try {
             data = await spin(async () => {
                 if (page !== undefined) {
-                    // Single-page mode: explicit page requested, no loop
                     return api.get(`/api/scraps?perPage=50&page=${page}${healthFilter}`);
                 }
-                // Fetch-all mode: paginate until a page returns < 200 items
                 const perPage = 200;
                 let result = [];
                 let pageNum = 1;
@@ -606,16 +306,6 @@ export function attachListCommand(parent, attachOpts = {}) {
             }, 'Fetching scraps…');
         }
         catch (err) {
-            // Spinner already failed by oraPromise — report with the scrap-specific
-            // prefix kept, but route through the shared classifier so exit code +
-            // --json envelope stay consistent with every other command. (#71)
-            //
-            // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
-            // which the shared reportError() can't add) used to silently swallow
-            // --debug: unlike the central index.ts catch, it never printed the raw
-            // stack trace. optsWithGlobals() reads --debug off the ROOT command
-            // (this leaf has no --debug of its own) so it can honor the flag
-            // locally instead. (#86 finding 9)
             const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
             const { exitCode, envelope } = classifyError(err);
             const message = `Failed to fetch scraps: ${envelope.message}`;
@@ -630,9 +320,6 @@ export function attachListCommand(parent, attachOpts = {}) {
             process.exitCode = exitCode;
             return;
         }
-        // #179 — check the RAW response, before --status narrows it further,
-        // so a genuinely empty (all-healthy) result is never mistaken for an
-        // unconfirmed filter.
         warnIfUnconfirmedHealthFilter(data, opts.unhealthy);
         if (opts.status)
             data = data.filter((s) => lastStatus(s) === opts.status);
@@ -645,21 +332,17 @@ export function attachListCommand(parent, attachOpts = {}) {
             title: s.title || '(untitled)',
             cron: s.cron || '—',
             status: statusIcon(lastStatus(s)),
-            // #179 — next to the existing status badge, per the issue's own
-            // wording (see healthBadge() above for the two source signals).
             health: healthBadge(s),
             'last run': lastRun(s),
             updated: formatDate(s.updatedAt),
         }));
         table(tableRows, ['id', 'title', 'cron', 'status', 'health', 'last run', 'updated']);
-        // Print footer when --limit truncates
         if (limit !== undefined && rows.length < totalMatched) {
             console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
         }
     });
 }
 attachListCommand(scraps, { hidden: true });
-// get — promoted to a top-level verb (#108)
 export function attachGetCommand(parent, attachOpts = {}) {
     return parent
         .command('get <id>', attachOpts)
@@ -674,9 +357,6 @@ export function attachGetCommand(parent, attachOpts = {}) {
         console.log(chalk.dim(`  ID:       `) + data._id);
         console.log(chalk.dim(`  Cron:     `) + (data.cron || '—'));
         console.log(chalk.dim(`  Status:   `) + statusIcon(lastStatus(data)));
-        // #179 — same badge `list` renders (see healthBadge() above); `get`
-        // never sends `minConsecutiveFailures`, so this always reads the
-        // free `lastCronOutcome` breadcrumb, never the live per-run count.
         console.log(chalk.dim(`  Health:   `) + healthBadge(data));
         console.log(chalk.dim(`  Last run: `) + lastRun(data));
         console.log(chalk.dim(`  Updated:  `) + formatDate(data.updatedAt));
@@ -684,14 +364,6 @@ export function attachGetCommand(parent, attachOpts = {}) {
 }
 attachGetCommand(scraps, { hidden: true });
 const VALID_TIERS = ['tier0', 'tier1', 'tier2', 'tier3', 'tier4'];
-/**
- * #86 findings 4/5 — shared honest-tier renderer for `create --tier` and
- * `update --tier/--force-tier`. Reads the typed `_tierOverride` echoed back
- * by the server (#1559) so both commands show the SAME truth: a refusal, an
- * allowed ceiling raise (+ spend warning), or a silently clamped proxyTier.
- * Human-mode output only — a --json caller gets the same truth for free from
- * the full scrap object (which already includes `_tierOverride`).
- */
 function renderTierOverrideHuman(data) {
     const ov = data._tierOverride;
     if (!ov)
@@ -716,64 +388,25 @@ function renderTierOverrideHuman(data) {
         }
     }
 }
-/**
- * #86 finding 4b — old-server fallback. When a tier was requested but the
- * response carries no `_tierOverride` at all, the server is too old to
- * confirm what actually got applied. Echoing the REQUESTED value as if it
- * were the outcome is exactly the silent-clamp lie #1559 fixed — warn
- * instead, on stderr (safe under --json too; stdout purity is untouched).
- */
 function warnIfUnconfirmedTier(data, tierWasRequested, id) {
     if (data._tierOverride || !tierWasRequested)
         return;
     console.error(chalk.yellow(`  ⚠ Server did not confirm the tier change (older server) — verify with: trawl get ${id}`));
 }
-/**
- * #88 item 3 — the --json machine-readable counterpart to
- * warnIfUnconfirmedTier's stderr warning above. A --json caller (an agent
- * scripting this CLI) has no reliable reason to read stderr — that channel
- * is advisory-only everywhere else in this CLI, and stdout must stay the
- * sole payload. Without this, the ONLY signal that the server never
- * confirmed the tier change was a string on stderr, invisible to any --json
- * consumer parsing stdout alone. Adds `_tierUnconfirmed: true` to the
- * emitted object under EXACTLY the same condition warnIfUnconfirmedTier
- * warns on (tier requested, response carries no `_tierOverride`) — never
- * fabricated, never present otherwise.
- */
 function withTierUnconfirmed(data, tierWasRequested) {
     if (data._tierOverride || !tierWasRequested)
         return data;
     return { ...data, _tierUnconfirmed: true };
 }
-/** #86 finding 5 — the standard error envelope for a refused tier override,
- * routed through the same reportError() central formatting path used
- * everywhere else (exit 1: a business-logic refusal, not a usage error).
- *
- * #107 review F3 — uses `RefusalError` (kind:"refused"), not a bare `Error`
- * (which fell through classifyError's default `kind:"unknown"` bucket,
- * indistinguishable from a generic crash even though the README sells `kind`
- * as the machine discriminant an agent branches on).
- */
 function reportTierRefusal(data, wantsJson) {
     const ov = data._tierOverride;
     const message = `Tier ceiling override refused: ${ov?.reason ?? 'unknown'} (requested ${ov?.requestedMaxTier ?? '—'}; kept the registry cap)`;
     return reportError(new RefusalError(message), { json: wantsJson });
 }
-// create
 scraps
     .command('create')
     .description('Create a new scrap')
     .requiredOption('-t, --title <title>', 'Scrap title')
-    // #170 review F6 — promoted from a plain `.option()` to `.requiredOption()`:
-    // this is unconditionally required (no positional alternative exists on
-    // THIS command, unlike the top-level `trawl create <url>`, which accepts
-    // `[url]` OR `--url` — deliberately left untouched, that either/or needs a
-    // human product decision, tracked separately). Before this, the flag's
-    // description carried the only "Required." signal, in English prose — the
-    // exact thing docs/agent-quickstart.md tells an agent not to parse.
-    // Commander itself now enforces it, so `trawl spec --json`'s published
-    // `mandatory:true` is honest instead of a second, driftable copy of this
-    // same fact.
     .requiredOption('-u, --url <url>', 'Target URL — the site the scrap targets, not necessarily the exact URL fetched at run time (a request script can compute that, e.g. a templated search query).')
     .option('-r, --request <request>', 'Request/query')
     .option('-d, --description <text>', 'Scrap description')
@@ -784,10 +417,6 @@ scraps
         usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
-    // #163 — the API now requires a parseable `url` on create (trawl_node
-    // #1823/#1828); validate client-side BEFORE the request goes out so a
-    // missing/unparseable value surfaces as a readable usage error instead
-    // of a raw server 400/422.
     const url = tryValidateUrl(opts.url, opts);
     if (url === undefined)
         return;
@@ -798,9 +427,6 @@ scraps
         ...(opts.description !== undefined && { description: opts.description }),
         ...(opts.tier !== undefined && { proxyTier: opts.tier }),
     }), { text: 'Creating scrap…', successText: (d) => `Scrap created: ${chalk.bold(d._id)}` });
-    // #86 finding 4a — read _tierOverride back from the POST response and
-    // render it exactly like `update` does; never echo the requested tier as
-    // if it were applied when an older server doesn't confirm it.
     const tierWasRequested = opts.tier !== undefined;
     warnIfUnconfirmedTier(data, tierWasRequested, data._id);
     const refused = Boolean(data._tierOverride?.refused);
@@ -817,7 +443,6 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// update
 scraps
     .command('update <id>')
     .description('Update an existing scrap')
@@ -849,9 +474,6 @@ scraps
     const body = {};
     if (opts.title !== undefined)
         body.title = opts.title;
-    // #163 — omitting --url stays a no-op (the API keeps that allowed on
-    // update), but a value that IS supplied must still be a parseable URL —
-    // validate it client-side before the request goes out, same as create.
     if (opts.url !== undefined) {
         const url = tryValidateUrl(opts.url, opts);
         if (url === undefined)
@@ -900,7 +522,6 @@ scraps
     if (opts.tier !== undefined)
         body.proxyTier = opts.tier;
     if (opts.forceTier !== undefined) {
-        // Raise the ceiling; also start the run at that tier unless --tier says otherwise.
         body.proxyMaxTier = opts.forceTier;
         if (opts.tier === undefined)
             body.proxyTier = opts.forceTier;
@@ -917,10 +538,6 @@ scraps
         text: 'Updating scrap…',
         successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
     });
-    // #1559 / #86 findings 4b/5 — surface the effective tier + clamp/refuse
-    // reason (fixes the silent-clamp: the server may persist a lower tier
-    // than requested), and NEVER echo the requested value as applied when
-    // the server doesn't confirm it (old-server fallback below).
     const tierWasRequested = opts.tier !== undefined || opts.forceTier !== undefined;
     warnIfUnconfirmedTier(data, tierWasRequested, id);
     const refused = Boolean(data._tierOverride?.refused);
@@ -934,10 +551,6 @@ scraps
     }
     const shown = data;
     for (const key of Object.keys(body)) {
-        // Tier keys are rendered exclusively by renderTierOverrideHuman /
-        // warnIfUnconfirmedTier above — never echo them here, whether or not
-        // _tierOverride came back (an old-server echo of the REQUESTED value
-        // is exactly the silent-clamp lie #1559 fixed).
         if (key === 'proxyTier' || key === 'proxyMaxTier')
             continue;
         const src = key in shown ? shown[key] : body[key];
@@ -947,7 +560,6 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// run — promoted to a top-level verb (#108)
 export function attachRunCommand(parent, attachOpts = {}) {
     return parent
         .command('run <id>', attachOpts)
@@ -956,66 +568,25 @@ export function attachRunCommand(parent, attachOpts = {}) {
         .option('--json', 'Output the raw launch payload as JSON')
         .action(async (id, opts) => {
         validateObjectId(id);
-        // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
-        // tell "the run that's about to finish" apart from whatever the last run
-        // happened to be (including a dedup onto an already-in-flight run).
         const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-        // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
-        // server-side (30-250s); the 30s default was aborting it mid-flight.
         const call = () => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS });
-        // #107 — under --json the stdout path stays pure: no spinner channel at
-        // all, mirroring `trawl create`'s own --json handling.
         const data = opts.json
             ? await call()
             : await spin(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
         if (opts.json)
             json(data);
         else if (!opts.watch) {
-            /* #166 — see confirmNonTTY. Two deliberate choices here:
-             *
-             * "run complete", not "launched": `run` is the SYNCHRONOUS verb —
-             * GET /api/scraps/load/:id executes the scrap server-side (30-250s)
-             * and returns the finished result, so by the time this prints the run
-             * is over. The spinner's successText says "Scrap launched", but that
-             * is stderr chrome for a human watching it happen; THIS line is the
-             * machine surface, where a script reading "launched" would poll for a
-             * completion that already happened. `trigger` already draws the same
-             * distinction ("Worker triggered" async vs "Worker run complete" under
-             * --wait) — this matches that vocabulary.
-             *
-             * `--watch` is excluded because pollRunProgress below does its own
-             * reporting; without that guard a watched run would print this line
-             * and then narrate the same run. */
             confirmNonTTY(`Scrap ${id} run complete`);
         }
         if (opts.watch) {
-            // #107 — under --json, pollRunProgress suppresses its own intermediate
-            // console.log calls and instead emits exactly ONE final NDJSON outcome
-            // line (+ sets process.exitCode honestly) once the watch reaches a
-            // terminal status, a timeout, or a persistent poll error (review F1) —
-            // `run --json --watch` never again exits 0 after dead air regardless
-            // of what the watched run actually did.
             await pollRunProgress(id, beforeRun, { json: opts.json });
         }
-        // #151 — throttled post-run referral tip. Reached only when the
-        // launch call above didn't throw (a hard failure rejects it, unwinding
-        // straight to index.ts's central catch before this line ever runs)
-        // — and, when --watch polled to a terminal state, only when
-        // pollRunProgress didn't flag a genuine run failure/timeout/poll-error
-        // via a non-zero process.exitCode (#107 review F1). See lib/tips.ts
-        // for the throttle/TTY/json/opt-out/server-flag gating itself. #153 —
-        // now async (a due tip fetches the server's userFacing flag before
-        // printing), so this must be awaited: otherwise commander's
-        // parseAsync-driven action would resolve before the tip's own
-        // await settles, racing the process's natural exit.
         const runFailed = typeof process.exitCode === 'number' && process.exitCode !== 0;
         if (!runFailed)
             await maybeShowReferralTip({ json: opts.json });
     });
 }
 attachRunCommand(scraps, { hidden: true });
-// #70 — render an items array either as a table summary or --json. Shared by
-// both the default (persisted read) and --fresh (live execute) paths of `data`.
 function renderScrapItems(items, asJson) {
     if (asJson) {
         json(items);
@@ -1028,43 +599,15 @@ function renderScrapItems(items, asJson) {
     }
     console.log(chalk.dim('  Use --json for full output.'));
 }
-/**
- * #86 finding 6 — `data`'s honest empty-vs-error distinction, for both --json
- * and human prose. Before this, EVERY non-array outcome (never run, last run
- * failed, or the payload aged out of retention) collapsed to the SAME `[]` /
- * "No data yet." — indistinguishable from a genuine zero-item successful run.
- * That's a lie under --json: an agent can't tell "nothing to show" from "go
- * look at what actually happened". Mirrors reportError's dual json/human
- * shape (human line to stderr always; --json ALSO gets a machine envelope on
- * stdout) with a caller-chosen exit code + kind, since these states are not
- * all "usage" (2) — never-run / aged-out-of-retention are not_found (4), a
- * failed last run is a business-logic failure (1).
- */
-/**
- * #170 — `retryable`/`next` follow the SAME frozen `RETRY_POLICY` map
- * `classifyError` reads (errors.ts), keyed by `kind` — this path never
- * builds its own copy. `retryOverride` is for the one case here where the
- * kind alone is genuinely wrong: `in_progress`'s caller passes
- * `{retryable:true, next:['trawl data <id>']}` since retrying `data` (not
- * `--fresh`, which would 429 against the lock already held) IS worth doing
- * once the run finishes. Every other kind here (`not_found`, `run_failed`)
- * isn't in `RETRY_POLICY` at all — `retryFieldsFor` is total, so those fall
- * back to its conservative "not retryable, nothing to suggest" default.
- */
 function reportDataState(message, exitCode, kind, wantsJson, retryOverride) {
     console.error(chalk.red(`✗ ${message}`));
     if (wantsJson) {
         const { retryable, next } = retryOverride ?? retryFieldsFor(kind);
-        // #170 review F3 — typed as ErrorEnvelope so the compiler enforces
-        // `retryable` here too (this was one of two emitters a mutation test
-        // proved `tsc --noEmit` never actually guarded before this annotation —
-        // the untyped literal let `retryable` be omitted silently).
         const envelope = { message, kind, retryable, ...(next ? { next } : {}) };
         console.log(JSON.stringify({ error: envelope }));
     }
     process.exitCode = exitCode;
 }
-// data — promoted to a top-level verb (#108)
 export function attachDataCommand(parent, attachOpts = {}) {
     return parent
         .command('data <id>', attachOpts)
@@ -1074,15 +617,9 @@ export function attachDataCommand(parent, attachOpts = {}) {
         .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `run`)')
         .action(async (id, opts) => {
         validateObjectId(id);
-        // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
-        // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
         if (opts.errors) {
             const result = await fetchRunAndFix(id);
             if (!result) {
-                // #88 item 7 — unified no-runs shape with `doctor --json`: a bare
-                // `null` was indistinguishable from any other absent-payload state
-                // (a scrap CAN legitimately have a null-ish result elsewhere); an
-                // explicit `{status:"no_runs"}` object is unambiguous everywhere.
                 if (opts.json) {
                     json({ status: 'no_runs' });
                     return;
@@ -1090,13 +627,6 @@ export function attachDataCommand(parent, attachOpts = {}) {
                 console.log(chalk.dim('No runs yet.'));
                 return;
             }
-            // --json is honored for BOTH outcomes (success or failure) — an agent
-            // parsing `data --errors --json` must always get the flat run object,
-            // never prose gated behind a status check. (#71 finding 13)
-            // #185 — `docs` rides alongside as a sibling field on the same flat
-            // object (never nested under `run`, since there's no wrapper shape
-            // here), present only for a live mapped failureKind (see
-            // runDocsField's doc comment).
             if (opts.json)
                 return json({ ...pickRun(result.run), ...runDocsField(result.run) });
             if (result.run.status === true) {
@@ -1104,25 +634,18 @@ export function attachDataCommand(parent, attachOpts = {}) {
                 return;
             }
             console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
+            if (isAuthWall(result.run)) {
+                maybeSuggestSkillsForAuthWall();
+            }
             return;
         }
-        // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
-        // default path used to do silently: GET /api/scraps/load/:id executes a
-        // fresh scrap run server-side (requireQuota('scraps','execute') + a
-        // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
-        // burning execute quota and 429ing if a run is already in flight. A user
-        // or agent "just reading data" must never trigger that by accident.
         if (opts.fresh) {
-            // #91 P0 — same long-run endpoint as `run` (30-250s server-side);
-            // the 30s default was aborting it mid-flight.
             const loaded = await spin(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
                 text: 'Launching a fresh scrap run (consumes execute quota)…',
                 successText: 'Fresh run complete',
             });
             const items = loaded?.result?.data;
             if (!Array.isArray(items)) {
-                // --json always returns an array from `data` — [] is the honest
-                // "no items" signal instead of prose breaking JSON parsing. (#71)
                 if (opts.json) {
                     json([]);
                     return;
@@ -1130,18 +653,6 @@ export function attachDataCommand(parent, attachOpts = {}) {
                 console.log(chalk.dim('No data yet. Run the scrap first.'));
                 return;
             }
-            // #93 item 2 — --fresh used to render items without ever checking for a
-            // regression, unlike the persisted `data` path below (#88 item 2). The
-            // load() response's OWN embedded `scrap.history[0]` can't be trusted for
-            // this (see the ScrapLoadResult comment above): it may be the previous
-            // run's row, and even the right row never carries the regression flip.
-            // `--fresh` runs synchronously to completion server-side though — by the
-            // time this call returns, node has already awaited the regression patch
-            // — so a fresh GET /api/scraps/:id (the SAME read the persisted path
-            // below already trusts) reliably observes the finalized DB state.
-            // Best-effort: never fail --fresh's real output over this side check,
-            // and never gate on it — the items returned ARE this run's real,
-            // synchronously-computed data regardless of what this check finds.
             try {
                 const fresh = await api.get(`/api/scraps/${id}`);
                 if (fresh.history?.[0]?.statusDetail === 'regression') {
@@ -1149,56 +660,20 @@ export function attachDataCommand(parent, attachOpts = {}) {
                 }
             }
             catch {
-                // best-effort — the fresh run's items are still valid without this check
             }
             renderScrapItems(items, opts.json);
             return;
         }
-        // Default: read the last PERSISTED run payload — no quota, no run lock.
-        // History.data (trawl_node modules/historys/services/historys.service.js
-        // `update()`) is a JSON-stringified clone of the worker result, so it
-        // carries the same `.data` items array the live load endpoint returns —
-        // it's just pulled from the most recent history row instead of a fresh
-        // run. Retention keeps this only for the newest row per (scrap, status)
-        // bucket (config.trawl.keepData, default 1); older rows null it out.
-        //
-        // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
-        // Every other outcome below is an honest error envelope instead: never
-        // run (not_found/4), last run failed (1), or the payload aged out of
-        // retention (not_found/4) all used to collapse into the same silent [].
         const scrap = await api.get(`/api/scraps/${id}`);
         const last = scrap.history?.[0];
         if (!last?._id) {
             reportDataState(`Scrap ${id} has never run. Run it first (trawl run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
             return;
         }
-        // #88 item 1 — status:null is an IN-FLIGHT run (node persists
-        // {status:null, statusDetail:null, inFlight:true} the moment a run
-        // starts, and only flips status/statusDetail once it finishes). That is
-        // neither "never run" nor "the last run failed" — a caller reading data
-        // mid-run needs an honest "wait" signal. Never suggest --fresh here: a
-        // run already holds the server-side distributed lock, so --fresh would
-        // just 429 against it.
         if (last.status === null) {
-            // #170 — retrying `trawl data <id>` (unchanged) once the run
-            // finishes IS worth it; `--fresh` never is (it would 429 against the
-            // lock this very run already holds) — never suggested here.
             reportDataState(`Run in progress for ${id} — retry shortly.`, 1, 'in_progress', opts.json, { retryable: true, next: [`trawl data ${id}`] });
             return;
         }
-        // #86 review — node persists status=false for a GENUINE zero-item run
-        // too (historys schema: status boolean|null + statusDetail
-        // success/error/empty/regression; a zero-item run is status=false +
-        // statusDetail='empty', and the embedded history rows from GET
-        // /api/scraps/:id include statusDetail via the repository populate
-        // select). An 'empty' run is the one case [] is FOR — only a real
-        // failure (error/unknown detail) gets the run_failed envelope.
-        //
-        // #88 item 2 — statusDetail='regression' is ALSO status=false (an async
-        // patch flips it after item count dropped vs baseline), but the row's
-        // `data` still holds REAL, non-empty items — the write that persisted
-        // them succeeded before the regression was even detected. Treating it as
-        // run_failed would hide genuine data behind a false negative.
         const isEmptyRun = last.status === false && last.statusDetail === 'empty';
         const isRegression = last.status === false && last.statusDetail === 'regression';
         if (last.status === false && !isEmptyRun && !isRegression) {
@@ -1209,11 +684,6 @@ export function attachDataCommand(parent, attachOpts = {}) {
         let items;
         if (typeof detail?.data === 'string' && detail.data) {
             try {
-                // #159 — `detail.data` is the same JSON-string-within-JSON shape
-                // (`history.data`) the create --json bug lived in: a raw control
-                // character here would otherwise throw and silently report "aged
-                // out of retention" below for data that is actually present and
-                // recoverable, burning a --fresh re-run + quota for nothing.
                 items = parseServerJson(detail.data)?.data;
             }
             catch {
@@ -1222,23 +692,12 @@ export function attachDataCommand(parent, attachOpts = {}) {
         }
         if (!Array.isArray(items)) {
             if (isEmptyRun) {
-                // A genuine zero-item run whose payload is '[]' or absent — both are
-                // the SAME honest answer: no items, exit 0. Never the retention
-                // message (nothing aged out; there was nothing to persist).
                 renderScrapItems([], opts.json);
                 return;
             }
-            // #88 item 2 — a regression row whose payload aged out of retention has
-            // nothing left to show either; fall through to the SAME honest
-            // aged-out envelope a normal successful row would get (never fabricate
-            // items, never silently succeed).
             reportDataState(`No persisted data for the last run of ${id} — it aged out of retention. Pass --fresh to launch a new run.`, 4, 'not_found', opts.json);
             return;
         }
-        // #88 item 2 — a regression row's items are REAL (the write succeeded
-        // before the async patch flagged the drop) — return them on stdout
-        // (exit 0, both modes) with an honest stderr warning pointing at the
-        // diagnostic command, instead of hiding genuine data behind run_failed.
         if (isRegression) {
             console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
         }
@@ -1246,7 +705,6 @@ export function attachDataCommand(parent, attachOpts = {}) {
     });
 }
 attachDataCommand(scraps, { hidden: true });
-// history — list past runs for a scrap — promoted to a top-level verb (#108)
 export function attachHistoryCommand(parent, attachOpts = {}) {
     return parent
         .command('history <id>', attachOpts)
@@ -1267,8 +725,6 @@ export function attachHistoryCommand(parent, attachOpts = {}) {
             time: h.time ?? null,
             tier: h.proxyTier ?? null,
             failureKind: h.failureKind ?? null,
-            // trawl_node#1950 renamed blockType to block.kind; fall back to the
-            // deprecated flat field for a prod backend not yet on that tag.
             blockType: h.block?.kind ?? h.blockType ?? null,
             createdAt: h.createdAt ?? null,
         }));
@@ -1280,7 +736,6 @@ export function attachHistoryCommand(parent, attachOpts = {}) {
     });
 }
 attachHistoryCommand(scraps, { hidden: true });
-// run-info — single-run detail by history id — promoted to a top-level verb (#108)
 export function attachRunInfoCommand(parent, attachOpts = {}) {
     return parent
         .command('run-info <hid>', attachOpts)
@@ -1295,36 +750,24 @@ export function attachRunInfoCommand(parent, attachOpts = {}) {
             time: h.time ?? null,
             tier: h.proxyTier ?? null,
             failureKind: h.failureKind ?? null,
-            // trawl_node#1950 renamed blockType to block.kind; fall back to the
-            // deprecated flat field for a prod backend not yet on that tag.
             blockType: h.block?.kind ?? h.blockType ?? null,
             errorMessage: h.errorSnapshot?.errorMessage ?? null,
             selector: h.errorSnapshot?.selector ?? null,
             emptyContext: h.emptyContext ?? null,
             createdAt: h.createdAt ?? null,
-            // #185 — present only for a live mapped failureKind (see
-            // runDocsField's doc comment); omitted, never `docs: undefined`, for
-            // every other run so this object's own JSON.stringify never grows an
-            // unexpected key on existing consumers.
             ...runDocsField(h),
         };
         if (opts.json) {
             json(info);
             return;
         }
-        // The blob is an object; the table needs one line. --json keeps it whole.
         table([{ ...info, emptyContext: summarizeEmptyContext(info.emptyContext) }], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
-        // #184 safety-net — the run just shown carries a live login-wall
-        // verdict; if Claude's skills aren't installed either, point at the
-        // command that installs them too (never under --json, see the early
-        // return above).
         if (isAuthWall(h)) {
             maybeSuggestSkillsForAuthWall();
         }
     });
 }
 attachRunInfoCommand(scraps, { hidden: true });
-// delete
 scraps
     .command('delete <id>')
     .alias('rm')
@@ -1333,16 +776,6 @@ scraps
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    // #107 — never blocks on a y/N under --json or a non-TTY invocation
-    // (agent/CI subprocess); -f/--force always pre-confirms.
-    //
-    // #107 review F2 — `message` (the plain-id form) feeds the refusal
-    // UsageError, which can land verbatim in the `--json` error envelope;
-    // `chalk.bold(id)` is passed ONLY as `promptMessage`, shown solely on
-    // the interactive TTY `[y/N]` prompt. Before this split, the styled
-    // string was the ONLY message confirmDestructive had, so a non-TTY/
-    // --json refusal on `scraps delete X --json` emitted raw ANSI escape
-    // bytes inside the JSON string.
     const { proceed, blocked } = await confirmDestructive(`Delete scrap ${id}?`, {
         force: opts.force,
         json: opts.json,
@@ -1361,9 +794,8 @@ scraps
         return;
     }
     await spin(call, { text: 'Deleting…', successText: 'Scrap deleted' });
-    confirmNonTTY(`Scrap ${id} deleted`); // #166
+    confirmNonTTY(`Scrap ${id} deleted`);
 });
-// banner
 scraps
     .command('banner <id>')
     .description('Upload a banner image for a scrap')
@@ -1385,9 +817,6 @@ scraps
         jpeg: 'image/jpeg',
         webp: 'image/webp',
     };
-    // #91 P2 — an unsupported/unknown extension silently became image/png
-    // (uploading the raw bytes of, say, a .gif or .pdf under an image/png
-    // Content-Type — a lie about the actual file's format). Refuse instead.
     const mimeType = mimeMap[ext];
     if (!mimeType) {
         usageError(`Unsupported image type "${ext ? `.${ext}` : filename}" — use png, jpg, or webp.`, { json: opts.json });
@@ -1407,10 +836,8 @@ scraps
         text: 'Uploading banner…',
         successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
     });
-    // #166 — plain, unstyled: chalk.bold would emit escape codes into a pipe.
     confirmNonTTY(`Banner uploaded for scrap ${id}`);
 });
-// watch (stream activities)
 scraps
     .command('watch <id>')
     .description('Stream scrap activities in real-time')
@@ -1419,7 +846,6 @@ scraps
     validateObjectId(id);
     await watchActivities(id, opts.json);
 });
-// trigger — promoted to a top-level verb (#108)
 export function attachTriggerCommand(parent, attachOpts = {}) {
     return parent
         .command('trigger <id>', attachOpts)
@@ -1429,23 +855,9 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
         .option('--json', 'Output the raw trigger payload as JSON')
         .action(async (id, opts) => {
         validateObjectId(id);
-        // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
-        // tell "the run we just triggered" apart from whatever the last run
-        // happened to be. This is the dedup-prone path: `trigger`'s method:'worker'
-        // collapses onto an already-pending/running worker job for the same scrap
-        // (ScrapJobsService, LIVE_STATUSES) instead of creating a new history row —
-        // captureBeforeRunState records that so pollRunProgress can still track it.
         const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-        // #50 — default async: the backend (#1313) kicks off the run and returns a
-        // 'queued' envelope immediately instead of holding the connection for the
-        // whole run. --wait restores the old synchronous round-trip.
         const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
-        // #91 P0 — the synchronous --wait branch runs the scrap server-side
-        // (30-250s), same as `run`; the 30s default was aborting it
-        // mid-flight. The async (default) POST returns almost immediately, so it
-        // keeps the 30s default.
         const call = () => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path));
-        // #107 — under --json the stdout path stays pure: no spinner channel.
         const data = opts.json
             ? await call()
             : await spin(call, {
@@ -1456,26 +868,16 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
             json(data);
         }
         else {
-            /* #160, folded onto the shared helper by #166 — the rationale and the
-             * known residual now live once, on `confirmNonTTY` itself, instead of
-             * in the one call site that happened to be fixed first. Wording is
-             * unchanged on purpose: the trawl-internal QA runbook asserts on the
-             * exact "Worker triggered" / "Worker run complete" substrings. */
             confirmNonTTY(opts.wait ? `Worker run complete for scrap ${id}` : `Worker triggered for scrap ${id}`);
         }
-        // #107 — see the matching comment on `run`'s --watch call above (review
-        // F1): honest final NDJSON line + exit code under --json, human mode
-        // gets the same honest exit code too.
         if (opts.watch)
             await pollRunProgress(id, beforeRun, { json: opts.json });
     });
 }
 attachTriggerCommand(scraps, { hidden: true });
-// account subcommand group
 const account = scraps
     .command('account')
     .description('Manage scrap account credentials and session');
-// helper: prompt for a value with readline (visible input)
 async function promptLine(prompt) {
     const { createInterface } = await import('readline');
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -1488,7 +890,6 @@ async function promptLine(prompt) {
         rl.close();
     }
 }
-// account set
 account
     .command('set <id>')
     .description('Set credentials for a scrap account')
@@ -1500,13 +901,8 @@ account
     let username = opts.username || '';
     let password = opts.password || '';
     if (opts.password) {
-        // #107 — this advisory is stderr-only: stdout must stay pure under
-        // --json, and every other advisory in this CLI already follows that
-        // rule (warnIfUnconfirmedTier, token.ts's expiry hints, …).
         console.error(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
     }
-    // #107 — never blocks on a readline prompt under --json or a non-TTY
-    // invocation (agent/CI subprocess); pass -u/-p instead.
     const interactive = isInteractive({ json: opts.json });
     if (!username) {
         if (!interactive) {
@@ -1541,7 +937,6 @@ account
     console.log(chalk.dim('  Credentials: ') + (acc.hasCredentials ? chalk.green('✓ configured') : chalk.dim('not set')));
     console.log(chalk.dim('  Session:     ') + (acc.hasSession ? chalk.green('active') : chalk.dim('none')));
 });
-// account delete
 account
     .command('delete <id>')
     .description('Delete account credentials for a scrap')
@@ -1549,10 +944,6 @@ account
     .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    // #107 — never blocks on a y/N under --json or a non-TTY invocation.
-    // #107 review F2 — plain-id `message` for the refusal/JSON envelope,
-    // styled `promptMessage` for the interactive TTY prompt only (see the
-    // matching comment on `scraps delete` above).
     const { proceed, blocked } = await confirmDestructive(`Delete account credentials for scrap ${id}?`, { force: opts.force, json: opts.json, promptMessage: `Delete account credentials for scrap ${chalk.bold(id)}?` });
     if (blocked)
         return;
@@ -1570,9 +961,8 @@ account
         text: 'Deleting credentials…',
         successText: 'Account credentials deleted',
     });
-    confirmNonTTY(`Account credentials deleted for scrap ${id}`); // #166
+    confirmNonTTY(`Account credentials deleted for scrap ${id}`);
 });
-// account clear-session
 account
     .command('clear-session <id>')
     .description('Clear the saved session for a scrap account')
@@ -1589,38 +979,64 @@ account
         text: 'Clearing session…',
         successText: 'Session cleared',
     });
-    confirmNonTTY(`Session cleared for scrap ${id}`); // #166
+    confirmNonTTY(`Session cleared for scrap ${id}`);
 });
-// account session subcommand group
 const accountSession = account
     .command('session')
     .description('Manage scrap account session cookies (flavour B BYO-cookies)');
-// account session set
+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')));
+}
 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);
+    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)) {
+            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 +1045,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,7 +1061,97 @@ accountSession
     const acc = data.account;
     console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
 });
-// account status
+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 });
+}
+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);
+    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;
+    }
+    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) {
+        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;
+            }
+        }
+    }
+    const nonInteractiveReason = checkInteractiveEnvironment();
+    if (nonInteractiveReason) {
+        reportCaptureFailure({ ok: false, reason: 'non_interactive', message: nonInteractiveReason }, opts);
+        return;
+    }
+    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();
+        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) {
+        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
     .command('status <id>')
     .description('Show account credentials and session status for a scrap')
@@ -1652,8 +1161,6 @@ account
     const data = await spin(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
-        // #86 finding 12 — `json` is already statically imported at the top of
-        // this file; the dynamic import here was pure dead weight.
         return json(acc ?? null);
     }
     if (!acc) {
@@ -1682,7 +1189,6 @@ account
     }
     console.log(`${credLine} | ${sessionLine}`);
 });
-// doctor — diagnose last run of a scrap (error, failed selector, block status, page state, autofix)
 scraps
     .command('doctor <id>')
     .description('Diagnose the last run (error, failed selector, block status, page state, autofix outcome)')
@@ -1699,24 +1205,16 @@ scraps
         console.log(chalk.dim('No runs yet.'));
         return;
     }
-    // #185 — `docs` sits alongside `run`/`fix` (present only for a live
-    // mapped failureKind — see runDocsField's doc comment), never nested
-    // inside the allowlisted `run` object.
     if (opts.json)
         return json({ run: pickRun(result.run), fix: pickFix(result.fix), ...runDocsField(result.run) });
     console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
     if (opts.autofix && result.fix) {
         console.log('\n' + formatAutofix(result.fix));
     }
-    // #184 safety-net — formatDoctor already prints the login-wall hint
-    // (#182) above when this is a live auth wall; if Claude's skills aren't
-    // installed either, point at the command that installs them too (never
-    // under --json, see the early return above).
     if (isAuthWall(result.run)) {
         maybeSuggestSkillsForAuthWall();
     }
 });
-// autofix — show full auto-fix attempt detail (diff, dry-run, knowledge)
 scraps
     .command('autofix <id>')
     .description('Show the last auto-fix attempt for a scrap (decision, diff, dry-run, knowledge)')
@@ -1725,9 +1223,6 @@ scraps
     validateObjectId(id);
     const result = await fetchRunAndFix(id);
     if (!result) {
-        // #88 item 7 — unified no-runs shape with `doctor --json` / `data
-        // --errors --json`: a never-run scrap is a distinct, nameable state,
-        // not the same bare `null` a run-with-no-fix-attempt returns below.
         if (opts.json) {
             json({ status: 'no_runs' });
             return;
@@ -1736,8 +1231,6 @@ scraps
         return;
     }
     if (!result.fix) {
-        // A run DID happen, it just had no autofix attempt — genuinely "no
-        // data", unlike the never-run case above.
         if (opts.json) {
             json(null);
             return;
@@ -1749,7 +1242,6 @@ scraps
         return json(result.fix);
     console.log(formatAutofix(result.fix));
 });
-// snapshot — download the captured page HTML (or error-path HTML) for the last run
 scraps
     .command('snapshot <id>')
     .description('Download captured page HTML for the last run of a scrap')
@@ -1761,16 +1253,10 @@ scraps
     const scrap = await api.get(`/api/scraps/${id}`);
     const hid = scrap.history?.[0]?._id;
     if (!hid) {
-        // #91 P2 — same no-runs contract as `doctor`/`autofix`/`data --errors`
-        // (`{status:"no_runs"}`, exit 0) under --json.
         if (opts.json) {
             json({ status: 'no_runs' });
             return;
         }
-        // `-o` explicitly asked for a file to be written. Silently exiting 0
-        // with nothing written (and only a dim console line) is indistinguishable
-        // from success to a script checking the exit code alone — give it the
-        // SAME not_found envelope `scraps data`'s own never-run case uses.
         if (opts.out) {
             reportDataState(`Scrap ${id} has never run — nothing to write to ${opts.out}.`, 4, 'not_found', false);
             return;