@zosmaai/pi-llm-wiki 0.11.7 → 0.12.0

package/docs/superpowers/plans/2026-09-02-wiki-lint-fresh-vault-and-windows-capture-fixes.md

@@ -0,0 +1,284 @@
+# Wiki Lint Fresh-Vault + Windows Capture Fixes 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:** Fix two one-line bugs — `wiki_lint` crashing with ENOENT on fresh checkouts (issue #203) and `wiki_capture_source` corrupting the `original/` artifact name on Windows absolute paths (issue #204) — each with a regression test.
+
+**Architecture:** Both fixes slot into existing code with no new modules. #203: `runWikiLint` (private in `tools.ts`) persists the gap snapshot via `writeJson` without ensuring `.llm-wiki/.discoveries/` exists; it gets the same `mkdirSync(recursive)` treatment the `autoFix` report write in the same function already uses. #204: `fileCaptureSource` derives the artifact name with `filePath.split("/").pop()`, which is a no-op on Windows paths; replace with a small exported, platform-aware `originalFileNameForPath()` helper modeled on the existing `originalFileNameForUrl()` sibling so the behavior is unit-testable cross-platform.
+
+**Tech Stack:** TypeScript (ES2022, ESM), Vitest, Biome, pnpm.
+
+**Roadmap:** None
+
+**Phase:** Single-plan implementation (two independent one-line fixes, one branch, one PR)
+
+---
+
+## Background (what the engineer must know)
+
+- Repo: `@zosmaai/pi-llm-wiki`. Two bugs, both confirmed present on current `main`:
+  - **#203** — `runWikiLint()` (`extensions/llm-wiki/lib/tools.ts:879`) unconditionally writes `gaps.json` to `paths.discoveries` at ~line 1018. `ensureVaultStructure` (`lib/utils.ts:262`) does create `.discoveries` — but only when bootstrapping a vault. A fresh git checkout/worktree of an existing vault has `.discoveries` gitignored → absent → `writeJson` → `writeFileSync` throws ENOENT → the whole lint run is discarded and no report is ever delivered.
+  - **#204** — `fileCaptureSource()` (`extensions/llm-wiki/lib/source-packet.ts:114`) computes `const fileName = filePath.split("/").pop() || "unknown"`. On Windows an absolute path like `D:\any\dir\doc.md` contains no `/`, so `fileName` becomes the whole string; `preserveFileOriginal` then writes `join(packetPath, "original", "D:\any\dir\doc.md")` — a drive colon inside a filename segment, illegal on Windows → capture fails, empty packet left behind.
+- Test harness facts (verified, so the tests below compile as-is):
+  - `test/lint-okf.test.ts` drives the tool via `registerWikiLint({ registerTool: ... } as unknown as ExtensionAPI)` and `tool.execute("test", params, undefined, undefined, { cwd: root, hasUI: false })`. It imports `existsSync`, `rmSync`, `writeFileSync`, `readFileSync` from `node:fs` and `getVaultPaths`, `ensureVaultStructure` from `lib/utils.js` — everything this plan's test needs is already imported.
+  - Without a `Runtime` (the test case), `dispatchReported` (`tools.ts:82`) runs `work()` inline with **no catch** — so the ENOENT rejection propagates out of `tool.execute()`. That is why the failing test below fails by throwing.
+  - `test/source-capture.test.ts` already imports `{ captureFile, captureText, captureUrl }` from `lib/source-packet.js` and has a `makePaths()` helper + `mockPi()` from `./helpers.js`.
+- Commands: `pnpm test` (vitest), `pnpm typecheck`, `pnpm lint` (biome). Node/pnpm available; `pnpm --version` = 9.15.4.
+- Issue #171 is explicitly out of scope.
+
+## File Structure
+
+| File | Change | Responsibility in this plan |
+|---|---|---|
+| `extensions/llm-wiki/lib/tools.ts` | Modify (~line 1015, inside `runWikiLint`) | One-line `mkdirSync(paths.discoveries, { recursive: true })` before the gaps write |
+| `extensions/llm-wiki/lib/source-packet.ts` | Modify (line 3 import, line 114, new helper after `originalFileNameForUrl` at ~line 256) | Export `originalFileNameForPath(filePath)`; use it in `fileCaptureSource` |
+| `test/lint-okf.test.ts` | Modify (append one `it(...)` after the "refreshes a stale gap snapshot to empty on audit-only lint" test, ~line 183) | Regression test: lint on a vault without `.discoveries` completes and persists `gaps.json` |
+| `test/source-capture.test.ts` | Modify (extend the `source-packet.js` import; add one `it(...)` after the "should copy local non-PDF file content to extracted.md" test) | Unit test: `originalFileNameForPath` strips the platform's directory prefix |
+
+No new files. No config, docs, or schema changes.
+
+---
+
+### Task 1: Fix #203 — `wiki_lint` ENOENT on fresh vault
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/tools.ts` (inside `runWikiLint`, the gaps write at ~lines 1015-1020)
+- Test: `test/lint-okf.test.ts`
+
+- [x] **Step 1: Write the failing test**
+
+Append this `it(...)` to `test/lint-okf.test.ts`, immediately after the closing `});` of the test named `"refreshes a stale gap snapshot to empty on audit-only lint"` (that test ends with `expect(status.content[0].text).toContain("Gaps: 0");` + `});`, ~line 183). All symbols used are already imported in this file:
+
+```ts
+it("completes on a fresh checkout where .discoveries is not yet created (issue #203)", async () => {
+  const paths = getVaultPaths(root);
+  ensureVaultStructure(paths);
+  // Fresh checkouts / worktrees of an existing vault do not have the
+  // gitignored .discoveries directory — simulate that.
+  rmSync(paths.discoveries, { recursive: true, force: true });
+  writeFileSync(join(paths.dotWiki, "config.json"), JSON.stringify({ name: "Fresh lint" }));
+  writeFileSync(
+    join(paths.wiki, "concepts", "valid.md"),
+    "---\ntype: concept\n---\n\nValid.\n",
+  );
+
+  let tool: TestTool | undefined;
+  registerWikiLint({
+    registerTool: (definition: unknown) => {
+      tool = definition as TestTool;
+    },
+  } as unknown as ExtensionAPI);
+  if (!tool) throw new Error("wiki_lint was not registered");
+  const result = await tool.execute("test", { auto_fix: false }, undefined, undefined, {
+    cwd: root,
+    hasUI: false,
+  });
+
+  expect(result.isError).not.toBe(true);
+  // auto_fix:false returns the run summary (not the reportLines file content).
+  expect(result.content[0].text).toContain("LLM Wiki lint complete");
+  expect(existsSync(join(paths.discoveries, "gaps.json"))).toBe(true);
+  const snapshot = JSON.parse(readFileSync(join(paths.discoveries, "gaps.json"), "utf8"));
+  expect(snapshot.gaps).toEqual([]);
+});
+```
+
+- [x] **Step 2: Run the test to verify it fails**
+
+Run: `pnpm vitest run test/lint-okf.test.ts -t "fresh checkout"`
+
+Expected: FAIL — the `await tool.execute(...)` line throws `Error: ENOENT: no such file or directory, open '<root>/.llm-wiki/.discoveries/gaps.json'` (rejection propagates because `dispatchReported` has no runtime in tests).
+
+- [x] **Step 3: Write the minimal implementation**
+
+In `extensions/llm-wiki/lib/tools.ts`, inside `runWikiLint`, change this block (~lines 1015-1020):
+
+```ts
+  // The gap snapshot is generated discovery metadata consumed by wiki_status:
+  // persist it on every successful lint so status never reports a stale count.
+  // Corrective actions below (report, event, meta rebuild) stay autoFix-only.
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
+```
+
+to:
+
+```ts
+  // The gap snapshot is generated discovery metadata consumed by wiki_status:
+  // persist it on every successful lint so status never reports a stale count.
+  // Corrective actions below (report, event, meta rebuild) stay autoFix-only.
+  // mkdir mirrors the autoFix report write below: on a fresh checkout the
+  // gitignored .discoveries dir does not exist yet (issue #203).
+  mkdirSync(paths.discoveries, { recursive: true });
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
+```
+
+`mkdirSync` is already imported at the top of `tools.ts` (line 1: `import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";`) — no import change.
+
+- [x] **Step 4: Run the test to verify it passes**
+
+Run: `pnpm vitest run test/lint-okf.test.ts`
+
+Expected: PASS — all tests in the file green, including the new one.
+
+- [x] **Step 5: Run the full gate**
+
+Run: `pnpm test && pnpm typecheck && pnpm lint`
+
+Expected: all green (no unrelated breakage).
+
+- [x] **Step 6: Commit**
+
+```bash
+git add test/lint-okf.test.ts extensions/llm-wiki/lib/tools.ts
+git commit -m "fix: ensure .discoveries exists before lint persists the gap snapshot (#203)"
+```
+
+---
+
+### Task 2: Fix #204 — Windows drive colon in captured file name
+
+**Files:**
+- Modify: `extensions/llm-wiki/lib/source-packet.ts` (line 3 import; line 114 in `fileCaptureSource`; new exported helper after `originalFileNameForUrl`, which ends ~line 256)
+- Test: `test/source-capture.test.ts`
+
+- [x] **Step 1: Write the failing test**
+
+First, extend the existing import at line 5 of `test/source-capture.test.ts`:
+
+```ts
+import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
+```
+
+becomes:
+
+```ts
+import {
+  captureFile,
+  captureText,
+  captureUrl,
+  originalFileNameForPath,
+} from "../extensions/llm-wiki/lib/source-packet.js";
+```
+
+Then append this `it(...)` inside the `describe("source packet capture", ...)` block, immediately after the test named `"should copy local non-PDF file content to extracted.md"` (ends with `expect(existsSync(join(result.packetPath, "original", "notes.md"))).toBe(true);` + `});`):
+
+```ts
+it("derives the original artifact name with platform basename so drive letters stay out of file names (issue #204)", () => {
+  const absPath =
+    process.platform === "win32" ? "D:\\any\\dir\\doc.md" : "/home/user/any/dir/doc.md";
+  expect(originalFileNameForPath(absPath)).toBe("doc.md");
+});
+```
+
+- [x] **Step 2: Run the test to verify it fails**
+
+Run: `pnpm vitest run test/source-capture.test.ts -t "drive letters"`
+
+Expected: FAIL — module load error: `No export named "originalFileNameForPath"` (the named ESM import does not exist yet).
+
+- [x] **Step 3: Write the minimal implementation**
+
+In `extensions/llm-wiki/lib/source-packet.ts`, make three edits:
+
+1. Line 3 import — change:
+
+```ts
+import { extname, join } from "node:path";
+```
+
+to:
+
+```ts
+import { basename, extname, join } from "node:path";
+```
+
+2. After `originalFileNameForUrl` (the function ending `return "source.html";` + `});`/`}`, ~line 256), add:
+
+```ts
+/**
+ * Original-artifact name for a local file capture. Uses platform basename so
+ * Windows absolute paths (drive colon + backslashes) cannot leak into the
+ * packet/original file name (issue #204).
+ */
+export function originalFileNameForPath(filePath: string): string {
+  return basename(filePath) || "unknown";
+}
+```
+
+3. Inside `fileCaptureSource` (~line 114) — change:
+
+```ts
+  const fileName = filePath.split("/").pop() || "unknown";
+```
+
+to:
+
+```ts
+  const fileName = originalFileNameForPath(filePath);
+```
+
+`fileName` flows into `preserveFileOriginal(packetPath, filePath, fileName, content)` and the manifest `title` — both now get the clean basename.
+
+- [x] **Step 4: Run the test to verify it passes**
+
+Run: `pnpm vitest run test/source-capture.test.ts`
+
+Expected: PASS — all tests in the file green, including the new one.
+
+Note (honest ceiling): on Linux, POSIX `basename("D:\\any\\dir\\doc.md")` returns the string unchanged, so this assertion only has teeth on `win32` — it pins the operation choice (platform basename vs. slash-split) rather than reproducing Windows. Full Windows coverage needs a Windows CI leg or manual repro.
+
+- [x] **Step 5: Run the full gate**
+
+Run: `pnpm test && pnpm typecheck && pnpm lint`
+
+Expected: all green.
+
+- [x] **Step 6: Commit**
+
+```bash
+git add test/source-capture.test.ts extensions/llm-wiki/lib/source-packet.ts
+git commit -m "fix: use platform basename for file capture artifact names (#204)"
+```
+
+---
+
+### Task 3: Push branch, open PR
+
+**Files:** none (git/gh only)
+
+- [x] **Step 1: Push and open the PR**
+
+```bash
+git push -u origin fix/lint-fresh-vault-and-windows-basename
+gh pr create \
+  --title "fix: lint ENOENT on fresh vaults (#203) + Windows capture basename (#204)" \
+  --body "Fixes #203. Fixes #204.
+
+Two one-line fixes with regression tests:
+- wiki_lint: mkdirSync the gitignored .discoveries dir before persisting the gap snapshot (mirrors the autoFix report write in the same function).
+- wiki_capture_source: derive the original artifact name with platform basename instead of split('/').pop() so Windows absolute paths no longer embed a drive colon in the file name."
+```
+
+Expected: PR created; `Fixes #203` / `Fixes #204` auto-close the issues on merge.
+
+---
+
+## Setup (before Task 1)
+
+- [x] **Step 0: Branch from main**
+
+Working tree is clean (verified 2026-09-02); current branch is `qmd-phase-1` — do the work on a dedicated branch off `main`:
+
+```bash
+git checkout main
+git pull --ff-only
+git checkout -b fix/lint-fresh-vault-and-windows-basename
+```
+
+Expected: `Switched to a new branch 'fix/lint-fresh-vault-and-windows-basename'`.

