@trawlme/cli 1.20.0 → 1.22.0

package/dist/commands/scraps.js

@@ -5,7 +5,8 @@ import { api, LONG_RUN_TIMEOUT_MS } 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, reportError, UsageError } from '../lib/errors.js';
+import { classifyError, reportError, UsageError, RefusalError } from '../lib/errors.js';
+import { confirmDestructive, isInteractive } from '../lib/confirm.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /**
@@ -66,12 +67,21 @@ function statusIcon(status) {
     return chalk.dim('—');
 }
 export const scraps = new Command('scraps').description('Manage scraps');
-// shared SSE streaming helper
-async function watchActivities(id) {
-    console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
+// shared SSE streaming helper. `asJson` (#107) emits one raw JSON object per
+// line (NDJSON) on stdout instead of the human-formatted timestamped text —
+// a streaming command still needs a pure-stdout machine mode, just line-
+// delimited instead of a single blob (there's no single "final" payload to
+// wait for).
+async function watchActivities(id, asJson) {
+    if (!asJson)
+        console.log(chalk.dim('Streaming activities (Ctrl+C to stop)…\n'));
     for await (const event of api.stream(`/api/scraps/${id}/activities/stream`)) {
         try {
             const activity = JSON.parse(event);
+            if (asJson) {
+                console.log(JSON.stringify(activity));
+                continue;
+            }
             const time = new Date(activity.createdAt).toLocaleTimeString();
             console.log(`${chalk.dim(`[${time}]`)} ${activity.message}`);
         }
@@ -121,6 +131,14 @@ const POLL_INTERVAL_MS = 2000;
 // Mirrors LONG_RUN_TIMEOUT_MS (#91 item 1) — the server-side worst case this
 // polls for is the same one that timeout was sized for.
 const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
+// #107 review F1 — a genuinely unreachable API must not run the watch
+// silently for the full 300s timeout with dead air; after this many
+// CONSECUTIVE (not cumulative — any successful poll resets the counter)
+// failed polls, treat it as a persistent error and surface it immediately
+// instead of waiting out the clock. At the default 2s interval this gives up
+// after ~10s of continuous failures — comfortably longer than any single
+// transient blip, nowhere near the 300s ceiling.
+const MAX_CONSECUTIVE_POLL_ERRORS = 5;
 /**
  * #91 P1 — replaces "await the run to completion, THEN open the activities
  * SSE stream" (which showed NOTHING: the activities SSE
@@ -182,10 +200,37 @@ const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
  * this function has, so it resolves to the same honest timeout rather than
  * risk reporting a possibly-wrong outcome (never a lie, at worst a timeout
  * telling the caller to check `doctor`).
+ *
+ * #107 review F1 — before this fix, `run|trigger --json --watch` was
+ * outcome-blind: `quiet` suppressed ALL output (including "Run finished:
+ * failure" and the timeout notice), a transient poll error was caught and
+ * silently retried FOREVER within the deadline, and the process always
+ * exited 0 after the poll loop regardless of what the watched run actually
+ * did — dead air, then a clean exit code, even for a failed or timed-out
+ * run. An agent scripting this CLI had no way to tell success from failure
+ * from "we gave up". Fixed by:
+ *  - emitting exactly ONE final NDJSON line on stdout under `--json` once
+ *    the watch reaches ANY of its three exits (terminal status, timeout, or
+ *    a persistent poll error) — `{runId,status}` (+`error` for a poll
+ *    error) — while every intermediate progress line stays suppressed
+ *    (unchanged from before);
+ *  - setting `process.exitCode` non-zero on a genuine run failure, a
+ *    timeout, or a persistent poll error, and `0` on a real success — in
+ *    BOTH `--json` and human `--watch` modes (human mode used to exit 0
+ *    unconditionally, the same bug, just silent instead of dishonest);
+ *  - giving up after `MAX_CONSECUTIVE_POLL_ERRORS` consecutive failed reads
+ *    instead of retrying the same dead endpoint for the full 300s.
  */
 export async function pollRunProgress(id, before, opts = {}) {
     const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
     const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
+    // #107 — `run --json --watch` / `trigger --json --watch` must keep stdout
+    // pure JSON: none of this function's intermediate progress text is safe to
+    // print once a caller asked for --json. `asJson` suppresses every
+    // intermediate console.log below (including the pinch celebration frame)
+    // while the polling/wait logic itself runs unchanged; the ONE exception is
+    // the single final outcome line emitted right before each return below.
+    const asJson = opts.json ?? false;
     let beforeId = before?.id;
     let beforeAlreadyInFlight = before?.alreadyInFlight ?? false;
     // #97 — only an EXPLICIT captured:false (capture's GET actually threw)
@@ -193,10 +238,13 @@ export async function pollRunProgress(id, before, opts = {}) {
     // capture entirely) or `captured` being true/absent both mean "trust
     // beforeId as given", preserving every existing call site's behavior.
     let baselineEstablished = before?.captured ?? true;
-    console.log(chalk.dim('Live activity streaming has no signal for this run (async/cross-pod) — polling for progress instead…\n'));
+    if (!asJson) {
+        console.log(chalk.dim('Live activity streaming has no signal for this run (async/cross-pod) — polling for progress instead…\n'));
+    }
     const deadline = Date.now() + timeoutMs;
     const seen = new Set();
     let first = true;
+    let consecutivePollErrors = 0;
     while (Date.now() < deadline) {
         if (!first)
             await sleep(intervalMs);
@@ -204,9 +252,28 @@ export async function pollRunProgress(id, before, opts = {}) {
         let scrap;
         try {
             scrap = await api.get(`/api/scraps/${id}`);
+            consecutivePollErrors = 0;
         }
-        catch {
-            continue; // transient — keep polling rather than aborting the wait
+        catch (err) {
+            consecutivePollErrors++;
+            // #107 review F1 — a single failed read is still a TRANSIENT blip,
+            // safe to retry within the deadline (unchanged). Only once reads fail
+            // this many times IN A ROW is the API treated as genuinely
+            // unreachable — surface that honestly instead of quietly burning the
+            // full 300s timeout on a dead endpoint.
+            if (consecutivePollErrors >= MAX_CONSECUTIVE_POLL_ERRORS) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (asJson) {
+                    const outcome = { runId: beforeId, status: 'poll_error', error: message };
+                    console.log(JSON.stringify(outcome));
+                }
+                else {
+                    console.log(chalk.red(`✗ Polling failed repeatedly (${message}) — check status with: trawl scraps doctor ${id}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
+            continue;
         }
         const last = scrap.history?.[0];
         if (!last?._id)
@@ -233,6 +300,8 @@ export async function pollRunProgress(id, before, opts = {}) {
                 if (seen.has(key))
                     continue;
                 seen.add(key);
+                if (asJson)
+                    continue;
                 const time = new Date(a.createdAt).toLocaleTimeString();
                 console.log(`${chalk.dim(`[${time}]`)} ${a.message}`);
             }
@@ -242,141 +311,170 @@ export async function pollRunProgress(id, before, opts = {}) {
         }
         if (last.status !== null) {
             const outcome = last.statusDetail ?? (last.status ? 'success' : 'failure');
-            console.log(chalk.dim(`Run finished: ${outcome}`));
-            // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
-            // `status === true` success definition (regardless of statusDetail),
-            // never for a failed/regression run. Neither `run --watch` nor
-            // `trigger --watch` (the only two callers) has a --json flag, so this
-            // is always safe to print. Guarded by pinchEnabled() (NO_COLOR/non-TTY).
-            if (last.status === true && pinchEnabled()) {
-                console.log(renderPinch('celebrating'));
+            // #107 review F1 — the exit code, in BOTH modes: a regression row's
+            // WRITE actually succeeded (see lastStatus()'s own #91 comment above,
+            // and `scraps data`'s isRegression branch) and an 'empty' row is a
+            // genuine zero-item success — neither is a real failure. Only
+            // status:false with neither of those details (e.g. 'error', or no
+            // detail at all) is a genuine failed run.
+            const isGenuineFailure = last.status === false && outcome !== 'empty' && outcome !== 'regression';
+            if (asJson) {
+                const payload = { runId: last._id, status: outcome };
+                console.log(JSON.stringify(payload));
+            }
+            else {
+                console.log(chalk.dim(`Run finished: ${outcome}`));
+                // Pinch celebrates a clean run finish (#94) — mirrors doctor.ts's own
+                // `status === true` success definition (regardless of statusDetail),
+                // never for a failed/regression run. Guarded by pinchEnabled()
+                // (NO_COLOR/non-TTY) and never under --json (stdout must stay pure).
+                if (last.status === true && pinchEnabled()) {
+                    console.log(renderPinch('celebrating'));
+                }
             }
+            process.exitCode = isGenuineFailure ? 1 : 0;
             return;
         }
     }
-    console.log(chalk.yellow(`⚠ Timed out waiting for the run to finish — check status with: trawl scraps doctor ${id}`));
-}
-// list
-scraps
-    .command('list')
-    .alias('ls')
-    .description('List all scraps')
-    .option('--json', 'Output as JSON')
-    .option('--status <status>', 'Filter by last run status (success|failure|never|running|regression)')
-    // #88 item 8 — no custom parser here (unlike the old `(v) => parseInt(v,
-    // 10)`): a bad value like "abc" used to silently become NaN, which then
-    // sailed straight through `Number.isInteger`-less checks and into
-    // `.slice(0, NaN)` (silently truncates to 0 rows) or `?page=NaN` (silently
-    // sent to the server) — never a usage error. Keeping the raw string here
-    // lets the validation below mirror `history`'s own --limit check exactly
-    // (~line 660) and report the actual bad input in the error message.
-    .option('--limit <n>', 'Show only the first N results')
-    .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
-    .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;
+    // #107 review F1 — timeout: honest non-zero exit in both modes, plus the
+    // machine-readable final line under --json (never silently exit 0 after a
+    // watch that never actually confirmed what happened).
+    if (asJson) {
+        const outcome = { runId: beforeId, status: 'timeout' };
+        console.log(JSON.stringify(outcome));
     }
-    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;
-        }
+    else {
+        console.log(chalk.yellow(`⚠ Timed out waiting for the run to finish — check status with: trawl scraps doctor ${id}`));
     }
-    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 });
+    process.exitCode = 1;
+}
+// list — promoted to a top-level verb (#108, see the AttachOptions comment above)
+export function attachListCommand(parent, attachOpts = {}) {
+    return parent
+        .command('list', attachOpts)
+        .alias('ls')
+        .description('List all scraps')
+        .option('--json', 'Output as JSON')
+        .option('--status <status>', 'Filter by last run status (success|failure|never|running|regression)')
+        // #88 item 8 — no custom parser here (unlike the old `(v) => parseInt(v,
+        // 10)`): a bad value like "abc" used to silently become NaN, which then
+        // sailed straight through `Number.isInteger`-less checks and into
+        // `.slice(0, NaN)` (silently truncates to 0 rows) or `?page=NaN` (silently
+        // sent to the server) — never a usage error. Keeping the raw string here
+        // lets the validation below mirror `history`'s own --limit check exactly
+        // (~line 660) and report the actual bad input in the error message.
+        .option('--limit <n>', 'Show only the first N results')
+        .option('--page <n>', 'Fetch a specific page only (50 per page, no auto-pagination)')
+        .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 data;
-    try {
-        data = await oraPromise(async () => {
-            if (page !== undefined) {
-                // Single-page mode: explicit page requested, no loop
-                return api.get(`/api/scraps?perPage=50&page=${page}`);
+        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;
             }
-            // Fetch-all mode: paginate until a page returns < 200 items
-            const perPage = 200;
-            let result = [];
-            let pageNum = 1;
-            while (true) {
-                const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${pageNum}`);
-                result = result.concat(batch);
-                if (batch.length < perPage)
-                    break;
-                pageNum++;
+        }
+        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;
             }
-            return result;
-        }, 'Fetching scraps…');
-    }
-    catch (err) {
-        // Spinner already failed by oraPromise — report with the scrap-specific
-        // prefix kept, but route through the shared classifier so exit code +
-        // --json envelope stay consistent with every other command. (#71)
-        //
-        // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
-        // which the shared reportError() can't add) used to silently swallow
-        // --debug: unlike the central index.ts catch, it never printed the raw
-        // stack trace. optsWithGlobals() reads --debug off the ROOT command
-        // (this leaf has no --debug of its own) so it can honor the flag
-        // locally instead. (#86 finding 9)
-        const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
-        const { exitCode, envelope } = classifyError(err);
-        const message = `Failed to fetch scraps: ${envelope.message}`;
-        if (isDebug)
-            console.error(err);
-        if (opts.json) {
-            console.log(JSON.stringify({ error: { ...envelope, message } }));
         }
-        else if (!isDebug) {
-            console.error(chalk.red(`✗ ${message}`));
+        let data;
+        try {
+            data = await oraPromise(async () => {
+                if (page !== undefined) {
+                    // Single-page mode: explicit page requested, no loop
+                    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 pageNum = 1;
+                while (true) {
+                    const batch = await api.get(`/api/scraps?perPage=${perPage}&page=${pageNum}`);
+                    result = result.concat(batch);
+                    if (batch.length < perPage)
+                        break;
+                    pageNum++;
+                }
+                return result;
+            }, 'Fetching scraps…');
         }
-        process.exitCode = exitCode;
-        return;
-    }
-    if (opts.status)
-        data = data.filter((s) => lastStatus(s) === opts.status);
-    const totalMatched = data.length;
-    const rows = limit !== undefined ? data.slice(0, limit) : data;
-    if (opts.json)
-        return json(rows);
-    const tableRows = rows.map((s) => ({
-        id: s._id,
-        title: s.title || '(untitled)',
-        cron: s.cron || '—',
-        status: statusIcon(lastStatus(s)),
-        'last run': lastRun(s),
-        updated: new Date(s.updatedAt).toLocaleDateString(),
-    }));
-    table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
-    // Print footer when --limit truncates
-    if (limit !== undefined && rows.length < totalMatched) {
-        console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
-    }
-});
-// get
-scraps
-    .command('get <id>')
-    .description('Get scrap details')
-    .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    const data = await api.get(`/api/scraps/${id}`);
-    if (opts.json)
-        return json(data);
-    console.log(chalk.bold(data.title || '(untitled)'));
-    console.log(chalk.dim(`  ID:       `) + data._id);
-    console.log(chalk.dim(`  Cron:     `) + (data.cron || '—'));
-    console.log(chalk.dim(`  Status:   `) + statusIcon(lastStatus(data)));
-    console.log(chalk.dim(`  Last run: `) + lastRun(data));
-    console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
-});
+        catch (err) {
+            // Spinner already failed by oraPromise — report with the scrap-specific
+            // prefix kept, but route through the shared classifier so exit code +
+            // --json envelope stay consistent with every other command. (#71)
+            //
+            // This bespoke catch (kept for the "Failed to fetch scraps:" prefix,
+            // which the shared reportError() can't add) used to silently swallow
+            // --debug: unlike the central index.ts catch, it never printed the raw
+            // stack trace. optsWithGlobals() reads --debug off the ROOT command
+            // (this leaf has no --debug of its own) so it can honor the flag
+            // locally instead. (#86 finding 9)
+            const isDebug = Boolean(cmd.optsWithGlobals().debug || process.env['DEBUG']);
+            const { exitCode, envelope } = classifyError(err);
+            const message = `Failed to fetch scraps: ${envelope.message}`;
+            if (isDebug)
+                console.error(err);
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { ...envelope, message } }));
+            }
+            else if (!isDebug) {
+                console.error(chalk.red(`✗ ${message}`));
+            }
+            process.exitCode = exitCode;
+            return;
+        }
+        if (opts.status)
+            data = data.filter((s) => lastStatus(s) === opts.status);
+        const totalMatched = data.length;
+        const rows = limit !== undefined ? data.slice(0, limit) : data;
+        if (opts.json)
+            return json(rows);
+        const tableRows = rows.map((s) => ({
+            id: s._id,
+            title: s.title || '(untitled)',
+            cron: s.cron || '—',
+            status: statusIcon(lastStatus(s)),
+            'last run': lastRun(s),
+            updated: new Date(s.updatedAt).toLocaleDateString(),
+        }));
+        table(tableRows, ['id', 'title', 'cron', 'status', 'last run', 'updated']);
+        // Print footer when --limit truncates
+        if (limit !== undefined && rows.length < totalMatched) {
+            console.log(chalk.dim(`Showing ${rows.length} of ${totalMatched} — omit --limit to see all`));
+        }
+    });
+}
+attachListCommand(scraps, { hidden: true });
+// get — promoted to a top-level verb (#108)
+export function attachGetCommand(parent, attachOpts = {}) {
+    return parent
+        .command('get <id>', attachOpts)
+        .description('Get scrap details')
+        .option('--json', 'Output as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        const data = await api.get(`/api/scraps/${id}`);
+        if (opts.json)
+            return json(data);
+        console.log(chalk.bold(data.title || '(untitled)'));
+        console.log(chalk.dim(`  ID:       `) + data._id);
+        console.log(chalk.dim(`  Cron:     `) + (data.cron || '—'));
+        console.log(chalk.dim(`  Status:   `) + statusIcon(lastStatus(data)));
+        console.log(chalk.dim(`  Last run: `) + lastRun(data));
+        console.log(chalk.dim(`  Updated:  `) + new Date(data.updatedAt).toLocaleString());
+    });
+}
+attachGetCommand(scraps, { hidden: true });
 const VALID_TIERS = ['tier0', 'tier1', 'tier2', 'tier3', 'tier4'];
 /**
  * #86 findings 4/5 — shared honest-tier renderer for `create --tier` and
@@ -420,7 +518,7 @@ function renderTierOverrideHuman(data) {
 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}`));
+    console.error(chalk.yellow(`  ⚠ Server did not confirm the tier change (older server) — verify with: trawl get ${id}`));
 }
 /**
  * #88 item 3 — the --json machine-readable counterpart to
@@ -441,11 +539,17 @@ function withTierUnconfirmed(data, tierWasRequested) {
 }
 /** #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). */
+ * everywhere else (exit 1: a business-logic refusal, not a usage error).
+ *
+ * #107 review F3 — uses `RefusalError` (kind:"refused"), not a bare `Error`
+ * (which fell through classifyError's default `kind:"unknown"` bucket,
+ * indistinguishable from a generic crash even though the README sells `kind`
+ * as the machine discriminant an agent branches on).
+ */
 function reportTierRefusal(data, wantsJson) {
     const ov = data._tierOverride;
     const message = `Tier ceiling override refused: ${ov?.reason ?? 'unknown'} (requested ${ov?.requestedMaxTier ?? '—'}; kept the registry cap)`;
-    return reportError(new Error(message), { json: wantsJson });
+    return reportError(new RefusalError(message), { json: wantsJson });
 }
 // create
 scraps
@@ -611,27 +715,41 @@ scraps
     if (refused)
         process.exitCode = 1;
 });
-// run
-scraps
-    .command('run <id>')
-    .description('Run a scrap')
-    .option('-w, --watch', 'Show progress after launching (polls — see `trawl scraps trigger --watch`, #91)')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
-    // tell "the run that's about to finish" apart from whatever the last run
-    // happened to be (including a dedup onto an already-in-flight run).
-    const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-    // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
-    // server-side (30-250s); the 30s default was aborting it mid-flight.
-    await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
-        text: 'Launching scrap…',
-        successText: 'Scrap launched',
+// run — promoted to a top-level verb (#108)
+export function attachRunCommand(parent, attachOpts = {}) {
+    return parent
+        .command('run <id>', attachOpts)
+        .description('Run a scrap')
+        .option('-w, --watch', 'Show progress after launching (polls — see `trawl trigger --watch`, #91)')
+        .option('--json', 'Output the raw launch payload as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // #91 P1 / #93 item 1 — captured BEFORE launching so pollRunProgress can
+        // tell "the run that's about to finish" apart from whatever the last run
+        // happened to be (including a dedup onto an already-in-flight run).
+        const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
+        // #91 P0 — GET /api/scraps/load/:id runs the scrap synchronously
+        // server-side (30-250s); the 30s default was aborting it mid-flight.
+        const call = () => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS });
+        // #107 — under --json the stdout path stays pure: no spinner channel at
+        // all, mirroring `trawl fetch`'s own --json handling.
+        const data = opts.json
+            ? await call()
+            : await oraPromise(call, { text: 'Launching scrap…', successText: 'Scrap launched' });
+        if (opts.json)
+            json(data);
+        if (opts.watch) {
+            // #107 — under --json, pollRunProgress suppresses its own intermediate
+            // console.log calls and instead emits exactly ONE final NDJSON outcome
+            // line (+ sets process.exitCode honestly) once the watch reaches a
+            // terminal status, a timeout, or a persistent poll error (review F1) —
+            // `run --json --watch` never again exits 0 after dead air regardless
+            // of what the watched run actually did.
+            await pollRunProgress(id, beforeRun, { json: opts.json });
+        }
     });
-    if (opts.watch) {
-        await pollRunProgress(id, beforeRun);
-    }
-});
+}
+attachRunCommand(scraps, { hidden: true });
 // #70 — render an items array either as a table summary or --json. Shared by
 // both the default (persisted read) and --fresh (live execute) paths of `data`.
 function renderScrapItems(items, asJson) {
@@ -665,266 +783,287 @@ function reportDataState(message, exitCode, kind, wantsJson) {
     }
     process.exitCode = exitCode;
 }
-// data
-scraps
-    .command('data <id>')
-    .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
-    .option('--json', 'Output as JSON')
-    .option('--errors', 'Show failure diagnostics when the last run failed')
-    .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `scraps run`)')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
-    // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
-    if (opts.errors) {
-        const result = await fetchRunAndFix(id);
-        if (!result) {
-            // #88 item 7 — unified no-runs shape with `doctor --json`: a bare
-            // `null` was indistinguishable from any other absent-payload state
-            // (a scrap CAN legitimately have a null-ish result elsewhere); an
-            // explicit `{status:"no_runs"}` object is unambiguous everywhere.
-            if (opts.json) {
-                json({ status: 'no_runs' });
+// data — promoted to a top-level verb (#108)
+export function attachDataCommand(parent, attachOpts = {}) {
+    return parent
+        .command('data <id>', attachOpts)
+        .description('Get scrap data (last persisted run — read-only, no quota). Use --fresh to launch a new run instead.')
+        .option('--json', 'Output as JSON')
+        .option('--errors', 'Show failure diagnostics when the last run failed')
+        .option('--fresh', 'Launch a fresh run instead of reading the last persisted payload (consumes execute quota, same as `run`)')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // --errors: fetch full run + fix detail via fetchRunAndFix (DRY with doctor).
+        // Read-only: GET /api/scraps/:id + GET /api/historys/:hid, no quota, no run lock.
+        if (opts.errors) {
+            const result = await fetchRunAndFix(id);
+            if (!result) {
+                // #88 item 7 — unified no-runs shape with `doctor --json`: a bare
+                // `null` was indistinguishable from any other absent-payload state
+                // (a scrap CAN legitimately have a null-ish result elsewhere); an
+                // explicit `{status:"no_runs"}` object is unambiguous everywhere.
+                if (opts.json) {
+                    json({ status: 'no_runs' });
+                    return;
+                }
+                console.log(chalk.dim('No runs yet.'));
                 return;
             }
-            console.log(chalk.dim('No runs yet.'));
+            // --json is honored for BOTH outcomes (success or failure) — an agent
+            // parsing `data --errors --json` must always get the flat run object,
+            // never prose gated behind a status check. (#71 finding 13)
+            if (opts.json)
+                return json(pickRun(result.run));
+            if (result.run.status === true) {
+                console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
+                return;
+            }
+            console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
             return;
         }
-        // --json is honored for BOTH outcomes (success or failure) — an agent
-        // parsing `data --errors --json` must always get the flat run object,
-        // never prose gated behind a status check. (#71 finding 13)
-        if (opts.json)
-            return json(pickRun(result.run));
-        if (result.run.status === true) {
-            console.log(chalk.green('✓ Last run succeeded. No errors to show.'));
+        // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
+        // default path used to do silently: GET /api/scraps/load/:id executes a
+        // fresh scrap run server-side (requireQuota('scraps','execute') + a
+        // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
+        // burning execute quota and 429ing if a run is already in flight. A user
+        // or agent "just reading data" must never trigger that by accident.
+        if (opts.fresh) {
+            // #91 P0 — same long-run endpoint as `run` (30-250s server-side);
+            // the 30s default was aborting it mid-flight.
+            const loaded = await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
+                text: 'Launching a fresh scrap run (consumes execute quota)…',
+                successText: 'Fresh run complete',
+            });
+            const items = loaded?.result?.data;
+            if (!Array.isArray(items)) {
+                // --json always returns an array from `data` — [] is the honest
+                // "no items" signal instead of prose breaking JSON parsing. (#71)
+                if (opts.json) {
+                    json([]);
+                    return;
+                }
+                console.log(chalk.dim('No data yet. Run the scrap first.'));
+                return;
+            }
+            // #93 item 2 — --fresh used to render items without ever checking for a
+            // regression, unlike the persisted `data` path below (#88 item 2). The
+            // load() response's OWN embedded `scrap.history[0]` can't be trusted for
+            // this (see the ScrapLoadResult comment above): it may be the previous
+            // run's row, and even the right row never carries the regression flip.
+            // `--fresh` runs synchronously to completion server-side though — by the
+            // time this call returns, node has already awaited the regression patch
+            // — so a fresh GET /api/scraps/:id (the SAME read the persisted path
+            // below already trusts) reliably observes the finalized DB state.
+            // Best-effort: never fail --fresh's real output over this side check,
+            // and never gate on it — the items returned ARE this run's real,
+            // synchronously-computed data regardless of what this check finds.
+            try {
+                const fresh = await api.get(`/api/scraps/${id}`);
+                if (fresh.history?.[0]?.statusDetail === 'regression') {
+                    console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
+                }
+            }
+            catch {
+                // best-effort — the fresh run's items are still valid without this check
+            }
+            renderScrapItems(items, opts.json);
             return;
         }
-        console.log(formatDoctor(result.scrap.title, result.run, result.fix, id));
-        return;
-    }
-    // #70 — --fresh is the explicit opt-in for a LIVE run. This is what the
-    // default path used to do silently: GET /api/scraps/load/:id executes a
-    // fresh scrap run server-side (requireQuota('scraps','execute') + a
-    // distributed run lock — trawl_node modules/scraps/routes/scraps.routes.js),
-    // burning execute quota and 429ing if a run is already in flight. A user
-    // or agent "just reading data" must never trigger that by accident.
-    if (opts.fresh) {
-        // #91 P0 — same long-run endpoint as `scraps run` (30-250s server-side);
-        // the 30s default was aborting it mid-flight.
-        const loaded = await oraPromise(() => api.get(`/api/scraps/load/${id}`, { timeoutMs: LONG_RUN_TIMEOUT_MS }), {
-            text: 'Launching a fresh scrap run (consumes execute quota)…',
-            successText: 'Fresh run complete',
-        });
-        const items = loaded?.result?.data;
+        // Default: read the last PERSISTED run payload — no quota, no run lock.
+        // History.data (trawl_node modules/historys/services/historys.service.js
+        // `update()`) is a JSON-stringified clone of the worker result, so it
+        // carries the same `.data` items array the live load endpoint returns —
+        // it's just pulled from the most recent history row instead of a fresh
+        // run. Retention keeps this only for the newest row per (scrap, status)
+        // bucket (config.trawl.keepData, default 1); older rows null it out.
+        //
+        // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
+        // Every other outcome below is an honest error envelope instead: never
+        // run (not_found/4), last run failed (1), or the payload aged out of
+        // retention (not_found/4) all used to collapse into the same silent [].
+        const scrap = await api.get(`/api/scraps/${id}`);
+        const last = scrap.history?.[0];
+        if (!last?._id) {
+            reportDataState(`Scrap ${id} has never run. Run it first (trawl run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
+            return;
+        }
+        // #88 item 1 — status:null is an IN-FLIGHT run (node persists
+        // {status:null, statusDetail:null, inFlight:true} the moment a run
+        // starts, and only flips status/statusDetail once it finishes). That is
+        // neither "never run" nor "the last run failed" — a caller reading data
+        // mid-run needs an honest "wait" signal. Never suggest --fresh here: a
+        // run already holds the server-side distributed lock, so --fresh would
+        // just 429 against it.
+        if (last.status === null) {
+            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 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 {
+                items = JSON.parse(detail.data)?.data;
+            }
+            catch {
+                items = undefined;
+            }
+        }
         if (!Array.isArray(items)) {
-            // --json always returns an array from `data` — [] is the honest
-            // "no items" signal instead of prose breaking JSON parsing. (#71)
-            if (opts.json) {
-                json([]);
+            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 data yet. Run the scrap first.'));
+            // #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;
         }
-        // #93 item 2 — --fresh used to render items without ever checking for a
-        // regression, unlike the persisted `data` path below (#88 item 2). The
-        // load() response's OWN embedded `scrap.history[0]` can't be trusted for
-        // this (see the ScrapLoadResult comment above): it may be the previous
-        // run's row, and even the right row never carries the regression flip.
-        // `--fresh` runs synchronously to completion server-side though — by the
-        // time this call returns, node has already awaited the regression patch
-        // — so a fresh GET /api/scraps/:id (the SAME read the persisted path
-        // below already trusts) reliably observes the finalized DB state.
-        // Best-effort: never fail --fresh's real output over this side check,
-        // and never gate on it — the items returned ARE this run's real,
-        // synchronously-computed data regardless of what this check finds.
-        try {
-            const fresh = await api.get(`/api/scraps/${id}`);
-            if (fresh.history?.[0]?.statusDetail === 'regression') {
-                console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
-            }
-        }
-        catch {
-            // best-effort — the fresh run's items are still valid without this check
+        // #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);
-        return;
-    }
-    // Default: read the last PERSISTED run payload — no quota, no run lock.
-    // History.data (trawl_node modules/historys/services/historys.service.js
-    // `update()`) is a JSON-stringified clone of the worker result, so it
-    // carries the same `.data` items array the live load endpoint returns —
-    // it's just pulled from the most recent history row instead of a fresh
-    // run. Retention keeps this only for the newest row per (scrap, status)
-    // bucket (config.trawl.keepData, default 1); older rows null it out.
-    //
-    // #86 finding 6 — [] is reserved for a GENUINE zero-item successful run.
-    // Every other outcome below is an honest error envelope instead: never
-    // run (not_found/4), last run failed (1), or the payload aged out of
-    // retention (not_found/4) all used to collapse into the same silent [].
-    const scrap = await api.get(`/api/scraps/${id}`);
-    const last = scrap.history?.[0];
-    if (!last?._id) {
-        reportDataState(`Scrap ${id} has never run. Run it first (trawl scraps run ${id}) or pass --fresh to launch one now.`, 4, 'not_found', opts.json);
-        return;
-    }
-    // #88 item 1 — status:null is an IN-FLIGHT run (node persists
-    // {status:null, statusDetail:null, inFlight:true} the moment a run
-    // starts, and only flips status/statusDetail once it finishes). That is
-    // neither "never run" nor "the last run failed" — a caller reading data
-    // mid-run needs an honest "wait" signal. Never suggest --fresh here: a
-    // run already holds the server-side distributed lock, so --fresh would
-    // just 429 against it.
-    if (last.status === null) {
-        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 {
-            items = JSON.parse(detail.data)?.data;
+    });
+}
+attachDataCommand(scraps, { hidden: true });
+// history — list past runs for a scrap — promoted to a top-level verb (#108)
+export function attachHistoryCommand(parent, attachOpts = {}) {
+    return parent
+        .command('history <id>', attachOpts)
+        .description('List past runs for a scrap (newest first)')
+        .option('--json', 'Output as JSON')
+        .option('-n, --limit <n>', 'Max runs to show', '20')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        const limit = Number(opts.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+            usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+            return;
         }
-        catch {
-            items = undefined;
+        const scrap = await api.get(`/api/scraps/${id}`);
+        const runs = (scrap.history ?? []).slice(0, limit).map((h) => ({
+            hid: h._id,
+            status: h.statusDetail ?? null,
+            time: h.time ?? null,
+            tier: h.proxyTier ?? null,
+            failureKind: h.failureKind ?? null,
+            blockType: h.blockType ?? null,
+            createdAt: h.createdAt ?? null,
+        }));
+        if (opts.json) {
+            json(runs);
+            return;
         }
-    }
-    if (!Array.isArray(items)) {
-        if (isEmptyRun) {
-            // A genuine zero-item run whose payload is '[]' or absent — both are
-            // the SAME honest answer: no items, exit 0. Never the retention
-            // message (nothing aged out; there was nothing to persist).
-            renderScrapItems([], opts.json);
+        table(runs, ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'createdAt']);
+    });
+}
+attachHistoryCommand(scraps, { hidden: true });
+// run-info — single-run detail by history id — promoted to a top-level verb (#108)
+export function attachRunInfoCommand(parent, attachOpts = {}) {
+    return parent
+        .command('run-info <hid>', attachOpts)
+        .description('Show details of a single run (status, tier, failureKind, error)')
+        .option('--json', 'Output as JSON')
+        .action(async (hid, opts) => {
+        validateObjectId(hid);
+        const h = await api.get(`/api/historys/${hid}`);
+        const info = {
+            hid,
+            status: h.statusDetail ?? null,
+            time: h.time ?? null,
+            tier: h.proxyTier ?? null,
+            failureKind: h.failureKind ?? null,
+            blockType: h.blockType ?? null,
+            errorMessage: h.errorSnapshot?.errorMessage ?? null,
+            selector: h.errorSnapshot?.selector ?? null,
+            emptyContext: h.errorSnapshot?.emptyContext ?? null,
+            createdAt: h.createdAt ?? null,
+        };
+        if (opts.json) {
+            json(info);
             return;
         }
-        // #88 item 2 — a regression row whose payload aged out of retention has
-        // nothing left to show either; fall through to the SAME honest
-        // aged-out envelope a normal successful row would get (never fabricate
-        // items, never silently succeed).
-        reportDataState(`No persisted data for the last run of ${id} — it aged out of retention. Pass --fresh to launch a new run.`, 4, 'not_found', opts.json);
-        return;
-    }
-    // #88 item 2 — a regression row's items are REAL (the write succeeded
-    // before the async patch flagged the drop) — return them on stdout
-    // (exit 0, both modes) with an honest stderr warning pointing at the
-    // diagnostic command, instead of hiding genuine data behind run_failed.
-    if (isRegression) {
-        console.error(chalk.yellow(`⚠ Item count regressed vs baseline for the last run of ${id} — see: trawl scraps doctor ${id}`));
-    }
-    renderScrapItems(items, opts.json);
-});
-// history — list past runs for a scrap
+        table([info], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
+    });
+}
+attachRunInfoCommand(scraps, { hidden: true });
+// delete
 scraps
-    .command('history <id>')
-    .description('List past runs for a scrap (newest first)')
+    .command('delete <id>')
+    .alias('rm')
+    .description('Delete a scrap')
+    .option('-f, --force', 'Skip confirmation prompt')
     .option('--json', 'Output as JSON')
-    .option('-n, --limit <n>', 'Max runs to show', '20')
     .action(async (id, opts) => {
     validateObjectId(id);
-    const limit = Number(opts.limit);
-    if (!Number.isInteger(limit) || limit < 1) {
-        usageError(`Invalid --limit "${opts.limit}" (expected a positive integer)`, { json: opts.json });
+    // #107 — never blocks on a y/N under --json or a non-TTY invocation
+    // (agent/CI subprocess); -f/--force always pre-confirms.
+    //
+    // #107 review F2 — `message` (the plain-id form) feeds the refusal
+    // UsageError, which can land verbatim in the `--json` error envelope;
+    // `chalk.bold(id)` is passed ONLY as `promptMessage`, shown solely on
+    // the interactive TTY `[y/N]` prompt. Before this split, the styled
+    // string was the ONLY message confirmDestructive had, so a non-TTY/
+    // --json refusal on `scraps delete X --json` emitted raw ANSI escape
+    // bytes inside the JSON string.
+    const { proceed, blocked } = await confirmDestructive(`Delete scrap ${id}?`, {
+        force: opts.force,
+        json: opts.json,
+        promptMessage: `Delete scrap ${chalk.bold(id)}?`,
+    });
+    if (blocked)
         return;
-    }
-    const scrap = await api.get(`/api/scraps/${id}`);
-    const runs = (scrap.history ?? []).slice(0, limit).map((h) => ({
-        hid: h._id,
-        status: h.statusDetail ?? null,
-        time: h.time ?? null,
-        tier: h.proxyTier ?? null,
-        failureKind: h.failureKind ?? null,
-        blockType: h.blockType ?? null,
-        createdAt: h.createdAt ?? null,
-    }));
-    if (opts.json) {
-        json(runs);
+    if (!proceed) {
+        console.log(chalk.dim('Aborted.'));
         return;
     }
-    table(runs, ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'createdAt']);
-});
-// run-info — single-run detail by history id
-scraps
-    .command('run-info <hid>')
-    .description('Show details of a single run (status, tier, failureKind, error)')
-    .option('--json', 'Output as JSON')
-    .action(async (hid, opts) => {
-    validateObjectId(hid);
-    const h = await api.get(`/api/historys/${hid}`);
-    const info = {
-        hid,
-        status: h.statusDetail ?? null,
-        time: h.time ?? null,
-        tier: h.proxyTier ?? null,
-        failureKind: h.failureKind ?? null,
-        blockType: h.blockType ?? null,
-        errorMessage: h.errorSnapshot?.errorMessage ?? null,
-        selector: h.errorSnapshot?.selector ?? null,
-        emptyContext: h.errorSnapshot?.emptyContext ?? null,
-        createdAt: h.createdAt ?? null,
-    };
+    const call = () => api.delete(`/api/scraps/${id}`);
     if (opts.json) {
-        json(info);
+        await call();
+        json({ deleted: true, id });
         return;
     }
-    table([info], ['hid', 'status', 'time', 'tier', 'failureKind', 'blockType', 'errorMessage', 'selector', 'emptyContext', 'createdAt']);
-});
-// delete
-scraps
-    .command('delete <id>')
-    .alias('rm')
-    .description('Delete a scrap')
-    .option('-f, --force', 'Skip confirmation prompt')
-    .action(async (id, opts) => {
-    validateObjectId(id);
-    if (!opts.force) {
-        const { createInterface } = await import('readline');
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        let answer;
-        try {
-            answer = await new Promise((resolve) => {
-                rl.question(`Delete scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
-            });
-        }
-        finally {
-            rl.close();
-        }
-        if (answer !== 'y' && answer !== 'yes') {
-            console.log(chalk.dim('Aborted.'));
-            return;
-        }
-    }
-    await oraPromise(() => api.delete(`/api/scraps/${id}`), { text: 'Deleting…', successText: 'Scrap deleted' });
+    await oraPromise(call, { text: 'Deleting…', successText: 'Scrap deleted' });
 });
 // banner
 scraps
     .command('banner <id>')
     .description('Upload a banner image for a scrap')
     .requiredOption('-f, --file <path>', 'Path to image file (jpg, png, webp)')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     const { readFileSync, existsSync } = await import('fs');
     const { basename } = await import('path');
     if (!existsSync(opts.file)) {
-        usageError(`File not found: ${opts.file}`);
+        usageError(`File not found: ${opts.file}`, { json: opts.json });
         return;
     }
     const filename = basename(opts.file);
@@ -940,14 +1079,20 @@ scraps
     // Content-Type — a lie about the actual file's format). Refuse instead.
     const mimeType = mimeMap[ext];
     if (!mimeType) {
-        usageError(`Unsupported image type "${ext ? `.${ext}` : filename}" — use png, jpg, or webp.`);
+        usageError(`Unsupported image type "${ext ? `.${ext}` : filename}" — use png, jpg, or webp.`, { json: opts.json });
         return;
     }
     const fileBuffer = readFileSync(opts.file);
     const blob = new Blob([fileBuffer], { type: mimeType });
     const formData = new FormData();
     formData.append('banner', blob, filename);
-    await oraPromise(() => api.upload(`/api/scraps/${id}/banner`, formData), {
+    const call = () => api.upload(`/api/scraps/${id}/banner`, formData);
+    if (opts.json) {
+        const data = await call();
+        json(data);
+        return;
+    }
+    await oraPromise(call, {
         text: 'Uploading banner…',
         successText: `Banner uploaded for scrap ${chalk.bold(id)}`,
     });
@@ -956,40 +1101,54 @@ scraps
 scraps
     .command('watch <id>')
     .description('Stream scrap activities in real-time')
-    .action(async (id) => {
-    validateObjectId(id);
-    await watchActivities(id);
-});
-// trigger
-scraps
-    .command('trigger <id>')
-    .description('Launch a scrap as a background worker (returns immediately)')
-    .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
-    .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
+    .option('--json', 'Output each activity as a JSON line (NDJSON) instead of formatted text')
     .action(async (id, opts) => {
     validateObjectId(id);
-    // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
-    // tell "the run we just triggered" apart from whatever the last run
-    // happened to be. This is the dedup-prone path: `trigger`'s method:'worker'
-    // collapses onto an already-pending/running worker job for the same scrap
-    // (ScrapJobsService, LIVE_STATUSES) instead of creating a new history row —
-    // captureBeforeRunState records that so pollRunProgress can still track it.
-    const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
-    // #50 — default async: the backend (#1313) kicks off the run and returns a
-    // 'queued' envelope immediately instead of holding the connection for the
-    // whole run. --wait restores the old synchronous round-trip.
-    const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
-    // #91 P0 — the synchronous --wait branch runs the scrap server-side
-    // (30-250s), same as `scraps run`; the 30s default was aborting it
-    // mid-flight. The async (default) POST returns almost immediately, so it
-    // keeps the 30s default.
-    await oraPromise(() => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path)), {
-        text: opts.wait ? 'Running worker…' : 'Triggering worker…',
-        successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
-    });
-    if (opts.watch)
-        await pollRunProgress(id, beforeRun);
+    await watchActivities(id, opts.json);
 });
+// trigger — promoted to a top-level verb (#108)
+export function attachTriggerCommand(parent, attachOpts = {}) {
+    return parent
+        .command('trigger <id>', attachOpts)
+        .description('Launch a scrap as a background worker (returns immediately)')
+        .option('-w, --watch', 'Poll for progress after triggering (#91 — the default async run happens in a separate cron pod; activities SSE never reaches it)')
+        .option('--wait', 'Run synchronously and wait for the result (legacy behaviour)')
+        .option('--json', 'Output the raw trigger payload as JSON')
+        .action(async (id, opts) => {
+        validateObjectId(id);
+        // #91 P1 / #93 item 1 — captured BEFORE triggering so pollRunProgress can
+        // tell "the run we just triggered" apart from whatever the last run
+        // happened to be. This is the dedup-prone path: `trigger`'s method:'worker'
+        // collapses onto an already-pending/running worker job for the same scrap
+        // (ScrapJobsService, LIVE_STATUSES) instead of creating a new history row —
+        // captureBeforeRunState records that so pollRunProgress can still track it.
+        const beforeRun = opts.watch ? await captureBeforeRunState(id) : undefined;
+        // #50 — default async: the backend (#1313) kicks off the run and returns a
+        // 'queued' envelope immediately instead of holding the connection for the
+        // whole run. --wait restores the old synchronous round-trip.
+        const path = opts.wait ? `/api/scraps/worker/${id}` : `/api/scraps/worker/${id}?wait=false`;
+        // #91 P0 — the synchronous --wait branch runs the scrap server-side
+        // (30-250s), same as `run`; the 30s default was aborting it
+        // mid-flight. The async (default) POST returns almost immediately, so it
+        // keeps the 30s default.
+        const call = () => (opts.wait ? api.post(path, undefined, { timeoutMs: LONG_RUN_TIMEOUT_MS }) : api.post(path));
+        // #107 — under --json the stdout path stays pure: no spinner channel.
+        const data = opts.json
+            ? await call()
+            : await oraPromise(call, {
+                text: opts.wait ? 'Running worker…' : 'Triggering worker…',
+                successText: opts.wait ? 'Worker run complete' : 'Worker triggered',
+            });
+        if (opts.json)
+            json(data);
+        // #107 — see the matching comment on `run`'s --watch call above (review
+        // F1): honest final NDJSON line + exit code under --json, human mode
+        // gets the same honest exit code too.
+        if (opts.watch)
+            await pollRunProgress(id, beforeRun, { json: opts.json });
+    });
+}
+attachTriggerCommand(scraps, { hidden: true });
 // account subcommand group
 const account = scraps
     .command('account')
@@ -1013,28 +1172,49 @@ account
     .description('Set credentials for a scrap account')
     .option('-u, --username <username>', 'Account username')
     .option('-p, --password <password>', 'Account password (insecure: prefer interactive prompt)')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     let username = opts.username || '';
     let password = opts.password || '';
     if (opts.password) {
-        console.log(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
+        // #107 — this advisory is stderr-only: stdout must stay pure under
+        // --json, and every other advisory in this CLI already follows that
+        // rule (warnIfUnconfirmedTier, token.ts's expiry hints, …).
+        console.error(chalk.yellow('⚠ Passing --password on the command line is insecure and may be stored in shell history.'));
     }
+    // #107 — never blocks on a readline prompt under --json or a non-TTY
+    // invocation (agent/CI subprocess); pass -u/-p instead.
+    const interactive = isInteractive({ json: opts.json });
     if (!username) {
+        if (!interactive) {
+            usageError('Username is required — pass -u/--username (refusing to block on a prompt, non-interactive).', { json: opts.json });
+            return;
+        }
         username = await promptLine('Username: ');
         if (!username) {
-            usageError('Username is required.');
+            usageError('Username is required.', { json: opts.json });
             return;
         }
     }
     if (!password) {
+        if (!interactive) {
+            usageError('Password is required — pass -p/--password (refusing to block on a prompt, non-interactive).', { json: opts.json });
+            return;
+        }
         password = await promptPassword('Password: ');
         if (!password) {
-            usageError('Password is required.');
+            usageError('Password is required.', { json: opts.json });
             return;
         }
     }
-    const data = await oraPromise(() => api.put(`/api/scraps/${id}/account`, { username, password }), { text: 'Saving credentials…', successText: 'Credentials saved' });
+    const call = () => api.put(`/api/scraps/${id}/account`, { username, password });
+    if (opts.json) {
+        const data = await call();
+        json(data);
+        return;
+    }
+    const data = await oraPromise(call, { text: 'Saving credentials…', successText: 'Credentials saved' });
     const acc = data.account;
     console.log(chalk.dim('  Credentials: ') + (acc.hasCredentials ? chalk.green('✓ configured') : chalk.dim('not set')));
     console.log(chalk.dim('  Session:     ') + (acc.hasSession ? chalk.green('active') : chalk.dim('none')));
@@ -1044,26 +1224,27 @@ account
     .command('delete <id>')
     .description('Delete account credentials for a scrap')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
-    if (!opts.force) {
-        const { createInterface } = await import('readline');
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        let answer;
-        try {
-            answer = await new Promise((resolve) => {
-                rl.question(`Delete account credentials for scrap ${chalk.bold(id)}? ${chalk.dim('[y/N]')} `, (a) => resolve(a.trim().toLowerCase()));
-            });
-        }
-        finally {
-            rl.close();
-        }
-        if (answer !== 'y' && answer !== 'yes') {
-            console.log(chalk.dim('Aborted.'));
-            return;
-        }
+    // #107 — never blocks on a y/N under --json or a non-TTY invocation.
+    // #107 review F2 — plain-id `message` for the refusal/JSON envelope,
+    // styled `promptMessage` for the interactive TTY prompt only (see the
+    // matching comment on `scraps delete` above).
+    const { proceed, blocked } = await confirmDestructive(`Delete account credentials for scrap ${id}?`, { force: opts.force, json: opts.json, promptMessage: `Delete account credentials for scrap ${chalk.bold(id)}?` });
+    if (blocked)
+        return;
+    if (!proceed) {
+        console.log(chalk.dim('Aborted.'));
+        return;
+    }
+    const call = () => api.delete(`/api/scraps/${id}/account`);
+    if (opts.json) {
+        await call();
+        json({ deleted: true, id });
+        return;
     }
-    await oraPromise(() => api.delete(`/api/scraps/${id}/account`), {
+    await oraPromise(call, {
         text: 'Deleting credentials…',
         successText: 'Account credentials deleted',
     });
@@ -1072,9 +1253,16 @@ account
 account
     .command('clear-session <id>')
     .description('Clear the saved session for a scrap account')
-    .action(async (id) => {
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
     validateObjectId(id);
-    await oraPromise(() => api.delete(`/api/scraps/${id}/account/session`), {
+    const call = () => api.delete(`/api/scraps/${id}/account/session`);
+    if (opts.json) {
+        await call();
+        json({ cleared: true, id });
+        return;
+    }
+    await oraPromise(call, {
         text: 'Clearing session…',
         successText: 'Session cleared',
     });
@@ -1088,11 +1276,12 @@ accountSession
     .command('set <id>')
     .description('Upload browser session cookies for a scrap (Puppeteer cookie JSON array)')
     .requiredOption('-c, --cookies <file>', 'Path to a Puppeteer cookie JSON array file')
+    .option('--json', 'Output as JSON')
     .action(async (id, opts) => {
     validateObjectId(id);
     const { existsSync, readFileSync } = await import('fs');
     if (!existsSync(opts.cookies)) {
-        usageError(`File not found: ${opts.cookies}`);
+        usageError(`File not found: ${opts.cookies}`, { json: opts.json });
         return;
     }
     let cookies;
@@ -1101,22 +1290,31 @@ accountSession
         cookies = JSON.parse(raw);
     }
     catch (e) {
-        usageError(`Failed to parse cookies file: ${e.message}`);
+        usageError(`Failed to parse cookies file: ${e.message}`, { json: opts.json });
         return;
     }
     if (!Array.isArray(cookies)) {
-        usageError('Cookies file must contain a JSON array');
+        usageError('Cookies file must contain a JSON array', { json: opts.json });
         return;
     }
     if (cookies.length === 0) {
-        usageError('Cookies array must not be empty');
+        usageError('Cookies array must not be empty', { json: opts.json });
         return;
     }
     if (!cookies.every((c) => c && typeof c.name === 'string' && typeof c.value === 'string')) {
-        usageError('Each cookie must have a name (string) and value (string)');
+        usageError('Each cookie must have a name (string) and value (string)', { json: opts.json });
+        return;
+    }
+    const call = () => api.put(`/api/scraps/${id}/account/session`, { cookies });
+    if (opts.json) {
+        const data = await call();
+        json(data);
         return;
     }
-    const data = await oraPromise(() => api.put(`/api/scraps/${id}/account/session`, { cookies }), { text: 'Uploading session cookies…', successText: `Session cookies saved for scrap ${chalk.bold(id)}` });
+    const data = await oraPromise(call, {
+        text: 'Uploading session cookies…',
+        successText: `Session cookies saved for scrap ${chalk.bold(id)}`,
+    });
     const acc = data.account;
     console.log(chalk.dim('  Session: ') + (acc.hasSession ? chalk.green('✓ active') : chalk.dim('none')));
 });