@claxedo/sandbox-manager 0.9.0 → 0.10.0

package/dist/lease-failure.d.ts

@@ -0,0 +1,173 @@
+import { isSandboxCheckpointUnusableCause, sandboxCheckpointUnusableCauses, type SandboxCheckpointUnusableCause } from "@claxedo/sandbox-contract";
+import type { SandboxLease } from "./contract";
+/**
+ * A driver's ensure throws this shape when the runtime process exited before it
+ * was ever ready. The cause is in the boot itself (a repository credential that
+ * is gone, a branch that does not exist), so polling the driver again cannot
+ * heal it. Structural for the reason `SandboxListingUnsupported` is.
+ */
+export type SandboxRuntimeBootFailure = {
+    runtimeBootFailed: true;
+    message: string;
+};
+export declare function isSandboxRuntimeBootFailure(err: unknown): err is SandboxRuntimeBootFailure;
+export declare class SandboxRuntimeBootError extends Error implements SandboxRuntimeBootFailure {
+    readonly runtimeBootFailed: true;
+    constructor(reason: string);
+}
+export { isSandboxCheckpointUnusableCause, sandboxCheckpointUnusableCauses, type SandboxCheckpointUnusableCause };
+/**
+ * A driver throws this shape when the checkpoint a start restores cannot be
+ * used. Every start from it is refused the same way, and the image is never
+ * booted in its place: only the person's Start fresh, which drops the
+ * checkpoint, lets the next start boot the image.
+ */
+export type SandboxCheckpointUnusable = {
+    checkpointUnusable: SandboxCheckpointUnusableCause;
+    message: string;
+};
+export declare function isSandboxCheckpointUnusable(err: unknown): err is SandboxCheckpointUnusable;
+export declare class SandboxCheckpointUnusableError extends Error implements SandboxCheckpointUnusable {
+    readonly checkpointUnusable: SandboxCheckpointUnusableCause;
+    constructor(checkpointUnusable: SandboxCheckpointUnusableCause, reason: string);
+}
+/**
+ * A driver throws this shape when the provider says the host a lease names no
+ * longer exists: deleted outside the control plane, or its stopped disk
+ * expired. Nothing on that host can serve or be stopped again, so the lease
+ * ends and the next start places a new host.
+ */
+export type SandboxHostGone = {
+    hostGone: true;
+    message: string;
+};
+export declare function isSandboxHostGone(err: unknown): err is SandboxHostGone;
+export declare class SandboxHostGoneError extends Error implements SandboxHostGone {
+    readonly hostGone: true;
+    constructor(reason: string);
+}
+/**
+ * A driver throws this shape when its provider refused the key the driver was
+ * made with (an HTTP 401 or 403 to the key itself). Retrying cannot heal it;
+ * a new key can, which is why the person is told where keys are kept.
+ */
+export type SandboxProviderKeyRefused = {
+    providerKeyRefused: true;
+    message: string;
+};
+export declare function isSandboxProviderKeyRefused(err: unknown): err is SandboxProviderKeyRefused;
+export declare class SandboxProviderKeyRefusedError extends Error implements SandboxProviderKeyRefused {
+    readonly providerKeyRefused: true;
+    constructor(reason: string);
+}
+/**
+ * A driver throws this shape when Claxedo, not the provider, refuses the
+ * start, and `message` is already the one line a person reads: the lease
+ * keeps it as it is, where any other driver error is the provider's.
+ */
+export type SandboxStartRefusal = {
+    startRefused: true;
+    message: string;
+};
+export declare function isSandboxStartRefusal(err: unknown): err is SandboxStartRefusal;
+export declare class SandboxStartRefusedError extends Error implements SandboxStartRefusal {
+    readonly startRefused: true;
+    constructor(reason: string);
+}
+/** The error a lease keeps when `driver`'s provider refused its key; the driver's message stays for the operator. */
+export declare function sandboxProviderKeyRefusedError(driver: string, message: string): string;
+/** The error a lease keeps when `driver` failed at its provider; the driver's message, which names hosts, requests and provider codes, stays for the operator. */
+export declare function sandboxProviderFailedError(driver: string, message: string): string;
+export declare const SANDBOX_START_WINDOWS: readonly ["minute", "hour", "day"];
+export type SandboxStartWindow = (typeof SANDBOX_START_WINDOWS)[number];
+/** A provider's start limit an account used up: `limit` starts per `window`. */
+export type SandboxStartLimit = {
+    window: SandboxStartWindow;
+    limit: number;
+};
+/**
+ * A driver throws this shape when its provider refused a start because the
+ * account's start limit is used up. A minute's or an hour's limit is waited
+ * out before the next attempt; a day's is not retried on its own, since every
+ * attempt until it frees up is refused again, and a person trying again runs it.
+ */
+export type SandboxProviderRateLimited = {
+    providerRateLimited: SandboxStartLimit;
+    message: string;
+};
+export declare function isSandboxProviderRateLimited(err: unknown): err is SandboxProviderRateLimited;
+export declare class SandboxProviderRateLimitedError extends Error implements SandboxProviderRateLimited {
+    readonly providerRateLimited: SandboxStartLimit;
+    constructor(providerRateLimited: SandboxStartLimit, reason: string);
+}
+/** How long a start waits out a used-up limit before it is tried again; a day's limit has no automatic retry. */
+export declare function sandboxStartLimitRetryMs(window: SandboxStartWindow): number | undefined;
+/**
+ * The error a lease keeps when `driver`'s provider refused a start at its
+ * start limit. Claxedo waits out a minute's or an hour's limit itself, and
+ * each surface tells when that next try runs, so only a day's line names what
+ * the person does.
+ */
+export declare function sandboxProviderRateLimitedError(driver: string, limit: SandboxStartLimit): string;
+/** The used-up window when a lease's error is a start the provider refused at its start limit. */
+export declare function sandboxProviderRateLimit(error: string | undefined): SandboxStartWindow | undefined;
+export declare function sandboxRuntimeBootFailedError(reason: string): string;
+export declare function sandboxCheckpointUnusableError(cause: SandboxCheckpointUnusableCause, reason: string): string;
+/** The cause and the driver's one line when an ensure error says the checkpoint a start restores cannot be used. */
+export declare function sandboxCheckpointUnusable(error: string | undefined): {
+    cause: SandboxCheckpointUnusableCause;
+    message: string;
+} | undefined;
+export declare function sandboxHostGoneError(reason: string): string;
+/** The error a lease stopped for a runtime that answered nothing for `forMs` keeps until its next start. */
+export declare function sandboxRuntimeUnresponsiveError(forMs: number): string;
+/** The one line a person is told for why a stopped lease stopped, when it was neither a person's stop nor an idle one. */
+export declare function sandboxStopReason(error: string | undefined): string | undefined;
+export declare function workspaceRuntimeBootReason(diagnostic: string): string | undefined;
+/**
+ * What a driver keeps of a runtime's log within `maxChars`. A Node stack
+ * under the boot-failure line is longer than the bound a driver puts on the
+ * tail (600 chars on Boat, 2026-10-15 staging), so a tail alone keeps the
+ * frames and loses the one line that names the reason.
+ */
+export declare function runtimeBootDiagnostic(log: string, maxChars: number): string;
+/**
+ * The boot's own reason when an ensure error says a start cannot boot until
+ * what it boots from changes: a runtime whose boot failed, or a checkpoint
+ * that cannot be used.
+ */
+export declare function sandboxRuntimeBootFailure(error: string | undefined): string | undefined;
+/** The error a lease keeps when the runtime it serves stopped answering its health reports. */
+export declare const SANDBOX_RUNTIME_UNHEALTHY = "runtime_unhealthy";
+/** The error a capped lease answers when it kept none of its own. */
+export declare const SANDBOX_RETRY_CAP_EXCEEDED = "runtime_retry_cap_exceeded";
+/**
+ * The one line a person is told for a start step's error: the runtime's own
+ * reason for a boot that failed, the provider's refusal in Claxedo's words,
+ * else the error's first line.
+ */
+export declare function sandboxStartFailureReason(error: string): string;
+export declare function sandboxLeaseEndedUnderStart(error: string | undefined): boolean;
+export declare function sandboxLeaseFailure(lease: SandboxLease, input: {
+    now: number;
+    maxRetryCount: number;
+}): SandboxLeaseFailure | undefined;
+/**
+ * `boot` carries the runtime's own reason, which repeats until what it boots
+ * from changes; `checkpoint_unusable` a start whose checkpoint cannot be
+ * restored for its `cause`, refused until the person starts the workspace
+ * fresh; `unhealthy` is a serving runtime that stopped answering; and
+ * `provider` the driver's error. `retrying` holds while the lease's scheduled
+ * retry is still ahead and its retry budget is not spent: a start in progress
+ * is waiting it out, and the next ensure runs it.
+ */
+export type SandboxLeaseFailure = {
+    kind: "boot" | "unhealthy" | "provider";
+    message: string;
+    retrying: boolean;
+} | {
+    kind: "checkpoint_unusable";
+    cause: SandboxCheckpointUnusableCause;
+    message: string;
+    retrying: false;
+};

