Phase 1 slice 3b: Route sandbox create through the OpenShell lifecycle adapter
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 43m
- Merged PRs (30d)
- 718
Description
Parent: #9811
## Product decision
- Decision: Accept
- Reason: Complete the Phase 1 create boundary after #11905 removes the duplicate standard Docker and Podman lifecycle authority.
- Placement: Extend the final lifecycle contract and CLI implementation under `src/lib/adapters/openshell/`. Keep onboarding and rebuild responsible for lifecycle policy, ownership, recovery, and rollback.
- Accountable maintainer and implementation owner: @rsliter
- Validation plan: Exact CLI adapter tests, typed-fake onboarding and rebuild tests, repository boundary checks, and existing runtime evidence only where build, upload, or readiness behavior lacks a stable local boundary.
- Approval recorded: 2026-09-16
## Outcome
After #11905 lands, route the surviving ordinary custom-Dockerfile, persisted legacy-Dockerfile, custom-image, rebuild, and recreate create operations through the final typed asynchronous OpenShell lifecycle interface.
Do not establish a second lifecycle authority or migrate standard managed-image code that #11905 will delete.
## Required sequence
1. Merge #11905 through its atomic PR.
2. Refresh canonical `main` and inventory every remaining production `sandbox create` construction and process invocation.
3. Confirm that the final lifecycle interface can represent each surviving ordinary create request.
4. Implement this issue as one residual ordinary-create slice.
5. Create accepted, assigned follow-on issues for every deferred production create consumer before this issue merges.
6. Do not begin #11831 until the production create inventory is stable.
## Scope
- Replace raw OpenShell argument handoffs for surviving ordinary custom-Dockerfile, persisted legacy-Dockerfile, custom-image, rebuild, and recreate paths with semantic requests.
- Preserve current source, policy, provider reference, environment, resource, GPU, driver, label, startup, gateway, readiness, progress, timeout, and identity behavior.
- Move remaining CLI argument construction, child-environment filtering, process control, output parsing, timeout handling, cancellation, and redacted diagnostics for these consumers into the final CLI implementation.
- Remove obsolete command renderers, parsers, and raw argument plumbing after their final consumer migrates.
- Preserve action-owned authorization, ownership revalidation, lifecycle locks, rollback, recovery, and cleanup ordering.
- Reject raw preconstructed OpenShell create arguments at the typed boundary.
## Mutation semantics
- A create request contains semantic fields and a frozen named gateway target.
- A failure before process spawn is definite and publishes no sandbox ownership.
- Timeout, interruption, transport loss, output-limit termination, or acknowledgement loss after spawn is ambiguous.
- An ambiguous result requires observation of the exact create-attempt identity before recovery or retry.
- No automatic mutation retry or cross-transport fallback is allowed.
- A successful command does not establish success until the expected sandbox identity reaches the required observed state.
- Credential values must not enter arguments, results, logs, diagnostics, or model-visible output.
- Staged policy input must use owner-only permissions and verified cleanup.
## Acceptance evidence
- Allowed: Each surviving ordinary create and recreate path maps its semantic inputs to the final CLI implementation and preserves current observed behavior.
- Denied: Malformed sources, reserved environment overrides, credential values, gateway drift, ownership drift, or changed create-attempt identity prevent process spawn or success publication.
- Ambiguous: Post-spawn transport ambiguity causes exact observation and never a blind retry.
- Failure or recovery: Readiness or identity verification failure preserves pending recovery authority and uses exact named deletion only when cleanup is authorized.
- The completed change removes the migrated consumers’ raw OpenShell argument handoffs and does not add another lifecycle registry, journal, fallback, or compatibility mode.
- Focused adapter, onboarding, rebuild, recovery, credential-canary, and repository boundary tests pass.
## Dependencies and coordination
- Blocked by #11905 and its atomic implementation PR #11909.
- Reconcile #11877 through #11905 because it changes managed-bootstrap code scheduled for removal.
- Re-inventory Portable after #11874 and #11909 settle.
- Reuse the named deletion and observer contracts merged through #11838.
- Stop and re-plan if #11905 changes supported custom or legacy creation behavior, leaves two lifecycle authorities, or does not provide a suitable semantic create boundary.
## Deferred scope
- Standard managed-image Docker and native Podman creation: #11905.
- Snapshot clone creation: a focused accepted and assigned follow-on issue.
- Portable creation: a focused accepted and assigned follow-on coordinated with #10056.
- MXC and Windows native-artifact creation: the accepted provider-specific owner recorded through #9813.
- Authorized selected-gateway bulk uninstall deletion: #11831.
- SDK and gRPC lifecycle implementations: #9831.
- New create options, retry policy, timeout policy, progress wording, resource fields, or local image-build semantics.
## Stop conditions
- Do not implement this issue before #11905 merges.
- Do not create a temporary lifecycle adapter or migrate managed-bootstrap code scheduled for deletion.
- Do not alter Portable lifecycle authority in this issue.
- Do not merge a partial create migration until each remaining production consumer has an accepted, assigned owner.
- Do not begin #11831 before the complete production create inventory is stable.
Contributor guide
Assessment
This issue has not been assessed yet.