pi-pier 0.2.7 → 0.3.0

package/README.md

@@ -43,14 +43,25 @@ The installer also verifies node / pi / herdr versions, probes local paths, and
 | Tool | Purpose |
 |---|---|
 | `todo_write` | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Projected live onto the pane title (`▶i ○p ■b ✓c (N/M) · current task`). `/todos` command to view/edit/unblock |
-| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume` |
+| `subagent` | Delegate self-contained subtasks to an isolated pi session in its own herdr pane. Actions: `spawn` (default; foreground / parallel / background), `list`, `send`, `interrupt`, `resume`, `output` (incremental preview of a running subagent's pane output) |
 | `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
-| `ask_user_question` | Human gate: structured options plus Other; pane shows blocked in herdr while waiting |
+| `ask_user_question` | Human gate: 2-5 authored options plus a trailing free-text row (`allowOther: false` for pure choice); multiple related questions per call. A `multi: true` question opens an interactive toggle list (space toggles, `a` all, enter confirms, esc declines); pane shows blocked in herdr while waiting |
+
+### Commands
+
+| Command | Purpose |
+|---|---|
+| `/todos` | Show the todo list, or edit it: `/todos done|drop|rm|unblock <fuzzy match>` |
+| `/locks` | Show write locks held by this pane and by live panes — the **human/operator view** of the write-lock beacons (herdr only). Agents see the holders inside their own write warnings; the raw tokens are readable via `herdr agent list` |
+| `/pier-config` | Read-only configuration guide over five planes: bare call = index + hands a guided change to the agent; `show [plane\|all]` = effective value + source (`env > workspace > user > default`); `check` = validate all planes; `doc [path]` = write a report |
 
 ### Behaviors
 
 - **Human-in-the-loop**: every subagent is a visible, interactive TUI pane — step into it anytime to talk directly (fix bugs, take over, answer its `ask_user_question`). Blocked gates raise sidebar markers + notifications
-- **Soft locks**: write paths lock per-pane; conflicts warn/block instead of racing
+- **Blocking dialogs block the pane**: pi's `ui_prompt_start` / `ui_prompt_end` events cover the inherently blocking `ctx.ui` dialogs (`select` / `confirm` / `input` / `editor`), so a dialog from any extension (not only pier's own ask tool) reports the pane as blocked and emits the `herdr:blocked` edge; nested gates are coalesced. `custom` is excluded because pi also routes resident overlays through it (pier's slim-frame overlay never calls `done()`, and a resident overlay keeps pi's prompt span open anyway)
+- **Role gate stops early**: a tool call denied by the role manifest returns `terminate`, so a batch whose results are all terminating ends without another model round trip
+- **Readable transcript**: pier's own session entries (todo edits, subagent/terminal registries, role manifests, soft approvals) and its reminder messages render as compact cards instead of raw JSON
+- **Soft locks**: write paths register per-pane beacons; conflicts warn (default) or block (`PI_HERDR_WRITE_LOCK=1`) instead of racing silently. Warnings name **every** holder — the audience split is: agent reads its own tool-result warning, human reads `/locks` (or `herdr agent list` for the raw token table). `write`/`edit` only — `bash` writes are not covered
 - **Role profiles**: built-in `master` / `worker-default`; custom roles mount from `.pi-herdr/roles/<name>.json`. Toolsets converge per role — deny rules cannot be bypassed
 - **Settlement notices folded**: background subagent completions inject between turns (max 3 shown, rest collapsed) instead of flood-filling at run end
 
