@bachi/pi-coder 1.0.0

package/extensions/rewind/index.ts

@@ -0,0 +1,400 @@
+/**
+ * pi-rewind — Claude Code style checkpointing and /rewind for pi.
+ *
+ * What it does
+ *   - Snapshots the working tree before every user prompt that starts a turn
+ *     (Claude Code's checkpoint model), stored on a shadow git repository under
+ *     ~/.pi/agent/rewind/<project>/git — the project's own git history, index
+ *     and refs are never touched.
+ *   - Catches the files that snapshot cannot see: anything an `edit`/`write`
+ *     tool touches outside the project root (or inside it but `.gitignore`d,
+ *     or under a nested repo) is copied into a pre-image blob right before the
+ *     tool runs, so a rewind restores those too.
+ *   - `/rewind` (or Esc twice at an empty prompt) opens the rewind menu:
+ *     restore code and conversation, restore conversation, restore code,
+ *     summarize from here, never mind.
+ *   - Conversation restore uses pi's native session-tree navigation, which
+ *     drops the selected user message and puts its text back into the editor —
+ *     exactly what Claude Code does.
+ *
+ * Esc + Esc
+ *   pi's built-in double-escape action (`doubleEscapeAction` in settings.json,
+ *   default "tree") is replaced by this extension. Set it to "none" so the
+ *   built-in tree navigator no longer fires:
+ *
+ *     { "doubleEscapeAction": "none" }
+ *
+ *   The extension then counts two raw Esc presses within 500 ms while the agent
+ *   is idle and the editor is empty, and dispatches /rewind. Escapes are never
+ *   consumed, so Esc still aborts streaming, aborts a running `!` bash command
+ *   and cancels dialogs exactly as before. When the setting is not "none" the
+ *   extension warns once at session start.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  MAX_CHECKPOINTS_PER_SESSION,
+  type RewindStore,
+  attachEntryId,
+  captureExternalFile,
+  createCheckpoint,
+  gc,
+  listCheckpoints,
+  openStore,
+  pruneSession,
+  pruneStaleSessions,
+} from "./checkpoints.ts";
+import { runRewindFlow } from "./flow.ts";
+import { pickFromList } from "./picker.ts";
+
+/** Claude Code / pi both use a 500 ms double-escape window. */
+const DOUBLE_ESCAPE_WINDOW_MS = 500;
+const STATUS_KEY = "rewind";
+
+interface RewindState {
+  store: RewindStore | null;
+  sessionId: string | null;
+  /** Reason the store could not be opened; reported once, then silent. */
+  disabledReason: string | null;
+  /** Latest context, used by the raw-input handler (it receives no ctx). */
+  ctx: ExtensionContext | null;
+  /** True while an extension dialog is open (ui_prompt_start/end). */
+  dialogOpen: boolean;
+  /** Timestamp of the previous bare Esc press, 0 when the window expired. */
+  lastEscapeAt: number;
+  /** Serializes every git operation that touches the shadow index. */
+  queue: Promise<unknown>;
+  /** Guards against repeating the doubleEscapeAction warning. */
+  warnedAboutSetting: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+  const state: RewindState = {
+    store: null,
+    sessionId: null,
+    disabledReason: null,
+    ctx: null,
+    dialogOpen: false,
+    lastEscapeAt: 0,
+    queue: Promise.resolve(),
+    warnedAboutSetting: false,
+  };
+
+  /** Run git work one job at a time: two concurrent `git add` calls on the
+   *  same shadow index would corrupt it. */
+  function serialized<T>(task: () => Promise<T>): Promise<T> {
+    const run = state.queue.then(task, task);
+    state.queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  function updateStatus(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    if (!state.store || !state.sessionId) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+    const count = listCheckpoints(state.store, state.sessionId).length;
+    const theme = ctx.ui.theme;
+    ctx.ui.setStatus(
+      STATUS_KEY,
+      `${theme.fg("dim", "◆")} ${theme.fg("muted", `${count} checkpoint${count === 1 ? "" : "s"}`)}`,
+    );
+  }
+
+  // ===========================================================================
+  // Session lifecycle
+  // ===========================================================================
+
+  pi.on("session_start", async (_event, ctx) => {
+    state.ctx = ctx;
+    state.dialogOpen = false;
+    state.lastEscapeAt = 0;
+
+    const sessionId = ctx.sessionManager.getSessionId();
+    state.sessionId = sessionId;
+
+    try {
+      state.store = openStore(ctx.cwd, getAgentDir());
+      state.disabledReason = null;
+    } catch (error) {
+      state.store = null;
+      state.disabledReason = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Rewind unavailable: ${state.disabledReason}`, "warning");
+      return;
+    }
+
+    // Esc+Esc replaces pi's built-in double-escape action; warn when the
+    // setting still points at the tree navigator.
+    warnIfDoubleEscapeStillBuiltIn(ctx);
+
+    const store = state.store;
+    const resumeCheckpointCount = listCheckpoints(store, sessionId).length;
+
+    // Snapshot the state the session starts from. Not awaited: a cold shadow
+    // index on a large repo can take seconds and must not delay startup.
+    serialized(async () => {
+      await createCheckpoint(store, { sessionId, kind: "session-start" });
+      await pruneSession(store, sessionId, MAX_CHECKPOINTS_PER_SESSION);
+      if (ctx.hasUI) updateStatus(ctx);
+    }).catch(() => undefined);
+
+    // Retention sweep + gc in the background.
+    serialized(async () => {
+      const swept = await pruneStaleSessions(store);
+      if (swept > 0) await gc(store);
+      if (resumeCheckpointCount > 0 && ctx.hasUI) updateStatus(ctx);
+    }).catch(() => undefined);
+
+    attachInputListener(ctx);
+  });
+
+  pi.on("session_shutdown", async () => {
+    // Let in-flight checkpoint work finish before pi tears the session down.
+    await state.queue.catch(() => undefined);
+  });
+
+  // ===========================================================================
+  // Checkpoints: one per user prompt, taken before the turn runs
+  // ===========================================================================
+
+  /**
+   * `message_end` for the user message is the moment pi records a prompt, and
+   * it happens before any tool of that turn executes — so the snapshot really
+   * is "the code as it was when you sent this". It also covers follow-up and
+   * steered prompts, which `before_agent_start` never sees.
+   *
+   * The user entry itself only lands in the session tree a little later (pi
+   * appends it while the assistant message is recorded), so the conversation
+   * target is attached on the assistant message / turn end instead. Matching by
+   * prompt text keeps multiple pending prompts apart.
+   */
+  pi.on("message_end", async (event, ctx) => {
+    state.ctx = ctx;
+    const role = event.message?.role;
+    if (role !== "user" && role !== "assistant") return;
+    if (!state.store || !state.sessionId) return;
+
+    if (role === "user") {
+      const prompt = messageText(event.message.content);
+      const store = state.store;
+      const sessionId = state.sessionId;
+      // Awaited on purpose: the snapshot must be complete before this turn's
+      // first tool can touch the working tree.
+      await serialized(async () => {
+        await createCheckpoint(store, { sessionId, kind: "prompt", prompt });
+        await pruneSession(store, sessionId, MAX_CHECKPOINTS_PER_SESSION);
+        if (ctx.hasUI) updateStatus(ctx);
+      }).catch(() => undefined);
+      return;
+    }
+
+    resolveEntryIds(ctx);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    state.ctx = ctx;
+    resolveEntryIds(ctx);
+  });
+
+  function resolveEntryIds(ctx: ExtensionContext): void {
+    const store = state.store;
+    const sessionId = state.sessionId;
+    if (!store || !sessionId) return;
+
+    const all = listCheckpoints(store, sessionId);
+    const unresolved = all.filter((cp) => cp.kind === "prompt" && !cp.entryId);
+    if (unresolved.length === 0) return;
+
+    const usedEntryIds = new Set(
+      all.filter((cp) => cp.entryId).map((cp) => cp.entryId as string),
+    );
+    const branch = ctx.sessionManager.getBranch();
+
+    for (const checkpoint of unresolved) {
+      for (let i = branch.length - 1; i >= 0; i -= 1) {
+        const entry = branch[i];
+        if (entry.type !== "message") continue;
+        if (entry.message.role !== "user") continue;
+        if (usedEntryIds.has(entry.id)) continue;
+        if (messageText(entry.message.content) !== checkpoint.prompt) continue;
+        attachEntryId(store, sessionId, checkpoint.id, entry.id);
+        usedEntryIds.add(entry.id);
+        break;
+      }
+    }
+  }
+
+  // ===========================================================================
+  // Pre-images: files the worktree snapshot cannot see
+  // ===========================================================================
+
+  /**
+   * Fires after `tool_execution_start` and before the tool runs, which is the
+   * only moment the old bytes are still on disk. Only the built-in file editors
+   * are tracked — a `bash` command (`sed -i`, `cat >`) can touch anything and
+   * is not parseable, so inside the project root those changes are still caught
+   * by the worktree snapshot while edits *outside* the root are not.
+   */
+  pi.on("tool_call", async (event, ctx) => {
+    state.ctx = ctx;
+    if (!state.store || !state.sessionId) return;
+    if (event.toolName !== "edit" && event.toolName !== "write") return;
+    const path = (event.input as { path?: unknown } | undefined)?.path;
+    if (typeof path !== "string" || path === "") return;
+
+    const store = state.store;
+    const sessionId = state.sessionId;
+    // Serialized with the checkpoint writes: both rewrite the metadata file.
+    // Awaited, so the copy is complete before the tool can change the file.
+    await serialized(async () => {
+      captureExternalFile(store, sessionId, path);
+    }).catch(() => undefined);
+  });
+
+  // ===========================================================================
+  // /rewind
+  // ===========================================================================
+
+  pi.registerCommand("rewind", {
+    description: "Rewind code and/or conversation to an earlier prompt (Claude Code style)",
+    handler: async (_args, ctx: ExtensionCommandContext) => {
+      state.ctx = ctx;
+      // Ignore Esc presses while the menu dialogs are open.
+      state.dialogOpen = true;
+      state.lastEscapeAt = 0;
+      try {
+        if (!state.store || !state.sessionId) {
+          ctx.ui.notify(
+            state.disabledReason
+              ? `Rewind unavailable: ${state.disabledReason}`
+              : "Rewind is not ready yet",
+            "warning",
+          );
+          return;
+        }
+        // Late resolution attempt for prompts whose entry id is still missing.
+        resolveEntryIds(ctx);
+        await runRewindFlow(ctx, {
+          store: state.store,
+          sessionId: state.sessionId,
+          // Scrollable picker: pi's built-in select renders every row, which
+          // pushes the cursor out of the viewport on long sessions.
+          pick: pickFromList,
+        });
+        if (ctx.hasUI) updateStatus(ctx);
+      } finally {
+        state.dialogOpen = false;
+        state.lastEscapeAt = 0;
+      }
+    },
+  });
+
+  // ===========================================================================
+  // Esc + Esc
+  // ===========================================================================
+
+  pi.on("ui_prompt_start", async () => {
+    state.dialogOpen = true;
+  });
+
+  pi.on("ui_prompt_end", async () => {
+    state.dialogOpen = false;
+    state.lastEscapeAt = 0;
+  });
+
+  let inputUnsubscribe: (() => void) | null = null;
+
+  function attachInputListener(ctx: ExtensionContext): void {
+    if (inputUnsubscribe) return;
+    inputUnsubscribe = ctx.ui.onTerminalInput((data) => {
+      // A bare Esc is exactly "\x1b"; arrow keys and other sequences are longer
+      // and must not count towards a double press.
+      if (data !== "\x1b") {
+        state.lastEscapeAt = 0;
+        return undefined;
+      }
+      // Never consume: Esc keeps aborting streams, `!` bash runs and dialogs.
+      if (state.dialogOpen) return undefined;
+      const current = state.ctx;
+      if (!current || !current.isIdle()) return undefined;
+      if (current.ui.getEditorText().trim() !== "") return undefined;
+
+      const now = Date.now();
+      if (now - state.lastEscapeAt <= DOUBLE_ESCAPE_WINDOW_MS) {
+        state.lastEscapeAt = 0;
+        dispatchRewind();
+        // Consume this second press. Two reasons: the selector opened by
+        // dispatchRewind() is focused synchronously, so an unconsumed Esc would
+        // land on it and cancel the menu it just opened; and consuming keeps
+        // the press from pi's built-in double-escape action, so /rewind takes
+        // over even when `doubleEscapeAction` is still "tree" or "fork".
+        return { consume: true };
+      }
+      // The first press is passed through untouched, so a lone Esc still
+      // aborts streams, aborts `!` bash runs and cancels dialogs.
+      state.lastEscapeAt = now;
+      return undefined;
+    });
+  }
+
+  /**
+   * Dispatch the /rewind command through pi's own command path, so the handler
+   * receives a command context (with navigateTree) — a shortcut or raw-input
+   * handler only ever gets a plain context.
+   */
+  function dispatchRewind(): void {
+    try {
+      pi.sendUserMessage("/rewind", { expandPromptTemplates: true });
+    } catch (error) {
+      state.ctx?.ui.notify(
+        `Could not open /rewind: ${error instanceof Error ? error.message : String(error)}`,
+        "warning",
+      );
+    }
+  }
+
+  function warnIfDoubleEscapeStillBuiltIn(ctx: ExtensionContext): void {
+    if (state.warnedAboutSetting || !ctx.hasUI) return;
+    state.warnedAboutSetting = true;
+    try {
+      const settingsPath = join(getAgentDir(), "settings.json");
+      const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as {
+        doubleEscapeAction?: string;
+      };
+      const action = settings.doubleEscapeAction ?? "tree";
+      if (action !== "none") {
+        ctx.ui.notify(
+          `Esc+Esc still opens pi's ${action} view. Set "doubleEscapeAction": "none" in ${settingsPath} to let /rewind take over.`,
+          "warning",
+        );
+      }
+    } catch {
+      // No readable settings file — nothing to warn about.
+    }
+  }
+}
+
+/** Plain text of a message's content (string or content parts). */
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const part of content) {
+    if (part && typeof part === "object" && "text" in part && typeof part.text === "string") {
+      parts.push(part.text);
+    }
+  }
+  return parts.join("\n");
+}

