mosaicstack/stack
6
0
Fork 1
Code Issues 298 Pull Requests 18 Actions Packages Projects Releases 15 Wiki Activity
Files
d6434fc941684ea1fa27047882ea18369e68fa31
stack/scratchpads/2026-08-17-fleet-identity-comms-mosaic-tree.md
T
jarvis d6434fc941
ci/woodpecker/pr/ci Pipeline was successful
Details
scratchpads: 2026-08-17 fleet identity/comms/mosaic-tree continuation record 
Anchors the sb-it-1-dt session's outputs in this repo so continuation
does not depend on jarvis-brain (P0, not retained): ~/.mosaic tree model
as-built (incl. fleet/agents store + *.env.generated overlays), decisions
register (MOSAIC-D-001/-02 pending ruling, tooling-migration direction,
watcher-provisioning-at-instantiation), #1295 pointers, sequenced open
work queue, and rules for tonight's homelab agents (lane next, #1280
attribution, evidence-file protection).
2026-08-17 17:08:27 -05:00

10 KiB
Raw Blame History

2026-08-17 — Fleet identity, comms delivery, and the ~/.mosaic tree (continuation record)

Status: active continuation record | Owner: Jason (rulings) / fleet (delivery) | Created: 2026-08-17, sb-it-1-dt session with Jarvis (jarvis-brain) Audience: the homelab agents continuing this effort tonight. Read this whole file before acting; it supersedes nothing but preserves structure and decisions that must not be lost.

Why this exists

