Files
reverse-engineering-anything/docs/reference/limits-and-recovery.md
T

25 KiB

Analysis settings, limits, and recovery

Use this guide to inspect and change REA analysis budgets, and to recover from a resource limit. See the MCP contracts, the limit inventory, and the verification report.

Runtime settings through MCP

inspect_analysis_settings lists the curated settings, their current and launch values, source, bounds, application point and relevant operation names. Filters by exact setting IDs, provider or operation intersect. Inspection marks active worker values as not_observed and distinguishes known server limits from unknown client deadlines and receive buffers.

update_analysis_settings accepts an atomic changes array. Each entry names an exact setting and either action: "set" with a schema-validated value, or action: "reset". Reset restores the launch value. expected_revision is an optional compare-and-set guard; conflicts and duplicate keys change nothing. An unchanged write does not advance the revision.

The revision tracks override state, not only effective numeric values. Setting an explicit override equal to the launch value still changes its source to runtime and advances the revision. Reset removes that override, even if the effective number stays the same. Validation, revision checks, and duplicate-key checks all happen before publishing the replacement snapshot; a rejected batch cannot partially apply. Clients coordinating writes can supply expected_revision; without it, valid updates apply to the current state.

Precedence and lifetime

Where a setting supports an explicit per-call argument, precedence is:

  1. The caller's explicit argument.
  2. The accepted operation's runtime override.
  3. Valid launch configuration, where that setting has an environment seed.
  4. The built-in default when launch configuration is absent.

An invalid launch value does not fall through to the built-in default. Preserve omitted caller arguments in Evidence: resolving an internal default must not rewrite the request as though the caller supplied it. null is the explicit unbounded value for ghidra.decompile_timeout_seconds; it is not a substitute for an unknown or omitted value elsewhere.

A write does not extend active work, relaunch a provider, clear retained cleanup, or invalidate successful Evidence.

Expanded ASAR listing admission defaults to 64 MiB and has its own launch seed, REA_ASAR_MAX_LISTING_BYTES. Raising asar.max_header_bytes alone cannot admit expanded paths and entries that exceed this separate budget. The listing bound uses exact safe-integer byte accounting; the host heap and transport constraints remain independent. A lower runtime value is enforced on the next listing even when the archive header was already examined.

Ghidra value-flow controls default to 3,000 operations, 64 inputs per operation, and 12,000 edges. They accept positive Java integer counts and use the respective REA_GHIDRA_VALUE_FLOW_MAX_OPERATIONS, REA_GHIDRA_VALUE_FLOW_MAX_INPUTS_PER_OPERATION, and REA_GHIDRA_VALUE_FLOW_MAX_EDGES launch seeds. Truncation names the exhausted control. Completed Evidence remains accessible, but a new function dossier is observed with the accepted controls instead of replaying an earlier projection.

The native decompiler payload control is separate from those projections and from decompile time. Its launch seed is REA_GHIDRA_DECOMPILE_MAX_PAYLOAD_MIB. Accepted explicit values are 1..2047 MiB: the supported Ghidra implementation shifts that value into a signed integer byte capacity. Omission or runtime null keeps the provider's own default; REA does not guess that default from a different provider version. Changing payload options takes effect before the next native decompile.

Per-call resource policies and selection

An agent can also use controls declared directly by an operation. These do not require a runtime setter or restart. Keep omitted fields omitted in Evidence; report the resolved policy separately where needed. See the owning guides for Apktool string pages, source maps, historical captures, JavaScript precision, managed inspection, and Frida capture.

The same accepted policy must reach acquisition, parsing, worker requests, serialization, cached-result admission and generated consumers where those stages exist. Desktop state views and emitted AgentEnv Python share one policy; delivery pagination never substitutes for producer selection. Capture limits must be selected before an experiment: another experiment cannot recover bytes that were dropped from a previous live observation.

Overrides belong to one REA runtime, survive target close/open, and disappear when REA exits. Connections sharing that runtime share its overrides. No files, ambient environment, registrations or upstream software are edited. Overrides are runtime-wide, not scoped to a target or an individual connection.

Failure and retry

An ASAR admission error supplies details.limit with the exact setting, effective value, units, bounds, scope, application point, update_mode, pending_restart and, when known, required bytes and value source. The agent can immediately call:

{
  "changes": [
    { "setting": "asar.max_header_bytes", "action": "set", "value": 33554432 }
  ]
}

Then retry the same full-archive request once work and cleanup have settled. No preliminary inspection or source subset is required. The setter does not retry automatically. If an explicit per-call value caused the failure, correct that argument; raising a runtime default cannot override it.

