Clarify gateway and middleware timeout settings

projects/egress-gate/README.md

@@ -92,12 +92,29 @@ written by a harness to disk.
 from egress_gate.gates import create_builtin_registry
 from egress_gate.service import EgressGateServer
 
-server = EgressGateServer(create_builtin_registry())
+server = EgressGateServer(
+    create_builtin_registry(),
+    timeout_middleware_processing=10,
+)
 server.serve_sync("127.0.0.1:50051")
 ```
 
-The service creates one `Timeout` per evaluation and passes that deadline
-through slot acquisition, policy preparation, and `RequestProcessor.process`.
+In this example, `timeout_middleware_processing` gives each evaluation 10
+seconds. Omitting it uses the one-second service default. The value is expressed
+in seconds, must be at least 10 milliseconds, and must resolve to whole
+milliseconds. The service passes one resulting `Timeout` through slot
+acquisition, policy preparation, and `RequestProcessor.process`.
+
+`Describe` leaves the optional binding RPC timeout empty, so OpenShell applies
+the timeout configured on the gateway registration to the complete RPC. The
+registration CLI defaults to 30 seconds and accepts `--timeout` to write a
+different value.
+The helper remembers the gateway file and registration name. On later CLI
+starts, `serve` reads the current gateway timeout and requires the processing
+timeout to be lower. If no registration has been added with the CLI, `serve`
+starts without this check. If the gateway timeout expires, OpenShell applies
+the policy's `on_error` behavior; use `on_error: fail_closed` when middleware
+timeout failures must deny.
 
 ## Documentation and examples
 

projects/egress-gate/docs/architecture/request-lifecycle.md

@@ -55,6 +55,12 @@ encoded output limits return an atomic deny with source `runtime_limit` and
 `egress_gate_limit_exceeded`. No partial mutations or findings are returned.
 Gate contract and execution failures remain gRPC failures.
 
+The internal processing timeout can return this denial only while the RPC is
+still active. The OpenShell gateway owns a separate outer RPC ceiling. If that
+outer clock expires first, OpenShell applies the middleware entry's `on_error`
+policy instead of receiving an Egress Gate result. Use `on_error: fail_closed`
+when middleware timeout failures must deny the request.
+
 ## 5. Serialize the result
 
 The Egress Gate service adapter maps the protobuf-free `EgressResult` to

projects/egress-gate/docs/architecture/service-boundary.md

@@ -19,7 +19,7 @@ supervisor applies allowed mutations to the intercepted request.
 
 | RPC | Behavior |
 | --- | --- |
-| `Describe` | Advertise Egress Gate and the pre-credentials HTTP binding |
+| `Describe` | Return Egress Gate's pre-credentials HTTP binding |
 | `ValidateConfig` | Validate a complete registry-backed pipeline without publishing it |
 | `EvaluateHttpRequest` | Adapt one request, prepare/reuse policy, execute, and serialize |
 
@@ -29,10 +29,23 @@ encoded configuration before registry parsing.
 
 ## Shared deadline and workers
 
-`EvaluateHttpRequest` creates one monotonic `Timeout`. That same deadline is
-used for semaphore acquisition, policy preparation, replacement-lock waits,
-gate execution, and final result checks. `RequestProcessor.process` accepts the
-caller-owned timeout and never creates or stores one.
+`EvaluateHttpRequest` converts `timeout_middleware_processing` into one monotonic
+`Timeout` used for semaphore acquisition, policy preparation, replacement-lock
+waits, gate execution, and final result checks. `Describe` leaves the binding's
+optional RPC timeout empty. OpenShell therefore applies the separately
+configured gateway registration timeout to the complete RPC.
+
+The middleware protocol does not report the resolved gateway timeout back to
+Egress Gate, and OpenShell does not propagate it as a gRPC deadline. For the
+normal CLI-managed path, `add-gateway-registration` remembers the gateway TOML
+path and registration name. `serve` reads the current timeout from that entry
+at startup and requires it to be greater than
+`timeout_middleware_processing`. Direct Python API use and manually managed
+registrations do not have this startup check. If the gateway timeout expires
+first, OpenShell applies the policy's `on_error` behavior.
+
+`RequestProcessor.process` accepts the caller-owned timeout and never creates or
+stores one.
 
 Synchronous work runs in a bounded four-slot executor. The gRPC server permits
 sixteen concurrent RPCs. Cancellation does not stop Python code that already

projects/egress-gate/docs/evaluation.md

@@ -36,7 +36,7 @@ The repository includes a regex policy and two request cases. Run them from
 uv run egress-gate evaluate \
   --policy examples/regex-redaction/egress-gate-config.yaml \
   --cases examples/regex-redaction/cases.yaml \
-  --timeout-seconds 1
+  --timeout 1s
 ```
 
 The command prepares the policy once, runs each case with a fresh timeout, and

projects/egress-gate/docs/operations.md

@@ -13,7 +13,7 @@ environment as needed.
 ```bash title="Start Egress Gate"
 uv run egress-gate gates list
 uv run egress-gate gates schema
-uv run egress-gate serve --listen 0.0.0.0:50051 --timeout-seconds 4
+uv run egress-gate serve --listen 0.0.0.0:50051 --timeout 4s
 ```
 
 Use a reachable non-loopback address only when the supervisor is outside the
@@ -28,15 +28,30 @@ registrations.
 
 ```bash title="Register Egress Gate"
 uv run egress-gate add-gateway-registration \
-  --host-ip YOUR_HOST_IPV4 --name egress-gate --port 50051
+  --host-ip YOUR_HOST_IPV4 --name egress-gate --port 50051 --timeout 30s
 ```
 
 The command updates `OPENSHELL_GATEWAY_CONFIG`, then
 `$XDG_CONFIG_HOME/openshell/gateway.toml`, then
 `~/.config/openshell/gateway.toml`. Use `--config PATH` for another file.
