@pentoshi/clai 4.18.0 → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## v5.0.0 — 2026-10-22
+
+This release covers all changes since **v4.19.0**, including the REA integration, session and interface improvements, provider fixes, and the reliability work below.
+
+### Accurate completion statistics
+
+- Show output tokens per second alongside elapsed time, file changes, and `/changes` in Classic and OpenTUI, including narrow layouts and restored transcripts.
+- Calculate TPS from reported output tokens and model-active generation time across foreground calls. Tool execution, user waits, auxiliary calls, and compaction do not inflate the rate; reasoning tokens are not counted twice.
+- Preserve earlier valid measurements when a later generation is interrupted. Aborted turns retain measured TPS, and exact partial usage is included when the provider reports it. Missing usage is never replaced with guessed token counts.
+
+### Live output and durable queued prompts
+
+- Keep tool-output and job pagers live in both interfaces, following streamed output, spool replacement, final artifacts, externally appended job logs, and log rotation.
+- Preserve paused scrolling when output completes, with explicit follow controls, bounded reads, redacted output, and cleanup of subscriptions and file watchers.
+- Stream the OpenTUI compaction pager through progress, replacement, final summaries, and failures instead of opening a frozen snapshot.
+- Persist unsent queued prompts per session with validated, redacted, atomic storage. Recover them after crashes, normal shutdown, session switches, and composer editing.
+- Remove a queued prompt only after foreground model submission is acknowledged. Pre-submission failures retain and pause the prompt rather than silently losing it or retrying indefinitely. Private/no-history sessions do not persist the queue.
+
+### On-demand reverse engineering with REA
+
+- Add managed REA installation, updates, connection controls, and status, with `@rea`, `/rea <task>`, and an in-app `/rea guide` in both interfaces.
+- Attach a version-matched, grouped tool index and workflow only when needed, preserving the stable system prompt and native tool catalog. Indicate tools that need an open target, an analysis engine, or unavailable prerequisites.
+- Add explicit user-run `/rea engines` status, install, use, and remove workflows for Ghidra, Java, and configured external engines. The agent cannot install analysis engines on its own.
+- Harden downloads with trusted HTTPS hosts, redirect validation, published SHA-256 checks, streamed size limits, stall detection, and disk-space checks. Reject unsafe archive entries and corrupted extraction.
+- Improve macOS, Linux x64/ARM64, and Windows installation behavior, including native decompiler builds where required, Windows path and rename handling, stale staging cleanup, selected-engine environment precedence, and clear unsupported-platform guidance.
+- Improve cancellation, reconnect sequencing, staged-update version reporting, installation contention messages, strict argument hints, exact tool lookup, and lazy archive loading.
+
+### Sessions, compaction, and terminal interfaces
+
+- Store sessions in individual append-only delta logs, automatically importing legacy `history.jsonl` while preserving the original file. Keep rejected frames separately and avoid unnecessary history reloads.
+- Rebuild compaction memory around the active goal, scoped instructions, gathered context, completed work, next steps, relevant files, genuine issues, and the latest user prompts. Preserve inherited instruction scope and stable replay prefixes.
+- Reduce per-frame transcript work and smooth wheel scrolling in both interfaces. Fix OpenTUI wheel stalls, duplicate acceleration, window-update races, and final-tool-card reachability without discarding saved history.
+- Refresh startup cards with clearer mode and permission badges, responsive labels, a consolidated version/welcome row, and correct provider/model pairing in Classic.
+- Improve whole-cell mouse selection, padding-origin drags, selectable startup and plan content, and plain-click behavior. Remove the transcript scrollbar.
+- Render markdown in completed and streaming reasoning, including emphasis and fenced code, with incremental caches. Improve status spacing, context chips, and tool durations.
+- Print large piped `history --show` output completely under Bun and regenerate the README preview from the real OpenTUI renderer.
+
+### Providers and agent reliability
+
+- Cache model lists for two minutes instead of up to thirty; never cache empty or fallback lists. Add `/model refresh` and `/models refresh [filter]`, bypass stale/in-flight results, and identify unavailable live catalogs accurately.
+- Size reasoning output budgets from learned, live, remembered, or documented model limits, up to 131,072 tokens where supported. Preserve context fit and learn actual output caps from provider rejections with a bounded retry.
+- Send a stable per-session River `prompt_cache_key`, preserve DeepSeek reasoning on tool-bearing requests, and derive Free/Zen context limits from the live catalog.
+- Recover from malformed DSML tool calls rather than terminating the turn.
+- Allow `http.fetch` to reach private, loopback, CGNAT, and metadata addresses while retaining engagement-scope enforcement.
+- Recover from asynchronous shell artifact open, write, and flush failures without crashing Bun or discarding bounded output. Surface actionable storage warnings and fatal-shutdown diagnostics.
+- Clean recognized session scratch folders after ten days of inactivity, checking at most daily across processes. Protect active sessions, recently modified files, and symlink targets; leave saved conversations and global/custom artifact retention unchanged. Compare expiry conservatively at millisecond precision so filesystem timestamp rounding cannot delete a folder at the exact ten-day boundary.
+
+### Safer tools and agent guidance
+
+- Allow `fs.edit` replacements of `""` to delete exact matching text. Keep empty search text invalid with actionable guidance rather than a generic argument error.
+- Clarify exact current `oldText`, whitespace and line endings, safe creation/insertion alternatives, stale-preview risks, and the requirement to re-read after a no-match result.
+- Require Responder delegation for finite work expected to exceed four to five minutes, including long suites, builds, scans, and CI watches. Keep interactive sessions in terminal tools and persistent servers/watchers in named normal background jobs.
+- Preserve useful prompt safeguards and raise the native prompt-overhead guard to 23,000 estimated tokens.
+- Keep deliverables out of scratch directories and avoid adopting unrelated same-named projects. Scope persistent instructions to the actual project while preserving cross-turn prompt-cache prefixes.
+- Prevent MCP fuzzy matching from overriding built-in tool names or wire spellings, preserving built-in confirmation and parallel-safety rules.
+
+### Validation and distribution
+
+- Expand regressions for provider cancellation and exact TPS, both terminal interfaces, live pagers, queue submission/restart/shutdown behavior, atomic storage, tool edits, prompt variants, cache stability, and platform-specific REA behavior.
+- Isolate test home directories and disable the real keychain during tests so placeholder provider keys cannot overwrite developer credentials.
+- Harden CI checkout credentials and require SHA-256 evidence in the REA smoke test.
+- Synchronize the v5 version across runtime metadata, npm lockfile, Homebrew and Scoop templates, and include this changelog in the npm package.
+
+### Upgrade notes
+
+- Existing configuration remains supported; legacy session history is imported automatically and retained.
+- Queued-prompt persistence does not promise distributed exactly-once delivery across a crash between remote acceptance and local acknowledgement.
+- TPS is omitted when exact provider usage is unavailable rather than displaying a fabricated rate.
+- REA engine setup remains an explicit user action; platform prerequisites and limitations are documented in [REA.md](REA.md).
+
+[Full comparison since v4.19.0](https://github.com/pentoshi007/clai/compare/v4.19.0...v5.0.0)

package/CONTRIBUTING.md

@@ -41,7 +41,8 @@ The tests use fixtures, isolated storage, and a mocked browser launcher; provide
 | `npm run test:deterministic -- test/mcp` | Check MCP transports, tool catalogs, authentication, and concurrent credential/config storage with local fixtures. |
 | `npm run embed-prompts:check` | Check that embedded prompts match their source Markdown. |
 | `npm run release:verify` | Validate dependency pins, lockfile, and release metadata. |
-| `npm run compile` | Build native release binaries through Bun. |
+| `npm run compile` | Build all six minified native release targets through Bun. |
+| `npm run compile -- --target bun-linux-arm64` | Build one target; `--target` is repeatable and `--outdir` selects the output directory. |
 | `npm run doctor` | Inspect available tools and provider configuration. |
 
 To run a focused test:
@@ -90,7 +91,7 @@ Distribution manifests under `manifests/` are templates. The release workflow ge
 
 For behavior changes, add or update meaningful regression coverage and run the focused tests first. Run the relevant typecheck, build, deterministic suite, terminal checks, and release validation before submitting. UI changes should cover both renderers; process and privilege changes need the platform coverage defined in CI. Run native performance checks without competing build or full-suite workloads.
 
-For documentation-only changes, check examples against current CLI help, validate links and formatting, and check any issue-template YAML. A full local application suite is unnecessary unless the change affects code, runtime prompts, or generated artifacts.
+For documentation-only changes, check examples against current CLI help, validate links and formatting, and check any issue-template YAML. The README preview `.github/assets/clai-opentui.svg` is rendered from the real OpenTUI interface; regenerate it with `bun run scripts/render-readme-preview.ts` after visible UI changes. A full local application suite is unnecessary unless the change affects code, runtime prompts, or generated artifacts.
 
 CI currently covers Node 22 and 24 on Linux, Bun OpenTUI conformance, Classic on macOS, and process/privilege and MCP behavior on macOS and Windows. The [workflow](.github/workflows/ci.yml) is the source of truth for required checks. All relevant remote checks must pass.
 

package/PROVIDERS.md

@@ -125,9 +125,9 @@ For model choice, use `/model` or `clai model <name>`. Use the `/provider` picke
 
 The `free` integration discovers free models from two gateways: `free-1/<model>` uses [OpenCode Zen](https://opencode.ai/docs/zen/), and `free-2/<model>` uses [Kilo](https://kilo.ai/docs/gateway/api-reference). Model availability can change independently at each gateway. Zen's Jev decision models use the separate System One API and are omitted from the chat model picker.
 
-Kilo's model catalog supplies context and output limits directly. Zen's model list currently omits those limits, so clai fills missing values from the exact model entry in the OpenCode provider catalog on [Models.dev](https://github.com/anomalyco/models.dev#api). Discovery follows live model IDs, including newly added models, without a clai update or a hardcoded limit entry. Values reported by the gateway take precedence. The two sources keep separate limits even when model names match; older unprefixed Zen model selections also use the discovered limits.
+Kilo's model catalog supplies context and output limits directly. Zen models are discovered from the live [OpenCode provider catalog](https://models.opencode.ai/api.json): non-deprecated, zero-cost entries determine the list, including models omitted from Zen's `/models` response. Missing gateway limits come from each exact catalog entry, without per-model allowlists, context pins, or upstream model-name guesses. Values reported by the gateway take precedence. The two sources keep separate limits even when model names match; older unprefixed Zen model selections also use the discovered limits.
 
-Discovered limits are cached for 30 minutes and retained locally for later sessions. A newly discovered Zen model ID can trigger an earlier metadata refresh; retries for unpublished limits or failed lookups have a one-minute cooldown. When discovery is unavailable, clai keeps previously learned limits, then uses its model table or the 200,000-token default if no limit is known. A 200k context can also be an actual gateway limit, rather than a fallback. Use `/context` to inspect the selected session's context budget.
+Discovered limits are cached for 30 minutes and retained locally for later sessions. A newly discovered Zen model ID can trigger an earlier metadata refresh; retries for unpublished limits or failed lookups have a one-minute cooldown. For Zen only, a published 200,000-token context is configured as 250,000 tokens in clai; every other published limit is used unchanged. This is a clai policy, not a guarantee that the gateway accepts more than its published limit. When discovery is unavailable, clai keeps previously learned limits; unknown Zen limits use the conservative 200,000-token default, not the upstream model table. Explicit session context overrides remain available. Use `/context` to inspect the selected session's context budget.
 
 Agent turns retry temporary HTTP 429 failures up to four times, with visible waits of 5, 8, 10, and 15 seconds. This includes gateway responses that report an unavailable upstream endpoint. Shorter provider retry hints can shorten a wait. Standalone requests allow three retries by default.
 
@@ -208,7 +208,7 @@ Use `/usage` to inspect reported cached input and cache writes. An initial cache
 - Applicable authentication, quota, rate-limit, and server failures can rotate credentials. The most recently successful credential is preferred.
 - Cross-provider fallback is opt-in through `/fallback on`. `/freeonly on` restricts fallback by clai's configured provider categories; this filter does not determine a model's price or account bill.
 
-Saved credentials are retained in the plaintext recovery file `~/.clai/keys.json`, with restricted POSIX permissions, and are also written to the OS keyring when available. See [configuration and privacy](README.md#configuration-and-privacy).
+Saved credentials are retained in the plaintext recovery file `~/.clai/keys.json`, with restricted POSIX permissions, and are also written to the OS keyring when available. See [configuration and privacy](guides/configuration.md).
 
 ## Web search
 

package/REA.md

@@ -0,0 +1,96 @@
+# REA: Reverse Engineer Anything
+
+clai integrates the official [morluto/rea](https://github.com/morluto/rea) project as an on-demand capability. Use `/rea` in either terminal interface to open its picker.
+
+| Command | Effect |
+| --- | --- |
+| `/rea install` | Install the latest official `rea-agents` package privately for clai. |
+| `/rea setup` | Install if needed and connect clai's managed REA server. |
+| `/rea update` | Verify and stage the latest release without interrupting an existing analysis. |
+| `/rea use` | Connect if necessary and insert an editable `@rea` token in your draft. |
+| `/rea on` | Enable REA for the session without editing the draft. |
+| `/rea off` | Stop only clai's managed REA server. |
+| `/rea status` | Check installation, connection and maintenance state without starting a server. |
+| `/rea reconnect` | Reconnect or adopt an update when it is safe to discard the current analysis connection. |
+| `/rea guide` | Open the usage guide in a markdown pager: commands, how the agent uses REA, supported targets and prerequisites for your OS, permissions, resource use and troubleshooting. |
+| `/rea engines` | Show which analysis engines (Ghidra, Hopper, IDA, Kuna) are ready on this machine and the exact command that fixes each one that is not. |
+| `/rea engines install ghidra` | After a confirmation, download the official Ghidra release and make it usable by REA. |
+| `/rea engines install java` | After a confirmation, install a private JDK 21 for REA's server when Java is what is missing. |
+| `/rea engines use <engine> <location>` | Use an installation you already have: a Ghidra folder, a JDK home, the Hopper launcher, an IDA MCP registration file or a Kuna executable. |
+| `/rea engines remove <engine>` | Forget an engine; clai asks before deleting anything it installed. |
+| `/rea <task>` | Submit `@rea <task>`, for example `/rea inspect this Electron app`. |
+
+`/rea` is the command that opens these options; `@rea` is the token that attaches REA to a prompt. Type `@rea` anywhere in a normal prompt. The token is highlighted in both composers, like `@mcp:` and skill mentions, and is never treated as a file (attach a file that is really named `rea` as `@./rea`). When a turn contains `@rea`, clai connects an installed REA before the model is called and gives the model the workflow and the tool index described below; if REA is not installed, the model is told to run `rea.manage action=setup`. The agent can also choose REA through `rea.manage` when the task warrants it; no manual activation is required. Installation and agent-initiated state changes use the normal permission policy. Ask/plan mode can inspect status and guidance but cannot install or change REA state.
+
+## Installation without npm or npx
+
+The installer uses clai's existing JavaScript runtime and HTTPS APIs; it does not invoke a shell, Homebrew, curl, PowerShell, tar, unzip, npm or npx from PATH. A compatible existing Node installation with its npm CLI is reused, looked up in this order: `CLAI_REA_NODE`, the Node that is running clai, then `node` on PATH. Otherwise clai downloads an official Node 24 LTS runtime with npm into its private installation. The native compiled clai binary therefore does not require a preinstalled Node toolchain.
+
+A compatible Node is 22.19+, 24.15+ or 26+ (upstream REA also accepts 24.11 to 24.14, but SQLite inspection needs 24.15+ or 26+). `CLAI_REA_NODE` must point at the `node` executable and is read when REA is installed; to move an existing installation to a different Node, remove `current.json` and run `/rea setup`. Installation is cancellable with Esc from either interface, and a download is abandoned after 60 seconds without data rather than after a fixed total time, so slow links can finish.
+
+Supported portable targets are macOS, Linux and Windows on x64/ARM64, subject to the official Node release's OS/libc support. nodejs.org does not publish Linux musl builds (Alpine), so install Node with the system package manager there. Unavailable architectures/builds produce an error that names the required Node versions and `CLAI_REA_NODE`, not an incompatible executable. Native engine support is a separate upstream constraint.
+
+Files live under `~/.clai/tools/rea` (or `$CLAI_DATA_DIR/tools/rea`). Node archives are checked against the official SHA-256 manifest; REA/npm tarballs use registry SHA-512 integrity. npm verifies dependency integrity, lifecycle scripts are disabled, and the install uses isolated registry/config/cache settings. Package acquisition requires access to `nodejs.org` and `registry.npmjs.org` as applicable. TLS/registry checksum verification is not an independent publisher-signature guarantee.
+
+A staged release is published only after its launcher reports the expected version, and the pointer file is replaced atomically (retrying briefly on Windows when another process holds it). Failures leave the previous release intact. Concurrent maintenance is serialized across processes and deduplicated within a process; a second clai session that waits too long is told that another session is installing. The current and previous releases are always kept so running MCP processes are not broken by an update; reconnect explicitly when ready. Releases older than that, including leftovers from interrupted installs, are removed once they are seven days old. An install takes about 250 MB with an existing Node and about 450 MB when clai also downloads one (the npm cache is shared across releases). Setup never changes Claude Code, Codex, other clients' registrations, skills, or the project's MCP configuration.
+
+## Efficient agent use
+
+REA is for shipped artifacts, decompilation, JavaScript/Electron applications, managed assemblies, Android, firmware, saved captures and requested runtime evidence—not ordinary source-repository reading.
+
+Only one small `rea.manage` tool is permanently advertised. Installing does not start a server. Enabling registers `clai-rea` for the current runtime, preserves other selected MCP servers, and connects once. Repeated enables reuse the analysis. REA's tools are not added to the provider's native tool catalog; the agent calls them through `mcp.call`.
+
+On `@rea`, on enable and on a `guide` request the model receives, once per conversation, a workflow of about 4,200 characters, an `ENGINE:` line and a version-matched index generated from the live catalog: every tool name, grouped by verb, with its required arguments, `~` where the tool accepts `detail` and `!` where it changes state or the target (about 8,300 characters for REA 6.7.0's 207 tools, bounded at 10,000). The index lets the agent call tools directly; `mcp.tools` with an exact tool name returns just that tool's full schema for optional fields and structured arguments. REA schemas are strict, so an argument a tool does not list is rejected and clai appends the accepted argument names to the error. The context is sent once per conversation: later turns that repeat `@rea` reuse it, and it is sent again, once, only if it changed (for example after you install an engine and reconnect).
+
+So that the agent does not call tools that cannot work, clai asks REA once per connection (one `binary_session` call, about 2 seconds and 50 KB, not repeated) which tools need an open target, an analysis engine or a missing prerequisite, and marks the index: `#` acts on the binary opened by `open_binary` and takes no path, `^` also needs an analysis engine, `%` is unavailable on this machine. The `ENGINE:` line says which engines are ready. When a call still fails, clai replaces REA's long machine-readable error with a short instruction: pass no `path` to a `#` tool and call `open_binary` first; thin a universal Mach-O to one slice with `lipo` before Ghidra or Kuna can read it; or, when no engine is ready, do not retry and tell the user to run `/rea engines`. If the availability report cannot be read, the plain index is used. Repeating `enable` on a live connection returns it again on request, without restarting anything. The always-advertised `rea.manage` description is kept to about 450 characters because it is sent with every request. The long human-oriented usage guide is shown only by `/rea guide` and is never sent to the model. Version-matched detailed workflow references remain on disk for focused reading. Prefer summaries, retained Evidence IDs, selected fields and bounded pages instead of repeating analysis or requesting full results. A host timeout does not establish that server work stopped: inspect state/Evidence before retrying. Inspect the actual current schema or returned remediation rather than guessing arguments or reinstalling.
+
+REA activation never rewrites the stable system prompt, native tool schemas, or prior messages. State and workflow changes enter the append-only conversation context. Cache-prefix regression tests cover installation, activation, discovery, calls, update, reconnect, disable and subsequent composer selection in both native/text tool modes and multiple provider wire formats. Provider cache eviction, compaction and switching providers/models remain independent of this guarantee.
+
+## Analysis engines
+
+Static JavaScript and Electron inspection, managed (.NET) assemblies, archives, Mach-O headers, plists, signatures and metadata need no engine. Native decompilation (procedures, pseudocode, strings, cross-references, assembly) needs one of Ghidra, Hopper, IDA or Kuna, and REA does not ship any of them.
+
+Engines are installed by you, never by the agent. `/rea engines` shows what is ready and what to run, and `/rea setup` points at it when it connects REA with no engine ready. `install` shows what it will download and where it will write (press `ctrl+o` for the full plan), asks for confirmation, shows progress and can be cancelled with Esc; `remove` asks before deleting anything clai installed, reconnects REA first so nothing is still using the files, refuses while a turn is running with REA connected, and says so if a folder could not be deleted (on Windows a folder that REA's Ghidra has open can be neither moved nor removed). The agent's workflow tells it not to install or configure an engine and to send you to `/rea engines` instead, and `rea.manage` has no engine action. Only one engine operation runs at a time. If REA is connected and idle when an install finishes, clai reconnects it so the new engine is used straight away; the engine is verified with REA before the install is reported as done.
+
+| System | `install ghidra` | `install java` |
+| --- | --- | --- |
+| macOS arm64 and x64 | Yes. Ghidra does not ship a macOS decompiler, so clai builds it once (one to three minutes; needs the Xcode Command Line Tools). | Yes |
+| Linux x64 | Yes; the decompiler is in the download. | Yes (glibc) |
+| Linux arm64 | Yes; builds the decompiler once (needs make, g++ and bison). | Yes (glibc) |
+| Windows x64 | Yes; the decompiler is in the download. REA's Windows Ghidra support is experimental upstream. | Yes |
+| Anything else (Windows arm64, Alpine and other musl Linux, 32-bit) | Not offered; `/rea engines` says so and why. Use `/rea engines use ghidra <folder>` with your own installation. | Not offered for musl; use `/rea engines use java <JDK home>` |
+
+Hopper is a commercial macOS and Linux application and Kuna is not available on Windows; clai does not install either. IDA needs your own installation and an MCP registration file. These are connected with `/rea engines use`. Android, firmware, capture and similar tools (JADX, apktool, binwalk, tshark and others) have their own prerequisites; `/rea engines` lists the ones that block tools on your machine with the fix REA reports, and clai does not install them.
+
+What `install ghidra` does:
+
+- Resolves the newest Ghidra 12.1.x release on GitHub (the series REA 6.7.0 needs) and refuses to continue unless GitHub publishes a SHA-256 for the download. Downloads are HTTPS only, limited to `github.com`, `*.githubusercontent.com`, `api.github.com` and `api.adoptium.net`, with every redirect re-checked, a size limit and a 60-second stall guard.
+- Checks free disk space first (about 570 MB to download, 1.6 GB while installing and 900 MB afterwards), extracts the archive itself (no `unzip`), and rejects absolute paths, `..`, symlinks, encrypted or ZIP64 entries and checksum mismatches.
+- Builds the native decompiler where needed with `make` using at most four jobs, with a 30-minute limit. It checks for the build tools before downloading anything and tells you what to install.
+- Stages everything in a temporary folder, moves it into `~/.clai/tools/ghidra/<version>` only when it is complete, then asks REA whether Ghidra is usable. A failed or cancelled install leaves nothing behind and keeps the previous version; after a successful one, older versions that clai installed are removed.
+
+Ghidra also needs a JDK 21 or newer. `install ghidra` does not change your system Java: if REA reports that Java is missing or too old, clai offers `install java`, which puts Eclipse Temurin 21 (about 200 MB, SHA-256 verified) in `~/.clai/tools/jdk/` and uses it for REA's server only.
+
+Settings live in `~/.clai/tools/rea/engines.json` (mode 0600; `$CLAI_DATA_DIR/tools/rea` if set). They are passed to REA's server as `GHIDRA_INSTALL_DIR`, `JAVA_HOME`, `HOPPER_LAUNCHER_PATH`, `REA_IDA_MCP_CONFIG` and `REA_KUNA_COMMAND`; a choice made with `/rea engines` takes precedence over the same variable in your own environment, for REA's server only (your shell is untouched), and `/rea engines remove` hands control back to your environment. Variables you have not set through `/rea engines` are passed through unchanged. Reconnect REA (`/rea reconnect`) after changing them yourself.
+
+Ghidra and Kuna cannot open universal (fat) Mach-O files such as most system binaries on macOS. The agent is told to thin one slice into the session scratch directory with `lipo <file> -thin <arch> -output <scratch>/<name>-<arch>` (`llvm-lipo` when `lipo` is missing) and open that. Hopper opens universal files directly.
+
+## Limits
+
+clai does not execute the target. On Linux, owned-process analysis needs a procps-compatible `ps`. The agent follows the selected tool's actual prerequisite or remediation and continues with supported work.
+
+Portable archives and failure cases have deterministic cross-platform fixtures. The implementation was live-tested on Linux ARM64 with REA 6.7.0 and portable Node/npm, including a standalone compiled integration smoke with no system executables on PATH. That smoke bootstrapped Node 24.22.0, discovered 207 tools, performed a digest-bound static analysis and disabled the server without removing the installation.
+
+The engine installers were run for real on freshly provisioned GitHub-hosted machines: Linux x64 and arm64, Windows x64, macOS arm64 and macOS Intel. Each one already exported its own Java (17 on Linux and Windows, 21 on macOS) and had no engine. On each, the shipped code installed Temurin 21 and Ghidra 12.1.4, REA reported Ghidra ready, and `open_binary`, `list_procedures`, `search_procedures` and `procedure_pseudo_code` returned decompiled code for a real system binary (an ELF `ls`, Windows' `whoami.exe`, a thinned Mach-O `ls`). Timings on GitHub's network, where the 543 MB download is quick; on a home connection the download dominates:
+
+| Machine | JDK | Ghidra | Decompiler |
+| --- | --- | --- | --- |
+| Linux x64 | 4 s | 11 s | in the download |
+| Linux arm64 | 3 s | 53 s | built (make, g++ and bison were present) |
+| macOS arm64 | 5 s | 73 s | built |
+| macOS Intel | 10 s | 184 s | built |
+| Windows x64 | 5 s | 18 s | in the download |
+
+The JDK takes 310 to 345 MB on disk and Ghidra 864 to 877 MB. The whole check on each machine, REA's own installation included, stayed under 500 MB of memory in clai's process; measured on its own on macOS arm64, the Ghidra install peaked at about 260 MB and used about 33 seconds of CPU. An Alpine container and a Windows 11 ARM machine report themselves as unsupported with the reason; nothing is downloaded there.
+
+Not exercised live: Hopper, IDA and Kuna, the interactive install dialogs on Windows terminals (they run the same code as the macOS ones, which were driven through a pseudo-terminal), and the unauthenticated GitHub API limit (60 requests per hour per address, which clai explains when it is hit).