package/extensions/llm-wiki/index.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { bootstrapVault } from "./lib/bootstrap.js";
 import { registerWikiDashboardCommand } from "./lib/dashboard-command.js";
 import { installGuardrails } from "./lib/guardrails.js";

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

@@ -1,8 +1,8 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { KnowledgeDiagnostic } from "./knowledge-document.js";
-import { type ProjectionResult, appendEvent, rebuildMetadata } from "./metadata.js";
-import { type VaultPaths, ensureVaultStructure, fmtDate, writeJson } from "./utils.js";
+import { appendEvent, type ProjectionResult, rebuildMetadata } from "./metadata.js";
+import { ensureVaultStructure, fmtDate, type VaultPaths, writeJson } from "./utils.js";
 import { inspectWritableVault, readVaultConfig } from "./vault-format.js";
 
 export const WIKI_SCHEMA = [

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

@@ -6,9 +6,9 @@
  * from on-disk vault state (see lib/dashboard.ts) and rendered as plain
  * text through a Container + Text.
  */
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { Container, Text, matchesKey } from "@mariozechner/pi-tui";
-import { type DashboardStats, collectDashboardStats } from "./dashboard.js";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, matchesKey, Text } from "@earendil-works/pi-tui";
+import { collectDashboardStats, type DashboardStats } from "./dashboard.js";
 import type { Runtime } from "./runtime.js";
 
 type App = ExtensionAPI;
