Two commands, and the seam between them is the point. `mosaic store` admits a
reviewed directory into ~/.mosaic/{plugins,skills} and entitles nobody.
`mosaic fleet plugin enable` writes one entry into one seat's profile.json and
copies nothing. A plugin reaching a seat therefore takes two deliberate acts,
and neither happens as a side effect of the other -- the same split adoption.ts
already documents.
Entries are `<name>@<version>` as one path segment, and admission has no flag to
skip the version. HARNESS-HOMES triage #8 specified `store/<name>/<version>`
with symlink pinning; that layout is unreachable from a profile as launch is
built today. `resolveManagedLinks` in fleet-launch-command.ts resolves a profile
entry as a single path segment and refuses a symlink there, and its STORE_ENTRY
charset admits `@` while rejecting `/`. Proven against the built CLI, not
assumed: a dry-run launch of a seat with [email protected] enabled plans
.../agents/smoke/.claude/plugins/[email protected] -> .../.mosaic/plugins/[email protected]
This discrepancy is reported to the design owner rather than settled here.
Admission is `--as <name>@<version>`, not `--name` + `--version`. The first cut
used `--version` and a unit test could not see the problem: Commander's own
--version is on the program, so `mosaic store add … --version 1.2.0` printed the
CLI version and admitted nothing. Only an end-to-end run of the built binary
caught it. The regression test now registers under a program that sets a
version, which is the shape that fails.
`--live` is refused rather than accepted-and-ignored. An operator who asks for a
live change and gets a success message would reasonably believe the seat changed.
Not addressed here: launch composes `enabledPlugins` from the settings layers
only, never from profile.plugins, so an entitled plugin is linked into the seat
but not listed there. Reported separately.
Tests: 48 new (16 store module, 11 store command, 21 fleet plugin). Suite 1753
passed / 4 failed, the 4 being the mutator-gate acceptance failures already red
on origin/main. Root build 25/25.
The two streams collided without conflicting. main added a 'Pi persistent
goals' section pointing at docs/guides/{user,admin}-guide.md; next's #1210
restructure had already moved both files to docs/_old_structure/guides/.
Git merged the addition cleanly because neither side touched the other's
lines, so the break only surfaced in fleet-documentation.spec.ts.
dev-guide.md stayed at docs/guides/ and needed no change. Anchors verified
present at the new paths.
next carries 108 commits main lacks; main carries 23 next lacks, including
the MOSAIC_GIT_IDENTITY work that per-agent git credentials depend on.
Neither stream alone can ship 0.0.50: next drops identity, main drops
everything since the split.
Conflicts and how they were settled:
- packages/mosaic/package.json test:framework-shell -- union. Neither side
removed an entry; next added 6, main added 8, one shared. 50 total.
- framework/tools/git/pr-merge.sh -- next's form. It permits base 'main' or
'next'; main's permits 'main' only, and the release line targets next.
- framework/tools/git/test-ci-queue-wait-tristate.sh -- both sides appended
to the same region (next: merge-readiness assertions; main: a real-clock
watchdog control). Kept both.
- docs/SITEMAP.md -- both sides appended distinct sections. Kept both.
Launch will not delete a real directory sitting where it expects a managed
link -- an auth/<harness>/primary that someone logged into by hand, or a
plugin directory a seat acquired before the central store existed. That
refusal is right and it is also a dead end: the operator gets a composition
error and no way forward.
`mosaic fleet adopt` is the way forward. Bare, it lists every such directory
and the command that resolves it. With a verb, it moves one where it belongs.
Nothing here deletes. A promotion is a rename; an occupied destination is a
refusal, not a merge; a cross-device rename is reported rather than retried as
copy-then-delete, because a copy-then-delete is a delete.
Store adoption stops at the move and does not install the link. The seat's
.mosaic-managed-links.json belongs to launch, and a link written behind it
fails the next composition as an unrecorded symlink -- one refusal traded for
another. The next launch installs and records it when the profile lists the
entry; whether a seat gets a plugin stays `mosaic fleet plugin`'s decision.
W-F3 of docs/plans/2026-08-14_fleet-seats-on-web1.md.
`mosaic auth enroll | assign | list | default` (W-F5). Until now a host had one
account per harness, so an author seat and a reviewer seat were the same
principal wearing two names, and a review carried out under that arrangement is
self-review. Bundles under ~/.mosaic/auth/<harness>/<bundle>/ are what a seat's
profile.json points at, so two seats on one host can hold genuinely different
accounts.
Enroll does not reimplement any harness's login. It creates the bundle
directory owner-only, points the harness's own home at it by environment, runs
the harness, and then checks what landed: credential present, permissions
tightened, and the account recorded. Claude is reached through
CLAUDE_SECURESTORAGE_CONFIG_DIR rather than a symlink because it writes by
rename(2), which replaces a symlink instead of following it. --no-login prints
the environment for an operator who would rather run the login themselves.
The check worth naming is identity: enroll reads the account back out of what
the harness wrote and refuses quietly to accept a bundle named for one account
that holds another. That mistake is otherwise silent -- an operator enrolling
the reviewer bundle logs in out of habit as the author, both seats collapse to
one principal, and nothing else in the system notices.
Assign re-parses a seat's profile before rewriting its bundle, so an already
broken profile is reported here rather than re-serialized into something that
looks repaired and still fails at launch. An unenrolled bundle is assigned but
said out loud, because the seat will refuse to launch until the account exists.
registerAuthCommand now returns its Command so these local verbs can hang off
it. They never talk to the gateway and work on a host where it is down.
41 tests. Each of the load-bearing checks was mutation-tested: nine mutations,
each killing exactly the one test that covers it.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1
Found by rehearsing the full install on a greenfield Debian 13 VM
(mosaic-sbx-dev) rather than on a host that already had a working Mosaic
tree. Each one is invisible on a developer machine and fatal on a new host.
1. Required system settings layer. The framework ships runtime/<harness>/
for claude, codex, opencode and pi but a settings.json only for claude,
so requiring the file made every pi, codex and opencode seat refuse to
compose. The system layer is now optional; what must exist is the
harness runtime directory, which is the thing that actually proves the
framework is installed and carries that harness.
2. Required mcpServers in canonical Claude settings. The shipped
settings.json has no such key, so `fleet agent new` refused to scaffold
any Claude seat. Absent now means the same as empty. A present but
wrong-typed value is still an error.
3. Never-enrolled hosts were told their auth directory "must be a real,
non-symlink directory", which reads as a tampering report when the real
situation is that nobody has logged in yet. Absent and wrong-shaped are
now separate messages, and the absent one names `mosaic auth enroll`.
4. A fleet seat whose host had no system SOUL.md reached checkSoul(),
which spawns the interactive `mosaic wizard` with inherited stdio. On a
detached tmux seat that parks the pane on a menu with nobody at it: the
session is live, the systemd unit reports fine, and no agent ever
starts. A seat's identity is its own SOUL.md, written by `fleet agent
new`, so the fleet path checks that and fails loudly instead.
Each fix has a regression test verified red against the unfixed source.
The launch.spec.ts seat fixtures gained a SOUL.md they always should have
had -- without it those tests were satisfied by whatever SOUL.md the
developer's real ~/.config/mosaic happened to contain.
Full suite before and after: the same 5 pre-existing failures in
mutator-gate.acceptance.spec.ts and install-ordering-guard.spec.ts,
1585 -> 1591 passing. typecheck and eslint clean.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WYgWocp36goy8hj2ui6ps1
The roster lane and the harness-homes lane did not touch. start-agent-session.sh
ran `mosaic yolo "$RUNTIME"` with HOME set to the operator's home, so every fleet
seat on a host shared the operator's harness home and, for Claude, the operator's
own ~/.claude credentials. Nothing in framework/ called `mosaic fleet launch` at
all, which meant ~/.mosaic was a directory nothing read.
The pane now runs `mosaic fleet launch "$AGENT_NAME"` when a scaffolded seat
exists at $PANE_HOME/.mosaic/fleet/agents/<name>/profile.json, and the historical
command otherwise. Detection uses $PANE_HOME/.mosaic rather than MOSAIC_DATA_HOME
because the pane environment is cleared with env -i; the composition resolves the
same root from HOME, so the two cannot disagree.
Additive by construction: a host with no scaffolded seats launches exactly as
before, so this can land ahead of any seat being enrolled.
- fleet launch gains --dangerous, threaded to launchFleetRuntime. Without it a
seat launched from the roster would drop the permissions footing `mosaic yolo`
gave it and prompt at a pane with nobody at it. The roster launcher asks for it
explicitly so it stays visible in the process table instead of becoming a
profile default.
- A caller's --model replaces the profile's instead of being appended after it.
The roster carries a model per seat and is the surface operators edit; emitting
both flags would leave the choice to each harness's argument parser.
- Claude workdir trust is written into the seat's .claude.json when the pane will
run in a seat home. It previously always went to the operator's ~/.claude.json,
which would leave the seat prompting on its first turn.
Covers Jason's scope amendment for web1: without this seam, "multiple
authentication accounts and agent pegging to auth" cannot be demonstrated on a
roster-managed seat.
Claude Code saves credentials by writing a sibling temp file and rename()-ing
it over the target. rename(2) replaces a symlink rather than following it, so
the managed link W-F1/W-F2 planted at <seat>/.claude/.credentials.json is
destroyed by the first token refresh and the seat silently forks its
credentials. The in-place fallback arm opens with O_NOFOLLOW and would refuse
the link anyway. Evidence, quoting the 2.1.232 binary:
docs/reports/harness/claude-credential-write-path-2026-08-14.md (jarvis-brain).
CLAUDE_SECURESTORAGE_CONFIG_DIR resolves the credential directory
independently of CLAUDE_CONFIG_DIR, so the temp file and the rename both land
inside the bundle. That is the property the design wanted -- share the
credential, never the transcripts -- with no symlink and no privileges.
- new fleet/credential-sharing.ts owns the harness -> credential-file and
harness -> credential-directory-variable maps, so scaffold and launch cannot
disagree about the mechanism. It also removes the duplicate credential-file
name table the two already carried.
- launch composes CLAUDE_SECURESTORAGE_CONFIG_DIR from the resolved bundle
directory and plans no credential link for Claude. The value is always the
absolute bundle path: Claude reads an empty value as ~/.claude, which is the
operator's own account.
- scaffold stops emitting the credential symlink and its manifest entry for
Claude, and tolerates one left by an earlier scaffold rather than reporting
it as a foreign file or rewriting it.
- FIRST_AUTH_REFUSAL still fires when a real file occupies the seat path.
- Harnesses absent from the map (pi, codex, opencode) keep managed links; the
containment specs now exercise them on pi.
Answers promotion gate #1 negatively for the frozen mechanism and positively
for the replacement. E3.3 (two seats refreshing one bundle at once) is still
open.
AMD1213-C: repair stale array consumer, fail closed on foreign link provenance, validate manifests before mutation, and exercise the fleet MCP preflight call path.
The lease-overlay split (a42d5e2e) moved the promotion hooks out of the
base Claude settings template; the wiring test still read the base alone
and failed on the absent UserPromptSubmit event, stopping the whole
test:framework-shell chain. The test now composes base + lease overlay
the way a launched seat does (hook event arrays concatenate, base
first) and asserts the same wiring contract against that view.
Reported-by: goals (clean-head probe on 5e154310)
Claude Code writes installed_plugins.json and other metadata files into
the seat's plugins directory during a session, so refusing every real
entry made composition fail on each seat's second launch. Only a real
directory is an unmanaged entry the pruner would orphan; plain files are
harness state and pass through untouched. Found by the in-box hour-gate
relaunch of the probe seat.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
The installed ~/.config/mosaic home flattens the repo's
packages/mosaic/framework/ prefix: the real file is
<home>/runtime/<harness>/settings.json, exactly as launch.ts already
resolves it everywhere. The fleet launch composition leaked the repo
layout (framework/runtime/...) into the system layer path, so a real
installed home failed with COMPOSITION_FAILED while the temp-fixture
specs (which mirrored the same wrong prefix) stayed green. Found by the
in-box hour-gate dry-run against the installed mos-dev-stage home.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
Integration adjudication (fred, W-F1): the general arrays-replace merge rule
conflicts with the gap-7 base/overlay split — base and lease overlay share
the PreToolUse and Stop events, so replace semantics would silently drop the
base QA hooks from every gated seat. Ruling: hook event arrays directly
under the top-level hooks key concatenate (base first); all other arrays
keep replace semantics; null tombstones still delete an event.
- mutator-gate acceptance now asserts lease wiring against the COMPOSED
gated settings (base + lease-overlay via the launcher's own merge),
matching the post-split contract.
- fleet subcommand canary gains the intended new 'agent' surface from T3.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
Integration reconciliation of T2/T3 seams on feat/wf-fleet-mvp:
- fleet launch now resolves the user root through defaultFleetDataHome()
(MOSAIC_DATA_HOME), the same seam fleet agent new uses, instead of a
divergent MOSAIC_USER_HOME variable.
- Launching an unscaffolded name raises AGENT_NOT_SCAFFOLDED with the
actionable message pointing at 'mosaic fleet agent new <name>' (acceptance
carried over from the T3 card after the roster-v2 reconciliation moved it
onto the launch path).
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
runRuntimeLaunchEntry set MOSAIC_HOME to the shipped framework root, so
launch-runtime.py appended its launch ledger to
framework/fleet/run/sessions/events.ndjson — polluting the tree that
manifest.spec.ts walks and failing its completeness check in CI.
Point MOSAIC_HOME at the per-entry temp root instead. Nothing in the
launch chain resolves tools via MOSAIC_HOME (entry scripts resolve via
SCRIPT_DIR); the ledger is its only consumer here.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
The two install-linker-compatibility tests still asserted the pre-isolation
behavior (mosaic skill links planted in $HOME/.claude/skills). This branch
deliberately moved the link farm into the mosaic-owned harness homes
($MOSAIC_HOME/.claude/skills) and demoted the base-install dirs to
cleanup-only legacy targets, so the tests now assert the new topology:
the skill links appear under the harness home, foreign links in the legacy
dir are preserved, and no new mosaic link is planted in the base install.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Dtdjx4Gxude9fwyLezCrhh
The mosaic wrapper makes pane_current_command=node (RUNTIME_ACCEPTABLE_COMMANDS.claude=['claude','node']); the walk matters precisely in that no-shell-wrapper case. Match reality.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013SAYFkRhQfhguY7AHfiUC8
The launcher runs the runtime as a spawnSync CHILD of node(mosaic) (deliberate,
per launch.ts:99 — parent survives to propagate signals), so
MOSAIC_LEASE_SESSION_ID lives on the claude child, not the pane's root pid. The
transport read only pane.pid's /proc/environ and returned RESOLVE_FAILED for
every real 'mosaic claude' seat. Now BFS the pane's process subtree (bounded,
injectable children-reader) and read the first descendant that carries a valid
lease id; fail-closed if none. Unit tests now exercise the real walk (pane=node
without lease -> child=claude with lease) rather than mocking the resolution.
Found by scooby greenfield E2E on fomo-lin with proc-level evidence.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_013SAYFkRhQfhguY7AHfiUC8
MAX_LEASE_TTL_SECONDS (daemon cap+default) and DEFAULT_TTL_SECONDS
(lease_promote client) both move to 3600. The 5-minute TTL made
gated-by-default sessions unusable (re-promotion mid-task); 1 hour
matches a working session. Full test:framework-shell RC=0.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_013SAYFkRhQfhguY7AHfiUC8
Jason Woltje
shaggyandmos-dt-0
jason.woltjeandMos