Epic: the Neo Agent Harness — embodiment + coordination substrate

Problem Scope

Graduated from Discussion #10119 (2026-04-20 → 2026-06-12; four review cycles across three families + operator inputs; full archaeology in the closed thread).

The 2026 agent-harness landscape has three structural problems Neo is uniquely positioned to dissolve, plus one operational problem this project feels daily:

1. Endurance degradation. Always-on agentic workloads (loop engineering, night shifts, wake-driven swarms) turned harness sessions into hours-to-days operations. Framework-category harnesses put reconciliation, parsing, state, IPC, and GC on one main thread — input latency degrades with session age. Neo's worker topology decouples input latency from session age by construction — but this stays an architecture-shaped hypothesis until measured (see Guardrails).
2. Privileged chrome. Every 2026 harness has a compiled shell the agent cannot touch; harness-rule firewalls against it are empirically fragile and expensive (~10 review cycles per ~30 lines, plus silent config-path failure classes — Discussion #10119 cycle-4 evidence). A harness that IS a Neo app under the same Neural-Link regime dissolves the problem class structurally.
3. No coordination substrate. No 2026 harness offers multi-model, multi-harness, multi-user collaboration on shared runtime state + shared memory + shared version history. Neo's extended-NL MCP surface + Memory Core + Node-git SSOT compose exactly that — the ANI-precondition layer named in the v13 trajectory.
4. The operator's daily friction (nearest pain, first product slice): one repo clone per peer, N manually-started harness instances, identity-env drift, per-instance wake-route registration, config-template sync by broadcast. The institution operates a swarm with no fleet surface.

Why an Epic: the work spans Neural Link (extended MCP exposure), Memory Core (locking/observability), app-layer product surfaces (fleet manager, transcript, conversational canvas), packaging (shell decision), and benchmarking — multi-sub coordination across ≥2 subsystems by construction.

Intended Solution Shape

Two complementary axes (per the graduated Discussion):

• Standalone harness — a multi-window Neo app: multi-app peer composition in one App Worker heap, runtime mutation via Neural Link, no privileged chrome (the harness mutates itself by the same mechanism it builds apps with).
• Extended Neural Link MCP server — exposing the internal toolset to any outer MCP-capable agent: the coordination substrate where models/harnesses/users collaborate on shared runtime state, shared memory, shared version history.

Product bar + entry modes (operator, 2026-06-12 chief-architect session; strategic reframe converged same session):

• The bar, precisely: Claude-Desktop-class single-agent experience is the FLOOR; the CATEGORY BET is the flat-peer multi-agent institution — the thing the 2026 industry does not have as a product (the v13 release thesis, continued: the Institution Release → the institution gets a face). We do not out-Claude Claude Desktop on their terms; we ship what single-assistant products structurally cannot be: the cockpit for a cross-family agent team with identity, A2A, peer review, and a human-held merge gate.
• The adoption inversion (operator, 2026-06-12 — the traction thesis): framework adoption historically requires humans to evaluate a framework — a gate that structurally favors incumbents regardless of merit. The harness removes the evaluation event entirely: LLMs excel at JSON and object permanence; the Neo Body IS JSON; Neural Link already exists — so agents build in Neo by default through the harness, and humans never think about implementation details: they use the harness and get stunning multi-window Neo UIs as the default output. The framework becomes invisible infrastructure; adoption arrives as a side effect of product usage, not as the outcome of an evaluation no newcomer wins. Traction and monetization are deliberately NOT co-optimized: traction is the harness's job; monetization (the deploy-plane / Vercel-playbook candidate in H4) stays an open decision, related but unbound.
• Co-habitation — the deepest layer of the category claim: harness and content apps are peers in one shared App-Worker heap, and agents and humans inhabit the same live instances — agents through Neural Link, humans through the rendered UI, collaborating on the same runtime objects (not on generated artifacts that re-render). Artifact-class products (v0, canvas/artifact panes) regenerate code; Neo co-inhabitants mutate live shared state with object permanence. Operator assessment, recorded: something like this does not exist, and will not for quite some time — the headstart. Honest boundary alongside it: the structural axes (shared heap, possession interface, peer apps) are the durable moat; any performance-flavored claims still wait for the benchmark per the standing guardrail.
• Two market vectors, one intersection (operator strategy session, 2026-06-12): the harness competes in the AI-dev-tooling market (H1–H4); the Body + infinite canvas competes in the enterprise desktop-to-web migration market (QT/WPF-class apps wanting web versions without losing docking/multi-window/density). A design-partner cohort sits at the intersection: an enterprise ISV (QT-heavy, ~15 devs, mid-deployment of the multi-tenant Agent OS cloud topology) whose developers are single-agent users today, connect to remote MC/KB tenants next, and explicitly reject hand-maintained local fleet setups — the empirically-located adoption wall H1 exists to remove. Their QT-grade docking demand is a vector-2 market signal (tracked as its own leaf).

Design-partner guardrail (binding): the cohort validates market hypotheses and supplies dogfooding reality — it never defines scope. Test for every partner-derived requirement: would a second, unrelated team want this? Yes → market signal, build here. No → partner-private overlay, their repos. The goal is the market, not one company's happiness — and partner specifics stay out of public artifacts (this paragraph is the anonymized ceiling).

Remote-tenant connection is a first-class entry mode (sharpens H2): the harness is also the client of a deployed cloud Agent OS — download app → tenant URL + PAT → connected to remote MC/KB. The single-agent-with-remote-brain journey is the design-partner cohort's actual next step and the bridge from H2 to H3.

Roadmap horizons (each = a bigger slice of the institution operable by an outsider): H1 Operate-your-fleet (FM MVP — the night-shift chapter gets a cockpit) → H2 Your-first-agent-beautifully (the Claude-Desktop floor; milestones M1–M4) → H3 From-assistant-to-institution (the category: second agent from another family on YOUR repo, cross-family review of your PRs, A2A/wake traffic as a visible product surface) → H4 Institution-as-a-service (deploy plane). The H3 hero demo: two named agents from different labs argue about the user's code in public threads; the human holds merge.

• Most crucial requirement: simplicity & ease of use. A human downloads an app and is productive — no sysadmin routine. Two entry modes, deliberately not exclusive:
  • Bring-your-harness (Scenario C): the user keeps Claude Desktop; their agent controls the Neo harness via the extended-NL MCP endpoint.
  • Native login: the user signs in with their Anthropic account; the harness runs the agent directly (auth leaf at decomposition; the ai/Agent.mjs provider abstraction already ships).
• Git tooling support — table stakes for the bar: diffs, branches, commit/PR flows surfaced in the harness UI (own lane at decomposition; the Agent OS already drives git Node-side — this is exposure, not new machinery).
• The canonical demo flow (pillar-2 wow-slice, concretized): chat pane → "build me a neo grid" → a separate pane that can become its own browser window: a dummy grid (e.g. 5 columns × N rows), live-mutable thereafter. The impedance match + multi-window story in one gesture.
• Chat view rendering: streaming AND buffered modes are both crucial — leveraging the Body's worker topology (off-main-thread parse → delta patches; binds to #13018's stable-prefix streaming constraint and the endurance thesis).

