@trawlme/cli 3.4.2 → 3.5.1

package/README.md

@@ -6,7 +6,7 @@
 
 Command-line client for [Trawl](https://trawl.me) — manage your scraps from the terminal.
 
-> ⚠️ **Early stage.** APIs may change before `1.0`. Pin a version if you depend on this in CI.
+> 📌 **Versioned with semantic-release** — breaking CLI-surface changes always ship as a new major. Pin a major (`@trawlme/cli@^3`) if you depend on the CLI in CI.
 
 > 🤖 **Driving this CLI from an AI agent?** See [docs/agent-quickstart.md](docs/agent-quickstart.md) for the minimal surface (`create`, `--json`, `TRAWL_TOKEN`, exit codes) — this README is the full human/CI guide.
 
@@ -48,7 +48,7 @@ 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
+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 data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run — read-only, no quota; --fresh to launch one)
@@ -59,6 +59,8 @@ trawl whoami [--json]                          Show the authenticated user's ide
 trawl ping [--json]                            Health/version handshake against the Trawl API
 ```
 
+(`trawl create` AI-generates and persists a new scrap from a URL + a goal — distinct from `trawl scraps create`, which is raw manual scrap entry.)
+
 > **No breaking change:** every verb above is also still reachable under its pre-reorg path, `trawl scraps <verb>` (e.g. `trawl scraps list`, `trawl scraps run <id>`) — kept as a hidden alias so scripts written before the surface reorg keep working. `trawl --help` only shows the top-level form above; `trawl scraps --help` only shows the remaining scrap-management commands below.
 
 `create`/`whoami`/`ping` are fully non-interactive — all three read auth only from `TRAWL_TOKEN`/the stored login token, never prompt. `trawl create` runs the AI wizard server-side (`POST /api/ai/wizard`): generate scrap code from `--prompt` via LLM, persist the scrap, trigger its FIRST run, and auto-fix on failure (default on — `--no-autofix` disables it, sending `autoFix:false`). On a successful first run (human mode) it prints a small **data sample** (item count + first-item fields + one truncated value) as proof of value — best-effort, silent if the sample can't be fetched — and points `Next step` at `trawl data <id>` (the data), with `trawl get <id>` as the secondary detail view. `--json` skips the sample fetch and prints the raw wizard payload verbatim. `success` is an honest outcome of that first run, not "did the HTTP call succeed" — a failed first run is still a 200 response (the scrap was still created; auto-fix, when enabled, retries in the background), and the CLI exits 1 in that case (both human and `--json` modes) even though `--json` always prints the raw payload verbatim. The call legitimately takes 30–250s+ server-side (AI generation + a real run), same long-run timeout as `run`/`data --fresh`/`trigger --wait` below. `trawl whoami`/`trawl ping` mirror the MCP `trawl_whoami`/`trawl_health_ping` tools as closely as the REST surface allows (`GET /api/users/me` / `GET /api/health`) — `ping`'s `--json` payload is admin-enriched (version/uptime/db) and just `{"status":"ok"}` for anyone else.
@@ -243,6 +245,8 @@ This project uses `legacy-peer-deps` (see `.npmrc`) due to a transitive peer-dep
 
 Issues and PRs are welcome — please open an issue first for non-trivial changes so we can align on direction.
 
+Releases: a merge to `main` publishes to the npm **`next`** dist-tag (candidate channel — try it with `npm i -g @trawlme/cli@next`). The **`latest`** tag is promoted manually after QA, so a merge never ships to default installs directly.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/commands/create.js

@@ -88,7 +88,7 @@ async function printDataSample(historyId) {
     }
 }
 export const create = new Command('create')
-    .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated)')
+    .description('Create a persistent, self-healing scrap from a URL + a goal (AI-generated) — distinct from `trawl scraps create`, which is raw manual entry')
     .argument('[url]', 'Target public URL (http/https)')
     .requiredOption('--prompt <goal>', 'What to extract/scrape, in plain language (required)')
     .option('--url <url>', 'Target public URL — alias of the positional argument')

package/dist/commands/ping.js

@@ -6,7 +6,14 @@ export const ping = new Command('ping')
     .description('Health/version handshake against the Trawl API')
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
-    const data = await api.get('/api/health');
+    // #148 — the server route is optionalAuth (public, enriched for an admin
+    // JWT — see the PingResponse doc above); `api.publicGet` mirrors that:
+    // it attaches a stored/env token when one happens to be available but
+    // never REQUIRES one, so `ping` works as a zero-config sanity check even
+    // with no `trawl login` ever run. `api.get` (the authenticated path)
+    // would throw notLoggedInError() locally before this ever reached the
+    // network, defeating the whole point of a pre-login handshake.
+    const data = await api.publicGet('/api/health');
     // #106 review (kimi) — honest exit code: a soft-degraded 200 (status !== 'ok')
     // must exit non-zero so `trawl ping || handle_degraded` doesn't treat a
     // degraded API as healthy. Applies in BOTH --json and human modes, alongside

package/dist/commands/scraps.js

@@ -710,7 +710,7 @@ scraps
 export function attachRunCommand(parent, attachOpts = {}) {
     return parent
         .command('run <id>', attachOpts)
-        .description('Run a scrap')
+        .description('Run a scrap (blocks until finished)')
         .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) => {

package/dist/index.js

@@ -293,7 +293,29 @@ export async function runCli(argv = process.argv) {
         }
     });
     try {
-        await program.parseAsync(argv);
+        // #148 — a bare `trawl` (no args at all) reads as "let me look around",
+        // not a failure: it should behave exactly like `trawl --help` (same
+        // text, stdout, exit 0). Left to commander's own default, a program with
+        // subcommands and no root action handler treats zero args as "probably
+        // missing subcommand" and calls `this.help({ error: true })` internally
+        // (see node_modules/commander/lib/command.js `_parseCommand`) — which
+        // writes the SAME help text to stderr and throws a CommanderError with
+        // exitCode 1 (caught below, bucketed into HELP_OR_VERSION_CODES since its
+        // code is 'commander.help', so only the exit code carries the mistake
+        // through — text already went to the wrong stream by then). Intercepting
+        // here, before parseAsync ever runs, avoids fighting that internal
+        // decision entirely and can't affect a genuine unknown top-level command
+        // (`trawl frobnicate`) — that path only runs when `isBareInvocation` is
+        // false, so it still reaches `this.unknownCommand()` unchanged (stderr,
+        // exit 2, code 'commander.unknownCommand' — never in
+        // HELP_OR_VERSION_CODES).
+        if (isBareInvocation(argv)) {
+            program.outputHelp();
+            process.exitCode = 0;
+        }
+        else {
+            await program.parseAsync(argv);
+        }
     }
     catch (err) {
         const { debug } = program.opts();

package/dist/lib/api.d.ts

@@ -60,6 +60,7 @@ export interface RequestOptions {
 }
 export declare const api: {
     get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+    publicGet: <T>(path: string, opts?: RequestOptions) => Promise<T>;
     getText: (path: string, opts?: RequestOptions) => Promise<string>;
     post: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;
     put: <T>(path: string, body?: unknown, opts?: RequestOptions) => Promise<T>;

package/dist/lib/api.js

@@ -314,6 +314,47 @@ async function publicPost(path, body, baseUrlOverride, reqOpts = {}) {
         throw new Error('Invalid JSON in server response');
     }
 }
+/**
+ * Unauthenticated GET — for endpoints the server itself treats as public/
+ * optional-auth (e.g. `GET /api/health`, home.route.js's `optionalAuth`
+ * middleware: enriches the response for an admin JWT, passes through
+ * otherwise). Unlike `request()`, this NEVER throws `notLoggedInError()` for
+ * a missing token — that guard exists for endpoints that genuinely require
+ * auth, and applying it here defeated the whole point of a pre-login
+ * sanity-check (#148). The token is still attached as a best-effort Cookie
+ * when one happens to be stored/env-set, so an already-authenticated caller
+ * still gets the admin-enriched payload — it's just never REQUIRED.
+ * `throwIfError(res, true)` mirrors `publicPost`'s "public endpoint" 401
+ * wording, even though this route's optionalAuth middleware never actually
+ * rejects a request for lacking/invalid credentials.
+ */
+async function publicGet(path, reqOpts = {}) {
+    const token = getToken();
+    const url = `${getApiUrl()}${path}`;
+    const timeoutMs = getTimeoutMs(reqOpts.timeoutMs);
+    const res = await safeFetch(url, {
+        headers: {
+            'User-Agent': USER_AGENT,
+            ...(token ? { Cookie: `TOKEN=${token}` } : {}),
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+    }, timeoutMs);
+    await throwIfError(res, true);
+    const text = await res.text();
+    try {
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        // Unwrap API envelope { type, message, data: T }
+        if (parsed !== null && typeof parsed === 'object' && 'data' in parsed) {
+            return parsed.data;
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error('Invalid JSON in server response');
+    }
+}
 async function getText(path, reqOpts = {}) {
     const token = getToken();
     if (!token)
@@ -332,6 +373,7 @@ async function getText(path, reqOpts = {}) {
 }
 export const api = {
     get: (path, opts) => request(path, {}, opts),
+    publicGet: (path, opts) => publicGet(path, opts),
     getText: (path, opts) => getText(path, opts),
     post: (path, body, opts) => request(path, {
         method: 'POST',

package/dist/lib/pinch.d.ts

@@ -3,29 +3,30 @@
  * art. Distinct from Clawd's 8-bit lane: Pinch is drawn with full 24-bit
  * (`\x1b[38;2;r;g;bm` / `\x1b[48;2;r;g;bm`) color blocks, not a fixed palette.
  *
- * The 9×6 cube-grid (#133 mini) is packed two grid rows into one terminal
- * row: the
- * upper row's color becomes the half-block's foreground, the lower row's
- * becomes its background, using the upper-half-block glyph '▀' (or '▄' when
- * only the lower half is filled). A 6-row grid therefore renders in 3
- * terminal rows, 9 columns wide. '.' cells are transparent — no color
- * escape is emitted for that half, so the terminal's own background shows
- * through.
+ * Each grid is packed two rows into one terminal row: the upper row's color
+ * becomes the half-block's foreground, the lower row's becomes its
+ * background, using the upper-half-block glyph '▀' (or '▄' when only the
+ * lower half is filled). '.' cells are transparent — no color escape is
+ * emitted for that half, so the terminal's own background shows through.
  *
- * Grids + palette are mirrored from trawl_vue
- * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
- * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
- * package). Claws are 1-wide 2-tall 'O' blocks at cols 0 / 8, on the SIDES
- * (raised for wave/thumbsup/celebrating/shocked), per the r6f shape.
+ * The grids are the founder-approved 2D front avatar (`AVATAR_GRIDS`, rev
+ * r6f) from trawl_vue `src/modules/trawl/assets/mascot/_src/pinch.model.mjs`,
+ * ported VERBATIM (no cross-repo import — cli is a standalone npm package).
+ * Each is 14 cols × 8 rows (the source's 9th all-'.' pad row is dropped) →
+ * renders in 4 terminal rows, 14 columns wide. This is the mascot "de face":
+ * antennae on top, 2-wide white eyes + navy pupils, pink cheek blush, a
+ * U-smile (corners + a 2-wide dropped center), and the signature 2-WIDE
+ * orange claws on the body flanks (cols 0-1 / 12-13).
  *
- * State parity (#135): the CLI now carries all 9 canonical AVATAR_STATES
- * from the source model — idle · working · celebrating · thumbsup · confused
- * · wave · heart · sleepy · shocked — with the SAME names (before #135 the
- * CLI shipped 4 states and called `working` "thinking", a name not in the
- * source). Each is a 9×6 mini redraw preserving that state's distinguishing
- * feature.
+ * History: #133 shrank this to a 9×6 mini (1-wide claws, a single-pixel
+ * mouth) — #141 reverted to this faithful 14×9 founder art after it read as
+ * "trop loin du 3D".
  *
- * See comes-io/trawl_cli#94, comes-io/trawl_cli#122, comes-io/trawl_cli#135.
+ * State parity (#135): the CLI carries all 9 canonical AVATAR_STATES with the
+ * source's own names — idle · working · celebrating · thumbsup · confused ·
+ * wave · heart · sleepy · shocked.
+ *
+ * See comes-io/trawl_cli#94, #122, #135, #141.
  */
 export type PinchState = 'idle' | 'working' | 'celebrating' | 'thumbsup' | 'confused' | 'wave' | 'heart' | 'sleepy' | 'shocked';
 /** All 9 canonical states, in the source model's AVATAR_STATES order. */
@@ -42,9 +43,10 @@ export declare function renderPinch(state: PinchState, frame?: number): string;
 /**
  * #131 — the ART lines only (no caption), optionally COMPACT: trailing and
  * leading fully-transparent grid rows are dropped so Pinch takes fewer
- * terminal lines (some grids carry an all-'.' padding row). `frame` is passed
- * through to `gridForState` — only `working` reacts to it (the cyan antenna
- * blip toggles), so the loop can pulse the tips while the body stays still.
+ * terminal lines (confused/sleepy carry an all-'.' leading row). `frame` is
+ * passed through to `gridForState` — only `working` reacts to it (the cyan
+ * antenna blip toggles), so the loop can pulse the tips while the body stays
+ * still.
  */
 export declare function renderPinchArt(state: PinchState, opts?: {
     compact?: boolean;

package/dist/lib/pinch.js

@@ -3,29 +3,30 @@
  * art. Distinct from Clawd's 8-bit lane: Pinch is drawn with full 24-bit
  * (`\x1b[38;2;r;g;bm` / `\x1b[48;2;r;g;bm`) color blocks, not a fixed palette.
  *
- * The 9×6 cube-grid (#133 mini) is packed two grid rows into one terminal
- * row: the
- * upper row's color becomes the half-block's foreground, the lower row's
- * becomes its background, using the upper-half-block glyph '▀' (or '▄' when
- * only the lower half is filled). A 6-row grid therefore renders in 3
- * terminal rows, 9 columns wide. '.' cells are transparent — no color
- * escape is emitted for that half, so the terminal's own background shows
- * through.
+ * Each grid is packed two rows into one terminal row: the upper row's color
+ * becomes the half-block's foreground, the lower row's becomes its
+ * background, using the upper-half-block glyph '▀' (or '▄' when only the
+ * lower half is filled). '.' cells are transparent — no color escape is
+ * emitted for that half, so the terminal's own background shows through.
  *
- * Grids + palette are mirrored from trawl_vue
- * `src/modules/trawl/assets/mascot/_src/pinch.model.mjs` (AVCOLORS +
- * AVATAR_GRIDS, rev r6f) — no cross-repo import (cli is a standalone npm
- * package). Claws are 1-wide 2-tall 'O' blocks at cols 0 / 8, on the SIDES
- * (raised for wave/thumbsup/celebrating/shocked), per the r6f shape.
+ * The grids are the founder-approved 2D front avatar (`AVATAR_GRIDS`, rev
+ * r6f) from trawl_vue `src/modules/trawl/assets/mascot/_src/pinch.model.mjs`,
+ * ported VERBATIM (no cross-repo import — cli is a standalone npm package).
+ * Each is 14 cols × 8 rows (the source's 9th all-'.' pad row is dropped) →
+ * renders in 4 terminal rows, 14 columns wide. This is the mascot "de face":
+ * antennae on top, 2-wide white eyes + navy pupils, pink cheek blush, a
+ * U-smile (corners + a 2-wide dropped center), and the signature 2-WIDE
+ * orange claws on the body flanks (cols 0-1 / 12-13).
  *
- * State parity (#135): the CLI now carries all 9 canonical AVATAR_STATES
- * from the source model — idle · working · celebrating · thumbsup · confused
- * · wave · heart · sleepy · shocked — with the SAME names (before #135 the
- * CLI shipped 4 states and called `working` "thinking", a name not in the
- * source). Each is a 9×6 mini redraw preserving that state's distinguishing
- * feature.
+ * History: #133 shrank this to a 9×6 mini (1-wide claws, a single-pixel
+ * mouth) — #141 reverted to this faithful 14×9 founder art after it read as
+ * "trop loin du 3D".
  *
- * See comes-io/trawl_cli#94, comes-io/trawl_cli#122, comes-io/trawl_cli#135.
+ * State parity (#135): the CLI carries all 9 canonical AVATAR_STATES with the
+ * source's own names — idle · working · celebrating · thumbsup · confused ·
+ * wave · heart · sleepy · shocked.
+ *
+ * See comes-io/trawl_cli#94, #122, #135, #141.
  */
 /** Grid-char → RGB, ported from AVCOLORS (pinch.model.mjs, rev r6f). 'C'
  * (cyan) is the `working` thinking-blip — not present in any static grid,
@@ -52,107 +53,125 @@ export const PINCH_STATES = [
     'shocked',
 ];
 /**
- * Explicit per-state 9×6 grids (#133 mini shape, #135 full state parity).
- * The 14×9 grids were ported from trawl_vue's AVATAR_GRIDS (pinch.model.mjs,
- * rev r6f); these mini redraws preserve each state's feature at a smaller
- * pixel count. Grid layout (cols 0-8, body/shell cols 1-7):
- *   row 0  antennae (O at cols 2,6 — spread to 1,7 when drooped)
- *   row 1  head top      (+ claw at col 0/8 when RAISED)
- *   row 2  eyes          (+ claw at col 0/8 when RAISED)
- *   row 3  head mid
- *   row 4  mouth corners + blush  (+ claw at col 0/8 when RESTING)
- *   row 5  head bottom + mouth center  (+ claw at col 0/8 when RESTING)
- * Claws are the 1-wide 2-tall O blocks at cols 0/8. Eyes: left = W+K at
- * cols 2-3, right = K+W at cols 5-6 (pupils inward). The smile is a U (like
- * the source 3D / AVGRID): the mouth CORNERS sit on row 4 and the CENTER
- * dips to row 5 — never a flat single-row bar (#137).
+ * The founder 2D front avatar grids (`AVATAR_GRIDS`, pinch.model.mjs rev
+ * r6f), ported VERBATIM — rows 0-7 of each 9-row grid (the trailing all-'.'
+ * pad row 8 is dropped; it only exists to square the SVG canvas). 14 cols,
+ * 8 rows → 4 terminal lines. Layout:
+ *   rows 0-1  antennae (2 orange, drooped/spread for confused & sleepy)
+ *   row  2    head top      (+ claw at cols 0-1/12-13 when RAISED)
+ *   rows 3-4  eyes: 2-wide W whites (row 3) + K pupils (row 4)
+ *   row  5    head mid
+ *   rows 6-7  mouth + blush + the 2-WIDE claws on the flanks
+ * The claws are 2×2 O blocks OUTSIDE the body silhouette (cols 0-1 / 12-13),
+ * raised to rows 3-4 for celebrating / shocked (and the right claw for
+ * wave / thumbsup). The smile is a U: corners K on row 6, a 2-wide center
+ * KK on row 7.
  */
 const GRIDS = {
-    // calm resting face, both claws down, normal smile.
     idle: [
-        '..O...O..',
-        '.BBBBBBB.',
-        '.BWKBKWB.',
-        '.BBBBBBB.',
-        'OBPKBKPBO',
-        'OBBBKBBBO',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBBOO',
+        'OOBBBBKKBBBBOO',
     ],
     // idle pose + the cyan thinking-blip on the antenna tips (frame-toggled in
     // `gridForState`) — the only animated static state.
     working: [
-        '..O...O..',
-        '.BBBBBBB.',
-        '.BWKBKWB.',
-        '.BBBBBBB.',
-        'OBPKBKPBO',
-        'OBBBKBBBO',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBBOO',
+        'OOBBBBKKBBBBOO',
     ],
-    // both claws raised (rows 1-2) + a big open mouth.
+    // both claws raised to rows 3-4 + a big open mouth (rows 6-7).
     celebrating: [
-        '..O...O..',
-        'OBBBBBBBO',
-        'OBWKBKWBO',
-        '.BBBBBBB.',
-        '.BKBBBKB.',
-        '.BBKKKBB.',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        'OOBWWBBBBWWBOO',
+        'OOBWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        '..BBPKKKKPBB..',
+        '..BBBKKKKBBB..',
     ],
-    // right claw raised (rows 1-2) + a thumb pixel poking up above it (row 0,
-    // col 8); left claw resting.
+    // right claw raised (rows 3-4) + a thumb pixel poking up (row 2, col 12);
+    // left claw resting on the flank (rows 6-7).
     thumbsup: [
-        '..O...O.O',
-        '.BBBBBBBO',
-        '.BWKBKWBO',
-        '.BBBBBBB.',
-        'OBPKBKPB.',
-        'OBBBKBBB.',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBBO.',
+        '..BWWBBBBWWBOO',
+        '..BWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBB..',
+        'OOBBBBKKBBBB..',
     ],
-    // antennae drooped + spread, flat mouth (no K), claws resting. A '?' is
-    // appended beside the eye line by `renderPinch`.
+    // antennae drooped + spread (row 1, cols 3 & 10), flat mouth (blush only, no
+    // smile K on row 6), claws resting. A '?' is appended by `renderPinch`.
     confused: [
-        '.O.....O.',
-        '.BBBBBBB.',
-        '.BWKBKWB.',
-        '.BBBBBBB.',
-        'OBPBBBPBO',
-        'OBBBBBBBO',
+        '..............',
+        '...O......O...',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BWKBBBBKWB..',
+        '..BBBBBBBBBB..',
+        'OOBBPBBBBPBBOO',
+        'OOBBBBKKBBBBOO',
     ],
-    // right claw raised (rows 1-2), left claw resting; base face.
+    // right claw raised (rows 3-4), left claw resting; base face.
     wave: [
-        '..O...O..',
-        '.BBBBBBBO',
-        '.BWKBKWBO',
-        '.BBBBBBB.',
-        'OBPKBKPB.',
-        'OBBBKBBB.',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWBOO',
+        '..BWKBBBBKWBOO',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBB..',
+        'OOBBBBKKBBBB..',
     ],
-    // pink heart-eyes (P replaces the W+K pupils), claws resting, normal smile.
+    // pink heart-eyes (P fills both eye blocks, rows 3-4), claws resting, normal
+    // smile.
     heart: [
-        '..O...O..',
-        '.BBBBBBB.',
-        '.BPPBPPB.',
-        '.BBBBBBB.',
-        'OBPKBKPBO',
-        'OBBBKBBBO',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        '..BPPBBBBPPB..',
+        '..BPPBBBBPPB..',
+        '..BBBBBBBBBB..',
+        'OOBBPKBBKPBBOO',
+        'OOBBBBKKBBBBOO',
     ],
-    // closed eyes (flat K line, no white), antennae drooped + spread, flat
-    // mouth, claws resting — like confused but eyes shut and no '?'.
+    // closed eyes (flat K line on row 4, no white), antennae drooped + spread,
+    // flat mouth, claws resting — like confused but eyes shut and no '?'.
     sleepy: [
-        '.O.....O.',
-        '.BBBBBBB.',
-        '.BKKBKKB.',
-        '.BBBBBBB.',
-        'OBPBBBPBO',
-        'OBBBBBBBO',
+        '..............',
+        '...O......O...',
+        '..BBBBBBBBBB..',
+        '..BWWBBBBWWB..',
+        '..BKKBBBBKKB..',
+        '..BBBBBBBBBB..',
+        'OOBBPBBBBPBBOO',
+        'OOBBBBKKBBBBOO',
     ],
-    // both claws raised (rows 1-2) + a small round mouth (single K, row 4) —
-    // like celebrating's raise but a startled dot mouth, not the wide smile.
+    // pupils up a row (row 3 carries K, row 4 all white), both claws raised
+    // (rows 3-4), a small round mouth (row 6 only) — startled, not the wide
+    // celebrating grin.
     shocked: [
-        '..O...O..',
-        'OBBBBBBBO',
-        'OBWKBKWBO',
-        '.BBBBBBB.',
-        '.BBBKBBB.',
-        '.BBBBBBB.',
+        '....O....O....',
+        '....O....O....',
+        '..BBBBBBBBBB..',
+        'OOBWKBBBBKWBOO',
+        'OOBWWBBBBWWBOO',
+        '..BBBBBBBBBB..',
+        '..BBPBKKBPBB..',
+        '..BBBBBBBBBB..',
     ],
 };
 const CAPTIONS = {
@@ -166,8 +185,8 @@ const CAPTIONS = {
     sleepy: 'Pinch is sleepy…',
     shocked: 'Pinch is shocked!',
 };
-/** Antenna-tip cells (row 0) for the `working` cyan blip: cols 2 & 6. */
-const ANTENNA_TIP_COLS = [2, 6];
+/** Antenna-tip cells (grid row 0) for the `working` cyan blip: cols 4 & 9. */
+const ANTENNA_TIP_COLS = [4, 9];
 /** Replace the chars at `indices` in `row` with `ch` — never mutates `row`. */
 function setCells(row, indices, ch) {
     const chars = row.split('');
@@ -212,7 +231,7 @@ function renderCell(upper, lower) {
     return `${fgCode(upperColor)}${bgCode(lowerColor)}▀${RESET}`;
 }
 /** Pack a grid into terminal lines, 2 grid rows per line (upper=fg, lower=bg).
- * The #133 mini grid is 6 rows → 3 lines. */
+ * The 14×8 founder grid is 8 rows → 4 lines. */
 function renderGrid(rows) {
     const lines = [];
     for (let i = 0; i < rows.length; i += 2) {
@@ -238,8 +257,8 @@ export function renderPinch(state, frame = 0) {
     const grid = gridForState(state, frame);
     const lines = renderGrid(grid);
     if (state === 'confused') {
-        // "beside the art" — a bold '?' to the right of the eye row. In the #133
-        // mini grid the eyes are grid rows 2-3, which pack into terminal line 1.
+        // "beside the art" — a bold '?' to the right of the eye row. The eyes are
+        // grid rows 2-3 (head-top + eye-whites), which pack into terminal line 1.
         lines[1] = `${lines[1]}  \x1b[1m?${RESET}`;
     }
     return [...lines, CAPTIONS[state]].join('\n');
@@ -247,9 +266,10 @@ export function renderPinch(state, frame = 0) {
 /**
  * #131 — the ART lines only (no caption), optionally COMPACT: trailing and
  * leading fully-transparent grid rows are dropped so Pinch takes fewer
- * terminal lines (some grids carry an all-'.' padding row). `frame` is passed
- * through to `gridForState` — only `working` reacts to it (the cyan antenna
- * blip toggles), so the loop can pulse the tips while the body stays still.
+ * terminal lines (confused/sleepy carry an all-'.' leading row). `frame` is
+ * passed through to `gridForState` — only `working` reacts to it (the cyan
+ * antenna blip toggles), so the loop can pulse the tips while the body stays
+ * still.
  */
 export function renderPinchArt(state, opts = {}) {
     let grid = gridForState(state, opts.frame ?? 0);

package/docs/agent-quickstart.md

@@ -27,7 +27,7 @@ first-class on every one, and none of them ever blocks on a prompt (see
 ```
 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
+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 data <id> [--json] [--fresh] [--errors]  Get scrap data (last persisted run, or --fresh to launch one)

package/package.json

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