pi-pier 0.3.0 → 0.3.1

package/src/todos-service.ts

@@ -1,13 +1,6 @@
-/** Why: Preserve the established compatibility and safety behavior (D65, D75). */
+/** Single owner of todo state; every mutation path (tool, human edit, M17 reconcile, archive) lands here (D65, D75). */
 import { EventEmitter } from 'node:events';
-import {
-  applyTodoEdits,
-  foldLatestTodosMeta,
-  listsEqual,
-  type TodoEdit,
-  type TodoItem,
-} from './todo-core.ts';
-import { countCompletedTransitions } from './progress-core.ts';
+import { applyTodoEdits, completionTransitions, foldLatestTodosMeta, listsEqual, type TodoEdit, type TodoItem } from './todo-core.ts';
 import type { RuntimeRoleManifest } from './tool-gate.ts';
 
 export interface TodosConfig {
@@ -17,21 +10,13 @@ export interface TodosConfig {
 
 export type TodoCompletionSource = 'tool' | 'reconcile' | 'human' | 'archive';
 
-export interface TodoCompletedEvent {
-  count: number;
-  at: number;
-  source: TodoCompletionSource;
-}
-
 export class TodosService extends EventEmitter {
   private _items: TodoItem[] = [];
-  /**
-   * Live list (read-only). Mutations must go through replace/applyEdits/rebuild.
-   */
+  /** Live list (read-only). Mutations must go through replace/applyEdits/rebuild. */
   get items(): readonly TodoItem[] {
     return this._items;
   }
-  /** Why: Preserve the established compatibility and safety behavior. */
+  /** Clock anchor for staleness/archiving; null until the first write. */
   lastWriteAt: number | null = null;
   readonly config: TodosConfig;
 
@@ -40,17 +25,14 @@ export class TodosService extends EventEmitter {
     this.config = config;
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (D75). */
+  /** D75: subagents are strict (one in_progress); the role manifest may force parallel mode. */
   static configFromRuntime(manifest: RuntimeRoleManifest | null, isSubagent: boolean): TodosConfig {
     const strict = isSubagent;
     const mode = manifest?.services?.todos?.mode;
-    const allowParallelInProgress = mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict;
-    return { strict, allowParallelInProgress };
-  }
-
-  /** Defensive copy for callers that must not mutate service state. */
-  getSnapshot(): TodoItem[] {
-    return this._items.map((it) => ({ ...it }));
+    return {
+      strict,
+      allowParallelInProgress: mode === 'parallel' || mode === 'serial' ? mode === 'parallel' : !strict,
+    };
   }
 
   replace(items: readonly TodoItem[], opts?: { source?: TodoCompletionSource }): { changed: boolean } {
@@ -76,24 +58,22 @@ export class TodosService extends EventEmitter {
     return { changed: true };
   }
 
-  /** Why: Preserve the established compatibility and safety behavior (M16). */
+  /** M16: ETA and compaction boundaries feed off this single completion diff (same rule as the tool's D36 report). */
   private emitCompletedTransitions(
     before: readonly TodoItem[],
     after: readonly TodoItem[],
     source: TodoCompletionSource = 'tool',
   ): void {
-    const count = countCompletedTransitions(before, after);
+    const count = completionTransitions(before, after).length;
     if (count > 0) this.emit('todo.completed', { count, at: Date.now(), source });
   }
 
+  /** Branch replay: fold the JSONL to the authoritative list. A branch with no snapshot (/new, or /tree
+   *  back before the first todo_write) has no list, so the previous session's items must not survive. */
   rebuild(entries: readonly unknown[]): void {
-    // Why: Preserve the established compatibility and safety behavior.
-    // Why: Preserve the established compatibility and safety behavior.
     const folded = foldLatestTodosMeta(entries as Parameters<typeof foldLatestTodosMeta>[0]);
-    if (folded) {
-      this._items = folded.items;
-      this.lastWriteAt = folded.writtenAt;
-    }
+    this._items = folded ? folded.items : [];
+    this.lastWriteAt = folded ? folded.writtenAt : null;
     this.emit('todo.updated', { items: this._items, reason: 'rebuild' });
   }
 }

package/src/tool-error.ts

@@ -1,17 +1,11 @@
 /**
- * A1: pi only marks a tool result as failed when `execute()` throws — "Returning a value never sets
- * the error flag regardless of what properties you include in the return object"
- * (pi docs/extensions.md, "Signaling errors").
+ * pi only marks a tool result as failed when `execute()` throws; returning a value never sets the
+ * error flag (pi docs/extensions.md, "Signaling errors"). Every hard failure goes through
+ * `toolError()`, while deliberate non-failures (empty result set, "no match within Xms", a pane that
+ * has not produced output yet) stay normal results.
  *
- * The round-2 audit found 20+ real failures in pier's tools returned as plain text, so neither the
- * model nor pi's own hooks keyed on `event.isError` could see them (pier's B1 "subagent alive but
- * reported no output" self-heal was dead code for exactly that reason). Every hard failure now goes
- * through `toolError()`; deliberate non-failures (empty result set, "no match within Xms", a pane
- * that simply has not produced output yet) stay normal results.
- *
- * The "Error: " prefix the old text returns carried is dropped: the provider's tool-result error
- * channel and pi's red rendering already mark it, and keeping it would double the prefix once pi
- * formats a thrown error.
+ * The leading "Error: " text is stripped: the provider's tool-result error channel and pi's red
+ * rendering already mark it, and keeping it would double the prefix once pi formats a thrown error.
  */
 export class ToolError extends Error {
   constructor(message: string) {
@@ -20,7 +14,6 @@ export class ToolError extends Error {
   }
 }
 
-/** Throw a tool failure (never returns). */
 export function toolError(message: string): never {
   throw new ToolError(message);
 }

package/src/tool-gate.ts

@@ -1,31 +1,40 @@
-/** Why: Preserve the established compatibility and safety behavior (C7, D76, D77, D79, WS-D6). */
+/**
+ * Worker execution enforcement (C7, D76/D77/D82) — pure. RuntimeRoleManifest is THE runtime manifest
+ * shape; the file format lives in role-manifest.ts and the composed/persisted shapes derive from it
+ * (manifest-compose.ts, role-state.ts).
+ */
 import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
 
-/** Why: Preserve the established compatibility and safety behavior. */
 export interface RuntimeRoleManifest {
   role: string;
   version?: string;
   tools: string[];
   permissions: Record<string, PermissionAction>;
-  /** Why: Preserve the established compatibility and safety behavior (D82). */
+  /** Stance for tools outside `tools`; 'allow' keeps user-installed extensions visible (D82). */
   unknownTools?: UnknownToolStance;
   services?: {
     todos?: {
       mode?: 'serial' | 'parallel';
     };
   };
+  /** P0 per-role guidelines (RFC §4.6): injected as a `pier-role` prompt section each turn. */
+  guidelines?: string[];
 }
 
-/** Why: Preserve the established compatibility and safety behavior. */
+/** Parse the env-carried manifest; malformed input is null (fail-open: no gate) rather than a crash. */
 export function parseRuntimeManifest(envValue: string | undefined): RuntimeRoleManifest | null {
   if (!envValue) return null;
   try {
     const m = JSON.parse(envValue) as RuntimeRoleManifest;
     if (!m || typeof m.role !== 'string' || !Array.isArray(m.tools)) return null;
-    // Why: Preserve the established compatibility and safety behavior (D82).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       m.unknownTools = 'deny';
     }
+    if (m.guidelines !== undefined) {
+      m.guidelines = Array.isArray(m.guidelines)
+        ? m.guidelines.filter((g) => typeof g === 'string' && g.trim() !== '')
+        : undefined;
+    }
     return m;
   } catch {
     return null;
@@ -43,7 +52,6 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   const perm = manifest.permissions[toolName] ?? manifest.permissions['*'] ?? 'allow';
   const known = manifest.tools.includes(toolName);
   const stance = manifest.unknownTools ?? 'deny';
-  // Why: Preserve the established compatibility and safety behavior (D82).
   if (perm === 'deny' || (!known && stance === 'deny')) {
     return {
       kind: 'deny',
@@ -59,27 +67,36 @@ export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | n
   return { kind: 'allow' };
 }
 
-/** Why: Preserve the established compatibility and safety behavior (D77, D82). */
-export function planActiveTools(
-  manifestTools: string[],
-  currentActive: string[],
+/**
+ * 'allow' keeps every tool but the explicit deny rules (D82 user-installed-extension axis); 'deny'
+ * intersects with the manifest. Shared by planActiveTools (visibility) and role-state's switch
+ * planning (all-tools universe).
+ */
+export function filterToolsByStance(
+  manifestTools: readonly string[],
+  universe: readonly string[],
   opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
-): { next: string[]; changed: boolean } | null {
-  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+): string[] {
   if ((opts?.unknownTools ?? 'deny') === 'allow') {
     const denied = new Set(
       Object.entries(opts?.permissions ?? {})
-        .filter(([, v]) => v === 'deny')
-        .map(([k]) => k),
+        .filter(([, action]) => action === 'deny')
+        .map(([name]) => name),
     );
-    const next = currentActive.filter((t) => !denied.has(t));
-    if (next.length === 0) return null;
-    return { next, changed: next.length !== currentActive.length };
+    return universe.filter((name) => !denied.has(name));
   }
   const wanted = new Set(manifestTools);
-  const next = currentActive.filter((t) => wanted.has(t));
-  if (next.length === 0) return null;
-  const changed = next.length !== currentActive.length;
-  return { next, changed };
+  return universe.filter((name) => wanted.has(name));
 }
 
+/** Null means "keep the current active set": an empty result must never clear every tool (D77). */
+export function planActiveTools(
+  manifestTools: readonly string[],
+  currentActive: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): { next: string[]; changed: boolean } | null {
+  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+  const next = filterToolsByStance(manifestTools, currentActive, opts);
+  if (next.length === 0) return null;
+  return { next, changed: next.length !== currentActive.length };
+}

package/src/vocab.ts

@@ -1,20 +1,17 @@
 /**
- * pi-herdr bridge vocabulary (M22: title is the board).
- *
- * DESIGN.md §4.2: no new transport. Wire = herdr NDJSON; todo authority = pi
- * session JSONL; display = pane.report_metadata title / state_labels.
+ * pi-herdr bridge vocabulary. DESIGN.md §4.2: no new transport — wire = herdr NDJSON, todo authority
+ * = pi session JSONL, display = pane.report_metadata title / state_labels.
  */
 
-/** Todo five-state (D34: three-state + blocked/abandoned, aligned with OMP). */
+/** Five states (D34): three-state + blocked/abandoned, aligned with OMP. */
 export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'abandoned';
 
 export const TODO_STATUSES: readonly TodoStatus[] = ['pending', 'in_progress', 'completed', 'blocked', 'abandoned'];
 
-/** Todo item: content + status; optional blocker (blocked only) and phase (D43). No stable id (last-write-wins). */
+/** Todo item: content + status; blocker only when blocked; optional phase groups (D43). No id (last-write-wins). */
 export interface TodoItem {
   content: string;
   status: TodoStatus;
-  /** Non-empty string only when status==='blocked' (D34). */
   blocker?: string;
   /** Optional group name (D43); non-empty, ≤30 chars. */
   phase?: string;
@@ -27,58 +24,88 @@ export interface TodoSnapshot {
   items: TodoItem[];
 }
 
-/** Snapshot counts (confirmation copy and title projection). */
 export interface TodoCounts {
   pending: number;
   inProgress: number;
   completed: number;
-  /** D91: blocked as its own column (title quartet ▶○■✓). */
+  /** D91: blocked is its own column (title quartet ▶○■✓). */
   blocked: number;
 }
 
 /** Source name for pane.report-agent. */
 export const REPORT_AGENT_SOURCE = 'pi-herdr';
 
-/** First-upgrade key used to clear the old 16-key chunked tokens (M13b leftover). */
+/** First-upgrade key used to clear the old 16-key chunked tokens (M13b). */
 export const PI_HERDR_META_KEY = 'pi-herdr';
 
-/** Model-facing todo tool name (DSH-compatible). */
 export const TODO_TOOL_NAME = 'todo_write';
 
 /** Snapshot key in tool-result details (persisted in session JSONL). */
 export const TODO_DETAILS_KEY = 'pi-herdr.todo';
 
-/** Confirmation copy (byte-aligned with DSH so model vocab transfers; blocked is appended only when present). */
+/** Confirmation copy (byte-aligned with DSH so model vocab transfers). */
 export function formatTodoConfirmation(items: readonly TodoItem[]): string {
   const c = countTodos(items);
   const base = `Updated todo list: ${c.pending} pending, ${c.inProgress} in progress, ${c.completed} completed.`;
-  // A4: blocked items used to be invisible here (the model read "nothing pending" while items sat
-  // blocked waiting on a human). Appending only when non-zero keeps the DSH-aligned wording intact.
+  // Append blocked only when non-zero — the model must not read "nothing pending" while items sit
+  // blocked on a human. Zero keeps the DSH-aligned wording intact.
   return c.blocked > 0 ? `${base.slice(0, -1)}, ${c.blocked} blocked.` : base;
 }
 
+/** Every status the todo model knows; anything else in a snapshot is corrupt data (D34). */
+const STATUS_LOOKUP: Readonly<Record<TodoStatus, true>> = {
+  pending: true,
+  in_progress: true,
+  completed: true,
+  blocked: true,
+  abandoned: true,
+};
+
+/**
+ * Corrupt snapshots carry arbitrary JSON as `status` (`extractSnapshotFromDetails` does not validate),
+ * so every table lookup keyed by status must pass through this first — `TODO_MARKS['constructor']`
+ * would otherwise render a function, and `groups['constructor'].push` would throw.
+ */
+export const isTodoStatus = (value: unknown): value is TodoStatus =>
+  typeof value === 'string' && Object.hasOwn(STATUS_LOOKUP, value);
+
+const COUNTED_STATUSES = {
+  pending: 'pending',
+  in_progress: 'inProgress',
+  completed: 'completed',
+  blocked: 'blocked',
+} as const satisfies Partial<Record<TodoStatus, keyof TodoCounts>>;
+
+/** The four states that occupy a count column (`abandoned` is terminal and deliberately uncounted). */
+const isCountedStatus = (status: TodoStatus): status is keyof typeof COUNTED_STATUSES =>
+  Object.hasOwn(COUNTED_STATUSES, status);
+
 export function countTodos(items: readonly TodoItem[]): TodoCounts {
-  let pending = 0;
-  let inProgress = 0;
-  let completed = 0;
-  let blocked = 0;
+  const counts: TodoCounts = { pending: 0, inProgress: 0, completed: 0, blocked: 0 };
   for (const it of items) {
-    if (it.status === 'pending') pending++;
-    else if (it.status === 'in_progress') inProgress++;
-    else if (it.status === 'completed') completed++;
-    else if (it.status === 'blocked') blocked++;
-    // abandoned is omitted (D34); blocked is its own column (D91)
+    const status = it?.status;
+    if (isTodoStatus(status) && isCountedStatus(status)) counts[COUNTED_STATUSES[status]] += 1;
   }
-  return { pending, inProgress, completed, blocked };
+  return counts;
 }
 
+/** Why a settlement carried no closing text (p24-class mis-attribution vs a truly silent worker). */
+export type SettlementNullReason = 'silent' | 'attribution-suspect' | 'extraction-failed';
+
+const NULL_CLOSING_SENTENCE: Record<SettlementNullReason, string> = {
+  'attribution-suspect': 'Its closing message could NOT be read — the session attribution is suspect (a wrong transcript may have been read). Check `subagent action output` / the ledger sessionFile before assuming it produced nothing; its work may be complete.',
+  'extraction-failed': 'It appears to have ended with a final report, but the closing text could not be extracted — read it from the session transcript.',
+  silent: 'It left no closing message.',
+};
+
 /** Subagent settlement notice (aligned with DSH). */
 export function formatSettlementNotice(
   agentId: string,
   closingMessage: string | null,
+  nullReason: SettlementNullReason = 'silent',
 ): string {
   const head = `Background subagent ${agentId} finished and will do no further work unless you send it more.`;
   return closingMessage
     ? `${head} Its closing message: ${closingMessage}`
-    : `${head} It left no closing message.`;
+    : `${head} ${NULL_CLOSING_SENTENCE[nullReason]}`;
 }

package/src/ask-multi.ts

@@ -1,260 +0,0 @@
-/**
- * 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;
-}