@vincemakes/kiso-tui-cells 0.7.0 → 0.9.0

package/dist/approval-panel.d.ts

@@ -27,6 +27,54 @@
 export type PanelFlavor = "approval" | "simple";
 export type PanelPhase = "options" | "rule" | "amend";
 export type PanelSel = 0 | 1 | 2 | 3;
+/** One option of a question: the label the human picks, plus an
+ *  optional one-line description (the model's own words). */
+export interface AskOption {
+    readonly label: string;
+    readonly description?: string;
+}
+/** One question: 2-4 options, single- or multi-select, and an optional
+ *  ≤12-cell header (the panel's title when present — the schema caps
+ *  it so the title never fights the counter for the row). */
+export interface AskQuestion {
+    readonly question: string;
+    readonly header?: string;
+    readonly options: readonly AskOption[];
+    readonly multiSelect?: boolean;
+}
+/** The whole ask_user call: 1-4 questions, walked in order. */
+export interface AskSpec {
+    readonly questions: readonly AskQuestion[];
+}
+/** One answered question — the three shapes the tool_result carries:
+ *  a single choice, a multi-select list, or the typed-in answer. */
+export type AskAnswer = {
+    readonly q: string;
+    readonly choice: string;
+} | {
+    readonly q: string;
+    readonly choices: readonly string[];
+} | {
+    readonly q: string;
+    readonly custom: string;
+};
+/** The ask's outcome: every question answered, or the decline — an
+ *  HONEST recorded outcome that names what was skipped, never silence. */
+export type AskResult = {
+    readonly answers: readonly AskAnswer[];
+} | {
+    readonly declined: readonly string[];
+};
+/** The ask panel's runtime state — the editor owns and advances it,
+ *  the compositor reads it. `picks` and `custom` are per question, so
+ *  a walk back (←) shows what was already chosen. */
+export interface AskRuntime {
+    readonly qIndex: number;
+    readonly cursor: number;
+    readonly picks: readonly (readonly number[])[];
+    readonly custom: readonly (string | null)[];
+    readonly phase: "options" | "custom";
+}
 /** The ALWAYS-verbose args (the panel's body): the untruncated diff
  *  (edit/write), or the full text (shell = the command line, other =
  *  the pretty-printed JSON). The CLI composes them UNTRUNCATED — the
@@ -64,6 +112,10 @@ export interface PanelView {
     /** The fallback question — the y/n text for the dock-less path
      *  (a TTY without a dock, or a pipe). */
     readonly fallbackQuestion: string;
