Phase 1 slice 3: Route sandbox create and delete through the OpenShell adapter
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
Parent Epic: #9802
## Product decision
- Decision: Accept
- Reason: Move the existing sandbox create and delete behavior behind the typed OpenShell boundary so lifecycle actions no longer depend on CLI argument, environment, process, or output details.
- Placement: Add the transport-neutral lifecycle contract and CLI implementation under `src/lib/adapters/openshell/`. Keep onboarding, destroy, rebuild, snapshot, portable runtime, and uninstall responsible for lifecycle policy, ownership, rollback, recovery, and cleanup ordering.
- Accountable maintainer and implementation owner: @rsliter
- Validation plan: Typed-fake action tests, exact CLI implementation tests, current lifecycle regression suites, repository boundary checks, and focused existing E2E only where a real process, container, or cleanup boundary is not covered locally.
- Approval recorded: 2026-09-15
## Outcome
Route every in-scope production sandbox create and delete operation in `src/lib/` through one typed asynchronous OpenShell lifecycle interface without changing supported lifecycle, rollback, recovery, timeout, or user-facing progress behavior.
## Accepted scope
- Define transport-neutral create and delete requests, results, progress, and failure classifications.
- Move CLI argument construction, environment filtering, policy input staging, capability probing, process control, output parsing, timeout handling, cancellation, and transport diagnostics into the CLI implementation.
- Migrate ordinary onboarding, GPU native and compatibility creation, managed-bootstrap creation, snapshot cloning, recreate, destroy, rebuild, rollback, failed-attempt cleanup, portable lifecycle, scoped uninstall, and authorized full-uninstall deletion.
- Require a frozen named gateway for single-sandbox mutations. Preserve selected-gateway targeting only for the accepted unscoped full-uninstall compatibility path.
- Preserve exact ownership revalidation and lifecycle locks in action code. The adapter does not authorize deletion and does not retry mutations.
- Remove direct production create and delete command construction after the final in-scope consumer migrates. Record every remaining plugin, tooling, E2E, or provider-specific occurrence as an accepted exception or follow-on owner.
## Accepted mutation semantics
- A create request contains semantic fields rather than raw CLI arguments. Managed runtimes may provide trusted execution authority but may not pass preconstructed OpenShell create arguments through onboarding.
- A zero delete command exit means the mutation was accepted, not that deletion completed. An action may declare success only after explicit absence on the frozen gateway.
- A failure before process spawn is definite. Timeout, interruption, transport loss, output-limit termination, or acknowledgement loss after spawn is ambiguous because the remote mutation may have occurred.
- Ambiguous mutation results require exact observation before retry. No automatic transport fallback or mutation retry is allowed.
- Full uninstall may preserve `sandbox delete --all` only when the operation owns the selected gateway. Partial or unverifiable bulk deletion preserves provider, gateway, and registry state for recovery.
- Raw OpenShell output remains inside the CLI implementation. Actions consume typed progress, typed failure reasons, and bounded redacted diagnostics.
## Acceptance evidence
- Successful create preserves the current image or source, policy, provider, environment, resource, GPU, driver, label, startup, gateway, readiness, and exact-identity inputs.
- Destroy, rebuild, recreate rollback, snapshot replacement, portable cleanup, failed GPU-attempt cleanup, and scoped uninstall delete only after their current ownership checks and complete only after explicit absence.
- A same-name replacement, gateway drift, ownership drift, malformed input, or reserved environment override prevents mutation.
- Create and delete timeout, cancellation, connection loss, malformed output, persistent presence, identity replacement, and cleanup failure preserve the current recovery authority and do not trigger blind retry.
- GPU compatibility fallback remains limited to one attempt and starts only after stable sandbox absence and native-container cleanup are proven.
- Provider credential values do not enter arguments, results, logs, or diagnostics. OpenShell child environment remains allowlisted, and staged policy input uses owner-only permissions with verified cleanup.
## Capability slices and order
1. Migrate owned single-sandbox deletion and its explicit-absence reconciliation: #11838.
2. Migrate all in-scope create variants, including managed-bootstrap and snapshot creation: #11830.
3. Migrate accepted bulk uninstall behavior, remove obsolete command paths, and close the production boundary inventory: #11831.
If these slices use separate pull requests, every remaining consumer must have an accepted, assigned follow-on issue before the first partial pull request merges.
## Dependencies and coordination
- Reuse the observer contract from #9803 and policy contract from #9805.
- Reconcile the final contracts and touched consumers from #11741, #11614, #11792, #11616, and #10774 before merging conflicting code.
- Stop and re-plan if those changes alter gateway authority, lifecycle ownership, credential custody, timeout behavior, or the accepted consumer set.
## Deferred scope
- Plugin lifecycle migration and reviewed production-boundary exceptions: #9813.
- SDK and gRPC lifecycle implementations: #9826.
- New create options, lifecycle behavior, retry policy, timeout policy, progress wording, resource fields, or local image-build semantics.
Contributor guide
Assessment
This issue has not been assessed yet.