pi-better-harness 0.27.0 → 0.27.2

package/README.md

@@ -79,6 +79,11 @@ images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls
 are included. Tools without a custom call renderer use a generic icon and a
 compact argument hint. Compaction summaries also collapse to one quiet row with
 the pre-compaction token count; Ctrl+O reveals their original summary.
+Custom transcript messages from any extension also fold to a quiet disclosure
+row with the message type and first content line. This includes background
+completion batches and subagent health/timing alerts. Ctrl+O or a fullscreen
+click reveals the original content and any custom renderer. Direct UI notices
+are unchanged.
 Execution, sandboxing, and agent-facing payloads are unchanged.
 When a foreground run ends, each consecutive block of tool calls folds further
 into one disclosure row showing the call count and any failures. Only the failure
@@ -105,7 +110,7 @@ Normal mode is the initial default. Changing tool output saves the choice in
 global `settings.json` under `piBetterHarness.toolOutput`, as well as the current
 session. New sessions inherit it; resumed branches retain their own saved choice.
 This is a version-sensitive internal TUI adapter,
-tested with Pi 0.82.1, 0.99.1, and the bundled Pi 1.0.0 CLI; incompatible APIs
+tested with Pi 0.82.1, 0.99.1, and the bundled Pi 1.0.4 CLI; incompatible APIs
 produce a warning and leave ordinary output enabled. Print/RPC output and
 exported transcripts are unchanged.
 

package/extensions/minimal-output/hook.ts

