@vincemakes/kiso-tui 0.8.0 → 0.10.0

package/dist/compositor.js

@@ -48,9 +48,12 @@ import { leadWidth } from "./width.js"; // W23: the ONE width authority (the edi
 // KC3.5: the panel-slot reads come from the DISPATCHERS — one source
 // for four reads, so an ask can never render half as an approval.
 import { panelAffordanceOf, panelLeadOf, panelRowsOf, panelStatusOf } from "./ask-panel.js";
-import { atPanelRows } from "./at-picker.js";
-import { Container, ROLLUP_NOUN, SPINNER, bodySpacing, boxBottom, boxTop, cellComponent, foldLine, pendingQueueRows, statusLine, turnFold, visibleWidth, } from "./components.js";
+import { atPanelRows, bandHeader } from "./at-picker.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 { 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). */
@@ -118,12 +121,24 @@ export class Body {
     // panel is up it replaces the live region, owns the input lead, and
     // derives the status row (the CLI's painting status yields).
     #panelState = null;
+    /** TUI2-R1 (D): the keys sheet's slot read — the editor's boolean.
+     *  Unbound, the sheet cannot render and every frame is byte-identical
+     *  to before the round. */
+    #sheetState = null;
+    /** TUI2-R1.5 7(a): the sheet's previous up/down state — a transition
+     *  in either direction takes the full-redraw path. */
+    #sheetWasUp = false;
+    /** This frame is an overlay open or close — it must not scroll. */
+    #overlayFrame = false;
     #inputState = () => ({ line: "", cursor: 0 });
     #inputPrompt = "";
     #menuState = null;
     // 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
@@ -136,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
@@ -152,7 +177,10 @@ 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)
             this.#queueState = dockBindings.queue;
     }
@@ -212,6 +240,19 @@ export class Body {
             this.#write(`→ ${escapeTerminal(name)}(${escapeTerminal(JSON.stringify(input).slice(0, 200))})\n`);
             return;
         }
+        // TUI2-R1.5 ① (VD-1): the tool's start CLOSES an open text block —
+        // the inactive path above has always done this; the active path
+        // forgot, and the consequence was structural. textAppend only ever
+        // grows the LAST cell, so a text block with a tool cell after it can
+        // never receive another byte: it is finished in fact while its
+        // `done` flag says otherwise. The commit loop takes leading DONE
+        // cells, so that one stale flag parked the whole rest of the turn
+        // behind it — every tool cell then reached the screen through the
+        // FORCE-commit path, which by design bypasses the fold-hold. That is
+        // why the walkthrough saw nine individual rows: not a fold that
+        // declined to form, a fold that was never consulted.
+        this.#closeOpenThinking();
+        this.#closeOpenText();
         // W12: the cell carries the delegate's child roles from the FULL
         // input — the display summary is sliced at 60 chars (unparseable);
         // the roles are the only running-state data the parent holds (there
@@ -282,6 +323,30 @@ export class Body {
         }
         this.#mark();
     }
+    /**
+     * TUI2-R1 (C) — the RUNNING call's observed output.
+     *
+     * The CLI tails the shell tool's progress sidecar and hands what it
+     * read to the cell. Deliberately narrow: only a cell that is still
+     * RUNNING accepts it, so an observation can never overwrite a real
+     * result, and an unchanged read costs no frame at all (a poller
+     * fires far more often than the output changes).
+     *
+     * This adds no event and no durable state. The text lands in the
+     * cell's live rendering and is replaced wholesale by the tool's own
+     * result at settle — which is the only text anything else ever reads.
+     */
+    toolProgress(callId, text) {
+        if (!this.#isActive())
+            return; // the pipe path has no live region
+        const cell = this.#toolCell(callId);
+        if (cell === null || cell.kind !== "tool" || cell.state !== "running" || cell.done)
+            return;
+        if (cell.resultText === text)
+            return;
+        cell.resultText = text;
+        this.#mark();
+    }
     toolSucceeded(callId) {
         if (!this.#isActive())
             this.#write("  ok\n");
@@ -492,7 +557,7 @@ export class Body {
         this.#cells.push({ kind: "banner", version, extensionsText, resume, done: true });
         this.#mark();
     }
-    raw(lines) {
+    raw(lines, wrap) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
             this.#closeOpenText();
@@ -502,7 +567,7 @@ export class Body {
         }
         this.#closeOpenThinking();
         this.#closeOpenText();
-        this.#cells.push({ kind: "raw", lines, done: true });
+        this.#cells.push({ kind: "raw", lines, done: true, ...(wrap === undefined ? {} : { wrap }) });
         this.#mark();
     }
     /** The last COMPLETE thinking block, for /think. */
@@ -522,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];
@@ -555,8 +644,16 @@ export class Body {
             // land as NEW content, history is never rewritten, ADR-0046).
             const turnsBack = this.#cells.slice(idx + 1).filter((c) => c.kind === "user").length;
             const p = palette();
+            const back = `${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} back`;
+            // TUI2-R1 (B): an EXPLORATION head lists per TOOL — the counts
+            // the row showed, then one row per tool with its subjects. The
+            // header keeps W15's shape; only the subject changes.
+            if (cell.rolled.parts !== undefined) {
+                const header = `${p.bold}▞${p.reset} expanded · ${escapeTerminal(`explored ${exploreCounts(cell.rolled.parts)}`)} · ${back}`;
+                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}`)} · ${turnsBack} ${turnsBack === 1 ? "turn" : "turns"} 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}`)],
@@ -572,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,
             ],
         };
