@trawlme/cli 3.12.0 → 3.12.2

package/dist/commands/doctor.js

@@ -1,27 +1,6 @@
 import { api } from '../lib/api.js';
 import chalk from 'chalk';
 import { formatDate } from '../lib/format.js';
-/**
- * Known anti-bot vendors that the worker's `block.kind` field may name
- * (ex-flat `blockType`, trawl_node#1950). Ordered by first-match;
- * `block.kind` is a freeform worker string, not an enum (see the `Run.block`
- * doc comment), so this is a best-effort substring match against the real
- * field — never an invented/mocked value.
- *
- * `datadome`/`perimeterx`/`akamai`/`cloudflare` are literal substrings the
- * current worker emits (detect.js). `kasada` is forward-compatible: the issue
- * (#62 / wall-registry WS-7) names it as a genuine wall, but the current
- * worker vocabulary does not yet emit it — this branch lights up
- * automatically if/when a future worker classifier does, without a CLI
- * change.
- *
- * trawl_cli#182 — an `auth` entry used to live here, rendering a login wall
- * as "walled: auth — no reliable bypass". Removed: unlike a real anti-bot
- * vendor, a login wall's own reliable bypass is the user's session cookies,
- * so that verdict was wrong, not just early. `failureKind==='auth'`
- * (trawl_node#1975) is the honest signal for a login wall — see the
- * dedicated branch in `formatDoctor` below.
- */
 const WALL_VENDOR_PATTERNS = [
     [/datadome/i, 'DataDome'],
     [/kasada/i, 'Kasada'],
@@ -29,66 +8,18 @@ const WALL_VENDOR_PATTERNS = [
     [/akamai/i, 'Akamai'],
     [/cloudflare/i, 'Cloudflare'],
 ];
-/**
- * Resolve a known anti-bot vendor name from a worker `block.kind`
- * string. Returns null when the run succeeded, when there is no `block.kind`
- * signal at all, or when `block.kind` names something other than a known
- * vendor (e.g. `proxy-domain-gate`, `rate_limited_per_host`) — those stay on
- * the genuine-error path since we can't honestly attribute them to a specific
- * "no reliable bypass" wall.
- *
- * `blocked` is deliberately NOT consulted here (#177): it is a mid-run,
- * attempt-level signal the worker only stamps on one envelope shape, so it
- * reads `false` on the great majority of genuinely walled runs (the early-block
- * throw path sets `block.kind` but never `blocked` — 63 of 64 walled runs
- * measured on prod). `status === true` wins instead: a run that ultimately
- * returned data was not walled, even if an earlier tier's `block.kind` stamp
- * survived on the row.
- *
- * trawl_node#1950 renamed the flat `blockType` field to nested `block.kind`.
- * Read `block?.kind` first, falling back to the deprecated flat `blockType` —
- * this CLI can be published (and talk to prod) before the trawl_node prod tag
- * containing #1950 is cut (see the `Run.blockType` doc comment), so a prod
- * response can still be the pre-#1950 flat shape for a while.
- */
 export function detectWallVendor(run) {
-    // A run that returned data was not walled. `status === true` is not the whole
-    // predicate: trawl_node flips a degraded-but-non-empty run to
-    // `status:false, statusDetail:'regression'` (scraps.service.js, #1112) via a
-    // patch that never clears `block.kind` — so keying on `status` alone would
-    // print "no reliable bypass" next to "Regression: length N vs baseline M",
-    // which is the same contradiction this guard exists to remove.
     if (run.status === true || run.statusDetail === 'regression')
         return null;
     const kind = run.block?.kind ?? run.blockType ?? null;
     if (!kind)
-        return null; // no signal at all
+        return null;
     for (const [pattern, label] of WALL_VENDOR_PATTERNS) {
         if (pattern.test(kind))
             return label;
     }
     return null;
 }
-/**
- * #184 — true for a run currently carrying a live (non-stale) login-wall
- * verdict. Extracted out of `formatDoctor`'s own local `authWall` const so
- * `commands/scraps.ts`'s `doctor`/`run-info` actions can reuse the EXACT
- * same guard to decide whether to fire the skills-install safety-net nudge
- * (lib/skillsNudge.ts `maybeSuggestSkillsForAuthWall`) — one rule, not two
- * copies that could quietly drift apart.
- *
- * Same staleness guard as `detectWallVendor` above and for the same reason:
- * `failureKind` is a terminal classification trawl_node stamps once, but
- * `patchForRegression` can flip `status`/`statusDetail` to success/
- * regression LATER without ever clearing it — so a run that ultimately
- * succeeded or degraded must never still read as an active auth wall.
- *
- * Typed structurally loose (not `Pick<Run, ...>`) on purpose: `Run.status`/
- * `statusDetail` are required fields, but `scraps.ts`'s own `HistoryRun`
- * (the run-info command's shape) declares the same three fields OPTIONAL —
- * a `Pick<Run, ...>` parameter type would reject that caller at compile
- * time even though every field it actually reads is present at runtime.
- */
 export function isAuthWall(run) {
     return run.failureKind === 'auth' && run.status !== true && run.statusDetail !== 'regression';
 }
@@ -120,28 +51,8 @@ export function pickFix(fix) {
         .filter((k) => k in fix)
         .map((k) => [k, fix[k]]));
 }
-/**
- * Pure formatter — returns a human-readable diagnosis string for a run.
- * Used by `doctor`, `doctor --autofix`, and `data --errors`.
- *
- * @param scrapTitle - Display name of the scrap
- * @param run        - Owner-safe history run object
- * @param fix        - Optional autofix activity (null = no fix attempted)
- * @param scrapId    - Scrap document id (used in hint lines — autofix/snapshot take scrap id, not run id)
- * @returns Multi-line string ready for console.log
- */
 export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     const lines = [];
-    // Header + status badge. status:null means a run is IN FLIGHT (node
-    // persists {status:null, statusDetail:null, inFlight:true} the moment a
-    // run starts) — that must never render as "failed". (#88 item 1)
-    //
-    // #91 LOW — a regression row (status:false, statusDetail:'regression') was
-    // falling into the same red "failed" bucket as a genuine failure, then
-    // showing a contradictory "Regression: X vs Y" detail line right below it.
-    // A regression run's write actually SUCCEEDED (the item count just dropped
-    // vs baseline, detected by an async patch afterward — see #88 item 2 in
-    // scraps.ts) — it needs its own distinct badge, not "failed".
     const ok = run.status === true;
     const badge = ok
         ? chalk.green('● success')
@@ -154,69 +65,8 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
                     : chalk.red('● failed');
     lines.push(`${chalk.bold(scrapTitle)}  ${badge}${run.statusDetail ? ` (${run.statusDetail})` : ''}`);
     lines.push(chalk.dim(`  Run ID:  ${run._id}`));
