@vincemakes/kiso-tui 0.8.0 → 0.10.0

package/dist/context-ledger.d.ts

@@ -0,0 +1,66 @@
+/**
+ * TUI2-R1 (E) — /context's attribution rows.
+ *
+ * The question "where did my context go?" has had an answer since E3:
+ * the trace sidecar's rent ledger records, per request, exactly what
+ * each static surface costs, and the context manifest records what the
+ * conversation costs. Until now that answer was only readable by
+ * someone willing to parse JSONL.
+ *
+ * This module is the presentation half and nothing else — a pure
+ * function from counts to rows, with no idea where the counts came
+ * from. That matters for the purity gate: the trace surface is an
+ * OBSERVATION surface (ADR-0051 §6), correctness never reads it, and
+ * keeping the reader in the CLI and the renderer here means this module
+ * cannot accidentally become a second correctness path.
+ *
+ * Every number is a count the ledger already carries. Nothing here
+ * estimates, projects, or predicts.
+ */
+/** The counts one request's ledger yields, already grouped by surface.
+ *  Estimated tokens throughout (the rent ledger's own chars/4 convention
+ *  — R6), because that is the unit the ledger records. */
+export interface ContextLedger {
+    /** The model's context window, as the session is configured. */
+    readonly window: number;
+    /** system:base + every system:ext:* append EXCEPT skills. */
+    readonly systemPrompt: number;
+    /** system:base alone — the detail behind the row. */
+    readonly systemBase: number;
+    /** how many extensions appended (the detail's count). */
+    readonly appends: number;
+    /** the sum of the tool:* lines. */
+    readonly toolTable: number;
+    readonly tools: number;
+    /** system:ext:skills — broken out because it is an INDEX of content
+     *  rather than an instruction, and it grows with the workspace rather
+     *  than with the build. 0 when the extension is not loaded. */
+    readonly skillsIndex: number;
+    /** how many skills the index lists — 0 when the caller cannot know
+     *  (the rent ledger records surfaces, never their contents). */
+    readonly skills: number;
+    /** the per-request skeleton (the `envelope` rent line). */
+    readonly envelope: number;
+    /** the context manifest's turn segments — the conversation itself. */
+    readonly messages: number;
+    readonly turns: number;
+}
+/**
+ * The rows: the header, the bar, one row per surface that EXISTS, and
+ * the free remainder.
+ *
+ * An absent surface is an absent row — the rent ledger's own R9 rule
+ * ("not paid = no rent"), carried into the display: a session with no
+ * skills extension should not read a "skills index 0" row, because the
+ * zero would look like a measurement rather than an absence.
+ *
+ * The columns are fixed so the numbers line up as a column of numbers;
+ * the detail text rides after them, dim, and is cut by the caller's
+ * width if it must be.
+ */
+export declare function contextRows(ledger: ContextLedger): string[];
+/** TUI2-R1 (E) — the honest fallback. The ledger is written PER REQUEST:
+ *  a session that has not called the model yet has no sidecar, and the
+ *  right thing to show is that fact and the one step that produces one.
+ *  Never an empty bar — an empty bar reads as "measured zero". */
+export declare function contextUnavailableRows(reason: string): string[];

package/dist/context-ledger.js

