@trawlme/cli 3.12.0 → 3.12.2

package/README.md

@@ -36,7 +36,7 @@ Four methods:
 3. **Token flag** — `trawl login --token <jwt>` (CI/CD, direct JWT)
 4. **API key** — `TRAWL_API_KEY=trawl_xxx trawl list` (scoped, revocable one-by-one — the recommended credential for an agent driving this CLI; see [docs/agent-quickstart.md](docs/agent-quickstart.md))
 
-A `TRAWL_API_KEY` is a `trawl_*`-prefixed credential (create/revoke one in the Trawl dashboard) sent as `Authorization: Bearer` instead of the session `Cookie: TOKEN=` a JWT uses — `trawl` picks the right one automatically based on the credential's own shape, never a flag. `TRAWL_API_KEY` wins over `TRAWL_TOKEN` when both happen to be set. It is scoped server-side — in practice to a set of scraps, since the dashboard's key-create form sets only the scrap allow-list; narrowing which *actions* a key may perform needs an explicit `scopes` array at creation over the API, and a key without one has every action granted. It works on most of the Core tier — `create`/`list`/`get`/`data`/`history`/`run-info`/`run`/`trigger`/`ping`, including the `--watch` **polling flag** on `run`/`trigger` — plus, outside Core, `scraps account status`/`scraps doctor`/`scraps autofix` (all three only ever read routes trawl_node opened to keys). It does **not** work on `whoami`, `scraps update`/`delete`, `scraps account set`/`delete`/`clear-session`/`session set`, `scraps banner`, `scraps snapshot` (the scrap lookup it starts from is dual-auth, but the `html-snapshot` route it downloads from isn't), or the standalone SSE **command** `scraps watch` (do not conflate the two: `--watch` is a flag on `run`/`trigger` and works under a key; `scraps watch` is a separate command and is JWT-only) — those stay JWT-only and fail with a `kind:"auth"` envelope (exit `3`) pointing at `trawl login` under a key. This list mirrors trawl_node's route wiring as of this writing, not a frozen guarantee — for anything not named here, trust the real `--json` envelope over this paragraph. Never send both a key and a JWT on the same request — the CLI only ever attaches one. `list --unhealthy` (and the plain health badge on `list`/`get`) rides the same `GET /api/scraps`/`GET /api/scraps/:id` routes as the rest of the group — no separate auth path — so it works under a key exactly like plain `list`/`get`, and a scrap-scoped key still only ever sees its own allow-listed scraps through the filter.
+A `TRAWL_API_KEY` is a `trawl_*`-prefixed credential (create/revoke one in the Trawl dashboard) sent as `Authorization: Bearer` instead of the session `Cookie: TOKEN=` a JWT uses — `trawl` picks the right one automatically based on the credential's own shape, never a flag. `TRAWL_API_KEY` wins over `TRAWL_TOKEN` when both happen to be set. It is scoped server-side — in practice to a set of scraps, since the dashboard's key-create form sets only the scrap allow-list; narrowing which *actions* a key may perform needs an explicit `scopes` array at creation over the API, and a key without one has every action granted. It works on most of the Core tier — `create`/`list`/`get`/`data`/`history`/`run-info`/`run`/`trigger`/`ping`, including the `--watch` **polling flag** on `run`/`trigger` — plus, outside Core, `scraps account status`/`scraps doctor`/`scraps autofix` (all three only ever read routes the API opened to keys). It does **not** work on `whoami`, `scraps update`/`delete`, `scraps account set`/`delete`/`clear-session`/`session set`/`session capture`, `scraps banner`, `scraps snapshot` (the scrap lookup it starts from is dual-auth, but the `html-snapshot` route it downloads from isn't), or the standalone SSE **command** `scraps watch` (do not conflate the two: `--watch` is a flag on `run`/`trigger` and works under a key; `scraps watch` is a separate command and is JWT-only) — those stay JWT-only and fail with a `kind:"auth"` envelope (exit `3`) pointing at `trawl login` under a key. This list mirrors the server's route wiring as of this writing, not a frozen guarantee — for anything not named here, trust the real `--json` envelope over this paragraph. Never send both a key and a JWT on the same request — the CLI only ever attaches one. `list --unhealthy` (and the plain health badge on `list`/`get`) rides the same `GET /api/scraps`/`GET /api/scraps/:id` routes as the rest of the group — no separate auth path — so it works under a key exactly like plain `list`/`get`, and a scrap-scoped key still only ever sees its own allow-listed scraps through the filter.
 
 Custom API URL: `trawl login --url https://self-hosted.example.com`
 
@@ -76,7 +76,7 @@ trawl spec [--json]                            Print a versioned, machine-readab
 - `history` lists past runs (newest first); `run-info <hid>` shows details of a single run from that history.
 - `data` returns the last persisted run payload (no execute quota); `--fresh` runs the scrap live instead (consumes execute quota); `--errors` shows the last run's error detail (`--json` on a never-run scrap returns `{"status":"no_runs"}`, exit 0, matching `scraps doctor --json`). `[]` on stdout means a genuine zero-item successful run — a scrap that has never run, whose last run failed, or whose payload aged out of retention returns a `--json` error envelope (exit 4/1/4 respectively) instead. Two more honest states: a run still **in flight** (`status: null` server-side) returns a `kind:"in_progress"` error envelope (exit 1, "retry shortly" — never suggests `--fresh`, which would just 429 against the run already holding the lock); a run whose item count **regressed** vs baseline (`statusDetail: "regression"`) still returns the real, non-empty items on stdout (exit 0) plus a stderr warning pointing at `scraps doctor <id>` — the data itself is genuine even though the run is flagged.
 - `get` (and anything reading through it, like `data`'s default path) embeds only the newest 100 history rows on the returned scrap object — `run-info` and `scraps doctor` fetch a single run directly and are unaffected by that cap. `list`/`get` show a distinct amber `▼` "regression" badge, never the red `✗` a genuine failure gets (matches `scraps doctor`'s own badge).
-- `list`/`get` also show a **health** badge next to the status badge. By default it reads the scrap's own `lastCronOutcome` field (always present, no extra cost): `⚠ cron paused` when the last scheduled tick was skipped for being unhealthy, `—` otherwise — a breadcrumb of the last tick, not a live read (never set on a no-cron scrap, can lag by one tick). `list --unhealthy` asks the API to filter to scraps whose *current* consecutive-failure streak is 3+ (trawl_node's own threshold) and annotates each with the exact `consecutiveFailedRuns`/`unhealthySince` — shown instead of the badge whenever present, and never re-derived client-side from history. `--json` carries whichever fields the request produced: `lastCronOutcome` always, `consecutiveFailedRuns`/`unhealthySince` only when `--unhealthy` was passed. **Old-server safety:** a server predating trawl_node#1952 silently ignores the unknown `--unhealthy` query param and returns everything, unfiltered — the CLI detects that (no returned item carries `consecutiveFailedRuns`) and prints a stderr warning instead of presenting the full list as "your unhealthy scraps".
+- `list`/`get` also show a **health** badge next to the status badge. By default it reads the scrap's own `lastCronOutcome` field (always present, no extra cost): `⚠ cron paused` when the last scheduled tick was skipped for being unhealthy, `—` otherwise — a breadcrumb of the last tick, not a live read (never set on a no-cron scrap, can lag by one tick). `list --unhealthy` asks the API to filter to scraps whose *current* consecutive-failure streak is 3+ (the server's own threshold) and annotates each with the exact `consecutiveFailedRuns`/`unhealthySince` — shown instead of the badge whenever present, and never re-derived client-side from history. `--json` carries whichever fields the request produced: `lastCronOutcome` always, `consecutiveFailedRuns`/`unhealthySince` only when `--unhealthy` was passed. **Old-server safety:** an older server version that predates this filter silently ignores the unknown `--unhealthy` query param and returns everything, unfiltered — the CLI detects that (no returned item carries `consecutiveFailedRuns`) and prints a stderr warning instead of presenting the full list as "your unhealthy scraps".
 - **Long-running calls (`create`, `run`, `data --fresh`, `trigger --wait`):** these hit server-side paths that can legitimately take 30–250s+ (AI generation + scrap creation + a first run for `create`; proxy tier escalation + AI-fix retries for the other three) — the CLI arms a 300s timeout for exactly these four call sites instead of the generic 30s default. `TRAWL_TIMEOUT` (see below) still overrides ALL requests, including these — set it if you need a tighter or looser ceiling than 300s, but note a global override that tight also clamps `create`.
 - **`--watch` is poll-based, not a live stream:** the activities SSE endpoint has no backlog and, for the default async `trigger` (no `--wait`), runs in a separate cron-consumer pod whose events never reach the API pod holding the SSE connection — a naive "await the run, then open SSE" shows nothing. `run --watch` and `trigger --watch` instead poll `GET /api/scraps/:id` (terminal status) and the activities REST list until the run finishes, printing each new activity line as it appears. The watched run's outcome drives the exit code too, in BOTH human and `--json` mode: a genuinely failed terminal run, a poll timeout, or a persistently unreachable API all exit non-zero — a clean successful run is the only exit `0`. A run that never reaches a terminal status within 300s prints an honest timeout notice pointing at `scraps doctor <id>` (human mode) — see the `--json` shape below. `scraps watch <id>` (the standalone command, no trigger) is unchanged — it still opens the live SSE stream directly.
 - `spec --json` prints the CLI's own command tree — `{specVersion, cliVersion, commands[], exitCodes, errorKinds, kindExitCodes, docsUrl?, llmsUrl?}` — DERIVED at runtime by walking the live commander tree (never a hand-maintained file, which would silently drift from reality). Each entry in `commands[]` carries its full path (e.g. `"scraps account session set"`), description, `hidden` (the legacy `scraps <verb>` aliases above), `leaf` (false for a pure namespace/group node like `scraps`/`skills`/`telemetry` — invoking one directly is a guaranteed-failing tool, not a real command), `aliases`, `arguments`, `options`, and an optional per-command `docs` deep link (e.g. every `scraps account *` command points at the account-sessions guide); `exitCodes`/`errorKinds`/`kindExitCodes` are read from the exact same source `classifyError` uses (see [Exit codes](#exit-codes)) — never a second copy. `kindExitCodes` is the inverse of `exitCodes`: `kind -> exitCode`, since exit code `1` alone is a shared bucket (`api`/`refused`/`unknown`/`in_progress`/`run_failed`/`upgrade_failed`) that `exitCodes`' flat label can't disambiguate. `docsUrl` is resolved server-first (`externalDocs.url` on the configured API base's own OpenAPI document, when declared), else derived from a KNOWN first-party `trawl.me` API host, else **omitted entirely** — never a guessed URL pointed at the wrong docs host for a self-hosted install. `llmsUrl` and every per-command `docs` link are narrower: they only ever come from that same known-host derivation, NEVER from a server-declared `docsUrl` — this CLI's own guide slugs have no reason to exist on a third party's own docs root, so a self-hosted server that declares `externalDocs.url` gets a correct top-level `docsUrl` but no `llmsUrl` and no per-command `docs` links. A `failureKind:"auth"` run's JSON payload (`doctor`/`data --errors`/`run-info`) carries the same `docs` field, by the same known-host-only rule. Without `--json`, `spec` prints one short human line (version + visible command count) pointing at `--json`.

