pi-better-harness 0.27.1 → 0.28.0

package/README.md

@@ -68,11 +68,12 @@ The bundled harness provides **Tool output: Normal / Minimal** in
 `/harness-settings`. `/tool-output minimal`, `/tool-output normal`, and
 `/tool-output` (toggle) remain compatibility shortcuts to the same preference.
 Minimal mode folds each tool call into a single-line header, including running
-calls. Each row has a single tool-specific icon: accent-colored while running,
-muted when completed, and error-colored when failed. Tool names stay muted;
-inline command/path arguments use the theme's distinct dim tone. Running and
-failed calls retain text labels so state never depends on color alone. Activity
-stays quieter than conversation text. Tool rows are indented two columns past
+calls. The tool-specific icon and tool name share a state color: accent while
+running, muted when completed, and error-colored when failed. In fullscreen Pi, a soft highlight travels through visible running names; inline
+command/path arguments stay dim. Scrollback terminals keep static state colors.
+Choose **Tool animation: Off** in `/harness-settings` for static running headers.
+Running and failed calls retain text labels so state never depends on color or
+motion alone. Tool rows are indented two columns past
 the assistant text padding. Long
 headers are truncated to the terminal width; result bodies,
 images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls
@@ -130,8 +131,10 @@ to the `/agents` catalog. `/sandbox`, `/subagents settings`, `/agents`, and
 `/goal settings` remain available in standalone installations.
 Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
 
-The hub includes **Tool output** when the bundled renderer extension is loaded.
-Changes apply immediately and also save the default for future sessions.
+The hub includes **Tool output** and **Tool animation** when the bundled renderer
+extension is loaded. Changes apply immediately and save the default for future
+sessions. The animation preference is stored in `piBetterHarness.toolAnimation`;
+normal output and expanded tool details are never animated.
 The hub also owns **Completions while busy**, shared by Subagents and Background
 Tasks. Choose **Wait until idle** (the default) or **Steer active run**. Changes
 apply immediately and autosave to the current session branch, including across

package/extensions/minimal-output/hook.ts

@@ -5,8 +5,10 @@ import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { supportsToolShimmer, toolIdentity } from "./tool-identity.ts";
+import { toolVisibility, type ViewportUI } from "./tool-visibility.ts";
 
