Sync upstream v1 APIs and sandbox lifecycle fixes

.agents/skills/review-crds/SKILL.md

@@ -29,7 +29,7 @@ Your output should be a list of violations conforming to the following JSON form
 
 ## Hints
 
-- All CRDs are defined in `pkg/api/v1alpha1`.
+- All CRDs are defined in `api/infra/k8s/ate/v1`.
 
 ## References
 - [Kubernetes API Conventions](references/api-conventions.md)

.agents/skills/sync-upstream-main/SKILL.md

@@ -8,7 +8,10 @@ description: Merge agent-substrate/substrate upstream/main into the kagent-dev/s
 The fork uses merge-based synchronization. Start a branch from current
 `origin/main`, merge `upstream/main`, and submit that branch to `origin/main`.
 Preserve upstream ancestry so later synchronizations contain only new changes.
-Do not replay fork commits, squash upstream history, force-push, or push to main.
+Each sync PR must contain exactly one sync merge commit on top of `origin/main`,
+with all conflict resolutions, integration fixes, and skill updates folded into
+it. Preserve the incoming upstream commits; do not squash their history.
+Do not replay fork commits or push to main.
 Creating a PR requires an explicit request or approval; approval to create it
 does not authorize merging it.
 
@@ -31,9 +34,9 @@ does not authorize merging it.
    render check excludes preserved manifests, so passing it alone does not
    establish parity. Keep `charts/substrate-crds/templates` synchronized with
    generated CRDs.
-6. Commit the merge with `git commit -s`. Keep any additional fixes or workflow
-   documentation in focused signed-off commits. Omit issue and PR references
-   from commit messages.
+6. Commit the merge with `git commit -s`. Fold later fixes and documentation
+   into that same commit with `git commit --amend -s`; do not leave follow-up
+   commits on the sync branch. Omit issue and PR references from commit messages.
 
 ## Validate and investigate failures
 
@@ -56,9 +59,18 @@ that the failure is resolved. Report test counts and skips when relevant.
 
 ## Publish the PR
 
-Before publishing, fetch both refs again and incorporate any new main changes
-with merges. Verify that both recorded main tips are ancestors of the branch,
-the diff is intentional, and the worktree is clean. Push only the sync branch.
+Before publishing, fetch both refs again. If either main tip changed, rebuild
+the single merge from the latest `origin/main` and `upstream/main`, reapplying
+and checking the integration fixes. Do not stack additional merge commits.
+Verify that `git rev-list --first-parent --count origin/main..HEAD` returns `1`
+and HEAD has exactly two parents: `origin/main` first, `upstream/main` second.
+Check that the diff is intentional and the worktree is clean.
+
+Push only the sync branch. When amending an already published merge, verify
+the remote still matches the last observed PR head and push with an explicit
+`--force-with-lease=refs/heads/<sync-branch>:<observed-sha>`. Never force-push
+unguarded or overwrite another contributor's changes. Verify that folding
+commits preserved the intended tree, and report checks for the new commit SHA.
 
 When PR creation is authorized, open it against `kagent-dev/substrate:main`.
 Describe the upstream SHA, material changes, conflict resolutions, required

.agents/skills/triage-issues/SKILL.md

@@ -48,7 +48,7 @@ Apply all areas that are touched. Most issues need one or two; a few need more.
 
 | Label | Scope |
 |---|---|
-| `area/api` | User-facing Substrate API (`pkg/proto/ateapipb/`, proto definitions, API semantics, versioning) |
+| `area/api` | User-facing Substrate API (`api/ateapi/v1/`, proto definitions, API semantics, versioning) |
 | `area/api-machinery` | API server internals: RPC handlers, storage layer, syncer, controllers (`cmd/ateapi/`, `cmd/atecontroller/`) |
 | `area/network` | Networking: atenet-router, Envoy, ext_proc, DNS, xDS, ingress (`cmd/atenet/`) |
 | `area/node` | Node agent and worker lifecycle: atelet, sandbox launch, OCI, cgroups (`cmd/atelet/`) |

.github/SECURITY.md

