docs(limits): describe how to design admission recovery

.agents/skills/reverse-engineer-anything/SKILL.md

@@ -38,8 +38,9 @@ target, or it fails again, tell the user and ask them to restart the MCP
 client. If REA could not start its connection, retry once, then tell the user
 and ask them to restart the MCP client. Do not retry a startup failure that
 returns the same unchanged result. Run `rea doctor` when REA could not start
-or tools stay missing after that restart. Read the recovery guide before a
-second repair attempt.
+or tools stay missing after that restart. For `cleanup_incomplete`, a retryable
+capacity limit, or `configuration_invalid`, follow the recovery guide's ladder
+before asking for a restart. Read that guide before a second repair attempt.
 
 1. Diagnose without changing REA or client configuration. `npx` may download
    the package and write to npm's cache. For Codex, run

.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md

@@ -81,6 +81,37 @@ installed CLI's command help. Refresh the catalog if stale; do not guess fields
 from an older skill or return the entire catalog to repair one field. Correct
 all reported fields before retrying.
 
+## Recovery ladder
+
+Follow the returned remediation. Change a request field or a `REA_*` setting
+only when that text explicitly recommends the change. Restart REA when it says
+the value is read at startup. A mention that a control does not raise a limit
+is not a recommendation to change it. Do not invent a setting. Host memory and
+`NODE_OPTIONS` do not raise a REA admission unless that remediation says so.
+
+- MCP connection dropped: retry that 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 REA's connection failed and ask them to restart
+  the MCP client. Do not run `rea doctor` for the drop itself.
+- REA could not start its connection: retry once, then tell the user and ask
+  them to restart the MCP client. Run `rea doctor` when REA could not start or
+  tools stay missing after that restart. Do not retry a startup failure that
+  returns the same unchanged result.
+- `cleanup_incomplete`, or retained cleanup owners in the error details: retry
+  that exact cleanup owner. Do not start new work that needs those resources
+  until that owner confirms release. Repeating the original call is not that
+  retry.
+- Capacity, when the result is `resource_constraint` and `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`: correct the named setting in the environment that
+  starts REA (the shell or the MCP registration), then restart REA. Run
+  `rea doctor` to see the `runtime-configuration:` check. Re-run `rea setup`
+  for that client when the registration must carry the new setting, then
+  reconnect.
+- `invalid_request`: correct the reported fields from the current schema. Do
+  not repeat the unchanged call.
+
 ## Repair registration when needed
 
 For Codex:

CONTRIBUTING.md

@@ -26,6 +26,8 @@ to locate provider and shared-workflow bottlenecks, preserve Evidence, and
 compare equivalent real tasks before claiming an improvement.
 
 When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.
+When adding or changing an admission ceiling, budget, or deadline, follow
+[admission limits and recovery](docs/design/limits-and-recovery.md).
 
 ## Reporting issues
 

docs/.vitepress/config.ts

