pi-message-sidebar 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.1.0
+
+> Pi 0.84.4: transcript overlap during TUI mode switches and narrow-pane width failures are resolved by mode-specific reserved layouts.
+
+- Changed development installation to a directory symlink with `index.ts`, so relative `src/` imports resolve through Pi's global extension auto-discovery.
+- Added a real auto-discovery load test for the installed extension shape.
+- Removed the persistent overlay implementation.
+- Added reserved-width rendering for regular TUI mode.
+- Added native `HStack` layout integration for fullscreen TUI mode.
+- Added responsive collapse below 123 terminal columns.
+- Added ANSI-safe truncation and width assertions for every sidebar row.
+- Preserved the session-path copy interaction from the existing working tree.
+- Split the extension into focused source modules, each below 400 lines.
+- Added unit tests and real pseudo-terminal smoke tests at wide and narrow sizes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Frapporti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# pi-message-sidebar
+
+Persistent message history sidebar for [Pi](https://pi.dev).
+
+## Features
+
+- Fixed 42-column panel on the right
+- Main transcript and editor render in their own reserved width
+- Native side-by-side layout in fullscreen TUI mode
+- Regular-mode compositor that reserves the same width in scrollback mode
+- Automatic collapse when the terminal cannot keep an 80-column main pane
+- First and last five user messages remain visible
+- Gap indicator shows hidden message counts
+- `Ctrl+Shift+H` focuses the sidebar
+- Arrow keys navigate messages
+- `Enter` expands or collapses a message
+- `c` copies the session path
+- `Escape` returns focus to Pi
+- Width assertions cover every rendered sidebar line
+
+## Requirements
+
+Pi 0.84.4 or newer. This extension uses the renderer-switching and fullscreen layout APIs shipped with the 0.84 series.
+
+## Installation
+
+### Development symlink
+
+```bash
+git clone git@github.com:Fornace/pi-message-sidebar.git ~/repos/pi-message-sidebar
+ln -s ~/repos/pi-message-sidebar ~/.pi/agent/extensions/message-sidebar
+```
+
+### Pi package
+
+```bash
+pi install npm:pi-message-sidebar
+# or from git
+pi install git:github.com/Fornace/pi-message-sidebar
+```
+
+## Usage
+
+The sidebar appears automatically in interactive mode when the terminal is at least 123 columns wide. It collapses below that breakpoint so Pi keeps a usable main pane.
+
+- Press `Ctrl+Shift+H` to focus or unfocus the sidebar.
+- Press `↑` or `↓` to navigate.
+- Press `PageUp`, `PageDown`, `Home`, or `End` for larger jumps.
+- Press `Enter` to expand or collapse the selected message.
+- Press `c` to copy the current session path.
+- Press `Escape` to return focus to Pi.
+
+## Architecture
+
+- `index.ts` is the auto-discovered extension entrypoint.
+- `src/layout.ts` reserves a real horizontal region in fullscreen mode and composes an equivalent region in regular mode.
+- `src/sidebar-component.ts` owns message navigation and bounded rendering.
+- `src/status-dock.ts` renders session, model, context, cost, and extension status data.
+- `src/style.ts` provides ANSI-safe row filling and width helpers.
+- `src/constants.ts` owns responsive layout thresholds.
+
+Every source file stays below 400 lines.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./message-sidebar.ts";
+export { collectUserMessages } from "./message-sidebar.ts";

package/message-sidebar.ts

@@ -0,0 +1,162 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ReadonlyFooterDataProvider,
+} from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { isViewportTUI, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { isSidebarVisible } from "./src/constants.ts";
+import { SidebarLayoutBridge } from "./src/layout.ts";
+import { SidebarComponent, type UserMessage } from "./src/sidebar-component.ts";
+
+function extractUserText(message: { content: unknown }): string {
+  if (typeof message.content === "string") return message.content;
+  if (!Array.isArray(message.content)) return "";
+  return message.content
+    .filter((content): content is { type: "text"; text: string } => {
+      return typeof content === "object" && content !== null && (content as any).type === "text";
+    })
+    .map((content) => content.text)
+    .join(" ");
+}
+
+export function collectUserMessages(ctx: ExtensionContext): UserMessage[] {
+  const messages: UserMessage[] = [];
+  let index = 0;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "message" || entry.message.role !== "user") continue;
+    index++;
+    const text = extractUserText(entry.message).trim();
+    if (text) messages.push({ id: entry.id, text, index, timestamp: entry.timestamp });
+  }
+  return messages;
+}
+
+class FooterDataBridge {
+  constructor(
+    private readonly tui: TUI,
+    private readonly ctx: ExtensionContext,
+    footerData: ReadonlyFooterDataProvider,
+    private readonly onChange: () => void,
+    private readonly onDispose: () => void,
+  ) {
+    this.unsubscribe = footerData.onBranchChange(onChange);
+  }
+
+  private readonly unsubscribe: () => void;
+
+  render(width: number): string[] {
+    if (isSidebarVisible(this.tui.terminal.columns)) return [];
+    const model = this.ctx.model?.id ?? "no model";
+    const cwd = this.ctx.sessionManager.getCwd();
+    return [truncateToWidth(`${model}  ${cwd}`, width, "…")];
+  }
+
+  invalidate(): void { this.onChange(); }
+  dispose(): void { this.unsubscribe(); this.onDispose(); }
+}
+
+export default function messageSidebar(pi: ExtensionAPI): void {
+  let sidebar: SidebarComponent | null = null;
+  let tui: TUI | null = null;
+  let cachedContext: ExtensionContext | null = null;
+  let footerData: ReadonlyFooterDataProvider | null = null;
+  let refreshQueued = false;
+
+  const scheduleRefresh = (ctx: ExtensionContext | null = cachedContext) => {
+    if (refreshQueued) return;
+    refreshQueued = true;
+    setImmediate(() => {
+      refreshQueued = false;
+      if (sidebar && ctx) sidebar.updateMessages(collectUserMessages(ctx));
+      else sidebar?.refresh();
+    });
+  };
+
+  const toggleFocus = (ctx: ExtensionContext) => {
+    const activeTui = tui;
+    if (!sidebar || !activeTui) {
+      ctx.ui.notify("Sidebar is still initializing", "warning");
+      return;
+    }
+    if (!isSidebarVisible(activeTui.terminal.columns)) {
+      ctx.ui.notify("Sidebar needs a terminal width of at least 123 columns", "warning");
+      return;
+    }
+    const focused = !sidebar.isFocused();
+    sidebar.setFocused(focused);
+    activeTui.requestRender();
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    cachedContext = ctx;
+    ctx.ui.setWidget(
+      "message-sidebar-layout",
+      (currentTui) => {
+        tui = currentTui;
+        sidebar = new SidebarComponent({
+          tui: currentTui,
+          ctx,
+          getFooterData: () => footerData,
+          getThinkingLevel: () => pi.getThinkingLevel(),
+          messages: collectUserMessages(ctx),
+        });
+        return new SidebarLayoutBridge(currentTui, sidebar);
+      },
+      { placement: "belowEditor" },
+    );
+
+    ctx.ui.setFooter((currentTui, _theme, data) => {
+      footerData = data;
+      scheduleRefresh(ctx);
+      return new FooterDataBridge(currentTui, ctx, data, () => scheduleRefresh(ctx), () => {
+        if (footerData === data) footerData = null;
+      });
+    });
+
+    ctx.ui.onTerminalInput((data) => {
+      if (tui && !isSidebarVisible(tui.terminal.columns) && sidebar?.isFocused()) {
+        sidebar.setFocused(false);
+        tui.requestRender();
+        return undefined;
+      }
+      if (tui && isViewportTUI(tui)) return undefined;
+      if (matchesKey(data, "escape") && sidebar?.isFocused()) {
+        sidebar.setFocused(false);
+        tui?.requestRender();
+        return { consume: true };
+      }
+      if (sidebar?.isFocused()) {
+        sidebar.handleInput(data);
+        return { consume: true };
+      }
+      return undefined;
+    });
+  });
+
+  pi.on("session_shutdown", () => {
+    sidebar = null;
+    tui = null;
+    cachedContext = null;
+    footerData = null;
+  });
+
+  pi.registerShortcut("ctrl+shift+h", {
+    description: "Focus or unfocus message sidebar",
+    handler: async (ctx) => toggleFocus(ctx),
+  });
+
+  pi.registerCommand("sidebar", {
+    description: "Focus or unfocus message sidebar (Ctrl+Shift+H)",
+    handler: async (_arguments, ctx) => toggleFocus(ctx),
+  });
+
+  pi.on("message_end", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("turn_end", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("agent_end", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("model_select", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("thinking_level_select", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("session_compact", (_event, ctx) => scheduleRefresh(ctx));
+  pi.on("session_tree", (_event, ctx) => scheduleRefresh(ctx));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-message-sidebar",
+  "version": "1.1.0",
+  "description": "Persistent responsive message history sidebar for Pi",
+  "keywords": ["pi-package", "pi-extension", "sidebar", "tui"],
+  "author": "Francesco Frapporti <effedue@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fornace/pi-message-sidebar.git"
+  },
+  "files": ["index.ts", "message-sidebar.ts", "src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "test:pty": "node test/pty-smoke.mjs regular 142 55 && node test/pty-smoke.mjs regular 121 55 && node test/pty-smoke.mjs fullscreen 142 55 && node test/pty-smoke.mjs fullscreen 121 55",
+    "typecheck": "tsc --noEmit",
+    "test:load": "node --import tsx test/load.test.mjs"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "^24.0.0",
+    "node-pty": "^1.1.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.4"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,10 @@
+export const SIDEBAR_WIDTH = 42;
+export const SIDEBAR_GAP = 1;
+export const RESERVED_WIDTH = SIDEBAR_WIDTH + SIDEBAR_GAP;
+export const MIN_MAIN_WIDTH = 80;
+export const PINNED_COUNT = 5;
+export const GAP_WINDOW = 3;
+
+export function isSidebarVisible(terminalWidth: number): boolean {
+  return terminalWidth >= MIN_MAIN_WIDTH + RESERVED_WIDTH;
+}

package/src/layout.ts

@@ -0,0 +1,196 @@
+import type { Component, TUI, ViewportTUI } from "@earendil-works/pi-tui";
+import {
+  HStack,
+  TuiAltScreen,
+  TuiMainScreen,
+  compositeTuiLine,
+  isViewportTUI,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import { MIN_MAIN_WIDTH, RESERVED_WIDTH, SIDEBAR_WIDTH, isSidebarVisible } from "./constants.ts";
+
+const REGULAR_PATCH_KEY = Symbol.for("pi-message-sidebar.regular-layout");
+const FULLSCREEN_PATCH_KEY = Symbol.for("pi-message-sidebar.fullscreen-layout");
+
+type RegularPatchState = {
+  originalRender: (this: TuiMainScreen, width: number) => string[];
+  refs: number;
+  sidebar: Component;
+};
+
+type FullscreenPatchState = {
+  originalSetLayoutRoot: (this: ViewportTUI, root: Component | undefined) => void;
+  refs: number;
+  sidebar: Component;
+  latestRoot?: Component;
+  roots: WeakMap<object, Component>;
+};
+
+function defocusHiddenSidebar(tui: TUI, sidebar: Component, width: number): boolean {
+  const visible = isSidebarVisible(width);
+  if (!visible && (sidebar as any).isFocused?.()) {
+    (sidebar as any).setFocused(false);
+    if ((tui as any).getFocusedComponent?.() === sidebar) tui.setFocus(null);
+  }
+  return visible;
+}
+
+function renderRegularLayout(
+  renderer: TuiMainScreen,
+  state: RegularPatchState,
+  width: number,
+): string[] {
+  if (!defocusHiddenSidebar(renderer, state.sidebar, width)) {
+    return state.originalRender.call(renderer, width);
+  }
+
+  const mainWidth = width - RESERVED_WIDTH;
+  const mainLines = state.originalRender.call(renderer, mainWidth);
+  const terminalRows = Math.max(1, renderer.terminal.rows);
+  const sidebarLines = state.sidebar.render(SIDEBAR_WIDTH).slice(0, terminalRows);
+  const viewportStart = Math.max(0, mainLines.length - terminalRows);
+  const rows = Math.max(mainLines.length, viewportStart + sidebarLines.length);
+  const result = [...mainLines];
+  while (result.length < rows) result.push("");
+
+  for (let row = 0; row < sidebarLines.length; row++) {
+    const index = viewportStart + row;
+    result[index] = compositeTuiLine(
+      result[index] ?? "",
+      sidebarLines[row]!,
+      mainWidth + RESERVED_WIDTH - SIDEBAR_WIDTH,
+      SIDEBAR_WIDTH,
+      width,
+    );
+  }
+  return result;
+}
+
+function installRegularLayout(sidebar: Component): () => void {
+  const prototype = TuiMainScreen.prototype as TuiMainScreen & {
+    [REGULAR_PATCH_KEY]?: RegularPatchState;
+  };
+  const existing = prototype[REGULAR_PATCH_KEY];
+  if (existing) {
+    existing.refs++;
+    existing.sidebar = sidebar;
+    return () => uninstallRegularLayout(prototype, existing);
+  }
+
+  const originalRender = prototype.render;
+  const state: RegularPatchState = { originalRender, refs: 1, sidebar };
+  prototype[REGULAR_PATCH_KEY] = state;
+  prototype.render = function renderWithSidebar(width: number): string[] {
+    return renderRegularLayout(this, state, width);
+  };
+  return () => uninstallRegularLayout(prototype, state);
+}
+
+function uninstallRegularLayout(
+  prototype: TuiMainScreen & { [REGULAR_PATCH_KEY]?: RegularPatchState },
+  state: RegularPatchState,
+): void {
+  state.refs--;
+  if (state.refs > 0) return;
+  delete (prototype as any).render;
+  delete prototype[REGULAR_PATCH_KEY];
+}
+
+function wrapFullscreenRoot(root: Component, sidebar: Component, tui: TUI): Component {
+  return new HStack([
+    { component: root, basis: 0, grow: 1, shrink: 1, minSize: MIN_MAIN_WIDTH },
+    {
+      component: sidebar,
+      basis: SIDEBAR_WIDTH,
+      grow: 0,
+      shrink: 0,
+      minSize: SIDEBAR_WIDTH,
+      maxSize: SIDEBAR_WIDTH,
+      visible: ({ width }) => defocusHiddenSidebar(tui, sidebar, width),
+    },
+  ], { gap: RESERVED_WIDTH - SIDEBAR_WIDTH });
+}
+
+function installFullscreenLayout(tui: TUI, sidebar: Component): () => void {
+  const prototype = TuiAltScreen.prototype as TuiAltScreen & {
+    [FULLSCREEN_PATCH_KEY]?: FullscreenPatchState;
+  };
+  const existing = prototype[FULLSCREEN_PATCH_KEY];
+  if (existing) {
+    existing.refs++;
+    existing.sidebar = sidebar;
+    reapplyCurrentFullscreenRoot(tui, existing);
+    return () => uninstallFullscreenLayout(tui, prototype, existing);
+  }
+
+  const originalSetLayoutRoot = Object.getOwnPropertyDescriptor(TuiAltScreen.prototype, "setLayoutRoot")?.value as
+    | FullscreenPatchState["originalSetLayoutRoot"]
+    | undefined;
+  if (!originalSetLayoutRoot) throw new Error("Pi fullscreen layout API is unavailable");
+  const state: FullscreenPatchState = {
+    originalSetLayoutRoot,
+    refs: 1,
+    sidebar,
+    roots: new WeakMap(),
+  };
+  prototype[FULLSCREEN_PATCH_KEY] = state;
+  prototype.setLayoutRoot = function setLayoutRootWithSidebar(root: Component | undefined): void {
+    if (!root) {
+      state.originalSetLayoutRoot.call(this, undefined);
+      return;
+    }
+    state.latestRoot = root;
+    state.roots.set(this, root);
+    state.originalSetLayoutRoot.call(this, wrapFullscreenRoot(root, state.sidebar, this));
+  };
+  reapplyCurrentFullscreenRoot(tui, state);
+  return () => uninstallFullscreenLayout(tui, prototype, state);
+}
+
+function reapplyCurrentFullscreenRoot(tui: TUI, state: FullscreenPatchState): void {
+  if (!isViewportTUI(tui)) return;
+  const root = state.roots.get(tui as object) ?? ((tui as any).layoutRoot as Component | undefined);
+  if (root) (tui as TuiAltScreen).setLayoutRoot(root);
+}
+
+function uninstallFullscreenLayout(
+  tui: TUI,
+  prototype: TuiAltScreen & { [FULLSCREEN_PATCH_KEY]?: FullscreenPatchState },
+  state: FullscreenPatchState,
+): void {
+  state.refs--;
+  if (state.refs > 0) return;
+  if (isViewportTUI(tui) && state.latestRoot) {
+    state.originalSetLayoutRoot.call(tui, state.latestRoot);
+  }
+  prototype.setLayoutRoot = state.originalSetLayoutRoot;
+  delete prototype[FULLSCREEN_PATCH_KEY];
+}
+
+export class SidebarLayoutBridge implements Component {
+  private readonly uninstallRegular: () => void;
+  private readonly uninstallFullscreen: () => void;
+
+  constructor(private readonly tui: TUI, sidebar: Component) {
+    this.uninstallRegular = installRegularLayout(sidebar);
+    this.uninstallFullscreen = installFullscreenLayout(tui, sidebar);
+    tui.requestRender(true);
+  }
+
+  render(): string[] { return []; }
+  invalidate(): void {}
+  dispose(): void {
+    this.uninstallFullscreen();
+    this.uninstallRegular();
+    this.tui.requestRender(true);
+  }
+}
+
+export function assertLinesFit(lines: readonly string[], width: number, label: string): void {
+  for (const [index, line] of lines.entries()) {
+    const measured = visibleWidth(line);
+    if (measured > width) {
+      throw new Error(`${label} line ${index} exceeds width (${measured} > ${width})`);
+    }
+  }
+}

package/src/sidebar-component.ts

@@ -0,0 +1,221 @@
+import {
+  copyToClipboard,
+  type ExtensionContext,
+  type ReadonlyFooterDataProvider,
+} from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { GAP_WINDOW, PINNED_COUNT, SIDEBAR_WIDTH } from "./constants.ts";
+import { assertLinesFit } from "./layout.ts";
+import { renderStatusDock } from "./status-dock.ts";
+import {
+  BG,
+  BG_HDR,
+  BG_SEL,
+  BOLD,
+  DIM,
+  FG_ACC,
+  FG_BRIGHT,
+  FG_DIM,
+  FG_EXP,
+  FG_FAINT,
+  FG_MID,
+  FG_NORM,
+  FG_TIME,
+  RST,
+  fillRow,
+  formatTime,
+  wrapText,
+} from "./style.ts";
+
+export type UserMessage = { id: string; text: string; index: number; timestamp: string };
+
+type SidebarOptions = {
+  tui: TUI;
+  ctx: ExtensionContext;
+  getFooterData: () => ReadonlyFooterDataProvider | null;
+  getThinkingLevel: () => string;
+  messages: UserMessage[];
+};
+
+export class SidebarComponent {
+  private focused = false;
+  private selected = 0;
+  private expanded = new Set<number>();
+  private messages: UserMessage[];
+  private version = 0;
+  private restoreFocus: Component | null = null;
+  private cachedSignature = "";
+  private cachedLines: string[] = [];
+
+  constructor(private readonly options: SidebarOptions) {
+    this.messages = options.messages;
+    this.selected = Math.max(0, this.messages.length - 1);
+  }
+
+  isFocused(): boolean { return this.focused; }
+
+  setFocused(focused: boolean): void {
+    if (this.focused === focused) return;
+    if (focused) {
+      this.restoreFocus = (this.options.tui as any).getFocusedComponent?.() ?? null;
+      this.focused = true;
+      this.options.tui.setFocus(this);
+    } else {
+      this.focused = false;
+      if ((this.options.tui as any).getFocusedComponent?.() === this) {
+        this.options.tui.setFocus(this.restoreFocus);
+      }
+      this.restoreFocus = null;
+    }
+    this.refresh();
+  }
+
+  updateMessages(messages: UserMessage[]): void {
+    this.messages = messages;
+    this.selected = Math.min(this.selected, Math.max(0, messages.length - 1));
+    this.refresh();
+  }
+
+  refresh(): void {
+    this.version++;
+    this.options.tui.requestRender();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) return this.setFocused(false);
+    if (matchesKey(data, "c")) { void this.copySessionPath(); return; }
+    if (matchesKey(data, "up")) this.selected = Math.max(0, this.selected - 1);
+    else if (matchesKey(data, "down")) this.selected = Math.min(this.messages.length - 1, this.selected + 1);
+    else if (matchesKey(data, "pageUp")) this.selected = Math.max(0, this.selected - 10);
+    else if (matchesKey(data, "pageDown")) this.selected = Math.min(this.messages.length - 1, this.selected + 10);
+    else if (matchesKey(data, "home")) this.selected = 0;
+    else if (matchesKey(data, "end")) this.selected = Math.max(0, this.messages.length - 1);
+    else if (matchesKey(data, "return") || matchesKey(data, "enter") || data === " ") {
+      if (this.expanded.has(this.selected)) this.expanded.delete(this.selected);
+      else this.expanded.add(this.selected);
+    } else return;
+    this.refresh();
+  }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, Math.min(SIDEBAR_WIDTH, width));
+    const targetHeight = Math.max(15, this.options.tui.terminal.rows);
+    const signature = this.signature(safeWidth, targetHeight);
+    if (signature === this.cachedSignature) return this.cachedLines;
+
+    const lines = this.renderHeader(safeWidth);
+    if (this.messages.length === 0) {
+      lines.push(fillRow(" No messages yet", safeWidth, BG));
+    } else {
+      lines.push(...this.renderMessages(safeWidth));
+    }
+
+    const dock = renderStatusDock(
+      safeWidth,
+      this.options.ctx,
+      this.options.getFooterData(),
+      this.options.getThinkingLevel(),
+      this.focused,
+    );
+    while (lines.length < targetHeight - dock.length) lines.push(fillRow(" ", safeWidth, BG));
+    const bodyLimit = Math.max(0, targetHeight - dock.length);
+    const result = [...lines.slice(0, bodyLimit), ...dock].slice(0, targetHeight);
+    assertLinesFit(result, safeWidth, "sidebar");
+    this.cachedSignature = signature;
+    this.cachedLines = result;
+    return result;
+  }
+
+  invalidate(): void {
+    this.cachedSignature = "";
+    this.cachedLines = [];
+  }
+
+  private renderHeader(width: number): string[] {
+    const icon = this.focused ? `${FG_ACC}●${RST}` : `${FG_DIM}○${RST}`;
+    const mode = this.focused ? `${FG_ACC}●${RST} ${FG_MID}focused${RST}` : `${FG_DIM}passive${RST}`;
+    const separator = `${FG_DIM}${"─".repeat(Math.max(0, width - 4))}${RST}`;
+    return [
+      fillRow(" ", width, BG_HDR),
+      fillRow(` ${icon} ${BOLD}${FG_BRIGHT}Messages${RST}${FG_DIM} ${this.messages.length}${RST}  ${mode}`, width, BG_HDR),
+      fillRow(" ", width, BG_HDR),
+      fillRow(` ${separator}`, width, BG),
+    ];
+  }
+
+  private renderMessages(width: number): string[] {
+    const result: string[] = [];
+    let previous = -1;
+    for (const index of this.visibleIndices()) {
+      if (index > previous + 1 && previous >= 0) {
+        result.push(fillRow(`     ${FG_DIM}··· ${index - previous - 1} more ···${RST}`, width, BG));
+      }
+      result.push(...this.renderMessage(index, width));
+      previous = index;
+    }
+    return result;
+  }
+
+  private renderMessage(index: number, width: number): string[] {
+    const message = this.messages[index]!;
+    const selected = index === this.selected;
+    const background = selected ? BG_SEL : BG;
+    const arrow = selected && this.focused ? `${FG_ACC}▸${RST}` : " ";
+    const number = `${FG_FAINT}${String(message.index).padStart(2)}${RST}`;
+    const time = `${FG_TIME}${formatTime(message.timestamp)}${RST}`;
+    if (!this.expanded.has(index)) {
+      const prefix = ` ${arrow}${number} ${time} `;
+      const text = truncateToWidth(message.text.replace(/\s+/g, " "), Math.max(0, width - visibleWidth(prefix)), "…");
+      return [fillRow(`${prefix}${selected ? FG_BRIGHT : FG_NORM}${text}${RST}`, width, background)];
+    }
+
+    const lines = [fillRow(` ${arrow}${number} ${time}`, width, background)];
+    const wrapped = wrapText(message.text, Math.max(1, width - 4));
+    for (const line of wrapped.slice(0, 8)) lines.push(fillRow(`   ${FG_EXP}${line}${RST}`, width, background));
+    if (wrapped.length > 8) {
+      lines.push(fillRow(`   ${FG_DIM}${DIM}…+${wrapped.length - 8} lines${RST}`, width, background));
+    }
+    lines.push(fillRow(" ", width, background));
+    return lines;
+  }
+
+  private visibleIndices(): number[] {
+    const total = this.messages.length;
+    if (total <= PINNED_COUNT * 2 + 1) return Array.from({ length: total }, (_, index) => index);
+    const indices = new Set<number>();
+    for (let i = 0; i < PINNED_COUNT; i++) indices.add(i);
+    for (let i = total - PINNED_COUNT; i < total; i++) indices.add(i);
+    if (this.selected >= PINNED_COUNT && this.selected < total - PINNED_COUNT) {
+      const start = Math.max(PINNED_COUNT, Math.min(this.selected - 1, total - PINNED_COUNT - GAP_WINDOW));
+      for (let i = start; i < start + GAP_WINDOW; i++) indices.add(i);
+    }
+    return [...indices].sort((a, b) => a - b);
+  }
+
+  private signature(width: number, height: number): string {
+    const usage = this.options.ctx.getContextUsage?.();
+    const statuses = this.options.getFooterData()?.getExtensionStatuses();
+    return JSON.stringify({
+      width,
+      height,
+      version: this.version,
+      messages: this.messages.length,
+      model: this.options.ctx.model?.id,
+      thinking: this.options.getThinkingLevel(),
+      usage,
+      statuses: statuses ? [...statuses.entries()] : [],
+    });
+  }
+
+  private async copySessionPath(): Promise<void> {
+    const target = this.options.ctx.sessionManager.getSessionFile() ?? this.options.ctx.sessionManager.getSessionId();
+    try {
+      await copyToClipboard(target);
+      this.options.ctx.ui.notify(`Copied ${basename(target)}`, "info");
+    } catch {
+      this.options.ctx.ui.notify(`Session path: ${target}`, "warning");
+    }
+  }
+}

package/src/status-dock.ts

@@ -0,0 +1,154 @@
+import type {
+  ExtensionContext,
+  ReadonlyFooterDataProvider,
+} from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  BG,
+  BG_CARD,
+  BG_HDR,
+  FG_BRIGHT,
+  FG_DIM,
+  FG_FAINT,
+  FG_INFO,
+  FG_MID,
+  RST,
+  contextColor,
+  fillRow,
+  formatCwd,
+  formatTokens,
+  progressBar,
+  sanitizeStatusText,
+} from "./style.ts";
+
+type Usage = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  latestCacheHitRate?: number;
+  contextPercent: number | null;
+  contextWindow: number;
+};
+
+function computeUsage(ctx: ExtensionContext): Usage {
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  let cost = 0;
+  let latestCacheHitRate: number | undefined;
+
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+    const usage = (entry.message as any).usage ?? {};
+    input += usage.input ?? 0;
+    output += usage.output ?? 0;
+    cacheRead += usage.cacheRead ?? 0;
+    cacheWrite += usage.cacheWrite ?? 0;
+    cost += usage.cost?.total ?? 0;
+    const prompt = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+    latestCacheHitRate = prompt > 0 ? ((usage.cacheRead ?? 0) / prompt) * 100 : undefined;
+  }
+
+  const context = ctx.getContextUsage?.();
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    cost,
+    latestCacheHitRate,
+    contextPercent: context?.percent ?? null,
+    contextWindow: context?.contextWindow ?? ctx.model?.contextWindow ?? 0,
+  };
+}
+
+function dockHeader(width: number, title: string): string {
+  const pad = " ";
+  const ruleWidth = Math.max(0, width - visibleWidth(pad) - visibleWidth(title) - 1);
+  return fillRow(`${pad}${FG_FAINT}${title}${RST} ${FG_FAINT}${"─".repeat(ruleWidth)}${RST}`, width, BG);
+}
+
+function dockRow(width: number, label: string, value: string): string {
+  const pad = " ";
+  const labelWidth = 5;
+  const maxValueWidth = Math.max(0, width - visibleWidth(pad) - labelWidth - 1);
+  const clipped = truncateToWidth(value, maxValueWidth, "…");
+  return fillRow(`${pad}${FG_FAINT}${label.padEnd(labelWidth)}${RST} ${clipped}`, width, BG_CARD);
+}
+
+export function renderStatusDock(
+  width: number,
+  ctx: ExtensionContext,
+  footerData: ReadonlyFooterDataProvider | null,
+  thinkingLevel: string,
+  focused: boolean,
+): string[] {
+  const usage = computeUsage(ctx);
+  const rows = [fillRow(" ", width, BG), dockHeader(width, "runtime")];
+  const branch = footerData?.getGitBranch();
+  const sessionName = ctx.sessionManager.getSessionName();
+  const workspace = [
+    `${FG_BRIGHT}${formatCwd(ctx.sessionManager.getCwd())}${RST}`,
+    branch ? `${FG_INFO}${branch}${RST}` : undefined,
+    sessionName ? `${FG_MID}${sessionName}${RST}` : undefined,
+  ].filter(Boolean).join(` ${FG_FAINT}•${RST} `);
+  rows.push(dockRow(width, "cwd", workspace));
+
+  const sessionId = ctx.sessionManager.getSessionId();
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  const shortId = sessionId.replace(/-/g, "").slice(-8);
+  rows.push(dockRow(width, "sess", [
+    `${FG_INFO}#${shortId}${RST}`,
+    sessionFile ? `${FG_FAINT}${basename(sessionFile)}${RST}` : undefined,
+  ].filter(Boolean).join(` ${FG_FAINT}•${RST} `)));
+
+  const model = ctx.model;
+  if (model) {
+    const provider = footerData && footerData.getAvailableProviderCount() > 1
+      ? `${FG_FAINT}${model.provider}${RST} `
+      : "";
+    const thinking = model.reasoning ? ` ${FG_FAINT}•${RST} ${FG_MID}${thinkingLevel}${RST}` : "";
+    rows.push(dockRow(width, "model", `${provider}${FG_BRIGHT}${model.id}${RST}${thinking}`));
+  }
+
+  const contextDisplay = usage.contextPercent === null
+    ? `?/${formatTokens(usage.contextWindow)}`
+    : `${usage.contextPercent.toFixed(1)}%/${formatTokens(usage.contextWindow)}`;
+  const usingSubscription = model ? Boolean((ctx.modelRegistry as any).isUsingOAuth?.(model)) : false;
+  const tokenParts = [
+    usage.input ? `↑${formatTokens(usage.input)}` : undefined,
+    usage.output ? `↓${formatTokens(usage.output)}` : undefined,
+    usage.cacheRead ? `R${formatTokens(usage.cacheRead)}` : undefined,
+    usage.cacheWrite ? `W${formatTokens(usage.cacheWrite)}` : undefined,
+    usage.latestCacheHitRate !== undefined && (usage.cacheRead || usage.cacheWrite)
+      ? `CH${usage.latestCacheHitRate.toFixed(1)}%`
+      : undefined,
+  ].filter(Boolean).join(" ");
+  rows.push(dockRow(
+    width,
+    "ctx",
+    `${contextColor(usage.contextPercent)}${contextDisplay}${RST} ${progressBar(usage.contextPercent)}`,
+  ));
+  rows.push(dockRow(
+    width,
+    "use",
+    `${FG_BRIGHT}$${usage.cost.toFixed(3)}${usingSubscription ? " sub" : ""}${RST}` +
+      (tokenParts ? ` ${FG_FAINT}•${RST} ${FG_MID}${tokenParts}${RST}` : ` ${FG_FAINT}• no token usage${RST}`),
+  ));
+
+  const statuses = footerData ? [...footerData.getExtensionStatuses().entries()].sort(([a], [b]) => a.localeCompare(b)) : [];
+  for (const [, text] of statuses.slice(0, 2)) {
+    rows.push(dockRow(width, "stat", `${FG_INFO}•${RST} ${FG_MID}${sanitizeStatusText(text)}${RST}`));
+  }
+
+  rows.push(fillRow(" ", width, BG));
+  const hint = focused
+    ? `${FG_DIM}↑↓${RST} ${FG_MID}nav${RST} ${FG_FAINT}·${RST} ${FG_DIM}Enter${RST} ${FG_MID}expand${RST} ${FG_FAINT}·${RST} ${FG_DIM}c${RST} ${FG_MID}copy${RST} ${FG_FAINT}·${RST} ${FG_DIM}Esc${RST} ${FG_MID}done${RST}`
+    : `${FG_DIM}Ctrl+Shift+H${RST} ${FG_MID}focus${RST}`;
+  rows.push(fillRow(` ${hint}`, width, BG_HDR));
+  return rows;
+}

