@zosmaai/pi-llm-wiki 0.12.0 → 0.12.2

package/docs/superpowers/plans/2026-09-05-wikilink-alias-pipe-table-only.md

@@ -0,0 +1,257 @@
+# Wikilink Alias Pipe Escaping — Table-Only Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop escaping `[[target|alias]]` pipes outside of Markdown table rows, so the `.md` files pi writes stay valid for external readers (Obsidian, VS Code Wiki Links) that don't understand the escaped `\|` form.
+
+**Architecture:** The escape logic lives in one pure function `escapeWikilinkAliasPipes(body)` in `extensions/llm-wiki/lib/knowledge-document.ts`, called from both write paths (`createKnowledgeDocument` for new/edited pages and `patchKnowledgeDocument` for ingest source updates). The fix narrows that function so its pipe-escaping regex only runs on lines that are Markdown table rows. Everything else (prose, lists, headings, fenced code) is passed through verbatim. No new files, no new public API — this is a one-function behavioral change.
+
+**Tech Stack:** TypeScript (ES2022, ESM), Vitest (tests), Biome (lint), `tsc` (typecheck). Pure functions, no I/O inside the function under test.
+
+**Roadmap:** None. Single focused bug fix.
+
+**Phase:** Single-plan implementation.
+
+---
+
+## Context (read before starting)
+
+- **The bug:** `escapeWikilinkAliasPipes` applies its escaping regex to *every* non-fenced line, including prose. So `[[entities/peanut-cat|Peanut]]` in a sentence is written to disk as `[[entities/peanut-cat\|Peanut]]`. pi-llm-wiki's own reader tolerates this (`normalizeWikilinkTarget` strips a trailing `\`), but external readers treat `\|` as a literal backslash-pipe and report "Unresolved or ambiguous wiki-link".
+- **The intent (introduced in PR #158, commit `7f1eea0`):** the escaping exists so an aliased wikilink inside a Markdown table cell doesn't have its inner `|` read as a cell delimiter. That intent is valid — it just must be *scoped* to table rows.
+- **Current code (`knowledge-document.ts` ~line 593):**
+
+  ```ts
+  function escapeWikilinkAliasPipes(body: string): string {
+    let inFence = false;
+    return body
+      .split("\n")
+      .map((line) => {
+        if (/^\s*(`{3,}|~{3,})/.test(line)) {
+          inFence = !inFence;
+          return line;
+        }
+        if (inFence) return line;
+        return line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]");
+      })
+      .join("\n");
+  }
+  ```
+
+  The final `return line.replace(...)` runs for every non-fenced line — that's the bug.
+
+- **Call sites (both go through `escapeWikilinkAliasPipes`):**
+  - `createKnowledgeDocument` → `knowledge-document.ts:634` (`normalizedBody`). Covers `/wiki create_page`, `wiki_ensure_page`, and auto-created stub concepts.
+  - `patchKnowledgeDocument` → `knowledge-document.ts:664`. Covers ingest source updates in `ingest-worker.ts:390`.
+- **Table-row detection:** a Markdown table row starts (after optional whitespace) with `|` and ends (after optional whitespace) with `|`. Regex: `/^\s*\|.*\|\s*$/`. The separator row (`| --- |`) and header row match this but contain no `[[...|...]]`, so the replace is a no-op on them — safe.
+- **Existing test that encodes the buggy behavior and MUST be updated:** `test/ingest-worker.test.ts:309` expects prose `[[concepts/transformer\|T]]`. After the fix it must expect the *unescaped* form `[[concepts/transformer|T]]` (the prose lives in a source page, not a table).
+- **Existing tests that must stay green (no change needed):**
+  - `test/knowledge-document.test.ts:63` — table row escapes, fenced code does not. Stays.
+  - `test/knowledge-links.test.ts:51-52, 61` — reader-side, verifies both escaped and unescaped forms resolve. Unaffected by a writer change. Stays.
+
+## Files changed
+
+- Modify: `extensions/llm-wiki/lib/knowledge-document.ts` (the fix)
+- Modify: `test/knowledge-document.test.ts` (add prose regression test)
+- Modify: `test/ingest-worker.test.ts` (update buggy escaping assertion)
+
+---
+
+## Task 1: Write a failing test that pins the prose bug
+
+**Files:**
+- Modify: `test/knowledge-document.test.ts`
+
+- [ ] **Step 1: Add a regression test asserting prose wikilinks are written verbatim**
+
+Find the existing table-escape test in `test/knowledge-document.test.ts` (around line 63) — it currently ends right before the `it.each([...])` block that starts at line 71:
+
+```ts
+  it("escopes alias-pipe escaping to Markdown table rows only", () => {
+    const table = createKnowledgeDocument(
+      "concepts/table.md",
+      { type: "concept" },
+      "| Name |\n| --- |\n| [[entities/gildan|Gildan]] |",
+    );
+    // Table row: alias pipe MUST be escaped so the cell isn't split.
+    expect(table.body).toContain("[[entities/gildan\\|Gildan]]");
+
+    const prose = createKnowledgeDocument(
+      "concepts/prose.md",
+      { type: "concept" },
+      "See [[entities/peanut-cat|Peanut]] and [[entities/alice|Alice]] here.",
+    );
+    // Prose: alias pipes MUST stay literal so external readers follow the link.
+    expect(prose.body).toContain("[[entities/peanut-cat|Peanut]]");
+    expect(prose.body).toContain("[[entities/alice|Alice]]");
+    expect(prose.body).not.toContain("\\|");
+
+    // Fenced code stays verbatim (existing behavior, keep asserting).
+    const fenced = createKnowledgeDocument(
+      "concepts/fenced.md",
+      { type: "concept" },
+      "```md\n[[entities/raw|Raw]]\n```",
+    );
+    expect(fenced.body).toContain("[[entities/raw|Raw]]");
+  });
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `npx vitest run test/knowledge-document.test.ts -t "escopes alias-pipe escaping to Markdown table rows only"`
+
+Expected: FAIL. The `prose.body` assertions fail because the current implementation escapes the pipes and writes `[[entities/peanut-cat\|Peanut]]`. (The table-row assertion already passes.)
+
+- [ ] **Step 3: Commit the failing test**
+
+```bash
+git add test/knowledge-document.test.ts
+git commit -m "test: add regression for prose wikilink alias-pipe escaping"
+```
+
+Expected: the commit lands with the test still red.
+
+---
+
+## Task 2: Scope the escaping to Markdown table rows only
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/knowledge-document.ts`
+
+- [ ] **Step 1: Replace the escape function so its regex only runs on table rows**
+
+In `extensions/llm-wiki/lib/knowledge-document.ts`, replace the current `escapeWikilinkAliasPipes` function (from `/** Escape wikilink alias pipes so generated content remains valid in Markdown tables. */` through its closing `}`) with this version:
+
+```ts
+/** Escape wikilink alias pipes only inside Markdown table rows.
+ *
+ * A bare `|` inside `[[target|alias]]` would be read as a table cell
+ * delimiter when the row is rendered, so table rows need the pipe escaped as
+ * `[[target\\|alias]]`. Prose, lists, headings, and fenced code keep their
+ * pipes literal, so the written file stays valid for external readers
+ * (Obsidian, VS Code Wiki Links) that don't understand the escaped form. */
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+
+function escapeWikilinkAliasPipes(body: string): string {
+  let inFence = false;
+  return body
+    .split("\n")
+    .map((line) => {
+      if (/^\s*(`{3,}|~{3,})/.test(line)) {
+        inFence = !inFence;
+        return line;
+      }
+      if (inFence) return line;
+      // Only table rows (and no-op separator/header rows) get the escape pass.
+      return TABLE_ROW.test(line)
+        ? line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]")
+        : line;
+    })
+    .join("\n");
+}
+```
+
+The key change: the final `return` now guards the `.replace(...)` behind `TABLE_ROW.test(line)`, leaving non-table lines untouched.
+
+- [ ] **Step 2: Run the test to verify it passes**
+
+Run: `npx vitest run test/knowledge-document.test.ts -t "escopes alias-pipe escaping to Markdown table rows only"`
+
+Expected: PASS. The prose assertions now hold because non-table lines are passed through verbatim; the table-row assertion still holds because the escaping still runs on table rows.
+
+- [ ] **Step 3: Commit the fix**
+
+```bash
+git add extensions/llm-wiki/lib/knowledge-document.ts
+git commit -m "fix: escape wikilink alias pipes only inside Markdown table rows"
+```
+
+---
+
+## Task 3: Correct the ingest-worker prose assertion
+
+**Files:**
+- Modify: `test/ingest-worker.test.ts`
+
+- [ ] **Step 1: Update the assertion at line ~309 to expect unescaped prose pipes**
+
+Find this block in `test/ingest-worker.test.ts` (inside the `commitSynthesis` "normalize" test, ~line 292-310):
+
+```ts
+      expect(res.ok).toBe(true);
+      const written = readFileSync(join(paths.wiki, "sources", "SRC-001.md"), "utf8");
+      expect(written).toContain("[[concepts/transformer\\|T]]");
+```
+
+The source page body is plain prose (`The [[transformer|T]] changed everything.`), so after the fix the pipe is no longer escaped. Change it to:
+
+```ts
+      expect(res.ok).toBe(true);
+      const written = readFileSync(join(paths.wiki, "sources", "SRC-001.md"), "utf8");
+      expect(written).toContain("[[concepts/transformer|T]]");
+```
+
+- [ ] **Step 2: Run the ingest-worker test**
+
+Run: `npx vitest run test/ingest-worker.test.ts`
+
+Expected: PASS. (Before this change it would FAIL because the source page now stores the unescaped form.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/ingest-worker.test.ts
+git commit -m "test: expect unescaped wikilink pipes in prose source pages"
+```
+
+---
+
+## Task 4: Full verification and commit sweep
+
+**Files:**
+- (none new)
+
+- [ ] **Step 1: Run the full test suite**
+
+Run: `pnpm test`
+
+Expected: all tests pass. If anything else fails, it is encoding the old escaping behavior — update that assertion to the correct (unescaped-for-prose) expectation.
+
+- [ ] **Step 2: Typecheck**
+
+Run: `pnpm typecheck`
+
+Expected: clean (no diagnostics).
+
+- [ ] **Step 3: Lint**
+
+Run: `pnpm lint`
+
+Expected: clean (no lint errors).
+
+- [ ] **Step 4: Commit any remaining changes**
+
+```bash
+git add -A
+git commit -m "test: full suite, typecheck, lint green for alias-pipe fix"
+```
+
+Expected: working tree clean.
+
+---
+
+## Self-Review Checklist
+
+1. **Spec coverage:** The issue (escaped `\|` in prose breaks external readers) is covered by Task 2's fix and Task 1's regression test. The ingest-worker regression is covered by Task 3.
+2. **Placeholder scan:** No TBD/TODO/“implement later” markers. Every step has concrete code and exact commands.
+3. **Type consistency:** `escapeWikilinkAliasPipes` keeps its `(body: string) => string` signature; `TABLE_ROW` is `RegExp`. Call sites unchanged.
+4. **Phase boundary health:** After Task 2 the project is still green — the reader still handles both escaped and unescaped forms (knowledge-links tests), so no migration or half-done state. The only behavior change is on the write side, which is what the issue targets.
+
+## Verification commands (verbatim)
+
+```bash
+npx vitest run test/knowledge-document.test.ts
+npx vitest run test/ingest-worker.test.ts
+pnpm test
+pnpm typecheck
+pnpm lint
+```

package/extensions/llm-wiki/index.ts

@@ -12,6 +12,7 @@ import {
   registerObservationReminder,
   registerWikiObserve,
 } from "./lib/observation.js";
+import { recoverQmdIndex } from "./lib/qmd-indexing.js";
 import {
   formatRecallContext,
   registerWikiRecall,
@@ -36,6 +37,7 @@ import {
   registerWikiLint,
   registerWikiLogEvent,
   registerWikiRebuildMeta,
+  registerWikiReindex,
   registerWikiReindexEmbeddings,
   registerWikiSearch,
   registerWikiStatus,
@@ -58,7 +60,7 @@ import { applySessionStartStatus } from "./lib/visible-status.js";
 /**
  * @zosmaai/pi-llm-wiki — LLM Wiki extension for Pi
  *
- * Registers 13 custom tools and installs guardrails (+3 agent-trajectory tools
+ * Registers 14 custom tools and installs guardrails (+3 agent-trajectory tools
  * when `llm-wiki.trajectories` is enabled — opt-in, off by default, issue #80):
  * - wiki_recall (layered: personal + project vaults)
  * - wiki_retro (lightweight: single markdown file)
@@ -107,6 +109,7 @@ export default function (pi: ExtensionAPI) {
   registerWikiLint(pi, runtime);
   registerWikiStatus(pi);
   registerWikiRebuildMeta(pi, runtime);
+  registerWikiReindex(pi);
   registerWikiReindexEmbeddings(pi, runtime);
   registerWikiLogEvent(pi);
   registerWikiWatch(pi);
@@ -218,6 +221,16 @@ export default function (pi: ExtensionAPI) {
       sessionModelId: (ctx.model as { id?: string })?.id,
     });
 
+    // Fire-and-forget QMD index recovery. Generated-state repair only — it must
+    // never block heuristic recall or the first-turn injection path.
+    runtime.launchTask(ctx, `qmd-recovery:${paths.root}`, async () => {
+      try {
+        await recoverQmdIndex(paths);
+      } catch (err) {
+        console.warn(`[llm-wiki] QMD index recovery failed: ${(err as Error).message}`);
+      }
+    });
+
     // One-time, user-visible session notice announcing the full wiki loop
     // (issue #77). Without this, recall/observe/retro are invisible — they
     // live only in the system prompt. Queued for the first prompt so it never

package/extensions/llm-wiki/lib/bootstrap.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { KnowledgeDiagnostic } from "./knowledge-document.js";
@@ -76,6 +77,7 @@ export function bootstrapVault(paths: VaultPaths, input: BootstrapInput): Bootst
     topic: input.topic,
     created: existing.created ?? fmtDate(),
     version: existing.version ?? "1.0",
+    vault_id: existing.vault_id ?? randomUUID(),
     ...(created ? { knowledge_format: "okf-0.2" } : {}),
   };
 

package/extensions/llm-wiki/lib/indexing.ts

@@ -25,6 +25,7 @@
 
 import { reindexEmbeddings, resolveEmbedder } from "./embeddings.js";
 import { rebuildMetadataLight } from "./metadata.js";
+import { invalidateQmdAfterProjectionFailure, reindexQmdVault } from "./qmd-indexing.js";
 import type { LaunchCtx, Runtime } from "./runtime.js";
 import type { VaultPaths } from "./utils.js";
 
@@ -65,7 +66,29 @@ export function scheduleReindex(
       while (dirty.has(root)) {
         dirty.delete(root);
         const projection = rebuildMetadataLight(paths);
-        if (!projection.ok) continue;
+        if (!projection.ok) {
+          // Generated QMD search state is repairable and must not fail the
+          // authoritative write. On a projection failure, only invalidate unsafe
+          // QMD entries (never index valid additions).
+          try {
+            await invalidateQmdAfterProjectionFailure(paths);
+          } catch {
+            // Best-effort safety pass; a busy/transient lock must not abort the
+            // metadata drain loop.
+          }
+          continue;
+        }
+
+        try {
+          // Post-projection lexical QMD pass. Model-free and repairable.
+          await reindexQmdVault(paths, {
+            scope: "changed",
+            components: ["lexical"],
+            force: false,
+          });
+        } catch {
+          // Generated search indexing is repairable and must not fail the write.
+        }
 
         // Refresh embeddings only after metadata is consistent. Stale-aware and
         // a no-op unless an embedder is configured.

package/extensions/llm-wiki/lib/ingest-worker.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { AgentTool, StreamFn } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
 import { Type } from "typebox";
@@ -494,7 +494,11 @@ Rules:
 export interface RunIngestSynthesisArgs {
   model: Model<Api>;
   apiKey: string;
-  headers?: Record<string, string>;
+  headers?: Record<string, string | null>;
+  /** Stream function for extension-registered providers (issue #222). */
+  streamFn?: StreamFn;
+  /** Provider-scoped env from auth resolution (issue #222; pi >= 0.85). */
+  env?: Record<string, string>;
   paths: VaultPaths;
   sourceId: string;
   manifest: Record<string, unknown>;
@@ -522,6 +526,8 @@ export async function runIngestSynthesis(
     model,
     apiKey,
     headers,
+    streamFn,
+    env,
     paths,
     sourceId,
     manifest,
@@ -582,6 +588,8 @@ export async function runIngestSynthesis(
     model,
     apiKey,
     headers,
+    streamFn,
+    env,
     systemPrompt,
     userPrompt,
     tools: [commitTool as AgentTool],

package/extensions/llm-wiki/lib/knowledge-document.ts

@@ -26,7 +26,14 @@ export type DiagnosticCode =
   | "event_source_unreadable"
   | "event_invalid_json"
   | "event_invalid_timestamp"
-  | "event_missing_kind";
+  | "event_missing_kind"
+  | "config_invalid_vault_id"
+  | "qmd_index_missing"
+  | "qmd_index_stale"
+  | "qmd_index_error"
+  | "qmd_index_busy"
+  | "qmd_manifest_invalid"
+  | "qmd_swap_interrupted";
 
 export interface KnowledgeDiagnostic {
   severity: DiagnosticSeverity;
@@ -589,7 +596,15 @@ export function serializeKnowledgeDocument(document: KnowledgeDocument): string
   return body ? `---\n${yaml}---\n\n${body}\n` : `---\n${yaml}---\n`;
 }
 
-/** Escape wikilink alias pipes so generated content remains valid in Markdown tables. */
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+
+/** Escape wikilink alias pipes only inside Markdown table rows.
+ *
+ * A bare `|` inside `[[target|alias]]` would be read as a table cell
+ * delimiter when the row renders, so table rows need the pipe escaped as
+ * `[[target\|alias]]`. Prose, lists, headings, and fenced code keep their
+ * pipes literal, so the written file stays valid for external readers
+ * (Obsidian, VS Code Wiki Links) that don't understand the escaped form. */
 function escapeWikilinkAliasPipes(body: string): string {
   let inFence = false;
   return body
@@ -600,7 +615,9 @@ function escapeWikilinkAliasPipes(body: string): string {
         return line;
       }
       if (inFence) return line;
-      return line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]");
+      return TABLE_ROW.test(line)
+        ? line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]")
+        : line;
     })
     .join("\n");
 }

package/extensions/llm-wiki/lib/knowledge-links.ts

@@ -38,23 +38,55 @@ function normalizeWikilinkTarget(target: string): string {
   return target.trim().replace(/\\$/, "");
 }
 
+// Blank out code spans, fenced/indented code blocks, and raw HTML (the same
+// node types the link walk skips), preserving length so offsets stay valid.
+function maskCodeRegions(tree: Root | null, body: string): string {
+  if (!tree) return body;
+  const ranges: Array<[number, number]> = [];
+  function visit(node: Nodes): void {
+    const position = (node as { position?: { start: { offset: number }; end: { offset: number } } })
+      .position;
+    if (node.type === "inlineCode" || node.type === "code" || node.type === "html") {
+      if (position) ranges.push([position.start.offset, position.end.offset]);
+    }
+    if ("children" in node && Array.isArray((node as { children?: Nodes[] }).children)) {
+      for (const child of (node as { children: Nodes[] }).children) {
+        visit(child);
+      }
+    }
+  }
+  visit(tree);
+  if (ranges.length === 0) return body;
+  const chars = body.split("");
+  for (const [start, end] of ranges) {
+    for (let i = start; i < end && i < chars.length; i++) {
+      if (i >= 0) chars[i] = " ";
+    }
+  }
+  return chars.join("");
+}
+
 export function extractKnowledgeLinks(body: string): KnowledgeLinks {
   const markdown: ExtractedLink[] = [];
   const wikilinks: ExtractedLink[] = [];
 
-  // Extract legacy wikilinks. A table-safe alias uses an escaped pipe: [[target\\|alias]].
-  for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-    wikilinks.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
-  }
-
   // Parse with CommonMark AST
-  let tree: Root;
+  let tree: Root | null = null;
   try {
     tree = fromMarkdown(body);
   } catch {
-    return { markdown, wikilinks };
+    tree = null;
   }
 
+  // Extract legacy wikilinks. A table-safe alias uses an escaped pipe: [[target\\|alias]].
+  // Scan the code-masked body so [[...]] inside code is not a real link.
+  const scanBody = maskCodeRegions(tree, body);
+  for (const match of scanBody.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
+    wikilinks.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
+  }
+
+  if (!tree) return { markdown, wikilinks };
+
   // Build definition map (case-insensitive)
   const defs = new Map<string, Definition>();
   function collectDefs(node: Nodes) {

package/extensions/llm-wiki/lib/model-command.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import {
   Container,
-  matchesKey,
+  getKeybindings,
+  Input,
   type SelectItem,
   SelectList,
   type SelectListTheme,
@@ -93,8 +94,18 @@ function buildPickerItems(
   return { items, selectedIndex };
 }
 
+/** Case-insensitive substring on label/value. Not SelectList.setFilter (prefix-on-value). */
+function itemMatchesQuery(item: SelectItem, query: string): boolean {
+  if (!query) return true;
+  const needle = query.toLowerCase();
+  return item.label.toLowerCase().includes(needle) || item.value.toLowerCase().includes(needle);
+}
+
 /** Editor-dock picker; `ui.custom` without overlay replaces the input slot like `/model`. */
 class ModelPickerScreen extends Container {
+  private readonly allItems: SelectItem[];
+  private readonly listTheme: SelectListTheme;
+  private readonly search: Input;
   private list: SelectList;
   private doneFn: (result?: string) => void;
   private closed = false;
@@ -107,27 +118,61 @@ class ModelPickerScreen extends Container {
     done: (result?: string) => void,
   ) {
     super();
+    this.allItems = items;
+    this.listTheme = buildSelectTheme(theme);
     this.doneFn = done;
     this.addChild(new Text(title, 0, 0));
     this.addChild(new Spacer(1));
-    this.list = new SelectList(
-      items,
-      Math.min(MAX_VISIBLE, Math.max(items.length, 1)),
-      buildSelectTheme(theme),
-    );
-    this.list.setSelectedIndex(selectedIndex);
-    this.list.onSelect = (item) => this.finish(item.value);
-    this.list.onCancel = () => this.finish(undefined);
+    this.search = new Input();
+    this.search.focused = true;
+    this.addChild(this.search);
+    this.list = this.makeList(items, selectedIndex);
     this.addChild(this.list);
   }
 
   handleInput(data: string): void {
-    // matchesKey covers kitty CSI-u Esc; SelectList cancel is the fallback.
-    if (matchesKey(data, "escape")) {
+    const kb = getKeybindings();
+    if (
+      kb.matches(data, "tui.select.up") ||
+      kb.matches(data, "tui.select.down") ||
+      kb.matches(data, "tui.select.confirm")
+    ) {
+      this.list.handleInput(data);
+      return;
+    }
+    // tui.select.cancel defaults to escape + ctrl+c and the kitty CSI-u Esc
+    // form, so one keybinding check covers every cancel keypath (no hardcoded Esc,
+    // so a remapped binding is honored).
+    if (kb.matches(data, "tui.select.cancel")) {
       this.finish(undefined);
       return;
     }
-    this.list.handleInput(data);
+    this.search.handleInput(data);
+    this.applyFilter();
+  }
+
+  private makeList(items: SelectItem[], selectedIndex: number): SelectList {
+    const list = new SelectList(
+      items,
+      Math.min(MAX_VISIBLE, Math.max(items.length, 1)),
+      this.listTheme,
+    );
+    list.setSelectedIndex(selectedIndex);
+    list.onSelect = (item) => this.finish(item.value);
+    list.onCancel = () => this.finish(undefined);
+    return list;
+  }
+
+  private applyFilter(): void {
+    const filtered = this.allItems.filter((item) => itemMatchesQuery(item, this.search.getValue()));
+    const previous = this.list.getSelectedItem()?.value;
+    const selectedIndex = Math.max(
+      0,
+      filtered.findIndex((item) => item.value === previous),
+    );
+    this.removeChild(this.list);
+    this.list = this.makeList(filtered, selectedIndex);
+    this.addChild(this.list);
   }
 
   private finish(result?: string): void {