docs: align workflow recovery and current Evidence contracts

docs/browser-scenario-contract.md

@@ -23,9 +23,9 @@ that rejection does not roll back browser effects. REA removes its owned
 future-document scripts, restores live frame methods, then disconnects.
 Add secret declarations, storage seeds, and additional artifact or event
 capture only when needed. Action, secret, and storage counts are not capped.
-Duration, action, and navigation
-timeouts remain fixed provider-owned liveness limits; the request does not
-accept a caller-controlled `limits` object.
+Duration, action, and navigation timeouts remain fixed provider-owned liveness
+limits. `capture.limits` controls retained event and network-content budgets;
+it does not change those liveness deadlines.
 
 ## Minimal launch example
 
@@ -179,12 +179,44 @@ declared action. Each step reports action status, elapsed time, sanitized URLs,
 event bounds, and independently typed capture states for screenshot, DOM,
 accessibility, URL, history, and storage. Console, page-error, network,
 WebSocket, frame, worker, popup, and cancelled-download events are attributed to
-steps and all observed events and requested artifacts are returned inline.
-There are no event, frame, worker, popup, WebSocket, DOM-node,
-accessibility-node, storage-entry, screenshot-count, or cumulative
-metadata-byte caps. Requested artifacts and observed events are returned
-inline without application-defined size ceilings. Other missing sections
-remain explicit and make the capture ineligible for equality claims.
+steps. Retained events and requested artifacts are returned inline; omitted
+events are counted by kind and identify affected network transactions.
+Event and selected network-content retention have caller-selected limits under
+`capture.limits`. Omitted values use the defaults below; every supplied value
+must be a positive safe integer, and callers can raise or lower a default.
+Byte limits are conservative allocation-cost estimates for retained event
+values, including UTF-16 storage and JSON expansion, rather than serialized
+bytes or a promise about exact process memory. `events.omissions.by_kind`
+reports counts and reasons for omitted event kinds. Its
+`network_transactions` rows identify affected transaction IDs and omitted
+event kinds; `network_transaction_range` identifies the contiguous IDs beyond
+the transaction limit. Omission metadata is bounded by the selected
+transaction limit. Other missing sections remain explicit and make the capture
+ineligible for equality claims.
+
+The default limits are 10,000 events, 4 MiB estimated allocation for one
+event, 16 MiB estimated allocation across retained events, 1,024 network
+transactions, 64 KiB of body bytes per transaction phase, 1 MiB estimated
+allocation for body redaction/base64, 1 MiB for retained header values, and
+1 MiB for network metadata. The same limits are included in the capture
+Evidence. Playwright materializes response bodies before REA can inspect their
+byte length; `max_network_body_bytes` bounds subsequent retained copies and
+does not bound the browser API read itself. A body that exceeds its selected
+limit has an explicit `body-size-limit` or `body-allocation-limit` unavailable
+state with the observed and allowed values.
+
+Additional implementation bounds are 16 simultaneous network-content reads,
+a 5-second deadline for each provider API read, and 2,048 live event-listener
+owners. These are not caller-selectable. The concurrency bound queues admitted
+content jobs and does not itself omit observations; a provider read timeout
+produces a typed unavailable state, while exceeding listener capacity produces
+event-kind omission counts. A preflight avoids body redaction and base64 copies
+when the currently available event budget already rejects the body.
+Concurrent reads may each pass that check before their events are retained;
+their retained-copy work is bounded by 16 times the selected per-body
+allocation limit. The Playwright response Buffer itself is materialized before
+REA can apply that limit. Requested artifacts and retained events are returned
+inline within the declared limits.
 Attach-mode captures also declare the unavoidable pre-attach event gap.
 
 Selected event families are observed on the root page and discovered descendant
@@ -288,16 +320,21 @@ retained representation after redaction.
 
 Only completed responses are read. At the end of the final step, observation
 stops; requests still in flight emit `request-unfinished`, and their observed
