rhuss · rhuss · Jul 9, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 11, 2026
diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md
@@ -17,16 +17,21 @@ This project uses YAML form issue templates. When creating issues, match the tem
 
 ### Bug Reports
 
-Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. Apply area or topic labels only when they are clearly known.
+Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. The diagnostic must identify the OpenShell version tested, whether the latest release or known fixes were checked, and whether possible duplicate issues were searched. If the agent cannot verify the latest release or search existing issues, say so explicitly instead of guessing. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "bug: <concise description>" \
   --body "$(cat <<'EOF'
 ## Agent Diagnostic
 
-<Paste the output from the agent's investigation. What skills were loaded?
-What was found? What was tried?>
+- Skills loaded: <skills used during investigation>
+- OpenShell version tested: <version from openshell --version or other source>
+- Latest release checked: <version checked, or unable to verify>
+- Known fixes reviewed: <release notes / merged PRs checked, or unable to verify>
+- Possible duplicates reviewed: <existing issues searched, or unable to verify>
+- Findings: <what the agent found and tried>
+- Remaining reason for filing: <why this still appears to be a bug>
 
 ## Description
 
@@ -44,6 +49,8 @@ What was found? What was tried?>
 - OS: <os>
 - Docker: <version>
 - OpenShell: <version>
+- Latest release checked: <yes/no and reason>
+- Possible duplicates checked: <yes/no and reason>
 
 ## Logs
 

diff --git a/.agents/skills/debug-openshell-cluster/SKILL.md b/.agents/skills/debug-openshell-cluster/SKILL.md
@@ -268,6 +268,57 @@ kubectl -n openshell get configmap openshell-config -o jsonpath='{.data.gateway\
 kubectl -n <sandbox-namespace> get sandbox <sandbox-name> -o jsonpath='{.spec.template.spec.serviceAccountName}{"\n"}'
 ```
 
+If `topology = "sidecar"` is rendered under `[openshell.drivers.kubernetes]`,
+sandbox pods should have an `openshell-network-init` init container running
+`--mode=network-init`, an `agent` container running
+`openshell-sandbox --mode=process`, and an `openshell-supervisor-network`
+container running `--mode=network`. The init container owns nftables setup and
+should be the only sidecar topology container with `NET_ADMIN`. It also needs
+`CHOWN`/`FOWNER` to hand shared emptyDir state to the effective sidecar UID. The
+default binary-aware network sidecar runs as UID 0 with primary GID
+`sandbox_gid` and adds `SYS_PTRACE` plus `DAC_READ_SEARCH`. When
+`process_binary_aware_network_policy = false`, it runs as the configured
+non-root `proxy_uid` without those inspection capabilities. The pod `fsGroup`
+is set to `sandbox_gid` in both modes.
+
+In sidecar topology only the network sidecar should mount the gateway bootstrap
+credentials (`openshell-sa-token` and `openshell-client-tls`). The process
+container should not receive `OPENSHELL_ENDPOINT`, gateway TLS env vars, the
+sandbox token file, or those credential mounts. Instead, the network sidecar
+serves policy and provider environment state over the Unix control socket from
+`OPENSHELL_SIDECAR_CONTROL_SOCKET` (`/run/openshell-sidecar/control.sock` by
+default). The process supervisor must be the first and only client. After
+validating its peer UID, GID, and PID, the sidecar unlinks the listener. If the
+connection later closes, the network sidecar exits non-zero so Kubernetes can
+restart it with a fresh listener. If the process supervisor fails before
+launching the workload,
+inspect both containers for control-socket bind, connect, bootstrap, or update
+errors. If new SSH/exec sessions do not pick up refreshed provider environment,
+inspect the network sidecar settings-poll logs and the process container logs
+for provider environment update handling; the process container should consume
+newer provider-env revisions without receiving gateway credentials.
+
+The process container reports the workload entrypoint PID over the same control
+socket, and the network sidecar uses that PID for binary-scoped policy
+decisions through `/proc`. If rules with `policy.binaries` are unexpectedly
+denied, inspect the sidecar control logs and confirm the pod has
+`shareProcessNamespace: true`.
+The shared state directory should preserve `sandbox_gid` inheritance
+(`02775`). Sidecar SSH uses the Linux abstract socket
+`@openshell-sidecar-ssh`; the network sidecar verifies its peer PID before
+bridging gateway relay requests. No `ssh.sock` file should appear in the shared
+state directory.
+Inspect all three when sandbox registration or egress enforcement fails:
+
+```bash
+kubectl -n openshell get configmap openshell-config -o jsonpath='{.data.gateway\.toml}' | grep -E '^\[openshell\.drivers\.kubernetes\]|^topology\s*='
+kubectl -n <sandbox-namespace> get pod <sandbox-pod> -o jsonpath='{range .spec.initContainers[*]}{.name}{" "}{.command}{"\n"}{end}'
+kubectl -n <sandbox-namespace> get pod <sandbox-pod> -o jsonpath='{range .spec.containers[*]}{.name}{" "}{.command}{"\n"}{end}'
+kubectl -n <sandbox-namespace> logs <sandbox-pod> -c openshell-network-init --tail=200
+kubectl -n <sandbox-namespace> logs <sandbox-pod> -c openshell-supervisor-network --tail=200
+kubectl -n <sandbox-namespace> logs <sandbox-pod> -c agent --tail=200
+```
+
 ### Step 6: Check VM-Backed Gateways
 
 Use the VM driver logs and host diagnostics available in the user's environment. Verify:

diff --git a/.agents/skills/helm-dev-environment/SKILL.md b/.agents/skills/helm-dev-environment/SKILL.md
@@ -60,9 +60,25 @@ mise run helm:skaffold:dev
 mise run helm:skaffold:run
 ```
 