@@ -84,6 +84,12 @@ export class DashboardScreen extends Container {
   }
 }
 
+// ponytail: overlay options matching pi-blackhole's config modal style
+const OVERLAY_OPTS = {
+  overlay: true,
+  overlayOptions: { anchor: "center", width: "92%", maxHeight: "95%" } as const,
+};
+
 /**
  * Register the /wiki-dashboard command.
  */
@@ -100,7 +106,7 @@ export function registerWikiDashboardCommand(pi: ExtensionAPI, runtime: Runtime)
       const stats = await collectDashboardStats(ctx.cwd);
       await ctx.ui.custom((_tui, _theme, _keybindings, close) => {
         return new DashboardScreen(renderStatsLines(stats), close);
-      });
+      }, OVERLAY_OPTS);
     },
   });
 }

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

@@ -11,7 +11,7 @@
  *
  * No writes, no LLM calls, no new files. Pure reader.
  */
-import { readFile, readdir, stat } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import type { VaultPaths } from "./utils.js";
 import { readJson, resolveVaultPaths } from "./utils.js";
 

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

@@ -7,7 +7,7 @@ import { parseKnowledgeDocument } from "./knowledge-document.js";
 import type { Registry } from "./metadata.js";
 import type { LaunchCtx, Runtime } from "./runtime.js";
 import type { TaskConfig } from "./task-config.js";