@@ -61,10 +72,12 @@ This extension mutates the pi session even outside herdr. After `pi install npm:
 | Surface | Bare `pi` (no `HERDR_ENV`) | Inside herdr |
 |---|---|---|
 | `todo_write`, `/todos`, widget, anti-freeze, stop reminder | live | live |
-| `ask_user_question` | live (TUI select/input) | live + blocked marker |
+| `ask_user_question` | live (TUI select/input; multi questions use the toggle list) | live + blocked marker |
+| Blocked reporting for blocking `ctx.ui` dialogs (`ui_prompt_start/end`, `select`/`confirm`/`input`/`editor`) | live | live + blocked marker |
 | Hidden inject (`before_agent_start` todo-read; settle reminder) | live | live |
 | `subagent`, `terminal` | **not registered** | live |
 | `/locks`, write-lock on `write`/`edit` | not installed | live |
+| `/pier-config` (read-only config guide over 5 planes) | live | live |
 | slim-frame overlay, pane title, pipe, isolate worktree | off | live |
 | `setActiveTools` role visible layer | off | on (herdr master) |
 
@@ -91,15 +104,15 @@ pi overwrites tools/commands by name; event listeners stack.
 ## Requirements
 
 - Node ≥ 22
-- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only the todo loop and `ask_user_question` load
+- pi ≥ 0.84.4 (`@earendil-works/pi-coding-agent`)
+- **herdr ≥ 0.9.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only the todo loop and `ask_user_question` load
 
 ## Development
 
 ```sh
 git clone https://github.com/July24/pier && cd pier
 npm install --ignore-scripts
-npm test   # node --test, ~250 unit tests
+npm test   # node --test, ~590 unit tests
 ```
 
 See the [monorepo README](https://github.com/July24/pier) for design principles, the herdr-plugin half, and the one-shot installer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
   "license": "MIT",
   "type": "module",
@@ -39,6 +39,10 @@
       "./skills/pi-herdr-workflow"
     ]
   },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test \"test/*.test.ts\""
+  },
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.1",
     "@deepseek-ai/cordis-plugin-group": "^1.0.1",
@@ -50,6 +54,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
-    "typebox": "~1.3.7"
+    "typebox": "~1.3.7",
+    "typescript": "~5.9.3"
   }
 }

package/schemas/efficiency-config.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://herdr-pi.local/schemas/efficiency-config.schema.json",
+  "title": "pier efficiency configuration (D100-D103)",
+  "type": "object",
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "onlineContextCompact": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用待办驱动的在线上下文压缩" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录在线压缩的决策与节省量日志" },
+        "cacheWriteReadRatio": {
+          "oneOf": [
+            { "type": "number", "minimum": 0 },
+            { "type": "string", "enum": ["auto"] }
+          ],
+          "default": "auto",
+          "description": "KV 缓存写入与读取成本比。auto 表示从 ctx.model.cost 自动推导"
+        },
+        "firstCompactionRequestScale": { "type": "number", "default": 2.0, "minimum": 1.0 },
+        "subsequentCompactionMargin": { "type": "number", "default": 1.5, "minimum": 1.0 },
+        "keepRecentTokens": {
+          "type": "integer",
+          "default": 20000,
+          "minimum": 1000,
+          "description": "原生压缩保留区大小（同时用于 archiveTokens 估算与 nativeCompactionFeasible 预检）。缺省自动继承 pi 的 compaction.keepRecentTokens 设置（默认 20000）。"
+        }
+      },
+      "additionalProperties": false
+    },
+    "observationPack": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用大工具输出冷热分级打包" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录观察结果打包与召回日志" },
+        "thresholdBytes": { "type": "integer", "default": 10240, "minimum": 1024 },
+        "fullSends": { "type": "integer", "default": 2, "minimum": 1 },
+        "recallChunkBytes": { "type": "integer", "default": 16384, "minimum": 1024 },
+        "excerptBytes": { "type": "integer", "default": 1024, "minimum": 128 }
+      },
+      "additionalProperties": false
+    },
+    "evidencePreservingReducer": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用长测试日志保真提炼" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否记录提炼比对、耗时与回退日志" },
+        "model": {
+          "type": "string",
+          "description": "专用的轻量 Reducer 模型 (provider/model)。缺省使用当前模型并在日志中提示经济性"
+        },
+        "minBytes": { "type": "integer", "default": 4096, "minimum": 512 },
+        "maxChars": { "type": "integer", "default": 600000 },
+        "maxOutputTokens": { "type": "integer", "default": 2048 },
+        "timeoutMs": { "type": "integer", "default": 5000, "description": "同步拦截超时上限，默认 5 秒避免阻塞" },
+        "localOnly": { "type": "boolean", "default": false, "description": "仅本地归档长日志并跳过模型提炼" }
+      },
+      "additionalProperties": false
+    },
+    "jev": {
+      "type": "object",
+      "description": "jev 决策层（RFC docs/rfc-jev-integration.md）：可选的 System One 分类调用，逐点 fail-open",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "是否启用 jev 决策层（还需配置 apiKey 才会真正发起调用）" },
+        "logEnabled": { "type": "boolean", "default": false, "description": "是否写 efficiency-logs/jev.jsonl（不记录请求/响应 body）" },
+        "baseUrl": { "type": "string", "description": "API 根地址覆盖（中转/网关）；缺省 https://api.typesafe.ai" },
+        "model": { "type": "string", "default": "jev-1.13.0", "description": "钉住的版本化模型 id；别名会静默漂移导致校准阈值失真" },
+        "timeoutMs": { "type": "integer", "default": 2000, "minimum": 500, "description": "单次调用总预算（AbortController 硬杀，SDK 无总预算模式）" },
+        "minConfidence": { "type": "number", "default": 0.6, "minimum": 0, "maximum": 1, "description": "Choice/Score 答案被采纳的最低置信度，低于则按未回答处理" },
+        "apiKey": { "type": "string", "description": "API key。解析优先级：PIER_JEV_API_KEY 环境变量 > 此处 > TYPESAFE_API_KEY 环境变量" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/skills/pi-herdr-workflow/SKILL.md

@@ -88,6 +88,18 @@ The ledger is an append-only JSONL file at `~/.pi/agent/herdr-pi/history/<flatte
 
 Call: `subagent(action: "resume", taskId: "<uuid>")`
 