@@ -0,0 +1,87 @@
+/**
+ * TUI2-R1 (E) — /context's attribution rows.
+ *
+ * The question "where did my context go?" has had an answer since E3:
+ * the trace sidecar's rent ledger records, per request, exactly what
+ * each static surface costs, and the context manifest records what the
+ * conversation costs. Until now that answer was only readable by
+ * someone willing to parse JSONL.
+ *
+ * This module is the presentation half and nothing else — a pure
+ * function from counts to rows, with no idea where the counts came
+ * from. That matters for the purity gate: the trace surface is an
+ * OBSERVATION surface (ADR-0051 §6), correctness never reads it, and
+ * keeping the reader in the CLI and the renderer here means this module
+ * cannot accidentally become a second correctness path.
+ *
+ * Every number is a count the ledger already carries. Nothing here
+ * estimates, projects, or predicts.
+ */
+import { palette } from "./render.js";
+const BAR_CELLS = 12;
+/** k-units for the ledger's columns: 25700 → 25.7k, 300 → 300, 11 → 11.
+ *
+ *  TUI2-R1.5 ⑤ (VD-15): the floor was 100, which put `11`, `0.3k` and
+ *  `25.7k` in one right-aligned column — two unit systems stacked, and
+ *  the reader has to switch between them row by row to compare. The
+ *  repo already had a k-formatter with a 1000 floor (render.ts's kUnit,
+ *  which the status row and every settled card use); this now agrees
+ *  with it, so /context speaks the same number language as the rest of
+ *  the product. It still differs from kUnit in never having a null to
+ *  report — every ledger figure is a measured count. */
+function k(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k` : String(Math.round(n));
+}
+/**
+ * The rows: the header, the bar, one row per surface that EXISTS, and
+ * the free remainder.
+ *
+ * An absent surface is an absent row — the rent ledger's own R9 rule
+ * ("not paid = no rent"), carried into the display: a session with no
+ * skills extension should not read a "skills index 0" row, because the
+ * zero would look like a measurement rather than an absence.
+ *
+ * The columns are fixed so the numbers line up as a column of numbers;
+ * the detail text rides after them, dim, and is cut by the caller's
+ * width if it must be.
+ */
+export function contextRows(ledger) {
+    const p = palette();
+    const used = ledger.systemPrompt + ledger.toolTable + ledger.skillsIndex + ledger.envelope + ledger.messages;
+    const free = Math.max(0, ledger.window - used);
+    const ratio = ledger.window > 0 ? Math.min(1, used / ledger.window) : 1;
+    const filled = Math.max(0, Math.min(BAR_CELLS, Math.round(ratio * BAR_CELLS)));
+    const rows = [
+        `${p.bold}context — ${k(used)} / ${k(ledger.window)} tokens (${Math.round(ratio * 100)}%)${p.reset}`,
+        `${p.bold}${"▰".repeat(filled)}${p.reset}${p.dim}${"▱".repeat(BAR_CELLS - filled)}${p.reset}`,
+    ];
+    /** One surface row: the label at 14 columns, the count right-aligned
+     *  at 5, then the dim detail. */
+    const row = (label, value, detail) => `  ${p.bold}▰${p.reset} ${label.padEnd(14)}${p.bold}${k(value).padStart(5)}${p.reset}${detail === "" ? "" : `  ${p.dim}${detail}${p.reset}`}`;
+    if (ledger.systemPrompt > 0) {
+        rows.push(row("system prompt", ledger.systemPrompt, `(base ${k(ledger.systemBase)}${ledger.appends > 0 ? ` + ${ledger.appends} extension append${ledger.appends === 1 ? "" : "s"}` : ""})`));
+    }
+    if (ledger.toolTable > 0)
+        rows.push(row("tool table", ledger.toolTable, `${ledger.tools} tool${ledger.tools === 1 ? "" : "s"}`));
+    if (ledger.skillsIndex > 0) {
+        // the skill COUNT is not in the ledger (rent records surfaces, not
+        // their contents) — a caller that knows it passes it, and a caller
+        // that does not gets the honest half of the sentence rather than a
+        // fabricated number.
+        rows.push(row("skills index", ledger.skillsIndex, `${ledger.skills > 0 ? `${ledger.skills} skill${ledger.skills === 1 ? "" : "s"}, ` : ""}tier-1 lines only`));
+    }
+    if (ledger.envelope > 0)
+        rows.push(row("envelope", ledger.envelope, ""));
+    if (ledger.messages > 0)
+        rows.push(row("messages", ledger.messages, `${ledger.turns} turn${ledger.turns === 1 ? "" : "s"}`));
+    rows.push(`  ${p.dim}▱ ${"free".padEnd(14)}${k(free).padStart(5)}${p.reset}`);
+    return rows;
+}
+/** TUI2-R1 (E) — the honest fallback. The ledger is written PER REQUEST:
+ *  a session that has not called the model yet has no sidecar, and the
+ *  right thing to show is that fact and the one step that produces one.
+ *  Never an empty bar — an empty bar reads as "measured zero". */
+export function contextUnavailableRows(reason) {
+    const p = palette();
+    return [`${p.bold}context — no ledger yet${p.reset}`, `  ${p.dim}${reason}${p.reset}`];
+}

package/dist/editor.d.ts

@@ -23,8 +23,9 @@
  */
 import { charWidth, displayWidth, widthOf } from "./width.js";
 export { charWidth, displayWidth, widthOf };
-import type { PanelState, PanelVerdict, PanelView } from "./approval-panel.js";
+import { type PanelState, type PanelVerdict, type PanelView } from "./approval-panel.js";
 import { type AtItem, type AtMatch } from "./at-picker.js";
+import { type SessionCardView, type SessionPickState } from "./session-picker.js";
 export declare const PROMPT = "\u258C ";
 export declare const PROMPT_WIDTH: number;
 /** v3 §04 — the slash-command menu's command table (English one-liners). */
@@ -60,6 +61,9 @@ export declare class Editor {
     bindQueue(state: () => readonly string[], pop: () => string | null): void;
     /** The whole buffer as text (the CLI's line()/clearLine()). */
     line(): string;
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen(): boolean;
     clearLine(): void;
     /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
      *  their legacy meaning (the CURSOR LINE's visible slice and the
@@ -98,6 +102,12 @@ export declare class Editor {
         selected: number;
         capped: boolean;
     } | null;
+    /** Open the picker on a bound card source. The composer is cleared
+     *  (the buffer becomes the filter query) and `onPick` receives the
+     *  chosen id — or null when the human leaves without picking, which
+     *  is a first-class outcome and not an error. */
+    beginPick(cards: () => readonly SessionCardView[], onPick: (id: string | null) => void): void;
+    pickState(): SessionPickState | null;
     /** One-shot question mode: the NEXT submit answers, not a turn. */
     question(_query: string, cb: (answer: string) => void): void;
     /** Cancel a pending question — the buffer stays (its text becomes the

package/dist/editor.js

@@ -26,10 +26,15 @@ import { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 // authority) — re-exported so the editor's public surface is unchanged.
 export { charWidth, displayWidth, widthOf };
 import { palette } from "./render.js";
+import { PICK_MAX } from "./approval-panel.js";
 // KC3.5: the panel-slot dispatchers — the ask branch folded into the
 // W21 lead/rows, so this file keeps ONE panel and one key owner.
 import { askCommitCustom, askKey, askStart, panelLead } from "./ask-panel.js";
 import { AT_VISIBLE, atFilter } from "./at-picker.js";
+// TUI2-R2 ②: the session picker — the band's THIRD occupant. Its filter
+// is the @ picker's rank aimed at the session id; the editor owns the
+// keys, the compositor draws the rows.
+import { sessionFilter } from "./session-picker.js";
 // TUI v4 #16d: the input row is the blue brick + the edit area — the
 // "you>" text is gone (the brick IS the prompt; the pipe path's readline
 // prompt keeps its own "you> " — v2a line mode, byte-for-byte).
@@ -42,6 +47,8 @@ export const MENU_ITEMS = [
     { name: "/think", desc: "show the last full thinking block" },
     { name: "/last", desc: "show the most recent tool call's input and output" },
     { name: "/status", desc: "show session id, event count, and context estimate" },
+    // TUI2-R1 (E): the rent-ledger attribution — where the context went
+    { name: "/context", desc: "show where the context went — the last request's rent ledger" },
     { name: "/help", desc: "print this list of commands" },
 ];
 /** KC1 §3 — the newline code point. Every source (paste, Ctrl+J, the
@@ -109,6 +116,12 @@ export class Editor {
     // coexist; the editor never interprets the key itself.
     #expandCbs = [];
     #onRender;
+    /** TUI2-R1 (D): the keys sheet — a static one-screen overlay opened by
+     *  `?` on an empty composer and closed by the next key, whatever it
+     *  is. Deliberately a BOOLEAN and not a panel: the panel machinery
+     *  exists for interactions (a lead, a status, a reducer, a stashed
+     *  buffer), and the sheet has no interaction to speak of. */
+    #sheetOpen = false;
     #menuOpen = false; // v3 §04: the slash-command menu
     #menuSel = 0;
     // KC3 §3 — the @ file picker. THREE fields and no more: the armed
@@ -127,6 +140,20 @@ export class Editor {
     // next open re-snapshots, so a stale list can never be shown.
     #atList = null;
     #atItems = null;
+    // TUI2-R2 ② — the session picker. Two fields: the bound source (its
+    // presence IS "the picker is up") and the selection. The query, like
+    // the @ picker's, is DERIVED from the buffer on every read rather
+    // than stored — so every existing buffer op (backspace, the kills,
+    // paste) filters correctly with no handler of its own.
+    //
+    // The picker is MODAL in a way the @ picker is not: it opens before
+    // a session exists, owns the whole composer, and the only ways out
+    // are a pick and an esc. That is why the commit callback lives here
+    // rather than on the line channel — the caller is waiting for an id,
+    // not for a turn.
+    #pickCards = null;
+    #pickCommit = null;
+    #pickSel = 0;
     // A2 (the feel): the session-scoped input history — every submitted TURN
     // line (never a question answer), capped at 100, never persisted. ↑↓
     // navigate it ONLY from an empty input or while already browsing.
@@ -194,6 +221,11 @@ export class Editor {
     line() {
         return String.fromCodePoint(...this.#chars);
     }
+    /** TUI2-R1 (D): whether the keys sheet is up — the compositor's slot
+     *  read (bound like the menu and the picker). */
+    sheetOpen() {
+        return this.#sheetOpen;
+    }
     clearLine() {
         this.#chars = [];
         this.#cursor = 0;
@@ -241,7 +273,7 @@ export class Editor {
      *  the frame's clamp is the authority. */
     #visibleRows(lineCount) {
         const H = process.stdout.rows ?? 24;
-        const bands = (this.#menuOpen ? this.#menuFiltered().length : 0) + this.#atRows() + this.#queueState().length;
+        const bands = (this.#menuOpen ? this.#menuFiltered().length : 0) + this.#atRows() + this.#pickRows() + this.#queueState().length;
         return Math.max(1, Math.min(lineCount, N_MAX, Math.max(1, H - 3 - bands)));
     }
     /** The dock's input-row state — ADDITIVE (§5): `line` + `cursor` keep
@@ -379,6 +411,11 @@ export class Editor {
     #atArm() {
         if (this.#atItems === null)
             return;
+        // TUI2-R2 ②: not inside a session filter. An `@` typed into the
+        // picker's query is a character in a session id, and a file picker
+        // opening over a session picker would put two bands in one slot.
+        if (this.#pickUp())
+            return;
         if (this.#panel !== null || this.#menuOpen || this.#questionCb !== null)
             return;
         if (this.#atToken() === null)
@@ -424,6 +461,71 @@ export class Editor {
         const view = this.#atView();
         return view === null ? 0 : Math.min(view.matches.length, AT_VISIBLE) + 1;
     }
+    // ── TUI2-R2 ② — the session picker ───────────────────────────────
+    /** Open the picker on a bound card source. The composer is cleared
+     *  (the buffer becomes the filter query) and `onPick` receives the
+     *  chosen id — or null when the human leaves without picking, which
+     *  is a first-class outcome and not an error. */
+    beginPick(cards, onPick) {
+        this.#pickCards = cards;
+        this.#pickCommit = onPick;
+        this.#pickSel = 0;
+        this.#chars = [];
+        this.#cursor = 0;
+        this.#reflow();
+        this.#onRender();
+    }
+    /** The picker's state, derived: the full card list (the id column
+     *  measures over ALL of them, so the columns never jump), the
+     *  filtered matches, and the selection CLAMPED at read time — the
+     *  same correction discipline the @ picker uses, for the same
+     *  reason: narrowing can only ever shrink the list. */
+    #pickView() {
+        if (this.#pickCards === null)
+            return null;
+        const cards = this.#pickCards();
+        const matches = sessionFilter(cards, this.line());
+        return { cards, matches, selected: Math.max(0, Math.min(this.#pickSel, matches.length - 1)) };
+    }
+    pickState() {
+        return this.#pickView();
+    }
+    #pickUp() {
+        return this.#pickCards !== null;
+    }
+    /** The band's height estimate: the header + the windowed rows (or
+     *  the one "no match" row) + the counter. */
+    #pickRows() {
+        const view = this.#pickView();
+        return view === null ? 0 : Math.min(Math.max(view.matches.length, 1), AT_VISIBLE) + 2;
+    }
+    /** Close and hand the verdict back. The callback fires AFTER the
+     *  state is cleared, so a caller that re-enters (a second picker, a
+     *  session that starts) never sees the closing picker's rows. */
+    #pickClose(id) {
+        const cb = this.#pickCommit;
+        this.#pickCards = null;
+        this.#pickCommit = null;
+        this.#pickSel = 0;
+        this.#chars = [];
+        this.#cursor = 0;
+        this.#reflow();
+        cb?.(id);
+        this.#onRender();
+    }
+    /** Enter takes the SELECTED session. An empty match set takes
+     *  nothing and leaves the picker up: a picker that invented a pick
+     *  when the query matched nothing would resume the wrong session,
+     *  which is the one failure this surface must never have. */
+    #pickAccept() {
+        const view = this.#pickView();
+        if (view === null)
+            return;
+        const card = view.matches[view.selected];
+        if (card === undefined)
+            return;
+        this.#pickClose(card.id);
+    }
     /** One-shot question mode: the NEXT submit answers, not a turn. */
     question(_query, cb) {
         this.#questionCb = cb;
@@ -442,6 +544,9 @@ export class Editor {
             phase: "options",
             sel: 0,
             ask: view.ask === undefined ? null : askStart(view.ask),
+            // TUI2-R2 ④: the pick's walk — present exactly when the view is
+            // a pick, the same contract the ask's runtime has.
+            pick: view.pick === undefined ? null : { cursor: 0, phase: "options" },
             amend: "yes",
             onCommit,
             stash: { chars: this.#chars, cursor: this.#cursor, scroll: this.#scroll },
@@ -466,7 +571,13 @@ export class Editor {
         const panel = this.#panel;
         if (panel === null)
             return null;
-        return { view: panel.view, phase: panel.phase, sel: panel.sel, ...(panel.ask === null ? {} : { ask: panel.ask }) };
+        return {
+            view: panel.view,
+            phase: panel.phase,
+            sel: panel.sel,
+            ...(panel.ask === null ? {} : { ask: panel.ask }),
+            ...(panel.pick === null ? {} : { pick: panel.pick }),
+        };
     }
     enter() {
         if (this.#entered)
@@ -510,6 +621,17 @@ export class Editor {
     feed(raw) {
         const text = this.#pending + this.#decoder.decode(raw, { stream: true });
         this.#pending = "";
+        // TUI2-R1 (D): the sheet is up — ANY key closes it, and the key
+        // that closed it is CONSUMED. The whole chunk goes, deliberately:
+        // an arrow key is three bytes, and closing on the first while
+        // letting `[A` fall through as literal text would be a sheet that
+        // types into your composer on the way out. A dismissal costs one
+        // keystroke; that is the entire contract.
+        if (this.#sheetOpen) {
+            this.#sheetOpen = false;
+            this.#onRender();
+            return;
+        }
         let i = 0;
         while (i < text.length) {
             const c = text[i];
@@ -530,6 +652,44 @@ export class Editor {
                 // only esc and enter are intercepted while typing), esc
                 // declines the whole call. Everything else falls through to
                 // the ordinary editing chain below.
+                // TUI2-R2 ④: a PICK panel routes its own keys — a digit moves
+                // the cursor to that option (never commits: the choice is
+                // CONFIRMED, so a mistyped digit is a mistake you can see
+                // before it takes effect), `t` opens the type-it line, enter
+                // commits, esc backs out then cancels. The swallow rule below
+                // is the ask's, for the ask's reason: a typed `/` must not arm
+                // the menu under a panel that owns the keys.
+                if (panel.pick !== null) {
+                    const typing = panel.pick.phase === "custom";
+                    if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
+                        this.#pickPanelEsc();
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "\x0d" || c === "\x0a") {
+                        this.#pickPanelEnter();
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && c !== undefined && c >= "1" && c <= "9") {
+                        this.#pickPanelDigit(Number(c) - 1);
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && (c === "t" || c === "T")) {
+                        panel.pick = { cursor: panel.pick.cursor, phase: "custom" };
+                        this.#chars = [];
+                        this.#cursor = 0;
+                        this.#scroll = 0;
+                        this.#onRender();
+                        i += 1;
+                        continue;
+                    }
+                    if (!typing && c !== undefined && c >= " " && c !== "\x7f") {
+                        i += 1;
+                        continue;
+                    }
+                }
                 if (panel.ask !== null) {
                     const typing = panel.ask.phase === "custom";
                     if (c === "\x1b" && !text.slice(i + 1).startsWith("[") && !text.slice(i + 1).startsWith("O")) {
@@ -578,22 +738,49 @@ export class Editor {
                     i += 1;
                     continue;
                 }
-                if (c === "1" || c === "y" || c === "Y") {
-                    if (panel.phase === "options")
+                // TUI2-R2 ⑧ — the shortcut keys belong to the OPTIONS phase and
+                // to it alone.
+                //
+                // `1`/`y` select yes and `3`/`n` select no, and they used to be
+                // applied in every phase of every flavour: the `i += 1;
+                // continue;` sat OUTSIDE the phase check, so a phase where the
+                // key meant nothing swallowed it anyway. A phase where a letter
+                // means nothing is exactly a phase where a human is typing
+                // prose — so every y, n, 1 and 3 vanished from the line,
+                // silently, with no error and no visible cause. "yes, run it
+                // now 13" committed as "es, ru it ow ".
+                //
+                // Three typed phases were affected: the ask's custom answer,
+                // the approval panel's rule input, and its amend/feedback line.
+                // The rule input is the one that mattered most — it writes a
+                // DURABLE don't-ask-again rule, so a dropped character persists
+                // a rule the human never typed.
+                //
+                // Slice ④ met the same mechanism on the new pick panel
+                // ("openai/deepseek-reasoner" -> "opeai/deepseek-reasoer") and
+                // guarded pick alone, because the rest was a behaviour change
+                // owed its own red. This is that guard, stated once for every
+                // flavour: the options phase keeps its keys, and every typed
+                // phase keeps its text.
+                const optionsPhase = panel.pick === null && // a pick has no yes and no no
+                    panel.phase === "options" && // the rule / amend lines are prose
+                    (panel.ask === null || panel.ask.phase === "options"); // and so is a typed ask answer
+                if (optionsPhase) {
+                    if (c === "1" || c === "y" || c === "Y") {
                         this.#panelSelect(1);
-                    i += 1;
-                    continue;
-                }
-                if (c === "2" && panel.phase === "options" && panel.view.flavor === "approval") {
-                    this.#panelRule();
-                    i += 1;
-                    continue;
-                }
-                if (c === "3" || c === "n" || c === "N") {
-                    if (panel.phase === "options")
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "2" && panel.view.flavor === "approval") {
+                        this.#panelRule();
+                        i += 1;
+                        continue;
+                    }
+                    if (c === "3" || c === "n" || c === "N") {
                         this.#panelSelect(3);
-                    i += 1;
-                    continue;
+                        i += 1;
+                        continue;
+                    }
                 }
             }
             if (c === "\x1b") {
@@ -632,6 +819,15 @@ export class Editor {
                     this.#refreshMenu();
                     i += 1;
                 }
+                else if (this.#pickUp()) {
+                    // TUI2-R2 ②: esc leaves the picker with nothing picked.
+                    // The caller reads null and exits 0 — declining to resume
+                    // is a normal thing to do, not a failure, so it must not
+                    // fall through to the escapeCbs (which mean "abort the
+                    // run" and there is no run yet).
+                    this.#pickClose(null);
+                    i += 1;
+                }
                 else if (this.#atUp()) {
                     // KC3 §3: esc closes the picker and leaves the BUFFER
                     // ALONE — unlike the menu's esc, which clears it. The
@@ -752,6 +948,17 @@ export class Editor {
                     cb();
                 i += 1;
             }
+            else if (c === "?" && this.#composerIdle() && this.#chars.length === 0) {
+                // TUI2-R1 (D): `?` opens the keys sheet — but ONLY on an
+                // empty composer with nobody else holding the keys. Mid-text
+                // it is the question mark a human is typing, and #composerIdle
+                // already encodes "no panel, no menu, no picker, no browse".
+                // The precedence can only ever ADD: every state that used to
+                // insert a `?` still inserts one.
+                this.#sheetOpen = true;
+                this.#onRender();
+                i += 1;
+            }
             else if (c !== undefined && c < " ") {
                 i += 1; // other control — ignored
             }
@@ -804,9 +1011,25 @@ export class Editor {
             if (this.#panel !== null) {
                 // W21: the panel owns the keys. KC3.5: an ask uses ↑↓ for
                 // the option cursor (the approval panel still has no ↑↓ role).
-                if (this.#panel.ask !== null && this.#panel.ask.phase === "options")
+                if (this.#panel.pick !== null && this.#panel.pick.phase === "options") {
+                    // TUI2-R2 ④: ↑↓ walk the pick's cursor — the same list the
+                    // digits address, the other muscle.
+                    const n = Math.min(this.#panel.view.pick.options.length, PICK_MAX);
+                    const cur = this.#panel.pick.cursor;
+                    this.#panel.pick = { cursor: final === "A" ? Math.max(0, cur - 1) : Math.min(Math.max(0, n - 1), cur + 1), phase: "options" };
+                }
+                else if (this.#panel.ask !== null && this.#panel.ask.phase === "options")
                     this.#askStep(final === "A" ? "up" : "down");
             }
+            else if (this.#pickUp()) {
+                // TUI2-R2 ②: the session picker owns ↑↓ while up — the
+                // SELECTION, never the composer's line walk and never the
+                // history browse. It sits above both because the picker is
+                // modal: there is no turn to recall and no second line to
+                // walk to while it is open.
+                const view = this.#pickView();
+                this.#pickSel = final === "A" ? Math.max(0, view.selected - 1) : Math.min(Math.max(0, view.matches.length - 1), view.selected + 1);
+            }
             else if (this.#menuOpen) {
                 if (final === "A")
                     this.#menuSel = Math.max(0, this.#menuSel - 1);
@@ -990,6 +1213,60 @@ export class Editor {
         }
         this.#onRender();
     }
+    /**
+     * TUI2-R2 ④ — the pick panel's three keys.
+     *
+     * A digit MOVES the cursor rather than committing. The list is short
+     * and the digits are adjacent on the keyboard; a picker that acted on
+     * the keypress would make a mistyped 3 a model switch, and the whole
+     * point of a confirm step is that the choice is visible before it is
+     * taken.
+     */
+    #pickPanelDigit(index) {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        // a digit past the list is INERT — an option nobody has is never
+        // selected, and the cursor stays where the human left it
+        if (index < 0 || index >= Math.min(panel.view.pick.options.length, PICK_MAX))
+            return;
+        panel.pick = { cursor: index, phase: "options" };
+        this.#onRender();
+    }
+    /** enter — the typed line when there is one (an EMPTY line is not a
+     *  choice and commits nothing), else the option under the cursor. */
+    #pickPanelEnter() {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        if (panel.pick.phase === "custom") {
+            const line = this.line().trim();
+            if (line === "")
+                return;
+            this.#panelClose({ action: "picked", result: { custom: line } });
+            return;
+        }
+        if (panel.view.pick.options.length === 0)
+            return; // nothing to take
+        this.#panelClose({ action: "picked", result: { index: panel.pick.cursor } });
+    }
+    /** esc — back out of the type-it line first, then cancel the panel.
+     *  Two escapes, two meanings, exactly as the approval panel's
+     *  rule/amend phases already work. */
+    #pickPanelEsc() {
+        const panel = this.#panel;
+        if (panel === null || panel.pick === null)
+            return;
+        if (panel.pick.phase === "custom") {
+            panel.pick = { cursor: panel.pick.cursor, phase: "options" };
+            this.#chars = [];
+            this.#cursor = 0;
+            this.#scroll = 0;
+            this.#onRender();
+            return;
+        }
+        this.#panelClose({ action: "cancel" });
+    }
     #panelClose(verdict) {
         const panel = this.#panel;
         if (panel === null)
@@ -1113,6 +1390,7 @@ export class Editor {
         return (this.#panel === null &&
             !this.#menuOpen &&
             !this.#atUp() && // KC3 §3: the @ picker owns the keys while up, exactly like the menu
+            !this.#pickUp() && // TUI2-R2 ②: and so does the session picker — `?` is a query character there
             this.#historyIdx === null &&
             !this.#queuePopMode &&
             !this.#pasting &&
@@ -1145,6 +1423,12 @@ export class Editor {
         this.#onRender();
     }
     #submit() {
+        // TUI2-R2 ②: the session picker takes Enter before anything else —
+        // while it is up there is no turn to submit and no line to send.
+        if (this.#pickUp()) {
+            this.#pickAccept();
+            return;
+        }
         // KC3 §3: Enter ACCEPTS while the picker is up — the same rule the
         // menu's A1 feel established (complete first, let the user read
         // what they got, and let the NEXT Enter send it). An @ reference

package/dist/index.d.ts

@@ -6,13 +6,15 @@
  * editor, the diff renderer, and the palette.
  */
 export { Body, Dock, CURSOR_MARKER, type BodyOptions } from "./compositor.js";
-export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, type PanelArgs, type PanelFlavor, type PanelPhase, type PanelSel, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.js";
-export { Container, foldLine, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
+export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, PICK_MAX, modelPickView, pickAffordance, pickBlockRows, pickLeadPlain, type PickOption, type PickResult, type PickRuntime, type PickSpec, type PanelArgs, type PanelFlavor, type PanelPhase, type PanelSel, type PanelState, type PanelVerdict, type PanelView, } from "./approval-panel.js";
+export { Container, foldLine, foldWords, visibleWidth, SPINNER, type Component, type FrameCtx } from "./components.js";
 export { Editor, MENU_ITEMS, PROMPT, PROMPT_WIDTH, displayWidth, charWidth, widthOf, type MenuItem, } from "./editor.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, escapeTerminal, foldResult, foldThinking, kUnit, palette, renderEvent, renderRecap, renderResumeList, renderSessionLine, renderStatusLine, relativeTime, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type PathResolver, type RecapStats, type ResumeMeta, type RenderInput, type RenderResult, type RunUsage, } from "./render.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
-export { STATUS_GLYPHS, idleStatus, runningStatus } from "./status.js";
+export { STATUS_GLYPHS, cacheHitPct, idleStatus, runningStatus, type StatusMeter } from "./status.js";
+export { contextRows, contextUnavailableRows, type ContextLedger } from "./context-ledger.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact } from "./strings.js";
-export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, longestRun, type AtItem, type AtMatch } from "./at-picker.js";
+export { AT_CAP, AT_SKIP, AT_VISIBLE, atEmbed, atFilter, atPanelRows, atWindow, bandHeader, longestRun, type AtItem, type AtMatch } from "./at-picker.js";
+export { BADGE_GLYPH, idColumn, sessionAge, sessionBadge, sessionCounterRow, sessionFilter, sessionListFooter, sessionListRow, sessionNote, sessionPickerRows, sessionRow, type SessionCardView, type SessionPickState, } from "./session-picker.js";
 export { ASK_HEADER_CAP, ASK_MAX_OPTIONS, ASK_MAX_QUESTIONS, ASK_MIN_OPTIONS, askAffordance, askAnswers, askBlockRows, askCommitCustom, askDeclineAll, askDeclineList, askKey, askLeadPlain, askStart, askStatus, askView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type AskStep, } from "./ask-panel.js";
-export { extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
+export { KEY_BINDINGS, PANEL_KEYS_ROW, displayVerb, extensionsBannerText, helpRows, keysHelpRow, keysSheetRows, unansweredAskView, type BannerExtension, type KeyBinding } from "./strings.js";