@trawlme/cli 1.18.6 → 1.19.0

package/dist/commands/scraps.d.ts

@@ -1,10 +1,21 @@
 import { Command } from 'commander';
 export declare const scraps: Command;
 /** The top-of-history snapshot pollRunProgress needs to identify which run
- * it's watching — see captureBeforeRunState. */
+ * it's watching — see captureBeforeRunState.
+ *
+ * #97 — `captured` discriminates WHY `id` is undefined: `true` means the GET
+ * succeeded and the scrap genuinely has no history yet (an honest "never
+ * run" signal pollRunProgress can trust immediately); `false` means the GET
+ * itself threw, so `id`/`alreadyInFlight` carry NO information at all — the
+ * scrap could easily have prior (possibly terminal) history that this
+ * lookup simply never saw. Before this field existed, both cases produced
+ * the identical `{id: undefined, alreadyInFlight: false}` shape, so
+ * pollRunProgress could not tell them apart (see its own #97 comment).
+ */
 interface BeforeRunState {
     id?: string;
     alreadyInFlight: boolean;
+    captured: boolean;
 }
 /**
  * #91 P1 — replaces "await the run to completion, THEN open the activities
@@ -38,6 +49,35 @@ interface BeforeRunState {
  * (the dedup case) — a same-id row that was already TERMINAL at capture is
  * neither, and must not be latched onto as "done" (it's just the previous
  * run, still sitting there until a genuinely new run supersedes it).
+ *
+ * #97 — capture-failed fallback. The dedup-race fix above assumes `before`
+ * is trustworthy. When `captureBeforeRunState`'s own GET threw,
+ * `before.id` is `undefined` — and that is INDISTINGUISHABLE from "the
+ * scrap has genuinely never run" (also `id: undefined`), which is exactly
+ * the case `isNewRun` above is designed to match on the very first row that
+ * ever appears. So on the very first poll, ANY pre-existing history row —
+ * even the STALE PREVIOUS run, already terminal — satisfied
+ * `last._id !== undefined` and got reported as "the run we just launched"
+ * finishing, when it was really just whatever ran before.
+ *
+ * Fix: `before.captured === false` defers trusting a baseline at all.
+ * Instead of comparing against the (unknown) `beforeId` from the start, the
+ * FIRST successful poll read is treated as the deferred capture itself —
+ * exactly what `captureBeforeRunState` would have returned had its GET
+ * succeeded — and only READS from that point on are compared against it,
+ * via the exact same `isNewRun` / `isDedupOntoInFlight` logic above. A
+ * pre-existing terminal row observed on that first read becomes `beforeId`
+ * (not a match for itself), so it correctly falls into "still the stale
+ * previous run" below and the poll keeps waiting; a row still in flight
+ * becomes the `alreadyInFlight` baseline, exactly like a successful capture
+ * would have recorded. Either way this costs at most one extra poll
+ * interval, bounded by the same deadline as everything else. The one
+ * remaining edge case — capture failed AND the scrap never ran before AND
+ * the triggered run already finished by the very first poll — is genuinely
+ * undecidable from "stale pre-existing row" with no more information than
+ * 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`).
  */
 export declare function pollRunProgress(id: string, before: BeforeRunState | undefined, opts?: {
     intervalMs?: number;

package/dist/commands/scraps.js

@@ -7,6 +7,7 @@ import { promptPassword } from '../lib/prompt.js';
 import { validateObjectId } from '../lib/validate.js';
 import { classifyError, reportError, UsageError } from '../lib/errors.js';
 import { formatDoctor, formatAutofix, fetchRunAndFix, pickRun, pickFix } from './doctor.js';
+import { renderPinch, pinchEnabled } from '../lib/pinch.js';
 /**
  * Print a usage/validation error consistently: human text to stderr, or a
  * machine envelope on stdout under --json (never both — reportError is the
@@ -96,17 +97,21 @@ async function watchActivities(id) {
  * recognize that dedup case too, instead of waiting forever for an `_id`
  * that will never arrive (#93 item 1).
  *
- * Best-effort: a failed lookup falls back to `{alreadyInFlight:false}`,
- * which is still correct for a scrap that has never run (id undefined).
+ * #97 — a failed lookup used to fall back to `{alreadyInFlight:false}` with
+ * no `id`, which LOOKED identical to "scrap has never run" — but is not:
+ * the scrap may well have prior (possibly terminal) history this GET simply
+ * never observed. `captured:false` flags that distinction explicitly so
+ * pollRunProgress can defer trusting a baseline instead of risking a stale
+ * pre-existing row being reported as the run just launched.
  */
 async function captureBeforeRunState(id) {
     try {
         const scrap = await api.get(`/api/scraps/${id}`);
         const top = scrap.history?.[0];
-        return { id: top?._id, alreadyInFlight: top?.status === null };
+        return { id: top?._id, alreadyInFlight: top?.status === null, captured: true };
     }
     catch {
-        return { id: undefined, alreadyInFlight: false };
+        return { id: undefined, alreadyInFlight: false, captured: false };
     }
 }
 function sleep(ms) {
@@ -148,12 +153,46 @@ const POLL_TIMEOUT_MS = LONG_RUN_TIMEOUT_MS;
  * (the dedup case) — a same-id row that was already TERMINAL at capture is
  * neither, and must not be latched onto as "done" (it's just the previous
  * run, still sitting there until a genuinely new run supersedes it).
+ *
+ * #97 — capture-failed fallback. The dedup-race fix above assumes `before`
+ * is trustworthy. When `captureBeforeRunState`'s own GET threw,
+ * `before.id` is `undefined` — and that is INDISTINGUISHABLE from "the
+ * scrap has genuinely never run" (also `id: undefined`), which is exactly
+ * the case `isNewRun` above is designed to match on the very first row that
+ * ever appears. So on the very first poll, ANY pre-existing history row —
+ * even the STALE PREVIOUS run, already terminal — satisfied
+ * `last._id !== undefined` and got reported as "the run we just launched"
+ * finishing, when it was really just whatever ran before.
+ *
+ * Fix: `before.captured === false` defers trusting a baseline at all.
+ * Instead of comparing against the (unknown) `beforeId` from the start, the
+ * FIRST successful poll read is treated as the deferred capture itself —
+ * exactly what `captureBeforeRunState` would have returned had its GET
+ * succeeded — and only READS from that point on are compared against it,
+ * via the exact same `isNewRun` / `isDedupOntoInFlight` logic above. A
+ * pre-existing terminal row observed on that first read becomes `beforeId`
+ * (not a match for itself), so it correctly falls into "still the stale
+ * previous run" below and the poll keeps waiting; a row still in flight
+ * becomes the `alreadyInFlight` baseline, exactly like a successful capture
+ * would have recorded. Either way this costs at most one extra poll
+ * interval, bounded by the same deadline as everything else. The one
+ * remaining edge case — capture failed AND the scrap never ran before AND
+ * the triggered run already finished by the very first poll — is genuinely
+ * undecidable from "stale pre-existing row" with no more information than
+ * 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`).
  */
 export async function pollRunProgress(id, before, opts = {}) {
     const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
     const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
-    const beforeId = before?.id;
-    const beforeAlreadyInFlight = before?.alreadyInFlight ?? false;
+    let beforeId = before?.id;
+    let beforeAlreadyInFlight = before?.alreadyInFlight ?? false;
+    // #97 — only an EXPLICIT captured:false (capture's GET actually threw)
+    // defers the baseline. `before` itself being undefined (callers that skip
+    // 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'));
     const deadline = Date.now() + timeoutMs;
     const seen = new Set();
@@ -172,6 +211,16 @@ export async function pollRunProgress(id, before, opts = {}) {
         const last = scrap.history?.[0];
         if (!last?._id)
             continue; // no history row recorded yet
+        if (!baselineEstablished) {
+            // #97 — deferred capture: whatever we see on this first successful
+            // read becomes the reference point, BEFORE the isNewRun check below
+            // ever runs against it. This must happen before that check, not
+            // after, so a pre-existing terminal row is recognized as stale on
+            // this very same iteration rather than one poll late.
+            beforeId = last._id;
+            beforeAlreadyInFlight = last.status === null;
+            baselineEstablished = true;
+        }
         const isNewRun = last._id !== beforeId;
         const isDedupOntoInFlight = last._id === beforeId && beforeAlreadyInFlight;
         if (!isNewRun && !isDedupOntoInFlight)
@@ -194,6 +243,14 @@ 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'));
+            }
             return;
         }
     }

package/dist/index.d.ts

@@ -36,6 +36,15 @@ export declare function isEntryPoint(argv1: string | undefined, moduleUrl: strin
  * subcommand cases)
  */
 export declare function isHelpOrVersion(argv: string[]): boolean;
+/**
+ * True for a bare `trawl` invocation — no subcommand, no flags at all. This
+ * is the CLI's "first thing a new user sees" moment (commander prints its
+ * own top-level help right after), distinct from `isHelpOrVersion` which is
+ * intentionally broader (also matches `--help`/`--version`/`trawl help`
+ * anywhere in argv) — the Pinch wave banner (#94) only wants the narrowest
+ * case so it never shows up ahead of e.g. `trawl scraps --help`.
+ */
+export declare function isBareInvocation(argv: string[]): boolean;
 /** Best-effort scan for a `--json` flag in raw argv, used only when parsing
  * itself failed before any command's own `.opts()` could be resolved (a
  * commander usage error — unknown option/command, missing required arg). Same

package/dist/index.js

@@ -11,6 +11,7 @@ import { token } from './commands/token.js';
 import { autoUpdateInstalledSkills } from './lib/skills.js';
 import { initPostHog, captureCommand, shutdown, registerAllowedCommands } from './lib/posthog.js';
 import { classifyError, reportError } from './lib/errors.js';
+import { renderPinch, pinchEnabled } from './lib/pinch.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 /**
@@ -96,6 +97,17 @@ export function isHelpOrVersion(argv) {
         return true;
     return false;
 }
+/**
+ * True for a bare `trawl` invocation — no subcommand, no flags at all. This
+ * is the CLI's "first thing a new user sees" moment (commander prints its
+ * own top-level help right after), distinct from `isHelpOrVersion` which is
+ * intentionally broader (also matches `--help`/`--version`/`trawl help`
+ * anywhere in argv) — the Pinch wave banner (#94) only wants the narrowest
+ * case so it never shows up ahead of e.g. `trawl scraps --help`.
+ */
+export function isBareInvocation(argv) {
+    return argv.slice(2).length === 0;
+}
 /** Best-effort scan for a `--json` flag in raw argv, used only when parsing
  * itself failed before any command's own `.opts()` could be resolved (a
  * commander usage error — unknown option/command, missing required arg). Same
@@ -171,6 +183,12 @@ export function bestEffortCommandName(argv, allowedNames) {
 export async function runCli(argv = process.argv) {
     if (!isHelpOrVersion(argv))
         autoUpdateInstalledSkills();
+    // Pinch wave banner (#94) — bare `trawl` only, guarded so it never shows
+    // under NO_COLOR/non-TTY/piped output (pinchEnabled() covers all three).
+    if (isBareInvocation(argv) && pinchEnabled()) {
+        console.log(renderPinch('wave'));
+        console.log();
+    }
     initPostHog();
     const program = createProgram();
     // Must run before parseAsync — installs on every node in the tree,
@@ -270,6 +288,12 @@ export async function runCli(argv = process.argv) {
             // (stderr), never both; `quiet` skips the human line when the raw
             // stack was already dumped above under --debug.
             process.exitCode = reportError(err, { json: wantsJson, quiet: isDebug });
+            // Pinch confused frame (#94) — never under --json (stdout must stay
+            // pure JSON) and guarded by pinchEnabled() (NO_COLOR/non-TTY/piped).
+            // Printed to stderr, alongside reportError's own human line above.
+            if (!wantsJson && pinchEnabled()) {
+                console.error(renderPinch('confused'));
+            }
         }
     }
     finally {

package/dist/lib/pinch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pinch — Trawl's voxel lobster mascot, rendered as 24-bit ANSI half-block
+ * 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 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) 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
+ * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
+ * are transparent — no color escape is emitted for that half, so the
+ * terminal's own background shows through.
+ *
+ * See comes-io/trawl_cli#94.
+ */
+export type PinchState = 'wave' | 'thinking' | 'celebrating' | 'confused';
+/**
+ * Render Pinch as 24-bit ANSI half-block art for the given state, plus a
+ * one-line caption. Pure — never touches process.env/stdout; callers must
+ * gate on `pinchEnabled()` before printing the result.
+ *
+ * `frame` only affects 'thinking' (2-frame spinner alternation); every other
+ * state ignores it.
+ */
+export declare function renderPinch(state: PinchState, frame?: number): string;
+/**
+ * True when it's safe to print Pinch art: a real color-capable interactive
+ * terminal. False under NO_COLOR (https://no-color.org — presence, not
+ * value, disables color output), a non-TTY stdout (piped/redirected output —
+ * covers --json/--quiet/CI log capture), or TERM=dumb.
+ */
+export declare function pinchEnabled(): boolean;

package/dist/lib/pinch.js

@@ -0,0 +1,147 @@
+/**
+ * Pinch — Trawl's voxel lobster mascot, rendered as 24-bit ANSI half-block
+ * 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 12×9 cube-grid (AVGRID proto v11.4, locked 2026-07-16) 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
+ * 9-row grid therefore renders in 5 terminal rows, 12 columns wide. '.' cells
+ * are transparent — no color escape is emitted for that half, so the
+ * terminal's own background shows through.
+ *
+ * See comes-io/trawl_cli#94.
+ */
+/** Grid-char → RGB. 'C' (cyan) is a "thinking" blip, not present in BASE_GRID. */
+const PALETTE = {
+    B: [0x3b, 0x82, 0xf6], // blue — shell
+    O: [0xee, 0x90, 0x18], // orange — antennae / claws
+    W: [0xff, 0xff, 0xff], // white — eye whites
+    K: [0x12, 0x30, 0x33], // navy — pupils / mouth
+    P: [0xf9, 0xa8, 0xd4], // pink — claw tips
+    C: [0x08, 0x91, 0xb2], // cyan — thinking-spinner antenna blip
+};
+const TRANSPARENT = '.';
+/** Base 12×9 grid — Pinch waving (also the 'wave' state, unmodified). */
+const BASE_GRID = [
+    '...O....O...',
+    '...O....O...',
+    '.BBBBBBBBBB.',
+    '.BWWBBBBWWB.',
+    '.BWKBBBBKWB.',
+    '.PBBBBBBBBP.',
+    '.BBBKBBKBBB.',
+    '.BBBBKKBBBB.',
+    'OO........OO',
+];
+const CAPTIONS = {
+    wave: 'Pinch says hi.',
+    thinking: 'Pinch is thinking…',
+    celebrating: 'Pinch is celebrating!',
+    confused: 'Pinch looks confused.',
+};
+/** Replace the chars at `indices` in `row` with `ch` — never mutates `row`. */
+function setCells(row, indices, ch) {
+    const chars = row.split('');
+    for (const i of indices)
+        chars[i] = ch;
+    return chars.join('');
+}
+/** Derive the per-state grid from BASE_GRID (which is never mutated). */
+function gridForState(state, frame) {
+    const rows = [...BASE_GRID];
+    switch (state) {
+        case 'thinking':
+            // Odd frames: both antenna tips (row 0, cols 3 & 8) blip cyan — a
+            // 2-frame spinner alternation with no layout shift.
+            if (frame % 2 === 1) {
+                rows[0] = setCells(rows[0], [3, 8], 'C');
+            }
+            return rows;
+        case 'celebrating':
+            // Fists up: the row-8 corner claws move up to row 7's corners; row 8's
+            // corners go transparent (arms raised, no longer at the sides).
+            rows[7] = setCells(rows[7], [0, 11], 'O');
+            rows[8] = setCells(rows[8], [0, 1, 10, 11], TRANSPARENT);
+            return rows;
+        case 'confused':
+            // Pupils removed (row 4, cols 3 & 8) — blank white eyes.
+            rows[4] = setCells(rows[4], [3, 8], 'W');
+            return rows;
+        case 'wave':
+        default:
+            return rows;
+    }
+}
+const RESET = '\x1b[0m';
+const fgCode = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+const bgCode = ([r, g, b]) => `\x1b[48;2;${r};${g};${b}m`;
+/**
+ * One terminal column: combine an upper (fg-half) + lower (bg-half) grid
+ * cell into a single half-block character. Either half may be transparent
+ * independently — no bg/fg escape is emitted for a transparent half, so the
+ * terminal's own background/foreground shows through it.
+ */
+function renderCell(upper, lower) {
+    const upperColor = upper === TRANSPARENT ? null : PALETTE[upper];
+    const lowerColor = lower === TRANSPARENT ? null : PALETTE[lower];
+    if (!upperColor && !lowerColor)
+        return ' ';
+    // Lower half transparent — draw the upper half-block with fg only, no bg
+    // (the glyph's own unpainted lower half already shows the terminal bg).
+    if (!lowerColor)
+        return `${fgCode(upperColor)}▀${RESET}`;
+    // Upper half transparent — draw the LOWER half-block glyph instead, with
+    // fg set to the lower color and no bg, so the painted half is the bottom.
+    if (!upperColor)
+        return `${fgCode(lowerColor)}▄${RESET}`;
+    return `${fgCode(upperColor)}${bgCode(lowerColor)}▀${RESET}`;
+}
+/** Pack a 9-row grid into 5 terminal lines (rows 0-1, 2-3, 4-5, 6-7, 8-blank). */
+function renderGrid(rows) {
+    const lines = [];
+    for (let i = 0; i < rows.length; i += 2) {
+        const upperRow = rows[i];
+        const lowerRow = rows[i + 1] ?? TRANSPARENT.repeat(upperRow.length);
+        let line = '';
+        for (let c = 0; c < upperRow.length; c++) {
+            line += renderCell(upperRow[c], lowerRow[c]);
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/**
+ * Render Pinch as 24-bit ANSI half-block art for the given state, plus a
+ * one-line caption. Pure — never touches process.env/stdout; callers must
+ * gate on `pinchEnabled()` before printing the result.
+ *
+ * `frame` only affects 'thinking' (2-frame spinner alternation); every other
+ * state ignores it.
+ */
+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 (grid rows
+        // 4-5 pack into terminal line index 2).
+        lines[2] = `${lines[2]}  \x1b[1m?${RESET}`;
+    }
+    return [...lines, CAPTIONS[state]].join('\n');
+}
+/**
+ * True when it's safe to print Pinch art: a real color-capable interactive
+ * terminal. False under NO_COLOR (https://no-color.org — presence, not
+ * value, disables color output), a non-TTY stdout (piped/redirected output —
+ * covers --json/--quiet/CI log capture), or TERM=dumb.
+ */
+export function pinchEnabled() {
+    if (process.env['NO_COLOR'] !== undefined)
+        return false;
+    if (!process.stdout.isTTY)
+        return false;
+    if (process.env['TERM'] === 'dumb')
+        return false;
+    return true;
+}

package/package.json

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