Merge pull request 'Design 41: every file on a node is managed through node-files (WP9, ADR 0394)' (#380) from design/41-node-files into main

Reviewed-on: #380

03-DESIGN/01-to-be/41-the-shell-and-the-accounts-environment.md

@@ -2,8 +2,9 @@
 layer: to-be
 status: in-progress
 code: [mesh-host, mesh-controller, mesh-catalog]
-updated: 2026-10-12
+updated: 2026-10-16
 decisions:
+  - "ADR 0394"
   - "ADR 0310"
   - "ADR 0268"
   - "ADR 0252"
@@ -90,6 +91,7 @@ WP5  assign and prove                            (operator-gated)       needs WP
 WP6  a module puts the account in a group        (mesh-host, mesh-controller, mesh-catalog)   issue 247
 WP7  the control-node withholds execute          (mesh-controller, mesh-catalog)          ADR 0268
 WP8  a node's files and accounts are read        (mesh-sdk, mesh-catalog, mesh-controller) ADR 0310, issue 418
+WP9  every file on a node is managed            (mesh-catalog, mesh-controller) ADR 0394, issue 900
 ```
 
 WP1, WP2 and WP4 are independent, and are built in parallel on one feature branch per repository
@@ -341,6 +343,10 @@ out, the control-node's value is set to `withhold` and zsh is pushed to it. Then
 
 *`mesh-sdk`, `mesh-catalog`, `mesh-controller`. ADR 0310, extending ADR 0268; tracked by issue 418.*
 
+**Replaced by WP9.** ADR 0394 supersedes ADR 0310: `node-files` takes over every read below, with the same
+bounds, content rule and refusal of secret places; once `node-files` is held on every node, the next delivery
+removes `node-reads` and `mesh-reads`.
+
 ADR 0268 §5 has narrow read tools take the common reads over from `execute`, so that an approval is asked for an
 act and not for a read, and ADR 0286 §44 sets the approval mark on `execute` only once those reads have a tool on
 every node. Two had none: reading or searching a file, and looking up an account or a group.
@@ -366,3 +372,38 @@ under the same issue.
 `mesh-sdk` test of the content rule and one in each of its users; `mesh_search` for `cat`, `grep` and
 `getent passwd` finding the verbs. Live, the kernel's RAID status file is read through the seat on the home
 server, and the agent's credentials file on the laptop is refused.
+
+## WP9 — Every file on a node is managed through `node-files`
+
+*`mesh-catalog`, `mesh-controller`. ADR 0394; tracked by issue 900.*
+
+`node-reads` only reads, and as an account that cannot open a person's home, so nothing in the mesh could copy,
+move, write or delete a file, and a cleanup needed a shell on the machine. Most files belong to no module: homes,
+project folders, downloads, logs, scratch.
+
+- **A node seat, `node-files`, on every node**, held by a module of its own, `mesh-files`, beside `mesh-reads`
+  in the catalogue; the controller holds the seat's definition beside the other node seats. It has a verb for each file action: list,
+  stat, readlink, read, search, write, copy, move, delete, make a folder, change mode, change owner, account and group
+  lookup, and the trash's list and restore. Each says what it replaces (ADR 0245): `ls`, `stat`, `readlink`, `cat`,
+  `grep`, `cp`, `mv`, `rm`, `mkdir`, `chmod`, `chown`, `getent passwd`, `getent group`, `id`, and `ssh <node> cp` for a
+  copy between nodes.
+- **It may touch every file.** It declares no account of its own: the tool runner starts it as the node's
+  operator account, which has sudo without a password, and it uses `sudo -n` only where that account's own rights
+  do not reach. It keeps each file's owner and modes as well as it can: a copy or a move keeps them, a new file
+  takes its folder's owner. Which files to touch is the caller's responsibility; it judges no permission.
+- **Nothing is lost at once.** A file deleted or overwritten goes to the node's trash with who asked and why, is
+  restorable for 7 days, and is emptied after.
+- **A path a module owns is refused**, naming the module and its tool, unless the call says `override` with a
+  reason; an override is recorded and said to the operator.
+- **It replaces `node-reads`.** Its reads keep WP8's bounds, content rule and kernel reads. Every node is
+  assigned `mesh-reads`, so `node-reads` and `mesh-reads` are removed by the next delivery, once `mesh-files`
+  holds `node-files` on every node.
+- **No Approve is asked**; every act is recorded with its caller. Read and search never return the content
+  of a known credential file or a secret place (the mesh never prints a token); copying or moving one is
+  allowed.
+
+**Proof.** The module's tests: each verb against a temporary tree keeps owner and modes, a new file takes its
+folder's owner, a delete is restorable from the trash and gone after 7 days, an owned path is refused and an
+override recorded, a credential file's content is never returned. Live: the operator's `~/.claude` on a workstation is listed, a file in `/etc` is read through sudo, and a file copied from one node to another
+arrives with its owner and modes.
+