rea-agents 1.2.0 → 1.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 # REA: Reverse Engineer Anything
 
-### One CLI and MCP server for coding agents to reverse engineer anything
+### One CLI and MCP server for agents to reverse engineer anything
 
 **See a feature you like. Understand how it works, down to the binary level.**
 
@@ -24,7 +24,7 @@
 
 ---
 
-See a feature in an app that you want in your own product? Give the app to your coding agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements.
+See a feature in an app that you want in your own product? Give the app to your agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements.
 
 REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, and controlled process capture. The longer-term toolkit extends the same agent workflow to packaged apps, JavaScript bundles, websites, APIs, protocols, mobile artifacts, firmware, runtime behavior, and differences between versions.
 
@@ -73,7 +73,7 @@ REA shows how it reached its conclusions. It does not claim to recover original
 |                          |                                                                                      |
 | ------------------------ | ------------------------------------------------------------------------------------ |
 | **Built for agents**     | Ask what an app does and let your agent inspect it instead of guessing.              |
-| **CLI and MCP**          | Run the same reverse-engineering capabilities from your terminal or coding agent.    |
+| **CLI and MCP**          | Run the same reverse-engineering capabilities from your terminal or agent.           |
 | **Complexity handled**   | REA installs and manages the reverse-engineering tools behind the scenes.            |
 | **From insight to code** | Understand a feature, then build your own version in the same coding session.        |
 | **Local by design**      | Analysis runs on your Mac. REA does not upload the app to a hosted analysis service. |
@@ -88,7 +88,7 @@ npm install --global rea-agents
 rea setup
 ```
 
-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.
+Installing the CLI does not update Homebrew, Node.js, npm, Hopper, or 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.
 
@@ -100,7 +100,7 @@ curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
 
 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
+### With an agent — recommended
 
 ```bash
 npx skills add morluto/rea
@@ -108,7 +108,7 @@ 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.
 
-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.
+Review the setup plan, approve it if appropriate, then describe the app or feature you want to understand. Hopper can run in its free demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.
 
 ### From Terminal — no installation
 
@@ -118,7 +118,7 @@ npx -y rea-agents doctor
 npx -y rea-agents analyze /Applications/Notes.app
 ```
 
-Review the setup plan before confirming it. Restart a configured coding agent so it loads REA.
+Review the setup plan before confirming it. Restart a configured agent so it loads REA.
 
 ### From Terminal — install the `rea` command
 
@@ -157,13 +157,13 @@ If something is not working, run:
 npx -y rea-agents doctor
 ```
 
-`rea doctor --json` is read-only and distinguishes unsupported hosts, missing dependencies, a missing local analysis engine, configuration drift, and healthy checks. Fresh-install activation is reported by setup because Hopper does not expose a reliable noninteractive activation probe.
+`rea doctor --json` is read-only and distinguishes unsupported hosts, missing dependencies, a missing local analysis engine, configuration drift, and healthy checks. Paid-license activation is optional: on Linux, REA runs the supported Hopper demo build on a private Xvfb display and selects Hopper's offered demo mode for each analysis session.
 
 ### Linux installation and troubleshooting
 
-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 macOS, approved setup downloads Hopper's official DMG, verifies it, and installs the app into `~/Applications` without Homebrew or administrator privileges. Hopper may show its demo or license prompt when first opened; 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`.
+On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, approved setup downloads the pinned official Hopper 6.4.2 package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman` to install Hopper and the Xvfb, Python, X11, and XTEST packages used by demo sessions. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`. Demo sessions run on an isolated 1280×1024 Xvfb display. REA verifies the exact supported Hopper binary, its owned process ancestry, the expected dialog geometry, and bridge state before selecting `Try the Demo`; any mismatch fails closed.
 
 The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
 
@@ -178,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`. 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`. Linux demo automation requires `Xvfb`, Python 3, `libX11.so.6`, and `libXtst.so.6`; approved setup installs those direct runtime dependencies and does not interact with the user's desktop display. Hopper's free demo supports analysis with vendor-defined limits, and a paid license is optional. 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.
 
