Distillation

Date: Sep 8, 2026

• 🟡 (07:13) Inspection of /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server.go showed server limits/constants: socketPath = "/run/opencode-pty/supervisor.sock", maxSessions = 16, maxUnauthenticated = 32, maxAdmissionsPerMinute = 120, socketBufferSize = 128 * 1024, and handshakeTimeout = 5 * time.Second.
• 🟡 (07:13) Server stores active-session and unauthenticated admission semaphores as buffered channels, all accepted connections in map[*net.UnixConn]struct{}, expected UID/GID, and a single global admissions []time.Time protected by mutex.
• 🟡 (07:13) NewServer() resolves the fixed account "byk" via user.Lookup("byk"), parses its UID/GID, creates a maxSessions-capacity session channel and maxUnauthenticated-capacity unauthenticated channel, and initializes the fatal-error channel with capacity 1.
• 🟡 (07:13) Serve() refuses to run unless os.Geteuid() == 0, invokes server.manager.CleanupOrphans(ctx) before listening, and then accepts Unix connections and applies admitUnauthenticated() before starting handle() goroutines.
• 🟡 (07:13) Admission-control review found admitUnauthenticated() first reserves one of 32 unauthenticated slots and then applies one shared rolling quota of 120 admissions per minute before authentication. Consequently, same-UID unauthenticated peers can consume the global minute quota before a legitimate authenticated MainPID reaches authenticate().
• 🟡 (07:13) handle() applies 128 * 1024 socket read/write buffers, creates handshakeCtx with a 5 * time.Second timeout, sets the connection deadline to the same duration, calls authenticate(...), releases the unauthenticated slot only after successful authentication, and then attempts to reserve one of 16 session slots.
• 🟡 (07:13) Session startup in handle() receives a START frame and cwd descriptor via receiveStart(), clears the socket deadline after START processing, generates a random transient-unit name from 16 cryptographically random bytes, creates a Unix socket pair, performs peer.Recheck(handshakeCtx, server.manager), and calls server.manager.Start(...).
• 🟡 (07:13) Per-session cleanup is wrapped in sync.Once, but calls server.manager.StopAndWait(ctx, unitName) using the parent context. Cleanup failures trigger server.fail(...), which logs the error, sends it once on server.fatal, and closes the listener and all tracked connections.
• 🟡 (07:13) serveSession() launches four goroutines for copyInput(), copyOutput(), watchDisconnect(), and manager.Wait(). It handles parent cancellation, disconnect, STOP, input failure, output completion/failure, and unit completion; PTY output draining uses outputDrainTimeout and calls unix.Shutdown(..., unix.SHUT_RDWR) on timeout.
• 🟡 (07:13) copyInput() accepts only an empty protocol.TypeStop frame or a nonempty protocol.TypeInput payload no larger than protocol.MaxIOPayloadSize; all other frames return protocol.ErrInvalidFrame.
• 🟡 (07:13) watchDisconnect() duplicates the connection descriptor with unix.F_DUPFD_CLOEXEC, polls every 250 milliseconds for unix.POLLRDHUP | unix.POLLHUP | unix.POLLERR, and closes the duplicate on return.
• 🟡 (07:13) receiveStart() reads the protocol.HeaderSize header and declared payload separately via receiveExact(), permits at most protocol.MaxFrameSize, requires exactly one received fd and protocol.TypeStart, decodes the START payload, and verifies the cwd descriptor is a directory whose stat.Dev and stat.Ino match start.Device and start.Inode.
• 🟡 (07:13) FD-receive review found receiveExact() allocates only unix.CmsgSpace(4) bytes of ancillary-data space per receive, despite needing to handle malicious sends containing 3 or more descriptors.
• 🟡 (07:13) receiveExact() calls receiveMessage() with unix.MSG_CMSG_CLOEXEC, but immediately returns protocol.ErrInvalidFrame when MSG_TRUNC or MSG_CTRUNC is set, before parsing the current ancillary buffer and closing any descriptors installed by that recvmsg; receiveStart() can close only descriptors already appended to its fds slice.
• 🟡 (07:13) Additional FD error paths in receiveExact() return directly on unix.ParseSocketControlMessage() or unix.ParseUnixRights() failure. Parsed rights are appended to *fds, and the function rejects once len(*fds) > 1; outer receiveStart() closes accumulated descriptors on the returned error.
• 🟡 (07:13) listen() rejects an existing non-socket at /run/opencode-pty/supervisor.sock, removes an existing socket, creates a Unix listener, and applies mode 0660.
• 🟡 (07:13) socketPair() creates AF_UNIX SOCK_STREAM|SOCK_CLOEXEC descriptors and applies both SO_SNDBUF and SO_RCVBUF at 128 * 1024 to each endpoint.
• 🟡 (07:13) frameWriter.write() serializes writes with a mutex and, when the writer supports SetWriteDeadline(time.Time), applies time.Now().Add(operationTimeout) before calling protocol.WriteFrame().