document compatibility roadmap

doc/compatibility-roadmap.md

@@ -0,0 +1,90 @@
+# 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
+
+```text
+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 directly require the plan9port plumber. The default namespace lookup follows plan9port-style conventions (`$NAMESPACE`, then a derived `/tmp/ns...` path), but this can be replaced or made explicit later.
+
+### 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.