-responses have explicitly unavailable bodies. This cutoff does not wait for
-long-lived streaming connections. Already-started content reads settle before
-browser cleanup, with a provider-owned five-second timeout per read and
-cancellation support. Failed or unexposed reads retain per-content states and make selected
-event coverage incomplete. Body events can arrive during later steps or final
-drain; event bounds describe receipt during the step, while the source event
-reference establishes the transaction phase. Comparison attributes content, like
-every other event of its transaction, to the step that sent the request (the
-receipt step when that request was not observed) and excludes the sequence
-reference from normalization.
+responses have explicitly unavailable bodies. Already-admitted content reads
+drain before browser cleanup. At most 16 reads run at once; queued work is
+bounded by the selected network-transaction limit and by successful admission
+of its request or response event. Each provider API read has its own five-second
+timeout once it starts, so queue wait adds to total drain and cleanup time; this
+is not a five-second total capture cutoff. Cancellation interrupts active reads
+and queued jobs produce cancelled states without calling their provider APIs.
+This drain does not wait for long-lived unfinished streaming connections and
+does not refetch unfinished response bodies. Failed or unexposed reads retain
+per-content states and make selected event coverage incomplete. Body events can
+arrive during later steps or final drain; event bounds describe receipt during
+the step, while the source event reference establishes the transaction phase.
+Comparison attributes content, like every other event of its transaction, to
+the step that sent the request (the receipt step when that request was not
+observed) and excludes the sequence reference from normalization.
 Playwright scenario capture does not supply initiator stacks; passive CDP
 observation retains its own initiator evidence.
 

docs/cli.md

@@ -319,11 +319,44 @@ redirected, which keeps large results smaller for agents and scripts; pipe
 through `jq .` for indented files. Output selection and formatting do not change
 operation status.
 
-| Status    | Meaning                                                                                                                                              |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0`       | The operation completed. Its result may include partial evidence, warnings or unresolved questions.                                                  |
-| `1`       | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. |
-| `128 + N` | Signal `N` ended the process, where the shell or runtime preserves the conventional signal-derived status.                                           |
+For `cutter-command`, `--json-output` requests command-specific JSON from
+Cutter when available. This is separate from `--format json`, which selects the
+CLI result representation; the global `--json` flag selects that same CLI
+representation.
+
+Cutter still accepts deprecated `--json=true` and `--json=false` compatibility
+values. When both forms are present, `--json-output` takes precedence in either
+argument order. Bare `--json` retains its global meaning of selecting JSON CLI
+output formatting.
+
+| Status    | Meaning                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`       | The operation completed. Its result may include partial evidence, warnings or unresolved questions.                                                                                                                                                                                                                                                                                    |
+| `1`       | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available.                                                                                                                                                                                                                                   |
+| `128 + N` | Signal-derived status. An unhandled signal may have ended the process, with the shell or runtime preserving the conventional status; a command may instead have handled the signal, waited for its operation and cleanup to settle, and assigned the same status (`130` for SIGINT, `143` for SIGTERM). In the handled case, it may also have printed a structured `cancelled` result. |
+
+A `cancelled` result does not by itself determine the exit status; it depends on
+the command's signal handling. Commands routed through the shared
+`withCommandCancellation` handler in the CLI set status `130` for SIGINT or
+`143` for SIGTERM after their operation settles. Current source registrations
+use that handler for process capture and comparison (`capture-process`,
+`compare-process-captures`), JavaScript application analysis (`analyze` when it
+selects the JavaScript lane, and `analyze-javascript-application`), selected
+browser, web and Electron commands (including `analyze-web-bundle`,
+`observe-web-execution`, `capture-browser-scenario` and
+`capture-electron-scenario`), and the platform and provider command families
+for Android/ADB, Apktool/JEB/Flutter, firmware, PCAP and signal analysis,
+WASM/EVM, Go/Rust and binary diagnostics, Frida instrumentation, the Cutter
+command, objdump, Rizin and GDB. In these paths, a returned structured
+`cancelled` result can be printed before the wrapper assigns the
+signal-derived status. This describes the current source routing; it is not a
+claim that every command or provider runtime has been independently exercised.
+
+`inspect-artifact` also returns a structured cancelled result, but its direct
+analysis cancellation path does not set a signal-derived exit status, so it
+exits `1`. Setup has its own contract: cancellation exits `0`. Treat the
+structured result and process status as separate signals when scripting
+cancellation.
 
 `setup --dry-run` returns `planned` and exits `0`; a cancelled setup also exits
 `0`. Setup returns `1` for `needs_confirmation` or `needs_human`.

docs/javascript-application-workflows.md