+## 2.5 Configuration questions
+
+When the user asks about pier/pi configuration (or asks to change it), start from the read-only
+guide instead of guessing: `/pier-config show all` reports every knob's **effective value and
+source** (`env > workspace > user > default`), `check` validates all five planes (efficiency
+D100–D103, roles, pi settings, boot-config, `PIER_*`/`PI_HERDR_*` env), and `doc` writes a report
+into `<repo>/.pi-herdr/config-report.md`. Bare `/pier-config` injects the full guided-change
+workflow. Key rules: an untrusted project's workspace layer is ignored (report it, never edit
+blindly); pi-owned settings go through pi's own `/settings`; prefer
+`npx pier-setup@latest update --force` for boot-config; change one plane at a time and show a diff
+before writing. Overview: `docs/configuration.md`.
+
 ## 3. Human gate
 
 - For a human decision (approval, tradeoff, direction), use `ask_user_question` (this plugin). Prefer 2-5 options with short labels and tradeoffs in `description`. Do **not** author an "Other" option — the UI appends "Other (type your own)". Use `recommended` (0-based) for the default and `questions` to batch related decisions (max 4). While waiting, your pane is **blocked** in herdr so the human can see and intervene. The answer comes back as the tool result, then you continue.

package/src/ansi-text.ts