@@ -191,25 +191,40 @@ rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state
 
 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?
+### CLI or agent?
 
-| If you want to…                                           | Use                                                            |
-| --------------------------------------------------------- | -------------------------------------------------------------- |
-| Ask an agent to investigate an app and build a feature    | Install the skill, then talk to your agent                     |
-| 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`        |
+| If you want to…                                                 | Use                                                                       |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Ask an agent to investigate an app and build a feature          | Install the skill, then talk to your agent                                |
+| 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`            |
+| Run or resume a persistent two-version artifact analysis        | `rea investigate-versions`                                                |
+| Reuse immutable analysis results without relaunching a provider | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
+| 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:
 
 ```bash
 export REA_EVIDENCE_ROOTS_JSON='["/absolute/path/to/evidence"]'
+export REA_INVESTIGATION_INPUT_ROOTS_JSON='["/absolute/path/to/releases"]'
 rea evidence-import /absolute/path/to/evidence/bundle.json
 rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
 rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
+rea investigate-versions /absolute/path/to/releases/v1 /absolute/path/to/releases/v2 /absolute/path/to/evidence/releases.json --yes --workspace-name releases
 ```
 
+`investigate-versions` inventories both versions, checkpoints their observed
+Evidence, derives an artifact comparison, and records a changed-behavior report.
+Both input paths must resolve beneath `REA_INVESTIGATION_INPUT_ROOTS_JSON`;
+workspace files remain independently restricted by `REA_EVIDENCE_ROOTS_JSON`.
+The workspace uses deterministic content identities and monotonic CAS-linked
+revisions, so the same request resumes an interrupted run or reuses a completed
+run without replacing earlier investigations. It currently compares static
+artifact structure only; it does not execute either version, and its report
+keeps every difference labeled as a behavior candidate. See
+[Persistent investigation workspaces](docs/investigation-workspaces.md).
+
 Historical source import requires a separate allowlist and never treats source as current behavioral authority:
 
 ```bash
@@ -219,6 +234,30 @@ rea import-reference-source /absolute/path/to/source
 
 Exports never replace an existing file unless `--overwrite` is explicit. Imports are size/depth bounded, validate every Evidence v2 ID and manifest, and never execute bundle content.
 
+Provider-neutral analysis snapshots persist successful, immutable REA calls and
+their Evidence v2 records. They are exact caches rather than Hopper databases:
+REA reuses an entry only when the binary digest, format, architecture, operation
+parameters, loader arguments, and provider identity match. Custom Hopper loader
+overrides disable snapshots because their provider configuration cannot be
+replayed safely. Cursor-dependent and mutating calls are never cached. Snapshot
+files can contain proprietary analysis results and local
+paths, so REA keeps them local, writes them with owner-only permissions, and
+requires a separate approved root:
+
+```bash
+export REA_ANALYSIS_SNAPSHOT_ROOTS_JSON='["/absolute/path/to/analysis"]'
+rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
+# The same exact query can now be answered from the snapshot.
+rea analyze /absolute/path/to/app --snapshot /absolute/path/to/analysis/app.json
+```
+
+Exact CLI evidence replays happen before any provider starts. In MCP sessions,
+pass `snapshot_path` to `open_binary` to import a snapshot atomically while
+opening its matching target; MCP providers may still start before a cached call
+is replayed. Pass `snapshot_path` and, when required, `overwrite: true` to
+`close_binary` to save atomically before Hopper resources are released. If the
+save fails, REA deliberately leaves the session open.
+
 ## One prompt, a full investigation
 
 ```text
@@ -246,7 +285,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 - Reconstruct an app's authentication, storage, update, or networking flow.
 - Recover enough structure to document an undocumented format or interface.
 - Trace a suspicious behavior from a string or symbol to the code that implements it.
-- Compare implementation paths across two app versions by switching targets in one session.
+- Run, checkpoint, resume, and reuse a content-addressed artifact investigation across two versions.
 - Turn recovered behavior into product features, tests, migration notes, ports, or interoperable replacements.
 - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
 - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
@@ -273,6 +312,7 @@ REA is already useful for native application investigation on macOS:
 - 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.
