docs(osep): propose secure PVC subpath initialization

[cwj2001]

Problem

Kubernetes requires a volumeMount.subPath directory to exist before the Pod starts. A referenced PVC can be bound while a new task- or sandbox-specific subdirectory is absent, causing mount/startup failure. Creating that directory outside OpenSandbox requires separate credentials or a helper workload and cannot preserve a final read-only mount cleanly.

Proposal

• Adds draft OSEP-0021 for opt-in, secure initialization of a missing Kubernetes PVC Volume.subPath.
• Adds one default-off, mount-scoped field: Volume.createSubPathIfMissing.
• Clarifies OSEP-0003: ordinary missing-subPath behavior is runtime-dependent; secure creation is explicit opt-in.

The initial boundary is Linux Kubernetes, an existing PVC, and non-Pool creation. The final mount remains read-only or read-write as requested. A server-owned, non-privileged init container performs descriptor-relative, no-follow creation; callers cannot supply an image, command, UID/GID/mode, or PodSpec fragment.

Relationship to OSEP-0020 / #1573

This is an independent proposal, not a modification or supersession claim. It deliberately uses a mount-scoped field, supports a read-only final mount, and makes old/mixed-version rollout fail closed through a capability-aware create path.

Review requested

Please review these design decisions before implementation:

1. Is mount-scoped Volume.createSubPathIfMissing the right minimal public contract?
2. Is a distinct capability-aware create route the right way to prevent older or mixed server replicas from silently ignoring the opt-in?
3. Is the initial Kubernetes/Linux/PVC/non-Pool boundary appropriate?
4. Are the proposed stable error categories and remaining HTTP-status mapping suitable for the Lifecycle API?

Compatibility and non-goals

• Existing requests are unchanged; the option is additive and default-off.
• Pool, Docker, and other backends fail explicitly rather than falling back.
• PVC provisioning/deletion, permission repair, generic lifecycle hooks, and direct client Kubernetes access are out of scope.
• This PR intentionally contains no implementation, schema, SDK, or generated-code changes.

Validation

• git diff --check

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f947602ade

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reconcile the extra route with the sole-option requirement

The requirement says this boolean is the only public option introduced, but the normative rollout contract later adds both /v1/sandboxes/capability-aware-create and OpenSandbox-Required-Capability. Implementers therefore cannot satisfy both sections: either they expand the public protocol contrary to this requirement or omit the mechanism required for mixed-version safety. Define the route and header as part of the public interface here, or redesign negotiation so the field truly is the only addition.

AGENTS.md reference: AGENTS.md:L117-L120

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Specify the retryability mapping before implementation

When initialization fails, permanent permission/policy errors and transient storage/I/O errors all use VOLUME_SUBPATH_INITIALIZATION_FAILED, so clients can distinguish them only through the HTTP status; however, this section makes retryability mandatory while deferring that status mapping to a later decision. Consequently an implementation cannot satisfy requirement 9 or the test plan's “correct retryability” assertion without inventing protocol behavior that other implementations may choose differently. Make the stable 4xx/5xx mapping part of this contract.

AGENTS.md reference: AGENTS.md:L117-L120

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Add OSEP-0021 to the proposal index

Adding this proposal without updating oseps/README.md leaves the directory's stated “complete list” ending at OSEP-0019, even though drafts are included there. As a result, readers using the repository's OSEP entry point cannot discover OSEP-0021; add its title, draft status, and update date to that table.

Useful? React with 👍 / 👎.