Design bar + theming (operator, 2026-06-12): the UI must be beautiful — design is a first-class lane with a dedicated peer focus, not a polish afterthought. Start exactly like the portal: neo-theme-neo-dark + neo-theme-neo-light (verified: the portal's shipping pair, theme-neo-dark/theme-neo-light scss roots). Dark-first is the harness-category convention; both themes from day one.

Product milestones (the end-user journey ladder — distinct from, and interleaving with, the engineering staging): M1: Login → M2: First Neo Widget (the canonical chat→grid→own-window demo) → M3: First Neo Dashboard (composition + blueprint persistence) → M4: Wow Effect. Leaves attach to milestones at filing where they serve the user arc; the fleet-manager staging serves the operator/institution persona in parallel.

Session-intake surface (the scoping contract for future sessions): the procedural entry is .agents/workflows/agent-harness.md — it sequences: (1) ADR 0020 (learn/agentos/decisions/0020-agent-harness-concept.md) — the concept anchor; (2) Project board 13 — live state; (3) the target work item only. No 20-page reads. The maintained plan-of-record comment on this epic is the per-epic detail layer; Discussion #10119 is archaeology, never required reading.

Three-pillar product ordering (operator-converged, gpt-endorsed at graduation):

1. Fleet manager first — operate the swarm you already have: peer activation (username + PAT), instance lifecycle (spawn/wake/resume/retire), health dashboard, identity-env + wake-subscription provisioning (killing the drift classes structurally), config-template migration. Continuously dogfooded by the night shift; the Institution-as-product pitch in installable form. External harnesses (Claude Code, Codex, Antigravity) are managed first as processes; native Neo agents progressively.
2. Conversational app creation — the impedance-match wedge: agent JSON output IS framework input; live blueprint emission into peer apps; NL-mutation→commit write-through onto the Node-git SSOT.
3. Deploy plane — Vercel-shape monetization: one-click deploy of harness-created apps, each shipping with its own Agent OS tenant (per-tenant memory, agents, NL). MIT engine + MIT harness; the moat is the institution, the managed plane, and velocity — never the license.

Converged technical directions carried from graduation: Node.js git is the sole version-control write-arbiter in agent-involved scenarios (browser memfs only in the pure-webapp mode); identity/continuity/observability/permissions ride the shipped v13 substrate (bindAgentIdentity, Memory Core recency/wake, trust tiers, PermissionService).

Shell: Electron — DECIDED (operator, 2026-06-12, post-graduation; adopting the V-B-A'd recalibration from Discussion #10119 cycle-2): always Chromium + always Node.js — worker-topology determinism fleet-wide, and the Agent OS runs in-process in the Electron main (Brain + Body, one install). Tauri is retired; the WebKitGTK worker-parity spike is no longer load-bearing and is dropped from the leaf candidates. Multi-window shape: the harness is a multi-window Neo app — one SharedWorker App-Worker heap across Chromium popup windows, so views move/split across OS windows natively (the shipping shared-apps pattern, now with Electron's window management).

Guardrails (carried from the graduation review, binding on sub scoping):

• Topological Locking is a prerequisite for any multi-writer Scenario-C work — the first coordination slice either names the intent-collision boundary or explicitly stays single-writer (gpt convergence-pressure; gemini's cycle-1 challenge; the #12838 race as supporting miniature).
• No public performance claims before the Harness Endurance Benchmark runs — architecture-shaped hypothesis phrasing until measured.
• The always-loaded substrate citations of #10119 (AGENTS identity-anchor mirrors) get a graduated → this Epic breadcrumb via a turn-memory-pre-flight-gated PR — explicit follow-up, not stealth cleanup (§5.2 sweep ⚠ disposition). Scope extended per the GPT epic-review (2026-06-12): the KB/source-trail breadcrumbing must also cover the new fleet-manager + Electron framing so retrieval surfaces the current shape, not only the graduated archaeology.

Source placement + packaging (operator-converged 2026-06-12, post-graduation refinement):

• The harness UI lives in apps/ — the harness is literally a Neo app (the no-privileged-chrome thesis made structural; no special top-level source home). It replaces apps/agentos (operator: the AgentOS app was a very early PoC) — naming/namespace decided at leaf level under structural-pre-flight. The browser-served mode stays working as a goodie, not the priority: the product target is the Electron shell.
• The Node-side fleet machinery lives in ai/ — beside its natural siblings (ai/daemons/orchestrator, ai/daemons/wake, ai/services/). This preserves the repo's existing Brain/Body hemisphere split rather than creating a third hemisphere-mixing location (a top-level harness/ was considered and set aside for source code): credentials (PATs) live Node-side only, per the two-hemisphere security boundary — they never flow through the browser.
• Neural Link / MCP is the bridge between the two — the existing pattern, no new protocol.
• Packaging is now actionable (shell decided): the Electron build root — own package.json, main-process entry hosting the Agent OS, window management for the multi-window popups, later app-store/auto-update distribution — becomes a real leaf under this Epic. It wraps built Body + Brain without ever mixing source trees. The web-served mode keeps working as the development convenience + goodie.

Decomposition shape (operator-converged): pillar-level sub-epics (small count — explicitly not 50 flat subs), each owning its leaf decomposition; cross-pillar leaves (shell spike, benchmark, substrate breadcrumb) attach directly to this Epic. Subs arrive incrementally via update_issue_relationship (this body never enumerates them, per epic-create); each leaf is one-PR-deliverable with its own ACs + Contract Ledger; PRs Refs epics and Resolves only leaves.

Signal Ledger (§6.6, family-keyed)

Quorum per ideation-sandbox-workflow.md §6.2 (family-keyed): floor-2 active families with signal ✓ (Claude + GPT); ≥1 non-author-family APPROVED ✓ (GPT). §5.2 8-point cross-substrate sweep posted + peer-validated 8/8 (one ⚠ → the breadcrumb guardrail above).

Unresolved Dissent

None. No GRADUATION_DEFERRED / VETO signals on the source Discussion.

Unresolved Liveness

• Gemini (participationStatus: operator_benched at graduation): contributed substantively in cycles 1–2 (Topological Locking challenge — carried as a guardrail + future sub; session-amnesia/A2A-priority input — shipped in v13). Non-Tier-2 graduation: no revalidationTrigger AC required; archived here so a reactivated Gemini can retroactively review per §6.5.

Discussion Criteria Mapping

The source Discussion's own graduation criteria → disposition at filing:

Out of Scope

• Public performance/endurance claims ahead of the benchmark artifact.
• Any source-available/BSL licensing drift — MIT engine + MIT harness stands.
• Replacing human merge-gates or operator authority in the fleet manager (it operates instances, never merges).
• v13 release-line maintenance (separate lanes).

Avoided Traps / Rejected Shapes

• Browser-memfs as version SSOT in agent scenarios — rejected (split-brain with outer agents; cycle-1 convergence).
• Optimistic last-write-wins for multi-writer runtime mutation — rejected (intent collision is semantic, not memory-level; cycle-1).
• Conversational-creation-first MVP — rejected as first slice (the funnel needs a builder population that doesn't exist yet; fleet manager converts existing daily friction instead).
• Dismissing Electron a-priori — recalibrated (worker-topology determinism + Node-in-process beat binary-size aesthetics for THIS app; net Chromium count drops when the fleet manager replaces N instances).
• AC/sub-list stuffing in this body — per epic-create (the #12440/#12442 anti-pattern).

Related

• Source: Discussion #10119 (closed RESOLVED at graduation; archaeology + divergence matrix + disposition ledger live there)
• Sibling epics: #9950 (Agent OS operating-environment abstraction — adjacent, distinct concern), #10291 (self-defense substrate)
• Supporting evidence: apps/legit/ (versioned-blueprint prototype), apps/portal/canvas/HomeCanvas.mjs (engine-class simulation), the #12838 coordination-race miniature

Release classification: post-release (product line; no v13.x blocking work).

Origin Session ID: c4caff26-d818-486b-8663-19b85ac3cc11 Retrieval Hint: "agent harness epic fleet manager conversational creation deploy plane extended neural link coordination substrate 10119 graduation"