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 the current project files and eligible unsaved buffer text. 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, the agent gets a fresh snapshot and repairs its proposal. The user can instead 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 base manifest and a writable execution tree. The manifest records actual saved content, uncommitted changes, eligible untracked files, overlaid unsaved contents, path identity and file metadata. Starting from Git HEAD alone is incorrect. Unchanged unsaved overlay content is never mistaken for an agent edit.

S-02. Snapshot membership follows the project's file-access policy. Tracked files are included; eligible non-ignored untracked files are included. A named, ordinary dirty project buffer is explicitly included even if untracked or ignored, unless access policy excludes it. Excluded dirty files are reported before execution; they are not silently represented by stale disk text. Unnamed buffers and out-of-project buffers remain explicitly attachable context but are not mapped into 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 generation, not an unchecked recursive copy while files are changing. Capture editor state coherently, retain exact content and provenance, and validate disk identities/content for the manifest. Retry invalidated capture. If a stable snapshot cannot be established, show Waiting for workspace instead of starting against a mixed tree. A provider turn consumes the captured generation; later typing does not invalidate that already valid starting point.

S-05. Human keystrokes do not continuously modify the execution tree. On-demand editor tools may return newer live text, clearly labeled as newer than the execution base. The agent may reason about it, but tool reads cannot silently rewrite its files or claim its tests include that text. The next normal turn starts from a fresh human 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 the execution tree. Citations use environment/project-relative identity so opening them reaches the human editor. Reading newer human content requires the explicit editor-context route. An absolute-path write to the original is denied, not silently redirected. Adapters must make execution versus human paths explicit in tool results.

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 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, base versions, conflict reasons and all accepted/rejected review choices. Show one current notification with file navigation and actions for Retry, Resolve with instruction, Review, Reject and Cancel. Subsequent typing updates state without repeated notifications or automatic repair calls on every keystroke.

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 it still conflicts, schedule one agent repair continuation for that new human generation, using a fresh protected execution base. Supply original task, retained proposal, conflicting changes, review choices and any explicit resolution instruction as context. The continuation must preserve current human content, stay within the original task, and rerun appropriate validation. Mechanical rebase and provider regeneration are recorded separately.

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 human 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.

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 context is available through a scoped backing tool and a shipped skill whenever a bound editor is healthy. The skill instructs the agent to read live state before relying on current selection or unsaved text. Availability is not a claim that every provider will always choose to invoke the skill. A turn includes a compact editor-presence reference; it does not continuously inject every keystroke into the prompt.

C-06. The tool returns explicit editor/buffer identity, revision, modified state, filetype, cursor, selection, viewport and content origin. Read the active buffer at invocation time in the bound project. If focus moved to another project, return Outside bound project rather than following it. Hidden project buffers are discoverable and readable by explicit ID.

C-07. Default context reads return the selection or a window around the cursor, up to 400 lines and 64 KiB, with omitted ranges declared. Explicit range reads allow the agent to retrieve the rest. These context limits do not truncate the execution snapshot or merge base. Diagnostics and semantic context are optional, version-tagged enrichments; unavailable LSP/Tree-sitter does not block basic context.

C-08. Buffer notifications drive context-cache updates. Do not scan all buffers or resend full files on every keystroke. Bound transport queues; on overflow or a detected event gap, mark the cache stale and resnapshot before returning authoritative context or applying edits. Large editor events must not block input while merging.

C-09. Agent tools expose bounded read 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. The user can run Validate current editor state in a new isolated snapshot, including unsaved changes. 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 content included in the base is not attributed 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 proposed 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.

Proposed 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 default product behavior above is decided for this proposal. 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. This version resolves its publication timing, conflict scope, concurrency, recovery and automatic repair defaults for review.