ADR 0283: a part waiting for the operator's secret or setting is said as waiting and passes the first-node gate (issue 386)

A module whose only unhealthy part waited for the operator's secret failed
its gate, held every later walk and told the operator there was nothing to
do. The record adds a waits answer and a waiting state, checked by the
controller, read by the gate as waits for a person, and said as a
needs-operator condition naming the act; and secret families so each SMB
source's password is one hidden line at the desk prompt.

03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md

@@ -2,8 +2,9 @@
 layer: to-be
 status: in-progress
 code: [mesh-host, mesh-controller, mesh-lab, mesh-catalog]
-updated: 2026-10-08
+updated: 2026-10-10
 decisions:
+  - 02-DECISIONS/0283-a-part-that-waits-for-the-operators-secret-or-setting-is-said-as-waiting-passes-the-first-node-gate-and-names-the-act.md
   - 02-DECISIONS/0254-a-wait-for-a-persons-new-login-is-not-a-gates-failure-and-each-module-of-a-send-keeps-its-own-pass.md
   - 02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md
   - 02-DECISIONS/0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md
@@ -121,8 +122,16 @@ period do the timing, without an execution per look from outside.
 
 **Per module and long-running resource, the node-engine keeps a state:** `healthy`, `unhealthy` (with the
 reason: down, restarting, or the check's failure in words), `starting` (inside grace), `held` (§1) or
-`unknown` (nothing could be read). With it: since when, the failing streak, and the restarts counted. Every
-start of a resource — a new build, a recreate, a restart — begins in `starting`.
+`unknown` (nothing could be read), or `waiting` (its tool check says it waits for the operator, below).
+With it: since when, the failing streak, and the restarts counted. Every start of a resource — a new build,
+a recreate, a restart — begins in `starting`.
+
+**A tool check answers one of three: healthy, unhealthy, or waits**
+([ADR 0283](../../02-DECISIONS/0283-a-part-that-waits-for-the-operators-secret-or-setting-is-said-as-waiting-passes-the-first-node-gate-and-names-the-act.md)).
+*Waits* says nothing of the module is wrong but a part that cannot work until the operator gives something:
+each wait names one own secret or one setting of the module, the part, and what the operator gives, in words
+with no path, address or value. The answer's shape is mesh-sdk's, read by the module and the node-engine
+alike. One look that says it states the resource `waiting`, inside the grace too, with its waits.
 
 **Said three ways**, as the core already says its own state:
 
@@ -146,6 +155,14 @@ place of `unhealthy` ([ADR 0254](../../02-DECISIONS/0254-a-wait-for-a-persons-ne
 cleared as above, its summary one sentence that says to log out and in again. When the login has come and
 a unit still fails, it clears and `unhealthy` is raised.
 
+**A wait for the operator's secret or setting is its own condition**, `module.<module>.<machine>.needs-operator`,
+in place of `unhealthy` (ADR 0283): a warning, the operator's, never escalated by age, raised and cleared as
+above. The controller first checks the wait: a secret it names must be the module's own, declared issued
+outside the mesh, and hold no value given on that machine; a setting must be one the module declares. Its
+plain words name the act — "Needs you: type the password of the source … at <machine>'s desk prompt", or
+approve the setting when an agent proposes it — and never say there is nothing to do. A wait that fails the
+check is said as `unhealthy`, with why.
+
 **`status`** lists it with the other conditions; **`node show`** shows each module's resources with their
 state and since when, so "is it working" has an answer without opening a terminal on the machine.
 
@@ -174,6 +191,11 @@ fails at the bound until the operator logs in again.
 The node-engine names the account on every resource that runs in an account's own manager, which is how
 the controller tells such a unit from one that is broken.
 
+**A wait for the operator's secret or setting is a wait for a person too** (ADR 0283, issue 386). A module
+whose only resources not healthy are `waiting`, each wait checked as in §4, reads **waits for a person**: a
+pass, carried in the verdict, nothing put back. Unlike a new login, a secret not given is owed by every
+build alike, so any build of the module is excused while the wait checks out.
+
 **Each module of a send keeps its own pass** (ADR 0254). A send is still judged as one, with one verdict.
 The gate also counts, per module, the judgings in a row that found it healthy or waiting for a person;
 when the send fails, a module whose count reached the passes asked keeps a pass, said "on its own", and is

03-DESIGN/01-to-be/52-shares-and-mounts.md

@@ -7,6 +7,7 @@ code:
   - mesh-catalog modules/mounts
 updated: 2026-10-10
 decisions:
+  - 02-DECISIONS/0283-a-part-that-waits-for-the-operators-secret-or-setting-is-said-as-waiting-passes-the-first-node-gate-and-names-the-act.md
   - 02-DECISIONS/0277-a-trusted-setting-is-proposed-through-a-verb-and-set-on-the-operators-warrant-and-a-modules-own-secret-is-asked-for-and-typed-at-the-desk.md
   - 02-DECISIONS/0263-a-share-is-a-provision-a-node-mounts-it-on-demand-and-only-nodes-that-ask-get-it.md
   - 02-DECISIONS/0051-shared-data-is-the-operators.md
@@ -55,7 +56,7 @@ The glossary holds the three words.
 | `nfs-server` | the catalogue | holds `node-nfs-server`, provides the provision, writes its export file, runs the service, opens 2049 to the private network |
 | `mounts` | the catalogue | holds `node-mounts`, writes a unit pair per share, keeps each share's state, serves the tools |
 | the binding | the controller | gives a consumer the server's name; the consumer asks the server's seat for each share's path and access over the bus |
-| the credential | the vault | the `mounts` module's own secret `smb-credentials`, issued outside the mesh and given with `secret accept`, unsealed on the node as a file |
+| the credential | the vault | per SMB source, the `mounts` module's own secret `smb-password-<source>` (a member of the family `smb-password-*`), issued outside the mesh and given with `secret accept` or typed at the desk prompt, unsealed on the node as a file; the username is the setting `smb-users` |
 
 ## 1. The server: `nfs-server`
 
@@ -102,12 +103,18 @@ The glossary holds the three words.
   this node mounts, by the server's name for them. `none` (the default) mounts none.
 - **Its setting `sources`.** Occasional sources: `name=smb://<host>/<share>@<mountpoint>` or
   `name=disk:<uuid>@<mountpoint>`, each optionally `:ro`. `none` (the default) is none.
-- **Its secret `smb-credentials`.** One section per SMB source, `[name]` with `username=` and
-  `password=`, issued outside the mesh and given with `secret accept <node> mounts smb-credentials
-  --from <file>` at the controller's terminal — or asked for by an agent with the controller's `secret-ask`
-  verb, on which a hidden prompt opens at that machine's desk naming the module, the secret and who asked,
-  and the operator types it there ([ADR 0277](../../02-DECISIONS/0277-a-trusted-setting-is-proposed-through-a-verb-and-set-on-the-operators-warrant-and-a-modules-own-secret-is-asked-for-and-typed-at-the-desk.md)). The process writes one credentials file per source, readable by root only. A source
-  with no section is said with that remedy and is not mounted.
+- **Its setting `smb-users`.** The username of each SMB source, `name=username`, space-separated; `none` (the
+  default) is none. Not a secret, so it is a setting.
+- **Its secret family `smb-password-*`.** One member per SMB source, `smb-password-<source>`, holding that
+  source's password as one line, issued outside the mesh and asked for by an agent with the controller's
+  `secret-ask` verb, on which a hidden prompt opens at that machine's desk naming the module, the secret and
+  who asked, and the operator types it there ([ADR 0277](../../02-DECISIONS/0277-a-trusted-setting-is-proposed-through-a-verb-and-set-on-the-operators-warrant-and-a-modules-own-secret-is-asked-for-and-typed-at-the-desk.md));
+  or given with `secret accept <node> mounts smb-password-<source> --from <file>` at the controller's
+  terminal. The mesh never makes a member, so one not given is no file ([ADR 0283](../../02-DECISIONS/0283-a-part-that-waits-for-the-operators-secret-or-setting-is-said-as-waiting-passes-the-first-node-gate-and-names-the-act.md)).
+  The process writes one credentials file per source from the username and the password, readable by root
+  only. A source whose username or password is not given is not mounted, and its health answers *waits*,
+  naming the setting or the secret and what the operator gives: the controller says it as
+  `needs-operator`, and the first-node gate does not fail a build for it (ADR 0283).
 - **Its settings are trusted settings** (a trusted file asks for them), so a verb may not set them outright:
   an agent proposes them (`settings propose mounts … --node <node>`) and the operator approves on their
   phone, where the ask shows each source in its shape ("recalbox=‹address›@‹path›") and the layer's
@@ -213,9 +220,9 @@ folders, none refused for a reason not understood.
    export goes; the mesh's stays. *Undo:* `zfs set sharenfs=<the old value>` by a person, recorded as a
    hand-act.
 7. **The downloads**, the same way: read-only first, then read-write.
-8. **The gaming device**: an agent asks for `smb-credentials` with `secret-ask`, and the operator types it at
-   that machine's desk (or gives it with `secret accept` at the terminal); the agent proposes the source in
-   `sources`, and the operator approves it on their phone; `node-mounts.list` says it `absent` while the
+8. **The gaming device**: the agent proposes the source in `sources` and its username in `smb-users`, and the
+   operator approves each on their phone; an agent asks for `smb-password-<source>` with `secret-ask`, and the
+   operator types it at that machine's desk (or gives it with `secret accept` at the terminal); `node-mounts.list` says it `absent` while the
    device is off, and it mounts on access when it is on. Then its fstab line is adopted.
 9. **The laptop**, read-only, granted read-only on the home server.