Neuron orchestrator v2 implementation plan

Status: implemented and independently reviewed at 6593414626819cecadb032885031d777f3c3f0b5, 8 October 2026. Focused automated gates, affected-package typechecks, clean macOS arm64 build and archive inspection passed. The candidate is on feat/orchestrator-v2; it has not been installed or launched. This artifact stays outside the repository. Verification is automated only, as requested. No browser, Electron launch, live provider run, or real application test was performed.

The integration results record actual test batches, independent reviews, the final ZIP identity and SHA-256, and the separate installation/data-transition boundary. The specification below remains the reviewed implementation plan.

Outcome and completion boundary

Integrate T3 Code's V2 orchestration into Neuron on an isolated branch, preserve Neuron's product scope and custom features, prove the database cutover on fixtures, and produce a clean committed desktop ZIP suitable for the daily installer. The existing main checkout, its notification-copy WIP, installed app, and live databases stay untouched. Installation, launch, and any transition of a running daily process are separate actions; this task prepares a daily-ready candidate using automated evidence.

Daily-ready means the release gates below pass. A build alone does not satisfy them. No claim of native visual QA or live-provider acceptance will be made.

Pinned starting points and import method

Decisions that govern the port

  1. Keep Neuron identity, MIT notices, macOS/Linux hosts, web/desktop clients, local/direct/SSH environments, explicit update/publishing configuration, blocks, preview, whiteboards, peer settings and native notifications. Mobile, Windows/WSL, cloud accounts, managed relays, analytics, unrelated OAuth/secret/MCP Apps additions and Python-based installation routes remain outside scope.
  2. Preserve deployed migration IDs 1–51. Map upstream 50–56 to Neuron 52–58 respectively, in dependency order, with tests for the fork manifest. Upstream 57–60 are later-main changes excluded from this baseline. Never replace Neuron's 50/51 records with upstream names. Validate exact names and every required predecessor ID before migration: a hole below the maximum is a failure, not a recognized source. Reject unknown or upstream-preview ledgers with a typed recovery message unless a separate exact conversion is deliberately implemented.
  3. V2 uses statev2.sqlite, seeded once through read-only SQLite backup from state.sqlite. Never overwrite an existing V2 target or write to the V1 source. A failed migration keeps the original and target for recovery; no automatic deletion/reset. Copied legacy tables remain intact.
  4. Migrated native sessions are not resurrected. First continuation starts a fresh provider session with bounded context. Preserve conversation text, supported attachments, thread/project metadata and inert historical plans, system notices and tool/activity history. Unknown history payloads remain retrievable; import cannot silently drop them or activate old approvals. Historical checkpoints remain stored and accessible as read-only history/diffs; restoration must stay disabled unless a faithful compatibility path is proven by automated tests. New V2 checkpoints retain normal restore guarantees.
  5. Owned-child delegation within the invoking project is distinct from unrelated peer access. Sender and target projectPeerTools opt-in remains mandatory for unrelated discovery/read/send/interrupt/update and cross-project launch/schedule. An owned child may be coordinated with peers disabled. Existing peer tool names, read bounds, delivery-key deduplication and receiving permission mode survive. Live handler checks enforce settings revocation immediately.
  6. Optional preview and whiteboard tools remain independently scoped. Credential reuse compares every optional capability. Instructions describe only the tools actually granted and retain Neuron blocks and collaborative-browser guidance across resume, handoff and provider changes.
  7. Automated evidence is the sole acceptance method for this task. All provider execution tests use fixture transports/synthetic adapters. No *.live.test.ts, real provider CLI, app/browser launch, or repo-wide check is permitted.

Work ownership and order

The primary agent owns the import, shared integration boundaries, dependency installation, conflicts, combined verification, commits, publication and build. Subagents own explicitly assigned files after the shared baseline lands. Writes to server.ts, ws.ts, contract indexes, package manifests and runtime composition are coordinated centrally. Parallel test jobs are bounded to avoid overloading the workstation. A reviewer reads the completed plan before implementation; final review covers the complete diff against the Neuron fixed point.

Phase 1. Review the plan and materialize the baseline

Review scope, history policy, migration ordering, provider coverage, test isolation and packaging deliverables. Repair findings before import. Copy the normalized V2 path set and merge Neuron's overlay. Keep a conflict manifest outside the worktree. Align Effect packages to rc.115 and Vite+ to 1.0 only where required, retain Neuron build patches and allowed native dependencies, regenerate the lockfile, and sync the Effect reference through the repository sync workflow. Never manually edit vendored references.

Primary files: root manifests/config; apps/server, apps/web, apps/desktop; packages/contracts, shared, client-runtime, effect-acp, effect-codex-app-server, ssh, tailscale; Neuron-only packages/whiteboard; targeted scripts and patches. Preserve brand assets, marketing identity, and all fork-only launchers.