-    // Error message — an honest accept-wall string for known-walled scraps
-    // (DataDome/Kasada/PerimeterX/Akamai terminal verdict from the worker),
-    // otherwise the real error (genuine transient failure).
-    //
-    // trawl_cli#182 — the wall-vendor verdict (this CLI's own
-    // WALL_VENDOR_PATTERNS matched against block.kind/blockType) and the
-    // login-wall hint (node's failureKind==='auth', trawl_node#1975) are two
-    // INDEPENDENT server-derived signals with no shared contract: node's block
-    // classifier (modules/historys/helpers/failureKind.js BLOCK_TYPE_PATTERN)
-    // and this CLI's vendor table live in different repos and can legitimately
-    // disagree. Concretely, `kasada` matches this CLI's table but is absent
-    // from node's block pattern, and the deprecated flat `blockType` fallback
-    // is a field node's classifier no longer reads at all — so a run can come
-    // back `failureKind:'auth'` (the server says login wall) while also
-    // matching a vendor here (this CLI says Kasada/DataDome/etc), both true
-    // signals about the same run, neither one wrong.
-    //
-    // trawl_cli#169 precedent: never assert client-side what only the server
-    // knows. Silently picking a winner between two disagreeing signals is
-    // exactly that — printing "no reliable bypass" alone asserts the run is
-    // NOT an auth wall (may stop someone from trying a fixable cookie
-    // problem); printing the cookie hint alone asserts the run is NOT a
-    // vendor wall (may send someone chasing cookies against a wall no cookie
-    // fixes). This CLI cannot tell which is true without either importing
-    // node's BLOCK_TYPE_PATTERN (a second source of truth for the same list —
-    // how this defect got here) or re-detecting the login URL itself (the
-    // client-side re-derivation this fix deliberately rejects). So when both
-    // fire, render ONE hedged line naming both readings instead of picking:
-    // never emit the bare "no reliable bypass" verdict in that case — it is
-    // exactly the false precision this branch exists to avoid.
-    //
-    // `conflictingSignals` is deliberately NOT gated on `scrapId` the way the
-    // plain hint below is: the false "no reliable bypass" verdict is wrong
-    // regardless of whether we also have an id to build an actionable command
-    // for, so a scrapId-less conflicting run must still avoid it. Only the
-    // action line degrades (to a generic Settings pointer) when there's no id.
-    //
-    // Single-signal cases are untouched: a plain vendor match (no
-    // failureKind:'auth') still gets "no reliable bypass"; a plain
-    // failureKind:'auth' (no vendor match) still gets the plain hint block
-    // below. `errMsg` stays suppressed whenever any hint form (conflicting or
-    // plain) is about to render — node's own `errorMessage` for an auth run
-    // (historys.service.js ~line 774) IS the hint copy verbatim, literal
-    // `<id>` placeholder and all, so printing it here would just be a second
-    // rendering of the same information. If neither hint form renders (no
-    // vendor conflict and no scrapId for the plain hint), fall back to node's
-    // raw message rather than dropping the error entirely.
     const wallVendor = detectWallVendor(run);
     const errMsg = run.errorMessage ?? run.errorSnapshot?.errorMessage;
-    // trawl_cli#182 — same `status`/`statusDetail` guard as `detectWallVendor`
-    // above, and for the same reason (see its doc comment): `failureKind` is a
-    // terminal classification trawl_node stamps once
-    // (modules/historys/services/historys.service.js ~line 837), but
-    // `patchForRegression` (modules/scraps/services/scraps.service.js ~line
-    // 1972) can flip `status`/`statusDetail` to success/regression LATER,
-    // without ever clearing `failureKind`. Left unguarded, a run that
-    // ultimately succeeded or degraded could still carry a stale
-    // `failureKind:'auth'` and render the login-wall hint (or the
-    // conflicting-signals hedge) right next to a green "success" badge or a
-    // "Regression: length N vs baseline M" line — the exact contradiction
-    // `detectWallVendor`'s guard already exists to prevent for `block.kind`.
-    // One rule, not two coincidences: both checks guard the same two fields
-    // against the same after-the-fact patch.
     const authWall = isAuthWall(run);
     const authHintWillRender = authWall && Boolean(scrapId);
     const conflictingSignals = Boolean(wallVendor) && authWall;