package/dist/lease-lifecycle.d.ts

@@ -0,0 +1,65 @@
+import type { SandboxLease } from "./contract";
+import type { SandboxCheckpointUnusableCause, SandboxStartWindow } from "./lease-failure";
+/** Who stopped the host: a person or the plane's explicit stop, the idle policy, the plane for a runtime that stopped answering, or the provider on its own. */
+export type SandboxStopCause = "explicit" | "idle" | "unresponsive" | "provider";
+/** `unsaved`: the stop ended the machine without capturing it; `unfrozen`: it captured files whose runtime did not freeze first. */
+export type SandboxStopOutcome = {
+    unsaved?: true;
+    unfrozen?: true;
+};
+/**
+ * The lease transitions a deployment meters. A lease epoch is one boot: a wake
+ * acquires a new epoch with its own start, so `activeMs` (the epoch's start to
+ * its stop or destroy) is the machine time that boot spent, and is present only
+ * when the lease was serving at that moment. A destroyed epoch is `hostGone`
+ * when the provider lost its host, rather than Claxedo destroying it. A failed
+ * epoch whose start goes
+ * on in the next epoch is `retrying`; the start the person waits on has not
+ * failed until an epoch fails without one. `startLimit` is the provider's
+ * start-limit window an epoch was refused at. `hostLeftRunning` is a failed
+ * start whose host the manager could not stop, so it may still bill, and
+ * `checkpointUnusable` the cause of one refused because the checkpoint it
+ * restores cannot be used. `startedFresh` is the person dropping the lease's
+ * checkpoint so the next start boots the image; its `checkpointUnusable` is
+ * the cause the lease's last start was refused for, when it was. A stop is
+ * `unsaved` when it ended the machine without capturing it, so the lease
+ * keeps the checkpoint it had before, and `unfrozen` when it captured the
+ * files of a runtime that did not freeze first.
+ */
+export type SandboxLifecycleEvent = {
+    workspaceId: string;
+    epoch: number;
+    driver: string;
+    labels: Record<string, string>;
+} & (({
+    kind: "stopped";
+    cause: SandboxStopCause;
+    activeMs?: number;
+} & SandboxStopOutcome) | {
+    kind: "destroyed";
+    hostGone: boolean;
+    activeMs?: number;
+} | ({
+    kind: "failed";
+} & SandboxStartFailureFacts) | {
+    kind: "startedFresh";
+    checkpointUnusable?: SandboxCheckpointUnusableCause;
+});
+type SandboxStartFailureFacts = {
+    bootFailed: boolean;
+    retrying: boolean;
+    startLimit?: SandboxStartWindow;
+    hostLeftRunning?: true;
+    checkpointUnusable?: SandboxCheckpointUnusableCause;
+};
+export declare function createLifecycleReporter(sink: ((event: SandboxLifecycleEvent) => void) | undefined, now: () => number): {
+    stopped: (lease: SandboxLease, cause: SandboxStopCause, outcome?: SandboxStopOutcome) => void;
+    /** `endedAt` is when the host was last proven serving: a stop the provider made on its own is learned after the fact. */
+    hostStopped: (lease: SandboxLease, endedAt?: number) => void;
+    destroyed: (lease: SandboxLease) => void;
+    /** `endedAt` is when the host was last proven serving: the provider's loss is learned after the fact. */
+    hostGone: (lease: SandboxLease, endedAt?: number) => void;
+    failed: (lease: SandboxLease, failure: SandboxStartFailureFacts) => void;
+    startedFresh: (lease: SandboxLease, checkpointUnusable: SandboxCheckpointUnusableCause | undefined) => void;
+};
+export {};