@@ -0,0 +1,83 @@
+/**
+ * ANSI-aware text measurement and clipping for pier's TUI surfaces.
+ *
+ * Why a local implementation: the todo widget, the pinned pane title and the
+ * ask_user_question multi-select all need width-correct clipping, but importing
+ * `visibleWidth`/`truncateToWidth` from pi-tui would make those paths depend on a
+ * package that may be absent in stripped installs. The table below only has to be
+ * right for ASCII plus the CJK/emoji ranges that actually appear in user content.
+ */
+
+const SGR = /\x1b\[[0-9;]*m/y;
+
+/** Approximate terminal cell width of one code point (0, 1 or 2). */
+export function charWidth(cp: number): number {
+  if (cp < 32) return 0;
+  if (cp >= 0x7f && cp < 0xa0) return 0;
+  if (cp >= 0x0300 && cp <= 0x036f) return 0; // combining marks
+  if (
+    (cp >= 0x1100 && cp <= 0x115f)
+    || (cp >= 0x2e80 && cp <= 0x303e)
+    || (cp >= 0x3041 && cp <= 0x33ff)
+    || (cp >= 0x3400 && cp <= 0x4dbf)
+    || (cp >= 0x4e00 && cp <= 0x9fff)
+    || (cp >= 0xa000 && cp <= 0xa4cf)
+    || (cp >= 0xac00 && cp <= 0xd7a3)
+    || (cp >= 0xf900 && cp <= 0xfaff)
+    || (cp >= 0xfe30 && cp <= 0xfe6f)
+    || (cp >= 0xff00 && cp <= 0xff60)
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** Rendered cell width of a string that may contain SGR sequences (zero width). */
+export function styledWidth(line: string): number {
+  let width = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    width += charWidth(cp);
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return width;
+}
+
+/**
+ * Cut a styled line to `width` cells without breaking escape sequences.
+ * Wide glyphs count as two cells, so CJK content stays inside the frame.
+ */
+export function truncateStyled(line: string, width: number): string {
+  if (width <= 0) return '';
+  if (styledWidth(line) <= width) return line;
+  const keep = Math.max(0, width - 1); // reserve one cell for the ellipsis
+  let out = '';
+  let used = 0;
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      out += m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    if (used + w > keep) break;
+    out += cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    used += w;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return `${out}\x1b[0m…`;
+}

package/src/ask-multi.ts

@@ -0,0 +1,260 @@
+/**
+ * ask_user_question multi-select: pure state machine + a thin TUI component.
+ *
+ * Why: the previous multi path asked the human to *type* "1,3" into a text prompt,
+ * which is the weakest part of the human gate. This module renders a real toggle
+ * list (space to toggle, enter to confirm, esc to decline) with the authored
+ * choices, an optional trailing free-text row, and a live selection count.
+ *
+ * The transition function is pure so the UX is testable without a terminal; the
+ * component only maps keys to it. Installing the free-text row is opt-out
+ * (`allowOther: false`) for pure-choice questions.
+ */
+import { truncateStyled } from './ansi-text.ts';
+
+export interface MultiSelectOption {
+  label: string;
+  description?: string;
+}
+
+export interface MultiSelectConfig {
+  options: readonly MultiSelectOption[];
+  /** Render the trailing free-text row (pi-herdr's "Other"). */
+  allowOther: boolean;
+  /** 0-based index of the recommended option, marked in the list. */
+  recommended?: number;
+}
+
+export interface MultiSelectState {
+  /** Cursor row: 0..options.length-1 are choices, options.length is the Other row. */
+  cursor: number;
+  /** Toggle state per authored option (never includes the Other row). */
+  selected: readonly boolean[];
+}
+
+export type MultiSelectKey = 'up' | 'down' | 'toggle' | 'confirm' | 'cancel' | 'all' | 'ignore';
+
+export type MultiSelectOutcome =
+  | { kind: 'selected'; labels: string[] }
+  | { kind: 'other' }
+  | { kind: 'cancel' };
+
+export interface MultiSelectStep {
+  state: MultiSelectState;
+  outcome?: MultiSelectOutcome;
+}
+
+export function createMultiSelectState(config: MultiSelectConfig): MultiSelectState {
+  return { cursor: 0, selected: config.options.map(() => false) };
+}
+
+/** Total rows including the optional Other row; the cursor wraps inside this. */
+export function rowCount(config: MultiSelectConfig): number {
+  return config.options.length + (config.allowOther ? 1 : 0);
+}
+
+export function isOtherRow(state: MultiSelectState, config: MultiSelectConfig): boolean {
+  return config.allowOther && state.cursor === config.options.length;
+}
+
+export function selectedLabels(state: MultiSelectState, config: MultiSelectConfig): string[] {
+  const labels: string[] = [];
+  config.options.forEach((option, i) => {
+    if (state.selected[i]) labels.push(option.label);
+  });
+  return labels;
+}
+
+/** Apply one key. A returned outcome ends the interaction. */
+export function stepMultiSelect(state: MultiSelectState, key: MultiSelectKey, config: MultiSelectConfig): MultiSelectStep {
+  const rows = rowCount(config);
+  if (rows === 0) return key === 'cancel' ? { state, outcome: { kind: 'cancel' } } : { state };
+  switch (key) {
+    case 'cancel':
+      return { state, outcome: { kind: 'cancel' } };
+    case 'up':
+    case 'down': {
+      const delta = key === 'up' ? -1 : 1;
+      const cursor = (state.cursor + delta + rows) % rows;
+      return { state: { ...state, cursor } };
+    }
+    case 'all': {
+      const anyUnselected = state.selected.some((v) => !v);
+      return { state: { ...state, selected: state.selected.map(() => anyUnselected) } };
+    }
+    case 'toggle': {
+      if (isOtherRow(state, config)) return { state };
+      const selected = state.selected.map((v, i) => (i === state.cursor ? !v : v));
+      return { state: { ...state, selected } };
+    }
+    case 'confirm': {
+      if (isOtherRow(state, config)) return { state, outcome: { kind: 'other' } };
+      // Enter on a choice row confirms the current toggles; a single-choice
+      // question (multi: false) needs no separate space press.
+      if (config.options.length === 1) {
+        return { state, outcome: { kind: 'selected', labels: [config.options[0]!.label] } };
+      }
+      return { state, outcome: { kind: 'selected', labels: selectedLabels(state, config) } };
+    }
+    default:
+      return { state };
+  }
+}
+
+/* ── Key matching ──────────────────────────────────────────────────── */
+
+export type KeyMatcher = (data: string, key: Exclude<MultiSelectKey, 'ignore'>) => boolean;
+
+/**
+ * Fallback matcher for raw key sequences, used when pi-tui cannot be imported.
+ * Ordering inside `handleInput` matters for escape: arrow sequences are matched
+ * before the bare ESC key because both start with 0x1b.
+ */
+export const FALLBACK_KEY_SEQUENCES: Record<Exclude<MultiSelectKey, 'ignore'>, readonly string[]> = {
+  up: ['\x1b[A', '\x1bOA', 'k'],
+  down: ['\x1b[B', '\x1bOB', 'j'],
+  toggle: [' '],
+  confirm: ['\r', '\n'],
+  cancel: ['\x1b', '\x03'],
+  all: ['a', 'A'],
+};
+
+export const fallbackKeyMatcher: KeyMatcher = (data, key) => FALLBACK_KEY_SEQUENCES[key].includes(data);
+
+/**
+ * Prefer pi-tui's `matchesKey` (it understands terminal variations and keybindings
+ * remaps); fall back to the built-in sequences when the package is unavailable.
+ */
+export async function loadKeyMatcher(): Promise<KeyMatcher> {
+  try {
+    const tui = await import('@earendil-works/pi-tui') as {
+      matchesKey?: (data: string, key: unknown) => boolean;
+      Key?: Record<string, unknown>;
+    };
+    const Key = tui.Key;
+    if (typeof tui.matchesKey === 'function' && Key && typeof Key.up === 'string') {
+      const map: Record<string, unknown> = {
+        up: Key.up,
+        down: Key.down,
+        toggle: Key.space,
+        confirm: Key.enter,
+        cancel: Key.escape,
+        all: 'a',
+      };
+      return (data, key) => tui.matchesKey!(data, map[key]);
+    }
+  } catch {
+    /* pi-tui absent: use the built-in sequences. */
+  }
+  return fallbackKeyMatcher;
+}
+
+/* ── TUI component ─────────────────────────────────────────────────── */
+
+export interface MinimalTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+export interface MultiSelectComponent {
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+}
+
+export interface MultiSelectUiOptions {
+  title: string;
+  config: MultiSelectConfig;
+  theme: MinimalTheme;
+  matcher: KeyMatcher;
+  /** Called with the outcome; the host resolves ctx.ui.custom. */
+  done(outcome: MultiSelectOutcome): void;
+  /** Ask for the gate label used by the renderer (tests only). */
+  requestRender?: () => void;
+}
+
+const RECOMMENDED = ' (Recommended)';
+
+export function multiSelectLines(state: MultiSelectState, config: MultiSelectConfig, theme: MinimalTheme): string[] {
+  const lines: string[] = [];
+  config.options.forEach((option, i) => {
+    const cursor = i === state.cursor ? theme.fg('accent', '> ') : '  ';
+    const box = state.selected[i] ? theme.fg('success', '[x]') : '[ ]';
+    const label = `${option.label}${config.recommended === i ? RECOMMENDED : ''}`;
+    const styled = state.selected[i] ? theme.bold(label) : label;
+    const desc = option.description ? theme.fg('dim', ` — ${option.description}`) : '';
+    lines.push(`${cursor}${box} ${styled}${desc}`);
+  });
+  if (config.allowOther) {
+    const cursor = isOtherRow(state, config) ? theme.fg('accent', '> ') : '  ';
+    lines.push(`${cursor}${theme.fg('dim', '[ ] Other (type your own)')}`);
+  }
+  return lines;
+}
+
+export function multiSelectFooter(state: MultiSelectState, config: MultiSelectConfig, theme: MinimalTheme): string {
+  const picked = selectedLabels(state, config).length;
+  const count = picked > 0 ? theme.fg('success', ` · ${picked} selected`) : '';
+  return theme.fg('dim', '↑/↓ move · space toggle · a all · enter confirm · esc cancel') + count;
+}
+
+export function createMultiSelectComponent(opts: MultiSelectUiOptions): MultiSelectComponent {
+  let state = createMultiSelectState(opts.config);
+  let finished = false;
+  const finish = (outcome: MultiSelectOutcome): void => {
+    if (finished) return;
+    finished = true;
+    opts.done(outcome);
+  };
+  return {
+    render(width: number): string[] {
+      const head = opts.theme.bold(opts.title);
+      const body = multiSelectLines(state, opts.config, opts.theme);
+      const footer = multiSelectFooter(state, opts.config, opts.theme);
+      return [head, ...body, '', footer].map((line) => truncateStyled(line, width));
+    },
+    handleInput(data: string): void {
+      if (finished) return;
+      // Arrow sequences are checked before the bare ESC key (shared 0x1b prefix).
+      const key: MultiSelectKey = opts.matcher(data, 'up') ? 'up'
+        : opts.matcher(data, 'down') ? 'down'
+        : opts.matcher(data, 'toggle') ? 'toggle'
+        : opts.matcher(data, 'confirm') ? 'confirm'
+        : opts.matcher(data, 'cancel') ? 'cancel'
+        : opts.matcher(data, 'all') ? 'all'
+        : 'ignore';
+      if (key === 'ignore') return;
+      const next = stepMultiSelect(state, key, opts.config);
+      state = next.state;
+      opts.requestRender?.();
+      if (next.outcome) finish(next.outcome);
+    },
+    invalidate(): void { /* No cached lines. */ },
+  };
+}
+
+/**
+ * Run the toggle list through `ctx.ui.custom`.
+ * Returns null when the host cannot render custom components (RPC mode / older pi),
+ * so the caller can fall back to the typed-index prompt.
+ */
+export async function runMultiSelect(
+  custom: (factory: unknown) => Promise<unknown>,
+  title: string,
+  config: MultiSelectConfig,
+): Promise<MultiSelectOutcome | null> {
+  const matcher = await loadKeyMatcher();
+  const result = await custom((tui: unknown, theme: unknown, _keybindings: unknown, done: (value: unknown) => void) =>
+    createMultiSelectComponent({
+      title,
+      config,
+      theme: theme as MinimalTheme,
+      matcher,
+      done: (outcome) => done(outcome),
+      requestRender: () => (tui as { requestRender?: () => void } | undefined)?.requestRender?.(),
+    }));
+  if (result === undefined || result === null) return null;
+  const outcome = result as MultiSelectOutcome;
+  if (outcome.kind === 'cancel' || outcome.kind === 'other' || outcome.kind === 'selected') return outcome;
+  return null;
+}