@@ -10,6 +10,9 @@ metadata:
 Prepare every report with the required [advisory template](assets/advisory-template.md);
 keep GitHub metadata separate from its description.
 
+Keep the [private reporting form](../../../.github/VULNERABILITY_REPORT.yml) and
+the template aligned when changing report requirements.
+
 ## Scope and privacy
 
 Follow the repository's current [SECURITY.md](../../../SECURITY.md). This contributor
 
@@ -28,8 +28,9 @@ revision. State who verified what and any failed attempts or limitations.}}
 ## Additional details
 
 {{Optional: include supported details that help review, such as the root cause,
-severity rationale and CVSS/CWE, a proposed fix or verified workaround, known
-unaffected deployments, or a related private PR. Omit this section if none are available.}}
+severity rationale and CVSS/CWE, existing CVE identifiers, disclosure deadlines,
+a proposed fix or verified workaround, known unaffected deployments, or a related
+private PR. Omit this section if none are available.}}
 
 ## Open questions
 
 
@@ -195,6 +195,17 @@ every member one at a time. The PID must survive each case, while an open
 replacement confirmed within the recovery timeout, so the runtime terminated
 the workload.
 
+For RFC 0017 app-listener validation, enable the listener and supply the app TLS
+Secret on the shared Deployment, plus a separate NetworkPolicy allowing the test
+client/proxy to reach its app port. Runtime-port access does not grant app access.
+Discovery returns the acknowledged owner's Pod IP and app port; no headless app
+Service is needed. Exercise HTTP/WebSocket reconnection through graceful downscale
+and abrupt loss, preserving workload generation/PID/in-memory state and the public
+hostname. Verify stale-owner rejection independently of the replacement's success.
+Shared serving leases expire within fifteen seconds of issuance and do not renew
+from configuration alone. Do not claim seamless socket migration or infer external
+ingress readiness from an advertisement.
+
 ### 2. Deploy OpenShell
 
 **Iterative dev** (rebuilds on file changes, recommended during active development):
@@ -255,8 +266,9 @@ task running while using those endpoints.
 ### Viewing local traces
 
 The gateway exports OTLP/gRPC to
-`http://openshell-collector.observability.svc.cluster.local:4317` through the
-default Skaffold values. Forward OTLP/gRPC and the trace UI to the host:
+`http://openshell-collector.observability.svc.cluster.local:4317` through
+`ci/values-local-tracing.yaml`, which only `skaffold.yaml` layers. The Kubernetes
+E2E wrapper omits it, so E2E clusters export no traces. Forward OTLP/gRPC and the trace UI to the host:
 
 ```bash
 mise run helm:k3s:forward
@@ -267,9 +279,10 @@ Kubernetes compute-driver spans under their distinct service names, along with
 Agent Sandbox controller reconciliation spans linked through the Sandbox
 trace-context annotation. The same command exposes OTLP/gRPC on
 `http://127.0.0.1:4317` and, when deployed, the Kubernetes gateway on
-`http://127.0.0.1:8090`. The local `gateway:docker`, `gateway:podman`, and
-`gateway:vm` tasks detect the collector listener at startup and enable trace
-export, OCSF log export, and the agent trace relay only while it is reachable.
+`http://127.0.0.1:8090`. The local `gateway`, `gateway:docker`,
+`gateway:podman`, and `gateway:vm` tasks enable trace export, OCSF log export,
+and the agent trace relay only when `OPENSHELL_DEV_OTLP_ENDPOINT` is set, for
+example `OPENSHELL_DEV_OTLP_ENDPOINT=http://127.0.0.1:4317`.
 Spans an agent exports from inside a sandbox arrive through the supervisor's
 relay with `openshell.telemetry.source=agent` and share `openshell.sandbox.id`
 with that sandbox's supervisor spans.
@@ -631,6 +644,7 @@ for dependencies still declared in `Chart.yaml`.
 | `deploy/helm/openshell/skaffold.yaml` | Skaffold config — images, Helm releases, values overlays |
 | `deploy/helm/openshell/values.yaml` | Default Helm values |
 | `deploy/helm/openshell/ci/values-skaffold.yaml` | Dev overrides (image pull policy, TLS disabled for local Skaffold) |
