@vigent/cli 0.2.3 → 0.3.1

package/dist/hunk-review.js

@@ -0,0 +1,218 @@
+/**
+ * The `:review` window: the agent's changes hunk by hunk.
+ *
+ *   j/k ]c/[c  next / previous hunk      J/K  next / previous file
+ *   x  drop the hunk (take it out of the worktree)
+ *   X  drop the whole file               u  undo the last drop
+ *   q / Esc  close
+ */
+import { truncateToWidth, visibleWidth } from "./tui.js";
+import { patchFor } from "./hunks.js";
+import { keyFromInput } from "./keys.js";
+import { RESET } from "./theme.js";
+export class HunkReview {
+    painter;
+    icons;
+    title;
+    files;
+    height;
+    host;
+    flat = [];
+    index = 0;
+    top = 0;
+    undo = [];
+    dropped = 0;
+    message = "";
+    busy = false;
+    constructor(painter, icons, title, files, height, host) {
+        this.painter = painter;
+        this.icons = icons;
+        this.title = title;
+        this.files = files;
+        this.height = height;
+        this.host = host;
+        this.flatten();
+    }
+    flatten() {
+        this.flat = this.files.flatMap((file, fileIdx) => file.hunks.map((hunk) => ({ file, hunk, fileIdx })));
+        this.index = Math.min(this.index, Math.max(0, this.flat.length - 1));
+    }
+    rows(width) {
+        const out = [];
+        this.files.forEach((file, fi) => {
+            const n = file.hunks.length;
+            out.push({ text: `${file.path}  ${file.binary ? "(binary: X drops it)" : `${n} hunk${n === 1 ? "" : "s"}`}`, group: "Title", hunk: -1, header: true });
+            for (const hunk of file.hunks) {
+                const idx = this.flat.findIndex((h) => h.hunk === hunk && h.fileIdx === fi);
+                out.push({ text: hunk.header, group: "Special", hunk: idx, header: true });
+                for (const l of hunk.lines) {
+                    out.push({
+                        text: truncateToWidth(l.replace(/\t/g, "  "), width, "…"),
+                        group: l.startsWith("+") ? "Added" : l.startsWith("-") ? "Removed" : l.startsWith("\\") ? "Comment" : "NormalFloat",
+                        hunk: idx,
+                    });
+                }
+            }
+        });
+        return out;
+    }
+    handleInput(data) {
+        const key = keyFromInput(data);
+        if (this.busy)
+            return;
+        switch (key) {
+            case "q":
+            case "<Esc>":
+            case "<C-c>":
+                this.host.close();
+                return;
+            case "j":
+            case "n":
+            case "<Down>":
+            case "<Tab>":
+                this.move(1);
+                break;
+            case "k":
+            case "N":
+            case "<Up>":
+            case "<S-Tab>":
+                this.move(-1);
+                break;
+            case "]":
+            case "[":
+                this.pendingBracket = key;
+                return;
+            case "c":
+                if (this.pendingBracket)
+                    this.move(this.pendingBracket === "]" ? 1 : -1);
+                break;
+            case "J":
+                this.moveFile(1);
+                break;
+            case "K":
+                this.moveFile(-1);
+                break;
+            case "g":
+                this.index = 0;
+                break;
+            case "G":
+                this.index = Math.max(0, this.flat.length - 1);
+                break;
+            case "x":
+                this.dropHunk();
+                return;
+            case "X":
+                this.dropFile();
+                return;
+            case "u":
+                this.undoLast();
+                return;
+        }
+        this.pendingBracket = undefined;
+        this.host.requestRender();
+    }
+    pendingBracket;
+    move(d) {
+        if (this.flat.length === 0)
+            return;
+        this.index = Math.max(0, Math.min(this.flat.length - 1, this.index + d));
+    }
+    moveFile(d) {
+        const cur = this.flat[this.index]?.fileIdx ?? 0;
+        const target = d > 0 ? this.flat.findIndex((h) => h.fileIdx > cur) : this.flat.findIndex((h) => h.fileIdx === Math.max(0, cur - 1));
+        if (target >= 0)
+            this.index = target;
+    }
+    run(patch, label, action) {
+        this.busy = true;
+        this.message = action === "drop" ? "dropping…" : "restoring…";
+        this.host.requestRender();
+        (action === "drop" ? this.host.drop(patch) : this.host.restore(patch))
+            .then((files) => {
+            if (action === "drop") {
+                this.undo.push({ patch, label });
+                this.dropped++;
+                this.message = `dropped ${label} · u undoes`;
+            }
+            else {
+                this.dropped--;
+                this.message = `restored ${label}`;
+            }
+            this.files = files;
+            this.flatten();
+        })
+            .catch((err) => {
+            this.message = `git couldn't ${action === "drop" ? "drop" : "restore"} ${label}: ${err.message}`;
+        })
+            .finally(() => {
+            this.busy = false;
+            this.host.requestRender();
+        });
+    }
+    dropHunk() {
+        const cur = this.flat[this.index];
+        if (!cur)
+            return;
+        const n = cur.file.hunks.indexOf(cur.hunk) + 1;
+        this.run(patchFor(cur.file, [cur.hunk]), `hunk ${n} of ${cur.file.path}`, "drop");
+    }
+    dropFile() {
+        const cur = this.flat[this.index];
+        const file = cur?.file ?? this.files[0];
+        if (!file)
+            return;
+        if (file.binary && file.hunks.length === 0) {
+            this.message = "binary files can't be dropped here yet";
+            this.host.requestRender();
+            return;
+        }
+        this.run(patchFor(file), file.path, "drop");
+    }
+    undoLast() {
+        const last = this.undo.pop();
+        if (!last) {
+            this.message = "nothing to undo";
+            this.host.requestRender();
+            return;
+        }
+        this.run(last.patch, last.label, "restore");
+    }
+    invalidate() { }
+    render(width) {
+        const P = this.painter;
+        const I = this.icons;
+        const inner = Math.max(30, width) - 2;
+        const bg = P.attr("NormalFloat").bg;
+        const sel = P.attr("PmenuSel").bg ?? P.attr("Visual").bg;
+        const border = (s) => P.on("FloatBorder", bg) + s + RESET;
+        const row = (content, used, rowBg = bg) => border(I.v) + content + P.on("NormalFloat", rowBg) + " ".repeat(Math.max(0, inner - used)) + RESET + border(I.v);
+        const total = this.flat.length;
+        const title = ` ${this.title} · ${total} hunk${total === 1 ? "" : "s"} left${this.dropped ? ` · ${this.dropped} dropped` : ""} `;
+        const lines = [border(I.tl + I.h) + P.on("FloatTitle", bg) + truncateToWidth(title, inner - 2, "…") + RESET + border(I.h.repeat(Math.max(0, inner - 1 - visibleWidth(truncateToWidth(title, inner - 2, "…")))) + I.tr)];
+        const body = Math.max(3, this.height() - 4);
+        const rows = this.rows(inner - 3);
+        if (total === 0) {
+            rows.length = 0;
+            rows.push({ text: this.dropped ? "every change is dropped: nothing would be merged (u undoes)" : "no changes", group: "Comment", hunk: -1 });
+        }
+        // keep the selected hunk's header in view, a little below the top
+        const at = rows.findIndex((r) => r.hunk === this.index && r.header);
+        if (at >= 0 && (at < this.top || at >= this.top + body - 3))
+            this.top = Math.max(0, at - 2);
+        this.top = Math.min(this.top, Math.max(0, rows.length - body));
+        for (const r of rows.slice(this.top, this.top + body)) {
+            const on = r.hunk === this.index && total > 0;
+            const rowBg = on && r.header ? sel : bg;
+            const bar = on ? P.on("Title", rowBg) + "▌ " : P.on("NormalFloat", rowBg) + "  ";
+            const text = truncateToWidth(r.text, inner - 3, "…");
+            lines.push(row(bar + P.on(on && r.header ? "PmenuSel" : r.group, rowBg) + text, 2 + visibleWidth(text), rowBg));
+        }
+        while (lines.length < body + 1)
+            lines.push(row("", 0));
+        const msg = this.message || "x drop hunk · X drop file · u undo · j/k hunks · J/K files · q close · :merge takes what's left";
+        lines.push(border(I.lt + I.h.repeat(inner) + I.rt));
+        lines.push(row(P.on(this.message ? "ModeMsg" : "Comment", bg) + ` ${truncateToWidth(msg, inner - 2, "…")}`, Math.min(inner, visibleWidth(msg) + 1)));
+        lines.push(border(I.bl + I.h.repeat(inner) + I.br));
+        return lines;
+    }
+}

