Specify and plan M3b: the runner and the tools

A draft spec for the owner's review and 13 offline tasks with their given
tests: shared tool arguments and host rules in proto, the sealed fetch
target (M3a finding 14), the toolkit tools and SOCKS5 egress proxy, and
brokerd's [runner], podman argument lists, runtime and proxy lifecycle. Each
task's tests were run against a reference at that task's end state (560 to
638 tests, clippy clean); the reference is not in the repository. Adds the
runner-unavailable runbook entry and tip T23 (ETXTBSY in script tests).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-22 22:29:27 -07:00
co-authored by Claude Opus 5.5
parent d988edac4a
commit b426ca1958
47 changed files with 4491 additions and 2 deletions
+26 -1
View File
@@ -33,7 +33,7 @@ bxctl grants check
It prints each problem as `<file>:<line>: <problem>`. Common ones: a misspelled field (unknown
fields are errors); `secret` set (not supported until M4); `patterns` set (not supported); `hosts`
on a file tool or `paths` on `http_fetch`; a relative path or one with `..`, `.` or `//`; the path
on a file tool or `paths` on `http_fetch`; a relative path or one with `..`, `.` or `//`; a path with `:` or `,` (it cannot be mounted); the path
`/` (grant the directories you mean); a `deny` grant whose `max_taint` is not `"secret"` (it would
stop denying once the session read a secret); a host with uppercase letters, a port, or an IP
address; a file name with characters outside `[a-z0-9-]`.
@@ -229,6 +229,31 @@ the limit. Then start `brokerd` again if it exited.
**Check.** `brokerd` prints `serving tools on …`, and a tool call is decided again.
## runner-unavailable
**What you see.** A tool call fails with "the tool runner could not start the container", and
`brokerd` prints what Podman said, then this entry.
**Why.** `brokerd` asked Podman to start the tool's container, or for `http_fetch` the egress
proxy's, and Podman could not: the program is missing, the image in `[runner] image` is not
loaded, the proxy's network does not exist, or the proxy did not create its socket in time.
Nothing ran for the call.
**Confirm.**
```sh
podman --version # the program [runner] podman names
podman image inspect --format '{{.Digest}}' <image> # must be the digest in [runner] image
podman ps -a --filter label=boxmaker # containers left behind, if any
```
**Fix.** Install Podman or correct `[runner] podman`. Load the image built from
`deploy/tools-image.nix` (`podman load < result`) and put its digest in `[runner] image`. For the
proxy, check that `[runner] egress_network` names a network Podman has (`pasta` needs the `passt`
package). Remove leftovers with `podman rm -f` on the listed names.
**Check.** Ask for a `read_file` the grants allow; it returns the file.
## broker-state-damaged
**What you see.** `brokerd` prints an error reading or writing