# pivi end-to-end proof

Run `just test-e2e` from `neovim/`.
Run `just test tests/bugabinga/pivi`, `just drive`, `just test-contract` for complementary layers.

`run.lua` owns isolated child Neovim; `scenarios.lua` drives real `:Pi` commands, native buffer mappings, RPC barriers, editor state.
`provider.ts` registers installed Pi AI’s native `fauxProvider`, scripts responses through extension commands, holds requests until explicit release or abort.
Pi still loads user extensions, skills, prompts, settings, providers, context through normal discovery.
Suite asserts user-scoped resources actually reached `get_commands`.
Only additive test extension, explicit zero-cost model, temporary session directory, native `--offline` are added.
Original repository project-local Pi resources are not exercised: execution cwd is isolated temporary project.
No metered model, provider HTTP server, protocol emulator, filesystem watcher, sleeps, live-editor restart, global config write.
`--offline` prevents Pi’s automatic network refresh; arbitrary user extensions can still perform their own I/O.
Runtime files live in OS temp; runner closes owned Pi children, waits for exit, quits owned editor, removes scratch directory.
Failed startup, predicate deadline, RPC response, handler failure, cleanup → nonzero exit.
Every owned RPC child’s `failures()` is asserted empty after shutdown, including help, replaced, stopped children.
`PIVI_E2E_INJECT_HANDLER_FAILURE=1` injects real response-handler exception; cleanup must exit nonzero with owned-child diagnostic.
Global Pi `settings.json` bytes are read before startup, compared after cleanup; unreadable or changed settings fail closed.
Native picker overrides restore after every scenario, including exceptions.
Autocompaction E2E is excluded: Pi’s `set_auto_compaction` persists global settings rather than session-local state.
Initial development runs unintentionally set global `compaction.enabled=false`.
Prior implementation transcript `01a12064-d46f-7364-bf6f-cefdef5438d3`, entry `9b2cb98a`, line 232 confirms added field versus committed settings, not original working-tree value.
All 248 transcript entries inspected; no pre-write settings content or diff captured.
User approved Default autocompaction → parent removed only `compaction` object from global settings; unrelated edits, including `hideThinkingBlock`, preserved.
Current suite runs with default autocompaction, never invokes its globally persistent toggle.
Native `vim.g.pivi_arguments` adds CLI arguments to working/help children without replacing normal config.

## Coverage matrix

Goal numbers follow acceptance bullets in binding `.system/specs/NVIM-SPEC-GMWDCMJZ-pivi-native-neovim-integration/index.md`.
E2E means real child Neovim + Pi + faux provider; editor/pure means existing Plenary coverage, not model-to-editor proof.
No line-coverage percentage is claimed.

