feat(path-cli): native ratatui picker — Atuin-style selection, skim removed

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to the Toolpath workspace are documented here.
 
+## The built-in picker is now native — Atuin-style session selection — 2026-08-03
+
+The embedded picker behind `path share` / `path resume` /
+`path p import <provider>` is no longer skim: it's a first-party
+ratatui implementation at `crates/path-cli/src/tui/`, built for exactly
+the picking Toolpath does. All picker call sites keep working
+unchanged; the external `fzf` backend is untouched as the escape hatch.
+
+- **`path-cli`** (0.17.0): native picker backend on ratatui 0.30 +
+  nucleo-matcher, rendering on stderr so piped stdout stays clean.
+  Adaptive layouts: preview-less pickers open a small Atuin-style
+  inline viewport under the prompt; preview-bearing pickers take the
+  alternate screen, side-by-side when the terminal is wide enough and
+  stacked when it isn't.
+- Previews run async off the event loop (no tokio): a 100 ms debounce
+  coalesces held-down arrows, results are cached per row, a stale
+  preview never overwrites a newer one, and superseded preview
+  commands are killed. Failures render in-pane instead of crashing
+  the picker.
+- Queries get fzf-style operators via nucleo: space-separated words
+  AND together, plus `'exact`, `^prefix`, and `!negate`. Matching runs
+  over the visible columns only, exactly like `--with-nth`.
+- `--picker native` replaces `--picker skim` (`skim` survives as a
+  hidden alias with a one-time stderr note); `auto` still prefers the
+  built-in backend and falls back to external `fzf` when the
+  `embedded-picker` feature is compiled out.
+- The skim dependency is gone (the `embedded-picker` feature now pulls
+  `ratatui`/`crossterm`/`nucleo-matcher`/`ansi-to-tui`), and opt-in
+  PTY smoke tests (`cargo test -p path-cli --test picker_pty --
+  --ignored`) drive the real binary end to end.
+
 ## Projected Claude sessions are resumable again — 2026-07-30
 
 Two fixes found by live-resuming a projected session against the real

CLAUDE.md

