docs(policy): explain ambiguity preflight behavior

Signed-off-by: John Myers <9696606+johntmyers@users.noreply.github.com>

Author: johntmyers

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -106,6 +106,30 @@ The middleware service must start before the gateway and be reachable from both
 
 At request time, distinguish an explicit `middleware_denied` result from `middleware_failed`. A denial is always enforced. A failure follows the policy-local `on_error`: `fail_closed` blocks the request, while `fail_open` bypasses only that stage and emits a detection finding. If a running supervisor cannot install a new registry, it preserves its last-known-good generation and emits a configuration failure event.
 
+For network policy validation failures, first distinguish a gateway mutation
+rejection from a supervisor runtime rejection. Direct policy updates,
+incremental merges and approvals, provider attachments, and provider-profile
+fanout are validated against the complete effective policy before persistence
+when the gateway knows the affected sandbox scope. A `FAILED_PRECONDITION`
+ambiguity response means no invalid revision or partial fanout was stored.
+Supervisor validation remains defense in depth for startup, races, and policy
+sources outside those mutation paths.
+
+Runtime rejection behavior is configured only in `gateway.toml`:
+
+```toml
+[openshell.gateway]
+policy_validation_failure_mode = "fail_closed"
+```
+
+The default `fail_closed` mode deactivates the previous generation, closes
+pinned relays, and quarantines new egress until a valid generation loads.
+`retain_last_valid` explicitly keeps the previous valid policy active; without
+one it still fails closed. Restart the gateway after changing this field.
+Inspect sandbox OCSF configuration and finding events for the validation
+rationale, configured and effective modes, active generation, and the explicit
+`previous_policy_active` state.
+
 ### Step 4: Check Docker-Backed Gateways
 
 ```bash
@@ -400,6 +424,8 @@ openshell logs <sandbox-name>
 | Provider profiles disappear after enabling an interceptor catalog | `provider_profile_sources` selected only an authoritative interceptor or returned invalid/duplicate IDs | Inspect source list and interceptor `Describe`/catalog logs; include `builtin` and `user` when intended |
 | Gateway fails after registering supervisor middleware | Service unavailable, invalid manifest, duplicate binding, reserved name, or invalid body/timeout limit | Middleware service and gateway logs; `[[openshell.supervisor.middleware]]`; `Describe` response |
 | Policy update rejects `network_middlewares` | Unknown middleware name, implementation-owned config invalid, duplicate order, broad/invalid host selector, or fail-closed coverage of `tls: skip` | Policy error, gateway logs, middleware `ValidateConfig`, selector and order fields |
+| Policy mutation returns `FAILED_PRECONDITION` for endpoint ambiguity | Equally specific effective endpoint selectors disagree on connection or request-processing metadata | CLI error, base and provider-composed policy, affected profile attachments; confirm no new revision was stored |
+| Supervisor enters policy quarantine | A runtime candidate failed validation while `policy_validation_failure_mode = "fail_closed"` | Sandbox OCSF config/finding events, validation rationale, active generation, `previous_policy_active` |
 | HTTP request returns `middleware_failed` or `middleware_denied` | Selected stage failed or explicitly denied the admitted request | Sandbox OCSF logs; policy-local middleware config; service availability; `on_error` |
 | Custom compute driver is unavailable | Driver process/socket missing, inaccessible, or configured with a reserved/mismatched name | Socket ownership/mode, driver service logs, gateway `GetCapabilities` logs |
 | Image pull failure | Gateway or sandbox image cannot be pulled | Runtime events and image pull credentials |

.agents/skills/generate-sandbox-policy/SKILL.md

@@ -237,7 +237,10 @@ Only needed for the **Moderate** and **Full** tiers. Translate API path paramete
 | `/api/v1/models/{model_id}/versions/{version}` | `/api/v1/models/*/versions/*` |
 | All sub-paths under `/api/v1/` | `/api/v1/**` |
 
-Remember: `*` does not cross `/` boundaries. Use `**` for recursive matching across path segments.
+Path matching uses the runtime `glob` engine. Both `*` and `**` may cross `/`
+boundaries; `?` matches one character, and bracket classes such as `[0-9]` and
+`[!0]` are supported. Prefer segment-shaped patterns such as
+`/repos/*/issues` for readability, but do not rely on `*` to stop at `/`.
 
 ### Building the Explicit Rules List
 
@@ -439,7 +442,7 @@ The policy needs to go somewhere. Determine which mode applies:
 
 2. **Check for conflicts**:
    - Does a policy with the same key already exist? If so, ask the user whether to **replace** it, **merge** new endpoints/binaries into it, or use a different key.
-   - Does an existing policy already cover the same host:port? Warn the user — overlapping endpoint coverage across policies causes OPA evaluation errors (complete rule conflict).
+   - Does an existing endpoint selector overlap the new selector? Compatible overlaps are allowed and can intentionally aggregate allow and deny rules. Reject or revise equally specific overlaps that disagree on connection or request-processing metadata, including TLS, destination constraints, protocol/parser behavior, enforcement, or credential handling. A more-specific path selector may override broader request-processing metadata.
 
 3. **Apply the change**:
    - **Adding a new policy**: Insert the new policy block under `network_policies`, maintaining the file's existing indentation and style.

.agents/skills/generate-sandbox-policy/examples.md

@@ -727,7 +727,9 @@ An exact IP is treated as `/32` — only that specific address is permitted.
 **Agent workflow**:
 
 1. Read `sandbox-policy.yaml`
-2. Check that no existing policy already covers `api.github.com:443` — if one does, warn about overlap
+2. Check existing selectors for `api.github.com:443`. Compatible overlaps may
+   aggregate request rules; revise equally specific overlaps that disagree on
+   TLS, destination, protocol/parser, enforcement, or credential behavior.
 3. Check that the key `github_readonly` doesn't already exist
 4. Insert the new policy under `network_policies`:
 

.agents/skills/openshell-cli/SKILL.md

@@ -351,6 +351,13 @@ Edit `current-policy.yaml` to allow the blocked actions. **For policy content au
 openshell policy set dev --policy current-policy.yaml --wait
 ```
 
