Repository navigation
Closed as not planned
Closed as not planned
Copy link
Labels
new featureA new user-facing capabilityA new user-facing capability
Milestone
Description
Parent: #545 (index). This issue owns the B5 Sandbox lifecycle slice. It is not the daemon control-slot work in #547.
Summary
#545 B5 is 0/10 done and 2/10 partial. Today sandbox.close is an op-intent that stops and deletes the Sandbox with no Draining state, no CAS on a generation and no exec lease. Three failure modes follow:
- a reclaimer that decided "idle" can kill an exec between the decision and the kill, losing uncommitted Workspace data;
- a crashed exec leaves
busyset with no lease deadline, so "never kill while an exec is active" becomes "never reclaim", leaking capacity and cost; - a provider-side disappearance leaves the record
Ready/Busyforever, and the stale base revision can then be used by a snapshot push.
The fix is a small, explicit protocol, not a new subsystem.
Scope (from #545 B5, plus the state enum in B0)
-
Drainingis entered by CAS ongeneration. - an active exec holds an exec lease deadline.
- close sequence: mark
Draining→ check lease/generation → close or abort → recordClosed/Lost. - no kill while a lease is live; lease expiry moves to
Lost/Unresolved, never a blind kill. - close is idempotent; a stale generation aborts.
- failures are
Unresolved; no unbounded retry. -
Lostis a first-class state. -
last activityuses a monotonic clock. - reclamation has
reclaim.enabled,--dry-runand a freeze / kill switch, and records the reason for every close. - reclamation is keyed by machine / backend, never by isolation class.
-
Creating / Provisioning / Starting / Ready / Busy / Draining / Closed / Lost / Failed / Unresolvedare explicit (from [B] Sandbox compute plane: machines, backends, observability and lifecycle #545 B0-140).
Protocol
Ready --CAS(generation)--> Draining --active exec/mount == 0, or lease expiry--> Closed
\--lease expiry / provider gone--> Lost
- The Sandbox record carries
generation,active_exec_leases[],lease_deadline,last_activity_monotonicandclose_reason. close(generation)is idempotent: a second close with the same generation is a no-op; a stale generation is refused, not retried.- A live exec lease blocks the close. Lease expiry is an explicit
Lost/Unresolvedtransition; never a blind kill. - Every close records its reason and the evidence that decided it (idle deadline, lease expiry, operator, provider gone).
- Reclamation runs under
reclaim.enabled;--dry-runand--freezeare mandatory operational brakes.
Non-goals
- The daemon admission slot lifetime and recovery admission belong to daemon: bound an admitted control slot's lifetime and keep recovery admissible when the pool is exhausted (#540 follow-up) #547 (a different custody layer, no shared code).
- Scratch ownership and cleanup are the B6 issue.
- Provider adapters are the B7 issue.
Acceptance
- A concurrent exec started between the reclamation decision and the kill is never killed.
-
Lostis reachable and observable fromsandbox get; a lease expiry producesLost/Unresolved, not a retry. - A stale-generation close aborts without side effects.
- Close is idempotent under replay.
-
reclaim.enabled=false,--dry-runand--freezeeach stop the destructive path. - State-machine tests cover every transition; one fault-injection test covers a panic or exit during close.
Dependencies
- No D2 / D6 / D12 dependency; can start now.
- The B6 issue depends on the generation and
Lost/Unresolvedsemantics defined here. - The explicit state enum also unblocks the B0/B8 read models.
Related
- Parent index: [B] Sandbox compute plane: machines, backends, observability and lifecycle #545
- B0 contract: B0: machine/backend contract — isolation, scheduling, capacity and read models (B8/B10) #551
- B5 lifecycle: B5: Sandbox lifecycle — generation CAS, exec lease, Draining and first-class Lost #548
- B6 scratch: B6: Sandbox scratch lifecycle — owned path, generation check, bounded cleanup #549
- B9 worker health: B9: machine worker health and liveness — a dead worker must never leave a call hanging #550
- StoragePlacement guard: B0: refusal for a misplaced Store — StoragePlacement guard for live SQLite on Family 2 #552
- B4 WSL2: B4: Windows via a WSL2 worker and Docker backend (blocked on D2/O5) #553
- B7 cloud/provider: B7: cloud and provider adapters — Family 1/2 contract, transport and storage binding (blocked on D6/D12) #554
- Step runtime: step-runtime: exec_async / exec_wait / exec_status outside the Sandbox compute plane #555
- daemon: bound an admitted control slot's lifetime and keep recovery admissible when the pool is exhausted (#540 follow-up) #547 is the daemon-admission follow-up: a different custody layer, not this sub-issue.
Residuals consolidated from #422 and #423
- Explicitly cover an abandoned/orphaned mounted Workspace that retains a Sandbox after its application process is gone.
- Lease expiry or caller death must not authorize discarding uncommitted Workspace state; preserve exact ownership and uncertainty.
- Cover stopped-container lifecycle and cleanup after known owner release, not only a standalone reclamation helper.
The older reports #422 and #423 are being consolidated here/#549. This is not a claim that this issue's branch has been integrated or qualified on the target.
Metadata
Metadata
Assignees
Labels
new featureA new user-facing capabilityA new user-facing capability
Activity
mengmengmengqiang commentedon Nov 4, 2026
Maintainer: this sub-issue was created without labels because the available token has no
triagepermission. Requested labels:v2.0.0,bug. Please add them (and adjust if the repo's triage rules disagree).docs(545): index the implementation status board (6/16/41 + 3 N/A, 60…
docs(549): record the scratch contract and the narrowed trigger (Ephe…
mengmengmengqiang commentedon Nov 4, 2026
All #548 checkboxes are now covered by the B5 branches and tests.
Evidence:
agent-b5/agent-b548/agent-b548b.sandbox_lifecycle8/8, apisandbox_lifecycle9/9,sandbox_records3/3,typed_records7/7,home_layout_33/3.SandboxStateenum: Creating, Provisioning, Starting, Ready, Busy, Draining, Closed, Lost, Failed, Unresolved; one facts→state mapping; get/list serialization; old/absent records migrate.Qualification (not a checkbox): the Docker E2E was not run because the verification sandbox has no Docker socket/CLI.
sandbox_familyfails atproject.initon overlayfs (SQLite lock), before any B5 path.failedhas no live control producer today; it is reachable from an explicitstate: "failed"record.mengmengmengqiang commentedon Nov 5, 2026
All checkboxes are covered by the verified branches/PRs; evidence is recorded in the issue evidence comments and the subagent reports.
mengmengmengqiang commentedon Nov 5, 2026
Reopened: the delivery gate is code on the target branch + PR merged + CI green + traceable evidence. This issue was closed on branch/test evidence only; its PR/branch is not merged to
layerfs_v2_0_0yet.style(sandbox): rustfmt B5 close and unfence its protocol doc (Epheme…
style(sandbox): rustfmt B5 close and unfence its protocol doc (Epheme…
19 remaining items
docs(549): record the scratch contract and the narrowed trigger (Ephe…
refactor(548): move reclamation policy beside its own module (Ephemer…
docs(549): record the scratch contract and the narrowed trigger (Ephe…
style(sandbox): rustfmt B5 close and unfence its protocol doc (Epheme…
test(548): live close/exec E2E on native and docker (Ephemeral-AI-Lab…
test(548): start docker machine and inspect the container by runtime …
refactor(sandbox): tighten the B5 lifecycle types and docs (Ephemeral…
docs(548): name the nine explicit Sandbox states (Ephemeral-AI-Lab#548)
fix(548): keep an Unknown exec lease until its deadline (Ephemeral-AI…
refactor(548): move reclamation policy beside its own module (Ephemer…
docs(549): record the scratch contract and the narrowed trigger (Ephe…
Record the history of #566 by mengmengmengqiang (rain): feat(sandbox)…
yifanxuaaa commentedon Nov 7, 2026
Closed by the owner (2026-11-07). PR #566 is shown as merged into
layerfs_v2_0_0, but it was recorded as history only (agit merge -s oursin #601): mengmengmengqiang's commits and credit are kept, but none of its code is on the branch. The control layer split (layerfs-project#101) replaced this area, and the port was cancelled, so this is not delivered. The exec-lease and cancel part continues in Ephemeral-AI-Lab/layerfs-project#113.