fix(groups): finish Phase 1 — MNP root management, upload targets, eject state

Review of the Phase 1 commit found the RO/RW model sound but three paths
unfinished, each of which broke the flow the phase exists to deliver. Plus
29 test failures it introduced and no coverage for anything it added.

Uploads went to the wrong directory. The node read a `root` field on
file_upload that no client ever sent, so every upload landed in the first
writable root while the Files toolbar offered its button based on the root
being browsed — with two writable roots, uploading from one wrote into the
other. Files now names the root it is showing; Chat names one chosen in the
shell (an operator-configured directory arrives in Phase 2); the node refuses
an unknown name rather than falling back, and refuses read-only and ejected
roots by code.

Shared directories were unreachable on the web. The table read its roots
only from the loopback API, which resolves to "not available" in a browser,
so the section rendered for nobody there — while the Uploads controls it
replaced had worked — and the transport.updateRoot/ejectRoot/plugRoot methods
beside it were dead. MNP is now the path, loopback the fallback for a local
node with no live connection, and adding a root over MNP takes a typed path
since no web page can browse a remote disk.

Ejecting updated nobody's screen. transport.js resolves an admin ack against
the pending request and returns, which is right for every op whose caller
knows the value it chose; the root acks carry state only the node can compute,
so the operator who clicked Eject was the one client that never saw it happen.
And the ejected flag reached roster.db but was never read back, so a restart
undid it and the next scan read an empty mount point as an erased library.

Also: the member-upload endpoint answered 200 and did nothing (removed); the
wizard ignored the first root's RW switch; reload compared roots on name and
path, so editing writable in node.toml did nothing; the table had no path
column, which is the only thing separating two libraries sharing a basename;
apps_enabled normalisation differed between the two sides of a signed subject.

Tests: eject/plug, per-root upload refusal and the node.toml rewrite had no
coverage at all. test_member_upload_policy.py is replaced by
test_root_writable_policy.py — it tested a removed feature — and every
property worth keeping from it moved rather than being dropped.

Docs: draft-v6 structural decision 9 is annotated as superseded (the operator
can no longer have a directory only they may write to — a real capability
removed, flagged rather than hidden), the man page documents the root verb and
the RO/RW fields, and refactor-groups.md §7b records what the plan got wrong.

Suite: 41 failures before, 13 after — all 13 pre-existing on main.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011pvMdvLBG92jyhvD5pD6us

1 files changed, 112 insertions, 13 deletions

diff --git a/man/meshbay-node.1 b/man/meshbay-node.1
index 1e1173b..92067a2 100644
--- a/man/meshbay-node.1
+++ b/man/meshbay-node.1
@@ -68,12 +68,18 @@ List all hosted groups with their roots, key status, file count, and
 connected peers.
 .
 .TP
-\fBgroup add\fR \fIname\fR \fB\-\-dir\fR \fIpath\fR [\fB\-\-upload\-dir\fR \fIpath\fR]
+\fBgroup add\fR \fIname\fR \fB\-\-dir\fR \fIpath\fR
 Attach a hub\-side group to this node by writing a
 .B [[groups]]
 entry to
 .IR node.toml .
 The group must already exist on the hub.
+The directory becomes the group's first root, and is
+.B read\-write
+so that a new group can receive an upload without further configuration;
+pass
+.B \-\-no\-writable
+for a group that only publishes.
 Run
 .B meshbay\-node reload
 afterwards, then
@@ -88,6 +94,54 @@ Asks for confirmation unless
 .B \-\-yes
 is given.
 .
