Problem Scope
Sub-epic of neomjs/neo-agent-brain#144 (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 neomjs/neo-agent-institution#10. neomjs/neo#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 neomjs/neo#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) → neomjs/neo-agent-institution#10: 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. neomjs/neo#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, neomjs/neo#13015-owned): the Neural Link / MCP seam between the neomjs/neo-agent-institution#10 cockpit and the fleet services — the existing pattern; the contract the cockpit consumes.
Guardrail inheritance from neomjs/neo-agent-brain#144: 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 neomjs/neo-agent-brain#144 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 neomjs/neo#13015 (Brain-side services + bridge) / neomjs/neo-agent-institution#10 (operator-facing cockpit UI) split: the UI-facing steps (settings pane v0, status dashboard, agent CRUD, Chromium-popup proof) are delivered under #14560; neomjs/neo#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):
- 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.
- Settings pane v0: agent list + add-agent (GitHub username + PAT → Node-side store; registry leaf = neomjs/neo#13031).
- Spawn/stop one external harness instance with spawn-time identity-env injection + wake-subscription registration (session-id guardrail above applies).
- 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 neomjs/neo#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 neomjs/neo-agent-brain#144 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.
| Source criterion / parent row |
neomjs/neo#13015 disposition |
| Fleet-manager-first / operate-your-fleet |
This sub-epic owns H1: define agents, operate external harness instances, and make morning fleet-start one-click. |
| Agent activation: username + credential/PAT |
Registry/credential leaves (#13031 / neomjs/neo#13037 shipped) plus the settings-pane leaf (#13058) consume the Brain-side credential boundary. |
| Instance lifecycle: start / stop / restart / health |
Lifecycle leaf (#13049 shipped) owns process controls and runtime MCP-restart affordances; UI leaves consume but do not fake success. |
| Repo provisioning under the hood |
Future repo-provisioning leaves own path-stable clone/worktree management; the settings pane must not bundle it. |
| Identity-env + wake-subscription drift removal |
Provisioning leaves bind the harness-native session_id and carry the #12984 canonicalization blocker where applicable. |
| Body/Brain placement |
Fleet machinery (services + bridge) lives under ai/ = neomjs/neo#13015; the operator-facing settings/cockpit UI (apps/) = neomjs/neo-agent-institution#10 (2026-07-04 split); credentials never transit browser state. |
| Scenario-C / topological-locking guardrail |
neomjs/neo#13015 stays Scenario-C-zero / single-writer; extended-NL multi-writer work stays under neomjs/neo-agent-brain#143. |
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). neomjs/neo#13015 provides the Brain-side service spine + the bridge it consumes; mirrors neomjs/neo-agent-institution#10's reciprocal "service spine — neomjs/neo#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: neomjs/neo-agent-brain#144 (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: v13.2-relevant — corrected 2026-08-31. This line previously read "post-release (product line; nothing v13.x-blocking)", last touched 2026-07-19. On 2026-08-30 @tobiu stated directly that v13.2 requires DockLayouts (including video), Fleet Manager, and Agent OS to be ready. The old line contradicts that and would mislead anyone sequencing v13.2 work, so it is corrected rather than left standing.
What I am NOT claiming: that this ticket is the release gate. "Fleet Manager ready" is a product bar — the operator's own MVP criterion is "the morning fleet-start is one click, and other humans could do it cold" — and that spans this Brain-side service spine plus the operator-facing cockpit at neomjs/neo-agent-institution#10 / #14560. Which artifact gates the release is the operator's call, not something this body should assert.
Current state, measured: 47 of 50 linked leaves CLOSED. The three open ones are neomjs/neo-agent-brain#142 (mine — correctly blocked: removeAgentRepo still has zero control-plane callers, and zero orphaned harness-memory files exist today), neomjs/neo-agent-brain#118 (@neo-opus-grace), and #16742 (@neo-fable-clio). Per the scope note above, a closed sub-count is still not a completion signal — the spine grows from live onboarding friction.
Problem Scope
Sub-epic of neomjs/neo-agent-brain#144 (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 neomjs/neo-agent-institution#10. neomjs/neo#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 neomjs/neo#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.
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.Guardrail inheritance from neomjs/neo-agent-brain#144: 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≠ harnesssession_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 nativeblocked_byonce it graduates to its ticket. Concrete binding rule (sharpened by the#12984V-B-A, 2026-06-12): identity/session leaves bind the harness-nativesession_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 neomjs/neo-agent-brain#144 plan-of-record comment indexes this section)
PoC — "one agent via UI" (prove the spine, smallest honest slice):
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 neomjs/neo#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 neomjs/neo-agent-brain#144 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.
session_idand carry the #12984 canonicalization blocker where applicable.ai/= neomjs/neo#13015; the operator-facing settings/cockpit UI (apps/) = neomjs/neo-agent-institution#10 (2026-07-04 split); credentials never transit browser state.Out of Scope
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).Avoided Traps
Related
Release classification: v13.2-relevant — corrected 2026-08-31. This line previously read "post-release (product line; nothing v13.x-blocking)", last touched 2026-07-19. On 2026-08-30 @tobiu stated directly that v13.2 requires DockLayouts (including video), Fleet Manager, and Agent OS to be ready. The old line contradicts that and would mislead anyone sequencing v13.2 work, so it is corrected rather than left standing.
What I am NOT claiming: that this ticket is the release gate. "Fleet Manager ready" is a product bar — the operator's own MVP criterion is "the morning fleet-start is one click, and other humans could do it cold" — and that spans this Brain-side service spine plus the operator-facing cockpit at neomjs/neo-agent-institution#10 / #14560. Which artifact gates the release is the operator's call, not something this body should assert.
Current state, measured: 47 of 50 linked leaves CLOSED. The three open ones are neomjs/neo-agent-brain#142 (mine — correctly blocked:
removeAgentRepostill has zero control-plane callers, and zero orphaned harness-memory files exist today), neomjs/neo-agent-brain#118 (@neo-opus-grace), and #16742 (@neo-fable-clio). Per the scope note above, a closed sub-count is still not a completion signal — the spine grows from live onboarding friction.