stack/agents/darkwing/work/queue-190/DESIGN.md

Row 190 design: several Mosaic Stack instances on one host

Brief: docs/plans/2026-10-20_multi-instance.md, blob 4e8f1e0528 (commit 48ebee0ff, rev 2259). Line 16 now limits isolation to addressing on one uid and points to row 195 (190b). Gitea #1688. MVP T1 item 1 (mos-0974, DECISIONS Q176-Q178). Owner Darkwing, reviewer Filbert, gate owner Sage. Base: da230ca48. Worktree: /mnt/storage/scratch/darkwing-r190, branch darkwing/row190.

Mos ruled Q1 in mos-0986 (2026-10-20T18:53:48Z). O1 is approved with one added sentence, and R1 is ranked required, as row 190b. See "Rulings" at the end. Revision 2 of this file adds that sentence and the section. Revision 3 answers Filbert's review of revision 2 (B1, B2, N1-N6). "Review rounds" at the end lists each change.

Summary

• One carrier. Inside every process, the instance is the config file that MOSAIC_CONFIG names, or the default config when it is unset. This is how the code works today. No package learns an instance name.
• --instance NAME exists only on the shell entry points that name units, ports or wrappers, or that create a config. NAME maps to ~/.config/mosaic-NAME/config.json. The default instance is dev, which maps to today's ~/.config/mosaic-dev/config.json. With no flag, everything is byte-identical to today.
• Units: mosaic-bus-NAME@<business>, mosaic-webui-NAME, mosaic-discord-NAME@<binding>. The default keeps mosaic-bus@, mosaic-webui and mosaic-discord@.
• A data root is claimed by a marker file that bootstrap writes. A tool aimed at one instance refuses a data root that carries another instance's marker, or no marker at all for a named instance.
• Copies stay shared. The pointer, activation log, backups, rollback sets and rehearsals already live under $DATA, so they become per instance with no new code.
• One limit holds through all of this. Every instance runs as the same Unix user. That separates instances by addressing: no Mosaic command aimed at one names a file, unit or port of another. It is not an OS permission boundary. R1 covers what that means for Melanie's instance.

Inventory