| Goal | Evidence | Boundary / gap |
| --- | --- | --- |
| 1 slash commands / slash position | E2E slash; drive slash; command_spec | Actual first-character keyboard entry remains drive rather than provider E2E |
| 2 authored markdown / code / copying | E2E ask; editor/render_spec | Actual pixels manual L6 |
| 3 collapsed subject / outcome / focus | E2E edit; editor/highlight_spec, fold_spec | Actual pixels manual L6 |
| 4 expand / collapse / detail | E2E edit native folds, native entry inspection float; editor/detail_spec | Actual pixels manual L6 |
| 5 diff / dedicated comparison / navigation | E2E edit `:Pi diff`, native first-change navigation; editor/diff_spec, navigate_spec | Actual pixels manual L6 |
| 6 progressive output / truncation / full output | E2E native RPC shell with release barrier, 3000-line truncation, full-output navigation; session_spec | Requires installed shell + node; no timed sleeps |
| 7 grouped search / quickfix | E2E actual upstream grep across files, file-heading/conceal/highlight extmarks, quickfix; tool_spec | Known grep location rows grouped; opaque extension search output stays readable |
| 8 syntax-aware read / location | E2E tools; editor/render_spec, navigate_spec | Navigation editor layer; actual pixels manual |
| 9 failed tool single line | E2E findings/follow/failure; tool_spec | Verified with missing-file read |
| 10 collapsed result / history unchanged | E2E edit; editor/fold_spec | Native folds verified against real persisted history |
| 11 entry motions / locations | E2E native next/previous tool mappings, first-change/full-output navigation; editor/navigate_spec | Callback invocation rather than physical keypress |
| 12 no presentation RPC / stream budget | E2E ask cached summary; editor/render_spec | Long answer budget editor layer |
| 13 help during working run / isolation | E2E help | Real held working run + independent help child |
| 14 bounded help view / recent messages / error | E2E actual outgoing RPC payload for originating view, hidden tail exclusion, layout, selection, messages/error; context_spec, help_spec | Native transport observed without replacing provider; line + Unicode-character bounds |
| 15 running-version / plugin docs | E2E help `nvim_help`, real tool resolves installed Plenary docs; docs_spec | Actual model answer semantics not evaluated by scripted provider |
| 16 help cannot mutate | help_spec allowlist; E2E help safety scripted malicious Lua/write calls | Unrestricted Lua removed from help allowlist; trusted user extension hooks still retain OS permissions |
| 17 steer / follow-up delivery | E2E delivery | Both persisted after explicit release |
| 18 prompt accept steers / distinct follow-up | E2E queue; command_spec | Buffer-local native mapping callback, not physical keypress |
| 19 list / clear pending queue | E2E queue | Actual `:Pi queue`, `:Pi clear` |
| 20 create / switch / stop / independent lifetime | E2E sessions, prompt, stop | Multiple owned Pi children |
| 21 latest / explicit resume / no model | E2E resume latest, resume identity | Identity and model-call counter asserted |
| 22 prior-session listing / choose | E2E `:Pi prior` native picker resumes persisted identity without model; resume completion; store_spec | `:Pi sessions` remains live-session picker; `:Pi resume` remains latest |
| 23 restored addressable history / tool pairing | E2E restart, branched recorded-session fixture, 2000 real recorded-message copies, timer callbacks interleave; `:Pi new` rejected after yielded restore; backfill_spec | Active leaf ancestry only; discarded text/results excluded; selected tool details retained; enforced 10s total budget currently fails |
| 24 silent restored tool / no fabricated diff | backfill_spec, tool_spec | Real restoration now preserves reported details |
| 25 restart history / identity / place | E2E restart, sessions, arbitrary `large.jsonl` restart with CLI-only `--session-dir` | Real child replacement; 2000-message identity/history retained without conventional filename or store env; draft, transcript buffer, cursor, active session; empty sessions use native `--session-id` |
| 26 descriptors / idempotent external restore | E2E descriptor; session_spec, keys_spec | No editor-session hook added |
| 27 missing descriptor / missing session | E2E missing identity/nil descriptor, zero child spawn; session_spec | Known empty live identities use native session-id; absent persisted identities never fall back to latest |
| 28 unsaved immutable source selection | E2E ranged unsaved submission + queued snapshot survives later mutation and reaches persisted history; context_spec | Range command linewise selection; visual character/block selection remains editor-layer only |
| 29 unsaved reads / fresh ambient state | E2E tools; bridge_spec, context_spec | Real upstream read with injected buffer operations |
| 30 arbitrary Lua / structured operations | E2E tools, findings | Real cross-process companion clients |
| 31 edit / disk coherence / undo / trail | E2E edit; editor/edit_spec | Artificial unsaved setup explicitly closes its undo block before agent edit |
| 32 incomplete args inert ghost | E2E edit observes real ghost deltas + unchanged changedtick; partial_spec | Native faux chunk stream |
| 33 dedicated follow viewport | E2E findings/follow/failure; editor/follow_spec | Missing paths never become empty authoritative buffers |
| 34 qf / loclist / diagnostics / navigation | E2E qf, real companion Lua loclist/diagnostics, foreign namespace retained, native lfirst/cfirst navigation | Structured convenience tools + unrestricted Lua; no LSP semantic tools |
| 35 normal extensions / dialogs / tools | E2E slash, tools, start; Pi contract | TUI-only capabilities intentionally absent; arbitrary extensions not exhaustively tested |
| 36 optional consumer / cached events | E2E ask; drive cached state; editor/publish_spec | Absent-producer degradation editor layer |
| 37 native integration ownership | E2E start preserves source window; keys_spec, editor/publish_spec, transcript_spec | User full Neovim init not loaded by isolated harness |
| 38 no filesystem watchers | Source architecture; edit persistence tests | No runtime watcher instrumentation |

## Verified repairs

Resume option reached command builder only in isolated unit test, never session spawn.
Restart therefore started fresh Pi instead of resuming identity.
Reload lost transcript registry, prompt closures, active-session choice, cursor placement; stale child exit could republish stopped status.
Empty sessions have identity but no persisted file; native `--session-id` restores identity without inventing history.
History adapter missed Pi’s actual `toolCall` discriminator and discarded result details.
Session listing used obsolete XDG location, assumed bucket layout even with flat explicit session directories.
Failed tool output spilled inline despite single-line failure spec.
Follow mode loaded missing paths before reads, making nonexistent files look like authoritative empty buffers.
Reopened prompt ignored `pivi_start_insert=false`; repeated reload could leave isolated editor in insert mode during shutdown.
Model/name/thinking/new commands now refresh cached session metadata.
Companion bridge scratch directories now clean up in `finally`; native subprocess timeout bounds unreachable clients.
Unrestricted `nvim_lua` is excluded from help’s read-only tool allowlist; real malicious faux calls prove editor/file mutations are rejected.
Help composed its context after opening its own window → captured help rather than originating view when window focus changed.
Help now snapshots before presentation; Unicode-safe bounds prevent long lines or whole-buffer selections from defeating small payloads.
Descriptor restoration no longer silently continues latest session when saved identity is absent.
`:Pi prior` lists persisted sessions through existing store + `vim.ui.select`; cancellation starts nothing.
Native `bash_execution_update` deltas correlate by command ID; final truncation/full-output metadata survives live UI and history restoration.
Concurrent model/shell submissions are rejected explicitly; `:Pi abort-bash` exposes native shell cancellation.
Known grep output gains file-group headings + matched-line highlighting as decoration, preserving authored text; findings reach quickfix.
History decoration now resolves one extmark by ID rather than listing every entry.
History listing now uses one ordered native extmark query instead of per-entry queries plus sorting; focused-entry lookup seeks one native extmark instead of enumerating history.
Restoration renders 32 operations per event-loop turn, folds once, cancels deferred work after stop/replacement.
Runner tracks every RPC child across module reloads, including stopped/replaced sessions, not just active/help children.
Descriptors preserve authoritative session file; header identity validation precedes store ID fallback.
`:Pi new` rejects restoration in progress, preventing queued backfill from contaminating fresh conversation.
Runner verifies failures for every owned child after shutdown; injected real handler failure proves nonzero exit.
Editor shutdown uses synchronous RPC request before closing channel, preventing quit notification loss on error path.

## Branch restoration proof

Installed Pi 1.1.0 `dist/modes/rpc/rpc-mode.js` implements `get_entries` with `sessionManager.getEntries()`, returning full entry tree plus `leafId`.
Installed `dist/core/session-manager.js` implements `getBranch(fromId?)` by walking parent IDs from active leaf, reversing resulting path; null leaf yields empty history.
Adapter selects same ancestor chain before tool-result indexing, includes metadata ancestors, preserves complete result content/details.
Missing leaf/parent target, invalid ID, duplicate ID, cyclic active ancestry → empty restoration, never full-tree fallback.
RPC decoder maps JSON null to Lua nil; nil root parent therefore terminates ancestry, indistinguishable from omitted parent field.
Legacy ID-less fixtures retain linear rendering; graph entries without authoritative leaf fail closed.
E2E builds branched JSONL from actual persisted header/entries, reassigning native parent links around shared root, resumes through real Pi.
Discarded prompt/tool/diff sentinels never render; selected `edit-live` call retains reported diff; restoration makes zero model calls.
Fixture construction tests persisted branch ancestry, not interactive Pi tree navigation or in-memory null-leaf persistence.
Large linear fixture remains native-parent compatible; restoration/restart still retain 2000 addressable entries with event-loop yields.
No custom RPC or extension capability added.

## Verification

Latest full suite: 815 passed, 0 failed, 0 errors across 63 suites; non-opt-in contract skip included.
Drive: 7 scenarios passed.
Opt-in Pi contract: 8 passed, 0 failed, 0 errors.
Latest three uninstrumented E2E runs: 29 scenarios, 28 passed, 1 failed each; global settings byte guard passed.
Large restoration exceeded unchanged 10s total budget: 16366.233ms, 12897.6071ms, 14270.949ms.
New/export and stop passed in all three runs after unconditional large-scenario timer/session/active-source cleanup.
Earlier all-green E2E result is historical, not current proof.
Earlier concurrent verification run passed all scenario assertions but failed global-settings byte guard; subsequent isolated rerun exited 0 with unchanged settings.
Initial adapter run exposed RPC decoder’s null-to-nil root-parent conversion; fixed before successful rerun.
Prior injected handler failure proof: exit 1, owned RPC child diagnostic; all owned children shut down.
Latest injected-failure rerun hit outer 240s tool timeout without captured result; process inspection afterward found no Neovim/test children, so this rerun is not claimed as passing.

## Restore-budget investigation

In-memory counters/timers ran inside isolated real-Pi E2E children; instrumentation persisted across pivi reloads.
Baseline profiled large session: create-to-history-response 19733.5407ms, first-to-last entry opening 796.1205ms, create-to-restored 20533.1933ms.
Native buffer writes: 3001 calls / 91.1114ms; extmark-by-ID: 70496 calls / 202.7643ms; extmark writes: 12000 calls / 76.1890ms.
Large transcript was hidden during initial restore, so final fold application cost 0.0055ms; this is not a visible-fold performance claim.
Optimized profiled run: create-to-history-response 16453.1942ms, first-to-last entry opening 656.5959ms, create-to-restored 17115.4452ms.
Extmark-by-ID calls fell to 8000 / 19.8051ms; ordered history queries used 1119 native range calls / 185.6017ms, including timer polling during startup.
Later first-response profile: get_state arrived at 8091.5413ms, get_session_stats at 8091.7119ms, get_entries at 8108.3877ms, restoration completed at 8403.9267ms.
That profiled E2E passed all 29 actual scenarios, including arbitrary large-file restart; its extra profiling record is not a feature scenario.
Instrumented absolute timings include wrapper overhead; independent uninstrumented runs above still failed total budget.
Most wall time precedes backfill planning: native Pi startup/session loading/user extension initialization remains unresolved.
No startup subtraction, budget relaxation, resource-discovery suppression, or settings change was made.
One earlier profiling run failed the global-settings byte guard; no settings were restored or modified by this investigation, later profiling and sequential validation passed that guard.
Current evidence does not establish robust sub-10s end-to-end restoration margin.