review: silkd zero-copy fan-out and upload decode, claim_ref_prefix wire pin, docs sync, deps

.github/workflows/build-boot.yml

@@ -62,7 +62,7 @@ jobs:
         run: echo "kernel=$(cat boot/kernel/VERSION)" >> "$GITHUB_OUTPUT"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0
@@ -73,7 +73,7 @@ jobs:
 
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: boot
           file: boot/Dockerfile
@@ -126,7 +126,7 @@ jobs:
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0

.github/workflows/build-os-images.yml

@@ -174,10 +174,10 @@ jobs:
           echo "silkd=$(sed -n 's/^version = "\(.*\)"/\1/p' silkd/Cargo.toml | head -1)" >> "$GITHUB_OUTPUT"
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4.3.0
+        uses: docker/setup-qemu-action@v4.4.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0
@@ -225,7 +225,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Build and push
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: os-image/${{ matrix.name }}
           file: os-image/${{ matrix.name }}/${{ matrix.tag }}/Dockerfile
@@ -265,10 +265,10 @@ jobs:
         run: echo "silkd=$(sed -n 's/^version = "\(.*\)"/\1/p' silkd/Cargo.toml | head -1)" >> "$GITHUB_OUTPUT"
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4.3.0
+        uses: docker/setup-qemu-action@v4.4.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0
@@ -316,7 +316,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Build and push
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: os-image/${{ matrix.name }}
           file: os-image/${{ matrix.name }}/${{ matrix.tag }}/Dockerfile

.github/workflows/build-silkd.yml

@@ -54,7 +54,7 @@ jobs:
         uses: actions/checkout@v7.0.1
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0
@@ -65,7 +65,7 @@ jobs:
 
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@v7.3.0
+        uses: docker/build-push-action@v7.4.0
         with:
           context: silkd
           file: silkd/Dockerfile
@@ -115,7 +115,7 @@ jobs:
           merge-multiple: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@v4.6.0

.github/workflows/publish-pypi.yml

@@ -58,7 +58,7 @@ jobs:
           # The in-repo base SDK installs first, so an adapter release never
           # resolves (or fails to resolve) cocoonstack-sandbox from PyPI.
           python -m pip install -q ./sdk/python
-          python -m pip install -q "${{ steps.pkg.outputs.dir }}" ruff==0.15.20 pytest==8.4.2
+          python -m pip install -q "${{ steps.pkg.outputs.dir }}" ruff==0.15.22 pytest==8.4.2
           (cd "${{ steps.pkg.outputs.dir }}" && ruff check . && python -m pytest -q)
 
       - name: Build sdist + wheel

.github/workflows/python.yml

@@ -33,7 +33,7 @@ jobs:
         with:
           python-version: "3.12"
       - name: Install tooling
-        run: pip install ruff==0.15.20 pytest==8.4.2 mypy==1.19.1 && pip install -e sdk/python -e sdk/openai -e sdk/langchain
+        run: pip install ruff==0.15.22 pytest==8.4.2 mypy==1.20.2 && pip install -e sdk/python -e sdk/openai -e sdk/langchain
       - name: Lint
         run: ruff format --check . && ruff check .
       - name: Test cocoonsandbox

.github/workflows/release.yml

@@ -33,9 +33,9 @@ jobs:
           tar -C silkd/target/x86_64-unknown-linux-musl/release \
             -czf "dist-extra/silkd_Linux_x86_64.tar.gz" silkd
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4.3.0
+        uses: docker/setup-qemu-action@v4.4.0
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4.3.0
+        uses: docker/setup-buildx-action@v4.4.1
       - name: Build silkd (musl static, arm64)
         # Emulated cargo build via the carrier Dockerfile — byte-consistent
         # with the image artifact; slow but release-rare.
@@ -49,6 +49,7 @@ jobs:
       - name: goreleaser
         uses: goreleaser/goreleaser-action@v7.2.3
         with:
+          version: v2.18.2
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ github.token }}

README.md

@@ -173,6 +173,7 @@ working — images built here boot with an unmodified cocoon.
 
 The server stack — sandboxd, silkd, the boot chain, the OS images, and the
 MCP server — is licensed under [AGPL-3.0](LICENSE). The client SDKs
-(`sdk/go`, `sdk/python`, `sdk/openai`, `sdk/langchain`) are licensed under
-Apache-2.0 (see the `LICENSE` file in each directory), so embedding a
-client in a proprietary agent stack carries no copyleft obligation.
+(`sdk/go`, `sdk/python`, `sdk/openai`, `sdk/langchain`) and the
+`protocol/wire` module the Go SDK requires are licensed under Apache-2.0
+(see the `LICENSE` file in each directory), so embedding a client in a
+proprietary agent stack carries no copyleft obligation.

boot/Dockerfile