package/extensions/rewind/picker.ts

@@ -0,0 +1,135 @@
+/**
+ * pi-rewind picker — the scrollable checkpoint selector behind `/rewind`.
+ *
+ * Why not `ctx.ui.select()`: pi's built-in extension selector appends one row
+ * per option and never scrolls (`ExtensionSelectorComponent.updateList()`), so
+ * a session with more checkpoints than the terminal has rows produces a dialog
+ * taller than the viewport — and pi-tui paints only the **last**
+ * `terminal.rows` lines of the document, which cuts the dialog's top away:
+ * the title, and the `→` cursor row it opens on. The user is left with a list
+ * whose selection arrow is somewhere off screen.
+ *
+ * This picker keeps the dialog inside the viewport instead: the list window is
+ * sized to the terminal (`pickerListRows` in viewport.ts) and pi-tui's
+ * `SelectList` windows the rows around the selection, so the arrow is always
+ * visible and the list scrolls. `SelectList` also draws a `(12/37)` position
+ * line while scrolling, and it is theme-aware and mouse-aware for free.
+ *
+ * Movement keys are handled here rather than inside `SelectList` for two
+ * reasons: `SelectList` wraps around at both ends (`up` on the newest
+ * checkpoint jumps to the oldest) while pi's own dialogs clamp, and it has no
+ * page/home/end handling. Keys therefore clamp, `PageUp`/`PageDown` move a
+ * window at a time, `Home`/`End` jump to the ends, and `j`/`k` work like they
+ * do in pi's built-in selector. `Enter`/`Esc` are left to `SelectList`, so
+ * their configured bindings apply.
+ *
+ * Hosts that cannot render extension components (RPC, print) make
+ * `ctx.ui.custom()` resolve `undefined`; the caller (`pickValue` in flow.ts)
+ * then falls back to `ctx.ui.select()`.
+ */
+
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  DynamicBorder,
+  getSelectListTheme,
+  keyHint,
+  keyText,
+  rawKeyHint,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Container,
+  Key,
+  SelectList,
+  Text,
+  type TuiMouseEvent,
+  matchesKey,
+  truncateToWidth,
+} from "@earendil-works/pi-tui";
+
+import type { PickOutcome, PickerItem } from "./flow.ts";
+import { pickerListRows } from "./viewport.ts";
+
+export async function pickFromList(
+  ctx: ExtensionCommandContext,
+  title: string,
+  items: PickerItem[],
+): Promise<PickOutcome> {
+  const picked = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) => {
+    const rows = pickerListRows(tui.terminal?.rows);
+    const list = new SelectList(items, Math.min(items.length, rows), getSelectListTheme());
+    list.onSelect = (item) => done(item.value);
+    list.onCancel = () => done(null);
+
+    const container = new Container();
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    container.addChild(list);
+    container.addChild(new Line(() => hintLine(theme, items.length > rows)));
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    /** Where the cursor is; `SelectList` exposes the selected item, not its index. */
+    const cursor = (): number => {
+      const item = list.getSelectedItem();
+      return item ? items.indexOf(item) : 0;
+    };
+    const moveTo = (index: number): void => {
+      list.setSelectedIndex(Math.max(0, Math.min(items.length - 1, index)));
+    };
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (keybindings.matches(data, "tui.select.up") || data === "k") {
+          moveTo(cursor() - 1);
+        } else if (keybindings.matches(data, "tui.select.down") || data === "j") {
+          moveTo(cursor() + 1);
+        } else if (keybindings.matches(data, "tui.select.pageUp")) {
+          moveTo(cursor() - rows);
+        } else if (keybindings.matches(data, "tui.select.pageDown")) {
+          moveTo(cursor() + rows);
+        } else if (matchesKey(data, Key.home)) {
+          moveTo(0);
+        } else if (matchesKey(data, Key.end)) {
+          moveTo(items.length - 1);
+        } else {
+          list.handleInput(data);
+        }
+        tui.requestRender();
+      },
+      handleMouse: (event: TuiMouseEvent) => container.handleMouse(event),
+    };
+  });
+
+  // `undefined` is what a host that cannot render custom components returns;
+  // `null` is this component's own cancel value.
+  if (picked === undefined) return { status: "unsupported" };
+  if (picked === null) return { status: "cancelled" };
+  return { status: "picked", value: picked };
+}
+
+/** Footer hint. The paging keys only matter once the list does not fit. */
+function hintLine(theme: Theme, pageable: boolean): string {
+  const parts = [rawKeyHint("↑↓", "navigate")];
+  if (pageable) {
+    // Both page keys in one hint: `keyHint` would print the key name twice.
+    const keys = `${keyText("tui.select.pageUp")}/${keyText("tui.select.pageDown")}`;
+    parts.push(`${theme.fg("dim", keys)}${theme.fg("muted", " page")}`);
+  }
+  parts.push(keyHint("tui.select.confirm", "select"), keyHint("tui.select.cancel", "cancel"));
+  return `  ${parts.join("  ")}`;
+}
+
+/** A single line that truncates to the render width instead of wrapping into two. */
+class Line implements Component {
+  constructor(private readonly text: () => string) {}
+
+  render(width: number): string[] {
+    return [truncateToWidth(this.text(), width, "…")];
+  }
+
+  invalidate(): void {
+    // Nothing cached: the text is rebuilt from the live theme on every render.
+  }
+}