@@ -232,69 +82,38 @@ export function formatDoctor(scrapTitle, run, fix = null, scrapId) {
     else if (errMsg && !authHintWillRender) {
         lines.push(chalk.dim('  Error:   ') + chalk.red(errMsg));
     }
-    // Failed selector
     if (run.errorSnapshot?.selector) {
         lines.push(chalk.dim('  Failed selector: ') + chalk.cyan(run.errorSnapshot.selector));
     }
-    // Blocked
     lines.push(chalk.dim('  Blocked: ') + (run.blocked ? chalk.red('yes') : 'no'));
-    // Proxy tier (abstract, kept for owner)
     if (run.proxyTier && TIER_LABELS[run.proxyTier]) {
         lines.push(chalk.dim('  Proxy:   ') + TIER_LABELS[run.proxyTier]);
     }
-    // Empty context detail
     if (run.statusDetail === 'empty' && run.emptyContext?.page) {
         const page = run.emptyContext.page;
         lines.push(chalk.dim('  Empty context:   ') + `url=${page.url ?? '?'}  anchors=${page.totalAnchors ?? '?'}`);
     }
-    // Login-wall hint (trawl_node#1975 `failureKind==='auth'`) — trust node's
-    // verdict, never re-detect the login URL client-side. Hypothesis-framed
-    // ("likely fix"), not a promise: measured cases (Reddit/X/Instagram) had
-    // valid cookies and stayed walled. Gated on `scrapId` alone (via
-    // `authHintWillRender` above, shared with the generic error line so the
-    // two can't drift apart), NOT the `scrapId ?? run._id` fallback used
-    // elsewhere here — `run._id` is a history id, and the session-set command
-    // on one silently targets the wrong document.
-    //
-    // trawl_cli#182 — excludes `conflictingSignals`: when a wall-vendor match
-    // also fired, the combined hedged line above already covers the cookie
-    // suggestion. Rendering this plain, unhedged block too would stack a
-    // second verdict under the first (and directly contradict it, since this
-    // block asserts the run IS a login wall with no caveat) — exactly the
-    // two-verdicts-for-one-run defect this fix removes. Exactly one verdict
-    // block renders per run.
     if (authHintWillRender && !conflictingSignals) {
         lines.push('');
         lines.push(chalk.yellow('  Login wall (hypothesis): ') + 'this looks like a login redirect — your own session cookies are the likely fix.');
         lines.push(chalk.dim(`  → trawl scraps account session set ${scrapId} -c cookies.json   (or app Settings → Account)`));
     }
-    // Regression detail. trawl_node#1950 dropped the redundant `regressionDetected`
-    // boolean — it was `true` on every row iff `statusDetail === 'regression'`,
-    // so read that directly (works against a pre- or post-#1950 backend alike,
-    // no CLI/backend sequencing gap: `statusDetail` isn't part of this rename).
     if (run.statusDetail === 'regression') {
         lines.push(chalk.dim('  Regression:      ') + `length ${run.length ?? '?'} vs baseline ${run.baselineLength ?? '?'}`);
     }
-    // Autofix summary (when fix exists)
     if (fix) {
         lines.push(`  ${chalk.magenta('Autofix:')}        ${fix.outcome ?? '?'}${fix.classification ? ` — ${fix.classification}` : ''}${fix.reason ? ` (${fix.reason})` : ''}`);
         lines.push(chalk.dim(`  → full diff/dry-run/knowledge: trawl scraps autofix ${scrapId ?? run._id}  (or doctor --autofix)`));
     }
-    // Timestamp
     if (run.createdAt) {
         lines.push(chalk.dim('  Run at:  ') + formatDate(run.createdAt));
     }
-    // Snapshot hint
     if (run.errorSnapshot?.html || run.statusDetail === 'empty' || run.statusDetail === 'error') {
         lines.push('');
         lines.push(chalk.dim(`  → trawl scraps snapshot ${scrapId ?? run._id} --error   (download error-path HTML)`));
     }
     return lines.join('\n');
 }
-/**
- * Pure formatter — returns a human-readable autofix detail block.
- * Shows diff, dry-run results, knowledge consulted.
- */
 export function formatAutofix(fix) {
     const lines = [];
     lines.push(chalk.magenta.bold('Autofix attempt'));
@@ -324,17 +143,12 @@ export function formatAutofix(fix) {
     }
     return lines.join('\n');
 }
-/**
- * Fetch the latest run + its ai_fix_end activity for a scrap.
- * Returns null if the scrap has no runs yet.
- */
 export async function fetchRunAndFix(scrapId) {
     const scrap = await api.get(`/api/scraps/${scrapId}`);
     const hid = scrap.history?.[0]?._id;
     if (!hid)
         return null;
     const run = await api.get(`/api/historys/${hid}`);
-    // api.get unwraps the { data: T } envelope — the response is the array directly
     const acts = await api.get(`/api/scraps/${scrapId}/activities?history=${hid}&limit=5`);
     const fixAct = Array.isArray(acts) ? acts.find((a) => a.type === 'ai_fix_end') : undefined;
     const fix = fixAct ? { ...fixAct.metadata, createdAt: fixAct.createdAt } : null;

package/dist/commands/login.js

@@ -28,60 +28,11 @@ async function promptEmail() {
         rl.close();
     }
 }