@@ -4,7 +4,7 @@
 # under /boot/ for os-image builds to COPY --from. Built per-platform on
 # native runners (a kernel build under QEMU emulation takes hours).
 
-FROM debian:12.15-slim@sha256:88200866dfff7ea7f5cbcb6ec7c8a701889efe6fe859fe64d6990e4b07ea4171 AS kbuild
+FROM debian:12.15-slim@sha256:3783cc01769c7b2b1b83a5c5ad96c815348e28ed7da68e2e3687004faa906251 AS kbuild
 RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential bc bison flex libelf-dev libssl-dev \
     xz-utils curl ca-certificates python3 \
@@ -84,7 +84,7 @@ COPY init/Cargo.toml init/Cargo.lock ./
 COPY init/src ./src
 RUN cargo build --release --locked && cp target/release/sandbox-init /sandbox-init
 
-FROM busybox:musl@sha256:32b5cdad7cce41dfd53d0ae06baebcf8357a147ee7694dc706911c373bc30c37 AS bb
+FROM busybox:musl@sha256:ea2b9914a16a4ac1981994af97b318f7c7d4db76b580c56177f08bf76f4a0be8 AS bb
 
 FROM kbuild AS pack
 ARG INITRD_DEBUG=0

docs/benchmarks.md

@@ -66,11 +66,10 @@ builds one warm pool (small, the warm tier), one golden-only pool
 (medium, warm=0 — every claim is a clone), claims the cold tier from an
 unpooled template, then measures the data plane (`fs_stat` round-trips via
 `rpcbench`, `fs_pull` throughput via `pullbench`). `rpcbench` prints A
-(dial per RPC), C (the current SDK keep-alive path), and B (a pre-dialed
-spare); `make bench` keeps A in its table so new runs remain comparable with
-the dated log below. It prints a markdown table stamped with the host evidence:
-virtualization (`systemd-detect-virt`), CPU, kernel, cocoon version, image
-digest.
+(dial per RPC) and C (the current SDK keep-alive path); `make bench` keeps A
+in its table so new runs remain comparable with the dated log below. It
+prints a markdown table stamped with the host evidence: virtualization
+(`systemd-detect-virt`), CPU, kernel, cocoon version, image digest.
 
 Knobs (environment variables): `WARM`/`WARM_N` (warm-pool depth and burst
 size — the burst must stay within the depth, or refill loses the race and

docs/browser.md

@@ -52,9 +52,9 @@ through an authorized claim and never sits on a guest NIC.
 
 ## Checkpoint / branch a live browser
 
-`sb.Checkpoint` + `ck.New` fork a warmed browser — in-memory tabs,
-cookies, localStorage — in checkpoint-restore time; the branch answers
-`/json/version` without relaunching Chrome. Hosted browser services
+On the `none` lane, `sb.Checkpoint` + `ck.New` fork a warmed browser —
+in-memory tabs, cookies, localStorage — in checkpoint-restore time; the
+branch answers `/json/version` without relaunching Chrome. Hosted browser services
 cold-start a browser per session; here a warmed profile is a template you
 branch from.
 

docs/egress.md

@@ -296,17 +296,19 @@ baked into a guest **when the guest is created** — at golden build, or at a
 pre-golden cold claim's provision (both via silkd; only the golden-build
 install is off the claim path). It is
 **not** re-installed on re-claim: a clone, checkpoint restore, archive wake, or
-reconcile adopts the guest with whatever root it was born with. A `.cafp`
-sidecar ties golden adoption to the baked bytes, so a changed root rebuilds
-goldens — but nothing rebuilds an existing checkpoint, archive, promoted
-template, or live/hibernated claim. Because the baked cert is the shared cluster
-root, promote/checkpoint/archive carry no node-private material and stay
-unrestricted.
+reconcile adopts the guest with whatever root it was born with. Each golden's
+`.stamp` file records what it baked (the root fingerprint, the lane verdict,
+and the warmup argv), and a golden is adopted only when its stamp exists and
+matches, so a changed root rebuilds goldens; a golden from before the stamp
+has none and is rebuilt once. Nothing rebuilds an existing checkpoint,
+archive, promoted template, or live/hibernated claim. Because the baked cert
+is the shared cluster root, promote/checkpoint/archive carry no node-private
+material and stay unrestricted.
 
 **Intermediate rotation is seamless.** Issue a fresh intermediate from the same
 root, point the node's config at it, restart: leaves still chain to the root
-every guest already trusts, and `.cafp` (the root fingerprint) is unchanged, so
-no golden rebuilds.
+every guest already trusts, and the root fingerprint in each golden's `.stamp`
+is unchanged, so no golden rebuilds.
 
 **Root rotation needs a drain, not a hot swap.** A guest verifies leaves only
 against the root(s) it was born with, so the node's leaves must chain to a root

docs/performance.md