+| `deploy/helm/openshell/ci/values-local-tracing.yaml` | OTLP export to the `helm:k3s:create` collector (Skaffold only) |
 | `deploy/helm/openshell/ci/values-cert-manager.yaml` | cert-manager PKI overlay (opt-in; disables pkiInitJob) |
 | `deploy/helm/openshell/ci/values-gateway.yaml` | Envoy Gateway GRPCRoute + Gateway overlay |
 | `deploy/helm/openshell/ci/values-high-availability.yaml` | HA test overlay (`replicaCount: 2` with external PostgreSQL Secret) |
 
@@ -41,6 +41,11 @@ tag, or start a second `Pre-release` run for a tag; it has no concurrency guard.
 - `Release` (`release.yml`) is dispatched by hand with the stable version. It
   picks the highest `-pre.N` on `main` whose whole `Pre-release` run passed,
   creates the stable tag on that commit, and publishes without requalifying.
+- Stable releases publish public schemas to `buf.build/openshell/core` with
+  the release tag as the label; prereleases skip Buf publication. The Buf
+  repository must exist and Actions must have a `BUF_TOKEN` secret with write
+  access. A failed Buf push fails the release run; follow Recovery before
+  rerunning the failed publication job.
 
 ## Setup
 
 
@@ -83,3 +83,18 @@ updating a Snap Store support track. Docs retain an
 immutable version and advance latest only for a newer version.
 
 Watch the stable release run and report its result.
+
+## PyPI publishing
+
+Stable releases publish the Python wheel to PyPI from `wheel-publish.yml`, which the `publish-pypi` job in `release-publish.yml` calls after the GitHub Release is created. The workflow downloads the wheel from the stable GitHub Release, not a run's build artifact, and checks the stable tag's source commit and the wheel's release checksum. It uses Trusted Publishing with the `pypi` GitHub environment. PyPI matches the workflow file that contains the publishing job, so configure the `openshell` PyPI project's GitHub publisher with owner `NVIDIA`, repository `OpenShell`, workflow `wheel-publish.yml`, and environment `pypi`. No PyPI API token or GitLab trigger credentials are required.
+
+The environment must allow the branch used to dispatch Release or `wheel-publish.yml`. For a support release, explicitly allow its support branch before dispatching. Required reviewers, if configured, must approve the PyPI job. An existing wheel on PyPI is skipped; PyPI does not allow replacing a published wheel.
+
+If a stable release did not reach PyPI, publish the wheel without rerunning Release:
+
+```shell
+gh workflow run wheel-publish.yml -R NVIDIA/OpenShell --ref main \
+  -f release-tag=vX.Y.Z -f source-sha=<tag commit> -f python-version=X.Y.Z
+```
+
+Development and prerelease wheels remain GitHub Release assets and do not publish to PyPI.
@@ -28,6 +28,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c
 | TUI behavior | `tui-development` |
 | Release artifacts or smoke coverage | `test-release-canary` |
 | Release cadence, tagging, or qualification workflows | `release-captain` |
+| Release workflows or publishers | `release-openshell`, `release-captain`; keep the Release workflows table and the manual-trigger rule in `CI.md` current |
 | CI diagnostics | `watch-github-actions` |
 | Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` |
 | Gator supervision | `launch-openshell-gator` |
 
@@ -135,25 +135,32 @@ For tmachine Kubernetes conformance failures, inspect the `e2e-results-conforman
 
 For the `e2e-suites` lane (`.github/workflows/e2e-suites.yml`), the last lines of the job log give the runner's result: PASS, FAIL (exit 1) after the end of the nextest log (which names the failed tests), or ERROR (exit 2) with the step that broke. FAIL and ERROR also appear as annotations on the run's summary page. Then inspect the `e2e-results-<family>-<package>-<environment>-<installer>` artifact, which holds `junit.xml`, `nextest.log` and, after a failure, the guest's `diagnostics/`.
 
-`Pre-release` temporarily omits Codex Security from its `Security Scan` job.
-`Release` uses the passing prerelease qualification result. Other scanners and
-qualification gates still run. Use the standalone
-`Codex Security Release Qualification` workflow for manual investigation.
-
-For `Codex Security`, an exit code of 2 with partial coverage is an incomplete
-scan, not a HIGH/CRITICAL threshold failure. Check the execution diagnostics in
-the job summary and the `codex-security-diagnostics-<run>-<attempt>` artifact on
+`Pre-release` runs Codex Security as a separate advisory qualification job.
+It scans the exact prerelease tag against the previous stable release. Findings
+and scanner execution failures do not affect qualification or publication;
+failed steps and warnings remain visible. `Release` uses the passing prerelease
+qualification result. Codex Security has no schedule or manual trigger.
+
+For Codex Security `0.8.3`, exit code 2 means an execution or required-output
+failure. Deferred investigations no longer cause that exit code. Check the
+execution diagnostics in the job summary and the
+`codex-security-diagnostics-<run>-<attempt>` artifact on
 scan failure. It contains fixed status values, aggregate coverage counts, and
 disk space before, after, and the minimum sampled every five seconds. Missing
 coverage or manifest documents indicate no readable final report was available;