+    /** KC3.5: the questions, when this view is an ASK. Present = the
+     *  panel renders the ask block and the editor routes the ask keys;
+     *  absent = the approval/simple panel, unchanged. */
+    readonly ask?: AskSpec;
 }
 export type PanelVerdict = {
     readonly action: "allow";
@@ -76,6 +128,13 @@ export type PanelVerdict = {
     readonly reason: string;
 } | {
     readonly action: "cancel";
+}
+/** KC3.5: the ask's own verdict — the answers (or the decline) the
+ *  cli hands back to the tool. Only ask views ever produce it, so
+ *  the approval path's switch is untouched. */
+ | {
+    readonly action: "answers";
+    readonly result: AskResult;
 };
 /** The bound panel state the compositor reads — the editor owns the
  *  phase/selection state machine and the key routing; the compositor
@@ -84,6 +143,8 @@ export interface PanelState {
     readonly view: PanelView;
     readonly phase: PanelPhase;
     readonly sel: PanelSel;
+    /** KC3.5: the ask's walk — present exactly when `view.ask` is. */
+    readonly ask?: AskRuntime;
 }
 /** The block's rows — EXACTLY the preview's frame shape, the gutter at
  *  the left edge (the preview's two-space mock indent is its own

package/dist/approval-panel.js

@@ -50,10 +50,14 @@ function panelRuleText(view) {
  *  single-row discipline — the row never folds). */
 function panelOptionsRow(view, sel, W) {
     const p = palette();
+    // TUI2-R1.5 ⑪ (VD-13): ONE separator grammar. The options were
+    // two-space separated while every other metadata group in the product
+    // uses `·`, and at 80 columns that put `3 No` far enough from its
+    // neighbours to read as detached rather than as the third option.
     const o1 = sel === 1 ? `${p.bold} 1 Yes${p.reset}` : ` 1 Yes`;
-    const o3 = sel === 3 ? `${p.bold} 3 No${p.reset}` : ` 3 No`;
+    const o3 = sel === 3 ? `${p.bold}3 No${p.reset}` : `3 No`;
     if (view.flavor === "simple")
-        return `${o1}  ${o3}`;
+        return `${o1} · ${o3}`;
     // the option-2 span: " 2 Yes, don't ask again for <name>" — the
     // fixed part is 45 (the gutter + the 1/3 options + the separators +
     // the 28-cell prefix); the name cuts to W−46 + "…". The "…" needs
@@ -62,13 +66,18 @@ function panelOptionsRow(view, sel, W) {
     // DROPS: the rule name is the cuttable span, the 1/3 options are
     // the semantics — the approval decision must survive a narrow
     // winch, and invariant ① must never fire on the options row.
-    if (W < 47)
-        return cutLine(`${o1}  ${o3}`, Math.max(1, W - 2));
-    const name = escapeTerminal(view.name);
-    const budget = W - 46;
-    const shown = visibleWidth(name) > W - 45 ? `${widthCut(name, budget)}…` : name;
-    const o2 = sel === 2 ? `${p.bold} 2 Yes, don't ask again for ${shown}${p.reset}` : ` 2 Yes, don't ask again for ${shown}`;
-    return `${o1}  ${o2}  ${o3}`;
+    // TUI2-R1.5 ⑪: option 2 states what it DOES; the tool it would do it
+    // for is the panel's title, one row above, and repeating it here was
+    // what made this row the widest thing in the block. The fixed part is
+    // now 33 cells, so the whole row survives far narrower windows than the
+    // 47 the rule name used to demand.
+    const o2 = sel === 2 ? `${p.bold}2 Yes, don't ask again${p.reset}` : `2 Yes, don't ask again`;
+    const full = `${o1} · ${o2} · ${o3}`;
+    if (visibleWidth(full) <= W - 2)
+        return full;
+    // too narrow for the middle option: the 1/3 decision is the semantics
+    // and must survive any winch (invariant ① never fires on this row).
+    return cutLine(`${o1} · ${o3}`, Math.max(1, W - 2));
 }
 /** The block's rows — EXACTLY the preview's frame shape, the gutter at
  *  the left edge (the preview's two-space mock indent is its own
@@ -80,7 +89,11 @@ export function panelBlockRows(view, phase, sel, W, maxRows) {
     const rows = [];
     rows.push(`${gutter}${cutLine(panelRuleText(view), Math.max(1, W - 2))}`);
     rows.push(`${gutter}${cutLine(`${p.bold}${escapeTerminal(view.title)}${p.reset}`, Math.max(1, W - 2))}`);
-    rows.push(`${cutLine(`${p.dim}─ the full args — never truncated ─${p.reset}`, Math.max(1, W - 2))}`);
+    // TUI2-R1.5 ⑤ (VD-11): the divider is a LABEL, not a design note. "the
+    // full args — never truncated" is a sentence about the implementation,
+    // addressed to whoever was building the panel; the human reading it
+    // during an approval wants to know what the block below is.
+    rows.push(`${cutLine(`${p.dim}─ args (full) ─${p.reset}`, Math.max(1, W - 2))}`);
     // the args — the bounded block's body: fold, then cap. The └ cut is
     // ONE row (the W20 discipline): when the args exceed the budget, one
     // notice row carries the count and where the rest is (the event log).
@@ -100,7 +113,15 @@ export function panelBlockRows(view, phase, sel, W, maxRows) {
     rows.push(...shown);
     rows.push(`${gutter}${panelOptionsRow(view, sel, W)}`);
     rows.push(`${gutter}${p.dim}${panelAffordance(view, phase, sel)}${p.reset}`);
-    rows.push(`${p.dim}└ ${p.reset}`);
+    // TUI2-R1.5 11 (VD-13): a real bottom RULE, in the block's own edge
+    // vocabulary — the same box-drawing run its divider already uses —
+    // anchored at the gutter column. It used to be `\u2514 `: a two-cell stub
+    // floating at column 1, with no rule running from it and no corner
+    // above it to answer. Worse, `\u2514 ` is the cut-notice prefix everywhere
+    // else in the product, so a CAPPED panel emitted two elbow rows in a
+    // row meaning entirely different things. The rule reads as an edge,
+    // and the cut notice above it reads as a notice.
+    rows.push(`${p.dim}\u2514${"\u2500".repeat(Math.max(0, W - 1))}${p.reset}`);
     return rows;
 }
 /** The input row's lead for the panel's phase (the preview's chrome

package/dist/components.d.ts

@@ -108,12 +108,19 @@ export type BodyCell = {
      *  the head of an N > 2 same-tool run renders the group (the
      *  work order's claimed shape: "✓ read  5 files (2.4k lines,
      *  1.1s)" + the target children). The members carry null — the
-     *  compositor's rolled-heads bookkeeping renders them []. */
+     *  compositor's rolled-heads bookkeeping renders them [].
+     *  TUI2-R1 (B): `parts` is set when the run spans MORE THAN ONE
+     *  read-only tool — the same mechanism, the exploration row.
+     *  Absent (a single-name run) keeps W13's row byte for byte. */
     rolled: null | {
         count: number;
         lines: number;
         elapsed: string;
         targets: string[];
+        parts?: readonly {
+            name: string;
+            subjects: readonly string[];
+        }[];
     };
     /** W19: a DENIED call's reason (the CLI extracted it from the
      *  result's "[Permission denied] " prefix, keyed on the "denied"
@@ -152,6 +159,7 @@ export type BodyCell = {
     kind: "raw";
     lines: string[];
     done: true;
+    wrap?: "words";
 } | {
     kind: "terminal";
     label: string;
@@ -196,11 +204,7 @@ export declare function cellComponent(cell: BodyCell): Component;
  *  (the gutter's 2 cells), so a long line hard-folds INSIDE the chip
  *  and invariant ① holds on the band. */
 export declare function pendingQueueRows(lines: readonly string[], W: number): string[];
-/** Fold a line's CONTENT at W−2 and prefix EVERY row with the gutter
- *  (W2: a wrapped tool row keeps its state mark — the left edge alone
- *  distinguishes the states at --plain; the UserMessage rail precedent,
- *  v5 #16f). The gutter carries its own SGR (e.g. the bold ✓). W21:
- *  exported for the approval panel's text args (the same │ gutter). */
+export declare function foldWords(line: string, W: number): string[];
 export declare function gutterFold(gutter: string, line: string, W: number): string[];
 /** A6: the tool-header variant — ONE cut row, never a fold. A wide
  *  header (a long target path, a wordy denial reason) used to wrap
@@ -210,12 +214,32 @@ export declare function gutterFold(gutter: string, line: string, W: number): str
  *  full content. The budget: the gutter's own visible width + the
  *  ellipsis ride the row (the invariant ① cap holds). */
 export declare function gutterCut(gutter: string, line: string, W: number): string[];
+export declare function expandSuffix(lines: number | null, room: number): string;
 /** W13 — the rollup opt-in table: which tools collapse, and the count
  *  NOUN (read_file calls → "5 files", list_dir → "5 dirs", search_text
  *  → "5 matches"). Only these tools opt in — a shell burst is never
  *  rolled up (its rows carry meaning). The folded-turn line (W14) reuses
  *  the plurals for its other-tool terms ("2 dirs", "1 match"). */
 export declare const ROLLUP_NOUN: Readonly<Record<string, string>>;
+/** Whether a tool joins an exploration run. Exactly the read-only set —
+ *  writes, edits, shells and extension tools never group (a burst of
+ *  side effects is a list of things that HAPPENED, and every row of it
+ *  carries meaning). */
+export declare function isExploreTool(name: string): boolean;
+/** "8 files · 14 searches" — the per-tool counts in first-call order. */
+export declare function exploreCounts(parts: readonly {
+    name: string;
+    subjects: readonly string[];
+}[]): string;
+/** TUI2-R1 (B) — the expanded list: ONE row per tool, the verb column
+ *  then the distinct subjects in first-call order, a repeated subject
+ *  carrying its ×count, the first three shown and the rest counted.
+ *  A search's subject is its PATTERN (quoted — the thing that was
+ *  looked for); a read's or a list's is its path. */
+export declare function exploreRows(parts: readonly {
+    name: string;
+    subjects: readonly string[];
+}[], W: number): string[];
 /** W14 — the folded-turn line: a whole QUIET turn (no text), once it is
  *  scrollback, becomes ONE line — the work order's claimed shape
  *  (`▞ thought 19s · 5 reads · no edits`), the counts accumulated at

package/dist/components.js

@@ -251,6 +251,66 @@ class ThinkingFold {
  *  distinguishes the states at --plain; the UserMessage rail precedent,
  *  v5 #16f). The gutter carries its own SGR (e.g. the bold ✓). W21:
  *  exported for the approval panel's text args (the same │ gutter). */
+/**
+ * TUI2-R1.5 ⑨ (VD-10) — the WORD-aware fold, for text a human reads.
+ *
+ * foldLine is a hard character fold at the width. That is exactly right
+ * for verbatim tool output, where a byte is a byte and a break is a
+ * display artefact the reader knows to ignore; it is exactly wrong for
+ * prose, where the reader's eye has to reassemble "ex" + "pected" into a
+ * word it already knew. The walkthrough read three of those off one
+ * screen.
+ *
+ * The implementation is a wrapper, not a second engine: the text is cut
+ * at the last space that fits and each resulting segment is handed to
+ * foldLine, which keeps the SGR close/reopen discipline, the display-
+ * width arithmetic and the newline handling in ONE place. A word longer
+ * than the width falls through to foldLine's hard break — an
+ * overflowing row would violate invariant ①, and a word that cannot fit
+ * has to be broken somewhere.
+ */
+/** The SGR spans still open at the end of `text`, given those open at
+ *  its start. A reset closes everything; anything else stacks. */
+function spansOpenAfter(text, before) {
+    let open = [...before];
+    for (const m of text.matchAll(/\x1b\[[0-9;]*m/g)) {
+        if (m[0] === "\x1b[0m")
+            open = [];
+        else
+            open.push(m[0]);
+    }
+    return open;
+}
+export function foldWords(line, W) {
+    if (W < 1)
+        return [line];
+    const out = [];
+    for (const para of line.split("\n")) {
+        if (visibleWidth(para) <= W) {
+            out.push(para);
+            continue;
+        }
+        let rest = para;
+        // the spans open at the cut point, so each emitted row closes them
+        // and the next row reopens them — foldLine's own discipline, applied
+        // across the segments this function creates.
+        let open = [];
+        while (visibleWidth(rest) > W) {
+            // the widest prefix that fits, then back up to the last space in
+            // it — the SGR-aware cut keeps the spans intact
+            const head = widthCut(rest, W);
+            const at = head.lastIndexOf(" ");
+            if (at <= 0)
+                break; // one long word (or no space at all) — hard-break it
+            const cut = head.slice(0, at);
+            out.push(`${cut}${open.length > 0 || /\x1b\[[0-9;]*m/.test(cut) ? "\x1b[0m" : ""}`);
+            open = spansOpenAfter(cut, open);
+            rest = `${open.join("")}${rest.slice(cut.length + 1)}`;
+        }
+        out.push(...foldLine(rest, W));
+    }
+    return out.length > 0 ? out : [""];
+}
 export function gutterFold(gutter, line, W) {
     const textW = Math.max(1, W - 2);
     return foldLine(line, textW).map((r) => `${gutter}${r}`);
@@ -340,6 +400,21 @@ function settledMeta(c) {
  *  read/write/edit → the path, shell → the command, list_dir → path ??
  *  "(root)". Parsed from the FULL input — the folded summary is a
  *  truncated slice. */
+/** TUI2-R1.5 ④(a) (VD-4) — the header text for a cell that has NOT
+ *  settled yet (queued, awaiting approval, running).
+ *
+ *  These three states printed `c.input`: a 60-char slice of the call's
+ *  JSON, escapes and all. The done card printed the plain command
+ *  through toolTarget, so the SAME call read as
+ *  `shell {"command":"for i in 1 2 3 4 5 6; do echo \"step $i · compil`
+ *  while it ran and as `shell for i in 1 2 3 4 5 6; …` a second later.
+ *  One formatter now, for every state. A cell whose full input somehow
+ *  will not parse keeps the old slice — the header always says
+ *  something. */
+function liveTarget(c) {
+    const target = toolTargetOf(c);
+    return escapeTerminal(target === "?" ? c.input : target);
+}
 function toolTargetOf(c) {
     let input = {};
     try {
@@ -381,7 +456,22 @@ class ToolExecution {
         const c = this.cell;
         const verb = escapeTerminal(c.name.replace("_file", ""));
         const verbCol = verb.length < 5 ? `${verb}${" ".repeat(5 - verb.length)}` : verb;
-        const summary = escapeTerminal(c.input);
+        const parts = c.rolled?.parts;
+        if (c.rolled !== null && parts !== undefined) {
+            // TUI2-R1 (B) — the exploration row: a run that spans more than
+            // one read-only tool. The counts are BOLD (what the reader is
+            // being told), the timing and the affordance dim — the
+            // prototype's placement. The affordance names what the key
+            // SHOWS here ("lists them"), because a group row's expand is a
+            // list of calls, not a body of output.
+            const r = c.rolled;
+            const counts = exploreCounts(parts);
+            const head = `${p.bold}✓${p.reset} explored ${p.bold}${counts}${p.reset}`;
+            const tail = ` (${r.elapsed}s)`;
+            const room = W - visibleWidth(head) - tail.length;
+            const affordance = " · ctrl+r lists them";
+            return [cutLine(`${head}${p.dim}${tail}${affordance.length <= room ? affordance : ""}${p.reset}`, W)];
+        }
         if (c.rolled !== null) {
             // W13 — the rolled-up group's ONE row + the target children:
             // the work order's claimed shape, verbatim — the verbCol's
@@ -408,45 +498,223 @@ class ToolExecution {
             // denial appends `· by <decidedBy>` — the aggregated head row
             // names the decider; a human denial (no decidedBy) has no tail.
             if (c.reason !== null) {
-                const by = c.verdict !== null && c.verdict.decidedBy !== undefined ? ` · by ${escapeTerminal(c.verdict.decidedBy)}` : "";
+                const by = attribution(c);
                 const out = gutterCut(`${p.red}✗${p.reset} `, `${p.red}${escapeTerminal(`${c.name} ${toolTargetOf(c)}`)} (${escapeTerminal(c.reason)}${by})${p.reset}`, W);
                 out.push(...toolBlockBody(c, W));
                 return out;
             }
             const elapsed = c.startedAt !== null && c.doneAt !== null ? ((c.doneAt - c.startedAt) / 1000).toFixed(1) : "?";
-            const meta = escapeTerminal(settledMeta(c));
+            // TUI2-R1.5 ⑤ (VD-6): the line count is stated EXACTLY ONCE. Every
+            // read card carried it twice — `(2 lines, 0.0s) · 2 lines · ctrl+r
+            // expands` — because the parens and the suffix were written by
+            // different rounds, each unaware the other was counting. The
+            // SUFFIX keeps it (it is the one that also names the key), so a
+            // meta that says only "<n> lines" drops out when a suffix will
+            // carry it. A meta that says something else — read_file's
+            // "200 of 250 lines", a diff's "+1 -1", a shell's "exit 0" — is a
+            // different fact and stays.
+            const rawMeta = settledMeta(c);
+            const dup = hiddenLines(c, W) !== null && new RegExp(`^${hiddenLines(c, W)} lines?$`).test(rawMeta);
+            const meta = dup ? "" : escapeTerminal(rawMeta);
             // A4: the target rides the settled head row — the verb's
             // summary column (W3's 5-char pad keeps the paths lined up).
             // A5: an extension's auto-approval appends `· approved by
             // <decidedBy>` — the "why wasn't I asked" answer; the human
             // approval (no decidedBy) leaves the row unchanged.
-            const approvedBy = c.verdict !== null && c.verdict.decidedBy !== undefined ? ` · approved by ${escapeTerminal(c.verdict.decidedBy)}` : "";
-            const out = c.isError
-                ? gutterCut(`${p.red}✗${p.reset} `, `${p.red}${verbCol} ${escapeTerminal(toolTargetOf(c))} (${meta}${approvedBy}, ${elapsed}s)${p.reset}`, W)
-                : gutterCut(`${p.bold}✓${p.reset} `, `${verbCol} ${escapeTerminal(toolTargetOf(c))} (${meta}${approvedBy}, ${elapsed}s)`, W);
+            const approvedBy = attribution(c);
+            // TUI2-R1 (A): the card names its own key — the suffix rides the
+            // settled head row.
+            // TUI2-R1.5 ④(c): the suffix is now RESERVED rather than given
+            // the leftovers. It used to take the width that happened to be
+            // left, so a long command spent it all and the row said nothing
+            // about the seven lines behind the key — tolerable while the
+            // body was on screen, a silence now that the body is not. The
+            // command is the cuttable span (the approval panel's option-2
+            // rule name is the same idea); the affordance is the semantics.
+            const hidden = hiddenLines(c, W);
+            // TUI2-R1.5 ⑤: the shortest tier is RESERVED — the affordance is
+            // the semantics. TUI2-R1.5 pin 4: and the parts give way in a
+            // PINNED ORDER, rather than whichever happened to be last.
+            const text = settledHeadText(verbCol, escapeTerminal(toolTargetOf(c)), meta, approvedBy, elapsed, W - 2 - (hidden === null ? 0 : SUFFIX_MIN));
+            const out = c.isError ? [`${p.red}✗${p.reset} ${p.red}${text}${p.reset}`] : [`${p.bold}✓${p.reset} ${text}`];
+            out[0] = appendSuffix(out[0], expandSuffix(hidden, W - visibleWidth(out[0])));
             out.push(...toolBlockBody(c, W));
             return out;
         }
         if (c.state === "approval") {
             // W2: the ⏸ is the GUTTER (the left edge), never the line's tail
-            const out = gutterCut(`${p.bold}⏸${p.reset} `, `${verbCol} ${summary}`, W);
+            const out = gutterCut(`${p.bold}⏸${p.reset} `, `${verbCol} ${liveTarget(c)}`, W);
             out.push(...toolBlockBody(c, W));
             return out;
         }
         if (c.state === "running") {
             // W2: the spinner IS the gutter (the left edge); the elapsed
-            // rides the summary's tail
+            // rides the summary's tail.
+            // TUI2-R1.5 ④(a) (VD-4): the duration is its OWN trailing segment.
+            // It used to be concatenated into the text BEFORE the cut, so a
+            // header wider than the row lost it entirely or, worse, kept it
+            // welded to the last surviving characters of a cut word
+            // ("compil 1s"). The head is cut against the room the duration
+            // leaves; the duration then rides the row, always legible.
             const elapsed = c.startedAt !== null ? Math.max(1, Math.round((ctx.now - c.startedAt) / 1000)) : 1;
-            const out = gutterCut(`${p.bold}${SPINNER[ctx.spinnerI % SPINNER.length]}${p.reset} `, `${verbCol} ${summary} ${elapsed}s`, W);
+            const dur = ` · ${elapsed}s`;
+            const out = gutterCut(`${p.bold}${SPINNER[ctx.spinnerI % SPINNER.length]}${p.reset} `, `${verbCol} ${liveTarget(c)}`, Math.max(4, W - dur.length));
+            out[0] = `${out[0]}${p.dim}${dur}${p.reset}`;
             out.push(...toolBlockBody(c, W));
             return out;
         }
         // W2: ◦ replaces → for QUEUED — · is the separator inside every
         // metadata group; a queued marker that is also the separator
         // glyph reads as noise
-        return gutterCut(`${p.dim}◦${p.reset} `, `${verbCol} ${summary}`, W);
+        return gutterCut(`${p.dim}◦${p.reset} `, `${verbCol} ${liveTarget(c)}`, W);
+    }
+}
+// ---- TUI2-R1 (A): the self-naming expand affordance ----
+/**
+ * TUI2-R1 (A) — how many lines a COLLAPSED settled cell is hiding, or
+ * null when it hides nothing.
+ *
+ * The affordance is a statement about hidden content: a cell whose body
+ * is already whole on screen must not advertise a key that would show it
+ * the same thing, and a cell that already carries its own renderer cut
+ * (`└ +N earlier rows · ctrl+r`, `└ +N more · ctrl+r`) already teaches
+ * the key at the place the content stops. What is LEFT — and it is the
+ * common case — is every settled non-shell call, whose collapsed body is
+ * empty: the whole result sits behind the key with nothing on screen
+ * saying so.
+ *
+ * The count is the RESULT's own line count (the tool's truncation note
+ * included — it is a line the expand will show), never a row count and
+ * never a cap.
+ */
+function hiddenLines(c, W) {
+    if (c.expanded || c.state !== "done" || c.rolled !== null || c.reason !== null)
+        return null;
+    if (c.name === "delegate")
+        return null; // its body is the one-line summary, always whole
+    const n = countLines(c.resultText);
+    if (n === 0)
+        return null;
+    if (c.isError)
+        return null; // errorBody's own cut row is the affordance there
+    // TUI2-R1.5 ④(c) (VD-5): a settled shell renders NO body, so its whole
+    // output is behind the key exactly like every other settled call. The
+    // retired branch only claimed a suffix once the output passed the
+    // five-row cap, because below that the tail was on screen; there is no
+    // tail now, and a card hiding four lines while saying nothing is the
+    // silence TUI2-R1 (A) set out to remove.
+    return n; // every other settled call renders NO body — all of it is behind the key
+}
+/**
+ * TUI2-R1 (A) — the suffix, in the width that is LEFT.
+ *
+ * Three tiers, degrading: the full form teaches the key AND what it
+ * does, the terse form keeps the count and the key, the bare form keeps
+ * the key alone. Below that the row is left exactly as it is today — the
+ * affordance is worth a suffix, never worth cutting the path the row
+ * exists to name (invariant ① holds by construction: the tier is chosen
+ * against the room the row actually has).
+ */
+/** TUI2-R1.5 ⑤ — the cells a settled head row reserves for its
+ *  affordance: exactly the shortest tier, " · ctrl+r". The suffix used
+ *  to take whatever width happened to be left, so a long target spent it
+ *  all and the card said nothing about the lines behind the key. Every
+ *  row that fitted its head before still fits it; only a head that would
+ *  have eaten the whole row gives up its last nine cells. */
+const SUFFIX_MIN = " · ctrl+r".length;
+/**
+ * TUI2-R1.5 pin 4 — the settled head row's text, with a PINNED cut
+ * order.
+ *
+ * The row carries four things of very different value, and until now a
+ * single trailing widthCut decided between them by position: the parens
+ * came last, so the parens were what got cut. The walkthrough caught
+ * both consequences —
+ *
+ *   ✓ shell printf '…' 1 2 … 12 (exit 0 · approv… · ctrl+r
+ *   ✓ shell for i in 1 2 3 …                          … · ctrl+r
+ *
+ * — an UNCLOSED parenthesis, and a row that lost the exit code and the
+ * duration to a command string that had no claim on them. A cut that
+ * leaves `(exit 0 · approv…` has not shortened a fact, it has broken
+ * one: the reader is left holding the beginning of a sentence.
+ *
+ * The order, tightest last:
+ *   1. the affordance is already reserved by the caller (⑤);
+ *   2. the RESULT CORE — `(exit 0, 3.0s)`, `(+1 -1, 0.2s)` — renders
+ *      whole, closing paren included, or not at all;
+ *   3. the ATTRIBUTION segment drops before the core is touched: it is
+ *      a note about who decided, and the result is what happened;
+ *   4. the COMMAND/target truncates with `…`. It is the most
+ *      compressible thing on the row — a reader recognises a command
+ *      from its head — and it is the only part with a natural ellipsis.
+ */
+function settledHeadText(verbCol, target, meta, attr, elapsed, room) {
+    const core = `(${meta === "" ? "" : `${meta}, `}${elapsed}s)`;
+    const withAttr = `(${[meta, attr.replace(" · ", "")].filter((x) => x !== "").join(" · ")}${meta === "" && attr === "" ? "" : ", "}${elapsed}s)`;
+    const lead = `${verbCol} `;
+    const fit = (t, parens) => {
+        const line = `${lead}${t}${parens === "" ? "" : ` ${parens}`}`;
+        return visibleWidth(line) <= room ? line : null;
+    };
+    // 1. everything
+    const full = fit(target, withAttr);
+    if (full !== null)
+        return full;
+    // 2. the attribution gives way
+    const bare = fit(target, core);
+    if (bare !== null)
+        return bare;
+    // 3. the target truncates, the core stays whole
+    const budget = room - visibleWidth(lead) - visibleWidth(core) - 2; // the space + the ellipsis
+    if (budget >= 1)
+        return `${lead}${widthCut(target, budget)}… ${core}`;
+    // 4. below that even the core cannot ride: the row is the call's
+    //    identity and its affordance, and no half-open parenthesis.
+    return `${lead}${widthCut(target, Math.max(1, room - visibleWidth(lead)))}`;
+}
+/**
+ * TUI2-R1.5 ⑤ (VD-11) — approval attribution, about humans.
+ *
+ * A5 put the DECIDER on the settled head row to answer "why wasn't I
+ * asked". The walkthrough found the answer being given nine times in a
+ * row as `approved by mode:default` — and `mode:default` is not an
+ * answer. It is the runtime's own backfill (run.ts stamps it when no
+ * policy expressed an opinion at all), so the row was announcing the
+ * ambient default as though something had decided.
+ *
+ * The signal is inverted and reduced to the fact worth a human's eye:
+ * `decidedBy` PRESENT means a policy handled it — ambient, unremarkable,
+ * silent. `decidedBy` ABSENT means the human was asked and answered, and
+ * that is worth recording on the row: ` · approved`, ` · denied`.
+ */
+function attribution(c) {
+    if (c.verdict === null || c.verdict.decidedBy !== undefined)
+        return "";
+    return c.verdict.decision === "denied" ? " · denied" : " · approved";
+}
+export function expandSuffix(lines, room) {
+    if (lines === null)
+        return "";
+    const count = `${lines} line${lines === 1 ? "" : "s"}`;
+    for (const tier of [` · ${count} · ctrl+r expands`, ` · ${count} · ctrl+r`, " · ctrl+r"]) {
+        if (tier.length <= room)
+            return tier;
     }
+    return "";
 }
+/** The suffix as the row's dim tail (the empty suffix leaves the row's
+ *  bytes untouched — a caller never has to branch). */
+function appendSuffix(row, suffix) {
+    if (suffix === "")
+        return row;
+    const p = palette();
+    return `${row}${p.dim}${suffix}${p.reset}`;
+}
+/** TUI2-R1 (A) — the expanded block's last row: the way back. The
+ *  rollup's expanded list carries a second clause (its members' full
+ *  outputs live in /last, which the group row cannot show). */
+const COLLAPSE_ROW = "ctrl+r collapses";
 /** W13 — the rollup opt-in table: which tools collapse, and the count
  *  NOUN (read_file calls → "5 files", list_dir → "5 dirs", search_text
  *  → "5 matches"). Only these tools opt in — a shell burst is never
@@ -457,6 +725,61 @@ export const ROLLUP_NOUN = {
     list_dir: "dirs",
     search_text: "matches",
 };
+// ---- TUI2-R1 (B): the exploration rollup ----
+/** TUI2-R1 (B) — the exploration row's nouns. Deliberately NOT
+ *  ROLLUP_NOUN: that table says what a SINGLE-tool rollup counts
+ *  ("5 matches"), and this row counts CALLS across tools, where
+ *  "14 searches" is what happened. Both tables stay — changing the
+ *  older one would move an assertion this round did not declare. */
+const EXPLORE_NOUN = {
+    read_file: ["file", "files"],
+    list_dir: ["dir", "dirs"],
+    search_text: ["search", "searches"],
+};
+/** TUI2-R1 (B) — the verb column of the expanded list. `search_text`
+ *  reads as "search" there: the column names the ACT, and the raw tool
+ *  name is what the cut notes carry (they name what the model calls). */
+const EXPLORE_VERB = { read_file: "read", list_dir: "list", search_text: "search" };
+/** Whether a tool joins an exploration run. Exactly the read-only set —
+ *  writes, edits, shells and extension tools never group (a burst of
+ *  side effects is a list of things that HAPPENED, and every row of it
+ *  carries meaning). */
+export function isExploreTool(name) {
+    return EXPLORE_NOUN[name] !== undefined;
+}
+/** "8 files · 14 searches" — the per-tool counts in first-call order. */
+export function exploreCounts(parts) {
+    return parts
+        .map((part) => {
+        const [singular, plural] = EXPLORE_NOUN[part.name] ?? ["call", "calls"];
+        return `${part.subjects.length} ${part.subjects.length === 1 ? singular : plural}`;
+    })
+        .join(" · ");
+}
+/** TUI2-R1 (B) — the expanded list: ONE row per tool, the verb column
+ *  then the distinct subjects in first-call order, a repeated subject
+ *  carrying its ×count, the first three shown and the rest counted.
+ *  A search's subject is its PATTERN (quoted — the thing that was
+ *  looked for); a read's or a list's is its path. */
+export function exploreRows(parts, W) {
+    const p = palette();
+    const rows = [];
+    for (const part of parts) {
+        const counts = new Map();
+        for (const s of part.subjects)
+            counts.set(s, (counts.get(s) ?? 0) + 1);
+        const shown = [...counts.entries()].slice(0, 3).map(([s, n]) => (n > 1 ? `${s} ×${n}` : s));
+        const more = counts.size > 3 ? ` (+${counts.size - 3})` : "";
+        const verb = EXPLORE_VERB[part.name] ?? part.name;
+        rows.push(cutLine(`${p.dim}${BODY_ROW}${escapeTerminal(`${verb.padEnd(6)} ${shown.join(" · ")}${more}`)}${p.reset}`, W));
+    }
+    // TUI2-R1.5 ① (VD-15): the footer used to promise "/last shows the full
+    // outputs". /last shows the LAST call only — for a nine-call burst that
+    // is one output out of nine, and a footer that sends the human to a
+    // place the content is not is worse than a footer that says nothing.
+    rows.push(cutLine(`${p.dim}${CUT_ROW}${COLLAPSE_ROW}${p.reset}`, W));
+    return rows;
+}
 /** The count term with the singular/plural forms — "no reads", "1 read",
  *  "5 reads". The noun's singular drops the plural suffix ("dirs" → "dir",
  *  "matches" → "match"). */
@@ -556,19 +879,33 @@ function toolBlockBody(c, W) {
                 ? errorBody(c, W)
                 : c.name === "delegate"
                     ? delegateSettled(c, W)
-                    : c.name.startsWith("shell")
-                        ? shellTail(c.resultText, W)
-                        : []
+                    : // TUI2-R1.5 ④(c) (VD-5): a settled shell collapses like
+                        // every other settled call. It used to keep its last
+                        // rows plus a "+N earlier rows · ctrl+r" cut FOREVER —
+                        // six rows per call, so three shells owned a screen. The
+                        // approved R1 prototype's state 2 is one line; the head
+                        // row's own suffix already names the count and the key,
+                        // and ctrl+r shows the whole block, not a five-row window
+                        // of it.
+                        []
             : c.state === "running"
                 ? c.name === "delegate"
                     ? delegateRunning(c, W)
-                    : liveWindow(c.resultText, W)
+                    : c.name === "shell"
+                        ? shellLiveTail(c.resultText, W)
+                        : liveWindow(c.resultText, W)
                 : c.state === "approval"
                     ? diffBody(c.diff, W)
                     : [];
     const note = c.expanded ? null : toolCutNote(c.name, c.resultText);
     if (note !== null)
         rows.push(...foldLine(`${p.dim}${CUT_ROW}${note}${p.reset}`, W));
+    // TUI2-R1 (A): an EXPANDED block says how to put it back. The footer
+    // rides a block that HAS rows — an expanded delegate whose summary
+    // marker is missing renders nothing, and a lone footer under a head
+    // row would be an affordance for an empty block.
+    if (c.expanded && rows.length > 0)
+        rows.push(...foldLine(`${p.dim}${CUT_ROW}${COLLAPSE_ROW}${p.reset}`, W));
     blockMemo.set(c, { width: W, state, content, rows });
     return rows;
 }
@@ -639,6 +976,49 @@ function liveWindow(text, W) {
     const cut = foldLine(`${p.dim}${CUT_ROW}+${rows.length - (CAP_LIVE_WINDOW - 1)} earlier rows · ctrl+r${p.reset}`, W);
     return [...rows.slice(rows.length - (CAP_LIVE_WINDOW - 1)), ...cut];
 }
+/**
+ * TUI2-R1 (C) — the RUNNING shell's live tail.
+ *
+ * The rows are the sidecar's last lines, NEWEST AT THE BOTTOM (a tail
+ * grows downward, and the row nearest the footer is the newest thing the
+ * command said). The window is the SAME three rows W8 fixed: two tail
+ * rows and the footer, blank-padded before the output fills them, so the
+ * block's height still changes exactly once — at settle.
+ *
+ * With nothing observed the shape is exactly today's "waiting for
+ * output": a sidecar that never appeared, a command that has not
+ * printed, and a temp dir that refused the write are indistinguishable
+ * from here, and all three mean the same thing — nothing to show.
+ *
+ * The footer names the state AND the two gestures that apply while a
+ * command runs, because this is precisely when a human wants them.
+ */
+function shellLiveTail(text, W) {
+    if (text === "")
+        return liveWindow("", W);
+    const p = palette();
+    // TUI2-R1.5 ④(b) (VD-4): the tail's first row is never a blank gutter.
+    // Two sources, both fixed here, and the W8 fixed-window height is kept
+    // by both fixes:
+    //  - leading empty lines in the sidecar (a 4096-byte tail can begin on
+    //    a line boundary, and the reader's .trimEnd only trims the other
+    //    end) are skipped;
+    //  - the short-output pad moved from the TOP to the BOTTOM. It exists
+    //    so the block's height never changes while the command runs (W8);
+    //    at the top it put an empty row above the command's very first
+    //    line, which is the frame the walkthrough filed. At the bottom the
+    //    output starts under its own header and grows downward, and the
+    //    height is just as fixed.
+    const all = blockRows(text, W);
+    const from = all.findIndex((r) => visibleWidth(r) > visibleWidth(BODY_ROW));
+    const rows = from < 0 ? [] : all.slice(from);
+    if (rows.length === 0)
+        return liveWindow("", W);
+    const kept = rows.slice(Math.max(0, rows.length - (CAP_LIVE_WINDOW - 1)));
+    while (kept.length < CAP_LIVE_WINDOW - 1)
+        kept.push(`${p.dim}${BODY_ROW}${p.reset}`);
+    return [...kept, cutLine(`${p.dim}${CUT_ROW}live tail · esc stop · alt+⏎ redirect${p.reset}`, W)];
+}
 /** W12: the delegate's child sessions collapse to the tool row plus ONE
  *  line — the height NEVER changes (running → settled replaces the row
  *  in place). The running row derives from the INPUT: the parent has no
@@ -748,8 +1128,10 @@ class AssistantMessage {
         this.cell = cell;
     }
     render(W, _ctx) {
+        // TUI2-R1.5 9 (VD-10): the model's prose is the clearest case of
+        // text a human reads — it wraps at word boundaries.
         const text = escapeTerminal(this.cell.text);
-        const wrapped = foldLine(text, W);
+        const wrapped = foldWords(text, W);
         return wrapped.length > 0 ? wrapped.map((l) => colorInlineCode(l)) : [""];
     }
 }
@@ -760,7 +1142,8 @@ class ErrorLine {
         this.cell = cell;
     }
     render(W, _ctx) {
-        return foldLine(escapeTerminal(this.cell.text), W);
+        // TUI2-R1.5 9 (VD-10): a notice is a sentence addressed to a human.
+        return foldWords(escapeTerminal(this.cell.text), W);
     }
 }
 /** The CLI's pre-rendered blocks (the banner, the recap, slash-command
@@ -773,7 +1156,12 @@ class RawBlock {
         this.cell = cell;
     }
     render(W, _ctx) {
-        return this.cell.lines.flatMap((l) => foldLine(l, W));
+        // TUI2-R1.5 9 (VD-10): the raw channel carries BOTH kinds of text —
+        // /help's sentences and /last's verbatim tool output — so the
+        // CALLER says which it is. Verbatim is the default: a surface that
+        // has not thought about it must not have its bytes reflowed.
+        const fold = this.cell.wrap === "words" ? foldWords : foldLine;
+        return this.cell.lines.flatMap((l) => fold(l, W));
     }
 }
 /** The terminal label + the status line. W11: the rhythm gap blank is

package/dist/diff.d.ts

@@ -20,13 +20,33 @@ export interface DiffResult {
     lines: DiffLine[];
     added: number;
     removed: number;
+    /** TUI2-R1.5 ② (VD-2): the search is not in the file — the tool will
+     *  ERROR, so the panel shows the honest note carried in `lines` and
+     *  never a diff. Absent on every real diff. */
+    notFound?: true;
 }
 /** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
 export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
-/** edit_file: the search→replace windows replace in place — the changed
- *  region is KNOWN, so the diff is the old window vs the new window,
- *  context from the surrounding file. */
-export declare function editFileDiff(oldContent: string, search: string, replace: string): DiffResult;
+/** edit_file: the preview of a CHARACTER splice.
+ *
+ *  TUI2-R1.5 ② (VD-2): the locator is the tool's own, verbatim — the
+ *  workspace edit_file does `i = text.indexOf(search)` and writes
+ *  `text.slice(0, i) + replace + text.slice(i + search.length)`. This
+ *  function mirrors those two lines and diffs the result against the
+ *  original; it does not model the edit, it reproduces it.
+ *
+ *  The retired locator required the search to align to FULL LINES. A
+ *  mid-line search ("// OLD" inside "  // OLD") therefore missed, and
+ *  the miss branch rendered the WHOLE FILE as the old side: a one-line
+ *  edit was drawn as a catastrophic rewrite, on the approval panel, at
+ *  the moment a human was deciding whether to allow it. A preview that
+ *  can be that wrong is worse than no preview.
+ *
+ *  A genuine miss is now reported as a miss: the tool will return
+ *  `pattern not found in <path>` and change nothing, so the panel says
+ *  exactly that instead of inventing a diff for an edit that will not
+ *  happen. `path` names the file in that note. */
+export declare function editFileDiff(oldContent: string, search: string, replace: string, path?: string): DiffResult;
 /** write_file: a new file is all +; an existing file diffs row-level
  *  against its old content. */
 export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;

package/dist/diff.js

@@ -91,23 +91,37 @@ function stats(diff) {
     }
     return { added, removed };
 }
-/** edit_file: the search→replace windows replace in place — the changed
- *  region is KNOWN, so the diff is the old window vs the new window,
- *  context from the surrounding file. */
-export function editFileDiff(oldContent, search, replace) {
-    const oldLines = oldContent.split("\n");
-    const searchLines = search.split("\n");
-    const replaceLines = replace.split("\n");
-    // Locate the search window (the first occurrence — the edit tool's own
-    // semantics); no occurrence → the whole file is the old side.
-    let at = -1;
-    for (let i = 0; i + searchLines.length <= oldLines.length; i += 1) {
-        if (oldLines.slice(i, i + searchLines.length).join("\n") === search) {
-            at = i;
-            break;
-        }
+/** edit_file: the preview of a CHARACTER splice.
+ *
+ *  TUI2-R1.5 ② (VD-2): the locator is the tool's own, verbatim — the
+ *  workspace edit_file does `i = text.indexOf(search)` and writes
+ *  `text.slice(0, i) + replace + text.slice(i + search.length)`. This
+ *  function mirrors those two lines and diffs the result against the
+ *  original; it does not model the edit, it reproduces it.
+ *
+ *  The retired locator required the search to align to FULL LINES. A
+ *  mid-line search ("// OLD" inside "  // OLD") therefore missed, and
+ *  the miss branch rendered the WHOLE FILE as the old side: a one-line
+ *  edit was drawn as a catastrophic rewrite, on the approval panel, at
+ *  the moment a human was deciding whether to allow it. A preview that
+ *  can be that wrong is worse than no preview.
+ *
+ *  A genuine miss is now reported as a miss: the tool will return
+ *  `pattern not found in <path>` and change nothing, so the panel says
+ *  exactly that instead of inventing a diff for an edit that will not
+ *  happen. `path` names the file in that note. */
+export function editFileDiff(oldContent, search, replace, path) {
+    const at = oldContent.indexOf(search);
+    if (at < 0) {
+        return {
+            lines: [{ kind: " ", text: `pattern not found in ${path ?? "the file"}` }],
+            added: 0,
+            removed: 0,
+            notFound: true,
+        };
     }
-    const lines = at < 0 ? withContext(lcsDiff(oldLines, replaceLines)) : withContext(lcsDiff(oldLines, [...oldLines.slice(0, at), ...replaceLines, ...oldLines.slice(at + searchLines.length)]));
+    const result = oldContent.slice(0, at) + replace + oldContent.slice(at + search.length);
+    const lines = withContext(lcsDiff(oldContent.split("\n"), result.split("\n")));
     return { lines, ...stats(lines) };
 }
 /** write_file: a new file is all +; an existing file diffs row-level

package/dist/index.d.ts

@@ -6,10 +6,11 @@
  * package); the cli never imports it directly. Experimental — no
  * API-stability promise yet.
  */
-export { SPINNER, foldLine, visibleWidth, bodySpacing, Container, cellComponent, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, type FrameCtx, type RenderLine, type Component, type BodyCell, } from "./components.js";
+export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, type FrameCtx, type RenderLine, type Component, type BodyCell, } from "./components.js";
 export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
 export { pendingQueueRows } from "./components.js";
 export { charWidth, displayWidth, leadWidth, widthOf } from "./width.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 { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, type PanelArgs, type PanelFlavor, type PanelPhase, type PanelSel, type PanelState, type PanelVerdict, type PanelView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, } from "./approval-panel.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact, } from "./strings.js";
+export { extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, colorInlineCode, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type ResumeMeta, } from "./render.js";

package/dist/index.js

@@ -6,7 +6,7 @@
  * package); the cli never imports it directly. Experimental — no
  * API-stability promise yet.
  */
-export { SPINNER, foldLine, visibleWidth, bodySpacing, Container, cellComponent, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, } from "./components.js";
+export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, } from "./components.js";
 export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
 // W22 (the v8 input round): the pending-queue chips — the SAME
 // UserMessage chip with the □ gutter, pre-rendered above the input
@@ -23,4 +23,6 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 // listing/view/note, the uncertain execution's view. The flow stays in
 // the cli; what the human reads is presentation.
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, } from "./strings.js";
+// KC3.5: the interrupted-ask copy and the extracted /help table.
+export { extensionsBannerText, helpRows, unansweredAskView } from "./strings.js";
 export { bannerLines, COLOR_OFF, COLOR_ON, colorInlineCode, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";

package/dist/strings.d.ts

@@ -58,3 +58,103 @@ export declare function projectUntrustedNote(count: number, root: string): strin
  *  question because it reaches the terminal as raw text there; the
  *  panel's own rows are escaped by the panel renderer. */
 export declare function uncertainView(name: string, executionId: string): PanelView;
+/**
+ * KC3.5 — the SAME uncertainty gate, said honestly for an ask_user call.
+ *
+ * "Did the interrupted execution apply?" is the right question for a
+ * side effect and the wrong one for a question: nothing applied, the
+ * human simply never answered. The COPY special-cases ask_user; the
+ * mechanism does not — the verdict still maps to the runtime's own
+ * rerun/abandoned resolution, whose error-fill text is untouched.
+ *
+ * (The round's ① probe pinned why this surface exists at all: the
+ * shipped recovery blocks on a started-unreported execution regardless
+ * of idempotency, so an interrupted ask meets this gate on the way
+ * back. Re-asking is safe — that is what "1 re-ask" says out loud.)
+ */
+export declare function unansweredAskView(executionId: string): PanelView;
+/** An extension as the banner names it — the live `connecting` flag is
+ *  the MCP bridge's in-flight state ("mcp (connecting…)"). Structural on
+ *  purpose: the runtime's KisoExtension satisfies it without this
+ *  package importing the runtime. */
+export interface BannerExtension {
+    readonly name: string;
+    readonly connecting?: boolean;
+}
+/**
+ * KC3.5 slice ⓪ (the extraction) — the `[N extensions: …]` banner text:
+ * the built-in column, then the user-level names, then the project-level
+ * ones marked `project:`.
+ *
+ * A pure function of three name lists, so what the banner SAYS is
+ * testable without a terminal — which matters this round, because the
+ * count is where the ask's TTY gate becomes visible: an interactive
+ * session reads `built-in: mcp, skills, subagent, ask` and a piped one
+ * reads `built-in: mcp, skills, subagent`, from this one composition.
+ */
+export declare function extensionsBannerText(builtIn: readonly BannerExtension[], user: readonly BannerExtension[], project: readonly BannerExtension[]): string;
+/** One gesture: what you press, and what it does. */
+export interface KeyBinding {
+    readonly keys: string;
+    readonly what: string;
+}
+/**
+ * TUI2-R1 (D) — THE key table. Every reader derives from it: the `?`
+ * sheet and /help's keys row. A sheet that has drifted from the keys is
+ * worse than no sheet, and the only way to make drift impossible is to
+ * have one table and no second copy of it.
+ *
+ * The order is the sheet's reading order, which is why it is grouped by
+ * WHAT A HUMAN IS DOING rather than alphabetically: the three ways to
+ * put something in (send, newline, files), the three ways to change
+ * course (stop, redirect, commands), then the walks (history, expand),
+ * then the completions.
+ */
+export declare const KEY_BINDINGS: readonly KeyBinding[];
+/** The panel keys, which belong to a panel rather than the composer —
+ *  one dim line rather than four table rows, because they apply only
+ *  while a panel is up. */
+/**
+ * TUI2-R1.5 pin 6 — this row has to be true of BOTH panel flavors, and
+ * "digits select" was wrong in both directions at once.
+ *
+ * On an APPROVAL a digit only moves the selection (editor's #panelSelect
+ * sets `sel` and renders); ENTER is what resolves it. A reader who
+ * pressed 1 and walked away had approved nothing — the worst kind of
+ * false affordance, on the surface where the stakes are a side effect.
+ *
+ * On an ASK the opposite: a digit on a SINGLE-choice question answers it
+ * and advances the walk (ask-panel's askKey → advance), so "select"
+ * undersold it. A multi-select question toggles and waits for enter,
+ * like the approval.
+ *
+ * "digits pick · ⏎ confirms" is the sentence both flavors satisfy. The
+ * single-choice fast path — where the confirm is implicit — is the one
+ * thing a single row cannot also carry; it is an omission, never a lie.
+ */
+export declare const PANEL_KEYS_ROW = "panels: digits pick \u00B7 \u23CE confirms \u00B7 space toggles \u00B7 t types an answer";
+/**
+ * TUI2-R1 (D) — the sheet, one screen, static.
+ *
+ * Rows CUT at the width rather than folding: the sheet's contract with
+ * the reader is "one screen", and a folded grid at 40 columns is two
+ * screens pretending to be one. A narrow terminal shows fewer columns
+ * of the same truth, which is the honest degradation.
+ */
+export declare function keysSheetRows(W: number): string[];
+/** TUI2-R1 (D) — the keys as ONE line, for /help. The same table the
+ *  sheet renders, joined — so the two can disagree only by deleting a
+ *  test. The sheet is the readable form; this is the greppable one. */
+export declare function keysHelpRow(): string;
+/**
+ * KC3.5 slice ⓪ (the extraction) — the /help command table.
+ *
+ * The rows were eight bodyLog calls in the CLI's dispatcher; they are
+ * presentation, and presentation belongs here (the KC3 §1 pattern —
+ * the FLOW, which is "print these on the chain, then re-prompt", stays
+ * in dispatch.ts). The last row carries its own newline exactly as it
+ * did inline: bodyLog splits on \n, so `exit` and `keys` land as two
+ * rows from one call — the shape the KC1/KC2/KC3 gestures were added
+ * to, unchanged.
+ */
+export declare function helpRows(): string[];

package/dist/strings.js

@@ -18,6 +18,7 @@
  * looked up here.
  */
 import { escapeTerminal, palette } from "./render.js";
+import { displayWidth } from "./width.js";
 /** v2a: the interactive prompt — the identity accent. readline owns the
  *  echo of what the user types; we own the prompt's color. (v2c: the
  *  readline prompt keeps "you> " — the brick ▌ is the dock's row only;
@@ -79,3 +80,215 @@ export function uncertainView(name, executionId) {
         fallbackQuestion: `⚠ interrupted execution: ${escapeTerminal(name)} (${executionId}) — did it apply? (y)es / (n)o `,
     };
 }
+/**
+ * KC3.5 — the SAME uncertainty gate, said honestly for an ask_user call.
+ *
+ * "Did the interrupted execution apply?" is the right question for a
+ * side effect and the wrong one for a question: nothing applied, the
+ * human simply never answered. The COPY special-cases ask_user; the
+ * mechanism does not — the verdict still maps to the runtime's own
+ * rerun/abandoned resolution, whose error-fill text is untouched.
+ *
+ * (The round's ① probe pinned why this surface exists at all: the
+ * shipped recovery blocks on a started-unreported execution regardless
+ * of idempotency, so an interrupted ask meets this gate on the way
+ * back. Re-asking is safe — that is what "1 re-ask" says out loud.)
+ */
+export function unansweredAskView(executionId) {
+    return {
+        flavor: "simple",
+        name: "unanswered question",
+        title: `ask_user (${executionId})`,
+        speaker: "kiso",
+        statusText: "▸ unanswered question",
+        args: { kind: "text", lines: [executionId] },
+        ruleOverride: "an unanswered question was interrupted — ask it again? — 1 re-ask · 3 drop",
+        fallbackQuestion: `⚠ an unanswered question was interrupted (${executionId}) — ask it again? (y)es / (n)o `,
+    };
+}
+/**
+ * KC3.5 slice ⓪ (the extraction) — the `[N extensions: …]` banner text:
+ * the built-in column, then the user-level names, then the project-level
+ * ones marked `project:`.
+ *
+ * A pure function of three name lists, so what the banner SAYS is
+ * testable without a terminal — which matters this round, because the
+ * count is where the ask's TTY gate becomes visible: an interactive
+ * session reads `built-in: mcp, skills, subagent, ask` and a piped one
+ * reads `built-in: mcp, skills, subagent`, from this one composition.
+ */
+export function extensionsBannerText(builtIn, user, project) {
+    const total = builtIn.length + user.length + project.length;
+    if (total === 0)
+        return "";
+    const label = (e) => (e.connecting === true ? `${e.name} (connecting…)` : e.name);
+    const parts = [];
+    if (builtIn.length > 0)
+        parts.push(`built-in: ${builtIn.map(label).join(", ")}`);
+    if (user.length > 0)
+        parts.push(user.map(label).join(", "));
+    if (project.length > 0)
+        parts.push(`project: ${project.map(label).join(", ")}`);
+    return ` · [${total} extension${total === 1 ? "" : "s"}: ${parts.join(" · ")}]`;
+}
+/**
+ * TUI2-R1 (D) — THE key table. Every reader derives from it: the `?`
+ * sheet and /help's keys row. A sheet that has drifted from the keys is
+ * worse than no sheet, and the only way to make drift impossible is to
+ * have one table and no second copy of it.
+ *
+ * The order is the sheet's reading order, which is why it is grouped by
+ * WHAT A HUMAN IS DOING rather than alphabetically: the three ways to
+ * put something in (send, newline, files), the three ways to change
+ * course (stop, redirect, commands), then the walks (history, expand),
+ * then the completions.
+ */
+export const KEY_BINDINGS = [
+    { keys: "enter", what: "send" },
+    { keys: "ctrl+j / shift+⏎", what: "newline" },
+    { keys: "@", what: "files" },
+    { keys: "esc", what: "stop" },
+    { keys: "alt+⏎ / ctrl+⏎", what: "redirect" },
+    { keys: "/", what: "commands" },
+    { keys: "↑↓", what: "history / queue pop" },
+    { keys: "ctrl+r", what: "expand cells" },
+    { keys: "tab", what: "complete (menu / @)" },
+    { keys: "?", what: "this sheet" },
+];
+/** The panel keys, which belong to a panel rather than the composer —
+ *  one dim line rather than four table rows, because they apply only
+ *  while a panel is up. */
+/**
+ * TUI2-R1.5 pin 6 — this row has to be true of BOTH panel flavors, and
+ * "digits select" was wrong in both directions at once.
+ *
+ * On an APPROVAL a digit only moves the selection (editor's #panelSelect
+ * sets `sel` and renders); ENTER is what resolves it. A reader who
+ * pressed 1 and walked away had approved nothing — the worst kind of
+ * false affordance, on the surface where the stakes are a side effect.
+ *
+ * On an ASK the opposite: a digit on a SINGLE-choice question answers it
+ * and advances the walk (ask-panel's askKey → advance), so "select"
+ * undersold it. A multi-select question toggles and waits for enter,
+ * like the approval.
+ *
+ * "digits pick · ⏎ confirms" is the sentence both flavors satisfy. The
+ * single-choice fast path — where the confirm is implicit — is the one
+ * thing a single row cannot also carry; it is an omission, never a lie.
+ */
+export const PANEL_KEYS_ROW = "panels: digits pick · ⏎ confirms · space toggles · t types an answer";
+/** The sheet's grid: the first six bindings in two 3-column rows, the
+ *  last four in two 2-column rows (the wide entries get the room). The
+ *  COLUMN STOPS are the prototype's absolute positions, floored by the
+ *  content (a future binding widens its column rather than overrunning
+ *  it — the grid degrades to one space, never to a collision). */
+const SHEET_GRID = [
+    [0, 1, 2],
+    [3, 4, 5],
+    [6, 7],
+    [8, 9],
+];
+const SHEET_STOPS = [
+    [16, 43],
+    [16, 43],
+    [36],
+    [36],
+];
+/**
+ * TUI2-R1 (D) — the sheet, one screen, static.
+ *
+ * Rows CUT at the width rather than folding: the sheet's contract with
+ * the reader is "one screen", and a folded grid at 40 columns is two
+ * screens pretending to be one. A narrow terminal shows fewer columns
+ * of the same truth, which is the honest degradation.
+ */
+export function keysSheetRows(W) {
+    const p = palette();
+    const cell = (i) => {
+        const b = KEY_BINDINGS[i];
+        return b === undefined ? "" : `${p.code}${b.keys}${p.reset} ${b.what}`;
+    };
+    const plainCell = (i) => {
+        const b = KEY_BINDINGS[i];
+        return b === undefined ? "" : `${b.keys} ${b.what}`;
+    };
+    const rows = [`${p.bold}keys${p.reset}`];
+    for (let r = 0; r < SHEET_GRID.length; r += 1) {
+        const indexes = SHEET_GRID[r];
+        let row = "";
+        let width = 0;
+        for (let c = 0; c < indexes.length; c += 1) {
+            row += cell(indexes[c]);
+            width += displayWidth(plainCell(indexes[c]));
+            const stop = SHEET_STOPS[r][c];
+            if (stop === undefined)
+                continue; // the last column pads nothing
+            const pad = Math.max(1, stop - width);
+            row += " ".repeat(pad);
+            width += pad;
+        }
+        rows.push(row);
+    }
+    rows.push(`${p.dim}${PANEL_KEYS_ROW}${p.reset}`);
+    return rows.map((row) => cutRow(row, W));
+}
+/** One row, cut at the width — SGR-aware, the ellipsis after the reset
+ *  (the cutLine convention; duplicated here rather than imported so the
+ *  strings module keeps its no-components-dependency shape). */
+function cutRow(row, W) {
+    let out = "";
+    let width = 0;
+    for (let i = 0; i < row.length;) {
+        if (row[i] === "\x1b") {
+            const m = /^\x1b\[[0-9;]*m/.exec(row.slice(i))?.[0] ?? row[i];
+            out += m;
+            i += m.length;
+            continue;
+        }
+        const cw = displayWidth(row[i]);
+        if (width + cw > W)
+            return `${out}${palette().reset}`;
+        out += row[i];
+        width += cw;
+        i += 1;
+    }
+    return out;
+}
+/** TUI2-R1 (D) — the keys as ONE line, for /help. The same table the
+ *  sheet renders, joined — so the two can disagree only by deleting a
+ *  test. The sheet is the readable form; this is the greppable one. */
+export function keysHelpRow() {
+    return KEY_BINDINGS.map((b) => `${b.keys} ${b.what}`).join(" · ");
+}
+/**
+ * KC3.5 slice ⓪ (the extraction) — the /help command table.
+ *
+ * The rows were eight bodyLog calls in the CLI's dispatcher; they are
+ * presentation, and presentation belongs here (the KC3 §1 pattern —
+ * the FLOW, which is "print these on the chain, then re-prompt", stays
+ * in dispatch.ts). The last row carries its own newline exactly as it
+ * did inline: bodyLog splits on \n, so `exit` and `keys` land as two
+ * rows from one call — the shape the KC1/KC2/KC3 gestures were added
+ * to, unchanged.
+ */
+export function helpRows() {
+    const p = palette();
+    const cmd = (name, desc) => `${p.bold}${name}${p.reset}    ${desc}`;
+    return [
+        cmd("/help", "print this list of commands"),
+        cmd("/think", "show the last full thinking block"),
+        cmd("/last", "show the most recent tool call's input and output"),
+        cmd("/status", "show session id, event count, and context estimate"),
+        cmd("/mode", "show the approval tier; /mode <name> switches (manual/default/accept-edits/plan/bypass)"),
+        cmd("/model", "list model profiles; /model <name|provider/model> switches"),
+        cmd("/compact", "summarize the older conversation to free context"),
+        // TUI2-R1 (D): DELIBERATELY UNCHANGED. Deriving this sentence from
+        // KEY_BINDINGS would be an improvement and it would also move an
+        // assertion outside the round's two declared supersession classes,
+        // so the sheet is the derived surface and this row keeps its bytes.
+        // `keysHelpRow()` exists for the round that is allowed to make the
+        // swap; until then the drift guard is the test that every binding
+        // in the table is mentioned here.
+        `${cmd("exit", "leave the session")}\n${cmd("keys", "enter sends · ctrl+J newline (shift+enter where encoded) · esc stops the run · alt+⏎ stops it and sends this instead · @ files · 1-4 answers an ask")}`,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tui-cells",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "kiso tui-cells — the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
   "type": "module",
   "license": "MIT",