pi-pier 0.3.0 → 0.4.1

package/README.md

@@ -1,7 +1,7 @@
 # pi-pier
 
 > [!IMPORTANT]
-> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`; `subagent` / `terminal` are not registered. Pane integration, notifications, and workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
+> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`; `subagent` / `terminal` are not registered. Pane integration and notifications require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
 
 **pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
 
@@ -21,7 +21,7 @@ pi install git:github.com/July24/pier
 
 ## Install the herdr half (companion plugin)
 
-The herdr plugin `pier.workbench` provides the other half: main-tab bootstrap (auto-start a pi master session per workspace), blocked-gate notifications (system notifications when a subagent waits for a human), and the focus-heat layout (focused pane grows in place). Install it from the same repo:
+The herdr plugin `pier.workbench` provides the other half: blocked-gate notifications (system notifications when a subagent waits for a human), the focus-heat layout (focused pane grows in place), and the ops dashboard / sidebar agent view. Install it from the same repo:
 
 ```sh
 herdr plugin install July24/pier/packages/pier-workbench --yes
@@ -31,10 +31,10 @@ Or install **both halves at once** with the one-shot installer from the monorepo
 
 ```sh
 git clone https://github.com/July24/pier && cd pier
-node install.mjs        # user mode: installs both halves + generates local bootstrap config
+node install.mjs        # user mode: installs both halves
 ```
 
-The installer also verifies node / pi / herdr versions, probes local paths, and writes the workbench bootstrap config (`boot-config.json`) into herdr's plugin config dir.
+The installer also verifies node / pi / herdr versions.
 
 ## What you get
 
@@ -43,26 +43,30 @@ 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`, `output` (incremental preview of a running subagent's pane output) |
+| `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), `role` (switch that worker's role profile mid-session — pi records the toolset change as a transcript delta, so it applies on the worker's next request and survives resume). Every spawned task gets a stable slug: outputs print `slug@paneId`, and `agentId` accepts the slug, the pane id, or the combined form |
+| `report_progress` | Worker panes only: send the delegating master a short checkpoint update without ending the task. Arrives in the master's context as a display-less custom message (no turn, no chat flood), rendered as a `⤴ progress` card |
 | `terminal` | Persistent interactive shells in dedicated herdr panes. Actions: `open`, `send`, `read`, `signal`, `close`, `list` |
-| `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>` |
+| `/dashboard [overlay]` | Ops dashboard. Default opens the shared Pier **popup** on its `Dashboard` tab (90% × 80%, singleton); `overlay` opens the same view as an independent full-window pane. Non-Herdr falls back to an in-pane text view. |
+| `/pier-tree [overlay]` | Master only: the full delegation tree — your complete todo list plus every running subagent's full list (live-pushed over the pipe) and settled nodes with ages. Default opens the same shared popup on its `Tree` tab (the snapshot refreshes on every todo/worker push; `1`/`2`/`Tab` switch views inside the popup); `overlay` opens an independent full-window pane; bare pi / a missing plugin falls back to the in-pane notify view. The resident widget stays one line per agent and hides entirely once the self list is fully completed (D113/D114) |
 | `/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 |
+| `/pier-role` | Show the current role + available role names, or switch mid-session: `/pier-role <name>` (widening beyond the current toolset asks for confirmation; the switch lands as a transcript tool delta) |
+| `/pier-config` | Read-only configuration guide over four 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
+- **Delegation identity**: the worker knows who delegated it — spawn env (`PI_HERDR_DELEGATION`) replays through the worker marker and the session's own first-frame entry; its system prompt carries a `pier-delegation` section (identity + delivery contract), the transcript opens with an "⟵ delegated by master …" card, the pane title gets an `↳` prefix, and `pi-parent`/`pi-task` tokens feed the workbench dashboard tree and blocked-alert attribution
 - **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
+- **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. A role manifest may carry `guidelines` (behavior constraints a toolset cannot express); they ride the system prompt as a `pier-role` section each turn. Masters can switch a worker's role remotely via `subagent action:"role"`; humans can switch the pane they are in via `/pier-role`
 - **Settlement notices folded**: background subagent completions inject between turns (max 3 shown, rest collapsed) instead of flood-filling at run end
 
 ## Scope & degradation
@@ -72,12 +76,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; multi questions use the toggle list) | live + blocked marker |
+| `ask_user_question` | live (TUI picker for single and multi; host select dialog / typed prompts as RPC fallback) | 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 |
+| `/pier-config` (read-only config guide over 4 planes) | live | live |
 | slim-frame overlay, pane title, pipe, isolate worktree | off | live |
 | `setActiveTools` role visible layer | off | on (herdr master) |
 
