@claxedo/sandbox-manager 0.6.0 → 0.9.0

package/dist/image-name.mjs

@@ -0,0 +1,34 @@
+// src/runtime-version.ts
+var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+function workspaceRuntimeVersion() {
+  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
+}
+
+// src/image-name.ts
+var SNAPSHOT_SCHEMA_VERSION = 8;
+var DEFAULT_SANDBOX_IMAGE_REPOSITORY = "ghcr.io/kyashrathore/claxedo-sandbox";
+function snapshotVersion(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function sandboxImageRepository(env = process.env) {
+  const repository = env.CLAXEDO_SANDBOX_IMAGE_REPOSITORY?.trim();
+  return repository ? repository : DEFAULT_SANDBOX_IMAGE_REPOSITORY;
+}
+function buildIdSuffix(buildId, env) {
+  const id = (buildId ?? env.CLAXEDO_SANDBOX_BUILD_ID)?.trim();
+  return id ? `-${snapshotVersion(id)}` : "";
+}
+function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env) {
+  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+}
+function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env = process.env) {
+  return `claxedo-workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+}
+export {
+  DEFAULT_SANDBOX_IMAGE_REPOSITORY,
+  SNAPSHOT_SCHEMA_VERSION,
+  defaultSandboxImage,
+  defaultSnapshotName,
+  sandboxImageRepository,
+  snapshotVersion
+};

package/dist/image.d.ts

@@ -1,8 +1,23 @@
-import { Daytona, Image } from "@daytona/sdk";
+import type { Daytona, Image } from "@daytona/sdk";
 export { RUNTIME_DIR, WORKSPACE_RUNTIME_PORT, WORKSPACE_DIR } from "./defaults";
 export { SNAPSHOT_SCHEMA_VERSION, snapshotVersion, defaultSandboxImage, defaultSnapshotName, } from "./image-name";
+/**
+ * Sink for snapshot-build progress. Every message here reports a long
+ * operation an operator is actively waiting on — a snapshot build takes
+ * minutes, and the Daytona builder's `onLogs` stream is the only view into
+ * whether it is progressing or wedged.
+ *
+ * Defaults to `console.info`, deliberately unconditional: the same reasoning as
+ * `onEgressUnenforced` in index.ts — someone who never wires a sink still sees
+ * the build. Pass your own to route it into a logger; pass `() => {}` only if
+ * you have another way to observe the build.
+ */
+export type SandboxImageLogSink = (message: string, context?: Record<string, unknown>) => void;
+export type SandboxImageOptions = {
+    log?: SandboxImageLogSink;
+};
 export declare const SANDBOX_IMAGE_REPOSITORY: string;
 export declare const SANDBOX_IMAGE: string;
 export declare const SNAPSHOT_NAME: string;
-export declare function buildSandboxImage(): Image;
-export declare function ensureSnapshot(daytona: Daytona): Promise<string>;
+export declare function buildSandboxImage(): Promise<Image>;
+export declare function ensureSnapshot(daytona: Daytona, options?: SandboxImageOptions): Promise<string>;

package/dist/image.mjs

@@ -1,6 +1,3 @@
-// src/image.ts
-import { Image, DaytonaNotFoundError } from "@daytona/sdk";
-
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
@@ -11,16 +8,8 @@ var RUNTIME_DIR = "/opt/workspace-runtime";
 
 // src/runtime-version.ts
 var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
-var versionCache;
 function workspaceRuntimeVersion() {
-  if (versionCache) return versionCache;
-  const envVersion = process.env.WORKSPACE_RUNTIME_VERSION;
-  if (envVersion) {
-    versionCache = envVersion;
-    return versionCache;
-  }
-  versionCache = DEFAULT_WORKSPACE_RUNTIME_VERSION;
-  return versionCache;
+  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
 
 // src/image-name.ts
@@ -44,61 +33,87 @@ function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env =
   return `claxedo-workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
 }
 
+// ../claxedo-helpers/dist/guards.mjs
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+
+// src/json.ts
+function text(input) {
+  return typeof input === "string" && input.length > 0 ? input : void 0;
+}
+
 // src/image.ts