@@ -589,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
@@ -603,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");
@@ -680,6 +798,11 @@ export class Body {
     }
     /** Bind the editor's slash-command menu state — the MenuSelect slot
      *  occupant (the menu replaces the editor's view while open). */
+    /** TUI2-R1 (D): bind the editor's keys-sheet flag. */
+    bindSheet(state) {
+        this.#sheetState = state;
+        this.#mark();
+    }
     bindMenu(state) {
         this.#menuState = state;
     }
@@ -689,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. */
@@ -772,10 +900,20 @@ export class Body {
      *  screen rows), threaded against the previous sibling's OWN rows. */
     liveCount() {
         const panel = this.#panelState?.() ?? null;
+        const sheet = this.#sheetState?.() === true;
         const queueRows = this.#queueRows(this.#opts.width(), this.#opts.height());
         // KC1 §6: the composer's extra rows are chrome too — the scalar
         // counts them exactly like the menu/queue bands (N = 1 ⇒ +0)
         const inputExtra = this.#inputRows(this.#opts.width(), this.#opts.height(), this.#menuRows(this.#opts.width()).length, queueRows.length).rows.length - 1;
+        // TUI2-R1 (D): the sheet occupies the live region, exactly like the
+        // panel — the scalar must say so, or the cap arithmetic disagrees
+        // with the screen.
+        if (sheet) {
+            return (keysSheetRows(this.#opts.width()).slice(0, Math.max(1, this.#opts.height() - 4 - inputExtra - queueRows.length)).length +
+                CHROME_ROWS +
+                inputExtra +
+                queueRows.length);
+        }
         if (panel !== null) {
             // W21: the panel's own rows (the cap is exact — the scalar
             // reflects the screen). W22: the queue chips occupy their
@@ -861,7 +999,26 @@ export class Body {
         const chromeRows = CHROME_ROWS + inputExtra + menuRows.length + queueRows.length;
         let liveLines = [];
         const panel = this.#panelState?.() ?? null;
-        if (panel !== null) {
+        // TUI2-R1.5 ⑦(a) (VD-8): the sheet is an OVERLAY, and the frame it
+        // opens on — and the one it closes on — take the full-redraw path.
+        // The sheet REPLACES the live region, so on an idle composer (where
+        // the live region is empty) opening it GROWS the model by its own
+        // height; the frame's skip grows with it and the difference is paid
+        // in real LFs — rows scrolled permanently into the terminal's
+        // scrollback, which closing cannot undo, because the scrollback is
+        // not ours to rewrite. Measured: three rows per open on a full
+        // screen. The overlay below displaces content on screen instead.
+        const sheetUp = this.#sheetState?.() === true;
+        this.#overlayFrame = sheetUp || this.#sheetWasUp;
+        this.#sheetWasUp = sheetUp;
+        if (sheetUp) {
+            // TUI2-R1 (D): the sheet REPLACES the live region — the same
+            // slot the panel uses, for the same reason (it is what the
+            // human is reading right now). It cannot coexist with a panel:
+            // the editor only opens it from an idle composer.
+            liveLines = keysSheetRows(W).slice(0, Math.max(1, H - 4 - inputExtra - queueRows.length));
+        }
+        else if (panel !== null) {
             // W21: the panel REPLACES the running tool's live window — the
             // bounded block, capped at H−4 (the panel IS the live region;
             // the W11 blank would separate it from the frozen content).
@@ -870,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;
             }
@@ -885,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;
                 }
@@ -940,14 +1115,17 @@ export class Body {
     #commitCell(i, W, ctx) {
         const cell = this.#cells[i];
         const lines = this.#foldOrRollup(cell, i, W, ctx);
-        // W15: a tool cell whose last committed row carried the "ctrl+r"
-        // affordance (the renderer cut "└ … ctrl+r") joins the expand
-        // history — the detection is the renderer's OWN output, so the
-        // read's "/last"-only cut note never lands here.
+        // W15: a tool cell whose committed rows carried the "ctrl+r"
+        // affordance joins the expand history — the detection is the
+        // renderer's OWN output, so the read's "/last"-only cut note never
+        // lands here. TUI2-R1 (A/B): the affordance is no longer only the
+        // renderer cut's "└ … ctrl+r" — the self-naming head suffix and
+        // the exploration row carry it on the HEAD row, and a promise the
+        // key does not answer would be the one thing worse than silence.
         // unshift: the cells commit oldest-first, so the NEWEST cut lands
         // at the front — the expand pointer's "newest back" walk starts
         // where the user's last key press would aim.
-        if (cell.kind === "tool" && /└ .*ctrl\+r/.test(lines[lines.length - 1] ?? ""))
+        if (cell.kind === "tool" && lines.some((l) => l.includes("ctrl+r")))
             this.#collapsed.unshift(i);
         this.#lineCache[i] = lines;
         const placed = bodySpacing(i > 0 ? this.#lineCache[i - 1] : null, lines);
@@ -967,7 +1145,51 @@ export class Body {
         const turn = cell.turn >= 0 ? this.#turns[cell.turn] : undefined;
         if (turn === undefined || turn !== this.#turns[this.#turns.length - 1])
             return false;
-        return !turn.ended && !turn.hasText;
+        if (!turn.ended && !turn.hasText)
+            return true;
+        // the turn's END releases every hold — the settle is where the run
+        // is decided, and a held cell at settle would never commit at all.
+        if (turn.ended)
+            return false;
+        return this.#growingRun(i);
+    }
+    /** TUI2-R1.5 ① (VD-1) — the explore-run hold. W14's hold covers the
+     *  QUIET turn only, and the model's own narration ("let me look at the
+     *  parser area") sets hasText before the first read even starts: from
+     *  there each completion committed in its OWN frame, the head committed
+     *  alone, and `members.every(done)` — the fold's gate — could never be
+     *  true again. Every real session therefore degraded to one row per
+     *  call while the unit suite, which feeds the burst synchronously,
+     *  stayed green (the walkthrough's frame s1-06).
+     *
+     *  The hold is the smallest honest fix: a DONE explore cell whose run
+     *  can still GROW does not commit yet — its committed form is not
+     *  decided until the run is closed. The run closes at the first
+     *  non-explore cell (the model's next word, an edit, a shell) or at the
+     *  turn's end, and the whole run then commits in ONE frame, which is
+     *  exactly the shape the fold was written for.
+     *
+     *  The force-commit path never consults this (see #held's callers): the
+     *  screen's hard cap still wins, so the screen never sticks — a run
+     *  under real screen pressure degrades mid-turn, and the rows it
+     *  already froze stay frozen (history is never rewritten, ADR-0046). */
+    #growingRun(i) {
+        const cell = this.#cells[i];
+        if (cell.kind !== "tool" || !isExploreTool(cell.name))
+            return false;
+        // the run is still growing while NOTHING but explore cells follow —
+        // the turn-less noise cells (permission raws, ⚠ notices) are
+        // transparent here for the same reason the run scan sees through
+        // them: the streaming execution interleaves them between the calls.
+        for (let j = i + 1; j < this.#cells.length; j += 1) {
+            const next = this.#cells[j];
+            if (next.kind === "raw" || next.kind === "notice")
+                continue;
+            if (next.kind === "tool" && isExploreTool(next.name))
+                continue;
+            return false; // a non-explore cell closed the run — commit now
+        }
+        return true;
     }
     /** W14/W13 — the release-time decision at a commit, BEFORE the cell's
      *  own render: the folded-turn fold first (a QUIET turn — ended, no
@@ -996,26 +1218,38 @@ export class Body {
                 return [];
             }
         }
-        if (cell.kind !== "tool" || ROLLUP_NOUN[cell.name] === undefined)
+        if (cell.kind !== "tool" || !isExploreTool(cell.name))
             return cellComponent(cell).render(W, ctx);
-        // the maximal same-name run around i — forward/backward scans over
+        // TUI2-R1 (B): the run is over the READ-ONLY SET, not one name —
+        // a model exploring mixes read/list/search, and the same-name scan
+        // split every real burst into fragments. Writes, edits, shells and
+        // extension tools still break the run at the first one.
+        // the maximal read-only run around i — forward/backward scans over
         // the cells. The turn-less noise cells (the permission raws, the ⚠
         // notices) are TRANSPARENT: the streaming execution (loop.ts launch)
         // interleaves them BETWEEN the calls of one burst, so the run must
         // see through them. It never crosses a user/text/thinking cell —
         // those separate turns and contexts.
+        // TUI2-R1.5 ① (VD-1): the backward scan stops at the cells this
+        // FRAME is committing. A cell committed in an earlier frame is
+        // frozen — its rows are on the screen and in the scrollback — so it
+        // can never become the head of a rollup now, and a run that
+        // force-committed its first rows mid-turn must not have the rest
+        // silently absorbed into a summary that was computed without them.
+        // The degraded head keeps its individual row; the rest of the run
+        // rolls on its own.
         let s = i;
         let head = i;
-        while (s > 0) {
+        while (s > this.#committedAtFrameStart) {
             const prev = this.#cells[s - 1];
             if (prev.kind === "raw" || prev.kind === "notice") {
                 s -= 1;
                 continue;
             }
-            if (prev.kind !== "tool" || prev.name !== cell.name)
+            if (prev.kind !== "tool" || !isExploreTool(prev.name))
                 break;
             s -= 1;
-            head = s; // a same-name tool precedes — it is the group's head
+            head = s; // a read-only tool precedes — it is the group's head
         }
         let e = i;
         while (e + 1 < this.#cells.length) {
@@ -1024,7 +1258,7 @@ export class Body {
                 e += 1;
                 continue;
             }
-            if (next.kind !== "tool" || next.name !== cell.name)
+            if (next.kind !== "tool" || !isExploreTool(next.name))
                 break;
             e += 1;
         }
@@ -1042,13 +1276,18 @@ export class Body {
             this.#rolledHeads.add(head);
             let total = 0;
             const targets = [];
+            // TUI2-R1 (B): the per-tool parts, in first-call order — the
+            // exploration row's counts and its expanded list both read them.
+            // A search's subject is the PATTERN it looked for (quoted); a
+            // read's or a list's is the path it named.
+            const parts = [];
             for (const m of members) {
                 // the lines count, excluding the tool's OWN truncation note
                 // (read_file's "… N more lines") — the per-cell meta's rule
                 const noteAt = m.resultText.lastIndexOf("\n… ");
                 const shown = noteAt >= 0 ? m.resultText.slice(0, noteAt) : m.resultText;
-                const parts = shown.split("\n");
-                total += parts[parts.length - 1] === "" ? parts.length - 1 : parts.length;
+                const rows = shown.split("\n");
+                total += rows[rows.length - 1] === "" ? rows.length - 1 : rows.length;
                 let input = {};
                 try {
                     input = JSON.parse(m.inputFull);
@@ -1059,11 +1298,19 @@ export class Body {
                 }
                 const target = toolTarget(m.name, input);
                 targets.push(target.split("/").pop() ?? target);
+                const subject = m.name === "search_text" ? `"${String(input.pattern ?? "")}"` : target;
+                const part = parts.find((x) => x.name === m.name);
+                if (part === undefined)
+                    parts.push({ name: m.name, subjects: [subject] });
+                else
+                    part.subjects.push(subject);
             }
             const first = members[0];
             const last = members[members.length - 1];
             const elapsed = first.startedAt !== null && last.doneAt !== null ? ((last.doneAt - first.startedAt) / 1000).toFixed(1) : "?";
-            cell.rolled = { count: members.length, lines: total, elapsed, targets };
+            // TUI2-R1 (B): `parts` rides ONLY a mixed run — a single-name
+            // run keeps W13's row, byte for byte (the generalization adds).
+            cell.rolled = { count: members.length, lines: total, elapsed, targets, ...(parts.length > 1 ? { parts } : {}) };
             return cellComponent(cell).render(W, ctx);
         }
         // a MEMBER of an already-rolled run → [] (its rows live in the
@@ -1127,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);
@@ -1134,7 +1390,11 @@ export class Body {
         if (menu === null || menu === undefined || menu.items.length === 0)
             return [];
         const p = palette();
-        const rows = [];
+        // TUI2-R1.5 ⑦(b) (VD-8): the band NAMES itself, the same way the @
+        // picker's does. Both render frameless directly above the composer,
+        // so with scrollback behind them there was nothing to say where the
+        // surface began — the rows read as more history.
+        const rows = [bandHeader("commands", W)];
         for (let i = 0; i < menu.items.length; i += 1) {
             const item = menu.items[i];
             const text = i === menu.selected
@@ -1268,6 +1528,7 @@ export class Body {
      *  EVERY row is idempotent: N consecutive resizes end with the same
      *  screen as a single jump to the same size. */
     #drawFull(out, W, H, liveTop, liveLines, queueRows, menuRows, editor) {
+        const overlay = this.#overlayFrame;
         const inputExtra = editor.rows.length - 1; // KC1: the composer's rows above the retired single input row
         const committed = this.#committedLinesThisFrame;
         // 0. the FROZEN rows — the re-folded committed content (re-flowed
@@ -1295,7 +1556,15 @@ export class Body {
         // window (the committed share + the live + the chrome), r
         // monotone, every row 1..H re-painted (the V6-1 every-row rule).
         const all = [...frozen, ...committed, ...liveLines];
-        const skip = Math.max(0, all.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
+        // TUI2-R1.5 7(a) (VD-8): while the sheet is up the window does NOT
+        // move. skip is frozen at its pre-open value and #lastSkip is left
+        // alone, so no LF is emitted and nothing enters the scrollback; the
+        // march below is clamped to the window instead, which makes the
+        // sheet displace content ON SCREEN. Closing takes the full-redraw
+        // path with the same #lastSkip and every displaced row comes back.
+        const skip = overlay
+            ? this.#lastSkip
+            : Math.max(0, all.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
         // A8b (the shrink-trigger's completion): the rows that LEAVE the
         // window scroll into the terminal's scrollback — the LF mechanism
         // (the steady path's own). Only the rows the paint re-covers (the
@@ -1307,7 +1576,7 @@ export class Body {
         // shrink EVERY frame) loses the scrolled-away turns from the
         // terminal's scrollback entirely (finding #A8b — the queued-flood
         // content loss).
-        if (skip > 0) {
+        if (skip > 0 && !overlay) {
             const leaving = Math.max(0, skip - this.#lastSkip);
             // A8b (the fresh leaving share): a leaving row whose old-screen
             // copy is stale — the committed-this-frame lines (their old rows
@@ -1328,12 +1597,32 @@ 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");
         }
-        this.#lastSkip = skip;
+        if (!overlay)
+            this.#lastSkip = skip;
         let r = 1;
-        for (const line of all.slice(skip)) {
+        // the window's content rows: everything above the chrome. With the
+        // overlay up `all` can exceed it, and the rows that give way are the
+        // OLDEST on screen — they are still in the model and come back on
+        // the close.
+        const contentRows = Math.max(0, H - CHROME_ROWS - inputExtra - queueRows.length - menuRows.length);
+        const march = all.slice(skip);
+        for (const line of march.length > contentRows ? march.slice(march.length - contentRows) : march) {
             out.push(`\x1b[${r};1H\x1b[0K${this.#checked(line, W)}`);
             r += 1;
         }
@@ -1367,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
@@ -1384,8 +1672,12 @@ export class Body {
         // frozenCount, so the lines at [frozenCount..skip−1] are the fresh
         // leaving share (their old-screen copies are stale).
         const frozenCount = this.#committedLines - committed.length;
-        const skip = Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
-        const leaving = Math.max(0, skip - this.#lastSkip);
+        // TUI2-R1.5 7(a): an overlay frame never moves the window (see
+        // #drawFull) — the sheet's rows displace content on screen instead
+        // of pushing it into the scrollback.
+        const overlay = this.#overlayFrame;
+        const skip = overlay ? this.#lastSkip : Math.max(0, this.#committedLines + liveLines.length + CHROME_ROWS + inputExtra + queueRows.length + menuRows.length - H);
+        const leaving = overlay ? 0 : Math.max(0, skip - this.#lastSkip);
         // the jump to the bottom row H, then N real LFs scroll the screen
         // exactly N rows — ONE per committed line (the bookkeeping; the
         // stale 1B anchor jumped to H−1 and the N LFs scrolled only N−1 —
@@ -1440,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:
@@ -1486,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`);
@@ -1522,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) {
@@ -1605,6 +1938,15 @@ export class Dock {
         }
         compositorRef.bindApproval(state);
     }
+    /** TUI2-R1 (D): bind the editor's keys-sheet flag — the slot read for
+     *  the ? overlay (the menu/picker binding pattern). */
+    bindSheet(state) {
+        if (compositorRef === null) {
+            dockBindings.sheet = state;
+            return;
+        }
+        compositorRef.bindSheet(state);
+    }
     bindInput(state, prompt) {
         if (compositorRef === null) {
             dockBindings.state = state; // the live buffer — order-agnostic
@@ -1630,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). */
@@ -1655,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, queue: null };
+const dockBindings = { state: null, prompt: "", menu: null, at: null, pick: null, panel: null, sheet: null, queue: null };