Hermit/docs/compat.md

# Platform support: Linux, WSL, macOS

CST-Agent targets POSIX systems: Linux (glibc and musl), WSL 2 and macOS.
Native Windows builds are covered separately in `README-windows.md`.

## Build

| Platform | Dependencies | Build |
|---|---|---|
| Debian / Ubuntu / WSL | `build-essential pkg-config libcurl4-openssl-dev libncurses-dev` | `make` |
| Fedora | `gcc make pkgconf libcurl-devel ncurses-devel` | `make` |
| Arch | `base-devel curl ncurses` | `make` |
| Alpine (musl) | `build-base pkgconf curl-dev ncurses-dev` | `make` |
| NixOS | `nix-shell` (uses `shell.nix`) | `make` |
| macOS | `xcode-select --install`, `brew install ncurses curl pkg-config` | `make` |

`make install PREFIX=~/.local` installs the binary; CMake works too
(`cmake -B build && cmake --build build && ctest --test-dir build`).

The Makefile picks `ncursesw`, then `ncurses`, through pkg-config. On macOS it
adds Homebrew's keg-only `ncurses`/`curl` to `PKG_CONFIG_PATH`; without
Homebrew it falls back to the system `-lncurses` (wide-character capable).

Verified so far: NixOS x86_64 with gcc and clang (`-Werror`, `make check`,
`make asan`, ctest), and every source compiled `-fsyntax-only` with
`x86_64-unknown-linux-musl-gcc` without warnings. Full musl, macOS and WSL
builds run in CI (`.gitea/workflows/ci.yml`; the macOS job needs a runner and
the `HAVE_MACOS_RUNNER` variable) or by hand with the checklist below.

## Files

| What | Where |
|---|---|
| API keys (one per provider, entered in the TUI or with `--ask-key`) | `$XDG_CONFIG_HOME/cst-agent/credentials` (default `~/.config/cst-agent/`), mode 0600 |
| Last provider, models, effort and approval mode | `$XDG_CONFIG_HOME/cst-agent/settings.json` |
| Sessions, undo snapshots, exports | `<workspace>/.agent/` (git-ignored automatically) |
| Saved permission rules | `<workspace>/.agent/permissions.json` |
| Project notes injected into the prompt | `<workspace>/AGENTS.md` (or `CST.md`) |

## Shell sandbox

In the default `auto` approval mode, `run_shell` runs inside an OS sandbox
when one is available. Commands may read and execute anything but may only
write beneath the workspace, the temp directory, `/dev/null` and `/dev/tty`.

| Platform | Sandbox | Notes |
|---|---|---|
| Linux 5.13+ | Landlock (raw syscalls, no extra library) | ABI ≥ 4 (6.7+) also blocks TCP connect/bind |
| Linux 5.5+ without Landlock (Android / Termux, WSL, older distros), x86_64 / aarch64 | seccomp user-notify | refuses IPv4/IPv6 sockets; see below |
| macOS | `sandbox_init` profile | also denies network |
| Older kernels, Windows | none | falls back to the read-only rules |

The status bar and sidebar show `auto · landlock`, `auto · seccomp`,
`auto · seatbelt` or `auto · rules`. `CST_SANDBOX=off` disables the
sandbox; `CST_SANDBOX=landlock` or `CST_SANDBOX=seccomp` allows only that
kind. When a sandboxed command looks blocked, the TUI asks whether to rerun
it outside the sandbox. The policy is built in the parent; the forked child
only makes a few async-signal-safe syscalls before `exec`, so the agent
itself is never confined.

**seccomp.** Used when Landlock is missing, e.g. Android GKI kernels. The
child installs a seccomp filter with a user-notify listener and passes the
listener to a supervisor thread in the agent. Opens with write flags and
every create / remove / rename / link / chmod / chown / utimes / xattr call
stop until the supervisor has read the path from the child's memory,
resolved it (cwd, dirfd, `..`, symlinks, `/proc/self`, `/dev/stdout`) and
answered: continue when it lands in the allowed places, `EACCES` otherwise.
Reads, exec and writes to already-open files are not checked. Background
jobs that outlive their shell are no longer the agent's descendants: with
Yama `ptrace_scope` ≥ 1 (common on desktop distros, absent on Android) the
supervisor cannot read their memory and their checked writes fail with
`EACCES`; once the run has finished they get `ENOSYS`. This keeps
mistakes out of the rest of the disk but is not a security boundary: the
kernel reads the path again after the check, so a hostile multi-threaded
program can swap it in between. The availability check runs in a
throwaway child, so a platform seccomp policy that kills the caller cannot
take the agent down.

