Distillation

Date: Sep 8, 2026

• 🟡 (07:13) Inspection of /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/auth.go showed authenticate() obtains both SO_PEERCRED and SO_PEERPIDFD via peerIdentity(), validates the peer UID/GID/PID, queries manager.ClientState(ctx), validates the systemd client identity, and stores that initial identity in authenticatedPeer.
• 🟡 (07:13) authenticatedPeer.validateCredentials() requires credential.Pid > 0 and exact matches against expectedUID and expectedGID; otherwise it returns "peer credentials do not match the expected client identity".
• 🟡 (07:13) authenticatedPeer.validateIdentity() requires the socket peer PID to equal clientIdentity.MainPID, and requires ActiveState == "active", SubState == "running", ControlGroup == expectedClientCgroup, and an InvocationID exactly 16 bytes long.
• 🟡 (07:13) authenticatedPeer.Recheck() first tests pidfd liveness with unix.PidfdSendSignal(peer.pidfd, 0, nil, 0), then re-queries manager.ClientState(ctx), repeats identity validation, and rejects admission if the current InvocationID differs from the initially authenticated invocation with "client service InvocationID changed during admission".
• 🟡 (07:13) peerIdentity() uses connection.SyscallConn() and raw.Control() to retrieve unix.SO_PEERCRED and unix.SO_PEERPIDFD; it rejects a negative pidfd, invokes unix.CloseOnExec(pidfd), and returns errors under the wrapper "SO_PEERCRED/SO_PEERPIDFD".
• 🟡 (07:13) authenticatedPeer.Close() closes its pidfd when pidfd >= 0 and sets the stored descriptor to -1; authentication failure paths call peer.Close() after obtaining the peer identity.
• 🟡 (07:13) Supervisor tests shown include TestReceiveStartClosesEveryExtraDescriptor, TestCopyInputRejectsOutputFrame, TestServeSessionDetectsDisconnectWhileInputForwardingBlocks, and TestTypeScriptTransportUsesHelperAndSplitsWrites; the TypeScript integration test uses a transient unit name matching opencode-pty-0123456789abcdef0123456789abcdef.service.
• 🟡 (07:13) Inspection of /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty-transport.ts showed protocol constants: MAGIC = Buffer.from("OPTY"), VERSION = 1, HEADER_SIZE = 12, MAX_FRAME_SIZE = 70 * 1024, MAX_IO_PAYLOAD_SIZE = 32 * 1024, frame types INPUT=2, OUTPUT=3, EXIT=4, ERROR=5, STARTED=6, STOP=7, STOPPED=8, and unit-name regex /^opencode-pty-[0-9a-f]{32}\.service$/.
• 🟡 (07:13) pty-transport.ts defaults to supervisor socket /run/opencode-pty/supervisor.sock and helper /usr/local/libexec/opencode-pty-client; it uses HELPER_TIMEOUT_MS = 5_000, STOP_TIMEOUT_MS = 25_000, and MAX_HELPER_ERROR_BYTES = 2_000.
• 🟡 (07:13) assertSupervisorAvailable() can skip helper verification only when verifyRootHelper === false; otherwise it requires the helper to be a root-owned regular executable file with no group/world write bits, then connects to the supervisor socket and verifies that Node exposes a valid connected socket descriptor.
• 🟡 (07:13) openSupervisorTransport() spawns the helper with arguments [String(runtimeSeconds), "a" + base64url(command), ...args.map(argument => "a" + base64url(argument))] and stdio ["pipe", "pipe", "pipe", connectedSocketFD(socket), binding.fd], passing the connected supervisor socket and binding descriptor as child fds 3 and 4.
• 🟡 (07:13) The TypeScript transport buffers supervisor output in pendingOutput until onOutput(listener) is registered, then drains the buffered Buffer objects in order via pendingOutput.splice(0).forEach(listener).
• 🟡 (07:13) The TypeScript frame parser requires magic OPTY, version 1, reserved header bytes 6 and 7 equal to zero, and payload length no greater than 70 * 1024; it accumulates partial socket data in buffer and processes complete frames in sequence.
• 🟡 (07:13) OUTPUT frames must carry 1..32 * 1024 bytes. STARTED frames must be nonempty UTF-8, occur only before unitName is set, and match /^opencode-pty-[0-9a-f]{32}\.service$/. ERROR frames must carry 1..32 * 1024 bytes of valid UTF-8.
• 🟡 (07:13) EXIT payload parsing requires at least 9 bytes: byte 0 is execMainCode, bytes 1..4 are big-endian execMainStatus, bytes 5..8 are a big-endian result-string length, and the remaining UTF-8 bytes must match that declared length; a valid EXIT resolves exited and calls socket.end().
• 🟡 (07:13) A STOPPED frame is accepted only with an empty payload while stopping === true; it synthesizes { execMainCode: 2, execMainStatus: 15, result: "stopped" }, resolves exited, and ends the socket.
• 🟡 (07:13) Unexpected frame types and malformed headers, payloads, UTF-8, unit names, or exit lengths destroy the TypeScript socket with explicit protocol errors; socket closure before a structured EXIT or STOPPED result fails the transport with "PTY supervisor connection closed before a structured exit.".
• 🟡 (07:13) openSupervisorTransport().write(data) splits input into chunks of at most MAX_IO_PAYLOAD_SIZE (32 * 1024) and writes each as a TYPE_INPUT frame under a 5_000 ms timeout; any timed-out write destroys the socket.
• 🟡 (07:13) openSupervisorTransport().close() sends one empty TYPE_STOP frame when not already stopping or settled, waits up to 25_000 ms for exited, destroys the socket on timeout, and otherwise waits for socket closure.
• 🟡 (07:13) connectedSocketFD() accesses Node’s private socket._handle.fd via Reflect.get, requires a nonnegative integer descriptor whose fstatSync(fd).isSocket() is true, and destroys the socket if Node does not expose a valid connected Unix-socket descriptor.
• 🟡 (07:13) waitForHelper() requires a helper stderr pipe, kills the helper with SIGKILL after 5_000 ms, retains stderr only while cumulative received size is at most 2_000 bytes, rejects signal termination, and reports retained stderr or PTY client helper exited with code ${code}. for a nonzero exit.