package/extensions/rewind/viewport.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Tests for the picker layout budget.
+ *
+ * Run with:  node --test ~/.pi/agent/extensions/rewind/viewport.test.ts
+ *
+ * The point of these cases is the invariant, not the arithmetic: whatever the
+ * terminal height, the dialog (list + its own chrome) plus the rows pi paints
+ * below it must fit the viewport. That is what keeps the selection arrow on
+ * screen for a session with more checkpoints than the terminal has rows.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  DEFAULT_TERMINAL_ROWS,
+  PICKER_CHROME_ROWS,
+  PICKER_MAX_LIST_ROWS,
+  PICKER_TAIL_RESERVE_ROWS,
+  pickerListRows,
+  resolveTerminalRows,
+} from "./viewport.ts";
+
+describe("resolveTerminalRows", () => {
+  it("falls back for values a non-TTY host reports", () => {
+    assert.equal(resolveTerminalRows(undefined), DEFAULT_TERMINAL_ROWS);
+    assert.equal(resolveTerminalRows(Number.NaN), DEFAULT_TERMINAL_ROWS);
+    assert.equal(resolveTerminalRows(0), DEFAULT_TERMINAL_ROWS);
+    assert.equal(resolveTerminalRows(-3), DEFAULT_TERMINAL_ROWS);
+  });
+
+  it("keeps real heights, floored to whole rows", () => {
+    assert.equal(resolveTerminalRows(41), 41);
+    assert.equal(resolveTerminalRows(41.9), 41);
+  });
+});
+
+describe("pickerListRows", () => {
+  it("leaves the chrome and the rows below the editor alone", () => {
+    assert.equal(pickerListRows(24), 24 - PICKER_CHROME_ROWS - PICKER_TAIL_RESERVE_ROWS);
+    assert.equal(pickerListRows(30), 30 - PICKER_CHROME_ROWS - PICKER_TAIL_RESERVE_ROWS);
+  });
+
+  it("caps tall terminals so the picker stays a picker", () => {
+    assert.equal(pickerListRows(120), PICKER_MAX_LIST_ROWS);
+    assert.equal(pickerListRows(1_000), PICKER_MAX_LIST_ROWS);
+  });
+
+  it("never returns less than one row, however short the terminal", () => {
+    assert.equal(pickerListRows(1), 1);
+    assert.equal(pickerListRows(8), 1);
+    assert.equal(pickerListRows(12), 2);
+  });
+
+  it("falls back to the assumed height when the size is unknown", () => {
+    assert.equal(pickerListRows(undefined), pickerListRows(DEFAULT_TERMINAL_ROWS));
+  });
+
+  it("degrades to a single row on terminals shorter than the dialog chrome", () => {
+    for (let rows = 1; rows < PICKER_CHROME_ROWS + PICKER_TAIL_RESERVE_ROWS; rows += 1) {
+      assert.equal(pickerListRows(rows), 1, `rows=${rows}`);
+    }
+  });
+
+  it("keeps the whole dialog inside the viewport at every height", () => {
+    // The dialog is the list plus its own chrome; the tail reserve stands in for
+    // the footer and the widgets pi paints below the editor container.
+    // Below this the chrome + tail reserve alone already fill the screen, so
+    // there is nothing to fit — see the single-row case above.
+    const minimumRows = PICKER_CHROME_ROWS + PICKER_TAIL_RESERVE_ROWS + 1;
+    for (let rows = minimumRows; rows <= 200; rows += 1) {
+      const painted = pickerListRows(rows) + PICKER_CHROME_ROWS + PICKER_TAIL_RESERVE_ROWS;
+      assert.ok(painted <= rows, `rows=${rows} would paint ${painted} lines`);
+    }
+  });
+});