package/dist/hunks.js

@@ -0,0 +1,60 @@
+/**
+ * `:review`: keep or drop the agent's changes one hunk at a time.
+ *
+ * The diff is the agent's whole change, fork point → working tree (commits,
+ * uncommitted edits and new files). Dropping a hunk reverse-applies just that
+ * hunk to the worktree (`git apply -R`), so `:merge` / `:pr`, which commit
+ * what's in the worktree, no longer carry it. Undo applies it again.
+ */
+import { execFile } from "node:child_process";
+/** Split `git diff` output into files and hunks. */
+export function parseDiff(text) {
+    const files = [];
+    let file;
+    let hunk;
+    for (const line of text.replace(/\n$/, "").split("\n")) {
+        if (line.startsWith("diff --git ")) {
+            const m = /^diff --git a\/(.*) b\/(.*)$/.exec(line);
+            file = { path: m ? m[2] : line.slice(11), header: [line], hunks: [], binary: false };
+            files.push(file);
+            hunk = undefined;
+            continue;
+        }
+        if (!file)
+            continue;
+        if (line.startsWith("@@")) {
+            hunk = { header: line, lines: [] };
+            file.hunks.push(hunk);
+            continue;
+        }
+        if (hunk) {
+            // "… N more lines" from a truncated diff is not part of any hunk
+            if (/^[ +\-\\]/.test(line) || line === "")
+                hunk.lines.push(line);
+            continue;
+        }
+        if (/^Binary files /.test(line) || line === "GIT binary patch")
+            file.binary = true;
+        file.header.push(line);
+    }
+    return files;
+}
+/** A patch with one file's header and just these of its hunks. */
+export function patchFor(file, hunks = file.hunks) {
+    // a new file's single hunk must create the whole file; a partial patch can't say "new file"
+    return `${[...file.header, ...hunks.flatMap((h) => [h.header, ...h.lines])].join("\n")}\n`;
+}
+function gitApply(cwd, patch, reverse) {
+    return new Promise((resolve, reject) => {
+        const child = execFile("git", ["apply", ...(reverse ? ["-R"] : []), "--whitespace=nowarn", "--recount", "-"], { cwd }, (err, _stdout, stderr) => (err ? reject(new Error(String(stderr).trim().split("\n")[0].replace(/^error: /, "") || err.message)) : resolve()));
+        child.stdin?.end(patch);
+    });
+}
+/** Take a change out of the agent's worktree. */
+export function dropPatch(worktree, patch) {
+    return gitApply(worktree, patch, true);
+}
+/** Put a dropped change back. */
+export function restorePatch(worktree, patch) {
+    return gitApply(worktree, patch, false);
+}