Every single-instance point I found in scripts/ and packages/*/src, outside tests, at da230ca48. The grep covered .config/mosaic-dev, mosaic-dev/config.json, MOSAIC_CONFIG, .mosaic-dev, dataRoot, the unit names, 7330/7332/7333, claude-session.env, BUSINESS=, COPIES and secrets. About 55 files read dataRoot from the loaded config. Those are already per instance and are not listed.

#	Where	What is single-instance	Change
F1	scripts/mosaic-config.mjs:41-45, :183	default config path and default dataRoot ~/.mosaic-dev	--instance NAME on bootstrap, validate, env; new op instance (D1)
F2	scripts/bootstrap.sh	runs mosaic-config.mjs bootstrap with no instance	passes --instance NAME through (D2)
F3	packages/cli/systemd/mosaic-bus.service.in:24	fixed EnvironmentFile=-%h/.config/mosaic-dev/secrets/claude-session.env, no MOSAIC_CONFIG	two placeholders that render to today's bytes for the default (D3)
F4	scripts/bus-service.sh:25-26, :102-118, :177	unit name [email protected]; busy and drop-in scans glob mosaic-bus@*	--instance; names and globs from D3
F5	packages/webui/systemd/mosaic-webui.service.in, scripts/webui-service.sh:68-69, :85, :274-279	one unit mosaic-webui.service; port default 7332; bus_on_copy globs mosaic-bus@*	--instance; a named instance must pass --port; port refusal (D4)
F6	packages/discord/systemd/[email protected], scripts/discord-service.sh:20-21, :153	one template; status reads ${XDG_CONFIG_HOME}/mosaic-dev/config.json and ignores MOSAIC_CONFIG	--instance; status reads the instance's config
F7	scripts/stack-copy.sh:8, :95	BUSINESS=mosaic-stack; check reads mosaic-webui.service and $BIN/mosaic	check --instance; wrapper --instance (D5)
F8	scripts/stack-release.sh:31, :416-425, :533-546, :607-628, :1478	CONSOLE_UNIT, mosaic-bus@ in capture, restore, busy check and drop-in scan; wrapper $BIN/mosaic	names from D3 and D5
F9	scripts/stack-release.sh:72, :99, :1405-1414	tester port refuses 7332 only; rehearse reserves 7332, 7333 and the pointer's port; LIVE_CFG default	reserved set from D4; LIVE_CFG follows --instance
F10	packages/conversation/src/guard.mjs:47-55, :111	the live-session guard protects ~/.mosaic-dev and the default config's dataRoot only	also protects each named instance's config dir, ~/.mosaic-NAME and its config's dataRoot, for names that pass the D1 rule (D7)
F11	packages/business/src/business.mjs:26, packages/seat/src/seat.mjs:47, packages/discord/src/binding.mjs:54	MOSAIC_CONFIG or the default	none: already follow the carrier
F12	packages/control-board/src/scan.mjs:30	default config only, --config PATH overrides	none: the control board is dev tooling, and it already takes --config
F13	scripts/reset.sh:2-4	refuses any target but /home/jwoltje/.mosaic-dev	none: reset stays default-only, and refuses a named instance
F14	scripts/land-work.sh:99, scripts/conductor-apply.sh	the conductor pipeline's config dir	none: dev pipeline, not an instance
F15	packages/business/src/business.mjs:23-27 (configDir)	the business files and secrets sit beside the config	none: per instance once the config is
F16	copies ${XDG_DATA_HOME}/mosaic-stack/copies in four scripts	one copies directory	shared on purpose (D5)

One naming collision to know about. "Instance" already means a role instance in packages/business (resolveInstance, b.roles keys). That word stays out of the packages. The new flag lives only in shell scripts and mosaic-config.mjs. The docs say "stack instance" wherever a reader could confuse the two.

D1. Instance identity

1. Name rule: ^[a-z][a-z0-9]{1,15}$. No hyphen. With a hyphen, systemd's prefix drop-ins (mosaic-bus-.service.d and so on) would gain a level per hyphen, and the guard scans would no longer be a fixed list. A hyphen would also let one name be a prefix of another's unit.

2. Mapping: NAME's config is <home>/.config/mosaic-NAME/config.json, where <home> is os.homedir() / $HOME, as mosaic-config.mjs uses today, not XDG_CONFIG_HOME. dev is the default instance, so --instance dev is the same as no flag, byte for byte. The mapping never produces ~/.config/mosaic (v1 and scripts/foundation use that).

3. Selection, in every shell entry point that takes it:

   --instance	MOSAIC_CONFIG	Result
   absent	absent	default, exactly today
   absent	set	that config, with default unit and wrapper names: today's behavior, and what every existing test does
   NAME	absent	NAME's config, and the entry point exports MOSAIC_CONFIG to everything it runs
   NAME	set	allowed only when both resolve (realpath) to the same file; otherwise exit 4, instance-config-mismatch

4. Node code takes no flag. scripts/mosaic, the bus host, the Console, the Discord connector, the task runner and the human CLI follow MOSAIC_CONFIG as they do now. A human reaches a named instance through its wrapper mosaic-NAME (D5) or by setting MOSAIC_CONFIG.

5. The mapping lives in one place: mosaic-config.mjs instance [--instance NAME] prints shell-safe exports. They are MOSAIC_INSTANCE, MOSAIC_CONFIG, MOSAIC_CONFIG_DIR and MOSAIC_UNIT_SUFFIX (empty for the default, -NAME otherwise). A sourced scripts/instance.sh turns those into BUS_TEMPLATE, BUS_GLOB, CONSOLE_UNIT, DISCORD_TEMPLATE, WRAPPER_NAME and SESSION_ENV. Every entry point uses that file, and row 191 can too.

6. Refusals: a bad name exits 4 (instance-name-invalid). For a named instance, a missing config exits 3 with the bootstrap hint, as today. Data-root claims are D2.

D2. Config canon and bootstrap

Bootstrap: scripts/bootstrap.sh --instance NAME runs mosaic-config.mjs bootstrap --instance NAME. It:

1. creates ~/.config/mosaic-NAME/ (mode 0700) and the config with wx, as today. It never overwrites; an existing config is validated and left alone;
2. writes the default dataRoot ~/.mosaic-NAME. The operator may change it before first use. The default instance keeps ~/.mosaic-dev;
3. claims the data root. It creates the root if absent (0700) and writes <dataRoot>/instance.json, {"instanceVersion":1,"name":"NAME"}, with wx, mode 0644. It refuses if the root exists and is not empty and holds no marker of its own name. An existing config whose root lacks the marker is a refusal, not a repair.

The claim check runs in scripts/instance.sh. Every entry point that takes --instance sources that file on every run, flag or no flag, so the check covers all four rows of the D1 table. It runs once the config has loaded, before the entry point reads or writes anything else. A missing config keeps today's refusal. bootstrap is the one exception, because it makes the claim (step 3 above).

• With --instance NAME (D1 rows 3 and 4), <dataRoot>/instance.json must be a regular, non-symlink file naming NAME. Otherwise exit 3, instance-root-unclaimed or instance-root-mismatch.
• With no flag (D1 rows 1 and 2), the selection takes the default's unit and wrapper names, so the marker must be absent or name dev. Otherwise exit 3, instance-root-mismatch, naming the marker's instance and the --instance flag to use. Row 2 is where this matters: MOSAIC_CONFIG=~/.config/mosaic-a/config.json scripts/stack-release.sh activate ID with no flag would otherwise drive a's data root through the default's units and $BIN/mosaic. With the check, it refuses before any unit is read or called.
• No marker exists anywhere today, and the existing tests' scratch configs carry none, so rows 1 and 2 behave exactly as they do now.

This blocks two configs from sharing one data root through the shell tools. It does not stop a hand-run MOSAIC_CONFIG=... scripts/mosaic bus start from a copy, but the bus store's writer lock (<dataRoot>/bus/writer.lock) still refuses a second broker on one root.

Q1, for Mos: the AGENTS.md invariant 2 wording

Today:

2. Configuration: ~/.config/mosaic-dev/config.json is the sole system config — created only by scripts/bootstrap.sh, never overwritten, fail-closed on any problem. Repo-scoped role authority lives in roles/*.json (versioned, reviewed commits only).

Proposed (O1, my recommendation):

2. Configuration: each stack instance has exactly one system config. The default instance's is ~/.config/mosaic-dev/config.json. Instance NAME's is ~/.config/mosaic-NAME/config.json, and its data root carries a marker that names it. ~ is the home of the OS user that runs the instance. A process reads only the config MOSAIC_CONFIG names, or the default's when that is unset. Configs are created only by scripts/bootstrap.sh [--instance NAME], never overwritten, fail-closed on any problem. Repo-scoped role authority lives in roles/*.json (versioned, reviewed commits only).

The "Data map (canon)" line in AGENTS.md changes to match: "~/.config/mosaic-dev/config.json, or ~/.config/mosaic-NAME/config.json per named instance: system config (user-authored; never auto-written)".

Alternatives:

• O2: named instances under the default's directory, ~/.config/mosaic-dev/instances/NAME/config.json. That keeps one config root, but the default's config dir would then contain every other instance's businesses and secrets. Anything allowed into the default's config dir reaches all of them. I recommend against it.
• O3: no canon change, MOSAIC_CONFIG only, no names. Unit names, ports and wrappers then have nothing to key on, so the brief's units point can't be met.

AGENTS.md is Sage's file. The row edits only those two lines, and only with the wording Mos rules.

D3. Units

	Default (unchanged)	Instance NAME
bus template	[email protected], %i = business	[email protected], %i = business
Console	mosaic-webui.service	mosaic-webui-NAME.service
Discord template	[email protected], %i = binding	[email protected], %i = binding
wrapper	$BIN/mosaic	$BIN/mosaic-NAME

The templates gain two placeholder lines:

• @CONFIG_ENV@. For the default, render deletes the line. For NAME, it becomes Environment=MOSAIC_CONFIG=<abs config path>, held to the plain character set the scripts already enforce.
• In the bus template, EnvironmentFile=-@SESSION_ENV@. For the default this renders as %h/.config/mosaic-dev/secrets/claude-session.env, today's text. For NAME it is <abs config dir>/secrets/claude-session.env.

Default renders therefore stay byte-identical to the base template's. A test (T-I8) compares them. The Console unit's comment "The unit sets no MOSAIC_* ... variable" gains "except MOSAIC_CONFIG for a named instance". The Description lines get [NAME] for named instances only.

The scans follow the names:

• Busy checks glob mosaic-bus@*.service for the default, as today, and mosaic-bus-NAME@*.service for NAME. Neither glob matches the other's units, so a running bus in one instance never blocks or reaches the other.
• The drop-in scan (bus-service.sh:118, stack-release.sh:628) covers bus units only, today and in this row. For a named instance it adds the bus directories that systemd applies to mosaic-bus-NAME@<business>: mosaic-bus-NAME@<business>.service.d, [email protected] and the shared prefix mosaic-bus-.service.d. The existing mosaic-.service.d and service.d scans stay. Since mosaic-bus-.service.d applies to every named bus, each named instance's scan refuses an ExecStart override there.
• Console and Discord drop-in scans stay out of scope, as they are today: no script scans mosaic-webui*.service.d or mosaic-discord*.service.d, and this row adds no scan for them. That includes the shared prefixes mosaic-webui-.service.d and mosaic-discord-.service.d, which systemd applies to every named Console and Discord unit. I'll record it as a follow-up.

Shared prefix directories are never instance state. The directories systemd applies to more than one instance are mosaic-bus-.service.d, mosaic-webui-.service.d, mosaic-discord-.service.d, mosaic-.service.d and service.d. Capture and restore never save or rewrite any of them. For NAME, the rollback set holds [email protected], mosaic-webui-NAME.service, [email protected], mosaic-bus-NAME@<business>.service.d, mosaic-webui-NAME.service.d and $BIN/mosaic-NAME, and nothing else. The default's set stays as it is (stack-release.sh:416-425). None of its directories applies to a named unit: systemd derives [email protected]'s prefixes by cutting at hyphens, which never yields [email protected] or mosaic-webui.service.d. So one instance's rollback can't rewrite a directory another instance's units read.

The human-proof rule still holds per instance. Jason or Mos starts each Console. Nothing here adds a start verb.

D4. Ports

• A named instance's Console has no default port. webui-service.sh install|render --instance NAME without --port exits 4. The default keeps 7332.
• Reserved for named instances: 7330 (the operator's bare Console), 7332 (the tunnel) and 7333 (the default's tester). The existing rule that no tester takes 7332 stays for every instance.
• Collision refusal. webui-service.sh install and stack-release.sh activate read every installed Console unit in UNIT_DIR: mosaic-webui.service (no --port there means 7332) and mosaic-webui-*.service. They take each unit's --port and --tester-port. If this instance's port or tester port equals any of them, the run exits 1 or 3 with port-claimed, naming the unit that holds the port. stack-release.sh rehearse adds those ports to its reserved list.
• Unit files are host configuration, not another instance's state, so reading them keeps the D7 rule that each instance reads only its own config and data root. No instance reads another's pointer.
• The claim covers installed units only. An instance that is bootstrapped but has no Console unit yet holds no port, so a second instance can take the port first. The loser's install then refuses port-claimed, which is safe. Nothing reserves a port at bootstrap.
• A port another process already holds still fails at bind, as today (serve exits 2).

D5. Copies, pointer and wrapper

• Copies stay shared, one ${XDG_DATA_HOME}/mosaic-stack/copies. They are read-only trees named by full commit id, and nothing prunes them (decision 96 condition 4). Any future prune must read every instance's pointer and log. This row doesn't add one.
• stack-release.sh takes --instance NAME. Its DATA, STATE, POINTER, LOG, backups, rollback sets, post-attempt directories and rehearsals all come from the loaded config's dataRoot (:1473-1477). They are per instance once the config is. flags_drift reads the pointer and this instance's unit only. Capture and restore (:416-425, :533-552) use the D3 names and $BIN/$WRAPPER_NAME.
• stack-copy.sh check --instance NAME checks mosaic-bus-NAME@<business>, mosaic-webui-NAME and $BIN/mosaic-NAME. --business stays required for a named instance. BUSINESS=mosaic-stack stays the default's default.
• The named-instance wrapper. stack-copy.sh wrapper ID --instance NAME writes $BIN/mosaic-NAME through a temp file and a rename. Line 2 is a marker, # mosaic-cli wrapper, instance NAME (row 190). The body sets MOSAIC_CONFIG to NAME's config, then runs exec "<copy>/scripts/mosaic" "$@". It has no Q81 lease line: that probe belongs to the default. It creates the file when absent, replaces a file with its own marker, and refuses any other file. The default wrapper code is unchanged.
• Q175 C1 applies per instance. A named instance's pointer can roll back to a copy from before Q175, and that copy refuses a config with a console key, the same trap the default has. Nothing new handles it here.

D6. Secrets

• The Claude session env file is <configDir>/secrets/claude-session.env, set by the bus unit (D3). The default's stays %h/.config/mosaic-dev/secrets/claude-session.env.
• The secrets slot root is <configDir>/secrets/mosaic-stack/, the same rule Q175 uses. Business credential files are absolute paths in the business file, which lives in <configDir>/businesses/. The operator puts each instance's tokens under its own config dir.
• Nothing in this row reads, creates or lists a secret file. Bootstrap creates <configDir> at 0700 and no secrets/ directory.

D7. Isolation proof (tests)

All tests use scratch roots under TMPDIR and the stand-in systemctl, journalctl and systemd-analyze from packages/cli/tests/stack-release.test.mjs. HOME is a scratch directory, so ~/.config/mosaic-* resolves inside it. None of them touches ~/.mosaic-dev, ~/.config/mosaic-dev, a live unit or a slot file. New tests go in stack-release.test.mjs (T55, so they share mk), plus a new packages/cli/tests/instances.test.mjs for the config and bootstrap cases and the two real hosts.

T-I5 binds two bus sockets under the scratch roots. The run keeps TMPDIR under ~/darkwing-scratch, within the 107-byte socket path limit (the row 177 lesson), and BUILD.md states the scratch path's length.

The guard (F10) is the one stated exception to "each instance reads only its own config and data root". It reads, and never writes, dataRoot from each ~/.config/mosaic-NAME/config.json whose NAME passes the D1 rule, so that a session can't write into another instance's root. The glob mosaic-* is filtered by the name rule. On this host it matches only mosaic-dev: mosaic, mosaic.bak and mosaic.bak1 don't match. An unreadable config adds nothing, as at guard.mjs:49-54. So, as with .mosaic-dev at :111, the guard also protects ~/.mosaic-NAME and ~/.config/mosaic-NAME/ for each name it finds, whatever that config says. A broken config for b can't drop b's default root from the guard.

Test	Shows
T-I1 bootstrap	bootstrap --instance a and --instance b create mosaic-a and mosaic-b configs, roots and markers. A second bootstrap changes no byte. A non-empty unmarked root refuses, including an existing non-empty ~/.mosaic-worktrees under --instance worktrees (the name passes the rule, so the claim is what stops it). Names A, a-b, x, a 17-character name and ../x exit 4. --instance dev writes exactly what no flag writes
T-I2 selection	the four rows of the D1 table, including the mismatch refusal and the realpath case that agrees
T-I3 render	bus, Console and Discord renders for a and b carry their own MOSAIC_CONFIG, EnvironmentFile and unit names, and no other instance's path
T-I4 ports	a --port 7340, then b --port 7340, refuses port-claimed. So do b --tester-port 7340, b with no --port, and b --port 7332. b --port 7341 passes
T-I5 side by side	two real bus hosts (scripts/mosaic bus start --no-launch) from the worktree, one per scratch config, both up at once. Each bus status answers from its own socket under its own root
T-I6 no cross-reach	activate and rollback on a, with b fully installed: b's units, drop-ins, wrapper, pointer, log, store and backups are byte-identical before and after, and so are the shared prefix directories mosaic-bus-.service.d, mosaic-webui-.service.d and mosaic-discord-.service.d, each seeded with a .conf file. a's rollback set holds none of them. calls.log names no b unit. An inotify read watch (the row 187 T53 watch) on b's config dir and data root counts zero events. Then the same with a and b swapped
T-I7 claims	a's config pointing at b's root refuses instance-root-mismatch. A named root with no marker refuses instance-root-unclaimed. A default config whose root carries a's marker refuses. D1 row 2: MOSAIC_CONFIG=<a's config> stack-release.sh activate C1 and bus-service.sh install, both with no flag, refuse instance-root-mismatch with exit 3. calls.log names no unit, and no unit, wrapper, pointer or store changes. A scratch config with no marker, run with no flag, passes as today
T-I8 default unchanged	default renders of all three units equal the da230ca48 templates' renders byte for byte. stack-release.sh --plan, status and stack-copy.sh check print the same text from the base script and the candidate in one fixture. The existing stack-release tests pass unchanged
T-I9 busy scoping	b's bus active does not refuse a's activate, and a's own bus active does
T-I10 guard	LiveSessionGuard refuses a path inside a named instance's config dir or data root. With b's config corrupt, it still refuses a path in ~/.mosaic-b and in ~/.config/mosaic-b/. A directory ~/.config/mosaic.bak adds nothing

Mutants

Each one must fail at least one test above. They are run against the candidate, the script restored and its sha256 checked after each, as in rows 187 and 188.

#	Change	Expected killer
M1	instance.sh ignores NAME and returns the default names	T-I3, T-I6
M2	the port-claimed check skipped	T-I4
M3	the marker check skipped	T-I7
M4	the bus render drops the MOSAIC_CONFIG line for a named instance	T-I3
M5	SESSION_ENV always the default path	T-I3
M6	the named busy glob widened to mosaic-bus*@*.service	T-I9
M7	the default render keeps an empty line where @CONFIG_ENV@ was	T-I8
M8	capture saves $BIN/mosaic for a named instance	T-I6
M9	--instance and a different MOSAIC_CONFIG accepted	T-I2
M10	the name pattern accepts a hyphen	T-I1
M11	bootstrap --instance opens the config without wx	T-I1
M12	the guard drops the named instances' roots	T-I10
M13	the claim check runs only when --instance is given	T-I7 (D1 row 2 case)
M14	capture and put_back include mosaic-bus-.service.d for a named instance	T-I6
M15	the guard drops the unconditional ~/.mosaic-NAME and keeps only the config's dataRoot	T-I10 (corrupt-config case)

Scope and boundaries

• In the row: F1-F10 code, the three templates, scripts/instance.sh, the tests, the package READMEs, and the two AGENTS.md lines in Mos's ruled wording (O1 plus the ~ sentence), nothing else in that file. docs/TOOLS.md gets the --instance text, written by me as part of the manifest (sage-1335).
• Not in the row:
  • standing up a real second instance (a later Q173 window, with a backup first and a STATE report after);
  • any tunnel or Traefik exposure (Jason, after Q175 SSO);
  • SSO, users and RBAC (T1 items 2 and 3);
  • the kill switch (row 191).
• No re-pin needed. The default's units, paths and ports don't change, and the live copy keeps running its own templates until a later activate. At that activate the default renders are byte-identical (T-I8).

Risks

• R1. Same Unix user. Every instance runs as jwoltje. A role session or a hand-run process in one instance can read another's files if it names them. This row only makes sure no Mosaic tool aimed at one instance names another's files, units or ports. For Melanie's instance, the real boundary is SSO plus RBAC (T1 items 2-3) for the Console. Mos ranked the stronger separation as required (mos-0986): row 190b, chained on this row, puts Melanie's hub under its own Linux user. This row stays on one uid.
• R2. The marker check guards the shell tools only (D2). A hand-run MOSAIC_CONFIG=... scripts/mosaic from a copy skips it. The writer lock still stops two brokers on one root. Filbert's N5 offered a fix: the shared loader could check the marker whenever the config path is a canonical ~/.config/mosaic-NAME/config.json. I'm leaving it out. Q175 C1 showed the cost of a shared-loader change, since every old copy refuses what it doesn't know, and a rollback lands on old copies. Row 190b, with its own uid, is the real boundary for the hub.
• R3. stack-release.sh is 1490 lines with many name literals. M1 and M8 plus T-I6 are there to catch a missed literal. Before in-review I'll grep the candidate for every bare mosaic-bus@, mosaic-webui and $BIN/mosaic and list each remaining one with its reason.

For row 191 (Rocko)

The resolution contract to build on:

1. Inside processes, MOSAIC_CONFIG, or the default when unset, through the existing loaders.
2. All state goes under that config's dataRoot.
3. Unit names come from scripts/instance.sh: BUS_TEMPLATE, BUS_GLOB, CONSOLE_UNIT, DISCORD_TEMPLATE and WRAPPER_NAME. Never from literals.
4. Shell entry points take --instance NAME. That name may change if Mos rules O2 or O3 on Q1.

Rulings

mos-0986 (2026-10-20T18:53:48Z), on revision 1 (sha256 3a6479764283...):

• Q1: O1 is approved, with one sentence added to the invariant: "~ is the home of the OS user that runs the instance." The proposed wording in D2 now carries it. The D1 mapping already uses os.homedir(), so an instance under another uid needs no more code in this row. The roles line and the Data map line change as proposed. O2 and O3 are rejected.
• R1: Mos ranks it required, not a follow-up (federation review B5, duckworth-0001; mos-0984 and mos-0985). A separate uid per instance is a hard precondition of federation R8 and of Case 2 row C2-13. This row lands as designed, on one uid, so scratch two-instance tests run without root. Row 190b (queue row 195, Gitea #1693, reviewer Duckworth), chained on this one and owned by Darkwing, designs Melanie's hub under its own Linux user.

Review rounds

Filbert, on revision 2 (sha256 5493c9df3ec0..., 2026-10-20T18:56:34Z): CHANGES, B1 and B2. Revision 3:

• B1. D2 now says the claim check runs on every row of the D1 table, flag or no flag, with bootstrap the one exception. With no flag, the marker must be absent or name dev. T-I7 gains the D1 row 2 case (a's config with no flag, through stack-release.sh activate and bus-service.sh install): exit 3 instance-root-mismatch, and calls.log names no unit. A marker-less scratch config still passes. M13 (the check runs only with --instance) dies on that case.
• B2 (1). D3 now says the drop-in scan covers bus units only, today and in this row. Console and Discord drop-in scans stay out of scope, including their shared prefixes, as a recorded follow-up.
• B2 (2). D3 lists the shared prefix directories and says capture and restore never save or rewrite them. It also gives the exact rollback set for NAME. T-I6 seeds mosaic-bus-.service.d, mosaic-webui-.service.d and mosaic-discord-.service.d and checks them byte for byte. M14 (capture includes mosaic-bus-.service.d) dies there.
• N1. D7 states the guard as the one read-only exception. The glob is filtered by the name rule. ~/.mosaic-NAME and ~/.config/mosaic-NAME/ are protected whatever the config says. T-I10 gains the corrupt-config and mosaic.bak cases, and M15 checks the unconditional root.
• N2. D4 says installed units are the only claim.
• N3. D7 states the TMPDIR rule, and BUILD.md will give the path length.
• N4. T-I1 gains the ~/.mosaic-worktrees case.
• N5. R2 records the loader option and why I'm leaving it out.
• N6. D5 has the one line on Q175 C1 per instance.
• N7 is Sage's brief line. Nothing changes here.