@trawlme/cli 1.18.1 → 1.18.3

package/dist/commands/scraps.js

@@ -5,25 +5,30 @@ import { api } from '../lib/api.js';
 import { table, json } from '../lib/format.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
-import { classifyError } from '../lib/errors.js';
+import { classifyError, reportError, UsageError } from '../lib/errors.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 /**
- * Print a usage/validation error consistently: human text to stderr always;
- * when the invoking command supports --json, ALSO emit a machine envelope on
- * stdout instead of leaving stdout silent/prose. 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)
+ * 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 = {}) {
-    console.error(chalk.red(`✗ ${message}`));
-    if (opts.json) {
-        console.log(JSON.stringify({ error: { message, kind: 'usage' } }));
-    }
-    process.exitCode = 2;
+    process.exitCode = reportError(new UsageError(message), { json: opts.json });
 }
 function lastStatus(scrap) {
     const last = scrap.history?.[0];
-    if (!last || last.status === null || last.status === undefined)
+    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';
     return last.status === true ? 'success' : 'failure';
 }
@@ -44,6 +49,8 @@ function statusIcon(status) {
         return chalk.green('✓');
     if (status === 'failure')
         return chalk.red('✗');
+    if (status === 'running')
+        return chalk.cyan('↻');
     return chalk.dim('—');
 }
 export const scraps = new Command('scraps').description('Manage scraps');
@@ -70,33 +77,55 @@ scraps
     .alias('ls')
     .description('List all scraps')
     .option('--json', 'Output as JSON')
-    .option('--status <status>', 'Filter by last run status (success|failure|never)')
-    .option('--limit <n>', 'Show only the first N results', (v) => parseInt(v, 10))
-    .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)', (v) => parseInt(v, 10))
-    .action(async (opts) => {
+    .option('--status <status>', 'Filter by last run status (success|failure|never|running)')
+    // #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)')
+    .action(async (opts, cmd) => {
     // 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;
     }
+    let limit;
+    if (opts.limit !== undefined) {
+        limit = Number(opts.limit);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+            return;
+        }
+    }
+    let page;
+    if (opts.page !== undefined) {
+        page = Number(opts.page);
+        if (!Number.isInteger(page) || page <= 0) {
+            usageError(`Invalid --page "${opts.page}" (expected a positive integer)`, { json: opts.json });
+            return;
+        }
+    }
     let data;
     try {
         data = await oraPromise(async () => {
-            if (opts.page !== undefined) {
+            if (page !== undefined) {
                 // Single-page mode: explicit page requested, no loop
-                const pageNum = opts.page;
-                return api.get(`/api/scraps?perPage=50&page=${pageNum}`);
+                return api.get(`/api/scraps?perPage=50&page=${page}`);
             }
             // Fetch-all mode: paginate until a page returns < 200 items
             const perPage = 200;
             let result = [];
-            let page = 1;
+            let pageNum = 1;
             while (true) {
-                const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${page}`);
+                const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${pageNum}`);
                 result = result.concat(batch);
                 if (batch.length < perPage)
                     break;
-                page++;
+                pageNum++;
             }
             return result;
         }, 'Fetching scraps…');
@@ -105,12 +134,22 @@ scraps
         // 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}`;
+        if (isDebug)
+            console.error(err);
         if (opts.json) {
             console.log(JSON.stringify({ error: { ...envelope, message } }));
         }
-        else {
+        else if (!isDebug) {
             console.error(chalk.red(`✗ ${message}`));
         }
         process.exitCode = exitCode;
@@ -119,7 +158,6 @@ scraps
     if (opts.status)
         data = data.filter((s) => lastStatus(s) === opts.status);
     const totalMatched = data.length;
-    const limit = opts.limit;
     const rows = limit !== undefined ? data.slice(0, limit) : data;
     if (opts.json)
         return json(rows);
@@ -155,6 +193,75 @@ scraps
     console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
 });
 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)
+        return;
+    if (ov.refused) {
+        console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
+            + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
+    }
+    else if (ov.effectiveMaxTier) {
+        console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
+            + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
+        if (ov.warning)
+            console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
+    }
+    if (ov.proxyTier) {
+        if (ov.proxyTier.clamped) {
+            console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
+                + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
+        }
+        else {
+            console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
+        }
+    }
+}
+/**
+ * #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 scraps 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). */
+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 Error(message), { json: wantsJson });
+}
 // create
 scraps
     .command('create')