@@ -74,7 +74,8 @@ SDKs keep one relay connection per handle with a 30s idle window.
 `e2e/cmd/rpcbench`, warm `rt:24.04` sandbox, `net=none`, n=200 `fs_stat`
 RPCs per arm, cocoon-test1 bare metal, client on the node, 2026-09-16 at
 5158a14. The two arms interleave sample by sample and swap which one leads,
-so drift cannot land on one of them.
+so drift cannot land on one of them. The pre-dialed spare row is a third arm
+that rpcbench ran after them at that commit and no longer carries.
 
 | per-RPC wall | plain p50 | plain p90 | TLS edge p50 | TLS edge p90 |
 | --- | --- | --- | --- | --- |
@@ -173,11 +174,11 @@ That experiment rejected the background pre-dialer because its ~0.2ms p50 win
 did not survive the tail. Current main instead implements protocol-level
 sequential reuse: silkd proto 2 serves RPCs back to back and each SDK handle
 parks completed relay connections for its next call. This is neither the
-pre-dialer nor concurrent multiplexing. `e2e/cmd/rpcbench` reports all three
-paths as A (dial per RPC), C (SDK keep-alive), and B (pre-dialed spare); the
-current numbers are in Relay connection reuse above, and they keep the
-pre-dialer declined — behind a TLS edge it tracks the dial arm, because it
-hides a handshake only while RPCs arrive slower than a dial completes.
+pre-dialer nor concurrent multiplexing. `e2e/cmd/rpcbench` reports A (dial
+per RPC) and C (SDK keep-alive); the numbers in Relay connection reuse above,
+the pre-dialed spare row included, keep the pre-dialer declined — behind a TLS
+edge it tracks the dial arm, because it hides a handshake only while RPCs
+arrive slower than a dial completes.
 
 **Template pre-check meta GET**: a single `ReadMeta` against MinIO
 measured 4.76ms cross-host (sub-ms node-local, 20-50ms on WAN S3; a

docs/silkd.md

@@ -44,7 +44,7 @@ suites — a frame only one side can parse fails CI.
 | group | ops | response flow |
 |---|---|---|
 | exec | `exec {argv, cwd?, env?, user?, detach?, session?}` | `started{pid}` → `stdout/stderr{data}`… → `exit{code}`; the client may stream `stdin{data}` / `stdin_close`. `detach` returns after `started`; the process keeps a bounded output ring for later `logs`/`attach` and leaves the table 5 minutes after it exits, after which its pid answers `not_found`; not combinable with `session`. With `session` only `argv` is used — `cwd`, `env`, `user` and `stdin` frames are ignored (the session owns them, and its commands read `/dev/null`) — no `started` is sent, and stderr arrives merged into `stdout`. A child's environment is cleared to `PATH`, `TERM` and the lane's proxy variables plus `env`; `HOME` and `USER` are set only with `user` |
-| procs | `ps` / `kill {pid, signal?}` / `attach {pid}` / `logs {pid}` | `ps` answers one `procs{procs}` frame, `kill` a bare `done`; `logs` and `attach` stream `stdout/stderr{data}`… then `exit{code}` (`logs` closes with `done`, and so does `attach` when the process is gone before its exit). Handles are guest pids; any connection can list, signal, replay, or re-attach live |
+| procs | `ps` / `kill {pid, signal?}` / `attach {pid}` / `logs {pid}` | `ps` answers one `procs{procs}` frame, `kill` a bare `done`; `logs` replays `stdout/stderr{data}`…, adds `exit{code}` once the process has exited, and closes with `done`; `attach` replays and follows `stdout/stderr{data}`… to `exit{code}`, or to `done` when the process is gone before its exit. Handles are guest pids; any connection can list, signal, replay, or re-attach live |
 | sessions | `session_create {id?, cwd?, env?}` / `session_list` / `session_rm {id}` | `session_created{id}` / `sessions{sessions}` / `done`. A session is a real persistent bash; `exec` with `session` runs inside it. Idle sessions are reaped after 30 minutes |
 | fs | `fs_write {path, mode?}` (+`data`/`data_end` frames) / `fs_read` / `fs_list` / `fs_stat` / `fs_mkdir {parents?}` / `fs_rm {recursive?}` / `fs_rename {from, to}` | `fs_read` streams `data{data}`… → `done` for a regular file and answers `bad_request` for a directory, device or FIFO, `fs_list` streams 4096-entry `entries{entries}` batches → `done`, `fs_stat` answers one `stat{info}`, and the mutating verbs terminate with `done`. Streaming runs both directions; write commits atomically via temp+rename and inherits an overwritten file's mode |
 | tree | `fs_push {dest}` (+tar as `data` frames) / `fs_pull {path}` | whole trees as tar streams through the guest tar: `fs_pull` streams `data{data}`… → `done`, `fs_push` terminates with `done` |

e2e/cmd/egresssmoke/main.go

@@ -36,7 +36,7 @@ func main() {
 	template := flag.String("template", "rt:24.04", "template with an egress policy")
 	wantToken := flag.String("secret", "", "the value the origin should observe injected")
 	netShape := flag.String("net", "none", "claim lane: none|egress")
-	reach := flag.String("reach", "127.0.0.1", "host the guest reaches the origin at (policy must allow it)")
+	reach := flag.String("reach", "127.0.0.1", "host the guest reaches the origin at")
 	nicAddr := flag.String("nicaddr", "", "static CIDR to bring the egress-lane NIC up with (default route via -reach)")
 	guarded := flag.Bool("guarded", true, "pool has an egress policy; false asserts the unlocked NIC reaches directly (negative control)")
 	echo := flag.String("echo", "postman-echo.com", "public HTTP host echoing request headers at /get, for the injection check")
@@ -122,18 +122,13 @@ func run(addr, token, template, wantToken, netShape, reach, nicAddr, echo string
 	return nil
 }
 
-// startOrigin serves one echo endpoint that returns the credential header the
-// proxy injected, on a host-local port.
+// startOrigin serves the host-local negative control, answering REACHED to a guest that dials it directly.
 func startOrigin() (*http.Server, int, error) {
 	ln, err := net.Listen("tcp", "0.0.0.0:0") //nolint:gosec // test origin the egress-lane guest reaches via the bridge
 	if err != nil {
 		return nil, 0, err
 	}
-	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if v := r.Header.Get("X-Egress-Token"); v != "" {
-			_, _ = io.WriteString(w, v) //nolint:gosec // test origin echoing the token we injected
-			return
-		}
+	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		_, _ = io.WriteString(w, "REACHED")
 	}), ReadHeaderTimeout: 10 * time.Second}
 	go func() { _ = srv.Serve(ln) }()

