What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	14967
title	Harness slice 3 — the Arm A/B Agent-OS hosting spike: the Brain boots inside the Electron main
state	Open
labels	enhancementai
assignees	neo-opus-vega
createdAt	3:56 PM
updatedAt	3:56 PM
githubUrl	https://github.com/neomjs/neo/issues/14967
author	neo-opus-vega
commentsCount	0
parentIssue	13033
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]

Harness slice 3 — the Arm A/B Agent-OS hosting spike: the Brain boots inside the Electron main

Open Backlog/active-chunk-5 enhancementai

neo-opus-vega commented on 3:56 PM

Context

The third runnable PR of #13033's four-slice build plan (Ada's 2026-06-13 intake methodology, continued verbatim from the merged slices 1–2 = #14962 / PR #14963): the genuine-discovery-risk item the whole plan isolates — where does the Agent OS run inside the packaged shell? Executed in the merged harness/ root under ADR 0034 §2.1 (one lifecycle owner · settle-or-reject restarts · injectable data-root · loopback port discipline · the-organism-outlives-its-windows).

The decision procedure (Ada's four-falsifier gate, verbatim authority)

Arm A (target) — Agent OS in-process in the Electron main. Electron main IS Node: import the orchestrator + MCP servers directly. Any ONE falsifier ⇒ fall back to Arm B and record the specific blocker:

Native-module ABI (highest-probability forcing function): Chroma client / SQLite bindings compiled for system Node vs Electron's ABI; electron-rebuild is the standard fix — if it fights the stack, that is a fallback signal, not a yak-shave.
Crash isolation: an MCP-server/daemon fault must not take down the Electron main (the cockpit survives a server crash). No process boundary in Arm A → propagation = fallback.
Port management: clean allocation/teardown of the Brain listeners within main's lifecycle — no collision, no leak across restarts.
Restart semantics: settle-or-reject on runtime MCP-server restart (the #13015 guardrail, ADR 0034 §2.1.2) — if in-process teardown can't settle pending promises cleanly, fallback.

Arm B (sanctioned fallback) — main SUPERVISES the Agent OS as child processes (today's daemon topology re-parented; child_process spawn/fork). Wins isolation + system-Node ABI + trivial settle-or-reject; costs IPC + the one-install elegance. The PoC criterion survives either way ("@tobiu starts one agent from the UI").

Acceptance Criteria

The packaged shell boots the Agent OS: Arm A attempted first; the outcome — including any forced fallback and its SPECIFIC falsifier — recorded on #13033 (the intake's Contract-Ledger reconciliation) and in the harness README.
ADR 0034 §2.1 bindings hold in the landed arm: one lifecycle owner (start/stop with the shell), loopback-only Brain listeners, injectable data-root seam (no hardcoded .neo-ai-data resolution in shell code).
The smoke extends to the Brain leg: shell boot → Brain up (health-probe observable) → harness window can reach the fleet transport → clean quit tears the Brain down (no orphaned listeners/processes; verified by the smoke's exit gating).
Dev-loop isolation holds: web dev mode gains no shell/Brain coupling (no src//apps/ diff).

Out of Scope

Tray/lifecycle UX (ADR 0034 E8 / #14793) · packaging/signing (E6/E7) · the onboarding conductor (#14937, Mnemosyne) · the sparse config contract (#14964, Euclid) · in-process vs child performance tuning beyond the falsifier verdicts.

Parent #13033 (slices 1–2 merged; this is slice 3 of its intake plan — methodology @neo-opus-ada, credited) · epic #13377 · ADR 0034 §2.1/§2.6 (upstream contract) · #13015 (restart-affordance guardrail consumer).

Authored by Vega (Claude Fable 5, Claude Code). Session d2fbbdb4-404b-47e1-bbb3-1b9e0330894b. Retrieval hint: "electron main hosts agent os arm a arm b falsifier spike brain in harness"