@@ -164,9 +271,10 @@ scraps
     .option('-r, --request <request>', 'Request/query')
     .option('-d, --description <text>', 'Scrap description')
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
+    .option('--json', 'Output as JSON')
     .action(async (opts) => {
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     const data = await oraPromise(() => api.post('/api/scraps', {
@@ -176,7 +284,24 @@ 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);
+    if (opts.json) {
+        if (refused) {
+            process.exitCode = reportTierRefusal(data, true);
+            return;
+        }
+        json(withTierUnconfirmed(data, tierWasRequested));
+        return;
+    }
     console.log(chalk.dim(`  Title: ${data.title}`));
+    renderTierOverrideHuman(data);
+    if (refused)
+        process.exitCode = 1;
 });
 // update
 scraps
@@ -196,14 +321,15 @@ scraps
     .option('--params-file <path>', 'Runtime params from a JSON file')
     .option('--tier <tier>', `Force proxy tier (${VALID_TIERS.join('|')})`)
     .option('--force-tier <tier>', `Raise the proxy-tier ceiling PAST the auto-cap (${VALID_TIERS.join('|')}) — history-gated: may be refused or cost more`)
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     if (opts.tier !== undefined && !VALID_TIERS.includes(opts.tier)) {
-        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --tier "${opts.tier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     if (opts.forceTier !== undefined && !VALID_TIERS.includes(opts.forceTier)) {
-        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`);
+        usageError(`Invalid --force-tier "${opts.forceTier}" (allowed: ${VALID_TIERS.join(', ')})`, { json: opts.json });
         return;
     }
     const body = {};
@@ -241,11 +367,11 @@ scraps
             parsed = JSON.parse(raw);
         }
         catch (e) {
-            usageError(`Invalid JSON for --params: ${e.message}`);
+            usageError(`Invalid JSON for --params: ${e.message}`, { json: opts.json });
             return;
         }
         if (!Array.isArray(parsed)) {
-            usageError('--params must be a JSON array of objects');
+            usageError('--params must be a JSON array of objects', { json: opts.json });
             return;
         }
         body.params = parsed;
@@ -259,6 +385,10 @@ scraps
             body.proxyTier = opts.forceTier;
     }
     if (Object.keys(body).length === 0) {
+        if (opts.json) {
+            process.exitCode = reportError(new UsageError('Nothing to update. Provide at least one option.'), { json: true });
+            return;
+        }
         console.log(chalk.yellow('Nothing to update. Provide at least one option.'));
         return;
     }
@@ -266,42 +396,35 @@ scraps
         text: 'Updating scrap…',
         successText: (d) => `Scrap updated: ${chalk.bold(d._id)}`,
     });
-    // #1559 — surface the effective tier + clamp/refuse reason (fixes the
-    // silent-clamp: the server may persist a lower tier than requested).
-    const ov = data._tierOverride;
+    // #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);
+    if (opts.json) {
+        if (refused) {
+            process.exitCode = reportTierRefusal(data, true);
+            return;
+        }
+        json(withTierUnconfirmed(data, tierWasRequested));
+        return;
+    }
     const shown = data;
     for (const key of Object.keys(body)) {
-        // Only suppress the raw proxyTier/proxyMaxTier echo when _tierOverride is
-        // present to report the truth. Against an older server (no _tierOverride)
-        // fall back to echoing the requested value from the body, so the tier is
-        // never silently dropped (worse than a misleading echo).
-        if ((key === 'proxyTier' || key === 'proxyMaxTier') && ov)
+        // 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];
         console.log(chalk.dim(`  ${key}: `) + String(src ?? '—'));
     }
-    if (ov) {
-        if (ov.refused) {
-            console.error(chalk.red(`  ✗ tier ceiling override refused: ${ov.reason ?? 'unknown'}`)
-                + chalk.dim(` (requested ${ov.requestedMaxTier ?? '—'}; kept the registry cap)`));
-            process.exitCode = 1;
-        }
-        else if (ov.effectiveMaxTier) {
-            console.log(chalk.green(`  ✓ tier ceiling: ${ov.effectiveMaxTier}`)
-                + chalk.dim(` (${ov.reason ?? ''}${ov.provider ? `, ${ov.provider}` : ''})`));
-            if (ov.warning)
-                console.log(chalk.yellow(`    ⚠ ${ov.warning}`));
-        }
-        if (ov.proxyTier) {
-            if (ov.proxyTier.clamped) {
-                console.log(chalk.yellow(`  ⚠ proxyTier requested ${ov.proxyTier.requested} → applied ${ov.proxyTier.effective}`)
-                    + chalk.dim(` (${ov.proxyTier.reason ?? 'capped'})`));
-            }
-            else {
-                console.log(chalk.dim(`  proxyTier: `) + ov.proxyTier.effective);
-            }
-        }
-    }
+    renderTierOverrideHuman(data);
+    if (refused)
+        process.exitCode = 1;
 });
 // run
 scraps
@@ -332,6 +455,25 @@ 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).
+ */
+function reportDataState(message, exitCode, kind, wantsJson) {
+    console.error(chalk.red(`✗ ${message}`));
+    if (wantsJson) {
+        console.log(JSON.stringify({ error: { message, kind } }));
+    }
+    process.exitCode = exitCode;
+}
 // data
 scraps
     .command('data <id>')
@@ -346,8 +488,12 @@ scraps
     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(null);
+                json({ status: 'no_runs' });
                 return;
             }
             console.log(chalk.dim('No runs yet.'));
@@ -397,17 +543,48 @@ scraps
     // 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 hid = scrap.history?.[0]?._id;
-    if (!hid) {
-        if (opts.json) {
-            json([]);
-            return;
-        }
-        console.log(chalk.dim('No data yet. Run the scrap first, or pass --fresh to launch one now.'));
+    const last = scrap.history?.[0];
+    if (!last?._id) {
+        reportDataState(`Scrap ${id} has never run. Run it first (trawl scraps run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
         return;
     }
-    const detail = await api.get(`/api/historys/${hid}`);
+    // #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) {
+        reportDataState(`Run in progress for ${id} — retry shortly.`, 1, 'in_progress', opts.json);
+        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) {
+        reportDataState(`Last run failed — see: trawl scraps data ${id} --errors`, 1, 'run_failed', opts.json);
+        return;
+    }
+    const detail = await api.get(`/api/historys/${last._id}`);
     let items;
     if (typeof detail?.data === 'string' && detail.data) {
         try {
@@ -418,14 +595,27 @@ scraps
         }
     }
     if (!Array.isArray(items)) {
-        if (opts.json) {
-            json([]);
+        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;
         }
-        console.log(chalk.dim('No persisted data for the last run (it may have failed, or aged out of retention). '
-            + 'Pass --fresh to launch a new run (consumes execute quota).'));
+        // #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}`));
+    }
     renderScrapItems(items, opts.json);
 });
 // history — list past runs for a scrap
