Distillation

Date: Sep 8, 2026

• 🔴 (04:09) User-provided systemd.kill(5) documentation stated KillMode= accepts control-group, mixed, process, or none; defaults to control-group; process is not recommended and none is strongly discouraged because processes may escape unit lifecycle/resource management.
• 🔴 (04:09) User-provided systemd.kill(5) documented shutdown sequencing: the configured initial signal is sent first, optionally followed immediately by SIGHUP; surviving processes later receive SIGKILL or FinalKillSignal= unless SendSIGKILL= disables it.
• 🔴 (04:09) User-provided systemd.kill(5) stated KillSignal= defaults to SIGTERM and systemd will always send SIGCONT immediately after the configured signal so suspended tasks can terminate cleanly.
• 🔴 (04:09) User-provided systemd.kill(5) stated RestartKillSignal= controls the initial signal during restart, defaults to the KillSignal= value, and was added in systemd version 244.
• 🔴 (04:09) User-provided systemd.kill(5) stated SendSIGHUP= defaults to no; SendSIGKILL= defaults to yes; FinalKillSignal= defaults to SIGKILL; and WatchdogSignal= defaults to SIGABRT.
• 🔴 (04:09) User-provided systemd.kill(5) noted FinalKillSignal=SIGQUIT or SIGABRT, together with LimitCORE=, can generate a coredump when debugging services that fail to terminate.
• 🔴 (04:09) User-provided documentation was from systemd version 255.
• 🔴 (04:09) User-provided intended pilot unit path was /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service.
• 🔴 (04:10) User-provided /home/byk/.local/share/opencode-v2-pilot/opencode-v2.service had [Unit] settings Description=OpenCode V2 Server and After=network.target.
• 🔴 (04:10) User-provided opencode-v2.service had [Service] settings: Type=simple; EnvironmentFile=/home/byk/.opencode/env; EnvironmentFile=/home/byk/.local/share/opencode-v2-pilot/server.env; Environment=OPENCODE_CONFIG_DIR=/home/byk/.local/share/opencode-v2-pilot/config/opencode; Environment=OPENCODE_DB=/home/byk/.local/share/opencode-v2-pilot/data/opencode/opencode.db; Environment=XDG_DATA_HOME=/home/byk/.local/share/opencode-v2-pilot/data; Environment=XDG_CACHE_HOME=/home/byk/.local/share/opencode-v2-pilot/cache; Environment=XDG_CONFIG_HOME=/home/byk/.local/share/opencode-v2-pilot/config; and Environment=XDG_STATE_HOME=/home/byk/.local/share/opencode-v2-pilot/state.
• 🔴 (04:10) User-provided opencode-v2.service ran with User=byk, WorkingDirectory=/home/byk, and startup gate ExecCondition=/usr/bin/test -f /etc/opencode/pty-supervisor-verified.
• 🔴 (04:10) User-provided opencode-v2.service used ExecStart=/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.
• 🔴 (04:10) User-provided opencode-v2.service configured Restart=always, RestartSec=5, Nice=-5, LimitNOFILE=65535, LimitNPROC=4096, MemoryMax=13G, and MemoryHigh=12G.
• 🔴 (04:10) User-provided opencode-v2.service hardening settings were NoNewPrivileges=true, ProtectSystem=strict, ProtectHome=read-only, ReadWritePaths=/home/byk, and PrivateTmp=yes.
• 🔴 (04:10) User-provided opencode-v2.service had [Install] setting WantedBy=multi-user.target; the file contained 33 lines.
• 🔴 (04:10) User-provided identity output showed uid=1000(byk) gid=1000(byk) with groups 1000(byk), 4(adm), 24(cdrom), 27(sudo), 30(dip), 46(plugdev), 101(lxd), and 111(docker).
• 🔴 (04:10) User-provided socket metadata showed /run/dbus/system_bus_socket was uid=0 gid=0 mode=666.
• 🔴 (04:10) User-provided socket metadata showed /var/run/docker.sock was a socket with uid=0 gid=111 mode=660.
• 🔴 (04:10) User-provided stat results showed neither /var/lib/lxd/unix.socket nor /var/snap/lxd/common/lxd/unix.socket existed; both returned stat: cannot statx ...: No such file or directory.
• 🟡 (04:11) Investigation checklist status: 1. “Inspect current pilot service, plugin code, host systemd versions, cgroup layout, and applicable local guidance” — completed, high priority; 2. “Verify systemd-run --pipe behavior and containment/authentication semantics from local docs/source” — completed, high priority; 3. “Analyze protocol, races, resource bounds, restart behavior, and same-UID impersonation threat” — completed, high priority; 4. “Produce concrete minimal architecture, commands/properties, risks, and merge verdict” — in progress, high priority.
• 🟡 (04:13) Investigation checklist was completed in full; “Produce concrete minimal architecture, commands/properties, risks, and merge verdict” changed from in progress to completed.
• 🟡 (04:13) Assistant’s verdict was DO-NOT-MERGE the approach exactly as proposed; a revised pilot could be viable only after the identified authentication, cwd, lifecycle, resource, and external-delegation issues were implemented and smoke-tested.
• 🟡 (04:13) Assistant found systemd-run --pipe could transport interactive bytes to /usr/bin/script, while KillMode=control-group could contain ordinary forks, double-forks, setsid(), and daemonization; rejection reasons were: exact cgroup membership cannot distinguish the server from same-UID children, pathname-only cwd has an authorization-to-execution race, killing systemd-run does not reliably stop its transient unit, --wait --collect --quiet lacks reliable structured signal/timeout status, supervisor/client failure can strand units without binding, PTYs as sibling units escape the service’s 13 GB memory and 4096-task limits, and Docker access allows work to be created outside the PTY cgroup.
• 🟡 (04:13) Assistant reported verified host state: Linux 6.8.0-117-generic; systemd 255.4-1ubuntu8.17; util-linux script 2.39.3; system bus available at /run/dbus/system_bus_socket; no usable user bus because systemctl --user returns No medium found; unified cgroup v2; deployed service /system.slice/opencode.service; intended opencode-v2.service not installed.
• 🟡 (04:13) Assistant reported code/service findings: intended unit runs as byk with NoNewPrivileges=true, PrivateTmp=yes, MemoryMax=13G, and LimitNPROC=4096; startup is gated by ExecCondition=/usr/bin/test -f /etc/opencode/pty-supervisor-verified; plugins/pty.ts:223-230 launches detached process groups; plugins/pty.ts:556-595 holds an open cwd directory descriptor during authorization; plugins/pty.ts:287-299 bounds output retention to 1 MB; service cgroup files are root-owned and not delegated.
• 🟡 (04:13) Assistant explicitly stated no files, units, or services were changed or started.
• 🟡 (04:13) Assistant explained that local systemd-run(1) and systemd v255 source confirm --pipe passes original stdin/stdout/stderr descriptors to PID 1 as StandardInputFileDescriptor, StandardOutputFileDescriptor, and StandardErrorFileDescriptor; with --pipe or --wait, systemd-run monitors the transient unit until inactive.
• 🟡 (04:13) Assistant described the viable data path as plugin <-> supervisor <-> pipes/socketpair <-> script <-> PTY slave <-> command; /usr/bin/script allocates the actual PTY even though the supervisor has no terminal.
• 🟡 (04:13) Assistant recommended --pipe, not --pty; when both are supplied, --pipe wins whenever the supervisor descriptors are not terminals.
• 🟡 (04:13) Assistant listed four systemd-run --pipe qualifications: 1. script can hang after piped stdin EOF, so explicit unit stop—not EOF—must handle disconnect; 2. the design lacks resize support, acceptable because pilot scope is spawn/write/output/kill/exit; 3. script -c accepts one shell command string, requiring fixed POSIX single-quote encoding and encoded-argv bounds; 4. use --expand-environment=no because manager-side ${...} expansion is the default.
• 🟡 (04:13) Assistant recommended a root-owned Unix stream socket at /run/opencode-pty/supervisor.sock, owned root:byk with mode 0660; filesystem permissions reduce exposure but do not authenticate the server because any byk child can connect.
• 🟡 (04:13) Assistant specified fail-closed authentication checks, in order: 1. read SO_PEERCRED; 2. require UID 1000 and expected GID; 3. obtain SO_PEERPIDFD; 4. require pidfd kernel support with no fallback to unpinned /proc/<pid>; 5. query PID 1 for MainPID, ControlGroup, ActiveState, SubState, and InvocationID of fixed unit opencode-v2.service; 6. require peer PID equal MainPID; 7. require ActiveState=active; 8. require exact cgroup 0::/system.slice/opencode-v2.service; 9. retain the peer pidfd and authenticated connection for its lifetime; 10. kill every unit owned by that connection when it closes.
• 🟡 (04:13) Assistant warned the exact expected cgroup must change if the server moves to a different slice.
• 🟡 (04:13) Assistant’s same-UID threat analysis: SO_PEERCRED fixes credentials at connect time; a child cannot claim its parent PID; forging SCM_CREDENTIALS with another PID requires CAP_SYS_ADMIN; security therefore requires equality with systemd’s current MainPID, because accepting any PID in /system.slice/opencode-v2.service permits child impersonation.
• 🟡 (04:13) Assistant required authenticated client descriptors to be CLOEXEC so children cannot inherit the socket; normal Node spawning then closes those descriptors during exec.
• 🟡 (04:13) Assistant clarified the trust boundary: a fully compromised authenticated server remains trusted; the supervisor protects against siblings and descendants, not the authenticated server process itself.
• 🟡 (04:13) Assistant selected one SOCK_STREAM connection per PTY because Node’s standard net API supports Unix stream sockets but not general SCM_RIGHTS; one connection per PTY avoids cross-session head-of-line blocking and makes connection closure unambiguously stop that PTY’s unit.
• 🟡 (04:13) Assistant specified binary framing as uint32_be payload_length, then uint8 message_type, then payload bytes.
• 🟡 (04:13) Assistant specified protocol limits: maximum incoming frame 80 KiB; write payload 65,536 UTF-8 bytes after escape decoding; command 4,096 bytes; 128 arguments; each argument 16,384 bytes; aggregate encoded argv 65,536 bytes; 25 supervisor sessions; pending output 256 KiB/session; pending input 64 KiB/session; control-frame queue fixed to a small count such as 16/connection.
• 🟡 (04:13) Assistant specified message types, in order: spawn, spawned, output, write, written, kill, exit, error.
• 🟡 (04:13) Assistant prohibited client control of: unit name; systemd property names/values; user/group; executable paths for systemd-run or script; slice/dependency names; environment-variable names; and supervisor-side paths.
• 🟡 (04:13) Assistant required supervisor-generated unit names from 128 random bits in format opencode-pty-<32 lowercase hexadecimal characters>.service, with collisions rejected rather than reused.
• 🟡 (04:13) Assistant required preserving the existing cwd authorization’s open directory descriptor rather than sending only a canonical pathname to WorkingDirectory=.
• 🟡 (04:13) Assistant specified cwd handoff steps: 1. plugin opens authorized directory and keeps its FileHandle; 2. spawn sends numeric fd, expected st_dev, expected st_ino, and canonical display path; 3. after authenticating exact MainPID, supervisor opens /proc/<peer-pid>/fd/<fd-number>; 4. supervisor verifies it is a directory, compares device/inode, and retains the duplicate; 5. the retained descriptor pins initial cwd.
• 🟡 (04:13) Assistant compared two cwd implementations. Preferred: a tiny fixed launcher receives one setup frame plus one directory fd via SCM_RIGHTS, calls fstat() and fchdir(), clears and reconstructs the environment, sends a fixed readiness record, executes /usr/bin/script, and keeps the socket as interactive stdin. CLI-only alternative: BindPaths=/proc/<supervisor-pid>/fd/<cwd-fd>:<canonical-path> plus WorkingDirectory=<canonical-path>, retaining the descriptor until startup succeeds.
• 🟡 (04:13) Assistant chose the launcher as smaller and easier to prove; the CLI-only bind-mount alternative remained unverified on this host because systemd applies mount namespace setup before changing to User=byk but working-directory setup afterward, /proc/<root-supervisor>/fd/... had not been smoke-tested, and paths containing : require rejection or correct systemd escaping.
• 🟡 (04:13) Assistant proposed direct argv invocation of /usr/bin/systemd-run with: --system, --no-ask-password, --quiet, --pipe, --wait, --collect, --service-type=exec, --expand-environment=no, --unit="opencode-pty-${RANDOM_HEX}.service", --slice=opencode-pty.slice, and then /usr/libexec/opencode-pty-launcher /usr/bin/script -qefc "${ENCODED_COMMAND}" /dev/null.
• 🟡 (04:13) Assistant proposed transient-unit properties: User=byk, Group=byk, NoNewPrivileges=yes, UMask=0077, KillMode=control-group, KillSignal=SIGTERM, FinalKillSignal=SIGKILL, SendSIGKILL=yes, SendSIGHUP=yes, TimeoutStopSec=2s, OOMPolicy=kill, Delegate=no, BindsTo=opencode-pty-supervisor.service, After=opencode-pty-supervisor.service, InaccessiblePaths=/run/dbus/system_bus_socket, InaccessiblePaths=-/run/user/1000/bus, InaccessiblePaths=-/var/run/docker.sock, and InaccessiblePaths=-/run/docker.sock.
• 🟡 (04:13) Assistant required adding --property="RuntimeMaxSec=${TIMEOUT_SECONDS}s" when a request includes a timeout.
• 🟡 (04:13) Assistant required constructing the launcher and supervisor command as an argv array and never invoking a shell around systemd-run.
• 🟡 (04:13) Assistant required script -c arguments to use POSIX quoting pattern 'text with '\'' embedded quotes', matching plugins/pty.ts:518-520.
• 🟡 (04:13) Assistant required preserving the plugin’s fixed environment exactly: HOME=/home/byk, LANG=C.UTF-8, PATH=/usr/bin:/bin, SHELL=/bin/sh, and TERM=xterm-256color.
• 🟡 (04:13) Assistant prohibited forwarding the server environment because /home/byk/.opencode/env may contain credentials; preferred launcher behavior was clearenv() followed by setting only the five fixed variables, rather than relying solely on systemd Environment= overrides.
• 🟡 (04:13) Assistant explained cgroup-v2 containment: setsid() changes only session/process-group membership; forks and double-forks retain cgroup membership; the unit has no delegation and root-owned cgroup files; KillMode=control-group signals every remaining unit process; after TimeoutStopSec=2s, systemd sends SIGKILL.
• 🟡 (04:13) Assistant required stopping by unit name with /usr/bin/systemctl stop "opencode-pty-${RANDOM_HEX}.service" and prohibited killing only the script PID, a process group, the systemd-run helper, or apparent shell leader.
• 🟡 (04:13) Assistant warned this is not a general sandbox because commands can delegate to daemons outside their cgroup; specifically, Docker group access permits requests through /var/run/docker.sock to launch work outside the PTY unit, so both /var/run/docker.sock and /run/docker.sock must be masked.
• 🟡 (04:13) Assistant also required masking system and user D-Bus sockets to prevent present or future externally managed work; network-based delegation through SSH, remote job systems, or local APIs remains an unavoidable pilot risk unless a behavior-changing network sandbox is added.
• 🟡 (04:13) Assistant noted transient PTY units are siblings rather than descendants of opencode-v2.service, so they do not inherit MemoryMax=13G, MemoryHigh=12G, or the task limit.
• 🟡 (04:13) Assistant proposed dedicated opencode-pty.slice aggregate limits: [Slice], MemoryHigh=8G, MemoryMax=10G, and TasksMax=2048; values were characterized as policy choices, but an unlimited slice was unacceptable because per-unit limits do not enforce the 25-session aggregate.
• 🟡 (04:13) Assistant required atomic supervisor capacity reservation before invoking systemd-run, released only after launch failure or final unit exit.
• 🟡 (04:13) Assistant defined lifecycle states in order: reserved -> starting -> running -> stopping -> exited.
• 🟡 (04:13) Assistant specified lifecycle/race rules: reserve before launch; subscribe to unit events before starting systemd-run; record generated unit name before external operations; mark disconnected-during-launch reservations canceled; wait for unit creation to fail or become observable before stopping it rather than merely killing systemd-run; treat unit not found as successful stop only after conclusive launch failure/exit; accept writes only in running; serialize writes/session; stop on protocol error, oversized frames, authentication loss, or connection close; emit exit only after both output descriptors EOF to preserve ordering; never reuse session or unit IDs.
• 🟡 (04:13) Assistant recommended BindsTo=opencode-pty-supervisor.service plus After=opencode-pty-supervisor.service so systemd stops PTY units when the supervisor becomes inactive.
• 🟡 (04:13) Assistant required supervisor startup cleanup to enumerate only strict generated-name matches, verify each unit’s BindsTo, and stop them before accepting clients; it must never act on a caller-provided prefix.
• 🟡 (04:13) Assistant explained --collect removes failed and successful transient units after completion but does not replace explicit stop handling.
• 🟡 (04:13) Assistant found systemd-run --wait process status insufficient for precise API reporting: normal nonzero exits propagate, signals map to a generic exception status, and timeout/watchdog/OOM/explicit kill/direct signal require systemd properties Result, ExecMainCode, and ExecMainStatus; --quiet hides the human summary and --collect may promptly remove the unit.
• 🟡 (04:13) Assistant required sd-bus monitoring while each unit exists and proposed structured exit output containing type, exitCode, exitSignal, result, timedOut, and oomKilled, exemplified by {"type":"exit","exitCode":0,"exitSignal":null,"result":"success","timedOut":false,"oomKilled":false}; human-readable systemd-run stderr must not be parsed.
• 🟡 (04:13) Assistant compared transient-unit launch approaches: CLI systemd-run was considered viable for the pilot but still requires sd-bus lifecycle monitoring; direct StartTransientUnit through sd-bus was presented as stronger because it removes one helper, provides an atomic start reply, directly passes descriptors, and exposes structured lifecycle state.
• 🟡 (04:13) Assistant’s exact merge acceptance gate required proving all 14 items on the host: 1. only current MainPID of opencode-v2.service connects; 2. same-cgroup child authentication fails; 3. PID exit/reuse cannot authenticate; 4. cwd inode survives pathname replacement; 5. interactive reads/writes work through script; 6. pre-exit output ordering is preserved; 7. backpressure bounds supervisor memory; 8. setsid() and double-fork descendants die on stop; 9. Docker and D-Bus sockets are inaccessible; 10. client disconnect during every launch phase leaves no unit; 11. supervisor crash/restart leaves no process or unit; 12. timeout, signal, normal exit, OOM, and explicit kill yield correct structured records; 13. failed units disappear after collection; 14. 25 concurrent sessions respect aggregate slice limits.