@@ -104,8 +108,8 @@ pi overwrites tools/commands by name; event listeners stack.
 ## Requirements
 
 - Node ≥ 22
-- 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
+- pi ≥ 1.3.0 (`@earendil-works/pi-coding-agent`) — `before_agent_start.messageType` and resumed-session active tools
+- **herdr ≥ 0.9.5** — required for subagents / pane integration / notifications (see the IMPORTANT note above); native `pane.focused`, self-reported resume, and shutdown-safe session saves restore subagent panes after a server restart
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -49,11 +49,11 @@
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.3.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-coding-agent": "1.3.0",
     "typebox": "~1.3.7",
     "typescript": "~5.9.3"
   }

package/schemas/role-manifest.schema.json

@@ -8,7 +8,13 @@
     "role": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "角色名，须与文件名一致" },
     "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "语义版本 x.y.z" },
     "model": { "type": "string", "pattern": "^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$", "description": "按角色路由模型 provider/model（WS-D10；可省略 = 进程默认）" },
-    "description": { "type": "string" },
+    "guidelines": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "P0 per-role 行为约束（RFC §4.6）：工具集表达不了的“怎么用”约束，每轮作为 pier-role prompt section 注入；空数组请省略"
+    },
     "manifest": {
       "type": "object",
       "properties": {

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

@@ -92,13 +92,12 @@ Call: `subagent(action: "resume", taskId: "<uuid>")`
 
 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
+source** (`env > workspace > user > default`), `check` validates all four planes (efficiency
+D100–D103, roles, pi settings, `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`.
+blindly); pi-owned settings go through pi's own `/settings`; change one plane at a time and show a
+diff before writing. Overview: `docs/configuration.md`.
 
 ## 3. Human gate
 

package/src/ansi-text.ts

@@ -1,16 +1,14 @@
 /**
  * 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.
+ * 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;
@@ -35,7 +33,7 @@ export function charWidth(cp: number): number {
   return 1;
 }
 
-/** Rendered cell width of a string that may contain SGR sequences (zero width). */
+/** Rendered cell width; SGR sequences count as zero cells. */
 export function styledWidth(line: string): number {
   let width = 0;
   let i = 0;
@@ -53,10 +51,7 @@ export function styledWidth(line: string): number {
   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.
- */
+/** Cut to `width` cells without breaking escape sequences; wide glyphs count as two cells. */
 export function truncateStyled(line: string, width: number): string {
   if (width <= 0) return '';
   if (styledWidth(line) <= width) return line;
@@ -81,3 +76,59 @@ export function truncateStyled(line: string, width: number): string {
   }
   return `${out}\x1b[0m…`;
 }
+
+/**
+ * Wrap to `width` cells, preferring space breaks and never splitting a wide glyph or an escape
+ * sequence. Open SGR codes are re-emitted at continuation starts so a style spanning the break (a
+ * dim description) survives; emitted lines end with a reset when a style is open.
+ */
+export function wrapStyled(line: string, width: number): string[] {
+  if (width <= 0) return [''];
+  const out: string[] = [];
+  let current = '';
+  let used = 0;
+  let spaceAt = -1; // index in `current` of the last breakable space
+  let open = '';    // SGR codes active at the scan position
+  let i = 0;
+  while (i < line.length) {
+    SGR.lastIndex = i;
+    const m = SGR.exec(line);
+    if (m && m.index === i) {
+      current += m[0];
+      open = m[0] === '\x1b[0m' ? '' : open + m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = line.codePointAt(i)!;
+    const w = charWidth(cp);
+    const chunk = cp > 0xffff ? line.slice(i, i + 2) : line[i]!;
+    if (used + w > width && used > 0) {
+      // A space that overflows breaks there; otherwise rewind to the last space so words stay whole.
+      const atSpace = chunk === ' ';
+      const head = !atSpace && spaceAt > 0 ? current.slice(0, spaceAt) : current;
+      const tail = !atSpace && spaceAt > 0 ? current.slice(spaceAt + 1) : '';
+      out.push(head.replace(/ +$/, '') + (open ? '\x1b[0m' : ''));
+      current = open + tail;
+      used = styledWidth(tail);
+      const tailSpace = tail.lastIndexOf(' ');
+      spaceAt = tailSpace > 0 ? open.length + tailSpace : -1;
+      if (atSpace) i += 1; // the breaking space is consumed, not re-processed
+      continue; // re-evaluate the pending char on the fresh line
+    }
+    if (used + w > width) {
+      // A glyph wider than the whole line (width 1): emit it alone.
+      out.push(current + chunk + (open ? '\x1b[0m' : ''));
+      current = open;
+      used = 0;
+      spaceAt = -1;
+      i += cp > 0xffff ? 2 : 1;
+      continue;
+    }
+    current += chunk;
+    used += w;
+    if (chunk === ' ') spaceAt = current.length - 1;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  if (current || out.length === 0) out.push(current);
+  return out;
+}

package/src/ask-dialog.ts

@@ -0,0 +1,308 @@
+/**
+ * ask_user_question dialog: one pier-owned selector for single- and multi-select questions, rendered
+ * through `ctx.ui.custom`. Both modes share it so the chrome — border rules, accent+bold title,
+ * `→ ` cursor, dim descriptions, keyHint footer — cannot diverge; only the checkbox column, the
+ * hints and the selection counter are mode-specific.
+ */
+import { styledWidth, truncateStyled, wrapStyled } from './ansi-text.ts';
+
+/** Label of the trailing free-text row; ask-user reuses it for the typed fallback list. */
+export const OTHER_ROW_LABEL = 'Other (type your own)';
+
+/** Marker the UI appends to the recommended row; the typed fallback list uses the same one. */
+export const RECOMMENDED_SUFFIX = ' (Recommended)';
+
+interface DialogOption {
+  label: string;
+  description?: string;
+}
+
+export interface DialogConfig {
+  options: readonly DialogOption[];
+  allowOther: boolean;
+  /** 0-based recommended option: the cursor starts on it, and multi mode also starts with it
+   *  checked so a bare enter agrees with single mode in both modes. */
+  recommended?: number;
+  /** true = toggle list (space toggles, enter confirms the set); false = pick-one (enter/space takes the cursor row). */
+  multi: boolean;
+}
+
+export interface DialogState {
+  /** 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[];
+}
+
+type DialogKey = 'up' | 'down' | 'toggle' | 'confirm' | 'cancel' | 'all' | 'ignore';
+
+export type DialogOutcome =
+  | { kind: 'selected'; labels: string[] }
+  | { kind: 'other' }
+  | { kind: 'cancel' };
+
+export interface DialogStep {
+  state: DialogState;
+  outcome?: DialogOutcome;
+}
+
+export function createDialogState(config: DialogConfig): DialogState {
+  const hasRecommended =
+    config.recommended !== undefined
+    && config.recommended >= 0
+    && config.recommended < config.options.length;
+  const start = hasRecommended ? config.recommended! : 0;
+  return {
+    cursor: start,
+    selected: config.options.map((_, i) => config.multi && hasRecommended && i === start),
+  };
+}
+
+export function rowCount(config: DialogConfig): number {
+  return config.options.length + (config.allowOther ? 1 : 0);
+}
+
+export function isOtherRow(state: DialogState, config: DialogConfig): boolean {
+  return config.allowOther && state.cursor === config.options.length;
+}
+
+export function selectedLabels(state: DialogState, config: DialogConfig): 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 stepDialog(state: DialogState, key: DialogKey, config: DialogConfig): DialogStep {
+  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': {
+      if (!config.multi) return { state };
+      const anyUnselected = state.selected.some((v) => !v);
+      return { state: { ...state, selected: state.selected.map(() => anyUnselected) } };
+    }
+    case 'toggle':
+    case 'confirm': {
+      if (isOtherRow(state, config)) return { state, outcome: { kind: 'other' } };
+      if (!config.multi) {
+        // Pick-one: enter and space both take the cursor row.
+        return { state, outcome: { kind: 'selected', labels: [config.options[state.cursor]!.label] } };
+      }
+      if (key === 'toggle') {
+        const selected = state.selected.map((v, i) => (i === state.cursor ? !v : v));
+        return { state: { ...state, selected } };
+      }
+      // Enter on a choice row confirms the current toggles; a single-choice
+      // question 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 };
+  }
+}
+
+/** The slice of pi's KeybindingsManager custom factories receive as 3rd arg. */
+export interface KeybindingsLike {
+  matches(data: string, keybinding: string): boolean;
+  getKeys(keybinding: string): string[];
+}
+
+/** Key resolution, in order (first match wins). `binding` is the host action id consulted when the
+ *  factory received a keybindings manager; `sequences` are the raw fallbacks used when it did not
+ *  (older hosts, tests). Mirrors pi's defaults, plus j/k for vim keys; `toggle` has no pi action. */
+const KEY_RESOLUTION: ReadonlyArray<{ key: DialogKey; binding?: string; sequences: readonly string[] }> = [
+  { key: 'up', binding: 'tui.select.up', sequences: ['\x1b[A', '\x1bOA', 'k'] },
+  { key: 'down', binding: 'tui.select.down', sequences: ['\x1b[B', '\x1bOB', 'j'] },
+  { key: 'toggle', sequences: [' '] },
+  { key: 'confirm', binding: 'tui.select.confirm', sequences: ['\r', '\n'] },
+  { key: 'cancel', binding: 'tui.select.cancel', sequences: ['\x1b', '\x03'] },
+];
+
+export function resolveDialogKey(data: string, keybindings?: KeybindingsLike): DialogKey {
+  for (const entry of KEY_RESOLUTION) {
+    if (entry.binding !== undefined && keybindings?.matches?.(data, entry.binding) === true) return entry.key;
+    if (entry.sequences.includes(data)) return entry.key;
+  }
+  return data === 'a' || data === 'A' ? 'all' : 'ignore';
+}
+
+export interface MinimalTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+interface DialogComponent {
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+}
+
+interface DialogUiOptions {
+  title: string;
+  config: DialogConfig;
+  theme: MinimalTheme;
+  keybindings?: KeybindingsLike;
+  /** Aborting cancels the dialog so the ask tool result and herdr gate settle. */
+  signal?: AbortSignal;
+  /** pi's ctrl+o tool-output expansion, when the host exposes it. */
+  toggleToolsExpanded?: () => void;
+  done(outcome: DialogOutcome): void;
+  requestRender?: () => void;
+}
+
+/** Numbered line for the typed-prompt fallback list (`1. Label (Recommended) — description`); the dialog
+ *  itself renders unnumbered rows. */
+export function numberedOptionLine(option: DialogOption, index: number, recommended?: number): string {
+  const marker = recommended === index ? RECOMMENDED_SUFFIX : '';
+  const description = option.description ? ` — ${option.description}` : '';
+  return `${index + 1}. ${option.label}${marker}${description}`;
+}
+
+export function dialogLines(state: DialogState, config: DialogConfig, theme: MinimalTheme): string[] {
+  const lines: string[] = [];
+  config.options.forEach((option, i) => {
+    const onCursor = i === state.cursor;
+    const cursor = onCursor ? theme.fg('accent', '→ ') : '  ';
+    const label = `${option.label}${config.recommended === i ? RECOMMENDED_SUFFIX : ''}`;
+    const desc = option.description ? theme.fg('dim', ` — ${option.description}`) : '';
+    if (config.multi) {
+      const box = state.selected[i] ? theme.fg('success', '[x]') : '[ ]';
+      const styled = state.selected[i] ? theme.bold(label) : label;
+      lines.push(`${cursor}${box} ${styled}${desc}`);
+    } else {
+      // Pick-one highlights the whole row — enter takes exactly what is lit.
+      const styled = onCursor ? theme.fg('accent', label) : label;
+      lines.push(`${cursor}${styled}${desc}`);
+    }
+  });
+  if (config.allowOther) {
+    const cursor = isOtherRow(state, config) ? theme.fg('accent', '→ ') : '  ';
+    const row = config.multi ? `[ ] ${OTHER_ROW_LABEL}` : OTHER_ROW_LABEL;
+    lines.push(`${cursor}${theme.fg('dim', row)}`);
+  }
+  return lines;
+}
+
+/** keyHint style shared with pi's selector: dim key + muted verb. */
+function hint(theme: MinimalTheme, key: string, verb: string): string {
+  return theme.fg('dim', key) + theme.fg('muted', ` ${verb}`);
+}
+
+function displayKeys(keybindings: KeybindingsLike | undefined, id: 'confirm' | 'cancel', fallback: string): string {
+  const keys = keybindings?.getKeys?.(`tui.select.${id}`);
+  return keys && keys.length > 0 ? keys.join('/') : fallback;
+}
+
+export function dialogFooter(
+  state: DialogState,
+  config: DialogConfig,
+  theme: MinimalTheme,
+  keybindings?: KeybindingsLike,
+  width?: number,
+): string {
+  const confirm = displayKeys(keybindings, 'confirm', 'enter');
+  const cancel = displayKeys(keybindings, 'cancel', 'escape/ctrl+c');
+  const picked = selectedLabels(state, config).length;
+  const chip = config.multi && picked > 0 ? theme.fg('success', ` · ${picked} selected`) : '';
+  const navigate = hint(theme, '↑↓', 'navigate');
+  const toggle = hint(theme, 'space', 'toggle');
+  const all = hint(theme, 'a', 'all');
+  const action = hint(theme, confirm, config.multi ? 'confirm' : 'select');
+  const cancelHint = hint(theme, cancel, 'cancel');
+  const parts = config.multi ? [navigate, toggle, all, action, cancelHint] : [navigate, action, cancelHint];
+  const fits = (segs: string[]): boolean => styledWidth(segs.join('  ') + chip) <= (width ?? Infinity);
+  // Narrow panes shed the most guessable extras first; the action keys and the live count are the floor.
+  for (const droppable of config.multi ? [all, navigate, cancelHint] : [navigate]) {
+    if (fits(parts)) break;
+    parts.splice(parts.indexOf(droppable), 1);
+  }
+  return parts.join('  ') + chip;
+}
+
+export function createDialogComponent(opts: DialogUiOptions): DialogComponent {
+  let state = createDialogState(opts.config);
+  let finished = false;
+  const onAbort = (): void => finish({ kind: 'cancel' });
+  function finish(outcome: DialogOutcome): void {
+    if (finished) return;
+    finished = true;
+    opts.signal?.removeEventListener('abort', onAbort);
+    opts.done(outcome);
+  }
+  if (opts.signal) opts.signal.addEventListener('abort', onAbort, { once: true });
+  return {
+    render(width: number): string[] {
+      const border = opts.theme.fg('border', '─'.repeat(Math.max(1, width)));
+      // Content wraps inside a 1-col margin each side (like pi's Text(text, 1, 0)) instead of clipping.
+      const inner = Math.max(1, width - 2);
+      const pad = (line: string): string => ` ${line}`;
+      return [
+        border,
+        '',
+        ...wrapStyled(opts.theme.fg('accent', opts.theme.bold(opts.title)), inner).map(pad),
+        '',
+        ...dialogLines(state, opts.config, opts.theme)
+          .flatMap((row) => wrapStyled(row, inner))
+          .map(pad),
+        '',
+        truncateStyled(` ${dialogFooter(state, opts.config, opts.theme, opts.keybindings, inner)}`, width),
+        '',
+        border,
+      ];
+    },
+    handleInput(data: string): void {
+      if (finished) return;
+      if (opts.keybindings?.matches?.(data, 'app.tools.expand') === true) {
+        opts.toggleToolsExpanded?.();
+        return;
+      }
+      const key = resolveDialogKey(data, opts.keybindings);
+      if (key === 'ignore') return;
+      const next = stepDialog(state, key, opts.config);
+      state = next.state;
+      opts.requestRender?.();
+      if (next.outcome) finish(next.outcome);
+    },
+    invalidate(): void { /* No cached lines. */ },
+  };
+}
+
+/** Run the dialog 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 select dialog or the typed prompt. */
+export async function runSelectDialog(
+  custom: (factory: unknown) => Promise<unknown>,
+  title: string,
+  config: DialogConfig,
+  options?: { signal?: AbortSignal; toggleToolsExpanded?: () => void },
+): Promise<DialogOutcome | null> {
+  if (options?.signal?.aborted) return { kind: 'cancel' };
+  const result = await custom((tui: unknown, theme: unknown, keybindings: unknown, done: (value: unknown) => void) =>
+    createDialogComponent({
+      title,
+      config,
+      theme: theme as MinimalTheme,
+      keybindings: keybindings as KeybindingsLike | undefined,
+      signal: options?.signal,
+      toggleToolsExpanded: options?.toggleToolsExpanded,
+      done: (outcome) => done(outcome),
+      requestRender: () => (tui as { requestRender?: () => void } | undefined)?.requestRender?.(),
+    }));
+  if (result === undefined || result === null) return null;
+  const outcome = result as DialogOutcome;
+  if (outcome.kind === 'cancel' || outcome.kind === 'other' || outcome.kind === 'selected') return outcome;
+  return null;
+}