+The gateway validates the complete effective candidate—including attached
+provider-profile policy—before it stores a direct update, incremental merge,
+approved proposal, provider attachment, or profile update that affects attached
+sandboxes. An ambiguity failure returns `FAILED_PRECONDITION`; the rejected
+candidate does not create a policy revision or partially update affected
+sandboxes. Fix the conflicting endpoint selectors and submit again.
+
 The `--wait` flag blocks until the sandbox confirms the policy is loaded (polls every second). Exit codes:
 - **0**: Policy loaded successfully
 - **1**: Policy load failed
@@ -569,6 +576,13 @@ openshell settings set --global --key providers_v2_enabled --value true
 
 Global mutations prompt for confirmation. Use `--yes` only in reviewed automation.
 
+`policy_validation_failure_mode` is gateway startup configuration, not a
+mutable `openshell settings` key. Set it under `[openshell.gateway]` in
+`gateway.toml` and restart the gateway. The security-first default is
+`fail_closed`; `retain_last_valid` is an explicit availability tradeoff. OCSF
+configuration events state whether the previous generation is active after a
+runtime validation failure.
+
 ## Workflow 10: Service Access
 
 Use `forward` for local access and `service` for a gateway-managed HTTP endpoint:

architecture/security-policy.md

@@ -108,10 +108,19 @@ connection metadata agrees. When request paths overlap, a path endpoint with a
 higher specificity rank deterministically overrides broader request-processing
 metadata. Equally specific overlapping endpoints must agree.
 
+Gateway mutation paths validate the complete effective candidate before
+persistence when the affected sandbox scope is known. Direct replacements,
+incremental merges and approvals, provider attachment, and profile fanout reject
+ambiguity atomically, without creating an invalid revision or partially
+activating an update. Supervisor validation remains the defense-in-depth
+boundary for startup, concurrent changes, and sources outside those mutations.
+
 The `[openshell.gateway] policy_validation_failure_mode` configuration controls
-rejected generations. It defaults to `fail_closed`, which publishes a quarantine
-generation, denies new egress, invalidates existing relays, and leaves the
-previous policy inactive. Operators may explicitly select
+candidates rejected by supervisor runtime validation. Gateway preflight
+rejections never become generations and leave the active policy unchanged. The
+runtime mode defaults to `fail_closed`, which publishes a quarantine generation,
+denies new egress, invalidates existing relays, and leaves the previous policy
+inactive. Operators may explicitly select
 `retain_last_valid`, which keeps the previous generation active. With no
 previous valid generation, the effective mode remains `fail_closed` regardless
 of the configured mode. The gateway distributes this startup configuration to

docs/reference/gateway-config.mdx

@@ -175,7 +175,7 @@ phases = ["validate"]
 
 Local Docker, Podman, and VM gateways can also set `[openshell.gateway.mtls_auth] enabled = true` to authenticate CLI callers from verified client certificates. Kubernetes deployments must leave this unset and use OIDC or a trusted access proxy; the Helm chart does not render this table.
 
