feat(runtime): negotiate recreation on RunImage

[skevetter]

ON_RUN lets a compatible host leave an existing workspace intact until RunImage validates its effective replacement configuration. API 1.3 adds host opt-in during discovery and an explicit per-request replacement permission; old hosts retain DELETE behavior and existing providers retain their legacy modes. Discovery never grants replacement permission, including when each RPC launches a fresh process.

The optional fake-runtime profile and reusable conformance cases cover running and stopped targets, unauthorized duplicates, invalid authorized requests (including nonempty-image requests with unsupported workspace and additional mount types), valid replacement and process restarts. These tests establish the protocol contract; actual MicroSandbox replacement safety remains a separate provider and host integration gate.

Validation: full uncached SDK race suite, vet, strict lint, all nine pre-commit hooks, module verification, protobuf lint/format and two identical pinned binding generations passed. Fresh full committed local CodeRabbit reviewed all 14 files with zero findings. The follow-up conformance race suite, vet, strict lint and all nine hooks passed. All ten applicable final-head CI jobs passed, including three-platform race/spawn coverage. Fresh Greptile scored 5/5. The completed full remote CodeRabbit reviewed all 13 selected files with no actionable findings; its generated-binding exclusion is covered locally and by generation CI. The generic private-helper docstring warning and unavailable remote Buf fetch were independently dispositioned; pinned local Buf breaking checks against the exact old schema passed. Production adoption remains a separate integration gate.