The resource owner constructs details.limit from the registry plus the budget it actually enforced. Metadata includes agent_editable: true, scope: "rea-runtime", update_mode, and pending_restart. update_mode is runtime when update_analysis_settings can change the active value, restart when this process keeps the value it started with, and parameter when the budget is adjustable through a per-call argument. Its source records whether the reported value came from a request or a default. An explicit analysis_timeout_ms, max_heap_mb, or command_timeout_ms, plus artifact reader limits and web-network capture budgets, use parameter. pending_restart is false when that reported value is the one this process is using. Optional required_value, source, and parameter fields are supplied only where known or applicable. Do not infer a source because a value happens to equal a default. Error copying, attribution, redaction, and delivery must preserve these facts. Human-readable remediation explains the same failure; clients should not need to parse that sentence to identify an editable setting.

A deadline controlled by something other than a registered setting reports details.limit with control_kind instead of setting. control_kind: "parameter" names the per-call contract field in parameter (native_command_timeout_ms, native_ui_deadline_ms, pwntools_timeout_ms) and applies on the next call. Services and their remediation text name only that field. A CLI command adds cli_flag, the option that sets the field on that command, from its own field-to-flag binding; MCP results do not carry it. A completed or partial result can record the same reference, for example a limit in a web bundle unknowns entry for a script that reached its analysis_timeout_ms deadline. That reference is part of the result and its Evidence identity, so the CLI never adds to it. Instead, the CLI renders the flags in its own --full-output envelope as meta.cli_controls, a map from each recorded contract field to the option that sets it on that command. The bare result is the record itself and gains no CLI field. control_kind: "environment" names the environment variable REA reads when it starts (REA_SWIFTC_COMPILE_TIMEOUT_MS): applies_at is next_startup, or next_invocation for a one-shot invocation. Both carry effective_value, unit, minimum, maximum and default_value. update_analysis_settings changes neither. A limit without control_kind is a registered setting.

This output is breaking. Results and errors no longer carry the previous restart boolean or a single effect field, and there is no compatibility alias. Read update_mode to see whether the setter can change the active value, and pending_restart to see whether a configured value is waiting. A configuration error for a Windows ChangeTime setting carries update_mode on details.settings. Its rejected value does not establish an accepted pending configuration, so pending_restart is omitted. The removed field names are listed in the changelog.

An inspected setting whose launch value is invalid and which has no runtime override likewise omits pending_restart: it has no accepted configured value to classify. Setting a valid runtime override reports pending_restart: false; resetting it restores the invalid launch state and the omission.

scope and applies_at describe a continuing caller, such as an MCP connection. A one-shot invocation, such as a CLI command, has released its provider session and exited its runtime before its caller reads the failure, so its adapter projects with an explicit "invocation" caller lifetime. details.limit then keeps every other field and reports scope: "rea-invocation", applies_at: "next_invocation" and the launch environment seed when one exists. agent_editable: true still holds, because the caller chooses that environment value or per-call parameter for the new invocation; update_mode: "runtime" and pending_restart: false mean the reported value is active in this process. update_mode: "restart" means update_analysis_settings does not change it. update_mode: "parameter" means the budget is adjustable through a per-call argument; source identifies where the reported value came from. A producer keeps guidance that holds only while its caller retains the session, such as "the Ghidra session remains usable" or a same-session runtime update, in continuingCallerGuidance; the shared presentation adds it only for a continuing caller. The producer's own message and remediation must stay true after the session is released. A composed error records each embedded child failure through childFailureDiagnostics, which snapshots it at composition for both lifetimes when they differ, so cleanup history keeps its state and the final projection selects the caller's form. Failures retained inside Evidence keep the continuing form, so CLI and MCP Evidence stay identical.

Cache policy is part of enforcement. Successful reusable analysis can survive a budget update. Transient Ghidra decompile failures remain uncached so a raised deadline can recover on the same Program. Admission checks still apply to reused data: lowering an ASAR limit must reject a cached oversized header. Neither raising a limit nor clearing a transient analysis failure authorizes skipping cleanup or changing the identity of the provider session.

Invalid launch configuration

Launch validation has two relevant boundaries. Settings validated by global configuration parsing can prevent REA from starting; an MCP setter cannot repair a server that is not running. Correct the launch environment or registration, use rea doctor for its configuration checks, and start REA again.

Provider-local validation can leave MCP available. For example, an invalid REA_JADX_OPERATION_TIMEOUT_MS is inspectable with source: "invalid", a configuration_error, and omitted value and launch_value. A valid runtime override repairs the effective JADX timeout without editing that launch seed. Inspection then reports the runtime value while retaining the launch error. Reset exposes the invalid launch state again; it does not repair or replace it with the built-in default. Provider availability and execution must resolve the same effective setting so readiness changes along with repair and reset. REA_NATIVE_MATCHING_REPRESENTATION_BYTES is validated the same way, by match_native_functions alone.

