feat(driver): host external runtime lifecycle operations

[skevetter]

External runtime declarations can now be exercised through an internal process host. The host verifies the prepared runtime before each operation, launches it through the SDK supervisor embedded as a hidden Devsy helper, negotiates Info, and performs preflight, Find, TargetArchitecture, RunImage, Start, Stop, and Delete calls. Each call closes and reaps its owned session; caller cancellation also interrupts handshake, and constructor Info negotiation has a bounded timeout.

Found container state is validated and converted to Devsy details, including mapping protocol stopped to Devsy exited. RunImage rejects unsupported mounts before RPC. Structured failures preserve canonical status, runtime category, and retryability while redacting returned messages and backend diagnostics. Runtime environment inheritance is retained, transport metadata has precedence, and workspace environment values participate in per-request redaction. Relative executable declarations additionally reject symlink escapes; these checks remain a trusted-code integrity check, not an atomic execution guarantee or a sandbox.

This is workstream C2. Exec, Logs, conversion from Devsy RunOptions into protocol intent, and drivercreate/workspace registration remain subsequent stages. No image backend, custom-driver environment helper, or built-in runtime behavior is changed. Per-operation ownership remains the initial implementation; real-runtime compatibility and measurements against a full workspace launch remain gates before cutover or pooling.

Import Runtime SDK v1.2.0 and refresh generated dependency notices, including version drift already present on main. The project owner selected MPL-2.0 for the SDK; merged SDK PR #21 adds its license file. An explicit detector entry covers the published v1.2.0 archive, which lacks that file.

Validation:

• Race-enabled tests for external host, provider resolver, and internal helper registration; production New and CLI-helper launch, real plugin restarts, cancellation/reaping, handshake/Info timeouts, malformed/incompatible Info, environment forwarding, symlink rejection, and secret canaries.
• Linux and Windows host-test cross-compilation; Go vet.
• CLI CI-parity lint and applicable prek hooks.
• Documentation production build (112 pages) and link validation.
• Full local CodeRabbit review and follow-up: no findings.

