@a-t-h-i/bot-lobby 0.6.7 → 0.6.8

package/src/knowledge/notes.ts

@@ -0,0 +1,143 @@
+/**
+ * The user's comments on knowledge: notes about one entry of an agent's
+ * knowledge file ("outdated, we moved to Redis"). They live in one
+ * append-only JSON-lines log per project, never inside the knowledge files
+ * (agents rewrite those when they compact them), and reach every agent that
+ * reads the knowledge: `annotate` puts each note right under its entry, so it
+ * travels with the entry into the prompt and the agent weighs it there.
+ *
+ * A note is tied to its entry by the entry's exact text. Editing the entry
+ * from the Knowledge tab moves its notes to the new text; a note whose entry
+ * changed some other way is kept, and shown under the file as detached.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { KnowledgeAgent } from "./paths.ts";
+import { parseEntries } from "./edit.ts";
+
+export interface KnowledgeNote {
+  id: string;
+  agent: KnowledgeAgent;
+  /** The knowledge file, e.g. `decisions.md`. */
+  file: string;
+  /** The exact text of the entry it is about. */
+  entry: string;
+  text: string;
+  createdAt: string;
+  /** The pi session that wrote it, when known. */
+  by?: string;
+}
+
+type NoteEvent =
+  | { kind: "note"; id: string; agent: KnowledgeAgent; file: string; entry: string; text: string; at: string; by?: string }
+  | { kind: "move"; id: string; entry: string; at: string }
+  | { kind: "remove"; id: string; at: string };
+
+/** Longest note kept; agents read it verbatim. */
+export const MAX_NOTE_CHARS = 2000;
+
+export function notesPath(dataRoot: string): string {
+  return join(dataRoot, "knowledge-comments.jsonl");
+}
+
+function append(dataRoot: string, event: NoteEvent): void {
+  const path = notesPath(dataRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(event)}\n`, "utf8");
+}
+
+/** The notes as they stand, oldest first. A torn line from a crashed writer is skipped. */
+export function readNotes(dataRoot: string | undefined): KnowledgeNote[] {
+  if (!dataRoot) return [];
+  const path = notesPath(dataRoot);
+  if (!existsSync(path)) return [];
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const notes = new Map<string, KnowledgeNote>();
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let event: NoteEvent;
+    try {
+      event = JSON.parse(line) as NoteEvent;
+    } catch {
+      continue;
+    }
+    if (!event || typeof event.id !== "string") continue;
+    if (event.kind === "note" && !notes.has(event.id) && typeof event.text === "string" && typeof event.entry === "string") {
+      notes.set(event.id, { id: event.id, agent: event.agent, file: event.file, entry: event.entry, text: event.text, createdAt: event.at, ...(event.by ? { by: event.by } : {}) });
+    } else if (event.kind === "move" && typeof event.entry === "string") {
+      const note = notes.get(event.id);
+      if (note) note.entry = event.entry;
+    } else if (event.kind === "remove") notes.delete(event.id);
+  }
+  return [...notes.values()];
+}
+
+/** Leave a note on an entry. */
+export function addNote(dataRoot: string, note: { agent: KnowledgeAgent; file: string; entry: string; text: string; by?: string }, now = new Date()): KnowledgeNote {
+  const text = note.text.trim().slice(0, MAX_NOTE_CHARS);
+  if (!text) throw new Error("a note needs some words");
+  if (!note.entry.trim()) throw new Error("a note needs an entry to be about");
+  const id = randomUUID().slice(0, 8);
+  const at = now.toISOString();
+  append(dataRoot, { kind: "note", id, agent: note.agent, file: note.file, entry: note.entry, text, at, ...(note.by ? { by: note.by } : {}) });
+  return { id, agent: note.agent, file: note.file, entry: note.entry, text, createdAt: at, ...(note.by ? { by: note.by } : {}) };
+}
+
+export function removeNote(dataRoot: string, id: string, now = new Date()): void {
+  append(dataRoot, { kind: "remove", id, at: now.toISOString() });
+}
+
+/** Move every note on `from` to `to`: the entry was edited, its notes stay with it. Returns how many moved. */
+export function moveNotes(dataRoot: string, agent: KnowledgeAgent, file: string, from: string, to: string, now = new Date()): number {
+  if (from === to) return 0;
+  const moving = readNotes(dataRoot).filter((note) => note.agent === agent && note.file === file && note.entry === from);
+  for (const note of moving) append(dataRoot, { kind: "move", id: note.id, entry: to, at: now.toISOString() });
+  return moving.length;
+}
+
+/** Drop every note on `entry`: the entry was deleted. Returns how many went. */
+export function removeNotesOn(dataRoot: string, agent: KnowledgeAgent, file: string, entry: string, now = new Date()): number {
+  const going = readNotes(dataRoot).filter((note) => note.agent === agent && note.file === file && note.entry === entry);
+  for (const note of going) removeNote(dataRoot, note.id, now);
+  return going.length;
+}
+
+/** `> Note from the user: …` with every line of a longer note quoted. */
+function noteLines(note: KnowledgeNote, about?: string): string[] {
+  const [first = "", ...rest] = note.text.split("\n");
+  const lead = about ? `Note from the user about "${about}": ` : "Note from the user: ";
+  return [`> ${lead}${first}`, ...rest.map((line) => `> ${line}`)];
+}
+
+/**
+ * A file's text with each note under the entry it is about, as the agents
+ * read it. A note whose entry is gone is added at the end, naming the entry it
+ * was about, so what the user said is never lost. Notes the text already
+ * carries (an agent copied them in when it compacted the file) are not added twice.
+ */
+export function annotate(content: string, notes: readonly KnowledgeNote[]): string {
+  if (notes.length === 0) return content;
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const entries = parseEntries(content);
+  const carried = (note: KnowledgeNote) => content.includes(noteLines(note)[0]!);
+  const pending = notes.filter((note) => !carried(note));
+  const detached: KnowledgeNote[] = [];
+  const under = new Map<number, KnowledgeNote[]>();
+  for (const note of pending) {
+    const entry = entries.find((candidate) => candidate.text === note.entry);
+    if (!entry) detached.push(note);
+    else under.set(entry.end, [...(under.get(entry.end) ?? []), note]);
+  }
+  // Bottom-up, so earlier positions stay where they are.
+  for (const at of [...under.keys()].sort((a, b) => b - a)) lines.splice(at, 0, ...under.get(at)!.flatMap((note) => noteLines(note)));
+  const body = lines.join("\n").replace(/\n+$/, "");
+  if (detached.length === 0) return body;
+  const about = (note: KnowledgeNote) => note.entry.replace(/\s+/g, " ").trim().slice(0, 60);
+  return `${body}\n\n${detached.flatMap((note) => noteLines(note, about(note))).join("\n")}`;
+}

package/src/knowledge/selector.ts

@@ -36,7 +36,7 @@ export function splitSections(markdown: string): string[] {
     .filter((part) => part.length > 0);
 }
 
-function score(sectionText: string, tokens: string[]): number {
+export function score(sectionText: string, tokens: string[]): number {
   const lower = sectionText.toLowerCase();
   return tokens.reduce((total, token) => total + (lower.includes(token) ? 1 : 0), 0);
 }

package/src/knowledge/store.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { knowledgeDir, STANDARDS_FILE, type KnowledgeAgent } from "./paths.ts";
+import { annotate, readNotes } from "./notes.ts";
 
 export function readFileOr(path: string, fallback = ""): string {
   try {
@@ -105,7 +106,20 @@ export function readKnowledgeSlices(
   };
 }
 
-/** Read an agent's knowledge by agent key; bot-lobby dirs win per file over the pre-rename ones. */
+/**
+ * Read an agent's knowledge by agent key; bot-lobby dirs win per file over the
+ * pre-rename ones. The user's notes on entries (Knowledge tab) sit right under
+ * the entries they are about, so every agent reads them with the knowledge.
+ */
 export function readAgentKnowledge(roots: readonly string[], agent: KnowledgeAgent) {
-  return readKnowledgeSlices(roots.map((root) => knowledgeDir(root, agent)), STANDARDS_FILE[agent]);
+  const slices = readKnowledgeSlices(roots.map((root) => knowledgeDir(root, agent)), STANDARDS_FILE[agent]);
+  const notes = readNotes(roots[0]).filter((note) => note.agent === agent);
+  if (notes.length === 0) return slices;
+  const about = (file: string) => notes.filter((note) => note.file === file);
+  return {
+    knowledge: annotate(slices.knowledge, about("knowledge.md")),
+    standards: annotate(slices.standards, about(STANDARDS_FILE[agent])),
+    decisions: annotate(slices.decisions, about("decisions.md")),
+    completed: annotate(slices.completed, about("completed-tasks.md")),
+  };
 }

package/src/lobby/ask.ts

@@ -6,7 +6,7 @@
  * answers become the user's turn for the next round.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PanelQuestion } from "./planner.ts";
+import type { PanelQuestion, SettledQuestion } from "./planner.ts";
 import { MAX_HEADER, MAX_LABEL, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, RESERVED, type AskAnswer, type AskOption, type AskQuestion, type AskResult } from "../ask/types.ts";
 import type { Asker } from "../ask/dialog.ts";
 
@@ -64,6 +64,35 @@ function answerText(answer: AskAnswer | undefined): string | undefined {
   return answer.answer?.trim() || undefined;
 }
 
+/** A multi-line answer keeps its lines under the `→` that opens it. */
+function indented(text: string, by: string): string {
+  return text.replace(/\n/g, `\n${by}`);
+}
+
+/** Every question of the round with the answer the user gave it, in the order asked. */
+function answered(questions: readonly PanelQuestion[], results: readonly AskResult[]): Array<{ number: number; question: PanelQuestion; answer: AskAnswer | undefined; text: string | undefined }> {
+  const rows: Array<{ number: number; question: PanelQuestion; answer: AskAnswer | undefined; text: string | undefined }> = [];
+  results.forEach((result, chunk) => {
+    const offset = chunk * MAX_QUESTIONS;
+    for (let i = 0; i < MAX_QUESTIONS; i++) {
+      const question = questions[offset + i];
+      if (!question) break;
+      const answer = result.answers.find((entry) => entry.questionIndex === i);
+      rows.push({ number: offset + i + 1, question, answer, text: answerText(answer) });
+    }
+  });
+  return rows;
+}
+
+/**
+ * What the user's reply settled: each question of the round with its answer,
+ * or without one when they left it. The panel is never allowed to ask a
+ * settled question again.
+ */
+export function settledQuestions(questions: readonly PanelQuestion[], results: readonly AskResult[]): SettledQuestion[] {
+  return answered(questions, results).map(({ question, text }) => ({ from: question.from, question: question.text.replace(/\s+/g, " ").trim(), ...(text ? { answer: text } : {}) }));
+}
+
 /**
  * The user's turn for the next round: every question with who asked it and
  * the answer (`→ …`), their notes, and what they left unanswered. Undefined
@@ -72,27 +101,19 @@ function answerText(answer: AskAnswer | undefined): string | undefined {
 export function answerMessage(questions: readonly PanelQuestion[], results: readonly AskResult[]): string | undefined {
   const lines: string[] = [];
   const skipped: string[] = [];
-  const notes: string[] = [];
-  let answered = 0;
-  results.forEach((result, chunk) => {
-    if (result.globalNote?.trim()) notes.push(result.globalNote.trim());
-    const offset = chunk * MAX_QUESTIONS;
-    for (let i = 0; i < MAX_QUESTIONS; i++) {
-      const question = questions[offset + i];
-      if (!question) break;
-      const answer = result.answers.find((entry) => entry.questionIndex === i);
-      const text = answerText(answer);
-      const label = `${offset + i + 1}. [${question.from}] ${question.text.replace(/\s+/g, " ").trim()}`;
-      if (!text) {
-        skipped.push(label);
-        continue;
-      }
-      answered += 1;
-      lines.push(`${label}\n   → ${text}${answer?.kind === "custom" ? " (in my words)" : ""}`);
-      if (answer?.notes?.trim()) lines.push(`   note: ${answer.notes.trim()}`);
+  const notes = results.map((result) => result.globalNote?.trim()).filter((note): note is string => Boolean(note));
+  let count = 0;
+  for (const { number, question, answer, text } of answered(questions, results)) {
+    const label = `${number}. [${question.from}] ${question.text.replace(/\s+/g, " ").trim()}`;
+    if (!text) {
+      skipped.push(label);
+      continue;
     }
-  });
-  if (answered === 0 && notes.length === 0) return undefined;
+    count += 1;
+    lines.push(`${label}\n   → ${indented(text, "     ")}${answer?.kind === "custom" ? " (in my words)" : ""}`);
+    if (answer?.notes?.trim()) lines.push(`   note: ${indented(answer.notes.trim(), "     ")}`);
+  }
+  if (count === 0 && notes.length === 0) return undefined;
   return [
     "Answers to the panel's questions:",
     ...lines,

package/src/lobby/issues.ts

@@ -63,7 +63,7 @@ export function ghError(result: Partial<ExecResult> & { error?: string }): strin
   return first.length > 160 ? `${first.slice(0, 159)}…` : first;
 }
 
-async function gh(exec: Exec, cwd: string, args: string[]): Promise<string> {
+export async function gh(exec: Exec, cwd: string, args: string[]): Promise<string> {
   let result: ExecResult;
   try {
     result = await exec("gh", args, { cwd, timeout: TIMEOUT_MS });

package/src/lobby/knowledge.ts

@@ -0,0 +1,179 @@
+/**
+ * The Knowledge tab's side of the disk: every agent's knowledge files, one
+ * file read as entries with the user's notes on them, and the edits the user
+ * can make — replace, add or delete an entry, edit the whole file — plus
+ * notes. Every write goes through the compactor's path, which archives the
+ * previous version first (`archive/<Agent>/…bak`), so an edit can be undone by
+ * hand. An entry is found again by its exact text; when the file changed on
+ * disk since the tab drew it, the edit is refused with a line saying so.
+ */
+import { join } from "node:path";
+import { compactKnowledgeFile } from "../knowledge/compactor.ts";
+import { findEntry, insertAfter, parseEntries, removeEntry, replaceEntry, type KnowledgeEntry } from "../knowledge/edit.ts";
+import { addNote, moveNotes, readNotes, removeNote, removeNotesOn, type KnowledgeNote } from "../knowledge/notes.ts";
+import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir, type KnowledgeAgent } from "../knowledge/paths.ts";
+import { readFirstExisting } from "../knowledge/store.ts";
+import { dataRoot, readDataRoots } from "../state/project.ts";
+
+/** What each knowledge file is, in words. */
+export const FILE_LABELS: Record<string, string> = {
+  "knowledge.md": "Knowledge",
+  "decisions.md": "Decisions",
+  "completed-tasks.md": "Completed tasks",
+  "standards.md": "Standards",
+  "design-language.md": "Design language",
+  "engineering-standards.md": "Engineering standards",
+  "testing-standards.md": "Testing standards",
+};
+
+/** Who the agents are, as the lobby names them. */
+export const AGENT_LABELS: Record<KnowledgeAgent, string> = { master: "Master (oracle)", designer: "Designer", backend: "Backend", qa: "QA" };
+
+export interface KnowledgeFileInfo {
+  agent: KnowledgeAgent;
+  file: string;
+  label: string;
+  chars: number;
+  /** Past the compaction threshold: the Master should compact it. */
+  over: boolean;
+  notes: number;
+}
+
+export interface KnowledgeView extends KnowledgeFileInfo {
+  content: string;
+  entries: KnowledgeEntry[];
+  /** Notes on entries this file has. */
+  attached: KnowledgeNote[];
+  /** Notes whose entry has changed or gone: kept, shown apart. */
+  detached: KnowledgeNote[];
+}
+
+/** An entry picked in the tab: its text, and which of several identical ones it is. */
+export interface EntryRef {
+  text: string;
+  occurrence: number;
+}
+
+export interface KnowledgeDeps {
+  root: string;
+  configDir: string;
+  /** Characters past which a file is over its compaction threshold. */
+  threshold: () => number;
+  /** Backups of a file kept in the archive. */
+  backups: () => number;
+  sessionId?: () => string | undefined;
+  now?: () => Date;
+}
+
+const CHANGED = "that entry changed on disk since it was drawn — r reloads the file";
+
+export class KnowledgeBook {
+  private readonly deps: KnowledgeDeps;
+
+  constructor(deps: KnowledgeDeps) {
+    this.deps = deps;
+  }
+
+  private get data(): string {
+    return dataRoot(this.deps.root, this.deps.configDir);
+  }
+
+  private read(agent: KnowledgeAgent, file: string): string {
+    return readFirstExisting(readDataRoots(this.deps.root, this.deps.configDir).map((root) => join(knowledgeDir(root, agent), file)));
+  }
+
+  /** Every agent's files in the order the tab lists them, with their size and notes. */
+  files(): KnowledgeFileInfo[] {
+    const notes = readNotes(this.data);
+    return (Object.keys(AGENT_DIR_NAMES) as KnowledgeAgent[]).flatMap((agent) =>
+      KNOWLEDGE_FILES[agent].map((file) => {
+        const chars = this.read(agent, file).length;
+        return { agent, file, label: FILE_LABELS[file] ?? file, chars, over: chars > this.deps.threshold(), notes: notes.filter((note) => note.agent === agent && note.file === file).length };
+      }),
+    );
+  }
+
+  /** One file as entries with their notes. */
+  open(agent: KnowledgeAgent, file: string): KnowledgeView {
+    const content = this.read(agent, file);
+    const entries = parseEntries(content);
+    const notes = readNotes(this.data).filter((note) => note.agent === agent && note.file === file);
+    const known = new Set(entries.map((entry) => entry.text));
+    return {
+      agent,
+      file,
+      label: FILE_LABELS[file] ?? file,
+      chars: content.length,
+      over: content.length > this.deps.threshold(),
+      notes: notes.length,
+      content,
+      entries,
+      attached: notes.filter((note) => known.has(note.entry)),
+      detached: notes.filter((note) => !known.has(note.entry)),
+    };
+  }
+
+  /** Write a file's new content with the previous one archived; the notice says where it went. */
+  private write(agent: KnowledgeAgent, file: string, content: string): string {
+    compactKnowledgeFile({ dataRoot: this.data, agent, file, content, backupCount: this.deps.backups(), ...(this.deps.now ? { now: this.deps.now() } : {}) });
+    return `saved ${agent}/${file} — the version before is in archive/${AGENT_DIR_NAMES[agent]}`;
+  }
+
+  /** Replace one entry with `text`, exactly as written; its notes move with it. */
+  edit(agent: KnowledgeAgent, file: string, ref: EntryRef, text: string): string {
+    const content = this.read(agent, file);
+    const entry = findEntry(content, ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    if (!text.trim()) return "nothing to save — d d deletes an entry, esc cancels";
+    const next = replaceEntry(content, entry, text);
+    if (next.trim() === content.trim()) return "nothing changed";
+    const notice = this.write(agent, file, next);
+    const moved = moveNotes(this.data, agent, file, entry.text, text.replace(/\s+$/, ""), this.deps.now?.());
+    return `${notice}${moved > 0 ? `; ${moved} note${moved === 1 ? "" : "s"} stayed with it` : ""}`;
+  }
+
+  /** Add a bullet after an entry (at the end when there is none). */
+  add(agent: KnowledgeAgent, file: string, after: EntryRef | undefined, text: string): string {
+    const content = this.read(agent, file);
+    const entry = after ? findEntry(content, after.text, after.occurrence) : undefined;
+    if (after && !entry) return CHANGED;
+    const next = insertAfter(content, entry, text);
+    if (next === content) return "nothing to add";
+    return this.write(agent, file, next);
+  }
+
+  /** Delete an entry, and the notes on it. */
+  remove(agent: KnowledgeAgent, file: string, ref: EntryRef): string {
+    const content = this.read(agent, file);
+    const entry = findEntry(content, ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    const notice = this.write(agent, file, removeEntry(content, entry));
+    const gone = removeNotesOn(this.data, agent, file, entry.text, this.deps.now?.());
+    return `${notice}${gone > 0 ? `; its ${gone} note${gone === 1 ? "" : "s"} went with it` : ""}`;
+  }
+
+  /** Replace a whole file (edited in pi's editor). */
+  replaceFile(agent: KnowledgeAgent, file: string, text: string): string {
+    const content = this.read(agent, file);
+    if (text.trim() === content.trim()) return "nothing changed";
+    return this.write(agent, file, text);
+  }
+
+  /** Leave a note on an entry: every agent that reads this knowledge reads it under the entry. */
+  comment(agent: KnowledgeAgent, file: string, ref: EntryRef, text: string): string {
+    const entry = findEntry(this.read(agent, file), ref.text, ref.occurrence);
+    if (!entry) return CHANGED;
+    try {
+      addNote(this.data, { agent, file, entry: entry.text, text, ...(this.deps.sessionId?.() ? { by: this.deps.sessionId!()! } : {}) }, this.deps.now?.());
+    } catch (error) {
+      return (error as Error).message;
+    }
+    return "note saved — every agent reads it under this entry";
+  }
+
+  /** Take a note back. */
+  unnote(id: string): string {
+    removeNote(this.data, id, this.deps.now?.());
+    return "note removed";
+  }
+}

package/src/lobby/layout.ts

@@ -91,6 +91,9 @@ export function wrapHanging(lead: string, text: string, width: number): string[]
   return body.map((line, index) => `${index === 0 ? lead : " ".repeat(indent)}${line}`);
 }
 
+/** The mark before a git branch name, in the lobby's title and a task's details. */
+export const BRANCH_GLYPH = "⎇";
+
 /** `── Title ───────` spanning `width`; `right` sits at the far end when it fits. */
 export function rule(width: number, title = "", theme?: LobbyTheme, right = "", color: LobbyColor = "borderMuted"): string {
   if (width <= 0) return "";
@@ -268,21 +271,84 @@ export function scrollThumb(total: number, rows: number, start: number): { from:
   return { from, to: from + size };
 }
 
-/** Page buttons in the bottom border of a pane that scrolls: two pages up, one up, one down, two down. */
-export const PAGER = "▲▲ ▲ ▼ ▼▼";
-/** Columns the pager takes with a space on each side. */
-export const PAGER_WIDTH = PAGER.length + 2;
-/** Narrowest box that has room for the pager beside its corners. */
-const PAGER_MIN_WIDTH = PAGER_WIDTH + 6;
-
-/** Which page button a column of a scrollable pane's bottom border is: -2, -1, 1 or 2 pages (negative up), or undefined. */
-export function pagerButton(width: number, column: number): -2 | -1 | 1 | 2 | undefined {
-  if (width < PAGER_MIN_WIDTH) return undefined;
-  const from = column - width;
-  if (from >= -12 && from <= -10) return -2;
-  if (from >= -9 && from <= -7) return -1;
-  if (from >= -6 && from <= -5) return 1;
-  if (from >= -4 && from <= -2) return 2;
+/** Lines a page moves a pane: its rows less one, so a line of context carries over. */
+export function pageStep(rows: number): number {
+  return Math.max(1, rows - 1);
+}
+
+/** How many pages a pane showing `rows` lines at a time holds out of `total`. */
+export function pageCount(total: number, rows: number): number {
+  return total <= rows ? 1 : 1 + Math.ceil((total - rows) / pageStep(rows));
+}
+
+/**
+ * The page a pane showing lines from `start` is on, counted so that the top is
+ * page 1 and the bottom the last, and a page's worth of scrolling from either
+ * end lands exactly on the next number: a log that opens at its newest line
+ * and a detail that opens at its first both step through the same numbers.
+ */
+export function pageOf(total: number, rows: number, start: number): number {
+  const end = Math.max(0, total - rows);
+  const behind = Math.ceil(Math.max(0, end - Math.max(0, start)) / pageStep(rows));
+  return Math.max(1, pageCount(total, rows) - behind);
+}
+
+/** One piece of the pager: a button, where the pane is, or what sits between them. */
+export interface PagerPart {
+  text: string;
+  role: "up" | "down" | "where" | "between";
+}
+
+/** Fewest columns of border kept either side of the pager, beside its two spaces. */
+const PAGER_MARGIN = 3;
+
+/**
+ * The pager in a scrolling pane's bottom border, as words a newcomer can read:
+ * `▲ prev · page 2/5 · next ▼`, shortening to `▲ prev · 2/5 · next ▼` and
+ * `▲ 2/5 ▼` as the pane narrows, and to nothing when even that will not fit
+ * in `room` columns. The page number is padded to the width of the page count,
+ * so the buttons stay where they are as it changes and a click can be traced
+ * from the pane's size alone.
+ */
+export function pager(total: number, rows: number, start: number, room: number): PagerPart[] | undefined {
+  const pages = pageCount(total, rows);
+  const count = String(pages);
+  const of = `${String(pageOf(total, rows, start)).padStart(count.length)}/${pages}`;
+  const between = (text: string): PagerPart => ({ text, role: "between" });
+  const up = (text: string): PagerPart => ({ text, role: "up" });
+  const down = (text: string): PagerPart => ({ text, role: "down" });
+  const where = (text: string): PagerPart => ({ text, role: "where" });
+  const variants: PagerPart[][] = [
+    [up("▲ prev"), between(" · "), where(`page ${of}`), between(" · "), down("next ▼")],
+    [up("▲ prev"), between(" · "), where(of), between(" · "), down("next ▼")],
+    [up("▲"), between(" "), where(of), between(" "), down("▼")],
+  ];
+  return variants.find((parts) => parts.reduce((sum, part) => sum + textWidth(part.text), 0) <= room);
+}
+
+/** Columns a box of `width` leaves for the pager's text: two spaces around it and a margin of border on each side. */
+function pagerRoom(width: number): number {
+  return width - 2 - 2 - PAGER_MARGIN;
+}
+
+/**
+ * Which button a column of a scrollable pane's bottom border is: -1 (a page
+ * up) or 1 (a page down), or undefined. The buttons take their words and the
+ * space beside them, so a click a little off still lands.
+ */
+export function pagerButton(width: number, column: number, total: number, rows: number): -1 | 1 | undefined {
+  const parts = pager(total, rows, 0, pagerRoom(width));
+  if (!parts) return undefined;
+  const size = parts.reduce((sum, part) => sum + textWidth(part.text), 0);
+  // The text ends one space before the corner: `… next ▼ ╯`.
+  const origin = width - 2 - size;
+  let at = origin;
+  for (const part of parts) {
+    const from = part.role === "up" ? origin - 1 : at;
+    const to = part.role === "down" ? width - 1 : at + textWidth(part.text);
+    if (column >= from && column < to) return part.role === "up" ? -1 : part.role === "down" ? 1 : undefined;
+    at += textWidth(part.text);
+  }
   return undefined;
 }
 
@@ -309,9 +375,20 @@ export function box(width: number, height: number, content: readonly string[], o
   const thumb = options.scroll ? scrollThumb(options.scroll.total, height - 2, options.scroll.start) : undefined;
   const rightEdge = (row: number) => (thumb && row >= thumb.from && row < thumb.to ? paint(theme, focused ? "accent" : "muted", "┃") : edge("│"));
   const rows = fill(content, height - 2).map((line, row) => `${edge("│")} ${fit(line, inner)} ${rightEdge(row)}`);
-  // A pane with more lines than rows carries page buttons in its bottom border; `pagerButton` finds them again for clicks.
-  const pager = thumb && width >= PAGER_MIN_WIDTH ? ` ${PAGER} ` : "";
-  const bottom = `${edge("╰")}${edge("─".repeat(width - 2 - textWidth(pager)))}${pager ? paint(theme, focused ? "accent" : "muted", pager) : ""}${edge("╯")}`;
+  // A pane with more lines than rows carries a pager in its bottom border; `pagerButton` finds its buttons again for clicks.
+  const parts = thumb && options.scroll ? pager(options.scroll.total, height - 2, options.scroll.start, pagerRoom(width)) : undefined;
+  const atTop = (options.scroll?.start ?? 0) <= 0;
+  const atEnd = options.scroll ? options.scroll.start >= options.scroll.total - (height - 2) : true;
+  const paintPart = (part: PagerPart): string => {
+    if (part.role === "between") return paint(theme, "dim", part.text);
+    if (part.role === "where") return paint(theme, focused ? "text" : "muted", part.text);
+    // A button that cannot go further is dimmed: the pane is at that end.
+    if (part.role === "up" ? atTop : atEnd) return paint(theme, "dim", part.text);
+    return bold(theme, paint(theme, focused ? "accent" : "text", part.text));
+  };
+  const pagerText = parts ? ` ${parts.map(paintPart).join("")} ` : "";
+  const pagerWidth = parts ? parts.reduce((sum, part) => sum + textWidth(part.text), 0) + 2 : 0;
+  const bottom = `${edge("╰")}${edge("─".repeat(width - 2 - pagerWidth))}${pagerText}${edge("╯")}`;
   return [top, ...rows, bottom];
 }