rea/docs/process-capture.md

Process capture

Process Capture runs one caller-selected command and records bounded evidence about its terminal behavior, scheduled interactions, process lifetime, and selected filesystem state. Use it to compare two direct runs of the same scenario, such as an authority build and a reconstruction. It does not replay a previous execution or emulate dependencies.

The command runs with the current user's permissions and inherits the host environment before applying the scenario's explicit overrides. This is not a sandbox. Filesystem observation paths select what REA snapshots; they do not restrict what the process can read or write. The inherited environment is not recorded, so its influence may remain unknown.

The installed PTY backend cannot preserve an explicit environment name __proto__. REA rejects that override before launch; use /usr/bin/env with __proto__=VALUE as an argument when that literal variable is required. The reserved REA_PROCESS_RUN_ID name also remains unavailable to scenario overrides.

Host support

Capturing a new scenario currently requires Linux or macOS and a working native PTY backend. Native Windows capture is unavailable because the PTY adapter does not yet verify descendant cleanup. The native Job Object controls used by other REA providers do not establish PTY capture support. Reinstalling the Windows PTY binary does not enable this workflow.

For Linux commands, use Linux REA inside WSL. Adapt the scenario to that hos