kandev/docs/plans/kubernetes-docker-workloads/task-01-workspace-grants.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-workspace-grants	Explicit companion workspace grants	completed	1		plan.md	REQ-EXECUTORS-K8S-DOCKER-001 REQ-EXECUTORS-K8S-DOCKER-003	AC-EXECUTORS-K8S-DOCKER-001.1 AC-EXECUTORS-K8S-DOCKER-001.2 AC-EXECUTORS-K8S-DOCKER-001.3 AC-EXECUTORS-K8S-DOCKER-001.4 AC-EXECUTORS-K8S-DOCKER-003.2 AC-EXECUTORS-K8S-DOCKER-003.3	../../specs/executors/system-design/kubernetes-docker-workloads.md

Task 01: Explicit companion workspace grants

Summary

Allow an explicitly named ordinary sidecar to share Kandev's workspace through the existing raw template. Keep runtime/auth mounts private in the composed spec, verify admitted grants against the requested template, and preserve snapshot and exact-resource lifecycle behavior.

In scope

• Use TDD for the template, composition and both-direction admission checks described in the system design; retain the main-container contract.
• Cover RO/RW, all three storage modes, unchanged profiles, extra sidecars, malicious admission and lost-Pod replacement after a profile edit.
• Keep UID, nonce, ownership and existing-claim cleanup regressions passing.
• Reconcile the foundation, ownership ADR and public executor template contract. Clarify README executor support and replace obsolete docs/k8s.md bulk-deploy advice with the current guide. Do not imply the full recipe is shipped yet.

Out of scope

Image builds, live cluster changes, new API/UI/profile fields, automatic mounts, privilege grants and broad refactors of unrelated executor lifecycle code.

Acceptance

1. An explicit ordinary sidecar mount survives composition; ambiguous/redirected grants and access to reserved runtime/auth material fail before API writes.
2. Admission cannot add, remove, transfer or alter a requested grant; known neutral defaults and unrelated compatible additions remain supported.
3. Snapshot replacement preserves the original grant and claim identity. Existing managed/existing-claim cleanup and nonce checks remain unchanged.

Verification

From the repository root, after the red/green implementation cycle:

(cd apps/backend && GOMAXPROCS=2 go test -p 1 ./internal/agent/kubernetes ./internal/agent/runtime/lifecycle -count=1)
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check

Add workspace_grant_test.go with TestWorkspaceGrantTemplateValidation, TestWorkspaceGrantComposition, TestWorkspaceGrantAdmission; add executor_kubernetes_workspace_grant_test.go with TestKubernetesWorkspaceGrantUsesLaunchSnapshot. Use assertions on resulting mounts/files/inventory and rejection outcomes, not internal call counts. Task 03 owns API-server defaulting and actual Docker bind evidence.

Files likely touched

• apps/backend/internal/agent/kubernetes/{template,compose,admission}.go
• apps/backend/internal/agent/kubernetes/workspace_grant_test.go (new)
• apps/backend/internal/agent/runtime/lifecycle/executor_kubernetes_workspace_grant_test.go (new)
• apps/backend/internal/agent/runtime/lifecycle/executor_kubernetes_reconnect.go, only if tests expose a required adjustment
• docs/public/k8s.md, docs/k8s.md, README.md
• docs/specs/kubernetes-executor/spec.md
• docs/decisions/2026-08-24-kubernetes-executor-resource-ownership.md

Dependencies

None. Start only after the user requests implementation of this package.

Risks

Comparing only admitted grants misses a removed recipient; comparing container positions permits transfer. Overly broad default normalization could hide a changed access mode. Avoid changing existing main-container validation.

Parallelism

sequential

Inputs

• Requirements, requirement 001.
• System design, Workspace grant and admission; Lifecycle and evidence.
• Existing template_validation_test.go, compose_test.go, admission_test.go, executor_kubernetes_test.go and executor_kubernetes_restart_test.go patterns.

Results

Implemented explicit RO/RW companion grants with exact mount shape, duplicate identity rejection and admission checks in both directions. Composition retains the requested grant without changing the managed volume or main container. Snapshot replacement tests cover retained grants and prevent profile edits from adding grants to recorded workloads. Existing ownership and cleanup checks pass.

Validation:

• Red: TestWorkspaceGrant* rejected valid grants and exposed accepted grant/recipient removal.
• Green: GOMAXPROCS=2 go test -p 1 ./internal/agent/kubernetes ./internal/agent/runtime/lifecycle -count=1 passed.
• python3 scripts/list-docs.py validate: 267 decisions and 870 specifications.
• python3 scripts/lint-spec-files.py --all: passed.
• node --test scripts/validate-public-docs.test.mjs: passed.
• git diff --check: passed.

Real API defaulting and Docker lifecycle evidence remain assigned to task 03. No neutral mount default normalization has been introduced.

Review regression: a writable PVC alias at /cache initially bypassed a read-only workspace grant in both managed-PVC and existing-claim modes. Composition and admission now reject those aliases while allowing unrelated PVC mounts. TestWorkspaceGrantAdmissionRejectsClaimAlias failed before the fix; the full Kubernetes package passed afterward with GOMAXPROCS=2 go test -p 1 ./internal/agent/kubernetes -count=1 -timeout=90s (0.281s test execution).