[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: f5663fb5-7b35-420a-9e9c-c7a6c2f16223

📥 Commits

Reviewing files that changed from the base of the PR and between 070ef37 and e6444a6.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (14)

• THIRD_PARTY_LICENSES.md
• cmd/internal/internal.go
• cmd/internal/runtime_supervisor.go
• cmd/internal/runtime_supervisor_test.go
• go.mod
• hack/licenses/overrides.ndjson
• pkg/driver/external/errors.go
• pkg/driver/external/host.go
• pkg/driver/external/host_test.go
• pkg/driver/external/internal/testfixture/main.go
• pkg/driver/external/lifecycle.go
• pkg/driver/external/production_test.go
• pkg/driver/external/session.go
• sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx

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

---

📝 Walkthrough

Walkthrough

This change adds an external runtime host that negotiates Runtime Protocol v1 capabilities and forwards lifecycle operations through supervised plugin processes. It adds the hidden supervisor command, error conversion and redaction, runtime validation, tests, dependency records, and driver documentation.

Changes

External runtime host

Layer / File(s)	Summary
Supervisor command and dependencies cmd/internal/..., go.mod, hack/licenses/overrides.ndjson, THIRD_PARTY_LICENSES.md	The hidden internal command registers runtime-supervisor. The module dependencies and license inventory add or update entries for the runtime SDK and related dependencies.
Host setup and supervised calls pkg/driver/external/errors.go, pkg/driver/external/host.go, pkg/driver/external/session.go, pkg/driver/external/host_test.go, pkg/driver/external/production_test.go, pkg/driver/external/internal/testfixture/main.go, sites/docs-devsy-sh/content/docs/developing-providers/driver.mdx	The host resolves and checks runtime executables, negotiates capabilities, and starts supervised plugin calls. It handles cancellation and redacts errors and diagnostics. Tests cover negotiation, process cleanup, environment handling, and executable path checks. The documentation describes the adapter operations and process behavior.
Lifecycle forwarding and validation pkg/driver/external/lifecycle.go, pkg/driver/external/host_test.go	The host forwards lifecycle operations, validates requests and runtime responses, converts container and mount data, and treats NotFound from delete as success. Tests cover lifecycle behavior and invalid inputs.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant HostNew as Host.New
  participant HostCall as Host.call
  participant Supervisor as internal runtime-supervisor
  participant RuntimePlugin as Runtime plugin
  HostNew->>HostCall: Request runtime Info
  HostCall->>Supervisor: Launch supervised plugin call
  Supervisor->>RuntimePlugin: Start plugin process
  RuntimePlugin-->>HostCall: Return InfoResponse
  HostCall-->>HostNew: Return validated InfoResponse

Loading

Merge Risk: ⚪ Minimal · up to e6444

No actionable issue was established in the new external runtime host. It is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to e6444

The new runtime executes trusted provider code with inherited environment access, making executable integrity and cleanup important. Workspace integration remains deferred, and no introduced security vulnerability was established. Provider provenance and recovery from interrupted backend changes still need validation before broader use.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — When invoked, the runtime can exercise the launching process's accessible filesystem and inherited credentials, potentially reaching backend assets beyond the workspace ID named in an RPC. Workspace IDs select operations; the inspected host does not turn trusted runtime code into a tenant-isolated execution environment. Actual backend and credential scope is not established.

Trust Boundaries and Controls

• observed — Provider declarations choose the executable, arguments, and expected checksum. The host snapshots those declarations and validates the prepared executable before each operation. Checksum equality establishes correspondence to the declaration, not independent authorization of its publisher; the trusted-provider model and resolver checks already existed at the PR base.
• observed — Environment inheritance preserves compatibility, while SDK transport metadata takes precedence over overrides. Diagnostics use streaming redaction; returned structured errors preserve status, category, and retryability without retaining raw backend diagnostics. Redaction covers recognized credential-bearing environment keys and all RunImage environment values, not every possible secret representation.

Resilience and Maintainability Implications

• inferred — Process cleanup and backend-resource recovery are separate guarantees. Cancellation closes the session lease, but the adapter does not reconcile an interrupted mutation automatically. Find and idempotent deletion offer recovery primitives; the inspected cancellation test exercises Preflight, not a partially committed mutation. A stranded resource or security impact was not demonstrated.

Hardening Proposals

• proposed — Before workspace cutover, define and exercise recovery after interruption at each mutation boundary, including commit-before-response failure, repeated operations, and concurrent operations on one workspace. Establish whether the caller or runtime owns reconciliation rather than treating process reaping as backend rollback.
• proposed — Document the authority responsible for accepting provider declarations and checksums before enabling production registration. If future runtimes are less trusted than provider code, introduce an explicit credential and execution-isolation policy rather than relying on checksums or the plugin handshake.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 10 files. (4 skipped:…	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 external runtime lifecycle operations to the driver host.

Full details: Docstring Coverage

Explanation

Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 10 files. (4 skipped: 4 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.}

[netlify]

✅ Deploy Preview for devsydev canceled.

Name	Link
🔨 Latest commit	e6444a6
🔍 Latest deploy log	https://app.netlify.com/projects/devsydev/deploys/6ac44f7c06bde10008c2fc01

[netlify]

✅ Deploy Preview for images-devsy-sh ready!

Name	Link
🔨 Latest commit	e6444a6
🔍 Latest deploy log	https://app.netlify.com/projects/images-devsy-sh/deploys/6ac44f7c2c641200086b8609
😎 Deploy Preview	https://deploy-preview-1383--images-devsy-sh.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[skevetter]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

[High risk] Adds external runtime driver with plugin lifecycle management.

The PR appears safe to merge based on the changes since the previous review.

What we checked:

• Fixture placed in the wrong folder: Yes. The test builds under binaries/runtime, and the resolver appends the lower-case runtime key to the binaries directory.

Summary

Devsy adds an internal host that checks a prepared external runtime and calls its lifecycle operations through a supervised process. This is an early integration stage: workspace registration, Exec, Logs, and conversion from Devsy run options are not included.

• External runtime calls now run through verified, supervised processes.
• Third-party notices now list the runtime SDK and refreshed dependency versions.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A["Host operation"] --> B["Verify prepared runtime"]
    B --> C["Launch hidden supervisor"]
    C --> D["Call runtime plugin"]
    D --> E["Close and reap session"]

Loading

_{Reviews (2) · Last reviewed commit: "test(driver): exercise production runtim..."}

[mergify]

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.

[skevetter]

@greptileai review

[skevetter]

CodeRabbit completed its full base-to-head review of e6444a6 with no actionable findings. The docstring coverage warning is advisory: comments are retained for process ownership, handshake cancellation, declaration snapshots, launch identity, and redaction boundaries. Blanket comments on straightforward RPC forwarding methods would restate the code. CLI lint, pre-commit, tests, and all applicable CI checks pass, so no additional code change is warranted for that metric.