+**Supervisor sidecar topology** (build once and leave running):
+```bash
+mise run helm:skaffold:run:sidecar
+```
+
+**Supervisor sidecar topology with TLS/mTLS enabled** (build once and leave running):
+```bash
+mise run helm:skaffold:run:sidecar-mtls
+```
+
 Both commands build the `gateway` and `supervisor` images and deploy the OpenShell Helm
-chart. The `pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
-generates mTLS secrets on first install. Envoy Gateway opt-in; see the Optional Add-ons section below.
+chart. The sidecar profile renders an `openshell-network-init` init container for
+nftables setup and an `openshell-supervisor-network` runtime sidecar for proxying.
+Binary-aware policy mode runs that sidecar as UID 0 with `SYS_PTRACE` and
+`DAC_READ_SEARCH`; relaxed mode can run it as the configured proxy UID. The
+sidecar-mTLS profile reuses `ci/values-sidecar.yaml` and restores
+`server.disableTls=false` inline for Skaffold. The `pkiInitJob` hook (a pre-install
+Job that runs `openshell-gateway generate-certs`) generates mTLS secrets on first
+install. Envoy Gateway opt-in; see the Optional Add-ons section below.
 
 The gateway Service uses ClusterIP. Access is via Envoy Gateway (port `8080`) or `kubectl port-forward`.
 
@@ -74,7 +90,8 @@ create the Secret named `openshell-ha-pg` with a `uri` key, then run
 ### TLS behaviour
 
 `ci/values-skaffold.yaml` sets `server.disableTls: true`, so Skaffold-based deploys run
-plaintext by default. To test with TLS enabled, comment out that line and redeploy.
+plaintext by default. To test sidecar topology with TLS enabled, use
+`mise run helm:skaffold:run:sidecar-mtls`.
 
 | Mode | `server.disableTls` | Gateway scheme |
 |------|---------------------|----------------|
@@ -126,6 +143,12 @@ openshell sandbox list --gateway-endpoint https://localhost:8090
 mise run helm:skaffold:delete
 ```
 
+For a sidecar-profile deployment:
+
+```bash
+mise run helm:skaffold:delete:sidecar
+```
+
 ### Delete the cluster entirely
 
 ```bash
@@ -250,6 +273,7 @@ for dependencies still declared in `Chart.yaml`.
 | `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) |
 | `deploy/helm/openshell/ci/values-keycloak.yaml` | Keycloak OIDC overlay |
+| `deploy/helm/openshell/ci/values-sidecar.yaml` | Supervisor sidecar topology overlay for Kubernetes e2e/dev |
 | `deploy/helm/openshell/ci/values-spire.yaml` | SPIFFE/SPIRE provider token grant overlay |
 | `deploy/helm/openshell/ci/values-spire-stack.yaml` | SPIRE hardened chart values for local dev |
 | `deploy/helm/openshell/ci/values-tls-disabled.yaml` | Lint-only: TLS + auth disabled (reverse-proxy edge termination) |

diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md
@@ -51,7 +51,7 @@ Query all open issues with the `state:triage-needed` label and process them in s
 gh issue list --label "state:triage-needed" --state open --json number,title --jq '.[].number'
 ```
 
-For each issue returned, run the full triage workflow (Steps 1-6). Report a summary at the end listing each issue and its classification.
+For each issue returned, run the full triage workflow (Steps 1-7). Report a summary at the end listing each issue and its classification.
 
 ## Step 1: Fetch the Issue
 
@@ -89,7 +89,23 @@ Check whether the issue body contains a substantive agent diagnostic section. Lo
 
 **If the diagnostic section is substantive**, proceed to Step 4.
 
-## Step 4: Diagnose and Validate
+## Step 4: Check Reported Version and Known Fixes
+
+Before deeper diagnosis, determine whether the report may already be fixed in a newer release.
+
+1. Extract the reported OpenShell version from the issue body, Agent Diagnostic, environment section, logs, and comments. If no version is provided, record that as missing context and continue.
+2. Check current release information and known fixes when available:
+   - `gh release list --limit 10`
+   - `gh release view <tag>`
+   - linked issues, merged PRs, release notes, and local git tags/history
+3. If network access or release metadata is unavailable, state the limitation in the triage comment instead of guessing.
+
+If the issue targets an older OpenShell release and a newer release or merged PR appears to address the same behavior:
+
+- If the reporter has already reproduced the issue on the fixed/current release, continue to Step 5.
+- If the reporter has not tested the fixed/current release, use the `fixed-in-release` classification in Step 6. Reference the fixing version and PR/issue when known, and ask for a fresh report or reopen if the issue still reproduces on that version.
+
+## Step 5: Diagnose and Validate
 
 Assess the report by investigating the codebase. Use the `principal-engineer-reviewer` sub-agent via the Task tool:
 
@@ -114,20 +130,21 @@ Based on the sub-agent's analysis, also attempt to validate the report directly:
 - For inference and provider-topology issues: reference the `debug-inference` skill's known failure patterns
 - For CLI/usage issues: reference the `openshell-cli` skill's command reference
 
-## Step 5: Classify
+## Step 6: Classify
 
 Based on the investigation, classify the issue into one of these categories:
 
 | Classification | Criteria | Action |
 |---------------|----------|--------|
 | **bug-confirmed** | Agent diagnostic and codebase analysis confirm a real defect | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Bug` issue type manually if needed |
 | **feature-valid** | Design proposal is sound, feasible given the architecture | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Feature` issue type manually if needed |
+| **fixed-in-release** | Report targets an older OpenShell release and a newer release or merged PR appears to address the behavior; no fixed/current-release reproduction is provided | Comment with the fixing version and PR/issue when known. Close as completed when the fix is clear, or request a retest if confirmation is still needed. Remove `state:triage-needed` when closing |
 | **duplicate** | An existing open issue covers this | Link the duplicate, close with comment |
 | **user-error** | The reported behavior is expected, or the issue is a misconfiguration | Comment with explanation and guidance, close |
 | **needs-more-info** | Report is substantive but missing critical reproduction details | Comment requesting specifics, keep `state:triage-needed` |
 | **needs-investigation** | Report appears valid but requires deeper analysis (spike candidate) | Label `spike`, remove `state:triage-needed` |
 
-## Step 6: Post Triage Comment
+## Step 7: Post Triage Comment
 
 Post a structured comment with the triage marker:
 
@@ -136,7 +153,7 @@ Post a structured comment with the triage marker:
 >
 > ## Triage Assessment
 >
-> **Classification:** <classification from Step 5>
+> **Classification:** <classification from Step 6>
 >
 > ### Summary
 > <2-3 sentences: what was found, whether the report is valid>
@@ -148,7 +165,7 @@ Post a structured comment with the triage marker:
 > <Next steps: ready for spike, needs more info from reporter, can be closed, etc.>
 ```
 
-Apply the appropriate labels as determined in Step 5.
+Apply the appropriate labels as determined in Step 6.
 
 **Do not apply `state:agent-ready`.** That is always a human decision.
 

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -9,15 +9,20 @@ body:
 
         OpenShell is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`debug-openshell-cluster`, `debug-inference`, `openshell-cli`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md) for the full skills table.
 
+        Please also check the latest OpenShell release and search existing issues for possible duplicates before filing. If you cannot upgrade, retest, or search existing issues, explain why in the diagnostic.
+
   - type: textarea
     id: agent-diagnostic
     attributes:
       label: Agent Diagnostic
       description: |