-import { type VaultPaths, readJson, writeJson } from "./utils.js";
+import { readJson, type VaultPaths, writeJson } from "./utils.js";
 import { assertWritableVault } from "./vault-format.js";
 
 /**

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

@@ -1,10 +1,10 @@
-import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import { scheduleReindex } from "./indexing.js";
 import { rebuildMetadataLight } from "./metadata.js";
 import type { Runtime } from "./runtime.js";
-import { isPathWithin, isProtectedPath, resolveVaultPaths } from "./utils.js";
 import type { VaultPaths } from "./utils.js";
+import { isPathWithin, isProtectedPath, resolveVaultPaths } from "./utils.js";
 import { inspectVaultFormat, isGeneratedOkfPath } from "./vault-format.js";
 
 /**

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

@@ -1,14 +1,14 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 /**
  * Host adapter for the two coding agents that can load this extension:
  *
- *  - **pi**   — `@mariozechner/pi-coding-agent`, config dir `.pi`
+ *  - **pi**   — `@earendil-works/pi-coding-agent`, config dir `.pi`
  *  - **omp**  — oh-my-pi (`@oh-my-pi/pi-coding-agent`), config dir `.omp`
  *
- * omp rewrites `@mariozechner/pi-*` (and bare `typebox`) imports onto its own
+ * omp rewrites `@earendil-works/pi-*` (and bare `typebox`) imports onto its own
  * bundled packages at load time (its `legacy-pi-compat.ts`), so the *module
  * graph* needs no changes. What does differ is the on-disk config layout:
  *
@@ -129,7 +129,7 @@ export function resolveProjectSettingsPath(cwd: string, host: HostKind = detectH
  *
  * Always writes to `settings.json` inside the agent dir — both hosts read it.
  */
