Electron build root: boot the Agent OS + harness windows in one shell

Context

The head of the PoC critical path for Epic #13012 (per the recorded gut-estimate: the ONE item with genuine discovery risk; everything else parallelizes in dev-server mode). Shell decision already made at the parent (operator, 2026-06-12): Electron — always Chromium + always Node.js; Tauri retired. This leaf creates the build root.

The Problem

The harness needs a packaged shell that boots the whole organism: the Electron main process hosting (or supervising) the Agent OS — orchestrator + MCP servers — while windows serve the harness Neo app on one SharedWorker heap. No such packaging root exists; the repo ships dev-server + daemon topologies only.

The Architectural Reality

• Topology decision carried from planning (the risk item): target = Agent OS in-process in the Electron main (Brain + Body, one install). Untested: MCP server lifecycle, port management, and restart semantics inside Electron main (restart affordances incl. settle-or-reject promise semantics are a #13015 lifecycle requirement). Sanctioned fallback (caps the risk): the main process supervises the Agent OS as a child process (today's daemon topology) — the PoC criterion survives either way; in-process becomes an MVP refinement if the spike fights back.
• Source-tree discipline (parent decision): the build root wraps built Body + Brain WITHOUT mixing source trees — own package.json, main-process entry, window management; placement via structural-pre-flight at implementation (a packaging root is the sanctioned exception shape discussed at the parent: source stays in apps/ + ai/).
• Multi-window: Chromium popups on one SharedWorker heap (the shipping shared-apps pattern); the shell adds BrowserWindow management + the Electron enhancement points consumed later by #13025/#13028/#13030 (exact spawn-at-position, move events, OS chrome control).
• Web mode stays the development convenience + goodie — the shell never becomes a dev-loop dependency.

Contract Ledger (new surfaces — this leaf INTRODUCES them)

Rows altitude-honest; shapes reconcile in the implementing PR.

Acceptance Criteria

• A packaged Electron app boots: main process brings up the Agent OS (in-process OR documented child-process fallback — the spike outcome is recorded either way), one window serves the harness app.
• Chromium popup windows join the same SharedWorker heap (multi-window proof inside the shell).
• The topology spike outcome (in-process vs fallback, with the friction found) is documented in the PR + reconciled into this Ledger.
• Dev-server/browser mode remains fully functional (no shell dependency leaks into the dev loop).

Out of Scope

• Settings pane content (#13015 leaves), themes (#13022), store/auto-update distribution (follow-up leaf once the root exists).
• The agentos-PoC replacement app itself (own leaf; this root LOADS whatever app exists).

Related

• Parent: Epic #13012. Milestone: M1 (the shell is the login vehicle). Board: Project 13.
• Consumers: #13015 (lifecycle), #13025/#13028/#13030 (Electron enhancement points), #13022 (themes render inside it).
• Closed Electron priors swept: #12958 (worker reply-loss, Electron-deterministic — its fix ships in v13), #12419 (macOS-Electron parent-chain-walk) — both inform, neither overlaps.

Origin Session ID: c4caff26-d818-486b-8663-19b85ac3cc11 Retrieval Hint: "electron build root main process agent os in-process child-process fallback packaging shell harness"