e2e/cmd/portsmoke/main.go

@@ -34,8 +34,6 @@ const (
 	claimTTL = 30 * time.Minute
 )
 
-var guestServerMode = uint32(0o755)
-
 func main() {
 	addr := flag.String("addr", "127.0.0.1:7777", "sandboxd address")
 	token := flag.String("token", "", "node api token")
@@ -111,7 +109,7 @@ func startGuestListener(ctx context.Context, sb *sandbox.Sandbox, listener strin
 	if err != nil {
 		return fmt.Errorf("read listener: %w", err)
 	}
-	if err := sb.WriteFile(ctx, guestServerPath, bin, &guestServerMode); err != nil {
+	if err := sb.WriteFile(ctx, guestServerPath, bin, new(uint32(0o755))); err != nil {
 		return fmt.Errorf("upload listener: %w", err)
 	}
 	argv := []string{

e2e/cmd/rpcbench/main.go

@@ -1,14 +1,12 @@
-// rpcbench measures the one-connection-per-RPC overhead on a live node and
-// what the alternatives buy: mode A dials+upgrades per RPC by hand; mode C
-// is the SDK's own path, one kept connection serving RPCs back to back; mode
-// B keeps one hand-dialed connection ahead, hiding the handshake behind the
-// previous call (H-4's decision data). A and C interleave sample by sample
+// rpcbench measures the one-connection-per-RPC overhead on a live node: mode
+// A dials+upgrades per RPC by hand; mode C is the SDK's own path, one kept
+// connection serving RPCs back to back. A and C interleave sample by sample
 // and swap which one leads, so node drift cannot land on one arm. Run by
 // hand against a claimed sandbox:
 //
 //	rpcbench -addr <node> -token <api token> -template <ref> -n 200
 //
-// An https:// address drives both hand-dialed modes through the TLS edge the
+// An https:// address drives the hand-dialed mode through the TLS edge the
 // SDK already uses, so A pays a handshake per RPC the way a real client does.
 package main
 
@@ -108,40 +106,6 @@ func run(addr, token, template, caCert string, n int) error {
 	}
 	report("A dial-per-RPC", a)
 	report("C SDK keep-alive", c)
-
-	spare := make(chan net.Conn, 1)
-	errs := make(chan error, 1)
-	go func() {
-		for {
-			conn, err := dial()
-			if err != nil {
-				errs <- err
-				return
-			}
-			select {
-			case spare <- conn:
-			case <-ctx.Done():
-				_ = conn.Close()
-				return
-			}
-		}
-	}()
-	b := make([]time.Duration, 0, n)
-	for range n {
-		start := time.Now()
-		var conn net.Conn
-		select {
-		case conn = <-spare:
-		case err := <-errs:
-			return err
-		}
-		if err := statRPC(conn); err != nil {
-			return err
-		}
-		b = append(b, time.Since(start))
-	}
-	cancel()
-	report("B pre-dialed spare", b)
 	return nil
 }