@claxedo/sandbox-manager 0.9.0 → 0.10.1

package/README.md

@@ -9,7 +9,22 @@ The package owns the generic pieces:
 - `SandboxTarget`
 - `SandboxLeaseStore`
 - `SandboxDriver`
-- provider drivers for Cloudflare, Daytona, Docker, fetch bridge, Modal, and Vercel
+- provider drivers for Cloudflare, Docker, fetch bridge, Modal, and Vercel
+
+`drivers/local-brokering` is a macOS test driver. The e2e hosted stack's
+sandbox fixture (`packages/harness/e2e/harness/hosted-sandbox-worker.ts`)
+injects its instance programmatically; it has no product driver ID or product
+configuration path. It runs the workspace runtime in a private directory under
+`sandbox-exec`, permitting outbound TCP to its HTTP proxy and the specified
+control-plane and relay loopback ports. The profile lets only `/bin/ps` execute
+outside the sandbox because macOS refuses its setuid binary inside
+`sandbox-exec`; the runtime stays under the network policy. The proxy accepts
+HTTPS CONNECT only for a registered secret host with an explicit loopback test
+upstream, terminates it with a private test CA, and applies the egress broker's
+placeholder substitution before forwarding. The runtime trusts the CA
+certificate, while its sandbox profile denies access to the CA and leaf private
+keys. Other CONNECT destinations are refused. It is not a production sandbox
+provider.
 
 It deliberately does not own Claxedo product auth, billing, app storage schema, routes, or relay tokens. Applications provide those through adapters and call `createSandboxManager`.
 
