T3 Code orchestrator v2: readiness for Neuron
Worth bringing into Neuron, but it needs a coordinated port. The engine has merged upstream and is available in nightlies. A direct pull would leave incompatible schemas, clients, and Neuron-specific behavior.
Recommendation: start an isolated integration branch now. Keep the daily app on its current engine until the migration, provider, and client gates below pass.
Effort: medium to large, across several packages. This is more than a small upstream fix. Confidence is high on the integration boundaries and moderate on runtime readiness; no dry-run port has established an elapsed-time estimate.
Is it ready upstream?
Merged Nightly release Hardening continues
PR #2829, “introduce new orchestrator”, merged on October 2 at 19:22 UTC, as de343914273eceb852a1d1d739cd1d38df7796ee. Its final head passed the core build, lint, typecheck, test, web, server-shard, and release checks inspected through the GitHub API. That demonstrates upstream acceptance, not compatibility with Neuron.
The latest stable release at the time of inspection is v0.0.45, published at 18:17 UTC on October 2, before the merge. The inspected nightly is v0.0.46-nightly.20261008.2833, at a6ec88f7a716fc421bd22c2484881c44110f9375. Stable inclusion has not happened yet.
The merge spans 1,912 files, with 380,729 additions and 203,651 deletions. These are GitHub's aggregate PR figures, including tests, fixtures, docs, and other platform changes. They are not a measure of the Neuron port's required code.
| Open concern | Evidence and implication |
|---|---|
| Interrupts, rollback, and context transfer | Hardening tracker #15013 remains open. It lists interrupt race policies and tests, typed context-transfer failures, capability checks, rollback without an active provider thread, and fork-from-subagent coverage. Treat these as explicit acceptance cases for the port. Individual entries may lag code changes. |
| Queued/waiting subscriptions | #15289 remains open. The inspected web source still considers only preparing, starting, and running states active for thread keep-alive, excluding queued and waiting. The mismatch is source-confirmed; it was not reproduced in a browser. |
| Storage-related disconnects | #15707 reports stalls during concurrent streaming on high-latency storage. Current persistence still uses synchronous Node SQLite. The reported runtime failures were not independently reproduced. Test responsiveness under realistic concurrent load before promotion. |
| Streaming performance fixes still moving | Text-coalescing work in #15767 and buffer work in #16317 are still open. ACP snapshot reduction #16682 merged on October 8. Use a pinned baseline containing relevant post-merge fixes, rather than the original V2 merge alone. |
Judgment: ready to evaluate and port in isolation. Not yet a low-risk replacement for Neuron's daily installation.
What it adds
The useful change is that Neuron can own a thread's work across provider sessions, interruptions, and child agents. Current V2 source separates the user-visible turn from the provider's native turns and execution nodes.
| Capability | Practical gain over Neuron today |
|---|---|
| Durable follow-up queues | Server-owned queued runs survive restart and can be inspected, edited, reordered, cancelled, or promoted to steering. Neuron already has queue and steer controls, but its normal queue lives in the web client's store. V2 adds durable shared queue state and holds queued work after restart. Source |
| Provider handoffs | Switch provider or provider instance within an app thread, carrying a budgeted selection of saved conversation context. This supports continuing work when an account or provider becomes unavailable. It does not preserve hidden reasoning or native tool state, and handoffs can omit history. Source |
| Forks and merge-back | Create a branch conversation at a source point, record lineage, and return its result to another thread. Native provider forks are used when supported; portable context is the fallback. Merge-back concerns conversation/context transfer and should not be advertised as automatic Git conflict resolution. Source |
| Subagents and delegated work | Project child work into visible lineage with status and results. Agents can delegate tasks to another provider/model, read task status, cancel work, and receive completion delivery. A child finishing does not finish the parent's turn. Neuron's existing peer-message tools are a smaller, separate feature. Source |
| Broader thread control through MCP | Launch and configure threads, discover projects, read/search history, send/wait/interrupt, and manage queue items or pending requests. Current source supports explicit cross-project launches. Neuron should retain its existing per-project peer-tool opt-in policy when adapting these capabilities. Source |
| Scheduled work and limit recovery | Schedule durable tasks and manage them through settings or MCP. Limited threads can resume or snooze at a reported provider reset time. These behaviors create real follow-up work and need enable/disable/cancel paths. Source |
| Provider modernization | V2 drivers cover Codex, Claude, Cursor through its SDK, Grok, OpenCode, Pi, and generic ACP Registry agents. OpenCode 2 is supported. Antigravity now uses the generic ACP route rather than a dedicated V2 adapter. Provider capabilities still differ. Source |
| Persisted side-effect execution | The implemented effect outbox records work, claims it through leases, and tracks completion, failure, and cancellation. Recovery can reconcile durable intent after a restart rather than depending solely on a live reactor subscription. Neuron already commits events, projections, and command receipts transactionally; V2 extends that model to explicit side-effect intents. Source |
Scope note: this feature inventory describes inspected V2/main code. The branch accumulated more than the core engine rewrite. The architecture proposal docs still contain future-tense material, so implementation claims above were checked against source.
Useful follow-ups that landed after the V2 merge
Current main also includes native Codex/Claude goal controls and webhook schedules from October 5, outside-agent MCP OAuth access from October 6, inline MCP Apps from October 7, and Muse provider support from October 8. These are optional adjacent work, not requirements for Neuron's first V2 cutover. Projectless threads already existed before V2. Ephemeral side chat remains an open feature request.
Why a direct pull will not work
The underlying approach is compatible with Neuron: Effect services, SQLite, typed RPC, events, projections, and provider adapters are already present. The difficult part is preserving the fork while replacing the orchestration contracts and their consumers.
| Boundary | Finding and required work |
|---|---|
| Migration IDs | Neuron migration 50 is Whiteboards and 51 is WhiteboardDurableDeletion. Upstream 50 is ProjectionThreadPullRequests and 51 is ProjectionThreadMessageContext. The migrator skips IDs at or below the recorded maximum, regardless of name. Copying Neuron's database into upstream V2 would skip these schema changes, while the importer directly queries their table and column. Add a deliberate compatibility bridge on the copied database and preserve the deployed migration history. Use a separate ledger for future fork-owned schema changes. Upstream evidence |
| Effect and dependencies | Neuron uses Effect 4.0.0-rc.112; inspected upstream main uses 4.0.1. SQL imports have moved from effect/unstable/sql to effect/sql. Align dependency/API versions before porting the engine, and include any required provider SDK and SQLite runtime changes. This mismatch is specific to current main, not a claim about every historical V2 commit. Upstream evidence |
| Contracts and shared state | Neuron's orchestration.ts and OrchestrationEngineService are replaced upstream by V2 contracts and services. Thread snapshots, run states, runtime requests, checkpoint references, and reducers change together. Port server, packages/contracts, and packages/client-runtime as one cutover. |
| Web and desktop | Chat, lineage, queue controls, approvals, Settings, palette actions, keybindings, notifications, and history loading all consume the changed model. Preserve Neuron's Mermaid/form block registry and collaborative preview UI. V2 introduces a protocol-version connection gate; old and new clients cannot be assumed compatible. Upstream evidence |
| Whiteboards and peer tools | Neuron's peer handlers call the V1 engine and projection query service. Whiteboard activity and durable deletion are coupled to V1 commands and event storage. Rebind these to V2, testing deletion, recreation, replay, and thread settlement. The initial database snapshot carries custom tables physically, but it does not make their application logic V2-aware. |
| Installer and rollback | Neuron's daily installer checks state.sqlite for open users. V2 uses statev2.sqlite. Extend the installer guard to both, retain data backups, and preserve the Neuron desktop identity while deciding how to isolate the browser profile. Database rollback does not undo workspace changes or shared settings. |
| Product scope | Translate upstream namespaces deliberately. Keep Neuron's macOS/Linux, web/desktop, local/direct/SSH, and explicit publishing/update configuration. Mobile, Windows, cloud accounts, relays, and analytics are outside the port. Exclude Python-backed ACP installation routes to respect Neuron's no-Python rule. |
Provider decisions for the first cut
Keep all six existing provider choices accounted for. Codex and Claude are the first end-to-end validation targets. Cursor needs the SDK transition and explicit limits around native fork, rollback, steering, and approvals. Grok and OpenCode need V2 lifecycle coverage. Antigravity needs a compatible ACP Registry mapping, with provider-instance IDs and configuration preserved. Pi and other registry agents can wait until the existing providers pass. “Present in the registry” does not mean equal capability across providers.
The history tradeoff needs an explicit decision
Upstream's first V2 launch takes a consistent SQLite snapshot of state.sqlite into statev2.sqlite. Later launches reuse that copy. Thread shells import first; user/assistant transcripts import lazily. The original V1 database remains available, and later V1 and V2 conversations do not sync. Settings, attachments, and workspace files remain shared. Sources
| Preserved in the V2 view | Not recreated as V2 history |
|---|---|
| Projects and thread IDs; titles; provider/model choice; permission and interaction modes; branch/worktree; archive, settlement, snooze, pin, ordering, and pull-request metadata; user/assistant text, timestamps, and supported attachments. | Live/native provider session identity; old run records; checkpoints and diffs; tool activity; approvals; proposed plans. The old records remain in the copied legacy tables, but V2 does not translate them into its new timeline model. |
The first continuation starts a fresh provider session with selected historical context. It is not a native resume of the old session. Full imported transcript availability and the smaller handoff selection are different things.
A port sequence with clear release gates
Pin the baseline and freeze the preservation list
The inspected October 8 nightly commit is a candidate baseline: it includes the ACP snapshot reduction fix. Review and pin that commit, rather than chasing main during the port. Its full CI suite was not independently verified here. Inventory Neuron blocks, whiteboards, preview tools, peer-tool permissions, namespace/configuration, and current provider instances. Keep unrelated local work separate.
Exit: every feature to preserve has an owner and an acceptance case; optional upstream additions are excluded explicitly.
Prove the database bridge first
Work on a consistent isolated copy. Resolve migration 50/51 collisions without rewriting deployed history. Test missing legacy schema, transcript import, metadata, custom tables, second launch, interrupted import, and read-only recovery. Keep custom future migrations in their own ledger.
Exit: source database unchanged; repeated launch is idempotent; expected history is accounted for; whiteboards remain usable; history limitations are accepted.
Bring contracts, engine, and adapters across together
Align Effect and runtime dependencies, then integrate V2 contracts, stores, outbox, recovery, and adapters with Neuron namespaces. Add focused behavioral tests for command deduplication, queue order and restart holds, interrupt races, limit resume, handoff failure, and checkpoint safety.
Exit: Codex and Claude work through start, stream, approval/question, steer, queue, stop, resume, fork, and restart. Every other existing provider has an explicit tested support decision.
Cut over clients and reconnect Neuron features
Update shared state and web/desktop rendering. Restore whiteboard lifecycle/activity and peer-tool authorization. Check chat, Settings, palette, and keybindings, including reverse actions. Verify local, direct network, SSH, multiple environments, and the protocol mismatch message.
Exit: focused checks pass; one integrated real-client pass is completed with the owner's browser permission; no Neuron feature disappears during replacement.
Burn in before changing the daily install
Run realistic long histories and concurrent provider work against copied data. Watch event-loop responsiveness, write volume, reconnect behavior, queued/waiting streams, and long-lived background tasks. Update installer database guards and browser-profile migration.
Exit: evidence covers the open upstream regression classes and rollback procedure. Promotion to the daily app is a separate authorized action.
Best next step: authorize the isolated port with the database bridge as its first deliverable. Waiting for a stable upstream release may reduce churn, but it will not resolve Neuron's schema collision or preserve fork-specific behavior automatically.
Evidence and limits
GitHub PR, release, issue, and check state was read live on October 8. Source inspection used upstream main df616cc5491dcc7dd80d3ade8decd88f7a652220 and Neuron 82af82df49dde6be4484851558cd8c7a7473062a. Upstream links below are pinned where possible. Open-issue and release status can change after this report.
No upstream dependency installation, application test suite, migration rehearsal, browser session, or desktop launch was run. Existing upstream tests and CI were inspected, not rerun. This is a source-based feasibility assessment. Runtime compatibility remains a release gate. The HTML received static structural checks; its layout was not browser-verified.
- V2 merge PR #2829; stable v0.0.45; inspected nightly. Merge/release timing and PR scope were verified through first-party APIs.
- User migration guide; migration constraints and ID divergence; migration manifest and warning; actual importer queries; one-time snapshot implementation.
- Queue controls and fork tools; queue UI.
- Portable handoff behavior and limits; handoff implementation.
- Fork service; relationship and lineage control.
- Orchestrator toolkit; Project discovery and launch toolkit; MCP mechanisms.
- Scheduled-task settings; schedule contracts; limited-thread behavior.
- Actual V2 driver registry; Cursor support limits; ACP and Antigravity route; OpenCode support.
- Durable effect outbox; worker, lease, and cancellation behavior; implemented execution contracts.
- Effect catalog; SQLite configuration; synchronous SQLite implementation.
- Current keep-alive predicate; reported mismatch.
apps/server/src/persistence/Migrations.ts, migrations 050_Whiteboards.ts and 051_WhiteboardDurableDeletion.ts; packages/contracts/src/orchestration.ts; apps/server/src/orchestration/Layers/OrchestrationEngine.ts; peer toolkit handlers; apps/web/src/components/ChatView.tsx; the web block registry; shared client state; pnpm-workspace.yaml; apps/server/src/config.ts; and scripts/neuron-daily.mjs. These are local code locators, not public repository links. The checkout has no configured Git remote. Architecture findings were checked against the current source rather than inferred solely from earlier fork notes.