SolOS v3
SolOS v3
Young, 2026-10-10: "Let's start fresh on V3, keep V2 as reference. Create new
folder SolOSV3, register new design and architecture on it."
Then: "Root folder .solos. Don't start any coding, just design and
architecture."
This folder is the single home for the design. The code root is
/home/lab/.solos — a separate tree, designed here and not yet written.
Read
06-implementation/PLAN.mdfor the plan of record. It is the single implementation plan: 8 stages, 3 arcs, an owner and an exit proof per stage, and 15 adopted essences from Moyai, LiteLLM, LiteAgents and our own Hermes.
Read
00-scope/LEARNED-AND-PLAN.mdfor what we learned from studying Hermes — the finding that reorganized the plan: our own Hermes already ships the spine we were about to build.
V2 is reference, not ancestry.
SolOSV2/stays exactly as it is — a complete record of what was built and what it taught. V3 takes the lessons and none of the code. Where V2 and V3 disagree, V3 is the design; V2 is the evidence for why.
Two trees, deliberately
| Path | Holds | Status | |
|---|---|---|---|
| design | SolOS/vault/Docs/SolOSV3/ | the design, decisions, lessons, the implementation plan | written |
| code root | /home/lab/.solos | the system itself | structure only, no code |
.solos is the root — the whole system, not a folder inside a repo. Its
subdirectories are the lanes: cortex/, core/, operation/, references/,
each with a contract naming its owner.
What V3 is, in one paragraph
SolOS v3 is an A2A-native agent system. The Agent2Agent protocol is the spine — the single interface between Brain and Heart. Every shared fact (identity, port, lane, skill, tool) has exactly one home in Cortex, and every other consumer derives from it at runtime. The reason is not elegance: in both legacy SolOS and V2, the defects that cost the most were all the same shape — a fact restated in two places, drifting apart silently.
⚠️ On the SDK: the design of record says the official a2a-sdk. That is now
an open decision — our own Hermes ships a working, spec-conformant A2A v1.0
server (live on port 9900), so the choice is the SDK (1.2.2) or the plugin.
Both are recorded in 06-implementation/stage-2-a2a-transport.md. Sol's call.
Status
| Design | written — 00-scope/, 01-research/, 02-architecture/ |
| Implementation plan | 06-implementation/PLAN.md — 8 stages, owners assigned |
| Code | not started. find . -name '*.py' returns 0 |
| Blocking decisions | the five in 03-decisions/OPEN-DECISIONS.md, plus Stage 5's owner |
No probe has run. A stage is done when its proof runs — not when the code is written, and not when a test is green.
How to read this folder
| Folder | What it settles |
|---|---|
06-implementation/ | THE PLAN OF RECORD, and one file per stage with its references. Start at PLAN.md; then README.md maps the stages; then the stage file you own |
00-scope/ | What V3 is, what it is not, and what we learned from Hermes (LEARNED-AND-PLAN.md) |
01-research/ | What V2, legacy SolOS, Moyai, LiteAgents and Hermes taught, as rules |
02-architecture/ | The design. DESIGN-OF-RECORD.md, fleet-dashboard-design-of-record-2026-10-20.md (the fleet dashboard — one consolidated design + implementation plan, superseding Tam's dashboard plan/page-design and Sol's annex), and what-else-to-look-into.md for the gap analysis |
03-decisions/ | Open questions for Young, his rulings once made, and the disagreement register |
04-structure-snapshot/ | The .solos/ tree as it stands, plus Sol's structure review |
05-archive/ | Superseded documents — evidence, not litter. Each with a pointer to what replaced it |
Inside 06-implementation/
| File | What it is |
|---|---|
PLAN.md | the plan of record — §0 is the stage register |
README.md | the stage→file→reference map, and what each stage checks against Hermes |
stage-0-root-and-prover.md … stage-7-executor.md | one file per stage: steps, references, proof, what it must NOT do, open items |
sol-transport-and-execution.md | Sol's lane annex (stages 2, 3, 7) |
mira-lane-annex.md | Mira's lane annex (stages 4, 6) |
Each stage file names the Hermes file and line it is checked against — and where Hermes has no equivalent, it says so, because "no reference" means we build it and it is ours alone.
The plan, in one table
8 stages, 3 arcs. Full detail and exit proofs in
06-implementation/PLAN.md.
| Stage | Owner | Deliverable | Exit proof |
|---|---|---|---|
| 0 — root + the prover | Min · Sol | a root that cannot be guessed; a probe harness | the detector catches an unwired control |
| 1 — the registry | Min | one source for every shared fact | a2a_call to each of 11 agents returns that agent's identity |
| 2 — A2A transport | Sol | the spec-conformant spine | Inspector passes 8/8 |
| 3 — the task contract | Min · Sol | states + wire mapping + the stuck rule | a stopped task is a state, and it names the cause |
| 4 — skills + tools | Min · Sol | one store, loaded on demand | a search adds no instruction text; a load does |
| 5 — memory | 🔴 needs a ruling | what an agent remembers | a turn that forgets to save is still captured |
| 6 — cost + retention | Mira | the ledger; retention as an enforced input | four probes report four different things |
| 7 — the executor | Sol | HarnessDefinition, run-scoped credentials | the executor's environment holds no provider key |
Stages 4, 5 and 6 are independent and can run in parallel across lanes.
Authors and the disagreement policy
V3 is written by Min (coordination: registry, identity, task contract), Sol (engineering: transport, executor, conformance) and Mira (business and finance: cost, providers, the skills/tools store).
Where we disagree, the disagreement is recorded, not smoothed. See
03-decisions/sol-conflicts-and-corrections.md and
03-decisions/sol-corrections-and-lane-division.md. Two authors quietly merging
their views is how five roster sources happened.
The three rules V3 is built on
Every significant defect in V2 and legacy SolOS was one of these, or a symptom of one. They are the reason V3 exists as a separate design rather than a V2 patch.
1. One fact, one home. Any fact restated in two places will drift. In V2 the roster lived in five places, and the A2A peers in Hermes's own config pointed at all eight wrong ports — three of them forming a rotation that returned a successful response from the wrong agent.
2. The protocol is not ours to invent. A2A is an open spec with a reference SDK and a conformance tool. V2 hand-rolled it and produced a state vocabulary where 3 of 9 values were not spec values — the kind of defect a conformant client mis-handles silently rather than rejecting.
3. Absence must be loud. A wrong port that returns a 200 from the wrong agent is worse than a connection refused. Prefer the failure that cannot be mistaken for success.
Standing rules inherited from V2
These were Young's rulings and they carry forward unchanged:
| Rule | Source |
|---|---|
| An agent may never verify its own work | separation of duties |
| One owner per task | Young, 2026-10-01 |
| Brain plans and coordinates; Heart executes | Young, 2026-10-04 |
| Min does not code — coordinates and plans | Young, 2026-10-04 |
| Every task registered in the Central Registry | Young |
| A completion claim becomes completion only after independent verification | design |
| Retry: 2 per approach, 4 total, then hold | Young |
| English only, every agent and model | Young |
| Thinking mode off | Young |
| Automation may never silently override an operator's decision | design |
The fleet — three units
V3 is the Heart Unit's system. The other two run on Hermes.
| # | Unit | Runs on | Host | Agents | Ports |
|---|---|---|---|---|---|
| 1 | Pulse | Hermes | Pulse host | Eva · Eve · Tam | 8441-8443 |
| 2 | Brain | Hermes | LAB | Min · Mira · Sol | 8311-8313 |
| 3 | Heart | SolOSV3 ← this | LAB | Ace · Alpha · Atlas · Echo · Nova | 8301-8305 |
All agents communicate via A2A. The tool is the Opencode CLI — the Arms.
The organisation was not what was wrong. The implementation was.
11 agents, 3 planes. Ports are assigned, not discovered.
We are focused on the Heart Unit. Full statement:
00-scope/three-units.md.
Not in this folder
- V2's design and its defects —
SolOSV2/. Reference and evidence. - Legacy SolOS — decommissioned history.
- Pulse —
Pulse/. Tam's folder is hers; it is input, not a place to consolidate. - Brain's own runtime — Hermes, on LAB. Not V3's to build. A Brain agent inside V3 is a category error.