Keep a fixed ceiling honest

A fixed ceiling is the exception. Keep one only for a stated format, protocol, or representation reason.

Inspection's separate constraints describe operator-owned, external, and fixed controls. REA can report its configured response budget and parent heap limit; client deadlines and receive buffers remain explicitly unknown. These are not entries accepted by the runtime setter. Raising a worker heap request cannot raise the parent heap, and raising a provider deadline cannot make the client wait longer.

The failure names the limit and the effective value. Say this release has no runtime override, and name what does not raise it. Do not invent a setting.

JSON values stop at MAX_JSON_DEPTH (1000) in jsonValue.ts: "JSON value exceeds maximum nesting depth of 1000. This release has no runtime override."

Typed refusals

A producer that refuses a request types the refusal instead of leaving recovery to the resource kind. The domain owner is analysisRefusal.ts. It has three variants. Each one projects under details.refusal with the operation the error is attributed to:

Variant Producer fact Projected fields
fixed_ceiling fixedAllowanceOptions(name, kind, { limit, unit, narrowing }), or an artifact reader's artifactFixedLimitFailure(allowance, outcome) allowance, allowance_kind, limit, unit, narrowing
adjustable_budget an AnalysisSettingLimit bound as limit control, setting, effective_value, unit, range, optional required_value
ambiguous_selector AnalysisInputError option ambiguousSelector: { field, candidates } field, candidates

Presentation is total over these variants. Authored remediation still wins. Without it, the variant names the recovery: fixed ceilings and their narrowing step, the budget's control and range for the caller's lifetime, or the selector field and its candidates. A resource refusal never falls back to text about worker limits, the MCP transport, or doctor. An ambiguous selector conforms to the input contract, so it does not ask the caller to inspect the schema.

A measured exhaustion or occupied admission is not a refusal. It declares measuredExhaustion: true and keeps the resource kind's recovery. The rea/typed-resource-refusal lint rule rejects a new AnalysisResourceConstraintError that names none of these. Older untyped constructions are counted in scripts/lint/rules/typed-resource-refusal-baseline.json, and those counts may only shrink.

Recovery text

The string the caller sees includes:

  • the limit or setting name
  • the effective value and unit
  • the source when known (default, setting, runtime, or request)
  • the default, the maximum, and the floor when the setting has one
  • the next action, including where to set it ("in the environment that starts REA")
  • whether a restart is required
  • what the change does not raise

Distinguish an invalid configuration from a valid budget exhausted by work. Preserve the configuration failure and its setting identity; apply the launch validation boundary when describing whether live repair is possible.

What agents do

