Problem scope
The harness's shell is decided (Electron — always Chromium + Node.js; ADR 0020 §3) but uncovered as structure: #13033 is only the build-root spike (the one genuine-discovery-risk item — Agent-OS-in-Electron-main vs child-process supervision). The full shell topic has no home: packaging the built Body + Brain (own package.json, no source-tree mixing), Agent-OS process lifecycle in the main process, and distribution (code-signing, auto-update, app-store). Without this, H1's "downloadable fleet-manager app" — the whole adoption-inversion premise — has no delivery vehicle.
Why an Epic: packaging + main-process hosting + lifecycle + distribution are ≥2 coordinated subs across the Electron build root, ai/ (the Node-side Agent OS it hosts), and release tooling.
Intended solution shape
The Electron packaging root that boots the whole organism: the main process hosts (or supervises) the Agent OS (orchestrator + MCP servers) while Chromium windows serve the harness Neo app on one SharedWorker heap. Credentials (PATs) stay Brain-side only (never transit the browser). Web-served mode remains the dev convenience + goodie, never the priority.
Decisive boundary (per the operator's WindowManager correction, 2026-06-15): Electron is the shell only — it does not own the additional windows. Multi-window is Chromium popups managed by Neo.manager.Window (browser-native → Electron-agnostic, which is exactly what keeps a future web version alive). So this epic is shell · main-process Agent-OS hosting · packaging · distribution — NOT window choreography (that belongs to the Infinite-Canvas + NL-control epics).
Out of scope
- Window management / multi-window choreography (browser-native popups via
Neo.manager.Window — the Infinite-Canvas + NL-control epics).
- The harness app's UI / features (the harness app lives in
apps/, replacing apps/agentos; this epic wraps the built output).
Avoided traps / rejected shapes
- Tauri / WebKitGTK — retired (ADR 0020: worker-topology determinism + Node-in-process beat binary-size aesthetics for this app).
- Electron owning the windows — rejected; windows are browser-native popups (keeps web-portability + matches the shipping shared-apps pattern).
- Mixing source trees — the packaging root wraps built Body + Brain (own
package.json); it never touches the source hemispheres.
Design authority
ADR 0034 — Electron shell architecture (learn/agentos/decisions/0034-electron-shell-architecture.md; Proposed via #14786 / PR #14924, ADR-0005 lifecycle) settles the six shared shell questions — process model + app lifecycle, the empirically-verified SharedWorker constraint set (headline: file:// packaging silently kills worker sharing; real origin + one partition required), the fail-closed security contract, dock/OS-window fusion (materialization-not-ownership), distribution, and dev/prod parity. Its §5 table is the E-leaf gate: E1 = #13033 as its live Contract Ledger stands (consumed unchanged); E2–E8 are post-E1 refinement leaves filed on demand, each citing its §5 row. The spikes/14786-electron-sharedworker/ reproducer (merged with the ADR) re-runs on every Electron major bump — owner: the E2 leaf owner.
First leaf: #13033 (build-root spike — the in-process-vs-child-process hosting decision; owner @neo-opus-ada). Steward: @neo-opus-vega.
Authored by @neo-opus-vega (Vega), harness steward, under ADR 0020 + the #13012 north-star checkpoint.
Problem scope
The harness's shell is decided (Electron — always Chromium + Node.js; ADR 0020 §3) but uncovered as structure: #13033 is only the build-root spike (the one genuine-discovery-risk item — Agent-OS-in-Electron-main vs child-process supervision). The full shell topic has no home: packaging the built Body + Brain (own
package.json, no source-tree mixing), Agent-OS process lifecycle in the main process, and distribution (code-signing, auto-update, app-store). Without this, H1's "downloadable fleet-manager app" — the whole adoption-inversion premise — has no delivery vehicle.Why an Epic: packaging + main-process hosting + lifecycle + distribution are ≥2 coordinated subs across the Electron build root,
ai/(the Node-side Agent OS it hosts), and release tooling.Intended solution shape
The Electron packaging root that boots the whole organism: the main process hosts (or supervises) the Agent OS (orchestrator + MCP servers) while Chromium windows serve the harness Neo app on one SharedWorker heap. Credentials (PATs) stay Brain-side only (never transit the browser). Web-served mode remains the dev convenience + goodie, never the priority.
Decisive boundary (per the operator's WindowManager correction, 2026-06-15): Electron is the shell only — it does not own the additional windows. Multi-window is Chromium popups managed by
Neo.manager.Window(browser-native → Electron-agnostic, which is exactly what keeps a future web version alive). So this epic is shell · main-process Agent-OS hosting · packaging · distribution — NOT window choreography (that belongs to the Infinite-Canvas + NL-control epics).Out of scope
Neo.manager.Window— the Infinite-Canvas + NL-control epics).apps/, replacingapps/agentos; this epic wraps the built output).Avoided traps / rejected shapes
package.json); it never touches the source hemispheres.Design authority
ADR 0034 — Electron shell architecture (
learn/agentos/decisions/0034-electron-shell-architecture.md; Proposed via #14786 / PR #14924, ADR-0005 lifecycle) settles the six shared shell questions — process model + app lifecycle, the empirically-verified SharedWorker constraint set (headline:file://packaging silently kills worker sharing; real origin + one partition required), the fail-closed security contract, dock/OS-window fusion (materialization-not-ownership), distribution, and dev/prod parity. Its §5 table is the E-leaf gate: E1 = #13033 as its live Contract Ledger stands (consumed unchanged); E2–E8 are post-E1 refinement leaves filed on demand, each citing its §5 row. Thespikes/14786-electron-sharedworker/reproducer (merged with the ADR) re-runs on every Electron major bump — owner: the E2 leaf owner.First leaf: #13033 (build-root spike — the in-process-vs-child-process hosting decision; owner @neo-opus-ada). Steward: @neo-opus-vega.
Authored by @neo-opus-vega (Vega), harness steward, under ADR 0020 + the #13012 north-star checkpoint.