@trawlme/cli 3.7.0 → 3.7.2

package/README.md

@@ -48,14 +48,15 @@ All commands accept a global `--debug` flag to show full error stack traces on f
 ```
 trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
                                                               Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
-trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
 trawl list|ls [--json] [--status <success|failure|never|running|regression>] [--limit <n>] [--page <n>]
 trawl get <id> [--json]                        Get scrap details
+trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
 trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
 trawl history <id> [--json] [-n <limit>]       List past runs for a scrap (newest first)
 trawl run-info <hid> [--json]                  Show details of a single run
-trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker (returns immediately)
 trawl whoami [--json]                          Show the authenticated user's identity
+trawl token [--json]                           Print the stored session JWT (for MCP Bearer auth)
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 
@@ -131,10 +132,9 @@ You can also install skills standalone (without the CLI): `npx @trawlme/skills i
 ```
 trawl login [--url <url>] [--token <jwt>] [--email <email>] [--password <pass>] [--json]
 trawl logout [--json]
-trawl token [--json]                         Print the stored session JWT (for MCP Bearer auth)
 ```
 
-`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `token`'s job). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
+`login --json` prints `{"ok":true,"apiUrl","config",email?}` on success — never the raw token (that's `trawl token`'s job, in the [Core commands](#core-commands-agent--human) section above — non-interactive/agent-consumable, unlike `login`/`logout`). `token --json` prints `{"token","exp","expiresAt"}` instead of the bare JWT + stderr advisories. See [Non-interactive rule](#non-interactive-rule) below: a missing `--email`/`--password` refuses immediately (usage error, exit 2) instead of prompting when `--json` is set or stdin/stdout isn't a real TTY.
 
 ### Telemetry
 

package/dist/commands/create.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS, NetworkError } from '../lib/api.js';
 import { json } from '../lib/format.js';
+import { parseServerJson } from '../lib/json.js';
 import { requireUrl, requireString } from '../lib/validate.js';
 import { UsageError } from '../lib/errors.js';
 import { renderPinch, pinchEnabled } from '../lib/pinch.js';
@@ -67,7 +68,10 @@ async function printDataSample(historyId) {
         const detail = await api.get(`/api/historys/${historyId}`);
         if (typeof detail?.data !== 'string' || !detail.data)
             return;
-        const items = JSON.parse(detail.data)?.data;
+        // #159 — same JSON-string-within-JSON shape as scrap.history[0].data;
+        // tolerate the documented raw-control-char server quirk here too instead
+        // of silently losing the sample to the outer try/catch below.
+        const items = parseServerJson(detail.data)?.data;
         if (!Array.isArray(items) || items.length === 0)
             return;
         console.log(chalk.dim(`  Sample:     `) + `${items.length} item${items.length === 1 ? '' : 's'}`);

package/dist/commands/scraps.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { spin } from '../lib/spinner.js';
 import { api, LONG_RUN_TIMEOUT_MS } from '../lib/api.js';
 import { table, json, formatDate } from '../lib/format.js';
+import { parseServerJson } from '../lib/json.js';
 import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
 import { classifyError, reportError, UsageError, RefusalError } from '../lib/errors.js';
@@ -69,7 +70,11 @@ async function watchActivities(id, 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);
+            // #159 — same tolerant parse as api.ts's response-parsing seam: an SSE
+            // activity line can carry the same server-side raw-control-character
+            // quirk as any other API payload, and this feeds `--json` NDJSON
+            // output too (not just create).
+            const activity = parseServerJson(event);
             if (asJson) {
                 console.log(JSON.stringify(activity));
                 continue;
@@ -340,6 +345,10 @@ export async function pollRunProgress(id, before, opts = {}) {
     }
     process.exitCode = 1;
 }
+// #149 item 3 — same shared-enum shape as VALID_TIERS below (~line 603):
+// keeps `--status`'s allowed values and its error message in one place,
+// mirrored from lastStatus()'s own return type so the two can never drift.
+const VALID_LAST_STATUSES = ['success', 'failure', 'never', 'running', 'regression'];
 // list — promoted to a top-level verb (#108, see the AttachOptions comment above)
 export function attachListCommand(parent, attachOpts = {}) {
     return parent
@@ -358,6 +367,14 @@ export function attachListCommand(parent, attachOpts = {}) {
         .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) => {
+        // #149 item 3 — validate --status against its enum the same way
+        // --tier already validates (usageError + return, checked first, before
+        // any other guard/async work — mirrors `create`/`update`'s --tier
+        // check below).
+        if (opts.status !== undefined && !VALID_LAST_STATUSES.includes(opts.status)) {
+            usageError(`Invalid --status "${opts.status}" (allowed: ${VALID_LAST_STATUSES.join(', ')})`, { json: opts.json });
+            return;
+        }
         // Guard: --limit and --page are mutually exclusive
         if (opts.limit !== undefined && opts.page !== undefined) {
             usageError('--limit and --page are mutually exclusive. Use one or the other.', { json: opts.json });
@@ -927,7 +944,12 @@ export function attachDataCommand(parent, attachOpts = {}) {
         let items;
         if (typeof detail?.data === 'string' && detail.data) {
             try {
-                items = JSON.parse(detail.data)?.data;
+                // #159 — `detail.data` is the same JSON-string-within-JSON shape
+                // (`history.data`) the create --json bug lived in: a raw control
+                // character here would otherwise throw and silently report "aged
+                // out of retention" below for data that is actually present and
+                // recoverable, burning a --fresh re-run + quota for nothing.
+                items = parseServerJson(detail.data)?.data;
             }
             catch {
                 items = undefined;
@@ -1118,7 +1140,7 @@ export function attachTriggerCommand(parent, attachOpts = {}) {
         .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('--wait', 'Run synchronously and wait for the result (legacy behaviour — prefer `trawl run` instead)')
         .option('--json', 'Output the raw trigger payload as JSON')
         .action(async (id, opts) => {
         validateObjectId(id);

package/dist/index.d.ts

@@ -95,6 +95,24 @@ export declare function hasJsonFlag(argv: string[]): boolean;
  * walks the whole tree and installs it everywhere. (#86 finding 3)
  */
 export declare function applyExitOverride(cmd: Command): void;
+/**
+ * #149 item 1 — commander's own usage-error line (unknown option, missing
+ * required arg, unknown command, …) is written via `Command#error()` ->
+ * `outputError()` straight to `process.stderr` BEFORE the exitOverride throw
+ * below is ever caught — in commander's own plain, uncolored `"error: …"`
+ * format, a visibly different convention from every other error this CLI
+ * prints (`reportError`'s `chalk.red('✗ ' + message)`). `configureOutput`'s
+ * `outputError` hook is exactly the one commander documents for reformatting
+ * the error text itself (`writeErr` also carries unrelated help output, e.g.
+ * `showHelpAfterError` — never enabled in this CLI, but out of scope to
+ * touch here). Overriding it on every node in the tree (same walk shape as
+ * applyExitOverride, for the same reason: addCommand()-attached subtrees
+ * don't otherwise inherit a parent's configureOutput) reformats that one line
+ * through the same red ✗ convention, stripping the redundant "error: " prefix
+ * first (stripCommanderErrorPrefix — the same prefix also leaks verbatim
+ * into the --json envelope's `message` field, see runCli's catch below).
+ */
+export declare function applyOutputConfiguration(cmd: Command): void;
 /**
  * #88 item 6 — best-effort command-name recovery for a commander parse error
  * that happened BEFORE any action ran, so `currentCommand` (the preAction

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from 'commander';
+import chalk from 'chalk';
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -14,7 +15,7 @@ import { whoami } from './commands/whoami.js';
 import { ping } from './commands/ping.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
-import { classifyError, reportError } from './lib/errors.js';
+import { classifyError, reportError, stripCommanderErrorPrefix } from './lib/errors.js';
 import { renderPinch, pinchEnabled } from './lib/pinch.js';
 import { maybeNotifyUpdate, scheduleUpdateCheck } from './lib/updateNotifier.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -91,26 +92,39 @@ export function createProgram() {
         .description('Trawl CLI — manage scraps from the terminal')
         .version(pkg.version)
         .option('--debug', 'Show full error stack traces');
-    // Core verbs (#108) — promoted/listed first: create, run, list, get, data,
-    // history, run-info, trigger, whoami, ping. `list`/`get`/`run`/`data`/
-    // `history`/`run-info`/`trigger` are built via scraps.ts's exported
-    // attachXCommand() factories — the SAME definition also stays wired
-    // (hidden) under `scraps` there, so every pre-#108 `trawl scraps <verb>`
-    // invocation keeps resolving (no breaking change).
+    // Core verbs (#108) — promoted/listed first, registration order now
+    // follows the guided flow a new user (or agent) actually walks: create it
+    // → list/get to see it → run/trigger to execute it → data to read the
+    // result → history/run-info for deeper diagnostics → whoami/token/ping as
+    // standalone identity/credential/health utilities (#149 item 6 — the
+    // pre-#149 order had `run` wedged between `create` and `list`, and
+    // `trigger` stranded after `run-info`, both ahead of ever having listed or
+    // inspected anything). `list`/`get`/`run`/`data`/`history`/`run-info`/
+    // `trigger` are built via scraps.ts's exported attachXCommand() factories —
+    // the SAME definition also stays wired (hidden) under `scraps` there, so
+    // every pre-#108 `trawl scraps <verb>` invocation keeps resolving (no
+    // breaking change).
     //
     // #114 — `create` replaced `fetch` in this slot: `POST /api/ai/wizard`
     // (AI-generate + persist + first-run + autofix), a distinct command from
     // the still-untouched `trawl scraps create` (raw-script management verb).
+    //
+    // #149 item 5 — `token` promoted from Management into Core: it satisfies
+    // every criterion the CORE_GROUP heading itself claims (agent + human,
+    // `--json` first-class, never interactive) at least as well as `whoami`/
+    // `ping` do, and exists specifically to feed an agent's MCP Bearer auth
+    // header (`$(trawl token)`) — a Management/human-CI bucket undersells that.
     program.commandsGroup(CORE_GROUP);
     program.addCommand(create);
-    attachRunCommand(program);
     attachListCommand(program);
     attachGetCommand(program);
+    attachRunCommand(program);
+    attachTriggerCommand(program);
     attachDataCommand(program);
     attachHistoryCommand(program);
     attachRunInfoCommand(program);
-    attachTriggerCommand(program);
     program.addCommand(whoami);
+    program.addCommand(token);
     program.addCommand(ping);
     // Management (#108) — human/CI surface, grouped below. `scraps` still
     // holds every pre-#108 management command (create/update/delete/banner/
@@ -120,7 +134,6 @@ export function createProgram() {
     program.addCommand(skills);
     program.addCommand(login);
     program.addCommand(logout);
-    program.addCommand(token);
     program.addCommand(telemetry);
     program.addCommand(upgrade);
     return program;
@@ -216,6 +229,33 @@ export function applyExitOverride(cmd) {
     for (const sub of cmd.commands)
         applyExitOverride(sub);
 }
+/**
+ * #149 item 1 — commander's own usage-error line (unknown option, missing
+ * required arg, unknown command, …) is written via `Command#error()` ->
+ * `outputError()` straight to `process.stderr` BEFORE the exitOverride throw
+ * below is ever caught — in commander's own plain, uncolored `"error: …"`
+ * format, a visibly different convention from every other error this CLI
+ * prints (`reportError`'s `chalk.red('✗ ' + message)`). `configureOutput`'s
+ * `outputError` hook is exactly the one commander documents for reformatting
+ * the error text itself (`writeErr` also carries unrelated help output, e.g.
+ * `showHelpAfterError` — never enabled in this CLI, but out of scope to
+ * touch here). Overriding it on every node in the tree (same walk shape as
+ * applyExitOverride, for the same reason: addCommand()-attached subtrees
+ * don't otherwise inherit a parent's configureOutput) reformats that one line
+ * through the same red ✗ convention, stripping the redundant "error: " prefix
+ * first (stripCommanderErrorPrefix — the same prefix also leaks verbatim
+ * into the --json envelope's `message` field, see runCli's catch below).
+ */
+export function applyOutputConfiguration(cmd) {
+    cmd.configureOutput({
+        outputError: (str, write) => {
+            const withoutNewline = str.endsWith('\n') ? str.slice(0, -1) : str;
+            write(chalk.red('✗ ' + stripCommanderErrorPrefix(withoutNewline)) + '\n');
+        },
+    });
+    for (const sub of cmd.commands)
+        applyOutputConfiguration(sub);
+}
 /** Commander's own codes for a successful --help/--version/`help` query —
  * these already printed their own output (to stdout) via commander itself;
  * runCli's catch must treat them as a clean exit, not an error. (#86 finding 3) */
@@ -264,6 +304,9 @@ export async function runCli(argv = process.argv) {
     // including subcommands added via addCommand() that don't otherwise
     // inherit it. (#86 finding 3)
     applyExitOverride(program);
+    // Same tree-walk requirement as applyExitOverride, same reason — installs
+    // the unified red ✗ error formatting on every node. (#149 item 1)
+    applyOutputConfiguration(program);
     const commandNames = collectCommandNames(program);
     // #88 item 6 — 'unknown' is a legitimate resolveCommandName() output (the
     // fallback for "no command resolved at all"), not free-form user input —
@@ -334,16 +377,22 @@ export async function runCli(argv = process.argv) {
             else {
                 // A usage error (unknown option/command, missing required arg, …) —
                 // commander already wrote its own human-readable line to stderr via
-                // Command#error(), so this never duplicates it. Force exit code 2
-                // (usage) regardless of whichever code commander suggests (it
-                // defaults these to 1), and add the --json machine envelope when
-                // resolvable — parsing failed before any command's own --json flag
-                // could be read off `currentCommand` (preAction never fired), so
-                // scan raw argv instead. (#86 finding 3)
+                // Command#error() (now reformatted through the same red ✗ convention
+                // by applyOutputConfiguration, #149 item 1), so this never duplicates
+                // it. Force exit code 2 (usage) regardless of whichever code
+                // commander suggests (it defaults these to 1), and add the --json
+                // machine envelope when resolvable — parsing failed before any
+                // command's own --json flag could be read off `currentCommand`
+                // (preAction never fired), so scan raw argv instead. (#86 finding 3)
                 if (isDebug)
                     console.error(err);
                 if (hasJsonFlag(argv)) {
-                    console.log(JSON.stringify({ error: { message: err.message, kind: 'usage' } }));
+                    // #149 item 2 — err.message still carries commander's own literal
+                    // "error: " prefix (set on the CommanderError itself, independent
+                    // of the outputError override above, which only reformats what
+                    // gets WRITTEN to stderr) — strip it so the envelope's `message`
+                    // stays clean for a machine parser.
+                    console.log(JSON.stringify({ error: { message: stripCommanderErrorPrefix(err.message), kind: 'usage' } }));
                 }
                 process.exitCode = 2;
                 // #88 item 6 — currentCommand is still undefined here whenever the

package/dist/lib/api.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import { getApiUrl, getToken } from './config.js';
+import { parseServerJson } from './json.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
 const USER_AGENT = `@trawlme/cli/${pkg.version}`;
@@ -135,13 +136,17 @@ function extractErrorMessage(raw, statusText) {
     if (!raw)
         return '';
     try {
-        const parsed = JSON.parse(raw);
+        // #159 — an error envelope's message/description/nested `error` string can
+        // carry the same raw-control-char server quirk as a success payload;
+        // recover it here too instead of falling all the way back to the raw,
+        // unparsed blob as the "error message".
+        const parsed = parseServerJson(raw);
         if (parsed && typeof parsed === 'object') {
             const env = parsed;
             const nested = typeof env.error === 'string' ? env.error : null;
             if (nested) {
                 try {
-                    const inner = JSON.parse(nested);
+                    const inner = parseServerJson(nested);
                     const details = inner.details;
                     if (details && typeof details.message === 'string')
                         return details.message;
@@ -178,7 +183,7 @@ function extractErrorMessage(raw, statusText) {
  */
 function extractUpgradeUrl(raw) {
     try {
-        const parsed = JSON.parse(raw);
+        const parsed = parseServerJson(raw);
         if (typeof parsed.upgradeUrl === 'string')
             return parsed.upgradeUrl;
         const details = parsed.details;
@@ -187,7 +192,7 @@ function extractUpgradeUrl(raw) {
         }
         if (typeof parsed.error === 'string') {
             try {
-                const inner = JSON.parse(parsed.error);
+                const inner = parseServerJson(parsed.error);
                 if (typeof inner.upgradeUrl === 'string')
                     return inner.upgradeUrl;
                 const innerDetails = inner.details;
@@ -252,7 +257,7 @@ async function request(path, options = {}, reqOpts = {}) {
     try {
         if (!text)
             return {};
-        const parsed = JSON.parse(text);
+        const parsed = parseServerJson(text);
         // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;
@@ -284,7 +289,7 @@ async function upload(path, formData, reqOpts = {}) {
     try {
         if (!text)
             return {};
-        const parsed = JSON.parse(text);
+        const parsed = parseServerJson(text);
         // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;
@@ -307,7 +312,7 @@ async function publicPost(path, body, baseUrlOverride, reqOpts = {}) {
     await throwIfError(res, true);
     const text = await res.text();
     try {
-        const data = text ? JSON.parse(text) : {};
+        const data = text ? parseServerJson(text) : {};
         return { data, headers: res.headers };
     }
     catch {
@@ -344,7 +349,7 @@ async function publicGet(path, reqOpts = {}) {
     try {
         if (!text)
             return {};
-        const parsed = JSON.parse(text);
+        const parsed = parseServerJson(text);
         // Unwrap API envelope { type, message, data: T }
         if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
             return parsed.data;

package/dist/lib/errors.d.ts

@@ -21,6 +21,18 @@ export declare class UsageError extends Error {
 export declare class RefusalError extends Error {
     constructor(message: string);
 }
+/**
+ * Commander prefixes every one of its own usage-error messages with the
+ * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
+ * etc. in commander's `command.js`) — harmless for its own plain default
+ * line, but redundant once this CLI reuses that message itself: (1) baked
+ * into a `--json` envelope's `message` field, a human-facing "error: " prefix
+ * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
+ * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
+ * would double up as "✗ error: unknown option …". Idempotent — a message
+ * that never had the prefix passes through unchanged. (#149 items 1/2)
+ */
+export declare function stripCommanderErrorPrefix(message: string): string;
 export interface ErrorEnvelope {
     message: string;
     status?: number;

package/dist/lib/errors.js

@@ -29,6 +29,20 @@ export class RefusalError extends Error {
         this.name = 'RefusalError';
     }
 }
+/**
+ * Commander prefixes every one of its own usage-error messages with the
+ * literal `"error: "` (see `missingArgument`/`unknownOption`/`unknownCommand`
+ * etc. in commander's `command.js`) — harmless for its own plain default
+ * line, but redundant once this CLI reuses that message itself: (1) baked
+ * into a `--json` envelope's `message` field, a human-facing "error: " prefix
+ * is dead weight for a machine parser that already reads `kind:"usage"`; (2)
+ * reformatted through the app's own `chalk.red('✗ ' + message)` convention it
+ * would double up as "✗ error: unknown option …". Idempotent — a message
+ * that never had the prefix passes through unchanged. (#149 items 1/2)
+ */
+export function stripCommanderErrorPrefix(message) {
+    return message.startsWith('error: ') ? message.slice('error: '.length) : message;
+}
 /**
  * Central status → exit-code map (#71 findings 13/14/60). Agents driving this
  * CLI unattended need to tell "you're not logged in" (3) from "that id

package/dist/lib/json.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared, tolerant JSON parsing for server response bodies (#159).
+ *
+ * The Trawl API is known to occasionally emit a raw, unescaped control
+ * character (U+0000–U+001F — a literal newline, NUL, BEL, …) inside a JSON
+ * string value, most often nested inside `scrap.history[0].data` (a
+ * worker-envelope blob embedded as a string field of the outer response —
+ * the exact server-side emission point is not yet pinned down; tracked in
+ * comes-io/trawl_node#1768). That is invalid per RFC 8259 — our own QA
+ * tooling already works around it by parsing raw API responses with
+ * Python's `json.loads(text, strict=False)` — but native `JSON.parse`
+ * has no equivalent lenient mode: it throws outright, and until this fix
+ * every one of `api.ts`'s response-parsing call sites (`request`, `upload`,
+ * `publicGet`, `publicPost`) turned that into a bare "Invalid JSON in server
+ * response" error, discarding the ENTIRE response — even a successful
+ * create/run whose scrap was already persisted server-side. Exactly the
+ * "payload-dependent, not a constant break" shape reported in #159: it only
+ * fires when the specific scraped content/log text happens to carry a raw
+ * control byte.
+ *
+ * `parseServerJson` recovers from that ONE known shape — nothing else. It
+ * tries a normal strict `JSON.parse` first (the common case, zero extra
+ * cost) and only falls back to a sanitizing re-parse when that throws.
+ * Genuinely malformed JSON (truncated body, stray token, …) still throws
+ * after the fallback also fails — this is a targeted recovery, not a
+ * general-purpose lenient parser.
+ */
+export declare function escapeRawControlCharsInJsonStrings(text: string): string;
+/**
+ * Parse a server response body, tolerating the known #159 quirk above. Never
+ * silently drops data: a byte that reaches here as a real control character
+ * comes back out as the same character (via the escape → JSON.parse
+ * unescape round trip) once parsed, and JSON.stringify guarantees it is
+ * re-escaped correctly on the way back out through the shared `--json`
+ * output seam (`lib/format.ts#json`).
+ */
+export declare function parseServerJson(text: string): unknown;

package/dist/lib/json.js

@@ -0,0 +1,104 @@
+/**
+ * Shared, tolerant JSON parsing for server response bodies (#159).
+ *
+ * The Trawl API is known to occasionally emit a raw, unescaped control
+ * character (U+0000–U+001F — a literal newline, NUL, BEL, …) inside a JSON
+ * string value, most often nested inside `scrap.history[0].data` (a
+ * worker-envelope blob embedded as a string field of the outer response —
+ * the exact server-side emission point is not yet pinned down; tracked in
+ * comes-io/trawl_node#1768). That is invalid per RFC 8259 — our own QA
+ * tooling already works around it by parsing raw API responses with
+ * Python's `json.loads(text, strict=False)` — but native `JSON.parse`
+ * has no equivalent lenient mode: it throws outright, and until this fix
+ * every one of `api.ts`'s response-parsing call sites (`request`, `upload`,
+ * `publicGet`, `publicPost`) turned that into a bare "Invalid JSON in server
+ * response" error, discarding the ENTIRE response — even a successful
+ * create/run whose scrap was already persisted server-side. Exactly the
+ * "payload-dependent, not a constant break" shape reported in #159: it only
+ * fires when the specific scraped content/log text happens to carry a raw
+ * control byte.
+ *
+ * `parseServerJson` recovers from that ONE known shape — nothing else. It
+ * tries a normal strict `JSON.parse` first (the common case, zero extra
+ * cost) and only falls back to a sanitizing re-parse when that throws.
+ * Genuinely malformed JSON (truncated body, stray token, …) still throws
+ * after the fallback also fails — this is a targeted recovery, not a
+ * general-purpose lenient parser.
+ */
+/**
+ * Escape any raw control character (U+0000–U+001F) found INSIDE a JSON
+ * string literal, leaving everything else — including legitimate raw
+ * whitespace between tokens (space/tab/CR/LF are valid there per RFC 8259) —
+ * untouched. A small state machine tracks whether the scan is currently
+ * inside a `"…"` string and whether the previous character was an unescaped
+ * backslash; it does not otherwise validate structure, so text that is
+ * invalid JSON for any OTHER reason still fails the subsequent `JSON.parse`
+ * call unchanged.
+ */
+const NAMED_CONTROL_CHAR_ESCAPES = {
+    '\n': '\\n',
+    '\r': '\\r',
+    '\t': '\\t',
+    '\b': '\\b',
+    '\f': '\\f',
+};
+export function escapeRawControlCharsInJsonStrings(text) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const ch = text[i];
+        const code = text.charCodeAt(i);
+        if (!inString) {
+            if (ch === '"')
+                inString = true;
+            out += ch;
+            continue;
+        }
+        if (escaped) {
+            out += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\') {
+            out += ch;
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = false;
+            out += ch;
+            continue;
+        }
+        if (code <= 0x1f) {
+            // Raw control character inside a string literal — recover the same
+            // way JSON.stringify would have escaped it on the way out, instead of
+            // losing the whole response to a SyntaxError.
+            out += NAMED_CONTROL_CHAR_ESCAPES[ch] ?? `\\u${code.toString(16).padStart(4, '0')}`;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Parse a server response body, tolerating the known #159 quirk above. Never
+ * silently drops data: a byte that reaches here as a real control character
+ * comes back out as the same character (via the escape → JSON.parse
+ * unescape round trip) once parsed, and JSON.stringify guarantees it is
+ * re-escaped correctly on the way back out through the shared `--json`
+ * output seam (`lib/format.ts#json`).
+ */
+export function parseServerJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (firstErr) {
+        try {
+            return JSON.parse(escapeRawControlCharsInJsonStrings(text));
+        }
+        catch {
+            throw firstErr;
+        }
+    }
+}

package/docs/agent-quickstart.md

@@ -20,21 +20,22 @@ agent should never need them.)
 
 ## Core commands (agent + human)
 
-These ten commands are the CLI's agent+human surface — `--json` is
+These eleven commands are the CLI's agent+human surface — `--json` is
 first-class on every one, and none of them ever blocks on a prompt (see
 [Non-interactive contract](#non-interactive-contract) below):
 
 ```
 trawl create <url> --prompt <goal> [--no-autofix] [--json]   # url also accepted as --url <url> (#116)
                                                               Create a persistent, self-healing scrap from a URL + a goal (AI-generated)
-trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
 trawl list|ls [--json] [--status <s>] [--limit <n>] [--page <n>]   List all scraps
 trawl get <id> [--json]                        Get scrap details
+trawl run <id> [--watch] [--json]              Run a scrap (blocks until finished)
+trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker
 trawl data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run, or --fresh to launch one)
 trawl history <id> [--json] [-n <limit>]       List past runs for a scrap
 trawl run-info <hid> [--json]                  Show details of a single run
-trawl trigger <id> [--watch] [--wait] [--json] Launch a scrap as a background worker
 trawl whoami [--json]                          Show the authenticated user's identity
+trawl token [--json]                           Print the stored session JWT (for MCP Bearer auth)
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {