Keep editing.
Let the agent catch up safely.

1. Decisions at a glance

The first private daily-use release targets local Codex on macOS with Neovim 0.11.5. It must include protection and conflict recovery. Messaging alone is an earlier usable slice. The remaining supported providers, Linux, web/desktop and remote modes have explicit gates; the panel need not wait for all of them.

2. User experience

A user enables Neovim integration for a project, binds an editor session and chooses a Neuron thread. The existing Open in Neovim workflow remains available. A statusline component identifies the bound thread and shows whether the connection is healthy, the agent is working, or changes are waiting.

The user can send a short message, compose a multiline prompt, or send a captured selection. Neuron shows the same durable message and response in its chat. Sending from Neovim does not create a separate conversation history.

When a protected turn starts, the agent receives a workspace containing current saved project files. The agent can discover which buffer the user is in, its file name and whether it has unsaved changes. Ordinary reads return saved text; they do not return the unsaved buffer. The user keeps editing normally. Agent changes appear as a candidate diff in Neuron while the agent works. They do not alter the human workspace yet.

At the end of the provider turn, Neuron reconciles the candidate with the latest human text. Compatible changes appear in buffers as a separate undoable action. Buffers that still contain human unsaved changes stay unsaved. If a conflict exists, the whole batch waits and a single notification names the affected files. Neuron does not insert conflict markers into the user's working buffer.

Saving a conflicted file wakes reconciliation. If a mechanical merge still fails after that save, the agent gets a fresh saved-file snapshot and repairs its proposal. Alternatively, the user can approve an exact resolution in Neovim or Neuron without first saving. Either client resolves the same pending batch; approval in both is not required. The user can also review, reject, cancel, or explicitly retry. The UI distinguishes provider completion from publication completion.

3. Ownership and protected execution

P-01. The human workspace is the original project directory, its registered Neovim buffers and its Git working state. The execution workspace is a separate writable tree for one protected turn. They have distinct identities even when they represent the same project.

P-02. The execution boundary must deny direct mutation of the human workspace by the provider, shells, descendants, subagents and enabled mutation tools. Coverage includes file contents, directory replacement, links and shared Git metadata. Merely changing the process working directory is insufficient. The coordinator's credentials and unrestricted editor RPC must not be exposed to the provider.

P-03. Local MCP processes and persistent command sessions must run inside the boundary or use a verified mediator. An external service that can mutate the human workspace is unavailable in protected mode until it has an enforceable route. Provider tools, credentials and network access must not supply a host-side write bypass through an unsandboxed service. The proof suite determines supported configurations.

P-04. Neuron-originated mutations, including file-editor saves, checkpoint restore and another thread's publication, must use the same coordinator. A human save through the registered editor remains available. Human editing is not subject to agent approval.

P-05. A failed or unavailable boundary prevents a protected turn from starting. Losing the editor connection prevents publication, but an already isolated turn may finish producing its candidate. There is no automatic fallback to unprotected execution. Enabling or disabling protection applies to new turns; existing pending proposals retain their protection rules.

P-06. The guarantee covers Neuron-managed protected execution and coordinated publication into registered editor state. It does not stop root, unrelated applications or unregistered editors from writing. Observed external disk changes invalidate publication assumptions. A final hash check is not an operating-system compare-and-swap; the implementation must prove serialization against participating editor/Neuron writers and must not claim exclusion of unrelated writers.

P-07. The first version allows one authoritative Neovim session per human workspace. Multiple windows or tabs in that session are supported. A second registered session with a loaded copy of an affected file blocks publication until ownership is resolved, even if the second copy is clean. Unpairing an editor never saves or discards its buffers. Authority cannot transfer silently on reconnect.

4. Snapshot and concurrency contract

S-01. Each turn starts from an immutable saved-file base manifest and a writable execution tree. The manifest records actual disk content, saved-but-uncommitted changes, eligible saved untracked files, path identity and file metadata. Starting from Git HEAD alone is incorrect. Unsaved Neovim text is never overlaid into an execution snapshot, including normal follow-ups and automatic repair continuations.

S-02. Snapshot membership follows the project's file-access policy. Tracked files and eligible non-ignored saved untracked files are included. A dirty buffer with an existing disk file contributes only its disk version. A never-saved buffer contributes metadata such as path and unsaved/new state, not file contents or an invented empty file. Ignored and out-of-project files retain normal access rules. Explicitly sending a selection or buffer as a user attachment shares that chosen text as message context; it does not silently overlay the execution tree.

S-03. Repository metadata must be isolated. Human index, branch, refs and configuration are not changed by provider Git commands. Dependencies and caches may be reused only through a policy that cannot mutate the human tree. Existing runtime configuration needed to run the project follows the same file-access policy. Automatic publication excludes execution-only caches, dependencies and runtime state; it never drops a tracked source change solely because it resembles a generated file.

S-04. A start snapshot must be a verified disk generation, not an unchecked recursive copy while files are changing. Validate disk identities and content for the manifest. Capture editor metadata separately; private buffer snapshots belong to the coordinator, not the execution manifest. Retry invalidated disk capture. If a stable snapshot cannot be established, show Waiting for workspace instead of starting against a mixed tree. Unsaved typing alone does not invalidate a saved-file snapshot.

S-05. Human keystrokes do not modify the execution tree or enter agent context automatically. On-demand editor tools return current metadata, including active buffer identity and write state. The agent knows the file may differ from disk without seeing the difference. Only an explicit user send/attachment shares chosen unsaved text. The next normal turn and any automatic repair start from a fresh saved-file snapshot.

S-06. Different threads may execute concurrently in separate trees. Publication is serialized per human workspace. Every batch revalidates after earlier batches publish. A batch waiting for save does not hold the publication lock, so unrelated threads remain usable.

S-07. One thread has at most one unresolved publication batch. New user messages are durably queued while it waits. The user can cancel that batch and continue, or resolve it first. Resolve with instruction submits a user-authored instruction to the pending batch and schedules its repair; it does not get trapped behind the normal message queue. Automatic repair is not allowed to run concurrently with a new user turn or bypass an outstanding provider approval.

S-08. Candidate capture occurs after a successful provider completion and a verified write barrier. All execution-tree writers must stop/drain, or a proven immutable snapshot mechanism must isolate the captured generation. The first version does not promise that agent-created background servers survive this boundary. A provider that cannot establish the barrier is not yet supported for protected publication. Existing user-owned processes are never stopped.

S-09. Cancellation, provider failure or an unstable candidate produces a retained draft, never automatic publication. The user may inspect the draft and request a new proposal. A text-only successful turn with no execution delta needs no publication batch.

S-10. Provider working directories and ordinary file tools resolve to saved content in the execution tree. Citations use environment/project-relative identity so opening them reaches the human editor. The editor-context route supplies metadata only. An absolute-path write to the original is denied, not silently redirected. Adapters must make execution versus human paths explicit in tool results. Private coordinator snapshots, editor recovery files and user-facing resolution previews must not become an alternate automatic source of unsaved text for the provider.

5. Publication and merge rules

M-01. Compute the agent delta from execution base B to completed candidate A. For each changed file, compare B, A and latest human content H using a deterministic three-way text merge. H is coordinator-private text from the authoritative loaded buffer when present; otherwise it is verified disk content, subject to the known buffer registry. Disk changes that disagree with a loaded buffer require reconciliation before publication.

M-02. Merge preserves identical edits and combines non-overlapping edits. Conflicting replacements, deletion-versus-modification, incompatible metadata changes and ambiguous structural operations are held. The first version uses line-oriented text merging. Different edits on the same line may conservatively conflict. No LLM decides silently that one side should win.

M-03. Default publication unit is all publishable changes from one provider turn. Preflight every changed path. If any path conflicts, is unsupported, needs review or has uncertain ownership, apply none. The first version does not infer independent file groups or publish selected hunks from an unresolved refactor automatically.

M-04. Application must use exact expected editor generation, buffer revision, path identity and content hash. Compute merges outside Neovim, then perform a short conditional application. A moved extmark alone does not validate content. Do not mutate from a buffer notification callback or force the editor out of a modal operation.

M-05. If an affected buffer is active in Insert, Replace, Visual, operator-pending or command-line interaction, application waits for a safe normal editing state. The integration never sends Escape to interrupt typing for background publication. Show Ready, waiting for editor. Explicit Apply requests also wait for a safe editor operation. This is distinct from a merge conflict.

M-06. Once application is safe, each affected buffer receives one separate agent undo block. Preserve cursor/view where meaningful and do not jump to another file. No combined undo block may absorb preceding human typing. Multi-file publication is not advertised as one native Neovim undo action.

M-07. A file with human unsaved changes at final preflight is updated only in its buffer and remains unsaved. This includes buffers dirty at turn start unless their human changes have since actually been saved or discarded. An inherited dirty flag is not enough to determine content equality; verify buffer and disk representation.

M-08. An ordinary clean text file may be saved automatically through the coordinator only if its current human content matches its expected disk/buffer state and no participating human edit intervenes. Registered buffer writes must use a tested editor write path that respects relevant hooks and rechecks the result. Neuron must not alternate an RPC check and an uncoordinated disk write. Unsupported custom writers, newly dirty state or failed writes leave the file unsaved and produce an explicit receipt.

M-09. Automatic save never includes a file whose human unsaved changes were merged. New text files with no human counterpart can be created on disk after path-absence and alias checks. An existing unsaved new-file buffer counts as a human counterpart. A parent directory must not be replaced to create a file.

M-10. Renames, deletions, mode changes, binary changes, symlink changes and submodule operations require explicit review in the first version. A reviewed operation still must pass current-state checks. A dirty file is never deleted or renamed out from under its buffer. Choosing review does not grant permission to discard human content. Save or an explicit human discard/rename must resolve that condition first.

M-11. Initial automatic text merging supports ordinary UTF-8 files, including BOM, LF/CRLF and missing final newline, with exact representation retained. Mixed endings, unsupported encodings, alias ambiguity and text files above the initial 2 MiB merge limit wait for review. They are not truncated or force-converted. The threshold is a performance default to validate, not a limitation of Neovim itself.

M-12. A batch is logically all-or-held at preflight, but editor/filesystem operations are not a cross-file transaction. Journal intent and per-file pre/post revisions before acknowledging success. If a later operation fails, stop and mark Partial. Keep already applied human-visible changes; do not roll them back over subsequent typing. Recovery follows section 8.

M-13. User-visible publication outcomes distinguish Applied to buffers, Saved to disk, Waiting, Partial, Rejected and Cancelled. Mixed buffer/disk results are shown per file. A completed provider response must not label an unpublished batch as applied.

6. Waiting, save and regeneration

W-01. A conflict holds the whole publication batch and the next user turn in that thread. It does not suspend the human editor or other threads. The provider has completed its execution; Neuron waits without keeping an agent request open just to poll for a save.

W-02. Persist the original user request, candidate, saved base versions, private conflict state and all accepted/rejected review choices. Show one current notification in Neovim and Neuron with file navigation and actions for Approve resolution, Retry, Resolve with instruction, Review, Reject and Cancel. Subsequent typing updates private state without repeated notifications or automatic repair calls on every keystroke. Agent-facing receipts contain file identity, write state and outcome, not private unsaved lines or derived snippets.

W-03. Saving an affected conflict file, an explicit Retry, or completing a review resolution requests one reconciliation attempt. Save notifications are wake-ups. Reread final buffer and disk state after write hooks/formatting. Custom writes with missing notifications have the same explicit Retry path. A save that does not change the content does not trigger duplicate repair for an already attempted generation.

W-04. First rerun the deterministic merge against current H. If compatible, proceed through all publication checks. Saving does not grant permission to replay the old patch or choose the agent's side of a conflict.

W-05. If a conflict remains after a verified save, schedule one agent repair continuation for that newly saved generation, using a fresh protected saved-file base. Supply original task, retained agent proposal, saved file changes, non-text conflict metadata, explicit user resolution instructions and review decisions that do not disclose private text. Other files' unsaved contents stay private. An explicit Retry before save may rerun the private merge or authorize a repair from saved files, but never exposes unsaved text automatically. A newly dirty buffer is still checked privately when the revised proposal returns.

W-06. A repair continuation replaces the entire pending batch with a new revision. Previously compatible parts remain part of the requested intent. New changes are visible in the candidate diff. Any new conflict, file operation or review requirement is evaluated again. The original retained proposal is not modified in place.

W-07. Allow at most one automatic repair per newly saved generation and three automatic repairs per original turn. Coalesce saves while repair is active. After the cap or a repeated unresolved conflict on unchanged content, remain Waiting for review. Explicit Retry authorizes one more repair attempt; it does not reset an endless loop. Repair uses the provider/model and approval policy already selected for that thread, consumes normal usage, obeys existing usage limits, and appears in turn history. Reaching an approval or usage limit holds repair; the integration does not increase limits automatically.

W-08. Reject cancels the whole pending batch by default. Review may exclude individual hunks, but that creates a revised proposal requiring validation; it is not partial publication of the old batch. Cancel stops waiting/repair and retains a recoverable draft. Neither action undoes changes already applied in a Partial batch.

W-09. Neovim and Neuron display the same pending resolution, including the human's current unsaved side and the agent proposal. This preview is user-facing; it is not sent to the agent. Approval targets an exact batch revision, buffer generation/revision and resolved text. The user may choose or edit conflict resolutions while retaining unrelated human changes. A bare approval with unresolved conflicts cannot authorize a blind overwrite. The first accepted approval is durable and updates both clients; duplicate approval is harmless. Later typing or a replacement proposal invalidates stale approval and refreshes the preview.

W-10. Approving a resolution authorizes that reviewed buffer change, not a save of the entire dirty file and not sharing its unsaved contents with the agent. The coordinator rechecks every file in the batch and applies only when the batch is fully resolved. Dirty results remain unsaved. A separate explicit user save writes them to disk. Conflict-marker scratch/review buffers never replace the live file unless the user approves a completed resolution.

7. Messaging and live context

C-01. Provide configurable Plug mappings without taking existing keys by default. Neuron chat, Settings and command-palette actions share the same contracts; keybindings call those actions. Proposed commands are:

• Bind an editor with :NeuronBind and unbind with :NeuronUnbind.
• Send with :NeuronSend or open a draft with :NeuronCompose.
• Inspect state with :NeuronStatus and review with :NeuronReview.
• Retry with :NeuronRetry and cancel with :NeuronCancel.

C-02. A binding includes environment, project, editor instance and thread. Capture visual text, range and source revision before opening an asynchronous picker. Blockwise, reversed and Unicode selections retain their meaning without changing registers. Sending acknowledges once the user message is persisted. Retry with the same delivery ID cannot create another message or turn.

C-03. A busy thread receives a queued follow-up by default. Steering and interrupting are separate explicit actions and appear only when the provider supports them. A message queued earlier preserves its submitted selection snapshot; its eventual execution base is freshly captured when it starts. Both timestamps are available.

C-04. A multiline composer persists an unsent draft independently of Neovim's modified flag. Sending clears the draft only after persistence acknowledgement. Disconnects and closing the composer do not erase unsent text. Abandoning a draft is an explicit user action.

C-05. Active-buffer metadata is available through a scoped backing tool and a shipped skill whenever a bound editor is healthy. The skill explains how to discover the current buffer, file name and saved/unsaved/unknown state, and tells the agent to read file contents through ordinary saved-file tools. A compact editor-presence reference accompanies the turn. Neither the skill nor the reference grants access to unsaved buffer contents.

C-06. The tool returns editor/buffer identity, file name or unnamed state, opaque revision, filetype, cursor/range coordinates and write state, but no buffer text, selected text, text hashes or snippets derived from unsaved content. Resolve the active buffer at invocation time within the bound project. If focus moved to another project, return Outside bound project. Hidden project buffers are discoverable by metadata so their write state remains visible. Unknown or disconnected is never reported as saved.

C-07. Ordinary range reads return saved execution-file text. User-triggered Send selection/Send buffer actions are the explicit exception: they capture and attach the chosen unsaved text with its revision and declared omissions. Large attachments follow existing attachment limits; no silent truncation. Diagnostics, semantic extracts, tool errors and screenshots of private resolution previews must not automatically expose unsaved contents to the agent. The coordinator may use full private text for merging and user-facing review without including it in provider payloads.

C-08. Buffer notifications drive the coordinator's private cache and the agent-visible metadata cache separately. Do not scan all buffers or resend full files on every keystroke. Bound transport queues; on overflow or a detected event gap, mark state stale and resnapshot before returning authoritative metadata or applying edits. Large editor events must not block input while merging. Private cache data is not readable through provider-accessible tools or filesystem paths.

C-09. Agent tools expose bounded saved-file reads, editor metadata and proposal operations, not arbitrary editor Lua, shell commands or raw RPC. Access remains scoped to the thread/environment and the existing project file-access policy. Unbinding revokes context access, prevents new protected turns through that binding and holds existing publication until ownership is restored or the batch is cancelled.

8. Validation, undo and recovery

R-01. Every validation record names the command, result, execution generation and exact tested content manifest. Only instrumented executions with a verified stable input may receive a revision-specific Tested label. Agent prose reporting a test is retained as a provider report, not silently promoted to that label. A process that modifies its own test inputs prevents an unqualified exact-input claim.

R-02. A test against A remains a test against A. If reconciliation produces different merged content M, the visible merged result is Not tested at this revision. Ordinary clean textual merges may still apply; this is a publication policy, not a green-test guarantee. Default validation uses saved execution files. Testing unsaved editor contents requires a separate explicit user action that states which text is shared for validation; it is never an automatic repair or default context read. Repair continuations run appropriate checks, with the same revision rules.

R-03. Checkpoints retain the execution base/candidate and per-file publication receipts. The UI distinguishes proposed changes from actual buffer/disk changes. Human unsaved contents exist only in private coordinator recovery records and user-facing diffs; agent-facing checkpoint data does not expose them or attribute them to the agent. Pending batches do not create a falsely completed human-workspace checkpoint.

R-04. Restore and Undo agent changes create an inverse proposal against the recorded published version and reconcile with current human text. If the user edited the same content afterward, hold a conflict rather than restore the old file wholesale. Native u remains usable per buffer; a detected undo does not cause automatic reapplication of the old batch.

R-05. Persist pending proposals, repair counters, user review choices, publication intents and receipts before acknowledging their durable state. Editor presence/cursor updates are transient. On reconnect, assign a new connection generation and resnapshot. Never reuse cached buffer handles as evidence of current ownership.

R-06. After a lost apply acknowledgement, compare the recorded before/after state with the actual buffer/disk result. If the exact applied outcome is established, record it once without reapplying. If later human edits make the outcome ambiguous, hold for recovery review. Never guess from a matching filename or retry a mutation because the receipt is missing.

R-07. Recover a Partial batch by showing applied, unsaved, saved and remaining files. Resume only when already applied files still match their recorded outcome and remaining operations revalidate. Otherwise create a revised recovery proposal. Revert applied changes uses the inverse-proposal rules. There is no blanket rollback over human edits.

R-08. Pending and partial proposals survive restart and are never automatically expired. Completed/rejected proposal snapshots have a 30-day retention period, extendable by pinning. Cleanup must respect existing thread/checkpoint retention and preserve references still needed for recovery. Retained buffer snapshots are not a replacement for Neovim's own recovery files and are never restored into the editor without a user recovery action.

9. State and module contracts

The following names define behavior. Exact schema spelling is an implementation choice; state distinctions and preconditions are mandatory.

Approved lifecycle:

capturing → executing → capturing candidate → reconciling → ready → applying → applied

From reconciliation, a batch can enter waiting for save, waiting for editor, waiting for connection, waiting for workspace or waiting for review. A save/retry returns it to reconciliation or starts repairing → capturing candidate. Failed application becomes partial; interrupted execution becomes draft; explicit terminal decisions become rejected or cancelled. An applied batch records save state per file rather than using a single misleading Saved flag. Waiting states retain a reason and a concrete next action. No provider polling loop represents a durable wait.

