Distillation

Date: Sep 8, 2026

• 🟢 (06:45) Initial path probes found no /bots and no /home/byk/.local/share/opencode-local; tool suggested /home/byk/.local/share/opencode.
• 🟡 (06:46) Review inventory identified 22 files under /home/byk/.local/share/opencode-v2-pilot/supervisor: ROOT-ACCEPTANCE.md, PROTOCOL.md, go.mod, go.sum, opencode-pty.slice, opencode-pty-supervisor.service, cmd/client/main.go, cmd/client/main_test.go, cmd/launcher/main.go, cmd/launcher/main_test.go, cmd/supervisor/main.go, internal/protocol/frame.go, internal/protocol/frame_test.go, internal/supervisor/auth.go, internal/supervisor/auth_test.go, internal/supervisor/server.go, internal/supervisor/server_test.go, internal/supervisor/systemd.go, internal/supervisor/systemd_test.go, and binaries bin/opencode-pty-client, bin/opencode-pty-launcher, bin/opencode-pty-supervisor.
• 🟡 (06:46) Additional scoped files located: /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts, /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty-transport.ts, /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service, and /home/byk/.local/share/opencode-v2-pilot/CUTOVER.md; plugin directory also contains followup.ts.
• 🟡 (06:46) Frozen binary SHA-256 hashes: bin/opencode-pty-client = fb8739d98ff7882782005e04ef731b6120e8daf0719e606362a1fe620adc2cde; bin/opencode-pty-launcher = d833c859476f021565e8f425e6ee51353909060fa5f64ce629fb07d3411987dd; bin/opencode-pty-supervisor = c5c09ece21c802868721dfc3e2610496ad9630c1b3a4c258104bc92b2bd9aca1.
• 🟡 (06:46) Frozen binary metadata: bin/opencode-pty-client mode 755, UID/GID 1000:1000, size 2109912, mtime 2026-09-08 06:38:38.524405811 +0000; bin/opencode-pty-launcher mode 755, UID/GID 1000:1000, size 2098942, mtime 2026-09-08 06:38:38.512405908 +0000; bin/opencode-pty-supervisor mode 755, UID/GID 1000:1000, size 4407495, mtime 2026-09-08 06:38:38.491406077 +0000.
• 🟡 (06:46) All three binaries were reported as x86-64 ELF SYSV executables, statically linked, containing debug_info, and not stripped; build environment reported go version go1.22.2 linux/amd64, target linux/amd64, CGO_ENABLED=1, and compiler go1.22.2.
• 🟡 (06:46) Frozen supervisor-document/config hashes: ROOT-ACCEPTANCE.md = 9f70a745367e68d0f35aa14cb5048b8c83652cf10e279539ab16f25037757f1a; PROTOCOL.md = 2a588cef62538063cbe7f3dbc27305a7e8e2511a59a86c6cec6b5b18b1b2275f; go.mod = d1d088bdd65f99056657717658d3336ae233acd2ad39fa998ebe8a773f68348e; go.sum = dad6a6773121326ee41a6a081cf310444b6fcd3540f28f4b3f31de559d31726b; opencode-pty.slice = 5f03c865c17fbb54e2fa3a0e0c7cbf899ad4509228d1a7262aaa4ea3387b9e20; opencode-pty-supervisor.service = 63414c4afc3e4bad52d4738e9bfd1886a312012663dd4eb7390481cc50636239.
• 🟡 (06:46) Frozen command-source hashes: cmd/client/main.go = 9471c8c9dd2a8c00274e1e6ecc89983377c3810e2a7ad47b962df19ce6d2995b; cmd/client/main_test.go = 506fe06b72e9859bdd101b2c048b63c6b866a290a1ab27311ccaff9bdd23658b; cmd/launcher/main.go = c5fef296d93af561b99284f9e73bdd9569d8501f92bd34bf47a10ae2fe03f41b; cmd/launcher/main_test.go = e584ce5e320bc8c9dc6c250c548bbae517fa6ecdc721a5813cd6bb148fc3b090; cmd/supervisor/main.go = d7381fa5feeacacbf94cddbf36539f8544ccab9705fa4b7906207726d67c387d.
• 🟡 (06:46) Frozen protocol-source hashes: internal/protocol/frame.go = 83ef89be747e6c1bd51ba1474307980dd4e9d4c1d17360be1c02538c990f832d; internal/protocol/frame_test.go = c7c45eeaf44411bd6fe87998fce153cb8decda5df7d7e805fad9dc6f6cdfd591.
• 🟡 (06:46) Frozen supervisor-source hashes: internal/supervisor/auth.go = 7e87448cedd42966156ecd3a17e654ccec15e11d276ccdcf014c0fa66b49a974; internal/supervisor/auth_test.go = 9fc722a3e84e6a445c66a031882fc40ae6fc1f0216c21cd0e50770621bd6c7eb; internal/supervisor/server.go = 6e4230fcd20b8f5cdc6d417776ba1ea0bd6032882f358352ba1fd46bd71b6589; internal/supervisor/server_test.go = 7ef99b1f2cb77bf573327688d7ac734e712c4560154eee504a72203676a0285b; internal/supervisor/systemd.go = 7e1c6de7d917b584e207788899d9af5a96b262a5a7b52fcf8f1196dcfc0188cf; internal/supervisor/systemd_test.go = eede59ca6e0927c9ab8524b7a10cc59a32b0332250d7d45210f5c22f114ce4e1.
• 🟡 (06:46) Frozen external-scope hashes: /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts = f4f31124e753d11682f45aceef4c9344965de44b74b7afc4bb62968f469f52af; /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty-transport.ts = c8a117e96de883f01762765b21c3f2abeb09af9e22c74d5cf503b3204bb49f2d; /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service = c93e779848222afc2b96540f626a9f2b66a83cb38b459d25682269d1fc4b8928; /home/byk/.local/share/opencode-v2-pilot/CUTOVER.md = c6e731ef91d2ba97805685ec10ebb31c3baad8021b2c9bf5b327ab456691680f.
• 🟡 (06:46) Authentication inspection of internal/supervisor/auth.go: authenticate() obtains SO_PEERCRED and SO_PEERPIDFD through peerIdentity(), validates expected UID/GID and positive PID, queries manager.ClientState(ctx), requires peer PID to equal service MainPID, and requires ActiveState == "active", SubState == "running", exact expectedClientCgroup, and a 16-byte InvocationID (auth.go:19-39,66-80,83-107).
• 🟡 (06:46) peerIdentity() marks the returned pidfd close-on-exec with unix.CloseOnExec(pidfd) and rejects negative pidfds; authenticatedPeer.Close() closes the pidfd and sets it to -1 (internal/supervisor/auth.go:59-64,83-107).
• 🟡 (06:46) Admission recheck inspection: authenticatedPeer.Recheck() verifies pidfd liveness using unix.PidfdSendSignal(peer.pidfd, 0, nil, 0), re-queries client service state, repeats identity validation, and rejects an InvocationID change during admission (internal/supervisor/auth.go:42-57).
• 🟡 (06:47) internal/supervisor/server.go defines /run/opencode-pty/supervisor.sock, maxSessions = 16, maxUnauthenticated = 32, maxAdmissionsPerMinute = 120, socketBufferSize = 128 * 1024, and handshakeTimeout = 5 * time.Second (server.go:25-32).
• 🟡 (06:47) NewServer() resolves account byk, parses its UID and GID, and initializes bounded session and unauthenticated channels, a connection map, and a one-slot fatal channel (internal/supervisor/server.go:51-72).
• 🟡 (06:47) Server.Serve() refuses non-root execution, performs fail-closed startup CleanupOrphans(ctx) before listening, accepts Unix connections, applies unauthenticated admission bounds, tracks each accepted connection, and launches one handler goroutine per admitted connection (internal/supervisor/server.go:75-119).
• 🟡 (06:47) Connection admission sets read/write buffers to 128 * 1024, applies a 5-second handshake context and socket deadline, authenticates before acquiring one of 16 session slots, receives the start frame plus cwd descriptor, clears the deadline, creates a random unit name, and rechecks peer identity immediately before manager.Start(...) (internal/supervisor/server.go:122-218).
• 🟡 (06:47) Transient-unit cleanup is guarded by sync.Once; deferred cleanup failures trigger server.fail(...), and cleanup failure after a session error is treated as fatal rather than merely returned to the client (internal/supervisor/server.go:180-193,218-225).
• 🟡 (06:47) serveSession() concurrently runs copyInput, copyOutput, watchDisconnect, and manager.Wait; it cleans up on context cancellation, disconnect, input closure/error, explicit stop, output error, or unit completion, and bounds PTY-output draining with outputDrainTimeout, calling unix.Shutdown(..., unix.SHUT_RDWR) on timeout (internal/supervisor/server.go:228-335).
• 🟡 (06:47) Session input accepts only an empty protocol.TypeStop or a non-empty protocol.TypeInput no larger than protocol.MaxIOPayloadSize; all other frames return protocol.ErrInvalidFrame. Output is chunked at protocol.MaxIOPayloadSize into protocol.TypeOutput frames (internal/supervisor/server.go:337-368).
• 🟡 (06:47) Disconnect monitoring duplicates the client socket using unix.F_DUPFD_CLOEXEC, polls every 250 ms for POLLRDHUP|POLLHUP|POLLERR, and closes the duplicate on return (internal/supervisor/server.go:370-400).
• 🟡 (06:47) Start-message descriptor handling reads an exact protocol header and bounded payload, rejects length > protocol.MaxFrameSize, requires exactly one received fd and a protocol.TypeStart frame, decodes the start payload, and verifies the fd is a directory whose Dev and Ino exactly match start.Device and start.Inode (internal/supervisor/server.go:402-440).
• 🟡 (06:47) Ancillary descriptor receiving uses unix.Recvmsg(..., unix.MSG_CMSG_CLOEXEC), rejects zero-byte reads and MSG_TRUNC|MSG_CTRUNC, parses SCM_RIGHTS, and rejects more than one received fd (internal/supervisor/server.go:443-488).
• 🟡 (06:47) Socket setup refuses to overwrite a non-socket at /run/opencode-pty/supervisor.sock, removes a pre-existing socket, listens with net.ListenUnix, and sets mode 0660; the PTY socketpair uses AF_UNIX, SOCK_STREAM|SOCK_CLOEXEC, and 128 * 1024 send/receive buffers on both ends (internal/supervisor/server.go:490-528).
• 🟡 (06:47) Unit names contain 16 cryptographically random bytes formatted between unitPrefix and unitSuffix; exit payload encoding stores ExecMainCode in 1 byte, ExecMainStatus in 4 big-endian bytes, the result-string length in 4 big-endian bytes, then the result text (internal/supervisor/server.go:530-545).
• 🟡 (06:47) Error payloads are bounded to protocol.MaxIOPayloadSize and trimmed to valid UTF-8; frameWriter.write() serializes writes with a mutex and sets a write deadline of operationTimeout before protocol.WriteFrame(...) (internal/supervisor/server.go:547-595).
• 🟡 (06:47) Admission throttling combines a 32-slot concurrent unauthenticated cap with a rolling limit of 120 admissions per minute; denial releases the previously acquired unauthenticated slot (internal/supervisor/server.go:598-621).
• 🟡 (06:47) Fatal server errors are logged and sent only once via fatalOnce; fatal handling closes the listener and every tracked connection (internal/supervisor/server.go:623-654).