mosaicstack/stack
25
0
Fork 1
Code Issues 344 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

mosaic-brain: codify per-estate agent working memory (~/.mosaic) into the installer #1051

New Issue
Open
opened 2026-08-05 15:48:42 +00:00 by Ghost · 0 comments
Ghost commented 2026-08-05 15:48:42 +00:00
Copy Link
Copy Source

Summary

Agent working memory currently lives as plain files in no repository. Provisioned by hand once to prove the shape; this issue is to codify it into the installer.

mosaic-brain is a private git repo — one per estate — cloned to ~/.mosaic, holding the dynamic content agents accumulate while working. Config stays in ~/.config/mosaic; the two have different lifecycles and different blast radius when wrong.

agents/<seat>/   per-seat state (does NOT survive its seat)
lanes/<lane>/    lane-durable content (survives every seat in the lane)
board/           orchestration board
specs/           specifications a lane is chartered against
methods/         reusable technique extracted from work

The failure this fixes

A lane's continuity artifact — the accumulated operating doctrine of an entire mission — sat unbacked on a filesystem at 96% capacity. It survived seat rotation and would have survived nothing else.

The seats could not fix it themselves. The only substrate available belonged to a different estate, where those seats correctly hold no standing — the boundary working exactly as designed while a real artifact sat unprotected behind it.

Two alternatives were rejected on evidence:

  • Cross-estate grant — authorises the crossing rather than removing it; granted once, inherited forever by seats nobody re-examines.
  • Route all writes through a privileged agent — solves writes and not verification. A seat that must CONFIRM a spec it cannot read can only take it on trust or ask a third party, which destroys independent derivation, and it makes one agent a throughput bottleneck.

A per-estate brain removes the crossing instead of authorising it, and restores verification to the lane that has to do the verifying.

Requirements for the installer

R1 — Provision the brain. Ensure a per-estate mosaic-brain exists; clone to ~/.mosaic. If it exists, clone — do not re-create.

R2 — Derive the estate; never assume it. The brain belongs to the estate of the git host being used, not the host the installer runs on. Hosts straddle — a machine can sit in one estate and push to another. Estate is a property of the target.

R3 — Grant through the credential broker, not a hand-run script. Verify the resulting permission by reading it back with the seat's own credential, not the admin's.

R4 — Assert a postcondition, not "the clone ran". ~/.mosaic exists, is a git repo, has the expected remote, is on main, and the running identity can read AND write it — proven by round-trip, not exit code.

R5 — Negative control in the install test. A seat outside the estate must be REFUSED. An access check that only tests the allowed case cannot fail.

R6 — Never write secrets. Ship the .gitignore (*.token *.key *.pem .env credentials.json). The broker holds credentials; the brain never does.

R7 — Migration, not just creation. Detect pre-existing local-disk state and move it in or report it. A brain that starts empty beside an unbacked directory has not solved the problem it exists to solve.

R8 — doctor must check it. Missing clone, wrong remote, no write access, or an uncommitted local state directory are defects to surface; doctor --fix should repair the first three.

Open questions for the implementer

  • Discovery — how does a host know which brain is its estate's? Config value, or derived from the configured git host?
  • Multi-host sync — several hosts may share an estate's brain. Push cadence, conflict policy (append-only ledger vs last-writer-wins), and whether seats push directly or via a lane lead.
  • Retention — lane directories accumulate. Archive rather than delete, and the rule needs an owner. Reaping by age or size is known-unsafe: the biggest directories are the busiest seats.
  • Phase ordering — the brain needs a credential to clone, and credentials come from the broker, so brain-provisioning must sit after credential provisioning in the phase model.

Relationship to other work