+.SS Root management
+A group has one or more named roots: directories on this machine that its
+members see. Each is read\-only or read\-write, independently; a group whose
+roots are all read\-only is valid and accepts no uploads at all.
+.
+.TP
+.B root list
+List this group's roots with their flags and current availability.
+.
+.TP
+\fBroot add\fR \fIpath\fR [\fB\-\-name\fR \fIname\fR] [\fB\-\-writable\fR] [\fB\-\-removable\fR]
+Add a directory to the group. The name defaults to the directory's
+basename; two roots in a group cannot share a name, compared without
+regard to case, and no root may sit inside another.
+Run
+.B meshbay\-node reload
+afterwards to start indexing it.
+.
+.TP
+\fBroot remove\fR \fIname\fR
+Remove a root from the group. Files on disk are untouched; only
+.I node.toml
+changes. The last remaining root cannot be removed.
+Asks for confirmation unless
+.B \-\-yes
+is given.
+.
+.TP
+\fBroot set\fR \fIname\fR [\fB\-\-writable\fR|\fB\-\-no\-writable\fR] [\fB\-\-removable\fR|\fB\-\-no\-removable\fR]
+Change a root's flags without removing it. Takes effect immediately; no
+reload is needed.
+.
+.TP
+\fBroot eject\fR \fIname\fR
+Mark a removable root as ejected before physically disconnecting the
+device. Its files are hidden from members and its index entries are
+frozen \(em nothing is deleted \(em and the directory watcher stops, so
+the unplug produces no deletions to propagate. The device can then be
+removed safely. Refused on a root that is not marked
+.BR removable .
+.
+.TP
+\fBroot plug\fR \fIname\fR
+Re\-enable an ejected root once the device is back. Refused if the
+directory is not readable, since clearing the flag while the device is
+still absent would hand the next scan an empty directory. The root is
+rescanned, so anything that changed while it was away is picked up.
+.
 .SS Member management
 .TP
 .B member list
@@ -196,11 +250,33 @@ Shared directory, used with
 .BR "group add" .
 .
 .TP
-\fB\-\-upload\-dir\fR \fIpath\fR
-Separate upload directory, used with
-.BR "group add" .
-Files land directly in this directory (not in a subdirectory) and it
-appears as its own root in the index.
+.BR \-\-writable ", " \-\-no\-writable
+Whether a root accepts uploads from group members, used with
+.BR "root add" ", " "root set" " and " "group add" .
+Uploads land in an
+.I uploads
+subdirectory of the root; existing files are never replaced.
+A new root is read\-only unless
+.B \-\-writable
+is given; the directory passed to
+.B "group add"
+is the exception and is writable by default.
+.
+.TP
+.BR \-\-removable ", " \-\-no\-removable
+Whether a root lives on a device that gets disconnected, used with
+.BR "root add" " and " "root set" .
+Enables
+.BR "root eject" " and " "root plug" ,
+and makes the node treat the directory suddenly disappearing as an
+unannounced eject rather than as a deletion.
+.
+.TP
+\fB\-\-name\fR \fIname\fR
+Explicit name for a root, used with
+.BR "root add" .
+Default: the directory's basename. Required for a drive or filesystem
+root, which has no basename to derive one from.
 .
 .TP
 .B \-\-yes
@@ -343,15 +419,18 @@ Human\-readable group name.
 .
 .TP
 .B shared_dir
-Single\-directory shorthand: equivalent to declaring one root named after
-the directory's basename, which receives uploads. Cannot be combined with
+Single\-directory shorthand: equivalent to declaring one read\-write root
+named after the directory's basename. Cannot be combined with
 .BR [[groups.roots]] .
 .
 .TP
 .B upload_dir
-A separate filesystem path for uploads. Files land directly in it (not in
-a subdirectory) and it appears as its own root in the index. When set,
-no other root receives uploads.
+Deprecated. A separate filesystem path for uploads, from before roots
+carried their own read\-write flag. A configuration still using it is
+read as a second, writable root and every other root is forced
+read\-only. Use
+.B writable
+on the intended root instead.
 .
 .TP
 .B visibility
@@ -399,10 +478,30 @@ A view hint: one of
 Currently unused.
 .
 .TP
-.B upload
-Boolean. Exactly one root per group must receive uploads. Default:
+.B writable
+Boolean. Whether members may upload into this root. Uploads land in an
+.I uploads
+subdirectory; an existing file is never replaced. Any number of roots in
+a group may be writable, including none. Default:
+.BR false .
+.
+.TP
+.B removable
+Boolean. Whether this root lives on a device that gets disconnected.
+Enables
+.BR "meshbay\-node root eject" ,
+and makes the directory suddenly disappearing freeze the root rather
+than look like a deletion of everything in it. Default:
 .BR false .
 .
+.TP
+.B upload
+Deprecated spelling of
+.BR writable ,
+read for configurations written before the two were separated.
+.B writable
+wins where both appear.
+.
 .SS [keystore]
 .TP
 .B path