package/dist/lease-retry-wait.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxLeaseStore } from "./contract";
+/**
+ * Ends the wait a failed start left on the workspace's lease, its retry budget
+ * with it, for a change that may have fixed what the start failed on: the next
+ * start runs the driver at once, as a start of its own. True when a wait was
+ * lifted; a lease that is not waiting on a failed start is left as it is.
+ */
+export declare function liftSandboxRetryWait(leaseStore: SandboxLeaseStore, workspaceId: string): Promise<boolean>;

package/dist/lease-start.d.ts

@@ -0,0 +1,21 @@
+import type { SandboxBootMode, SandboxDriver, SandboxLease, SandboxStartProgress } from "./contract";
+/**
+ * The boot path a lease is on, read from its row alone, for the provisioning
+ * answers given before a driver step runs, so the connect UI keeps its honest
+ * label across the whole wait. Mirrors the predicates the manager's step uses
+ * when no caller boot source is set: the driver-snapshot default and its
+ * `resuming`. A host that never published a URL never served, so resuming it
+ * is the workspace's first start as the person sees it, not a wake.
+ */
+export declare function leaseBootMode(lease: SandboxLease, driver: Pick<SandboxDriver, "metadata" | "resumeHost">): SandboxBootMode;
+/**
+ * The start the next epoch continues: the one a stale epoch was taken over
+ * in, or the one a provider failure interrupted while its retry is scheduled
+ * and its budget lasts. A boot failure, a spent budget, a lifted retry wait, a
+ * lost serving runtime and a stop all end the start the person was waiting
+ * on; the next epoch is a start of its own.
+ */
+export declare function continuedStart(lease: SandboxLease | undefined, input: {
+    now: number;
+    maxRetryCount: number;
+}): SandboxStartProgress | undefined;