-        Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try?
+        Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try? Which OpenShell version did it test, and did it check the latest release, known fixes, and possible duplicates?
       placeholder: |
         Example:
         - Loaded `debug-inference` skill
+        - Tested OpenShell v0.x.x
+        - Checked latest release / known fixes: no matching fix found
+        - Searched existing issues for duplicates: no matching issue found
         - Ran `openshell inference get` and `openshell provider get ollama`
         - Found `OPENAI_BASE_URL=http://127.0.0.1:11434/v1`, which is unreachable from the gateway
         - Updated the provider to use `host.openshell.internal`, but the issue persists because the gateway is remote
@@ -47,11 +52,13 @@ body:
     id: environment
     attributes:
       label: Environment
-      description: OS, Docker version, OpenShell version, and any other relevant details.
+      description: OS, Docker version, OpenShell version tested, whether the latest release and existing issues were checked, and any other relevant details.
       placeholder: |
         - OS: macOS 15.2 / Ubuntu 24.04 / Windows 11 + WSL2
         - Docker: Docker Desktop 4.x / Docker Engine 27.x
         - OpenShell: v0.x.x (output of `openshell --version`)
+        - Latest release checked: yes / no, because ...
+        - Possible duplicates checked: yes / no, because ...
     validations:
       required: true
 
@@ -75,5 +82,9 @@ body:
           required: true
         - label: I loaded relevant skills (e.g., `debug-openshell-cluster`, `debug-inference`, `openshell-cli`)
           required: true
+        - label: I checked the latest OpenShell release and either reproduced the issue there or explained why I cannot upgrade/test it
+          required: true
+        - label: I searched existing issues for possible duplicates or explained why I could not
+          required: true
         - label: My agent could not resolve this — the diagnostic above explains why
           required: true
diff --git a/.github/workflows/branch-e2e.yml b/.github/workflows/branch-e2e.yml
@@ -121,16 +121,25 @@ jobs:
         include:
           - agent_sandbox_api: v1beta1
             agent_sandbox_version: v0.5.0
+            topology: combined
+            extra_helm_values: ""
           - agent_sandbox_api: v1alpha1
             agent_sandbox_version: v0.4.6
+            topology: combined
+            extra_helm_values: ""
+          - agent_sandbox_api: v1beta1
+            agent_sandbox_version: v0.5.0
+            topology: sidecar
+            extra_helm_values: deploy/helm/openshell/ci/values-sidecar.yaml
     permissions:
       contents: read
       packages: read
     uses: ./.github/workflows/e2e-kubernetes-test.yml
     with:
       image-tag: ${{ github.sha }}
-      job-name: Kubernetes E2E (Rust smoke, Agent Sandbox ${{ matrix.agent_sandbox_api }})
+      job-name: Kubernetes E2E (Rust smoke, ${{ matrix.topology }}, Agent Sandbox ${{ matrix.agent_sandbox_api }})
       agent-sandbox-version: ${{ matrix.agent_sandbox_version }}
+      extra-helm-values: ${{ matrix.extra_helm_values }}
 
   kubernetes-ha-e2e:
     needs: [pr_metadata, build-gateway, build-supervisor]

diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml
@@ -93,7 +93,7 @@ jobs:
           path: docs-website
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           version: "0.10.12"
 

diff --git a/.packit.yaml b/.packit.yaml
@@ -66,7 +66,7 @@ jobs:
     trigger: commit
     branch: main
     owner: "maxamillion"
-    project: "openshell"
+    project: "nvidia-openshell"
     identifier: main-commit
     targets:
       - fedora-all
@@ -79,7 +79,7 @@ jobs:
   - job: copr_build
     trigger: release
     owner: "maxamillion"
-    project: "openshell"
+    project: "nvidia-openshell"
     targets:
       - fedora-all
       - epel-10

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -258,6 +258,8 @@ Telemetry events are limited to anonymous operational categories and counts, suc
 
 Opting out applies only to telemetry emitted by OpenShell. Third-party services, model providers, inference endpoints, agents, or tools that you configure and use with OpenShell may have their own terms and privacy practices.
 
+We publish aggregate usage trends from this telemetry every two weeks. See the [community telemetry reports](telemetry/README.md) for the latest summary.
+
 ## Notice and Disclaimer
 
 This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.