Depends on the credential broker (#1045) for R3 — the grant path is mosaic cred, not a script. Related: #1043 (identity never reaching the agent), #1049 (estate boundary enforced only by host-string matching).

Reference implementation and full write-up live in the bootstrapped repo at docs/ADOPTION.md.

## Summary Agent working memory currently lives as **plain files in no repository**. Provisioned by hand once to prove the shape; **this issue is to codify it into the installer.** `mosaic-brain` is a private git repo — **one per estate** — cloned to **`~/.mosaic`**, holding the dynamic content agents accumulate while working. Config stays in `~/.config/mosaic`; the two have different lifecycles and different blast radius when wrong. ``` agents/<seat>/ per-seat state (does NOT survive its seat) lanes/<lane>/ lane-durable content (survives every seat in the lane) board/ orchestration board specs/ specifications a lane is chartered against methods/ reusable technique extracted from work ``` ## The failure this fixes A lane's continuity artifact — the accumulated operating doctrine of an entire mission — sat **unbacked on a filesystem at 96% capacity**. It survived seat rotation and would have survived nothing else. **The seats could not fix it themselves.** The only substrate available belonged to a **different estate**, where those seats correctly hold no standing — the boundary working exactly as designed while a real artifact sat unprotected behind it. Two alternatives were rejected on evidence: - **Cross-estate grant** — authorises the crossing rather than removing it; granted once, inherited forever by seats nobody re-examines. - **Route all writes through a privileged agent** — solves *writes* and **not verification**. A seat that must CONFIRM a spec it cannot read can only take it on trust or ask a third party, which destroys independent derivation, and it makes one agent a throughput bottleneck. **A per-estate brain removes the crossing instead of authorising it, and restores verification to the lane that has to do the verifying.** ## Requirements for the installer **R1 — Provision the brain.** Ensure a per-estate `mosaic-brain` exists; clone to `~/.mosaic`. If it exists, clone — do not re-create. **R2 — Derive the estate; never assume it.** The brain belongs to the estate of the **git host being used**, not the host the installer runs on. **Hosts straddle** — a machine can sit in one estate and push to another. Estate is a property of the *target*. **R3 — Grant through the credential broker,** not a hand-run script. **Verify the resulting permission by reading it back with the seat's own credential**, not the admin's. **R4 — Assert a postcondition, not "the clone ran".** `~/.mosaic` exists, is a git repo, has the expected remote, is on `main`, and **the running identity can read AND write it** — proven by round-trip, not exit code. **R5 — Negative control in the install test.** A seat outside the estate must be REFUSED. An access check that only tests the allowed case cannot fail. **R6 — Never write secrets.** Ship the `.gitignore` (`*.token *.key *.pem .env credentials.json`). The broker holds credentials; the brain never does. **R7 — Migration, not just creation.** Detect pre-existing local-disk state and move it in or report it. **A brain that starts empty beside an unbacked directory has not solved the problem it exists to solve.** **R8 — `doctor` must check it.** Missing clone, wrong remote, no write access, or an uncommitted local state directory are defects to surface; `doctor --fix` should repair the first three. ## Open questions for the implementer - **Discovery** — how does a host know which brain is its estate's? Config value, or derived from the configured git host? - **Multi-host sync** — several hosts may share an estate's brain. Push cadence, conflict policy (append-only ledger vs last-writer-wins), and whether seats push directly or via a lane lead. - **Retention** — lane directories accumulate. Archive rather than delete, and the rule needs an owner. **Reaping by age or size is known-unsafe: the biggest directories are the busiest seats.** - **Phase ordering** — the brain needs a credential to clone, and credentials come from the broker, so brain-provisioning must sit **after** credential provisioning in the phase model. ## Relationship to other work Depends on the credential broker (**#1045**) for R3 — the grant path is `mosaic cred`, not a script. Related: **#1043** (identity never reaching the agent), **#1049** (estate boundary enforced only by host-string matching). Reference implementation and full write-up live in the bootstrapped repo at `docs/ADOPTION.md`.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-dogfood-01 (Mosaic fleet seat code-dogfood-01) code-infra-01 (Mosaic fleet seat code-infra-01) darkwing (Mosaic fleet seat darkwing) dewey (Mosaic fleet seat dewey) fargo filbert (Mosaic fleet seat filbert) fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) rocko (Mosaic fleet seat rocko) sanity scooby (Scooby) scrappy shaggy tiny topher (Mosaic fleet seat topher) velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1051