-var log = {
-  info(_message, _context) {
-  }
-};
+function defaultImageLogSink(message, context) {
+  if (context) console.info(message, context);
+  else console.info(message);
+}
 var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
 var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
 var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
-function buildSandboxImage() {
+async function buildSandboxImage() {
+  const { Image } = await import("@daytona/sdk");
   return Image.base(SANDBOX_IMAGE);
 }
 function snapshotUsable(state) {
   return state === "ready" || state === "active";
 }
-async function createSnapshot(daytona) {
-  log.info("Creating sandbox snapshot (this may take a few minutes)...", { name: SNAPSHOT_NAME });
+function snapshotView(input) {
+  const row = asRecord(input) ?? {};
+  return { id: text(row.id), state: text(row.state), errorReason: text(row.errorReason) };
+}
+async function activateSnapshot(snapshots, id) {
+  const activate = asRecord(snapshots)?.activate;
+  if (typeof activate !== "function") throw new Error("Daytona SDK does not support snapshot activation");
+  await activate.call(snapshots, { id });
+}
+async function createSnapshot(daytona, log) {
+  log("Creating sandbox snapshot (this may take a few minutes)...", { name: SNAPSHOT_NAME });
   await daytona.snapshot.create(
-    { name: SNAPSHOT_NAME, image: buildSandboxImage() },
+    { name: SNAPSHOT_NAME, image: await buildSandboxImage() },
     {
       timeout: 120,
-      onLogs: (chunk) => log.info("[snapshot]", { text: chunk })
+      onLogs: (chunk) => log("[snapshot]", { text: chunk })
     }
   );
   return SNAPSHOT_NAME;
 }
-async function ensureSnapshot(daytona) {
+async function ensureSnapshot(daytona, options = {}) {
+  const log = options.log ?? defaultImageLogSink;
   try {
-    const existing = await daytona.snapshot.get(SNAPSHOT_NAME);
+    const existing = snapshotView(await daytona.snapshot.get(SNAPSHOT_NAME));
     if (existing.state === "inactive") {
-      log.info("Snapshot is inactive, reactivating...", { name: SNAPSHOT_NAME, id: existing.id });
-      await daytona.snapshot.activate({ id: existing.id });
+      log("Snapshot is inactive, reactivating...", { name: SNAPSHOT_NAME, id: existing.id });
+      if (!existing.id) throw new Error("Daytona snapshot is inactive but reports no id to activate");
+      await activateSnapshot(daytona.snapshot, existing.id);
       for (let i = 0; i < 120; i++) {
-        const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
+        const snap = snapshotView(await daytona.snapshot.get(SNAPSHOT_NAME));
         if (snapshotUsable(snap.state)) return SNAPSHOT_NAME;
-        if (snap.state === "error") throw new Error(`Snapshot activation failed: ${snap.errorReason}`);
+        if (snap.state === "error") throw new Error(`Snapshot activation failed: ${snap.errorReason ?? "unknown"}`);
         await new Promise((resolve) => setTimeout(resolve, 2e3));
       }
       throw new Error("Snapshot activation timed out");
     }
     if (existing.state === "building") {
-      log.info("Snapshot is building, waiting (up to 10 min)...", { name: SNAPSHOT_NAME });
+      log("Snapshot is building, waiting (up to 10 min)...", { name: SNAPSHOT_NAME });
       for (let i = 0; i < 300; i++) {
-        const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
+        const snap = snapshotView(await daytona.snapshot.get(SNAPSHOT_NAME));
         if (snapshotUsable(snap.state)) return SNAPSHOT_NAME;
-        if (snap.state === "error") throw new Error(`Snapshot build failed: ${snap.errorReason}`);
-        if (i % 15 === 0) log.info("Still waiting for snapshot...", { state: snap.state, elapsed: `${i * 2}s` });
+        if (snap.state === "error") throw new Error(`Snapshot build failed: ${snap.errorReason ?? "unknown"}`);
+        if (i % 15 === 0) log("Still waiting for snapshot...", { state: snap.state, elapsed: `${i * 2}s` });
         await new Promise((resolve) => setTimeout(resolve, 2e3));
       }
       throw new Error("Snapshot build timed out after 10 minutes");
     }
     return SNAPSHOT_NAME;
   } catch (err) {
+    const { DaytonaNotFoundError } = await import("@daytona/sdk");
     if (!(err instanceof DaytonaNotFoundError)) throw err;
   }
-  return createSnapshot(daytona);
+  return createSnapshot(daytona, log);
 }
 export {
   RUNTIME_DIR,

package/dist/index.d.ts

@@ -1,8 +1,65 @@
 import { DEFAULT_WORKSPACE_RUNTIME_PORT } from "./constants";
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID, SandboxSecretBrokering } from "@claxedo/sandbox-contract";
+export type { SandboxSecretBrokering } from "@claxedo/sandbox-contract";
+import { type SandboxCheckpointCaptureInput, type SandboxCheckpointRestoreInput, type SandboxCheckpointResult } from "./checkpoint-manager";
 export { DEFAULT_WORKSPACE_RUNTIME_PORT };
+export * from "./checkpoint-manager";
+export * from "./hosted-network-policy";
 export type SandboxRegion = string;
 export type SandboxDriverId = SandboxDriverID | "fetch";
+export type SandboxCaptureScope = "none" | "same-resource" | "filesystem" | "directories";
+export type SandboxCaptureSourceBehavior = "not-applicable" | "preserved" | "stopped" | "deleted";
+export type SandboxRestoreMountBehavior = "not-applicable" | "same-resource" | "copy-on-write" | "new-resource";
+export type SandboxPersistenceCapabilities = {
+    resume: "same-sandbox" | "replacement-restore";
+    capture: SandboxCaptureScope;
+    clone: boolean;
+    captureSource: SandboxCaptureSourceBehavior;
+    retention: "not-applicable" | "provider-managed" | "explicit";
+    restoreMount: SandboxRestoreMountBehavior;
+};
+export declare function validateSandboxPersistenceCapabilities(input: SandboxPersistenceCapabilities): {
+    valid: false;
+    reason: string;
+} | {
+    reason?: undefined;
+    valid: true;
+};
+export type SandboxCheckpointReference = {
+    id: string;
+    providerReference: string;
+    sourceEpoch: number;
+    capturedAt: number;
+    metadata: {
+        scope: Exclude<SandboxCaptureScope, "none">;
+        sourceBehavior: Exclude<SandboxCaptureSourceBehavior, "not-applicable">;
+        retentionExpiresAt?: number;
+        restoreMount: Exclude<SandboxRestoreMountBehavior, "not-applicable">;
+    };
+};
+type SandboxRestoreIdentity = {
+    checkpointId: string;
+    sourceEpoch: number;
+};
+export type SandboxRestoreStatus = (SandboxRestoreIdentity & {
+    state: "pending";
+    requestedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "restoring";
+    requestedAt: number;
+    startedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "ready";
+    requestedAt: number;
+    startedAt: number;
+    completedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "failed";
+    requestedAt: number;
+    startedAt?: number;
+    failedAt: number;
+    error: string;
+});
 export type SandboxDriverMetadata = {
     /** Where the sandbox driver code can execute. This is not sandbox infrastructure. */
     driverRunsIn: Array<"worker" | "node" | "local">;
@@ -16,25 +73,110 @@ export type SandboxDriverMetadata = {
      * How the driver can honor a `SandboxBrokeredSecret` — a credential the
      * sandbox may USE for outbound requests but must NEVER be able to READ.
      *
-     * - `"native"` — the provider brokers it automatically on egress to the
-     *   allowlisted hosts, with no extra infrastructure: Daytona secret
-     *   placeholders + egress proxy; Vercel firewall header transforms. The
-     *   driver injects it during `ensureHost`.
-     * - `"proxy"` — brokering is achievable but only via a host-operated egress
-     *   proxy the driver routes through (Cloudflare's official Worker-proxy
-     *   pattern: the sandbox gets a short-lived JWT, egress hits the Worker,
-     *   the Worker injects the real credential — the raw value never enters the
-     *   sandbox). Not automatic; requires the host's proxy to be wired.
+     * - `"native"` — the provider brokers it on egress to the allowlisted hosts
+     *   with no extra infrastructure of ours: Daytona secret placeholders,
+     *   Vercel firewall header transforms, Cloudflare outbound handlers reading
+     *   the value from KV. The driver installs it during `ensureHost`.
      * - `"none"` — no way to keep the value out of sandbox processes. The
      *   provider may still have an encrypted secret STORE (e.g. Modal secrets),
-     *   but those are exposed as readable env vars, so they cannot satisfy the
+     *   but it is exposed as a readable env var, which cannot satisfy the
      *   never-readable contract.
+     */
+    secretBrokering: SandboxSecretBrokering;
+    /**
+     * How the driver can enforce a RESTRICTED `SandboxNetworkPolicy` — i.e.
+     * whether the sandbox's outbound network can actually be contained.
+     *
+     * A `SandboxNetworkPolicy` states the same allowance in up to two encodings:
+     * `hosts` (names) and `cidrs` (addresses). A driver contains egress if it
+     * enforces AT LEAST ONE encoding the policy carries and blocks everything
+     * else; the encodings are alternatives, not additive requirements.
+     *
+     * - `"hosts-and-cidrs"` — the provider filters by name AND by address
+     *   (Daytona: `domainAllowList` + `networkAllowList`).
+     * - `"hosts"` — the provider filters by hostname only (Vercel firewall).
+     * - `"none"` — the driver cannot express an egress allowlist. This covers
+     *   BOTH drivers that throw when handed a restricted policy (exe, docker,
+     *   box, and modal for host policy) AND — more dangerously — drivers that
+     *   silently ignore `net` and run wide open (cloudflare, the fetch bridge).
+     *   Modal is `"none"` even though it can cut the network entirely: a total
+     *   blackout is not an allowlist and cannot serve a workspace that has to
+     *   clone a repo and reach a model provider.
      *
-     * The manager fails closed unless the driver actually injects brokered
-     * secrets (today: `"native"` only). `"proxy"` records an achievable ceiling
-     * that is not yet wired and therefore also fails closed.
+     * The manager reads this to decide what the driver is handed:
+     * `sandboxEgressDisposition` enforces where it can and WITHHOLDS (loudly)
+     * where it cannot. See `SandboxEgressDisposition` for the posture and
+     * `public-docs/sandbox-egress.md` for the operator-facing consequence.
      */
-    secretBrokering: "native" | "proxy" | "none";
+    egressControl: SandboxEgressControl;
+    persistence: SandboxPersistenceCapabilities;
+};
+/** @see SandboxDriverMetadata.egressControl */
+export type SandboxEgressControl = "none" | "hosts" | "hosts-and-cidrs";
+/**
+ * What the manager does with a caller's `net` for a given driver.
+ *
+ * Owner directive (2026-07-28): *"for egress in sandbox enforce where we can
+ * and document where we cant."* That replaces the previous fail-closed refusal
+ * for drivers with no egress control at all — provisioning now proceeds, and
+ * the gap is made loud instead of fatal.
+ *
+ *  - `"enforce"` — the driver gets the policy verbatim and contains the
+ *    sandbox. Also the answer when the caller asked for no containment
+ *    (absent / `allow-all`), which is nothing to enforce.
+ *  - `"withhold"` — the driver declares `egressControl: "none"`, so there is no
+ *    containment to be had. The policy is NOT handed down: half the `"none"`
+ *    drivers throw on a restricted policy (exe, docker, modal, box) and the
+ *    other half silently drop it (cloudflare, the fetch bridge). Withholding at
+ *    the manager means the throwing drivers never see one — their throws stay
+ *    in place as their own last line of defence — and the silently-dropping
+ *    ones stop pretending. The sandbox comes up with UNRESTRICTED egress, which
+ *    is a real exposure, so the manager warns (see `onEgressUnenforced`).
+ *  - `"refuse"` — the driver HAS egress control but cannot express this
+ *    particular policy's encoding (a hosts-only driver handed an address-only
+ *    allowlist). Deliberately still fail-closed: this is a composition mistake
+ *    on an otherwise-enforcing driver, and degrading it to "withhold" would
+ *    weaken the enforcing path. `hostedSandboxNetworkPolicy` only ever emits
+ *    hosts, so no production path reaches it.
+ *
+ * Pure, like `validateSandboxPersistenceCapabilities`, so the manager, the
+ * composition layer, and tests can all ask the same question.
+ */
+export type SandboxEgressDisposition = {
+    action: "enforce";
+} | {
+    action: "withhold";
+    reason: "sandbox_egress_uncontained";
+} | {
+    action: "refuse";
+    reason: "sandbox_egress_policy_unenforceable";
+};
+/** @see SandboxEgressDisposition */
+export declare function sandboxEgressDisposition(control: SandboxEgressControl, net: SandboxNetworkPolicy | undefined): SandboxEgressDisposition;
+/**
+ * Emitted whenever a restricted egress policy is withheld because the composed
+ * driver declares no egress control. This is the "document where we can't" half
+ * of the directive expressed at runtime: an unrestricted sandbox that nobody
+ * was told about is the original finding, so the degrade is never silent.
+ *
+ * Two phases, because a per-create line is easy to miss in request logs:
+ *  - `"composition"` — once per `createSandboxManager` per driver, at boot.
+ *  - `"ensure"` — every time a caller's policy is actually withheld, naming the
+ *    workspace and the allowlist that did not take effect.
+ */
+export type SandboxEgressUnenforcedEvent = {
+    phase: "composition" | "ensure";
+    reason: "sandbox_egress_uncontained";
+    /** `SandboxDriver.id` of the composed driver. */
+    driver: string;
+    /** Always `"none"` today — carried so a sink can group without re-deriving. */
+    egressControl: SandboxEgressControl;
+    /** Ready-to-log sentence. Sinks that only forward text can use this alone. */
+    message: string;
+    /** Present on `"ensure"`. */
+    workspaceId?: string;
+    /** The allowlist the caller asked for and did NOT get. Present on `"ensure"`. */
+    requested?: SandboxNetworkPolicy;
 };
 /**
  * A credential the SANDBOX must be able to USE for outbound requests but must
@@ -46,7 +188,7 @@ export type SandboxDriverMetadata = {
  *
  * Guarantees enforced by the manager: brokered secrets are never written to
  * labels, never logged, and never captured in a driver snapshot. A driver
- * whose `metadata.secretBrokering !== "native"` cannot honor them and the
+ * whose `metadata.secretBrokering` is not `"native"` cannot honor them and the
  * manager refuses to provision (fail-closed).
  */
 export type SandboxBrokeredSecret = {
@@ -63,7 +205,49 @@ export type SandboxBrokeredSecret = {
      * the sandbox to attach itself (Daytona).
      */
     header?: string;
+    /**
+     * The authentication scheme `header` carries, when it has one (`Bearer`).
+     *
+     * A driver that WRITES the whole header composes `"<scheme> <value>"`; one
+     * that SUBSTITUTES a placeholder the sandbox already wrote after the scheme
+     * ignores it, because the scheme is in the request before the value is.
+     */
+    scheme?: string;
+    /**
+     * The methods and path prefixes the credential may be attached to, on top of
+     * `hosts`. A vendor host serves far more than the routes a turn needs —
+     * api.anthropic.com also answers the organization-admin API — and everything
+     * sharing the sandbox reaches the same host.
+     *
+     * Optional so a producer that has not been taught to state a policy still
+     * type-checks, and fails closed instead: a driver that can express them
+     * attaches the credential only within them, so an absent or empty policy
+     * names a host and nothing else, and nothing is spendable at a host alone. A
+     * driver whose provider cannot express them documents that it drops them,
+     * and the host allowlist is all the containment there is.
+     */
+    methods?: readonly string[];
+    pathPrefixes?: readonly string[];
 };
+/**
+ * What the sandbox presents so a header-injecting driver recognizes the request
+ * as one asking for that secret.
+ *
+ * Carries no authority: the value is attached at the edge, keyed by the host
+ * and this string, and the string itself is never accepted by a vendor. The
+ * Cloudflare sandbox Worker is deployed on its own and cannot depend on this
+ * package, so it matches on its own copy of the prefix; a driver minting
+ * anything else sends every brokered request upstream bare, which is what
+ * `brokered-placeholder.test.ts` exists to catch.
+ */
+export declare function brokeredSecretPlaceholder(name: string): string;
+/**
+ * The environment a header-injecting driver must add so the sandbox can present
+ * each secret. Daytona is absent from this: its own mount fills the same
+ * variables with the placeholder it substitutes, and an env entry would shadow
+ * it with a string Daytona does not know.
+ */
+export declare function brokeredPlaceholderEnv(secrets: readonly SandboxBrokeredSecret[] | undefined): Record<string, string>;
 export type SandboxExposure = {
     kind: "loopback";
 } | {
@@ -92,6 +276,9 @@ export type SandboxLease = {
     lastHeartbeatAt?: number;
     lastActivityAt?: number;
     labels?: Record<string, string>;
+    checkpoint?: SandboxCheckpointReference;
+    persistence?: SandboxPersistenceCapabilities;
+    restore?: SandboxRestoreStatus;
 };
 export type SandboxLeaseAcquireInput = {
     homeRegion: SandboxRegion;
@@ -112,6 +299,12 @@ export type SandboxLeasePatch = Partial<Pick<SandboxLease, "status" | "sandboxId
     nextRetryAt?: number | null;
     /** `null` clears the stored value; `undefined` leaves it unchanged. */
     lastError?: string | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    checkpoint?: SandboxCheckpointReference | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    persistence?: SandboxPersistenceCapabilities | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    restore?: SandboxRestoreStatus | null;
 };
 /**
  * Canonical SandboxLeasePatch merge semantics shared by every lease store driver:
@@ -131,6 +324,8 @@ export type SandboxNetworkPolicy = {
     hosts?: string[];
     cidrs?: string[];
 };
+/** Brokered destinations are the minimum egress needed to use the credential. */
+export declare function sandboxNetworkPolicyWithBrokeredHosts(policy: SandboxNetworkPolicy, secrets: readonly SandboxBrokeredSecret[] | undefined): SandboxNetworkPolicy;
 export type SandboxBootSource = {
     kind: "image";
     image: string;
@@ -162,7 +357,16 @@ export type SandboxDriverEnsureInput = {
     secrets?: SandboxBrokeredSecret[];
     source?: SandboxSource;
     exposure?: SandboxExposure;
-    /** Optional egress policy (allow-all when omitted). */
+    /**
+     * Egress policy. Omitted means allow-all, which is only appropriate for a
+     * single-tenant deployment the operator already trusts.
+     *
+     * A driver can rely on this being ABSENT whenever it declares
+     * `egressControl: "none"`: the manager withholds the policy rather than hand
+     * it to a driver that would either throw on it or silently drop it. A driver
+     * that receives a restricted policy here is one that declared it can enforce
+     * it. @see SandboxEgressDisposition
+     */
     net?: SandboxNetworkPolicy;
     /** Optional snapshot/image to boot from (user-supplied or pre-built). */
     snapshot?: string;
@@ -183,6 +387,11 @@ export type SandboxTarget = {
 export type SandboxSnapshotResult = {
     snapshotId: string;
 };
+export type SandboxCommandResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
 export type SandboxDriver = {
     id: string;
     metadata: SandboxDriverMetadata;
@@ -203,6 +412,11 @@ export type SandboxDriver = {
     stop?: (target: SandboxTarget) => Promise<void>;
     destroy?: (target: SandboxTarget) => Promise<void>;
     snapshot?: (target: SandboxTarget) => Promise<SandboxSnapshotResult>;
+    inspect?: (target: SandboxTarget) => Promise<SandboxTarget | undefined>;
+    exec?: (target: SandboxTarget, command: string) => Promise<SandboxCommandResult>;
+    clone?: (target: SandboxTarget, input: {
+        name: string;
+    }) => Promise<SandboxTarget>;
 };
 export type SandboxManager = {
     ensure: (workspaceId: string, input: SandboxManagerInput) => Promise<SandboxEnsureResult>;
@@ -211,6 +425,8 @@ export type SandboxManager = {
     target: (workspaceId: string) => Promise<SandboxTargetResult>;
     touch: (workspaceId: string) => Promise<SandboxTouchResult>;
     snapshot: (workspaceId: string) => Promise<SandboxSnapshotManagerResult>;
+    checkpoint: (workspaceId: string, input: SandboxCheckpointCaptureInput) => Promise<SandboxCheckpointResult>;
+    restore: (workspaceId: string, input: SandboxCheckpointRestoreInput) => Promise<SandboxCheckpointResult>;
     stop: (workspaceId: string) => Promise<SandboxMutationResult>;
     destroy: (workspaceId: string) => Promise<SandboxMutationResult>;
     release: (workspaceId: string) => Promise<{
@@ -232,6 +448,10 @@ export type SandboxManagerInput = {
     secrets?: SandboxBrokeredSecret[];
     source?: SandboxSource;
     exposure?: SandboxExposure;
+    /**
+     * @see SandboxDriverEnsureInput.net — enforced by a capable driver, withheld
+     * (with a warning) by one that declares `egressControl: "none"`.
+     */
     net?: SandboxNetworkPolicy;
     snapshot?: string;
 };
@@ -247,6 +467,14 @@ export type SandboxRegisterInput = {
     now?: number;
 };
 export type SandboxHeartbeatInput = SandboxRegisterInput;
+/**
+ * What a provisioning cycle is actually doing, for honest progress UI.
+ * `restore` = booting a replacement restored from the workspace's snapshot
+ * (files come back), `resume` = restarting the same paused resource,
+ * `cold-start` = a fresh sandbox with no prior state to bring back (first
+ * boot, or nothing snapshot-able survived).
+ */
+export type SandboxBootMode = "restore" | "resume" | "cold-start";
 export type SandboxEnsureResult = ({
     status: "ready";
 } & SandboxTarget & {
@@ -257,6 +485,7 @@ export type SandboxEnsureResult = ({
     retryAfterMs: number;
     epoch: number;
     homeRegion: SandboxRegion;
+    bootMode?: SandboxBootMode;
 } | {
     status: "unavailable";
     retryAfterMs?: number;
@@ -301,7 +530,31 @@ export type SandboxGarbageCollectResult = {
         target: SandboxTarget;
         error: string;
     }>;
+    /**
+     * Set when the driver cannot enumerate provider state, so the four arrays
+     * above mean "we could not look" rather than "nothing is orphaned". Absent on
+     * a real sweep. Callers must treat it as a FAILED sweep: four empty arrays
+     * reported as success is the exact defect finding B1 names.
+     */
+    listingUnsupported?: true;
+    /** Driver id, so an ops report can name which driver could not look. */
+    driver?: string;
 };
+/**
+ * A driver's `list()` may throw this shape to say "my backing service cannot
+ * enumerate", as distinct from "listing failed this time". `garbageCollect()`
+ * converts it into `listingUnsupported` (a loud, non-fatal capability gap);
+ * every other error propagates as a real sweep failure.
+ *
+ * Structural rather than an `instanceof` check on purpose: drivers are published
+ * as separate entry points and bundlers duplicate class identities, so a
+ * nominal check would silently fall through to "transient failure" in exactly
+ * the deployment that needs the distinction.
+ */
+export type SandboxListingUnsupported = {
+    listingUnsupported: true;
+};
+export declare function isSandboxListingUnsupported(err: unknown): err is SandboxListingUnsupported;
 export type SandboxManagerOptions = {
     leaseStore: SandboxLeaseStore;
     driver: SandboxDriver;
@@ -312,5 +565,16 @@ export type SandboxManagerOptions = {
     retryCapCooldownMs?: number;
     now?: () => number;
     appLabel?: string;
+    /**
+     * Sink for the loud half of "enforce where we can, document where we can't".
+     * Called at composition time and again every time a restricted policy is
+     * withheld from a driver that cannot enforce it.
+     *
+     * Defaults to `console.warn(event.message)`. Pass your own to route the gap
+     * into a telemetry pipeline instead — but note the default is deliberately
+     * unconditional: an operator who never wires a sink still gets the warning.
+     * Pass `() => {}` only if you have another way to surface it.
+     */
+    onEgressUnenforced?: (event: SandboxEgressUnenforcedEvent) => void;
 };
 export declare function createSandboxManager(options: SandboxManagerOptions): SandboxManager;