+It remembers the absolute gateway file path and registration name in
+`$XDG_CONFIG_HOME/openshell-egress-gate/registration.toml`, or under
+`~/.config` when `XDG_CONFIG_HOME` is unset.
 Start the gateways again with the same commands or service managers that you
 normally use.
 
+The optional registration `--timeout` sets the gateway RPC timeout written to
+the TOML file and defaults to 30 seconds. It accepts whole seconds or
+milliseconds, such as `45s` or `500ms`, and must be greater than 10ms so the
+internal processing budget can remain lower. Rerunning the command writes the
+value passed on that invocation. Set Egress Gate's internal processing budget with
+`egress-gate serve --timeout DURATION`; the Python API calls that setting
+`timeout_middleware_processing`. It must be at least 10ms and resolve to whole
+milliseconds. When a remembered registration exists, `serve` reads its current
+gateway timeout and refuses to start unless the processing timeout is lower. A
+manually managed setup with no remembered registration starts without this
+check.
+
 To remove a registration, stop any running gateways that use the configuration
 again. List the available names with:
 
@@ -54,9 +69,10 @@ uv run egress-gate remove-gateway-registration --name egress-gate
 
 Start the gateways again after the command completes.
 
-The generated OpenShell middleware timeout is five seconds. Keep the Egress
-Gate `--timeout-seconds` below it so queueing, preparation, and transport have
-headroom.
+`serve --timeout` covers queueing, policy preparation, and every configured
+gate. If the gateway timeout expires first despite the startup check, OpenShell
+applies the policy's `on_error` setting: `fail_closed` denies the request, while
+`fail_open` allows it to continue.
 
 If the middleware RPC returns gRPC `RESOURCE_EXHAUSTED`, capacity may remain
 accounted for briefly while completed RPCs are torn down. The OpenShell gateway

projects/egress-gate/docs/reference/limits-and-failures.md

@@ -6,9 +6,10 @@ agent_markdown: true
 
 # Limits and failure behavior
 
-Limits are fail-closed and content-safe. The `service/` package checks exact
-encoded protobuf sizes. Domain models check scalar, aggregate, and result
-limits.
+Egress Gate-owned limits are fail-closed and content-safe. The `service/`
+package checks exact encoded protobuf sizes. Domain models check scalar,
+aggregate, and result limits. OpenShell owns the separate outer RPC ceiling and
+applies its configured `on_error` behavior when that ceiling expires first.
 
 | Area | Limit |
 | --- | ---: |
@@ -20,7 +21,9 @@ limits.
 | Result metadata aggregate strings | 32 KiB |
 | Gate traces per result | 10 |
 | Header mutations per gate evaluation | 64 |
-| Processing timeout | 30 seconds maximum |
+| Offline `--timeout` | 10 milliseconds minimum; whole milliseconds |
+| `timeout_middleware_processing` | 10 milliseconds minimum; whole milliseconds |
+| Gateway registration timeout | Operator-configurable; helper default 30 seconds |
 | Concurrent processing slots | 4 |
 
 Request context and target aggregates, headers, replacement bodies, regex
@@ -34,7 +37,7 @@ rejected value.
 | --- | --- |
 | Invalid phase, envelope, policy, or input encoding | gRPC `INVALID_ARGUMENT` |
 | Gate contract or unexpected execution failure | gRPC `INTERNAL` |
-| Deadline or pipeline processor limit | deny, source `runtime_limit`, code `egress_gate_limit_exceeded` |
+| Internal processing deadline or pipeline processor limit | deny, source `runtime_limit`, code `egress_gate_limit_exceeded` |
 | Gate terminal deny | deny, source `gate`, gate-owned reason code |
 | Pipeline default deny | deny, source `pipeline_default`, code `egress_gate_default_deny` |
 | Pipeline default allow | allow, source `pipeline_default`, no reason code |
@@ -44,6 +47,10 @@ trace details. Failed policy preparation leaves the active policy unchanged.
 Stable error catalogs and reason codes never include request content or
 arbitrary exception text.
 
+An internal processing timeout returns the runtime-limit denial only while the
+RPC remains active. If the gateway's independent outer RPC ceiling expires
+first, OpenShell applies the middleware entry's `on_error` policy.
+
 ## Finding contract
 
 The released OpenShell wire contract has five fields. The pipeline processor's

projects/egress-gate/examples/class-based-gate/README.md

@@ -39,7 +39,7 @@ Start Egress Gate with this example registry and content-safe debug diagnostics:
 uv run egress-gate \
   --debug \
   --registry examples.class-based-gate.keyword_gate:registry \
-  serve --listen 0.0.0.0:50051 --timeout-seconds 4
+  serve --listen 0.0.0.0:50051 --timeout 4s
 ```
 
 Before you change the gateway configuration, stop any running OpenShell

projects/egress-gate/examples/custom-gate/README.md

@@ -46,7 +46,7 @@ Start Egress Gate with this example registry and content-safe debug diagnostics:
 uv run egress-gate \
   --debug \
   --registry examples.custom-gate.keyword_gate:registry \
-  serve --listen 0.0.0.0:50051 --timeout-seconds 4
+  serve --listen 0.0.0.0:50051 --timeout 4s
 ```
 
 Before you change the gateway configuration, stop any running OpenShell

projects/egress-gate/examples/regex-redaction/README.md

@@ -26,7 +26,7 @@ working directory contains the pattern catalog referenced by `policy.yaml`.
 ```bash
 uv run egress-gate --debug serve \
   --listen 0.0.0.0:50051 \
-  --timeout-seconds 4
+  --timeout 4s
 ```
 
 Before you change the gateway configuration, stop any running OpenShell