-deferred items or surfaces needing follow-up can explain partial coverage.
+deferred items or surfaces needing follow-up describe coverage limitations.
+Current reports omit the legacy completeness field, so the diagnostic's
+`coverage` value is `unknown`; use `scan_status` and the exit code for execution.
 Sampling cannot rule out a disk spike between samples.
 
 Artifacts and logs in this public repository are public. Never upload the raw
 scan directory, `report.md`, `coverage.json`, findings, agent state, or scanner
 logs. Coverage reasons and notes are free text and may disclose vulnerabilities.
 The public diagnostic intentionally omits them; detailed review needs an
-approved private destination. Helpers must come from the workflow revision,
+approved private destination. Setting the repository variable
+`CODEX_SECURITY_DIAGNOSTICS_PUBLIC_KEY` enables bounded scanner logging and
+encrypted report retention. Only ciphertext is uploaded; the private key stays
+local. See `CI.md` for decryption. Helpers must come from the workflow revision,
 not from the candidate under scan.
 
 `setup-nix` retries development-shell preparation once when `prepare-shell`
 
@@ -32,11 +32,11 @@ kubernetes-shared-supervisor-pool = { max-threads = 1 }
 filter = "test(/gateway_(scale_and_rollout|pod_rolls)$/)"
 test-group = "kubernetes-ha"
 
-# Both change the shared supervisor pool of the release they run against: one
-# kills a member, the other scales the pool. Never run them at once. Test
-# names, not binary(), for the reason above.
+# These change the shared supervisor pool of the release they run against:
+# they kill members or gateways, or scale the pool. Never run them at once.
+# Test names, not binary(), for the reason above.
 [[profile.e2e-kubernetes.overrides]]
-filter = "test(/^(losing_a_supervisor_pod_moves_its_sandboxes_without_restarting_them|scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running)$/)"
+filter = "test(/^(losing_a_supervisor_pod_moves_its_sandboxes_without_restarting_them|scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running|pool_sessions_follow_their_supervisors_gateway)$/)"
 test-group = "kubernetes-shared-supervisor-pool"
 
 # Scaling the pool runs two bounded Helm upgrades (up to 6 minutes each), waits
@@ -46,6 +46,11 @@ test-group = "kubernetes-shared-supervisor-pool"
 filter = "test(/^scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running$/)"
 slow-timeout = { period = "60s", terminate-after = 20 }
 
+# Three bounded rollouts (up to 5 minutes each) and four settle and exec rounds.
+[[profile.e2e-kubernetes.overrides]]
+filter = "test(/^pool_sessions_follow_their_supervisors_gateway$/)"
+slow-timeout = { period = "60s", terminate-after = 20 }
+
 # Relative to the profile store dir (`e2e/rust/target/nextest/e2e-kubernetes/`).
 [profile.e2e-kubernetes.junit]
 path = "../../../../../results/e2e-kubernetes.xml"
@@ -31,6 +31,11 @@
 /tasks/scripts/check_maintainer_approval_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 /tasks/scripts/alert_maintainer_change_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 
+# Reviewer routing registry and helper
+/REVIEWERS.md @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
+/tasks/scripts/check_review_readiness.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
+/tasks/scripts/check_review_readiness_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
+
 # PR issue acceptance checks
 /tasks/scripts/check_issue_acceptance.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 /tasks/scripts/check_issue_acceptance.test.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
 
@@ -15,5 +15,5 @@ contact_links:
     url: https://github.com/NVIDIA/OpenShell/blob/main/SECURITY.md
     about: >
       Do not report security vulnerabilities through GitHub issues. Follow
-      the disclosure process in SECURITY.md — report through the NVIDIA PSIRT
-      web form or email psirt@nvidia.com.
+      the disclosure process in SECURITY.md — use GitHub's private vulnerability
+      reporting form.