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 host; this does not establish capture of a native Windows process tree. Comparing existing capture Evidence through the CLI or MCP remains available on Windows and does not launch a PTY or the captured target.

On supported capture hosts, a missing or incompatible native PTY binary has a different recovery: reinstall REA for the active platform, architecture, and Node.js version with optional dependencies enabled. Capability diagnostics distinguish this from the Windows capture-adapter limitation.

macOS also requires Apple's Swift compiler through xcrun for process ownership inspection. REA compiles its packaged, narrow process-inspection helper into a private temporary directory before a capture or owned provider process starts; the same prerequisite applies to owned provider-process supervision on macOS. REA removes that directory when it exits. REA does not install Xcode, Command Line Tools, or other software. Capability checks prepare this helper before reporting macOS capture as available.

Stopping process sampling or cancelling an ownership query waits for its issued inspection command to exit. Closing a macOS ownership reader rejects new queries and waits for admitted helper commands before removing their executable directory.

Capture a command

For a small first capture, save this as scenario.json:

{
  "executable": "node",
  "arguments": ["-e", "console.log('ready')"],
  "timeout_ms": 5000
}

Run the scenario through the CLI:

rea capture-process ./scenario.json --json > capture.json

--json is required when saving input for JSON consumers; the default terminal format is TOON. The file contains the complete capture Evidence re