Gate: dependency installation succeeds; workspace imports/exports resolve; an exact file/conflict inventory exists; no forbidden product paths or Python installer runtime returns. Conditional returns in introduced code have braces and multiline blocks.

Phase 2. Prove persistence and historical cutover

Migration owner adapts persistence/Migrations.ts, V2 schema migrations, snapshot initialization, importer and projection recovery. Map upstream changes starting at Neuron 52. Test through-50/through-51 fixtures, fresh V2, existing V2 with new work, unsupported ledgers, committed WAL, failed snapshot, interrupted import and second boot. Import all supported Neuron metadata and keep legacy history inert and ordered. Add a history-version/progress mechanism so already-imported transcripts can receive newly supported historical items idempotently.

The migration owner also owns the historical compatibility seam. Represent inert historical records through existing V2 system_notice/proposed_plan/faithful tool items where appropriate, with an optional typed legacy-origin record carrying original identity, kind, payload and checkpoint reference. Full opaque payload remains preserved in storage and is retrieved through the existing bounded turn-item detail reader. Extend the typed contract once, rather than running the V1 engine or inventing live provider nodes. The client owner renders this history as archived and does not offer response or plan-execution controls. For legacy checkpoint diffs, add a dedicated bounded, read-only request authorized like checkpoint reads, resolved from copied legacy turns and checkpoint diff storage. Do not map these into V2 restore commands. Test authentication, deleted-thread access, paging/size bounds, order, restart repair and absence of live effects. If exact historical display cannot be represented faithfully, the compatibility reader must expose the original record with an explicit archived label rather than silently omit it.

Preserve project default model, scripts, environment mode, auto-pull, favicon/icon, deletion identity and timestamps in application baseline events; rebuild must reproduce them. Preserve whiteboard tables and pending activity. Imported thread.created changes creation-incarnation sequence, so adapt pending activity only for an exact validated pre-cutover identity. Keep durable deletion triggers on new application event appends, never projection-row deletion.

Gate: original fixture bytes/logical WAL contents remain unchanged; exact prior migration records survive; required upstream schema exists; history completeness/progress and metadata compare correctly; migration emits no provider effects or stale native approvals; second boot introduces no duplicates; projection rebuild leaves boards/settings intact.

Phase 3. Reconnect whiteboards and desktop notification streams

Server preservation owner ports whiteboard reads to V2 projections, durable activity to a V2 command/receipt, lifecycle invalidation and settlement races. Preserve revision conflicts, change history, idempotency, reference creation identity, deletion/recreation and undrained activity preventing auto-settle. A later explicit settle wins over an older board activity, including equal timestamp races; a rename does not.

Notification owner retains notifications.ts wire/desktop contracts and replaces V1 event/snapshot reads with V2 run/runtime-request projection reads. Choose a consistent app-run identity for the existing notification turn field. Preserve subscribe-before-snapshot ordering, bounded replay, completion-only success, no imported-history popups, request resolution, deduplication, foreground suppression, actionable request retention and thread-title copy. Upstream delegation mailbox is not a replacement for this stream.

