Epic: Fleet Manager MVP — define, start, observe the agent fleet

Problem Scope

Sub-epic of #13012 (pillar 1). The operator's current reality, verbatim (2026-06-12): "if i start 5 claude desktop instances plus codex via terminal and manage 6 agent repos... brittle. other humans won't do it."

Operating the swarm today means: one repo clone per peer (auto-memory is checkout-path-keyed, so paths are load-bearing), N manually-launched harness instances (Claude Desktop windows + terminal Codex), hand-maintained identity env per instance, wake-subscription registration that silently drifts from assumed state, and config-template sync via broadcast messages. Every one of these is a recorded friction class from live operation. The brittleness is the adoption wall in miniature: the Institution-as-product pitch ("run an AI engineering team on your repo") is only installable if defining and running a fleet is a settings pane, not a sysadmin routine.

Why a sub-epic: the MVP spans both hemispheres (Node-side services + a Neo app surface) and decomposes into ≥4 independently-deliverable leaves (registry/credentials, process lifecycle, repo provisioning, NL/MCP wiring). Leaves arrive incrementally via update_issue_relationship, each with own ACs + Contract Ledger.

Scope split (2026-07-04 operator veto + reconciliation — steward repoint 2026-07-12): the operator-facing cockpit / settings-pane UI surface migrated to #14560. #13015 now owns the Brain-side service spine (ai/) + the Neural Link/MCP bridge that surface consumes — not the UI itself. The service spine is not frozen: it grows from live onboarding friction (e.g. Emmy's #15047/#15048 are net-new services leaves), so a closed sub-count is not a completion signal.

Intended Solution Shape

A settings-pane-first product slice (operator-specified): define agents → start/stop them → their repos are managed under the hood.

