mosaicstack/stack
6
0
Fork 1
Code Issues 297 Pull Requests 19 Actions Packages Projects Releases 15 Wiki Activity

mosaic-brain: git-tracked ~/.mosaic user-config storage with clobber-free agent sync (skill+wrapper, hook-enforced) #1290

New Issue
Open
opened 2026-08-17 20:42:29 +00:00 by Ghost · 0 comments
Ghost commented 2026-08-17 20:42:29 +00:00
Copy Link
Copy Source

Summary

mosaic-brain: the user-config storage for Mosaic Stack — ~/.mosaic/ as a git-tracked repo. Replaces jarvis-brain (P0 legacy; its data migration is a separate epic, out of scope here).

Two requirements from the operator:

  1. Git-tracked. Local git is the MINIMUM (works with no git service available). Remote sync via the user's git service is a desired function when present.
  2. Mechanical clobber-free sync. Multiple fleet agents share one ~/.mosaic on a host, and multiple hosts may share one remote. Prose discipline ("re-read before edit") is not sufficient — per the Constitution's "Hooks are the gate", this needs a mechanical path.

Repo topology

  • ~/.mosaic/ IS the working tree (git init at first install by the mosaic installer; not a clone elsewhere).
  • Local-only default: git init + local commits on main. Optional origin added when the user configures a git service; installer/mosaic doctor should detect and wire it.
  • Seeded .gitignore (mandatory, secret-safety):
    • auth/ (harness tokens: pi/claude)
    • fleet/agents/*.env.generated, fleet/agents/*.env (per-agent credentials, mode 600)
    • config/, plugins/, skills/ (runtime state; plugins is 6.9M of binaries)
    • state/, gateway/, wake/, credentials*, secrets/ if/when relocated here (see #1288 item 5)
  • Extends #1288: after seeding the tree (installer item 1), the installer runs git init + first commit.

Clobber-free sync mechanics

Two distinct collision domains:

A. Intra-host (agents share one working tree):

  • Commit-per-logical-change (already a Constitution rule) makes each agent edit an atomic, attributable unit.
  • Shared registry files (TOOLS.md index rows, fleet roster) mutated ONLY through the agent mutation tool below — never raw file writes. Enforcement extends the #1289 hook pattern: deny direct write/edit tool calls to designated shared files; allow the wrapper.
  • Per-file advisory locks (flock) inside the wrapper serialize concurrent edits on one host.
  • Session Lifecycle Contract hook: session-end script auto-commits any stragglers with agent-attributed message (agent=<name> scope=<files>).

B. Cross-host (remote sync):

  • Pull --rebase before push; never force-push (trunk rules already apply).
  • Conflicts are NEVER auto-resolved (existing multi-agent safety rule) — the sync tool halts, reports the conflicted files, and surfaces to the operator as a blocked state.
  • Sync points: launcher session start (pull before context load if remote configured) and session end (commit + push).

Agent mutation tool ("tools tool")

Decision point raised by the operator: local MCP server vs skill?

Recommendation: skill + thin shell wrapper first; MCP later only if needed.

  • The wrapper (e.g., mosaic-brain edit <file> --op add-row|set|...) is the mechanical core: acquire flock → re-read → apply STRUCTURED edit (row/section ops, never whole-file rewrite) → validate → atomic commit → release.
  • A skill teaches every harness to use it — same pattern as the existing mosaic-tools skill + tools/git/*.sh wrappers. Zero server process, zero per-harness MCP config, works on local-git-only installs.
  • MCP adds value only for harness-native tool integration; it does not add enforcement (hooks do, per #1289) and adds an always-on server dependency. Revisit after the skill path proves out.
  • Wrapper lives in ~/.config/mosaic/tools/brain/ (framework-shipped, tested) — agent-developed extensions still go to ~/.mosaic/tools/ per #1288 comment 22995.

Cross-refs

  • #1288 — seed set gains git-init step + .gitignore; sync points hook into launcher contract (G3)
  • #1289 — hook-deny pattern extended to shared-file direct writes
  • jarvis-brain → mosaic-brain data migration: separate epic, not scoped here

Out of scope

  • Hosting a git service for users without one (local-git minimum covers that)
  • jarvis-brain content migration
  • OpenBrain relationship (semantic memory vs. file-based config storage — orthogonal layers)
## Summary **mosaic-brain**: the user-config storage for Mosaic Stack — `~/.mosaic/` as a git-tracked repo. Replaces jarvis-brain (P0 legacy; its data migration is a separate epic, out of scope here). Two requirements from the operator: 1. **Git-tracked.** Local git is the MINIMUM (works with no git service available). Remote sync via the user's git service is a desired function when present. 2. **Mechanical clobber-free sync.** Multiple fleet agents share one `~/.mosaic` on a host, and multiple hosts may share one remote. Prose discipline ("re-read before edit") is not sufficient — per the Constitution's "Hooks are the gate", this needs a mechanical path. ## Repo topology - `~/.mosaic/` IS the working tree (git init at first install by the mosaic installer; not a clone elsewhere). - Local-only default: `git init` + local commits on `main`. Optional `origin` added when the user configures a git service; installer/`mosaic doctor` should detect and wire it. - **Seeded `.gitignore` (mandatory, secret-safety):** - `auth/` (harness tokens: pi/claude) - `fleet/agents/*.env.generated`, `fleet/agents/*.env` (per-agent credentials, mode 600) - `config/`, `plugins/`, `skills/` (runtime state; plugins is 6.9M of binaries) - `state/`, `gateway/`, `wake/`, `credentials*`, `secrets/` if/when relocated here (see #1288 item 5) - Extends #1288: after seeding the tree (installer item 1), the installer runs git init + first commit. ## Clobber-free sync mechanics Two distinct collision domains: **A. Intra-host (agents share one working tree):** - Commit-per-logical-change (already a Constitution rule) makes each agent edit an atomic, attributable unit. - Shared registry files (TOOLS.md index rows, fleet roster) mutated ONLY through the agent mutation tool below — never raw file writes. Enforcement extends the #1289 hook pattern: deny direct write/edit tool calls to designated shared files; allow the wrapper. - Per-file advisory locks (flock) inside the wrapper serialize concurrent edits on one host. - Session Lifecycle Contract hook: `session-end` script auto-commits any stragglers with agent-attributed message (`agent=<name> scope=<files>`). **B. Cross-host (remote sync):** - Pull `--rebase` before push; never force-push (trunk rules already apply). - Conflicts are NEVER auto-resolved (existing multi-agent safety rule) — the sync tool halts, reports the conflicted files, and surfaces to the operator as a blocked state. - Sync points: launcher session start (pull before context load if remote configured) and session end (commit + push). ## Agent mutation tool ("tools tool") Decision point raised by the operator: local MCP server vs skill? **Recommendation: skill + thin shell wrapper first; MCP later only if needed.** - The wrapper (e.g., `mosaic-brain edit <file> --op add-row|set|...`) is the mechanical core: acquire flock → re-read → apply STRUCTURED edit (row/section ops, never whole-file rewrite) → validate → atomic commit → release. - A skill teaches every harness to use it — same pattern as the existing `mosaic-tools` skill + `tools/git/*.sh` wrappers. Zero server process, zero per-harness MCP config, works on local-git-only installs. - MCP adds value only for harness-native tool integration; it does not add enforcement (hooks do, per #1289) and adds an always-on server dependency. Revisit after the skill path proves out. - Wrapper lives in `~/.config/mosaic/tools/brain/` (framework-shipped, tested) — agent-developed extensions still go to `~/.mosaic/tools/` per #1288 comment 22995. ## Cross-refs - #1288 — seed set gains git-init step + `.gitignore`; sync points hook into launcher contract (G3) - #1289 — hook-deny pattern extended to shared-file direct writes - jarvis-brain → mosaic-brain data migration: separate epic, not scoped here ## Out of scope - Hosting a git service for users without one (local-git minimum covers that) - jarvis-brain content migration - OpenBrain relationship (semantic memory vs. file-based config storage — orthogonal layers)
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
fargo fred happy jason.woltje (Jason Woltje) 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) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 sanity scooby (Scooby) scrappy shaggy tiny velma vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1290