rea-agents 1.0.0 → 1.2.0

package/README.md

@@ -11,14 +11,14 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![68 MCP tools](https://img.shields.io/badge/MCP_tools-68-5c4ee5?style=flat-square)](#68-tools-for-investigation)
-[![Node.js 24](https://img.shields.io/badge/Node.js-24.18.x-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
 [Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
-<code>curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash</code>
+<code>npm install --global rea-agents && rea setup</code>
 
 </div>
 
@@ -81,15 +81,24 @@ REA shows how it reached its conclusions. It does not claim to recover original
 
 ## Quick start
 
-### One-command install — recommended
+### Install the CLI — recommended
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
+npm install --global rea-agents
+rea setup
 ```
 
-The installer supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux. It installs compatible Node.js 24/npm 11 prerequisites, the exact latest `rea-agents-*` release, the official Hopper package, detected client registrations, and the bundled skill, then verifies the result. macOS uses Homebrew; Linux uses the native package manager and may show a system authorization prompt. Pin a reproducible release with `REA_VERSION=0.3.0`; `REA_VERSION` is the only supported installer environment override.
+Installing the CLI does not update Homebrew, Node.js, npm, Hopper, or coding-agent configuration. `rea setup` detects what is already present, prints every proposed change, and asks before applying it.
+
+REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. Registrations are additive, backup-first, and read back after writing. You can safely rerun setup.
+
+An optional curl wrapper installs the same CLI package and starts setup only when a terminal is available:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
+```
 
-REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. It configures detected clients with documented local MCP files; Devin is reported as skipped because its public documentation does not define a local configuration file. You can safely rerun the installer or `rea setup --yes`. If REA's local analysis engine needs one-time activation, installation remains intact and setup reports the exact remaining action rather than claiming full readiness.
+Pass installer options after `bash -s --`, for example `--dry-run`, `--no-setup`, or `--version 1.0.0`. The curl wrapper never installs prerequisites or configures integrations itself. See [Installation and setup](docs/installation.md) for its exact mutation boundary.
 
 ### With a coding agent — recommended
 
@@ -99,23 +108,23 @@ npx skills add morluto/rea
 
 Ask your agent to set up REA. It will check your Mac, explain anything it needs to install, ask for approval, and guide you through system prompts. After setup, restart the agent if it asks you to load the full REA toolset.
 
-Approve installation if needed, complete the one-time activation when prompted, then describe the app or feature you want to understand. REA handles the binary-analysis tools behind the scenes.
+Review the setup plan, approve it if appropriate, complete Hopper's one-time activation when prompted, then describe the app or feature you want to understand.
 
 ### From Terminal — no installation
 
 ```bash
-npx -y rea-agents setup --yes
+npx -y rea-agents setup
 npx -y rea-agents doctor
 npx -y rea-agents analyze /Applications/Notes.app
 ```
 
-If macOS or an installer asks for confirmation, complete the prompt and run the same command again. Restart a configured coding agent so it loads REA.
+Review the setup plan before confirming it. Restart a configured coding agent so it loads REA.
 
 ### From Terminal — install the `rea` command
 
 ```bash
 npm install --global rea-agents
-rea setup --yes
+rea setup
 rea doctor
 rea analyze /Applications/Notes.app
 ```
@@ -137,9 +146,10 @@ Choose either the no-install commands or the global installation. You do not nee
 
 - macOS 12 or newer
 - Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
-- Node.js 24.18.x with npm 11.16.x
+- Node.js 22.19+ or 24.11+ (including newer releases)
+- npm; REA does not require or install a particular npm version
 
-You do not need to choose or install binary-analysis tools yourself. REA setup handles them when needed. Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate desktop application with its own license. REA can install the official macOS or Linux package, but you must approve installation and complete its one-time activation.
+Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate desktop application with its own license. Setup reuses an existing installation. If Hopper is missing, interactive setup proposes the official package and includes it in the confirmation plan. Unattended installation requires `rea setup --yes --install-hopper`.
 
 If something is not working, run:
 
@@ -151,7 +161,9 @@ npx -y rea-agents doctor
 
 ### Linux installation and troubleshooting
 
-On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, setup downloads the matching official Hopper package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman`. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`.
+On macOS, approved setup downloads Hopper's official DMG, verifies it, and installs the app into `~/Applications` without Homebrew or administrator privileges. It opens Hopper once for activation; no manual drag-and-drop is required.
+
+On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, approved setup downloads the matching official Hopper package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman`. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`.
 
 The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
 
@@ -166,7 +178,7 @@ If doctor reports a missing analysis engine even though the file exists, inspect
 ldd /opt/hopper/bin/Hopper | grep 'not found'
 ```
 
-Install the missing distribution packages and rerun `rea setup --yes`. Hopper is a desktop application: real analysis requires an active `DISPLAY` or `WAYLAND_DISPLAY`, plus one-time license activation. The curl installer places the `rea` command in `~/.local/bin` on Linux; add that directory to future shell `PATH` values if it is not already present.
+Install the missing distribution packages and rerun `rea setup`. Hopper is a desktop application: real analysis requires an active `DISPLAY` or `WAYLAND_DISPLAY`, plus one-time license activation. The curl installer places the `rea` command in `~/.local/bin` on Linux; add that directory to future shell `PATH` values if it is not already present.
 
 REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` on macOS and `/opt/hopper/bin/Hopper` on Linux. Explicit configuration always takes precedence.
 
@@ -177,7 +189,7 @@ rea uninstall
 rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state
 ```
 
-Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
+Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
 
 ### CLI or coding agent?
 
@@ -187,6 +199,7 @@ Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evid
 | Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`                               |
 | Validate, canonicalize, or compare Evidence v2 bundles    | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
 | Import source as historical reference                     | `rea import-reference-source`                                  |
+| Capture or compare controlled process behavior            | `rea capture-process` or `rea compare-process-captures`        |
 
 Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
 
@@ -255,12 +268,12 @@ The public interface describes what the agent is trying to learn. Providers deci
 REA 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, child processes, filesystem changes, and loopback HTTP/WebSocket exchanges, then compare normalized captures.
+- 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.
@@ -286,7 +299,7 @@ REA is growing into a toolkit for understanding software across static artifacts
 7. **More targets and platforms** — Windows-native providers and ConPTY verification, Linux parity, websites and APIs, mobile artifacts, firmware, document formats, and other software-defined systems.
 8. **Differential reconstruction** — compare artifacts, functions, bundles, protocols, UIs, and process captures; track residual unknowns; verify a reconstruction against observed behavior.
 
-Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow.
+Roadmap items describe direction, not shipped support. New providers must produce the same evidence and safety metadata as existing capabilities before they become part of the public workflow. Once REA has multiple optional toolchains, setup can become capability-selective; the consent rules for that future work are recorded in the [installation roadmap](docs/roadmap.md).
 
 See the [static-analysis provider evaluation](docs/provider-evaluation.md) for the current research matrix and admission gate.
 
@@ -377,10 +390,28 @@ environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY
 adapter uses host networking, it also requires
 `REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.
 
+Capture a scenario or compare two saved Process Capture v4 Evidence records:
+
+```bash
+rea capture-process ./scenario.json > authority.json
+rea capture-process ./reconstruction.json > reconstruction.json
+rea compare-process-captures authority.json reconstruction.json
+```
+
+The comparison reports each observed dimension separately and identifies the
+first terminal, interaction, exit, filesystem, protocol, process, or shim
+divergence. See [Process Capture v4](docs/process-capture.md) for scenario
+fields, command-shim replay, checkpoint triggers, limits, and safety behavior.
+
 If the native PTY backend is unavailable, install Xcode command-line tools and
 run `npm run rebuild:native`. Linux source builds require Python, `make`, and a
 C++ toolchain. Compatible packaged binaries do not require this rebuild.
 
+ASAR inventory verifies Electron integrity metadata for both archive entries
+and `.asar.unpacked` companion files. Integrity failures identify the logical
+path, declared and calculated SHA-256 values, and whether the entry was
+unpacked; REA does not silently accept the mismatched artifact.
+
 ## Security model
 
 REA does not provide a hosted analysis service. Hopper communication uses an authenticated private local socket. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. REA is not a security sandbox: providers and launched targets run with the current user's permissions, and each capability reports its side effects and limitations. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).

package/dist/application/ArtifactInventory.js

@@ -7,16 +7,21 @@ import { ArtifactReaderFailure, } from "../artifacts/ArtifactReader.js";
 import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
 import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
 import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.js";
+import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";
 import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
 import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
 import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+const NATIVE_MOUNT_DISABLED = {
+    nativeMountApproved: false,
+    nativeMountEnabled: false,
+};
 /** Inventory one local artifact without extracting or mounting it. */
-export const inventoryArtifact = async (inputPath, limits, page, signal) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, signal);
+export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
     const metadata = await lstat(path);
@@ -24,7 +29,7 @@ export const scanArtifactInventory = async (inputPath, limits, signal) => {
     const rootDigest = metadata.isDirectory()
         ? null
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
-    const reader = await createReader(path, rootFormat);
+    const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
         const { nodes, occurrences } = await scanReader(reader, limits, signal);
         materializeDirectoryNodes(occurrences, nodes);
@@ -104,7 +109,7 @@ const inventoryLimitations = (format, reader) => {
         return ["Universal Mach-O slices require the native macOS lipo adapter."];
     return ["Artifact has no child container entries."];
 };
-const createReader = async (path, format) => {
+const createReader = async (path, format, nativeMount, signal) => {
     switch (format) {
         case "directory":
             return new DirectoryArtifactReader(path);
@@ -118,57 +123,88 @@ const createReader = async (path, format) => {
             return process.platform === "darwin"
                 ? new MachOSliceArtifactReader(path)
                 : undefined;
+        case "dmg":
+            if (!nativeMount.nativeMountApproved)
+                return undefined;
+            if (!nativeMount.nativeMountEnabled)
+                throw new ArtifactReaderFailure("unavailable", "Native DMG mounting is disabled by operator policy");
+            return NativeDmgArtifactReader.create(path, signal);
         default:
             return undefined;
     }
 };
+const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
+    const nested = new AsarArtifactReader(adapterKey);
+    try {
+        await visit(nested, logicalPath);
+    }
+    finally {
+        await nested.close();
+    }
+};
+const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
+    logicalPath.toLowerCase().endsWith(".asar") &&
+    entry.adapterKey.startsWith("/");
+const emptyScan = () => ({ nodes: new Map(), occurrences: [] });
 const scanReader = async (reader, limits, signal) => {
-    const nodes = new Map();
-    const occurrences = [];
+    const { nodes, occurrences } = emptyScan();
     if (reader === undefined)
         return { nodes, occurrences };
     const occurrenceByPath = new Map();
     const registry = new ArtifactPathRegistry();
     let totalBytes = 0;
-    for await (const entry of reader.entries(signal)) {
-        if (occurrences.length >= limits.maxEntries)
-            throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
-        const logicalPath = normalizeArtifactPath(entry.path, limits);
-        registry.add(logicalPath, entry.kind);
-        preflightEntry(entry, limits);
-        const parent = nearestParent(logicalPath, occurrenceByPath);
-        const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-        if ((entry.kind === "file" || entry.kind === "slice") && !entry.encrypted) {
-            const remainingBytes = limits.maxTotalBytes - totalBytes;
-            if (remainingBytes <= 0)
-                throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
-            if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)
-                throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
-            const digest = await hashReadable(await reader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
-            totalBytes += digest.bytes;
-            if (entry.declaredSha256 !== null &&
-                entry.declaredSha256 !== digest.sha256)
-                throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`);
-            if (totalBytes > limits.maxTotalBytes)
-                throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
-            const classified = entry.kind === "slice"
-                ? { kind: "universal-slice", format: "mach-o" }
-                : classifyArtifactContent(logicalPath, digest.prefix);
-            const node = createArtifactNode({
-                sha256: digest.sha256,
-                size: digest.bytes,
-                kind: classified.kind,
-                format: classified.format,
-                executable: entry.executable,
-                contentState: "embedded",
+    const digestEntry = async (currentReader, entry, logicalPath) => {
+        if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
+            return undefined;
+        const remainingBytes = limits.maxTotalBytes - totalBytes;
+        if (remainingBytes <= 0)
+            throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
+        if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)
+            throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
+        const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
+        totalBytes += digest.bytes;
+        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+            throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                calculatedSha256: digest.sha256,
+                unpacked: entry.unpacked,
             });
-            nodes.set(node.artifact_id, node);
-            occurrence.artifact_id = node.artifact_id;
-            occurrence.hash_status = "verified";
+        const classified = entry.kind === "slice"
+            ? { kind: "universal-slice", format: "mach-o" }
+            : classifyArtifactContent(logicalPath, digest.prefix);
+        return createArtifactNode({
+            sha256: digest.sha256,
+            size: digest.bytes,
+            kind: classified.kind,
+            format: classified.format,
+            executable: entry.executable,
+            contentState: "embedded",
+        });
+    };
+    const visit = async (currentReader, prefix) => {
+        for await (const entry of currentReader.entries(signal)) {
+            if (occurrences.length >= limits.maxEntries)
+                throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
+            const logicalPath = normalizeArtifactPath(prefix.length === 0 ? entry.path : `${prefix}/${entry.path}`, limits);
+            const expandableAsar = isExpandableAsar(entry, logicalPath);
+            registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);
+            preflightEntry(entry, limits);
+            const parent = nearestParent(logicalPath, occurrenceByPath);
+            const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
+            const node = await digestEntry(currentReader, entry, logicalPath);
+            if (node !== undefined) {
+                nodes.set(node.artifact_id, node);
+                occurrence.artifact_id = node.artifact_id;
+                occurrence.hash_status = "verified";
+            }
+            occurrences.push(occurrence);
+            occurrenceByPath.set(logicalPath, occurrence);
+            if (expandableAsar)
+                await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
-        occurrences.push(occurrence);
-        occurrenceByPath.set(logicalPath, occurrence);
-    }
+    };
+    await visit(reader, "");
     return { nodes, occurrences };
 };
 const classifyRoot = async (path, directory) => {

package/dist/application/CommandShimReplay.js

@@ -0,0 +1,136 @@
+import { createServer } from "node:http";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const RUNNER = `const command = process.argv[2];
+const response = await fetch(process.env.REA_SHIM_LEDGER_URL, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ command, arguments: process.argv.slice(3), working_directory: process.cwd() }),
+});
+if (!response.ok) process.exit(127);
+const route = await response.json();
+let elapsed = 0;
+for (const output of route.outputs) {
+  const wait = Math.max(0, output.at_ms - elapsed);
+  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  elapsed = output.at_ms;
+  (output.stream === "stdout" ? process.stdout : process.stderr).write(output.data);
+}
+if (route.termination.type === "signal") process.kill(process.pid, route.termination.signal);
+else process.exit(route.termination.code);
+`;
+const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * Start bounded executable replay wrappers and their private invocation ledger.
+ *
+ * Exact argument matching is deliberate: a fallback to the host executable
+ * would make an unmatched dependency call look authoritative. Unmatched and
+ * exhausted routes therefore fail visibly and remain part of the capture.
+ */
+export const startCommandShimReplay = async (scenario, temporaryRoot, started) => {
+    const binPath = join(temporaryRoot, "shims");
+    await mkdir(binPath);
+    const runnerPath = join(temporaryRoot, "shim-runner.mjs");
+    await writeFile(runnerPath, RUNNER, { mode: 0o600, flag: "wx" });
+    for (const shim of scenario.command_shims) {
+        const path = join(binPath, shim.name);
+        const wrapper = `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(runnerPath)} ${shellQuote(shim.name)} "$@"\n`;
+        await writeFile(path, wrapper, { mode: 0o700, flag: "wx" });
+        await chmod(path, 0o700);
+    }
+    const events = [];
+    let truncated = false;
+    const calls = new Map();
+    const server = createServer((request, response) => {
+        if (request.method !== "POST" || request.url !== "/invoke") {
+            response.writeHead(404).end();
+            return;
+        }
+        readInvocation(request)
+            .then((invocation) => {
+            const shim = scenario.command_shims.find(({ name }) => name === invocation.command);
+            const routeIndex = shim?.routes.findIndex(({ arguments: expected }) => JSON.stringify(expected) === JSON.stringify(invocation.arguments));
+            const key = `${invocation.command}:${String(routeIndex ?? -1)}`;
+            const used = calls.get(key) ?? 0;
+            const route = shim !== undefined && routeIndex !== undefined && routeIndex >= 0
+                ? shim.routes[routeIndex]
+                : undefined;
+            const outcome = route === undefined
+                ? "unmatched"
+                : used >= route.max_calls
+                    ? "exhausted"
+                    : "matched";
+            if (events.length >= scenario.limits.protocol_events)
+                truncated = true;
+            else
+                events.push({
+                    sequence: events.length,
+                    at_ms: Math.max(0, Date.now() - started),
+                    command: invocation.command,
+                    route_index: routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,
+                    arguments: invocation.arguments,
+                    working_directory: invocation.working_directory,
+                    outcome,
+                });
+            if (outcome !== "matched" || route === undefined) {
+                response.writeHead(409).end();
+                return;
+            }
+            calls.set(key, used + 1);
+            response
+                .writeHead(200, { "content-type": "application/json" })
+                .end(JSON.stringify(route));
+        })
+            .catch(() => response.writeHead(400).end());
+    });
+    await listen(server);
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server);
+        throw new Error("command shim ledger did not bind an IPv4 port");
+    }
+    return {
+        binPath,
+        url: `http://127.0.0.1:${String(address.port)}/invoke`,
+        events,
+        get truncated() {
+            return truncated;
+        },
+        close: () => closeServer(server),
+    };
+};
+const readInvocation = async (request) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 64 * 1024)
+            throw new Error("shim invocation exceeds limit");
+        chunks.push(buffer);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (typeof value !== "object" ||
+        value === null ||
+        !("command" in value) ||
+        typeof value.command !== "string" ||
+        !("arguments" in value) ||
+        !Array.isArray(value.arguments) ||
+        !value.arguments.every((item) => typeof item === "string") ||
+        !("working_directory" in value) ||
+        typeof value.working_directory !== "string")
+        throw new Error("invalid shim invocation");
+    return {
+        command: value.command,
+        arguments: value.arguments,
+        working_directory: value.working_directory,
+    };
+};
+const listen = (server) => new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(0, "127.0.0.1", () => {
+        server.off("error", rejectListen);
+        resolveListen();
+    });
+});
+const closeServer = (server) => new Promise((resolveClose, rejectClose) => server.close((cause) => cause === undefined ? resolveClose() : rejectClose(cause)));

