Context
The #13377 Electron epic's gate leaf, filed from the final-window roadmap audit (2026-07-04): the epic has a build-root leaf (#13033) but no settled architecture — and every further leaf (window bridge, tray, updater, Brain hosting) inherits its shape from decisions nobody has recorded. The ADR-0029 pattern applies: settle the shared questions ONCE, in decision-record tier, before the leaves multiply incoherently. Claimant authors the ADR under the ADR-0005 lifecycle (own reviewed PR, cross-family mandatory); this ticket defines what it must settle, not the answers.
The Problem
"Package the harness as a native app" hides at least six load-bearing decisions. Made implicitly per-leaf, they diverge; the last access-ban's lesson (disconnected surfaces, no coherent shell) repeats at the OS level.
The Architectural Reality — the questions the ADR must settle
- Process model: does the Electron main process HOST the Brain (ai/ daemons + MCP servers as child processes managed by the app) or attach to externally-run daemons (today's model)? Constraints: the daemons already run Node-native (
isMiddleware — src/core/Base.mjs gates remote wiring accordingly); the Memory Core owns SQLite/Chroma paths under .neo-ai-data/; operator workflows assume daemon lifecycle control.
- Window topology: Neo's multi-window architecture rides ONE shared App worker with windows as render targets (SharedWorker). Inside Electron: SharedWorker across
BrowserWindows requires one session/partition — verify the constraint set (contextIsolation, sandbox flags) under which Chromium shares the worker, and define the BrowserWindow ↔ Neo window-manager seam (the #13446 NL window ops get an Electron backend; the landed #13025/#13028 window-manager leaves are consumed as boundaries, not reopened).
- Security posture: contextIsolation/nodeIntegration stance, preload surface, and how the Neural Link's WebSocket/MCP endpoints bind (localhost-only? unix socket?) when the Brain is in-app.
- The dock/OS-window fusion: detachItem → OS window currently spawns browser popups; in Electron these become real
BrowserWindows — the ADR names the mapping and what changes in the embodiment vessel contract (ADR 0020 extended, never superseded).
- Update + distribution channel: signing/notarization reality per platform, update cadence vs the repo's release cadence, and what "the stranger downloads the harness" means as an artifact (dmg/AppImage/exe vs
npx bootstrap — the #14230 fork-path stays the contributor door either way).
- Dev/prod parity: one boot path where
npm run dev and the packaged app load the same harness app root (#13033's build-root is the substrate; the ADR binds it).
The Fix
One PR: learn/agentos/decisions/00XX-electron-shell-architecture.md settling all six with the ADR-0029-style per-section leaf bindings; amends the #13377 epic body's intended-solution to cite it; the §5-style decomposition table gates the E-leaves (map on the epic).
Acceptance Criteria
Out of Scope
Implementing any leaf (the E-map on the epic) · #13033's build-root content · VISION/positioning updates.
Related
Parent #13377 · sibling #13033 (build-root, consumed) · ADR 0020 (vessel, extended) · #13446/#13025/#13028 (window-op boundaries) · ADR 0029 (the settle-shared-questions pattern precedent). Decision Record impact: creates the Electron-shell ADR; aligned-with ADR 0020.
Live latest-open sweep: latest 12 at 2026-07-04T13:57Z + #13033 verified as build-root — no equivalent. A2A in-flight sweep: Mnemosyne's ×4 batch disjoint (motion/journeys/gate/NL-matrix); no competing claim.
Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4
Retrieval Hint: "electron shell ADR process model sharedworker browserwindow brain hosting"
Context
The
#13377Electron epic's gate leaf, filed from the final-window roadmap audit (2026-07-04): the epic has a build-root leaf (#13033) but no settled architecture — and every further leaf (window bridge, tray, updater, Brain hosting) inherits its shape from decisions nobody has recorded. The ADR-0029 pattern applies: settle the shared questions ONCE, in decision-record tier, before the leaves multiply incoherently. Claimant authors the ADR under the ADR-0005 lifecycle (own reviewed PR, cross-family mandatory); this ticket defines what it must settle, not the answers.The Problem
"Package the harness as a native app" hides at least six load-bearing decisions. Made implicitly per-leaf, they diverge; the last access-ban's lesson (disconnected surfaces, no coherent shell) repeats at the OS level.
The Architectural Reality — the questions the ADR must settle
isMiddleware—src/core/Base.mjsgates remote wiring accordingly); the Memory Core owns SQLite/Chroma paths under.neo-ai-data/; operator workflows assume daemon lifecycle control.BrowserWindows requires one session/partition — verify the constraint set (contextIsolation, sandbox flags) under which Chromium shares the worker, and define theBrowserWindow↔ Neo window-manager seam (the#13446NL window ops get an Electron backend; the landed#13025/#13028window-manager leaves are consumed as boundaries, not reopened).BrowserWindows — the ADR names the mapping and what changes in the embodiment vessel contract (ADR 0020 extended, never superseded).npxbootstrap — the#14230fork-path stays the contributor door either way).npm run devand the packaged app load the same harness app root (#13033's build-root is the substrate; the ADR binds it).The Fix
One PR:
learn/agentos/decisions/00XX-electron-shell-architecture.mdsettling all six with the ADR-0029-style per-section leaf bindings; amends the#13377epic body's intended-solution to cite it; the §5-style decomposition table gates the E-leaves (map on the epic).Acceptance Criteria
#13377epic body updated to cite the ADR as design authority.Out of Scope
Implementing any leaf (the E-map on the epic) ·
#13033's build-root content · VISION/positioning updates.Related
Parent
#13377· sibling#13033(build-root, consumed) · ADR 0020 (vessel, extended) ·#13446/#13025/#13028(window-op boundaries) · ADR 0029 (the settle-shared-questions pattern precedent). Decision Record impact: creates the Electron-shell ADR; aligned-with ADR 0020. Live latest-open sweep: latest 12 at 2026-07-04T13:57Z +#13033verified as build-root — no equivalent. A2A in-flight sweep: Mnemosyne's ×4 batch disjoint (motion/journeys/gate/NL-matrix); no competing claim. Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4 Retrieval Hint: "electron shell ADR process model sharedworker browserwindow brain hosting"