package/dist/commands/create.d.ts

@@ -1,37 +1,9 @@
 import { Command } from 'commander';
-/**
- * `POST /api/ai/wizard` response contract (#114, trawl_node —
- * ai.wizard.service.js#runWizard, shipped S1, contract LOCKED). The wizard
- * chains, entirely server-side: AI code generation -> scrap creation ->
- * the FIRST run (ScrapsService.load) -> auto-fix on failure (autoFix
- * defaults true unless `--no-autofix` maps to `autoFix:false`).
- *
- *  - `success` is an HONEST outcome of that first run, not "did the HTTP
- *    call succeed" — a failed first run is still a 200 response (the scrap
- *    itself was created either way; auto-fix, when enabled, retries in the
- *    background). Callers must branch on `success`, never assume 2xx means
- *    "the scrap works".
- *  - `scrap` is the full created Scrap object (present whenever creation got
- *    far enough to persist it — a hard failure before that point surfaces as
- *    a real HTTP error instead, handled by the shared error path).
- *  - `historyId` is best-effort (a failed server-side lookup leaves it
- *    `null`, never breaks the response) — it points at the first run just
- *    executed.
- */
 export interface WizardResponse {
     success: boolean;
     scrap?: {
         _id: string;
         title: string;
-        /**
-         * Cron expression the wizard schedules this scrap on. As of #114/S1
-         * (trawl_node ai.wizard.service.js#runWizard's `scrapBody`) this is
-         * hardcoded server-side to a DAILY run — `'0 7 * * *'` / `cronTimezone:
-         * 'UTC'` — unconditionally, regardless of `--prompt`/`--no-autofix`.
-         * Present on the scrap object returned here (the wizard controller
-         * passes the created scrap straight through, no stripping) — change or
-         * disable it with `trawl scraps update <id> --cron <expr>` / `--no-cron`.
-         */
         cron?: string | null;
         cronTimezone?: string;
         [key: string]: unknown;

package/dist/commands/create.js

@@ -8,12 +8,6 @@ import { requireUrl, requireString } from '../lib/validate.js';
 import { UsageError } from '../lib/errors.js';
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 import { startPinchAnimation } from '../lib/pinchAnimation.js';
-/** Best-effort, honest first-run summary — never claims a background retry
- * happened when auto-fix was disabled for this call, and never claims a
- * scrap was persisted when the response carries none (#114-F3 — a hard
- * failure before persistence still comes back as `success:false` with no
- * `scrap` at all; claiming "auto-fix retrying in the background" then would
- * be fabricated — there is nothing to retry). */
 function firstRunLabel(data, autoFixEnabled) {
     if (data.success)
         return 'succeeded';
@@ -23,10 +17,6 @@ function firstRunLabel(data, autoFixEnabled) {
         return 'failed (auto-fix retrying in the background)';
     return 'failed';
 }
-/** Best-effort human description of a daily cron (`M H * * *`) — the only
- * shape the wizard's server-side default currently produces. Falls back to
- * printing the raw expression for anything else rather than guessing at a
- * schedule the CLI can't actually parse. */
 function describeCron(cron) {
     const match = /^(\d{1,2})\s+(\d{1,2})\s+\*\s+\*\s+\*$/.exec(cron.trim());
     if (!match)
@@ -34,16 +24,6 @@ function describeCron(cron) {
     const [, min, hour] = match;
     return `daily ${hour.padStart(2, '0')}:${min.padStart(2, '0')}`;
 }
-/**
- * #114-F2 — a wizard-created scrap runs on a DAILY cron by default
- * server-side; surface that up front rather than leaving it to be
- * discovered later as an unexpected recurring quota charge. Reads the real
- * `cron`/`cronTimezone` field off the response scrap when present; falls
- * back to the known wizard default wording ONLY when the field is missing
- * from the response (an older server, or a future rename) — never invents a
- * schedule value that might not match what the server actually applied.
- * Returns null when there's no scrap to schedule at all.
- */
 function scheduleLabel(scrap) {
     if (!scrap)
         return null;
@@ -53,24 +33,11 @@ function scheduleLabel(scrap) {
     }
     return 'scheduled daily by default';
 }
-/**
- * #121 — onboarding principle: a successful `create` should SHOW the value,
- * not just an id. Best-effort fetch of the first run's persisted data (the
- * same read-only, no-quota path `trawl data <id>` uses:
- * `GET /api/historys/:historyId` → a JSON string `{ data: [...] }`) and print
- * a small proof-of-value sample (count + first-item keys + one truncated
- * value line — never a full dump; that's what `trawl data --json` is for).
- * ANY failure (network, parse, no data) is swallowed silently — the sample is
- * a bonus, it must never turn a successful create into a failure or noise.
- */
 async function printDataSample(historyId) {
     try {
         const detail = await api.get(`/api/historys/${historyId}`);
         if (typeof detail?.data !== 'string' || !detail.data)
             return;
-        // #159 — same JSON-string-within-JSON shape as scrap.history[0].data;
-        // tolerate the documented raw-control-char server quirk here too instead
-        // of silently losing the sample to the outer try/catch below.
         const items = parseServerJson(detail.data)?.data;
         if (!Array.isArray(items) || items.length === 0)
             return;
@@ -88,7 +55,6 @@ async function printDataSample(historyId) {
         }
     }
     catch {
-        // best-effort — a missing sample never fails or noises up a good create
     }
 }
 export const create = new Command('create')
@@ -99,15 +65,6 @@ export const create = new Command('create')
     .option('--no-autofix', 'Disable AI auto-fix on first-run failure (default: on)')
     .option('--json', 'Output the raw API payload')
     .action(async (rawUrl, opts) => {
-    // Fast, local usage-errors (exit 2) — never a round-trip to the server
-    // for something we can already tell is bad. Same fail-fast pattern the
-    // former `fetch` command used for its URL argument.
-    //
-    // #116 — the url is accepted BOTH as the positional argument (agent
-    // one-liner) and as `--url` (muscle memory from `scraps create` and the
-    // API body {url, goal}). Exactly one is required; both are fine only
-    // when identical — two DIFFERENT urls is ambiguous, refuse loudly
-    // rather than silently picking one.
     if (rawUrl === undefined && opts.url === undefined) {
         throw new UsageError("missing required argument 'url' (positional, or --url <url>)");
     }
@@ -121,58 +78,28 @@ export const create = new Command('create')
         goal,
         ...(opts.autofix === false && { autoFix: false }),
     };
-    // #91/#106-F1 long-run pattern — the wizard runs AI generation + scrap
-    // creation + a real FIRST run (+ autofix retries) entirely server-side,
-    // legitimately 30-250s+. The 30s DEFAULT_TIMEOUT_MS would abort it
-    // mid-flight and fabricate a NetworkError timeout for a request that was
-    // always going to succeed.
     const call = () => api.post('/api/ai/wizard', body, { timeoutMs: LONG_RUN_TIMEOUT_MS });
-    // #106-F2 pattern carried over from `fetch` — under --json stdout must
-    // be provably pure: no spinner channel at all. Only the human path gets
-    // the ora progress indicator; --json calls the API directly.
     let data;
     if (opts.json) {
         data = await call();
     }
     else {
-        // #122/#131 — while the server-side wizard runs (legitimately 30-250s+,
-        // see LONG_RUN_TIMEOUT_MS above) Pinch ANIMATES in place (claw-wiggle)
-        // on a color-capable TTY; otherwise the ora spinner (which itself
-        // no-ops under a non-TTY, so piped human output stays clean). Both
-        // write to stderr only — stdout purity under `--json` is guaranteed by
-        // the `opts.json` branch above, never by this code.
         const anim = pinchEnabled() ? startPinchAnimation(`Creating a scrap from ${url}…`) : null;
         try {
             data = anim
                 ? await call()
                 : await spin(call, {
-                    // No verdict symbol (#106-F3) — ora's success only means "the
-                    // HTTP call didn't throw", not "the first run succeeded".
                     text: `Creating a scrap from ${url}…`,
                     successText: 'Request complete',
                 });
         }
         catch (err) {
             anim?.stop();
-            // #114-F1 — a client-side timeout (NetworkError, "timed out after
-            // …ms" per api.ts's safeFetch) does NOT mean the wizard failed
-            // server-side: the scrap creation + first run keep going on the
-            // server after the CLI gives up waiting, so the scrap may already
-            // exist (or land moments later). Warn BEFORE rethrowing so a retry
-            // isn't the first instinct — a blind retry creates a duplicate scrap
-            // and burns AI-generation quota a second time for the same goal.
-            // Only a NetworkError whose message identifies it as the timeout
-            // branch qualifies — a DNS/connection-refused NetworkError never
-            // reached the server at all, so there's nothing to warn about here.
             if (err instanceof NetworkError && /timed out/i.test(err.message)) {
                 console.error(chalk.yellow('⚠ The request timed out client-side, but the scrap may STILL have been created server-side — run `trawl list` before retrying (a retry creates a DUPLICATE scrap + burns quota).'));
             }
-            // Rethrow unchanged so index.ts's classifyError/exit-code taxonomy
-            // stays intact (this stays a NetworkError -> exit 5, same as before).
             throw err;
         }
-        // Success — stop + erase the animation so the result prints on a clean
-        // line (the celebrating/confused frame below is the one-shot outcome).
         anim?.stop();
     }
     if (opts.json) {
@@ -190,19 +117,11 @@ export const create = new Command('create')
         console.log(chalk.dim(`  First run:  `) + firstRunLabel(data, autoFixEnabled));
         if (schedule)
             console.log(chalk.dim(`  Schedule:   `) + schedule);
-        // #121 — on a successful first run, prove the value: show a small data
-        // sample (best-effort, silent on failure) before the next-step hint.
         if (data.success && data.historyId)
             await printDataSample(data.historyId);
-        // #121 — the natural next command is the DATA, not the metadata: point
-        // at `trawl data` primarily, keep `trawl get` as the secondary detail view.
         if (scrapId) {
             console.log(chalk.dim(`  Next step:  `) + `trawl data ${scrapId}` + chalk.dim(`  (details: trawl get ${scrapId})`));
         }
-        // #114-F3 — only claim a background retry is happening when a scrap
-        // actually exists to retry (never fabricate progress that isn't real);
-        // `firstRunLabel` above already covers the !scrap / autofix-disabled
-        // wording, this adds the actionable poll target on top.
         if (!data.success && data.scrap && autoFixEnabled) {
             const pollTarget = data.historyId
                 ? `\`trawl data ${scrapId}\` or \`trawl run-info ${data.historyId}\``
@@ -210,18 +129,10 @@ export const create = new Command('create')
             console.log(chalk.yellow(`  Note:       `) +
                 `Auto-fix is retrying in the background — do NOT re-run create; poll ${pollTarget}.`);
         }
-        // #122 — Pinch reacts to the HONEST first-run outcome (same signal the
-        // ✓/✗ line above already renders): celebrates a real success, looks
-        // confused on a genuine failure. Belt-and-suspenders `!opts.json`
-        // alongside pinchEnabled() — see the 'thinking' print above for why.
         if (!opts.json && pinchEnabled()) {
             console.log(data.success ? renderPinch('celebrating') : renderPinch('confused'));
         }
     }
-    // Honest exit code alongside the honest payload — a --json caller gets
-    // the raw body regardless (never wrapped/altered), but a script checking
-    // the exit code alone must be able to tell "first run failed" from "ran
-    // fine" without parsing. Same contract the former `fetch` command used.
     if (!data.success)
         process.exitCode = 1;
 });

package/dist/commands/doctor.d.ts

@@ -1,9 +1,3 @@
-/**
- * Run diagnostics shape — mirrors the owner-safe REST shape returned by
- * GET /api/historys/:id (Phase 1 projection, 2026-05-27).
- * Cost and proxy-nature fields are intentionally absent by design.
- * Abstract proxyTier (Tier 0–4) is kept.
- */
 export interface Run {
     _id: string;
     status: boolean | null;
@@ -28,11 +22,6 @@ export interface Run {
     block?: {
         kind?: string | null;
     } | null;
-    /** @deprecated trawl_node#1950 renamed this to `block.kind`. Kept as a read
-     * fallback (see detectWallVendor) for the window where this CLI is
-     * published ahead of the trawl_node prod tag — a prod backend served from
-     * the pre-#1950 tag still returns this flat field, not `block.kind`. Drop
-     * once prod is confirmed on a tag containing #1950. */
     blockType?: string | null;
     proxyTier?: string | null;
     baselineLength?: number | null;
@@ -40,64 +29,14 @@ export interface Run {
     createdAt?: string;
     time?: number | null;
     triggeredBy?: string | null;
-    /** trawl_node#1975 — freeform failure classification (`'auth'` = login-wall
-     * empty run, cookies are the fix). Not a TS union — trawl_node's own set
-     * is additive/open, so this CLI must stay read-safe against a future
-     * value it doesn't know about yet, same posture as `block.kind` above. */
     failureKind?: string | null;
 }
-/**
- * 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 declare function detectWallVendor(run: Pick<Run, 'status' | 'statusDetail' | 'block' | 'blockType'>): string | 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 declare function isAuthWall(run: {
     failureKind?: string | null;
     status?: boolean | null;
     statusDetail?: string | null;
 }): boolean;
-/**
- * Autofix activity metadata — from the persisted ai_fix_end activity.
- * aiUsage (cost) is stripped server-side; all diagnostics are kept.
- */
 export interface FixActivity {
     outcome: 'applied' | 'failed' | 'skipped' | 'breaker_tripped' | 'timeout' | null;
     classification?: string | null;
@@ -127,26 +66,8 @@ interface ScrapHead {
 }
 export declare function pickRun(run: Run): Partial<Run>;
 export declare function pickFix(fix: FixActivity | null): Partial<FixActivity> | null;
-/**
- * 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 declare function formatDoctor(scrapTitle: string, run: Run, fix?: FixActivity | null, scrapId?: string): string;
-/**
- * Pure formatter — returns a human-readable autofix detail block.
- * Shows diff, dry-run results, knowledge consulted.
- */
 export declare function formatAutofix(fix: FixActivity): string;
-/**
- * Fetch the latest run + its ai_fix_end activity for a scrap.
- * Returns null if the scrap has no runs yet.
- */
 export declare function fetchRunAndFix(scrapId: string): Promise<{
     scrap: ScrapHead;
     run: Run;