-interface ToolUI {
+interface ToolUI extends ViewportUI {
   requestRender(): void;
   children?: TranscriptComponent[];
   handleViewportInput?(data: string): unknown;
@@ -70,6 +72,8 @@ interface ToolPrototype {
 }
 interface HookState {
   enabled: boolean;
+  animationEnabled: boolean;
+  stopAnimation(): void;
   owners: number;
   redraw(collapse?: boolean): void;
   restore(): void;
@@ -79,6 +83,7 @@ interface HookState {
 }
 export interface MinimalOutputHook {
   setEnabled(enabled: boolean): void;
+  setAnimationEnabled(enabled: boolean): void;
   completeRun(): void;
   restoreCompletedCalls(ids: Iterable<string>): void;
   dispose(): void;
@@ -146,7 +151,7 @@ function harnessCallDetail(name: string, input: unknown): string | undefined {
   }
 }
 
-function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3): string[] {
+function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3, animationTime?: number): string[] {
   if (width <= 0) return [];
   // Render the call alone at a wider width so terminal wrapping becomes truncation.
   const header = Boolean(component.getCallRenderer?.()) && component.callRendererComponent?.render(Math.max(4096, width + 1))
@@ -170,7 +175,7 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   const icon = TOOL_ICONS[component.toolName] ?? "\u25c7";
   const title = ` ${icon} ${label}`;
   const styled = theme
-    ? ` ${theme.fg(failed ? "error" : running ? "accent" : "muted", icon)} ${theme.fg("muted", label)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
+    ? ` ${toolIdentity(icon, label, failed ? "error" : running ? "accent" : "muted", theme, animationTime)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
     : `${title}${detail ? `  ${detail}` : ""}${suffix}`;
   return [truncateToWidth(`${" ".repeat(Math.min(indent, Math.max(0, width - 1)))}${styled}`, width)];
 }
@@ -304,6 +309,50 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     const seen = new WeakSet<ToolComponent>();
     const components = new Set<WeakRef<ToolComponent>>();
+    const animationReferences = new WeakMap<ToolComponent, WeakRef<ToolComponent>>();
+    const animated = new Map<WeakRef<ToolComponent>, number>();
+    const settled = new WeakSet<ToolComponent>();
+    let animationTimer: ReturnType<typeof setInterval> | undefined;
+    const stopAnimation = () => {
+      if (animationTimer !== undefined) clearInterval(animationTimer);
+      animationTimer = undefined;
+      animated.clear();
+    };
+    const canAnimate = (component: ToolComponent) => {
+      const theme = getTheme?.();
+      return state!.enabled && state!.animationEnabled && component.ui.mode === "fullscreen"
+        && !!theme && supportsToolShimmer(theme)
+        && !component.expanded && !component.result?.isError && (!component.result || component.isPartial)
+        && !settled.has(component);
+    };
+    const pruneAnimation = () => {
+      for (const [reference, lastRender] of animated) {
+        const component = reference.deref();
+        if (!component || !canAnimate(component) || Date.now() - lastRender > 400
+          || toolVisibility(component.ui, component) !== true) animated.delete(reference);
+      }
+      if (!animated.size) stopAnimation();
+    };
+    const animationTime = (component: ToolComponent, width: number, indent: number) => {
+      if (width <= indent + 3 || !canAnimate(component) || toolVisibility(component.ui, component) === false) return undefined;
+      let reference = animationReferences.get(component);
+      if (!reference) { reference = new WeakRef(component); animationReferences.set(component, reference); }
+      animated.set(reference, Date.now());
+      if (animationTimer === undefined) {
+        animationTimer = setInterval(() => {
+          pruneAnimation();
+          const uis = new Set<ToolUI>();
+          for (const reference of animated.keys()) {
+            const component = reference.deref();
+            if (!component) continue;
+            uis.add(component.ui);
+          }
+          for (const ui of uis) ui.requestRender();
+        }, 80);
+        animationTimer.unref?.();
+      }
+      return toolVisibility(component.ui, component) === true ? Date.now() : undefined;
+    };
     let completed = new Map<string, object>();
     let groups = new WeakMap<ToolComponent, ToolGroup>();
     let layouts = new WeakMap<ToolComponent, { parent: TranscriptComponent; anchor?: TranscriptComponent }>();
@@ -344,11 +393,15 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     state = {
       enabled: false,
+      animationEnabled: true,
+      stopAnimation,
       owners: 0,
       completeRun() {
+        stopAnimation();
         const run = {};
         for (const reference of components) {
           const component = reference.deref();
+          if (component) settled.add(component);
           if (component?.result && !component.isPartial && !completed.has(component.toolCallId)) {
             completed.set(component.toolCallId, run);
             if (this.enabled) component.setExpanded(false);
@@ -357,6 +410,11 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         this.redraw();
       },
       restoreCompletedCalls(ids) {
+        stopAnimation();
+        for (const reference of components) {
+          const component = reference.deref();
+          if (component) settled.add(component);
+        }
         const history = {};
         completed = new Map(Array.from(ids, id => [id, history]));
         groups = new WeakMap();
@@ -372,8 +430,10 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           else component.invalidate();
           component.ui.requestRender();
         }
+        pruneAnimation();
       },
       restore() {
+        stopAnimation();
         clearHover();
         for (const [ui, { original, wrapper }] of inputWrappers) {
           if (ui.handleViewportInput === wrapper) ui.handleViewportInput = original;
@@ -498,6 +558,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           this.ui.handleViewportInput = wrapper;
         }
         if (!seen.has(this)) { seen.add(this); components.add(new WeakRef(this)); }
+        pruneAnimation();
         if (!current.enabled || this.expanded) return originals.updateDisplay.apply(this, args);
         const showImages = this.showImages;
         const lastRenderer = this.resultRendererComponent;
@@ -517,6 +578,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         if (args[0] === false && !mouseHandling && group) group.open = false;
         const result = originals.setExpanded.apply(this, args);
         if (group) group.expanded += Number(this.expanded) - Number(wasExpanded);
+        pruneAnimation();
         return result;
       },
       getResultRenderer(this: ToolComponent, ...args: unknown[]) {
@@ -531,7 +593,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         const padding = layout?.anchor?.outputPad ?? 1;
         const indent = Number.isFinite(padding) ? Math.max(0, Math.floor(padding)) + 2 : 3;
         const group = groupFor(this, layout?.parent);
-        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent), width);
+        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent, animationTime(this, width, indent)), width);
         const open = group.open || group.expanded > 0;
         const first = group.members[0] === this;
         const lines: string[] = [];
@@ -591,6 +653,12 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
       current.enabled = enabled;
       current.redraw(enabled);
     },
+    setAnimationEnabled(enabled) {
+      if (disposed) return;
+      current.animationEnabled = enabled;
+      if (!enabled) current.stopAnimation();
+      current.redraw();
+    },
     dispose() {
       if (disposed) return;
       disposed = true;

package/extensions/minimal-output/index.ts

@@ -10,6 +10,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   let enabled = false;
   let running = false;
   let initialDefault: boolean | undefined;
+  let motionEnabled = true;
 
   function defaultEnabled(): boolean {
     if (initialDefault !== undefined) return initialDefault;
@@ -52,6 +53,16 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       enabled = false;
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
     }
+    try {
+      const motion = readHarnessSetting<{ version?: unknown; enabled?: unknown }>("toolAnimation");
+      if (motion !== undefined && (motion?.version !== 1 || typeof motion.enabled !== "boolean")) {
+        throw new Error("Invalid tool-animation default in global settings.json.");
+      }
+      motionEnabled = motion?.enabled !== false;
+    } catch (error) {
+      motionEnabled = false;
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
         const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
@@ -60,6 +71,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     // Observe transcript components from startup, so the toggle also redraws existing rows.
     if (await ensureHook(ctx)) {
+      hook!.setAnimationEnabled(motionEnabled);
       hook!.restoreCompletedCalls(ctx.sessionManager.getBranch().flatMap(entry =>
         entry.type === "message" && entry.message.role === "toolResult" ? [entry.message.toolCallId] : []));
       if (enabled) collapseTools(ctx);
@@ -93,7 +105,21 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     id: "tool-output", label: "Tool output", values: ["Normal", "Minimal"],
     get: () => enabled ? "Minimal" : "Normal", change,
   };
-  const register = () => pi.events.emit("harness-settings:register", setting);
+  const animationSetting: SettingsControl = {
+    id: "tool-animation", label: "Tool animation", values: ["Shimmer", "Off"],
+    get: () => motionEnabled ? "Shimmer" : "Off",
+    async change(value, ctx) {
+      if (value !== "Shimmer" && value !== "Off") throw new Error("Invalid tool animation mode.");
+      if (!await ensureHook(ctx)) throw new Error("Tool animation settings are unavailable in this Pi runtime.");
+      updateHarnessSetting("toolAnimation", () => ({ version: 1, enabled: value === "Shimmer" }));
+      motionEnabled = value === "Shimmer";
+      hook!.setAnimationEnabled(motionEnabled);
+    },
+  };
+  const register = () => {
+    pi.events.emit("harness-settings:register", setting);
+    pi.events.emit("harness-settings:register", animationSetting);
+  };
   let stopSettings: (() => void) | undefined;
   const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
   subscribe();
@@ -115,6 +141,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     enabled = false;
     running = false;
     initialDefault = undefined;
+    motionEnabled = true;
   });
 
   pi.registerCommand("tool-output", {

package/extensions/minimal-output/tool-identity.ts

@@ -0,0 +1,66 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+type RGB = [number, number, number];
+interface ConcreteColor { kind: string; index?: number; r?: number; g?: number; b?: number }
+const concreteColors = (theme: Theme) => (theme as Theme & { colors?: Record<string, ConcreteColor> }).colors;
+const PERIOD = 2400;
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function themeRgb(theme: Theme, token: "accent" | "text"): RGB | undefined {
+  const color = concreteColors(theme)?.[token];
+  if (color?.kind === "rgb" && color.r !== undefined && color.g !== undefined && color.b !== undefined) {
+    return [color.r, color.g, color.b];
+  }
+  return rgb(theme.getFgAnsi(token));
+}
+
+export function supportsToolShimmer(theme: Theme): boolean {
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  const accent = concreteColors(theme)?.accent;
+  return (!!base && !!light && base.some((value, index) => value !== light[index]))
+    || (accent?.kind === "indexed" && accent.index !== undefined && accent.index >= 0 && accent.index < 16);
+}
+
+function rgb(ansi: string): RGB | undefined {
+  const direct = /\x1b\[38;2;(\d+);(\d+);(\d+)m/.exec(ansi);
+  if (direct) return [Number(direct[1]), Number(direct[2]), Number(direct[3])];
+  const indexed = /\x1b\[38;5;(\d+)m/.exec(ansi);
+  if (!indexed) return undefined;
+  const index = Number(indexed[1]);
+  // The first 16 colors are terminal-defined; keep them untouched rather than guess.
+  if (index < 16 || index > 255) return undefined;
+  if (index >= 232) { const gray = 8 + (index - 232) * 10; return [gray, gray, gray]; }
+  const cube = index - 16;
+  const channel = (value: number) => value === 0 ? 0 : 55 + value * 40;
+  return [channel(Math.floor(cube / 36)), channel(Math.floor(cube / 6) % 6), channel(cube % 6)];
+}
+
+function foreground(color: RGB, mode: "truecolor" | "256color"): string {
+  if (mode === "truecolor") return `\x1b[38;2;${color.join(";")}m`;
+  const channel = (value: number) => Math.max(0, Math.min(5, Math.round((value - 55) / 40)));
+  const index = 16 + channel(color[0]) * 36 + channel(color[1]) * 6 + channel(color[2]);
+  return `\x1b[38;5;${index}m`;
+}
+
+export function toolIdentity(icon: string, label: string, tone: "accent" | "muted" | "error", theme: Theme, time?: number): string {
+  if (tone !== "accent" || time === undefined) return theme.fg(tone, `${icon} ${label}`);
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  if (!supportsToolShimmer(theme)) return theme.fg(tone, `${icon} ${label}`);
+  const letters = Array.from(graphemes.segment(label), part => part.segment);
+  const radius = Math.max(2, Math.min(4, letters.length / 3));
+  const position = (time % PERIOD) / PERIOD * (letters.length + radius * 2) - radius;
+  const mode = theme.getColorMode();
+  const name = letters.map((letter, index) => {
+    const distance = Math.abs(index - position) / radius;
+    const shine = distance < 1 ? (1 + Math.cos(distance * Math.PI)) * 0.48 : 0;
+    if (!base || !light) {
+      const intensity = shine > 0.72 ? "\x1b[1m" : shine > 0.18 ? "" : "\x1b[2m";
+      return `\x1b[22m${intensity}${letter}`;
+    }
+    const color = base.map((value, channel) => Math.round(value + (light[channel] - value) * shine)) as RGB;
+    return `${foreground(color, mode)}${letter}`;
+  }).join("");
+  return theme.fg(tone, `${icon} \x1b[22m${name}\x1b[22m`);
+}

package/extensions/minimal-output/tool-visibility.ts

@@ -0,0 +1,61 @@
+interface Rect { x: number; y: number; width: number; height: number }
+interface LegacyComponent {
+  mouseLayout?: { children: { component: LegacyComponent; height: number }[] };
+  paddingX?: number;
+  paddingY?: number;
+}
+interface LayoutBox {
+  component: LegacyComponent;
+  rect: Rect;
+  clip: Rect;
+  children: LayoutBox[];
+  lineOffset?: number;
+}
+export interface ViewportUI { mode?: string; currentLayout?: { root: LayoutBox }; hasOverlay?(): boolean; hasActiveSelection?(): boolean }
+const frames = new WeakMap<ViewportUI, { root: LayoutBox; known: Set<object>; visible: Set<object> }>();
+
+function intersects(a: Rect, b: Rect): boolean {
+  return a.width > 0 && a.height > 0 && b.width > 0 && b.height > 0
+    && a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+// The guarded fullscreen adapter uses the last painted layout, never calls render()
+// to measure visibility, and leaves scrollback hosts on static state colors.
+export function toolVisibility(ui: ViewportUI, component: object): boolean | undefined {
+  if (ui.mode !== "fullscreen" || ui.hasOverlay?.() || ui.hasActiveSelection?.()) return false;
+  const root = ui.currentLayout?.root;
+  if (!root) return undefined;
+  if (!root.rect || !root.clip || !Array.isArray(root.children)) return false;
+  let frame = frames.get(ui);
+  if (frame?.root !== root) {
+    frame = { root, known: new Set(), visible: new Set() };
+    const current = frame;
+    const legacy = (child: LegacyComponent, rect: Rect, clip: Rect) => {
+      if (!child || typeof child !== "object") return;
+      current.known.add(child);
+      if (!intersects(rect, clip)) return;
+      current.visible.add(child);
+      const children = child.mouseLayout?.children;
+      if (!children) return;
+      const paddingY = child.paddingY ?? 0;
+      const paddingX = child.paddingX ?? 0;
+      if (children.reduce((height, entry) => height + entry.height, 0) + paddingY * 2 !== rect.height) return;
+      let y = rect.y + paddingY;
+      for (const entry of children) {
+        legacy(entry.component, { x: rect.x + paddingX, y, width: Math.max(0, rect.width - paddingX * 2), height: entry.height }, clip);
+        y += entry.height;
+      }
+    };
+    const visit = (box: LayoutBox) => {
+      if (!box?.component || !box.rect || !box.clip || !Array.isArray(box.children)) return;
+      current.known.add(box.component);
+      if (!intersects(box.rect, box.clip)) return;
+      current.visible.add(box.component);
+      if (box.children.length) for (const child of box.children) visit(child);
+      else legacy(box.component, { ...box.rect, y: box.rect.y - (box.lineOffset ?? 0) }, box.clip);
+    };
+    visit(root);
+    frames.set(ui, frame);
+  }
+  return frame.known.has(component) ? frame.visible.has(component) : undefined;
+}

package/node_modules/pi-better-plan/README.md

@@ -1,104 +1,66 @@
 # pi-better-plan
 
-`pi-better-plan` keeps a structured execution plan visible while Pi works.
+See what Pi is working on, what is done, and what comes next.
 
-![Pi Better Plan package preview](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-plan.png)
-
-## What It Does
-
-- Gives models one `update_plan` interface for checklist updates, workflow binding, and workflow transitions, plus `get_plan` for inspection.
-- Supports dependency edges (`id` and `dependsOn`) so independent ready steps can run concurrently.
-- Shows the complete checklist of completed, active, pending, and blocked steps above the editor.
-- Persists plan state and display preferences on the active Pi session branch.
-- Keeps a completed plan visible for 30 seconds, then clears it automatically.
-- Opens the complete plan with `/plan`.
+## Install
 
-Plan progress is checklist progress, not an estimate of effort. The extension never infers completion from prose or successful tool calls.
+```sh
+pi install npm:pi-better-plan
+```
 
-## Coordinating Delegated Work
+## Using the plan
 
-Use the plan as the foreground coordinator's milestone ledger. Delegate independent, sufficiently substantial work early with subagents, and use background tasks for long-running processes or repeated checks. Keep doing unblocked foreground work after launch; do not poll workers.
+Ask Pi to make a plan for your task. The checklist appears above the editor and updates as Pi works.
 
-Before the first implementation milestone, check for independent work and follow
-the active subagent delegation mode. Without `pi-better-subagents`, the plan uses
-adaptive guidance. Manual keeps planned work in the foreground unless the user or
-an active workflow explicitly requires delegation. Adaptive delegates substantial
-independent work when useful. Coordinator consults current catalog roles and
-delegates nontrivial role-owned work while retaining integration and final
-verification in the foreground.
+By default, you see up to five steps around the current work. The view starts at the beginning and moves toward the end as work progresses. Ellipses show how many steps are hidden; the progress count always covers the whole plan.
 
-Independent foreground and delegated milestones may both be `in_progress` only
-when both are actually underway. Use steps for distinct deliverables, not
-individual worker processes; worker tools and the background-work navigator own
-run status. Complete verification and the plan only after every relevant
-delegated task is terminal and its result or failure has been inspected and
-integrated.
+Click the plan to expand or collapse it in Pi's fullscreen mode. In regular terminal mode, use `/plan expand` or `/plan collapse`. For the full plan with details, run `/plan`.
 
-For a DAG, assign stable ids to prerequisite steps and list those ids in dependent steps' `dependsOn`. Dependencies must exist in the same plan; cycles and starting or completing a step before its prerequisites are complete are rejected. `get_plan` reports pending steps whose prerequisites are complete as ready. Plans without edges keep their existing behavior.
+Rows show `✓` for done, `●` for active, `○` for pending, and `!` for blocked. Pi marks steps complete explicitly; the count is not an estimate of effort.
 
-When an explicitly invoked skill declares `workflow-role: coordinator` in its metadata, that skill's task plan takes precedence. The generic checklist stays persisted but is hidden, and `update_plan` refuses generic checklist updates until workflow ownership is released. `/plan` never opens a stale generic checklist during workflow ownership.
+Your plan and display settings survive reload and follow the session branch. A completed checklist clears after 30 seconds. A released workflow plan stays visible for reference, but cannot be edited until the workflow resumes.
 
-For any workflow using the shared task-plan contract (including `resolve-issues` and `rush-issues`), bind its plan through `update_plan` with the absolute `.resolve-issues/rush/<run-id>/task-plan.json` path and its persisted `planRevision`:
+## Examples
 
-```json
-{ "workflow": {
-  "path": "/absolute/project/.resolve-issues/rush/run-1/task-plan.json",
-  "revision": 12
-} }
-```
+These images show the same eight-step plan, rendered by the actual widget with demonstration data.
 
-This binds the run to the session and shows its fleet stages and units in the widget, `/plan`, and `get_plan`. It does not rewrite the plan, increment its revision, or append a profiling event. The binding survives Pi session resume, and ownership release restores the prior generic checklist. Repeat this form to reload an externally saved checkpoint at its exact revision. `sync_workflow_plan` has been removed; migrate its old `{path, revision}` arguments into `update_plan`'s `workflow` object.
+### Just started
 
-After binding, record every transition with `update_plan` and a `workflow` object instead of editing `task-plan.json` or the profiling log by hand:
+The first five steps are visible.
 
-```json
-{ "workflow": {
-  "event": "unit-validated",
-  "revision": 12,
-  "changes": [
-    { "id": "1201", "set": { "stage": "done", "status": "in-flight", "worker": null, "headSha": "abc123" } },
-    { "id": "C1", "set": { "status": "combining" } }
-  ],
-  "profiling": { "outcome": "succeeded", "wallMs": 540000 }
-} }
-```
+![Plan at the start, showing steps 1 through 5](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/plan-examples/start.png)
 
-You may include `path` and `revision` alongside `event` and `changes` in the first call to bind and save a transition together. A rejected transition does not activate a new binding. Every successful binding or transition requests a TUI refresh; there is no separate synchronization tool to call afterward.
+### In the middle
 
-Each issue row shows where it is between code and delivery: `●` while it is being built, `◐ implemented` once `stage` is `done` with a `headSha`, `◑ review passed` while `reviewedHead` equals `headSha`, and `✓` only at `status: succeeded`, when the change has landed on the target branch by a merged PR or a direct push. Only `✓` rows count as complete.
+The active step has nearby context, with hidden steps counted on both sides.
 
-`changes` addresses units, components, and fleet stages by id (a change without an id sets run-level fields); all changes in one call are one transition. For a scope change, a change with `target` `unit` or `component` and an `add` row appends a new row; existing rows cannot be removed or renamed. The tool checks ids, dependencies (including cycles), worker slots, and status/stage values against the shared issue-resolution contract (a fleet status of `n/a` is saved as `not-applicable`), refuses a stale `revision`, appends an optional `decision`, then saves the plan atomically with `planRevision + 1` and a new `updatedAt`, and appends one profiling event with the same revision to the log the run already uses (`profiling/run.jsonl` or `profiling.jsonl`). A rejected update changes nothing. The event is appended before the plan is renamed into place, so a crash between the two can leave the log one revision ahead; the next update notices, reuses that revision, and marks its event with `logAheadRevision`.
+![Plan in the middle, showing steps 2 through 6 with step 4 active](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/plan-examples/middle.png)
 
-The binding records the active workflow's name, which is shown in the plan view. A different workflow cannot read or update that binding; a new invocation or ownership release invalidates it. The skill name is not an allowlist: explicit binding opts a workflow into the shared schema and transition rules, while path confinement to `.resolve-issues/rush/<run-id>/task-plan.json`, run identity, size limits, and revision checks still apply. Workflows using other schemas or storage locations retain their own planning and must not bind incompatible state.
+### Near the end
 
-## Plan Display
+The view shifts to the last five steps.
 
-Native and workflow-synced plans share a `plan` heading, completion counts, aligned identifiers and titles, and status colors. Completed rows use `✓`, active rows `●`, pending rows `○`, and blocked rows `!`. Active and blocked rows also carry text labels; failed workflow rows use `×` and `failed` rather than an active indicator.
+![Plan near completion, showing steps 4 through 8 with step 7 active](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/plan-examples/near-end.png)
 
-Workflow identity, revision, and fleet progress sit on a secondary line that wraps on narrow terminals. `/plan` uses the same styling and shows workflow stage, raw status, worker, dependencies, and notes beneath each issue. Use ↑/↓ to move the selection and Escape or ← to return. The passive widget never captures editor arrow keys.
+### Expanded
 
-## Install
+See every step. Click again or run `/plan collapse` to return to the compact view.
 
-```sh
-pi install npm:pi-better-plan
-```
+![Expanded plan showing all eight steps](https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/plan-examples/expanded.png)
 
 ## Commands
 
-```text
-/plan
-/plan clear
-/plan hide
-/plan show
-/plan pin auto
-/plan pin on
-/plan pin off
-```
+| Command | What it does |
+| --- | --- |
+| `/plan` | Open the full plan. Use Up/Down to select a step and Escape to return. |
+| `/plan expand` | Show all steps above the editor. |
+| `/plan collapse` | Return to the five-step view. |
+| `/plan hide` | Hide the plan without deleting it. |
+| `/plan show` | Show it again. |
+| `/plan clear` | Remove the displayed plan. |
 
-`pin auto` and `pin on` currently use the compact widget until Pi exposes a reserved right-rail extension interface. A floating overlay is intentionally not used as a substitute because it would cover transcript content.
+## For developers
 
-## Development
+Pi uses `update_plan` to create or update a plan and `get_plan` to inspect it. Plans can include dependencies and work running in parallel.
 
-```sh
-npm run verify
-```
+See the [technical reference](./REFERENCE.md) for workflow integration, delegation rules, display settings, tests, and screenshot generation.

package/node_modules/pi-better-plan/REFERENCE.md

@@ -0,0 +1,111 @@
+# Plan reference
+
+Technical details for workflow authors and contributors. For installation, screenshots, and everyday use, see the [README](./README.md).
+
+## Coordinating Delegated Work
+
+Use the plan as the foreground coordinator's milestone ledger. Delegate independent, sufficiently substantial work early with subagents, and use background tasks for long-running processes or repeated checks. Keep doing unblocked foreground work after launch; do not poll workers.
+
+Before the first implementation milestone, check for independent work and follow
+the active subagent delegation mode. Without `pi-better-subagents`, the plan uses
+adaptive guidance. Manual keeps planned work in the foreground unless the user or
+an active workflow explicitly requires delegation. Adaptive delegates substantial
+independent work when useful. Coordinator consults current catalog roles and
+delegates nontrivial role-owned work while retaining integration and final
+verification in the foreground.
+
+Independent foreground and delegated milestones may both be `in_progress` only
+when both are actually underway. Use steps for distinct deliverables, not
+individual worker processes; worker tools and the background-work navigator own
+run status. Complete verification and the plan only after every relevant
+delegated task is terminal and its result or failure has been inspected and
+integrated.
+
+For a DAG, assign stable ids to prerequisite steps and list those ids in dependent steps' `dependsOn`. Dependencies must exist in the same plan; cycles and starting or completing a step before its prerequisites are complete are rejected. `get_plan` reports pending steps whose prerequisites are complete as ready. Plans without edges keep their existing behavior.
+
+When an explicitly invoked skill declares `workflow-role: coordinator` in its metadata, that skill's task plan takes precedence. The generic checklist stays persisted but is hidden, and `update_plan` refuses generic checklist updates until workflow ownership is released. `/plan` never opens a stale generic checklist during workflow ownership.
+
+For any workflow using the shared task-plan contract (including `resolve-issues` and `rush-issues`), bind its plan through `update_plan` with the absolute `.resolve-issues/rush/<run-id>/task-plan.json` path and its persisted `planRevision`:
+
+```json
+{ "workflow": {
+  "path": "/absolute/project/.resolve-issues/rush/run-1/task-plan.json",
+  "revision": 12
+} }
+```
+
+This binds the run to the session and shows its fleet stages and units in the widget, `/plan`, and `get_plan`. It does not rewrite the plan, increment its revision, or append a profiling event. The binding survives Pi session resume. Ownership release keeps the last bound plan visible as a read-only handoff; a generic checklist update or `/plan clear` replaces or dismisses it. Repeat this form to reload an externally saved checkpoint at its exact revision. `sync_workflow_plan` has been removed; migrate its old `{path, revision}` arguments into `update_plan`'s `workflow` object.
+
+After binding, record every transition with `update_plan` and a `workflow` object instead of editing `task-plan.json` or the profiling log by hand:
+
+```json
+{ "workflow": {
+  "event": "unit-validated",
+  "revision": 12,
+  "changes": [
+    { "id": "1201", "set": { "stage": "done", "status": "in-flight", "worker": null, "headSha": "abc123" } },
+    { "id": "C1", "set": { "status": "combining" } }
+  ],
+  "profiling": { "outcome": "succeeded", "wallMs": 540000 }
+} }
+```
+
+You may include `path` and `revision` alongside `event` and `changes` in the first call to bind and save a transition together. A rejected transition does not activate a new binding. Every successful binding or transition requests a TUI refresh; there is no separate synchronization tool to call afterward.
+
+Each issue row shows where it is between code and delivery: `●` while it is being built, `◐ implemented` once `stage` is `done` with a `headSha`, `◑ review passed` while `reviewedHead` equals `headSha`, and `✓` only at `status: succeeded`, when the change has landed on the target branch by a merged PR or a direct push. Only `✓` rows count as complete.
+
+`changes` addresses units, components, and fleet stages by id (a change without an id sets run-level fields); all changes in one call are one transition. For a scope change, a change with `target` `unit` or `component` and an `add` row appends a new row; existing rows cannot be removed or renamed. The tool checks ids, dependencies (including cycles), worker slots, and status/stage values against the shared issue-resolution contract (a fleet status of `n/a` is saved as `not-applicable`), refuses a stale `revision`, appends an optional `decision`, then saves the plan atomically with `planRevision + 1` and a new `updatedAt`, and appends one profiling event with the same revision to the log the run already uses (`profiling/run.jsonl` or `profiling.jsonl`). A rejected update changes nothing. The event is appended before the plan is renamed into place, so a crash between the two can leave the log one revision ahead; the next update notices, reuses that revision, and marks its event with `logAheadRevision`.
+
+The binding records the active workflow's name, which is shown in the plan view. A different active workflow cannot read or update that binding; a new invocation invalidates it. After ownership release, the prior binding remains available for read-only inspection but cannot authorize writes. The skill name is not an allowlist: explicit binding opts a workflow into the shared schema and transition rules, while path confinement to `.resolve-issues/rush/<run-id>/task-plan.json`, run identity, size limits, and revision checks still apply. Workflows using other schemas or storage locations retain their own planning and must not bind incompatible state.
+
+## Plan Display
+
+Native and workflow-synced plans share a `plan` heading, completion counts, aligned identifiers and titles, and status colors. Completed rows use `✓`, active rows `●`, pending rows `○`, and blocked rows `!`. Active and blocked rows also carry text labels; failed workflow rows use `×` and `failed` rather than an active indicator.
+
+Workflow identity, revision, and fleet progress sit on a secondary line that wraps on narrow terminals. `/plan` uses the same styling and shows workflow stage, raw status, worker, dependencies, and notes beneath each issue. Use ↑/↓ to move the selection and Escape or ← to return. The passive widget never captures editor arrow keys.
+
+The folded widget shows at most five steps. Active steps take priority, with nearby steps filling the window; if more than five are active, the last five in plan order are shown. Early progress shows the head, late or completed progress shows the tail. Ellipses count omitted rows, while summary counts always cover the entire plan. Expanding reveals all steps without the detailed notes from `/plan`.
+
+In Pi's fullscreen TUI, a plain left click on the visible plan toggles expansion without taking editor focus. Regular terminal mode keeps mouse events for terminal selection and scrollback; use `/plan expand` or `/plan collapse` there. Expansion and display preferences survive reload and follow the active session branch.
+
+## Commands
+
+```text
+/plan
+/plan clear
+/plan hide
+/plan show
+/plan expand
+/plan collapse
+/plan pin auto
+/plan pin on
+/plan pin off
+```
+
+`pin auto` and `pin on` currently use the compact widget until Pi exposes a reserved right-rail extension interface. A floating overlay is intentionally not used as a substitute because it would cover transcript content.
+
+## Development
+
+```sh
+npm run verify
+```
+
+From the repository root, run the real terminal journey with tmux:
+
+```sh
+node --import tsx --import ./scripts/isolate-registry.mjs --test scripts/plan-navigation.tui.e2e.test.mjs
+```
+
+Regenerate only the example screenshots, then check the gallery assets:
+
+```sh
+npm run gallery:render -- --plan-examples
+npm run gallery:check
+```
+
+To also exercise fullscreen mouse dispatch on a mouse-capable Pi build:
+
+```sh
+PI_PLAN_TUI_CLI=/absolute/path/to/pi PI_PLAN_TUI_MOUSE=1 \
+  node --import tsx --import ./scripts/isolate-registry.mjs --test scripts/plan-navigation.tui.e2e.test.mjs
+```

package/node_modules/pi-better-plan/package.json

@@ -1,13 +1,14 @@
 {
   "name": "pi-better-plan",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Structured execution plans with persistent progress for Pi.",
   "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "REFERENCE.md"
   ],
   "keywords": [
     "pi-package",

package/node_modules/pi-better-plan/src/index.ts

@@ -13,6 +13,8 @@ import {
   replacePlan,
 } from "./plan-state.js";
 import { createFullPlanComponent, renderCompactPlan } from "./plan-render.js";
+import { createPlanWidget } from "./plan-widget.js";
+import { COMPACT_PLAN_ROWS } from "./plan-presentation.js";
 import {
   createRushPlanComponent, readRushPlan, renderRushPlan, workflowBinding,
   WORKFLOW_PLAN_ENTRY, type RushPlan, type WorkflowPlanBinding,
@@ -85,6 +87,8 @@ const PLAN_ACTIONS: readonly AutocompleteItem[] = [
   { value: "clear", label: "clear", description: "Remove the current plan" },
   { value: "hide", label: "hide", description: "Hide the plan widget" },
   { value: "show", label: "show", description: "Restore automatic plan display" },
+  { value: "expand", label: "expand", description: "Show all steps in the plan widget" },
+  { value: "collapse", label: "collapse", description: "Show up to five relevant steps" },
   { value: "pin auto", label: "pin auto", description: "Use automatic plan pinning" },
   { value: "pin on", label: "pin on", description: "Keep the plan pinned" },
   { value: "pin off", label: "pin off", description: "Keep the plan unpinned" },
@@ -119,6 +123,7 @@ function workflowPlanOwner(ctx: ExtensionContext): string | null {
 export default function planExtension(pi: ExtensionAPI): void {
   let currentPlan: PlanSnapshot | null = null;
   let displayMode: PlanDisplayMode = "auto";
+  let expanded = false;
   let displayedWorkflowOwner: string | null = null;
   let rushBinding: WorkflowPlanBinding | null = null;
   let rushPlan: RushPlan | null = null;
@@ -128,16 +133,26 @@ export default function planExtension(pi: ExtensionAPI): void {
   const unsubscribeWorkflow = pi.events.on("pi-better-workflow:changed", (owner) => {
     displayedWorkflowOwner = owner && typeof owner === "object" && "name" in owner && typeof owner.name === "string"
       ? owner.name : null;
-    rushBinding = null;
-    rushPlan = null;
-    rushError = null;
+    if (displayedWorkflowOwner) {
+      rushBinding = null;
+      rushPlan = null;
+      rushError = null;
+    }
     refreshWidget?.(true);
   });
 
   const refresh = (force = false): void => refreshWidget?.(force);
 
   const loadRushPlan = (ctx: ExtensionContext): RushPlan | null => {
-    if (!rushBinding || workflowPlanOwner(ctx) !== rushBinding.owner) return null;
+    const owner = workflowPlanOwner(ctx);
+    const binding = workflowBinding(ctx.sessionManager.getBranch());
+    displayedWorkflowOwner = owner;
+    rushBinding = binding && (!owner || binding.owner === owner) ? binding : null;
+    if (!rushBinding) {
+      rushPlan = null;
+      rushError = null;
+      return null;
+    }
     try {
       const plan = readRushPlan(rushBinding.path, ctx.cwd);
       if (plan.runId !== rushBinding.runId) throw new Error("Rush run identity changed.");
@@ -151,17 +166,24 @@ export default function planExtension(pi: ExtensionAPI): void {
     return rushPlan;
   };
 
-  const displayWorkflowPlan = (plan: RushPlan, binding: WorkflowPlanBinding): void => {
+  const displayWorkflowPlan = (plan: RushPlan, binding: WorkflowPlanBinding, readOnly = false): void => {
     if (!rushBinding || rushBinding.owner !== binding.owner || rushBinding.path !== binding.path || rushBinding.runId !== binding.runId) {
       pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "set", ...binding });
     }
-    displayedWorkflowOwner = binding.owner;
+    displayedWorkflowOwner = readOnly ? null : binding.owner;
     rushBinding = binding;
     rushPlan = plan;
     rushError = null;
     refresh(true);
   };
 
+  const clearWorkflowPlan = (): void => {
+    if (rushBinding) pi.appendEntry(WORKFLOW_PLAN_ENTRY, { version: 1, kind: "clear" });
+    rushBinding = null;
+    rushPlan = null;
+    rushError = null;
+  };
+
   const cancelCompletedPlanClear = (): void => {
     if (completedPlanClearTimer) clearTimeout(completedPlanClearTimer);
     completedPlanClearTimer = undefined;
@@ -196,17 +218,19 @@ export default function planExtension(pi: ExtensionAPI): void {
     currentPlan = state.plan;
     displayedWorkflowOwner = workflowPlanOwner(ctx);
     const binding = workflowBinding(ctx.sessionManager.getBranch());
-    rushBinding = binding?.owner === displayedWorkflowOwner ? binding : null;
+    rushBinding = binding && (!displayedWorkflowOwner || binding.owner === displayedWorkflowOwner) ? binding : null;
     rushPlan = null;
     rushError = null;
     if (rushBinding) loadRushPlan(ctx);
     displayMode = state.displayMode;
+    expanded = state.expanded;
     if (ctx.hasUI) ctx.ui.setStatus(LEGACY_PLAN_NAV_STATUS_KEY, undefined);
     refresh(true);
     scheduleCompletedPlanClear();
   };
 
   const persistPlan = (plan: PlanSnapshot): void => {
+    clearWorkflowPlan();
     currentPlan = plan;
     pi.appendEntry(EXTENSION_NAME, planSetEntry(plan));
     refresh(true);
@@ -219,6 +243,12 @@ export default function planExtension(pi: ExtensionAPI): void {
     refresh(true);
   };
 
+  const setExpanded = (value: boolean): void => {
+    expanded = value;
+    pi.appendEntry(EXTENSION_NAME, { version: 1, kind: "expansion", expanded, at: Math.floor(Date.now() / 1_000) });
+    refresh(true);
+  };
+
   const installWidget = (ctx: ExtensionContext): void => {
     if (!ctx.hasUI) return;
     ctx.ui.setWidget(
@@ -226,20 +256,26 @@ export default function planExtension(pi: ExtensionAPI): void {
       (tui, theme) => {
         const localRefresh = (force = false): void => tui.requestRender(force);
         refreshWidget = localRefresh;
-        return {
-          render(width: number): string[] {
+        const widget = createPlanWidget(
+          (width: number): string[] => {
             if (displayMode === "hidden" || displayedWorkflowOwner !== workflowPlanOwner(ctx)) return [];
-            if (displayedWorkflowOwner) {
-              if (rushBinding?.owner !== displayedWorkflowOwner) return [];
+            if (displayedWorkflowOwner || rushBinding) {
+              if (!rushBinding || (displayedWorkflowOwner && rushBinding.owner !== displayedWorkflowOwner) ||
+                  !workflowBinding(ctx.sessionManager.getBranch())) return [];
               const fg = typeof theme?.fg === "function"
                 ? (color: string, value: string) => theme.fg(color as never, value)
                 : undefined;
-              return rushPlan ? ["", ...renderRushPlan(rushPlan, width, false, fg, displayedWorkflowOwner)] : [];
+              return rushPlan ? renderRushPlan(rushPlan, width, false, fg, rushBinding.owner, !displayedWorkflowOwner, expanded) : [];
             }
             if (!currentPlan) return [];
-            return ["", ...renderCompactPlan(currentPlan, width, theme as never)];
+            return renderCompactPlan(currentPlan, width, theme as never, expanded);
           },
-          invalidate() {},
+          () => (rushBinding ? rushPlan?.issues.length ?? 0 : currentPlan?.steps.length ?? 0) > COMPACT_PLAN_ROWS,
+          () => expanded,
+          () => setExpanded(!expanded),
+        );
+        return {
+          ...widget,
           dispose() {
             if (refreshWidget === localRefresh) refreshWidget = undefined;
           },
@@ -251,21 +287,23 @@ export default function planExtension(pi: ExtensionAPI): void {
 
   const showFullPlan = async (ctx: ExtensionContext): Promise<void> => {
     const owner = workflowPlanOwner(ctx);
-    if (owner) {
+    const binding = workflowBinding(ctx.sessionManager.getBranch());
+    if (owner || binding) {
       const plan = loadRushPlan(ctx);
+      const planOwner = owner ?? binding!.owner;
       if (!plan) {
-        ctx.ui.notify(`${owner} plan unavailable: ${rushError ?? "not bound"}`, "warning");
+        ctx.ui.notify(`${planOwner}${owner ? " plan" : " read-only handoff"} unavailable: ${rushError ?? "not bound"}`, "warning");
         return;
       }
       if (ctx.mode !== "tui") {
-        ctx.ui.notify(renderRushPlan(plan, 160, true, undefined, owner).join("\n"), "info");
+        ctx.ui.notify(renderRushPlan(plan, 160, true, undefined, planOwner, !owner).join("\n"), "info");
         return;
       }
       await ctx.ui.custom<void>((tui, theme, _keys, done) => {
         const fg = typeof theme?.fg === "function"
           ? (color: string, value: string) => theme.fg(color as never, value)
           : undefined;
-        const component = createRushPlanComponent(plan, () => done(), fg, owner);
+        const component = createRushPlanComponent(plan, () => done(), fg, planOwner, !owner);
         return { render: (width) => component.render(width), handleInput(data) {
           component.handleInput?.(data);
           tui.requestRender();
@@ -315,16 +353,26 @@ export default function planExtension(pi: ExtensionAPI): void {
       const owner = workflowPlanOwner(ctx);
       const input = params as { explanation?: string; plan?: PlanStepInput[]; workflow?: WorkflowPlanInput };
       if (input.workflow !== undefined) {
-        if (!owner) throw new Error("No workflow owns the task plan; send plan instead of workflow.");
+        const savedBinding = workflowBinding(ctx.sessionManager.getBranch());
+        if (!owner && (input.workflow.event !== undefined || input.workflow.changes !== undefined ||
+            input.workflow.decision !== undefined || input.workflow.profiling !== undefined || !savedBinding)) {
+          throw new Error(savedBinding
+            ? `${savedBinding.owner} plan is a read-only handoff. Reinvoke /skill:${savedBinding.owner} before updating its workflow plan.`
+            : "No workflow owns the task plan; send plan instead of workflow.");
+        }
         if (input.plan !== undefined) throw new Error("Send either plan or workflow, not both.");
         const { path, ...transition } = input.workflow;
         if (transition.event === undefined && (transition.changes !== undefined || transition.decision !== undefined || transition.profiling !== undefined)) {
           throw new Error("workflow.event is required when sending changes, decision, or profiling.");
         }
-        let binding = rushBinding?.owner === owner ? rushBinding : null;
+        let binding = savedBinding && (!owner || savedBinding.owner === owner) ? savedBinding : null;
         if (path !== undefined) {
+          if (!owner && path !== binding?.path) {
+            throw new Error(`${binding!.owner} plan is a read-only handoff; only its bound path can be reloaded. Reinvoke /skill:${binding!.owner} to bind a workflow plan.`);
+          }
           if (transition.revision === undefined) throw new Error("workflow.revision is required with workflow.path.");
           const plan = readRushPlan(path, ctx.cwd);
+          if (!owner && plan.runId !== binding!.runId) throw new Error("Rush run identity changed.");
           if (plan.planRevision !== transition.revision) {
             if (transition.event === undefined) {
               rushPlan = null;
@@ -333,10 +381,10 @@ export default function planExtension(pi: ExtensionAPI): void {
             }
             throw new Error(`Rush plan revision mismatch: expected ${transition.revision}, found ${plan.planRevision}.`);
           }
-          binding = { owner, path, runId: plan.runId };
+          binding = { owner: owner ?? binding!.owner, path, runId: plan.runId };
           if (transition.event === undefined) {
-            displayWorkflowPlan(plan, binding);
-            return { content: [{ type: "text", text: `Showing ${owner} rev ${plan.planRevision}: ${plan.issues.length} units.` }], details: { ok: true, runId: plan.runId, revision: plan.planRevision } };
+            displayWorkflowPlan(plan, binding, !owner);
+            return { content: [{ type: "text", text: `Showing ${binding.owner} rev ${plan.planRevision}: ${plan.issues.length} units.${owner ? "" : " Read-only handoff."}` }], details: { ok: true, runId: plan.runId, revision: plan.planRevision, ...(!owner ? { readOnly: true } : {}) } };
           }
         }
         if (!binding) throw new Error(`No ${owner} plan is bound; send workflow.path and workflow.revision to update_plan first.`);
@@ -390,13 +438,16 @@ export default function planExtension(pi: ExtensionAPI): void {
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = workflowPlanOwner(ctx);
-      if (owner) {
+      const binding = workflowBinding(ctx.sessionManager.getBranch());
+      if (owner || binding) {
         const workflowPlan = loadRushPlan(ctx);
+        const planOwner = owner ?? binding!.owner;
         return {
           content: [{ type: "text", text: workflowPlan
-            ? renderRushPlan(workflowPlan, 160, true, undefined, owner).join("\n")
-            : `${owner} owns the task plan; ${rushError ?? "consult its persisted workflow state"}.` }],
-          details: { hasPlan: !!workflowPlan, plan: workflowPlan, progress: null, workflowOwner: owner },
+            ? renderRushPlan(workflowPlan, 160, true, undefined, planOwner, !owner).join("\n")
+            : owner ? `${owner} owns the task plan; ${rushError ?? "consult its persisted workflow state"}.`
+              : `${planOwner} read-only handoff unavailable: ${rushError ?? "not bound"}.` }],
+          details: { hasPlan: !!workflowPlan, plan: workflowPlan, progress: null, workflowOwner: planOwner, ...(!owner ? { readOnly: true } : {}) },
         };
       }
       if (!currentPlan) {
@@ -424,6 +475,7 @@ export default function planExtension(pi: ExtensionAPI): void {
           ctx.ui.notify("The workflow owns its plan; /plan clear cannot change it.", "warning");
           return;
         }
+        clearWorkflowPlan();
         clearPlan();
         ctx.ui.notify("Plan cleared.", "info");
         return;
@@ -436,13 +488,17 @@ export default function planExtension(pi: ExtensionAPI): void {
         setDisplayMode("auto");
         return;
       }
+      if (input === "expand" || input === "collapse") {
+        setExpanded(input === "expand");
+        return;
+      }
       const pinMode = input.match(/^pin\s+(auto|on|off)$/)?.[1] as PlanDisplayMode | undefined;
       if (pinMode) {
         setDisplayMode(pinMode);
         ctx.ui.notify(`Plan pin mode: ${pinMode}.`, "info");
         return;
       }
-      ctx.ui.notify("Usage: /plan [clear|hide|show|pin auto|pin on|pin off]", "warning");
+      ctx.ui.notify("Usage: /plan [clear|hide|show|expand|collapse|pin auto|pin on|pin off]", "warning");
     },
   });
 
@@ -454,7 +510,7 @@ export default function planExtension(pi: ExtensionAPI): void {
     restore(ctx);
   });
   pi.on("before_agent_start", async (event, ctx) => {
-    if (workflowPlanOwner(ctx)) return;
+    if (workflowPlanOwner(ctx) || workflowBinding(ctx.sessionManager.getBranch())) return;
     if (!currentPlan) return;
     return {
       systemPrompt: `${event.systemPrompt}\n\n${planPrompt(currentPlan, activeDelegationMode(pi))}`,

package/node_modules/pi-better-plan/src/plan-presentation.ts

@@ -22,6 +22,24 @@ export interface PlanPresentation {
 
 export const plainPlanTheme: PlanRenderTheme = { fg: (_color, value) => value };
 
+export const COMPACT_PLAN_ROWS = 5;
+
+function compactRowIndices(rows: PlanRow[]): number[] {
+  if (rows.length <= COMPACT_PLAN_ROWS) return rows.map((_, index) => index);
+  let active = rows.flatMap((row, index) =>
+    ["in_progress", "implemented", "reviewed"].includes(row.status) ? [index] : []);
+  if (!active.length) active = rows.flatMap((row, index) =>
+    row.status === "blocked" || row.status === "failed" ? [index] : []);
+  const firstPending = rows.findIndex((row) => row.status === "pending");
+  const anchor = active.at(-1) ?? (firstPending < 0 ? rows.length - 1 : firstPending);
+  const start = Math.max(0, Math.min(anchor - 2, rows.length - COMPACT_PLAN_ROWS));
+  const indices = new Set(active.slice(-COMPACT_PLAN_ROWS));
+  for (let index = start; index < start + COMPACT_PLAN_ROWS && indices.size < COMPACT_PLAN_ROWS; index++) {
+    indices.add(index);
+  }
+  return [...indices].sort((a, b) => a - b);
+}
+
 export function statusStyle(status: DisplayStatus): { glyph: string; color: string; label: string } {
   switch (status) {
     case "completed": return { glyph: "✓", color: "success", label: "" };
@@ -43,7 +61,7 @@ export function planText(value: string): string {
 
 export function renderPlanPresentation(
   plan: PlanPresentation, width: number, theme: PlanRenderTheme,
-  full = false, selectedIndex = -1,
+  full = false, selectedIndex = -1, expanded = false,
 ): string[] {
   const size = Math.max(1, Math.floor(width));
   const count = (status: DisplayStatus) => plan.rows.filter((row) => row.status === status).length;
@@ -65,7 +83,15 @@ export function renderPlanPresentation(
   const labelWidth = Math.min(12, Math.max(4, ...plan.rows.map((row) => visibleWidth(planText(row.label)))));
   const statusWidth = Math.min(24, Math.max(0, ...plan.rows.map((row) =>
     visibleWidth(planText(row.statusLabel ?? statusStyle(row.status).label)))));
-  for (const [index, row] of plan.rows.entries()) {
+  const indices = full || expanded ? plan.rows.map((_, index) => index) : compactRowIndices(plan.rows);
+  let previous = -1;
+  for (const index of indices) {
+    if (index > previous + 1) {
+      const omitted = index - previous - 1;
+      lines.push(theme.fg("dim", `  ... ${omitted} ${previous < 0 ? "earlier " : ""}${omitted === 1 ? "step" : "steps"}`));
+    }
+    previous = index;
+    const row = plan.rows[index]!;
     const style = statusStyle(row.status);
     const label = truncateToWidth(planText(row.label), labelWidth);
     const prefix = (index === selectedIndex ? theme.fg("accent", "› ") : "  ") +
@@ -94,6 +120,10 @@ export function renderPlanPresentation(
       }
     }
   }
+  if (previous < plan.rows.length - 1) {
+    const omitted = plan.rows.length - previous - 1;
+    lines.push(theme.fg("dim", `  ... ${omitted} more ${omitted === 1 ? "step" : "steps"}`));
+  }
   if (full) lines.push("", theme.fg("dim", "↑↓ navigate · esc / ← back"));
   return lines.map((line) => truncateToWidth(line, size));
 }

package/node_modules/pi-better-plan/src/plan-render.ts

@@ -15,8 +15,8 @@ function presentPlan(plan: PlanSnapshot): PlanPresentation {
   };
 }
 
-export function renderCompactPlan(plan: PlanSnapshot, width: number, theme: PlanRenderTheme): string[] {
-  return renderPlanPresentation(presentPlan(plan), width, theme);
+export function renderCompactPlan(plan: PlanSnapshot, width: number, theme: PlanRenderTheme, expanded = false): string[] {
+  return renderPlanPresentation(presentPlan(plan), width, theme, false, -1, expanded);
 }
 
 export function renderFullPlan(plan: PlanSnapshot, width: number, theme: PlanRenderTheme, selectedIndex = -1): string[] {

package/node_modules/pi-better-plan/src/plan-state.ts

@@ -16,6 +16,7 @@ interface SessionEntryLike {
 export interface ReconstructedPlanState {
   plan: PlanSnapshot | null;
   displayMode: PlanDisplayMode;
+  expanded: boolean;
 }
 
 function nowSeconds(): number {
@@ -176,13 +177,15 @@ export function planDisplayEntry(mode: PlanDisplayMode, at = nowSeconds()): Plan
 export function reconstructPlanState(entries: Iterable<SessionEntryLike>): ReconstructedPlanState {
   let plan: PlanSnapshot | null = null;
   let displayMode: PlanDisplayMode = "auto";
+  let expanded = false;
   for (const entry of entries) {
     if (entry.type !== "custom" || entry.customType !== EXTENSION_NAME || !isPlanEntry(entry.data)) continue;
     if (entry.data.kind === "set") plan = entry.data.plan;
     else if (entry.data.kind === "clear") plan = null;
-    else displayMode = entry.data.mode;
+    else if (entry.data.kind === "display") displayMode = entry.data.mode;
+    else expanded = entry.data.expanded;
   }
-  return { plan, displayMode };
+  return { plan, displayMode, expanded };
 }
 
 function isPlanEntry(value: unknown): value is PlanEntry {
@@ -190,6 +193,7 @@ function isPlanEntry(value: unknown): value is PlanEntry {
   const candidate = value as Partial<PlanEntry>;
   if (candidate.version !== 1) return false;
   if (candidate.kind === "clear") return true;
+  if (candidate.kind === "expansion") return typeof candidate.expanded === "boolean";
   if (candidate.kind === "display") {
     return candidate.mode === "auto" || candidate.mode === "on" || candidate.mode === "off" || candidate.mode === "hidden";
   }

package/node_modules/pi-better-plan/src/plan-widget.ts

@@ -0,0 +1,41 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+// Structural typing keeps keyboard-only Pi versions compatible with the fullscreen mouse API.
+interface PlanMouseEvent {
+  type: string;
+  button: string;
+  x: number;
+  y: number;
+  width: number;
+  shift?: boolean;
+  alt?: boolean;
+  ctrl?: boolean;
+}
+
+export function createPlanWidget(
+  render: (width: number) => string[],
+  isFoldable: () => boolean,
+  isExpanded: () => boolean,
+  toggle: () => void,
+): Component & { handleMouse(event: PlanMouseEvent): { handled: true; render: boolean } | undefined } {
+  let lines: string[] = [];
+  return {
+    render(width) {
+      lines = render(width);
+      if (lines.length && isFoldable()) {
+        lines = [truncateToWidth(`${isExpanded() ? "▾" : "▸"} ${lines[0]}`, width), ...lines.slice(1)];
+      }
+      return lines.length ? ["", ...lines] : [];
+    },
+    handleMouse(event) {
+      if (!isFoldable() || (event.type !== "click" && event.type !== "press") || event.button !== "left" || event.shift || event.alt || event.ctrl ||
+          event.x < 0 || event.x >= event.width || event.y < 1 || event.y > lines.length) return undefined;
+      // Pi synthesizes click only for a component that handled the initial press.
+      if (event.type === "press") return { handled: true, render: false };
+      toggle();
+      return { handled: true, render: true };
+    },
+    invalidate() { lines = []; },
+  };
+}

package/node_modules/pi-better-plan/src/types.ts

@@ -39,4 +39,5 @@ export interface PlanProgress {
 export type PlanEntry =
   | { version: 1; kind: "set"; plan: PlanSnapshot; at: number }
   | { version: 1; kind: "clear"; at: number }
-  | { version: 1; kind: "display"; mode: PlanDisplayMode; at: number };
+  | { version: 1; kind: "display"; mode: PlanDisplayMode; at: number }
+  | { version: 1; kind: "expansion"; expanded: boolean; at: number };

package/node_modules/pi-better-plan/src/workflow-plan.ts

@@ -113,7 +113,7 @@ export function workflowBinding(entries: Iterable<{ type: string; customType?: s
   for (const entry of entries) {
     if (entry.type === "custom" && entry.customType === "pi-better-workflow") {
       const data = entry.data;
-      if (isRecord(data) && data.version === 1 && (data.kind === "set" || data.kind === "clear")) binding = null;
+      if (isRecord(data) && data.version === 1 && data.kind === "set") binding = null;
     }
     if (entry.type !== "custom" || entry.customType !== WORKFLOW_PLAN_ENTRY) continue;
     const data = entry.data;
@@ -148,7 +148,7 @@ function unitStatus(unit: RushUnit): DisplayStatus {
   return unit.reviewedHead === unit.headSha ? "reviewed" : "implemented";
 }
 
-function presentRushPlan(plan: RushPlan, owner: string): PlanPresentation {
+function presentRushPlan(plan: RushPlan, owner: string, readOnly = false): PlanPresentation {
   // The warehouse canary only applies to data work; hide it otherwise.
   const stages = ["explore", "implement", "review", "ci", ...(plan.warehouseCanaryRequired ? ["canary"] : [])];
   const fleet = stages.map((stage) => {
@@ -158,6 +158,7 @@ function presentRushPlan(plan: RushPlan, owner: string): PlanPresentation {
     return { color: style.color, text: `  ${stage} ${style.glyph}${display === "unknown" ? ` ${planText(status)}` : ""}` };
   });
   const metadata = [[{ color: "dim", text: `${planText(owner)} · rev ${plan.planRevision}  ·` }, ...fleet]];
+  if (readOnly) metadata.push([{ color: "warning", text: "read-only handoff" }]);
   if (plan.spec?.title) metadata.push([{ color: "dim", text: plan.spec.title }]);
   return {
     metadata,
@@ -180,9 +181,11 @@ export function renderRushPlan(
   full = false,
   fg?: (color: string, value: string) => string,
   owner = "rush-issues",
+  readOnly = false,
+  expanded = false,
 ): string[] {
   const theme = fg ? { fg } : plainPlanTheme;
-  return renderPlanPresentation(presentRushPlan(plan, owner), width, theme, full);
+  return renderPlanPresentation(presentRushPlan(plan, owner, readOnly), width, theme, full, -1, expanded);
 }
 
 export function createRushPlanComponent(
@@ -190,7 +193,8 @@ export function createRushPlanComponent(
   onClose: () => void,
   fg?: (color: string, value: string) => string,
   owner = "rush-issues",
+  readOnly = false,
 ): Component {
   const theme = fg ? { fg } : plainPlanTheme;
-  return createPlanPresentationComponent(presentRushPlan(plan, owner), theme, onClose);
+  return createPlanPresentationComponent(presentRushPlan(plan, owner, readOnly), theme, onClose);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -55,7 +55,7 @@
   "dependencies": {
     "pi-better-background-tasks": "0.8.0",
     "pi-better-goal": "0.8.2",
-    "pi-better-plan": "0.7.0",
+    "pi-better-plan": "0.8.0",
     "pi-better-sandbox": "0.12.0",
     "pi-better-ssh": "0.1.2",
     "pi-better-subagents": "0.17.0",