Distillation

Date: Sep 8, 2026

• 🔴 [enforced-workflow] (05:24) User directive: run package tests from package directories such as packages/opencode; never run package tests from the repo root.
• 🔴 (05:24) User stated this codebase uses Effect for typed, composable TypeScript services, schemas, and workflows and requires current Effect v4 / effect-smol APIs rather than memory or older Effect v2/v3 examples.
• 🔴 [enforced-workflow] (05:24) User requires Effect-specific work to first inspect .opencode/references/effect-smol for exact APIs, examples, tests, and naming patterns; if missing, clone https://github.com/Effect-TS/effect-smol into that project path, not the skill folder. Existing repository code must also be inspected for local house style.
• 🔴 (05:24) User’s Effect implementation conventions: use Effect.gen(function* () { ... }) for multi-step workflows; use Effect.fn("Name") or Effect.fnUntraced(...) for reusable service methods or important workflows; prefer Effect Schema, branded schemas for IDs, and Schema.TaggedErrorClass for new typed domain errors.
• 🔴 (05:24) User’s Effect architecture conventions: keep HTTP handlers thin—decode input, read request context, call services, and map transport errors; place business rules in services; prefer Effect-aware platform abstractions where surrounding code does; keep layer composition explicit and avoid broad hidden provisioning.
• 🔴 (05:24) User prohibits introducing any, non-null assertions, unchecked casts, or older Effect APIs merely to satisfy types.
• 🔴 (05:24) User’s Effect testing conventions: use testEffect(...) from packages/opencode/test/lib/effect.ts for Effect services, layers, runtime context, scoped resources, and platform integrations; use it.live(...) for filesystem, Git repositories, HTTP servers, sockets, child processes, locks, real time, and other live platform behavior; prefer explicit test layers over ad hoc managed runtimes; use scoped fixtures and finalizers for temporary directories, flags, databases, fibers, servers, and global state.
• 🟡 (05:24) User-provided directory /home/byk/.local/share/opencode-v2-pilot/supervisor contains bin/, cmd/, go.mod, go.sum, internal/, opencode-pty-supervisor.service, opencode-pty.slice, PROTOCOL.md, and ROOT-ACCEPTANCE.md; related plugins are /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts and /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/followup.ts.
• 🟡 (05:24) /home/byk/.local/share/opencode-v2-pilot/supervisor/go.mod defines module opencode-pty-supervisor, Go 1.22, with github.com/coreos/go-systemd/v22 v22.5.0, github.com/godbus/dbus/v5 v5.1.0, and golang.org/x/sys v0.20.0.
• 🟡 (05:24) internal/protocol/frame.go defines protocol constants HeaderSize=12, MaxFrameSize=64 * 1024, MaxIOPayloadSize=32 * 1024, Version=1, frame types TypeStart=1, TypeInput=2, TypeOutput=3, TypeExit=4, TypeError=5, plus MaxArgs=128, MaxArgSize=4096, and MaxRuntimeSec=3600; frame magic is OPTY.
• 🟡 (05:24) internal/protocol/frame.go implements ReadFrame, WriteFrame, EncodeStart, DecodeStart, MarshalFrame, ParsePacket, parseHeader, and writeAll; Start carries Device uint64, Inode uint64, RuntimeSec uint32, and Args []string. Validation rejects empty command names, zero or more than 128 arguments, arguments over 4096 bytes, NUL-containing decoded arguments, runtimes over 3600 seconds, malformed/trailing payloads, unknown frame types, and frames over 64 * 1024 bytes.
• 🟡 (05:24) internal/protocol/frame_test.go includes TestStartRoundTrip, TestFrameRoundTrip, TestRejectsOversizedFrame, TestRejectsNULArgument, and FuzzParsePacket.
• 🟡 (05:24) internal/supervisor/auth.go authenticates Unix peers using SO_PEERCRED and SO_PEERPIDFD; it requires the peer PID to equal systemd’s current MainPID, service state to be "active", and control group to equal expectedClientCgroup, validates liveness with unix.PidfdSendSignal(pidfd, 0, nil, 0), then re-queries service identity to detect authentication-time changes.
• 🟡 (05:25) internal/supervisor/auth_test.go includes TestAuthenticateCurrentPeer, TestAuthenticateRejectsWrongMainPID, and TestAuthenticateRejectsInactiveService.
• 🟡 (05:25) internal/supervisor/systemd.go defines clientService="opencode-v2.service", supervisorService="opencode-pty-supervisor.service", ptySlice="opencode-pty.slice", expectedClientCgroup="/system.slice/opencode-v2.service", launcherPath="/usr/local/libexec/opencode-pty-launcher", unitPrefix="opencode-pty-", unitSuffix=".service", and stopTimeout=15 * time.Second; valid transient names match ^opencode-pty-[0-9a-f]{32}\.service$.
• 🟡 (05:25) internal/supervisor/systemd.go’s unitProperties(...) configures transient units with User="byk", Group="byk", NoNewPrivileges=true, UMask=0077, KillMode="control-group", KillSignal=15, FinalKillSignal=9, SendSIGKILL=true, OOMPolicy="kill", Delegate=false, RemainAfterExit=true, CollectMode="inactive", Slice=opencode-pty.slice, and bindings/order against opencode-pty-supervisor.service; it blocks /run/dbus/system_bus_socket, /run/docker.sock, /run/user/1000/bus, and /var/run/docker.sock, and sets RuntimeMaxUSec when runtimeSec > 0.
• 🟡 (05:25) internal/supervisor/systemd.go implements ClientState, transient-unit Start, signal-driven Wait, validated StopAndWait, subscribeUnitSignals, and CleanupOrphans; orphan cleanup only stops valid matching units whose sole BindsTo entry is opencode-pty-supervisor.service.
• 🟡 (05:25) internal/supervisor/systemd_test.go includes TestUnitNameGrammar, TestUnitPropertiesAreFixed, and TestDecodeUnitResult; invalid-name cases cover an empty identifier, uppercase hexadecimal, .scope, and path traversal suffixes.
• 🟡 (05:25) internal/supervisor/server.go defines socketPath="/run/opencode-pty/supervisor.sock", maxSessions=16, socketBufferSize=128 * 1024, and handshakeTimeout=5 * time.Second; Serve requires effective UID 0, cleans orphan units before listening, caps concurrent sessions at 16, and returns a TypeError frame containing "session limit reached" when full.
• 🟡 (05:25) internal/supervisor/server.go authenticates the connection, receives a TypeStart frame plus exactly one directory FD, verifies the directory’s device/inode against Start.Device and Start.Inode, creates a random unit name from 16 random bytes, starts a systemd transient unit, proxies input/output through framed Unix sockets, emits a TypeExit payload, and defers StopAndWait.
• 🟡 (05:25) internal/supervisor/server.go creates /run/opencode-pty/supervisor.sock, assigns ownership root plus the GID resolved for user byk, and sets mode 0660; existing non-socket paths are rejected rather than removed.
• 🟡 (05:25) internal/supervisor/server_test.go includes TestReceiveStartWithDirectoryDescriptor, TestReceiveStartRejectsMetadataMismatch, TestReceiveStartHandlesFragmentedHeader, TestCopyInputRejectsOutputFrame, and TestExitPayloadEncodingIsBounded.
• 🟡 (05:25) cmd/supervisor/main.go creates a context canceled by SIGINT or SIGTERM, constructs supervisor.NewSystemdManager(ctx), defers manager.Close(), and runs supervisor.NewServer(manager).Serve(ctx), printing errors to stderr and exiting with status 1.