@@ -60,6 +60,8 @@ provider implicitly.
 `trace_javascript_semantics` queries the authenticated companion graph without
 rereading mutable files. A seed may identify a semantic or application node,
 literal, function fingerprint, property, endpoint, event, or boundary field.
+For a recovered parse, coercion, or validation boundary, its field value is the
+static operation's method name (for example, `Number`).
 The query declares backward provenance, forward influence, callers, or
 ownership and can restrict admitted relation kinds. REA returns every matching
 seed and the complete reachable subgraph; callers do not choose node, relation,

docs/jeb-analysis.md

@@ -16,6 +16,12 @@ URL after validating its syntax. That validation does not establish that the
 JEB service is reachable or that a project is open; use the existing
 `inspect-jeb-client` command for a read-only service query.
 
+MCP `binary_session` probes the live JEB service and its advertised tool catalog.
+Availability is reported per operation: a reachable headless client can support
+inspection and decompilation while refusing `open_jeb_project`. Catalog discovery
+uses one 60-second deadline across connection and pagination; a responsive server
+cannot keep discovery running indefinitely by returning more pages.
+
 Verified against JEB 5.48.0 (Linux x64, licensed build) serving `jeb-mcp-server` 1.3.0 over streamable HTTP.
 
 ## Operations

docs/mcp-contracts.md

@@ -38,13 +38,10 @@ socket and device entries are not opened. Case-distinct archive members remain
 separate observations. Their case-insensitive materialization diagnostic does
 not reduce traversal coverage when both spellings were read.
 
-Current output also retains `coverage_status` (`complete` or `partial`) for existing clients, derived from the scoped traversal status. The owning parser normalizes retained `coverage_status` records to scoped coverage and rejects conflicting declarations.
-
-The coverage field is optional when reading older retained Evidence. The owning
-inventory parser recognizes historical REA scope notices for compatibility;
-unfamiliar legacy limitations remain conservative. Typed records do not derive
-coverage from limitation text. Pages from one inventory must carry the same
-coverage declaration.
+Current inventory Evidence requires scoped `coverage` with a `complete` or
+`unknown` status. Consumers use this producer-owned fact and reject records
+without it; limitations are explanatory and do not supply or infer coverage.
+Pages from one inventory must carry the same coverage declaration.
 
 Function dossiers can declare per-facet coverage in the optional
 `normalized_result.facet_availability` map. Each supplied facet is either

docs/native-investigation.md

@@ -481,8 +481,9 @@ user's permissions and may change files, show UI or use the network.
 
 Debugging must be allowed for the user (Developer Tools access). A
 hardened-runtime target without `com.apple.security.get-task-allow` cannot be
-debugged; `inspect_signature` reports this as the debugger-attach facet, and
-the tool fails with a `debugger-attach-denied` reason.
+debugged; `inspect_signature` reports the signature's `hardened_runtime` value
+and its `entitlements`, including `com.apple.security.get-task-allow` when it
+is present. A denied trace reports the `debugger-attach-denied` reason.
 
 ## Provider and verification boundaries
 

native/windows/README.md

@@ -26,6 +26,29 @@ its manifest. Release CI builds both, and `prepublishOnly` rejects a missing,
 stale, mismatched, or wrong-architecture artifact. A development tarball built
 without this lane reports Windows native controls as unavailable.
 
+## Restore the artifact in a source checkout
+
+The source tree omits `native/windows/build/` from Git. To run Windows
+provider-backed workflows from a checkout without the MinGW build lane, extract
+the two files from the published `rea-agents` tarball whose version exactly
+matches the checkout's `package.json` version. Do not use `latest` or copy files
+from another REA version; the loader verifies the manifest version, ABI,
+architecture, and addon digest before it grants authority.
+
+From the checkout root, replace `<matching-version>` with the `version` in
+`package.json`:
+
+```sh
+npm pack rea-agents@<matching-version>
+tar -xzf rea-agents-<matching-version>.tgz
+mkdir -p native/windows/build
+cp package/native/windows/build/manifest.json native/windows/build/
+cp package/native/windows/build/rea-windows-x64.node native/windows/build/
+```
+
+This is a manual recovery step. REA does not fetch or install the artifact
+automatically. Alternatively, build it using the Linux/MinGW lane above.
+
 ## Boundaries
 
 - Opaque Node objects carry a native type tag, resource kind, and closed state.