ollie/doc/compatibility-roadmap.md

Compatibility roadmap

This document records compatibility observations and possible future work. It is not an implementation plan. The current Linux-first behavior remains acceptable; these items can be prioritized when broader host support becomes useful.

Target architecture

olliesrv
  agent runtime, orchestration, and 9P service
  preferably host-neutral
       │
       └── toolsrv
             host-dependent tool execution boundary
             execution, filesystem, process, networking, sandbox

toolsrv should be extensible to other host systems so Ollie tools remain useful to as many people as possible. olliesrv may remain Linux-specific if that keeps the agent runtime simpler, but its current implementation has only a small set of host-specific assumptions and may be portable with limited work.

olliesrv

Current status

olliesrv is primarily implemented with portable Go facilities:

• 9P protocol handling over net.Conn.
• Unix and TCP listeners.
• Filesystem persistence and configuration.
• Context cancellation, goroutines, and process supervision.
• Provider and agent runtime logic.

The Plan 9 client dependency is a Go 9P implementation. olliesrv does not require an external namespace service. The default namespace lookup follows the standard $NAMESPACE convention, with a derived /tmp/ns... fallback; the service creates the directory when needed and removes it only when empty.

Compatibility observations

• cmd/olliesrv/internal/toolclient/spawn.go sets syscall.SysProcAttr.Pdeathsig for local toolsrv and remote SSH processes.
• Pdeathsig is available on Linux and FreeBSD but not macOS. Its use currently prevents builds on macOS and other systems whose SysProcAttr lacks that field.
• The same file uses Setpgid for remote SSH process management. This is also OS-specific and should be isolated if process-group behavior is retained.
• Existing context cancellation, explicit process killing, waiting, and toolsrv idle timeouts already provide most lifecycle management. Removing Pdeathsig is therefore a viable future option.
• A portable parent-death pipe is another possible option if orphan cleanup must remain consistent across hosts.
• Local session metadata hard-codes Platform: "linux" in session setup and local process metadata. It should eventually use runtime.GOOS or host-provided metadata.
• Remote deployment currently assumes bash, tar, ssh, and a Linux toolsrv binary. Remote host detection and platform-specific toolsrv artifacts will be needed for non-Linux remote hosts.
• D-Bus desktop notifications are optional at runtime, but the dependency is currently compiled into olliesrv. The notification integration could later be isolated or replaced with a host/frontend-specific notifier.

Possible future directions

1. Remove Pdeathsig and Setpgid from common code and rely on existing lifecycle cleanup.
2. Keep stronger process attributes in OS-specific files for Linux and FreeBSD.
3. Add a portable parent-death pipe when consistent orphan cleanup is required.
4. Add explicit socket/listen configuration so the service does not depend on an implicit Plan 9 namespace directory.
5. Detect and propagate local and remote platform metadata.
6. Separate remote deployment from the assumption that the host runs Linux.

toolsrv

Current status

toolsrv is currently Linux-specific. Restricted execution uses native Landlock system calls in a short-lived helper process. The installed sandbox policy and execution path assume Linux Landlock semantics.

The toolsrv protocol and namespace are more portable than the execution implementation. olliesrv communicates with toolsrv through authenticated 9P over a Unix socket, and remote execution already treats toolsrv as a separately deployed process.

Compatibility areas

Supporting other hosts will require platform-specific implementations for more than sandboxing:

• Tool process creation and lifecycle.
• Process groups, signals, and cancellation.
• Filesystem policy enforcement.
• Network policy enforcement.
• Environment and path handling.
• Resource limits and process supervision.
• Host metadata and capability reporting.
• Local and remote binary deployment.

Possible sandbox mechanisms include Capsicum and jails on FreeBSD, and the platform sandbox facilities on macOS. These mechanisms do not necessarily express the same path-based policy as Landlock, so each backend must declare its enforcement limits rather than silently weakening policy.

Possible future directions

1. Keep the generic sandbox interface and add OS-specific implementations behind it.
2. Define a host capability model for filesystem, process, network, and sandbox features.
3. Make tool execution report unsupported or degraded policy enforcement explicitly.
4. Build and deploy toolsrv artifacts per target host and architecture.
5. Add host-specific tests without making Linux behavior conditional at runtime.

WSL2

WSL2 provides a Linux kernel in a VM. It should use the existing Linux olliesrv and toolsrv implementations, subject to the kernel and distribution providing the required Linux features, including Landlock support.

Decision status

No compatibility work is scheduled now. This roadmap records the design boundary and observations for later prioritization.