Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
docs: document capture v4 and native mounts
morlutoaca518bb8858
diff --git a/README.md b/README.mdindex b6f6ea563..7d93940d3 100644--- a/README.md+++ b/README.md@@ -268,12 +268,12 @@ The public interface describes what the agent is trying to learn. Providers deciREA is already useful for native application investigation on macOS:- Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.-- Traverse content-addressed artifact graphs without extraction; materialize only approved occurrences into absent output roots.+- Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.- Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.- Search and trace features across symbols, strings, metadata, references, and call paths.- Record every successful result as deterministic Evidence v2 with artifact and provider identity, confidence, authority, limitations, and locations.- Export and import evidence bundles across sessions.-- Capture approved PTY scenarios as Process Capture v3 Evidence, including raw and rendered terminal frames, scripted interactions, child-process lifecycle, named filesystem checkpoints, deterministic command shims, and loopback HTTP/WebSocket exchanges.+- Capture approved PTY scenarios as Process Capture v4 Evidence, including committed run manifests, raw and rendered terminal frames, scripted interactions, descendant settlement, named filesystem checkpoints, deterministic command shims, and loopback HTTP/WebSocket exchanges.- Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence.- Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns.- Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence.@@ -390,7 +390,7 @@ environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTYadapter uses host networking, it also requires`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.-Capture a scenario or compare two saved Process Capture v3 Evidence records:+Capture a scenario or compare two saved Process Capture v4 Evidence records:```bashrea capture-process ./scenario.json > authority.json@@ -400,7 +400,7 @@ rea compare-process-captures authority.json reconstruction.jsonThe comparison reports each observed dimension separately and identifies thefirst terminal, interaction, exit, filesystem, protocol, process, or shim-divergence. See [Process Capture v3](docs/process-capture.md) for scenario+divergence. See [Process Capture v4](docs/process-capture.md) for scenariofields, command-shim replay, checkpoint triggers, limits, and safety behavior.If the native PTY backend is unavailable, install Xcode command-line tools anddiff --git a/docs/process-capture.md b/docs/process-capture.mdindex 6bc19465f..95470a068 100644--- a/docs/process-capture.md+++ b/docs/process-capture.md@@ -1,4 +1,4 @@-# Process Capture v3+# Process Capture v4Process Capture records one approved command as deterministic Evidence. It isintended for authority-versus-reconstruction checks where terminal behavior,@@ -11,6 +11,13 @@ HTTP/WebSocket exchanges, and process exit ownership. Missing or boundedobservations remain explicit; a truncated capture is never treated asequivalent to another capture.+Every v4 capture includes a run manifest with canonical SHA-256 commitments for+the secret-safe full scenario projection, comparison contract, executable,+normalization rules, command-shim plan, and replay plan. The manifest also+records the REA/provider versions, platform, architecture, PTY backend, and UTC+start/completion timestamps. Capture creation, Evidence import, and comparison+recompute the self-contained commitments and reject invalid lifecycle data.+## Enable the capabilityProcess execution is disabled until the operator supplies policy roots and@@ -31,7 +38,7 @@ not a security sandbox: the target runs with the current user's permissions.## Capture a scenario-`rea capture-process` reads a JSON scenario and writes Process Capture v3+`rea capture-process` reads a JSON scenario and writes Process Capture v4Evidence to stdout:```bash@@ -115,6 +122,10 @@ process, and shim behavior. `first_divergence` points to the earliest observeddifference. Residual unknowns prevent a claim of complete equivalence, but theydo not hide an observed difference in another dimension.+Captures must have equal comparison-contract commitments, but may identify+different scenarios and executables. MCP callers may set `max_capture_age_ms`;+the application clock then rejects stale captures before comparison.+## Limits and lifecycle behaviorScenarios bound output bytes, frames, files, file bytes, process observations,@@ -128,3 +139,9 @@ revalidates that identifier before signaling sampled process groups, includinggroups detached from the original parent. Temporary HOME, replay, shim,terminal, checkpoint, and sampling resources are released on success, failure,timeout, and cancellation.++After root exit, REA checks token-owned process groups every 50 ms. Two+consecutive empty observations establish `quiesced`; the settlement deadline+otherwise produces `alive_at_deadline`, while inspection or identity failures+produce `unverifiable`. Sampling can still miss short-lived or early-detached+descendants, which remains a residual unknown.