@@ -87,6 +87,10 @@ export default defineConfig({
         items: [
           { text: "MCP contracts", link: "/mcp-contracts" },
           { text: "Tool design", link: "/tool-design" },
+          {
+            text: "Admission limits and recovery",
+            link: "/design/limits-and-recovery",
+          },
           { text: "Testing", link: "/testing" },
           { text: "Client verification", link: "/client-verification" },
           {

docs/apktool-resource-analysis.md

@@ -167,6 +167,6 @@ Multi-locale and table-only projection were also verified through real CLI and
 stdio MCP workflows on Linux with Apktool 3.0.3/JDK 21 against NewPipe 0.29.1,
 ApiDemos 6.0.18 and Appium Settings 8.2.1. Independent XML projection checks,
 exact facts/Evidence parity and bounded task costs are recorded in the
-[shared-decode and table-only checkpoint](../experiments/analysis-efficiency/apktool-string-tables.md).
+[shared-decode and table-only checkpoint](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/apktool-string-tables.md).
 This qualifies selected resource facts, not application execution or independent
 binary resource-decoder completeness.

docs/design/limits-and-recovery.md

@@ -0,0 +1,124 @@
+# Admission limits and recovery
+
+How to add a REA-owned admission ceiling, budget, or deadline, and what a caller
+does when one is hit. This is a design rule, not an inventory. Ceilings that
+should become settings are tracked in
+[#6176](https://github.com/morluto/rea/issues/6176). Naming honesty for limit
+errors is [#5910](https://github.com/morluto/rea/issues/5910).
+
+## Name a default, then a setting when operators need headroom
+
+Put the number in a named constant with a unit. Do not leave it as a magic
+number at the call site.
+
+When a workload may need more room, add a setting whose unset value is that
+constant. One module under
+[`src/config/`](https://github.com/morluto/rea/blob/main/src/config) owns the
+default, any floor, the maximum, the schema, the parser, and the recovery
+text. Register that schema on `environmentSchema` in
+[`environment.ts`](https://github.com/morluto/rea/blob/main/src/config/environment.ts).
+`parseConfig` calls `parseEnvironment`. Doctor uses that same parser through
+`nativeAnalysisConfigurationError`, so startup and `rea doctor` accept the
+same values. Add the name to `SELECTED_REGISTRATION_SETTINGS` so `rea setup`
+copies it into the client registration. Unset keeps today's behavior. An
+invalid value is a `ConfigurationError` and projects as `configuration_invalid`.
+Do not fall back to the default.
+
+[`REA_REGEX_MATCHING_DEADLINE_MS`](https://github.com/morluto/rea/blob/main/src/config/regexMatchingDeadline.ts)
+([#6267](https://github.com/morluto/rea/pull/6267)) is the reference. Default
+5000 ms, floor 1 ms, maximum 2147483647 ms, because Node schedules a longer
+`setTimeout` delay as 1 ms. Setup copies the setting. A hit says:
+
+> The effective REA_REGEX_MATCHING_DEADLINE_MS value is 5000 ms (source default; default 5000 ms, floor 1 ms, maximum 2147483647 ms). Set REA_REGEX_MATCHING_DEADLINE_MS in the environment that starts REA to a positive decimal integer from 1 to 2147483647, then restart REA. The worker old-generation heap does not raise this deadline.
+
+[`REA_MCP_MAX_RESPONSE_BYTES`](https://github.com/morluto/rea/blob/main/src/config/mcpResponseBudget.ts)
+is the byte-budget shape: a decimal safe integer with a 10 MiB floor
+(`MINIMUM_RESPONSE_BYTES`), the same shared schema, and no silent fallback. A
+change needs a REA restart and a matching client receive buffer. It does not
+raise REA's reserved string limit or Node's string ceiling. The setup
+allowlist does not copy this setting. A new headroom setting should, following
+the regex deadline.
+
+A per-call budget is not an environment setting. JavaScript `max_heap_mb`
+(CLI `--max-heap-mb`) is an integer from 128 to 16384 MiB, default 1024. It
+applies on the next analysis, which starts a new worker, and does not restart
+REA. It does not raise the parent result budget, transfer ceilings, or fixed
+parser limits.
+
+Host memory and `NODE_OPTIONS` do not raise a REA admission unless that
+admission's recovery says so. The JavaScript parent result budget is one that
+does: its recovery says to set `NODE_OPTIONS` (for example
+`--max-old-space-size=<MiB>`) on the process that starts REA, then restart
+that process. `max_heap_mb` does not raise it.
+
+## Keep a fixed ceiling honest
+
+If the ceiling must stay fixed, say so in the failure. Name 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`](https://github.com/morluto/rea/blob/main/src/domain/jsonValue.ts):
+"JSON value exceeds maximum nesting depth of 1000. This release has no runtime
+override."
+
+## Recovery text
+
+The string the caller sees includes:
+
+- the limit or setting name
+- the effective value and unit
+- the source (`default` or `setting`)
+- 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
+
+Invalid settings never take this path. They are `configuration_invalid`.
+Doctor reports `runtime-configuration:<setting>` and says to correct it in the
+shell or the MCP registration, then rerun.
+
+## What agents do
+
+Follow `remediation.action`. Change a request field or a `REA_*` setting only
+when that text recommends the change. 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](https://github.com/morluto/rea/pull/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
+  to check the input files, then run `rea doctor`.
+- `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](https://github.com/morluto/rea/pull/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`: 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`: correct the reported fields from the current schema or
+  CLI help. Do not repeat the unchanged call.
+
+A restart is required for an environment setting and for a client still
+running the previous registration. It is not the first step for a transient
+MCP drop, a capacity wait, or retained cleanup.
+
+## Tests
+
+Lock the unset default, one accepted override, rejected floor, maximum, and
+syntax, and the recovery sentence through `parseEnvironment` and `parseConfig`.
+[`regexMatchingDeadline.test.ts`](https://github.com/morluto/rea/blob/main/src/config/regexMatchingDeadline.test.ts)
+is the pattern. Project the failure and assert `configuration_invalid` for a
+bad value and the recovery wording for a hit.

docs/go-binaries.md

@@ -61,7 +61,7 @@ rea inspect-go-binary ./application --detail summary --evidence_output ./go-evid
 `--evidence_output` is required for CLI summary delivery and never overwrites an
 existing file. The default CLI/MCP reply remains complete.
 
-[Measured workflows](../experiments/analysis-efficiency/go-build-views.md) include
+[Measured workflows](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/go-build-views.md) include
 catalog repetition and extra calls. Identity/count questions benefit from a
 single summary. In the tested Codex full-catalog configuration, a compound
 question about identity and one dependency uses fewer tokens in captured request JSON with

docs/index.md

@@ -62,7 +62,8 @@ For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md).
 | Use CLI/MCP and retain evidence                     | [CLI](cli.md), [MCP contracts](mcp-contracts.md), [agent prompts](mcp-prompts.md), [obligation ledgers](reconstruction-obligation-ledgers.md)                                                                                                                                                                                                                                                                                                  |
 
 For development, use [testing](testing.md), [client verification](client-verification.md),
-[tool design](tool-design.md), and [releasing](releasing.md).
+[tool design](tool-design.md), [admission limits and recovery](design/limits-and-recovery.md),
+and [releasing](releasing.md).
 [Reconstruction readiness](reconstruction-readiness.md) describes a development
 conformance verifier. [The 6.2 migration](migration-6.2.md) records that release's
 compatibility changes; [the roadmap](roadmap.md) tracks future work.

docs/jeb-analysis.md

@@ -42,7 +42,7 @@ reaches its budget returns a typed timeout naming the phase and the effective
 milliseconds, while caller cancellation remains a cancellation. Allow execution,
 cleanup, and delivery headroom in the outer MCP client deadline.
 
-Earlier verification used JEB 5.48.0 (Linux x64, licensed build) serving `jeb-mcp-server` 1.3.0 over streamable HTTP. The official Linux x64 CE build `5.48.0.202610071539` was also verified through real CLI and production stdio MCP native-code workflows; see the [Linux CE audit](../experiments/analysis-efficiency/jeb-linux-native.md) for measurements and limits. CE verification does not establish licensed/Demo Android decompilation or GUI behavior.
+Earlier verification used JEB 5.48.0 (Linux x64, licensed build) serving `jeb-mcp-server` 1.3.0 over streamable HTTP. The official Linux x64 CE build `5.48.0.202610071539` was also verified through real CLI and production stdio MCP native-code workflows; see the [Linux CE audit](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/jeb-linux-native.md) for measurements and limits. CE verification does not establish licensed/Demo Android decompilation or GUI behavior.
 
 ## Operations
 

docs/testing.md

@@ -946,7 +946,7 @@ analyzed as native code (75k methods on arm64) and decompiled through both
 CLI and MCP with explicit unit selection, plus the thin Java wrapper and
 decoded manifest. The dedicated Dart snapshot processor and `run_script`
 remained GUI-only surfaces in that headless build.
-The separate [Linux CE native audit](../experiments/analysis-efficiency/jeb-linux-native.md)
+The separate [Linux CE native audit](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/jeb-linux-native.md)
 uses the official CE `5.48.0.202610071539` direct CLI launcher and real
 CLI/stdio MCP ELF workflows. That audit does not qualify CE Java/Android
 decompilation or GUI project opening, and it does not replace the licensed

docs/tool-design.md

@@ -66,7 +66,9 @@ satisfy. A plan without execution does not establish runtime behavior.
   enforce the requested target and lifecycle.
 - Add limits only for real format, protocol, authority, or measured resource
   constraints. Report pagination, truncation, cancellation, and partial failure.
-  An assumed agent budget is insufficient justification for a limit.
+  An assumed agent budget is insufficient justification for a limit. Name the
+  ceiling and its recovery as described in
+  [admission limits and recovery](design/limits-and-recovery.md).
 
 ## Own the lifecycle
 

docs/verification/electron-cancellation-2026-10-16.md

@@ -100,7 +100,7 @@ diagnostic helper hashes were not captured at execution; the record marks that
 gap instead of assigning the later frozen hash to earlier runs.
 
 Build each pinned checkout, then run under the existing
-[resource observer](../../experiments/analysis-efficiency/resource-counters.md)
+[resource observer](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/resource-counters.md)
 and a private Xvfb instance. The shared verifier supports all four named cases:
 
 ```sh

docs/verification/javascript-retained-facts-2026-10-15.md

@@ -111,7 +111,7 @@ schemas, exec schema and host rendering are unmeasured. Final same-backend
 controls and optional-discovery measurements are recorded separately in JSON.
 
 Actual Codex CLI trials use the runnable
-[agent harness](../../experiments/analysis-efficiency/javascript-facts-agent.mjs),
+[agent harness](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/javascript-facts-agent.mjs),
 installed CLI 0.161.0, requested alias `gpt-5.6-terra` / high, unchanged questions
 per pair, and fresh processes/MCP. Restricted baseline tools are analysis and
 export; candidate adds the existing `inspect_analysis_view`. Both can reach the
@@ -194,7 +194,7 @@ execution as unknown; the candidate still exported once. The one invalid
 disabled-host attempt (37.679 s / 5.070758 CPU s / 880,414,720 B) is preserved
 as a harness failure, with unavailable operation counts.
 
-Use the [specific artifact oracle](../../experiments/analysis-efficiency/javascript-facts-grade.py) on the compact JSON:
+Use the [specific artifact oracle](https://github.com/morluto/rea/blob/42e1a17d6e6c0487f17be0bae248553c4caba7f7/experiments/analysis-efficiency/javascript-facts-grade.py) on the compact JSON:
 
 ```sh
 python3 experiments/analysis-efficiency/javascript-facts-grade.py \