@pify/shell-background 0.4.2 → 0.5.1

package/README.md

@@ -54,17 +54,22 @@ Put these in `.pi/shell-background.json` (project) or `<agentDir>/shell-backgrou
 {
   "autoBackgroundMs": 30000,
   "tailBytes": 65536,
+  "tailLines": 200,
   "maxBackground": 8
 }
 ```
 
-`autoBackgroundMs` is how long a foreground command may run before it auto-backgrounds; set it to `0` to disable auto-background (explicit `background: true` still works). `PIFY_SHELL_BG_MS` overrides it for one run or in CI. `tailBytes` bounds how much of a job's log a status result shows. `maxBackground` bounds how many jobs may be alive at once: over it, a `background: true` request is refused with a message naming the limit (the command can still run in the foreground), and a command that crosses the auto-background threshold simply stays in the foreground instead of moving — a command is never refused, only the decision to background it. Bad values fall back to the defaults with a warning rather than taking the tool down.
+`autoBackgroundMs` is how long a foreground command may run before it auto-backgrounds; set it to `0` to disable auto-background (explicit `background: true` still works). `PIFY_SHELL_BG_MS` overrides it for one run or in CI. `tailBytes` bounds how much of a job's log a status result reads; `tailLines` bounds how many lines of it the model is shown (0 disables the line shrink). `maxBackground` bounds how many jobs may be alive at once: over it, a `background: true` request is refused with a message naming the limit (the command can still run in the foreground), and a command that crosses the auto-background threshold simply stays in the foreground instead of moving — a command is never refused, only the decision to background it. Bad values fall back to the defaults with a warning rather than taking the tool down.
 
 Since pi 0.99 the bash tool also returns a machine-readable result — `structuredContent` — which codemode scripts and tools calling `ctx.executeTool("bash", …)` receive instead of the text. This package keeps pi's shape so such a script reads either tool unchanged: `output` (the whole log, up to 1 MiB, head and tail around an omission marker), `truncated`, `full_output_path`, `exit_code`, `wall_time_seconds` — plus `status` and `job_id`, because a command here can still be running when the tool returns; then `exit_code` is absent and `shell_status {id}` collects it, with the same structured result.
 
 A backgrounded command runs with no one to answer it, so its environment says so: `GIT_TERMINAL_PROMPT=0` and `GIT_EDITOR`/`EDITOR`/`VISUAL=true` are forced (a `git commit` without `-m` fails with "empty message" instead of waiting on an editor that never comes, and an https `git fetch` fails instead of prompting for a password), and pagers default to `cat` unless you set them. `CI` and `TERM` are left alone on purpose — dev servers and watchers read them.
 