package/src/style.ts

@@ -0,0 +1,77 @@
+import { basename } from "node:path";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+export const BG = "\x1b[48;5;232m";
+export const BG_SEL = "\x1b[48;5;235m";
+export const BG_HDR = "\x1b[48;5;233m";
+export const BG_CARD = "\x1b[48;5;234m";
+export const FG_FAINT = "\x1b[38;5;240m";
+export const FG_DIM = "\x1b[38;5;243m";
+export const FG_MID = "\x1b[38;5;248m";
+export const FG_NORM = "\x1b[38;5;250m";
+export const FG_BRIGHT = "\x1b[38;5;255m";
+export const FG_ACC = "\x1b[38;5;75m";
+export const FG_INFO = "\x1b[38;5;80m";
+export const FG_OK = "\x1b[38;5;114m";
+export const FG_WARN = "\x1b[38;5;215m";
+export const FG_ERR = "\x1b[38;5;203m";
+export const FG_TIME = "\x1b[38;5;242m";
+export const FG_EXP = "\x1b[38;5;252m";
+export const BOLD = "\x1b[1m";
+export const DIM = "\x1b[2m";
+export const RST = "\x1b[0m";
+
+export function fillRow(content: string, width: number, bg: string): string {
+  const safeWidth = Math.max(0, Math.floor(width));
+  if (safeWidth === 0) return "";
+  const injected = content.replace(/\x1b\[0m/g, `${RST}${bg}`);
+  return `${bg}${truncateToWidth(injected, safeWidth, "", true)}${RST}`;
+}
+
+export function wrapText(text: string, width: number): string[] {
+  return wrapTextWithAnsi(text.replace(/\s+/g, " ").trim(), Math.max(1, width));
+}
+
+export function formatTime(timestamp: string): string {
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.valueOf())) return "";
+  return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+
+export function sanitizeStatusText(text: string): string {
+  return text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
+}
+
+export function formatTokens(count: number): string {
+  if (!count) return "0";
+  if (count < 1_000) return String(count);
+  if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`;
+  if (count < 1_000_000) return `${Math.round(count / 1_000)}k`;
+  if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  return `${Math.round(count / 1_000_000)}M`;
+}
+
+export function contextColor(percent: number | null): string {
+  if (percent === null) return FG_DIM;
+  if (percent > 90) return FG_ERR;
+  if (percent > 70) return FG_WARN;
+  return FG_OK;
+}
+
+export function progressBar(percent: number | null, width = 10): string {
+  if (percent === null) return `${FG_DIM}${"░".repeat(width)}${RST}`;
+  const clamped = Math.max(0, Math.min(100, percent));
+  const filled = Math.round((clamped / 100) * width);
+  return `${contextColor(percent)}${"█".repeat(filled)}${FG_DIM}${"░".repeat(width - filled)}${RST}`;
+}
+
+export function formatCwd(cwd: string): string {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (home && cwd === home) return "~";
+  if (home && cwd.startsWith(`${home}/`)) return `~/${cwd.slice(home.length + 1)}`;
+  return basename(cwd) || cwd;
+}
+
+export function contentWidth(width: number, prefix: string, suffix = 0): number {
+  return Math.max(0, width - visibleWidth(prefix) - suffix);
+}