@@ -42,6 +42,18 @@ interface CompactionComponent extends Component {
 interface CompactionPrototype {
   render: CompactionComponent["render"];
 }
+interface CustomMessageComponent extends Component {
+  _expanded: boolean;
+  outputPad?: number;
+  message: { customType: string; content: string | { type: string; text?: string }[] };
+  setExpanded(expanded: boolean): void;
+}
+interface CustomMessagePrototype {
+  render: CustomMessageComponent["render"];
+  setExpanded: CustomMessageComponent["setExpanded"];
+  invalidate(): void;
+  handleMouse?(event: ToolMouseEvent): unknown;
+}
 
 type Method = (this: ToolComponent, ...args: unknown[]) => unknown;
 interface ToolMouseEvent { type: string; button: string; x: number; y: number; screenX: number; screenY: number; width: number; shift?: boolean; alt?: boolean; ctrl?: boolean }
@@ -229,6 +241,17 @@ export async function loadCompactionPrototype(): Promise<CompactionPrototype> {
   return module.CompactionSummaryMessageComponent.prototype;
 }
 
+export async function loadCustomMessagePrototype(): Promise<CustomMessagePrototype> {
+  const entry = sdkEntry(hostRequire());
+  const path = bundledHostEntry(entry) ?? join(dirname(entry), "modes/interactive/components/custom-message.js");
+  const module = await import(pathToFileURL(path).href);
+  const prototype = module.CustomMessageComponent?.prototype;
+  if (!prototype || ["render", "setExpanded", "invalidate"].some(name => typeof prototype[name] !== "function")) {
+    throw new Error("Pi's runtime does not expose its expandable custom-message display class.");
+  }
+  return prototype;
+}
+
 // Pi's ESM-only export cannot be resolved with require.resolve on older SDKs.
 function sdkEntry(require: ReturnType<typeof createRequire>): string {
   for (const directory of require.resolve.paths("@earendil-works/pi-coding-agent") ?? []) {
@@ -243,7 +266,7 @@ function sdkEntry(require: ReturnType<typeof createRequire>): string {
 }
 
 /** Internal TUI adapter: no tools are replaced and no result content is changed. */
-export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme, compactionPrototype?: CompactionPrototype): MinimalOutputHook {
+export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme, compactionPrototype?: CompactionPrototype, customMessagePrototype?: CustomMessagePrototype): MinimalOutputHook {
   for (const name of ["updateDisplay", "getResultRenderer", "getTextOutput", "setExpanded", "invalidate", "render"] as const) {
     if (typeof prototype[name] !== "function") {
       throw new Error(`Pi's tool display API is incompatible: missing ${name}. Normal output remains enabled.`);
@@ -409,6 +432,60 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         restore.call(this);
       };
     }
+    if (customMessagePrototype) {
+      const originalRender = customMessagePrototype.render;
+      const originalMouse = customMessagePrototype.handleMouse;
+      const renderDescriptor = Object.getOwnPropertyDescriptor(customMessagePrototype, "render");
+      const mouseDescriptor = Object.getOwnPropertyDescriptor(customMessagePrototype, "handleMouse");
+      const messages = new Set<WeakRef<CustomMessageComponent>>();
+      const seenMessages = new WeakSet<CustomMessageComponent>();
+      const render = function(this: CustomMessageComponent, width: number): string[] {
+        if (!seenMessages.has(this)) { seenMessages.add(this); messages.add(new WeakRef(this)); }
+        if (!current.enabled || this._expanded) return originalRender.call(this, width);
+        if (width <= 0) return [];
+        const label = stripVTControlCharacters(this.message.customType).replace(/[-_\s]+/g, " ").trim().replace(/^./, letter => letter.toUpperCase());
+        const content = typeof this.message.content === "string" ? this.message.content
+          : this.message.content.filter(block => block.type === "text").map(block => block.text ?? "").join("\n");
+        const detail = stripVTControlCharacters(content).split(/\r?\n/).map(line => line.replace(/\s+/g, " ").trim()).find(Boolean) ?? "";
+        const theme = getTheme?.();
+        const text = theme
+          ? ` ${theme.fg("muted", "\u25b8")} ${theme.fg("muted", label)}${detail ? `  ${theme.fg("dim", detail)}` : ""}`
+          : ` \u25b8 ${label}${detail ? `  ${detail}` : ""}`;
+        const padding = this.outputPad ?? 1;
+        const indent = Number.isFinite(padding) ? Math.max(0, Math.floor(padding)) + 2 : 3;
+        return [truncateToWidth(`${" ".repeat(Math.min(indent, width - 1))}${text}`, width)];
+      };
+      const mouse = function(this: CustomMessageComponent, event: ToolMouseEvent): unknown {
+        if (current.enabled && !this._expanded && event.type === "click" && event.button === "left"
+          && event.y === 0 && !event.shift && !event.alt && !event.ctrl) {
+          this.setExpanded(true);
+          return { handled: true, render: true };
+        }
+        return originalMouse?.call(this, event);
+      };
+      customMessagePrototype.render = render;
+      customMessagePrototype.handleMouse = mouse;
+      const redraw = current.redraw;
+      current.redraw = function(collapse) {
+        for (const reference of messages) {
+          const component = reference.deref();
+          if (!component) { messages.delete(reference); continue; }
+          if (collapse) component.setExpanded(false);
+          else component.invalidate();
+        }
+        redraw.call(this, collapse);
+      };
+      const restore = current.restore;
+      current.restore = function() {
+        for (const [name, wrapper, descriptor] of [["render", render, renderDescriptor], ["handleMouse", mouse, mouseDescriptor]] as const) {
+          if (customMessagePrototype[name] !== wrapper) continue;
+          if (descriptor) Object.defineProperty(customMessagePrototype, name, descriptor);
+          else Reflect.deleteProperty(customMessagePrototype, name);
+        }
+        messages.clear();
+        restore.call(this);
+      };
+    }
     const wrappers = {
       updateDisplay(this: ToolComponent, ...args: unknown[]) {
         if (typeof this.ui.handleViewportInput === "function" && !inputWrappers.has(this.ui)) {

package/extensions/minimal-output/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { installMinimalOutputHook, loadToolPrototype, loadCompactionPrototype, type MinimalOutputHook } from "./hook.ts";
+import { installMinimalOutputHook, loadToolPrototype, loadCompactionPrototype, loadCustomMessagePrototype, type MinimalOutputHook } from "./hook.ts";
 import type { SettingsControl } from "../settings/registry.ts";
 import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
 
@@ -37,7 +37,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     if (hook) return true;
     try {
-      hook = installMinimalOutputHook(await loadToolPrototype(), () => ctx.ui.theme, await loadCompactionPrototype());
+      hook = installMinimalOutputHook(await loadToolPrototype(), () => ctx.ui.theme, await loadCompactionPrototype(), await loadCustomMessagePrototype());
       return true;
     } catch (error) {
       ctx.ui.notify(`Minimal tool output is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");

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.0",
+  "version": "0.27.2",
   "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",