-The tail a result carries is cleaned the way pi's own bash cleans what the model sees — ANSI escapes, control characters and carriage-return progress frames stripped — so a chatty build or dev server does not spend tokens on colour codes and thousands of overwritten progress lines. The log file on disk keeps every byte.
+The tail a result carries is cleaned the way pi's own bash cleans what the model sees — ANSI escapes and control characters stripped — with two improvements borrowed from caveman's log compressors. A carriage-return redraw is **resolved to its last frame** rather than having the `\r` deleted: pi's own cleaning keeps every frame's text, so a 2000-frame progress bar arrives as one line holding all 2000 frames; here it arrives as `1999/2000`. And a long result is **shrunk by lines, not bytes**: the first and last lines are kept, every line that names trouble (`error`, `FAILED`, `Traceback`, `at …`, `File "…"`, `path:12:5:`, `FooError`, `caused by`, `exit status 1`) is kept wherever it sits, and the rest collapses into markers that count what they replaced — `[… 412 lines omitted (INFO ×380, DEBUG ×29) …]` — computed from exactly those lines. A byte window kept the *end* of a build log, where the summary is; a line window with that regex keeps the failing step in the middle too. Runs under three lines are shown as they are (a marker in place of one line only reads as a hole), the markers are recognised on a later poll so a shrunk result re-serialises identically (the provider prefix cache depends on it), and one note names what was left out and where the whole log is. The line shrink is guarded against truncating a *distinct* document: before a run of lines is collapsed, one representative of every kind of line a surviving line does not already resemble is kept (caveman's redundancy guard, vocabulary-containment with digit masking so lines differing only in a timestamp count as one). So a 50k-line repetitive build log collapses hard, while a 50k-line document where every line is distinct is kept and the shrink reports no win — the honest outcome rather than a silent deletion.
+
+A whole JSON test report in the tail — `pytest --json-report`, `jest --json` — is rendered as counts plus every failure with its stack trimmed to the first three and last two frames (`TEST SUMMARY: 240 passed, 3 failed` then each `FAILED: …`), instead of the raw document. Detection is on the exact top-level keys, so ordinary JSON is untouched; a truncated report is not valid JSON and falls through to the line view; the full report stays on disk. (JUnit XML lands in a file rather than on stdout and is left alone.)
+
+A log that cannot be read says `(log unavailable: …)` rather than `(no output)`, which would send the model polling for output that will never come. The log file on disk keeps every byte.
 
 ## Coexistence with @pify/pretty
 

package/extensions/shell-background.ts

@@ -208,7 +208,7 @@ export default function shellBackground(pi: ExtensionAPI) {
 
   function finished(job: Job): ToolResult {
     return {
-      content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
+      content: [{ type: "text", text: formatResult(job, settings.tailBytes, settings.tailLines) }],
       details: { id: job.id, status: job.status, exitCode: job.exitCode, signal: job.signal, background: false },
       structuredContent: structured(job),
       isError: job.status === "failed",
@@ -221,7 +221,7 @@ export default function shellBackground(pi: ExtensionAPI) {
     pi.sendMessage(
       {
         customType: DELIVERY_TYPE,
-        content: deliveryMessage(job.id, formatResult(job, settings.tailBytes)),
+        content: deliveryMessage(job.id, formatResult(job, settings.tailBytes, settings.tailLines)),
         display: true,
         details: { id: job.id, status: job.status, exitCode: job.exitCode },
       },
@@ -432,7 +432,7 @@ export default function shellBackground(pi: ExtensionAPI) {
             {
               type: "text",
               text:
-                formatResult(job, settings.tailBytes) +
+                formatResult(job, settings.tailBytes, settings.tailLines) +
                 `\n\n[kill signal sent; process had not exited after 3s — shell_status ${job.id} to confirm]`,
             },
           ],
@@ -446,7 +446,7 @@ export default function shellBackground(pi: ExtensionAPI) {
           ? `\n\n[killed: exceeded the ${params.timeout}s timeout]`
           : `\n\n[killed: the turn was aborted]`;
       return {
-        content: [{ type: "text", text: formatResult(job, settings.tailBytes) + note }],
+        content: [{ type: "text", text: formatResult(job, settings.tailBytes, settings.tailLines) + note }],
         details: { id: job.id, status: job.status },
         structuredContent: structured(job),
         isError: true,
@@ -559,7 +559,7 @@ export default function shellBackground(pi: ExtensionAPI) {
         registry.persist(job);
       }
       return {
-        content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
+        content: [{ type: "text", text: formatResult(job, settings.tailBytes, settings.tailLines) }],
         details: { id: job.id, status: job.status, exitCode: job.exitCode },
         structuredContent: structured(job),
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/shell-background",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Long-running bash goes async: background: true launches detached, and any command still running after 30s auto-backgrounds and delivers its result when it finishes",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -14,6 +14,12 @@ export interface ShellBgSettings {
   autoBackgroundMs: number;
   /** Bytes of the log tail shown in a status/collect result. */
   tailBytes: number;
+  /**
+   * Lines a result may carry before it is shrunk: first and last lines kept,
+   * every error/warning line kept wherever it sits, the rest collapsed into
+   * counted markers. 0 disables shrinking (the byte tail is still the cap).
+   */
+  tailLines: number;
   /**
    * How many jobs may be alive at once before a request to background one
    * more is refused and an auto-background transition is skipped. Every live
@@ -28,6 +34,7 @@ export interface ShellBgSettings {
 export const DEFAULT_SETTINGS: ShellBgSettings = {
   autoBackgroundMs: 30_000,
   tailBytes: 64 * 1024,
+  tailLines: 200,
   maxBackground: 8,
 };
 
@@ -36,6 +43,7 @@ const LIMITS: Record<keyof ShellBgSettings, { min: number; max: number }> = {
   // does not make every command look long-running.
   autoBackgroundMs: { min: 0, max: 3_600_000 },
   tailBytes: { min: 1024, max: 4 * 1024 * 1024 },
+  tailLines: { min: 0, max: 5000 },
   maxBackground: { min: 1, max: 64 },
 };
 

package/src/format.ts

@@ -3,8 +3,14 @@
  * job and a tail, produce the string — the extension supplies both.
  */
 import type { Job } from "./types.ts";
-import { readTail, countLines } from "./tail.ts";
+import { readTail } from "./tail.ts";
 import { sanitizeOutput } from "./sanitize.ts";
+import { DEFAULT_SHRINK, shrinkLines } from "./shrink.ts";
+import { parseTestReport, renderTestReport } from "./testreport.ts";
+
+function kb(bytes: number): string {
+  return bytes < 1024 * 1024 ? `${Math.max(1, Math.round(bytes / 1024))}KB` : `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
 
 function secs(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
@@ -34,22 +40,47 @@ export function header(job: Job): string {
 /**
  * The full result of a finished (or polled) job: the header, then the tail of
  * its output, with an honest note when output was truncated and where the whole
- * log lives.
+ * log lives. The tail is read as bytes (`tailBytes`), cleaned, and then shrunk
+ * by lines (`tailLines`): first and last lines kept, every error/warning line
+ * kept wherever it sits, the rest collapsed into counted markers — so a long
+ * build's failing step survives in the middle instead of only its summary at
+ * the end. The log on disk keeps every byte, and the note says where it is.
  */
-export function formatResult(job: Job, tailBytes: number): string {
+export function formatResult(job: Job, tailBytes: number, tailLines: number = DEFAULT_SHRINK.maxLines): string {
   const tail = readTail(job.logPath, tailBytes);
-  // Cleaned the way pi's own bash cleans its output for the model; the log on
-  // disk (which the truncation note points at) keeps every byte.
-  const text = sanitizeOutput(tail.text);
   const lines = [header(job)];
+  if (tail.missing) {
+    // A log that cannot be read is not a command that printed nothing: say so,
+    // or the model keeps polling for output that will never come.
+    lines.push(`(log unavailable: ${job.logPath} could not be read)`);
+    return lines.join("\n");
+  }
+  // Cleaned the way pi's own bash cleans its output for the model; the log on
+  // disk (which the note points at) keeps every byte.
+  const text = sanitizeOutput(tail.text).replace(/\n+$/, "");
   if (text.trim() === "") {
     lines.push(job.status === "running" ? "(no output yet)" : "(no output)");
-  } else {
-    if (tail.truncated) {
-      lines.push(`… showing the last ${countLines(text)} lines — full log: ${job.logPath}`);
+    return lines.join("\n");
+  }
+  // A whole JSON test report (pytest --json-report, jest --json) read from the
+  // tail becomes counts + every failure. Only when the tail holds the whole
+  // document — a truncated one is not valid JSON and falls through to the
+  // line view. The full report stays on disk.
+  if (!tail.truncated) {
+    const report = parseTestReport(text);
+    if (report) {
+      lines.push(renderTestReport(report));
+      return lines.join("\n");
     }
-    lines.push(text.replace(/\n+$/, ""));
   }
+  const shrunk = shrinkLines(text, { maxLines: tailLines, tail: Math.max(DEFAULT_SHRINK.tail, Math.floor(tailLines / 2)) });
+  const notes: string[] = [];
+  if (shrunk.omitted > 0) {
+    notes.push(`${shrunk.omitted} of ${shrunk.total} lines omitted, none with an error or warning (those are kept wherever they sit)`);
+  }
+  if (tail.truncated) notes.push(`this is the last ${kb(Buffer.byteLength(tail.text, "utf8"))} of a ${kb(tail.bytes)} log`);
+  if (notes.length > 0) lines.push(`… ${notes.join("; ")} — full log: ${job.logPath}`);
+  lines.push(shrunk.text);
   return lines.join("\n");
 }
 

package/src/redundancy.ts

@@ -0,0 +1,127 @@
+/**
+ * The guard that separates *eliding repetition* from *truncating a document*.
+ * A faithful port of caveman's keepNonRedundant (JuliusBrussee/caveman,
+ * engine/compressors/redundancy.go).
+ *
+ * The line shrink (shrink.ts) keeps the head, the tail, and every line that
+ * names trouble, and collapses the rest. On a build log that is the right
+ * call: the dropped lines are repeated chunk/step noise, each represented by
+ * a surviving one. On a 50k-line document where every line is distinct — a
+ * bibliography, a generated source file — the same transform would silently
+ * delete most of the content. This gate runs before the collapse: a line
+ * about to be dropped is KEPT when no surviving line already resembles it, so
+ * a distinct document retains a representative of every kind of line and only
+ * true repetition is elided. Deterministic (prefix cache), bounded (the work
+ * is the same on a 200-line and a 20,000-line payload), pure.
+ */
+
+const CONTAINMENT = 0.9; // a dropped line's vocabulary a survivor must carry to represent it
+const MAX_CLASSES = 64; // kept lines sampled to seed the represented classes
+const MAX_PROMOTIONS = 128; // first-of-kind lines kept before the payload is declared a document
+const MAX_UNIT_TOKENS = 128; // vocabulary built per line, so one long line cannot make this quadratic
+const MIN_WORD_TOKENS = 1; // letter-bearing tokens a line needs before its digits are masked
+
+interface Profile {
+  vocab: Set<string>;
+  masked: boolean;
+}
+
+/**
+ * A line reduced to its word/number tokens, every run of digits optionally
+ * collapsed to `#`. Masking lets two log lines that differ only in a timestamp
+ * recognise each other; a line with no words keeps its digits, because there
+ * the numbers ARE the content (`['1973.', 251]` must not match `['1974.', 260]`).
+ */
+function tokenize(unit: string, maskDigits: boolean): { vocab: Set<string>; words: number } {
+  const vocab = new Set<string>();
+  let words = 0;
+  let token = "";
+  let hasLetter = false;
+  let inDigits = false;
+  const flush = () => {
+    if (token.length > 0 && !vocab.has(token)) {
+      vocab.add(token);
+      if (hasLetter) words++;
+    }
+    token = "";
+    hasLetter = false;
+    inDigits = false;
+  };
+  for (const ch of unit.toLowerCase()) {
+    if (ch >= "0" && ch <= "9") {
+      if (maskDigits) {
+        if (!inDigits) {
+          token += "#";
+          inDigits = true;
+        }
+      } else {
+        token += ch;
+        inDigits = false;
+      }
+    } else if (/[a-z_]/.test(ch) || (ch.toLowerCase() !== ch.toUpperCase())) {
+      token += ch;
+      hasLetter = true;
+      inDigits = false;
+    } else {
+      flush();
+    }
+    if (vocab.size >= MAX_UNIT_TOKENS) return { vocab, words };
+  }
+  flush();
+  return { vocab, words };
+}
+
+function unitVocabulary(unit: string): Profile {
+  const masked = tokenize(unit, true);
+  if (masked.words >= MIN_WORD_TOKENS) return { vocab: masked.vocab, masked: true };
+  return { vocab: tokenize(unit, false).vocab, masked: false };
+}
+
+function representedBy(dropped: Profile, classes: Profile[]): boolean {
+  if (dropped.vocab.size === 0) return true; // punctuation-only line carries nothing to lose
+  const need = Math.ceil(CONTAINMENT * dropped.vocab.size - 1e-9);
+  for (const cls of classes) {
+    if (cls.masked !== dropped.masked) continue;
+    let hit = 0;
+    for (const token of dropped.vocab) {
+      if (cls.vocab.has(token)) {
+        hit++;
+        if (hit >= need) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Promote back to kept any not-yet-kept line that no surviving line
+ * represents. Mutates `keep` in place, in document order.
+ */
+export function keepNonRedundant(units: readonly string[], keep: boolean[]): void {
+  if (units.length !== keep.length) return;
+  const kept: number[] = [];
+  for (let i = 0; i < keep.length; i++) if (keep[i]) kept.push(i);
+
+  const classes: Profile[] = [];
+  const step = kept.length > MAX_CLASSES ? Math.floor(kept.length / MAX_CLASSES) : 1;
+  for (let n = 0; n < kept.length && classes.length < MAX_CLASSES; n += step) {
+    classes.push(unitVocabulary(units[kept[n]!]!));
+  }
+
+  let promotions = 0;
+  for (let i = 0; i < units.length; i++) {
+    if (keep[i]) continue;
+    if (promotions >= MAX_PROMOTIONS) {
+      // More distinct kinds of line than any repetitive stream has: a document.
+      // Keep the rest; the caller's "did this actually shrink?" check then
+      // passes the original through. Prefer the honest zero.
+      keep[i] = true;
+      continue;
+    }
+    const vocab = unitVocabulary(units[i]!);
+    if (representedBy(vocab, classes)) continue;
+    keep[i] = true;
+    promotions++;
+    classes.push(vocab);
+  }
+}

package/src/sanitize.ts

@@ -1,6 +1,10 @@
 /**
- * The same cleaning pi's own bash tool applies to what the model sees
- * (bash-executor.ts: `sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "")`).
+ * The cleaning pi's own bash tool applies to what the model sees
+ * (bash-executor.ts: `sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "")`),
+ * with one improvement: a carriage return is resolved, not deleted. pi drops
+ * the `\r` and keeps every progress frame's text, so a 2000-frame webpack bar
+ * arrives as one line holding all 2000 frames; here only the last frame of
+ * each line survives, which is what the terminal showed (see shrink.ts).
  *
  * This package re-registers `bash`, and a job's log is captured raw on disk on
  * purpose (the detached spawn writes straight to a file; no in-process pipes).
@@ -12,6 +16,8 @@
  * vendored here verbatim.
  */
 
+import { collapseCarriageReturns } from "./shrink.ts";
+
 // Valid string terminator sequences are BEL, ESC\, and 0x9c
 const ST = "(?:\\u0007|\\u001B\\u005C|\\u009C)";
 // OSC sequences only: ESC ] ... ST (non-greedy until the first ST)
@@ -44,7 +50,7 @@ export function sanitizeBinaryOutput(text: string): string {
     .join("");
 }
 
-/** Exactly what pi's bash gives the model: no ANSI, no control noise, no `\r`. */
+/** What pi's bash gives the model — no ANSI, no control noise — with `\r` redraws collapsed to their last frame. */
 export function sanitizeOutput(text: string): string {
-  return sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "");
+  return sanitizeBinaryOutput(collapseCarriageReturns(stripAnsi(text)));
 }

package/src/shrink.ts

@@ -0,0 +1,131 @@
+/**
+ * A long log, shrunk the way a person skims it: the first lines, the last
+ * lines, and every line that looks like trouble wherever it sits — the rest
+ * collapsed into counted markers. Adapted from caveman's log/terminal
+ * compressors (JuliusBrussee/caveman, engine/compressors/{log,terminal}.go):
+ * a byte window keeps the END of a build log, which is exactly where the
+ * summary is and not where the failing step was; a line window with an
+ * importance regex keeps both.
+ *
+ * Rules that matter, kept from the original:
+ * - an important line is never elided, no matter where it sits;
+ * - a run of fewer than 3 dropped lines is emitted verbatim — a marker that
+ *   replaces one line costs about what the line cost and reads as a hole;
+ * - a marker states facts computed from exactly the lines it replaces (their
+ *   log levels, counted), never a guess;
+ * - markers are recognised on re-entry and kept, so shrinking a shrunk text
+ *   is byte-identical — a result that re-serialises differently on a later
+ *   poll busts the provider's prefix cache.
+ * Pure; zero dependencies.
+ */
+
+/** Words that mark trouble, case-insensitive (`error:`, `FAILED`, `Traceback`). */
+const IMPORTANT_WORDS =
+  /\b(?:ERROR|FATAL|PANIC|EXCEPTION|TRACEBACK|FAIL|FAILED|FAILURE|WARN|WARNING|CRIT|CRITICAL|ALERT|EMERG|EMERGENCY)\b|^\s+at\s|^\s+File "|:\d+:\d+:|^\s*--->|caused by|\bexit (?:status|code) [1-9]/i;
+/** camelCase error types a bare ERROR never matches: AssertionError, ValueError, NullPointerException. Case-sensitive on purpose (not "terror"). */
+const CAMEL_ERROR = /\b[A-Za-z]+(?:Error|Exception)\b/;
+/** A log level token, for the marker's counts. */
+const LEVEL = /\b(TRACE|DEBUG|INFO|NOTICE|WARN|WARNING|ERROR|FATAL)\b/i;
+/** A marker this module wrote earlier; kept as-is on re-entry. */
+export const MARKER_RE = /^\[… \d+ lines omitted/;
+
+export function isImportantLine(line: string): boolean {
+  return IMPORTANT_WORDS.test(line) || CAMEL_ERROR.test(line) || MARKER_RE.test(line);
+}
+
+/**
+ * A bare carriage return rewinds the cursor: `10%\r20%\r100% done` only ever
+ * displayed `100% done`, and the earlier frames are visual history. Deleting
+ * the `\r` instead (what pi's own bash does) concatenates every frame into
+ * one enormous line. Keep the last non-empty segment of each line. A CRLF
+ * line ending leaves an empty final segment, so the content before it wins.
+ */
+export function collapseCarriageReturns(text: string): string {
+  if (!text.includes("\r")) return text;
+  return text
+    .split("\n")
+    .map((line) => {
+      if (!line.includes("\r")) return line;
+      let chosen = "";
+      for (const segment of line.split("\r")) if (segment.length > 0) chosen = segment;
+      return chosen;
+    })
+    .join("\n");
+}
+
+export interface ShrinkOptions {
+  /** Lines kept from the start. */
+  head?: number;
+  /** Lines kept from the end. */
+  tail?: number;
+  /** Texts of at most this many lines are returned untouched; 0 disables shrinking. */
+  maxLines?: number;
+}
+
+export interface Shrunk {
+  text: string;
+  /** Lines replaced by markers. */
+  omitted: number;
+  /** Lines in the input. */
+  total: number;
+}
+
+import { keepNonRedundant } from "./redundancy.ts";
+
+export const DEFAULT_SHRINK: Required<ShrinkOptions> = { head: 3, tail: 100, maxLines: 200 };
+
+function levelSummary(lines: string[]): string {
+  const counts = new Map<string, number>();
+  for (const line of lines) {
+    const m = LEVEL.exec(line);
+    if (!m) continue;
+    const key = m[1]!.toUpperCase();
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  if (counts.size === 0) return "";
+  // Every level seen, never a partial list; most frequent first, ties by name.
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([level, n]) => `${level} ×${n}`)
+    .join(", ");
+}
+
+function marker(run: number, dropped: string[]): string {
+  const summary = levelSummary(dropped);
+  return `[… ${run} lines omitted${summary ? ` (${summary})` : ""} …]`;
+}
+
+export function shrinkLines(text: string, opts: ShrinkOptions = {}): Shrunk {
+  const head = Math.max(0, opts.head ?? DEFAULT_SHRINK.head);
+  const tail = Math.max(0, opts.tail ?? DEFAULT_SHRINK.tail);
+  const maxLines = opts.maxLines ?? DEFAULT_SHRINK.maxLines;
+  const lines = text.split("\n");
+  const total = lines.length;
+  if (maxLines <= 0 || total <= maxLines) return { text, omitted: 0, total };
+  const keep = lines.map((line, i) => i < head || i >= total - tail || isImportantLine(line));
+  // Before collapsing, keep one representative of every DISTINCT line a run is
+  // about to drop, so a document of unique lines is not truncated — only true
+  // repetition is elided (caveman's redundancy guard).
+  keepNonRedundant(lines, keep);
+  const out: string[] = [];
+  let omitted = 0;
+  let i = 0;
+  while (i < total) {
+    if (keep[i]) {
+      out.push(lines[i]!);
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < total && !keep[j]) j++;
+    const run = j - i;
+    if (run < 3) {
+      for (let k = i; k < j; k++) out.push(lines[k]!);
+    } else {
+      out.push(marker(run, lines.slice(i, j)));
+      omitted += run;
+    }
+    i = j;
+  }
+  return { text: out.join("\n"), omitted, total };
+}

package/src/tail.ts

@@ -20,6 +20,8 @@ export interface Tail {
   truncated: boolean;
   /** Total size of the file in bytes. */
   bytes: number;
+  /** True when the log could not be opened at all — distinct from a command that printed nothing. */
+  missing?: boolean;
 }
 
 export const DEFAULT_TAIL_BYTES = 64 * 1024;
@@ -29,7 +31,7 @@ export function readTail(path: string, maxBytes: number = DEFAULT_TAIL_BYTES): T
   try {
     fd = openSync(path, "r");
   } catch {
-    return { text: "", truncated: false, bytes: 0 };
+    return { text: "", truncated: false, bytes: 0, missing: true };
   }
   try {
     const size = fstatSync(fd).size;

package/src/testreport.ts

@@ -0,0 +1,158 @@
+/**
+ * A machine-readable test report, rendered as counts plus every failure.
+ * Ported from caveman's test-report compressor (JuliusBrussee/caveman,
+ * engine/compressors/testreport.go), narrowed to the two JSON shapes a bash
+ * command actually prints to stdout: pytest-json-report and Jest `--json`.
+ * (JUnit XML lands in a file, not on stdout, and parsing it well needs an XML
+ * dependency this package does not take.)
+ *
+ * No failure is ever dropped: the summary counts every outcome, and each
+ * failure keeps its name, message and a stack trimmed to its first three and
+ * last two frames. Detection gates on the exact top-level keys, so ordinary
+ * JSON that merely mentions them is left to the normal tail. Pure; the full
+ * log stays on disk for recovery.
+ */
+
+export interface TestReport {
+  passed: number;
+  failed: number;
+  skipped: number;
+  errors: number;
+  duration?: number;
+  other: Record<string, number>;
+  failures: Array<{ name: string; message: string; type: "failure" | "error"; stack: string[] }>;
+}
+
+/** Keep a stack's first 3 and last 2 real frames, only when that drops at least 3. */
+export function trimStack(frames: string[]): string[] {
+  const clean = frames
+    .map((f) => f.trim())
+    .filter((f) => f !== "" && (/^at /.test(f) || /\.(py|java|js|ts|rb|go):/.test(f)));
+  if (clean.length < 8) return clean;
+  return [...clean.slice(0, 3), `... (${clean.length - 5} frames omitted)`, ...clean.slice(-2)];
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+function parsePytest(doc: Record<string, unknown>): TestReport | null {
+  if (!Array.isArray(doc.tests)) return null;
+  const r: TestReport = { passed: 0, failed: 0, skipped: 0, errors: 0, duration: num(doc.duration) || undefined, other: {}, failures: [] };
+  for (const t of doc.tests) {
+    if (!t || typeof t !== "object") continue;
+    const test = t as Record<string, unknown>;
+    const outcome = typeof test.outcome === "string" ? test.outcome : "";
+    const stageRepr = (name: string): string => {
+      const stage = test[name];
+      const lr = stage && typeof stage === "object" ? (stage as Record<string, unknown>).longrepr : undefined;
+      return typeof lr === "string" ? lr : "";
+    };
+    const longrepr = stageRepr("call") || stageRepr("setup") || stageRepr("teardown");
+    const nodeid = typeof test.nodeid === "string" ? test.nodeid : "(unknown)";
+    if (outcome === "passed") r.passed++;
+    else if (outcome === "skipped") r.skipped++;
+    else if (outcome === "failed" || outcome === "error") {
+      const isError = outcome === "error";
+      isError ? r.errors++ : r.failed++;
+      let message = "";
+      const stack: string[] = [];
+      for (const raw of longrepr.split("\n")) {
+        const line = raw.trim();
+        if (!line) continue;
+        if (!isError && line.startsWith("E ")) {
+          if (!message) message = line.slice(2).trim();
+        } else if (line.includes(".py:") || line.startsWith("at ")) stack.push(line);
+        else if (isError && !message && !line.includes(".py:")) message = line;
+      }
+      r.failures.push({ name: nodeid, message, type: isError ? "error" : "failure", stack: trimStack(stack) });
+    } else if (outcome) r.other[outcome] = (r.other[outcome] ?? 0) + 1;
+  }
+  return r;
+}
+
+function parseJest(doc: Record<string, unknown>): TestReport | null {
+  if (!Array.isArray(doc.testResults)) return null;
+  const r: TestReport = {
+    passed: num(doc.numPassedTests),
+    failed: num(doc.numFailedTests),
+    skipped: num(doc.numPendingTests),
+    errors: 0,
+    other: {},
+    failures: [],
+  };
+  for (const suite of doc.testResults) {
+    const results = suite && typeof suite === "object" ? (suite as Record<string, unknown>).assertionResults : undefined;
+    if (!Array.isArray(results)) continue;
+    for (const a of results) {
+      if (!a || typeof a !== "object") continue;
+      const test = a as Record<string, unknown>;
+      if (test.status !== "failed") continue;
+      const ancestors = Array.isArray(test.ancestorTitles) ? (test.ancestorTitles as unknown[]).map(String) : [];
+      const title = typeof test.title === "string" ? test.title : "";
+      const name = (typeof test.fullName === "string" && test.fullName) || [...ancestors, title].filter(Boolean).join(" › ") || "(unnamed)";
+      let message = "";
+      const stack: string[] = [];
+      const msgs = Array.isArray(test.failureMessages) ? test.failureMessages : [];
+      if (msgs.length > 0 && typeof msgs[0] === "string") {
+        for (const raw of (msgs[0] as string).split("\n")) {
+          const line = raw.trim();
+          if (!line) continue;
+          if (line.startsWith("at ") || line.includes(".test.") || line.includes(".spec.")) stack.push(line);
+          else if (!message) message = line;
+        }
+      }
+      r.failures.push({ name, message, type: "failure", stack: trimStack(stack) });
+    }
+  }
+  return r;
+}
+
+/** Parse a JSON test report, or null when the text is not one. Detection is on exact top-level keys. */
+export function parseTestReport(text: string): TestReport | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{")) return null;
+  // Byte pre-check so ordinary JSON is not parsed twice.
+  if (!trimmed.includes('"exitcode"') && !trimmed.includes('"numFailedTests"')) return null;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  const top = doc as Record<string, unknown>;
+  const report = "exitcode" in top && Array.isArray(top.tests) ? parsePytest(top)
+    : "numFailedTests" in top && Array.isArray(top.testResults) ? parseJest(top)
+    : null;
+  if (!report) return null;
+  const total = report.passed + report.failed + report.skipped + report.errors + Object.values(report.other).reduce((a, b) => a + b, 0);
+  return total === 0 ? null : report;
+}
+
+export function renderTestReport(r: TestReport): string {
+  const parts: string[] = [];
+  if (r.passed > 0) parts.push(`${r.passed} passed`);
+  if (r.failed > 0) parts.push(`${r.failed} failed`);
+  if (r.errors > 0) parts.push(`${r.errors} errors`);
+  if (r.skipped > 0) parts.push(`${r.skipped} skipped`);
+  for (const name of Object.keys(r.other).sort()) parts.push(`${r.other[name]} ${name}`);
+  let out = `TEST SUMMARY: ${parts.join(", ")}`;
+  if (r.duration && r.duration > 0) out += ` (${r.duration.toFixed(1)}s)`;
+  for (const f of r.failures) {
+    out += `\n\n${f.type === "error" ? "ERROR" : "FAILED"}: ${f.name}`;
+    if (f.message) for (const line of f.message.trim().split("\n")) out += `\n  ${line}`;
+    for (const frame of f.stack) out += `\n  ${frame}`;
+  }
+  return out;
+}
+
+/** `N failed, M passed`-style summary, or null — for a one-line collapsed row. */
+export function testCountLine(r: TestReport): string {
+  const parts: string[] = [];
+  if (r.failed > 0) parts.push(`${r.failed} failed`);
+  if (r.errors > 0) parts.push(`${r.errors} errors`);
+  if (r.passed > 0) parts.push(`${r.passed} passed`);
+  if (r.skipped > 0) parts.push(`${r.skipped} skipped`);
+  return parts.join(", ");
+}