Distillation

Date: Sep 8, 2026

• 🟡 (06:45) Review task status: “Inventory and hash exact review files, changed artifacts, binaries, and build metadata” was in_progress; four high-priority tasks remained pending: 1. trace plugin/transport/helper/supervisor/systemd-unit/cutover protocol end to end, 2. verify pinned Go, godbus, go-systemd, Node APIs, systemd property semantics, and binary provenance, 3. run unprivileged tests and reproducible source builds and compare binary hashes, 4. review tests/documents for realism and issue the classified verdict.
• 🟡 (06:45) Exact supervisor inventory contained 22 files: 1. /home/byk/.local/share/opencode-v2-pilot/supervisor/ROOT-ACCEPTANCE.md, 2. /home/byk/.local/share/opencode-v2-pilot/supervisor/PROTOCOL.md, 3. /home/byk/.local/share/opencode-v2-pilot/supervisor/bin/opencode-pty-client, 4. /home/byk/.local/share/opencode-v2-pilot/supervisor/bin/opencode-pty-launcher, 5. /home/byk/.local/share/opencode-v2-pilot/supervisor/bin/opencode-pty-supervisor, 6. /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty.slice, 7. /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty-supervisor.service, 8. /home/byk/.local/share/opencode-v2-pilot/supervisor/go.sum, 9. /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/client/main_test.go, 10. /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/client/main.go, 11. /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/supervisor/main.go, 12. /home/byk/.local/share/opencode-v2-pilot/supervisor/go.mod, 13. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/auth_test.go, 14. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server.go, 15. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/auth.go, 16. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/systemd.go, 17. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server_test.go, 18. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/systemd_test.go, 19. /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/launcher/main.go, 20. /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/launcher/main_test.go, 21. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/protocol/frame_test.go, 22. /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/protocol/frame.go.
• 🟡 (06:45) /home/byk/.local/share/opencode-v2-pilot/supervisor/go.mod defines module opencode-pty-supervisor, Go 1.22, and pins github.com/coreos/go-systemd/v22 v22.5.0, github.com/godbus/dbus/v5 v5.1.0, and golang.org/x/sys v0.20.0.
• 🟡 (06:45) /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/protocol/frame.go defines a 12-byte OPTY protocol header, version 1, MaxFrameSize = 70 * 1024, MaxIOPayloadSize = 32 * 1024, and frame types in exact order: TypeStart=1, TypeInput=2, TypeOutput=3, TypeExit=4, TypeError=5, TypeStarted=6, TypeStop=7, TypeStopped=8.
• 🟡 (06:45) Protocol START limits in internal/protocol/frame.go are MaxArgs=128, MaxCommandSize=4096, MaxArgSize=16384, MaxArgsSize=65536, and MaxRuntimeSec=3600; START contains Device uint64, Inode uint64, RuntimeSec uint32, Command string, and Args []string.
• 🟡 (06:45) EncodeStart() and DecodeStart() reject empty commands, NUL-containing or invalid-UTF-8 commands/arguments, oversized commands/arguments/aggregate argument data, more than 128 arguments, runtimes over 3600 seconds, malformed lengths, trailing payload bytes, and frames over 70 KiB. Header parsing rejects wrong magic/version, nonzero reserved bytes 6–7, oversized payloads, and unknown frame types.
• 🟡 (06:45) /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/auth.go authenticates Unix peers using both SO_PEERCRED and SO_PEERPIDFD, requires positive PID plus exact expected UID/GID, and validates the peer PID against systemd’s current client-service MainPID; it also requires ActiveState="active", SubState="running", exact expectedClientCgroup, and a 16-byte InvocationID.
• 🟡 (06:45) authenticatedPeer.Recheck() verifies pidfd liveness with unix.PidfdSendSignal(peer.pidfd, 0, nil, 0), fetches fresh ClientState, reruns identity validation, and rejects an InvocationID change during admission. peerIdentity() applies close-on-exec to the obtained pidfd, and authenticatedPeer.Close() closes it once and sets it to -1.
• 🟡 (06:45) /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server.go configures /run/opencode-pty/supervisor.sock, maxSessions=16, maxUnauthenticated=32, maxAdmissionsPerMinute=120, socketBufferSize=128 * 1024, and handshakeTimeout=5s; NewServer() resolves account byk to the expected UID/GID.
• 🟡 (06:45) Server.Serve() requires effective UID 0, treats startup CleanupOrphans() failure as fatal before listening, removes an existing socket only when it is actually a socket, creates the Unix listener, and chmods the socket to 0660.
• 🟡 (06:45) Admission handling limits concurrent unauthenticated connections to 32 and applies a rolling one-minute cap of 120 admissions. After successful authentication it releases the unauthenticated slot, then admits at most 16 active sessions; socket read/write buffers are set to 128 KiB and authentication plus START receipt occur under a 5-second connection deadline.
• 🟡 (06:45) Session startup flow in server.go: authenticate peer → receive and validate START plus exactly one cwd fd → clear the deadline → generate opencode-pty-<32 lowercase hex digits>.service-style random unit name from 16 cryptographic random bytes → create a CLOEXEC Unix stream socket pair → recheck authenticated peer identity → call manager.Start() with command, args, transferred stream, cwd, and runtime → close the transferred stream locally → emit TypeStarted containing the unit name.
• 🟡 (06:45) receiveStart() accumulates ancillary rights across exact header/payload reads, rejects MSG_TRUNC/MSG_CTRUNC, rejects more than one received fd, requires a TypeStart frame and exactly one fd, wraps it as approved-cwd, and verifies it is a directory whose Stat_t.Dev and inode exactly match the START payload. Recvmsg uses MSG_CMSG_CLOEXEC.
• 🟡 (06:45) Session I/O behavior in server.go: copyInput() accepts only nonempty TypeInput payloads up to protocol.MaxIOPayloadSize, except an empty TypeStop triggers errStopRequested; copyOutput() emits PTY reads as TypeOutput frames up to 32 KiB; frameWriter serializes writes with a mutex and applies operationTimeout as the write deadline.
• 🟡 (06:45) serveSession() concurrently runs client-input copying, PTY-output copying, disconnect watching, and manager.Wait(). Disconnect detection duplicates the socket fd with F_DUPFD_CLOEXEC, polls every 250 ms for POLLRDHUP|POLLHUP|POLLERR, and reports client disconnection on EOF/hangup.
• 🟡 (06:45) Stop handling calls cleanup, drains remaining PTY output under outputDrainTimeout, shuts down the stream on drain timeout, then emits TypeStopped. Normal unit completion calls cleanup, drains final PTY output under the same timeout, then emits TypeExit; encodeExit() serializes one byte of ExecMainCode, four bytes of ExecMainStatus, a four-byte result-string length, then the result bytes.
• 🟡 (06:45) Error-path cleanup is guarded by sync.Once; cleanup failures after session errors are escalated through server.fail(), which logs the error, sends one fatal error via fatalOnce, and closes the listener and all tracked client connections. Protocol error text is truncated to 32 KiB while preserving valid UTF-8.