@@ -280,7 +280,7 @@ Build the site after changes: `cd site && pnpm run build` (should produce 11 pag
 - opencode provider: `toolpath-opencode` reads a SQLite database at `~/.local/share/opencode/opencode.db` (opened read-only). Each session's messages and 12 typed part variants (text, reasoning, tool, step-start/-finish, snapshot, patch, file, agent, subtask, retry, compaction) land as one step per message with tool invocations attached. File diffs come from a sibling bare git repo at `snapshot/<project-id>/[<sha1(worktree)>]/` via `git2` tree↔tree diffs — opencode respects the user's `.gitignore`, so changes under gitignored paths fall back to tool-input-derived structural changes with no `raw` perspective. Project id is the SHA of the repo's first root commit. See `docs/agents/formats/opencode.md` for the full format reference.
 - Cursor (IDE) provider: `toolpath-cursor` reads Cursor.app's global `state.vscdb` SQLite (opened read-only) at `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` (macOS; `~/.config/Cursor/...` on Linux). Composers, bubbles, and content-addressed file blobs are stored as key-prefixed rows in the `cursorDiskKV` table (`composerData:<uuid>`, `bubbleId:<comp>:<bubble>`, `composer.content.<hash>`) plus a `composer.composerHeaders` index blob in `ItemTable`. The full tool-dispatch enum (53 entries, ids 0–63) is extracted from the workbench bundle into `TOOL_TABLE` for round-trip-correct numeric ids — projector-written composers load back into Cursor.app's UI with the right tool rendering. The cursor-agent CLI uses a different per-chat protobuf store at `~/.cursor/chats/<wsHash>/<chatId>/store.db` that this crate does not yet parse — that's deferred to a future `toolpath-cursor-cli` companion. See `docs/agents/formats/cursor.md` for the full format reference.
 - Format references for the agent on-disk formats we derive from live at `docs/agents/formats/`. The Claude Code format (`~/.claude/projects/…` JSONL) gets the deepest treatment — twelve focused docs at `docs/agents/formats/claude-code/` covering envelope, entry types, tools, session chains, compaction, writing-compatible JSONL, a linear walkthrough, and a version-keyed changelog. Sibling single-file references: `codex.md`, `gemini.md`, `opencode.md`. Keep them in sync with their derive crates when fields or behaviors change.
-- Interactive session selection: `path p import <provider>` (claude / gemini / pi / codex / opencode) auto-launches a fuzzy picker when stdin and stderr are TTYs and no `--session` was given. Backend: external `fzf` if on `$PATH`, otherwise the embedded skim picker (default-feature `embedded-picker`, defined in `crates/path-cli/src/skim_picker.rs`). Multi-select (TAB) produces a `Graph` document; single-select produces a `Path`. The picker uses `path show <provider> --…` as its `--preview` command. When neither backend can run (no TTY, or `--no-default-features` AND no `fzf`), it falls back to most-recent (with `--project`) or prints the manual recipe (without). `path p list <provider> --format tsv` is the documented machine-readable surface — column 1 is the project (for claude/gemini/pi) or session id (for codex/opencode), and the trailing column carries `first_user_message` so consumers can fuzzy-match by topic.
+- Interactive session selection: `path p import <provider>` (claude / gemini / pi / codex / opencode) auto-launches a fuzzy picker when stdin and stderr are TTYs and no `--session` was given. Backend: the first-party **native picker** at `crates/path-cli/src/tui/` (default-feature `embedded-picker`; ratatui + nucleo-matcher, renders on **stderr** so piped stdout stays clean), with external `fzf` as the escape hatch — the global flag is `--picker auto|fzf|native` (`skim` is a hidden legacy alias for `native`; `auto` prefers native and falls back to `fzf` only when the feature is compiled out). Layouts are adaptive: no preview → small inline viewport under the prompt; preview configured → fullscreen alt-screen (side-by-side at ≥100 cols, stacked below); previews run debounced (100 ms) on worker threads with per-row caching and kill-on-supersede. Multi-select (TAB) produces a `Graph` document; single-select produces a `Path`. The picker uses `path show <provider> --…` as its `--preview` command. When neither backend can run (no TTY, or `--no-default-features` AND no `fzf`), it falls back to most-recent (with `--project`) or prints the manual recipe (without). `path p list <provider> --format tsv` is the documented machine-readable surface — column 1 is the project (for claude/gemini/pi) or session id (for codex/opencode), and the trailing column carries `first_user_message` so consumers can fuzzy-match by topic. Opt-in PTY smoke tests: `cargo test -p path-cli --test picker_pty -- --ignored`.
 - Conversation metadata title field: `toolpath-claude::ConversationMetadata`, `toolpath-gemini::ConversationMetadata`, and `toolpath-pi::SessionMeta` all expose `first_user_message: Option<String>` — the first non-empty user-prompt text. Populated cheaply during the metadata pass (single-pass for Claude/Gemini; one extra short read for Pi). Used by the picker UI but useful for any "list sessions by topic" surface.
 - `path share` is the one-shot equivalent of `path p import <harness> | path p export pathbase`. It probes installed agent harnesses (claude/gemini/codex/opencode/pi), aggregates their sessions into a single fzf picker, and ranks rows whose project (claude/gemini/pi) or recorded cwd (codex/opencode) canonicalizes to the current directory at the top. `--harness` narrows the picker to one provider; `--harness X --session Y` (and `--project P` for keyed providers) skips the picker entirely. Pathbase flags (`--url`, `--anon`, `--repo`, `--slug`, `--public`) match `path export pathbase`. By default the derived doc is written to the cache like `import` does; pass `--no-cache` to skip. When the manifest shows the picked session unchanged since its last sync (`sync::fresh_cache_id`: stamps match, doc present; the freshness stat targets that one artifact directly, no sibling enumeration), share uploads the cached doc directly instead of re-deriving. The cache ingests maximally (thinking always included), and uploads carry the same full derivation as local projection (`resume`, `p export <harness>`) — there is no egress stripping.
 - `path resume <input>` is the inverse of `path share`. It accepts a Pathbase URL, an `owner/repo/slug` shorthand, a local toolpath JSON file, or a cache id; resolves it (caching URL fetches under `~/.toolpath/documents/` unless `--no-cache`); validates that the document is a single agent-bearing `Path`; then opens an `fzf` harness picker (skipped with `--harness X`). The picker pre-selects the source harness inferred from `path.meta.source` (`claude-code`/`gemini-cli`/`codex`/`opencode`/`pi`) when it's installed. After picking, `path resume` projects the session into the harness's on-disk layout under the chosen working directory (default: shell cwd; override with `-C, --cwd P`) and `execvp`'s the harness's resume command (`claude -r <id>` / `gemini --resume <id>` / `codex resume <id>` / `opencode --session <id>` / `pi --session <id>`). On Windows it spawns and waits, propagating the exit code. The exec is mockable via `cmd_resume::ExecStrategy` — production uses `RealExec`; integration tests use `RecordingExec` to capture the recipe without launching a real harness.