@@ -53,15 +68,200 @@ if (result.status === "ready") {
 await manager.stop("workspace-1")
 ```
 
-Swap `createDockerSandboxDriver` for `createDaytonaSandboxDriver`,
-`createModalSandboxDriver`, `createVercelSandboxDriver`,
-`createCloudflareSandboxDriver`, or `createBoxSandboxDriver` (all under
+Swap `createDockerSandboxDriver` for `createModalSandboxDriver`,
+`createVercelSandboxDriver`,
+`createCloudflareSandboxDriver`, or `createBoatSandboxDriver` (all under
 `@claxedo/sandbox-manager/drivers/*`) to place on a hosted provider instead —
 see [`docs/architecture.md`](docs/architecture.md) for the full driver
 comparison and each provider's required options. Swap `createMemoryLeaseStore`
 for a persisted `SandboxLeaseStore` implementation (e.g. backed by SQLite) to
 survive process restarts.
 
+The Boat driver checks the runtime's health endpoint after starting its container.
+If startup never becomes healthy, the failure includes a bounded container log
+tail and container exit information, with staged environment and registry secret
+values redacted before truncation. A diagnostic request failure preserves the
+original health failure.
+
+### Boat: what survives a stop, and what survives an image update
+
+A Boat sandbox is a Linux VM whose disk Boat snapshots at every stop; the
+runtime runs inside it as a Docker container over the canonical sandbox image's
+trees. Boat's snapshot keeps a container's settings but not its writable layer,
+and a resume creates every container again from its image
+([what a snapshot saves](https://docs.boat.dev/snapshots/whats-saved#docker);
+confirmed on a live sandbox 2026-10-14), so the driver keeps the machine's
+state on the VM's disk and mounts it into the container:
+
+| Path in the machine | Source on the VM disk | Stop and resume | Image update |
+| --- | --- | --- | --- |
+| `/workspace` | `claxedo-persistent/workspace` | kept | kept |
+| `~/.claxedo`, `~/.workspace-runtime` (runtime stores, harness homes) | `claxedo-persistent/claxedo`, `claxedo-persistent/workspace-runtime` | kept | kept |
+| `/root`, `/usr`, `/etc`, `/var`, `/opt`, `/home`, `/srv` | `claxedo-persistent/image-<image>/<tree>`, seeded from the image once per image | kept: dotfiles, `npm i -g`, `pip install`, `apt install`, anything written there | replaced by the new image's trees; the old image's are removed |
+| the container's hostname | `--hostname <workspace id>` | kept | kept |
+| everything else (`/tmp`, `/run`, processes) | none | gone, as on any reboot | gone |
+
+A new sandbox gets the image's trees one of two ways. A sandbox of the
+deployment's image is created from the release's runtime template (below), a
+named snapshot that already holds them, so its first start pulls and seeds
+nothing. Without a template, or when the organization's key cannot read it, or
+for any other image, the first start seeds them. The seed runs once per image, at the start that first names it: it pulls the
+image, streams the trees out of a created container of it with `docker cp` and
+unpacks them as root, leaving out `~/.cache` (which Boat's own snapshots leave
+out too) and npm's cache. The persistent root is created as root too: Docker
+made it as root on every sandbox that booted before the trees existed, and the
+VM user cannot create inside it. The seed then saves beside the trees what the
+container needs besides them: the image's env (`image.env`, given to the
+container with `--env-file`) and a stub image (`stub.tar`, 67 kB) holding the
+image's top level outside the trees (Debian's merged-`/usr` links and empty
+directories), its working directory, and a `claxedo.image` label naming the
+image. The seed starts no container of the image: Boat records the containers
+it sees, and one the seed ran for a second to read the image's root was
+recreated by a later restore as soon as the image was back, so the next seed
+could not remove the image. The trees are marked complete once they all
+landed, and a seed whose trees did not complete is redone from the pull; trees
+marked complete are never seeded again, since they hold what was changed since,
+so a seed missing only `stub.tar` or `image.env` (as one an earlier driver left)
+pulls the image and builds those alone. Once the runtime container runs from the
+stub, the start removes the image, any leftover container of it, and the archive
+Boat keeps of it in `/var/lib/ascii-docker-images` (Boat loads that archive
+again at every resume, 16–19 s for this image, and removing the image leaves it
+behind). It waits for the start because the container being replaced may run
+from the image itself, as an earlier driver's did.
+
+Every start then runs the container from the stub, loading `stub.tar` when
+Docker does not hold this image's stub, with every path above mounted. A wake
+therefore pulls nothing. On Boat, 2026-10-15, from the create or resume call to
+a healthy runtime, with a public repository checked out:
+
+| Start | Time | Where it goes |
+| --- | --- | --- |
+| cold, from the runtime template | 20.7, 26.8, 29.5 s | create to `machine_ready` 5–8 s, `image_ready` (stub and container start) 2 s later, the rest the runtime reading its files while Boat still downloads them |
+| cold, seeding (no template, or an unreadable one) | 55–96 s (81.5 s for the fallback) | the pull and seed, as fast as ghcr serves the image |
+| wake of a sandbox created from the template | 14.7, 17.2, 12.3 s | `machine_ready` 5 s, `image_ready` 1–3 s, then the runtime |
+| wake of a seeded sandbox | 8–20 s | the same phases, with no record of what the runtime reads first |
+
+The driver waits on Boat itself rather than reading the sandbox on a timer.
+Boat holds a command sent while a sandbox starts and runs it once the sandbox
+is ready, for up to 60 s, then refuses it as still starting
+([readiness](https://docs.boat.dev/readiness)), so the first command after a
+create or resume returns the moment the machine is ready and is sent again at
+once after a refusal. The runtime's health is probed inside the machine every
+100 ms by one command per 50 s window, which ends at the first answer or when
+the container leaves `running`/`paused`. A sandbox still archiving from a stop,
+which Boat offers no wait for, is read again after 250 ms, doubling to 2 s.
+
+A wake that pulled (before the stub) took 57–77 s, and failed when ghcr reset
+the connection. An image update re-seeds:
+the new image is pulled and seeded as above, its stub replaces the old one, and
+the old image's trees are removed.
+
+A start runs as two commands: the preparation (daemon, login, seed, stub)
+changes nothing a running container serves from, so its failure leaves a
+runtime of the previous image serving and the lease ready; the container start
+that follows replaces that container, so its failure is a boot failure the
+manager demotes. The container carries the stub's label, so a start finds a
+container of its own image (one Boat created again after a stop that was not
+this driver's, or the one the stop kept) and starts it rather than replacing
+it. Boat's restore creates a resumed sandbox's containers again about 2 s after
+Docker answers; when that create takes the runtime's name after the start looked
+for it, Docker answers that the name is in use, and the start waits a second
+(Docker holds the name from the start of Boat's create) and looks again, up to
+five times: this image's container (the one the stop kept, created again by
+Boat) is started, and another image's is removed and the runtime created again.
+Removing Boat's container instead lost the race at all five creates on a
+machine's first wake, as Boat created it again each time (2026-10-15). Docker named volumes were measured and rejected: Boat
+saves them through a path of its own, and a stop with 3.7 GB of them had not
+finished after ten minutes, while the same bytes under the work directory
+archived in 27 s.
+
+`stop` ends the runtime container with the 30 s grace Boat's own stop gives
+and keeps it, so Boat's snapshot records it stopped: the restore creates it
+again without starting it, and the start starts it after writing this boot's
+env file (each wake's runtime read that wake's env, 2026-10-15). Removed, it
+left Boat the set an earlier snapshot recorded, and Boat created and started the
+runtime again from it on the previous boot's env file. `host <port> --public` is
+sent once more when Boat answers that it could not stop the port's localhost
+relay, which is Boat's own request to try again.
+
+Two boots of one machine can run at once: Cloudflare re-ran a start's alarm on
+another machine while the first run still booted (staging, 2026-10-15), and a
+retried epoch resumes the same VM, so two seeds removed each other's trees.
+Each boot therefore stages its env and registry password under names of its own
+(`.claxedo-runtime-env.<boot>`, moved into place by its start), and its
+preparation, container start and `host --public` each hold `flock` on
+`/run/lock/claxedo-boot.lock` (two publishes of one port at once made Boat
+answer 500 on its own record of it). A second boot waits for the first's command to
+end, then finds the seed complete and the first's container, and starts it. The
+kernel releases a lock with its holder, so a holder Boat ended (a command past
+its time limit) releases it at once, and one whose caller went away holds it
+until its command ends, which Boat lets run (measured 2026-10-15). A wait past
+the command's limit less 60 s fails the boot with that reason. Staged files
+older than the 30-minute boot deadline belong to no running boot and are removed.
+A resume Boat refuses with `sandbox_resuming`, because the other boot resumed the
+sandbox first, waits for that resume instead of failing.
+
+### Boat runtime template
+
+Boat has no custom image: a named snapshot is its template
+([named snapshots](https://docs.boat.dev/snapshots/templates)). The release
+saves one per runtime image in its own Boat account, and every organization's
+key creates its sandboxes from it with a share code.
+
+What a template holds: a machine on which the driver already booted the image,
+then reset. It keeps `claxedo-persistent/image-<image>/` (the trees, `stub.tar`,
+`image.env`, marked complete) and Boat's `~/.ascii/playbook.json`, the record of
+the files the runtime opened first, which Boat downloads first at every start
+from the template. It holds no image and no Boat archive of one (the start
+removed them once the runtime ran from the stub), no container, no workspace,
+no runtime state and no boot env (`boatTemplateResetCommand`). On Boat,
+2026-10-15, the template of the staging image was 4.46 GB.
+
+Lifecycle, in `drivers/boat-template.ts`, run by
+`bun run --cwd packages/claxedo-server sandbox:boat-template --image=<image>`:
+
+1. **Name.** `claxedo-rt-` and the first 12 hex digits of the SHA-256 of the
+   image reference. The reference is content-addressed (its tag names the
+   build) and names the trees directory, so it is the template's key.
+2. **Build, once per image.** A ready template is reused and one still saving
+   is waited for; a missing or failed one is built on a builder sandbox: the
+   Boat driver boots the image there (pull, seed, stub, runtime healthy), the
+   builder is stopped and woken (Boat records what a sandbox opens first only
+   while it starts from a snapshot), the build waits for `hydrated` (Boat writes
+   the record once the download ends), resets the machine, stops it, and saves
+   it under the name. The builder is deleted whatever the outcome. On Boat,
+   2026-10-15, a build took 144 s: boot 56 s, stop 25 s, wake 31 s, hydration
+   7 s, reset and stop 14 s, save 8 s.
+3. **Share, at every deploy.** A share code (`bsh_…`) is a secret: whoever holds
+   it deploys the template, and Boat shows it once. Before the Worker deploy,
+   `--share-to` mints a new code, revoking none, and the deploy uploads
+   `CLAXEDO_BOAT_RUNTIME_TEMPLATE` (`{"image", "shareCode"}`) as a Worker secret.
+   Only after that deploy succeeded does `--deployed-share=<share id>` revoke
+   every other code of the template, so a failed deploy leaves the live
+   Worker's code working.
+4. **Use.** `ensureHost` creates a sandbox whose image is the template's
+   `from` the share code, under a create key of its own
+   (`claxedo:<workspace>:<epoch>:template`: Boat refuses a key sent again with
+   another body for 24 h). Its first start finds the trees seeded and loads the
+   stub. A template of another image is never used. When the organization's key
+   cannot read the template (`snapshot_not_found` for a wrong, revoked or
+   removed code; `api_key_action_forbidden` or `api_key_sandbox_forbidden` for a
+   key without `snapshot.read`), the driver logs it and creates the sandbox that
+   pulls and seeds; any other refusal fails the start as before. A wake resumes
+   the sandbox it has and never touches the template.
+5. **Prune.** After a successful deploy, the newest three templates of the
+   prefix are kept, the deployed image's among them, and the rest removed; Boat
+   removes their share codes with them. Pruning never runs before a deploy
+   succeeded, so it never removes the template the live Worker creates from.
+
+Cost: an account keeps 10 named snapshots free, then pays $1.70 a month for
+each, so three templates fit in the free ten unless the account saves others.
+A sandbox created from a share code is billed to the account that creates it.
+A deploy from a share code does not get the source's per-sandbox env, and Boat
+strips the source's logins, keys and SSH keys from it; the builder is created
+with `noEnv` and its reset removes everything a boot wrote outside the image's
+trees.
+
 ## Credentials & secrets
 
 There are two distinct channels for getting values into a sandbox, chosen by
@@ -89,7 +289,7 @@ await manager.ensure(workspaceId, {
     name: "NOTION_TOKEN",
     value: notionToken,          // never enters the sandbox in plaintext
     hosts: ["api.notion.com"],   // substituted/injected only for these hosts
-    header: "Authorization",     // required for Vercel; optional for Daytona
+    header: "Authorization",     // required for Vercel
   }],
 })
 ```
@@ -98,7 +298,6 @@ Per-provider mechanism (from each provider's official docs):
 
 | Driver | `secretBrokering` | Mechanism |
 | --- | --- | --- |
-| Daytona | `native` | `daytona.secret.create({name, value, hosts})`; the sandbox env holds an opaque `dtn_secret_…` placeholder and an egress proxy substitutes the real value only for allowlisted hosts ([docs](https://www.daytona.io/docs/en/secrets/)). |
 | Vercel | `native` | Firewall header-transform (`updateNetworkPolicy`): the value is spliced onto egress to the allowlisted hosts as `header`, so the sandbox makes an unauthenticated request ([docs](https://vercel.com/docs/sandbox/concepts/firewall)). `updateNetworkPolicy` replaces the whole policy, so the driver sends the **union** of the create-time allow-list and the brokered hosts — attaching a credential must not revoke egress the caller was already granted (a mid-run `npm install` would start failing), nor widen it to a brokered host the create-time policy never approved. |
 | Cloudflare | `native` | The driver sends named registrations to the API-token-gated Worker. KV holds the values outside the container; native HTTPS outbound handlers replace named placeholders in registered headers. Each request reads KV, so there is no expiring container JWT. KV propagation delay still applies to rotation and withdrawal. |
 | Modal | `none` | Modal [Secrets](https://modal.com/docs/guide/secrets) are an encrypted by-reference store, but exposed as **readable env vars** inside the sandbox — they cannot satisfy the never-readable contract. |
@@ -109,13 +308,32 @@ readable env. Only `native` keeps the value out of the sandbox and provisions
 normally; a `none` driver makes the manager refuse to provision (`status:
 "unavailable", error: "secret_brokering_unsupported"`) rather than expose or
 drop the credential. Brokered secret values are also never written to labels,
-never logged, and never captured in a driver snapshot.
+never logged, and never captured in a driver snapshot. A `none` driver's
+sandbox is handed no provider secret at all: on the hosted control plane its
+owner's model accounts reach the harness as placeholders spent through the
+plane's own egress broker (`@claxedo/server`'s
+`credentials/hosted-egress-broker/`), which the driver never sees. Its private
+repository is cloned the same way: `SandboxManagerInput.leaseEnv` mints, for
+the epoch and host the driver is about to boot, a broker placeholder and the
+binding URL the runtime points its git at; the broker attaches the
+connection's current token to that repository's smart-HTTP requests while the
+lease boots or serves, and the control plane re-delivers the placeholder at
+half its hour.
 
 > Native brokering keeps the original upstream URL. Cloudflare accepts its
 > named placeholder as the complete credential header, or with a Bearer prefix
 > for Authorization API-key clients. Modal remains `none`: its encrypted store
 > exposes credentials as readable environment variables inside the sandbox.
 
+**Never readable is not never spendable.** The placeholder sits in every
+process's environment, and the edge attaches the real value to any request to
+an allowlisted host that carries it, with no condition on which session or
+person sent it. Anything that runs in the sandbox can therefore spend what it
+was delivered. Claxedo delivers a workspace's sandbox only its owner's chosen
+provider accounts, never another person's, and treats the sandbox as shared
+trust among everyone admitted to that workspace: their sessions and shells can
+spend the owner's delivered accounts (owner ruling, 2026-09-28).
+
 ## Egress containment
 
 `SandboxManagerInput.net` restricts what the sandbox can reach on the network.
@@ -124,13 +342,13 @@ and the difference matters:
 
 - **Brokered secrets fail closed.** A driver that cannot broker refuses to
   provision (`error: "secret_brokering_unsupported"`).
-- **Egress does not.** Only `daytona` (names + CIDRs) and `vercel` (names) can
-  enforce an allowlist. Every other driver declares
-  `metadata.egressControl: "none"`, and for those the manager **withholds** the
-  policy and provisions anyway — the sandbox runs with unrestricted egress.
+- **Egress does not.** Only `vercel` (names) can enforce an allowlist. Every
+  other driver declares `metadata.egressControl: "none"`, and for those the
+  manager **withholds** the policy and provisions anyway — the sandbox runs
+  with unrestricted egress.
 
-Withholding rather than passing is deliberate: `exe`, `docker`, `modal` and
-`box` throw when handed a restricted policy, and `cloudflare` and the fetch
+Withholding rather than passing is deliberate: `docker`, `modal` and `boat`
+throw when handed a restricted policy, and `cloudflare` and the fetch
 bridge accept one and silently ignore it. Withholding at the manager means the
 throwing drivers never see a policy (their throws stay as their own last line of
 defence) and the silently-dropping ones stop pretending.
@@ -147,17 +365,6 @@ Pass `onEgressUnenforced` to route that into telemetry instead of `console.warn`
 — it receives a structured `SandboxEgressUnenforcedEvent`. Overriding the sink
 replaces the console warning, so only do it if the replacement is as visible.
 
-**Reuse and resume reapply the policy.** A restricted policy only reaches a
-provider as *creation* parameters, so a sandbox handed back rather than created
-— reuse in `ensureHost`, resume in `resumeHost` — would otherwise run on the
-policy in force when it was first created, possibly a wider one from an earlier
-caller. Daytona's allow-list is mutable post-create
-(`Sandbox.updateNetworkSettings`), so `daytona` reapplies the requested policy
-on both paths. A client too old to expose that call makes the driver **refuse
-the reuse**: a policy reported as applied but not in force is worse than no
-sandbox. Requesting no containment leaves the existing policy alone rather than
-clearing it — "not requested" is not "please unrestrict".
-
 `driver.metadata.egressControl` is the machine-readable source of truth, and
 `sandboxEgressDisposition(control, net)` is the pure predicate the manager uses,
 so you can ask the same question before composing. One exception stays fail
@@ -165,8 +372,8 @@ closed: a hosts-only driver handed an address-only policy is refused
 (`sandbox_egress_policy_unenforceable`) rather than degraded, because that
 driver *does* enforce egress — it just cannot express that encoding.
 
-> SDK conformance: the Daytona secret API and Vercel network-policy transform
-> shapes follow the providers' official docs and are validated structurally
+> SDK conformance: the Vercel network-policy transform shapes follow the
+> provider's official docs and are validated structurally
 > against the pinned SDK types; like all provider calls in this package they
 > are exercised against mocks in unit tests, with live-SDK integration
 > verified at deploy time.

package/dist/checkpoint-manager.d.ts

@@ -1,6 +1,8 @@
-import type { SandboxCheckpointReference, SandboxEnsureResult, SandboxLease, SandboxLeaseStore, SandboxManagerInput, SandboxSnapshotManagerResult, SandboxTargetResult } from ".";
+import type { SandboxCheckpointReference, SandboxEnsureResult, SandboxLease, SandboxLeaseStore, SandboxManagerInput, SandboxResource, SandboxSnapshotManagerResult, SandboxTargetResult } from "./contract";
 export type SandboxCheckpointRuntime = {
-    freeze: (policy: "drain" | "interrupt") => Promise<void>;
+    freeze: (policy: "drain" | "interrupt", options: {
+        idleBefore?: number;
+    }) => Promise<void>;
     flush: () => Promise<void>;
     scrub: () => Promise<void>;
     resume: () => Promise<void>;
@@ -12,7 +14,18 @@ export type SandboxCheckpointRuntime = {
 export type SandboxCheckpointCaptureInput = {
     runtime: SandboxCheckpointRuntime;
     policy?: "drain" | "interrupt";
-    retentionExpiresAt?: number;
+    /** Capture only a workspace that has had no work since this time; the runtime refuses the freeze otherwise. */
+    idleBefore?: number;
+};
+export type SandboxStopInput = {
+    /** Present when the workspace's state is captured before its host stops. */
+    runtime?: SandboxCheckpointRuntime;
+    idleBefore?: number;
+    expectedEpoch?: number;
+    /** The caller is the host: it stops itself once the lease says stopped, so the manager stops no host. */
+    hostStopsItself?: boolean;
+    /** How long the runtime had answered nothing when the caller stopped it; the stop is metered as unresponsive and the stopped lease says so. */
+    unresponsiveForMs?: number;
 };
 export type SandboxCheckpointRestoreInput = {
     runtime: SandboxCheckpointRuntime;
@@ -34,10 +47,22 @@ export declare function captureSandboxCheckpoint(input: {
     request: SandboxCheckpointCaptureInput;
     leaseStore: SandboxLeaseStore;
     target: (workspaceId: string) => Promise<SandboxTargetResult>;
-    snapshot: (workspaceId: string) => Promise<SandboxSnapshotManagerResult>;
+    snapshot: (workspaceId: string, committed?: string) => Promise<SandboxSnapshotManagerResult>;
+    deleteSnapshot?: (target: SandboxResource, snapshotId: string) => Promise<void>;
+    /**
+     * The capture ends this lease: its commit stops it, recording `stoppedError`
+     * as why, and the runtime stays frozen for the host stop that follows. A
+     * runtime that does not freeze is captured unfrozen, since its host stops
+     * either way; only an idle stop is the runtime's to refuse.
+     */
+    endsLease?: {
+        stoppedError?: string;
+    };
     now?: () => number;
     checkpointId?: () => string;
 }): Promise<SandboxCheckpointResult>;
+/** Deletes a provider snapshot no lease references; a failure leaks storage, never the checkpoint just taken. */
+export declare function discardSnapshot(discard: ((target: SandboxResource, snapshotId: string) => Promise<void>) | undefined, target: SandboxResource, snapshotId: string): Promise<void>;
 export declare function restoreSandboxCheckpoint(input: {
     workspaceId: string;
     request: SandboxCheckpointRestoreInput;

package/dist/checkpoint-manager.mjs

@@ -1,18 +1,95 @@
+// ../claxedo-helpers/dist/api-error.mjs
+var PUBLIC_API_ERRORS = {
+  repository_provider_unauthorized: { status: 502, message: "Repository provider refused authorization" },
+  repository_provider_unavailable: { status: 502, message: "Repository provider is unavailable" },
+  host_tunnel_timeout: { status: 503, retryable: true, message: "Host tunnel timed out" },
+  host_tunnel_response_body_too_large: { status: 413, message: "Host tunnel response body exceeds the relay limit" },
+  host_tunnel_unavailable: { status: 503, retryable: true, message: "Host tunnel is unavailable" },
+  workspace_checkpoint_unavailable: { status: 503, retryable: true, message: "Workspace checkpoint is unavailable" },
+  workspace_checkpoint_conflict: { status: 409, message: "Workspace checkpoint conflicted" },
+  invalid_input: { family: "access", status: 400, message: "The request names an invalid value" },
+  organization_policy_denied: { family: "access", status: 403, message: "Organization creation is disabled for this deployment" },
+  org_admin_required: { family: "access", status: 403, message: "Organization administrator authority is required" },
+  org_owner_required: { family: "access", status: 403, message: "Only an organization owner may grant, change or remove the owner role" },
+  org_owner_protected: { family: "access", status: 409, message: "The organization's founding owner cannot be removed or demoted" },
+  team_member_org_membership_required: { family: "access", status: 403, message: "The team member must belong to the team organization" },
+  project_member_org_membership_required: { family: "access", status: 403, message: "The project member must belong to the project organization" },
+  org_membership_required: { family: "access", status: 403, message: "Organization membership is required" },
+  project_admin_required: { family: "access", status: 403, message: "Project administrator authority is required" },
+  team_not_allowed_on_personal_org: { family: "access", status: 400, message: "Personal organizations cannot contain teams" },
+  team_member_target_required: { family: "access", status: 400, message: "Exactly one team member target is required" },
+  org_invitation_invalid: { family: "access", status: 409, message: "Invitation is invalid or unavailable" },
+  org_invitation_pending: { family: "access", status: 409, message: "An invitation to this address is already pending" },
+  org_invitation_rate_limited: { family: "access", status: 429, message: "Organization invitation limit exceeded" },
+  org_invitation_email_mismatch: { family: "access", status: 403, message: "Sign in with the invited verified email address" },
+  org_invitation_delivery_unavailable: { family: "access", status: 503, message: "Invitation delivery is unavailable" },
+  team_not_found: { family: "access", status: 404, message: "Team not found" },
+  team_member_not_found: { family: "access", status: 404, message: "Team member not found" },
+  org_member_not_found: { family: "access", status: 404, message: "Organization member not found" },
+  project_not_found: { family: "access", status: 404, message: "Project not found" },
+  project_member_not_found: { family: "access", status: 404, message: "Project member not found" },
+  project_member_owner_immutable: { family: "access", status: 409, message: "The project owner's access cannot be changed" },
+  resource_conflict: { family: "access", status: 409, message: "Organization or team authority changed concurrently" },
+  session_not_found: { family: "session_share", status: 404, message: "This session is not on the control plane, so it cannot be shared from People yet." },
+  session_share_admin_required: { family: "session_share", status: 403, message: "Only the person who started this session can manage its People." },
+  session_share_target_required: { family: "session_share", status: 400, message: "A session is shared with exactly one person" },
+  session_share_target_not_found: { family: "session_share", status: 404, message: "That person was not found in this organization." },
+  session_share_level_invalid: { family: "session_share", status: 400, message: "A share level is either follow or send." },
+  workspace_backing_conflict: { status: 409, message: "Workspace is provisioned in the cloud and cannot be placed on a machine" },
+  invalid_session_list_cursor: { status: 400, message: "Session list cursor does not match this query" },
+  BAD_REQUEST: { status: 400, message: "Invalid request" },
+  INTERNAL_SERVER_ERROR: { status: 500, message: "Internal error" },
+  CONTROL_PLANE_UNAVAILABLE: { status: 503, message: "Control Plane services are not configured" },
+  credential_verification_unsupported: { status: 400, message: "Credential provider does not support verification" },
+  credential_shape_invalid: { status: 400, message: "Credential secret has an unsupported shape" },
+  credential_provider_unavailable: { status: 502, retryable: true, message: "Credential provider request failed" },
+  credential_verification_failed: { status: 502, message: "Credential provider verification failed" },
+  credential_redirect_denied: { status: 502, message: "Sandbox provider redirects are not allowed" },
+  credential_endpoint_invalid: { status: 400, message: "Invalid credential provider endpoint" },
+  host_attestation_denied: { status: 403, message: "host_attestation_denied" },
+  signature_replayed: { status: 409, message: "signature_replayed" },
+  host_enrollment_not_found: { status: 404, message: "host_enrollment_not_found" },
+  enrollment_revoked: { status: 403, message: "enrollment_revoked" },
+  enrollment_paused: { status: 403, message: "enrollment_paused" },
+  enrollment_owner_ineligible: { status: 403, message: "enrollment_owner_ineligible" },
+  enrollment_key_version_mismatch: { status: 403, message: "enrollment_key_version_mismatch" },
+  invitation_invalid: { status: 403, message: "invitation_invalid" },
+  invitation_expired: { status: 410, message: "invitation_expired" },
+  invitation_revoked: { status: 410, message: "invitation_revoked" },
+  invitation_redeemed: { status: 409, message: "invitation_redeemed" },
+  invitation_host_conflict: { status: 409, message: "invitation_host_conflict" },
+  enrollment_generation_superseded: { status: 409, message: "enrollment_generation_superseded" },
+  host_assignment_outside_scope: { status: 400, message: "host_assignment_outside_scope" },
+  host_sealing_key_undeclared: { status: 409, message: "host_sealing_key_undeclared" },
+  host_provider_config_revision_stale: { status: 409, message: "host_provider_config_revision_stale" },
+  identity_conflict: { status: 409, message: "identity_conflict" },
+  registration_transition_denied: { status: 403, message: "registration_transition_denied" },
+  session_reservation_spent: { status: 409, message: "This session's create was undone; reserve it again to retry" },
+  actor_authorization_denied: { status: 403, message: "actor_authorization_denied" }
+};
+function publicApiErrorShape(code) {
+  const entry = PUBLIC_API_ERRORS[code];
+  return { status: entry.status, retryable: entry.retryable === true };
+}
+function publicApiFailure(code, message = PUBLIC_API_ERRORS[code].message) {
+  return Object.assign(new Error(message), { code, ...publicApiErrorShape(code) });
+}
+
 // src/checkpoint-manager.ts
 async function captureSandboxCheckpoint(input) {
   const lease = await requireLease(input.leaseStore, input.workspaceId);
-  if (lease.status !== "ready") throw new Error("workspace_checkpoint_lease_not_ready");
+  if (lease.status !== "ready") throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_lease_not_ready");
   const persistence = lease.persistence;
-  if (!persistence || persistence.capture === "none") throw new Error("workspace_checkpoint_unsupported");
+  if (!persistence || persistence.capture === "none") throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_unsupported");
   const target = await input.target(input.workspaceId);
-  if (target.status !== "ready") throw new Error(target.reason);
-  await input.request.runtime.freeze(input.request.policy ?? "drain");
+  if (target.status !== "ready") throw publicApiFailure("workspace_checkpoint_unavailable", target.reason);
+  const discard = persistence.capture === "same-resource" ? void 0 : input.deleteSnapshot;
   let capturedSource = false;
+  let result;
   try {
-    await input.request.runtime.flush();
-    await input.request.runtime.scrub();
-    const captured = persistence.capture === "same-resource" ? { ok: true, snapshotId: target.driverResourceId ?? target.sandboxId } : await input.snapshot(input.workspaceId);
-    if (!captured.ok) throw new Error(captured.reason);
+    const frozen = await freezeForCapture(input.request, input.endsLease !== void 0, input.workspaceId);
+    const captured = persistence.capture === "same-resource" ? { ok: true, snapshotId: target.driverResourceId ?? target.sandboxId } : await input.snapshot(input.workspaceId, (await input.leaseStore.get(input.workspaceId))?.checkpoint?.providerReference);
+    if (!captured.ok) throw publicApiFailure("workspace_checkpoint_conflict", captured.reason);
     capturedSource = true;
     const capturedAt = (input.now ?? Date.now)();
     const checkpoint = {
@@ -23,28 +100,59 @@ async function captureSandboxCheckpoint(input) {
       metadata: {
         scope: persistence.capture,
         sourceBehavior: requireCaptureSource(persistence.captureSource),
-        ...input.request.retentionExpiresAt === void 0 ? {} : { retentionExpiresAt: input.request.retentionExpiresAt },
-        restoreMount: requireRestoreMount(persistence.restoreMount)
+        restoreMount: requireRestoreMount(persistence.restoreMount),
+        ...frozen ? {} : { unfrozen: true }
       }
     };
+    const replaced = (await input.leaseStore.get(input.workspaceId))?.checkpoint;
     const updated = await input.leaseStore.update(input.workspaceId, lease.epoch, {
       checkpoint,
       restore: null,
-      ...persistence.captureSource === "stopped" || persistence.captureSource === "deleted" ? { status: "stopped" } : {}
+      ...input.endsLease?.stoppedError ? { lastError: input.endsLease.stoppedError } : {},
+      ...input.endsLease || persistence.captureSource === "stopped" || persistence.captureSource === "deleted" ? { status: "stopped" } : {}
     });
-    if (!updated) throw new Error("workspace_checkpoint_epoch_fenced");
-    return { status: "ready", lease: updated, checkpoint };
-  } finally {
-    if (!capturedSource || persistence.captureSource === "preserved") {
-      await input.request.runtime.resume();
+    if (!updated) {
+      await discardSnapshot(discard, target, captured.snapshotId);
+      throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_epoch_fenced");
     }
+    if (replaced && replaced.providerReference !== captured.snapshotId) {
+      await discardSnapshot(discard, target, replaced.providerReference);
+    }
+    result = { status: "ready", lease: updated, checkpoint };
+  } catch (error) {
+    if (!capturedSource || persistence.captureSource === "preserved") await thawAfterFailure(input.request.runtime, input.workspaceId);
+    throw error;
   }
+  if (!input.endsLease && persistence.captureSource === "preserved") await input.request.runtime.resume();
+  return result;
+}
+async function freezeForCapture(request, endsLease, workspaceId) {
+  try {
+    await request.runtime.freeze(request.policy ?? "drain", { idleBefore: request.idleBefore });
+    await request.runtime.flush();
+    await request.runtime.scrub();
+    return true;
+  } catch (error) {
+    if (!endsLease || request.idleBefore !== void 0) throw error;
+    console.warn("A stopping sandbox's runtime did not freeze; its files are captured as they are", { workspaceId, error: String(error) });
+    return false;
+  }
+}
+async function thawAfterFailure(runtime, workspaceId) {
+  await runtime.resume().catch((error) => {
+    console.warn("A runtime was not thawed after its capture failed", { workspaceId, error: String(error) });
+  });
+}
+async function discardSnapshot(discard, target, snapshotId) {
+  await discard?.(target, snapshotId).catch((error) => {
+    console.warn("A superseded sandbox snapshot could not be deleted", { workspaceId: target.workspaceId, snapshotId, error: String(error) });
+  });
 }
 async function restoreSandboxCheckpoint(input) {
   const lease = await requireLease(input.leaseStore, input.workspaceId);
   const checkpoint = lease.checkpoint;
   if (!checkpoint || input.request.checkpointId && checkpoint.id !== input.request.checkpointId) {
-    throw new Error("workspace_checkpoint_not_found");
+    throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_not_found");
   }
   if (lease.restore?.state === "ready" && lease.restore.checkpointId === checkpoint.id) {
     return { status: "ready", lease, checkpoint };
@@ -58,7 +166,7 @@ async function restoreSandboxCheckpoint(input) {
     startedAt: (input.now ?? Date.now)()
   };
   const staged = lease.status === "ready" && lease.epoch === checkpoint.sourceEpoch ? await input.leaseStore.update(input.workspaceId, lease.epoch, { status: "stopped", restore: restoring }) : await input.leaseStore.update(input.workspaceId, lease.epoch, { restore: restoring });
-  if (!staged) throw new Error("workspace_restore_epoch_fenced");
+  if (!staged) throw publicApiFailure("workspace_checkpoint_conflict", "workspace_restore_epoch_fenced");
   const result = await input.ensure(input.workspaceId, {
     homeRegion: staged.homeRegion,
     ...input.request.ensure,
@@ -81,7 +189,7 @@ async function restoreSandboxCheckpoint(input) {
         error: result.error ?? "workspace_restore_unavailable"
       }
     });
-    throw new Error(result.error ?? "workspace_restore_unavailable");
+    throw publicApiFailure("workspace_checkpoint_unavailable", result.error ?? "workspace_restore_unavailable");
   }
   await input.request.runtime.reconcile({ epoch: result.epoch, checkpointId: checkpoint.id });
   const ready = await input.leaseStore.update(input.workspaceId, result.epoch, {
@@ -94,23 +202,24 @@ async function restoreSandboxCheckpoint(input) {
       completedAt: (input.now ?? Date.now)()
     }
   });
-  if (!ready) throw new Error("workspace_restore_epoch_fenced");
+  if (!ready) throw publicApiFailure("workspace_checkpoint_conflict", "workspace_restore_epoch_fenced");
   return { status: "ready", lease: ready, checkpoint };
 }
 async function requireLease(store, workspaceId) {
   const lease = await store.get(workspaceId);
-  if (!lease) throw new Error("workspace_checkpoint_lease_missing");
+  if (!lease) throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_lease_missing");
   return lease;
 }
 function requireCaptureSource(value) {
   if (value === "preserved" || value === "stopped" || value === "deleted") return value;
-  throw new Error("workspace_checkpoint_capabilities_invalid");
+  throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_capabilities_invalid");
 }
 function requireRestoreMount(value) {
-  if (value === "same-resource" || value === "copy-on-write" || value === "new-resource") return value;
-  throw new Error("workspace_checkpoint_capabilities_invalid");
+  if (value === "same-resource" || value === "new-resource") return value;
+  throw publicApiFailure("workspace_checkpoint_conflict", "workspace_checkpoint_capabilities_invalid");
 }
 export {
   captureSandboxCheckpoint,
+  discardSnapshot,
   restoreSandboxCheckpoint
 };

package/dist/command.d.ts

@@ -1,3 +1,10 @@
 export declare function shell(input: string): string;
-export declare function file(...parts: string[]): string;
-export declare function env(input: Record<string, string>): string;
+/**
+ * Env rendered as a sourceable script (one `export KEY='value'` line per entry)
+ * so drivers can deliver it through a provider file channel and have the
+ * workload source it, instead of serializing values into exec argv where
+ * command logs and process listings expose them. Names that `export` cannot
+ * carry are refused outright — silently dropping them would boot the runtime
+ * missing configuration.
+ */
+export declare function envFile(input: Record<string, string>): string;