package/extensions/rewind/viewport.ts

@@ -0,0 +1,48 @@
+/**
+ * pi-rewind picker layout — how many checkpoint rows the dialog may show.
+ *
+ * Why this exists: pi-tui renders only the **last** `terminal.rows` lines of
+ * the document (`TuiMainScreen.render()`: `viewportStart = max(0, height -
+ * terminal.rows)`), so a dialog taller than the terminal loses its top. pi's
+ * built-in extension selector renders one row per option and never scrolls
+ * (`ExtensionSelectorComponent.updateList()`), which means a long checkpoint
+ * list pushes the title — and the `→` cursor row the dialog opens on — off the
+ * top of the screen, leaving the user with no visible cursor.
+ *
+ * The picker therefore sizes its window to the terminal and scrolls instead.
+ * The rows it must leave alone are named here, in one place:
+ *
+ *   - `PICKER_CHROME_ROWS`: the dialog's own non-list lines — top border,
+ *     title, key hint, bottom border, plus `SelectList`'s `(12/37)` line that
+ *     only appears while the list is scrolled. One row of slack is included so
+ *     a surprising extra line (a truncated hint that still wraps) cannot push
+ *     the title out of view.
+ *   - `PICKER_TAIL_RESERVE_ROWS`: what pi renders **below** the editor
+ *     container, which is where the custom component lives — the footer
+ *     (`⚡️ model | Ctx …`), the extra statusline rows, and any
+ *     `placement: belowEditor` widget such as pi-subagents' fleet line. Those
+ *     rows are painted after the dialog and would otherwise cover its bottom.
+ */
+
+/** Lines the picker dialog spends outside the list. */
+export const PICKER_CHROME_ROWS = 6;
+/** Lines to leave for what pi paints below the editor container. */
+export const PICKER_TAIL_RESERVE_ROWS = 4;
+/** Upper bound, so the picker does not take over a tall terminal. */
+export const PICKER_MAX_LIST_ROWS = 20;
+/** Assumed height when the host cannot report a terminal size. */
+export const DEFAULT_TERMINAL_ROWS = 24;
+
+/** Rows the picker dialog can show, for a terminal height that may be unknown. */
+export function pickerListRows(terminalRows: number | undefined): number {
+  const available = resolveTerminalRows(terminalRows) - PICKER_CHROME_ROWS - PICKER_TAIL_RESERVE_ROWS;
+  return Math.max(1, Math.min(PICKER_MAX_LIST_ROWS, available));
+}
+
+/** Terminal height with the non-TTY cases folded into a usable number. */
+export function resolveTerminalRows(terminalRows: number | undefined): number {
+  if (typeof terminalRows !== "number" || !Number.isFinite(terminalRows) || terminalRows <= 0) {
+    return DEFAULT_TERMINAL_ROWS;
+  }
+  return Math.floor(terminalRows);
+}