-/** #107 — the shared success-reporting tail for all three login paths (env
- * token, --token flag, email/password). Under --json, prints a single
- * structured result on stdout instead of the chalk lines — never the raw
- * token itself (that's what `trawl token` is for). */
 function reportLoginSuccess(opts, email) {
-    // #169 review finding 3 — stderr, both under --json and plain output: this
-    // is a warning about what happens AFTER login succeeds, not part of either
-    // payload shape, so it must never be silently dropped just because --json
-    // is set.
     const overrideVar = getLiveAuthEnvVar();
     if (overrideVar) {
         console.error(chalk.yellow(`⚠ ${overrideVar} is set in your environment — it overrides the token just stored here for every subsequent command until you unset it.`));
     }
-    // #184 — `login` is the ONE intentional human setup moment: bootstrap any
-    // bundled Claude skill the user doesn't have yet. Gated exactly like
-    // every other filesystem-mutating side effect in this CLI
-    // (json/TTY/opt-out — see lib/skills.ts's isSkillsActionAllowed), so a
-    // CI/agent `TRAWL_TOKEN=x trawl login --json` never writes into
-    // ~/.claude/skills on a machine with no Claude Code session to discover
-    // them. `isInteractive` is the exact TTY definition login already uses
-    // for its own email/password prompt gate (lib/confirm.ts) — stdin AND
-    // stdout, not just stdout. `bootstrapped` is `null` ONLY when gated out
-    // (json/non-TTY/opted-out) or when every bundled skill is already owned
-    // by trawl — the genuine "nothing to do" case, where the lines below
-    // naturally never print. It is non-null whenever anything was attempted,
-    // whether or not any of it actually landed — see the block below.
-    //
-    // stderr, same convention as the `overrideVar` warning right above (and
-    // for the same reason): this is orthogonal to the `--json` envelope's
-    // fixed shape below, so it must never risk landing on stdout — a defense
-    // that holds even if `bootstrapSkillsOnLogin`'s own json/TTY gate above it
-    // were ever wrong, not just a style match.
-    //
-    // #184 review (BLOCK + MAJOR) — `bootstrapped` is non-null whenever there
-    // was anything to attempt, whether or not any of it actually landed, so
-    // both halves below must be checked independently: `installed` prints the
-    // success line, `skipped` prints one honest line per skill that was
-    // requested but did NOT land (a permission error, or a pre-existing
-    // marker-less dir the ownership guard refused to overwrite) and WHY —
-    // `reason` is already a relayable, fact-only string (SkillOwnershipRefusalError's
-    // `.relayableReason`, or a raw fs error message) with no imperative, so it
-    // is safe to print verbatim on this channel. A total failure (installed
-    // empty, skipped non-empty) must read as "attempted and failed" — never
-    // fall through to silence, which is indistinguishable from "never
-    // attempted" (the exact false-success shape this issue exists to
-    // prevent). The restart note only applies to what actually landed, so it
-    // stays scoped to that branch.
-    //
-    // #184 defect 2 — `error` is the THIRD case: distinct from both "nothing
-    // to do" (bootstrapped is `null`, nothing prints) and "some/all skills
-    // failed" (`skipped`, above) — it means bootstrapSkillsOnLogin could not
-    // even determine which skills to install (the bundled skills package
-    // looks missing/corrupted). Stated as a fact, same convention as every
-    // other line here.
     const bootstrapped = bootstrapSkillsOnLogin({ json: opts.json, isTTY: isInteractive(opts) });
     if (bootstrapped) {
         if (bootstrapped.error) {
@@ -113,17 +64,11 @@ export const login = new Command('login')
     .option('-p, --password <password>', 'Password (CI only — visible in process list and shell history)')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // Validate --url but do NOT persist it yet. A failed signin must not
-    // brick the config by pointing it at an unreachable/wrong host while the
-    // OLD token stays stored (and would then be sent to that new host on the
-    // next command). Target this run via `pendingUrl` and persist only once
-    // a token has actually been obtained. (#68)
     const pendingUrl = opts.url ? requireUrl(opts.url, '--url') : undefined;
     const persistUrlIfPending = () => {
         if (pendingUrl)
             config.set('apiUrl', pendingUrl);
     };
-    // Check environment variable override first
     const envToken = process.env['TRAWL_TOKEN'];
     if (envToken) {
         config.set('token', requireFreshJwt(envToken, 'TRAWL_TOKEN'));
@@ -131,20 +76,15 @@ export const login = new Command('login')
         reportLoginSuccess(opts);
         return;
     }
-    // --token flag: direct JWT (CI / retrocompat)
     if (opts.token) {
         config.set('token', requireFreshJwt(opts.token, '--token'));
         persistUrlIfPending();
         reportLoginSuccess(opts);
         return;
     }
-    // Email/password flow
     if (opts.password) {
         console.error(chalk.yellow('Warning: passing --password on the command line is insecure.'));
     }
-    // #107 — never blocks on a readline prompt under --json or a non-TTY
-    // invocation (agent/CI subprocess); refuses with a clear, structured
-    // usage error instead, naming the flag (or TRAWL_TOKEN) to pass.
     if (!opts.email) {
         requireInteractive('Email is required — pass -e/--email, --token, or set TRAWL_TOKEN (refusing to block on a prompt, non-interactive).', { json: opts.json });
     }
@@ -154,7 +94,6 @@ export const login = new Command('login')
     const email = opts.email ?? (await promptEmail());
     const password = opts.password ?? (await promptPassword('Password: '));
     const { data, headers } = await api.publicPost('/api/auth/signin', { email, password }, pendingUrl);
-    // Try token from response body first, then fall back to Set-Cookie header
     let raw = typeof data === 'string' ? data : data.token;
     if (!raw) {
         const setCookie = headers.get('set-cookie') ?? '';
@@ -175,12 +114,6 @@ export const logout = new Command('logout')
     .option('--json', 'Output as JSON')
     .action((opts) => {
     config.set('token', '');
-    // #169 review finding 3 — this is the sharpest version of the gap: an
-    // operator runs `logout` SPECIFICALLY to kill access, and if
-    // TRAWL_API_KEY/TRAWL_TOKEN is set, access is NOT killed — every
-    // subsequent command keeps authenticating with the env credential this
-    // command cannot touch. The wording below must not read as a variant of
-    // "logged out"; it says plainly that access is still live.
     const overrideVar = getLiveAuthEnvVar();
     if (overrideVar) {
         console.error(chalk.yellow(`⚠ ${overrideVar} is still set in your environment — access is NOT revoked. Every subsequent command will keep authenticating with it until you unset it (or revoke the key in the dashboard).`));

package/dist/commands/ping.d.ts

@@ -1,19 +1,4 @@
 import { Command } from 'commander';
-/**
- * `GET /api/health` response shape (home.controller.js#health,
- * home.service.js#getHealthStatus) — MCP `trawl_health_ping` parity
- * (`{ok, version, uptime}`). The REST route enriches the payload with
- * `version`/`uptime`/`db`/`memory` ONLY for an admin caller
- * (home.controller.js's `isAdmin` gate); a non-admin JWT gets `{status:'ok'}`
- * alone on a healthy server. A non-2xx response (degraded, `status:503`)
- * throws an ApiError like any other failed request — but a 2xx response is
- * NOT a guarantee that `status === 'ok'` (#106 review F5): a soft-degraded
- * signal (e.g. a partial dependency outage) could still come back as a 200
- * with a non-"ok" `status`. The HTTP call not throwing only means the
- * transport succeeded, never that the reported health is good — so the
- * human-mode `✓ OK` line is gated on the actual field, not assumed from a
- * successful round-trip.
- */
 export interface PingResponse {
     status: string;
     db?: string;

package/dist/commands/ping.js

@@ -6,33 +6,18 @@ export const ping = new Command('ping')
     .description('Health/version handshake against the Trawl API')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    // #148 — the server route is optionalAuth (public, enriched for an admin
-    // JWT — see the PingResponse doc above); `api.publicGet` mirrors that:
-    // it attaches a stored/env token when one happens to be available but
-    // never REQUIRES one, so `ping` works as a zero-config sanity check even
-    // with no `trawl login` ever run. `api.get` (the authenticated path)
-    // would throw notLoggedInError() locally before this ever reached the
-    // network, defeating the whole point of a pre-login handshake.
     const data = await api.publicGet('/api/health');
-    // #106 review (kimi) — honest exit code: a soft-degraded 200 (status !== 'ok')
-    // must exit non-zero so `trawl ping || handle_degraded` doesn't treat a
-    // degraded API as healthy. Applies in BOTH --json and human modes, alongside
-    // the raw/decorated output below.
     if (data.status !== 'ok')
         process.exitCode = 1;
     if (opts.json) {
         json(data);
         return;
     }
-    // #119 — label it as the API's version, not a bare `v0.4.0` that reads as
-    // "the platform is v0.4" (it's the server package version field).
     const versionSuffix = data.version ? ` (api v${data.version})` : '';
     if (data.status === 'ok') {
         console.log(chalk.green('✓ OK') + versionSuffix);
     }
     else {
-        // #106 review F5 — never green-light a degraded API just because the
-        // HTTP call didn't throw; show the real reported status instead.
         console.log(chalk.yellow(`⚠ ${data.status}`) + versionSuffix);
     }
 });

package/dist/commands/scraps.d.ts

@@ -1,138 +1,18 @@
 import { Command } from 'commander';
-/**
- * #108 — surface reorg. `run`/`list`/`get`/`data`/`history`/`run-info`/
- * `trigger` are promoted to top-level verbs (see index.ts's `createProgram`)
- * alongside `create`/`whoami`/`ping` (#114 — `create` replaced `fetch` in
- * that group). Each is built by an exported
- * `attachXCommand(parent, attachOpts)` factory instead of a fixed
- * `scraps.command(...)` chain, so it can be attached TWICE with a single
- * source-of-truth definition: once to `program` (the new canonical
- * top-level path) and once more, hidden, right back onto `scraps` — so every
- * pre-#108 `trawl scraps <verb>` invocation keeps resolving unchanged
- * (`{ hidden: true }` only affects help visibility, never resolution).
- *
- * Future-drift guard: ALL `.option()`/`.argument()`/`.action()` wiring for a
- * promoted verb MUST live INSIDE its `attachXCommand` factory body, never
- * bolted onto one of its two call sites (index.ts's `createProgram` for the
- * top-level attach, this file's own `attachXCommand(scraps, { hidden: true
- * })` call for the legacy one). That's the only thing keeping `trawl run
- * <id>` and `trawl scraps run <id>` identical — a call-site-only tweak to
- * one attachment would silently diverge the two.
- */
 type AttachOptions = {
     hidden?: boolean;
 };
 export declare const scraps: Command;
-/** The top-of-history snapshot pollRunProgress needs to identify which run
- * it's watching — see captureBeforeRunState.
- *
- * #97 — `captured` discriminates WHY `id` is undefined: `true` means the GET
- * succeeded and the scrap genuinely has no history yet (an honest "never
- * run" signal pollRunProgress can trust immediately); `false` means the GET
- * itself threw, so `id`/`alreadyInFlight` carry NO information at all — the
- * scrap could easily have prior (possibly terminal) history that this
- * lookup simply never saw. Before this field existed, both cases produced
- * the identical `{id: undefined, alreadyInFlight: false}` shape, so
- * pollRunProgress could not tell them apart (see its own #97 comment).
- */
 interface BeforeRunState {
     id?: string;
     alreadyInFlight: boolean;
     captured: boolean;
 }
-/** The machine-readable outcome `pollRunProgress` prints as the single final
- * NDJSON line under `--json` (#107 review F1). `status` is the same honest
- * terminal string the human-mode "Run finished: <status>" line already
- * shows (`success`/`error`/`empty`/`regression`/…), or `'timeout'` /
- * `'poll_error'` for the two non-terminal exits. */
 export interface PollOutcome {
     runId?: string;
     status: string;
-    /** Present only for `status:'poll_error'` — the last poll failure's message. */
     error?: string;
 }
-/**
- * #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 declare function pollRunProgress(id: string, before: BeforeRunState | undefined, opts?: {
     intervalMs?: number;
     timeoutMs?: number;