[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: f32e60a3-a975-4588-84af-004e5fc14f84

---

---

📥 Commits

Reviewing files that changed from the base of the PR and between df5943d and d4d2d46.

---

---

⛔ Files ignored due to path filters (1)

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

---

---

📒 Files selected for processing (13)

• README.md
• cmd/devsy-fake-runtime/main.go
• conformance/fake/fake.go
• conformance/fake/integration_test.go
• conformance/fake/lifecycle.go
• conformance/fake/recreate_test.go
• conformance/fake/recreate_wire_test.go
• conformance/fake/suite_test.go
• conformance/recreate.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

Walkthrough

The change adds API 1.3 recreate-on-run negotiation and per-request replacement authorization. It updates API validation, adds an opt-in recreation profile to the fake runtime, and extends conformance checks for discovery, rejected requests, and successful replacement.

Changes

API 1.3 Recreate-on-Run

Layer / File(s)	Summary
Protocol and API version contract proto/devsy/runtime/v1/runtime.proto, runtimev1/validate.go, runtimev1/validate_test.go, README.md	Discovery requests gain a recreation capability field, and run requests gain an authorization field. Validation accepts ON_RUN from API minor 3. Tests cover version validation and protobuf encoding.
Fake runtime negotiation and replacement cmd/devsy-fake-runtime/main.go, conformance/fake/fake.go, conformance/fake/lifecycle.go, conformance/fake/*_test.go, conformance/fake/suite_test.go, README.md	The fake runtime gains an optional recreation profile. It advertises ON_RUN only for opted-in discovery requests and permits replacement only when the profile and run request authorize it. Tests cover negotiation, rejection safety, persistence, and legacy wire behavior.
Reusable recreation conformance conformance/recreate.go, conformance/suite.go, README.md	The conformance suite checks capability discovery, authorized replacement, rejected requests, and workspace preservation. The fake-runtime conformance setup runs both default and recreation profiles.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Host
  participant Runtime
  participant WorkspaceState
  Host->>Runtime: InfoRequest with supports_recreate_on_run
  Runtime-->>Host: Info response with RECREATE_MODE_ON_RUN
  Host->>Runtime: RunImageRequest with allow_recreate=true
  Runtime->>Runtime: Validate effective configuration
  Runtime->>WorkspaceState: Load existing workspace
  Runtime->>WorkspaceState: Save created container

Loading

---

---

Merge Risk: ⚪ Minimal · up to d4d2d

No concrete issue requiring a change before merge is established; complete the normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to d4d2d

The replacement contract has explicit permission, validation ordering, and legacy compatibility safeguards. Production adoption still needs independent verification of caller authorization and replacement failure recovery.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated replacement sink is a fake-runtime record selected by the request's workspace ID. Repeated accepted requests could affect multiple accessible records in the configured state directory. Production tenant, asset, credential, and environment exposure cannot be determined from this fixture boundary.

Security Findings and Attack Paths

• observed — The fake's absence of caller-ownership enforcement predates this PR: its Delete operation already removed a caller-selected workspace record after workspace validation, without an ownership lookup. This is counterevidence to treating the new permission bit as newly granting broad destructive authority in the fixture; it does not establish production authorization safety.

Trust Boundaries and Controls

• observed — The fixture requires enabled replacement capability and explicit current-request permission before overwriting an existing record. Checked validation precedes mutation, while discovery changes only the advertised mode. These controls prevent accidental authorization inheritance; authentication and workspace ownership remain separate production responsibilities.

Resilience and Maintainability Implications

• inferred — The fake serializes operations within one driver and saves through temporary-file rename, limiting visible state to complete records. A replacement may nevertheless be committed before its response is received. Sequential restart checks do not establish cross-process serialization, repeated-authorized-request idempotency, crash-point durability, or production recovery guarantees.

Hardening Proposals

• proposed — Before enabling a production ON_RUN provider, require integration evidence for authenticated ownership, complete effective-configuration validation before destruction, concurrent replacement serialization, retry and cancellation behavior, and recovery from materialization or launch failure. Treat this as an adoption gate, not certification supplied by the fake-runtime suite.

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding recreation negotiation for RunImage in the runtime API.

---

Full details: Docstring Coverage

Explanation

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

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

---

---

---

• Autofix · 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

[High impact] The PR appears safe to merge, with no actionable issues found in the latest changes.

Summary

Adds API 1.3 recreation on RunImage, with host opt-in during discovery and separate permission on each request.

• Hosts can negotiate ON_RUN without granting automatic replacement.
• The fake runtime replaces a workspace only for authorized ON_RUN calls.
• The conformance suite checks ON_RUN replacement for running and stopped workspaces.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Info request] --> B{Host opts in?}
  B -->|Yes, runtime supports it| C[Advertise ON_RUN]
  B -->|No, runtime supports ON_RUN| D[Advertise DELETE]
  E[RunImage request] --> F[Validate full configuration]
  F -->|Invalid| G[Reject without changing workspace]
  F -->|Valid| H{Workspace exists?}
  H -->|No| I[Create workspace]
  H -->|Yes| J{Replacement allowed?}
  J -->|No| K[Return AlreadyExists]
  J -->|Yes, ON_RUN supported| L[Replace workspace]

Loading

_{Reviews (2) · Last reviewed commit: "test(conformance): preserve state after ..." · Reviewed by Greptile}

[skevetter]

@greptileai review

[skevetter]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[skevetter]

The full current-head review covers all 13 selected source/docs/test files at d4d2d46; the organization filter excludes runtimev1/runtime.pb.go. The generated binding was covered by the full 14-file committed local review, two identical pinned generations, and passing generated-bindings CI. No actionable inline issues remain.

The docstring percentage is a generic coverage warning over primarily private fixture/conformance helpers. The wire fields, compatibility boundary and authorization/validation ordering are documented in the schema and README; adding implementation-restating comments to satisfy a percentage would not improve this contract. No code change is warranted.

CodeRabbit's Buf compatibility tool could not fetch old schema blob bd59cab3279f10effb9a5a8d4162ca47ca67bf24 through its unavailable proxy. That blob exactly matches the schema on current origin/main df5943d. Independently running pinned Buf 1.73.0 breaking checks against an exported copy of that exact base passed; CI Buf lint/format and generated bindings also passed. This dispositions the tool availability warning with actual compatibility evidence.

The production-adoption caveat is retained: this SDK protocol/fake/conformance change does not establish production caller ownership, concurrency, retries/cancellation or later materialization/launch recovery. Those are separate provider/host integration and actual-VM campaign gates; the contract does not promise rollback of later launch failures.