feat(runtime): validate workspace reuse without mutation

[skevetter]

External runtimes currently cannot validate whether an existing workspace still matches its creation-time ownership or mount policy. Add optional API 1.2 ReusePreflight, carrying the workspace ID and resolved developer identity. The RPC is read-only: incompatible reuse returns structured FailedPrecondition with explicit recreation guidance and must leave the workspace intact.

The fake runtime persists the creation identity and exercises successful reuse, incompatible and invalid requests, absence, cancellation, and unchanged state through the real plugin transport. Capability validation rejects advertising the addition below API 1.2; the conformance suite checks compatible reuse without mutation. This is the SDK prerequisite for the shared MicroSandbox parity baseline in devsy-org/devsy#1424.

Validation: all race tests, vet, strict lint, formatting, protobuf checks, and prek passed. Repeated binding generation produced identical hashes. Local CodeRabbit reviewed all 12 changed files with zero findings.

Summary by CodeRabbit

• New Features
  • API 1.2 supports read-only validation of an existing workspace before reuse. Compatible workspaces can proceed; incompatible creation-time contracts return a failure with recreation guidance, leaving the workspace unchanged.
  • Runtimes can advertise reuse validation support. Hosts skip the check when it is not advertised.
• Documentation
  • Added guidance on reuse validation, error handling, and the distinction between reuse checks and explicit recreation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 75f7b082-ac38-40cb-a0f7-fa86b519a7a6

📥 Commits

Reviewing files that changed from the base of the PR and between 3759ad6 and 3b582ab.

⛔ Files ignored due to path filters (2)

• runtimev1/runtime.pb.go is excluded by !**/*.pb.go
• runtimev1/runtime_grpc.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (10)

• README.md
• conformance/fake/fake.go
• conformance/fake/lifecycle.go
• conformance/fake/reuse.go
• conformance/fake/reuse_test.go
• conformance/reuse.go
• conformance/suite.go
• proto/devsy/runtime/v1/runtime.proto
• runtimev1/validate.go
• runtimev1/validate_test.go

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The API adds optional reuse preflight for API 1.2 runtimes. The fake runtime compares a workspace’s saved remote-user identity with the requested identity. Conformance checks cover successful validation, cancellation, and workspace state preservation.

Changes

Reuse Preflight

Layer / File(s)	Summary
API contract and version validation proto/devsy/runtime/v1/runtime.proto, runtimev1/validate.go, runtimev1/validate_test.go, README.md	The API adds the ReusePreflight RPC, its capability and message types, and validation that requires API 1.2 when the capability is enabled. The README describes the reuse-preflight contract.
Fake runtime identity validation conformance/fake/fake.go, conformance/fake/lifecycle.go, conformance/fake/reuse.go	The fake runtime advertises reuse preflight and saves the effective remote-user identity on new workspaces. Its preflight method loads the workspace and returns FailedPrecondition when the saved identity differs.
Conformance checks conformance/reuse.go, conformance/suite.go, conformance/fake/reuse_test.go	The suite registers reuse-preflight checks when the runtime advertises support. Tests cover matching and differing identities, missing workspaces, cancellation, and workspace state preservation.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Host
  participant Driver
  participant Workspace
  Host->>Driver: ReusePreflight(workspace_id, remote_user)
  Driver->>Workspace: Load workspace and saved remote-user label
  Workspace-->>Driver: Workspace identity
  Driver-->>Host: Success or FailedPrecondition

Loading

Merge Risk: ⚪ Minimal · up to 3b582

No actionable issue remains in the reuse-preflight change; it is ready to merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3b582

The new check preserves workspace state and requires explicit recreation when identities differ. No introduced security defect was identified in the inspected implementation. Risk is limited, but adoption by production hosts and runtimes remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — In the fake implementation, caller-controlled workspace IDs select records within the configured state directory through SHA-256-derived filenames. The new endpoint reads those records and returns compatibility status; it does not execute commands, modify mounts, or invoke lifecycle mutation.

Trust Boundaries and Controls

• observed — The generated RPC handler invokes the configured unary interceptor rather than bypassing it. Inside the fake driver, empty identity is rejected, caller-supplied creation labels cannot override the saved identity, and mismatches fail without mutation. These controls enforce compatibility, not tenant authorization.

Resilience and Maintainability Implications

• inferred — Preflight failures and interrupted or repeated calls cannot strand a partially updated workspace in this implementation because preflight performs no writes. Same-Driver operations are serialized, but a successful check is only a snapshot and does not reserve the workspace for subsequent reuse. The fixture explicitly requires one active owner per state directory.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 8 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding runtime validation for workspace reuse without mutating the workspace.

Full details: Docstring Coverage

Explanation

Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 8 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[skevetter]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

[Critical risk] Adds new gRPC API endpoint and updates protocol contract.

The PR appears safe to merge; no actionable issues were found.

What we checked:

• Older runtimes still work: The new version check applies only when a runtime advertises ReusePreflight. The conformance check skips runtimes that do not advertise it.

Summary

Adds optional API 1.2 ReusePreflight to check an existing workspace without changing it.

• Adds the request, response, capability, and generated RPC bindings.
• The fake saves the creation identity and returns structured errors for incompatible reuse.
• Adds transport tests and a capability-gated conformance check.
• Rejects advertising the capability below API 1.2.

Diagram

sequenceDiagram
  participant Host
  participant Runtime
  participant Workspace
  Host->>Runtime: ReusePreflight(workspace_id, remote_user)
  Runtime->>Workspace: Read saved creation identity
  Workspace-->>Runtime: Saved identity
  alt Identity matches
    Runtime-->>Host: Success
  else Identity differs
    Runtime-->>Host: FailedPrecondition with recreation guidance
  end
  Note over Runtime,Workspace: Workspace remains unchanged

Loading

_{Reviews (1) · Last reviewed commit: "feat(runtime): validate workspace reuse ..." · Reviewed by Greptile}

[skevetter]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[skevetter]

Final review gates for 3b582ab3acf98950d78fb92c3361d9176b7b2586: all nine applicable CI jobs passed, Greptile completed at 5/5, and full CodeRabbit completed with no actionable findings. Local race tests, vet, strict lint, protobuf checks, deterministic generation, pre-commit, and the complete local CodeRabbit diff review passed. No review threads remain; GitHub verifies the signed commit.

CodeRabbit's docstring percentage warning does not identify a missing exported contract: the RPC, capability, request field, exported handler, and README document the behavior. Unexported helpers and tests remain self-documenting under AGENTS.md. Its Buf tool could not access GitHub through its proxy; the dedicated generated-bindings CI job and local Buf checks both passed, so that tool failure is independently covered.