package/dist/icons.js

@@ -31,6 +31,7 @@ export const NERD = {
     list: "", // nf-fa-list
     caretRight: "", // nf-fa-caret_right
     caretDown: "", // nf-fa-caret_down
+    bell: "", // nf-fa-bell
 };
 /** An icon for a tool call, by the tool's name (Claude Code, Codex, OpenCode and pi names). */
 export function toolIcon(name) {

package/dist/keys.js

@@ -13,7 +13,7 @@
  * Like vim, a key that starts a longer mapping waits `timeoutlen` ms for the
  * rest; that is what makes `jk` = `<Esc>` in insert mode work.
  */
-import { parseKey } from "@mariozechner/pi-tui";
+import { parseKey } from "./tui.js";
 import { didYouMean } from "./suggest.js";
 export const KEY_MODES = ["normal", "insert", "visual", "command"];
 /** vigent's default <leader>, as in most Neovim configs (vim's own default is "\\") */
@@ -127,6 +127,8 @@ export const DEFAULT_KEYS = {
         "<leader>D": ":dash<CR>",
         "<leader>u": "session.tree",
         "<leader>s": ":settings<CR>",
+        "<leader>r": ":review<CR>",
+        "<leader>T": ":templates<CR>",
         "<leader>M": ":model<CR>",
         "<leader>e": ":effort<CR>",
         "<leader>E": ":engine<CR>",

package/dist/main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * The `vigent` command. Before anything else loads, it turns on Node's
+ * compile cache (Node 22.1 and later): the compiled code of vigent and its
+ * packages is kept on disk, so later starts skip compiling it again. That
+ * matters most for the pi engine's SDK, which is large. Set
+ * NODE_DISABLE_COMPILE_CACHE=1 to turn it off.
+ */
+import module from "node:module";
+try {
+    module.enableCompileCache?.();
+}
+catch {
+    // no cache: a read-only temp folder, say. Starting matters more.
+}
+await import("./cli.js");

package/dist/markdown.js

@@ -4,7 +4,7 @@
  * bullet lists, and > quotes (Comment). Code blocks are numbered so
  * VISUAL-mode `ib` and `yib` can select them.
  */
-import { wrapTextWithAnsi } from "@mariozechner/pi-tui";
+import { wrapTextWithAnsi } from "./tui.js";
 import { RESET } from "./theme.js";
 function inline(P, text) {
     let out = "";

package/dist/notify.js

@@ -0,0 +1,33 @@
+/**
+ * Telling you an agent is done while you look elsewhere: the terminal bell,
+ * and a desktop notification in terminals that show one for OSC 9 (iTerm2,
+ * WezTerm, Ghostty, kitty). Inside tmux the notification is passed through
+ * to the outer terminal.
+ */
+export const NOTIFY_MODES = ["auto", "bell", "desktop", "off"];
+/** Does this terminal turn OSC 9 into a desktop notification? */
+export function showsDesktopNotifications(env = process.env) {
+    const program = env.TERM_PROGRAM ?? "";
+    return (["iTerm.app", "WezTerm", "ghostty"].includes(program) ||
+        Boolean(env.KITTY_WINDOW_ID) ||
+        Boolean(env.GHOSTTY_RESOURCES_DIR) ||
+        Boolean(env.WEZTERM_PANE) ||
+        /kitty|ghostty/.test(env.TERM ?? ""));
+}
+/** The bytes to write for a notification: a bell, an OSC 9 notification, both, or nothing. */
+export function alertSequence(text, mode, env = process.env) {
+    if (mode === "off")
+        return "";
+    const desktop = mode === "desktop" || (mode === "auto" && showsDesktopNotifications(env));
+    let out = mode === "desktop" ? "" : "\x07";
+    if (desktop) {
+        // no control characters inside the notification text
+        const osc = `\x1b]9;${text.replace(/[\x00-\x1f\x7f]/g, " ")}\x07`;
+        // tmux swallows OSC 9 unless it's wrapped in a passthrough
+        out += env.TMUX ? `\x1bPtmux;${osc.replace(/\x1b/g, "\x1b\x1b")}\x1b\\` : osc;
+    }
+    return out;
+}
+/** Ask the terminal to report focus changes (\x1b[I / \x1b[O), so a visible agent doesn't notify. */
+export const FOCUS_REPORTING_ON = "\x1b[?1004h";
+export const FOCUS_REPORTING_OFF = "\x1b[?1004l";

package/dist/pi-sdk.js

@@ -0,0 +1,45 @@
+/**
+ * The pi engine's packages, loaded only when a pi agent needs them.
+ *
+ * They're the bulk of an install (about 200 MB with every model provider's
+ * SDK), and optional: the light install (`npm install --prefix ~/.vigent
+ * --omit=optional @vigent/cli`) leaves them out for people who only run Claude
+ * Code, Codex or OpenCode. Then pi shows as not installed, and nothing else
+ * changes. (npm ignores --omit=optional with -g, hence the folder.)
+ */
+export const PI_PACKAGE = "@mariozechner/pi-coding-agent";
+export const PI_INSTALL = "install vigent again without --omit=optional to add it";
+/** Whether the pi engine is installed next to vigent (found the way an import would find it). */
+export function piInstalled(resolve = (s) => import.meta.resolve(s)) {
+    try {
+        resolve(PI_PACKAGE);
+        resolve("@mariozechner/pi-ai");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function missing(err) {
+    const code = err?.code;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+const NOT_INSTALLED = `pi isn't installed (this is vigent's light install): ${PI_INSTALL}`;
+/** pi's agent SDK. */
+export async function loadPiSdk() {
+    try {
+        return await import("@mariozechner/pi-coding-agent");
+    }
+    catch (err) {
+        throw missing(err) ? new Error(NOT_INSTALLED) : err;
+    }
+}
+/** pi's model catalog and providers. */
+export async function loadPiAi() {
+    try {
+        return await import("@mariozechner/pi-ai");
+    }
+    catch (err) {
+        throw missing(err) ? new Error(NOT_INSTALLED) : err;
+    }
+}

package/dist/pi-ui.js

@@ -0,0 +1,78 @@
+/**
+ * pi extensions inside vigent.
+ *
+ * pi loads extensions (~/.pi/agent/extensions/, .pi/extensions/), skills and
+ * prompt templates by itself. What it needs from the program around it is a
+ * UI: an extension that asks before `rm -rf` calls ctx.ui.confirm(), a
+ * command answers with ctx.ui.notify(). This is that UI, drawn the vigent way:
+ * confirm is a y/n question, select and input are pickers, notify goes to the
+ * transcript and the message line, setStatus shows in the winbar. The parts
+ * that only make sense in pi's own TUI (custom editors, widgets, headers and
+ * footers) do nothing here, as they do in pi's print mode.
+ */
+/**
+ * pi's ExtensionUIContext over a host that may come later: until vigent
+ * attaches one (or in tests without a screen), dialogs answer like pi's print
+ * mode: no selection, no confirmation, no input.
+ */
+export function extensionUi(host, theme) {
+    const nothing = () => { };
+    return {
+        select: async (title, options) => host()?.select(title, options),
+        confirm: async (title, message) => (await host()?.confirm(title, message)) ?? false,
+        input: async (title, placeholder) => host()?.input(title, placeholder),
+        editor: async (title, prefill) => host()?.input(title, prefill),
+        notify: (message, type = "info") => host()?.notify(String(message), type),
+        setStatus: (key, text) => host()?.setStatus(key, text),
+        onTerminalInput: () => nothing,
+        setWorkingMessage: nothing,
+        setWorkingVisible: nothing,
+        setWorkingIndicator: nothing,
+        setHiddenThinkingLabel: nothing,
+        setWidget: nothing,
+        setFooter: nothing,
+        setHeader: nothing,
+        setTitle: nothing,
+        custom: async () => undefined,
+        pasteToEditor: nothing,
+        setEditorText: nothing,
+        getEditorText: () => "",
+        addAutocompleteProvider: nothing,
+        setEditorComponent: nothing,
+        getEditorComponent: () => undefined,
+        get theme() {
+            return theme();
+        },
+        getAllThemes: () => [],
+        getTheme: () => undefined,
+        setTheme: () => ({ success: false, error: "vigent draws its own theme (:colorscheme)" }),
+        getToolsExpanded: () => false,
+        setToolsExpanded: nothing,
+    };
+}
+/** Read what pi loaded from a live AgentSession. Anything missing reads as empty. */
+export function piResources(session) {
+    const loader = session?.resourceLoader;
+    const safe = (fn, fallback) => {
+        try {
+            return fn() ?? fallback;
+        }
+        catch {
+            return fallback;
+        }
+    };
+    const ext = safe(() => loader.getExtensions(), { extensions: [], errors: [] });
+    return {
+        extensions: [
+            ...(ext.extensions ?? []).map((e) => ({ path: String(e.resolvedPath ?? e.path ?? "") })),
+            ...(ext.errors ?? []).map((e) => ({ path: String(e.path ?? ""), error: String(e.error ?? "failed to load") })),
+        ],
+        commands: safe(() => session.extensionRunner.getRegisteredCommands(), []).map((c) => ({
+            name: String(c.invocationName ?? c.name),
+            description: c.description,
+        })),
+        skills: safe(() => loader.getSkills().skills, []).map((s) => ({ name: String(s.name), description: s.description, path: s.filePath })),
+        prompts: safe(() => session.promptTemplates, []).map((p) => ({ name: String(p.name), description: p.description })),
+        contextFiles: safe(() => loader.getAgentsFiles().agentsFiles, []).map((f) => String(f.path)),
+    };
+}

package/dist/picker.js

@@ -4,7 +4,7 @@
  * Type to filter, arrows / Ctrl-n / Ctrl-p / Tab to move (each move previews
  * the theme live), Enter to keep it, Esc to go back to the previous theme.
  */
-import { fuzzyFilter, parseKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { fuzzyFilter, parseKey, truncateToWidth, visibleWidth } from "./tui.js";
 import { RESET, sgr } from "./theme.js";
 export const PICKER_ICONS = {
     unicode: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", lt: "├", rt: "┤", current: "●", prompt: "❯" },
@@ -227,7 +227,9 @@ export class ChoicePicker {
     scroll = 0;
     items = [];
     loading = true;
-    constructor(painter, icons, title, items, current, custom, onDone, requestRender) {
+    onBackOut;
+    rows;
+    constructor(painter, icons, title, items, current, custom, onDone, requestRender, opts = {}) {
         this.painter = painter;
         this.icons = icons;
         this.title = title;
@@ -235,12 +237,15 @@ export class ChoicePicker {
         this.custom = custom;
         this.onDone = onDone;
         this.requestRender = requestRender;
+        this.searching = opts.search ?? false;
+        this.rows = opts.rows ?? VISIBLE;
+        this.onBackOut = opts.onBackOut;
         Promise.resolve(items)
             .then((list) => {
             this.items = list;
             this.loading = false;
             this.index = Math.max(0, list.findIndex((c) => c.value === current));
-            this.scroll = Math.max(0, this.index - VISIBLE + 1);
+            this.scroll = Math.max(0, this.index - this.rows + 1);
             this.requestRender();
         })
             .catch(() => {
@@ -276,6 +281,8 @@ export class ChoicePicker {
             else if (key === "backspace") {
                 if (this.query)
                     this.query = this.query.slice(0, -1);
+                else if (this.onBackOut)
+                    return this.onBackOut();
                 else
                     this.searching = false;
                 this.index = 0;
@@ -321,8 +328,8 @@ export class ChoicePicker {
         }
         if (this.index < this.scroll)
             this.scroll = this.index;
-        if (this.index >= this.scroll + VISIBLE)
-            this.scroll = this.index - VISIBLE + 1;
+        if (this.index >= this.scroll + this.rows)
+            this.scroll = this.index - this.rows + 1;
         this.requestRender();
     }
     invalidate() { }
@@ -334,7 +341,7 @@ export class ChoicePicker {
         const border = (s) => P.on("FloatBorder", bg) + s + RESET;
         const row = (content, used, rowBg = bg) => border(I.v) + content + P.on("NormalFloat", rowBg) + " ".repeat(Math.max(0, inner - used)) + RESET + border(I.v);
         const items = this.filtered();
-        const title = ` ${this.title} `;
+        const title = truncateToWidth(` ${this.title} `, Math.max(0, inner - 2), "…");
         const lines = [border(I.tl + I.h) + P.on("FloatTitle", bg) + title + RESET + border(I.h.repeat(Math.max(0, inner - 1 - visibleWidth(title))) + I.tr)];
         if (this.searching) {
             lines.push(row(P.on("Title", bg) + ` ${I.prompt} ` + RESET + P.on("NormalFloat", bg) + this.query + P.on("PmenuSel", undefined) + " " + RESET, visibleWidth(this.query) + 4));
@@ -345,15 +352,15 @@ export class ChoicePicker {
             lines.push(row(P.on("Comment", bg) + ` ${I.prompt} ${text}` + RESET, visibleWidth(text) + 3));
         }
         lines.push(border(I.lt + I.h.repeat(inner) + I.rt));
-        const shown = items.slice(this.scroll, this.scroll + VISIBLE);
-        for (let i = 0; i < VISIBLE; i++) {
+        const shown = items.slice(this.scroll, this.scroll + this.rows);
+        for (let i = 0; i < this.rows; i++) {
             const c = shown[i];
             if (!c) {
                 let text = "";
                 if (i === 0 && this.loading)
                     text = "  loading…";
                 else if (i === 0 && items.length === 0)
-                    text = this.custom && this.query.trim() ? `  Enter uses '${this.query.trim()}'` : "  no match";
+                    text = this.custom && this.query.trim() ? `  Enter uses '${this.query.trim()}'` : this.custom && this.items.length === 0 ? "  type it, then Enter" : "  no match";
                 lines.push(row(P.on("Comment", bg) + truncateToWidth(text, inner, "…") + RESET, Math.min(inner, visibleWidth(text))));
                 continue;
             }
@@ -361,9 +368,12 @@ export class ChoicePicker {
             const rowBg = selected ? (P.attr("PmenuSel").bg ?? P.attr("Visual").bg) : bg;
             const group = selected ? "PmenuSel" : "NormalFloat";
             const marker = c.value === this.current ? `${I.current} ` : "  ";
-            const name = truncateToWidth(`${marker}${c.value}`, Math.max(10, inner - 4), "…");
+            // notes line up in a column after the longest name (up to a third of the width)
+            const nameW = Math.min(Math.floor(inner / 3), Math.max(...items.map((x) => visibleWidth(x.value))));
+            const padded = c.note ? c.value + " ".repeat(Math.max(0, nameW - visibleWidth(c.value))) : c.value;
+            const name = truncateToWidth(`${marker}${padded}`, Math.max(10, inner - 4), "…");
             const note = c.note ? truncateToWidth(`  ${c.note}`, Math.max(0, inner - 2 - visibleWidth(name)), "…") : "";
-            lines.push(row(P.on(group, rowBg) + ` ${name}` + P.on("Comment", rowBg) + note + RESET, 1 + visibleWidth(name) + visibleWidth(note), rowBg));
+            lines.push(row(P.on(group, rowBg) + ` ${name}` + P.on(selected ? "PmenuSel" : "Comment", rowBg) + note + RESET, 1 + visibleWidth(name) + visibleWidth(note), rowBg));
         }
         const keys = this.searching ? "type to filter · Esc done" : "j/k move · Enter pick · q close";
         const count = ` ${items.length ? this.index + 1 : 0}/${items.length} · ${keys} `;