Automated Sync from main to stable

.agents/skills/apply-triage-action/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: apply-triage-action
+description: Apply, reject, or defer exactly one issue or CI recommendation from a local triage queue report. Use when the on-duty engineer explicitly supplies an item ID.
+metadata:
+  internal: true
+---
+
+# Apply Triage Action
+
+Process exactly one item ID from a queue-review report. Do not accept a natural-language approval without an ID. PRs are informational in v1.
+
+## Locate and validate
+
+1. Read the checkpoint and action records under `.agents/triage-duty/`; reconcile dispositions using the [local-state rules](../review-triage-queue/SKILL.md#local-state).
+2. Use the named report, or the latest report containing the ID. Read the recommendation and current disposition. Material changes to a previously selected recommendation require fresh review and selection.
+3. Reject missing, superseded, already-final, or ambiguous recommendations without making a write. Never substitute another item.
+4. Append every explicit disposition or attempted action to a dated local action record. Record repository, target, source report, ID, timestamp, disposition, reason, confirmed payload, and outcome; update the checkpoint afterward. Keep sensitive content out of the record; use `private reason withheld` for private reasons.
+
+## Reject or defer
+
+For **reject** or **defer**, require the engineer to give a reason. Record the local disposition.
+
+- **Reject** is terminal locally. Do not recommend the item again unless material new evidence changes the case.
+- **Defer** is non-terminal. Preserve its original priority and carry it into the next review's carried **Needs your decision** section.
+
+For shareable deferrals, draft a GitHub issue comment with reason, public links, and next step, or link existing waiting context. Use the confirmation rule below; declined posting leaves a local-only deferral. Keep private reasons out of external payloads and committable files. For missing reporter evidence, also propose the awaiting-information assessment state using `triage-issue`; unrelated dependency waits do not change lifecycle labels.
+
+## Apply
+
+Before any external write, re-read the target and determine whether it materially changed. Follow [Label Discovery](../../../CONTRIBUTING.md#label-discovery), retrieving all pages of current definitions before proposing a label change; use [`triage-issue`](../triage-issue/SKILL.md) for assessment states and maintainer authority.
+
+- If the action is already complete or would be a harmless no-op, make no external write and record the reason.
+- If new information makes the action unsafe or substantially different, stop and request a fresh review/selection.
+
+You MUST ALWAYS preview the exact payload, item ID, source report, and canonical target, then receive explicit confirmation for each individual external write. Selecting or deferring an item is not confirmation; comments, label changes, and closures require separate confirmations. Revalidate immediately before execution; changed payloads require a new preview and confirmation. Never reuse confirmation for a later invocation.
+
+After confirmation, perform only the approved action and record its outcome and public URL; mark applied only after success.
+
+Supported v1 actions:
+
+- Add the discovered triage-queue label to an open substantive community issue; recheck the [intake eligibility rules](../review-triage-queue/SKILL.md#gather-intake) and exclude duplicates, spam, and security disclosures.
+- Create one GitHub issue using [`create-github-issue`](../create-github-issue/SKILL.md).
+- Post one public issue comment, including waiting context or a duplicate explanation.
+- Change an issue's assessment state to awaiting information.
+- Close one issue with an evidenced reason; identify the canonical issue for duplicates.
+
+Never create a public GitHub issue for a security finding. Follow [SECURITY.md](../../../SECURITY.md).

.agents/skills/build-from-issue/SKILL.md

@@ -27,8 +27,10 @@ Use a single issue comment beginning with `> **🏗️ build-plan**` when a plan
 1. Check the current branch and working tree. Preserve unrelated work. Create an issue-specific branch or worktree as needed, following Branch Names in `CONTRIBUTING.md`.
 2. Implement the smallest coherent change that fulfills the acceptance criteria. Update relevant skills when behavior or commands change. Keep published documentation minimal: explain exactly what users need, avoid duplication across pages, and omit internal details with no user impact.
 3. Add meaningful tests for changed behavior and follow the verification guidance in `CONTRIBUTING.md`. Select format, lint, compile or type checks, and tests for affected components and their dependencies. Run the relevant E2E lane for infrastructure, sandbox, or policy changes. Guidance and template edits need applicable Markdown, YAML, link, and consistency checks. Do not require full Rust, SDK, or repository CI solely because a commit or PR is being created; broaden checks only for a concrete remaining risk or failed check.
-4. Review the diff, use a signed-off Conventional Commit, and prepare a PR following `create-github-pr`.
+4. Before pushing, apply the contributor access and issue acceptance check in `create-github-pr`. If blocked, preserve local work and report the reason. Review the diff, use a signed-off Conventional Commit, and prepare the PR.
 
 Every PR from this issue-backed workflow must have its own existing issue and use `Closes #<id>` in its Related Issue section. For work needing multiple PRs, split the scope into a closable issue per PR. A high-level issue may track those issues but should not be closed by an incomplete PR. Report the implementation, verification, and any remaining limitation in the PR description, rather than copying earlier issue diagnostics.
 
 Do not apply acceptance or roadmap decisions on behalf of a maintainer. Do not introduce `agent:*` workflow labels.
+
+For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

.agents/skills/build-openshell-mxc-windows/SKILL.md

@@ -21,6 +21,18 @@ Windows MSVC for the supported deliverables:
 It intentionally does not make Windows a Docker, Kubernetes, Podman, or VM
 runtime host.
 
+The supervisor and supervisor-process libraries participate in native Windows
+checks and tests. Their gateway session, boundary attachment, and TCP readiness
+are portable; only the optional Unix SSH/readiness socket adapters are gated.
+This is compile and control-plane coverage, not Windows isolation qualification.
+Preserve readiness gating on authenticated gateway acceptance and reconnection.
+The supervisor process-access multiplexer consumes boundary-provided streams;
+do not restore local PID, PTY, or process-group operations there. Native process
+mechanics belong to the sandbox or isolation backend. Keep the optional Unix
+SSH access adapter separate from portable session orchestration.
+Shared Sandbox Protocol audit validation defaults to strict Linux evidence;
+concrete platform validators must be selected by the implementing backend.
+
 ## Current Repository Shape
 
 The Windows build lane is implemented by these tracked files:

.agents/skills/build-openshell-mxc-windows/reference.md

@@ -111,8 +111,6 @@ top-level workspace targets for check/test:
 --exclude openshell-driver-vault
 --exclude openshell-driver-vm
 --exclude openshell-sandbox
---exclude openshell-supervisor
---exclude openshell-supervisor-process
 --exclude openshell-vfio
 ```
 
@@ -124,6 +122,10 @@ egress proxy. The Kubernetes Secrets and Vault libraries still compile as
 gateway dependencies; only their standalone Unix-socket binaries and
 package-level tests are excluded as top-level targets.
 
+The supervisor and supervisor-process packages now participate as top-level
+native check/test targets. Their portable session, attachment, and TCP readiness
+coverage does not enable a Windows isolation runtime.
+
 ## Common Errors
 
 ### Unix imports leak into Windows builds

.agents/skills/create-github-pr/SKILL.md

@@ -13,10 +13,30 @@ Create pull requests on GitHub using the `gh` CLI.
 
 - The `gh` CLI must be authenticated (`gh auth status`)
 - You must have commits on a branch that's pushed to the remote
-- Every PR must close an existing issue, except automated dependency updates as described in `CONTRIBUTING.md`. Follow Branch Names in `CONTRIBUTING.md` for contributor branch names.
+- Every PR must close an existing issue, except automated dependency updates and build or flaky-test fixes from authors with write access, as described in `CONTRIBUTING.md`. Follow Branch Names in `CONTRIBUTING.md` for contributor branch names.
 
 ## Before Creating a PR
 
+### Verify Contributor Access and Issue Acceptance
+
+Before pushing or creating a PR (including a draft), verify the author's access
+to the target repository, not their fork. For the authenticated `gh` user:
+
+```bash
+gh repo view OWNER/REPO --json nameWithOwner,viewerPermission
+gh issue view ISSUE_NUMBER --repo OWNER/REPO --json number,url,labels
+```
+
+Authors with verified `WRITE`, `MAINTAIN`, or `ADMIN` access may proceed without
+`state:accepted`; keep the issue link and note the missing label. Everyone else
+must link at least one target-repository issue and have `state:accepted` on each.
+Otherwise, preserve local work and report which issue needs acceptance. A direct
+request, roadmap placement, other labels, or vouch status does not bypass this gate.
+
+When acting for another author, verify their permissions. Resolve failed lookups
+before proceeding; retry sandbox network failures outside the sandbox before
+reporting an authentication problem. Vouch requirements still apply separately.
+
 ### Check Config Documentation
 
 If the branch changes gateway TOML parsing, `[openshell.gateway]` fields,
@@ -106,7 +126,7 @@ gh pr create --title "PR title" --body "PR description"
 
 ### Link to an Issue
 
-Every PR except an automated dependency update must close its own issue. Verify that the issue exists, remains open, and covers the PR scope. Automated dependency updates follow the exception in `CONTRIBUTING.md`. Use `Closes #<issue-number>` in the body so merge closes it:
+Every PR must close its own issue, except automated dependency updates and build or flaky-test fixes from authors with write access; both follow the exceptions in `CONTRIBUTING.md`. A PR without an issue describes the failure it fixes in the Related Issue section. Otherwise, verify that the issue exists, remains open, and covers the PR scope. Use `Closes #<issue-number>` in the body so merge closes it:
 
 ```bash
 gh pr create \
@@ -156,6 +176,9 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
 ## Changes
 <!-- Bullet list of key changes -->
 
+## Release Notes
+<!-- Optional: a few short, easy-to-read sentences about the user-facing change -->
+
 ## Testing
 <!-- What testing was done? -->
 - [ ] Checks appropriate to the affected code and behavior pass
@@ -168,6 +191,8 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
 ```
 
 Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.
+Keep the Release Notes section concise, with only a few easy-to-read sentences.
+Leave it empty when the summary already captures the user-facing change.
 
 ## Example PR (Complete)
 
@@ -189,6 +214,10 @@ Closes #456
 - Default page size is 100, max is 1,000
 - Structured responses include `next_page_token`
 
+## Release Notes
+
+Sandbox list results can now be paged through with `--page-size` and `--page-token`.
+
 ## Testing
 
 - [x] Relevant CLI format, lint, and unit checks pass
@@ -220,6 +249,9 @@ EOF
 
 The command outputs the PR URL and number.
 
+Rerun `PR Issue Acceptance` after linked issue labels change; it does not refresh
+automatically on issue-label events.
+
 **Display the URL using markdown link syntax** so it's easily clickable:
 
 ```

.agents/skills/fix-security-issue/SKILL.md

@@ -16,3 +16,5 @@ Use this skill after an authorized `review-security-issue` review identifies an
 5. Follow `create-github-pr` and use `Closes #<id>` for the reviewed issue. Every PR from this issue-backed remediation workflow must close its own issue; split multi-PR remediations into separate issues in the authorized security workflow. Keep the PR description appropriately scoped to its disclosure venue.
 
 Begin any fix comments with `> **🔧 security-fix-agent**`. Do not change human disposition or introduce `agent:*` workflow labels.
+
+For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

.agents/skills/helm-dev-environment/SKILL.md

@@ -57,6 +57,45 @@ Override with env vars before running `helm:k3s:create`:
   `mcr.microsoft.com/dotnet/aspire-dashboard:latest`)
 - `HELM_K3S_COLLECTOR_HEALTH_TIMEOUT` (default: `120` seconds)
 
+### Shared supervisor plumbing
+
+Set `gatewayConfig.openshell.drivers.kubernetes.supervisor_topology`
+using a values file (the table key is literally `openshell.drivers.kubernetes`):
+
+```yaml
+gatewayConfig:
+  openshell.drivers.kubernetes:
+    supervisor_topology: gateway
+```
+
+The gateway chart creates a single-replica shared supervisor Deployment,
+Service, NetworkPolicy, and an empty `<release>-supervisor-token` Secret in
+the release namespace, regardless of shared/managed/operator workspace mode.
+The gateway mints a supervisor token from its sandbox-JWT signing key, writes
+it into that Secret (the gateway Role may `get`/`patch` only that Secret), and
+renews it at half its lifetime; the supervisor mounts the Secret and presents
+the token on the private `openshell.supervisor.host.v1` assignment stream,
+which accepts nothing else. The topology requires gateway TLS and the signing
+key (`server.disableTls` is rejected; the gateway refuses to start without
+`gateway_jwt`). New sandbox generations run as sandbox instances in that
+process. The chart starts `--mode=shared`, sets `--gateway-endpoint` to the
+gateway gRPC URL, mounts the token at `--token-file`, and binds `--address`
+(5501) to a plain TCP health listener for the `tcpSocket` probes; nothing
+dials the supervisor but sandbox runtimes (5500) and the kubelet. Build the gateway, supervisor, and sandbox
+images from the same branch: all three must support the routed runtime
+connection and the assignment stream. `workspace` is reserved and rejected.
+Omit the field to disable it. `mise run
+e2e:kubernetes:shared-supervisor` runs the focused e2e
+(`ci/values-supervisor.yaml`). The task prepends that overlay to any
+colon-separated `OPENSHELL_E2E_KUBE_EXTRA_VALUES` list, so layer a
+workspace-mode overlay to cover managed namespaces:
+
+```bash
+OPENSHELL_E2E_KUBE_EXTRA_VALUES=deploy/helm/openshell/ci/values-workspace-managed.yaml \
+OPENSHELL_E2E_KUBE_IMAGE_PULL_SECRET=e2e-regcred \
+  mise run e2e:kubernetes:shared-supervisor
+```
+
 ### 2. Deploy OpenShell
 
 **Iterative dev** (rebuilds on file changes, recommended during active development):
@@ -81,7 +120,16 @@ The Skaffold flow builds distinct `gateway`, `sandbox`, and `supervisor` images
 and deploys the OpenShell Helm chart. The Kubernetes driver creates a
 capability-free workload Pod and a directly managed capability-free supervisor
 Pod. One namespace-wide NetworkPolicy denies direct egress from every OpenShell
-workload Pod. The
+workload Pod. New sandbox generations use `runtime-initiated` control: the sandbox
+runtime dials its supervisor through `os-supervisor-<id>`. The legacy
+`os-boundary-<id>` Service keeps selecting the workload for old gateways during
+rolling upgrades. New gateways create both Services and bind the control-mode
+annotation to its runtime generation. The driver adds a per-sandbox
+`os-control-<id>` NetworkPolicy for that path only. Existing running generations
+keep their connection until replaced; stop/start and gateway recovery that
+recreates both Pods upgrade legacy generations automatically. Use compatible
+gateway, supervisor, and sandbox runtime images together; there is no legacy
+rollout flag. The
 `pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
 generates gateway and CLI TLS secrets on first install. Supervisor Pods project
 only `ca.crt` and authenticate gateway RPCs with sandbox bearer tokens. User