Distillation

Date: Sep 8, 2026

• 🟡 (05:25) /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/launcher/main.go defines maxArgs=128 and maxArgSize=4096; run(...) decodes the command, calls syscall.Fchdir(2), replaces FD 2 with FD 1 via syscall.Dup2(1, 2), clears the environment, sets fixed values HOME=/home/byk, LANG=C.UTF-8, LOGNAME=byk, PATH=/usr/local/bin:/usr/bin:/bin, TERM=xterm-256color, and USER=byk, then executes /usr/bin/script with arguments script -qefc COMMAND /dev/null.
• 🟡 (05:25) Launcher argument decoding in cmd/launcher/main.go requires 1–128 encoded arguments, each beginning with a, conforming to [A-Za-z0-9_-], using canonical URL-safe unpadded base64, decoding to at most 4096 bytes without NUL; it single-quotes every decoded argument, escapes embedded ' as '\'', and joins arguments with spaces.
• 🟡 (05:25) /home/byk/.local/share/opencode-v2-pilot/supervisor/cmd/launcher/main_test.go contains: TestDecodeCommandQuotesEveryArgument (expects "'printf' '%s\\n' 'a'\\''b; $(id)' ''"), TestDecodeCommandRejectsInvalidGrammar (rejects "bad="), and TestLauncherExecutesInDescriptorDirectory (passes a temporary directory through stderr/FD 2 and verifies /usr/bin/pwd runs there).
• 🟡 (05:25) /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty-supervisor.service configures Type=exec, User=root, Group=byk, ExecStart=/usr/local/libexec/opencode-pty-supervisor, RuntimeDirectory=opencode-pty, RuntimeDirectoryMode=0750, RuntimeDirectoryPreserve=no, NoNewPrivileges=yes, UMask=0077, KillMode=control-group, KillSignal=SIGTERM, FinalKillSignal=SIGKILL, SendSIGKILL=yes, TimeoutStopSec=20s, OOMPolicy=kill, Delegate=no, RestrictAddressFamilies=AF_UNIX, PrivateTmp=yes, ProtectSystem=strict, kernel/control-group/clock protections, RestrictSUIDSGID=yes, LockPersonality=yes, and MemoryDenyWriteExecute=yes; it requires and starts after dbus.service and is wanted by multi-user.target.
• 🟡 (05:25) /home/byk/.local/share/opencode-v2-pilot/supervisor/opencode-pty.slice enables CPU, memory, and task accounting and sets MemoryMax=2G and TasksMax=512.
• 🟡 (05:26) /home/byk/.local/share/opencode-v2-pilot/supervisor/PROTOCOL.md specifies a one-PTY-per-Unix-SOCK_STREAM protocol with a 12-byte header: bytes 0–3 are OPTY, byte 4 is version 1, byte 5 is type, bytes 6–7 are zero, and bytes 8–11 are an unsigned big-endian payload length capped at 65536.
• 🔴 (05:26) User requires the PTY supervisor to validate the supplied directory descriptor and its st_dev/st_ino, require that it is a directory, and never resolve a client path.
• 🟡 (05:26) PTY protocol flow: the authenticated client sends one start frame (1) with exactly one SCM_RIGHTS directory descriptor; its payload contains unsigned big-endian st_dev, st_ino, optional runtime seconds, argument count, and length-prefixed argument bytes. Client input frames (2) are capped at 32768 bytes; supervisor output (3), exit (4), and error (5) frames are supported. Exit payload is one byte of ExecMainCode, four bytes of ExecMainStatus, four bytes of result-string length, and the structured systemd Result.
• 🟡 (05:26) PROTOCOL.md states that the launcher receives the unit stream as stdin/stdout and the approved cwd descriptor as stderr, calls fchdir(2), replaces stderr with stdout, clears and fixes the environment, decodes canonical URL-safe unpadded-base64 arguments matching a[A-Za-z0-9_-]*, shell-quotes each argument, and executes /usr/bin/script -qefc COMMAND /dev/null.
• 🔴 [enforced-workflow] (05:26) User requires every check in /home/byk/.local/share/opencode-v2-pilot/supervisor/ROOT-ACCEPTANCE.md to pass before starting or enabling the PTY supervisor service.
• 🟡 (05:26) ROOT-ACCEPTANCE.md defines 10 ordered acceptance steps: 1. Install freshly built bin/opencode-pty-supervisor and bin/opencode-pty-launcher as root-owned mode 0755 files under /usr/local/libexec; never execute either from the user-writable source tree. 2. Copy reviewed service/slice files to /etc/systemd/system as root-owned mode 0644, run systemd-analyze verify, and do not yet start or enable either unit. 3. Verify /usr/local/libexec, both binaries, and every parent directory are root-controlled and not writable by byk or any group. 4. With opencode-v2.service inactive, run a disposable root-started supervisor and verify every connection fails authentication, including fail-closed behavior on kernels lacking SO_PEERPIDFD. 5. In a test VM, use an isolated disposable client temporarily matching production identity and verify rejection of wrong PID, child PID, inactive state, wrong cgroup, PID replacement, missing/extra cwd descriptors, non-directory descriptors, and mismatched st_dev/st_ino. 6. Verify one valid session creates only opencode-pty-[0-9a-f]{32}.service, runs as byk:byk in opencode-pty.slice, receives the fixed environment, uses the descriptor-selected directory, and preserves spaces, quotes, shell metacharacters, and newlines without evaluation. 7. Inspect the transient unit over D-Bus, verify every unitProperties property is effective, and verify Docker, system D-Bus, and user D-Bus sockets are inaccessible from the command. 8. Exercise 16 concurrent sessions and rejection of the 17th, maximum frames/arguments, slow and disconnected readers, unlimited output until backpressure, optional RuntimeMaxSec, TERM-to-KILL escalation, nonzero/signal exits, protocol failure, client disconnect, and supervisor shutdown. 9. After every failure, verify the complete transient cgroup disappears and systemd emits UnitRemoved; restart only the disposable supervisor and verify strict-name/exact-BindsTo orphan cleanup removes owned orphans but leaves lookalike and foreign units. 10. Obtain an independent exact-source security review before installation or production cutover.
• 🟡 (05:26) The inspected local PTY plugin exposes exact constants MAX_SESSIONS_PER_OWNER = 5 and MAX_ARGUMENT_BYTES = 65_536; visible implementation details include a PTY-location session cap check, detached: true, argument-count validation, timeout handling, and bounded output buffering.
• 🔴 (05:26) User states the V2 executable serves the API and web UI from one origin and directs that nginx must not be added.
• 🟡 (05:26) /home/byk/.local/share/opencode-v2-pilot/CUTOVER.md preflight sequence: 1. Confirm production health on port 4096. 2. Confirm candidate revision with git -C /home/byk/Code/opencode-v2-pilot rev-parse HEAD and smoke the binary using /home/byk/Code/opencode-v2-pilot/packages/cli/dist-v2-pilot-final/cli-node-linux-x64/bin/opencode2-node --version. 3. Confirm the isolated candidate on port 14102 with authenticated curl --fail --user opencode:$OPENCODE_PASSWORD http://127.0.0.1:14102/api/health and curl --fail http://127.0.0.1:14102/ >/dev/null. 4. Call POST /api/plugin/await-activation and confirm both local plugins are active. 5. Create /home/byk/.local/share/opencode-v2-pilot/server.env mode 0600 containing OPENCODE_PASSWORD=<password>. 6. Install a root-owned PTY supervisor that creates and owns one cgroup per PTY. 7. Prove Session deletion, plugin unload, timeout, and explicit kill terminate a test descendant after it escapes the original process group. 8. Only then create root-owned /etc/opencode/pty-supervisor-verified; candidate startup is blocked without it by ExecCondition. 9. Run systemd-analyze verify /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service.
• 🔴 (05:26) User requires that the in-process PTY plugin and process-group signals never contain a child that calls setsid, daemonizes, or moves into another cgroup.
• 🔴 [enforced-workflow] (05:26) User directs that the readiness marker /etc/opencode/pty-supervisor-verified must never be created before the containment test proves Session deletion, plugin unload, timeout, and explicit kill terminate a descendant that escaped the original process group.
• 🔴 [enforced-workflow] (05:26) User requires explicit approval for cutover because it stops the running service, and directs never to cut over while the PTY supervisor gate is incomplete.
• 🟡 (05:26) CUTOVER.md cutover sequence: 1. Install the candidate as /etc/systemd/system/opencode-v2.service. 2. Run sudo systemctl daemon-reload. 3. Run sudo systemctl stop opencode.service. 4. Run sudo systemctl start opencode-v2.service. 5. After socket bind, verify /api/health, /, /site.webmanifest, /sw.js, and /openapi.json on port 4096. 6. Call POST /api/plugin/await-activation, then confirm followup and local-pty are active via GET /api/plugin. 7. Observe real browser traffic and run one follow-up plus one PTY smoke session. 8. Enable opencode-v2.service only after all checks pass, retaining opencode.service installed but disabled for rollback.
• 🟡 (05:26) CUTOVER.md rollback sequence: 1. Run sudo systemctl stop opencode-v2.service. 2. Run sudo systemctl start opencode.service. 3. Verify the legacy health endpoint and browser UI on port 4096. 4. Disable opencode-v2.service only after legacy service health is confirmed.
• 🔴 (05:26) User states the V2 database remains isolated under /home/byk/.local/share/opencode-v2-pilot/data; rollback never rewrites or deletes either database.
• 🟡 (05:26) /home/byk/.local/share/opencode-v2-pilot contains exactly 7 entries: cache/, config/, CUTOVER.md, data/, opencode-v2.service, state/, and supervisor/.
• 🟡 (05:26) /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service runs as User=byk from WorkingDirectory=/home/byk, reads /home/byk/.opencode/env and /home/byk/.local/share/opencode-v2-pilot/server.env, and sets 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.
• 🟡 (05:26) opencode-v2.service gates startup with ExecCondition=/usr/bin/test -f /etc/opencode/pty-supervisor-verified and launches /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.
• 🟡 (05:26) opencode-v2.service uses Restart=always, RestartSec=5, Nice=-5, LimitNOFILE=65535, LimitNPROC=4096, MemoryMax=13G, MemoryHigh=12G, NoNewPrivileges=true, ProtectSystem=strict, ProtectHome=read-only, ReadWritePaths=/home/byk, and PrivateTmp=yes; it is wanted by multi-user.target.
• 🟡 (05:26) Investigation located go-systemd APIs in /home/byk/go/pkg/mod/github.com/coreos/go-systemd/v22@v22.5.0/dbus/methods.go: StopUnitContext at line 122, StartTransientUnitContext at line 191, GetUnitPropertiesContext at line 272, GetUnitPathPropertiesContext at line 284, and GetUnitTypePropertiesContext at line 347.