package/dist/application/Doctor.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
+import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { probeHomebrew } from "./homebrew.js";
 import { linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
 const execFileAsync = promisify(execFile);
@@ -18,9 +19,8 @@ const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
  */
 export const runDoctor = async (target, host = systemDoctorHost()) => {
     const checks = [];
-    const nodeMajor = parseMajor(host.nodeVersion);
-    checks.push(check("node", nodeMajor >= 24, host.nodeVersion, {
-        remediation: "Install Node.js 24.18 or newer.",
+    checks.push(check("node", supportsNodeVersion(host.nodeVersion), host.nodeVersion, {
+        remediation: "Install Node.js 22.19+ or 24.11+.",
         classification: "missing_dependency",
     }));
     const macosVersion = host.platform === "darwin" ? await host.macosVersion() : undefined;
@@ -50,7 +50,7 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
             break;
         }
     checks.push(check("hopper", hopperPath !== undefined, hopperPath, {
-        remediation: "Run rea setup --yes to install Hopper, or set HOPPER_LAUNCHER_PATH.",
+        remediation: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
         classification: "missing_analysis_engine",
     }));
     if (target !== undefined)

package/dist/application/EvidenceBundleFiles.js

@@ -4,6 +4,7 @@ import writeFileAtomic from "write-file-atomic";
 import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessCapture, } from "../domain/processCapture.js";
 /** Read and validate a bounded evidence bundle inside an approved root. */
 export const readEvidenceBundle = async (path, policy) => {
     if (policy.roots.length === 0)
@@ -31,7 +32,14 @@ export const readEvidenceBundle = async (path, policy) => {
         if (!limits.ok)
             return limits;
         try {
-            return ok(parseEvidenceBundle(decoded));
+            const bundle = parseEvidenceBundle(decoded);
+            for (const record of bundle.records) {
+                if (record.predicate_type === "rea.process-capture/v3")
+                    throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
+                if (record.predicate_type === "rea.process-capture/v4")
+                    parseProcessCapture(record.normalized_result);
+            }
+            return ok(bundle);
         }
         catch (cause) {
             return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
@@ -60,8 +68,9 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
     if (bytes > policy.maxBytes)
         return err(new EvidenceFileError("write", "too-large"));
     try {
-        const canonicalParent = await realpath(dirname(resolve(path)));
-        const destination = resolve(canonicalParent, basename(resolve(path)));
+        const requestedPath = resolve(path);
+        const canonicalParent = await realpath(dirname(requestedPath));
+        const destination = resolve(canonicalParent, basename(requestedPath));
         if (!(await isApproved(destination, policy.roots)))
             return err(new EvidenceFileError("write", "outside-root"));
         const existing = await lstat(destination).catch((cause) => {
@@ -80,7 +89,7 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
             mode: 0o600,
             fsync: true,
         });
-        return ok({ path: destination, bytes });
+        return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
         return err(new EvidenceFileError("write", "io", { cause }));