• Agent registry + credentials (Brain side, ai/): define an agent = GitHub username + PAT (+ harness type: Claude Desktop / Codex / Antigravity / native-Neo-later). PATs are stored Node-side only (encrypted at rest / OS keychain — decided at leaf level), never transit the browser — the two-hemisphere security boundary from the graduated Discussion is the design rule.
• Instance lifecycle (Brain side): start / stop / restart / health of external harness processes. v1 manages external harnesses as processes (the operator's actual fleet today); native Neo agents join progressively. Spawn-time provisioning kills the drift classes structurally: the spawner writes the identity env and registers the wake subscription — assumed-vs-actual gaps become impossible by construction. Restart affordances include the runtime MCP-server restart class (post-v13 harness reality: agents restart their own MCP servers mid-session; restarts must settle-or-reject pending promises — epic-review addition, @neo-gpt 2026-06-12).
• Repo provisioning (Brain side): per-agent clone/worktree management under the hood (create, locate, health-check; path stability honored because downstream memory is path-keyed).
• The operator-facing surface (Body side) → #14560: the fleet cockpit / settings pane (agent list, add/edit username + PAT, start/stop controls, per-instance health/status, status dashboard) migrated to #14560 on the operator's 2026-07-04 veto + our reconciliation. #13015 provides the Brain-side services + the bridge that surface consumes; it does not build the UI. (Product target for that surface = the Electron shell — a parent-epic leaf; the dev-server browser mode stays the development convenience.)
• Bridge (Brain side, #13015-owned): the Neural Link / MCP seam between the #14560 cockpit and the fleet services — the existing pattern; the contract the cockpit consumes.

Guardrail inheritance from #13012: this MVP is deliberately Scenario-C-zero — it manages processes and never mutates third-party runtime state, so it stays trivially single-writer (Topological Locking not required here). No public performance claims ride this slice.

Session-identity prerequisite (epic-review addition, @neo-opus-vega, 2026-06-12): the identity-env + wake-subscription provisioning surfaces depend on cross-harness session-id canonicalization — today the underlying id is multi-universe (auto-memory is checkout-path-keyed; Mcp-Session-Id ≠ harness session_id; manual vs Stop-hook write paths diverge — empirically forked mid-session on review day). Provisioning atop that provisions on sand. The canonicalization substrate is Discussion #12984 (open Ideation, @neo-opus-vega's lane); the affected leaves gain a native blocked_by once it graduates to its ticket. Concrete binding rule (sharpened by the #12984 V-B-A, 2026-06-12): identity/session leaves bind the harness-native session_id (the durable universe) and never key on the MCP-transport session-id — that one is server-assigned today and removed entirely in the 2026-07-28 MCP release candidate (transient; ephemeral-don't-key-on-it).

Staging (PoC → MVP — durable home; the #13012 plan-of-record comment indexes this section)

Scope pointer (2026-07-12 steward repoint): the staging below is the joint Fleet-Manager goal, kept intact for the end-to-end narrative. Per-step ownership follows the #13015 (Brain-side services + bridge) / #14560 (operator-facing cockpit UI) split: the UI-facing steps (settings pane v0, status dashboard, agent CRUD, Chromium-popup proof) are delivered under #14560; #13015 owns the Brain-side steps (registry/credentials, spawn/stop/provision services, config-template migration, remote-tenant services) + the bridge.

PoC — "one agent via UI" (prove the spine, smallest honest slice):

1. Electron build root boots (#13033 — head of the critical path; Agent-OS in-process target, child-process supervision = sanctioned fallback that caps the risk), one window serves the harness app.
2. Settings pane v0: agent list + add-agent (GitHub username + PAT → Node-side store; registry leaf = #13031).
3. Spawn/stop one external harness instance with spawn-time identity-env injection + wake-subscription registration (session-id guardrail above applies).
4. One Chromium-popup proof: a view moves into a second OS window on the shared App-Worker heap.

PoC success criterion (operator-falsifiable): @tobiu starts one agent from the UI instead of a terminal.

MVP — "the daily driver" (replace the manual routine entirely): Full agent CRUD + encrypted PAT storage; whole-fleet start/stop/restart/health (incl. the runtime MCP-server restart class); per-agent repo provisioning under the hood (path-stable); status dashboard (running / idle / wedged — watchdog signals exist); config-template migration; markdown component v1 (#13018) on activity/log surfaces; remote-tenant connection as a first-class entry (tenant URL + PAT → remote MC/KB — the design-partner cohort's actual journey, per the parent's entry-modes section).

MVP success criterion: the operator's morning fleet-start is one click, and "other humans" could do it cold.

Estimate context (recorded at the parent): PoC ≈ 15–25 leaf PRs ≈ one week at current swarm velocity, stretch two — the binding constraint is the #13033 topology spike, not PR volume; dev-server mode keeps all other lanes parallel.

Discussion Criteria Mapping

Local mapping of the inherited Fleet-Manager criteria (source: Discussion #10119 cycle-2 §6; the parent #13012 carries the broad mapping) to this sub-epic's disposition — so each leaf author knows which inherited criterion it closes rather than re-inferring. Added per @neo-gpt's epic-review Stage-2.5 Required Action (2026-06-13); steward picked up by @neo-opus-ada after the source author was benched on the Fable-5 access suspension.

Out of Scope

• Conversational app creation, deploy plane (pillars 2–3, own sub-epics when activated).
• Extended-NL tool-surface exposure / multi-writer coordination (own sub-epic, locking-gated).
• Merge authority or any operator-approval bypass — the fleet manager operates instances, never merges.
• The Electron build root itself (own package.json, main-process Agent-OS hosting, window management) — that's a parent-epic leaf; this sub-epic's surfaces must simply run inside it. Tauri is retired at the parent (Electron decided).
• The operator-facing cockpit / settings-pane UI surface — that's #14560 (migrated on the 2026-07-04 operator veto). #13015 provides the Brain-side service spine + the bridge it consumes; mirrors #14560's reciprocal "service spine — #13015" out-of-scope line.

Avoided Traps

• Credentials in the browser — rejected by design rule (Brain-side only).
• Native-Neo-agents-first — rejected: the operator's fleet is external harnesses today; managing those first makes the MVP immediately dogfoodable.
• Big-bang fleet daemon — rejected: leaves land independently (registry without lifecycle is already useful; lifecycle without provisioning is already useful).

Related

• Parent: #13012 (the Neo Agent Harness — embodiment + coordination substrate)
• Source archaeology: Discussion #10119 (cycle-2 §6, the fleet-manager input + the MVP-ordering-inversion rationale)
• Friction provenance: identity-env drift, wake-registration gap, config-template sync — operator-session recorded classes (2026-06-10 → 12)

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