+- Persist automatic cross-version artifact runs as canonical, lock-protected workspaces with tamper-evident revision commitments.
 - 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.
@@ -283,6 +323,7 @@ REA is already useful for native application investigation on macOS:
 - Verify finite behavioral and structural reconstruction specifications with pass, fail, and unknown kept distinct.
 - Track residual unknowns through immutable CAS revisions, evidence-qualified resolution, contradictions, probes, and validated dependency relationships.
 - With explicit `unknown_registry_approved: true`, record bounded trace/capture residuals, typed provider unavailability, and capture disagreements automatically.
+- Start six [guided MCP workflows](docs/mcp-prompts.md) with live, session-aware completion for documents, procedures, providers, evidence, captures, artifact IDs, and active unknowns.
 
 Hopper is the first provider, not the boundary of the project. Some current workflows still require Hopper and macOS; every evidence record identifies the provider and limitations behind its result.
 
@@ -297,15 +338,15 @@ REA is growing into a toolkit for understanding software across static artifacts
 5. **Runtime observation** — approval-gated LLDB, Frida, system logs, process and filesystem observers, and native API tracing.
 6. **More static-analysis providers** — native platform utilities first, followed by Ghidra, IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, and other engines behind provider-neutral capabilities.
 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.
+8. **Differential reconstruction expansion** — add automatic function matching, protocol/UI comparison, controlled replay, residual-unknown planning, and reconstruction verification to persistent version runs.
 
 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.
 
-## Using REA with other coding agents
+## Using REA with other agents
 
-Setup currently configures Claude Desktop and Cursor automatically. Any coding agent that supports local MCP servers can use REA with the configuration below.
+Setup currently configures Claude Desktop and Cursor automatically. Any agent that supports local MCP servers can use REA with the configuration below.
 
 ### Manual MCP configuration
 
@@ -320,11 +361,16 @@ Setup currently configures Claude Desktop and Cursor automatically. Any coding a
 }
 ```
 
+MCP clients that support prompts can also discover six ordered investigation
+workflows through `prompts/list`. Their optional identifier arguments use the
+current session for bounded `completion/complete` suggestions; see
+[Guided MCP prompts and completion](docs/mcp-prompts.md).
+
 ## How it works
 
 ```mermaid
 flowchart LR
-    Agent["Coding agent"] --> REA["REA<br/>CLI + MCP"]
+    Agent["Agent"] --> REA["REA<br/>CLI + MCP"]
     Terminal --> REA
     REA --> Workspace["Investigation workspace<br/>evidence + artifacts + captures"]
     Workspace --> Router["Capability router"]
@@ -339,7 +385,7 @@ flowchart LR
     Artifact --> Target
 ```
 
-The CLI and MCP server use the same application workflows and evidence contracts. A provider declares which capabilities it supports and the side effects those capabilities may have. Terminal commands are short-lived; an MCP session can retain an active target and evidence ledger across an investigation.
+The CLI and MCP server use the same application workflows and evidence contracts. A provider declares which capabilities it supports and the side effects those capabilities may have. Terminal commands are short-lived; an MCP session can retain an active target and evidence ledger across an investigation. Approved persistent workspaces keep canonical Evidence and resumable run checkpoints across both process and session lifetimes.
 
 ## CLI
 
@@ -354,6 +400,7 @@ npx -y rea-agents function /Applications/Notes.app 0x1000
 npx -y rea-agents xrefs /Applications/Notes.app 0x1000
 npx -y rea-agents trace /Applications/Notes.app "offline"
 npx -y rea-agents compare /absolute/path/to/left-evidence.json /absolute/path/to/right-evidence.json
+npx -y rea-agents investigate-versions /path/to/v1 /path/to/v2 /absolute/path/to/evidence/releases.json --yes
 npx -y rea-agents capabilities
 npx -y rea-agents providers
 ```
@@ -373,6 +420,27 @@ rea mcp
 
 REA accepts a Mac `.app` folder directly. If an agent cannot find an app by name, tell it where the app is installed.
 
