SUPERVISOR

The fleet plane.

retrace grew past one process. retraced owns every traced binary on a host — registry, versioned policy, a hash-chained journal, and a live command channel — while telemetry keeps flowing over the existing OTLP plane. The CLI (retrace-ctl) speaks to it; the kernel enforcement compiler (retrace-profile enforce) takes its last word.

1 · The doctrine

Two planes

Control (low-rate, request/response + events, UDS locally, TLS remotely) is separate from telemetry (OTLP, unchanged). The supervisor never builds a second telemetry protocol — it attaches session id, policy epoch, host as an OTLP relay.

Fail-open liveness, fail-closed policy

A dead supervisor never kills a traced process; that is the same bounded, never-block discipline as the live-stream thread. The last-applied jail policy stays in force forever. Agent code lives off the engine hot path so any agent bug degrades to "no control channel" — never to a target crash.

Find with kernel truth, act with the preload

Kernel observation (eBPF on Linux, ETW on Windows) isspectator only; kernel enforcement (Landlock, seccomp, Seatbelt, AppContainer) is fail-closed; only the preload plane rewrites arguments. The three planes are graded against each other, never conflated.

The nonce doctrine

A HELLO without the spawner's nonce seats as a spectator: evidence always, policy never. A nonce-carrying HELLO takes a full seat and participates in policy.

2 · retraced — the daemon

retraced [--sock PATH] [--journal PATH] [--policy FILE] [--ctl PATH]
         [--nonce HEX32 | --nonce-file PATH]
         [--tls-listen HOST:PORT --tls-cert PEM --tls-key PEM --tls-ca PEM]
         [--user NAME] [--group NAME] [--fd N]
         [--exit-after N]
--sockAgent socket (UDS; default /tmp/retraced.agent.sock).
--journalThe hash-chained JSONL journal.
--policy FILEA policy file pushed to every registering agent.
--ctlLocal controller socket; PEERCRED-gated.
--nonce / --nonce-fileAgent channel nonce. No nonce → spectator: evidence, never policy.
--tls-* (all four)Fleet control plane: TLS 1.3 mutual auth only. Certs carry claim scopes in URI SAN. No plaintext remote mode exists.
--user / --groupPrivilege drop after every bind; a failed drop exits elevated never silently.
--fd NSocket activation (systemd LISTEN_FDS). Inherited listeners never unlinked.
--exit-after NHarness guard. An orphaned daemon cannot outlive its CI run.

The journal is append-only and hash-chained. Control-plane records flush the moment they are written; routine telemetry is buffered; an unclean shutdown leaves a recorded gap (retrace.journal.unclean) — never a silent one. Reboot replays; a broken chain refuses to start.

3 · retrace-ctl — the fleet CLI

retrace-ctl [--sock PATH] COMMAND              # local UDS controller
retrace-ctl --tls-host H:P --tls-cert PEM --tls-key PEM --tls-ca CA COMMAND   # fleet, mTLS
statusDaemon health + active sessions summary.
psLive session table -- pids, ppids, host/role, uptime.
driftPer-session libc-vs-kernel drift verdicts since last push.
policy-push FILESign + relay a POLICY_SET to every full seat.
freeze / thawSuspend and resume deny emission (snapshot tests).
kill PIDReap a workload through the control plane.
spawn --preload LIB -- ARGV...Fork the workload armed to join the daemon itself.

Every command maps to a claim scope (a URI SAN bit likeretrace:scope:status+ps+policy+kill). A peer whose cert lacks the scope is refused withscope denied and the attempt is journaled asretrace.auth.overscope. Local UDS peers hold all scopes (PEERCRED already gates the accept).

4 · Sessions & trees

# 1. fork the workload armed to join the daemon itself
retrace-ctl --sock /tmp/retraced.ctl.sock \
    spawn --preload /usr/lib/libretrace.so -- /usr/bin/detonation arg

# 2. inspect the live tree (depth-recursive; no fixed scan level)
retrace-ctl ps --tree

# 3. push a new jail policy to every full seat
retrace-ctl policy-push strict-jail.json

# 4. reap any session through the control plane
retrace-ctl kill <pid>

Every departure — natural exit, crash, or kill — is journaled (retrace.ctl.exit: pid, how, code) by the reap doctrine. A specimen that crashes, is killed, or leaves on its own is never a silent gap in the audit trail and never a zombie either. The session tree the registry carries is the tree the CLI prints, at every depth.

5 · Kernel enforcement & signed audit

# 1. observed-set -> policy
retrace-profile capture -o profile.json -- ./target

# 2. profile + declared set -> executable spec
retrace-profile enforce profile.json --inside declared.json -o spec.json

# 3. the spec seals with Ed25519 and runs under retrace-enforce
retrace-enforce --audit trail.jsonl --audit-key ed.pem spec.json -- ./target

One declared-set, four enforcement planes — Landlock, seccomp, Seatbelt, AppContainer — each exec bound to a hash-chained, Ed25519-signed audit trail that fails closed on tamper. A verify-audit chain re-derives everything it reads; swapping a seal or a key names itself.