Use details.limit for a direct runtime update when it names an editable setting with scope: "rea-runtime". For scope: "rea-invocation", set its environment or parameter for a new invocation instead. Follow remediation.action for per-call, fixed and external controls. Inspect settings only when bounds or application details are missing. Restart only when it says the value is read at startup. A sentence that a control does not raise the limit is not a request to change it.

  • Dropped MCP connection: retry the call once only when it is safe to repeat or known not to have started. If it may already have changed the target, or it fails again, tell the user and ask them to restart the MCP client. Do not start with rea doctor (#6353).
  • REA could not start its connection: retry once. If it fails again, tell the user and ask them to restart the MCP client, then run rea doctor. Do not retry a startup that returns the same unchanged result: tell the user REA could not start, ask them to restart the MCP client, then run rea doctor.
  • Unexpected process-command failure: do not repeat the command. Tell the user the reported reason and ask them to check the scenario or capture files it read; if they are valid, report the failure with its diagnostics. Doctor does not check process commands.
  • cleanup_incomplete: the operation is not retryable. Retry that exact cleanup owner, named in details.resources, and wait until it confirms release before admitting new work on those resources (#6357).
  • resource_constraint for capacity, when retryable is true: wait for the active admission to finish, then retry within the reported limits. Do not restart REA to free the slot.
  • configuration_invalid: when MCP remains available and the failure belongs to a curated provider-local setting, inspect and set a valid runtime override. Otherwise correct the named setting in the environment that starts REA, then start REA again. Run rea doctor for the runtime-configuration: check. Re-run rea setup for that client when the setting is on the registration allowlist, then reconnect so the new process sees it.
  • invalid_request: follow the specific recovery and reported issue. Inspect the schema or CLI help when the input violates the contract or the response asks for inspect_input_contract. A valid selector can instead require a different choice, such as selecting a reported address; an inventory miss does not establish that the target lacks the item. Do not repeat the unchanged call when the response says it cannot succeed unchanged.

A restart is required to adopt a changed launch environment or registration. The curated runtime settings above require no REA restart. It is not the first step for a transient MCP drop, a capacity wait, or retained cleanup.

Adding a runtime setting

  1. Identify the enforcing owner and the real resource constraint. A hardcoded limit becomes an REA_ runtime setting with a default, a floor, and a maximum. Its errors name the setting, the effective value, the source, and the range. A fixed ceiling is the exception and needs a stated format, protocol, or representation reason; that error names the limit and the effective value. A registry entry must not advertise authority REA lacks.
  2. Define the value type and named numeric bounds with the domain owner. Add the ID and metadata to analysisSettings.ts and analysisSettingDefinitions.ts. Reuse those bounds in runtime validation, launch parsing, and error metadata. Choose the application point and provider/operation associations from actual consumers; a shared control need not apply to every provider.
  3. If there is a launch seed, add its parser and appropriate configuration/doctor validation. Decide whether an invalid value blocks the runtime or only the provider. Add it to setup's SELECTED_REGISTRATION_SETTINGS when it should be forwarded; runtime editability does not automatically propagate it.
  4. Thread the shared reader through every applicable composition path. Resolve the effective value within the accepted operation, honor explicit arguments, and preserve their omission in Evidence. Keep availability checks consistent with execution. A worker heap request must not be described as a measured process memory limit.
  5. Enforce the value at its resource boundary and construct structured limit facts there. Preserve those facts through shared error projection and copies. Check cache reuse, lowered admission, transient failures, and retained cleanup against the same ownership rules.
  6. Update the public contracts and affected guides, then regenerate catalogs and packaged skill metadata using the repository commands. Keep externally owned and fixed controls in the separate inspection constraints, not in the editable registry. Validate both store semantics and a public recovery path.

Tests and verification

Cover the unset default, accepted overrides, rejected floor/maximum values, and invalid syntax through the owning parser and configuration boundary. regexMatchingDeadline.test.ts is one example. Assert error codes, setting IDs, values, units, provenance, application points, and resulting behavior. Check that adapters deliver the canonical recovery guidance, with independent assertions for its underlying facts. Avoid freezing prose or deriving all expected values from the same registry used by the implementation; either can hide the wrong failure. See test design for the assertion policy.

Runtime checks cover atomic validation, stale writes, reset, runtime isolation, accepted-operation snapshots, and explicit argument precedence. Public MCP acceptance must reject an oversized ASAR, raise admission, and successfully retry the same complete archive on the same connection. Lowering admission must also refuse previously cached headers. The real Ghidra timeout verifier checks recovery after a live update without replacing its session. Also cover invalid provider-local launch configuration, repair/reset availability, default and custom composition paths, and preservation of structured limits through error copies. Gates used to overlap work and updates need bounded acknowledgements and release/join in finally.

The verification report separates public MCP checks, simulated provider coverage, real Ghidra execution, and measured task costs. It does not establish real-provider behavior for every editable setting or active worker telemetry.

Artifact reader admission

inspect_artifact and extract_artifact accept dotnet_bundle, node_sea and godot groups in artifact_limits. Their controls apply when recognition or inventory encounters that format; supplying a policy does not assert the format is present. Unsupported keys are rejected. Each group follows one domain-owned default policy. See .NET bundles, Node SEA, Godot PCK and Bun standalone for format semantics.

artifact_limits.expanded_bytes selects aggregate plaintext work for ZIP, Bun, SEA and PCK readers, including repeated readable logical occurrences. Omission retains each archive's encoded-size-derived default. The .NET bundle group's own expanded_bytes controls its independently enforced bundle expansion.

Failures preserve details.reader_limit with the exact parameter, effective value, units, supported range, required value when known, next-call scope and can_increase. update_mode is parameter: the caller selects the value on the next call, and update_analysis_settings does not accept it. pending_restart is false. Web-network capture budgets use the same mode. When can_increase is true, raise that field and retry the same complete artifact. At the supported maximum, or when the required representation exceeds it, the failure is not retryable by increasing that budget; inspect the declared dimensions and input validity, or explicitly choose a suitable reader. Summary, pagination and selected extraction do not bypass producing admission. Intrinsic format, safe-integer, path validity and runtime representation constraints remain fixed.

Evidence parameters retain the exact selected object, including omission or {}. When an object was selected, inventory and extraction report the resolved effective_limits; summaries preserve those facts. These are accepted policies, not process-memory telemetry or a claim that every format reader ran. Complete source identities and graph manifests remain content-addressed independently of delivery selection. No partial extraction is claimed on admission failure.