rea-agents 4.1.0 → 6.0.0

package/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -1,5 +1,21 @@
 # Native, managed, and packaged artifacts
 
+## Recorded Linux crashes
+
+Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to
+inspect historical thread registers, signals, raw notes and original file
+ranges. It is independent of the active disassembler target. Source-bound
+register values and note bytes are observations; missing notes, signal-thread
+association and current executable/library identity remain unknown. PIDs are
+historical metadata and never authorize live attach or control.
+
+The optional `include_debugger_context` facet adds mapping candidates through
+caller-supplied GDB/pwndbg in an owned core-only session. Display names do not
+establish current file identity; zero reported flags leave permissions unknown.
+Requested unavailable context fails with setup guidance. See
+[recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
+for exact upstream profiles, bounds and verification coverage.
+
 ## Native targets
 
 After `open_binary`, use focused search, procedure, or function tools directly.
@@ -9,6 +25,12 @@ cross-references. Addresses and recovered pseudocode are analysis observations,
 not original source. Provider unavailability and unsupported metadata remain
 unknown rather than false.
 
+To see which functions or Objective-C methods a Mach-O actually calls in one
+run, use `observe_native_calls` with explicit breakpoints and a bounded
+`duration_ms`/`max_events`. It launches a new process under LLDB, so the target
+runs and may change files or use the network. Hardened-runtime targets need the
+`get-task-allow` entitlement.
+
 Use `binary_session` with no arguments to check the open target, selected
 provider, and alignment. Its default `result.tool_availability` includes the
 complete tool inventory with availability reasons and remediation. When choosing
@@ -37,29 +59,30 @@ assembly. Keep managed/native boundaries and unavailable reconstruction facts
 explicit. A bring-your-own reconstruction oracle is separate from the canonical
 parser and must not become an implicit setup dependency.
 
-## .NET NativeAOT
-
-A NativeAOT PE/ELF contains native code. Absence of PE/CLI metadata does not mean
-analysis must stop at assembly. Use native function analysis for recovered
-pseudocode; it is not reconstructed original C#.
-
-With an explicitly configured NativeAOT Ghidra adapter, call
-`inspect_native_load_image` after opening the target. Its optional
-`observations.metadata_recovery` returns the format, positive header evidence,
-coverage, derived-memory identity and type addresses/category paths inline.
-Then inspect a reported type with `inspect_native_data_type`, follow its
-`metadata_recovery.related_type`, interfaces and virtual slot addresses, and use
-`analyze_function` plus string/xref searches for implementation evidence. Keep
-`not_applicable`, partial recovery and unsupported layouts explicit. Generated
-`Class_address` names and inferred System.Object/String identities are not
-original names; custom field layouts remain unknown.
-
-Recovery modifies an ephemeral analysis database and may replace loaded metadata
-bytes with derived content. Original executable files remain unchanged. Distinguish
-original file offsets from derived analysis memory. Windows x64 PE **targets**
-can be analyzed on a supported Linux host; Windows **host** P0 does not admit
-this database recovery. See the [NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/ghidra-nativeaot.md)
-for the tested layout and optional bring-your-own adapter build.
+### .NET NativeAOT
+
+NativeAOT binaries contain native machine code, so ordinary CIL decompilers
+cannot recover the original method bodies. When managed metadata/CIL is absent,
+classify that as a native-analysis route rather than claiming source recovery.
+Open the native image with the selected deep provider and inspect functions,
+strings, calls, and references; describe decompiler output as pseudocode and
+inference.
+
+NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared
+libraries. Use file bytes and loader metadata rather than suffixes to identify
+them. For packaged apps, inventory/extract with REA's artifact tools and retain
+the exact contained image identity. PDB, ELF debug, or dSYM sidecars are
+additional evidence only when the provider accepts and matches them.
+
+For deeper type recovery, the optional third-party
+[Ghidra NativeAOT analyzer](https://github.com/Washi1337/ghidra-nativeaot)
+rehydrates ReadyToRun metadata and can recover method tables, type relationships,
+frozen objects, and strings. This is a Ghidra extension with its own install and
+interactive workflow; it is not currently part of REA's managed parser or
+headless Ghidra bridge. Treat its annotations as analysis evidence, retain the
+binary identity, and do not present recovered types as original source. Header
+discovery may require a symbol or analyst identification of the ReadyToRun
+header, depending on the binary and analyzer version.
 
 ## Packages and extraction
 
@@ -68,6 +91,21 @@ ASAR, or DMG inputs when the artifact graph and findings help answer the
 question. It returns the complete artifact graph inline. Cite graph manifest
 IDs when using them.
 
+For an IPA or a macOS `.app`, ZIP, or DMG, pass the inventory Evidence to
+`project_apple_application_graph`. It reports application roots and nested
+bundles by path convention: app extensions, XPC services, frameworks, login
+items, system and driver extensions, and plug-ins. It also lists privileged
+helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and
+executable candidates. Roles are path conventions, not parsed plists; read the
+listed plists with `inspect_plist`.
+
+After `open_binary` on a `.app` or Mach-O, use `trace_dylib_resolution` to see
+which file each `@rpath`, `@loader_path` and `@executable_path` load reaches for
+every executable in the bundle. It also lists missing or weak loads and earlier
+`@rpath` candidates that are absent. Narrow large bundles with `roots` or
+`architecture`. System paths stay undetermined because the dyld shared cache
+provides them.
+
 Use `extract_artifact` when materialized files are needed. It takes no arguments
 and materializes all regular files into a fresh temporary directory chosen by
 REA. Symlinks and encrypted entries are inventory facts, not extractable files.

package/third_party/README.md

@@ -0,0 +1,60 @@
+# Upstream analysis engines
+
+REA integrates existing tools through provider adapters. Upstream source remains
+unmodified and retains its own license; it is not copied into REA's domain or
+application code.
+
+## jadx-headless-mcp
+
+- Source: <https://github.com/1013503897/jadx-headless-mcp>
+- Submodule: `third_party/jadx-headless-mcp`
+- Release: `v0.7.1`
+- Commit: `5844800a486d2248fa949b74c9896285f5b54de2`
+- License: Apache-2.0; see the submodule's `LICENSE`.
+- Release identity: `src/android/JadxRelease.ts`.
+- REA integration: `src/android/`; no upstream patches in this version.
+
+Fetch source for inspection with:
+
+```sh
+git submodule update --init third_party/jadx-headless-mcp
+```
+
+Normal REA builds and installed npm packages do not require this submodule or a
+Gradle build. Supply a separately obtained JAR with `REA_JADX_MCP_JAR`; REA never
+downloads engines during an analysis operation. The audited release JAR is
+identified by SHA-256. A caller-supplied build reporting the supported protocol
+version retains its actual digest and an unknown source revision unless its
+bytes match the audited release.
+
+When updating: review upstream protocol and license changes, update the gitlink
+and release identity together, exercise the adapter's producer regressions, and
+run the real APK CLI/MCP lane. Never attribute modified engine bytes to the
+audited source revision.
+
+## Public APK fixture
+
+`scripts/fetch-android-fixtures.mjs` explicitly downloads the audited engine and
+Appium ApiDemos v6.0.18 into ignored `_reference/apk-integration/`. Both downloads
+are checked against fixed SHA-256 values. Fixture provenance is recorded in
+`scripts/fixtures/android-apidemos.json`; the source uses Apache-2.0. This is a
+static analysis fixture: no emulator, device, SDK installation or app execution
+is needed. APKs and JARs are neither tracked nor included in npm packages.
+
+## Firmware engines
+
+| Engine | Source | Release | Pinned commit | License |
+| --- | --- | --- | --- | --- |
+| Binwalk | <https://github.com/ReFirmLabs/binwalk> | v3.1.0 | `4fdab3d464d97b68e0af9088df3f9e2e1545b21c` | MIT, upstream `LICENSE` |
+| Unblob | <https://github.com/onekey-sec/unblob> | 26.6.4 | `1fcc7a0a584a70a96c31f5a276c20944d199a089` | MIT, upstream `LICENSE` |
+
+Source remains unmodified in `third_party/binwalk` and `third_party/unblob`.
+Release records live in `src/firmware/FirmwareRelease.ts`; REA adapters own the
+CLI/report interpretation and lifecycle in `src/firmware/`. Caller-supplied
+executables retain their actual launcher digest and unknown source revision;
+version output alone does not establish source identity. REA does not bundle
+extractors or download/install firmware engines during analysis.
+
+On updates: inspect actual pinned CLI and report producers, preserve licenses,
+update gitlinks/release records, run report regressions and the real firmware
+lane. See [firmware setup and coverage](../docs/firmware-analysis.md).

package/third_party/evmole/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Maxim Andreev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/third_party/evmole/README.md

@@ -0,0 +1,22 @@
+# EVM interface upstream profile
+
+REA integrates unchanged [EVMole](https://github.com/cdump/evmole) as the exact
+npm dependency `evmole@0.9.3`, with lockfile integrity verification. Tag `0.9.3`
+resolves to commit `0409707c2efef11a9043f9b4505cad5719054a7e`.
+
+The JavaScript binding and WASM engine remain in the original upstream package;
+REA contains only carrier validation, a worker adapter and portable contracts.
+No submodule or vendored engine fork is required. No signature database,
+LLM decompiler, blockchain node or RPC dependency is acquired.
+
+Upstream is MIT, copyright (c) 2023 Maxim Andreev. Its npm tarball omits the
+license file, so REA packages the unchanged tag's [LICENSE](LICENSE) here.
+The engine is initialized through the upstream `no_tla`/`initSync` interface
+only inside an owned worker; importing REA services performs no WASM/file I/O.
+
+Initial interface analysis uses `contractInfo` with selectors, arguments and
+stateMutability enabled. Selector recovery also extracts/reports terminal metadata;
+its reported representation is retained with explicit unknown precision/coverage.
+Other upstream outputs are separate future contracts;
+in particular, CFG destination IDs are not byte addresses and terminal CBOR
+metadata cannot establish a lossless integer claim through the current binding.

package/third_party/pwndbg/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dominik 'Disconnect3d' Czarnota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/third_party/pwndbg/README.md

@@ -0,0 +1,23 @@
+# pwndbg core context adapter
+
+REA uses caller-supplied unchanged [pwndbg](https://github.com/pwndbg/pwndbg)
+2026.09.15, commit `55596aa676a2756efb8d67034f31675170eabe48`, and GDB.
+The original MIT license is retained in `LICENSE.md`. Engine source and its
+dependencies are not vendored or acquired by REA.
+
+The adapter executes the selected upstream `gdbinit.py` with its original
+`__file__`, an explicitly selected existing virtual environment, and
+`PWNDBG_NO_AUTOUPDATE=1`. The upstream entrypoint and dependencies are trusted
+caller-supplied executable code. Reported versions establish observed behavior,
+not source authenticity. The real verification lane checks out the exact commit
+and uses its frozen `uv.lock` in isolated runner storage.
+
+Only `pwndbg.aglib.vmmap.get()` is queried, after establishing a core-only GDB
+connection without an executable. All original core notes and recorded register
+values come from the independent pwntools/pyelftools decoder. Mapping candidates
+are derived; original pathnames do not identify current host files, and reported
+flags zero leave permissions unknown. REA does not expose upstream command
+execution, live attach, target launch, implicit executable pairing or updates.
+
+Local actual verification uses Linux x64, GDB 13.1 and the exact upstream tag/build.
+Other GDB versions require their corresponding real workflow before being claimed.

package/third_party/pwntools/README.md

@@ -0,0 +1,40 @@
+# Offline ELF upstream profile
+
+REA uses caller-supplied, unchanged Python packages. It vendors no pwntools,
+pyelftools or Unicorn implementation and never installs these dependencies.
+
+| Upstream | Exact verified profile | License | Role |
+| --- | --- | --- | --- |
+| [pwntools](https://github.com/Gallopsled/pwntools) | 4.15.0; tag commit `3ad86ec5adab1abf9781ca7552a6f5d7cff7a33c` | MIT | ELF analysis and static mitigation/GOT/PLT heuristics |
+| [pyelftools](https://github.com/eliben/pyelftools) | 0.33 | Public domain | Original ELF sections, segments, symbols and relocations |
+| [Unicorn](https://github.com/unicorn-engine/unicorn) | 2.1.2 | GPL-2.0 | Upstream PLT emulation; distinct from executing the target as a host process |
+
+The adapter checks all three runtime versions before importing the ELF engine.
+Original upstream code/licenses remain in the caller-selected environment.
+No target or core binaries are committed. Fixtures are compiled in owned
+temporary storage from repository source and are never executed.
+
+`bridge/pwntools/layout.py` is an owned allocation-failure bootstrap;
+`layout_impl.py` is the adapter. It reads original tables through
+unchanged upstream APIs, preserves raw name bytes/ranges, and serializes uint64
+values as strings. It never accesses `ELF.libs`, `ELF.maps`, `ELF.libc` or
+`process.corefile`, which have materially different execution authority.
+
+The real verification lane traces host exec syscalls, checks original artifact
+hashes and observes released owned processes. No negative claim relies only on
+an unmodified target's sentinel: upstream can execute a patched copy when its
+runtime-library accessors are used.
+
+The instance-local adapter subclass forwards the documented pyelftools 0.33
+`iter_segments(type=...)` / `iter_sections(type=...)` filters missing from
+pwntools 4.15.0 cached overrides. No upstream file or global method is changed.
+Sectionless dynamic string tables use unique DT_STRTAB/DT_STRSZ mappings to
+file-backed PT_LOAD bytes; ambiguous or non-file-backed mappings are explicitly
+unsupported. Section-name table escapes follow the [ELF ABI](https://gabi.xinuos.com/elf/02-eheader.html):
+SHN_XINDEX represents actual indices at least 0xff00; ordinary absence uses index
+zero. Raw name offsets remain reported when the name table is absent.
+
+PLT convenience inference uses the unchanged upstream Unicorn instruction
+emulator. REA labels those maps as derived static evidence. The no-execution
+verification claim concerns launching the selected object as a host process,
+not the absence of static instruction emulation inside an analysis engine.

package/dist/application/AuthorizedArtifactInventory.js

@@ -1,7 +0,0 @@
-import { realpath } from "node:fs/promises";
-import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
-/** Resolve, authorize, and scan one artifact without a second path resolution. */
-export const scanAuthorizedArtifactInventory = async (inputPath, options = {}) => {
-    const path = await realpath(inputPath);
-    return scanCanonicalArtifactInventory(path, options);
-};

package/dist/application/JavaScriptSemanticGraphProjection.js

@@ -1,38 +0,0 @@
-import { compareCodePoints } from "../domain/canonicalOrdering.js";
-import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../domain/javascriptSemanticGraphSchemas.js";
-/** Find the innermost callable that contains one exact source range. */
-export const owningSemanticCallableNode = (location, ir, nodes) => {
-    if (location === null)
-        return undefined;
-    return ir.callables
-        .filter((callable) => contains(callable.location, location))
-        .sort((left, right) => compareCodePoints(positionKey(right.location), positionKey(left.location)))
-        .map(({ callableId }) => nodes.get(callableId))
-        .find((node) => node !== undefined);
-};
-/** Find retained semantic nodes whose exact ranges are within one expression. */
-export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) => node.identity.source_range !== null &&
-    contains(range, node.identity.source_range));
-/** Report extractor support without treating missing families as absence. */
-export const semanticFamilyStatus = (family, analysis) => {
-    if (![
-        "call-flow",
-        "boundary",
-        "child-process",
-        "closure",
-        "configuration",
-        "data-flow",
-        "event",
-        "object-flow",
-        "promise-ownership",
-        "request",
-        "resource-lifecycle",
-        "timer",
-    ].includes(family))
-        return "unsupported";
-    return analysis.truncated_scopes === 0 ? "partial" : "unknown";
-};
-const contains = (outer, inner) => pointCompare(outer.start, inner.start) <= 0 &&
-    pointCompare(outer.end, inner.end) >= 0;
-const pointCompare = (left, right) => left.line - right.line || left.column - right.column;
-const positionKey = (range) => `${String(range.start.line).padStart(12, "0")}:${String(range.start.column).padStart(12, "0")}`;

package/dist/application/ProcessCaptureLifecycle.js

@@ -1,299 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { digestProcessCommitment, processComparisonContract, processScenarioCommitment, } from "../domain/processCapture.js";
-import { PRODUCT_IDENTITY } from "../identity.js";
-import { snapshotRoots } from "./FilesystemSnapshot.js";
-import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
-import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
-import { observeOwnedProcessGroup } from "../process/ProcessOwnershipObservation.js";
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
-import { assertNotCancelled } from "./ProcessScenarioRuntimeValidation.js";
-import { normalizeProcessElapsedTime, normalizeProcessSamples, normalizeProcessText, } from "./ProcessNormalization.js";
-import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
-import { TerminalRenderer } from "./TerminalRenderer.js";
-import { scheduleProcessInterval } from "./ProcessTimer.js";
-/** Wait for trailing PTY callbacks before the capture becomes immutable. */
-export const settleProcessCaptureJournal = async (journal, quietMs = 25, maxWaitMs = 500) => {
-    const deadline = Date.now() + maxWaitMs;
-    let observed = journal.length;
-    let lastChangeAt = Date.now();
-    while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, 4));
-        if (journal.length !== observed) {
-            observed = journal.length;
-            lastChangeAt = Date.now();
-        }
-        else if (Date.now() - lastChangeAt >= quietMs)
-            return;
-    }
-};
-export const buildCaptureResult = (options) => {
-    const hasSensitiveScriptedInput = options.scenario.events.some((event) => event.type === "input" && event.sensitive);
-    const sensitiveInputUnknown = "Sensitive scripted input values are redacted from process capture Evidence.";
-    const filesystemObservationUnknown = "No filesystem observation paths were selected; filesystem effects remain unknown.";
-    const hasFilesystemObservations = options.scenario.filesystem_observation_paths.length > 0;
-    return {
-        manifest: options.manifest,
-        normalization: options.scenario.normalization,
-        frames: options.frames,
-        rendered_frames: options.renderedFrames,
-        interaction_events: options.interactions,
-        exit: {
-            code: options.exit.reason === "exited" && options.exit.exitCode >= 0
-                ? options.exit.exitCode
-                : null,
-            signal: options.exit.signal ?? null,
-            reason: options.exit.reason,
-        },
-        settlement: options.settlement,
-        process_samples: normalizeProcessSamples(options.samples, options.scenario, options.rootPid),
-        filesystem_checkpoints: options.checkpoints,
-        event_journal: options.eventJournal,
-        files_before: options.before.files,
-        files_after: options.after.files,
-        filesystem_effects: classifyFilesystemEffects(options.before.files, options.after.files),
-        truncated: options.truncated,
-        limitations: [
-            "Process trees are sampled and may omit short-lived descendants.",
-            ...(options.samplingPartial
-                ? ["Process-tree sampling ended with an incomplete observation."]
-                : []),
-            "Filesystem observations are before/after snapshots, not syscall traces.",
-            "Inherited host environment variables are not recorded and may affect results.",
-            ...(!hasFilesystemObservations ? [filesystemObservationUnknown] : []),
-            ...(hasSensitiveScriptedInput ? [sensitiveInputUnknown] : []),
-        ],
-        residual_unknowns: [
-            {
-                scope: "process",
-                reason: "Process trees are sampled and may omit short-lived descendants.",
-            },
-            {
-                scope: "environment",
-                reason: "Inherited host environment variables are not recorded.",
-            },
-            {
-                scope: "network",
-                reason: "Network activity is not observed by this capture.",
-            },
-            ...(!hasFilesystemObservations
-                ? [
-                    {
-                        scope: "filesystem",
-                        reason: filesystemObservationUnknown,
-                    },
-                ]
-                : []),
-            ...(hasSensitiveScriptedInput
-                ? [{ scope: "interaction", reason: sensitiveInputUnknown }]
-                : []),
-        ],
-    };
-};
-const hashFile = async (path) => {
-    const hash = createHash("sha256");
-    for await (const chunk of createReadStream(path))
-        hash.update(chunk);
-    return hash.digest("hex");
-};
-export const createRunManifest = async (scenario, startedAt, completedAt, host = {
-    platform: process.platform,
-    architecture: process.arch,
-}) => {
-    const executableSha256 = await hashFile(scenario.executable);
-    const scenarioCommitment = processScenarioCommitment(scenario, executableSha256);
-    const comparisonContract = processComparisonContract(scenario);
-    return {
-        rea_version: PRODUCT_IDENTITY.packageVersion,
-        provider_version: PROCESS_PROVIDER.version,
-        platform: host.platform,
-        architecture: host.architecture,
-        pty_backend: "node-pty",
-        started_at: startedAt.toISOString(),
-        completed_at: completedAt.toISOString(),
-        scenario: scenarioCommitment,
-        comparison_contract: comparisonContract,
-        full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
-        comparison_contract_sha256: digestProcessCommitment(comparisonContract),
-        executable_sha256: executableSha256,
-        normalization_sha256: digestProcessCommitment(scenario.normalization),
-    };
-};
-export const observeSettlement = async (runId, processGroupIds, settleMs, recordEvent = () => undefined, platform = process.platform) => {
-    if (platform === "win32") {
-        recordEvent("lifecycle", 1);
-        return { state: "unverifiable", elapsed_ms: 0 };
-    }
-    const started = Date.now();
-    let consecutiveEmpty = 0;
-    let deadlineReached = false;
-    while (!deadlineReached) {
-        const observations = await Promise.all([...new Set(processGroupIds)].map((processGroupId) => observeOwnedProcessGroup({
-            runId,
-            leaderPid: processGroupId,
-            processGroupId,
-        })));
-        if (observations.some(({ state }) => state === "unverifiable")) {
-            recordEvent("lifecycle", 1);
-            return { state: "unverifiable", elapsed_ms: Date.now() - started };
-        }
-        if (observations.every(({ state }) => state === "empty")) {
-            consecutiveEmpty += 1;
-            if (consecutiveEmpty >= 2) {
-                recordEvent("lifecycle", 1);
-                return { state: "quiesced", elapsed_ms: Date.now() - started };
-            }
-        }
-        else
-            consecutiveEmpty = 0;
-        deadlineReached = Date.now() - started >= settleMs;
-        if (deadlineReached)
-            break;
-        await new Promise((resolve) => setTimeout(resolve, 50));
-    }
-    recordEvent("lifecycle", 1);
-    return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
-};
-export const awaitTerminalExit = async ({ terminal, scenario, started, lastOutput, signal, timers, interactions, dispatchedEventIndexes, recordEvent, }) => new Promise((resolveExit) => {
-    // The kill caused by a deadline is observed later as an ordinary PTY exit.
-    // Keep the initiating lifecycle reason so comparisons distinguish a target
-    // exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
-    let reason = "exited";
-    terminal.onExit((exit) => {
-        recordEvent("lifecycle", 0);
-        for (const [eventIndex, event] of scenario.events.entries()) {
-            if (dispatchedEventIndexes.has(eventIndex))
-                continue;
-            const sequence = interactions.length;
-            interactions.push({
-                sequence,
-                scheduled_at_ms: event.at_ms,
-                dispatched_at_ms: Math.max(0, Date.now() - started),
-                type: event.type,
-                data: event.type === "input"
-                    ? "<not-dispatched>"
-                    : event.type === "resize"
-                        ? `${String(event.columns)}x${String(event.rows)}`
-                        : event.signal,
-                outcome: "target_exited",
-            });
-            recordEvent("interaction_events", sequence);
-        }
-        for (const timer of timers) {
-            timer.cancel();
-        }
-        timers.clear();
-        resolveExit({ ...exit, reason });
-    });
-    const timeout = scheduleProcessInterval(() => {
-        if (signal?.aborted === true) {
-            reason = "cancelled";
-            terminal.kill("SIGKILL");
-        }
-        else if (Date.now() - started >= scenario.timeout_ms) {
-            reason = "timeout";
-            terminal.kill("SIGKILL");
-        }
-        else if (Date.now() - lastOutput() >= scenario.idle_timeout_ms) {
-            reason = "idle_timeout";
-            terminal.kill("SIGKILL");
-        }
-    }, 20);
-    timers.add(timeout);
-});
-const processCaptureCleanupHost = {
-    platform: process.platform,
-    cleanupProcessGroup: cleanupOwnedProcessGroup,
-    removeTemporaryRoot: (path) => rm(path, { recursive: true, force: true }),
-};
-export const releaseProcessResources = async (options) => {
-    const host = options.host ?? processCaptureCleanupHost;
-    for (const timer of options.timers)
-        timer.cancel();
-    let failure;
-    try {
-        await options.renderer?.dispose();
-    }
-    catch (cause) {
-        void cause;
-        failure ??= "terminal renderer cleanup failed";
-    }
-    if (options.terminal !== undefined && host.platform !== "win32") {
-        for (const processGroupId of new Set(options.capturedProcessGroupIds)) {
-            const cleaned = await host.cleanupProcessGroup({
-                runId: options.runId,
-                leaderPid: processGroupId,
-                processGroupId,
-            });
-            if (!cleaned.cleaned)
-                failure ??= cleaned.reason;
-        }
-    }
-    try {
-        await host.removeTemporaryRoot(options.temporaryRoot);
-    }
-    catch (cause) {
-        void cause;
-        failure ??= "temporary process root cleanup failed";
-    }
-    return failure;
-};
-export const captureTerminalFrames = (options) => {
-    let outputBytes = 0;
-    let truncated = false;
-    options.terminal.onData((data) => {
-        options.onOutput();
-        const bytes = Buffer.byteLength(data);
-        if (outputBytes + bytes > options.scenario.limits.output_bytes) {
-            truncated = true;
-            return;
-        }
-        outputBytes += bytes;
-        const atMs = normalizeProcessElapsedTime(Date.now() - options.started, options.scenario.normalization.time_bucket_ms);
-        const normalized = normalizeProcessText(data, options.scenario, options.temporaryRoot, options.terminal.pid);
-        const sequence = options.frames.length;
-        options.frames.push({
-            sequence,
-            at_ms: atMs,
-            data: normalized,
-        });
-        options.renderer.write(data, atMs);
-        options.recordEvent("frames", sequence);
-    });
-    return () => truncated;
-};
-export const resolveProcessResult = (capture, executionFailure, cleanupFailure) => {
-    if (executionFailure instanceof ProcessCaptureError)
-        throw executionFailure;
-    if (executionFailure !== undefined)
-        throw new ProcessCaptureError("process capture failed", {
-            cause: executionFailure,
-        });
-    if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure, {
-            reason: "cleanup_incomplete",
-        });
-    if (capture === undefined)
-        throw new ProcessCaptureError("process capture produced no result");
-    return capture;
-};
-export const prepareProcessCapture = async (scenario, signal, host = systemProcessPreparationHost) => {
-    assertNotCancelled(signal);
-    const before = await snapshotRoots(scenario, signal);
-    const temporaryRoot = await host.createTemporaryRoot();
-    try {
-        const runId = randomUUID();
-        return { temporaryRoot, runId, before };
-    }
-    catch (cause) {
-        await host.cleanup(temporaryRoot);
-        throw cause;
-    }
-};
-const systemProcessPreparationHost = {
-    createTemporaryRoot: () => mkdtemp(join(tmpdir(), "rea-process-")),
-    cleanup: (path) => rm(path, { recursive: true, force: true }),
-};