Distillation

Date: Sep 8, 2026

• 🟡 (08:15) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/client/main.go (107 lines), the fixed client helper that sends a TypeStart frame over inherited fd 3 and transfers the approved cwd on inherited fd 4.
• 🔴 (08:15) User stated the fixed client helper never initiates a socket connection, resolves a caller path, or opens an application-selected path; it receives Node’s already-connected socket at fd 3 and approved directory at fd 4.
• 🟡 (08:15) cmd/client/main.go constants are socketFD = 3 and cwdFD = 4. sendStart() applies unix.CloseOnExec() to both descriptors, validates that fd 3 is connected with unix.Getpeername(), validates fd 4 is a directory with unix.Fstat() and unix.S_IFDIR, and embeds its stat.Dev and stat.Ino in protocol.Start (main.go:17-42).
• 🟡 (08:15) The helper encodes the start with protocol.EncodeStart(), frames it with protocol.MarshalFrame(protocol.Frame{Type: protocol.TypeStart, Payload: payload}), and sends the packet plus exactly the cwd descriptor using unix.SendmsgN(socket, packet, unix.UnixRights(cwd), nil, unix.MSG_NOSIGNAL). Any unsent packet suffix is completed with unix.Write(); a zero-byte write returns syscall.EIO (cmd/client/main.go:42-68).
• 🟡 (08:15) decodeStart(values, device, inode) requires 2 through protocol.MaxArgs+2 metadata values. It parses values[0] as an unsigned base-10 32-bit runtime and rejects values above protocol.MaxRuntimeSec; remaining values must be canonical unpadded URL-safe base64 prefixed by a, using only [A-Za-z0-9_-] after the prefix (cmd/client/main.go:71-106).
• 🟡 (08:15) In client metadata decoding, the first decoded item is bounded by protocol.MaxCommandSize, later items by protocol.MaxArgSize, aggregate argument bytes by protocol.MaxArgsSize, and all decoded items must be canonical on re-encoding and contain no NUL. The result is protocol.Start{Device: device, Inode: inode, RuntimeSec: uint32(runtime), Command: decoded[0], Args: decoded[1:]} (cmd/client/main.go:79-106).
• 🟡 (08:15) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/launcher/main.go (145 lines), which uses encodedArgumentsEnvironment = "OPENCODE_PTY_ARGV" and launcherFD = 3.
• 🟡 (08:15) The launcher's outer run() mode validates encoded arguments, calls syscall.Fchdir(2) on the approved cwd, replaces stderr with stdout via syscall.Dup2(1, 2), installs a fixed environment, stores encoded argv as dot-separated OPENCODE_PTY_ARGV, binds its own executable to fd 3, and executes /usr/bin/script (cmd/launcher/main.go:27-50).
• 🟡 (08:15) bindLauncher() opens /proc/self/exe with unix.O_RDONLY|unix.O_CLOEXEC. If its fd differs from launcherFD, it uses unix.Dup3(fd, 3, 0); if already fd 3, it clears close-on-exec with unix.FcntlInt(uintptr(fd), unix.F_SETFD, 0) (cmd/launcher/main.go:70-86).
• 🟡 (08:15) The launcher’s inner mode is selected only by the sole argument --exec. execCommand() requires OPENCODE_PTY_ARGV, splits it on ., decodes the original argv, restores the fixed environment, closes fd 3, and directly invokes syscall.Exec(command[0], command, os.Environ()) (cmd/launcher/main.go:27-30,52-68).
• 🟡 (08:15) decodeArguments() accepts 1 through protocol.MaxArgs+1 encoded items, requires canonical a[A-Za-z0-9_-]* URL-safe unpadded base64, applies protocol.MaxCommandSize, protocol.MaxArgSize, and protocol.MaxArgsSize, rejects NUL, and rejects an empty decoded command (cmd/launcher/main.go:88-123).
• 🔴 (08:15) User stated command and argument bytes never contain NUL.
• 🟡 (08:15) setFixedEnvironment() clears the inherited environment and sets exactly HOME=/home/byk, LANG=C.UTF-8, LOGNAME=byk, PATH=/usr/local/bin:/usr/bin:/bin, SHELL=/bin/sh, TERM=xterm-256color, and USER=byk (cmd/launcher/main.go:125-141).
• 🟡 (08:15) scriptArguments() returns, in order, script, -q, -e, -f, -c, /bin/sh -i -c 'exec /proc/self/fd/3 --exec', /dev/null (cmd/launcher/main.go:143-145).
• 🟡 (08:15) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/supervisor/main.go (31 lines). It creates a context canceled by SIGINT or SIGTERM, opens supervisor.NewSystemdManager(ctx), constructs supervisor.NewServer(manager), calls server.Serve(ctx), and exits with status 1 after printing any initialization or serving error.
• 🟡 (08:15) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/PROTOCOL.md (50 lines). The design uses one Unix SOCK_STREAM connection per PTY; the Node SEA process opens and retains it, and the supervisor authenticates immutable peer credentials against the exact opencode-v2.service MainPID.
• 🔴 (08:15) User stated source behavior never proves that all other Node child processes inherit neither the authenticated socket nor the approved-cwd descriptor; exact Node 26.4 SEA inheritance and same-UID delegation remain target-host acceptance blockers.
• 🟡 (08:15) The documented frame header is 12 bytes: bytes 0–3 ASCII OPTY, byte 4 version 1, byte 5 type, bytes 6–7 zero, and bytes 8–11 unsigned big-endian payload length. Maximum frame payload is 71,680 bytes; input/output payloads are at most 32,768 bytes; one accepted 65,536-byte plugin write is split into at most two input frames.
• 🟡 (08:15) The helper sends exactly one start frame, type 1, with exactly one SCM_RIGHTS descriptor. The supervisor receives descriptors atomically with MSG_CMSG_CLOEXEC, closes every received descriptor on every error, requires exactly one directory, and compares its st_dev and st_ino against the frame.
• 🟡 (08:15) The documented start payload ordering is: 1. 8-byte unsigned big-endian st_dev; 2. 8-byte unsigned big-endian st_ino; 3. 4-byte unsigned big-endian runtime seconds, where zero selects 3,600 seconds; 4. 2-byte unsigned big-endian command byte length; 5. 2-byte unsigned big-endian argument count; 6. command bytes; 7. each argument as a 2-byte unsigned big-endian length followed by its bytes.
• 🟡 (08:15) Documented start limits are command length 1–4,096 UTF-8 bytes, at most 128 arguments, each argument at most 16,384 UTF-8 bytes, aggregate argument bytes at most 65,536, and runtime at most 3,600 seconds.
• 🔴 (08:15) User stated a valid transient unit name always matches opencode-pty-[0-9a-f]{32}.service; the plugin never reports spawn success before receiving started frame type 6.
• 🟡 (08:15) Documented session frames are: input type 2, non-empty opaque bytes up to 32,768; output type 3, non-empty opaque bytes up to 32,768; exit type 4, structured systemd completion; error type 5, non-empty UTF-8 truncated to 32,768 bytes; stop type 7, empty request to stop and wait for the complete unit cgroup; stopped type 8, empty acknowledgement sent only after bounded cleanup and final-output drain.
• 🟡 (08:15) The exit payload contains one byte ExecMainCode, four bytes unsigned big-endian ExecMainStatus, four bytes unsigned big-endian result-string length, and the UTF-8 systemd Service Result. The plugin maps CLD_EXITED to exitCode, CLD_KILLED/CLD_DUMPED to numeric exitSignal, and retains the exact systemd result; explicit stop maps to result stopped, CLD_KILLED, and signal 15 as a protocol completion record rather than a claimed systemd ExecMain result.
• 🔴 (08:15) User stated client disconnect always stops and waits for the complete transient cgroup.
• 🟡 (08:15) The protocol fails closed on unknown types, malformed lengths, extra descriptors, descriptor truncation, and wrong-direction frames. The supervisor stops the unit before bounded final-output drain and sends exit only after output EOF; cleanup failure is sent when possible, logged, and terminates the supervisor so no ambiguous accepted unit remains active, while transient-unit BindsTo provides shutdown cleanup.
• 🟡 (08:15) The documented PTY flow executes /usr/bin/script -q -e -f -c "/bin/sh -i -c 'exec /proc/self/fd/3 --exec'" /dev/null; the inner launcher decodes argv, clears the temporary argument environment value, restores the fixed environment, closes fd 3, and directly calls execve with preserved argv boundaries. The fixed inner shell is interactive, and script -e preserves normal command status.
• 🔴 (08:15) User stated this is an interactive PTY transport, not a general security sandbox; pilot commands retain workspace and IPv4/IPv6 network access.
• 🔴 (08:15) User stated a same-UID process capable of ptrace, /proc descriptor access, process control, inheritance, or descriptor delegation against the Node SEA MainPID remains a deployment blocker; exact-host acceptance must prove descriptor inheritance is limited to the one fixed helper invocation.
• 🟡 (08:15) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/ROOT-ACCEPTANCE.md (45 lines), which forbids installation, startup, enablement, or readiness until all 16 checks pass on the exact target host; source tests never substitute for these checks.
• 🔴 [enforced-workflow] (08:15) User’s root-only acceptance sequence is: 1. reproducibly rebuild all three binaries twice with CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags=-buildid=, require matching sets, and record source revision, Go version, dependency sums, commands, and SHA-256 hashes; 2. verify /usr/local/libexec, all parents, and binaries are root-owned and not writable by byk or a group; 3. validate root-owned mode-0644 candidate service/slice files in a disposable VM using systemd-analyze verify and D-Bus property inspection without altering production; 4. prove the peer is the Node SEA MainPID rather than helper, including exact UID/GID, active/running, cgroup, 16-byte InvocationID, mandatory SO_PEERPIDFD, and rejection after MainPID/invocation replacement.
• 🔴 [enforced-workflow] (08:15) User’s root-only acceptance sequence continues: 5. syscall/descriptor-trace the final helper to prove it receives only ordinary stdio plus fd 3 and fd 4, sends one bounded start frame with one SCM_RIGHTS descriptor, opens no application-selected path, performs no socket/connect operation, and leaves no unrelated Node child inheriting the descriptors; 6. exercise unauthenticated quota/rate limiting separately from authenticated capacity and require handshake D-Bus operations within five seconds; 7. verify one session creates only a correctly named unit running as byk:byk without supplementary privileged groups and with required sandbox/resource properties; 8. preserve workspace and IPv4/IPv6 access while proving same-UID impersonation/delegation paths are blocked.
• 🔴 [enforced-workflow] (08:15) User’s root-only acceptance sequence continues: 9. verify exact protocol limits and reject malformed UTF-8, NUL, missing/extra descriptors, MSG_CTRUNC, metadata mismatch, wrong direction, unknown types, and oversized frames; 10. verify a real PTY and fixed /bin/sh -i shell with spaces, quotes, metacharacters, newlines, terminal behavior, stdout/stderr ordering, EOF, script -e, zero/nonzero exits, and signals without losing argv boundaries; 11. run 16 concurrent sessions, reject the 17th, and cover reader/input blocking, disconnect, backpressure, maximum output, runtime expiry, TERM-to-KILL escalation, protocol failure, shutdown, D-Bus failures/timeouts, startup cancellation, and every non-done or ambiguous StartTransientUnit result; 12. after every StartTransientUnit path, require bounded StopUnit and full cgroup removal, client/journal cleanup errors, and strict-name plus exact-BindsTo orphan cleanup.
• 🔴 [enforced-workflow] (08:15) User’s root-only acceptance sequence concludes: 13. verify aggregate-slice and per-session CPU, memory, tasks, I/O, runtime, and output-backpressure controls under pressure; 14. run bun /tmp/opencode/pty-plugin-smoke.ts ten times outside the auto-discovered plugin directory and then against freshly built helpers plus an isolated disposable supervisor, covering permissions, source identity, ownership, deletion, in-flight deletion, reservations, JSON envelopes, regex/UTF-8/output/STOP bounds, framing, transfer, notifications, timeouts, and cleanup; 15. on exact Node 26.4 SEA, deterministically enumerate the helper descriptors before its first application operation and prove an unrelated child inherits neither descriptor, with Node 24 explicitly insufficient; 16. obtain independent correctness/security reviews, match review-source-hash to embedded pty-source:sha256, install the reviewed verifier, and create the exact readiness marker only after every gate passes.
• 🟡 (08:15) Required root-controlled installation commands install bin/opencode-pty-supervisor, bin/opencode-pty-launcher, bin/opencode-pty-client, and verify-readiness under /usr/local/libexec as root:root mode 0755, with the verifier installed as /usr/local/libexec/opencode-pty-verify-readiness.
• 🟡 (08:15) /etc/opencode/pty-supervisor-verified must be a root-owned mode-0644 regular file containing exactly four newline-terminated lines in fixed order: revision=opencode-v2-pilot:git:<reviewed-40-hex-commit>;pty-source:sha256:<reviewed-source-manifest-hash>, then standard sha256sum records for /usr/local/libexec/opencode-pty-supervisor, /usr/local/libexec/opencode-pty-launcher, and /usr/local/libexec/opencode-pty-client. Duplicate or trailing lines are invalid.
• 🔴 (08:15) User stated root acceptance, exact Node 26.4 SEA inheritance, same-UID delegation/ptrace isolation, target-host systemd properties, and independent reviews remain deployment blockers until performed on final artifacts; source tests never close these gates.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/verify-readiness (34 lines). It uses MARKER=/etc/opencode/pty-supervisor-verified and exact EXPECTED_REVISION='revision=opencode-v2-pilot:git:2ac698d65aa4690a694307e9cbdf44537ea9a4fb;pty-source:sha256:fff146df36754bc59d473a070985c4310cb57bdad64473ec7f68b5be5014286f'.
• 🟡 (08:16) verify-readiness requires the marker to be a nonsymlink regular file with /usr/bin/stat -c '%u:%g:%a' exactly 0:0:644, reads exactly four lines via fd 3, rejects trailing lines, requires the exact embedded revision/source-manifest line, and compares each remaining line exactly with /usr/bin/sha256sum output for the supervisor, launcher, and client installed paths.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/CUTOVER.md (43 lines). It specifies that OpenCode V2 serves API and web UI from one origin and nginx must not be added.
• 🔴 [enforced-workflow] (08:16) User’s cutover preflight requires: production healthy on port 4096; candidate revision and opencode2-node --version checks; candidate health/UI on port 14102; both local plugins active after POST /api/plugin/await-activation; mode-0600 /home/byk/.local/share/opencode-v2-pilot/server.env containing OPENCODE_PASSWORD=<password>; all supervisor/ROOT-ACCEPTANCE.md checks; complete-cgroup cleanup for deletion, unload, expiry, kill, disconnect, and ambiguous start; exact Node 26.4 SEA descriptor/same-UID isolation; independent approval; installation and validation of the exact readiness marker/verifier; and systemd-analyze verify of supervisor, slice, and candidate units.
• 🔴 [enforced-workflow] (08:16) User stated cutover requires explicit approval because it stops the running service and must never proceed while root acceptance, independent reviews, or the content-bound readiness marker are incomplete.
• 🟡 (08:16) Cutover order is: 1. install /etc/systemd/system/opencode-v2.service; 2. sudo systemctl daemon-reload; 3. sudo systemctl stop opencode.service; 4. sudo systemctl start opencode-v2.service; 5. verify /api/health, /, /site.webmanifest, /sw.js, and /openapi.json on port 4096; 6. call POST /api/plugin/await-activation and confirm followup and local-pty in GET /api/plugin; 7. observe browser traffic and run one follow-up plus one PTY smoke session; 8. enable opencode-v2.service only after all checks pass while retaining disabled opencode.service for rollback.
• 🟡 (08:16) Rollback order is: 1. sudo systemctl stop opencode-v2.service; 2. sudo systemctl start opencode.service; 3. verify legacy health and UI on port 4096; 4. disable opencode-v2.service only after legacy health is confirmed. The V2 database remains isolated at /home/byk/.local/share/opencode-v2-pilot/data, and rollback never rewrites or deletes either database.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty-supervisor.service (59 lines). It runs /usr/local/libexec/opencode-pty-supervisor as root with group byk, no supplementary groups, RuntimeDirectory=opencode-pty, mode 0750, UMask=0077, KillMode=control-group, TERM then KILL, TimeoutStopSec=20s, OOMPolicy=kill, and Delegate=no.
• 🟡 (08:16) The supervisor service hardening includes NoNewPrivileges=yes, empty capability and ambient sets, RestrictAddressFamilies=AF_UNIX, PrivateTmp=yes, PrivateDevices=yes, PrivateMounts=yes, PrivateNetwork=yes, ProtectSystem=strict, ProtectHome=yes, kernel/control-group/clock/hostname protections, ProtectProc=invisible, ProcSubset=pid, RestrictNamespaces=yes, RestrictSUIDSGID=yes, LockPersonality=yes, MemoryDenyWriteExecute=yes, RestrictRealtime=yes, DevicePolicy=closed, and denial of Docker and user-D-Bus socket paths.
• 🟡 (08:16) Supervisor service accounting limits are MemoryHigh=192M, MemoryMax=256M, and TasksMax=64, with CPU, memory, tasks, and I/O accounting enabled. Its syscall deny list is @clock @cpu-emulation @debug @module @mount @obsolete @privileged @raw-io @reboot @resources @swap.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty.slice (14 lines). The slice enables CPU, memory, tasks, and I/O accounting with CPUQuota=800%, IOWeight=100, MemoryHigh=1536M, MemoryMax=2G, and TasksMax=512.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service (35 lines). It requires and starts after opencode-pty-supervisor.service, runs as byk from /home/byk, and gates startup with ExecCondition=/usr/local/libexec/opencode-pty-verify-readiness.
• 🟡 (08:16) opencode-v2.service starts /home/byk/Code/opencode-v2-pilot/packages/cli/dist-v2-pilot-final/cli-node-linux-x64/bin/opencode2-node serve --hostname=0.0.0.0 --port=4096; it uses /home/byk/.opencode/env and /home/byk/.local/share/opencode-v2-pilot/server.env, restarts always after 5 seconds, and sets Nice=-5, LimitNOFILE=65535, LimitNPROC=4096, MemoryHigh=12G, and MemoryMax=13G.
• 🟡 (08:16) V2 service paths are OPENCODE_CONFIG_DIR=/home/byk/.local/share/opencode-v2-pilot/config/opencode, OPENCODE_DB=/home/byk/.local/share/opencode-v2-pilot/data/opencode/opencode.db, XDG_DATA_HOME=/home/byk/.local/share/opencode-v2-pilot/data, XDG_CACHE_HOME=/home/byk/.local/share/opencode-v2-pilot/cache, XDG_CONFIG_HOME=/home/byk/.local/share/opencode-v2-pilot/config, and XDG_STATE_HOME=/home/byk/.local/share/opencode-v2-pilot/state.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/config/opencode/tsconfig.json: strict no-emit ESNext configuration with module="Preserve", moduleResolution="Bundler", allowImportingTsExtensions=true, Bun types, and includes plugins/**/*.ts plus test/**/*.ts. @opencode/plugin maps to /home/byk/Code/opencode-v2-pilot/packages/plugin/src/promise/index.ts, and @opencode/plugin/* maps to /home/byk/Code/opencode-v2-pilot/packages/plugin/src/promise/*.ts.
• 🟡 (08:16) Inspected /home/byk/.local/share/opencode-v2-pilot/config/opencode/package.json: private ESM package with dependency effect at file:/home/byk/Code/opencode-v2-pilot/node_modules/.bun/effect@4.0.0-rc.112/node_modules/effect and dev dependency @types/bun version 1.2.21.
• 🟡 (08:16) /tmp/opencode contains the reviewed smoke harness /tmp/opencode/pty-plugin-smoke.ts, multiple numbered smoke-result series including pty-plugin-smoke-1.json through pty-plugin-smoke-10.json, review/fixes/final/proof variants, reproducible-build directories /tmp/opencode/pty-review-fresh-a and /tmp/opencode/pty-review-fresh-b containing all three binaries, and current/final supervisor, launcher, and client artifacts.