@pi-archimedes/subagent 2.10.4 → 2.11.0

package/src/index.ts

@@ -1,15 +1,24 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, type TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { SUBAGENT_PARAMS_SCHEMA } from "./tool-schema.js";
+import { SUBAGENT_PARAMS_SCHEMA, SUBAGENT_OUTPUT_SCHEMA, subagentStructuredContent } from "./tool-schema.js";
 import { executeSubagent, executeParallel } from "./execute.js";
-import { formatParallelResults } from "./format.js";
+import { formatParallelResults, formatSingleResult } from "./format.js";
 // agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
+import { RowBlock } from "./row-block.js";
 import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
 import { renderToolHeader } from "@pi-archimedes/core/tool-render";
+import { reportPiSupport } from "@pi-archimedes/core/pi-support";
+import { diag, describeError } from "@pi-archimedes/core/log";
 import { discoverAgents, discoverAgentsAll, findAgent, formatAgentList } from "./agents.js";
 import { validateModel, firstError } from "./model-validation.js";
+import {
+  unknownToolEntries,
+  formatUnknownToolsWarning,
+} from "./tool-validation.js";
+import { resolveThinkingLevel } from "./thinking-validation.js";
+import { toNativeUsage, sumNativeUsage } from "./usage.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -27,12 +36,38 @@ interface RenderTheme {
 // ── Tool registration ───────────────────────────────────────────────────────
 
 export function registerSubagent(pi: ExtensionAPI): void {
+  // Floor check before anything that can fail (ADR 0026). This package spawns
+  // pi with flags and reads event fields that only behave correctly on 1.x
+  // (`--tools` semantics, `agent_settled.aborted`, print-mode exit codes), and a
+  // peer range cannot say so at install time. Warn and register anyway — the
+  // tool must still show up in /plugins. Entry point for both meta and the
+  // standalone default export, so `registerAgentsCommand` needs no second call.
+  reportPiSupport("subagent", "1.2.0");
+
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
     description:
       "Delegate tasks to subagents. Provide either 'task' (single) or 'tasks' (parallel). Agent is optional — omit for a config-less run with the parent's model and all tools. Model override is rarely needed; the agent config or parent model is used by default.",
     parameters: SUBAGENT_PARAMS_SCHEMA,
+    outputSchema: SUBAGENT_OUTPUT_SCHEMA,
+    /**
+     * Declared to the model, never callable from a codemode script — pi's own
+     * wording for this exposure is "orchestrating" tools
+     * (`dist/core/extensions/types.d.ts`, `ToolExposure`), and dispatching a
+     * child session is that.
+     *
+     * Measured cost, so it is not discovered later: before this line a codemode
+     * script could dispatch a child and read its report — `tools.subagent({ task:
+     * "Reply with exactly the single word: child" })` resolved to
+     * `{ mode: "single", results: [ { outcome: "completed", finalOutput: "child",
+     * usage: {…} } ] }` on a real headless pi. After it the same call reports
+     * `tools.subagent does not exist`, and `subagent` is gone from the script's
+     * `ALL_TOOLS`. A script that wants a child's work now has to ask the model to
+     * dispatch one; `list_agents` stays `direct`, so scripts can still read the
+     * catalogue. The model's own dispatches are unaffected.
+     */
+    exposure: "model-only",
 
     async execute(
       _id: string,
@@ -68,6 +103,9 @@ export function registerSubagent(pi: ExtensionAPI): void {
           // Skip model validation for tasks already caught by unknown-agent check
           if (t.agent && unknownAgentSet.has(t.agent)) continue;
           const taskAgentConfig = t.agent ? findAgent(agents, t.agent) : undefined;
+          // A `tools:` list the config read rejected is never applied, so the task
+          // cannot run as configured — say so before anything spawns.
+          if (taskAgentConfig?.toolsError) errors.push(taskAgentConfig.toolsError);
           const me = firstError(
             validateModel(t.model, ctx.modelRegistry, { agentName: t.agent }),
             validateModel(taskAgentConfig?.model, ctx.modelRegistry, {
@@ -88,6 +126,20 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // Membership only becomes knowable here, with the handle in scope — and
+        // it is a warning, so the batch still runs (see warnUnavailableTools).
+        const warnedTools = new Set<string>();
+        const warnedThinking = new Set<string>();
+        for (const t of params.tasks) {
+          warnUnavailableTools(
+            pi,
+            ctx,
+            warnedTools,
+            t.agent ?? "subagent",
+            t.agent ? findAgent(agents, t.agent)?.tools : undefined,
+          );
+          warnUnknownThinkingLevel(ctx, warnedThinking, t.agent ? findAgent(agents, t.agent)?.thinking : undefined);
+        }
         const results: SubagentResult[] = await executeParallel({
           tasks: params.tasks.map((t) => ({
             agent: t.agent ?? undefined,
@@ -101,6 +153,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
             toolCallId: _id,
           })),
           signal: signal ?? undefined,
+          events: pi.events,
           onUpdate: (progress: SubagentProgress[]) => {
             onUpdate?.({
               content: [],
@@ -113,8 +166,11 @@ export function registerSubagent(pi: ExtensionAPI): void {
           },
         });
 
+        const nativeUsage = sumNativeUsage(results);
         return {
           content: [{ type: "text", text: formatParallelResults(results) }],
+          ...(nativeUsage ? { usage: nativeUsage } : {}),
+          structuredContent: subagentStructuredContent("parallel", results),
           details: {
             mode: "parallel",
             results,
@@ -158,6 +214,18 @@ export function registerSubagent(pi: ExtensionAPI): void {
             isError: true,
           };
         }
+        // A rejected `tools:` list is a config error, not a runtime one: the child
+        // would run with a different tool set than the config asked for, so it
+        // does not run at all.
+        if (agentConfig?.toolsError) {
+          return {
+            content: [{ type: "text", text: agentConfig.toolsError }],
+            details: { mode: "single", results: [], progress: undefined },
+            isError: true,
+          };
+        }
+        warnUnavailableTools(pi, ctx, new Set(), params.agent ?? "subagent", agentConfig?.tools);
+        warnUnknownThinkingLevel(ctx, new Set(), agentConfig?.thinking);
         const result: SubagentResult = await executeSubagent({
           agent: params.agent ?? undefined,
           agentConfig,
@@ -166,6 +234,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
           activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
+          events: pi.events,
           toolCallId: _id,
           onUpdate: (progress: SubagentProgress) => {
             onUpdate?.({
@@ -180,13 +249,31 @@ export function registerSubagent(pi: ExtensionAPI): void {
         });
 
         return {
-          content: [{ type: "text", text: result.finalOutput ?? result.error ?? "completed" }],
+          content: [{ type: "text", text: formatSingleResult(result) }],
+          // The cost report — but only for a run this session performed. A
+          // bridge-dispatched run is a session of the desktop's own and books
+          // its usage there; pi folds a tool result's `usage` into THIS
+          // session's totals, so publishing it here would count the money twice
+          // (the same reason the `COST_UPDATE` route was deleted).
+          ...(result.usageAccountedElsewhere ? {} : { usage: toNativeUsage(result.usage) }),
+          // Successes only. The predicate is the one two lines below, so a run
+          // that reports itself as failed carries no structured content and a
+          // codemode script keeps rejecting with the text it rejects with today
+          // (see `SUBAGENT_OUTPUT_SCHEMA`).
+          ...(result.error === undefined ? { structuredContent: subagentStructuredContent("single", [result]) } : {}),
           details: {
             mode: "single",
             results: [result],
             progress: result.progress ? [result.progress] : undefined,
           },
-          isError: result.exitCode !== 0,
+          // Only a *failed* run is a tool error. A truncated answer and a
+          // cancelled one both produced something, and `isError` is how the model
+          // and the Client decide to retry or give up (ADR 0028). `error` is the
+          // predicate because the exit code is not one — a json child exits 0 for
+          // an errored run — and `stream.ts` guarantees a failed run always
+          // carries an explanation while a completed/truncated/aborted one never
+          // does.
+          isError: result.error !== undefined,
         };
       }
 
@@ -231,18 +318,21 @@ export function registerSubagent(pi: ExtensionAPI): void {
         false) as boolean;
 
       const renderTheme = theme as unknown as RenderTheme;
-      const text = new Text("", 0, 0);
+      // A RowBlock, not a plain Text: the subagent rows are cut at the width pi
+      // renders them at, and only the component is ever handed that width.
+      const lastComponent = (context as { lastComponent?: unknown })?.lastComponent;
+      const rows = lastComponent instanceof RowBlock ? lastComponent : new RowBlock();
       const renderContext = {
         expanded,
         isError: toolResult.isError ?? false,
-        lastComponent: (context as { lastComponent?: Text })?.lastComponent,
+        lastComponent: rows,
         state: (context as Record<string, unknown>)?.state ?? {},
         invalidate: () => {},
       };
-      (context as Record<string, unknown>).lastComponent = text;
+      (context as Record<string, unknown>).lastComponent = rows;
 
       try {
-        const rendered = renderSubagentResult(text, toolResult, { expanded }, renderTheme, renderContext as any);
+        const rendered = renderSubagentResult(rows, toolResult, { expanded }, renderTheme, renderContext as any);
         return rendered;
       } catch (e) {
         debugText.setText("render error: " + (e instanceof Error ? e.message : String(e)));
@@ -256,6 +346,76 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+/**
+ * Warn (never fail) about allowlist entries no registered tool satisfies right
+ * now, naming each one.
+ *
+ * Membership cannot be checked any earlier: `pi.getAllTools()` needs this
+ * handle, and the config read is pure filesystem. And it must not fail the run:
+ * a legitimate name is missing whenever its plugin is toggled off or its MCP
+ * server is disconnected, so a hard error would make `tools: web_search` unusable
+ * for anyone who disabled `web`. One warning per entry per tool call — a parallel
+ * batch of eight agents sharing a list warns once, not eight times.
+ *
+ * Diagnostics go to `diag()` because a `console.*` write is discarded by a
+ * subagent child and smears the fullscreen frame (see `core/log.ts`); the
+ * on-screen copy only goes out where there is a UI to receive it.
+ */
+function warnUnavailableTools(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  alreadyWarned: Set<string>,
+  agentName: string,
+  tools: string[] | undefined,
+): void {
+  if (!tools || tools.length === 0) return;
+  let unknown: string[];
+  try {
+    const known = pi.getAllTools().map((t) => t.name);
+    unknown = unknownToolEntries(tools, known).filter((entry) => !alreadyWarned.has(entry));
+  } catch (e) {
+    // A handle that cannot answer is not a reason to lose the dispatch.
+    diag("subagent", `tool-membership check skipped for "${agentName}": ${describeError(e)}`);
+    return;
+  }
+  if (unknown.length === 0) return;
+  for (const entry of unknown) alreadyWarned.add(entry);
+  const message = formatUnknownToolsWarning(agentName, unknown);
+  diag("subagent", message);
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.notify(message, "warning");
+  } catch {
+    // A context too stale to notify must not fail the run it is only warning about.
+  }
+}
+
+/**
+ * Warn (never fail) about a `thinking:` level pi's `--thinking` does not take.
+ *
+ * `spawnSubagent` withholds the flag in this case, which is what pi would have
+ * done anyway — the difference is that the child no longer runs at the default
+ * level silently: pi's own notice is a stderr warning, and a successful json
+ * child's stderr is never read. One warning per distinct value per tool call.
+ */
+function warnUnknownThinkingLevel(
+  ctx: ExtensionContext,
+  alreadyWarned: Set<string>,
+  thinking: string | undefined,
+): void {
+  if (thinking === undefined || alreadyWarned.has(thinking)) return;
+  const { warning } = resolveThinkingLevel(thinking);
+  if (!warning) return;
+  alreadyWarned.add(thinking);
+  diag("subagent", warning);
+  if (!ctx.hasUI) return;
+  try {
+    ctx.ui.notify(warning, "warning");
+  } catch {
+    // Same rule as the tool-membership warning: a report must not lose a run.
+  }
+}
+
 export function registerListAgentsTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "list_agents",

package/src/render.ts

@@ -1,4 +1,4 @@
-import { Text } from "@earendil-works/pi-tui";
+import { RowBlock, row, type RowSegment } from "./row-block.js";
 import type { SubagentDetails, SubagentProgress, SubagentToolResult } from "./types.js";
 import {
   renderCompactSingle,
@@ -17,107 +17,117 @@ type Theme = { fg: (token: string, text: string) => string; bold: (text: string)
 type RenderContext = {
   expanded: boolean;
   isError: boolean;
-  lastComponent: Text | undefined;
+  lastComponent: RowBlock | undefined;
   state: Record<string, unknown>;
   invalidate: () => void;
 };
 
+/**
+ * Draw a subagent result (or its live progress) into `rows`.
+ *
+ * `rows` is a `RowBlock` rather than a plain `Text` because the renderers below
+ * hand back whole content: the component is what knows the width pi is drawing
+ * at, and it is what cuts each row to that width (`row-block.ts`).
+ */
 export function renderSubagentResult(
-  text: Text,
+  rows: RowBlock,
   result: SubagentToolResult,
   options: { expanded: boolean },
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   const details: SubagentDetails | undefined = result.details;
   const expanded = context.expanded ?? options.expanded;
 
   if (!details) {
-    text.setText(theme.fg("dim", "  no results"));
-    return text;
+    rows.setText(theme.fg("dim", "  no results"));
+    return rows;
   }
 
   // ── Streaming progress (results empty but progress has data) ──────────
   if (details.results.length === 0 && details.progress && details.progress.length > 0) {
     if (details.progress.length === 1) {
-      return renderProgressUpdate(text, details.progress[0]!, expanded, theme, context);
+      return renderProgressUpdate(rows, details.progress[0]!, expanded, theme, context);
     }
-    return renderProgressUpdatesParallel(text, details, expanded, theme, context);
+    return renderProgressUpdatesParallel(rows, details, expanded, theme, context);
   }
 
   if (details.results.length === 0) {
-    text.setText(theme.fg("dim", "  no results"));
-    return text;
+    rows.setText(theme.fg("dim", "  no results"));
+    return rows;
   }
 
   // ── Single agent ────────────────────────────────────────────────────────
   if (details.mode === "single" || details.results.length === 1) {
-    return renderSingleAgent(text, details.results[0]!, details.progress?.[0], expanded, theme, context);
+    return renderSingleAgent(rows, details.results[0]!, details.progress?.[0], expanded, theme, context);
   }
 
   // ── Parallel agents ─────────────────────────────────────────────────────
-  return renderParallelAgents(text, details, expanded, theme, context);
+  return renderParallelAgents(rows, details, expanded, theme, context);
 }
 
 function renderSingleAgent(
-  text: Text,
+  rows: RowBlock,
   result: SubagentDetails["results"][number],
   progress: SubagentDetails["progress"] extends (infer U)[] | undefined ? U | undefined : undefined,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
-    return renderExpanded(text, result, progress, theme);
+    return renderExpanded(rows, result, progress, theme);
   }
-  return renderCompactSingle(text, result, progress, theme, context);
+  renderCompactSingle(rows, result, progress, theme, context);
+  return rows;
 }
 
 function renderParallelAgents(
-  text: Text,
+  rows: RowBlock,
   details: SubagentDetails,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
     const progressArr: SubagentProgress[] = details.progress ?? [];
-    const lines = details.results.map((result, i) => {
-      return buildExpandedText(result, progressArr[i], theme);
-    });
-    text.setText(lines.join("\n\n"));
-    return text;
+    rows.setSegments(joinBlocks(details.results.map((result, i) => buildExpandedText(result, progressArr[i], theme))));
+    return rows;
   }
-  return renderCompactParallel(text, details, theme, context);
+  renderCompactParallel(rows, details, theme, context);
+  return rows;
 }
 
 function renderProgressUpdate(
-  text: Text,
+  rows: RowBlock,
   progress: SubagentProgress,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
-    return renderProgressExpanded(text, progress, theme);
+    return renderProgressExpanded(rows, progress, theme);
   }
-  return renderCompactProgress(text, progress, theme, context);
+  renderCompactProgress(rows, progress, theme, context);
+  return rows;
 }
 
 function renderProgressUpdatesParallel(
-  text: Text,
+  rows: RowBlock,
   details: SubagentDetails,
   expanded: boolean,
   theme: Theme,
   context: RenderContext,
-): Text {
+): RowBlock {
   if (expanded) {
     const progressArr: SubagentProgress[] = details.progress ?? [];
-    const lines = progressArr.map((progress) => {
-      return buildProgressExpandedText(progress, theme);
-    });
-    text.setText(lines.join("\n\n"));
-    return text;
+    rows.setSegments(joinBlocks(progressArr.map((progress) => buildProgressExpandedText(progress, theme))));
+    return rows;
   }
-  return renderCompactParallelProgress(text, details, theme, context);
+  renderCompactParallelProgress(rows, details, theme, context);
+  return rows;
+}
+
+/** One blank row between agents — the spacing the old `join("\n\n")` produced. */
+function joinBlocks(blocks: RowSegment[][]): RowSegment[] {
+  return blocks.flatMap((blockLines, i) => (i === 0 ? blockLines : [row(""), ...blockLines]));
 }

package/src/row-block.test.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { Text, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { RowBlock, block, row, truncateRow } from "./row-block.js";
+
+const dim = (t: string) => `\x1b[2m${t}\x1b[0m`;
+const bold = (t: string) => `\x1b[1m${t}\x1b[0m`;
+const RESET = "\x1b[0m";
+
+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("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);
+  });
+});