row 210 (#1707): DESIGN.md r3, duckworth-0043 C1 (Q-J0 revoke line matches section 6), N1-N4, sage-1468 scope line (harness tool out, Q-S3) and 1.7 approval (Gizmoduck)

agents/gizmoduck/work/queue-210/DESIGN.md

@@ -0,0 +1,538 @@
+# Row 210 (#424, Gitea #1707): agent host access with sudo through the credential store
+
+Gizmoduck, 2026-10-20, r3. Design only, no code. Reviewer Duckworth, gate owner Sage. Due 2026-10-27 (Q184).
+
+- Brief: `docs/plans/2026-10-20_host-credentials.md` at 9db578ff5.
+- Base read: `origin/refactor` 9ba31b5b3. Row 199 read as DESIGN.md r6 (4d3007ec9) and its code and
+  BUILD.md at addee664a on `megavolt/row199`.
+- PRD: REQ-CRED-3 in Honker's 1.7 draft (`agents/honker/work/queue-194/PRD-1.7-DRAFT.md:111-115`, 11cb0423b).
+  Jason approved PRD 1.7 (d52febb5 yes at 20:36:47Z, mos-1089), so REQ-CRED-3 is in.
+- Scope (sage-1468): this row ships the `host.run` broker op, the grant check, the executor and the receipts,
+  all testable over `broker.sock`. The `host_run` harness tool is out, as 199 left its publish tool out
+  (199 BUILD.md deviation 12). Sage files one follow-up row for the agent-facing harness tools, publish and
+  `host_run`, in `packages/harness`. Duckworth's r2 N5 (the tool help says a gated call leaves stdin under
+  4 KiB) belongs to that row.
+- Branch `gizmoduck/row210`. Row claimed in-progress (rev 2361) after Sage cleared the after (rev 2359). It
+  lands only after 199, rebased onto 199's landing (Q177).
+
+Rounds:
+- r3 (duckworth-0043, REVIEW-r2.md at 52b5fee63, approved with C1, and sage-1468, sage-1472): C1 Q-J0's revoke
+  line now matches section 6, the connection is cut and a started command may keep running. Q-S3 answered,
+  the harness tool is out (scope line above, D10). N1 the runner list takes Duckworth's whole list, and D6
+  says the per-call decision is the control. N2 numeric shorthand, unspecified and mapped addresses and
+  `*.localhost` refuse (D3, T1). N3 the pids file records each pid's start time (D7, T27). N4 the mutant
+  table is in order.
+- r2 (sage-1450): no `"any"` grant. The command boundary is an argv allowlist per host grant, and load refuses
+  a wildcard (D6, T26, M6, M28). PRD 1.7 is frozen, so `host.sudo` stays a hard wait and Jason decides each
+  call. Section 5 now holds the proposed 1.8 routing requirement. D5 is confirmed against 199's deviation 11.
+  The seat network gap is a known limit with what closes it (section 6). Cites now point at 199's code.
+- r2 (duckworth-0042, REVIEW-r1.md at 8140b7f39): B1 events name host, user and argv in clear (D5 step 6,
+  T22, M30). B2 a gated call's question shows stdin in full (D4, T9, M31). B3 the key and processes die with
+  the bus, and bus start sweeps leftovers (D7, T27, M32 to M34). B4 Q-J0 for Jason in section 10, worded to
+  stand alone (mos-1088). Notes taken: N1 (E12, runGit's kill shape), N2 (loopback refused, own-host limit),
+  N3 (process groups), N4 (stdin can make a prefix root), N5 (`-l` and a separate address), N6 (D8 framing),
+  N7 (section 7).
+
+## 1. What the code does today
+
+| # | Fact | Cite |
+|---|---|---|
+| E1 | The bus reads credentials for two kinds only, `gitea` and `vikunja` | `bus/src/credentials.mjs:22`, `business/src/vocabulary.mjs:103` |
+| E2 | A credential value must match `^[-A-Za-z0-9._~]+\n?$`, at least 16 and at most 16384 bytes. An OpenSSH private key fails it at the first `-----BEGIN` space | `bus/src/credentials.mjs:84-87` |
+| E3 | `assertClean` searches `JSON.stringify(result)` for each token. JSON escapes a newline, so a multi-line secret is never found: `JSON.stringify("a\nb").includes("a\nb")` is `false` (run on node here) | `bus/src/credentials.mjs:95-103` |
+| E4 | `use()` turns any exception in the operation into `service-failed`, then runs `assertClean` | `bus/src/credentials.mjs:104-117` |
+| E5 | Host to bus-child IPC is serial, one request at a time, with a 10 s timeout. A slow reply breaks the channel | `cli/src/host.mjs:31`, `:270` |
+| E6 | The web verbs run in the bus child over `broker.sock`. `requestWeb` checks keys, runs `#secretCheck`, checks the grant `roles[s.role].web`, records `action.allowed` (requested), calls `onAdmit()` so the server raises the socket timeout, runs the service and records completion | `bus/src/broker.mjs:1492-1530`, `bus/src/server.mjs:87-95` |
+| E7 | `roles[role].web` comes from the resolved tool limit. A role entry in the bus holds `authority`, `web` and `credentials` | `bus/src/business.mjs:17-20` |
+| E8 | A business-file role entry takes `definition`, `holder`, `vars`, `tracker`, `credentials`. Anything else refuses at load | `business/src/business.mjs:89` |
+| E9 | The chief's `organization.set` takes only `ORGANIZATION_KEYS`. The human-only `instances.set` takes `INSTANCE_KEYS` and refuses any definition that declares a credential (`organization-credentials-out-of-scope`). Holder, credentials and tracker stay hand edits | `bus/src/broker.mjs:145-147`, `:1248-1298`, `business/src/instance-settings.mjs:1-5`, `:22-31` |
+| E10 | An action outside ROUTED is a hard wait and classifies `gated` for every role. No role file may grant one | `bus/src/broker.mjs:44-70`, `business/src/vocabulary.mjs:58-88`, PRD REQ-WAIT-2 and 3 |
+| E11 | The seat sandbox does not confine the network, abstract Unix sockets or the host UID | `seat/src/sandbox.mjs:29-31` |
+| E12 | On refactor the bus child spawns nothing. With 199 it spawns git: `publishRemote` (`bus/src/runtime.mjs:245` at addee664a) runs `runGit`, a detached group leader that gets SIGTERM at the limit, then SIGKILL to the group after a grace period | `seat/src/checkout.mjs:95-138` at addee664a |
+| E13 | Role networks are `none`, `api-only`, `open`. The bundle carries the value, and the sandbox's own comment says the network is not confined (E11) | `business/src/vocabulary.mjs:101`, `harness/src/bundle.mjs:252` |
+
+Row 199 gives, in code at addee664a: `useFor` (`bus/src/credentials.mjs:228`), `issue` (`:156`), `revoke`
+(`:197`), `remove` (`:211`), the kind list (`:49`), the token pattern (`:19`, `:143`), the store dir's file
+regex `^(gitea|vikunja)(\.tmp)?$` (`:222`) and `withGitea` (`bus/src/runtime.mjs:233`). From its design: the store at `<configDir>/secrets/agents/<business>/<agent>/<kind>` (D1), the `{store: true}`
+reference (D2), the read path (D3, D3a), `useFor(session, kind, op)` with the call-site allowlist test (D5),
+the `publish` grant shape, a list on the role entry plus a hard-wait action whose decision binds the commit
+(D9), and the human-only lifecycle verbs with `changes.jsonl` receipts (section 6).
+
+## 2. Probe (throwaway keys, scratch sshd on 127.0.0.1:22410, OpenSSH 10.5p1)
+
+Run in `/mnt/storage/scratch/gizmo-210-probe` with keys made for the probe and deleted after. No real key or
+host was touched.
+
+| Probe | Result |
+|---|---|
+| `ssh-add -` with the private key on stdin, to an agent on a private socket | works, "Identity added: (stdin)" |
+| `IdentityAgent=<sock>` with `IdentitiesOnly=yes` and `IdentityFile=none` | refused, `Permission denied (publickey)`. With `IdentitiesOnly`, ssh offers only agent keys that match a configured identity |
+| same with `IdentityFile=<the public key file>` | works, rc 0 |
+| `-i /dev/fd/3` with the key on fd 3 | fails, "Identity file /dev/fd/3 not accessible". ssh closes inherited fds, so the fd route is out |
+| a known_hosts file pinning the wrong key under `HostKeyAlias` with `StrictHostKeyChecking=yes` | refused, "Host key verification failed", rc 255 |
+| `printf '%s|'` with `'a b'` and `'it'\''s'` single-quoted, plus an unquoted `$((1+1))` as a control | prints `a b|it's|2|`. The quoted elements arrive whole, and only the unquoted control expanded |
+| remote `exit 7` | ssh exits 7 |
+| killing the agent | its socket file is gone |
+
+## 3. Decisions
+
+### D1. The kind and its naming
+
+One key per (agent, host). The kind name is `host.<hostId>`, so the store file is
+`<configDir>/secrets/agents/<business>/<agent>/host.<hostId>` (199 D1, unchanged). `hostId` matches
+`^[a-z0-9][a-z0-9-]{0,31}$`.
+
+The closed kind set becomes `gitea`, `vikunja` and the family `host.<hostId>`. One exported helper,
+`credentialKind(name)` in `vocabulary.mjs`, answers whether a name is a kind, and each place that checks
+kinds calls it: `SERVICES` users (`role.mjs:105-118`), 199's `bus/src/credentials.mjs:49` and the store
+file regex at `:222`, the broker's service
+check, the CLI `issue` date flag and 199's remove regex. A build test greps for literal `'gitea', 'vikunja'`
+lists outside `vocabulary.mjs` and fails on a new one.
+
+Why per host and not per agent. A key that leaks, or a host that is retired, is revoked for that host alone.
+ops-01 installs one public key per host, and an `authorized_keys` line names one agent. The cost is more keys
+for Jason to issue, one per grant.
+
+A role definition declares the kind once as `{"service": "host"}` with no scopes. The business file binds the
+concrete hosts (D3). A definition can't name a host, because hosts belong to one stack instance.
+
+The date is `--rotate-by DATE`, as for gitea. An ssh key doesn't expire on its own, so `status()` reports
+`rotation-due` or `valid`, the gitea branch.
+
+### D2. The value check
+
+`checkValue(kind, text)` replaces the one regex at `credentials.mjs:84`. For `gitea` and `vikunja` it is
+today's check, unchanged. For `host.*` the value must be:
+
+- PEM framed by `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----`, LF line ends,
+  at most 16384 bytes (the existing cap).
+- An `openssh-key-v1` blob with cipher `none`, kdf `none`, exactly one key, type `ssh-ed25519`. Parsed in
+  node with `Buffer`, no ssh-keygen call, so the check runs at bus start without a process.
+- The two check integers equal, and the public key in the private section equals the one in the header.
+
+Anything else refuses `credential-format`. An encrypted key refuses, because the bus has no way to ask for a
+passphrase and `BatchMode=yes` would fail at use time instead of at load. The parsed public key is kept with
+the entry so `status` and D7 can print its fingerprint without touching the private part.
+
+### D3. The grant
+
+Four layers. Each must hold, and the code checks all four on every call.
+
+1. **Role definition, reviewed commit.** `roles/<def>.json` lists `{"service": "host"}` in `credentials`. That
+   is the "reviewed role change" in the brief. Once a PRD version routes `host.sudo` (section 5), the same
+   reviewed commit puts `host.sudo` in that definition's `authority.withinRole`.
+2. **Host registry, business file, hand edit.** A new top-level key:
+   ```
+   "hosts": { "<hostId>": { "address": "10.1.1.53", "port": 22, "user": "localadmin",
+                            "hostKeys": ["ssh-ed25519 AAAA..."] } }
+   ```
+   `address` is an IPv4 or IPv6 literal or a DNS name matching `^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$`.
+   An address of this machine refuses at load (r2 N2, r3 N2). For an IP literal, which `net.isIP` decides,
+   that is `127.0.0.0/8`, `0.0.0.0/8`, `::1`, `::`, and an IPv4-mapped `::ffff:` form of either IPv4 range.
+   For a name, it is `localhost` and any name ending in `.localhost`. A name made only of digits and dots
+   refuses unless `net.isIP` reads it as IPv4, so the shorthand `127.1` and the integer `2130706433`, which
+   pass the DNS pattern and which the resolver reads as 127.0.0.1, refuse. A label starting `0x` refuses for
+   the same reason. `port` is 1 to 65535. `user` matches `^[a-z_][a-z0-9_-]{0,31}$`. `hostKeys` is a non-empty list of
+   `ssh-ed25519`, `ecdsa-sha2-nistp256` or `ssh-rsa` public key lines, type and base64 only, no comment.
+3. **Agent grant, business file, hand edit.** A new role-entry key beside 199's `publish`:
+   ```
+   "hosts": { "<hostId>": { "commands": [["systemctl", "status"], ["journalctl", "-u"]] } }
+   ```
+   Each `hostId` must be in the registry, and the role's definition must declare `host`. A role entry with
+   `hosts` whose definition lacks `host` refuses at load and names `roles.<agent>.hosts`. `commands` is the
+   command boundary (D6).
+4. **The key.** `credentials["host.<hostId>"] = {"store": true, "rotateBy": DATE}` with the file present
+   (199 D2, D3a). A grant without an issued key refuses `credential-unavailable` at call time, as 199 does.
+
+Who writes each layer is in section 4. Neither the chief nor any agent can reach layers 2 to 4: `hosts` is
+outside `ORGANIZATION_KEYS` and `INSTANCE_KEYS` (E9), `instances.set` already refuses a definition that
+declares credentials (E9), and 199's `issue` is human-only.
+
+### D4. The action and the decision binding
+
+`host.sudo` is a new action in ACTIONS and in neither ROUTED list. Until a PRD version routes it, it is a hard
+wait and classifies `gated` for every role (E10). Each call then needs a decision the human resolved. PRD 1.7
+is frozen (sage-1450, decision d52febb5 cites its sha256), so under 1.7 Jason decides every `host.run`.
+
+The decision binds one call, the way 199 D9 binds `pushCommit`. When the action is `host.sudo`, the
+`decision.raise` event body gets `hostRun = {host, argvSha256, stdinSha256}`, from the raise's own args. The
+question shown to the human ends with the host id, the user, the argv with each element JSON-quoted, and the
+stdin in full as one JSON string, so Jason sees all of what runs (B2). The broker appends that text itself, and
+the agent can't shape it. The whole question keeps the 4096-character cap (`broker.mjs:126`, `:1654`), so on a
+gated call stdin is as large as the cap allows and no larger. A raise that doesn't fit refuses
+`invalid-request`. `argv ["bash"]` can't be granted at all (D6), and `["tee", "/etc/x"]` with a stdin Jason
+can't see is ruled out by showing it. `#authorityFor` refuses `decision-mismatch` when the call's host, argv hash or stdin hash differs, as
+`holderRun` does at `broker.mjs:796`. A decision is spent once (`decision-consumed`).
+
+After routing, a definition that lists `host.sudo` within-role runs without a decision, and `decision` is
+optional for that class only. The grant layers in D3 still apply.
+
+### D5. The executor: a `broker.sock` verb in the bus child
+
+```
+host.run {"host", "argv": [..], "stdin"?, "timeout"?, "decision"?}
+  -> {"exit", "signal", "stdout", "stderr", "truncated": {"stdout", "stderr"}, "ms"} or a refusal
+```
+
+It runs in the bus child, shaped like `requestWeb` (E6), not as a host IPC op. A sudo command can take
+minutes and the host channel times out at 10 s and serves one request at a time (E5). The key is in the bus
+child's memory already (199 D3), so no ticket has to cross to the CLI host. Row 199's publish needs a ticket
+because git and the working repo live in the CLI host. ssh needs neither. 199's BUILD.md deviation 11
+(addee664a) keeps credential use in the bus child too: the push runs there under `withGitea`, and the host
+socket only checks and polls. Sage confirmed D5 matches that shape (sage-1450). `host.run` needs no host
+socket and no poll, because the agent calls `broker.sock` directly. The helper is `withHost(session, host,
+fn)`, beside `withGitea`, calling `useFor(session, "host." + host, fn)`.
+
+Order of checks. Each refusal goes through `broker.refuse()` and logs `action.refused`.
+
+1. `keys(args)`, then `#secretCheck(args)`, then identity from the cap.
+2. `host` is in the registry (`host-unknown`).
+3. `host` is in `roles[s.role].hosts` (`host-not-granted`). This is the REQ-CRED-3 check "a grant exists for
+   that agent and that host".
+4. `argv` shape (D6) and `commands` match (`command-not-granted`).
+5. `#checkAuthority(s, "host.sudo", {decision, target: host, context})` (D4).
+6. Record `action.allowed` phase `requested` with host, address, user and argv in clear (B1), and stdin as
+   size and sha256. Every arg already passed `#secretCheck` in step 1, as the web verbs log their url
+   (`broker.mjs:1521`). After routing, the event log is the record of what ran as root. Then `onAdmit()`, which
+   sets the socket timeout to the call's timeout plus 10 s, as the web branch does (`server.mjs:95`).
+7. `credentials.useFor(s, "host." + host, run)`, where `run` is D7.
+8. D8's leak check on the output, then `#secretCheck` on the result.
+9. Record phase `completed` with host, argv, exit, signal, ms, and size and sha256 of stdout and stderr. The
+   output itself never goes into an event. A failure records `host-failed` with the same fields.
+
+Only one `host.run` per (agent, host) runs at a time. A second refuses `host-busy`. That keeps a stuck call
+from piling up ssh processes and makes revoke (D9) simple.
+
+Spawns reuse `runGit`'s shape (E12): an argv array, never a shell, `detached: true` so each process leads its
+own group, SIGTERM to the group at the limit and SIGKILL after a grace period. If the helper can be shared, it
+is, rather than a second copy. `env` is `{PATH: "/usr/bin:/bin"}` only, plus `SSH_AUTH_SOCK` for `ssh-add`.
+Each spawn is wrapped in `setpriv --pdeathsig KILL --`, the prefix the seat sandbox already uses
+(`seat/src/sandbox.mjs:44`), so it dies when the bus child dies (B3).
+
+### D6. The command boundary
+
+`argv` is an array of 1 to 256 strings. Each is 1 to 4096 bytes of UTF-8 with no NUL, and the total is at most
+32768 bytes. `argv[0]` must not contain `/` unless it starts with `/`. `stdin` is optional, a string of at most
+65536 bytes, and goes through `#secretCheck` with the args.
+
+The remote command is built by the bus, never taken as a string:
+
+```
+sudo -n -- 'argv0' 'argv1' ...
+```
+
+Each element is POSIX single-quoted: wrap in `'`, and replace each `'` with `'\''`. The probe shows the
+remote shell gets each element back exactly (section 2). `sudo -n` fails instead of prompting, so a host
+without NOPASSWD returns sudo's error, not a hang. The host's login shell for `user` must be POSIX. That is a
+host precondition for ops-01, listed in section 7.
+
+`commands` in the grant is an argv allowlist and nothing else. It is a non-empty list of argv prefixes. An
+argv passes when its first N elements equal some prefix of length N, compared element by element as literal
+strings, with no globbing. `[["systemctl", "status"]]` admits `systemctl status nginx` and refuses
+`systemctl restart nginx`.
+
+There is no wildcard grant (sage-1450). Business-file load refuses, naming `roles.<agent>.hosts.<id>.commands`:
+
+- any value that isn't a list, including the strings `"any"` and `"*"`,
+- an empty list, an empty prefix, a non-string element, or a duplicate prefix,
+- an element containing `*`, `?` or `[`, so nobody writes a glob that the matcher would read literally,
+- a prefix whose first element, by basename, is a shell, a command runner or an interpreter. Shells: `sh`,
+  `bash`, `dash`, `zsh`, `ksh`, `fish`, `busybox`. Runners: `su`, `sudo`, `doas`, `pkexec`, `runuser`, `env`,
+  `xargs`, `nohup`, `setsid`, `timeout`, `nice`, `systemd-run`, `chroot`, `nsenter`, `unshare`, `setpriv`,
+  `capsh`, `flock`, `stdbuf`, `ionice`, `chrt`, `taskset`, `strace`, `script`, `watch`. Interpreters:
+  `python3`, `perl`, `ruby`, `node`, `awk` (Sage's ruling on duckworth-0043 N1). Each would turn the prefix
+  back into "any". T26 has one case per name.
+
+That list can't be complete, and it isn't the control. Under 1.7 the control is Jason's decision on each
+call, bound to host, argv and stdin (D4, Q-S1). The list only refuses the obvious cases at load, early. Many commands can still start a shell or an editor as root (`systemctl edit`,
+`find -exec`, interpreters). The allowlist limits mistakes and narrows what a grant means, but it is not a
+sandbox. Stdin goes to the command, so some prefixes are root on their own: `[["tee"]]` or `[["dd"]]` writes
+any file as root from stdin (N4). Section 6 says what remains.
+
+Output: stdout and stderr each capped at 1 MiB. Past the cap the bus keeps reading and drops the rest so the
+remote side doesn't block, and sets `truncated`. `timeout` defaults to 60 s, maximum 900 s. At the timeout
+the bus sends SIGTERM to the ssh process group, then SIGKILL after 5 s, and answers `signal`. ssh's own exit
+code 255 and a remote command exiting 255 can't be told apart. The result returns stderr so the agent can see
+which, and the doc says so.
+
+### D7. Handing the key to ssh
+
+Per call, inside `useFor`'s operation:
+
+1. `mkdtemp` a dir under `<configDir>/secrets/run/` with mode 0700. `<configDir>` is never bound into a sandbox
+   (199 D3). The socket path is checked against the 107-byte Unix socket limit before use, refusing
+   `host-failed` if over.
+2. Write two files in it, mode 0600: `known_hosts` with one line per pinned key, `mosaic-host-<hostId> <type>
+   <base64>`, and `id.pub` with the entry's public key (D2).
+3. Write `<dir>/pids` with the bus child's pid. Each line in it is a pid and that process's start time,
+   field 22 of `/proc/<pid>/stat`, so a reused pid never matches (duckworth-0043 N3). Start `ssh-agent -D -a <dir>/a.sock` as its own group leader,
+   append its pid, and wait for the socket. Run `ssh-add -t <timeout + 30> -` with `SSH_AUTH_SOCK` set and the
+   private key written to its stdin. The key never touches disk, argv or env. `-t` makes ssh-agent drop the key
+   at the call's timeout plus 30 s even if nothing else runs (B3). ssh is the second group leader, and its pid
+   is appended too. Timeout, revoke and the `finally` kill both groups, ssh-agent's and ssh's (N3).
+4. Run ssh with exactly these options and nothing from any config file:
+   ```
+   ssh -F /dev/null -T -p <port>
+     -o BatchMode=yes -o IdentitiesOnly=yes -o IdentityFile=<dir>/id.pub -o IdentityAgent=<dir>/a.sock
+     -o StrictHostKeyChecking=yes -o UserKnownHostsFile=<dir>/known_hosts -o GlobalKnownHostsFile=/dev/null
+     -o HostKeyAlias=mosaic-host-<hostId> -o UpdateHostKeys=no -o CheckHostIP=no -o VerifyHostKeyDNS=no
+     -o ForwardAgent=no -o ForwardX11=no -o ClearAllForwardings=yes -o PermitLocalCommand=no
+     -o ProxyCommand=none -o ProxyJump=none -o ControlMaster=no -o ControlPath=none
+     -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3
+     -l <user> -- <address> <remote command from D6>
+   ```
+   The user goes in `-l` and the address is its own argument, so nothing depends on how ssh splits `@` or on
+   an IPv6 literal (N5). `-F /dev/null` stops `~/.ssh/config` from adding a ProxyCommand, a different key or forwarding. The pin is
+   `StrictHostKeyChecking=yes` against a file the bus wrote from the registry, so there is no trust on first
+   use: an unknown or changed host key refuses with rc 255 (probe, section 2) and the bus answers
+   `host-key-mismatch` when stderr has "Host key verification failed".
+5. In a `finally`: kill both groups, remove the dir. A test asserts the dir is gone after success, refusal,
+   timeout and an exception thrown inside the operation.
+6. If the bus child is killed, the `finally` never runs. `--pdeathsig` kills ssh-agent and ssh with it, and
+   `-t` drops the key anyway. At bus start, before `broker.sock` listens, the bus sweeps
+   `<configDir>/secrets/run/`. A recorded pid counts as alive only when it exists and its start time matches.
+   For each dir whose bus pid is no longer alive, it sends SIGKILL to each recorded pid that is alive and
+   whose `/proc/<pid>/cmdline` names that dir, then removes the dir. A dir whose bus pid is alive is left
+   alone. Any other entry there refuses start, as 199 refuses a stray file
+   in the store (`credentials.mjs:222`). Revoke after a restart has nothing in flight to reach.
+
+The 0600 temp key file route the brief allows is not used. The agent route keeps the private key off disk,
+and the fd route doesn't work (probe).
+
+### D8. The leak check
+
+This is defense in depth (N6). The remote never holds the private key and forwarding is off, so output can
+carry the key only if the agent already had it. `assertClean` misses a multi-line key (E3). A `host.*` entry
+in the shared token map makes its loop compare against a value that never matches, which is harmless. For a `host.*` entry, `useFor` checks the result with
+`assertCleanKey(result, entry)`, which searches the JSON text for:
+
+- each base64 body line of the PEM of 24 characters or more,
+- the whole body with line breaks removed,
+- the 32-byte ed25519 private seed as lowercase hex and as base64 at each of the three byte offsets.
+
+A match refuses `credential-leak`. The output is dropped, and the event records only sizes and hashes. The
+existing `assertClean` still runs for the token kinds. The same function runs on `stdin` before the call, so
+an agent can't round-trip a key it somehow has back through the host.
+
+### D9. Lifecycle
+
+199's verbs carry over with `KIND = host.<hostId>`. Two additions:
+
+- `issue AGENT host.<id>` checks D2, then prints the public key line and a suggested `authorized_keys` line
+  for ops-01: `from="<stack host address>",restrict <type> <base64> mosaic-<business>-<agent>-<id>`. It
+  prints only public material.
+- `revoke` also kills a `host.run` in flight for that agent and host (process group SIGKILL) before it drops
+  the key. The call answers `credential-unavailable`. Remote processes that the killed ssh started may keep
+  running (section 6).
+
+`status` shows each host entry with its fingerprint (SHA256 of the public key), the rotate date and state.
+The tester gets `status` and `revoke` only, as in 199.
+
+### D10. Where the files change
+
+| File | Change |
+|---|---|
+| `business/src/vocabulary.mjs` | `host.sudo` in ACTIONS, `credentialKind`, host id pattern |
+| `business/src/business.mjs` | top-level `hosts` registry, role-entry `hosts`, load checks from D3 |
+| `business/src/role.mjs` | `{"service": "host"}` in `checkCredentials` with no scopes |
+| `business/src/credentials.mjs` | `host.*` refs take `rotateBy` |
+| `bus/src/credentials.mjs` | kind check via `credentialKind`, `checkValue` (D2), `assertCleanKey` (D8), busy and kill map |
+| `bus/src/host-run.mjs` (new) | D6 argv and quoting, D7 ssh-agent and ssh spawn, cleanup |
+| `bus/src/broker.mjs` | `host.run` verb (D5), `host.sudo` in `#authorityFor` with `hostRun` (D4) |
+| `bus/src/server.mjs` | `host.run` branch beside the web branch with `onAdmit` |
+| `bus/src/business.mjs` | carry `hosts` onto the bus role entry |
+| `cli` | 199's `credentials issue` accepts `host.<id>`, prints D9's lines |
+
+No `packages/harness` file changes. The `host_run` tool is Sage's follow-up row (sage-1468).
+
+Row 199's own kind and regex are not changed inside row 199. This row rebases onto 199's landing and changes
+them here.
+
+## 4. Who grants (brief item, "yours to propose with reasons")
+
+Proposal: **Jason, at every layer that widens access. No agent, chief included, and not the tester.**
+
+| Layer | Who | How | Why |
+|---|---|---|---|
+| Definition declares `host` (and later lists `host.sudo`) | Jason | reviewed commit to `roles/*.json`, as for any role authority (AGENTS.md invariant 7) | It decides which kinds of agent may ever hold a host key. Review puts a second seat on it |
+| Host registry and pins | Jason, with ops-01's key fingerprints | hand edit of the business file | The pin is the host identity. A wrong pin is a man-in-the-middle on root. It must come from the host side, not from a first connection |
+| Agent grant `roles.<agent>.hosts` | Jason | hand edit of the business file | Q183: "not all agents will need to have that access". The per-agent, per-host choice is his |
+| Key `issue` | Jason | 199's human-only `issue` | The key passes through the caller. The tester is an agent (199 section 6, duckworth N1) |
+| `authorized_keys` on the host | ops-01 | host side, from the line `issue` prints | ops-01 owns the hosts (brief) |
+| Revoke | Jason, Mos, or the tester | `revoke` | Taking access away should be quick and needs no new trust |
+
+Why not a reviewed commit for the agent grant too. The business file lives in `<configDir>`, outside the
+repository (AGENTS.md invariant 2), and per-instance grants already stay hand edits there (E9, 199 D9 step 2).
+Moving grants into the repo would put host addresses and the per-instance roster under review, which is a
+bigger change than this row. The definition layer is the reviewed one.
+
+Why not the chief. A chief with this power could hire an agent and grant it root. 199 already keeps hires
+uncredentialed (199 D13). `instances.set` refuses credentialed definitions today (E9), and this row keeps it
+that way.
+
+REQ-CRED-3 says the who-grants answer is set by this design and approved by Jason. The table above is that
+answer.
+
+## 5. The routing gap and a proposed 1.8 requirement
+
+PRD 1.7 routes `role.hire`, `role.fire` and `git.push.remote`, not `host.sudo`, and 1.7 is frozen (sage-1450).
+This row builds for 1.7 as it stands. `host.sudo` is a hard wait under REQ-WAIT-3, and Jason decides each
+`host.run`, bound to host, argv and stdin (D4). That is safe, and slower than Q183's "allow agents to perform
+their jobs". The routing goes in 1.8. Sage takes the line below to Mos for Jason. I don't edit the PRD.
+
+Proposed for PRD 1.8, beside REQ-CRED-3:
+
+> **REQ-CRED-4.** The action `host.sudo` is routed. A role whose definition lists it within-role may run a
+> command with sudo on a host without a decision for each call, but only when all of these hold: the
+> definition declares the host credential kind, the business file grants that agent that host, the command
+> matches the grant's argv allowlist, and the agent's key for that host is issued. A grant names exact
+> argv prefixes. A wildcard grant is refused. A role without `host.sudo` within-role still needs a decision
+> for each call. Jason adds `host.sudo` to a definition only through a reviewed role change.
+
+Routing is then one reviewed commit: `host.sudo` into both ROUTED lists and into the chosen definitions'
+`withinRole`, as 199 does for `git.push.remote`.
+
+The brief also says this row lands only after the PRD version holding REQ-CRED-3 is approved. Jason approved
+1.7 (d52febb5 yes at 20:36:47Z, mos-1089), so that holds. 1.7 doesn't route `host.sudo`, so Q-S1 stands.
+
+## 6. Limits, said plainly
+
+- **Known limit: the seat network isn't confined, so root can outlive the grant.** `seat/src/sandbox.mjs:29-31`
+  says the sandbox doesn't confine the network (E11). An agent whose allowlist admits any command that can
+  write a file as root, or start a shell, can add its own key to `authorized_keys` on the host. It can then
+  ssh straight from its sandbox, around the bus, the events and revoke. An `authorized_keys` `from=` option
+  doesn't help, because the sandbox shares the stack host's address. The allowlist (D6) narrows this but
+  doesn't close it.
+  What closes it: a seat sandbox with its own network namespace (`bwrap --unshare-net`), where the only way
+  out is the bus sockets and the model proxy, so role network `none` and `api-only` are enforced and not just
+  carried in the bundle (E13). With that in place, a planted key is useless from the sandbox. Until then,
+  ops-01's host-side audit (sudo log, `authorized_keys` changes) is the check after the fact. Sage is
+  reporting the gap to Mos as its own follow-up (sage-1450). It is not this row.
+- **The stack's own machine.** A registry entry for the machine the stack runs on, or any machine holding the
+  stack's `<configDir>`, gives an agent with a root-writing command every agent's keys and tokens, not only
+  root there (N2). Load refuses loopback addresses, but it can't know every address of the stack's machine.
+  Jason doesn't register it.
+- **Revoke stops the stack's path, not remote processes.** Killing ssh may leave a remote process running.
+  `-T` gives no tty, so there is no SIGHUP from a closing terminal.
+- **Same OS user.** Anything running as the stack's OS user outside a sandbox can read the key file, as 199 D6
+  says for every kind.
+- **Exit 255** is ssh's failure code and also a remote exit code (D6).
+- **The pin trusts the registry.** Whoever writes the business file controls which host key is trusted. That
+  is Jason (section 4).
+
+## 7. Host preconditions (ops-01, not this row)
+
+- `user` has NOPASSWD sudo and a POSIX login shell. `sudo` has no `requiretty` for that user.
+- The agent's key is in `authorized_keys` with `from="<stack host>",restrict`.
+- The host's public keys are handed to Jason for the registry.
+- Duckworth's #423 r5 condition (duckworth-0035) applies. If ops-01 changes #423 step 1 to fit this design,
+  for example per-agent `from=...,restrict` lines for localadmin, that change goes to Duckworth as a diff
+  before it runs. That is the live part, not this row (N7).
+
+## 8. Tests
+
+All tests use a scratch sshd on 127.0.0.1 started by the test, with keys made by the test, and a fake `sudo`
+on the test user's PATH that prints its argv as JSON and runs nothing as root. The sshd config sets
+`AuthorizedKeysFile` and `HostKey` in the test's `mkdtemp` dir. A helper skips the ssh tests with a visible
+reason only when `/usr/bin/sshd` is missing, and the gate fails if any of them skipped. No test reaches
+another host.
+
+| # | Test | Refusal or result |
+|---|---|---|
+| T1 | business load: `hosts` registry field checks, bad address, each own-machine form from D3 (`127.0.0.2`, `0.0.0.0`, `::1`, `::`, `::ffff:127.0.0.1`, `::ffff:0.0.0.0`, `localhost`, `a.localhost`, `127.1`, `2130706433`, `0x7f.1`), with `10.1.1.53` and `host.example` as controls, port, user, empty `hostKeys`, a key line with a comment | load refuses, names the key path |
+| T2 | role entry `hosts` naming an unknown host, or on a definition without `host` | load refuses `roles.<agent>.hosts` |
+| T3 | `organization.set` and `instances.set` with `hosts` in args | `invalid-request`, and the file is unchanged |
+| T4 | value check: a valid unencrypted ed25519 key loads. An encrypted key, an RSA key, two keys, CRLF, a gitea token in a `host.*` slot, and a PEM in a `gitea` slot each refuse | `credential-format` |
+| T5 | `host.run` with an unknown host | `host-unknown` |
+| T6 | `host.run` on a host not in the caller's grant, including a host granted to another agent | `host-not-granted` |
+| T7 | argv shape: empty, a NUL, too long, too many, a relative path with `/`, non-string | `invalid-request` |
+| T8 | allowlist: a matching argv runs, a longer argv runs, a shorter one and a differing element refuse | `command-not-granted` |
+| T9 | before routing: no decision refuses, a decision for another argv, another host or another stdin refuses, a spent one refuses. The stored question carries host, user, argv and the full stdin, and a raise whose question would pass 4096 characters refuses | `gated`, `decision-mismatch`, `decision-consumed`, `invalid-request` |
+| T10 | quoting: argv with spaces, quotes, `$()`, backticks, `;`, newline and glob characters reaches fake sudo unchanged | fake sudo's JSON equals argv |
+| T11 | the remote command starts `sudo -n --` | fake sudo sees `-n` and `--` first |
+| T12 | exit code and signal pass through, timeout kills the process group and answers `signal` | result fields |
+| T13 | output cap: 2 MiB of stdout returns 1 MiB and `truncated.stdout: true`, and the call doesn't hang | result fields |
+| T14 | host key pin: the sshd presents a key not in `hostKeys` | `host-key-mismatch`, and no command ran (fake sudo's marker file absent) |
+| T15 | a registry with the right key passes on a fresh dir with no `~/.ssh/known_hosts` in HOME. A HOME with a `~/.ssh/config` setting a ProxyCommand doesn't change the call | runs, and the proxy marker is absent |
+| T16 | leak: the fake sudo prints the private key file (multi-line), and in a second case prints only one body line, and in a third the seed in hex | `credential-leak`, the event has no output |
+| T17 | `stdin` containing a body line of the key | `credential-leak` before any spawn |
+| T18 | cleanup: after success, refusal, timeout and a thrown error, the run dir is gone and no `ssh-agent` or `ssh` with that dir in argv survives | dir absent, pgrep empty |
+| T19 | the private key never appears in the argv or env of any spawned process (read from `/proc/<pid>/cmdline` and `environ` while the fake sudo sleeps) | absent |
+| T20 | second concurrent call for the same agent and host | `host-busy` |
+| T21 | revoke during a sleeping call kills it, and the next call refuses | `credential-unavailable` |
+| T22 | events: `action.allowed` requested and completed carry host, address, user and argv in clear, and sizes and hashes of stdin, stdout and stderr. Never the output, the stdin or the key | event bodies |
+| T23 | `issue` of a `host.*` kind prints the public line and the `authorized_keys` suggestion and never the private key | stdout and stderr checked |
+| T24 | build grep: no literal `'gitea', 'vikunja'` kind list outside `vocabulary.mjs`, and 199's `credentials.use(` allowlist unchanged | grep |
+| T25 | no role file in `roles/` lists `host.sudo` while it is a hard wait (REQ-WAIT-2) | grep |
+| T27 | SIGKILL the bus child while fake sudo sleeps: the ssh and ssh-agent pids are gone within 2 s. A call with `timeout` 1 leaves an agent whose key is gone after 31 s (`ssh-add -l` on its socket, agent kept alive by the test). The next bus start removes the run dir, kills a planted live process whose cmdline names it, leaves a dir whose bus pid is alive, and leaves a live process whose pid matches but whose start time doesn't | pids, `ssh-add -l`, dir state |
+| T26 | load refuses `commands` as `"any"`, `"*"`, `{}`, `[]`, `[[]]`, a non-string element, a duplicate prefix, an element with `*`, `?` or `[`, and a prefix starting with each listed shell or runner, `/bin/bash` included | load refuses, names `roles.<agent>.hosts.<id>.commands` |
+
+## 9. Mutants
+
+One per refusal, plus the two the brief names. Each must be killed.
+
+| # | Mutant | Killed by |
+|---|---|---|
+| M1 | registry check skipped | T5 |
+| M2 | agent grant check skipped | T6 |
+| M3 | grant check reads any agent's `hosts` | T6 |
+| M4 | each argv shape check removed, one mutant each (5) | T7 |
+| M5 | prefix match compares only `argv[0]` | T8 |
+| M6 | load accepts a string `commands` (wildcard grant) | T26 |
+| M7 | `#checkAuthority` call removed | T9 |
+| M8 | `hostRun` argv hash not compared | T9 |
+| M9 | `hostRun` stdin hash not compared | T9 |
+| M10 | quoting drops the `'\''` replacement | T10 |
+| M11 | `sudo -n` loses `-n` | T11 |
+| M12 | **host key pin skipped**: `StrictHostKeyChecking=accept-new` | T14 |
+| M13 | **pin skipped another way**: `UserKnownHostsFile` set to the user's default | T14, T15 |
+| M14 | `-F /dev/null` removed | T15 |
+| M15 | **key leaks into output**: `assertCleanKey` not called | T16 |
+| M16 | leak check uses only the joined body | T16 (one-line case) |
+| M17 | stdin leak check removed | T17 |
+| M18 | `finally` cleanup removed | T18 |
+| M19 | key passed with `-i` from a temp file left on disk | T18, T19 |
+| M20 | output cap removed | T13 |
+| M21 | timeout kill removed | T12 |
+| M22 | busy check removed | T20 |
+| M23 | revoke doesn't kill the in-flight call | T21 |
+| M24 | event records stdout | T22 |
+| M25 | each value check removed, one mutant each (encrypted, type, count, CRLF) | T4 |
+| M26 | `organization.set` accepts `hosts` | T3 |
+| M27 | load check for a definition without `host` removed | T2 |
+| M28 | shell and runner check removed, and a second mutant compares `argv[0]` without taking the basename | T26 |
+| M29 | glob character check removed | T26 |
+| M30 | `requested` event drops argv | T22 |
+| M31 | the question omits stdin | T9 |
+| M32 | `--pdeathsig` dropped from the spawns | T27 |
+| M33 | `ssh-add` without `-t` | T27 |
+| M34 | start sweep removed, a second mutant sweeps without checking the bus pid, and a third ignores the start time | T27 |
+| M35 | loopback check removed | T1 |
+
+The mutant script follows row 201's shape: copy the packages to scratch, anchor each mutant once, run each
+test file in its own process group with a timeout, control first, exit 1 on any survivor. It runs on Sage's
+slot.
+
+## 10. Questions
+
+- Q-S1, answered (sage-1450): 1.7 is frozen. Hard wait under 1.7, and section 5 holds the 1.8 proposal.
+- Q-S1 still holds after 1.7's approval, which doesn't route `host.sudo` (sage-1468).
+- Q-S2, answered (sage-1450): 199's deviation 11 keeps credential use in the bus child, so D5 stays.
+- **Q-J0 (Jason, through Mos, before landing, B4, mos-1088).** Word for word:
+
+  > Q-J0 (#424). Who may give an agent sudo on another machine?
+  > Proposal: only you. No agent can, and that includes the chief of staff and the tester.
+  > You make a grant in four steps, all yours. A reviewed change to the agent's role allows machine keys at all.
+  > You list the machine and its fingerprint. You give that agent that machine with an exact list of allowed
+  > commands. You issue the key, and ops-01 installs it. Until a later PRD says otherwise, you also approve
+  > each command before it runs. You, Mos or the tester can revoke at once. The stack drops the key and cuts
+  > its connection. A command already started on the machine may keep running. A grant of "any" command is
+  > root on that machine, so the design refuses it. Some listed commands, such as a file writer, still reach
+  > root, so grant a machine only to an agent you'd trust as root there.
+  > Do you approve: only you grant machine access, as above? Yes or no. I recommend yes.
+
+  Mos records the answer in DECISIONS.md in jason-master-restart.
+- **Q-J1 (Jason, through Mos, at the live window):** the first grants, each an argv allowlist per agent and
+  host. Not needed for the build.
+- Q-S3, answered (sage-1468): the `host_run` harness tool is out of this row. Sage files a follow-up row for
+  publish and `host_run` in `packages/harness` (scope line at the top).