review: whole-repo round after #329 (style, cuts −44 prod, OpenPty takes wire.PtyOpen)

[CMGS]

What

Review round over the 42 files the hygiene ledger listed as due after #315–#329 (the perf batch): style, comments, LOC/cut-list, plus correctness review of the 22 production files. No behavior change.

Three commits:

• review: (6523d8c), style and layout:
  • relayEnds moves above the Server methods it was splitting, and relay.go's free funcs move below auditTee's method set.
  • KeptNode and FakeAgent move above their tests.
  • Func types spelled out twice get names: bulkMaker, chunkSink.
  • Multi-fact godocs and module docstrings shrink to one line.
  • belowFloor no longer shadows comparable.
  • Tests reuse breakStore and waitFor, and a helper comment that only restated its name is gone.
• cut: (6ad8796), cut-list and /simplify:
  • DecodeResponse calls DecodeResponseInto(line, nil), so the private decodeResponse layer goes away; decodeAs is inlined.
  • The SDK's three recv helpers become one transient read.
  • reapOnce collects purge checkpoints inside its locked scan.
  • ReadFile reuses ReadFileTo, and archiveEnabledFor is inlined.
  • Two tests share one upload fake, and the upgrade test uses the existing black_hole fixture.
• cut: (OpenPty): OpenPty takes wire.PtyOpen directly, and the field-for-field PtyOpts copy is deleted. This is a breaking change for SDK callers (sandbox.PtyOpts{...} becomes wire.PtyOpen{...}), approved for the next release; docs and the e2e smoke are updated.
• review: (43279d5), doc fix: resolve_program's doc no longer claims full execvp equivalence. Unlike execvp, it does not move on to the next PATH entry when a candidate's exec fails with ENOENT.

Net LOC: prod −44, test −29. Comment lines in Go/Rust: +8 −13; most of the + side is relay.go comments moving with their code.

Why the recv merge is safe

Every read now goes through RecvTransient, so a bulk frame's Data is valid only until the next read.

• Bulk frames (stdout, stderr, data) reach only streaming consumers: drainData, pumpStdio, and the pty and port drains. Each hands the bytes to an io.Writer or a pipe before reading again.
• ReadFile copies into its own buffer.
• The remaining reads (expect, streamRPC/collectRPC, watch) only ever see non-bulk types: Done, Info, Stat, Entries, Match, Event and so on.

Findings adjudicated but not applied

• Correctness reviewers (Go correctness and concurrency, SDK/wire contract, Rust ownership, async and hot path) reported no P1 or P2. The only P3 is the execvp ENOENT fall-through above. It is kept as is because it matches bash's PATH lookup and needs a broken interpreter to trigger.
• Contract godocs stay multi-line, because the frame sequence and token handling don't fit one line: PortForward, GitClone, silkd.Conn, Client.__init__.
• frame.go's const-group labels stay. They map each group to its wire field and its Rust enum.
• resolve_program stats on the runtime thread. That is a few µs per PATH entry; spawn_blocking would cost more than the posix_spawn it enables saves.
• fs.rs String parameters stay as they are: the strings are moved out of a consumed request, so nothing is copied.
• The idle-sweep any-pool check stays. The proposed rewrite is not shorter and saves one tiny allocation every 5 s.
• settlePendingSnap → resolvePendingSnap merge is not done, because it would reorder the hibernate usage event ahead of the claims commit.
• The shardOf empty guard stays. Without it, a wrong assumption becomes a divide-by-zero panic on the claim path.
• Python test fixture consolidation is skipped: it is structure-only churn with no defect.
• The asl forwarder findings (skipIdle, refillGated, benignSweepErr) were already recorded as KEPT in the ledger.

Gates

• Lint and asl:
  • make go-lint: 10× 0 issues.
  • asl on darwin and linux: clean for wire, sandboxd and sdk/go.
• Go:
  • go test -race for wire, sandboxd, sdk/go, e2e and mcp: passes on macOS and on linux/arm64.
  • TestCaddyTLSCluster with Caddy 2.11.4: passes.
• Rust (silkd): cargo fmt --check, clippy -D warnings and cargo test pass on macOS and in a linux/arm64 rust:1.98.1 container.
• Python: ruff format --check, ruff check, mypy and pytest (234 passed) pass on macOS and linux/arm64.