+### CLI exit status
+
+| Status    | Meaning                                                                                                                                                                                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0`       | The requested operation completed. Truthful unknowns, warnings, and bounded or truncated evidence remain successful results.                                                                                                                                             |
+| `1`       | Arguments, policy, permission, provider analysis, integrity checking, cancellation, timeout, setup, diagnostics, update, uninstall, output encoding, or output writing prevented completion. Structured output identifies the failure category when REA could encode it. |
+| `128 + N` | The process ended from signal `N`, where the shell or runtime preserves the conventional signal-derived status.                                                                                                                                                          |
+
+`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`
+because configuration is not ready; rerun it after approval or remediation.
+`doctor` returns `1` when any check is unhealthy. Output format, full envelopes,
+filters, and token controls never change the operation status.
+
+When REA feeds a shell pipeline, enable `pipefail` so a downstream formatter
+cannot hide its failure:
+
+```bash
+set -o pipefail
+rea inventory-artifact ./app.asar --json | jq . > inventory.json
+```
+
 ## Current Hopper provider
 
 REA starts Hopper when needed; Hopper does not need to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that it will remain behind the current application.
@@ -442,7 +510,7 @@ No. Setup can install Hopper for you, but Hopper remains separate software with
 <details>
 <summary><strong>Does REA upload the app?</strong></summary>
 
-REA has no hosted analysis service. Current providers analyze artifacts and capture behavior locally. Your coding agent or model provider may have its own data policy, so review that separately.
+REA has no hosted analysis service. Current providers analyze artifacts and capture behavior locally. Your agent or model provider may have its own data policy, so review that separately.
 
 </details>
 
@@ -456,7 +524,7 @@ No decompiler can guarantee the original source. REA gives an agent pseudocode,
 <details>
 <summary><strong>Which agents can use REA?</strong></summary>
 
-Any coding agent that can run a local MCP server can use the manual configuration. Setup currently detects and configures Claude Desktop and Cursor automatically.
+Any agent that can run a local MCP server can use the manual configuration. Setup currently detects and configures Claude Desktop and Cursor automatically.
 
 </details>
 

package/bridge/hopper_bridge.py

@@ -20,6 +20,22 @@ MAX_SEARCH_PATTERN_LENGTH = 256
 MAX_SEARCH_VALUE_LENGTH = 4096
 
 
+def _session_document():
+    """Find only the document opened for this authenticated REA session."""
+    target = os.path.realpath(REA_TARGET_PATH)
+    for document in Document.getAllDocuments():
+        paths = (document.getExecutableFilePath(), document.getDatabaseFilePath())
+        for path in paths:
+            if path and os.path.realpath(path) == target:
+                return document
+    return None
+
+
+MAX_REGEX_BACKTRACKING_PATHS = 10000
+MAX_REGEX_CANDIDATE_LENGTH = 4096
+MAX_REGEX_SEARCH_WORK_UNITS = 1000000
+
+
 def _hex(value):
     return "0x%x" % value
 
@@ -216,33 +232,150 @@ def _search_inventory(document, kind):
     return inventory
 
 
+def _checked_regex_paths(left, right, operation):
+    """Apply one path-count operation without crossing the static work budget."""
+    if operation == "add":
+        exceeded = left > MAX_REGEX_BACKTRACKING_PATHS - right
+        result = left + right
+    else:
+        exceeded = right != 0 and left > MAX_REGEX_BACKTRACKING_PATHS // right
+        result = left * right
+    if exceeded or result > MAX_REGEX_BACKTRACKING_PATHS:
+        raise ValueError(
+            "Regex exceeds the %d-path backtracking budget"
+            % MAX_REGEX_BACKTRACKING_PATHS
+        )
+    return result
+
+
+def _repeat_regex_paths(child_paths, minimum, maximum):
+    """Count every bounded repetition path, including alternative child paths."""
+    paths = 0
+    repeated_paths = 1
+    for count in range(maximum + 1):
+        if count >= minimum:
+            paths = _checked_regex_paths(paths, repeated_paths, "add")
+        if count < maximum:
+            repeated_paths = _checked_regex_paths(
+                repeated_paths, child_paths, "multiply"
+            )
+    return paths
+
+
+def _validate_regex_class(items):
+    """Accept only constant-time character-class operations."""
+    allowed = {
+        sre_parse.CATEGORY,
+        sre_parse.LITERAL,
+        sre_parse.NEGATE,
+        sre_parse.RANGE,
+    }
+    if any(operation not in allowed for operation, _ in items):
+        raise ValueError("Regex operation is not supported by the bounded matcher")
+
+
 def _validate_regex_node(node, inside_repeat=False):
-    """Reject regex structures with disproportionate or non-local evaluation cost."""
+    """Return capped path and step bounds for Python regex evaluation."""
+    leaf_operations = {
+        sre_parse.ANY,
+        sre_parse.AT,
+        sre_parse.CATEGORY,
+        sre_parse.LITERAL,
+        sre_parse.NOT_LITERAL,
+    }
     forbidden = {
         sre_parse.ASSERT,
         sre_parse.ASSERT_NOT,
         sre_parse.GROUPREF,
         sre_parse.GROUPREF_EXISTS,
     }
+    for name in ("GROUPREF_IGNORE", "GROUPREF_LOC_IGNORE", "GROUPREF_UNI_IGNORE"):
+        operation = getattr(sre_parse, name, None)
+        if operation is not None:
+            forbidden.add(operation)
     repeat_tokens = {sre_parse.MAX_REPEAT, sre_parse.MIN_REPEAT}
     possessive = getattr(sre_parse, "POSSESSIVE_REPEAT", None)
     if possessive is not None:
         repeat_tokens.add(possessive)
+    atomic = getattr(sre_parse, "ATOMIC_GROUP", None)
+
+    paths = 1
+    steps = 0
     for operation, argument in node:
         if operation in forbidden:
             raise ValueError("Regex lookarounds and backreferences are not supported")
-        if operation in repeat_tokens:
+        if operation in leaf_operations:
+            operation_paths = 1
+            operation_steps = 1
+        elif operation == sre_parse.IN:
+            _validate_regex_class(argument)
+            operation_paths = 1
+            operation_steps = 1
+        elif operation in repeat_tokens:
             if inside_repeat:
                 raise ValueError("Nested regex repetitions are not supported")
             minimum, maximum, child = argument
             if maximum == sre_parse.MAXREPEAT or maximum > 1000:
-                raise ValueError("Unbounded or excessive regex repetitions are not supported")
-            _validate_regex_node(child, True)
+                raise ValueError(
+                    "Unbounded or excessive regex repetitions are not supported"
+                )
+            child_paths, child_steps = _validate_regex_node(child, True)
+            operation_paths = _repeat_regex_paths(
+                child_paths, minimum, maximum
+            )
+            operation_steps = maximum * child_steps
         elif operation == sre_parse.SUBPATTERN:
-            _validate_regex_node(argument[-1], inside_repeat)
+            operation_paths, operation_steps = _validate_regex_node(
+                argument[-1], inside_repeat
+            )
         elif operation == sre_parse.BRANCH:
+            operation_paths = 0
+            operation_steps = 0
             for branch in argument[1]:
-                _validate_regex_node(branch, inside_repeat)
+                branch_paths, branch_steps = _validate_regex_node(
+                    branch, inside_repeat
+                )
+                operation_paths = _checked_regex_paths(
+                    operation_paths,
+                    branch_paths,
+                    "add",
+                )
+                operation_steps = max(operation_steps, branch_steps)
+        elif atomic is not None and operation == atomic:
+            operation_paths, operation_steps = _validate_regex_node(
+                argument, inside_repeat
+            )
+        else:
+            raise ValueError("Regex operation is not supported by the bounded matcher")
+        paths = _checked_regex_paths(paths, operation_paths, "multiply")
+        steps += operation_steps
+    return paths, steps
+
+
+def _bounded_regex_matcher(expression, backtracking_paths, steps_per_path):
+    """Create a matcher with per-candidate and cumulative work bounds."""
+    remaining_work = MAX_REGEX_SEARCH_WORK_UNITS
+    work_per_character = backtracking_paths * max(steps_per_path, 1)
+
+    def matches(value):
+        nonlocal remaining_work
+        if not isinstance(value, str):
+            raise ValueError("Regex candidates must be strings")
+        if len(value) > MAX_REGEX_CANDIDATE_LENGTH:
+            raise ValueError(
+                "Regex candidate exceeds the %d-character safety limit"
+                % MAX_REGEX_CANDIDATE_LENGTH
+            )
+        required_work = work_per_character * max(len(value), 1)
+        if required_work > remaining_work:
+            raise ValueError(
+                "Regex search exceeds the %d-unit work budget"
+                % MAX_REGEX_SEARCH_WORK_UNITS
+            )
+        remaining_work -= required_work
+        return expression.search(value) is not None
+
+    return matches
 
 
 def _search_page(document, kind, params):
@@ -268,11 +401,13 @@ def _search_page(document, kind, params):
     else:
         try:
             parsed = sre_parse.parse(pattern)
-            _validate_regex_node(parsed)
+            backtracking_paths, steps_per_path = _validate_regex_node(parsed)
             expression = re.compile(pattern, 0 if case_sensitive else re.IGNORECASE)
-        except re.error as error:
+        except (re.error, OverflowError) as error:
             raise ValueError("Invalid regex pattern") from error
-        matches = lambda value: expression.search(value) is not None
+        matches = _bounded_regex_matcher(
+            expression, backtracking_paths, steps_per_path
+        )
 
     selected = []
     total = 0
@@ -493,8 +628,29 @@ def _dispatch(method, params):
     global _selected_document
     if method == "health":
         return {"name": "REA Hopper bridge", "version": "1.0.0", "run_id": REA_RUN_ID}
-    if method == "shutdown":
-        return {"shutdown": True}
+    if method in ("shutdown", "shutdown_document"):
+        document = _session_document()
+        if document is None:
+            return {"shutdown": True, "analysis_stopped": True, "document_closed": True}
+        if document.backgroundProcessActive():
+            document.requestBackgroundProcessStop()
+        if method == "shutdown" and REA_OWNS_PROCESS_LIFETIME:
+            return {
+                "shutdown": True,
+                "analysis_stopped": not document.backgroundProcessActive(),
+                "document_closed": False,
+                "cleanup_required": True,
+            }
+        if document.backgroundProcessActive():
+            document.waitForBackgroundProcessToEnd()
+        document.closeDocument()
+        analysis_stopped = not document.backgroundProcessActive()
+        document_closed = _session_document() is None
+        return {
+            "shutdown": True,
+            "analysis_stopped": analysis_stopped,
+            "document_closed": document_closed,
+        }
     if method == "list_documents":
         return [document.getDocumentName() for document in Document.getAllDocuments()]
     if method == "current_document":
@@ -604,9 +760,9 @@ def _dispatch(method, params):
         if method == "procedure_pseudo_code":
             return procedure.decompile()
         if method == "procedure_callers":
-            return [_procedure_name(item) for item in procedure.getAllCallerProcedures()]
+            return sorted((_hex(item.getEntryPoint()) for item in procedure.getAllCallerProcedures()), key=lambda value: int(value, 16))
         if method == "procedure_callees":
-            return [_procedure_name(item) for item in procedure.getAllCalleeProcedures()]
+            return sorted((_hex(item.getEntryPoint()) for item in procedure.getAllCalleeProcedures()), key=lambda value: int(value, 16))
         if method == "procedure_info":
             blocks = list(procedure.basicBlockIterator())
             length = sum(max(0, block.getEndingAddress() - block.getStartingAddress()) for block in blocks)
@@ -657,7 +813,9 @@ def _serve_connection(connection):
             if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
                 raise PermissionError("Invalid bridge capability")
             result = _dispatch(request["method"], request["params"])
-            should_stop = request["method"] == "shutdown"
+            should_stop = request["method"] == "shutdown_document" or (
+                request["method"] == "shutdown" and not result.get("cleanup_required", False)
+            )
             response = {"id": request_id, "result": _json_safe(result)}
         except Exception as error:
             response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512], "type": _diagnostic_type(error)}}