Distillation

Date: September 8, 2026

• 🟡 (07:53) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server.go lines 35–184. Server holds a unitManager, Unix listener, bounded sessions and unauthenticated channels, active Unix-connection map, buffered fatal-error channel, expected UID/GID, admission timestamps, main PID/identity-refresh state, mutex, wait group, and sync.Once fatal guard; errStopRequested is errors.New("client requested stop").
• 🟡 (07:53) NewServer(manager unitManager) in /home/byk/.local/share/opencode-v2-pilot/supervisor/internal/supervisor/server.go looks up the fixed client account "byk", parses its UID and GID as unsigned 32-bit integers, initializes sessions with maxSessions, unauthenticated with maxUnauthenticated, connections as map[*net.UnixConn]struct{}, and fatal as a one-entry error channel, then stores the parsed UID/GID as uint32.
• 🟡 (07:53) Server.Serve(ctx) requires effective UID 0, returning "supervisor must run as root" otherwise; it invokes server.manager.CleanupOrphans(ctx) before listening and wraps failures as "startup orphan cleanup: %w".
• 🟡 (07:53) Server.Serve(ctx) starts a goroutine that waits for context cancellation and calls server.closeConnections(). Its Unix accept loop waits for active handlers before returning on fatal errors or normal context cancellation.
• 🟡 (07:53) New Unix connections are accepted only when peerCredential(connection) succeeds, the peer UID and GID exactly match server.expectedUID and server.expectedGID, and server.admitUnauthenticated(server.likelyMainPID(ctx, credential.Pid)) succeeds. Any failure writes "authentication admission limit reached", closes the connection, and continues.
• 🟡 (07:53) Accepted connections are tracked via server.addConnection(connection), counted with server.wait.Add(1), and processed concurrently by go server.handle(ctx, connection).
• 🟡 (07:53) Server.handle(ctx, connection) tracks authenticated and acquiredSession; deferred cleanup releases the unauthenticated slot if authentication never completed, releases the session slot if acquired, removes and closes the connection, and calls server.wait.Done().
• 🟡 (07:53) Connection handling sets both read and write buffers to socketBufferSize, establishes handshakeCtx with handshakeTimeout, sets the socket deadline to time.Now().Add(handshakeTimeout), and authenticates through authenticate(handshakeCtx, connection, server.manager, server.expectedUID, server.expectedGID). Errors are returned to the peer using writeError.
• 🟡 (07:53) After successful authentication, Server.handle defers peer.Close(), marks the connection authenticated, releases its unauthenticated slot, and non-blockingly acquires a bounded session slot. If no slot is available, it writes "session limit reached" and returns.
• 🟡 (07:53) An authenticated session calls receiveStart(connection) to obtain start and cwd, defers cwd.Close(), clears the connection deadline with connection.SetDeadline(time.Time{}), generates a unit name via randomUnitName(), and initializes var cleanupOnce sync.Once.