Primary files: apps/server/src/whiteboard/*; V2 orchestrator/settlement commit seam; mcp/toolkits/whiteboard; notification signal/snapshot modules; centrally coordinated server.ts/ws.ts; contracts and shared notification client.

Gate: board lifecycle/activity suites and V2-backed notification stream tests pass; fake-provider completion and approval round trips produce the established desktop signal without gaps or duplicates; no production V1 thread/projection query survives outside explicitly bounded legacy history.

Phase 4. Preserve MCP permissions and provider instructions

MCP/provider owner adapts session registry, invocation scope, V2 ProviderSessionManager, existing peer handlers and new orchestrator services. Define owned-child checks centrally and enforce project opt-in on every unrelated-thread operation, including list filtering and older credential use after revocation. Bound reads and keep deterministic delivery IDs. Direct provider calls remain behind adapters; MCP dispatches commands.

Keep Neuron's runtime, block, preview and whiteboard instruction builders alongside new V2 orchestration context. Verify new/resumed/forked/switched provider sessions do not lose them. Keep preview tool names, current-tab ownership, background-open semantics and automation broker. Generic ACP installation permits approved Node/binary routes only.

Provider coverage: Codex and Claude exercise full synthetic lifecycle; Cursor exercises SDK lifecycle plus declared unsupported native rollback/fork and restart steering; Grok and OpenCode exercise V2 stream, queue, interrupt, permissions and recovery; Antigravity has an explicit compatible ACP mapping or dedicated V2 adaptation preserving existing instance configuration. Pi/other new providers are optional and may remain disabled until their focused automated cases pass. Unsupported capabilities fail before filesystem/provider mutation.

Gate: owned-child delegation succeeds with peer tools off; unrelated access fails without both opt-ins; setting revocation acts immediately; capability changes refresh credentials; preview-only/whiteboard-only sessions cannot gain peer authority; supported providers preserve permission ceilings and product context.

Phase 5. Cut over client state and every entry point

Client owner merges V2 shared models, reducers, queue state, history, lineage, approvals and Settings. Preserve environment+thread composite identity for drafts, forms, boards, previews, queues and notifications. Restore the registered fence dispatcher in ChatMarkdown.tsx and whiteboard/header/panel/keybinding paths in ChatView.tsx. Keep Neovim/editor custom integration and LAN phone-pairing behavior.

Carry protocol-v2 advertisement and mismatch gates through shared RPC, web, desktop local environment, direct network and SSH. Test stale server/client failure messages and same-thread-ID isolation across environments. Fix the queued/waiting detail-stream keep-alive predicate using the shared active-run semantics. Audit palette, Settings and keybindings as well as chat. Include unsnooze, resume queue, cancel scheduled work, close/reopen and relevant stop paths.

Gate: meaningful DOM/component interaction tests prove forms append to the correct draft without sending; shared-state tests prove queue/reconnect/history correctness; contracts and transports agree; both client builds compile; Neuron panels and notifications remain wired to the shared V2 state.

Phase 6. Automated regression, independent review and daily artifact

Run focused non-live suites grouped by behavior. Exercise concurrency/restart through typed receipts and worker drains, with deterministic fixture transports, never sleep/poll-based success. Use temporary Git repos for checkpoint cases. Include interrupted preparation, accepted-interrupt/normal-completion race, delayed ignored interrupt, successful queued-to-steer, handoff budget/failure, rollback without provider session, fork from subagent, background work and child completion ownership. Add bounded high-volume streaming tests for coalescing, retention and responsiveness without timing thresholds that depend on machine speed.

Run affected-package typechecks separately and targeted lint/format against introduced or changed files. Do not call root recursive checks. Build web, server (including Claude-history worker, Neuron service launcher and whiteboard renderer) and desktop packaging. Validate exported worker/asset paths from the bundle. Run daily-script tests covering both DB open-file guards, backups and retained prior bundle.

After fixes stabilize, request independent correctness/spec review of the full commit range against 82af82df. Repair substantive findings and rereview the full range. Commit only task-owned work. Build a desktop ZIP from the clean integration commit using pnpm daily build; inspect its Neuron identity, embedded commit, server/workers, renderer/font assets, updater-feed absence and archive integrity. Do not install or launch it.

Gate: all applicable automated checks pass; review has no unresolved release-blocking findings; clean source commit and reproducible ZIP exist; original main WIP is unchanged; a verification report records actual commands/results and untested live/visual areas. Only then label the candidate daily-ready.

Verification matrix

Area Required automated evidence
Schema/snapshot/import initializeV2Database, fork migration mapping, importer/cutover fixtures, complete project rebuild, inert legacy history, original immutability, V2 no-overwrite/retry
Execution Non-live V2 orchestrator/worker/replay suites; queue order/holds, interrupts, approvals/questions, handoffs, fork/merge, checkpoint restore ownership, restart recovery
Whiteboards Service/lifecycle/activity/presence/render/MCP suites, revision and incarnation races, imported/new V2 thread references, client scene sync and drafts
Notifications V2 signals/snapshot/stream race tests; shared coordinator, desktop controller, web history/settings tests; fake-provider RPC signal
Peer/MCP policy Both-project opt-in, owned-child exception, revocation, filtered discovery, read bounds, send dedup, receiving mode, optional capability isolation
Providers/context Synthetic adapter/replay tests per existing provider; native capability rejection; new/resumed/handoff instruction parity; ACP non-Python route
Client/transports V2 reducers/queue/history; queued/waiting keep-alive; form interactions and environment isolation; endpoint/RPC/protocol/direct/SSH tests
Packaging Affected package typechecks, targeted lint, web/server bundle, worker and whiteboard assets, daily script tests, clean-commit desktop ZIP inspection

Review and progress record

Independent migration reviewer approved the revised plan with no remaining blockers. The review required an explicit historical representation/API, exact baseline migration mapping, and predecessor/hole validation; all three are now specified above. Implementation adds malformed-schema-signature rejection and historical repair after new V2 continuation regression cases. Plan review findings and resolutions, phase status, command evidence and implementation review will be recorded in this external working artifact and its published HTML counterpart. They will not be committed to Neuron or copied into internal docs as implementation narration. Product docs change only where the cutover changes how users accomplish a task or exposes a necessary history/recovery limitation.

Sources