## Terminal notes

- UTF-8 locale gives the full UI. Under a non-UTF-8 locale, or with
  `CST_ASCII=1`, box and icon glyphs fall back to ASCII.
- `NO_COLOR=1` turns colours off.
- `/copy` uses OSC 52. iTerm2 needs "Applications in terminal may access
  clipboard"; tmux needs `set -g set-clipboard on`; Windows Terminal (WSL)
  supports it out of the box.
- Bracketed paste needs ncurses (all platforms above).
- macOS Terminal.app sends Option+Enter as Esc+Enter only with "Use Option as
  Meta key"; Ctrl+N always inserts a newline.
- Kitty keyboard protocol: at startup the TUI sends `CSI ? u`; if the terminal
  answers (kitty, WezTerm, foot, Ghostty, WHC Shell, ...) it pushes the
  "disambiguate" flag (`CSI > 1 u`) on the alternate screen and pops it on
  exit. That makes Shift+Enter / Ctrl+Enter (newline), Ctrl+Backspace (delete
  word) and an instant Esc work. Other terminals (and tmux) don't answer and
  keep the legacy keys. If the TUI is killed, the main screen's keyboard mode
  is untouched because the flags live on the alternate screen's stack.

## Acceptance checklist

Run on each platform before a release. Use a scratch git repository as the
workspace and a real API key (entered when the TUI asks for it).

Build and tests:

- [ ] `make` has no warnings; `make check` passes
- [ ] `make asan` passes (Linux; macOS: `make CFLAGS="-fsanitize=address,undefined -g" check`)
- [ ] `cmake -B build && cmake --build build && ctest --test-dir build` passes
- [ ] `make install PREFIX=/tmp/cst && /tmp/cst/bin/cst-agent --help`

CLI:

- [ ] `--list-sessions`, `--new`, `--resume <prefix>`, `--continue` behave as documented
- [ ] `--headless --prompt "list the files"` prints a transcript and exits 0
- [ ] First start asks for a provider and key; the credentials file is mode 0600
- [ ] Second start reuses provider, model and effort without asking

TUI:

- [ ] Typing Chinese/emoji keeps the cursor in the right column; ←→ Home End work
- [ ] Pasting a multi-line block does not send it; Enter sends
- [ ] `/` shows the command popup, Tab completes, `@` completes file paths
- [ ] Esc cancels a running turn; Esc on an empty prompt does nothing; Ctrl+C twice quits
- [ ] A long `run_shell` (e.g. `sleep 30`) stops promptly on Esc
- [ ] Write permission shows the diff; `a` saves a rule; `p` saves a shell prefix rule
- [ ] `ask_user` modal accepts a number, an arrow selection and typed text
- [ ] Todo panel appears while tasks are open; Ctrl+T hides it
- [ ] `/undo` restores files changed by the last turn; `/retry` re-asks
- [ ] `/diff`, `/export`, `/status`, `/tools off grep`, `/yolo` work
- [ ] Mouse: click a tool card to expand it, click in the input to move the
      cursor, click a picker row; `/mouse` turns it off
- [ ] Tab toggles Build/Plan, Shift+Tab cycles ask/auto/yolo, Ctrl+P opens the palette
- [ ] `/model` lists the provider's `/models` (marked `(api)`); a wrong key is re-asked
- [ ] `auto` mode: `echo x > ~/outside` in run_shell asks "Rerun outside the
      sandbox?" (Linux/Termux/macOS); with `CST_SANDBOX=off`, `ls` runs and `touch x` asks
- [ ] Resize the terminal during streaming: layout recovers
- [ ] `NO_COLOR=1` and `CST_ASCII=1` render readable screens

WSL specifics:

- [ ] Workspace under `/mnt/c/...` works (slower IO is expected); `~/project` is recommended
- [ ] Windows Terminal: mouse wheel scroll and OSC 52 `/copy`

macOS specifics:

- [ ] Builds with Homebrew ncurses and with the system ncurses (`brew unlink ncurses`)
- [ ] Terminal.app and iTerm2: arrows, Home/End, PgUp/PgDn, bracketed paste