package/dist/lease-types.d.ts

@@ -1,6 +1,5 @@
-import type { SandboxCheckpointReference, SandboxPersistenceCapabilities, SandboxRestoreStatus } from "./index";
+import type { SandboxCheckpointReference, SandboxMachineClass, SandboxPersistenceCapabilities, SandboxRestoreStatus, SandboxStartProgress } from "./contract";
 export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "destroyed" | "failed";
-export type SandboxComputeClass = "small" | "medium" | "large" | "gpu";
 export type SandboxLeaseRow = {
     workspace_id: string;
     lease_id: string;
@@ -21,6 +20,7 @@ export type SandboxLeaseRow = {
     driver_resource_id: string | null;
     driver_snapshot_id: string | null;
     sandbox_id: string | null;
+    routing_id?: string | null;
     url: string | null;
     retry_count: number;
     next_retry_at: number | null;
@@ -28,7 +28,7 @@ export type SandboxLeaseRow = {
     last_activity_at: number | null;
     last_health_failure_at: number | null;
     last_error: string | null;
-    compute_class: SandboxComputeClass | null;
+    machine_class: SandboxMachineClass | null;
     accel_base_image_id: string | null;
     accel_prepared_image_id: string | null;
     accel_snapshot_id: string | null;
@@ -36,6 +36,7 @@ export type SandboxLeaseRow = {
     checkpoint: SandboxCheckpointReference | null;
     persistence: SandboxPersistenceCapabilities | null;
     restore: SandboxRestoreStatus | null;
+    start: SandboxStartProgress | null;
     created_at: number;
     updated_at: number;
 };

package/dist/manager.d.ts

@@ -0,0 +1,2 @@
+import { type SandboxManager, type SandboxManagerOptions } from "./contract";
+export declare function createSandboxManager(options: SandboxManagerOptions): SandboxManager;

package/dist/runtime-env.d.ts

@@ -5,9 +5,12 @@ export type WorkspaceRuntimeControlEnv = {
     managementJwksUrl?: string;
     sessionAuthorityUrl?: string;
 };
+export declare function workspaceRuntimeIdentityEnvConflicts(env: Record<string, string> | undefined): string[];
+export declare function assertWorkspaceRuntimeIdentityEnv(env: Record<string, string> | undefined): void;
+export declare function workspaceRuntimeBootSecrets(env: Record<string, string>): string[];
 export declare function workspaceRuntimeBootEnv(input: Parameters<typeof workspaceRuntimeTargetEnv>[0] & Parameters<typeof workspaceRuntimeSourceEnv>[0] & {
     env?: Record<string, string>;
-    runner?: string;
+    nativeHarness?: string;
     controlEnv?: WorkspaceRuntimeControlEnv;
 }): Record<string, string>;
 export declare function workspaceRuntimeTargetEnv(input: {
@@ -30,6 +33,5 @@ export declare function workspaceRuntimeServiceExposureEnv(input: {
     driver: SandboxDriverID;
     source: "driver-service-url";
     access: "private" | "public" | "driver-authenticated" | "unknown";
-    fallbackAccess?: "private" | "public" | "driver-authenticated" | "unknown";
     note?: string;
 }): Record<string, string>;

package/dist/runtime-env.mjs

@@ -1,11 +1,44 @@
 // src/runtime-env.ts
+var WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS = [
+  "WORKSPACE_RUNTIME_WORKSPACE_ID",
+  "WORKSPACE_RUNTIME_HOST_ID",
+  "WORKSPACE_RUNTIME_RELAY_WORKSPACE_IDS"
+];
+function workspaceRuntimeIdentityEnvConflicts(env) {
+  if (!env) return [];
+  return WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS.filter((key) => env[key] !== void 0);
+}
+function assertWorkspaceRuntimeIdentityEnv(env) {
+  const conflicts = workspaceRuntimeIdentityEnvConflicts(env);
+  if (conflicts.length === 0) return;
+  throw new Error(
+    `sandbox env cannot set runtime identity ${conflicts.join(", ")}: the driver's placement owns the identity its target reports and the lease records`
+  );
+}
+var WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS = /* @__PURE__ */ new Set([
+  ...WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS,
+  "WORKSPACE_RUNTIME_DIRECTORY",
+  "WORKSPACE_RUNTIME_PORT",
+  "WORKSPACE_RUNTIME_HOST",
+  "WORKSPACE_RUNTIME_SOURCE_KIND",
+  "WORKSPACE_RUNTIME_GIT_REPO_URL",
+  "WORKSPACE_RUNTIME_GIT_BRANCH",
+  "WORKSPACE_RUNTIME_NATIVE_HARNESS",
+  "WORKSPACE_RUNTIME_RELAY_JWKS_URL",
+  "WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL",
+  "WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL"
+]);
+function workspaceRuntimeBootSecrets(env) {
+  return Object.entries(env).flatMap(([key, value]) => WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS.has(key) ? [] : [value]);
+}
 function workspaceRuntimeBootEnv(input) {
+  assertWorkspaceRuntimeIdentityEnv(input.env);
   const env = {
     ...workspaceRuntimeTargetEnv(input),
     ...workspaceRuntimeSourceEnv(input),
     ...input.env
   };
-  if (input.runner) env.WORKSPACE_RUNTIME_RUNNER = input.runner;
+  if (input.nativeHarness) env.WORKSPACE_RUNTIME_NATIVE_HARNESS = input.nativeHarness;
   if (input.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = input.controlEnv.relayJwksUrl;
   if (input.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = input.controlEnv.relayVerifyPem;
   if (input.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = input.controlEnv.managementJwksUrl;
@@ -35,12 +68,14 @@ function workspaceRuntimeServiceExposureEnv(input) {
     WORKSPACE_RUNTIME_SERVICE_EXPOSURE_SOURCE: input.source,
     WORKSPACE_RUNTIME_SERVICE_EXPOSURE_ACCESS: input.access,
     WORKSPACE_RUNTIME_SERVICE_EXPOSURE_DRIVER: input.driver,
-    ...input.fallbackAccess ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_FALLBACK_ACCESS: input.fallbackAccess } : {},
     ...input.note ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_NOTE: input.note } : {}
   };
 }
 export {
+  assertWorkspaceRuntimeIdentityEnv,
   workspaceRuntimeBootEnv,
+  workspaceRuntimeBootSecrets,
+  workspaceRuntimeIdentityEnvConflicts,
   workspaceRuntimeServiceExposureEnv,
   workspaceRuntimeSourceEnv,
   workspaceRuntimeTargetEnv

package/dist/runtime-snapshot.d.ts

@@ -0,0 +1,49 @@
+import type { SandboxLeaseStore, SandboxMutationResult, SandboxRuntimeSnapshotInput } from "./contract";
+/**
+ * How a deployment moves a lease's retry budget when its runtime reports on
+ * itself. Two answers, both deliberate:
+ *
+ * - `demote` — an unhealthy report stops the lease resolving for routing and
+ *   moves nothing else, so a reporting sandbox cannot spend a budget it does
+ *   not own; the next `ensure` decides what happens. The default, and what a
+ *   manager whose only observer is the runtime itself wants.
+ * - `retry-budget` — the report also spends the budget, the way a supervisor
+ *   running its own health monitor over the same sandbox already spends it.
+ *   Chosen where a lease has TWO observers of one sandbox: leaving them to
+ *   write different shapes for the same unhealthy minute is the divergence
+ *   this removes. It must hand the budget back on the next serving report,
+ *   or a flapping runtime walks its own lease into a terminal `failed`.
+ */
+export type SandboxRuntimeLivenessPolicy = {
+    kind: "demote";
+} | {
+    kind: "retry-budget";
+    /** `undefined` means the budget is spent: the lease stays unavailable until an operator acts. */
+    nextRetryAt: (input: {
+        retryCount: number;
+        now: number;
+    }) => number | undefined;
+};
+/**
+ * The one writer of a lease's liveness, shared by `SandboxManager`'s
+ * register/heartbeat and by any supervisor that probes the same question for
+ * itself. A second implementation of this sequence is how one deployment ends
+ * up able to revive a lease another deployment refuses to.
+ *
+ * Liveness only: identity stays whatever `recordTarget` wrote from the
+ * driver's answer (@see SandboxRuntimeSnapshotInput). It takes a
+ * `SandboxLeaseStore` and no driver, because recording that a sandbox is
+ * alive must not depend on provider credentials the deployment may no longer
+ * hold.
+ *
+ * Fenced twice — on the epoch the reporter names, and on the status read here
+ * — because the guards below and the write are separate transactions, and a
+ * stop, a destroy or a replacement epoch can land between them.
+ */
+export declare function applySandboxRuntimeSnapshot(input: {
+    leaseStore: SandboxLeaseStore;
+    workspaceId: string;
+    snapshot: SandboxRuntimeSnapshotInput;
+    now?: () => number;
+    liveness?: SandboxRuntimeLivenessPolicy;
+}): Promise<SandboxMutationResult>;

package/dist/runtime-version.d.ts

@@ -1 +1,10 @@
 export declare function workspaceRuntimeVersion(): string;
+/**
+ * The oldest workspace-runtime version a driver may restore a workspace's
+ * snapshot into running again. A filesystem snapshot carries the runtime it
+ * was taken with, so a fix to the runtime reaches a workspace that keeps
+ * waking only when this rises. Raise it, together with the runtime version,
+ * for a security-relevant runtime change alone: every snapshot below it is
+ * refused and its person must start the workspace fresh.
+ */
+export declare const MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";

package/dist/runtime-version.mjs

@@ -3,6 +3,8 @@ var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
 function workspaceRuntimeVersion() {
   return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
+var MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
 export {
+  MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION,
   workspaceRuntimeVersion
 };

package/dist/service-url-exposure.d.ts

@@ -3,7 +3,6 @@ export type SandboxServiceUrlExposure = {
     source: "driver-service-url";
     access: "private" | "public" | "driver-authenticated" | "unknown";
     driver: SandboxDriverID;
-    fallbackAccess?: "private" | "public" | "driver-authenticated" | "unknown";
     note?: string;
 };
 export declare function sandboxServiceUrlExposure(driver: SandboxDriverID): SandboxServiceUrlExposure;

package/dist/service-url-exposure.mjs

@@ -8,15 +8,6 @@ function sandboxServiceUrlExposure(driver) {
       note: "Docker service URLs resolve to a local loopback port on the host."
     };
   }
-  if (driver === "daytona") {
-    return {
-      source: "driver-service-url",
-      access: "driver-authenticated",
-      driver,
-      fallbackAccess: "public",
-      note: "Daytona uses a signed preview URL when available and falls back to a preview link."
-    };
-  }
   return {
     source: "driver-service-url",
     access: "public",

package/dist/start-fresh.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxDriver, SandboxLease, SandboxLeaseStore, SandboxMutationResult, SandboxResource } from "./contract";
+import type { createLifecycleReporter } from "./lease-lifecycle";
+/**
+ * Drops the lease's checkpoint, restore record and the failure it left, so
+ * the next start boots the image and clones the repository. Refused while a
+ * start or the runtime runs: a running workspace's files are not yet in any
+ * checkpoint, and a start in flight would restore what this drops.
+ */
+export declare function startSandboxFresh(input: {
+    workspaceId: string;
+    driver: SandboxDriver;
+    leaseStore: SandboxLeaseStore;
+    lifecycle: ReturnType<typeof createLifecycleReporter>;
+    resource: (lease: SandboxLease) => SandboxResource | undefined;
+    now: number;
+    maxRetryCount: number;
+}): Promise<SandboxMutationResult>;

package/dist/start-telemetry.d.ts

@@ -0,0 +1,37 @@
+import type { SandboxStartPhase } from "@claxedo/sandbox-contract";
+import type { SandboxBootMode, SandboxLease, SandboxLeaseStore, SandboxStartPhaseEvent, SandboxStartPhasesReport } from "./contract";
+/**
+ * The one writer of a lease epoch's start: each phase is persisted into the
+ * lease before it is emitted, at most once per epoch, so a phase observed by
+ * two pollers or reported twice by a runtime reaches the sink once.
+ */
+export declare function createSandboxStartRecorder(options: {
+    leaseStore: SandboxLeaseStore;
+    driver: string;
+    now: () => number;
+    onStartPhase?: (event: SandboxStartPhaseEvent) => void;
+}): {
+    /**
+     * The phases one provision call observes, each timed and written into the
+     * lease as it ends, so a poller reading the lease mid-boot sees how far the
+     * start has come. `opened` writes the epoch's `lease_decision` before the
+     * driver runs, so a stop that lands mid-boot finds the boot it ends on the
+     * row. A serving lease is not starting. An epoch acquired with a start it
+     * continues has that start and no phase yet; one acquired without begins
+     * its own here.
+     */
+    observe(lease: SandboxLease, input: {
+        bootMode: SandboxBootMode;
+        enteredAt: number;
+        labels: Record<string, string>;
+    }): {
+        opened: () => Promise<void>;
+        end: (phase: SandboxStartPhase) => Promise<void>;
+    } | undefined;
+    report(workspaceId: string, input: SandboxStartPhasesReport): Promise<void>;
+    markAfter(workspaceId: string, input: {
+        epoch: number;
+        phase: SandboxStartPhase;
+        notBefore: number;
+    }): Promise<void>;
+};

package/dist/stores/memory.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxLeaseStore, SandboxLease, SandboxRegion } from "..";
+import type { SandboxLeaseStore, SandboxLease, SandboxRegion } from "../contract";
 export declare function createMemoryLeaseStore(seed?: SandboxLease[]): SandboxLeaseStore;
 export declare function sandboxLease(input: Partial<SandboxLease> & {
     workspaceId: string;