@pi-archimedes/subagent 2.10.4 → 2.11.1

package/src/row-block.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Unit tests for the row primitives the subagent rows are drawn with.
+ *
+ * The two properties worth pinning down, both learned by measuring pi-tui:
+ *
+ *   * `truncateToWidth` puts the ellipsis **after** a colour reset
+ *     (`…\x1b[0m…` → `\x1b[0m...\x1b[0m`), so a truncated span loses the colour
+ *     of the span it belongs to. That is why the rows do not use it for the
+ *     ellipsis — see the "why not truncateToWidth" test, which pins the measured
+ *     bytes so the claim cannot quietly rot.
+ *   * `sliceByColumn` cuts on display cells (wide glyphs and emoji included) and
+ *     leaves the ANSI state open at the cut, so a plain `"..."` appended after
+ *     it inherits the style that was active where the line was cut.
+ */
+
+import { describe, it, expect } from "vitest";
+import { Box, Text, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { RowBlock, block, row, truncateRow, RESET } from "./row-block.js";
+
+const dim = (t: string) => `\x1b[2m${t}${RESET}`;
+const bold = (t: string) => `\x1b[1m${t}${RESET}`;
+
+const drawn = (line: string) => visibleWidth(stripTerminalSequences(line).replace(/\s+$/, ""));
+
+const LONG =
+  "Handle the review cycle for PR #107 in /home/daniel/Coding/Javascript/pi-archimedes and report every finding with a file:line reference so the maintainer can act on each one without re-reading the diff herself ";
+
+describe("truncateRow", () => {
+  it("leaves a row that fits untouched, byte for byte", () => {
+    const line = bold("general") + dim(": short task");
+    expect(truncateRow(line, 80)).toBe(line);
+  });
+
+  it("cuts on display cells and fills the frame exactly", () => {
+    for (const width of [200, 120, 80, 60, 40, 20]) {
+      const truncated = truncateRow(dim(LONG), width);
+      expect(drawn(truncated), `width ${width}`).toBe(width);
+      expect(stripTerminalSequences(truncated).endsWith("..."), `width ${width}`).toBe(true);
+    }
+  });
+
+  it("keeps the ellipsis inside the styled span (byte-exact)", () => {
+    // 10 columns, 3 of them the ellipsis: 7 visible characters of the dim text,
+    // then the dots — still inside the open `\x1b[2m`, then closed for us.
+    expect(truncateRow(dim("abcdefghijklmnop"), 10)).toBe(`\x1b[2mabcdefg...${RESET}`);
+  });
+
+  it("why not truncateToWidth: its ellipsis lands after the colour reset", () => {
+    // Measured against pi-tui 1.2.0. The dots are outside the dim span, which is
+    // the exact defect the old character-based `truncLine` existed to avoid.
+    expect(truncateToWidth(dim("abcdefghijklmnop"), 10)).toBe(
+      "\x1b[2mabcdefg\x1b[0m...\x1b[0m",
+    );
+    // Ours keeps the colour: nothing resets between the span's own colour and
+    // the dots.
+    const ours = truncateRow(dim("abcdefghijklmnop"), 10);
+    const beforeDots = ours.slice(0, ours.indexOf("..."));
+    expect(ours.slice(0, -RESET.length).endsWith("...")).toBe(true);
+    expect(beforeDots.startsWith("\x1b[2m")).toBe(true);
+    expect(beforeDots.includes(RESET)).toBe(false);
+  });
+
+  it("closes the style it left open, so padding is not painted", () => {
+    expect(truncateRow(dim(LONG), 30).endsWith(RESET)).toBe(true);
+  });
+
+  it("cuts at the first newline instead of bleeding into the next row", () => {
+    // The rule the old truncLine enforced: a newline is a hard boundary.
+    expect(stripTerminalSequences(truncateRow("line one\nline two\nline three", 40))).toBe("line one...");
+    expect(stripTerminalSequences(truncateRow("a\n\n\nb", 40))).toBe("a...");
+    expect(stripTerminalSequences(truncateRow("\nhello", 40))).toBe("...");
+    // Including when the first line is short enough to fit the frame.
+    expect(stripTerminalSequences(truncateRow(dim("short\nrest"), 40))).toBe("short...");
+  });
+
+  it("never splits a wide glyph, at any width", () => {
+    const cjk = "検証サイクルをPR107で実行して結果を報告".repeat(3);
+    for (const width of [40, 30, 21, 11, 5]) {
+      const truncated = truncateRow(cjk, width);
+      const cells = visibleWidth(truncated);
+      expect(cells, `cjk width ${width}`).toBeLessThanOrEqual(width);
+      // One cell of slack is the most a dropped double-width glyph can cost.
+      expect(cells, `cjk width ${width}`).toBeGreaterThanOrEqual(Math.min(width, 3) - 1);
+    }
+    expect(stripTerminalSequences(truncateRow(cjk, 40)).endsWith("...")).toBe(true);
+  });
+
+  it("never splits an emoji cluster, at any width", () => {
+    const emoji = ("🚀 ship 🔥 the ✅ change 🧪 with 📦 care 🎯 now 🏁 ship 🧭 ").repeat(3);
+    for (const width of [40, 27, 13, 7]) {
+      expect(visibleWidth(truncateRow(emoji, width)), `emoji width ${width}`).toBeLessThanOrEqual(width);
+    }
+  });
+
+  it("never emits a full SGR reset (\\x1b[0m) that would kill a container Box background", () => {
+    // Both when cut on width and when cut on a newline
+    const cutOnWidth = truncateRow(dim(LONG), 40);
+    expect(cutOnWidth.includes("\x1b[0m")).toBe(false);
+    expect(cutOnWidth.includes("\x1b[m")).toBe(false);
+
+    const cutOnNewline = truncateRow("general: Check status\nsecond line", 80);
+    expect(cutOnNewline.includes("\x1b[0m")).toBe(false);
+    expect(cutOnNewline.includes("\x1b[m")).toBe(false);
+
+    // Embedded \x1b[0m is safely converted to style reset
+    const embedded = truncateRow("\x1b[31merror\x1b[0m: details", 80);
+    expect(embedded.includes("\x1b[0m")).toBe(false);
+    expect(embedded.includes("\x1b[m")).toBe(false);
+  });
+
+  it("preserves an enclosing Box background across the entire row including padding", () => {
+    const bgFn = (t: string) => `\x1b[48;2;33;34;44m${t}\x1b[49m`;
+    const box = new Box(1, 1, bgFn);
+    const rows = new RowBlock();
+    rows.setSegments([
+      row("general: Check the status of PR #23 on danielcherubini/archimedes:\nsomething else"),
+    ]);
+    box.addChild(rows);
+    const lines = box.render(100);
+    // Line 1 is the content row
+    const contentLine = lines[1]!;
+    expect(contentLine).toBeDefined();
+    // Background escape was applied at the start and closed at the end
+    expect(contentLine.startsWith("\x1b[48;2;33;34;44m")).toBe(true);
+    expect(contentLine.endsWith("\x1b[49m")).toBe(true);
+    // No full reset in the middle that would kill the background before the padding
+    expect(contentLine.includes("\x1b[0m")).toBe(false);
+    expect(contentLine.includes("\x1b[m")).toBe(false);
+  });
+
+  it("survives widths with no room for an ellipsis", () => {
+    expect(truncateRow(LONG, 3)).toBe("...");
+    expect(truncateRow(LONG, 2)).toBe("..");
+    expect(truncateRow(LONG, 1)).toBe(".");
+    expect(truncateRow(LONG, 0)).toBe("");
+    expect(truncateRow(LONG, -5)).toBe("");
+  });
+});
+
+describe("RowBlock", () => {
+  const padTo = (line: string, width: number) =>
+    line + " ".repeat(Math.max(0, width - visibleWidth(line)));
+
+  const gamma = () => "gamma: " + LONG;
+
+  it("renders every logical line of setText as one row, padded to the frame", () => {
+    const rows = new RowBlock();
+    rows.setText(["alpha", "beta", gamma()].join("\n"));
+    const lines = rows.render(40);
+    expect(lines.length).toBe(3);
+    for (const line of lines) expect(visibleWidth(line)).toBe(40);
+  });
+
+  it("matches pi-tui's Text exactly while nothing needs truncating", () => {
+    // The rows used to be a plain Text; for short content the replacement must be
+    // byte-identical, or the fix silently restyles every row.
+    const text = ["alpha", "beta", "gamma"].join("\n");
+    const plain = new Text(text, 0, 0).render(80);
+    const rows = new RowBlock();
+    rows.setText(text);
+    expect(rows.render(80)).toEqual(plain);
+  });
+
+  it("truncates a long row to one line instead of wrapping it", () => {
+    const rows = new RowBlock();
+    rows.setText(bold("general") + dim(": " + LONG));
+    for (const width of [200, 120, 80, 60, 40]) {
+      const lines = rows.render(width);
+      expect(lines.length, `width ${width}`).toBe(1);
+      expect(drawn(lines[0]!), `width ${width}`).toBeGreaterThanOrEqual(width - 1);
+      expect(stripTerminalSequences(lines[0]!.replace(/\s+$/, "")).endsWith("..."), `width ${width}`).toBe(true);
+    }
+  });
+
+  it("keeps wrapped blocks wrapped, so multi-line content is not lost", () => {
+    const rows = new RowBlock();
+    rows.setSegments([row(bold("general") + dim(": " + LONG)), block(LONG)]);
+    const lines = rows.render(40);
+    // One row + a wrapped block: the block costs more than one line, the row not.
+    expect(lines.length).toBeGreaterThan(2);
+    expect(stripTerminalSequences(lines[0]!).trimEnd().endsWith("...")).toBe(true);
+    for (const line of lines) expect(visibleWidth(line)).toBeLessThanOrEqual(40);
+  });
+
+  it("re-renders for a new width instead of serving a stale frame", () => {
+    const rows = new RowBlock();
+    rows.setText(bold("general") + dim(": " + LONG));
+    const narrow = rows.render(40);
+    const wide = rows.render(120);
+    expect(narrow).not.toEqual(wide);
+    for (const [width, lines] of [
+      [40, narrow],
+      [120, wide],
+    ] as const) {
+      expect(lines.length).toBe(1);
+      expect(drawn(lines[0]!)).toBeGreaterThanOrEqual(width - 1);
+    }
+    // …and the same width again is stable (the cache is keyed by content + width).
+    expect(rows.render(120)).toEqual(wide);
+    // …and new content invalidates it, rather than serving the cached frame.
+    rows.setText(bold("general") + dim(": now in a hurry"));
+    const changed = rows.render(120);
+    expect(changed).not.toEqual(wide);
+    expect(stripTerminalSequences(changed[0]!).trimEnd()).toBe("general: now in a hurry");
+  });
+
+  it("renders nothing for blank content, like Text", () => {
+    const rows = new RowBlock();
+    rows.setText("");
+    expect(rows.render(80)).toEqual([]);
+    rows.setSegments([]);
+    expect(rows.render(80)).toEqual([]);
+    const blank = new RowBlock();
+    blank.setText("   ");
+    expect(blank.render(80)).toEqual(new Text("   ", 0, 0).render(80));
+  });
+
+  it("normalizes tabs to three spaces, like Text", () => {
+    const rows = new RowBlock();
+    rows.setText("a\tb");
+    expect(rows.render(80)).toEqual(new Text("a\tb", 0, 0).render(80));
+  });
+
+  it("pads every produced row to the frame", () => {
+    const rows = new RowBlock();
+    rows.setSegments([row("short"), block(LONG), row(dim(LONG))]);
+    const lines = rows.render(60);
+    for (const line of lines) expect(padTo(line, 60)).toBe(line);
+  });
+
+  it("sanitizes embedded \\x1b[0m in block segments to RESET when rendered and padded", () => {
+    const rows = new RowBlock();
+    rows.setSegments([block("\x1b[31merror message\x1b[0m: line one\nsecond line with \x1b[32msuccess\x1b[m details")]);
+    const lines = rows.render(80);
+    expect(lines.length).toBe(2);
+    for (const line of lines) {
+      expect(line.includes("\x1b[0m")).toBe(false);
+      expect(line.includes("\x1b[m")).toBe(false);
+      expect(visibleWidth(line)).toBe(80);
+    }
+    expect(lines[0]!).toContain(`\x1b[31merror message${RESET}: line one`);
+    expect(lines[1]!).toContain(`second line with \x1b[32msuccess${RESET} details`);
+  });
+});

package/src/row-block.ts

@@ -0,0 +1,209 @@
+/**
+ * Width-aware rows for the subagent tool's transcript rows.
+ *
+ * pi draws a tool row at the width it is rendering at: bash truncates inside
+ * `VisualLinePreview`/`truncateToVisualLines`, which are handed `render(width)`'s
+ * width. That module is not importable (pi's export map is `.` and `./rpc-entry`),
+ * so the rows here get the same behaviour from pi-tui's own helpers — the
+ * sanctioned route, per ADR 0029 ("width maths goes through pi-tui helpers").
+ *
+ * Two kinds of content, because the subagent draws two kinds of thing:
+ *
+ *   * a **row** — one logical line: the agent label, the stats line, the activity
+ *     line, the outcome line. It is cut at the render width, so it fills the
+ *     frame and truncates there, exactly like the bash row. Leaving it uncapped
+ *     inside a `Text` is not the fix: `Text.render(width)` *wraps*, so a long task
+ *     would become a multi-row block instead of one full-width row.
+ *   * a **block** — multi-line content that is meant to be read in full (the
+ *     expanded view's output, its task text, its tool-call history). It wraps,
+ *     as it always has (ADR 0020: expanded output is deliberately untruncated).
+ *
+ * The width therefore arrives per-render and nothing is cached across renders
+ * except keyed by (content, width).
+ */
+
+import { Text, sliceByColumn, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** The marker appended to a row that was cut. Plain text, so it inherits colour. */
+export const ROW_ELLIPSIS = "...";
+
+/**
+ * SGR reset for styled rows: resets foreground color and font styles (bold,
+ * dim, italic, underline, reverse video, strikethrough), but never resets the
+ * background color (SGR 49).
+ *
+ * Inside pi's tool execution component, rows are rendered inside a Box that
+ * applies a panel background (e.g. toolSuccessBg / toolPendingBg) across the
+ * entire row: `theme.bg(token, paddedLine)`. A full SGR reset (`\x1b[0m` or
+ * `\x1b[m`) cancels the Box-painted background mid-line, causing all subsequent
+ * padding spaces and trailing content to fall through to the terminal's default
+ * background (appearing as an unsightly mid-grey or mismatched bar after
+ * truncated text or early newlines).
+ */
+export const RESET = "\x1b[22;23;24;27;29;39m";
+
+/**
+ * Replace any full SGR resets (\x1b[0m or \x1b[m) with a style-and-foreground reset
+ * so the line never kills an enclosing container's background color mid-line.
+ */
+export function sanitizeRowResets(line: string): string {
+  return line.replace(/\x1b\[0?m/g, RESET);
+}
+
+/** How `Text` renders a tab; kept identical so short rows stay byte-identical. */
+const TAB_WIDTH = 3;
+
+/** `row`: one line, truncated to the frame. `block`: wrapped, never cut. */
+export type RowKind = "row" | "block";
+
+export interface RowSegment {
+  readonly kind: RowKind;
+  readonly text: string;
+}
+
+/** One logical line that must stay one line at any width. */
+export function row(text: string): RowSegment {
+  return { kind: "row", text };
+}
+
+/**
+ * What the row builders draw into: the two ways content reaches a `RowBlock`.
+ * Kept as a projection of `RowBlock` so a builder cannot ask for anything a row
+ * does not do (no `tui`, no width, no renderer — see ADR 0027).
+ */
+export type RowSink = Pick<RowBlock, "setText" | "setSegments">;
+
+/** Multi-line content that keeps pi-tui's wrapping. */
+export function block(text: string): RowSegment {
+  return { kind: "block", text };
+}
+
+/** Treat every logical line of `text` as a row (the compact view is all rows). */
+export function rowsFromText(text: string): RowSegment[] {
+  return text.split("\n").map(row);
+}
+
+/**
+ * Cut one styled row to `width` display cells.
+ *
+ * The ellipsis stays inside the styled span — the property the old character-based
+ * `truncLine` existed to keep, and the reason `truncateToWidth` is not used for
+ * the cut: it emits `…\x1b[0m…`, i.e. the dots land *after* a colour reset, so a
+ * truncated span loses its colour (`row-block.test.ts` pins those bytes).
+ * `sliceByColumn` cuts on display cells instead — wide glyphs and emoji included —
+ * and leaves the ANSI state open where it cuts, so a plain `"..."` appended after
+ * it inherits whatever colour the row was drawing at that point. The trailing
+ * reset then closes what was left open, so the row's padding is not painted.
+ *
+ * A newline is a hard boundary: the row stops at the first one rather than
+ * bleeding into the next row, and says so with the ellipsis.
+ */
+export function truncateRow(line: string, width: number): string {
+  if (width <= 0) return "";
+  const nlIdx = line.indexOf("\n");
+  const firstLine = nlIdx === -1 ? line : line.slice(0, nlIdx);
+  if (nlIdx === -1 && visibleWidth(firstLine) <= width) {
+    return sanitizeRowResets(firstLine);
+  }
+
+  const budget = width - ROW_ELLIPSIS.length;
+  // No room for both content and dots: show as many dots as the frame holds, so
+  // the row still reads as "cut" rather than as "the whole task".
+  if (budget <= 0) return sliceByColumn(ROW_ELLIPSIS, 0, width, true);
+  const sliced = sliceByColumn(firstLine, 0, budget, true);
+  return sanitizeRowResets(sliced + ROW_ELLIPSIS) + RESET;
+}
+
+/** Pad a rendered line out to the frame, the way `Text` does. */
+function padToWidth(line: string, width: number): string {
+  const used = visibleWidth(line);
+  return used >= width ? line : line + " ".repeat(width - used);
+}
+
+/**
+ * The rows of one subagent result, truncated at the width pi renders them at.
+ *
+ * A `Text` subclass, because everything that already knows how to hold a row —
+ * pi's own tool shell, and this package's `setText`-shaped renderers — expects
+ * one. `setText` treats every logical line as a row; `setSegments` is for the
+ * views that mix rows with wrapped blocks (expanded).
+ */
+export class RowBlock extends Text {
+  private segments: RowSegment[];
+  private content: string;
+  private cacheKey: string | undefined;
+  private cacheWidth: number | undefined;
+  private cacheLines: string[] | undefined;
+
+  constructor(text = "") {
+    // Edge-to-edge: pi's tool shell supplies the row's inset (a Box with its own
+    // padding), exactly as it did for the `Text` this replaces.
+    super(text, 0, 0);
+    this.segments = rowsFromText(text);
+    this.content = text;
+  }
+
+  /** Every logical line of `text` is a row. */
+  override setText(text: string): void {
+    super.setText(text);
+    this.content = text;
+    this.segments = rowsFromText(text);
+    this.cacheKey = undefined;
+    this.cacheWidth = undefined;
+    this.cacheLines = undefined;
+  }
+
+  /** Mixed content: rows truncated to the frame, blocks wrapped. */
+  setSegments(segments: RowSegment[]): void {
+    const text = segments.map((segment) => segment.text).join("\n");
+    super.setText(text);
+    this.content = text;
+    this.segments = segments;
+    this.cacheKey = undefined;
+    this.cacheWidth = undefined;
+    this.cacheLines = undefined;
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.cacheKey = undefined;
+    this.cacheWidth = undefined;
+    this.cacheLines = undefined;
+  }
+
+  override render(width: number): string[] {
+    // Cached across frames exactly the way `Text` caches: by content and width,
+    // because the duration in a running row changes the content between frames.
+    if (
+      this.cacheLines !== undefined &&
+      this.cacheKey === this.content &&
+      this.cacheWidth === width
+    ) {
+      return this.cacheLines;
+    }
+    const lines = this.layout(Math.max(1, width));
+    this.cacheKey = this.content;
+    this.cacheWidth = width;
+    this.cacheLines = lines;
+    return lines;
+  }
+
+  private layout(width: number): string[] {
+    // Nothing but blanks to draw: render no lines at all, matching `Text`.
+    if (this.segments.length === 0 || this.segments.every((s) => s.text.trim() === "")) {
+      return [];
+    }
+    const lines: string[] = [];
+    for (const segment of this.segments) {
+      const text = segment.text.replace(/\t/g, " ".repeat(TAB_WIDTH));
+      if (segment.kind === "block") {
+        for (const wrapped of wrapTextWithAnsi(text, width)) {
+          lines.push(padToWidth(sanitizeRowResets(wrapped), width));
+        }
+      } else {
+        lines.push(padToWidth(truncateRow(text, width), width));
+      }
+    }
+    return lines;
+  }
+}

package/src/run-outcome.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { decideRunOutcome } from "./run-outcome.js";
+
+// The decision table, pinned where it lives. Every row is a case the child can
+// actually produce on pi 1.2.0 — see the table comment in `run-outcome.ts` for
+// where each one comes from.
+
+const SETTLED = { settledAborted: false, stopReason: undefined, exitCode: 0, signal: undefined };
+
+describe("decideRunOutcome", () => {
+  it("completed: exit 0, clean stopReason, settled not aborted", () => {
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "stop" })).toBe("completed");
+    expect(decideRunOutcome(SETTLED)).toBe("completed");
+  });
+
+  it("truncated: stopReason length, whether the child exited 0 (json mode) or 1 (print mode)", () => {
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "length" })).toBe("truncated");
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "length", exitCode: 1 })).toBe("truncated");
+  });
+
+  it("aborted: agent_settled.aborted wins over a clean stopReason and a nonzero exit", () => {
+    expect(decideRunOutcome({ ...SETTLED, settledAborted: true })).toBe("aborted");
+    expect(decideRunOutcome({ ...SETTLED, settledAborted: true, exitCode: 143 })).toBe("aborted");
+    expect(decideRunOutcome({ ...SETTLED, settledAborted: true, stopReason: "length" })).toBe("aborted");
+  });
+
+  it("aborted: the provider aborted the last response", () => {
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "aborted" })).toBe("aborted");
+  });
+
+  it("aborted: killed by a cancellation signal before it could settle", () => {
+    const killed = { ...SETTLED, exitCode: null };
+    expect(decideRunOutcome({ ...killed, signal: "SIGTERM" })).toBe("aborted");
+    expect(decideRunOutcome({ ...killed, signal: "SIGKILL" })).toBe("aborted");
+    expect(decideRunOutcome({ ...killed, signal: "SIGHUP" })).toBe("aborted");
+    expect(decideRunOutcome({ ...killed, signal: "SIGINT" })).toBe("aborted");
+  });
+
+  it("aborted: pi's own signal handlers exit 143/129 instead of dying by the signal", () => {
+    // Observed against a real 1.2.0 child SIGTERM'd mid-run: `close` reported
+    // code 143 and NO signal, because print mode catches SIGTERM/SIGHUP and
+    // calls process.exit(143)/process.exit(129) itself
+    // (`dist/modes/print-mode.js`, registerSignalHandlers). Reading only
+    // `signal` would call a cancellation a failure.
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 143 })).toBe("aborted");
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 129 })).toBe("aborted");
+    // A completed last response does not make a cancelled child un-cancelled.
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 143, stopReason: "stop" })).toBe("aborted");
+    // And it outranks the shapes a cancellation can leave behind on the way out.
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 143, stopReason: "error" })).toBe("aborted");
+  });
+
+  it("failed: the child's last response errored, whatever the exit code says", () => {
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "error", exitCode: 1 })).toBe("failed");
+    expect(decideRunOutcome({ ...SETTLED, stopReason: "error", exitCode: 0 })).toBe("failed");
+  });
+
+  it("failed: a nonzero exit with no run behind it", () => {
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 1 })).toBe("failed");
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 2 })).toBe("failed");
+    // 130 (SIGINT) is NOT one of pi's handler exits — SIGINT is uncaught, so it
+    // arrives as a signal death above; anything else stays a failure.
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 130 })).toBe("failed");
+    expect(decideRunOutcome({ ...SETTLED, exitCode: 137 })).toBe("failed");
+  });
+
+  it("failed: a crash on an unexpected signal is not someone cancelling", () => {
+    expect(decideRunOutcome({ ...SETTLED, exitCode: null, signal: "SIGSEGV" })).toBe("failed");
+    expect(decideRunOutcome({ ...SETTLED, exitCode: null, signal: undefined })).toBe("failed");
+  });
+});