@@ -708,8 +898,9 @@ account
     const data = await oraPromise(() => api.get(`/api/scraps/${id}`), 'Fetching scrap…');
     const acc = data.account;
     if (opts.json) {
-        const { json: jsonFn } = await import('../lib/format.js');
-        return jsonFn(acc ?? null);
+        // #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) {
         console.log(chalk.dim('No account data available.'));
@@ -770,14 +961,19 @@ 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(null);
+            json({ status: 'no_runs' });
             return;
         }
         console.log(chalk.dim('No runs yet.'));
         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;

package/dist/commands/skills.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, } from '../lib/skills.js';
+import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, removeOrphanedSkills, } from '../lib/skills.js';
+import { UsageError } from '../lib/errors.js';
 function pickScope(opts) {
     return opts.local ? 'local' : 'user';
 }
@@ -9,7 +10,9 @@ function pickSkills(arg) {
     if (!arg || arg === 'all')
         return all;
     if (!all.includes(arg)) {
-        throw new Error(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
+        // Usage error (exit 2), not a generic bug (exit 1) — the caller typed a
+        // skill name that doesn't exist. (#86 finding 3)
+        throw new UsageError(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
     }
     return [arg];
 }
@@ -45,11 +48,12 @@ skills
     .command('install [skill]')
     .description('Install one or all bundled skills')
     .option('--local', 'Install at project level (./.claude/skills) instead of user level (~/.claude/skills)')
+    .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
     for (const name of targets) {
-        const dest = installSkill(name, scope);
+        const dest = installSkill(name, scope, { force: opts.force });
         console.log(chalk.green(`✓ Installed "${name}"`) + chalk.dim(` at ${dest}`));
     }
     console.log(chalk.dim('  Restart Claude Code if it was already running.'));
@@ -73,11 +77,19 @@ skills
     .command('update [skill]')
     .description('Reinstall over the existing skill (force sync with CLI version)')
     .option('--local', 'Update at project level')
+    .option('--force', 'Overwrite a pre-existing dir even if trawl did not install it (no .version marker)')
     .action((skill, opts) => {
     const scope = pickScope(opts);
     const targets = pickSkills(skill);
     for (const name of targets) {
-        const dest = installSkill(name, scope);
+        const dest = installSkill(name, scope, { force: opts.force });
         console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
     }
+    // #86 review — same orphan sweep as the startup auto-sync: an explicit
+    // `skills update` must also drop CLI-owned dirs whose skill was renamed
+    // or removed upstream (e.g. 1.0.0's `trawl` → 1.3.1's `trawl-cli`),
+    // instead of leaving a stale ghost teaching outdated usage. Only the
+    // scope being updated is swept; marker-less dirs are never touched.
+    // removeOrphanedSkills prints its own honest stderr line per removal.
+    removeOrphanedSkills(scope);
 });

package/dist/commands/token.js

@@ -1,21 +1,30 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import config from '../lib/config.js';
+import { getToken } from '../lib/config.js';
+import { AuthError, notLoggedInError } from '../lib/api.js';
+import { reportError } from '../lib/errors.js';
 import { decodeExp } from '../lib/jwt.js';
 export const token = new Command('token')
     .description('Print the stored session JWT (for MCP Bearer auth)')
     .action(() => {
-    const stored = config.get('token');
+    // getToken() resolves TRAWL_TOKEN env first, then the stored config
+    // token (see config.ts:47-51) — matching every other token consumer in
+    // the CLI instead of reading the config store directly. (#86 finding 1)
+    const stored = getToken();
     if (!stored) {
-        console.error(chalk.red('✗ Not logged in. Run: trawl login'));
-        process.exitCode = 1;
+        // Auth-classified (ApiError 401 → exit 3, kind:"auth"), not a generic
+        // exit 1 — an agent scripting `trawl token` needs to tell "not logged
+        // in" apart from an arbitrary bug. (#86 finding 1)
+        process.exitCode = reportError(notLoggedInError());
         return;
     }
     const exp = decodeExp(stored);
     const nowSeconds = Math.floor(Date.now() / 1000);
     if (exp !== null && exp < nowSeconds) {
-        console.error(chalk.red('✗ Session token expired. Run: trawl login to refresh.'));
-        process.exitCode = 1;
+        // Decoded entirely client-side (no HTTP call made) — AuthError, not a
+        // fabricated ApiError(401): the server never actually said this. (#88
+        // item 4)
+        process.exitCode = reportError(new AuthError('Session token expired. Run: trawl login to refresh.'));
         return;
     }
     // Print the raw token first (so it can be piped / copied)