-`[openshell.gateway] policy_validation_failure_mode` controls what sandbox supervisors do when a complete candidate policy fails validation. The default, `fail_closed`, deactivates the previous network policy, closes relays pinned to it, and denies new egress until a valid generation loads. `retain_last_valid` leaves the previous valid generation active. Both modes reject the candidate atomically; startup always fails closed when no previous valid generation exists. Changing the value requires restarting the gateway so it can reload `gateway.toml` and distribute the new posture to sandbox supervisors.
+`[openshell.gateway] policy_validation_failure_mode` controls what sandbox supervisors do when a complete candidate policy fails runtime validation. The default, `fail_closed`, deactivates the previous network policy, closes relays pinned to it, and denies new egress until a valid generation loads. `retain_last_valid` leaves the previous valid generation active. Both modes reject the candidate atomically; startup always fails closed when no previous valid generation exists. Gateway mutation paths that can preflight a known effective scope reject invalid candidates before persistence and leave the active policy unchanged regardless of this setting. Changing the value requires restarting the gateway so it can reload `gateway.toml` and distribute the new posture to sandbox supervisors.
 
 `[openshell.gateway.gateway_jwt] ttl_secs` controls gateway-minted sandbox JWT lifetime. When omitted, it defaults to `0`: the token `exp` claim and `expires_at_ms` response field become `0`, and the sandbox JWT does not expire. Use that default only for local single-player Docker, Podman, or VM gateways. Kubernetes and other shared deployments should set a positive TTL; Helm renders `3600` seconds by default, and the gateway logs a warning when a Kubernetes gateway uses `0`.
 

docs/reference/policy-schema.mdx

@@ -216,7 +216,7 @@ REST allow rules match HTTP requests by method, path, and optional query paramet
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `method` | string | Yes | HTTP method to allow (for example, `GET`, `POST`). `*` matches any method. |
-| `path` | string | Yes | URL path pattern. Supports `*` and `**` glob syntax. |
+| `path` | string | Yes | URL path glob. `*` and `**` match zero or more characters and may cross `/`; `?` matches one character; bracket classes such as `[0-9]` and `[!0]` are supported. |
 | `query` | map | No | Query parameter matchers keyed by decoded param name. Matcher value can be a glob string (`tag: "foo-*"`) or an object with `any` (`tag: { any: ["foo-*", "bar-*"] }`). |
 
 Example REST allow rules:

docs/sandboxes/policies.mdx

@@ -205,7 +205,21 @@ The following steps outline the hot-reload policy update workflow.
 
 OpenShell validates a complete candidate policy before activating any part of it. Endpoints may overlap when their connection and request-processing metadata agree. For example, two `api.example.com:443` REST entries can contribute different allow and deny rules when they use the same TLS, destination, credential, parser, and enforcement settings. A plain L4 endpoint may overlap an L7 endpoint because it authorizes the destination without contributing request-processing metadata. A more-specific path endpoint may override request-processing metadata from a broader endpoint, such as a `/graphql` GraphQL endpoint alongside a general REST endpoint for the same host. OpenShell rejects the candidate when overlapping exact or wildcard host selectors can both contribute equally specific endpoint configuration and disagree on those fields.
 
-The gateway's `policy_validation_failure_mode` configuration determines what happens after rejection. Set it under `[openshell.gateway]` in `gateway.toml`. Its default is `fail_closed`:
+When the gateway knows the affected sandbox scope, it validates the complete
+effective candidate before persistence. This covers direct policy replacement,
+incremental merges and proposal approvals, provider attachment, and
+provider-profile updates that fan out to attached sandboxes. An ambiguity
+failure returns `FAILED_PRECONDITION`; OpenShell stores no invalid policy
+revision and does not partially apply a profile update. Supervisor validation
+remains a defense-in-depth boundary for startup, concurrent changes, and policy
+sources outside those mutation paths.
+
+A gateway preflight rejection leaves the currently active policy unchanged
+regardless of failure mode because the candidate is never persisted or
+distributed. If a candidate reaches a supervisor and fails runtime validation,
+the gateway's `policy_validation_failure_mode` configuration determines the
+supervisor posture. Set it under `[openshell.gateway]` in `gateway.toml`. Its
+default is `fail_closed`:
 
 ```toml
 [openshell.gateway]
@@ -354,13 +368,14 @@ means:
 - match the endpoint `api.github.com:443`.
 - match HTTP method `POST`.
 - match paths like `/repos/acme/issues`.
-- do not match deeper paths like `/repos/acme/project/issues/123` because `*` matches one path segment.
+- also match deeper paths when the surrounding literals align, because `*` may include `/`.
 
 Path globs follow the same semantics as YAML allow and deny rules:
 
-- `*` matches one path segment.
-- `**` matches any number of segments.
-- `/repos/*/issues` matches one repository owner or name segment in the middle.
+- `*` and `**` match zero or more characters and may cross `/` boundaries.
+- `?` matches exactly one character.
+- bracket classes such as `[0-9]` and negated classes such as `[!0]` are supported.
+- `/repos/*/issues` matches any intervening text, including multiple path segments.
 - `/repos/**` matches everything under `/repos/`.
 
 The rule-level commands only modify method and path constraints. They do not change binaries, hostnames, ports, protocol settings, or WebSocket message payload matching.