package/src/run-outcome.ts

@@ -0,0 +1,84 @@
+import type { RunOutcome } from "./types.js";
+
+// ── The *Run outcome* decision table (CONTEXT.md vocabulary, ADR 0028) ──────
+//
+// The child's exit code cannot tell these apart, and after pi 1.2.0 it cannot
+// even be trusted to mean "failed": print mode exits **1** when the final
+// response hit the output token limit, so a useful-but-cut-off answer arrives as
+// the same `1` as a crash. `stream.ts` used to reduce the child to `code ?? 1`,
+// which destroyed that distinction exactly where the plan says it must not.
+//
+// The two signals that do carry it are the child's own `stopReason` (on the last
+// assistant `message_end`) and pi 1.1.0's `agent_settled.aborted`. Note that
+// `--mode json` — what the child actually runs — does *not* map `stopReason` onto
+// the exit code at all (that mapping lives in print mode's text branch), so a
+// json child reports truncation through `stopReason` alone and exits 0. Both
+// shapes are handled: truncation is read from the child, never inferred from
+// the code.
+//
+// | input                                                       | outcome     |
+// |-------------------------------------------------------------|-------------|
+// | `agent_settled.aborted: true`                               | aborted     |
+// | last assistant `stopReason: "aborted"`                      | aborted     |
+// | killed by a cancellation signal (SIGKILL/SIGINT — uncaught) | aborted     |
+// | killed by an unexpected signal (SIGSEGV, …)                 | failed      |
+// | exit 143 / 129 (pi caught SIGTERM / SIGHUP and exited)      | aborted     |
+// | last assistant `stopReason: "error"`                        | failed      |
+// | last assistant `stopReason: "length"` — exit 0 **or** 1     | truncated   |
+// | any other nonzero exit                                      | failed      |
+// | exit 0, nothing above matched                               | completed   |
+//
+// `truncated` is not an error and neither is `aborted`; `failed` is, and is what
+// the caller reports as one (the result carries no outcome in that case).
+
+/** Signals that mean "someone cancelled this run", as opposed to "it broke". */
+const CANCELLATION_SIGNALS = new Set(["SIGTERM", "SIGKILL", "SIGHUP", "SIGINT"]);
+
+/**
+ * The same cancellation, arriving as an exit code instead of a signal.
+ *
+ * print mode catches SIGTERM (and SIGHUP on non-Windows) and exits by itself —
+ * `process.exit(signal === "SIGHUP" ? 129 : 143)`
+ * (`pi-coding-agent/dist/modes/print-mode.js`, `registerSignalHandlers`) — so a
+ * real SIGTERM'd child closes with code 143 and **no** signal, which the table
+ * would otherwise read as an ordinary failure. Verified against a live 1.2.0
+ * child killed mid-run. SIGINT is not caught, so it still arrives as a signal
+ * death; SIGKILL cannot be caught at all. Hence exactly these two codes.
+ */
+const CANCELLATION_EXIT_CODES = new Set([143, 129]);
+
+export interface RunOutcomeInput {
+  /** `agent_settled.aborted` seen on the child's event stream. */
+  settledAborted: boolean;
+  /** `stopReason` of the last assistant message the child emitted. */
+  stopReason: string | undefined;
+  /** Process exit code, or `null` when it was terminated by a signal. */
+  exitCode: number | null;
+  /** The terminating signal, when there was one. */
+  signal: string | undefined;
+}
+
+/**
+ * Decide the run's terminal state, or `failed` when the run did not reach one.
+ *
+ * Order is the table above: cancellation first (an aborted run's `stopReason` may
+ * be `error` or `length` on the way out), then a signal death — which is decided
+ * before `stopReason`, because a killed child's last message says nothing about
+ * how it died — then the child's own account of how its last response ended
+ * (`error`, then `length`), then the exit code, which is the least informative of
+ * the three and therefore last. That last ordering is the whole point of the
+ * 1.2.0 change: exit 1 arrives for a crash and for a truncated answer alike, so
+ * `length` has to be read before the exit code or the distinction is lost again.
+ */
+export function decideRunOutcome(input: RunOutcomeInput): RunOutcome | "failed" {
+  if (input.settledAborted) return "aborted";
+  if (input.stopReason === "aborted") return "aborted";
+  if (input.exitCode === null) {
+    return CANCELLATION_SIGNALS.has(input.signal ?? "") ? "aborted" : "failed";
+  }
+  if (CANCELLATION_EXIT_CODES.has(input.exitCode)) return "aborted";
+  if (input.stopReason === "error") return "failed";
+  if (input.stopReason === "length") return "truncated";
+  if (input.exitCode !== 0) return "failed";
+  return "completed";
+}