@@ -6,26 +6,31 @@
 vulnerabilities.**
 
 Use [GitHub Private Vulnerability Reporting](https://github.com/agent-substrate/substrate/security/advisories/new)
-to report security vulnerabilities privately. Note that this project is not
-eligible for the
-[Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
+to report security vulnerabilities privately. Verify that there is no existing
+open GitHub issue covering the problem before creating a report.
 
-Please include:
+Please ensure your report is concise and clearly articulates the bug. It should
+include:
 
+- How the issue is reachable and exploitable by untrusted code running inside an
+  actor sandbox. Or a statement that it isn't exploitable from inside an actor
+  sandbox.
+- The security impact resulting from exploitation of the bug.
 - The affected component and version or commit SHA.
-- Steps to reproduce, or a proof of concept.
-- The potential impact, and mitigations if known.
+- Detailed steps to fully reproduce, or a proof of concept.
+- Mitigations if known.
 
 ### When to report
 
 - You found a potential security vulnerability in Agent Substrate.
-- You are unsure whether a security issue affects Agent Substrate.
 - You found a vulnerability in a project Agent Substrate depends on and it
   is exploitable through Agent Substrate. If that project has its own
   disclosure process, please report it there as well.
 
 ### When not to report
 
+- Theoretical bugs from static analysis without demonstration of an exploitable
+  security issue.
 - You need help securing or tuning a deployment (open a regular issue or
   discussion).
 - The issue is not security related.
@@ -76,8 +81,7 @@ from most to least severe:
 - Sample applications under `demos/` and load-testing harnesses under
   `benchmarking/`.
 - Documented scope boundaries and future capabilities listed in
-  [docs/security.md](../docs/security.md) and
-  [docs/roadmap.md](../docs/roadmap.md) at the time of your report. If you are
+  [docs/security.md](../docs/security.md) at the time of your report. If you are
   unsure whether a finding is covered by a documented limitation, report it
   privately anyway and let a maintainer make the call.
 

.golangci-kal.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # Config for kube-api-linter (github.com/kubernetes-sigs/kube-api-linter),
-# run by hack/verify/kube-api-linter.sh against the API types in pkg/api/.
+# run by hack/verify/kube-api-linter.sh against the API types in api/infra/.
 # It is a separate file from .golangci.yaml because the kubeapilinter module
 # plugin only exists in the golangci-lint-kube-api-linter binary, not in the
 # regular golangci-lint one.
@@ -75,34 +75,34 @@ linters:
     rules:
       # Pre-existing findings from rules that require Go API changes
       # (pointer fields, omitempty/omitzero tags, map-to-list refactors)
-      # on the existing v1alpha1 types. Each rule names the fields it
+      # on the existing ate/v1 types. Each rule names the fields it
       # excuses, so a field added to one of these types is still checked.
       # Fixing these on the existing types is tracked in issue #207.
-      - path: 'pkg/api/v1alpha1/sandboxconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/sandboxconfig_types\.go'
         text: '^requiredfields: .*\bAssetFile\.(SHA256|URL)\b'
-      - path: 'pkg/api/v1alpha1/sandboxconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/sandboxconfig_types\.go'
         text: '^(optionalfields|requiredfields): .*\bSandboxConfigSpec\.SandboxClass\b'
-      - path: 'pkg/api/v1alpha1/sandboxconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/sandboxconfig_types\.go'
         text: '^(nomaps|optionalfields): .*\bSandboxVersionConfig\.Assets\b'
-      - path: 'pkg/api/v1alpha1/sandboxconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/sandboxconfig_types\.go'
         text: '^(nonpointerstructs|requiredfields): .*\bSandboxConfig\.Spec\b'
-      - path: 'pkg/api/v1alpha1/csidriverconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/csidriverconfig_types\.go'
         text: '^requiredfields: .*\bCSIDriverConfigSpec\.(ControllerEndpoint|DriverName)\b'
-      - path: 'pkg/api/v1alpha1/csidriverconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/csidriverconfig_types\.go'
         text: '^optionalfields: .*\bCSIDriverConfigSpec\.NodeSocketOverride\b'
-      - path: 'pkg/api/v1alpha1/csidriverconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/csidriverconfig_types\.go'
         text: '^requiredfields: .*\bCSIDriverTLSConfig\.Enabled\b'
-      - path: 'pkg/api/v1alpha1/csidriverconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/csidriverconfig_types\.go'
         text: '^optionalfields: .*\bCSIDriverTLSConfig\.(ServerName|UsePodIdentity)\b'
-      - path: 'pkg/api/v1alpha1/csidriverconfig_types\.go'
+      - path: 'api/infra/k8s/ate/v1/csidriverconfig_types\.go'
         text: '^(nonpointerstructs|requiredfields): .*\bCSIDriverConfig\.Spec\b'
-      - path: 'pkg/api/v1alpha1/workerpool_types\.go'
+      - path: 'api/infra/k8s/ate/v1/workerpool_types\.go'
         text: '^optionalfields: .*\bWorkerPoolPodTemplate\.PriorityClassName\b'
-      - path: 'pkg/api/v1alpha1/workerpool_types\.go'
+      - path: 'api/infra/k8s/ate/v1/workerpool_types\.go'
         text: '^(optionalfields|requiredfields): .*\bWorkerPoolSpec\.(Replicas|WorkerImage)\b'
-      - path: 'pkg/api/v1alpha1/workerpool_types\.go'
+      - path: 'api/infra/k8s/ate/v1/workerpool_types\.go'
         text: '^optionalfields: .*\bWorkerPoolStatus\.(ReadyReplicas|Replicas|Selector)\b'
-      - path: 'pkg/api/v1alpha1/workerpool_types\.go'
+      - path: 'api/infra/k8s/ate/v1/workerpool_types\.go'
         text: '^(optionalfields|requiredfields): .*\bWorkerPool\.(Spec|Status)\b'
 
 issues:

AGENTS.md

@@ -25,6 +25,7 @@
 ### Scope
 
 - Keep each PR to one change. Send refactors, cleanups and follow-ups as separate PRs. For how to batch small fixes, see "Sizing PRs for review" in `CONTRIBUTING.md`.
+- Split a PR into commits that are easy to review in order. PRs are squash-merged, so only the branch `HEAD` needs to build and pass tests.
 - Follow "Contribution process" in `CONTRIBUTING.md`: open an issue first for anything beyond a small fix, and search open PRs and issues before you start.
 - Start the PR description with why the change is needed, or link the issue. Only write "Fixes #N" if the PR fully fixes it, and keep the description in sync with the final diff.
 - Rebase onto upstream `main` before opening a PR, and don't merge main into your branch. This file may have changed there. Follow that version.
@@ -68,6 +69,7 @@ See `hack/install-ate.sh` and `tools/setup-gcp` for provisioning and deploying c
 ## Repository Layout
 
 ```
+api/          # Public APIs: protos and CRD types, one directory per API and version
 cmd/          # One subdirectory per binary (ateapi, atelet, atenet, …)
 internal/     # Shared packages, internal to this module only
 pkg/          # Shared packages intended for external import
@@ -86,11 +88,12 @@ tools/        # Standalone Go tools (go run ./tools/<name>) for Dev/CI
 | Only used by one binary | `cmd/<binary>/internal/<pkg>` |
 | Shared across binaries, not for external import | `internal/<pkg>` |
 | Public API for external consumers | `pkg/<pkg>` |
-| Public proto (control-plane gRPC API) | `pkg/proto/<name>` |
+| Public gRPC API | `api/<name>/<version>` |
+| Kubernetes CRD types | `api/infra/k8s/<group>/<version>` |
 | Internal proto (atelet / ateworker) | `internal/proto/<name>` |
 | Dev/CI scripts | `hack/` |
 | Standalone Go dev/CI tools | `tools/<name>` with its own `go.mod` |
-| Self-contained plugin that nothing in the repo depends on | `internal/plugins/<name>` with its own `go.mod`, importing only `pkg/`; see `internal/plugins/README.md` |
+| Self-contained plugin that nothing in the repo depends on | `internal/plugins/<name>` with its own `go.mod`, importing only `api/` and `pkg/`; see `internal/plugins/README.md` |
 
 See `docs/dev/code-layout.md` for the full rationale and per-directory details.
 

CONTRIBUTING.md

@@ -70,7 +70,8 @@ down, small PRs get merged.
 * **Large PRs**: split huge changes into a series of smaller PRs, each a
   logically distinct feature. When the intermediate steps are not useful
   on their own, keep the change as one PR split into commits at logical
-  break points, and preserve those commits on merge.
+  break points for review. PRs are squash-merged, so only the branch
+  `HEAD` needs to build and pass tests.
 * **Small and bulk PRs**: if you find a typo, review the whole file and
   fix everything in one pass rather than sending the single edit. Group
   related typo, doc, and single-line cleanup fixes into one PR rather

README.md

@@ -11,7 +11,7 @@
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-[Quickstart](#quickstart-development) · [Security](docs/security.md) · [Architecture](docs/architecture.md) · [Roadmap](docs/roadmap.md) · [Contributing](CONTRIBUTING.md)
+[Quickstart](#quickstart-development) · [Security](docs/security.md) · [Architecture](docs/architecture.md) · [Contributing](CONTRIBUTING.md)
 
 </div>
 
@@ -260,7 +260,6 @@ We provide several sample applications demonstrating Agent Substrate's capabilit
 * [Upgrade Runbook](docs/upgrade.md): Upgrade a running install to a newer supported release, and roll back if needed.
 * [Node Storage](docs/node-storage.md): How to give snapshot I/O its own disk.
 * [Security Guide](docs/security.md): Security overview, security principles, and threat modeling.
-* [Roadmap](docs/roadmap.md): Current limitations and what is planned next.
 * [Benchmarking Guide](benchmarking/README.md): Locust-based load tests, monitoring stack, and the orchestrated benchmark harness.
 
 ## Tour

pkg/proto/ateapipb/AGENTS.md → api/ateapi/v1/AGENTS.md

@@ -1,4 +1,4 @@
-# ateapipb
+# ateapi
 
 `ateapi.proto` defines Substrate's public API.