pi-minimalist 0.1.2 → 0.2.2

package/src/core-patch.ts

@@ -1,8 +1,8 @@
 /**
- * RUNTIME core patches — the replacement for the old patch-pi.sh bundle edits.
+ * RUNTIME core patches: wrappers on Pi's real component prototypes.
  *
- * WHY THIS WORKS (the discovery that removed the patch script)
- * -----------------------------------------------------------
+ * WHY THIS WORKS
+ * --------------
  * Pi's bundled CLI loads extensions through jiti with
  * `virtualModules: VIRTUAL_MODULES` (see core/extensions/loader.ts; the bundle
  * sets `isBundledNode = true`). Those virtual modules are the bundle's OWN live
@@ -10,32 +10,26 @@
  * `@earendil-works/pi-coding-agent`, it receives the very same class objects the
  * running TUI instantiates — not a second copy from `dist/`.
  *
- * `ToolExecutionComponent` and `AssistantMessageComponent` are public exports,
- * and every seam the old patch script rewrote is a `prototype` method. Wrapping
- * those prototypes at load time therefore produces exactly the behavior the perl
- * substitutions produced, with three advantages:
+ * Every seam is a `prototype` method on a public export, so wrapping at load time
+ * leaves nothing on disk modified (a Pi upgrade cannot silently revert it) and
+ * the wrappers are ordinary TypeScript, unit-testable against the real
+ * components (see test/core-patch.test.ts).
  *
- *   - a Pi upgrade cannot silently revert it (nothing on disk is modified);
- *   - no `node --check`, no marker greps, no per-release regex maintenance;
- *   - the wrappers are ordinary TypeScript, unit-testable against the real
- *     components (see test/core-patch.test.ts).
- *
- * Each wrapper reads its behavior from the process-global bridge slots at CALL
- * time (see bridge.ts), so `/reload` swaps behavior without re-wrapping — and
- * an unloaded extension degrades to Pi's native rendering.
+ * Each wrapper reads its behavior from the process-global `Bridge` at CALL time
+ * (see bridge.ts), so `/reload` swaps behavior without re-wrapping — and an
+ * unloaded extension degrades to Pi's native rendering.
  */
 
 import type { Component } from "@earendil-works/pi-tui";
-import { BRIDGE_SYMBOLS } from "./bridge.ts";
-import { FoldableProse } from "./components.ts";
-import type { Config } from "./config.ts";
-import type { Row, ThemeLike } from "./row.ts";
+import { readBridge as bridge, type Bridge } from "./bridge.ts";
+import { EmptyComponent, FoldableProse } from "./components.ts";
+import type { ThemeLike } from "./row.ts";
+import type { NativeResultRenderer, ToolRenderer } from "./tool-renderer.ts";
 
 type Globals = Record<symbol, unknown>;
 
-function bridge<T>(key: keyof typeof BRIDGE_SYMBOLS): T | undefined {
-  return (globalThis as Globals)[Symbol.for(BRIDGE_SYMBOLS[key])] as T | undefined;
-}
+const EMPTY = new EmptyComponent();
+const barrier = (id: string) => bridge()?.observeBarrier(id);
 
 /** Applied-once marker per prototype, so /reload never double-wraps. */
 const PATCHED = Symbol.for("pi.minimalist.corePatched");
