@vincemakes/kiso-tui 0.9.0 → 0.10.0

package/dist/ask-panel.d.ts

@@ -27,7 +27,7 @@
  * durability would need a new durable mechanism), no "chat about this"
  * hand-off, no timeout and no countdown.
  */
-import { type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type PanelPhase, type PanelSel, type PanelState, type PanelView } from "./approval-panel.js";
+import { type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, type PanelPhase, type PanelSel, type PanelState, type PanelView, type PickRuntime } from "./approval-panel.js";
 /** The schema's own bounds — the registry refuses anything outside them
  *  (extensions/ask validates; these are the numbers it validates to). */
 export declare const ASK_MAX_QUESTIONS = 4;
@@ -77,13 +77,14 @@ export declare function askStatus(view: PanelView, state: AskRuntime): string;
 /** The input row's lead: the digit lead while picking, the typing lead
  *  in the custom phase (the rule-input phase's shape, reused). */
 export declare function askLeadPlain(state: AskRuntime): string;
-export declare function panelBlockRows(view: PanelView, phase: PanelPhase, sel: PanelSel, W: number, maxRows: number, ask?: AskRuntime): string[];
-export declare function panelLead(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
-export declare function panelLeadPlain(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
-export declare function panelStatus(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
-export declare function panelAffordance(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime): string;
+export declare function panelBlockRows(view: PanelView, phase: PanelPhase, sel: PanelSel, W: number, maxRows: number, ask?: AskRuntime, pick?: PickRuntime): string[];
+export declare function panelLead(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime, pick?: PickRuntime): string;
+export declare function panelLeadPlain(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime, pick?: PickRuntime): string;
+export declare function panelStatus(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime, pick?: PickRuntime): string;
+export declare function panelAffordance(view: PanelView, phase: PanelPhase, sel: PanelSel, ask?: AskRuntime, pick?: PickRuntime): string;
 /** The whole panel state in one call — the compositor's four reads share
- *  one source, so an ask can never render half as an approval. */
+ *  one source, so an ask can never render half as an approval (TUI2-R2
+ *  ④: nor a pick as either). */
 export declare const panelRowsOf: (s: PanelState, W: number, maxRows: number) => string[];
 export declare const panelLeadOf: (s: PanelState) => string;
 export declare const panelStatusOf: (s: PanelState) => string;

package/dist/ask-panel.js

@@ -27,7 +27,7 @@
  * durability would need a new durable mechanism), no "chat about this"
  * hand-off, no timeout and no countdown.
  */
-import { panelAffordance as basePanelAffordance, panelBlockRows as basePanelBlockRows, panelLead as basePanelLead, panelLeadPlain as basePanelLeadPlain, panelStatus as basePanelStatus, } from "./approval-panel.js";
+import { panelAffordance as basePanelAffordance, panelBlockRows as basePanelBlockRows, panelLead as basePanelLead, panelLeadPlain as basePanelLeadPlain, panelStatus as basePanelStatus, pickAffordance, pickBlockRows, pickLead, pickLeadPlain, pickStatus, } from "./approval-panel.js";
 import { cutLine } from "@vincemakes/kiso-tui-cells/components";
 import { escapeTerminal, palette } from "./render.js";
 /** The schema's own bounds — the registry refuses anything outside them
@@ -225,38 +225,49 @@ export function askLeadPlain(state) {
     return state.phase === "custom" ? "your answer: " : "1-4> ";
 }
 // ── the dispatchers: the panel slot, with the ask branch folded in ────
-export function panelBlockRows(view, phase, sel, W, maxRows, ask) {
+export function panelBlockRows(view, phase, sel, W, maxRows, ask, pick) {
+    if (view.pick !== undefined && pick !== undefined)
+        return pickBlockRows(view, pick, W, maxRows);
     if (view.ask !== undefined && ask !== undefined)
         return askBlockRows(view, ask, W, maxRows);
     return basePanelBlockRows(view, phase, sel, W, maxRows);
 }
-export function panelLead(view, phase, sel, ask) {
+export function panelLead(view, phase, sel, ask, pick) {
     const p = palette();
+    if (view.pick !== undefined && pick !== undefined)
+        return pickLead(view, pick);
     if (view.ask !== undefined && ask !== undefined)
         return `${p.bold}${askLeadPlain(ask)}${p.reset}`;
     return basePanelLead(view, phase, sel);
 }
-export function panelLeadPlain(view, phase, sel, ask) {
+export function panelLeadPlain(view, phase, sel, ask, pick) {
+    if (view.pick !== undefined && pick !== undefined)
+        return pickLeadPlain(view, pick);
     if (view.ask !== undefined && ask !== undefined)
         return askLeadPlain(ask);
     return basePanelLeadPlain(view, phase, sel);
 }
-export function panelStatus(view, phase, sel, ask) {
+export function panelStatus(view, phase, sel, ask, pick) {
+    if (view.pick !== undefined && pick !== undefined)
+        return pickStatus(view);
     if (view.ask !== undefined && ask !== undefined)
         return askStatus(view, ask);
     return basePanelStatus(view, phase, sel);
 }
-export function panelAffordance(view, phase, sel, ask) {
+export function panelAffordance(view, phase, sel, ask, pick) {
+    if (view.pick !== undefined && pick !== undefined)
+        return pickAffordance(pick);
     if (view.ask !== undefined && ask !== undefined)
         return askAffordance(ask);
     return basePanelAffordance(view, phase, sel);
 }
 /** The whole panel state in one call — the compositor's four reads share
- *  one source, so an ask can never render half as an approval. */
-export const panelRowsOf = (s, W, maxRows) => panelBlockRows(s.view, s.phase, s.sel, W, maxRows, s.ask);
-export const panelLeadOf = (s) => panelLead(s.view, s.phase, s.sel, s.ask);
-export const panelStatusOf = (s) => panelStatus(s.view, s.phase, s.sel, s.ask);
-export const panelAffordanceOf = (s) => panelAffordance(s.view, s.phase, s.sel, s.ask);
+ *  one source, so an ask can never render half as an approval (TUI2-R2
+ *  ④: nor a pick as either). */
+export const panelRowsOf = (s, W, maxRows) => panelBlockRows(s.view, s.phase, s.sel, W, maxRows, s.ask, s.pick);
+export const panelLeadOf = (s) => panelLead(s.view, s.phase, s.sel, s.ask, s.pick);
+export const panelStatusOf = (s) => panelStatus(s.view, s.phase, s.sel, s.ask, s.pick);
+export const panelAffordanceOf = (s) => panelAffordance(s.view, s.phase, s.sel, s.ask, s.pick);
 // ── the view: what the human reads when the model asks ────────────────
 /** The ask's PanelView. The dock-less fallback question is HONEST: a
  *  terminal without a panel cannot walk options, so it says the ask is

package/dist/compositor.d.ts

@@ -45,6 +45,7 @@
 import { type MenuItem } from "./editor.js";
 import type { PanelState } from "./approval-panel.js";
 import { type AtMatch } from "./at-picker.js";
+import { type SessionPickState } from "./session-picker.js";
 /** KC3 §4 — the @ picker's bound state (the editor's atState()). */
 export interface AtPanelState {
     readonly matches: readonly AtMatch[];
@@ -178,15 +179,6 @@ export declare class Body {
             isError: boolean;
         };
     } | null;
-    /** W15 — the expand key's target (ctrl+r). A cell still in the LIVE
-     *  region (the newest live tool) TOGGLES in place — the compositor
-     *  owns those rows and redraws them (the body flips to the full
-     *  form, no cap). A committed cell can never toggle — history is
-     *  never rewritten (ADR-0046) — so the key APPENDS a fresh expanded
-     *  block at the bottom instead, the /last idiom aimed at a chosen
-     *  cell: the pointer cycles the collapsed history, newest first, and
-     *  the header names the target ("N turns back" — the user cells
-     *  after it), so every press tells the user what they got. */
     expandNext(): {
         kind: "toggled";
     } | {
@@ -232,6 +224,9 @@ export declare class Body {
      *  band — see #menuRows for why that is a decision and not a
      *  shortcut. */
     bindAt(state: () => AtPanelState | null): void;
+    /** TUI2-R2 ②: bind the editor's session picker — the band's third
+     *  occupant (see #menuRows for why they share one). */
+    bindPick(state: () => SessionPickState | null): void;
     /** Bind the pending-turn queue — the CLI's live slots (chat.ts):
      *  the chips render in the menu-rows family, the live caps shrink
      *  by their rows, and the +N queued hint rides the status row. */
@@ -280,6 +275,10 @@ export declare class Dock {
      *  menu (see Body#menuRows). Unbound, the picker cannot render, and
      *  every frame is byte-identical to before the round. */
     bindAt(state: () => AtPanelState | null): void;
+    /** TUI2-R2 ②: bind the editor's session picker — the band's third
+     *  occupant. Unbound (every path but bare `kiso resume`), the picker
+     *  cannot render and every frame is byte-identical to before. */
+    bindPick(state: () => SessionPickState | null): void;
     /** W22: bind the pending-turn queue — the chips + the +N queued
      *  hint (the CLI binds it from chat(); the editor's pop keys ride
      *  the LineInput's own bindQueue). */

package/dist/compositor.js

@@ -49,9 +49,11 @@ import { leadWidth } from "./width.js"; // W23: the ONE width authority (the edi
 // for four reads, so an ask can never render half as an approval.
 import { panelAffordanceOf, panelLeadOf, panelRowsOf, panelStatusOf } from "./ask-panel.js";
 import { atPanelRows, bandHeader } from "./at-picker.js";
-import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, exploreRows, foldLine, isExploreTool, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
+// TUI2-R2 ②: the session picker's rows — the band's third occupant.
+import { sessionPickerRows } from "./session-picker.js";
+import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, exploreCounts, focusToken, exploreRows, foldLine, isExploreTool, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
 import { bannerLines, escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, toolTarget } from "./render.js";
-import { keysSheetRows } from "./strings.js";
+import { displayVerb, keysSheetRows } from "./strings.js";
 /** The cursor marker — an APC private sequence the focus component
  *  embeds at the edit position; the compositor strips it and moves
  *  relatively (it never reaches the terminal). */
@@ -134,6 +136,9 @@ export class Body {
     // KC3 §4: the @ picker's bound state — the SAME band as the menu
     // (see #menuRows: the two are mutually exclusive by construction).
     #atState = null;
+    // TUI2-R2 ②: the session picker's bound state — the same band again
+    // (see #menuRows), and modal, so it takes the band first.
+    #pickState = null;
     // W22: the pending-turn queue's bound state — the CLI's live slots
     // (chat.ts); the chips render in the menu-rows family (above the
     // box top), the live caps shrink by their rows, and the status
@@ -146,6 +151,16 @@ export class Body {
         // v6: the single writer — the compositor IS the dock; the CLI's
         // onDock callback (which used to re-pin the dock after a scroll)
         // is retired with the split.
+        // TUI2-R2pre ③: taking the ref SUPERSEDES whatever held it, so the
+        // outgoing compositor's resize listener comes off here. It is not
+        // only listener hygiene: every Dock call now reaches THIS instance,
+        // so a resize heard by the old one would have a compositor that owns
+        // no part of the screen paint a full redraw over it.
+        // (an explicit null check, not `?.#` — TS18030: an optional chain
+        // cannot contain a private identifier, and vitest transpiles without
+        // type-checking, so only `npm run typecheck` sees the difference)
+        if (compositorRef !== null)
+            compositorRef.#detachResize();
         compositorRef = this;
         // the Dock façade's bindings may arrive BEFORE this construction
         // (the CLI binds the editor state in makeLineInput, then constructs
@@ -162,6 +177,8 @@ export class Body {
             this.#menuState = dockBindings.menu;
         if (dockBindings.at !== null)
             this.#atState = dockBindings.at;
+        if (dockBindings.pick !== null)
+            this.#pickState = dockBindings.pick;
         this.#panelState = dockBindings.panel;
         this.#sheetState = dockBindings.sheet;
         if (dockBindings.queue !== null)
@@ -570,6 +587,30 @@ export class Body {
      *  cell: the pointer cycles the collapsed history, newest first, and
      *  the header names the target ("N turns back" — the user cells
      *  after it), so every press tells the user what they got. */
+    /**
+     * TUI2-R2 ⑤ — the cell the next ctrl+r will act on, or -1.
+     *
+     * The rule is expandNext's own first loop, extracted verbatim: the
+     * LAST live cell that can toggle. It is a separate method rather than
+     * a shared constant because the marker and the key must not merely
+     * agree today — the marker is a PROMISE about what the key will do,
+     * and the only way to keep it is to derive it from the same scan.
+     *
+     * The committed fallback (the #collapsed ring) is deliberately NOT
+     * marked: those rows are frozen history, never re-emitted, so a tint
+     * on them could not be moved when the pointer advances. A live target
+     * is the one the marker can tell the truth about.
+     */
+    #focusIndex() {
+        for (let i = this.#cells.length - 1; i >= this.#committed; i -= 1) {
+            const cell = this.#cells[i];
+            if (cell.kind === "tool" && cell.state !== "pending")
+                return i;
+            if (cell.kind === "checklist" && !cell.done)
+                return i;
+        }
+        return -1;
+    }
     expandNext() {
         for (let i = this.#cells.length - 1; i >= this.#committed; i -= 1) {
             const cell = this.#cells[i];
@@ -612,7 +653,7 @@ export class Body {
                 return { kind: "appended", lines: [header, ...exploreRows(cell.rolled.parts, this.#opts.width())] };
             }
             const noun = ROLLUP_NOUN[cell.name] ?? "calls";
-            const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${cell.name.replace("_file", "")} ${cell.rolled.count} ${noun}`)} · ${back}`;
+            const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${displayVerb(cell.name)} ${cell.rolled.count} ${noun}`)} · ${back}`;
             return {
                 kind: "appended",
                 lines: [header, ...cell.rolled.targets.map((t) => `  ${p.dim}└ ${escapeTerminal(t)}${p.reset}`)],
@@ -628,14 +669,16 @@ export class Body {
         }
         const turnsBack = this.#cells.slice(idx + 1).filter((c) => c.kind === "user").length;
         const p = palette();
-        const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${cell.name.replace("_file", "")} ${toolTarget(cell.name, input)}`)} · ${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} back`;
+        const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`${displayVerb(cell.name)} ${toolTarget(cell.name, input)}`)} · ${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} back`;
         return {
             kind: "appended",
             lines: [
                 header,
-                `--- ${cell.name} input ---`,
+                // TUI2-R2pre ④: the SECTION HEADERS say the act; the payloads
+                // below them (inputFull, resultText) are RAW and byte-identical.
+                `--- ${displayVerb(cell.name)} input ---`,
                 cell.inputFull,
-                `--- ${cell.name} output${cell.isError ? " (error)" : ""} ---`,
+                `--- ${displayVerb(cell.name)} output${cell.isError ? " (error)" : ""} ---`,
                 cell.resultText,
             ],
         };
@@ -645,13 +688,29 @@ export class Body {
     get active() {
         return this.#docked && this.#isActive();
     }
+    /** TUI2-R2pre ③ — the ONE place a resize listener is installed, and it
+     *  removes the previous one first. `process.stdout` is process-wide and
+     *  its listeners outlive the object that added them, so "add" without
+     *  "remove first" is a leak by construction: the old closure is
+     *  unreachable the moment #resizeHandler is overwritten, and not even
+     *  exit() can take it off. */
+    #attachResize() {
+        this.#detachResize();
+        this.#resizeHandler = () => this.onResize();
+        process.stdout.on("resize", this.#resizeHandler);
+    }
+    #detachResize() {
+        if (this.#resizeHandler === null)
+            return;
+        process.stdout.off("resize", this.#resizeHandler);
+        this.#resizeHandler = null;
+    }
     enter() {
         const rows = process.stdout.rows ?? 0;
         if (process.stdout.isTTY !== true || palette().bold === "" || rows < 4)
             return;
         this.#docked = true;
-        this.#resizeHandler = () => this.onResize();
-        process.stdout.on("resize", this.#resizeHandler);
+        this.#attachResize();
         this.#fullRedraw = true;
         this.#dirty = true;
         this.render(); // the FIRST frame — the full-redraw path, no pre-clear
@@ -659,13 +718,16 @@ export class Body {
     /** Teardown — CSI r (the "no broken terminal" contract byte), the
      *  chrome rows cleared, the cursor home at the input line. */
     exit() {
-        if (!this.#docked)
+        if (!this.#docked) {
+            // TUI2-R2pre ③: an un-docked compositor can still hold a listener
+            // (it was superseded, or enter() ran and the dock was torn down by
+            // another path) — the teardown is unconditional, the CHROME clear
+            // below is not.
+            this.#detachResize();
             return;
-        this.#docked = false;
-        if (this.#resizeHandler !== null) {
-            process.stdout.off("resize", this.#resizeHandler);
-            this.#resizeHandler = null;
         }
+        this.#docked = false;
+        this.#detachResize();
         const H = this.#lastH > 0 ? this.#lastH : process.stdout.rows ?? 24;
         const out = [];
         out.push("\x1b[r");
@@ -750,6 +812,11 @@ export class Body {
     bindAt(state) {
         this.#atState = state;
     }
+    /** TUI2-R2 ②: bind the editor's session picker — the band's third
+     *  occupant (see #menuRows for why they share one). */
+    bindPick(state) {
+        this.#pickState = state;
+    }
     /** Bind the pending-turn queue — the CLI's live slots (chat.ts):
      *  the chips render in the menu-rows family, the live caps shrink
      *  by their rows, and the +N queued hint rides the status row. */
@@ -960,9 +1027,21 @@ export class Body {
             liveLines = panelRowsOf(panel, W, Math.max(1, H - 4 - inputExtra - queueRows.length));
         }
         else {
+            // TUI2-R2 ⑤ (D, candidate 1): the FOCUS — the cell the next ctrl+r
+            // will act on brightens its own token. The index is derived from
+            // the SAME scan expandNext performs (#focusIndex shares its rule
+            // by construction), so the marker can never point at a cell the
+            // key would not take — which is the only way a focus marker is
+            // worth having.
+            const focus = this.#focusIndex();
             let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
-            for (const cell of this.#cells.slice(this.#committed)) {
+            for (let i = this.#committed; i < this.#cells.length; i += 1) {
+                const cell = this.#cells[i];
                 const rows = cellComponent(cell).render(W, ctx);
+                // the head row carries the affordance; the tint lands on it and
+                // nowhere else, which is what makes "exactly one" structural
+                if (i === focus && rows.length > 0)
+                    rows[0] = focusToken(rows[0], W);
                 liveLines.push(...bodySpacing(prev, rows));
                 prev = rows;
             }
@@ -975,9 +1054,15 @@ export class Body {
             this.#commitCell(this.#committed, W, ctx);
             liveLines = [];
             {
+                // TUI2-R2 ⑤: the focus re-derives after a commit — the cell it
+                // pointed at may have just left the live region
+                const focus = this.#focusIndex();
                 let prev = this.#committed > 0 ? this.#lineCache[this.#committed - 1] : null;
-                for (const cell of this.#cells.slice(this.#committed)) {
+                for (let i = this.#committed; i < this.#cells.length; i += 1) {
+                    const cell = this.#cells[i];
                     const rows = cellComponent(cell).render(W, ctx);
+                    if (i === focus && rows.length > 0)
+                        rows[0] = focusToken(rows[0], W);
                     liveLines.push(...bodySpacing(prev, rows));
                     prev = rows;
                 }
@@ -1289,6 +1374,15 @@ export class Body {
      * occupant knowing the other exists.
      */
     #menuRows(W) {
+        // TUI2-R2 ②: the session picker is the band's THIRD occupant and
+        // takes it first. It is modal — it opens before a session exists,
+        // so neither the menu nor the @ picker can be up beside it — and
+        // riding this channel buys it the same geometry every other band
+        // occupant already has: counted in chromeRows, clamped with the
+        // composer, redrawn with the frame.
+        const pick = this.#pickState?.() ?? null;
+        if (pick !== null)
+            return sessionPickerRows(pick, W, Date.now());
         const at = this.#atState?.() ?? null;
         if (at !== null)
             return atPanelRows(at, W);
@@ -1503,7 +1597,20 @@ export class Body {
             if (leaving < skip)
                 out.push(`\x1b[${leaving + 1};1H\x1b[0J`);
             out.push(`\x1b[${H};1H`);
-            for (let i = 0; i < skip; i += 1)
+            // TUI2-R2pre ② — scroll the rows that LEFT THE WINDOW SINCE THE
+            // LAST FRAME (`leaving`), never `skip`, which is the window's
+            // ABSOLUTE top. Scrolling the absolute top re-pushed the whole
+            // history's worth of rows on EVERY full redraw — and a live-region
+            // shrink takes this path, so that was most frames of a real
+            // session. The ED above had just blanked everything below row
+            // `leaving`, so what those surplus LFs carried into the terminal's
+            // scrollback was blank rows: the large blank bands mid-history of
+            // the owner's field report. The SCREEN never showed it because the
+            // repaint below covers every row 1..H (the V6-1 rule), and the
+            // house emulator drops scrolled rows on the floor — so no gate
+            // could see it either. Measured on the 5-turn 80x24 repro: the
+            // scrollback went from 162 blank rows of 168 to 14 of 52.
+            for (let i = 0; i < leaving; i += 1)
                 out.push("\n");
         }
         if (!overlay)
@@ -1549,8 +1656,7 @@ export class Body {
         // retired (the CHA is absolute — the base is irrelevant; the
         // CUB's base was the LAST write's end column, which the steady
         // frame's ELs leave at col 1 — the A3 finding)
-        out.push(`\x1b[${1 + editor.rows.length - editor.markerRow}A`);
-        out.push(`\x1b[${editor.markerCol}G`);
+        this.#parkCursor(out, H, H - 2 - inputExtra + editor.markerRow, editor.markerCol);
     }
     /** The steady-state frame — RELATIVE moves only (invariant ②); the
      *  commits scroll via the CUP-free real LF at the last row, and the
@@ -1626,6 +1732,16 @@ export class Body {
             if (H > anchorRow)
                 out.push(`\x1b[${H - anchorRow}B`);
         }
+        // TUI2-R2pre ②: this count is the COMMIT count on purpose, and it
+        // stays. It reads like the same mistake the full path made, but the
+        // two paths are doing different jobs: the full path REPAINTS every
+        // row, so anything it scrolls is a duplicate of what it is about to
+        // draw; the steady path does not repaint the frozen band, and the
+        // rows it scrolls carry the PRE-FRAME live copies of the cells that
+        // just committed — the A7 single-copy discipline (the old live band
+        // is EL'd first, so the repaint below is the only copy left). Making
+        // this `leaving` was measured: the A7 gate fails at 40x24 frame 106
+        // with the greeting duplicated in the terminal.
         for (let i = 0; i < committed.length; i += 1)
             out.push("\n");
         // the bottom-up repaint, from the last row up — V6-3 + W6 + KC1:
@@ -1672,6 +1788,11 @@ export class Body {
         }
         // 2. the STALE rows above the committed section — the scrolled old
         //    live copies (a live-drawn cell's pre-commit position): EL.
+        //    TUI2-R2pre ②: the old band's POST-SCROLL origin shifted up by
+        //    the rows that actually left — `leaving`. It read the commit
+        //    count only because the scroll above used to BE the commit
+        //    count; with the two decoupled, the old expression erases rows
+        //    of frozen content that never moved.
         const staleFrom = Math.max(1, this.#lastLiveTop - committed.length);
         for (let r = staleFrom; r < liveTop - committed.length; r += 1) {
             out.push(`\x1b[${r};1H\x1b[0K`);
@@ -1708,21 +1829,47 @@ export class Body {
                             : H - 3 - inputExtra;
         // the anchor: the MARKER'S row inside the composer (N = 1,
         // markerRow 0 ⇒ the retired H−2)
-        const down = H - 2 - inputExtra + editor.markerRow - lastRow;
-        if (down > 0)
-            out.push(`\x1b[${down}B`);
-        // W23: the CHA to the frame-derived column — the cursor rests AT
-        // the marker from ANY base (the retired afterW CUB clamped at col
-        // 1 — the steady frame's LAST write is the gap/stale EL: the A3
-        // finding; the A5/A8 live lines end mid-row, the ELs at col 1 —
-        // the CHA ignores the base by construction)
-        out.push(`\x1b[${editor.markerCol}G`);
+        this.#parkCursor(out, lastRow, H - 2 - inputExtra + editor.markerRow, editor.markerCol);
         // A8b: the steady path moves the window too (the scroll + the
         // repaint) — record its top so the next full-redraw's leaving count
         // is the rows the window dropped since the last frame, whatever the
         // path of the frames between (same formula as `skip` above).
         this.#lastSkip = skip;
     }
+    /**
+     * TUI2-R2 ⑤ (the R1.5 parked ⑩) — CURSOR AUTHORITY: the ONE frame-tail
+     * positioning sequence, and the compositor's alone.
+     *
+     * Both draw paths ended with their own hand-rolled park — the full
+     * path counting rows up from the status line, the steady path counting
+     * down from a six-branch re-derivation of which write happened to be
+     * last. Two implementations of one contract, each re-deriving byte
+     * order the drawing code already knew, and the walkthrough found the
+     * consequence three times over (the cursor resting in the status
+     * line's "de▮ault", at the end of streamed text, inside an approval
+     * panel's rule row). A terminal cursor is the product's claim about
+     * where the next keystroke lands; a claim made in two places is a
+     * claim that will eventually disagree with itself.
+     *
+     * One owner, one sequence: a single vertical move to the marker's row
+     * — in EITHER direction, which the steady path could not do (its move
+     * was `if (down > 0)`, so a cursor left BELOW the composer simply
+     * stayed there) — then the CHA to the frame-derived column.
+     *
+     * Relative, not a CUP, and deliberately: invariant ② reserves absolute
+     * addressing for the content area, and the composer is chrome. The
+     * CHA is absolute in the COLUMN only, which is what makes the park
+     * independent of wherever the last write ended (the A3 finding: the
+     * retired CUB's base was the gap EL's column 1, left of the lead).
+     */
+    #parkCursor(out, fromRow, toRow, col) {
+        const delta = toRow - fromRow;
+        if (delta > 0)
+            out.push(`\x1b[${delta}B`);
+        else if (delta < 0)
+            out.push(`\x1b[${-delta}A`);
+        out.push(`\x1b[${col}G`);
+    }
     /** Invariant ①: every emitted line fits the width — a violation is a
      *  CRASH with the diagnostic, never a silent truncate. */
     #checked(line, W) {
@@ -1825,6 +1972,16 @@ export class Dock {
         }
         compositorRef.bindAt(state);
     }
+    /** TUI2-R2 ②: bind the editor's session picker — the band's third
+     *  occupant. Unbound (every path but bare `kiso resume`), the picker
+     *  cannot render and every frame is byte-identical to before. */
+    bindPick(state) {
+        if (compositorRef === null) {
+            dockBindings.pick = state;
+            return;
+        }
+        compositorRef.bindPick(state);
+    }
     /** W22: bind the pending-turn queue — the chips + the +N queued
      *  hint (the CLI binds it from chat(); the editor's pop keys ride
      *  the LineInput's own bindQueue). */
@@ -1850,4 +2007,4 @@ let compositorRef = null;
  *  — the old snapshot froze `menu` at bindInput time and the slash-
  *  command menu silently never bound in the real CLI (the e2e gates
  *  bind the Body directly and could not see it). */
-const dockBindings = { state: null, prompt: "", menu: null, at: null, panel: null, sheet: null, queue: null };
+const dockBindings = { state: null, prompt: "", menu: null, at: null, pick: null, panel: null, sheet: null, queue: null };

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). */
@@ -101,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