review: images, CI, docs and the Python SDK

[CMGS]

The non-code and Python half of the LOC-justify round: four judgment lenses over the images and packaging, the workflows and Makefile and scripts, the docs against the code, and the Python SDK; every finding re-read in source before it landed. Nine commits, one purpose each. Nothing here touches sandboxd, silkd or the Go SDK.

Bugs

• android: every pty failed at spawn. pty_open runs $SHELL and falls back to /bin/bash; the android userspace has neither the variable nor bash, and silkd.rc set only SILKD_PORT and the proxy trio. The init service now sets SHELL=/system/bin/sh. The android smoke only runs exec, which is why nothing caught it; a hardware check of the android pty needs the android lane, which this round's kit does not have — not run.
• Python SDK: a read on a closed connection raised a bare ValueError outside the SandboxError hierarchy (Conn.recv caught OSError only); it is a ProtocolError now.
• Python SDK: timeout bounded each read of the dial, not the dial. docs/sdk-python.md promises it bounds the dial and upgrade; a node answering one header line per interval stretched a 0.2 s dial indefinitely — the "socket timeout is not a deadline" class from the last round, surviving in one place. The dial now spends every step from one deadline. A single header line trickled byte by byte is still bounded per read; that takes a hostile node.
• scripts/bench.sh ran under pipefail with one unguarded pipeline on its results step; a host without cocoon lost the whole bench there.
• make base passed no INPUTS_HASH, so a local edit to the secret-mounted install-agent.sh silently rebuilt against the cached layer; the target now computes the same content hash CI does.

Reproducibility and CI

• The four Rust gate workflows ran cargo clippy/cargo test without --locked while release.yml and both Dockerfiles have it; the PyPI gate installed pytest and ruff unpinned where python.yml pins them.
• python.yml ran on every branch push (twice per PR push); images.yml, silkd.yml and boot-init.yml did not list their own definitions in their path filters, so a change to how an image is built rebuilt nothing.
• A README edit under os-image/desktop/ forced an uncached rebuild of the heaviest image (the depth-3 cache-bust rule and the inputs hash both counted markdown); markdown stays out of both now.
• The desktop image fetched Chrome's signed apt repo over http while the base image had just moved every source to https; one duplicated kernel-config assertion; the images target's help line said "all VM images" for two of nine.

Python SDK hot path

decode_response's slice-and-b64decode(validate=True) fast path is 1.5× slower than json.loads below Python 3.11, where validation is a regex scan (py3.9 1258 vs 839 µs per 256 KiB frame, ABAB best of five), and 0.55–0.58× on 3.11/3.12. The package supports 3.9+; the fast path is gated on 3.11.

Docs

The README boot table promised sandbox.debug/sandbox.trace beside the Firecracker lane, but the pinned kernel builds no 8250 UART and cocoon boots that lane with console=ttyS0, so nothing they write is visible there; said now. The three error tables did not name the exec/pty user field (an unresolvable user is a bad_request; the guest distinguishes an unknown name from a failing name service). SandboxTimeout was missing from the Python errors list; ringsmoke from the e2e roster.

Owner calls, recorded in the round artifact rather than changed

FC lane console (+2 kernel config lines vs a boot-time cost); node-rt/python-rt built in parallel from byte-identical RUN blocks while the README says "same rootfs squashed"; flavors FROM base:24.04 (mutable; a branch dispatch can race a main run); ANDROID_BASE_IMAGE unpinned; asl has no CI step; mypy runs on sdk/python only; shellcheck and the 55 uses: lines are tag-pinned, not SHA; the Rust gate runs twice per push (silkd.yml ≡ build-silkd.yml); Python session exec puts the merged log in .stdout where Go puts it in Stderr; the 8 KiB makefile buffer on the relay (measure on Linux TCP first); cocoon.timeout/sandbox.init cmdline keys have no producer in either repo.

Evidence

Python, in a venv mirroring python.yml (3.12, ruff 0.15.20, pytest 8.4.2, mypy 1.19.1): ruff format --check and ruff check clean; sdk/python 215 passed (213 + the two new tests, the dial test shown failing on the previous code), mypy clean, openai 10 and langchain 14 passed. make sh-lint exit 0, all eleven workflow files parse, bash -n on the touched script, make help and make -n base render the new argument. No Go or Rust source changed. Main's own artifacts (e8de664) passed the seven-leg E2E, the ring leg and the two-node cluster phases on cocoon-test1/test2 earlier today; this branch adds no runtime change on those lanes beyond the android init file.