-export function resolveGlobalSettingsPath(host: HostKind = detectHost()): string {
+export function resolveGlobalSettingsPath(_host: HostKind = detectHost()): string {
   let agentDir = "";
   try {
     agentDir = getAgentDir();

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

@@ -1,28 +1,28 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import type { AgentTool } from "@mariozechner/pi-agent-core";
-import type { Api, Model } from "@mariozechner/pi-ai";
-import { Type } from "typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
+import { Type } from "typebox";
 import {
+  createKnowledgeDocument,
   type KnowledgeDiagnostic,
   type KnowledgeDocument,
-  createKnowledgeDocument,
   patchKnowledgeDocument,
   readKnowledgeDocumentFile,
   serializeKnowledgeDocument,
   writeKnowledgeDocumentFile,
 } from "./knowledge-document.js";
 import {
-  type WikilinkValidationMode,
   auditWikilinks,
   buildWikilinkIndex,
+  type WikilinkValidationMode,
 } from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
 import { resolveWikilinkValidation } from "./task-config.js";
-import { type VaultPaths, fmtDate, readJson, slugify } from "./utils.js";
-import { VaultWriteError, assertWritableVault } from "./vault-format.js";
+import { fmtDate, readJson, slugify, type VaultPaths } from "./utils.js";
+import { assertWritableVault, VaultWriteError } from "./vault-format.js";
 
 /**
  * Background ingest synthesis (issue #65, part of epic #63).

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

@@ -225,7 +225,7 @@ function resolveMarkdownTarget(
   // Convert decoded backslashes to /
   const normalized = decoded.map((s) => s.replace(/\\/g, "/")).join("/");
 
-  const sourceDir = sourceId.replace(/[^\/]*$/, ""); // directory of source
+  const sourceDir = sourceId.replace(/[^/]*$/, ""); // directory of source
   const parts = normalized.split("/");
   const isRootRelative = normalized.startsWith("/");
 

package/extensions/llm-wiki/lib/legacy-repair.ts

@@ -1,8 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
-  constants,
   chmodSync,
   closeSync,
+  constants,
   existsSync,
   fstatSync,
   fsyncSync,
@@ -10,8 +10,8 @@ import {
   lstatSync,
   mkdirSync,
   openSync,
-  readFileSync,
   readdirSync,
+  readFileSync,
   renameSync,
   unlinkSync,
   utimesSync,
@@ -19,14 +19,14 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
+  createKnowledgeDocument,
   type DiagnosticCode,
   type KnowledgeDiagnostic,
-  createKnowledgeDocument,
   parseKnowledgeDocument,
   parseMarkdownFrontmatter,
   serializeKnowledgeDocument,
 } from "./knowledge-document.js";
-import { type VaultPaths, readJson } from "./utils.js";
+import { readJson, type VaultPaths } from "./utils.js";
 import { discoverKnowledgeDocuments, inspectVaultFormat } from "./vault-format.js";
 
 const RECOVERABLE = new Set<DiagnosticCode>([

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

@@ -3,8 +3,8 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
-  readFileSync,
   readdirSync,
+  readFileSync,
   renameSync,
   rmSync,
   writeFileSync,
@@ -12,11 +12,11 @@ import {
 import { dirname, join } from "node:path";
 import type { KnowledgeDiagnostic, KnowledgeDocument } from "./knowledge-document.js";
 import {
-  type WikilinkIndex,
   buildResolvedBacklinks,
   buildWikilinkIndex,
+  type WikilinkIndex,
 } from "./knowledge-links.js";
-import { type VaultPaths, isPathWithin, readJson } from "./utils.js";
+import { isPathWithin, readJson, type VaultPaths } from "./utils.js";
 import {
   assertWritableVault,
   compareCodePoint,

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

@@ -1,6 +1,15 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  matchesKey,
+  type SelectItem,
+  SelectList,
+  type SelectListTheme,
+  Spacer,
+  Text,
+} from "@earendil-works/pi-tui";
 import type { Runtime } from "./runtime.js";
-import { type TaskConfig, parseModelRef, persistTaskModel } from "./task-config.js";
+import { parseModelRef, persistTaskModel, type TaskConfig } from "./task-config.js";
 
 /**
  * Model selection surface for the wiki background lane (issue #69, epic #63).
@@ -25,6 +34,12 @@ interface ModelLike {
 /** Words that clear the override and revert to the session model. */
 const CLEAR_WORDS = new Set(["session", "default", "reset", "clear", "none", "unset"]);
 
+/** Sentinel value for the "use session model" picker row — not a valid provider/id. */
+const SESSION_VALUE = "__session__";
+
+/** Same window size as pi's built-in `/model` picker. */
+const MAX_VISIBLE = 10;
+
 /** The status-bar key for the active-model label (so we can update it in place). */
 export const MODEL_STATUS_KEY = "llm-wiki-model";
 
@@ -43,6 +58,85 @@ function modelRef(m: ModelLike): string {
   return `${m.provider}/${m.id}`;
 }
 
+function buildSelectTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("dim", text),
+    scrollInfo: (text) => theme.fg("dim", text),
+    noMatch: (text) => theme.fg("muted", text),
+  };
+}
+
+function buildPickerItems(
+  pool: ModelLike[],
+  currentRef: string | undefined,
+): { items: SelectItem[]; selectedIndex: number } {
+  const items: SelectItem[] = [
+    {
+      value: SESSION_VALUE,
+      label: "↩ Use session model (clear override)",
+      description: currentRef ? undefined : "current",
+    },
+  ];
+  let selectedIndex = 0;
+  for (const m of pool) {
+    const ref = modelRef(m);
+    const isCurrent = currentRef === ref;
+    items.push({
+      value: ref,
+      label: ref,
+      description: isCurrent ? "current" : undefined,
+    });
+    if (isCurrent) selectedIndex = items.length - 1;
+  }
+  return { items, selectedIndex };
+}
+
+/** Editor-dock picker; `ui.custom` without overlay replaces the input slot like `/model`. */
+class ModelPickerScreen extends Container {
+  private list: SelectList;
+  private doneFn: (result?: string) => void;
+  private closed = false;
+
+  constructor(
+    title: string,
+    items: SelectItem[],
+    selectedIndex: number,
+    theme: Theme,
+    done: (result?: string) => void,
+  ) {
+    super();
+    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.addChild(this.list);
+  }
+
+  handleInput(data: string): void {
+    // matchesKey covers kitty CSI-u Esc; SelectList cancel is the fallback.
+    if (matchesKey(data, "escape")) {
+      this.finish(undefined);
+      return;
+    }
+    this.list.handleInput(data);
+  }
+
+  private finish(result?: string): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.doneFn(result);
+  }
+}
+
 /**
  * Register the `/wiki-model` slash command. Lets the user view the active
  * background task model and choose another (or revert to the session model).
@@ -108,15 +202,31 @@ export function registerWikiModelCommand(pi: ExtensionAPI, runtime: Runtime): vo
         return;
       }
 
+      if (typeof ctx.ui.custom !== "function") {
+        ctx.ui.notify(
+          `LLM Wiki: this host does not support the model picker. Pass provider/id (e.g. anthropic/claude-haiku) or "session". Active: ${current}.`,
+          "warning",
+        );
+        return;
+      }
+
       const available = (ctx.modelRegistry.getAvailable() as ModelLike[]) ?? [];
       const pool = available.length > 0 ? available : (ctx.modelRegistry.getAll() as ModelLike[]);
-      const sessionOption = "↩ Use session model (clear override)";
-      const options = [sessionOption, ...pool.map(modelRef)];
+      const currentRef = runtime.config.taskModel ? modelRef(runtime.config.taskModel) : undefined;
+      const { items, selectedIndex } = buildPickerItems(pool, currentRef);
 
-      const picked = await ctx.ui.select(`Wiki background model (current: ${current})`, options);
+      const picked = await ctx.ui.custom<string | undefined>((_tui, theme, _keybindings, done) => {
+        return new ModelPickerScreen(
+          `Wiki background model (current: ${current})`,
+          items,
+          selectedIndex,
+          theme,
+          done,
+        );
+      });
       if (picked === undefined) return; // cancelled
 
-      if (picked === sessionOption) {
+      if (picked === SESSION_VALUE) {
         apply(undefined);
         return;
       }