The editor adapter owns RPC, capabilities, snapshots and conditional application. The execution service owns isolation, processes and stable candidate capture. The pure coordinator owns decisions and expected transitions; Effect reactors perform side effects and emit typed receipts. Shared client state renders the same outcomes in desktop/web and Neovim. Provider adapters declare capabilities rather than weakening global semantics.

10. Worked scenarios

11. RPC panel stretch specification

The panel uses real Neovim remote UI attachment and rendering. It shares the editor adapter, context tools and protection coordinator with terminal use. It is not an independent text editor with Vim keybindings.

The first panel has one active input owner. Opening it requests an explicit handoff of the authoritative session from terminal input to panel input. Closing it detaches the view and permits terminal handoff; it does not terminate the server-owned editor or discard dirty buffers. If the existing terminal process cannot support reliable handoff, offer a separate explicitly bound panel session. Never pretend a newly launched instance contains the terminal's unsaved work or let two authorities publish to the same files.

Render the basic linegrid first with Neovim's own menus, command line and messages. Handle partial input acceptance, paste, mouse, focus, cursor modes, resize, redraw flush, clipboard and reconnect. Input composition must work for IME and Unicode. Browser shortcuts must not silently steal documented editor actions. Cursor blinking and redraws must not cause continuous idle repaint.

Unsaved shutdown offers Save, Discard or Cancel, with per-buffer results for partial save failure. Closing the panel alone does not ask to discard a persistent session. Reopening reconnects to the same owned process when available. A crashed process enters recovery; it does not silently create an empty replacement and report success.

Simultaneous independent terminal and panel views are outside the first panel milestone because attached UIs share editor state and sizing constraints. Multigrid, watched-extmark review controls and native completion widgets follow after basic input and lifecycle are reliable. Native diff review, quickfix findings and safe agent undo ship earlier.

12. Build slices and acceptance gates

Use focused tests, disposable Neovim/process fixtures and typed receipts. Test scheduling deterministically; production event coalescing does not justify sleep-based assertions. Static artifact rendering is separate from real client verification. Browser/computer use follows the repository's explicit authorization requirement. Human acceptance is concentrated on actual typing, notification timing, review ergonomics and the panel's feel.

13. Engineering decisions reserved for experiments

The product behavior above is approved with the user's saved-file and metadata-only correction. Four mechanisms still require evidence before implementation commits to them:

1. The containment runtime and exact macOS/Linux/provider policies, including credentials and host-service routes. Sandbox Runtime is a candidate, not an adopted dependency.
2. The snapshot and write-barrier mechanism, especially large workspaces and provider descendants. A content manifest alone does not prove atomic capture.
3. The merge library and coordinated clean-file write mechanism. Fixtures must prove representation, undo, format hooks and races. If clean auto-save cannot meet the contract, stop that slice and bring back evidence; do not quietly relax dirty protection.
4. Reliable terminal/panel handoff with the existing launcher and the user's configuration. The first panel must accurately expose whether it is the existing session or a separate session.

These are bounded experiments with defined outcomes. Changing publication timing, batch scope, automatic repair policy or the promise to preserve unsaved text is a product change requiring an updated spec, not an implementation shortcut.

14. Evidence and scope

The prior audit read 21 complete Neovim API/behavior references and ran disposable Neovim 0.11.5 RPC checks. This specification adds design decisions; it does not add an implementation or claim the acceptance tests have passed.

Neovim supplies buffer subscriptions, revisions and conditional application building blocks. Its native diff is not a complete three-way publication system, and editor notifications do not veto arbitrary external filesystem writes. These limits motivate the proposed coordinator and execution boundary. See the pinned core API, Lua reference for the installed release, autocommand lifecycle and deprecated batching implementation.

The UI protocol supports the proposed rendered panel but does not make multiple views independent editor sessions. Sandbox Runtime provides OS-level restrictions and remains a research-preview candidate requiring Neuron-specific validation.

The earlier build plan remains useful background. Version 0.2 records approval of that behavior with saved-file execution, metadata-only default editor context, private buffer merging and conflict-resolution approval in either client. Earlier unsaved-overlay recommendations are superseded.