A session on sb-it-1-dt (2026-08-17) produced three architecture decisions (two awaiting Jason's ruling), one incident postmortem (#1295), interim guardrail edits in the user-owned ~/.mosaic/ contract tree, and one new tool (ensure-watcher.sh). The work spans jarvis-brain (P0, not retained) and this repo (the product). This file is the stack-side anchor so continuation does not depend on jarvis-brain surviving.

1. The ~/.mosaic tree model — as-built, preserve this structure

Three-tree split (this is design intent, not accident; keep it through all framework work):

Tree Owner Rule
~/.config/mosaic/ framework upgrade-managed templates; NEVER user-edited; mosaic upgrade may overwrite
~/.mosaic/ user working contracts, guides, fleet agents; upgrades reconcile with deny-wins (user edits never overwritten)
repo satellites repos bootstrapped per-repo .mosaic/ state

As-built inventory of ~/.mosaic on sb-it-1-dt (2026-08-17):

  • Contract core: CONSTITUTION.md (L0 law), AGENTS.md (dispatcher + guide router + Fleet Comms Watcher requirement), SOUL.md (generic base for ALL fleet agents, zero persona — includes the new Fleet Boundaries section), STANDARDS.md (universal standards — includes new session identity + comms watcher hygiene sections), SYSTEM.md (pure communication contract, byte-identical to jarvis-brain's prompt-testing sr_opus_5_system_prompt.md), USER.md, TOOLS.md.
  • guides/ — user-owned working copies (E2E-DELIVERY, ORCHESTRATOR(+PROTOCOL,+LEARNINGS), WAKE-DOCTRINE, VAULT-SECRETS, etc.).
  • fleet/agents/ — the per-agent store (this is MOSAIC-D-002's substrate, already in use):
    • real agent dirs: fargo/, orchestrator/, probe/, vision/, weekly-update/ — shape: profile.json (harness/account/overlay pointer) + overlay.json + SOUL.md (persona) + scratch/ work/ notes/ subdirs (hygiene rules in root SOUL.md)
    • *.env.generated launch overlays: luna sol terra (carry MOSAIC_AGENT_NAME, _CLASS, _RUNTIME, _MODEL, _REASONING, _TOOL_POLICY) — these are the mosaic-fleet seat launch envs; inbox.env, itops.env also present
    • probe/ is the validated layout proof: auth-bundle symlink chain, per-agent sessions, plugin-store symlink (from 2026-08-07)
  • auth/, config/, memory/, plugins/, skills/, skills-local/ — per-tree copies/links for runtime isolation.
  • Related but outside the tree: watcher units at ~/.config/systemd/user/<agent>-comms-watcher.service; watcher seen-state at ~/.local/state/comms-watcher-<agent>/.

2. Decisions register (2026-08-17 session)

Full strict records live in jarvis-brain docs/decisions/mosaic-stack/ (render on its dashboard); both are Pending Jason's ruling. Summaries so the content survives P0:

  • MOSAIC-D-001 — SYSTEM.md as canonical harness system prompt. Static core (Constitution+AGENTS+USER+overlays) in one tracked file; launcher renders dynamic tail (mission/PRD/fleet/persona). Delivery: --append-system-prompt (repeatable) for pi/claude; symlinked core file for codex ($CODEX_HOME/instructions.md) and opencode (AGENTS.md); their dynamic tail via initial prompt (needs live verification). Static-first order is the cache win. SYSTEM.md in ~/.mosaic today is the communication-contract file — D-001's SYSTEM.md is the broader composition; naming to reconcile at implementation.
  • MOSAIC-D-002 — per-agent harness homes + mechanical profiles. Launch with targeted config-dir env vars (e.g. PI_CODING_AGENT_DIR=~/.mosaic/fleet/agents/<name>/pi), NOT literal HOME. SOUL.md identity mechanically generated from roster (single writer; kills the hand-copy drift measured in agents/vision/SOUL.md on jarvis-brain: declared Jarvis, answered Vision). Composes: SYSTEM core → per-agent SOUL → dynamic tail. MOSAIC_AGENT_NAME stays load-bearing for comms.
  • Comms delivery tooling belongs in the STACK framework, not jarvis-brain (decided in discussion; supersedes the interim placement). jarvis-brain keeps only the transport data (comms/ tree) while it lives. Agents launch from their own repos (terra from ~/src/stack etc.) — delivery is transport-repo-relative, so this works; but every installed watcher unit's ExecStart currently points into ~/src/jarvis-brain/scripts/ — that dependency is the P0 trap to remove. Migration = move tools + regenerate units, in one step.
  • Watcher provisioning is instantiation duty, never running-agent duty. Interim landed as jarvis-brain scripts/comms/ensure-watcher.sh (idempotent ensure + --status boot check + interim identity warnings: missing target session, pane MOSAIC_AGENT_NAME mismatch via /proc/<child>/environ, bare-runtime NOTE). Framework move: fold into mosaic agent --new + fleet launch + mosaic doctor drift check.
  • Prose guardrails landed (interim fences until mechanical fixes): ~/.mosaic/SOUL.md Fleet Boundaries (wrong-session tripwire; comms ownership; cross-agent investigation requires tasking) · STANDARDS.md session identity + watcher hygiene · AGENTS.md Fleet Comms Watcher requirement (P0-interim script path marked transitional).

3. Incident → #1295 (already tracked here)

https://git.mosaicstack.dev/mosaicstack/stack/issues/1295 — docs-seat incident: cwd-keyed session files served three lives (dev chat → goals seat → 22 watcher injections into a wedged process); name-based watcher delivery with no identity verification; wedge after pi 0.84.1→0.84.2 update passes every liveness instrument. Proposed fixes enumerated there; provisioning follow-up in comment ID 23027.

4. Open work queue (suggested sequence)

  1. Comms tooling migration PR (lane next): move comms-watcher.sh, install-watcher.sh, ensure-watcher.sh into the framework tree → deploy ~/.config/mosaic/tools/comms/; regenerate existing units' ExecStart to framework paths (one-command sweep); keep COMMS_WATCH_REPO per-host config (points at a brain checkout until the queue transport lands). Reference: jarvis-brain commit 701c353b1.
  2. Ensure-on-instantiation: mosaic agent --new / fleet launch call ensure semantics; mosaic doctor gains the drift check (--status --all semantics + fred's hand-written unit as the known drift case; also note daphne/docs/happy/pepper/sanity/tiny/fargo currently have no watcher — cover or consciously exempt).
  3. MOSAIC-D-002 implementation (after ruling): per-agent homes via targeted env vars; roster-generated SOUL.md single-writer; extend the existing *.env.generated pattern; launch ledger keeps config_home audit.
  4. MOSAIC-D-001 implementation (after ruling): SYSTEM.md sourcing + per-harness delivery + compose-contract becomes render-core+tail with drift check; bench cache-ordering before/after (jarvis-brain domains/software-dev/mosaic-stack/prompt-testing has the bench).
  5. Queue transport + forced separation (longer term): supersedes watcher path; identity-verification and wedge-detection remain valid regardless of transport.
  6. Docs inheritance: jarvis-brain AGENTS.md's durable comms guidance (E7 pi-glyph delivery gotchas, capture-pane rules, comms protocol) must be inherited into stack docs before P0 retirement.

5. Rules for tonight's agents

  • Lane: next only; nothing to main without Jason (standing ruling).
  • Attribution caveat #1280: Gitea/git identity from this host may misattribute (issue #1295 showed as created by @mos-dt-0); prefer per-invocation git -c user.name=<seat> and verify what the remote recorded.
  • Do not delete sb-it-1-dt:docs] (untracked file at repo root) — it is cited fleet-wide as incident evidence.
  • Edit user contracts in ~/.mosaic/, never the templates in ~/.config/mosaic/.
  • Do not restart other fleet seats unilaterally (goals/scrappy/sanity restart decisions are fred's/Jason's per the docs-seat report).

6. Artifact map

Artifact Where
Decision records D-001/D-002 (strict, pending ruling) jarvis-brain docs/decisions/mosaic-stack/2026-08-17_mosaic-d-00{1,2}_*.md
Incident issue + provisioning comment stack #1295 + comment 23027
ensure-watcher.sh (reference implementation) jarvis-brain scripts/comms/ensure-watcher.sh (commit 701c353b1)
Bench for prompt A/B (pi, thinking levels, footer-token semantics) jarvis-brain domains/software-dev/mosaic-stack/prompt-testing/ + docs/reports/2026-08-17-prompt-testing-glm-bench.md
Launcher inspection basis @mosaicstack/mosaic 0.0.49 dist/commands/launch.js (composeContract / ensureRuntimeConfig / harness-home isolation)
Guardrail edits ~/.mosaic/{SOUL,AGENTS,STANDARDS}.md on sb-it-1-dt (2026-08-17 16:53–17:04)
Reference in New Issue View Git Blame Copy Permalink