@@ -59,20 +53,6 @@ function once(target: object, name: string, apply: () => void): void {
 // each patch function keeps its precise internal shape for the body below.
 // ---------------------------------------------------------------------------
 
-type ToolRendererBridge = {
-  renderShell?: "self" | "default";
-  handles?: (name: string) => boolean;
-  renderCall?: (name: string, args: unknown, theme: unknown, context: unknown) => Component;
-  renderResult?: (
-    name: string,
-    result: unknown,
-    options: unknown,
-    theme: unknown,
-    context: unknown,
-    nativeRenderer?: unknown,
-  ) => Component | undefined;
-};
-
 type ToolExecutionProto = {
   toolName: string;
   toolCallId: string;
@@ -94,16 +74,12 @@ type ToolExecutionProto = {
 };
 
 /**
- * PATCH 1 — give the compact renderer priority and remove the self-shell spacer
- * when a tool row temporarily hosts the one folded-activity summary.
+ * Give the compact renderer priority and normalize the self-shell spacer when a
+ * tool row hosts the one folded-activity summary.
  *
- * Replaces the old `getCallRenderer` / `getResultRenderer` /
- * `hasRendererDefinition` / `getRenderShell` bundle rewrite, plus both
- * `create*Fallback` rewrites. The fallbacks no longer need patching: because
- * `hasRendererDefinition()` and the two getters now always answer for a handled
- * tool, core never reaches its verbose `formatToolExecution()` branch, and
- * late-registered tools with `toolDefinition === undefined` are covered by the
- * same condition.
+ * `hasRendererDefinition()` and the two getters always answer for a handled tool,
+ * so core never reaches its verbose `formatToolExecution()` branch, and
+ * late-registered tools with `toolDefinition === undefined` are covered too.
  *
  * The native tool definitions are NOT touched: this is render-only, so built-ins
  * keep their builtin source ownership and pi-subagents keeps exposing
@@ -117,19 +93,15 @@ export function patchToolExecution(proto: ToolExecutionProto): void {
   /**
    * "Ours" when the bridge claims this tool name — and ONLY then.
    *
-   * `handles()` is now the single authority (blacklist plus the master switch),
-   * so it covers rendererless MCP/third-party tools and late-registered tools
-   * whose definition is missing from the UI lookup entirely.
-   *
-   * There used to be an extra "...or the tool has no renderer of its own"
-   * fallback here. Under the old whitelist it was load-bearing. With a blacklist
-   * it silently OVERRODE the user: an excluded tool with no renderer, and every
-   * tool when `compactToolRows` was off, got compacted anyway.
+   * `handles()` is the single authority (blacklist plus the master switch), so it
+   * covers rendererless MCP/third-party tools and late-registered tools whose
+   * definition is missing from the UI lookup entirely. Do NOT also claim "any
+   * tool with no renderer of its own": that overrides the user's exclusions and
+   * the master switch.
    */
-  function claims(this: ToolExecutionProto): ToolRendererBridge | undefined {
-    const renderer = bridge<ToolRendererBridge>("toolRenderer");
-    if (!renderer?.renderCall) return undefined;
-    return renderer.handles?.(this.toolName) ? renderer : undefined;
+  function claims(this: ToolExecutionProto): ToolRenderer | undefined {
+    const renderer = bridge()?.toolRenderer;
+    return renderer?.handles(this.toolName) ? renderer : undefined;
   }
 
   once(proto, "toolExecution", () => {
@@ -138,6 +110,8 @@ export function patchToolExecution(proto: ToolExecutionProto): void {
     const ownership = new WeakMap<ToolExecutionProto, boolean>();
     function syncShell(this: ToolExecutionProto): boolean {
       const claimed = claims.call(this) !== undefined;
+      // A card we do not draw is still visible: let it cut folded runs.
+      if (!claimed && this.toolCallId) barrier(this.toolCallId);
       const shell = this.hasRendererDefinition()
         ? this.getRenderShell() === "self" ? this.selfRenderContainer : this.contentBox
         : this.contentTextRegion;
@@ -167,17 +141,17 @@ export function patchToolExecution(proto: ToolExecutionProto): void {
 
     proto.getCallRenderer = function () {
       const renderer = claims.call(this);
-      if (!renderer?.renderCall) return this.toolDefinition?.renderCall;
+      if (!renderer) return this.toolDefinition?.renderCall;
       return (args: unknown, theme: unknown, context: unknown) =>
-        renderer.renderCall!(this.toolName, args, theme, context);
+        renderer.renderCall(this.toolName, args, theme, context);
     };
 
     proto.getResultRenderer = function () {
       const renderer = claims.call(this);
-      if (!renderer?.renderResult) return this.toolDefinition?.renderResult;
-      const nativeRenderer = this.toolDefinition?.renderResult;
+      if (!renderer) return this.toolDefinition?.renderResult;
+      const nativeRenderer = this.toolDefinition?.renderResult as NativeResultRenderer | undefined;
       return (result: unknown, options: unknown, theme: unknown, context: unknown) => {
-        const component = renderer.renderResult!(this.toolName, result, options, theme, context, nativeRenderer);
+        const component = renderer.renderResult(this.toolName, result, options, theme, context, nativeRenderer);
         // `undefined` means "show Pi's own text output". Core's RESULT-RENDERER
         // path (unlike its fallback path) would wrap undefined in a MouseRegion
         // and crash at render, so resolve the fallback here instead.
@@ -203,7 +177,7 @@ export function patchToolExecution(proto: ToolExecutionProto): void {
       // Rebuild once on transition, never on every render (or during a renderer).
       if (syncShell.call(this)) nativeUpdateDisplay.call(this);
       const lines = nativeRender.call(this, width);
-      const ownsSummary = bridge<(id: string) => boolean>("activitySummaryRow")?.(this.toolCallId);
+      const ownsSummary = bridge()?.activitySummaryRow(this.toolCallId);
       // The summary must have the same one-line separation regardless of which
       // tool/assistant component happened to become its host.
       return ownsSummary ? withOneLeadingBlank(lines) : lines;
@@ -211,34 +185,40 @@ export function patchToolExecution(proto: ToolExecutionProto): void {
   });
 }
 
-/** Renders nothing, for the "no result content at all" case. */
-const EMPTY: Component = { render: () => [], invalidate: () => {} };
+/**
+ * A user message is visible but never observed otherwise, so without this a
+ * folded run could jump over it. It is a barrier: it only cuts runs.
+ */
+export function patchUserMessage(proto: { rebuild(): void }): void {
+  once(proto, "userMessage", () => {
+    const nativeRebuild = proto.rebuild;
+    // Keyed on the text: Pi builds NEW components for the same messages on every
+    // chat rebuild, and a per-component id would append a fresh barrier each time.
+    proto.rebuild = function (this: { rebuild(): void; text: string }) {
+      nativeRebuild.call(this);
+      barrier("user:" + this.text);
+    };
+  });
+}
 
 // ---------------------------------------------------------------------------
-// PATCH 2 — thinking blocks
+// Assistant messages: thinking, prose, summaries
 // ---------------------------------------------------------------------------
 
-type ThinkingBridge = (
-  text: string,
-  theme: unknown,
-  pad: number,
-  streaming?: boolean,
-  owner?: object,
-  runIndex?: number,
-) => Component;
-
 type AssistantProto = {
   contentContainer: { children: Component[] };
   hideThinkingBlock: boolean;
   thinkingVisibilityOverrides: Map<number, boolean>;
   markdownTheme: Record<string, unknown>;
-  outputPad: number;
   isStreaming: boolean;
   lastMessage?: any;
   updateContent(message: any, isStreaming?: boolean): void;
   render(width: number): string[];
+  handleMouse(event: MouseLike): unknown;
 };
 
+type MouseLike = { y: number; height: number };
+
 /** One thinking run: consecutive `thinking` blocks, exactly as core groups them. */
 function thinkingRuns(message: any): string[][] {
   const runs: string[][] = [];
@@ -258,8 +238,7 @@ function thinkingRuns(message: any): string[][] {
 
 /**
  * Core wraps every thinking run — and ONLY a thinking run — in a MouseRegion, so
- * the Nth MouseRegion in contentContainer is the Nth thinking run. That is the
- * seam this patch uses instead of the old bundle rewrite.
+ * the Nth MouseRegion in contentContainer is the Nth thinking run.
  *
  * Recognized STRUCTURALLY, not by `instanceof` or `constructor.name`, because
  * neither is reliable across Pi's loading modes:
@@ -274,15 +253,10 @@ function isMouseRegion(value: any): boolean {
   return typeof value?.onMouse === "function" && value.child !== undefined;
 }
 
-function thinkingRegions(children: Component[]): any[] {
-  return children.filter(isMouseRegion);
-}
-
 /**
- * PATCH 2 — collapsed preview, streaming expansion, all-purple expanded
- * Markdown, and the run-grouping chronology/spacer hooks.
- *
- * Replaces five bundle rewrites inside `updateContent` with one wrapper:
+ * Collapsed preview, streaming expansion, all-purple expanded Markdown, the
+ * run-grouping chronology/spacer hooks, and the summary spacing and mouse
+ * correction in `render` / `handleMouse`. `updateContent` does:
  *
  *  - active thinking: a streaming block stays COLLAPSED by default (its compact
  *    preview already shows the latest text). `keepActiveThinkingExpanded` forces
@@ -303,14 +277,19 @@ export function patchAssistantMessage(proto: AssistantProto): void {
   once(proto, "assistantMessage", () => {
     const nativeUpdateContent = proto.updateContent;
     const nativeRender = proto.render;
+    const nativeHandleMouse = proto.handleMouse;
     const compactState = new WeakMap<AssistantProto, boolean>();
+    // withOneLeadingBlank() changes the lines AFTER Container.render() recorded
+    // its mouse layout, so Pi's y (relative to the lines we returned) would
+    // miss the summary by that shift. Remember it to translate clicks back.
+    const mouseShift = new WeakMap<AssistantProto, { shift: number; height: number }>();
 
     proto.updateContent = function (this: AssistantProto, message: any, isStreaming = this.isStreaming) {
       const savedHide = this.hideThinkingBlock;
       const savedOverrides = this.thinkingVisibilityOverrides;
       // Default: a streaming block stays collapsed to its compact preview, which
       // already shows the newest text. Opt in to force it open instead.
-      const forceOpen = isStreaming && bridge<() => boolean>("keepActiveThinkingExpanded")?.() === true;
+      const forceOpen = isStreaming && bridge()?.keepActiveThinkingExpanded() === true;
       if (forceOpen) {
         this.hideThinkingBlock = false;
         this.thinkingVisibilityOverrides = new Map();
@@ -334,41 +313,43 @@ export function patchAssistantMessage(proto: AssistantProto): void {
         this.updateContent(this.lastMessage, this.isStreaming);
       }
       const lines = nativeRender.call(this, width);
-      const view = bridge<(owner: object) => "normal" | "hidden" | "summary">("activityMessageView")?.(this);
+      const view = bridge()?.activityMessageView(this);
       if (view === "hidden") return [];
-      return view === "summary" ? withOneLeadingBlank(lines) : lines;
+      if (view !== "summary") {
+        mouseShift.delete(this);
+        return lines;
+      }
+      mouseShift.set(this, { shift: lines.findIndex((line) => !visiblyBlank(line)) - 1, height: lines.length });
+      return withOneLeadingBlank(lines);
+    };
+
+    proto.handleMouse = function (this: AssistantProto, event: MouseLike) {
+      const moved = mouseShift.get(this);
+      return nativeHandleMouse.call(this, moved ? { ...event, y: event.y + moved.shift, height: moved.height } : event);
     };
   });
 }
 
 function compactThinking(): boolean {
-  return bridge<Config>("config")?.get("thinkingAsToolCall") === true;
+  return bridge()?.compactThinking() === true;
 }
 
+type Decorating = {
+  bridge: Bridge;
+  theme: ThemeLike | undefined;
+  component: AssistantProto;
+  message: any;
+  isStreaming: boolean;
+  compact: boolean;
+};
+
 function decorateThinking(component: AssistantProto, message: any, isStreaming: boolean, compact: boolean): void {
-  const preview = bridge<ThinkingBridge>("thinkingPreview");
-  const purple = bridge<(base: Record<string, unknown>, theme: unknown) => Record<string, unknown>>(
-    "thinkingMarkdownTheme",
-  );
-  const observeThinking = bridge<(owner: object, run: number, streaming: boolean, hidden: boolean) => string>(
-    "observeThinking",
-  );
-  const observeProse = bridge<(
-    owner: object,
-    contentIndex: number,
-    signal: {
-      phase?: "commentary" | "final_answer";
-      stopReason?: string;
-      streaming?: boolean;
-      timestamp?: number;
-    },
-  ) => string>("observeProse");
-  const proseView = bridge<(id: string, theme: ThemeLike) => Row | null | undefined>("proseView");
-  const messageSpacer = bridge<(owner: object) => boolean>("messageSpacer");
-  const theme = liveTheme();
+  const b = bridge();
+  if (!b) return;
+  const ctx: Decorating = { bridge: b, theme: liveTheme(), component, message, isStreaming, compact };
 
   const children = component.contentContainer.children;
-  const regions = thinkingRegions(children);
+  const regions: any[] = children.filter(isMouseRegion);
   const runs = thinkingRuns(message);
 
   // Direct Markdown children correspond one-for-one with non-empty text blocks;
@@ -384,73 +365,88 @@ function decorateThinking(component: AssistantProto, message: any, isStreaming:
   for (let i = 0; i < (message?.content?.length ?? 0); i++) {
     const content = message.content[i];
     if (content?.type === "text" && String(content.text ?? "").trim()) {
-      const phase = textPhase(content.textSignature);
-      const id = observeProse?.(component, i, {
-        phase,
-        stopReason: message.stopReason,
-        streaming: isStreaming,
-        timestamp: message.timestamp,
-      });
-      const target = proseChildren[prose++];
-      if (id && target && proseView && theme) {
-        children[target.index] = new FoldableProse(target.child, () => proseView(id, theme as ThemeLike));
-      }
+      wrapProse(ctx, i, proseChildren[prose++]);
       continue;
     }
     if (content?.type !== "thinking") continue;
     while (i + 1 < message.content.length && message.content[i + 1]?.type === "thinking") i++;
     const blocks = runs[run];
     if (!blocks) continue;
-    const entry = regions[run];
+    const region = regions[run];
     const runIndex = run++;
-    if (!entry) continue;
-
-    const inner = entry.child as any;
-    // Collapsed runs are a Text (the hidden label); expanded runs are a Markdown.
-    // Only Markdown carries a `theme` field, which is also the field the
-    // all-purple recolor needs, so one check serves both branches.
-    const hidden = inner?.theme === undefined;
-    // Pass `hidden` THROUGH, never `!hidden`. bridge.ts negates it into
-    // `expanded` itself, so negating here too inverted all run folding: expanded
-    // thinking became foldable (swallowing whole runs of tool rows into one
-    // summary) and collapsed thinking stopped folding entirely.
-    const id = observeThinking?.(component, runIndex, isStreaming, hidden);
-
-    if (!compact) {
-      // Native thinking still participates in the separately enabled activity
-      // fold, just like native prose. Otherwise keep Pi's component untouched.
-      if (id && proseView && theme) {
-        entry.child = new FoldableProse(inner, () => proseView(id, theme as ThemeLike));
-      }
-      continue;
-    }
+    if (region) wrapThinkingRun(ctx, region, blocks, runIndex);
+  }
 
-    if (hidden) {
-      if (!preview || !theme) continue;
-      // MouseRegion.child is `private` in TS only; reassigning keeps the
-      // existing click handler (and therefore the expand/collapse toggle).
-      entry.child = preview(
-        blocks.join("\n"),
-        theme,
-        component.outputPad,
-        isStreaming,
-        component,
-        runIndex,
-      );
-    } else if (purple && theme && inner?.theme !== undefined) {
-      // Markdown reads its (TS-private) theme at render time, and this runs
-      // before the first render, so recoloring in place needs no reconstruction.
-      inner.theme = purple(component.markdownTheme, theme);
-    }
+  wrapSpacer(ctx, children);
+}
+
+/** Wrap a host in the folding component for entry `id`. */
+function foldable({ bridge: b, theme }: Decorating, inner: Component, id: string): Component {
+  return new FoldableProse(
+    inner,
+    () => b.proseView(id, theme!),
+    () => b.proseHeader(id, theme!),
+    (onHeader) => b.click(id, onHeader),
+  );
+}
+
+/** Observe one prose block and, when a theme is live, let it fold. */
+function wrapProse(ctx: Decorating, contentIndex: number, target: { child: any; index: number } | undefined): void {
+  const { bridge: b, component, message, isStreaming, theme } = ctx;
+  const id = b.observeProse(component, contentIndex, {
+    stopReason: message.stopReason,
+    streaming: isStreaming,
+    timestamp: message.timestamp,
+  });
+  if (id && target && theme) component.contentContainer.children[target.index] = foldable(ctx, target.child, id);
+}
+
+/** Observe one thinking run (a MouseRegion) and replace what it shows. */
+function wrapThinkingRun(ctx: Decorating, region: any, blocks: string[], runIndex: number): void {
+  const { bridge: b, component, message, isStreaming, theme, compact } = ctx;
+  const inner = region.child as any;
+  // Collapsed runs are a Text (the hidden label); expanded runs are a Markdown.
+  // Only Markdown carries a `theme` field, which is also the field the
+  // all-purple recolor needs, so one check serves both branches.
+  const hidden = inner?.theme === undefined;
+  // Pass `hidden` THROUGH, never `!hidden`. The bridge negates it into
+  // `expanded` itself, so negating here too inverted all run folding: expanded
+  // thinking became foldable (swallowing whole runs of tool rows into one
+  // summary) and collapsed thinking stopped folding entirely.
+  const id = b.observeThinking(component, runIndex, isStreaming, hidden, message.timestamp);
+
+  if (!compact) {
+    // Native thinking still participates in the separately enabled activity
+    // fold, just like native prose. Otherwise keep Pi's component untouched.
+    if (id && theme) region.child = foldable(ctx, inner, id);
+    return;
+  }
+  if (!theme) return;
+
+  if (hidden) {
+    // MouseRegion.child is `private` in TS only; reassigning keeps the
+    // existing click handler (and therefore the expand/collapse toggle).
+    region.child = b.thinkingPreview(blocks.join("\n"), theme, isStreaming, component, runIndex);
+  } else {
+    // Markdown reads its (TS-private) theme at render time, and this runs
+    // before the first render, so recoloring in place needs no reconstruction.
+    inner.theme = b.thinkingMarkdownTheme(component.markdownTheme, theme);
+    // Host the header like native thinking does, so an opened run's header
+    // can sit above this row too.
+    if (id) region.child = foldable(ctx, inner, id);
   }
+}
 
-  // Leading spacer: hidden only when every row of this message is hidden.
-  // Identified by what it DOES (renders exactly one blank line) rather than by
-  // class, for the same cross-loading-mode reason as isMouseRegion.
+/**
+ * Leading spacer: hidden only when every row of this message is hidden.
+ * Identified by what it DOES (renders exactly one blank line) rather than by
+ * class, for the same cross-loading-mode reason as isMouseRegion.
+ */
+function wrapSpacer({ bridge: b, component }: Decorating, children: Component[]): void {
   const first = children[0] as any;
-  if (messageSpacer && first && typeof first.setLines === "function") {
+  if (first && typeof first.setLines === "function") {
     children[0] = {
-      render: () => (messageSpacer(component) === false ? [] : [""]),
+      render: () => (b.messageSpacer(component) === false ? [] : [""]),
       invalidate: () => {},
     };
   }
@@ -473,19 +469,9 @@ function visiblyBlank(line: string): boolean {
     .trim() === "";
 }
 
-function textPhase(signature: unknown): "commentary" | "final_answer" | undefined {
-  if (typeof signature !== "string" || !signature.startsWith("{")) return undefined;
-  try {
-    const phase = JSON.parse(signature).phase;
-    return phase === "commentary" || phase === "final_answer" ? phase : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /** Pi's live Theme instance, shared through globalThis by its theme module. */
-function liveTheme(): unknown {
-  return (globalThis as Globals)[Symbol.for("@earendil-works/pi-coding-agent:theme")];
+function liveTheme(): ThemeLike | undefined {
+  return (globalThis as Globals)[Symbol.for("@earendil-works/pi-coding-agent:theme")] as ThemeLike | undefined;
 }
 
 /**
@@ -499,6 +485,7 @@ function liveTheme(): unknown {
 export function patchCore(core: {
   ToolExecutionComponent?: new (...args: never[]) => unknown;
   AssistantMessageComponent?: new (...args: never[]) => unknown;
+  UserMessageComponent?: new (...args: never[]) => unknown;
 }): void {
   // Pi's `private` members make these classes structurally unassignable to the
   // interfaces above, so cross the boundary once, here, explicitly.
@@ -507,4 +494,6 @@ export function patchCore(core: {
   const assistant = proto(core.AssistantMessageComponent);
   if (tool) patchToolExecution(tool);
   if (assistant) patchAssistantMessage(assistant);
+  const user = proto(core.UserMessageComponent);
+  if (user) patchUserMessage(user);
 }

package/src/row.ts

@@ -4,15 +4,11 @@
  * TWO RULES THIS FILE ENFORCES
  * ---------------------------
  * 1. Rows are described as DATA and painted exactly once. Nothing downstream may
- *    re-parse painted text. An earlier version built `"read src/a.ts"` and then
- *    split it on the first space to recolor the action word, which silently
- *    assumed no label ever contains a space; run summaries were joined into
- *    `"read ×2, edit ×1"` and split back apart the same way.
+ *    re-parse painted text (splitting `"read src/a.ts"` on the first space
+ *    assumes no label contains a space).
  *
- * 2. Theme and settings are bound ONCE, in a `Painter`. There used to be a
- *    module-level mutable config with `config = defaultConfig()` defaults on four
- *    functions, which made painting depend on load order and let one test leak
- *    settings into the next.
+ * 2. Theme and settings are bound ONCE, in a `Painter`, so painting never
+ *    depends on load order and one test cannot leak settings into the next.
  *
  * Free of Pi extension-API runtime imports, so tests exercise real painting
  * without an extension runtime.
@@ -20,12 +16,8 @@
 
 // Type-only: erased at runtime, but makes a mistyped token ("succes") a compile
 // error instead of a theme.fg() throw that core turns into a verbose card.
-import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
-import type { Config } from "./config.ts";
-
-// ThemeBg is not exported publicly, so recover it from Theme.bg's own signature
-// rather than importing a deep dist path (which is not a package export).
-type ThemeBg = Parameters<Theme["bg"]>[0];
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { OPEN_MARKER, type Config } from "./config.ts";
 
 /**
  * Minimal theme surface. Pi's real Theme satisfies it; tests pass a fake that
@@ -37,7 +29,6 @@ type ThemeBg = Parameters<Theme["bg"]>[0];
  */
 export type ThemeLike = {
   fg(token: ThemeColor, text: string): string;
-  bg(token: ThemeBg, text: string): string;
 };
 
 /** One painted row. `text` is already colored; truncation happens at render. */
@@ -46,16 +37,21 @@ export type Row = {
   gutter: string;
   /** Fully colored row content. */
   text: string;
-  /** Full-width background, applied after truncation. */
-  highlight?: (text: string) => string;
+  /**
+   * Set on an expanded row: wrap instead of truncating. `head` is the colored
+   * `glyph label` prefix (no timer badge, whose width changes) and `body` the
+   * colored `[badge] details`; continuation lines are indented under `head`.
+   */
+  wrap?: { head: string; body: string };
+  /** Header line drawn above an opened run's first row (then one blank line); clicking it folds the run back. */
+  header?: Row;
 };
 
 /**
  * Visible columns a gutter occupies: one space, the glyph, one space.
  *
- * DERIVED from the row's own gutter text, never configured. An earlier design
- * exported this as a constant, which could disagree with the real glyph width and
- * shift every row.
+ * DERIVED from the row's own gutter text, never configured, so it cannot
+ * disagree with the real glyph width and shift every row.
  */
 export function gutterWidth(gutter: string): number {
   return gutter === "" ? 0 : 3;
@@ -78,8 +74,8 @@ export type Labeled = {
   badge?: string;
   /** Path, command, or preview text. */
   details?: string;
-  /** Highlight the row background (streaming thinking only). */
-  highlight?: boolean;
+  /** Wrap long details onto more lines instead of truncating (expanded tool rows). */
+  wrap?: boolean;
 };
 
 /** One folded name and how many times it appeared in a run. */
@@ -101,8 +97,6 @@ export type RunSummary = {
   running: Count[];
 };
 
-export const EMPTY_SUMMARY: RunSummary = { done: [], failed: [], running: [] };
-
 /**
  * Paints rows for one theme and one settings object.
  *
@@ -144,14 +138,24 @@ export class Painter {
     const parts: string[] = [];
     if (spec.glyph) parts.push(this.theme.fg(spec.glyphColor ?? tokens.label, spec.glyph));
     parts.push(this.theme.fg(labelColor, spec.label));
-    if (spec.badge) parts.push(this.theme.fg(tokens.label, spec.badge));
-    if (spec.details) parts.push(this.theme.fg(tokens.details, spec.details));
+    // The wrap indent is `glyph label` ONLY: the timer badge changes width every
+    // 1s/10s/100s and must not shift (re-wrap) the continuation lines.
+    const head = parts.join(" ");
+    // `text` is always ONE line. Details with real newlines (an expanded
+    // command) are flattened for it and kept for `wrap`, colored line by line so
+    // no color escape spans a newline.
+    const details = spec.details ?? "";
+    const flat = details.includes("\n") ? details.replace(/\s+/g, " ").trim() : details;
+    const paintDetails = (text: string) => this.theme.fg(tokens.details, text);
+    const badge = spec.badge ? this.theme.fg(tokens.label, spec.badge) : "";
+    const rest = [badge, flat && paintDetails(flat)].filter(Boolean);
+    const wrapBody = [badge, details && details.split("\n").map(paintDetails).join("\n")].filter(Boolean);
     return {
       // The gutter follows the label's hue, so thinking rows stay purple and tool
       // rows stay green without either caller naming a gutter color.
       gutter: this.gutter(labelColor),
-      text: parts.join(" "),
-      highlight: spec.highlight ? (text) => this.theme.bg(tokens.activeBg, text) : undefined,
+      text: [head, ...rest].join(" "),
+      wrap: spec.wrap && spec.details ? { head, body: wrapBody.join(" ") } : undefined,
     };
   }
 
@@ -176,6 +180,18 @@ export class Painter {
     return { gutter: this.gutter(label), text: groups.join(this.theme.fg(details, " · ")) };
   }
 
+  /**
+   * The header of an opened run: a muted control line, not data, so it carries
+   * no counts. Clicking it folds the run back. ASCII mode swaps `·` for `-`.
+   * No gutter bar: blank padding of the gutter width keeps its text aligned with
+   * the rows below it (no padding at all when the gutter is off).
+   */
+  header(): Row {
+    const ascii = this.config.get("glyphStyle") === "ascii";
+    const text = `${OPEN_MARKER[this.config.get("glyphStyle")]} Expanded ${ascii ? "-" : "·"} click to fold`;
+    return { gutter: this.config.get("gutter") ? "   " : "", text: this.theme.fg("muted", text) };
+  }
+
   private counts(counts: Count[], color: ThemeColor): string {
     const tokens = this.config.tokens();
     const glyphs = this.config.glyphs();